.env.example

# =====================================
# Stellar Micro-Donation API — .env.example
#
# Copy this file to .env and fill in the values:
#   cp .env.example .env
#
# Variables marked REQUIRED must be set before the server will start.
# Variables marked OPTIONAL have safe defaults and can be left commented.
# Full documentation: docs/CONFIGURATION.md
# =====================================


# =====================================
# Server Configuration
# =====================================

# Port the API server listens on.
PORT=3000

# Runtime environment. Use "development" locally, "production" in prod.
NODE_ENV=development

# Base path prefix prepended to all API routes.
# OPTIONAL — default: /api/v1
# API_PREFIX=/api/v1

# Comma-separated list of trusted proxy IPs/CIDRs (Express trust proxy).
# Set to your load balancer address in production.
# OPTIONAL — default: loopback
# TRUSTED_PROXIES=loopback

# Unique identifier for this instance (appears in structured log output).
# OPTIONAL — default: hostname
# INSTANCE_ID=

# Milliseconds to wait for in-flight requests to drain before force-exit.
# OPTIONAL — default: 30000
# SHUTDOWN_TIMEOUT_MS=30000

# Global per-request timeout in milliseconds. Streaming endpoints are exempt.
# OPTIONAL — default: 30000
# REQUEST_TIMEOUT_MS=30000


# =====================================
# Authentication (REQUIRED)
# =====================================

# Comma-separated list of API keys accepted by the legacy auth path.
# At least one key is required for any request to be authenticated.
# Example: dev_key_1234567890,dev_key_abcdef123456
API_KEYS=dev_key_1234567890,dev_key_abcdef123456

# Secret used to sign and verify JWT tokens.
# OPTIONAL — must satisfy secret strength rules if set
# JWT_SECRET=

# When true, admin endpoints require a valid TOTP code alongside the API key.
# OPTIONAL — default: false
# REQUIRE_ADMIN_2FA=false

# Issuer label embedded in TOTP QR codes.
# OPTIONAL — default: StellarDonationAPI
# TOTP_ISSUER=StellarDonationAPI

# Number of 30-second TOTP windows (±) accepted to tolerate clock skew.
# OPTIONAL — default: 1
# TOTP_WINDOW=1

# Seconds a SEP-10 challenge token remains valid.
# OPTIONAL — default: 300
# SEP10_CHALLENGE_TTL=300

# Stellar home domain used in SEP-10 web-auth challenges.
# OPTIONAL
# HOME_DOMAIN=

# Maximum failed authentication attempts before IP lockout.
# OPTIONAL — default: 5
# AUTH_MAX_ATTEMPTS=5

# Rolling window (ms) in which AUTH_MAX_ATTEMPTS failures trigger lockout.
# OPTIONAL — default: 60000
# AUTH_WINDOW_MS=60000

# Duration (ms) of the authentication lockout (default 15 min).
# OPTIONAL — default: 900000
# AUTH_LOCKOUT_MS=900000

# When true, every mutating request must carry a valid HMAC request signature.
# OPTIONAL — default: false
# REQUIRE_REQUEST_SIGNING=false

# HMAC secret used to verify inbound request signatures.
# OPTIONAL — required when REQUIRE_REQUEST_SIGNING=true
# REQUEST_SIGNING_SECRET=

# Seconds of clock skew tolerated in signed requests.
# OPTIONAL — default: 300
# REQUEST_SIGNING_WINDOW_SECONDS=300

# When true, POST/PATCH/PUT requests without X-Idempotency-Key are rejected.
# OPTIONAL — default: false
# REQUIRE_IDEMPOTENCY_KEY=false

# Lifetime of signed download/export URLs in milliseconds.
# OPTIONAL — default: 3600000 (1 hour)
# SIGNED_URL_EXPIRY_MS=3600000


# =====================================
# Encryption (REQUIRED)
# =====================================

# A stable 64-hex-character (32-byte) key used to encrypt sensitive data
# such as wallet secret keys stored in the database.
#
# ⚠  The server will REFUSE TO START if this is not set.
# ⚠  Changing this key makes all previously encrypted data unrecoverable.
#
# Generate a key:
#   npm run generate-key
#
# Then replace the placeholder below with the output.
ENCRYPTION_KEY=<run `npm run generate-key` and paste the 64-char hex output here>

# Previous encryption key used during key rotation.
# OPTIONAL — required when ENCRYPTION_KEY_VERSION=1
# ENCRYPTION_KEY_1=

# Active key version index. Set to 1 during key rotation.
# OPTIONAL — default: 0
# ENCRYPTION_KEY_VERSION=0

