This repository contains the backend server implementation for ZenServer, a secure payment API designed to solve the critical problem of payment fingerprint harvesting. Built with Deno and TypeScript, it provides an enterprise-grade security model for a public-facing, unauthenticated "browse-and-pay" user journey.

The primary goal is to allow users to complete payments without requiring login or account creation, while ensuring the process is protected from automated abuse through comprehensive security layers and advanced debugging capabilities.

The security model implements a multi-layered, defense-in-depth strategy with 9+ security checks that does not rely on user authentication:

1. Nonce-Gating System: Short-lived (60-second), single-use nonces required before payment fingerprint generation
2. CSRF Protection: Transient session context via SESSION and XSRF-TOKEN cookies
3. Bot Detection: Cloudflare Turnstile + Honeypot trap for automated traffic filtering
4. Request Security: User agent scanning, referer/origin validation, malicious header detection
5. Rate Limiting: Strict IP-based rate limiting on all sensitive endpoints
6. Size Validation: Request size limits to prevent denial-of-service attacks
7. Callback Authentication: ValidationCode hash verification for Zenpay server-to-server callbacks

NEW: Comprehensive debug mode with numbered security checks and correlation IDs:

# Enable debug mode
export DEBUG_MODE=true

# Expected debug output:
🔍 DEBUG SESSION STARTED
Correlation ID: 550e8400-e29b-41d4-a716-446655440000
POST /api/v1/create-nonce
IP: 192.168.1.1
───────────────────────────────────────
Check1: ✅ CORS Origin Check
Check2: ✅ CORS Validation Passed
Check3: ✅ User Agent Security Scan
Check4: ✅ Referer Validation
Check5: ✅ Origin Validation
Check6: ✅ Header Content Security Scan
Check7: ✅ Request Size Validation
Check8: ✅ Rate Limit Validation
Check9: ✅ Honeypot Bot Detection
───────────────────────────────────────
🔒 SECURITY CHECKS SUMMARY
Total checks: 9
Passed: 9 | Failed: 0
Response: 200
Duration: 45ms
🔍 DEBUG SESSION ENDED

NEW: Advanced honeypot implementation with emoji injection pattern:

• Frontend: Automatically injects email_verify: "🍯" in all createNonce requests
• Backend: Validates exact emoji match to detect bots
• Bot Response: Returns fake nonces to waste bot resources
• Human Response: Proceeds normally with real nonce generation

The system is designed around a simple, unauthenticated user journey:

1. Browse: User visits public website and selects a tour
2. Secure Context: Tour details page (/api/v1/tour/{id}) sets security cookies (SESSION, XSRF-TOKEN)
3. Pay Now: Client performs two-step process:
   • a. Request nonce from /api/v1/create-nonce (CSRF + Turnstile + Honeypot validation)
   • b. Exchange nonce for fingerprint via /api/v1/payment/exchange-nonce
4. Payment: Client uses fingerprint to initialize Zenpay payment plugin
5. Confirmation: Zenpay sends server-to-server callback with ValidationCode authentication

Note: No API keys or Authorization headers required for public flow.

Create a .env file with required variables:

# Zenpay Gateway Credentials
ZENPAY_USERNAME="your_zenpay_username"
ZENPAY_PASSWORD="your_zenpay_password"

# Security Configuration  
TURNSTILE_SECRET_KEY="your_cloudflare_turnstile_secret"
ADMIN_API_KEY="your_admin_api_key_for_shareable_links"

# Debug Configuration (optional)
DEBUG_MODE=true           # Enable detailed security debug output
LOG_LEVEL=INFO           # Logging level (DEBUG, INFO, WARN, ERROR)

# Server Configuration (optional)
PORT=5000                # Server port (default: 5000)

• Deno 1.40.2+
• Cloudflare Turnstile account for bot protection
• Zenpay merchant account

# Clone repository
git clone <repository-url>
cd ZenServer

# Create environment file
cp .env.example .env
# Edit .env with your credentials

# Start server with debug mode
export DEBUG_MODE=true
deno run --allow-net --allow-read --allow-env --allow-write src/main.ts

Server starts on http://localhost:5000 with detailed debug logging.

1. Start server with DEBUG_MODE=true
2. Make requests to see numbered security checks
3. Monitor correlation IDs across request lifecycle

# Test legitimate request (should pass)
curl -X POST http://localhost:5000/api/v1/create-nonce \
  -H "Content-Type: application/json" \
  -d '{"tourId": "paris", "cfToken": "turnstile-token", "email_verify": "🍯"}'

# Test bot request (should get fake nonce)  
curl -X POST http://localhost:5000/api/v1/create-nonce \
  -H "Content-Type: application/json" \
  -d '{"tourId": "paris", "cfToken": "turnstile-token", "email_verify": "bot-value"}'

1. GET /api/v1/tour/paris - Sets security cookies
2. POST /api/v1/create-nonce - Get nonce with security validation
3. POST /api/v1/payment/exchange-nonce - Exchange for payment fingerprint

• Correlation IDs: Track requests across entire middleware chain
• Session Lifecycle: Initialize → Process → Finalize → Cleanup
• Numbered Checks: Clear visibility into all 9+ security validations
• Performance Monitoring: Request duration and check timing
• Error Tracking: Detailed failure analysis with context

• Pattern: Frontend injects 🍯 emoji, backend validates exact match
• Detection: Missing field (suspicious), wrong value (bot), correct emoji (human)
• Response: Bots receive fake nonces, humans get real nonces
• Integration: Seamlessly integrated with debug numbering system

• ✅ 9 Numbered Security Checks with correlation tracking
• ✅ Advanced Honeypot with emoji injection pattern
• ✅ CSRF Protection via SESSION/XSRF-TOKEN cookies
• ✅ Bot Detection through Cloudflare Turnstile + honeypot
• ✅ Rate Limiting with IP-based throttling
• ✅ Request Validation including size limits and content scanning
• ✅ Callback Authentication via ValidationCode verification
• ✅ Debug Mode with comprehensive security visibility

Ready for one-click deployment to Val Town serverless platform. See docs/Val Town Deployment Guide.md for complete instructions.

Uses Deno's built-in HTTP server for local development with full debug capabilities.

1. Configure environment variables
2. Enable debug mode for development
3. Test honeypot detection with sample requests
4. Review security check output in debug logs
5. Deploy to production with DEBUG_MODE=false

Built with security-first design principles and comprehensive debug visibility for enterprise payment processing.