.env.example

# StellarEduPay environment example.
# Copy to .env for docker compose, or copy relevant backend keys to backend/.env.
# Replace every secret before using this outside local development.

# Core server
NODE_ENV=development # Express/runtime mode; use production in deployed environments.
PORT=5000 # Backend HTTP port; docker-compose maps this host port to container port 5000.
API_URL=http://localhost:5000/api # Public API URL used in Swagger/OpenAPI docs.
APP_URL=http://localhost:3000 # Public app URL (frontend, proxies /api) used in email unsubscribe links; must be https:// in production.
ALLOWED_ORIGIN=http://localhost:3000 # Allowed CORS origin or comma-separated origins.
TRUSTED_PROXY_HOPS=1 # Number of trusted reverse-proxy hops for client IP detection.

# MongoDB
MONGO_URI=mongodb://localhost:27017/stellaredupay # MongoDB connection string required by the backend.
MONGO_ROOT_USERNAME=root # Mongo root username used by docker-compose.
MONGO_ROOT_PASSWORD=change_me_mongo_root_password # Mongo root password used by docker-compose.
MONGODB_POOL_SIZE=20 # Canonical MongoDB max connection pool size.
DB_MAX_POOL_SIZE=20 # Legacy MongoDB pool-size alias still accepted by the backend.
DB_MIN_POOL_SIZE=10 # Minimum MongoDB connection pool size.
DB_MAX_IDLE_TIME_MS=30000 # Maximum idle time for MongoDB sockets.
DB_CONNECT_TIMEOUT_MS=10000 # MongoDB connection timeout.
DB_SOCKET_TIMEOUT_MS=45000 # MongoDB socket timeout.
DB_SERVER_SELECTION_TIMEOUT_MS=5000 # MongoDB server selection timeout.
DB_MAX_CONCURRENT=50 # Maximum concurrent database operations tracked by the app.
DB_READ_CONCERN=majority # MongoDB transaction read concern.
DB_WRITE_CONCERN=1 # MongoDB write concern value.
DB_JOURNAL=true # Whether MongoDB writes request journal acknowledgement.
DB_TRANSACTION_TIMEOUT_MS=30000 # MongoDB transaction timeout.
DB_MAX_RETRIES=3 # Maximum retry attempts for transient database errors.
DB_INITIAL_RETRY_DELAY_MS=100 # Initial database retry delay.
DB_MAX_RETRY_DELAY_MS=5000 # Maximum database retry delay.
MONGODB_CONNECT_RETRIES=5 # Startup MongoDB connection retry count.
MONGODB_CONNECT_DELAY_MS=2000 # Initial startup MongoDB retry delay.

# Authentication
JWT_SECRET=REPLACE_ME_run_openssl_rand_hex_32 # Secret for signing admin JWTs; generate a unique 64-byte value with: openssl rand -hex 32
JWT_EXPIRES_IN=8h # Legacy admin JWT expiry used by config.
JWT_ACCESS_TOKEN_TTL=8h # Admin access-token lifetime.
JWT_REFRESH_TOKEN_TTL=30d # Admin refresh-token lifetime.
ADMIN_USERNAME=admin # Break-glass admin username for /api/auth/login.
ADMIN_PASSWORD=change_me_admin_password # Plaintext fallback admin password for local development only.
ADMIN_PASSWORD_HASH= # Preferred bcrypt hash for the admin password; overrides ADMIN_PASSWORD when set.

