.env.example

# =============================================================================
# Healthy Stellar Backend — Environment Variables Reference
# =============================================================================
# Copy this file to .env and fill in the values for your environment:
#   cp .env.example .env
#
# Variables marked REQUIRED must be set before the application will start.
# Variables marked OPTIONAL have sensible defaults and can be left as-is for
# local development.
#
# Secrets (keys, passwords, tokens) must NEVER be committed to source control.
# Generate random secrets with:
#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# =============================================================================


# =============================================================================
# Core Application
# =============================================================================

# Runtime environment. Controls logging verbosity, SSL enforcement, and more.
# Values: development | test | staging | production
NODE_ENV=development

# HTTP port the server listens on.
PORT=3000

# Human-readable application name (used in logs and emails).
APP_NAME=Healthy Stellar

# Base URL of this server (used for CORS in production and tenant welcome emails).
# Example: https://api.healthystellar.com
# REQUIRED in production
APP_URL=http://localhost:3000

# Public domain used to build shareable record URLs.
# Example: https://app.healthystellar.com
APP_DOMAIN=http://localhost:4200

# API version string surfaced in OpenAPI docs.
API_VERSION=1.0.0


# =============================================================================
# Database — PostgreSQL
# =============================================================================
# Option 1: single connection URL (takes precedence over individual params).
# DATABASE_URL=postgresql://username:password@localhost:5432/healthy_stellar_dev

# Option 2: individual connection parameters (used when DATABASE_URL is unset).
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
# REQUIRED — no default is safe to ship
DB_PASSWORD=your_secure_db_password
DB_NAME=healthy_stellar_dev

# SSL (HIPAA requirement in production — set DB_SSL_ENABLED=true).
DB_SSL_ENABLED=false
# Paths to SSL certificates (leave blank for local dev).
DB_SSL_CA=
DB_SSL_CERT=
DB_SSL_KEY=

# Connection pool sizing.
# Guideline: (DB_POOL_MAX × worker_processes) < pg max_connections × 0.8
# Development: min=2 max=10 | Staging: min=5 max=20 | Production: min=10 max=50
DB_POOL_MIN=2
DB_POOL_MAX=10
DB_CONNECTION_TIMEOUT_MS=2000
DB_IDLE_TIMEOUT_MS=30000
# Pool utilisation threshold (0.0–1.0). Requests are rejected above this level.
DB_POOL_THRESHOLD=0.8

# Query performance guardrails.
DB_STATEMENT_TIMEOUT_MS=10000
DB_QUERY_TIMEOUT_MS=30000
DB_SLOW_QUERY_MS=100
SLOW_QUERY_THRESHOLD_MS=1000
CRITICAL_QUERY_THRESHOLD_MS=5000

# Maximum time for an entire HTTP request (covers DB + business logic).
REQUEST_TIMEOUT_MS=30000

# Test database (used by Jest e2e suite — not needed for normal dev).
# DB_NAME_TEST=healthy_stellar_test

# Analytics read-replica (issue #685) — optional. When unset, analytics/
# cohort/report queries transparently fall back to the primary connection
# above. Point these at a real read-replica/standby Postgres instance to
# route analytics traffic away from the primary database.
# DB_REPLICA_URL=
# DB_REPLICA_HOST=
# DB_REPLICA_PORT=5432
# DB_REPLICA_USERNAME=
# DB_REPLICA_PASSWORD=
# DB_REPLICA_NAME=
# DB_REPLICA_POOL_MIN=1
# DB_REPLICA_POOL_MAX=5


# =============================================================================
# Encryption & PHI (HIPAA Requirements)
# =============================================================================
# REQUIRED — 64-character hex string (32 bytes).
# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ENCRYPTION_KEY=your_64_character_hex_encryption_key_here

# REQUIRED — minimum 32 characters, used for field-level PHI encryption.
PHI_ENCRYPTION_KEY=your_phi_encryption_key_minimum_32_characters_here

# Toggle field-level encryption for PHI columns.
ENABLE_FIELD_LEVEL_ENCRYPTION=true
ENABLE_DATA_ENCRYPTION=true


# =============================================================================
# JWT & Authentication
# =============================================================================
# REQUIRED — minimum 32 characters.
JWT_SECRET=your_jwt_secret_key_minimum_32_characters_here
JWT_EXPIRATION=15m

# REQUIRED — minimum 32 characters.
JWT_REFRESH_SECRET=your_refresh_token_secret_minimum_32_characters_here
JWT_REFRESH_EXPIRATION=7d

# OIDC / SSO-specific JWT expiry (used by the OIDC module).
JWT_EXPIRES_IN=8h

