.env.example

# --- Stellar / Soroban ---

Stellar_NETWORK=testnet

# Required: Stellar secret key (S...) used to sign update_impact_score transactions
ADMIN_SECRET_KEY=
# Required: Soroban contract address for the ProjectRegistry
PROJECT_REGISTRY_CONTRACT_ID=
# Optional: Stellar RPC endpoint. Default: https://soroban-testnet.stellar.org
RPC_URL= https://soroban-testnet.stellar.org

# --- PostgreSQL connection (migrations) ---
# Required for staging/production; defaults are used for local development.
# If DB_NAME is unset, defaults to heliobond_dev in development and heliobond_test in test.
DB_HOST=localhost
DB_PORT=5432
DB_NAME=
DB_USER=postgres
DB_PASSWORD=

# --- HTTP server ---
# Optional: Port the API listens on. Default: 3001
PORT=3001
# Optional: Origin allowed by CORS. Default: http://localhost:3000
FRONTEND_URL= http://localhost:3000
# Optional: Bearer token for /api/admin/*. If unset, admin auth is skipped (dev only).
ADMIN_API_KEY=
# Token required to open a /ws WebSocket connection (via ?token= or Bearer auth).
# Falls back to ADMIN_API_KEY;if both unset, WebSocket auth is skipped (dev only).
# Token required to open a /ws WebSocket connection, sent as `Authorization: Bearer <token>`.
# No query-string (?token=) support. Required in production; if unset, WebSocket
# auth is skipped in dev/test only. Does NOT fall back to ADMIN_API_KEY.
WS_AUTH_TOKEN=

# --- RBAC ---
# Optional: User ID to grant the "admin" role at startup. This bootstraps the
# RBAC system, since the admin role is required to manage roles and there is
no other way to create the first admin. If unset, no initial admin is seeded.
INITIAL_ADMIN_USER_ID=

# --- Rate limiting (optional; sensible defaults applied when unset) ---
# Public endpoints: window length and max requests per IP per window
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX=100
# Admin endpoints: stricter limits (default window mirrors RATE_LIMIT_WINDOW_MS)
RATE_LIMIT_ADMIN_WINDOW_MS=60000
RATE_LIMIT_ADMIN_MAX=20

# --- IP Whitelist for admin endpoints (optional) --
# Comma-separated list of allowed IPs or CIDR ranges
# If empty or unset, IP whitelist is disabled (all IPs allowed)
ADMIN_IP_WHITELIST=
# Set to "false" to NOT bypass private/internal networks (default: true bypasses them)
ADMIN_IP_WHITELIST_BYPASS_PRIVATE=true

# --- Request Signing (optional) --
# HMAC secret for request signature verification
# If empty or unset, request signing is disabled
REQUEST_SIGNING_SECRET=

# --- APM (Application Performance Monitoring) ---
# APM provider: "datadog" | "newrelic" | "opentelemetry" | "none"
APM_PROVIDER=none
# DataDog APM (if APM_PROVIDER=datadog)
DD_AGENT_HOST=localhost
DD_SERVICE=heliobond-backend

DD_ENV=development
DD_VERSION=1.0.0
# New Relic (if APM_PROVIDER=newrelic)
NEW_RELIC_LICENSE_KEY
NEW_RELIC_APP_NAME=heliobond-backend
# OpenTelemetry (if APM_PROVIDER=opentelemetry)
OTEL_EXPORTER_OLTP_ENDPOINT=http://localhost:4318
OTEL_SERVICE_NAME=heliobond-backend

# --- Circuit Breaker ---
# Number of consecutive RFC failures before opening the circuit. Default: 5
CIRCUIT_BREAKER_THRESHOLD=5
# Cooldown (ms) before the circuit moves from OPEN to HALF_OPEN. Default: 30000
CIRCUIT_BREAKER_COOLDOWN_MS=30000

# --- Logging ---
# Log level: debug | info | warn | error
# Defaults to environment-based: development=debug, staging=info, production=warn
LOG_LEVEL=

# --- Body size limit --
# Maximum request body size accepted by express.json()
# Accepts any string parsable by bytes library (e.g. "100kb", "1mb", "50kb")
BOPY_SIZE_LIMIT=100kb
# Accepts any string parseable by bytes library (e.g. "100kb", "1mb", "50kb")
BODY_SIZE_LIMIT=100kb

