env.example

# =============================================================================
# IGLOO SERVER ENVIRONMENT CONFIGURATION
# =============================================================================
# Copy this file to .env and customize the values for your deployment
# Never commit your .env file to version control!

# =============================================================================
# OPERATION MODE
# =============================================================================
# HEADLESS mode: When true, uses environment variables for configuration (traditional mode)
# When false (default), uses database for user management and credential storage
HEADLESS=false

# =============================================================================
# DATABASE MODE CONFIGURATION (HEADLESS=false)
# =============================================================================
# Admin secret for initial setup (required for first user creation)
# Generate a secure secret: openssl rand -hex 32
# REQUIRED in HEADLESS=false. Server should refuse to start if unset or left as a placeholder.
# ---
# SECURITY WARNING: DO NOT LEAVE THIS AS THE DEFAULT VALUE.
# The server will refuse to start in database mode if this is not set to a secure, unique secret.
ADMIN_SECRET=REQUIRED_ADMIN_SECRET_NOT_SET

# Database path (optional, defaults to ./data)
# DB_PATH=/path/to/database

# =============================================================================
# HEADLESS MODE CONFIGURATION (HEADLESS=true)
# =============================================================================
# FROSTR credentials - Only used when HEADLESS=true
# Your FROSTR group and share credentials from Igloo Desktop
# Leave empty to start server in configuration-only mode
GROUP_CRED=
SHARE_CRED=

# Optional: Display name for your signing group (HEADLESS mode only)
GROUP_NAME=

# Optional: Directional peer policies for headless mode (JSON array or single object)
# Only overrides that block a direction are persisted (defaults are allow/allow)
# Example: PEER_POLICIES=[{"pubkey":"abcdef...","allowSend":false}]  # blocks outbound, leaves inbound default
PEER_POLICIES=

# =============================================================================
# SERVER CONFIGURATION
# =============================================================================
# Server host and port settings
# Use 'localhost' for local development, '0.0.0.0' for Docker deployments
HOST_NAME=localhost
HOST_PORT=8002

# Nostr relay URLs for FROSTR protocol communication
# Can be JSON array or comma-separated string
# Examples:
#   JSON: ["wss://relay.primal.net","wss://relay.damus.io"]
#   CSV:  wss://relay.primal.net,wss://relay.damus.io
RELAYS=["wss://relay.primal.net"]

# =============================================================================
# SECURITY CONFIGURATION
# =============================================================================
# Enable/disable authentication (set to 'false' for local development only)
# SECURITY WARNING: Never set to 'false' in production!
AUTH_ENABLED=true

# CORS (Cross-Origin Resource Sharing) Configuration
# Comma-separated list of allowed origins for API requests
# Examples:
#   Development: http://localhost:3000,http://localhost:8002
#   Production:  https://yourdomain.com,https://admin.yourdomain.com
# If not set:
#   - In development: wildcard (*) is used for convenience.
#   - In production: no CORS header is set, so browsers block cross-origin requests.
# WebSocket upgrades use a separate Origin enforcement path and support a special token:
#   - `@self` allows any Origin whose host matches the request host (port-agnostic).
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8002

# API Key Authentication
# Generate with: openssl rand -hex 32
# Used with header: X-API-Key: your-key or Authorization: Bearer your-key
API_KEY=your-secure-api-key-here

# Basic Authentication (username/password)
# Used for web UI login and HTTP basic auth
BASIC_AUTH_USER=admin
BASIC_AUTH_PASS=your-secure-password-here

# Session Management
# Used for web UI session cookies.
# If unset, the server auto-generates a 32-byte secret (64 hex chars) and persists it to:
#   - `<DB_PATH>/.session-secret` (or `./data/.session-secret` when `DB_PATH` is unset).
# In `NODE_ENV=production`, failure to load/generate/persist is fatal (process exits).
# In headless mode with a non-empty `API_KEY`, sessions are disabled to avoid file I/O.
# Optional override (must be 64 hex chars):
# SESSION_SECRET=your-64-hex-session-secret-here
SESSION_TIMEOUT=3600  # Session timeout in seconds (3600 = 1 hour)

