.env.example

# ==============================================================================
# ScatterID — Authoritative Environment Configuration Template
# ==============================================================================
# Copy this file to .env and configure values before starting services:
#   cp .env.example .env
#
# Tip: If you run `./scripts/quickstart.sh`, it will automatically create .env
# and generate secure 256-bit random cryptographic keys for you.
#
# Convention:
# Every tunable option is documented with a short explanatory comment above a
# commented-out line containing its default or placeholder value.
# ==============================================================================

# ──────────────────────────────────────────────────────────────────────────────
# 1. Cryptographic Authentication Keys & Secrets (Required)
# ──────────────────────────────────────────────────────────────────────────────

# 256-bit hex key gating all inbound ML-DSA-65 post-quantum signing & verification requests on the Python crypto-service.
# CRYPTO_SERVICE_API_KEY=<your-256-bit-hex-api-key-here>

# 256-bit hex Bearer token required for standard issuance (/issue), query (/credentials), and audit (/audit) endpoints on verification-api.
# VERIFICATION_API_KEY=<your-256-bit-hex-api-key-here>

# 256-bit hex Bearer token required for the web operator dashboard to authenticate inbound browser requests on /api/*.
# GATEWAY_API_KEY=<your-256-bit-hex-api-key-here>

# Dedicated higher-privilege Bearer token or X-Revoke-Key required to execute irreversible on-chain revocation on POST /revoke.
# MUST be distinct from VERIFICATION_API_KEY (the service will fail-fast at boot if they match).
# REVOKE_API_KEY=<your-256-bit-hex-revoke-key-here>

# 256-bit hex secret key used by ops-dashboard to sign and verify operator session JWTs (HMAC-SHA256).
# Service fails fast at boot if missing or if entropy < 256 bits (generate with: openssl rand -hex 32).
# JWT_SECRET=<your-256-bit-hex-session-secret-here>

# Server-side cryptographic pepper used to hash operator single-use recovery codes with HMAC-SHA256.
# Protects against offline dictionary/rainbow-table brute forcing in case of database leakage.
# Required in production (minimum 128 bits entropy; generate with: openssl rand -hex 32).
# RECOVERY_CODE_PEPPER=<your-256-bit-hex-recovery-pepper-here>

# Key Lifecycle, Zero-Downtime Rotation & Dual-Key Grace Windows:
# ScatterID enforces a 30-day recommended rotation SLA for all service-to-service keys.
# Run `./scripts/security/rotate_service_keys.sh --stage` to promote keys and stage grace window.
# Run `./scripts/security/audit_service_keys.sh` to audit key age and entropy posture.
#
# ISO-8601 timestamp marking last rotation date (used by audit and monitoring tooling).
# KEY_ROTATION_TIMESTAMP=2026-09-06T00:00:00Z
#
# Maximum key age in days before alerting and mandatory rotation (default: 30 days).
# KEY_MAX_AGE_DAYS=30
#
# Optional secondary/previous keys accepted during zero-downtime rolling deployment grace windows:
# VERIFICATION_API_KEY_PREVIOUS=
# REVOKE_API_KEY_PREVIOUS=
# CRYPTO_SERVICE_API_KEY_PREVIOUS=


# ──────────────────────────────────────────────────────────────────────────────
# 2. Microservice Network Endpoints & Hostnames
# ──────────────────────────────────────────────────────────────────────────────

# Internal HTTPS URL the Verification API and Dashboard use to communicate with the ML-DSA-65 crypto-service.
# CRYPTO_SERVICE_URL=https://crypto-service:5001

# Internal HTTP URL the Dashboard and client SDKs use to communicate with the Express Verification Gateway.
# VERIFICATION_API_URL=http://verification-api:3000

# Docker network hostname or IP for the crypto-service container used for TCP socket reachability checks.
# CRYPTO_SERVICE_HOST=crypto-service

# Docker network hostname or IP for the verification-api container used for TCP socket reachability checks.
# VERIFICATION_API_HOST=verification-api


# ──────────────────────────────────────────────────────────────────────────────
# 3. HashiCorp Vault Key Management Service (KMS)
# ──────────────────────────────────────────────────────────────────────────────

