.env.example

# =============================================================================
# Callora Backend — Environment Variables
# Copy this file to .env and fill in your values.
# Never commit .env to version control.
# =============================================================================

# -----------------------------------------------------------------------------
# Server
# -----------------------------------------------------------------------------
PORT=3000
NODE_ENV=development                        # development | production | test

# -----------------------------------------------------------------------------
# Database — primary connection string (used by Prisma / pg.Pool)
# -----------------------------------------------------------------------------
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/callora?schema=public

# -----------------------------------------------------------------------------
# Database — individual fields (used by health checks and direct Pool creation)
# -----------------------------------------------------------------------------
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=callora

# -----------------------------------------------------------------------------
# Database — connection pool tuning
# -----------------------------------------------------------------------------
DB_POOL_MAX=10
DB_IDLE_TIMEOUT_MS=30000
DB_CONN_TIMEOUT_MS=2000

# -----------------------------------------------------------------------------
# Database — read replicas (optional)
# -----------------------------------------------------------------------------
# Comma-separated list of PostgreSQL read-replica connection strings.
# When set, SELECT queries are round-robin routed to the listed replicas;
# INSERT / UPDATE / DELETE always use DATABASE_URL (primary).
# On any replica error the query is automatically retried against the primary.
# Leave blank (or omit) to route all queries to the primary.
#
# Format:
#   REPLICA_URLS=postgresql://user:pass@replica1:5432/db,postgresql://user:pass@replica2:5432/db
#
# REPLICA_URLS=

# -----------------------------------------------------------------------------
# Auth — REQUIRED, app will not start without these
# -----------------------------------------------------------------------------
JWT_SECRET=your-jwt-secret-here
ADMIN_API_KEY=your-admin-api-key-here
METRICS_API_KEY=your-metrics-api-key-here

# -----------------------------------------------------------------------------
# Security — bcrypt
# -----------------------------------------------------------------------------
# Bcrypt cost factor (salt rounds) used when hashing API keys.
# Valid range: 10–31. Default: 12.
# Higher values increase brute-force resistance but also increase hashing time.
# OWASP recommends a minimum of 10; 12 is a reasonable production default.
BCRYPT_COST_FACTOR=12

# -----------------------------------------------------------------------------
# Proxy / Gateway
# -----------------------------------------------------------------------------
UPSTREAM_URL=http://localhost:4000
PROXY_TIMEOUT_MS=30000
REST_RATE_LIMIT_WINDOW_MS=60000
REST_RATE_LIMIT_MAX_REQUESTS=100
WEBHOOK_SECRET_ROTATION_GRACE_MS=86400000

# -----------------------------------------------------------------------------
# Billing concurrency control
# -----------------------------------------------------------------------------
# Maximum concurrent billing deduct operations allowed per developer.
# Set this to 1 for fully serialized deducts, or higher to allow limited
# parallelism per developer.
BILLING_MAX_CONCURRENCY_PER_DEV=1
# How long an idle developer semaphore state is kept in memory (ms).
BILLING_SEMAPHORE_TTL_MS=300000

# -----------------------------------------------------------------------------
# Idempotency cleanup
# -----------------------------------------------------------------------------
# How long idempotency cache entries are kept before they become eligible
# for periodic cleanup (seconds).
IDEMPOTENCY_RETENTION_WINDOW_SECONDS=86400
# How often the idempotency sweeper job runs (milliseconds).
IDEMPOTENCY_SWEEPER_INTERVAL_MS=60000

# -----------------------------------------------------------------------------
# CORS — comma-separated list of allowed origins
# -----------------------------------------------------------------------------
CORS_ALLOWED_ORIGINS=http://localhost:5173

# -----------------------------------------------------------------------------
# Soroban RPC (optional — set SOROBAN_RPC_ENABLED=true to activate)
# -----------------------------------------------------------------------------
SOROBAN_RPC_ENABLED=false
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
SOROBAN_RPC_TIMEOUT=2000
SOROBAN_BILLING_RPC_URL=https://soroban-testnet.stellar.org
SOROBAN_BILLING_CONTRACT_ID=your-vault-contract-id
SOROBAN_BILLING_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
SOROBAN_BILLING_SOURCE_ACCOUNT=your-backend-source-account
SOROBAN_BILLING_BACKEND_SECRET_KEY=your-backend-secret-key
SOROBAN_BILLING_BALANCE_FN=balance
SOROBAN_BILLING_DEDUCT_FN=deduct
SOROBAN_BILLING_RPC_TIMEOUT_MS=5000

