.env.example

# =============================================================================
# VacciChain Environment Variables
# =============================================================================
# Copy this file to .env and fill in the required values:
#   cp .env.example .env
#
# Required variables are marked with [REQUIRED].
# Optional variables show their default after the = sign.
# =============================================================================

# -- Stellar / Soroban ------------------------------------------------------------

# Network to connect to: "testnet" or "mainnet" (default: testnet)
STELLAR_NETWORK=testnet

# Frontend network — must match STELLAR_NETWORK; Vite requires the VITE_ prefix
# to expose env vars to the browser bundle at build time.
VITE_STELLAR_NETWORK=testnet

# Horizon REST API for the chosen network
HORIZON_URL=https://horizon-testnet.stellar.org

# [REQUIRED] Soroban RPC endpoint for contract simulation and submission
# Testnet: https://soroban-testnet.stellar.org
# Mainnet: https://soroban-rpc.mainnet.stellar.gateway.fm
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org

# [REQUIRED] Network passphrase -- must exactly match the target network
# Testnet: "Test SDF Network ; September 2015"
# Mainnet: "Public Global Stellar Network ; September 2015"
STELLAR_NETWORK_PASSPHRASE=Test SDF Network ; September 2015

# -- Contract ---------------------------------------------------------------------

# [REQUIRED] Deployed contract address (56-char string starting with C)
# Obtain from: cd contracts && make deploy
VACCINATIONS_CONTRACT_ID=

# -- Backend auth -----------------------------------------------------------------

# [REQUIRED] Secret key for admin contract invocations (starts with S, 56 chars)
ADMIN_SECRET_KEY=

# [REQUIRED] Public key matching ADMIN_SECRET_KEY (starts with G, 56 chars)
# Grants the "issuer" role when this wallet authenticates via SEP-10
ADMIN_PUBLIC_KEY=

# [REQUIRED] Dedicated secret key for signing SEP-10 challenge transactions (starts with S, 56 chars)
SEP10_SERVER_KEY=

# SEP-10: home domain used as the manage_data key prefix ("<HOME_DOMAIN> auth")
# Must match the domain in your stellar.toml (e.g. vaccichain.example.com)
HOME_DOMAIN=localhost

# SEP-10: domain of this auth server -- included in the web_auth_domain manage_data operation
# May differ from HOME_DOMAIN when the auth server is on a subdomain
WEB_AUTH_DOMAIN=localhost

# [REQUIRED] Secret key for signing mint/revoke transactions (starts with S, 56 chars)
ISSUER_SECRET_KEY=

# [REQUIRED] JWT signing secret -- min 32 characters recommended
# Generate with: openssl rand -hex 32
# Rotate this value to invalidate all active sessions
JWT_SECRET=

# kid (Key ID) for the current JWT signing key (default: 1)
# Increment on each secret rotation so tokens carry the correct kid claim
JWT_KEY_ID=1

# Comma-separated list of previous JWT secrets still accepted for verification
# during the transition window after a rotation. Remove entries once all
# tokens signed with those secrets have expired.
# Example: JWT_PREVIOUS_KEYS=oldSecret1,oldSecret2
JWT_PREVIOUS_KEYS=

# -- Backend server ---------------------------------------------------------------

# TCP port for the Express backend (default: 4000)
PORT=4000

# API version header value returned in all responses (default: 1)
API_VERSION=1

# Winston log level (default: info)
# Allowed values: error | warn | info | http | debug
LOG_LEVEL=info

# Maximum JSON request body size accepted by the API (default: 10kb)
# Format: number + unit, e.g. "10kb", "1mb"
BODY_LIMIT=10kb

# Comma-separated list of allowed CORS origins (default: http://localhost:3000)
# Example: https://app.example.com,https://admin.example.com
ALLOWED_ORIGINS=http://localhost:3000

# Max retries for Soroban RPC calls before failing (default: 3)
SOROBAN_RPC_MAX_RETRIES=3

# Base transaction fee in stroops (1 XLM = 10,000,000 stroops; default: 100)
SOROBAN_FEE=100

# Fee bump tip in stroops to prioritise transactions during congestion (default: 0)
SOROBAN_TIP=0

# How often (ms) the event indexer polls for new contract events (default: 15000)
EVENT_POLL_INTERVAL_MS=15000

