.env.example

# =============================================================================
# Stellabill Backend — Environment Variable Reference
# =============================================================================
# Copy this file to .env and fill in real values.
# NEVER commit .env to version control — it is listed in .gitignore.
#
# Legend:
#   [REQUIRED]          — must be set in all environments or the server refuses to start.
#   [REQUIRED:prod]     — must be set in production/staging; optional in development.
#   [OPTIONAL]          — has a safe built-in default; override only when needed.
# =============================================================================

# -----------------------------------------------------------------------------
# Application
# -----------------------------------------------------------------------------

# [OPTIONAL] Runtime environment label. Affects CORS and logging behaviour.
# Values: development | staging | production
ENV=development

# [OPTIONAL] TCP port the HTTP server listens on. Range: 1–65535.
PORT=8080

# -----------------------------------------------------------------------------
# Database
# -----------------------------------------------------------------------------

# [REQUIRED] PostgreSQL connection string.
# Format: postgres://USER:PASSWORD@HOST:PORT/DBNAME?sslmode=require
# Use sslmode=require in production; sslmode=disable is acceptable for local dev.
DATABASE_URL=postgres://stellabill:changeme@localhost:5432/stellabill_dev?sslmode=disable

# [OPTIONAL] Read replica PostgreSQL connection string.
# If not set, falls back to DATABASE_URL (primary).
DATABASE_REPLICA_URL=postgres://stellabill:changeme@localhost:5432/stellabill_replica?sslmode=disable

# -----------------------------------------------------------------------------
# Authentication & authorisation
# -----------------------------------------------------------------------------

# [REQUIRED] HMAC secret used to sign and verify JWT tokens.
# Minimum 12 characters containing uppercase, lowercase, digit, and special character.
# Generate a strong value: openssl rand -base64 32
JWT_SECRET=CHANGE_ME_jwt_Secret1!

# [REQUIRED] Bearer token that protects admin-only endpoints.
# Same strength requirements as JWT_SECRET.
# Generate a strong value: openssl rand -base64 32
ADMIN_TOKEN=CHANGE_ME_admin_Token1!

# -----------------------------------------------------------------------------
# CORS
# -----------------------------------------------------------------------------

# [REQUIRED:prod] Comma-separated list of allowed HTTPS origins.
# In development the server defaults to allowing all origins (*).
# In production/staging set this to your exact frontend origin(s).
# Example: https://app.example.com,https://admin.example.com
ALLOWED_ORIGINS=http://localhost:3000
OUTBOX_PUBLISHER_CA_FILE=

# [OPTIONAL] Encrypt sensitive outbox payloads with subscriber JWKs (JWE).
OUTBOX_JWE_ENABLED=false
OUTBOX_JWE_SENSITIVE_EVENT_TYPES=webhook.received,payment.processed

# [OPTIONAL] Probability (0.0–1.0) of injecting a context cancellation into
# each outbox publish call. Only active when ENV=staging. Set to 0 to disable.
# Example: CHAOS_OUTBOX_PROB=0.1 (10 % chance per publish).
CHAOS_OUTBOX_PROB=0
# -----------------------------------------------------------------------------
# HTTP server tuning
# -----------------------------------------------------------------------------

# [OPTIONAL] Maximum size of request headers in bytes. Range: 1024–10485760 (10 MB).
MAX_HEADER_BYTES=1048576

# [OPTIONAL] Read, write, and idle timeouts in seconds. Range: 1–600.
READ_TIMEOUT=30
WRITE_TIMEOUT=30
IDLE_TIMEOUT=120

# -----------------------------------------------------------------------------
# Request / body size limits
# -----------------------------------------------------------------------------

# [OPTIONAL] Maximum raw request body size in bytes (default 10 MB).
MAX_REQUEST_SIZE=10485760

# [OPTIONAL] Maximum uncompressed size of a gzip body in bytes (default 50 MB).
MAX_GZIP_UNCOMPRESSED=52428800

# [OPTIONAL] Maximum allowed compression ratio before the request is rejected
# (uncompressed / compressed). Protects against zip-bomb attacks. Default: 10.
MAX_GZIP_RATIO=10.0

# -----------------------------------------------------------------------------
# Security headers
# -----------------------------------------------------------------------------

# [OPTIONAL] Value for the Content-Security-Policy frame-ancestors directive.
# Use 'none' to block all framing (recommended for APIs).
SECURITY_FRAME_ANCESTORS='none'

# -----------------------------------------------------------------------------
# Rate limiting
# -----------------------------------------------------------------------------

# [OPTIONAL] Enable or disable the rate limiter. Values: true | false.
RATE_LIMIT_ENABLED=true

