.env.example

# LiquiFact API Environment Variables
# Copy to .env and fill required values

# App environment (required)
NODE_ENV=development
PORT=3001
# Helmet config
HELMET_CSP=false
# JWT secret (required, min 32 chars, generate securely)
JWT_SECRET=your-super-secure-jwt-secret-key-at-least-32-chars-long-here

# CORS origins (optional, comma-separated)
# CORS_ALLOWED_ORIGINS=https://yourapp.com,http://localhost:3000

# Optional Sentry observability
# SENTRY_DSN=https://publickey@o123456.ingest.sentry.io/67890
# SENTRY_RELEASE=liquifact-backend@1.0.0
# SENTRY_ENVIRONMENT=production

# Cache
ESCROW_CACHE_TTL_SECONDS=30
REDIS_ESCROW_CACHE_ENABLED=false
# REDIS_URL=redis://localhost:6379
# Strict TTL for cached escrow summaries. Value is clamped to [5, 300].
REDIS_ESCROW_CACHE_TTL_SECONDS=30
# Invalidate cached summary when |currentLedger - cachedLedger| exceeds this threshold.
REDIS_ESCROW_LEDGER_GAP_THRESHOLD=3

# Body Size Limits (optional)
# BODY_LIMIT_JSON=100kb
# BODY_LIMIT_URLENCODED=50kb
# BODY_LIMIT_RAW=1mb
# BODY_LIMIT_INVOICE=512kb

# Soroban escrow funding submission stub
# Defaults to delegated mode; live signing/submission is disabled in code.
ESCROW_SIGNING_MODE=delegated
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
# LIQUIFACT_ESCROW_CONTRACT_ID=C...

# --------------------
# Escrow Address Mapping |
# --------------------
# JSON configuration mapping invoice IDs to Stellar escrow contract addresses.
# Used for early phases to resolve contract IDs without on-chain registry.
# Format: {"mappings":[{"invoiceId":"inv_123","escrowAddress":"GABC...","environment":"development","isActive":true}]}
# 
# Security notes:
# - Only map invoices you own or have explicit permission to map
# - Use environment-specific mappings for multi-deployment setups
# - Addresses must be valid Stellar public keys (56 chars, starting with 'G')
# - Invoice IDs should be non-empty strings with alphanumeric chars, underscores, hyphens
#
# Example configuration:
# ESCROW_ADDR_BY_INVOICE={"mappings":[{"invoiceId":"inv_demo_001","escrowAddress":"GABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890ABCDEFGHIJKLM","environment":"development","isActive":true},{"invoiceId":"inv_prod_001","escrowAddress":"GZYXWVUTSRQPONMLKJIHGFEDCBAZYXWVUTSRQPONML","environment":"production","isActive":true}],"defaultEnvironment":"development","allowlistEnabled":true,"cacheEnabled":true,"cacheTtlSeconds":300}
ESCROW_ADDR_BY_INVOICE=

# Custodial signing references only. Never store raw Stellar secret keys here.
ESCROW_CUSTODIAL_SIGNING_ENABLED=false
# ESCROW_CUSTODIAL_KMS_PROVIDER=aws-kms
# ESCROW_CUSTODIAL_KEY_ID=liquifact/escrow/fund/v1
# ESCROW_DOCUMENT_CUSTODIAL_KEY_ID=liquifact/docs/custody/v1

# ------------------------
# Stellar Network Config   |
# ------------------------
# STELLAR_NETWORK must match the corresponding SOROBAN_RPC_URL.
# The combination is validated at boot time - mismatches will prevent startup.
#
# Valid combinations:
#   TESTNET   + https://soroban-testnet.stellar.org
#   MAINNET  + https://soroban.stellar.org
#   FUTURENET + https://rpc-futurenet.stellar.org
#
# Do NOT use custom RPC URLs - they will fail validation.
STELLAR_NETWORK=TESTNET
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org

# Soroban retry configuration (optional)
# SOROBAN_MAX_RETRIES=3
# SOROBAN_BASE_DELAY=200
# SOROBAN_MAX_DELAY=5000

# Dev-only: Invoice to contractId mapping (comma-separated pairs: invoiceId:contractId)
# Example: inv1:contractA,inv2:contractB
ESCROW_ADDR_BY_INVOICE=

