.env.example

# ══════════════════════════════════════════════════════════════════════════════
# ENVIRONMENT TEMPLATE — Copy to .env and fill in your values
# ══════════════════════════════════════════════════════════════════════════════
# ⚠️  IMPORTANT: Never commit .env to git. It is already in .gitignore.
# This file contains PLACEHOLDER VALUES ONLY for local development.
# For production, use your cloud provider's secrets manager (AWS Secrets Manager, etc).
# See ENV_VARS.md for detailed documentation and security guidelines.
# ══════════════════════════════════════════════════════════════════════════════

NODE_ENV="development"
PORT=5000
API_VERSION="v1"

DATABASE_URL="postgresql://acbu_user:acbu_pass@localhost:5432/acbu_db"
# Optional: Read-replica for database operations
# DATABASE_URL_REPLICA="postgresql://acbu_user:acbu_pass@localhost:5433/acbu_db"

# Optional: Prisma Accelerate URL for runtime connection pooling (prisma:// protocol).
# Leave unset for local dev. Never use this for prisma migrate — it requires DATABASE_URL above.
# PRISMA_ACCELERATE_URL="prisma://accelerate.prisma-data.net/?api_key=..."
MONGODB_URI="mongodb://localhost:27017/acbu_db"
RABBITMQ_URL="amqp://guest:guest@localhost:5672"
JWT_SECRET="dev-jwt-secret-change-me-min-32-characters-long"
# Required explicitly in production — do not let this fall back to JWT_SECRET,
# they must be distinct trust boundaries. Generate a separate random value.
# CHALLENGE_TOKEN_SECRET=dev-challenge-token-secret-change-me-32chars

JWT_EXPIRES_IN="7d"
JWT_CLOCK_TOLERANCE_SECONDS=30
API_KEY_SALT=""
# ADMIN_API_KEY=""

# BE-001: HMAC secret for the /v1/webhooks/bills/:provider endpoint. Required
# in production once a real bills provider (not simulatedBillsPartner) is wired in.
# BILLS_WEBHOOK_SECRET=change-me-in-production

# CORS — comma-separated exact origins (no *; required in production).
# Unset in development defaults to http://localhost:3000
# CORS_ORIGIN=http://localhost:3000,https://app.example.com

# CDN_URL="https://cdn.example.com"

# B-058: PII field-level encryption key (AES-256-GCM).
# Must be a 64-character hex string (32 bytes). Required in production.
# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# PII_ENCRYPTION_KEY=your-64-char-hex-key-here

# B-063: OpenAI integration (used for KYC document analysis)
# OPENAI_API_KEY=sk-...
# OPENAI_ORG_MONTHLY_BUDGET_USD=50
# OPENAI_MAX_TOKENS_PER_REQUEST=2000

# OpenAI Fail-Open Controls
# OPENAI_FAIL_OPEN_ENABLED=true
# OPENAI_FAIL_OPEN_TIMEOUT_MS=2000
# OPENAI_FAIL_OPEN_MAX_RETRIES=2
# OPENAI_FAIL_OPEN_RETRY_BASE_MS=500

LOG_LEVEL="info"
# LOG_LEVEL_CONSOLE="info"
# LOG_LEVEL_FILE="info"

# ── Memory / heap (#436) ─────────────────────────────────────────────────────
# Cap the V8 heap so OOM kills happen predictably rather than at OS limit.
# Set to ~75% of the container/instance memory. Omit to rely on V8 default (~1.4 GB).
# NODE_OPTIONS=--max-old-space-size=512

# Heap usage percentage (of heap_size_limit) at which a WARNING is logged (default 85).
# MEMORY_LEAK_THRESHOLD_PCT=85

# How often the memory monitor samples heap usage, in milliseconds (default 30000).
# MEMORY_CHECK_INTERVAL_MS=30000

# Directory where .heapsnapshot files are written when heap pressure turns CRITICAL (default ./heapdumps).
# Ensure this path is writable and excluded from your Docker image or .gitignore.
# HEAP_DUMP_DIR=./heapdumps

# Rate Limiting
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=100
AUTH_RATE_LIMIT_WINDOW_MS=900000
AUTH_RATE_LIMIT_MAX_REQUESTS=10

# Rate Limiting Fallback (during cache/MongoDB outages)
# Stricter limits applied when cache is unavailable (fail-safe, not fail-open)
RATE_LIMIT_FALLBACK_MAX_REQUESTS=20
RATE_LIMIT_CIRCUIT_BREAKER_THRESHOLD=5
RATE_LIMIT_CIRCUIT_BREAKER_COOLDOWN_MS=60000

MAX_SIGNIN_ATTEMPTS=5
SIGNIN_LOCKOUT_DURATION_MS=900000

# Business calendar timezone for salary schedules and withdrawal windows (#408)
# BUSINESS_TIMEZONE=Africa/Lagos