# Target key during a live re-encryption pass (npm run migrate:reencrypt).
# OPTIONAL
# NEW_ENCRYPTION_KEY=

# HMAC secret for signing CSV/JSON export files. Must be distinct from ENCRYPTION_KEY.
# OPTIONAL
# EXPORT_SIGNING_SECRET=

# Secret from which anonymous donor tokens are derived. Must be distinct from ENCRYPTION_KEY.
# OPTIONAL
# ANONYMOUS_DONATION_SECRET=

# Signing backend: local (in-process), hsm, or kms.
# OPTIONAL — default: local
# SIGNING_PROVIDER=local


# =====================================
# Stellar Network Configuration
# =====================================

# Stellar environment to target.
# Allowed values: testnet | mainnet | futurenet
STELLAR_NETWORK=testnet

# Use mock Stellar responses — no outbound network calls are made.
# ✅ Keep true for local development and CI (no Stellar account needed).
# Set to false only when you need to test against a real Stellar network.
MOCK_STELLAR=true

# Artificial delay (ms) injected by the mock Stellar service.
# OPTIONAL — default: 0
# MOCK_STELLAR_LATENCY_MS=0

# Optional: override the Horizon endpoint for the selected network.
# Leave commented to use the default URL for STELLAR_NETWORK.
# HORIZON_URL=https://horizon-testnet.stellar.org

# Comma-separated list of fallback Horizon endpoints for automatic failover.
# When the primary endpoint fails health checks for consecutive attempts, the pool
# automatically switches to the first healthy fallback. Recovers to primary after cooldown.
# Example: HORIZON_FALLBACK_URLS=https://horizon.stellar.org,https://horizon-backup.stellar.org
# OPTIONAL — default: empty (no fallback)
# HORIZON_FALLBACK_URLS=

# Number of consecutive health check failures before failing over to a fallback endpoint.
# OPTIONAL — default: 3
# HORIZON_FAILOVER_THRESHOLD=3

# Cooldown period (ms) before attempting to switch back to the primary endpoint after recovery.
# OPTIONAL — default: 60000 (1 minute)
# HORIZON_RECOVERY_COOLDOWN_MS=60000

# Number of parallel Horizon HTTP connections per pool.
# OPTIONAL — default: 5
# HORIZON_POOL_SIZE=5

# Timeout (ms) for Horizon API requests.
# OPTIONAL — default: 15000
# HORIZON_API_TIMEOUT_MS=15000

# Timeout (ms) for transaction submission to Horizon.
# OPTIONAL — default: 30000
# HORIZON_SUBMIT_TIMEOUT_MS=30000

# Timeout (ms) for Horizon SSE stream connections.
# OPTIONAL — default: 60000
# HORIZON_STREAM_TIMEOUT_MS=60000

# Maximum number of automatic retries for failed Horizon requests.
# OPTIONAL — default: 3
# HORIZON_MAX_RETRY_ATTEMPTS=3

# Circuit breaker: failures before circuit opens.
# OPTIONAL — default: 5
# HORIZON_CB_FAILURE_THRESHOLD=5

# Circuit breaker: cooldown period (ms) after opening.
# OPTIONAL — default: 30000
# HORIZON_CB_COOLDOWN_MS=30000

# Multiplier applied to the network base fee when constructing transactions.
# OPTIONAL — default: 1
# STELLAR_FEE_MULTIPLIER=1

# Number of ledgers required before a transaction is considered confirmed.
# OPTIONAL — default: 3
# CONFIRMATION_LEDGER_THRESHOLD=3

# Minimum XLM balance required in a wallet for operations.
# OPTIONAL — default: 1
# MIN_RESERVE_XLM=1

# Interval (ms) between automatic transaction reconciliation runs.
# OPTIONAL — default: 30000
# TX_SYNC_INTERVAL_MS=30000

# Stellar secret key for service-initiated signing operations.
# Leave commented unless you explicitly need service signing.
# ⚠  Never commit a real secret key.
# SERVICE_SECRET_KEY=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Stellar secret key of the fee-bump sponsor account.
# OPTIONAL
# SPONSOR_SECRET=

# ── Service Account Balance Monitor ─────────────────────────────────────────
# Watches the fee-bump / scheduled-donation service account so operators are
# alerted before STELLAR_OP_UNDERFUNDED failures start occurring.

# Public key of the service account to monitor.
# OPTIONAL — defaults to the account derived from SERVICE_SECRET_KEY.
# SERVICE_ACCOUNT_PUBLIC_KEY=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# How often (ms) to check the service account balance via Horizon.
# OPTIONAL — default: 300000 (5 minutes)
# BALANCE_CHECK_INTERVAL_MS=300000

