.env.example

# ─────────────────────────────────────────────────────────────────────────────
# Disciplr Backend — Environment Variables Reference
#
# Copy this file to .env and fill in real values.
# Lines beginning with "#" are comments and are ignored at runtime.
# NEVER commit your actual .env to version control.
# ─────────────────────────────────────────────────────────────────────────────

# ── Core ──────────────────────────────────────────────────────────────────────

# Runtime environment. One of: development | production | test
NODE_ENV=development

# TCP port the HTTP server listens on (positive integer, default: 3000)
PORT=3000

# Logical service name included in structured log output
SERVICE_NAME=disciplr-backend

# PostgreSQL connection URL (required).
# Must start with postgres:// or postgresql://
DATABASE_URL=postgres://postgres:postgres@localhost:5432/disciplr

# ── CORS ──────────────────────────────────────────────────────────────────────

# Allowed cross-origin request origins (comma-separated http:// or https:// URLs).
# Production: set this explicitly — omitting it blocks ALL cross-origin requests.
# Development / test: defaults to http://localhost:3000 when unset.
# Use CORS_ORIGINS=* only if you intentionally want to allow every origin (not recommended).
# Example (multiple origins): CORS_ORIGINS=https://app.example.com,https://admin.example.com
CORS_ORIGINS=https://app.example.com

# ── Auth / Secrets ────────────────────────────────────────────────────────────

# General-purpose JWT signing secret (minimum 16 characters).
# MUST be changed from the default in production.
JWT_SECRET=change-me-in-production

# Access-token signing secret (minimum 16 characters).
JWT_ACCESS_SECRET=fallback-access-secret

# Refresh-token signing secret (minimum 16 characters).
JWT_REFRESH_SECRET=fallback-refresh-secret

# Access token lifetime — duration string: <number><unit> where unit is s/m/h/d.
JWT_ACCESS_EXPIRES_IN=15m

# Refresh token lifetime.
JWT_REFRESH_EXPIRES_IN=7d

# Secret used to sign file-download tokens (minimum 16 characters).
# MUST be changed from the default in production.
DOWNLOAD_SECRET=change-me-in-production

# ── Field encryption (reversible secrets at rest) ─────────────────────────────
#
# Reversible secrets that cannot be hashed (e.g. webhook HMAC signing secrets)
# are encrypted at rest with AES-256-GCM. Required in any environment that reads
# or writes those columns. See docs/field-encryption.md for the rotation runbook.
#
# Single-key shorthand: a base64-encoded 32-byte key (used under key id "default").
# Generate with:  openssl rand -base64 32
FIELD_ENCRYPTION_KEY=GENERATE_WITH_openssl_rand_base64_32
#
# Multi-key form for rotation: a JSON array of { kid, key } objects. The FIRST
# entry is the active key used to encrypt new data; the rest are retained so
# data written under a retired key id still decrypts. If set, this takes
# precedence over FIELD_ENCRYPTION_KEY.
# FIELD_ENCRYPTION_KEYS=[{"kid":"2026-06","key":"BASE64_32_BYTES"},{"kid":"2026-01","key":"OLD_BASE64_32_BYTES"}]

# ── Soroban ──────────────────────────────────────────────────────────────────────

# Soroban contract ID (56-char base32 starting with C). Required for submit mode.
SOROBAN_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Soroban network passphrase (e.g., Test SDF Network ; September 2015)
SOROBAN_NETWORK_PASSPHRASE=Test SDF Network ; September 2015

# Soroban source account (public key starting with G)
SOROBAN_SOURCE_ACCOUNT=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Soroban RPC URL (https endpoint)
SOROBAN_RPC_URL=https://example.com/soroban-rpc

# Soroban secret key (private key starting with S) – keep this secret!
SOROBAN_SECRET_KEY=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
# Stellar Horizon API endpoint (required when the Horizon listener is active).
# Must be a valid http:// or https:// URL.
HORIZON_URL=https://horizon-testnet.stellar.org

# Soroban contract address(es) to monitor (comma-separated; required with listener).
CONTRACT_ADDRESS=CDISCIPLR1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890

# Starting ledger sequence number (non-negative integer, default: 0 = latest).
START_LEDGER=1000000

# Maximum number of retry attempts for transient Horizon errors (default: 3).
RETRY_MAX_ATTEMPTS=3

# Initial retry back-off delay in milliseconds (default: 100).
RETRY_BACKOFF_MS=100

# ── Soroban submit mode ──────────────────────────────────────────────────────

# Required together to enable on-chain submit mode for vault creation.
SOROBAN_CONTRACT_ID=CDISCIPLRSOROBANCONTRACT1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ
SOROBAN_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
SOROBAN_SOURCE_ACCOUNT=GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
SOROBAN_SECRET_KEY=SBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Polling and timeout controls for submit mode.
SOROBAN_SUBMIT_POLL_INTERVAL_MS=1000
SOROBAN_SUBMIT_POLL_MAX_ATTEMPTS=30
SOROBAN_RPC_TIMEOUT_MS=30000
SOROBAN_SUBMIT_RETRY_MAX_BACKOFF_MS=5000 

# JWT Configuration
# Access token secret — used to sign/verify short-lived access tokens.
# Must be at least 32 characters in production.
JWT_ACCESS_SECRET=your-access-secret-min-32-chars-long
# Refresh token secret — used to sign/verify refresh tokens.
# Must be at least 32 characters in production.
JWT_REFRESH_SECRET=your-refresh-secret-min-32-chars-long
# Token lifetimes (defaults: 15m access, 7d refresh)
JWT_ACCESS_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d
ORG_RATE_LIMIT_MAX=200
ORG_RATE_LIMIT_WINDOW_MS=60000

# ── Webhooks ──────────────────────────────────────────────────────────────────

# Comma-separated hostnames allowed for outbound webhook delivery.
# If empty, all public hosts are allowed (RFC-1918, loopback, link-local blocked).
WEBHOOK_ALLOWED_HOSTS=hooks.example.com

# Secret for verifying inbound webhook signatures.
WEBHOOK_INBOUND_SECRET=your-inbound-webhook-secret

# Allowed timestamp skew for inbound webhook verification (ms, default: 300000).
WEBHOOK_INBOUND_SKEW_MS=300000

# Circuit breaker: consecutive failures before tripping (default: 5).
WEBHOOK_CIRCUIT_BREAKER_THRESHOLD=5

# Circuit breaker: sliding window in ms for failure counting (default: 60000).
WEBHOOK_CIRCUIT_BREAKER_WINDOW_MS=60000

# Circuit breaker: time before an OPEN breaker transitions to HALF_OPEN (default: 30000).
WEBHOOK_CIRCUIT_BREAKER_HALF_OPEN_TIMEOUT_MS=30000

# ── Graceful shutdown ──────────────────────────────────────────────────────────
# How long (ms) to wait for in-flight HTTP requests to finish before
# force-destroying sockets during SIGTERM shutdown (default: 30000).
SHUTDOWN_DRAIN_MS=30000