env.example

# ============================================================
# StellarKraal — Environment Variables
# ============================================================
# Copy this file to .env and fill in values for local dev:
#   cp .env.example .env
#
# Variables marked [Required] must be set before the service
# will start. Variables marked [Optional] have safe defaults.
#
# Variables marked [GitHub Secret: NAME] must also be stored
# as GitHub Actions repository secrets (Settings → Secrets
# and variables → Actions) so CI/CD workflows can inject them.
# Never commit real secrets to version control.
# ============================================================


# ------------------------------------------------------------
# SHARED — used by both frontend and backend
# ------------------------------------------------------------

# Stellar network to connect to.
# Format : "testnet" | "mainnet"
# Required. [GitHub Secret: NEXT_PUBLIC_NETWORK]
NEXT_PUBLIC_NETWORK=testnet

# Soroban JSON-RPC endpoint for the chosen network.
# Format : HTTPS URL
# Required. [GitHub Secret: RPC_URL]
RPC_URL=https://soroban-testnet.stellar.org

# Stellar Horizon API endpoint for the chosen network (fallback for account reads).
# Used as transparent fallback when Soroban RPC is unavailable for account balance queries.
# Format : HTTPS URL
# Optional. [GitHub Secret: HORIZON_URL]
# HORIZON_URL=https://horizon-testnet.stellar.org

# Deployed Soroban contract address (C... or G... format).
# Obtain this after running `stellar contract deploy`.
# Format : 56-character Stellar contract/account ID
# Required. [GitHub Secret: CONTRACT_ID]
CONTRACT_ID=CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM


# ------------------------------------------------------------
# FRONTEND — Next.js (NEXT_PUBLIC_* vars are bundled at build)
# ------------------------------------------------------------

# Base URL of the backend API, used by the Next.js frontend.
# Must be reachable from the browser in production.
# Format : HTTP(S) URL, no trailing slash
# Required. [GitHub Secret: NEXT_PUBLIC_API_URL]
NEXT_PUBLIC_API_URL=http://localhost:3001

# Public Soroban RPC URL exposed to browser-side SDK calls.
# Usually the same value as RPC_URL.
# Format : HTTPS URL
# Required. [GitHub Secret: NEXT_PUBLIC_RPC_URL]
NEXT_PUBLIC_RPC_URL=https://soroban-testnet.stellar.org


# ------------------------------------------------------------
# BACKEND — Node.js / Express API
# ------------------------------------------------------------

# TCP port the Express server listens on.
# Format : integer 1–65535
# Optional. Default: 3001
PORT=3001

# Node.js runtime environment. Controls logging verbosity,
# error detail, and certain security defaults.
# Format : "development" | "production" | "test"
# Optional. Default: development
NODE_ENV=development

# Application log level. Controls verbosity of application logs.
# Format : "debug" | "info" | "warn" | "error"
# Optional. Default: info
# LOG_LEVEL=info

# Log file rotation: maximum size per log file before creating a new one.
# Only applies in production. Examples: 10m, 100m, 1g
# Format : string with unit (b, kb, mb, gb)
# Optional. Default: 10m
# LOG_MAX_SIZE=10m

# Log file retention: number of log files to keep before automatic deletion.
# Only applies in production. Set to 7 for daily rotation = 7 days retention.
# Format : positive integer
# Optional. Default: 7
# LOG_MAX_FILES=7

# Allowed origin for CORS. Set to the frontend URL in
# production to prevent cross-origin requests from other hosts.
# Format : HTTP(S) URL, no trailing slash
# Optional (required in production). [GitHub Secret: FRONTEND_URL]
FRONTEND_URL=http://localhost:3000

# Comma-separated list of allowed CORS origins.
# Takes precedence over FRONTEND_URL when set.
# Wildcard "*" is only permitted in non-production environments.
# Format : comma-separated HTTP(S) URLs, e.g. https://app.example.com,https://staging.example.com
# Optional. [GitHub Secret: ALLOWED_ORIGINS]
# ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001

# JWT secret used to sign and verify access tokens.
# Must be at least 32 characters in production.
# Generate with: openssl rand -hex 32
# Format : arbitrary string, min 32 chars recommended
# Required in production. [GitHub Secret: JWT_SECRET]
JWT_SECRET=change-me-to-a-strong-jwt-secret-min-32-chars

# Access token TTL in milliseconds (default 15 minutes).
# Format : positive integer (milliseconds)
# Optional. Default: 900000
# ACCESS_TTL_MS=900000