# Balance (XLM) below which an "account.balance_low" webhook fires.
# OPTIONAL — default: 10
# BALANCE_ALERT_THRESHOLD_XLM=10

# Balance (XLM) below which the recurring donation scheduler is paused and an
# admin notification email is sent. Scheduler auto-resumes once restored.
# OPTIONAL — default: 2
# BALANCE_CRITICAL_THRESHOLD_XLM=2

# Recipient address for critical low-balance admin notification emails.
# Requires SMTP_HOST to also be configured.
# OPTIONAL
# ADMIN_ALERT_EMAIL=

# Stellar public key of the organisation's primary receiving account.
# OPTIONAL
# ORGANIZATION_ADDRESS=


# =====================================
# Database Configuration
# =====================================

# Path to the SQLite database file (relative to project root).
DB_PATH=./data/stellar_donations.db

# Maximum number of reusable SQLite connections in the in-process pool.
# OPTIONAL — default: 5
# DB_POOL_SIZE=5

# Minimum number of idle connections kept in the pool.
# OPTIONAL — default: 1
# DB_POOL_MIN=1

# Milliseconds to wait for a pooled connection before failing.
# OPTIONAL — default: 10000
# DB_ACQUIRE_TIMEOUT=10000

# Timeout (ms) applied to individual SQL queries.
# OPTIONAL — default: 5000
# DB_QUERY_TIMEOUT_MS=5000

# Queries exceeding this threshold (ms) are logged as slow.
# OPTIONAL — default: 1000
# SLOW_QUERY_THRESHOLD_MS=1000

# Number of days to retain audit log entries before purging.
# OPTIONAL — default: 90
# AUDIT_LOG_RETENTION_DAYS=90

# Cron expression for the data-retention cleanup job.
# OPTIONAL — default: 0 2 * * * (2 AM daily)
# RETENTION_SCHEDULE_CRON=0 2 * * *

# When true, the retention job logs what it would delete without removing records.
# OPTIONAL — default: false
# RETENTION_DRY_RUN=false


# =====================================
# CORS Configuration
# =====================================

# Comma-separated list of allowed origins for browser-based clients.
# Development default allows common localhost ports.
# Production: set this explicitly — leaving it unset rejects all browser origins.
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001,http://localhost:8080

# OPTIONAL overrides (uncomment to customise):
# CORS_ALLOWED_METHODS=GET,POST,PUT,PATCH,DELETE,OPTIONS
# CORS_ALLOWED_HEADERS=Content-Type,Authorization,X-API-Key,X-Request-ID,X-Idempotency-Key
# CORS_MAX_AGE=86400


# =====================================
# Logging Configuration
# =====================================

# Enable verbose debug logging — useful for local troubleshooting.
# ⚠  Never enable in production; may expose sensitive information.
DEBUG_MODE=false

# Write logs to files in addition to the console.
LOG_TO_FILE=false

# Directory for log files when LOG_TO_FILE=true.
LOG_DIR=./logs

# Include request/response bodies in console output.
LOG_VERBOSE=false

# Minimum log level: error | warn | info | debug
# OPTIONAL — default: info
# LOG_LEVEL=info

# Log output format: json | pretty
# OPTIONAL — default: json
# LOG_FORMAT=json

# Log raw request and response bodies.
# OPTIONAL — default: false
# LOG_BODY=false

# Fraction of requests to log (0-1). 1 logs every request.
# OPTIONAL — default: 1
# LOG_SAMPLE_RATE=1


# =====================================
# Donation Limits (XLM) — OPTIONAL
# =====================================

# Minimum donation amount accepted by validation.
MIN_DONATION_AMOUNT=0.01

# Maximum donation amount accepted by validation.
MAX_DONATION_AMOUNT=10000

# Daily cap per donor (0 = no limit).
MAX_DAILY_DONATION_PER_DONOR=0

# Platform fee percentage deducted from each donation (0-100).
# OPTIONAL — default: 0
# PLATFORM_FEE_PERCENT=0

# Maximum number of donations processed in parallel during batch submission.
# OPTIONAL — default: 5
# BULK_DONATION_CONCURRENCY=5

# Days after which a donation can no longer be disputed.
# OPTIONAL — default: 30
# DISPUTE_WINDOW_DAYS=30

# Hours after a donation during which a refund can be initiated.
# OPTIONAL — default: 24
# REFUND_WINDOW_HOURS=24

# Maximum number of rows accepted per bulk wallet-import request.
# OPTIONAL — default: 1000
# BULK_IMPORT_MAX_ROWS=1000