# ── Redis cache (not currently used — reserved for future use) ─────────────────
# NOTE: Redis is NOT included in docker-compose.yml and is not used by the
# active cache layer (src/utils/cache.ts uses MongoDB). These variables are
# reserved for a future Redis-backed cache. Do NOT add a Redis service to
# docker-compose unless the codebase is migrated to use it.
# REDIS_URL=redis://localhost:6379
# REDIS_SENTINELS=127.0.0.1:26379,127.0.0.1:26380
# REDIS_SENTINEL_NAME=mymaster
# REDIS_PASSWORD=
# REDIS_MAX_RETRIES_PER_REQUEST=3
# REDIS_READONLY_RETRY_ATTEMPTS=3
# REDIS_READONLY_RETRY_DELAY_MS=100

# Stellar / USDC swap
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
# Optional; defaults to https://soroban-testnet.stellar.org (or mainnet). Set if DNS to default RPC fails.
# STELLAR_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
STELLAR_SECRET_KEY=your-stellar-secret-key-here
# Circle USDC issuer — defaults are the well-known Circle addresses; override for a custom testnet asset (e.g. DemoUSDC)
USDC_ISSUER_TESTNET=GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
USDC_ISSUER_MAINNET=GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
# Stellar asset code for the swap asset (default USDC). For testnet DemoUSDC: set issuer above and e.g. USDC_ASSET_CODE_TESTNET=DemoUSDC
# USDC_ASSET_CODE_TESTNET=DemoUSDC
# USDC_ASSET_CODE_MAINNET=USDC
# Slippage tolerance for USDC→XLM DEX swap (basis points; 50 = 0.5%)
USDC_XLM_SLIPPAGE_BPS=50
# Bulk transfer CSV chunk size (rows per transaction chunk; default 100)
# BULK_TRANSFER_CHUNK_SIZE=100
# Bulk transfer upload limit in bytes (default 10485760 = 10 MiB)
# BULK_TRANSFER_MAX_FILE_SIZE_BYTES=10485760
# Minting contract: initialize with the SAC contract address for this issuer+code so mint_from_usdc matches the DEX asset; ensure a testnet path from that asset to XLM exists.
# CONTRACT_ORACLE=
# CONTRACT_RESERVE_TRACKER=
# CONTRACT_MINTING=
# CONTRACT_BURNING=
# CONTRACT_SAVINGS_VAULT=
# CONTRACT_LENDING_POOL=
# CONTRACT_ESCROW=

# ── S3 / KYC document storage (B-062) ────────────────────────────────────────
# S3 bucket for KYC document uploads (must be private — no public access)
# S3_BUCKET=acbu-kyc-documents
# AWS region for S3 (defaults to AWS_REGION if set)
# AWS_REGION=us-east-1
# S3_REGION=us-east-1
# Explicit credentials — omit to use IAM role / instance profile in production
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
# Optional: S3-compatible endpoint for local dev (e.g. MinIO)
# S3_ENDPOINT=http://localhost:9000
# Presigned URL TTLs (seconds). Defaults: 900 upload, 300 download
# S3_UPLOAD_URL_TTL_SECONDS=900
# S3_DOWNLOAD_URL_TTL_SECONDS=300
# HMAC-SHA256 secret for virus-scan webhook authentication (required in production)
S3_SCAN_WEBHOOK_SECRET=change-me-in-production

# #381: WAL / continuous backup guard.
# Set to "true" once WAL archiving is enabled on the database host
# (e.g. pgBackRest, Barman, AWS RDS automated backups, Supabase PITR).
# The app refuses to start in production until this is explicitly set to true.
# PG_WAL_BACKUP_CONFIGURED=true
# PG_WAL_BACKUP_PROVIDER=pgbackrest

# #383: Prisma migration history replicated guard.
# PRISMA_MIGRATION_HISTORY_REPLICATED=false

# #402: DB Connect Retry
# DB_CONNECT_MAX_RETRIES=8
# DB_CONNECT_BASE_BACKOFF_MS=250
# DB_CONNECT_MAX_BACKOFF_MS=10000

# ── Reserve rebalancing (#627) ───────────────────────────────────────────────
# Percentage drift threshold above which a currency is considered over/underweight
# and rebalancing instructions are generated. Default: 1 (meaning 1%).
# Raise to reduce rebalancing frequency; lower for tighter peg tracking.
# RESERVE_DRIFT_THRESHOLD_PCT=1

# ── Notifications (email / SMS) ───────────────────────────────────────────────
# NOTIFICATION_EMAIL_PROVIDER=log|sendgrid|ses|smtp
# NOTIFICATION_FROM_EMAIL=noreply@acbu.io
# NOTIFICATION_ALERT_EMAIL=ops@example.com
# SENDGRID_API_KEY=
# SMTP_HOST=smtp.example.com
# SMTP_PORT=587
# SMTP_SECURE=false
# SMTP_USER=
# SMTP_PASS=
# SMTP_MAX_CONNECTIONS=5
# SMTP_MAX_MESSAGES=100