# =============================================================================
# RATE LIMITING
# =============================================================================
# Enable/disable rate limiting protection
RATE_LIMIT_ENABLED=true

# Rate limit window in seconds (900 = 15 minutes)
RATE_LIMIT_WINDOW=900

# Maximum requests per window per IP address
RATE_LIMIT_MAX=600

# WebSocket abuse settings: see WEBSOCKET ABUSE PROTECTION (ADVANCED) below.

# NIP-46 session creation limits (per user)
# Defaults: 1 hour window across modes
NIP46_SESSION_RATE_LIMIT_WINDOW=3600
# Defaults: 30 sessions/hour in HEADLESS mode, 120 sessions/hour when DB backed
NIP46_SESSION_RATE_LIMIT_MAX=120

# =============================================================================
# OPERATION TIMEOUTS (ADVANCED)
# =============================================================================
# Signing operation timeout (ms). Alias: SIGN_TIMEOUT_MS (legacy).
# Clamped to 1000..120000ms.
# FROSTR_SIGN_TIMEOUT=30000
# SIGN_TIMEOUT_MS=30000
#
# Connectivity ping timeout (ms). Alias: PING_TIMEOUT_MS (legacy).
# Clamped to 1000..120000ms.
# CONNECTIVITY_PING_TIMEOUT_MS=10000
# PING_TIMEOUT_MS=10000
#
# Relay publish receipt timeout (ms). Alias: RELAY_PUBLISH_TIMEOUT (legacy).
# Clamped to 1000..120000ms.
# PUBLISH_EVENT_TIMEOUT_MS=30000
# RELAY_PUBLISH_TIMEOUT=30000
#
# Startup echo timeouts (ms). Alias: ECHO_TIMEOUT_MS (legacy).
# Clamped to 1000..60000ms.
# SELF_ECHO_TIMEOUT_MS=10000
# ECHO_TIMEOUT_MS=10000

# =============================================================================
# WEBSOCKET ABUSE PROTECTION (ADVANCED)
# =============================================================================
# WebSocket upgrade rate limiting (both `/api/events` and `/` upgrades).
# Defaults: window=RATE_LIMIT_WINDOW, max=30.
# RATE_LIMIT_WS_UPGRADE_WINDOW=900
# RATE_LIMIT_WS_UPGRADE_MAX=30
#
# Per-IP connection cap and message rate limiting (token bucket).
# WS_MAX_CONNECTIONS_PER_IP=5
# WS_MSG_RATE=20
# WS_MSG_BURST=40
#
# Legacy WebSocket auth compatibility for `/api/events`:
# - true (default): allow `?apiKey=` / `?sessionId=` query params on upgrades.
# - false: require headers or `Sec-WebSocket-Protocol` auth hints instead.
# ALLOW_QUERY_CREDENTIALS=true

# =============================================================================
# RECOVERY RATE LIMITS (ADVANCED)
# =============================================================================
# Recovery endpoint throttling (defaults: window=RATE_LIMIT_WINDOW, max=3).
# RATE_LIMIT_RECOVERY_WINDOW=900
# RATE_LIMIT_RECOVERY_MAX=3

# =============================================================================
# NODE LIFECYCLE & RELAY PROBING (ADVANCED)
# =============================================================================
# Relay probing:
# - SKIP_RELAY_PROBE=true: skip probing entirely (fastest startup).
# - DEFER_RELAY_PROBE=true: start immediately; probe in background for diagnostics only (ignored if SKIP_RELAY_PROBE=true).
# SKIP_RELAY_PROBE=false
# DEFER_RELAY_PROBE=false
#
# Skip headless startup echo broadcasts (perf option).
# SKIP_STARTUP_ECHO=false
#
# Bounds peer status memory (FIFO eviction).
# MAX_PEER_STATUS_ENTRIES=1000

# =============================================================================
# ERROR CIRCUIT BREAKER (ADVANCED)
# =============================================================================
# Exit the process after repeated unhandled exceptions (for supervisors to restart cleanly).
# ERROR_CIRCUIT_WINDOW_MS=60000
# ERROR_CIRCUIT_THRESHOLD=10
# ERROR_CIRCUIT_EXIT_CODE=1