# =====================================
# Rate Limiting — OPTIONAL
# =====================================

# Max requests per IP per time window.
RATE_LIMIT=100

# Auth token endpoint rate limit (requests per minute per IP).
# OPTIONAL — default: 10
AUTH_TOKEN_RATE_LIMIT=10

# Auth refresh endpoint rate limit (requests per minute per IP).
# OPTIONAL — default: 20
AUTH_REFRESH_RATE_LIMIT=20

# Backing store for rate-limit counters: memory | redis
# Use redis in multi-instance deployments.
# OPTIONAL — default: memory
# RATE_LIMIT_STORE=memory

# Redis connection URL. Required when RATE_LIMIT_STORE=redis.
# OPTIONAL
# REDIS_URL=redis://localhost:6379

# When RATE_LIMIT_STORE=redis, controls behaviour on Redis unavailability.
# true = allow requests (fail open); false = deny requests (fail closed).
# OPTIONAL — default: true
# RATE_LIMIT_FAIL_OPEN=true


# =====================================
# Caching — OPTIONAL
# =====================================

# Maximum entries in the shared in-memory LRU cache.
# OPTIONAL — default: 1000
# CACHE_MAX_SIZE=1000

# TTL (seconds) for cached wallet-balance responses.
# OPTIONAL — default: 30
# WALLET_BALANCE_CACHE_TTL_SECONDS=30

# TTL (seconds) for the in-memory API key lookup cache.
# OPTIONAL — default: 60
# API_KEY_CACHE_TTL_SECONDS=60

# TTL (seconds) for the donation stats cache.
# OPTIONAL — default: 60
# STATS_CACHE_TTL_SECONDS=60


# =====================================
# Service Account — OPTIONAL
# =====================================

# Stellar secret key for service-side signing operations.
# Leave commented unless you explicitly need service signing.
# ⚠  Never commit a real secret key.
# SERVICE_SECRET_KEY=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX


# =====================================
# Price Oracle (CoinGecko) — OPTIONAL
# =====================================

# CoinGecko API key for XLM/fiat exchange rates (demo/free plan, "CG-…" format).
# Without a key the public endpoint is used, which has stricter rate limits.
# Get one at https://www.coingecko.com/en/api
# COINGECKO_API_KEY=

# When CoinGecko is unavailable, XLM/USD is derived from the mid-market price of
# the XLM/USDC orderbook on the Stellar DEX. Defaults to the Circle USDC issuer
# for the active network; override to price against a different stablecoin.
# XLM_USDC_ASSET=USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN


# =====================================
# IPFS Certificate Pinning (Pinata) — OPTIONAL
# =====================================

# Pinata API key + secret for pinning donation impact certificates to IPFS.
# Without these, certificates fall back to local in-memory storage.
# Get them at https://app.pinata.cloud/developers/api-keys
# PINATA_API_KEY=
# PINATA_SECRET_KEY=

# Public IPFS gateway base URL for certificate links.
# OPTIONAL — default: https://gateway.pinata.cloud/ipfs
# IPFS_GATEWAY_URL=https://gateway.pinata.cloud/ipfs


# =====================================
# Email Receipts (SMTP) — OPTIONAL
# =====================================

# SMTP relay for sending donation receipt emails (any provider works,
# e.g. Brevo, Gmail app password, Mailgun). Without these, email
# delivery is skipped/fails gracefully.
# SMTP_HOST=smtp-relay.brevo.com
# SMTP_PORT=587
# SMTP_SECURE=false
# SMTP_USER=
# SMTP_PASS=
# SMTP_FROM must be a sender address verified with your provider.
# SMTP_FROM=


# =====================================
# Geographic IP Blocking — OPTIONAL
# =====================================

# Comma-separated ISO country codes to block (e.g. RU,IR,KP,CU).
# GEO_BLOCKED_COUNTRIES=

# Comma-separated ISO country codes to always allow (overrides blocked list).
# GEO_ALLOWED_COUNTRIES=

# Comma-separated IPs / CIDR ranges that bypass geo-blocking.
# GEO_ALLOWED_IPS=

# Path to MaxMind GeoLite2-Country.mmdb (default: ./data/GeoLite2-Country.mmdb).
# MAXMIND_DB_PATH=./data/GeoLite2-Country.mmdb


# =====================================
# Abuse Detection — OPTIONAL
# =====================================

# Rolling window (ms) in which request counts are tracked for burst detection.
# OPTIONAL — default: 60000
# ABUSE_WINDOW_MS=60000

# Number of requests within ABUSE_WINDOW_MS that triggers the burst-detection signal.
# OPTIONAL — default: 100
# ABUSE_SUSPICIOUS_THRESHOLD=100