# -----------------------------------------------------------------------------
# Horizon (optional — set HORIZON_ENABLED=true to activate)
# -----------------------------------------------------------------------------
HORIZON_ENABLED=false
HORIZON_URL=https://horizon-testnet.stellar.org
HORIZON_TIMEOUT=2000
SETTLEMENT_STATUS_SYNC_INTERVAL_MS=60000
SETTLEMENT_STATUS_SYNC_TIMEOUT_MS=5000
REVENUE_LEDGER_INDEXER_INTERVAL_MS=30000
REVENUE_LEDGER_INDEXER_BATCH_SIZE=500

# -----------------------------------------------------------------------------
# Stellar / Soroban network selection
# -----------------------------------------------------------------------------
STELLAR_NETWORK=testnet
# SOROBAN_NETWORK=testnet

# Active network-specific endpoints and contracts used by transaction building
STELLAR_TESTNET_HORIZON_URL=https://horizon-testnet.stellar.org
SOROBAN_TESTNET_RPC_URL=https://soroban-testnet.stellar.org
STELLAR_TESTNET_VAULT_CONTRACT_ID=
STELLAR_TESTNET_SETTLEMENT_CONTRACT_ID=

STELLAR_MAINNET_HORIZON_URL=https://horizon.stellar.org
SOROBAN_MAINNET_RPC_URL=https://soroban-mainnet.stellar.org
STELLAR_MAINNET_VAULT_CONTRACT_ID=
STELLAR_MAINNET_SETTLEMENT_CONTRACT_ID=

# Transaction builder defaults
STELLAR_BASE_FEE=100
STELLAR_TRANSACTION_TIMEOUT=300
# TRANSACTION_TIMEOUT=300

# -----------------------------------------------------------------------------
# Health checks
# -----------------------------------------------------------------------------
HEALTH_CHECK_DB_TIMEOUT=2000
APP_VERSION=1.0.0

# -----------------------------------------------------------------------------
# Logging
# ----------------------------------------------------------------------------- 
LOG_LEVEL=info
ACCESS_LOG_SAMPLE_RATE=1
# ACCESS_LOG_REDACT_FIELDS=path,correlationId

# ----------------------------------------------------------------------------- 
# Profiling
# -----------------------------------------------------------------------------
GATEWAY_PROFILING_ENABLED=false

# -----------------------------------------------------------------------------
# Body size limits
# REQUEST_BODY_LIMIT  — max JSON/form body for general API routes (default: 100kb)
# GATEWAY_BODY_LIMIT  — max body the gateway router will accept before proxying (default: 1mb)
# -----------------------------------------------------------------------------
REQUEST_BODY_LIMIT=100kb
GATEWAY_BODY_LIMIT=1mb

# -----------------------------------------------------------------------------
# Slow Query Alerting — via pg_stat_statements
# Requires the pg_stat_statements extension to be enabled on the database.
# The worker polls pg_stat_statements every SLOW_QUERY_POLL_INTERVAL_MS and
# fires a webhook when any query's mean_exec_time exceeds the threshold.
# -----------------------------------------------------------------------------
# Webhook URL to POST slow query alerts to (required to enable the feature).
# When omitted the worker is not started.
SLOW_QUERY_ALERT_WEBHOOK_URL=
# P95 latency threshold in milliseconds. Any query averaging above this will
# trigger an alert. Default: 500ms.
SLOW_QUERY_P95_THRESHOLD_MS=500
# How often to poll pg_stat_statements (milliseconds). Default: 300000 (5 min).
SLOW_QUERY_POLL_INTERVAL_MS=300000
# Deduplication window per query fingerprint (seconds). A query that was
# already alerted on will not fire again within this window. Default: 3600 (1h).
SLOW_QUERY_DEDUP_WINDOW_SECONDS=3600

# -----------------------------------------------------------------------------
# Usage Anomaly Detector — 5-minute rolling baseline per developer
# Compares the latest 5-minute window to the mean of the trailing 12 windows.
# When traffic exceeds baseline * multiplier, emits usage.anomaly.detected.
# -----------------------------------------------------------------------------
# Set to false to disable the background worker.
USAGE_ANOMALY_DETECTOR_ENABLED=true
# Traffic multiplier threshold (default 5x baseline).
USAGE_ANOMALY_MULTIPLIER=5
# Poll interval in milliseconds (default 300000 = 5 min).
USAGE_ANOMALY_POLL_INTERVAL_MS=300000
# Window size in milliseconds (default 300000 = 5 min).
USAGE_ANOMALY_WINDOW_MS=300000
# Number of trailing windows used for the baseline mean (default 12).
USAGE_ANOMALY_BASELINE_WINDOWS=12
# Optional dedup window per developer/window (defaults to USAGE_ANOMALY_WINDOW_MS).
# USAGE_ANOMALY_DEDUP_WINDOW_MS=300000