# Stellar network and payment sync
STELLAR_NETWORK=testnet # Stellar network selector: testnet or mainnet.
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org # Primary Horizon URL.
HORIZON_URL= # Backward-compatible Horizon URL fallback.
STELLAR_HORIZON_URLS= # Optional comma-separated Horizon failover URLs; overrides single URL when set.
SCHOOL_WALLET_ADDRESS= # Optional default school public wallet for migration/seed flows.
ACCEPTED_ASSET=XLM # Accepted payment asset code, for example XLM or USDC.
USDC_ISSUER= # Optional issuer override for USDC or another accepted credit asset.
CONFIRMATION_THRESHOLD=2 # Ledgers required before a transaction is confirmed.
FINALIZATION_THRESHOLD=10 # Ledgers required before a transaction is finalized.
POLL_INTERVAL_MS=30000 # Legacy transaction polling interval.
POLL_MAX_BACKOFF_MS=300000 # Maximum polling backoff after Horizon errors.
SYNC_INTERVAL_MS=60000 # Canonical automatic sync interval; 0 disables automatic sync.
SYNC_LOCK_TTL_MS=60000 # Distributed sync lock time-to-live.
SYNC_MAX_PAGES_PER_POLL=50 # Maximum Horizon pages processed in one poll cycle.
VERIFY_LOCK_TTL_MS=30000 # Payment verification lock time-to-live.
STELLAR_TIMEOUT_MS=10000 # Generic outbound Stellar timeout.
STELLAR_NETWORK_TIMEOUT_MS=10000 # Transaction retry queue Stellar request timeout.
STELLAR_CALL_RETRY_ATTEMPTS=3 # Generic Stellar call retry attempts.
STELLAR_CALL_RETRY_DELAY_MS=1000 # Generic Stellar call retry delay.
STELLAR_TX_TIMEOUT_SECONDS=300 # Transaction maxTime timeout in seconds.
STELLAR_TX_BASE_FEE=100 # Base fee for Stellar transactions.
STELLAR_TX_FEE_MULTIPLIER=1.5 # Multiplier applied to Horizon fee stats.
STELLAR_RATE_LIMIT_MIN_TIME=50 # Minimum spacing between Horizon requests.
STELLAR_RATE_LIMIT_MAX_CONCURRENT=10 # Maximum concurrent Horizon requests.
STELLAR_RATE_LIMIT_HIGH_WATER=100 # Horizon limiter queue high-water mark.
STELLAR_RATE_LIMIT_STRATEGY=LEAK # Horizon limiter strategy name.
STELLAR_RETRY_MAX_ATTEMPTS=5 # Rate-limited Stellar client retry attempts.
STELLAR_RETRY_INITIAL_DELAY=1000 # Initial retry delay for Stellar client calls.
STELLAR_RETRY_MAX_DELAY=30000 # Maximum retry delay for Stellar client calls.
STELLAR_RETRY_FACTOR=2 # Exponential retry factor for Stellar client calls.
HORIZON_RATE_LIMIT_HEADER=3600 # Expected Horizon hourly rate-limit budget.
HORIZON_RATE_LIMIT_WINDOW_MS=3600000 # Horizon rate-limit window in milliseconds.
STELLAR_BURST_ALLOWANCE=20 # Maximum short-window Stellar request burst size.
STELLAR_BURST_WINDOW=1000 # Stellar burst window in milliseconds.
CB_FAILURE_THRESHOLD=5 # Horizon circuit-breaker failure threshold.
CB_RESET_TIMEOUT_MS=30000 # Horizon circuit-breaker reset timeout.
CB_HALF_OPEN_SUCCESS_THRESHOLD=2 # Successes required to close a half-open Horizon circuit.