# Network address of the HashiCorp Vault instance holding ML-DSA-65 root signing key material.
# Must use https:// in production (http:// permitted only when VAULT_DEV_MODE=true).
# VAULT_ADDR=https://vault.scatterid.com:8200

# Allows HTTP communication and ambient VAULT_TOKEN for local testing only;
# Defaults to false (production mode enforces HTTPS and mandatory AppRole authentication).
# VAULT_DEV_MODE=false

# Vault AppRole Authentication (MANDATORY IN PRODUCTION):
# In production (VAULT_DEV_MODE=false), the crypto-service strictly enforces AppRole authentication.
# Ambient root/static VAULT_TOKEN is deprecated, strictly forbidden, and rejected at startup.
# Setup policy and credentials using: ./scripts/security/setup_vault_approle.sh
# VAULT_ROLE_ID=<your-vault-approle-role-id>
# VAULT_SECRET_ID=<your-vault-approle-secret-id>

# Development-only Ambient Vault Token (FORBIDDEN IN PRODUCTION):
# Accepted ONLY when VAULT_DEV_MODE=true for local mock/dev clusters. Ignored or rejected in production.
# VAULT_TOKEN=

# Key-value secret path inside Vault KV-v2 where active ML-DSA-65 private keys are stored.
# VAULT_SECRET_PATH=scatterid/mldsa

# Cryptographic signing boundary architecture ('transit' for isolated HSM/Transit boundary, 'kv' for legacy in-memory).
# In 'transit' mode, private key material never touches application runtime memory, neutralizing RCE key compromise.
# VAULT_SIGNING_MODE=transit

# Key name identifier inside Vault Transit engine when running in transit signing mode.
# VAULT_TRANSIT_KEY_NAME=scatterid-mldsa


# ──────────────────────────────────────────────────────────────────────────────
# 4. Transport Layer Security (TLS) Trust Store
# ──────────────────────────────────────────────────────────────────────────────

# Path to the Root CA certificate inside containers used to establish cryptographic trust with internal mTLS endpoints.
# NODE_EXTRA_CA_CERTS=/app/certs/ca.crt


# ──────────────────────────────────────────────────────────────────────────────
# 5. Local Host Port Mappings
# ──────────────────────────────────────────────────────────────────────────────

# Local host port bound to the Express Verification Gateway API.
# PORT_VERIFICATION_API=3000

# Local host port bound to the Python ML-DSA-65 Post-Quantum Crypto Service.
# PORT_CRYPTO_SERVICE=5001

# Local host port bound to the Operator Diagnostics Console and Management Dashboard.
# PORT_DASHBOARD=4000

# Local host port bound to the HashiCorp Vault Key Management Service.
# PORT_VAULT=8200


# ──────────────────────────────────────────────────────────────────────────────
# 6. Hyperledger Fabric Blockchain Network Configuration
# ──────────────────────────────────────────────────────────────────────────────

# Host and port of the primary peer node receiving transaction proposals.
# FABRIC_PEER_ENDPOINT=peer0.issuer.scatterid.com:7051

# TLS Server Name Indication (SNI) hostname override used during peer gRPC handshake.
# FABRIC_PEER_HOST_ALIAS=peer0.issuer.scatterid.com

# Name of the permissioned consortium channel where cryptographic anchors are committed.
# FABRIC_CHANNEL_NAME=scatterid-channel

# Name of the deployed smart contract defining AnchorProof, RevokeProof, and QueryProof methods.
# FABRIC_CHAINCODE_NAME=scatterproof

# Membership Service Provider identifier for the issuing organization.
# FABRIC_MSP_ID=IssuerMSP


# ──────────────────────────────────────────────────────────────────────────────
# 7. Persistence & Runtime Environment
# ──────────────────────────────────────────────────────────────────────────────

# Filesystem path to the durable SQLite database storing credential metadata and audit logs.
# SQLITE_DB_PATH=/app/data/credentials.db

# Node.js runtime environment mode controlling logging verbosity and error trace disclosure.
# NODE_ENV=production