feat(#109): Security hardening - secrets, JWT, and pre-beta config Th…

.env.example

@@ -1,80 +1,131 @@
 # .env.example — copy to .env and fill in values
-
-# ── Database ──────────────────────────────────────────────────
+# IMPORTANT: Never commit secrets to version control. Use ./scripts/generate-secrets.sh
+# for secure random values. See README.md "Pre-Beta Environment Setup Guide" for details.
+
+# ── DATABASE (Required for API) ────────────────────────────────
+# PostgreSQL connection string. Default for local Docker: port 5434
 DATABASE_URL="postgresql://useroutr:password@localhost:5434/useroutr"
-
-# ── Redis ─────────────────────────────────────────────────────
+
+# ── REDIS (Required for API) ───────────────────────────────────
+# Redis connection string for caching, job queues, and rate limiting
 REDIS_URL="redis://localhost:6379"
-
-# ── Auth ──────────────────────────────────────────────────────
-JWT_SECRET="your-256-bit-secret-here"
+
+# ── AUTHENTICATION (Required for API) ──────────────────────────
+# JWT_SECRET: Generate via `./scripts/generate-secrets.sh`
+# Base64-encoded 64 bytes (512 bits) for HS256 signing
+JWT_SECRET="your-jwt-secret-here"
+
+# JWT_EXPIRY: Token expiration time (used for session management)
 JWT_EXPIRY="7d"
-API_KEY_SALT="your-api-key-salt"
-
-# ── Stellar ───────────────────────────────────────────────────
-STELLAR_NETWORK="testnet"   # "mainnet" for production
+
+# BANK_SESSION_ENCRYPTION_KEY: Generate via `./scripts/generate-secrets.sh`
+# Base64-encoded 32 bytes for AES-256 encryption of bank session data
+BANK_SESSION_ENCRYPTION_KEY="your-bank-session-encryption-key-here"
+
+# BANK_WEBHOOK_SECRET: Generate via `./scripts/generate-secrets.sh`
+# Used to verify integrity of bank webhook payloads
+BANK_WEBHOOK_SECRET="your-bank-webhook-secret-here"
+
+# ── STELLAR (Required for payments) ────────────────────────────
+# Network choice: "testnet" for development, "mainnet" for production
+STELLAR_NETWORK="testnet"
+
+# Stellar RPC endpoints
 STELLAR_HORIZON_URL="https://horizon-testnet.stellar.org"
 STELLAR_SOROBAN_RPC_URL="https://soroban-testnet.stellar.org"
-STELLAR_RELAY_KEYPAIR_SECRET="S..."  # Relay hot wallet (NEVER share)
+
+# Relay keypair for HTLC hot wallet operations (NEVER share or commit)
+# Generate via: stellar key generate
+STELLAR_RELAY_KEYPAIR_SECRET="S..."
 STELLAR_RELAY_PUBLIC_KEY="G..."
-
-# ── Soroban Contracts ─────────────────────────────────────────
+
+# ── SOROBAN CONTRACTS (Required for settlement) ────────────────
+# Contract IDs deployed on Stellar (get from deployment output)
 SOROBAN_HTLC_CONTRACT_ID="C..."
 SOROBAN_SETTLEMENT_CONTRACT_ID="C..."
 SOROBAN_FEE_COLLECTOR_CONTRACT_ID="C..."
 SOROBAN_ESCROW_CONTRACT_ID="C..."
-
-# ── EVM (deploy HTLC on each chain) ───────────────────────────
-EVM_RELAY_PRIVATE_KEY="0x..."         # EVM relay wallet (NEVER share)
+
+# ── EVM CHAINS (Required for multi-chain support) ───────────────
+# EVM relay private key for hot wallet operations (NEVER share or commit)
+# Format: 0x<hex>, generate via ethers.js or MetaMask
+EVM_RELAY_PRIVATE_KEY="0x..."
+
+# HTLC contract addresses on each EVM chain
 HTLC_ADDRESS_ETHEREUM="0x..."
 HTLC_ADDRESS_BASE="0x..."
 HTLC_ADDRESS_BNB="0x..."
 HTLC_ADDRESS_POLYGON="0x..."
 HTLC_ADDRESS_ARBITRUM="0x..."
 HTLC_ADDRESS_AVALANCHE="0x..."
- 
-# RPC endpoints (use Alchemy / Infura in production)
+
+# RPC endpoints for each chain (use Alchemy/Infura for production reliability)
 RPC_ETHEREUM="https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
 RPC_BASE="https://base-mainnet.g.alchemy.com/v2/YOUR_KEY"
-RPC_BNB="https://bsc-dataseed.binance.org/"
-
+RPC_BNB="https://bsc-dataseed.binance.org"
 RPC_POLYGON="https://polygon-rpc.com"
 RPC_ARBITRUM="https://arb1.arbitrum.io/rpc"
 RPC_AVALANCHE="https://api.avax.network/ext/bc/C/rpc"
-
-# ── Circle CCTP ───────────────────────────────────────────────
+
+# ── CIRCLE CCTP (For stablecoin bridging) ──────────────────────
+# API key from Circle developer portal
 CIRCLE_API_KEY="your-circle-api-key"
-
-# ── Wormhole ──────────────────────────────────────────────────
-WORMHOLE_ENV="Testnet"   # "Mainnet" for production
-
-# ── Layerswap (Starknet) ──────────────────────────────────────
-LAYERSWAP_API_KEY="your-layerswap-key"
-
-# ── MoneyGram ─────────────────────────────────────────────────
-MONEYGRAM_HOME_DOMAIN="extstellar.moneygram.com"  # testnet
-# MONEYGRAM_HOME_DOMAIN="stellar.moneygram.com"  # mainnet
-
-# ── Stripe (card payments) ────────────────────────────────────
+
+# ── WORMHOLE (For cross-chain messaging) ───────────────────────
+# Environment: "Testnet" for development, "Mainnet" for production
+WORMHOLE_ENV="Testnet"
+
+# ── LAYERSWAP (For Starknet routing) ───────────────────────────
+# API key from Layerswap dashboard
+LAYERSWAP_API_KEY="your-layerswap-api-key"
+
+# ── MONEYGRAM (For fiat settlement) ────────────────────────────
+# Testnet domain (comment out for mainnet)
+MONEYGRAM_HOME_DOMAIN="extstellar.moneygram.com"
+# Mainnet domain (uncomment for production)
+# MONEYGRAM_HOME_DOMAIN="stellar.moneygram.com"
+
+# ── STRIPE (For card payments) ─────────────────────────────────
+# Secret key from Stripe dashboard (format: sk_test_... or sk_live_...)
 STRIPE_SECRET_KEY="sk_test_..."
+
+# Webhook signing secret from Stripe webhook settings
 STRIPE_WEBHOOK_SECRET="whsec_..."
-
-# ── Email ─────────────────────────────────────────────────────
+
+# ── EMAIL (For notifications) ──────────────────────────────────
+# API key from Resend dashboard
 RESEND_API_KEY="re_..."
+
+# From email address for notifications
 EMAIL_FROM="payments@useroutr.com"
-
-# ── Storage (Cloudinary) ──────────────────────────────────────
+
+# ── STORAGE (For media uploads) ────────────────────────────────
+# Cloudinary configuration for image storage
 CLOUDINARY_CLOUD_NAME="your-cloud-name"
-CLOUDINARY_API_KEY="your-api-key"
-CLOUDINARY_API_SECRET="your-api-secret"
-
-# ── App ───────────────────────────────────────────────────────
+CLOUDINARY_API_KEY="your-cloudinary-api-key"
+CLOUDINARY_API_SECRET="your-cloudinary-api-secret"
+
+# ── APPLICATION CONFIG ─────────────────────────────────────────
+# Port the API runs on
 PORT=3000
+
+# API URL for external access (used in webhooks, emails, etc.)
 API_URL="https://api.yourdomain.com"
+
+# Node environment
 NODE_ENV="development"
+
+# Frontend URLs (for CORS and redirects)
 NEXT_PUBLIC_API_URL="http://localhost:3000"
-FRONTEND_URL="http://localhost:3001"
+WWW_URL="http://localhost:3000"
 DASHBOARD_URL="http://localhost:3001"
 CHECKOUT_URL="http://localhost:3002"
-USEROUTR_FEE_BPS=50    # Default 0.5% platform fee
+
+# Platform fee in basis points (50 = 0.5%)
+USEROUTR_FEE_BPS=50
+
+# Stripe publishable key (public-facing)
 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
+
+# Bank session TTL in hours
+BANK_SESSION_TTL_HOURS=24