# [OPTIONAL] Rate-limiting strategy. Values: ip | user | hybrid.
RATE_LIMIT_MODE=ip

# [OPTIONAL] Sustained request rate per second. Range: 1–1000.
RATE_LIMIT_RPS=10

# [OPTIONAL] Maximum burst above the sustained rate. Range: 1–2000.
# Must be >= RATE_LIMIT_RPS.
RATE_LIMIT_BURST=20

# [OPTIONAL] Comma-separated URL paths exempt from rate limiting.
# Each path must start with '/'.
RATE_LIMIT_WHITELIST=/api/health

# -----------------------------------------------------------------------------
# Tracing
# -----------------------------------------------------------------------------

# [OPTIONAL] Trace exporter backend. Values: stdout | otlp | none.
TRACING_EXPORTER=stdout

# [OPTIONAL] Service name reported in trace spans.
TRACING_SERVICE_NAME=stellabill-backend

# [OPTIONAL] Enable bounded in-process tail decisions. Default: false.
TRACING_TAIL_ENABLED=false

# [OPTIONAL] Always retain traces whose server root takes at least this many
# milliseconds. Range: 1-600000. Default: 1000.
TRACING_TAIL_LATENCY_MS=1000

# [OPTIONAL] Baseline fraction of ordinary traces retained when tail sampling
# is enabled. Errors, 5xx responses, and slow requests are always retained.
# Range: 0.0-1.0. Default: 0.05.
TRACING_TAIL_ERROR_RATE=0.05

# -----------------------------------------------------------------------------
# Database connection pool
# -----------------------------------------------------------------------------
# All durations are in seconds. Invalid values are ignored and the built-in
# default is used instead (the server will log a warning).

# [OPTIONAL] Maximum total open connections. Range: 1–500. Default: 25.
DB_POOL_MAX_CONNS=25

# [OPTIONAL] Minimum connections kept warm. Range: 0–500. Default: 2.
DB_POOL_MIN_CONNS=2

# [OPTIONAL] Recycle connections after this many seconds. Default: 3600 (1 h).
DB_POOL_MAX_CONN_LIFETIME=3600

# [OPTIONAL] Evict idle connections after this many seconds. Default: 600 (10 min).
# Must be less than DB_POOL_MAX_CONN_LIFETIME.
DB_POOL_MAX_CONN_IDLE_TIME=600

# [OPTIONAL] Per-dial connection timeout in seconds. Range: 1–300. Default: 5.
DB_POOL_CONNECT_TIMEOUT=5

# [OPTIONAL] How often pgxpool probes idle connections in seconds. Default: 30.
DB_POOL_HEALTH_CHECK_PERIOD=30

# [OPTIONAL] How often pool metrics are scraped into Prometheus in seconds. Default: 15.
DB_POOL_METRICS_INTERVAL=15

# -----------------------------------------------------------------------------
# Audit logging
# -----------------------------------------------------------------------------

# [OPTIONAL] HMAC secret used to sign audit log entries (tamper-evident chain).
# Use a value distinct from JWT_SECRET.
AUDIT_HMAC_SECRET=CHANGE_ME_audit_Hmac1!

# [OPTIONAL] File path for the audit log (JSON Lines). Default: audit.log.
AUDIT_LOG_PATH=audit.log

# -----------------------------------------------------------------------------
# Legacy API deprecation
# -----------------------------------------------------------------------------

# [OPTIONAL] HTTP-date or RFC3339 timestamp emitted as the Sunset header on
# legacy /api/* aliases. Leave unset to omit Sunset while keeping Deprecation
# and successor Link headers.
LEGACY_API_SUNSET="Thu, 31 Dec 2026 23:59:59 GMT"

# -----------------------------------------------------------------------------
# Feature flags
# -----------------------------------------------------------------------------
# Individual flags use the FF_ prefix. Unknown flags default to false (fail-safe).

# [OPTIONAL] Enable subscription management endpoints. Default: true.
FF_SUBSCRIPTIONS_ENABLED=true

# [OPTIONAL] Enable billing plans endpoints. Default: true.
FF_PLANS_ENABLED=true

# [OPTIONAL] Enable the new billing flow. Default: false.
FF_NEW_BILLING_FLOW=false

# [OPTIONAL] Enable advanced analytics endpoints. Default: false.
FF_ADVANCED_ANALYTICS=false

# [OPTIONAL] Default state for any flag not explicitly listed above. Default: false.
FF_DEFAULT_ENABLED=false

# [OPTIONAL] Log a warning when a feature flag blocks a request. Default: true.
FF_LOG_DISABLED=true

# [OPTIONAL] Path to a JSON feature-flags config file (alternative to FF_* vars).
# FF_* individual vars take priority over this file.
FF_CONFIG_FILE=