# Refresh token TTL in milliseconds (default 7 days).
# Format : positive integer (milliseconds)
# Optional. Default: 604800000
# REFRESH_TTL_MS=604800000

# HMAC secret for verifying incoming webhook payloads.
# Must be at least 16 random bytes (32+ recommended).
# Generate with: openssl rand -hex 32
# Format : hex or arbitrary string, min 16 chars
# Optional (webhooks disabled if unset). [GitHub Secret: WEBHOOK_SECRET]
# WEBHOOK_SECRET=

# API key that grants access to /api/admin/* endpoints.
# Keep this secret; rotate immediately if compromised.
# Generate with: openssl rand -hex 16
# Format : arbitrary string, min 8 chars
# Optional (admin routes disabled if unset). [GitHub Secret: ADMIN_API_KEY]
# ADMIN_API_KEY=

# --- Rate limiting (requests per minute per IP) ---

# Global rate limit applied to every route.
# Format : positive integer
# Optional. Default: 60
RATE_LIMIT_GLOBAL=60

# Rate limit for authentication routes (/auth/*).
# Lower than global to slow brute-force attempts.
# Format : positive integer
# Optional. Default: 10
RATE_LIMIT_AUTH=10

# Rate limit for read-only routes (GET requests).
# Format : positive integer
# Optional. Default: 100
RATE_LIMIT_READ=100

# Rate limit for state-changing routes (POST/PUT/DELETE).
# Format : positive integer
# Optional. Default: 10
RATE_LIMIT_WRITE=10

# --- Request timeouts ---

# Maximum time in milliseconds for any request before the
# server responds with 408 Request Timeout.
# Format : positive integer (milliseconds)
# Optional. Default: 30000
TIMEOUT_GLOBAL_MS=30000

# Maximum time in milliseconds for write operations
# (loan origination, collateral updates, etc.).
# Format : positive integer (milliseconds)
# Optional. Default: 15000
TIMEOUT_WRITE_MS=15000

# --- RPC connection pool ---

# Minimum number of persistent RPC connections to maintain.
# Format : positive integer, must be ≤ POOL_MAX
# Optional. Default: 2
POOL_MIN=2

# Maximum number of concurrent RPC connections allowed.
# Format : positive integer, must be ≥ POOL_MIN
# Optional. Default: 10
POOL_MAX=10

# --- Caching ---

# Time-to-live for cached collateral appraisal results.
# Increase to reduce RPC calls; decrease for fresher prices.
# Format : positive integer (milliseconds)
# Optional. Default: 300000 (5 minutes)
APPRAISAL_CACHE_TTL_MS=300000


# ------------------------------------------------------------
# ALERTING — Slack & PagerDuty (backend alert dispatcher)
# ------------------------------------------------------------

# Slack incoming webhook URL for deployment and alert messages.
# Create one at https://api.slack.com/messaging/webhooks
# Format : https://hooks.slack.com/services/T.../B.../...
# Optional (Slack alerts disabled if unset). [GitHub Secret: SLACK_WEBHOOK_URL]
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK

# PagerDuty Events API v2 routing key for critical-severity alerts.
# Find this in PagerDuty under Services → Integrations.
# Format : 32-character alphanumeric string
# Optional (PagerDuty alerts disabled if unset). [GitHub Secret: PAGERDUTY_ROUTING_KEY]
PAGERDUTY_ROUTING_KEY=your-pagerduty-routing-key

# Base URL prepended to runbook paths in alert messages.
# Format : HTTPS URL, no trailing slash
# Optional. Default shown below.
RUNBOOK_BASE_URL=https://github.com/teslims2/StellarKraal-/blob/main/docs/runbooks

# Database URL — omit for SQLite (dev), set to postgres:// for PostgreSQL (staging/prod)
# DATABASE_URL=postgresql://user:password@localhost:5432/stellarkraal

# ── Health Factor Alert Thresholds ──────────────────────────────────────────────

# Warning threshold for health factor job (scaled by 10_000; default 1.3 → 13000).
# Fires a warning alert when a loan's health factor drops below this value.
# Format : positive integer (×10_000)
# Optional. Default: 13000
# HEALTH_FACTOR_WARN=13000

# Critical threshold for health factor job (scaled by 10_000; default 1.0 → 10000).
# Fires a critical alert when a loan's health factor drops below this value.
# Format : positive integer (×10_000)
# Optional. Default: 10000
# HEALTH_FACTOR_CRIT=10000