# Version label for the active JWT_SECRET.
# Increment (v2, v3, …) after each key rotation so SecretRotationService stays
# in sync after a process restart.
JWT_SECRET_VERSION=v1

# Session management (HIPAA § 164.312(a)(2)(i)).
SESSION_SECRET=your_session_secret_here
SESSION_MAX_AGE=86400000
# Inactivity timeout in minutes (HIPAA default: 15).
SESSION_TIMEOUT_MINUTES=15
MAX_SESSIONS_PER_USER=5
# Cron schedule for the session-cleanup background job.
SESSION_CLEANUP_CRON=*/15 * * * *


# =============================================================================
# Password Policy (HIPAA Compliance)
# =============================================================================
PASSWORD_MIN_LENGTH=12
# Days before a password must be changed (HIPAA: 90).
PASSWORD_EXPIRATION_DAYS=90
# Number of previous passwords that cannot be reused.
PASSWORD_HISTORY_COUNT=12
# Failed-login attempts before account lockout.
LOCKOUT_THRESHOLD=5
LOCKOUT_DURATION_MINUTES=30


# =============================================================================
# MFA Configuration
# =============================================================================
# Require MFA for medical staff accounts.
MFA_REQUIRED_FOR_STAFF=true
MFA_TIME_WINDOW=30
BACKUP_CODES_COUNT=8


# =============================================================================
# CORS & Security Headers
# =============================================================================
# Comma-separated list of allowed HTTP origins.
# Production: set explicitly — never use * in production.
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:4200

# WebSocket CORS origin (used by the Notifications gateway).
# Use * for local dev; set explicitly in production.
CORS_ORIGIN=http://localhost:4200

# Set to true to allow cookies / credentials in cross-origin requests.
CORS_CREDENTIALS=false

# Comma-separated IPs / CIDR ranges allowed to reach admin endpoints.
# Leave empty to block all admin access (fail-secure default).
# Example: ADMIN_IP_ALLOWLIST=192.168.1.0/24,10.0.0.1
ADMIN_IP_ALLOWLIST=

# Enable Helmet security headers.
ENABLE_SECURITY_HEADERS=true

# Redirect URL after a successful OIDC login (defaults to / if unset).
FRONTEND_URL=http://localhost:4200


# =============================================================================
# Redis (caching, sessions, rate limiting, queues)
# =============================================================================
REDIS_HOST=localhost
REDIS_PORT=6379
# Leave blank for no-auth local Redis.
REDIS_PASSWORD=
REDIS_DB=0
# Optional full URL — overrides individual settings above.
# REDIS_URL=redis://:password@localhost:6379/0


# =============================================================================
# Rate Limiting
# =============================================================================
RATE_LIMIT_TTL=60
RATE_LIMIT_MAX=100

# GraphQL subscription limits.
GRAPHQL_MAX_SUBSCRIPTIONS_PER_USER=10
GRAPHQL_MAX_SUBSCRIPTIONS_PER_TENANT=100


# =============================================================================
# Email (SMTP)
# =============================================================================
# NOTE: The application reads MAIL_* variables (not SMTP_*).
# Both sets are listed here for clarity; use the MAIL_* names.
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USER=your_email@example.com
# REQUIRED for email delivery
MAIL_PASSWORD=your_email_password
MAIL_FROM=noreply@healthystellar.com


# =============================================================================
# Stellar Blockchain
# =============================================================================
# Network to connect to. Values: testnet | mainnet
STELLAR_NETWORK=testnet

# Horizon REST API URL (auto-selected from STELLAR_NETWORK when omitted).
# STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org

# REQUIRED — Stellar account secret key used to sign transactions.
# Generate a keypair: https://laboratory.stellar.org/#account-creator
STELLAR_SECRET_KEY=your_stellar_secret_key_here

# REQUIRED — Soroban smart-contract ID for record anchoring.
STELLAR_CONTRACT_ID=your_contract_id_here

# Transaction fee budget in stroops (1 XLM = 10 000 000 stroops).
STELLAR_FEE_BUDGET=10000000

# Retry / resilience settings.
STELLAR_MAX_RETRIES=3
STELLAR_RETRY_MAX_ATTEMPTS=5
STELLAR_RETRY_BASE_DELAY_MS=1000
STELLAR_RETRY_MAX_DELAY_MS=30000
STELLAR_TRANSACTION_TIMEOUT_MS=60000
STELLAR_SEQUENCE_REFRESH_ENABLED=true
STELLAR_QUEUE_MAX_SIZE=1000
STELLAR_QUEUE_RETRY_INTERVAL_MS=30000
STELLAR_TRANSACTION_TTL_MS=3600000