# =============================================================================
# UPDATE CHECKS (`GET /api/update`) (ADVANCED)
# =============================================================================
# Disable update checks.
# UPDATE_CHECK_DISABLED=false
#
# Mark deployment as managed (also treated as managed when HEADLESS=true or SKIP_ADMIN_SECRET_VALIDATION=true).
# MANAGED_DEPLOYMENT=false
#
# GitHub API token to avoid rate limits (optional).
# GITHUB_TOKEN=
#
# Update check timeouts and cache TTLs (ms).
# UPDATE_CHECK_TIMEOUT_MS=5000
# UPDATE_CHECK_TTL_MS=21600000          # 6 hours
# UPDATE_CHECK_FAILURE_TTL_MS=900000    # 15 minutes
#
# Override version reported by `/api/update` (intended for packaged builds).
# APP_VERSION=

# =============================================================================
# ONBOARDING HARDENING (DB MODE ONLY) (ADVANCED)
# =============================================================================
# Stabilizes per-client identifiers across restarts; leave unset to use a best-effort fallback.
# FINGERPRINT_SECRET=
#
# Bounds the in-memory client-id cache lifetime (ms). Default 86400000, clamped 10m..7d.
# CLIENT_ID_TTL_MS=86400000
#
# Diagnostic logging for fingerprint fallbacks (avoid in production unless troubleshooting).
# LOG_FINGERPRINT_FALLBACK=false

# =============================================================================
# UI EVENT LOG (DB MODE ONLY) (ADVANCED)
# =============================================================================
# By default, `/ping/*` messages are suppressed from the persisted UI event log to avoid runaway growth
# on long-running deployments. Enable only when debugging ping behavior.
# UI_EVENT_LOG_INCLUDE_PINGS=false
#
# Optional: auto-delete older persisted UI event log entries (and unreferenced payload blobs).
# Set to a positive integer number of days. Example: keep 30 days of history.
# UI_EVENT_LOG_RETENTION_DAYS=30

# =============================================================================
# MANAGED INSTALL FLAGS (ADVANCED)
# =============================================================================
# Skip the onboarding "Enter Admin Secret" UI step (Umbrel-style managed deployments only).
# SKIP_ADMIN_SECRET_VALIDATION=false
#
# Auto-generate an ephemeral ADMIN_SECRET in CI/test or when explicitly enabled (non-production only).
# AUTO_ADMIN_SECRET=false

# =============================================================================
# ENVIRONMENT MODE
# =============================================================================
# Set to 'production' for production deployments
# This affects cookie security flags and other settings
NODE_ENV=development

# =============================================================================
# SECURITY EXAMPLES BY DEPLOYMENT TYPE
# =============================================================================

# DEVELOPMENT (Local testing - minimal security)
# AUTH_ENABLED=false
# NODE_ENV=development

# PERSONAL (Home server - medium security)
# AUTH_ENABLED=true
# API_KEY=personal-server-key-2024
# SESSION_SECRET=<generate-64-hex-with-openssl-rand-hex-32>
# SESSION_TIMEOUT=7200
# RATE_LIMIT_MAX=50

# TEAM (Shared server - good security)
# AUTH_ENABLED=true
# BASIC_AUTH_USER=teamadmin
# BASIC_AUTH_PASS=SecureTeamPassword123!
# API_KEY=team-automation-key-64chars
# SESSION_SECRET=<generate-64-hex-with-openssl-rand-hex-32>
# SESSION_TIMEOUT=3600
# RATE_LIMIT_MAX=100

# PRODUCTION (Public/cloud - high security)
# AUTH_ENABLED=true
# ALLOWED_ORIGINS=https://yourdomain.com,https://admin.yourdomain.com
# BASIC_AUTH_USER=prodadmin
# BASIC_AUTH_PASS=VerySecurePassword456!
# API_KEY=prod-api-key-with-64-random-chars-abcdef123456789
# SESSION_SECRET=<generate-64-hex-with-openssl-rand-hex-32>
# SESSION_TIMEOUT=1800
# RATE_LIMIT_ENABLED=true
# RATE_LIMIT_WINDOW=300
# RATE_LIMIT_MAX=30
# NODE_ENV=production