# DB (when added)
# DATABASE_URL=postgresql://user:pass@localhost:5432/liquifact
# AUDIT_LOG_ENABLED=true
# AUDIT_LOG_FAIL_CLOSED=false

# S3-compatible storage for SME invoice uploads
AWS_REGION=us-east-1
S3_ENDPOINT=https://s3.amazonaws.com
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
S3_BUCKET=liquifact-invoices

# -------------------------
# Prometheus Metrics Auth  |
# -------------------------
# Static bearer token required to scrape GET /metrics.
# If unset, only loopback (127.0.0.1, ::1) is allowed — suitable for
# private-network Prometheus scrapers. In production always set this.
# Generate with: openssl rand -hex 32
# METRICS_BEARER_TOKEN=replace-with-a-long-random-secret

# --------------------
# JWT Authentication |
# --------------------
# Secret used to sign and verify JSON Web Tokens.
# Must be a long, random string in production. Defaults to "test-secret" locally.
# JWT_SECRET=replace-with-a-long-random-secret

# ------------------------
# API Key Authentication |
# ------------------------
# Semicolon-separated list of API key entries, each a JSON object.
# Schema per entry:
#   key       (string, required) — must start with "lf_", min 10 chars
#   clientId  (string, required) — unique identifier for the service client
#   scopes    (array,  required) — non-empty list from: invoices:read, invoices:write, escrow:read
#   revoked   (bool,   optional) — set to true to disable the key without removing it
#
# Example (two entries — one active, one revoked):
# API_KEYS={"key":"lf_prod_service_a_key","clientId":"billing-service","scopes":["invoices:read","invoices:write"]};{"key":"lf_old_service_b_key","clientId":"legacy-service","scopes":["invoices:read"],"revoked":true}
#
# Key rotation: add the new key entry, deploy, then set "revoked": true on the
# old entry and redeploy. The old key is rejected immediately; the new key works
# from the first deploy.
# API_KEYS=

# --------------------
# Rate Limiting |
# --------------------
# Per-IP and per-API key rate limiting for public endpoints.
# Global limiter settings:
# RATE_LIMIT_WINDOW_MS=900000          # Time window in ms (default: 15 min = 900000)
# RATE_LIMIT_MAX_REQUESTS=100          # Max requests per window (default: 100)
# Sensitive endpoints (invoices, escrow):
# RATE_LIMIT_SENSITIVE_WINDOW_MS=3600000  # Time window in ms (default: 1 hour = 3600000)
# RATE_LIMIT_SENSITIVE_MAX=40           # Max requests per window (default: 40)
# API key specific limits:
# RATE_LIMIT_API_KEY_WINDOW_MS=900000   # Time window in ms (default: 15 min = 900000)
# RATE_LIMIT_API_KEY_MAX=1000          # Max requests per window (default: 1000)

# --------------------
# Batch Read Config |
# --------------------
# Concurrency limit for batched on-chain reads (default: 5)
# SOROBAN_BATCH_CONCURRENCY=5
# Timeout in milliseconds for individual on-chain reads within a batch (default: 5000)
# SOROBAN_BATCH_TIMEOUT_MS=5000


# Escrow event indexer (Horizon/websocket polling strategy)
# Feature-flagged background job. Stores latest on-chain contract events by invoiceId.
ESCROW_INDEXER_ENABLED=false
ESCROW_INDEXER_POLL_INTERVAL_MS=15000
ESCROW_INDEXER_BATCH_SIZE=100
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org

# -------------------------
# KYC Provider Config      |
# -------------------------
# External KYC provider integration. Both URL and API key must be set together,
# or both must be absent. Partial config (one without the other) is rejected at boot
# in non-test environments.
#
# KYC_PROVIDER_URL — Base URL of the KYC provider API (must be a valid HTTPS URL).
# KYC_PROVIDER_API_KEY — API key for authenticating with the provider (min 1 char).
# KYC_PROVIDER_SECRET — Optional secondary HMAC/signing secret for the provider.
#
# When unset, the KYC provider is disabled and the /ready check reports "disabled".
# When set, /ready probes the provider URL and reports "healthy" or "unhealthy".
#
# KYC_PROVIDER_URL=https://kyc.example.com
# KYC_PROVIDER_API_KEY=replace-with-your-kyc-api-key
# KYC_PROVIDER_SECRET=replace-with-your-kyc-signing-secret