# =============================================================================
# Soroban RPC (Stellar smart contracts)
# =============================================================================
# Soroban-RPC endpoint (auto-selected from STELLAR_NETWORK when omitted).
# SOROBAN_RPC_URL=https://soroban-testnet.stellar.org

# Override network for Soroban calls. Values: testnet | public
# SOROBAN_NETWORK=testnet

# Secret key of the account used to deploy contracts (CI / devops only).
# SOROBAN_CONTRACT_DEPLOYER_SECRET=


# =============================================================================
# IPFS
# =============================================================================
# Individual connection parameters.
IPFS_HOST=localhost
IPFS_PORT=5001
IPFS_PROTOCOL=http

# Full API URL — used by health checks and some services.
# Must match IPFS_HOST / IPFS_PORT above.
IPFS_API_URL=http://localhost:5001

# Alternate URL variable read by ipfs.service.ts.
IPFS_URL=http://localhost:5001


# =============================================================================
# Webhook Signature Secrets (HMAC-SHA256)
# =============================================================================
# REQUIRED — generate with:
#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
IPFS_WEBHOOK_SECRET=your_ipfs_webhook_secret_here
STELLAR_WEBHOOK_SECRET=your_stellar_webhook_secret_here

# REQUIRED — used to sign and verify internal queue payloads.
QUEUE_HMAC_SECRET=your_queue_hmac_secret_here


# =============================================================================
# OIDC / OAuth2 (Single Sign-On)
# =============================================================================
# Comma-separated list of enabled OIDC providers.
# Example: OIDC_PROVIDERS=azure,google
OIDC_PROVIDERS=

# Per-provider configuration — repeat this block for each provider listed above,
# replacing {PROVIDER} with the provider name in uppercase (e.g. AZURE, GOOGLE).
#
# OIDC_{PROVIDER}_ISSUER=https://login.microsoftonline.com/{tenant}/v2.0
# OIDC_{PROVIDER}_CLIENT_ID=your_client_id
# OIDC_{PROVIDER}_CLIENT_SECRET=your_client_secret
# OIDC_{PROVIDER}_REDIRECT_URI=http://localhost:3000/auth/oidc/{provider}/callback
# OIDC_{PROVIDER}_SCOPE=openid profile email
# OIDC_{PROVIDER}_AUTHORIZATION_URL=   # optional — auto-discovered from issuer
# OIDC_{PROVIDER}_TOKEN_URL=           # optional — auto-discovered from issuer
# OIDC_{PROVIDER}_JWKS_URI=            # optional — auto-discovered from issuer
# OIDC_{PROVIDER}_USERINFO_URL=        # optional — auto-discovered from issuer
#
# Azure AD example:
# OIDC_AZURE_ISSUER=https://login.microsoftonline.com/your-tenant-id/v2.0
# OIDC_AZURE_CLIENT_ID=your_azure_client_id
# OIDC_AZURE_CLIENT_SECRET=your_azure_client_secret
# OIDC_AZURE_REDIRECT_URI=http://localhost:3000/auth/oidc/azure/callback


# =============================================================================
# Logging
# =============================================================================
# Log verbosity. Values: error | warn | info | debug | verbose
LOG_LEVEL=debug
LOG_FILE_PATH=./logs
SLOW_REQUEST_THRESHOLD_MS=1000

# Loki (centralised log aggregation — leave blank to disable).
LOKI_HOST=http://localhost:3100
LOKI_USERNAME=
LOKI_PASSWORD=

# Retention periods.
APP_LOG_RETENTION_DAYS=30
# HIPAA requires audit logs for 6–7 years (2555 days).
AUDIT_LOG_RETENTION_DAYS=2555

# Set to true to include GET requests in the audit log (high volume — use with care).
AUDIT_GET_REQUESTS=false

# Enable individual audit / access logging features.
ENABLE_AUDIT_LOGGING=true
ENABLE_ACCESS_LOGGING=true
ENABLE_DETAILED_AUDIT=true

# In-memory ring-buffer size for the incident log.
INCIDENT_LOG_BUFFER_SIZE=200


# =============================================================================
# Metrics & Observability
# =============================================================================
# Bearer token required to access the /metrics endpoint.
# REQUIRED in production — generate a strong random value.
METRICS_TOKEN=your_secure_metrics_token_here

# Networks allowed to scrape /metrics (comma-separated IPs / CIDR).
METRICS_ALLOWED_NETWORKS=127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

# Prometheus base URL (used by SloService to query recording rules).
# Docker Compose: http://prometheus:9090 | Local dev: http://localhost:9090
PROMETHEUS_URL=http://prometheus:9090


# =============================================================================
# OpenTelemetry Distributed Tracing
# =============================================================================
OTEL_TRACING_ENABLED=true
OTEL_SERVICE_NAME=healthy-stellar-backend