# Duration (ms) a flagged IP remains in the suspicious list.
# OPTIONAL — default: 3600000 (1 hour)
# ABUSE_BLOCK_DURATION_MS=3600000

# Path to a persistent SQLite file for abuse-detection tracking.
# When unset, tracking is in-memory only.
# ABUSE_DB_PATH=


# =====================================
# Replay & Deduplication — OPTIONAL
# =====================================

# Window (seconds) within which a duplicate request signature is rejected.
# OPTIONAL — default: 300
# REPLAY_WINDOW_SECONDS=300

# Window (ms) within which identical request body hashes are deduplicated.
# OPTIONAL — default: 60000
# DEDUP_WINDOW_MS=60000

# Maximum entries in the in-memory deduplication cache.
# OPTIONAL — default: 10000
# DEDUP_MEM_CACHE_MAX_SIZE=10000


# =====================================
# Backup — OPTIONAL
# =====================================

# Local directory where encrypted database backup files are written.
# OPTIONAL — default: ./data/backups
# BACKUP_DIR=./data/backups

# Interval (ms) between automatic backup runs.
# OPTIONAL — default: 3600000 (1 hour)
# BACKUP_INTERVAL_MS=3600000

# S3 bucket name for off-site backup upload. When unset, backups are local only.
# BACKUP_S3_BUCKET=

# AWS region used for S3 backup uploads.
# OPTIONAL — default: us-east-1
# AWS_REGION=us-east-1


# =====================================
# SSE / WebSocket Streaming — OPTIONAL
# =====================================

# Maximum concurrent SSE connections allowed per API key.
# OPTIONAL — default: 10
# SSE_MAX_CONNECTIONS_PER_KEY=10

# Number of events buffered per SSE connection for reconnecting clients.
# OPTIONAL — default: 100
# SSE_EVENT_BUFFER_SIZE=100

# Maximum number of wallet subscriptions per WebSocket connection.
# OPTIONAL — default: 50
# WS_MAX_WALLETS=50

# Interval (ms) between WebSocket ping frames.
# OPTIONAL — default: 30000
# WS_HEARTBEAT_MS=30000


# =====================================
# Observability & Tracing — OPTIONAL
# =====================================

# Enable OpenTelemetry trace/metric export.
# OPTIONAL — default: false
# OTEL_ENABLED=false

# Service name reported to the OTLP collector.
# OPTIONAL — default: stellar-donation-api
# OTEL_SERVICE_NAME=stellar-donation-api

# OTLP exporter endpoint URL.
# OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318

# URL to POST anomaly-detection alerts to. When unset, alerts are logged only.
# ANOMALY_WEBHOOK_URL=


# =====================================
# Organisation Metadata — OPTIONAL
# (embedded in generated PDF receipts and tax documents)
# =====================================

# ORGANIZATION_LEGAL_NAME=
# ORGANIZATION_EIN=
# ORGANIZATION_EMAIL=
# ORGANIZATION_PHONE=
# ORGANIZATION_CITY=
# ORGANIZATION_STATE=
# ORGANIZATION_ZIP_CODE=
# ORGANIZATION_WEBSITE=


# =====================================
# Signing Providers (HSM / KMS) — OPTIONAL
# =====================================

# Signing backend: local | hsm | kms (default: local)
# SIGNING_PROVIDER=local

# PKCS#11 slot ID — required when SIGNING_PROVIDER=hsm
# HSM_SLOT_ID=

# PKCS#11 slot PIN — required when SIGNING_PROVIDER=hsm
# HSM_PIN=

# Cloud KMS provider: aws | gcp — required when SIGNING_PROVIDER=kms
# KMS_PROVIDER=

# KMS key ARN (AWS) or resource name (GCP)
# KMS_KEY_ID=


# =====================================
# Miscellaneous / Feature Config — OPTIONAL
# =====================================

# JSON object of feature-flag overrides, e.g. {"newDonationFlow":true}
# See docs/FEATURE_FLAGS_RUNTIME.md for available flags.
# FEATURE_FLAGS=

# Publicly accessible base URL of this API (used in generated links).
# API_BASE_URL=http://localhost:3000

# URI to which CSP violation reports are sent.
# CSP_REPORT_URI=

# When true, CSP violations are reported but not enforced.
# OPTIONAL — default: false
# CSP_REPORT_ONLY=false

# When true, TLS certificate verification is disabled for outbound webhook deliveries.
# ⚠  Never use in production.
# OPTIONAL — default: false
# WEBHOOK_ALLOW_TLS_SKIP_VERIFY=false