# Redis, queues, and distributed coordination
REDIS_HOST= # Redis host; set to localhost locally or redis in containers to enable BullMQ/distributed features.
REDIS_PORT=6379 # Redis port.
REDIS_PASSWORD= # Redis password; leave empty when Redis has no auth.
REDIS_LOG_THROTTLE_MS=60000 # Minimum interval for repeated Redis connection logs.
REDIS_RECONNECT_MAX_ATTEMPTS=8 # Maximum Redis reconnect attempts.
REDIS_RECONNECT_BASE_DELAY_MS=500 # Initial Redis reconnect delay.
REDIS_RECONNECT_MAX_DELAY_MS=30000 # Maximum Redis reconnect delay.
REPLICA_COUNT=1 # Explicit replica count for retry-backend safety warnings.
WEB_CONCURRENCY= # Platform-provided worker count fallback.
INSTANCE_COUNT= # Platform-provided instance count fallback.
NUMBER_OF_REPLICAS= # Orchestrator-provided replica count fallback.
LEADER_LOCK_TTL_MS=30000 # Leader-election lock time-to-live.
LEADER_RENEW_INTERVAL_MS=15000 # Leader-election renewal interval.
LEADER_ACQUIRE_INTERVAL_MS=10000 # Leader-election acquisition interval.
DRAIN_TIMEOUT_MS=60000 # Worker drain timeout during shutdown.
SHUTDOWN_TIMEOUT_MS=30000 # Forced shutdown timeout after receiving a signal.
RETRIES_ENABLED=true # Enables the BullMQ transaction retry queue.
RETRY_INTERVAL_MS=60000 # MongoDB retry worker interval.
RETRY_MAX_ATTEMPTS=10 # MongoDB retry worker max attempts.
MAX_RETRY_ATTEMPTS=10 # BullMQ retry max attempts.
INITIAL_RETRY_DELAY_MS=60000 # BullMQ initial retry delay.
MAX_RETRY_DELAY_MS=3600000 # BullMQ maximum retry delay.
RETRY_BACKOFF_MULTIPLIER=2 # BullMQ exponential backoff multiplier.
RETRY_JITTER_RATIO=0.2 # Jitter ratio applied to BullMQ retry delays.
DLQ_ENABLED=true # Enables dead-letter queue handling.
DLQ_MAX_AGE_MS=604800000 # Dead-letter queue retention window.
QUEUE_CONCURRENCY=5 # BullMQ retry worker concurrency.
TX_QUEUE_CONCURRENCY=5 # Transaction queue worker concurrency.
QUEUE_LOCK_DURATION_MS=30000 # BullMQ job lock duration.
QUEUE_STALLED_INTERVAL_MS=30000 # BullMQ stalled-job scan interval.
QUEUE_MAX_STALLED_COUNT=2 # Maximum stalled recoveries before failing a job.
MAX_QUEUE_DEPTH=1000 # Maximum in-flight payment processing depth.
QUEUE_BACKPRESSURE_HIGH_WATER=800 # Queue depth where backpressure begins.
QUEUE_BACKPRESSURE_LOW_WATER=500 # Queue depth where backpressure clears.
REPORT_QUEUE_CONCURRENCY=2 # Async report queue worker concurrency.
REPORT_JOB_TTL_MS=21600000 # Async report job retention.
OUTBOX_DISPATCH_INTERVAL_MS=5000 # Outbox dispatcher interval.

# Idempotency, payments, and currency conversion
IDEMPOTENCY_KEY_TTL_SECONDS=86400 # Stored idempotency key retention window.
IDEMPOTENCY_IN_FLIGHT_TTL_MS=30000 # In-flight idempotency reservation timeout.
PAYMENT_INTENT_TTL_SECONDS=86400 # MongoDB TTL for abandoned payment intents.
PAYMENT_INTENT_TTL_MS=86400000 # Runtime payment-intent expiry in milliseconds.
PAYMENT_WEBHOOK_URL= # Optional default payment webhook URL for schools without one.
MIN_PAYMENT_AMOUNT=0.01 # Minimum accepted payment amount.
MAX_PAYMENT_AMOUNT=100000 # Maximum accepted payment amount.
DEFAULT_FIAT_CURRENCY=USD # Default fiat currency for conversion snapshots.
PRICE_CACHE_TTL_MS=60000 # Fresh price cache lifetime.
PRICE_STALE_THRESHOLD_MS=3600000 # Maximum age for stale fallback prices.
SUPPORTED_CURRENCIES_TTL_MS=3600000 # Supported fiat currency list cache lifetime.
CURRENCY_LRU_MAX_SIZE=50 # In-process fiat conversion cache size.
ALLOWED_FIAT_CURRENCIES= # Optional comma-separated fiat allowlist.
COINGECKO_API_KEY= # Optional CoinGecko API key for higher rate limits.