# OTLP collector endpoint.
# Local Jaeger: http://localhost:4318/v1/traces
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces

# Sampling rate (0.0–1.0). Use 1.0 for dev, 0.1 for production.
OTEL_SAMPLING_RATE=1.0


# =============================================================================
# Backup & Disaster Recovery
# =============================================================================
BACKUP_ENABLED=true
# Cron schedule for automated backups (default: 2 AM daily).
BACKUP_SCHEDULE=0 2 * * *
BACKUP_DIR=/backups
BACKUP_RETENTION_DAYS=90
# REQUIRED — used to encrypt backup archives at rest.
BACKUP_ENCRYPTION_KEY=your_backup_encryption_key_here

# Pre-migration backup settings.
MIGRATION_BACKUP_ENABLED=true
MIGRATION_BACKUP_DIR=/tmp/db-backups
MIGRATION_BACKUP_TIMEOUT_MS=120000
# Block the migration run if the pre-migration backup fails.
MIGRATION_BACKUP_BLOCK_ON_FAILURE=true


# =============================================================================
# Migration Safety & Notifications
# =============================================================================
# Must be set to 'true' to allow migrations to run in production.
# This is a deliberate safety gate — do not set it permanently.
# CONFIRM_PRODUCTION_MIGRATION=true

# Identity logged in the migration audit trail.
# Falls back to GITHUB_ACTOR, then the OS USER environment variable.
# MIGRATION_EXECUTOR=your_name

# Slack notifications for migration events.
# MIGRATION_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/your/webhook/url
MIGRATION_SLACK_CHANNEL=#ops-migrations
# Set to true to notify on all environments, not just production.
MIGRATION_SLACK_ALL_ENVS=false


# =============================================================================
# Swagger / API Docs
# =============================================================================
# Basic-auth credentials protecting the Swagger UI (/api).
# Change these before deploying to any shared environment.
SWAGGER_USER=admin
SWAGGER_PASS=change_me_in_production


# =============================================================================
# File Uploads
# =============================================================================
# Maximum upload size in bytes (default: 100 MB).
UPLOAD_MAX_FILE_SIZE_BYTES=104857600
UPLOAD_PATH=./storage/uploads


# =============================================================================
# FHIR & Bulk Export
# =============================================================================
# Rows fetched per batch during FHIR bulk export.
BULK_EXPORT_BATCH_SIZE=500

# Data retention for medical records (legal minimum varies by jurisdiction).
RECORD_RETENTION_YEARS=7
DATA_RETENTION_DAYS=2555

# Event-store snapshot retention: number of most-recent snapshots kept per aggregate.
SNAPSHOT_RETENTION_COUNT=3


# =============================================================================
# HIPAA Compliance Feature Flags
# =============================================================================
HIPAA_COMPLIANCE_ENABLED=true


# =============================================================================
# Optional Module Feature Flags
# =============================================================================
# Telemedicine — virtual visits, remote monitoring, telehealth billing.
# Set to true to enable telemedicine endpoints.
TELEMEDICINE_ENABLED=false

# Telemedicine service base URL (required when TELEMEDICINE_ENABLED=true).
TELEMEDICINE_BASE_URL=https://telemedicine.app

# Surgical Management — surgical cases, operating rooms, outcomes.
# Set to true to enable surgical management endpoints.
SURGICAL_MANAGEMENT_ENABLED=false


# =============================================================================
# AWS (KMS key management — optional, required for envelope encryption)
# =============================================================================
# AWS_REGION=us-east-1
# AWS_ACCESS_KEY_ID=your_aws_access_key_id
# AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key


# =============================================================================
# Report Worker
# =============================================================================
# RSS memory limit for the report background worker process (MB).
REPORT_WORKER_RSS_LIMIT_MB=512


# =============================================================================
# Test / CI Variables (not needed for normal development)
# =============================================================================
# Dedicated test database — used by the Jest e2e suite.
# TEST_DB_HOST=localhost
# TEST_DB_PORT=5432
# TEST_DB_USERNAME=test_user
# TEST_DB_PASSWORD=test_password
# TEST_DB_NAME=healthy_stellar_test

# Set to true to run live Stellar integration tests (requires funded testnet account).
# STELLAR_INTEGRATION=false

# Set to true to run migration integration tests.
# INTEGRATION_TESTS=false

# Set to true to run AWS LocalStack integration tests.
# LOCALSTACK_TESTS=false

# Performance test thresholds (milliseconds).
# PERF_PATIENT_LOOKUP_THRESHOLD=100
# PERF_RECORD_RETRIEVAL_THRESHOLD=500
# PERF_RECORD_CREATION_THRESHOLD=200