# Path to the SQLite database file used by the indexer (default: /data/vaccichain.db)
DATABASE_PATH=/data/vaccichain.db

# -- Rate limiting ----------------------------------------------------------------

# Max SEP-10 challenge requests per IP per minute (default: 10)
RATE_LIMIT_SEP10=10

# Max public verify requests per IP per minute (default: 60)
RATE_LIMIT_VERIFY=60

# -- Brute-force protection -------------------------------------------------------

# Max failed /auth/verify attempts before blocking (default: 5)
BRUTE_FORCE_MAX_ATTEMPTS=5

# Sliding window for counting failures in milliseconds (default: 600000 = 10 min)
BRUTE_FORCE_WINDOW_MS=600000

# How long a blocked IP/wallet stays blocked in milliseconds (default: 900000 = 15 min)
BRUTE_FORCE_BLOCK_MS=900000

# -- Audit log --------------------------------------------------------------------

# Path to append-only NDJSON audit log (default: ./audit.log)
AUDIT_LOG_PATH=./audit.log

# -- Python analytics service -----------------------------------------------------

# TCP port for the FastAPI analytics service (default: 8001)
ANALYTICS_PORT=8001

# Base URL the analytics service uses to reach the backend (default: http://backend:4000)
BACKEND_URL=http://backend:4000

# API key required to access protected analytics endpoints (rates, issuers, anomalies)
# Generate with: openssl rand -hex 32
ANALYTICS_API_KEY=

# -- Anomaly detection ------------------------------------------------------------

# Mint count above which an issuer is flagged as anomalous (default: 50)
ANOMALY_THRESHOLD=50

# How often (minutes) the anomaly detection job runs (default: 15)
ANOMALY_SCHEDULE_MINUTES=15

# Webhook URL to POST alerts to when anomalies are detected (leave empty to disable)
# Slack example: https://hooks.slack.com/services/TXXXXXXXXX/BXXXXXXXXX/XXXXXXXX
ALERT_WEBHOOK_URL=

# Webhook payload format: slack | pagerduty | email (default: slack)
ALERT_WEBHOOK_TYPE=slack

# PagerDuty Events API v2 routing key -- required when ALERT_WEBHOOK_TYPE=pagerduty
# Set ALERT_WEBHOOK_URL=https://events.pagerduty.com/v2/enqueue
PAGERDUTY_ROUTING_KEY=

# Recipient email address -- required when ALERT_WEBHOOK_TYPE=email
# Format: user@example.com
ALERT_EMAIL_TO=

# -- Backup service ---------------------------------------------------------------

# S3 bucket name for analytics DB backups
S3_BUCKET_NAME=

# AWS credentials for S3 access
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=

# AWS region for S3 and Secrets Manager (default: us-east-1)
AWS_REGION=us-east-1

# Number of days to retain backups (default: 30)
RETENTION_DAYS=30

# Secret key for the demo issuer account (testnet only, starts with S)
DEMO_ISSUER_SECRET=

# Admin secret for demo/testing purposes (starts with S)
ADMIN_SECRET=

# -- Secrets Management (Production) ----------------------------------------------

# Enable AWS Secrets Manager for production (default: false)
# When true, secrets are fetched from AWS instead of .env
USE_AWS_SECRETS=false

# AWS Secrets Manager secret name/ARN containing all secrets
# Example: arn:aws:secretsmanager:us-east-1:123456789012:secret:vaccichain/prod/stellar
AWS_SECRET_NAME=

# -- Admin multi-signature --------------------------------------------------------

# Number of approvals required for critical admin operations (default: 2)
MULTISIG_THRESHOLD=2

# Comma-separated list of wallet addresses authorised to approve proposals
# Leave empty to allow any admin-role JWT holder to approve
# Example: MULTISIG_KEY_HOLDERS=GABC...,GDEF...,GHIJ...
MULTISIG_KEY_HOLDERS=

# How long a pending proposal stays valid in milliseconds (default: 3600000 = 1 hour)
MULTISIG_PROPOSAL_TTL_MS=3600000

# -- Patient consent --------------------------------------------------------------

# Set to "false" to waive consent requirement (e.g. jurisdiction config)
# Default: true (consent required before minting)
REQUIRE_PATIENT_CONSENT=true