# Request limits, validation, and reports
MAX_BODY_SIZE=10kb # Maximum JSON body size for normal endpoints.
JSON_MAX_DEPTH=10 # Maximum JSON nesting depth accepted by sanitizer.
JSON_MAX_ARRAY_LENGTH=100 # Maximum JSON array length accepted by sanitizer.
CSV_MAX_SIZE_BYTES=5242880 # Maximum CSV upload size.
CSV_MAX_ROWS=10000 # Maximum rows per CSV import.
CSV_MAX_COLUMNS=20 # Maximum columns per CSV import.
BULK_IMPORT_RATE_LIMIT=5 # Bulk student import requests allowed per hour.
VERIFY_RATE_LIMIT=10 # Payment verification requests allowed per minute.
REPORT_MAX_RANGE_DAYS=366 # Maximum report query date range.
LARGE_REPORT_THRESHOLD_DAYS=30 # Date range that switches reports to async mode.
REQUEST_TIMEOUT_MS=30000 # Inbound request timeout.

# Schedulers, retention, and background jobs
CONSISTENCY_CHECK_INTERVAL_MS=300000 # Consistency checker interval.
RECONCILIATION_INTERVAL_MS=86400000 # Payment reconciliation interval.
RECONCILIATION_DRIFT_THRESHOLD=0.5 # Reconciliation drift alert threshold.
RECONCILIATION_REPORT_INTERVAL_MS=86400000 # Reconciliation report scheduler interval.
METRICS_RECONCILE_INTERVAL_MS=21600000 # Metrics rollup reconciliation interval.
SESSION_CLEANUP_INTERVAL_MS=3600000 # Refresh-token session cleanup interval.
STUCK_PAYMENT_THRESHOLD_MS=300000 # Age before a processing payment is considered stuck.
STUCK_PAYMENT_RECONCILIATION_INTERVAL_MS=600000 # Stuck payment reconciliation interval.
STUCK_PAYMENT_RECONCILIATION_MAX_BATCH=100 # Maximum stuck payments reconciled per pass.
AUDIT_LOG_RETENTION_DAYS=730 # Runtime audit-log cleanup retention period.
AUDIT_LOG_TTL_DAYS=730 # Migration audit-log TTL retention period.
REMINDER_LOG_TTL_SECONDS=7776000 # Reminder log retention in seconds.
STUDENT_FEE_HISTORY_CAP=100 # Maximum fee history entries retained on a student document.
DISPUTE_SLA_HOURS=72 # Hours before disputes breach SLA.
DEFAULT_SCHOOL_ID=SCH-DEFAULT # Default school id used by migration scripts.

# Email, reminders, and SMS
REMINDER_INTERVAL_MS=3600000 # Fee reminder scheduler interval.
REMINDER_COOLDOWN_HOURS=48 # Minimum hours between reminders to the same student.
REMINDER_MAX_COUNT=5 # Maximum reminders sent per student.
EMAIL_PROVIDER=console # Email provider selector: console, smtp, ses, or sendgrid.
EMAIL_MAX_RETRIES=3 # Email send retry attempts.
EMAIL_RETRY_BASE_MS=500 # Initial email retry delay.
EMAIL_RETRY_MAX_MS=30000 # Maximum email retry delay.
EMAIL_PROVIDER_WEBHOOK_SECRET= # Shared secret for email delivery provider webhooks.
EMAIL_WEBHOOK_SECRET= # Shared secret for bounce/complaint webhook routes. Sent ONLY via the X-Webhook-Token header (never ?token=).
EMAIL_SNS_TOPIC_ARNS= # Comma-separated SNS topic ARNs allowed to post SES bounce/complaint notifications (signatures are verified).
EMAIL_SENDGRID_WEBHOOK_PUBLIC_KEY= # SendGrid Signed Event Webhook verification key (base64 or PEM).
SMTP_HOST= # SMTP host when EMAIL_PROVIDER=smtp.
SMTP_PORT=587 # SMTP port.
SMTP_SECURE=false # Whether SMTP uses TLS from connection start.
SMTP_USER= # SMTP username.
SMTP_PASS= # SMTP password.
SMTP_FROM=noreply@stellaredupay.com # Default sender address for email.
SMTP_FROM_EMAIL= # Default sender email for admin alerts (falls back to SMTP_USER).
SENDGRID_API_KEY= # SendGrid API key when EMAIL_PROVIDER=sendgrid.
AWS_REGION= # AWS region when EMAIL_PROVIDER=ses.
TWILIO_ACCOUNT_SID= # Twilio Account SID for SMS/WhatsApp.
TWILIO_AUTH_TOKEN= # Twilio auth token.
TWILIO_FROM_NUMBER= # Twilio SMS sender number.
TWILIO_WHATSAPP_FROM= # Twilio WhatsApp sender address.
ADMIN_ALERT_EMAIL= # Email address for admin alerts (warn + critical severity).
ADMIN_ALERT_WEBHOOK_URL= # Webhook URL for critical alerts only.