# --- CSRF Protection ---
# Comma-separated list of allowed origins for CSRF validation
CORS_ORIGINS=

# --- Stellar transaction polling ---
# Optional: How long (ms) to wait between polling for transaction confirmation. Default: 1500
POLL_INTERVAL_MS=1500
# Optional: Max number of polling attempts before timing out. Default: 20
POLL_MAX_ATTEMPT_PS=20

# --- Stellar transaction timeout ---
# Optional: Transaction timeout in seconds for Soroban contract calls. Default: 30
TX_TIMEOUT_SECONDS=30

# --- Stellar transaction retries (optional) --
# Optional: Max retry attempts for failed Stellar transactions. Default: 4
TX_MAX_RETRIES=4
# Optional: Base delay (ms) for exponential backoff between retries. Default: 200
TX_RETRY_BASE_DELAY_MS=200
# Optional: Max delay (ms) cap for retry backoff.
# Optional: Max delay (ms) cap for retry backoff. Default: 10000
TX_RETRY_MAX_DELAY_MS=10000

# --- Stellar RPC connection pool (optional; pool for lib/db-pool.ts) ---
# Optional: Minimum number of pooled connections. Default: 2
DB_POOL_MIN=2
# Optional: Maximum number of pooled connections. Default: 10
DB_POOL_MAX=10
# Optional: Timeout (ms) to acquire a connection from the pool. Default: 5000
DB_POOL_ACQUIRE_TIMEOUT_MS=5000
# Optional: Interval (ms) for pool health checks. Default: 30000
DB_POOL_HEALTH_CHECK_INTERVAL_MS=30000

# --- Database SSL (optional) ---
# Path to the CA certificate file for the database server.
# Required when the database uses a private CA (e.g., AWS RDS, GCP Cloud SQL)
# and the certificate is not in the system trust store.
# Set this to enable proper TLS certificate validation.
DB_SSL_CA_PATH=
# --- Idempotency (optional) ---
# Optional: TTL (ms) for the in-memory idempotency key store.
# Duplicate score update submissions for the same project within this window
# are rejected before reaching Stellar RPC. Default: 3600000 (1 hour)
IDEMPOTENCY_TTL_MS=3600000

# --- Cron (optional) ---
# Optional: Timezone for scheduled cron jobs. Default: UTC
CRON_TIMEZONE=UTC
# Optional: Failure threshold ratio (0..1) for cron health checks. Default: 0.5
CRON_FAILURE_THRESHOLD=0.5

# --- Graceful shutdown (optional) --
# Optional: Timeout (ms) to wait for graceful shutdown before forcing exit. Default: 30000
SHUTDOWN_TIMEOUT_MS=30000

# --- IoT simulation ---
# Optional: Maximum simulated solar power output in kW. Default: 1000
MAX_POWER_KW=1000
# Optional: Set to "true" to disable the in-memory IoT reading cache.
# Readings are deterministic per (project_id, hour), so the cache only skips
# redundant recomputation -- disabling it changes performance, not responses.
IOT_CACHE_DISABLED=
# Optional: Max entries retained by the IoT reading cache. Default: 1000
# Oldest entries are evicted first once the cap is reached.
IOT_CACHE_MAX_SIZE=1000

# --- Input validation ---
# Optional: Inclusive upper bound accepted for a :payload project parameter.
# Requests outside 1..MAX_PROJECT_ID are rejected with HTTP 400. Default: 1000000
MAX_PROJECT_ID=1000000

# --- Secrets Management --
# Provider: env | aws | vault | azure
SECRETS_PROVIDER=env
# AWS Secrets Manager (if SECRETS_PROVIDER=aws)
AWS_REGION=us-east-1
AWS_SECRET_ID=
AWS_SECRET_VERSION_ID=
# HashiCorp Vault (if SECRETS_PROVIDER=vault)
VAULT_ENDPOINT=http://localhost:8200
VAULT_TOKEN=
VAULT_SECRET_PATH=secret/data/heliobond
# Azure Key Vault (if SECRETS_PROVIDER=azure)
AZURE_VAULT_URL=
AZURE_TENANT_ID=
AZURE_CLIENT_ID=
AZURE_CLIENT_SECRET=
# Secret rotation (optional)
SECRETS_ROTATION_ENABLED=false
SECRETS_ROTATION_INTERVAL_MS=3600000