# Webhooks, metrics, and secrets
METRICS_TOKEN=change_me_to_a_32_character_metrics_token # Bearer token required for GET /metrics.
AUDIT_HMAC_KEY= # Optional audit integrity HMAC key; falls back to JWT_SECRET.
WEBHOOK_SECRET_ENCRYPTION_KEY= # 64-character hex key for stored webhook secrets.
WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS=300 # Inbound webhook timestamp tolerance.
WEBHOOK_REPLAY_WINDOW_S=300 # Outbound webhook replay window.
WEBHOOK_SECRET_ROTATION_OVERLAP_S=86400 # Default dual-signing overlap after POST /api/webhook-endpoints/:id/rotate-secret (max 7 days).
WEBHOOK_V1_SUNSET=2027-02-28 # Date (UTC, inclusive) after which the deprecated V1 webhook signature is never sent.
WEBHOOK_MAX_ATTEMPTS=3 # Maximum webhook delivery attempts.
WEBHOOK_LEASE_TIMEOUT_MS=30000 # Webhook delivery lease timeout.
WEBHOOK_RETRY_INTERVAL_MS=60000 # Webhook retry scheduler interval.
WEBHOOK_DELIVERY_TTL_SECONDS=7776000 # Webhook delivery record retention.
RECEIPT_SIGNATURE_SECRET=change_me_receipt_signature_secret # Secret used to sign receipts.
SIGNER_MASTER_KEY= # 64-character hex master key for encrypted school signing keys.
SIGNER_MASTER_KEY_OLD= # Previous signer master key during key rotation.

# Logging and realtime updates
LOG_LEVEL=info # Initial application log level.
LOG_MAX_SIZE=100m # Maximum size of each rotated log file.
LOG_MAX_FILES=14d # Number or age of rotated log files to keep.
LOG_REDACT_FIELDS=txHash,studentId,memo,senderAddress # Request fields redacted from logs.
LOG_REQUEST_HEADERS=false # Whether request headers are included in request logs.
SSE_HEARTBEAT_MS=15000 # Server-sent events heartbeat interval.
SSE_MAX_CONNECTIONS_PER_SCHOOL=100 # Server-sent events connection cap per school.

# Docker Compose and local operations
NEXT_PUBLIC_API_URL=http://localhost:5000/api # Frontend API URL passed as a Docker build arg.
BACKEND_MEM_LIMIT=512m # Backend container memory limit.
BACKEND_CPUS=1.0 # Backend container CPU limit.
FRONTEND_MEM_LIMIT=256m # Frontend container memory limit.
FRONTEND_CPUS=0.5 # Frontend container CPU limit.
MONGO_MEM_LIMIT=1g # Mongo container memory limit.
MONGO_CPUS=1.0 # Mongo container CPU limit.
REDIS_MEM_LIMIT=128m # Redis container memory limit.
BACKUP_DIR=./backups # Host directory mounted for Mongo backups.
RETAIN_DAYS=7 # Backup retention period in days.
GRAFANA_PASSWORD=admin # Local Grafana admin password for docker-compose.monitoring.yml.