.env.example

# =============================================================================
# Nova Rewards — Environment Variables Reference
# =============================================================================
#
# This file is the authoritative reference for every environment variable
# consumed by the Nova Rewards backend and frontend.
#
# HOW TO USE
# ----------
# 1. Copy this file:
#      cp .env.example .env.local        # frontend (Next.js)
#      cp .env.example backend/.env      # backend (Express)
# 2. Replace every placeholder value with a real value for your environment.
# 3. Never commit files containing real secrets to version control.
#
# VALIDATION
# ----------
# Backend:  novaRewards/backend/middleware/validateEnv.js
#           Called at server startup — missing required vars abort the process.
# Frontend: novaRewards/frontend/lib/env.js  (Zod schema)
#           Called at Next.js build time — missing required vars abort the build.
#
# CI CHECK
# --------
# .github/workflows/env-check.yml verifies that every variable defined in
# validateEnv.js and frontend/lib/env.js is present in this file.
# Run locally: node scripts/check-env-example.js
#
# GROUPING
# --------
# Variables are grouped by service. Required variables are marked [REQUIRED].
# Optional variables include their default value in a comment.
# =============================================================================


# =============================================================================
# ── Server ───────────────────────────────────────────────────────────────────
# =============================================================================

# TCP port the Express backend listens on.
# [OPTIONAL] Default: 3001
PORT=3001

# Runtime environment. Controls CORS policy, Swagger UI visibility, and logging.
# Values: development | test | staging | production
# [REQUIRED]
NODE_ENV=development

# Comma-separated list of allowed CORS origins.
# In production, list exact origins — no wildcards.
# [REQUIRED in production]
ALLOWED_ORIGIN=http://localhost:3000


# =============================================================================
# ── Stellar / Horizon ────────────────────────────────────────────────────────
# =============================================================================

# Stellar network to connect to.
# Values: testnet | mainnet
# [REQUIRED]
STELLAR_NETWORK=testnet

# Stellar Horizon REST API endpoint.
# Testnet:  https://horizon-testnet.stellar.org
# Mainnet:  https://horizon.stellar.org
# [REQUIRED]
HORIZON_URL=https://horizon-testnet.stellar.org

# Stellar Issuer Account — creates and issues the NOVA asset.
# Public key starts with G (56 characters).
# [REQUIRED]
ISSUER_PUBLIC=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Stellar Issuer Account secret key — signs issuance transactions.
# Secret key starts with S (56 characters). NEVER expose to the browser.
# [REQUIRED]
ISSUER_SECRET=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Stellar Distribution Account — sends NOVA tokens to user wallets.
# [REQUIRED]
DISTRIBUTION_PUBLIC=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# [REQUIRED]
DISTRIBUTION_SECRET=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX


# =============================================================================
# ── Soroban Smart Contracts ──────────────────────────────────────────────────
# =============================================================================

# Contract IDs are written automatically by scripts/deploy-contracts.sh.
# Leave blank until contracts are deployed to the target network.

# [OPTIONAL]
NOVA_TOKEN_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# [OPTIONAL]
REWARD_POOL_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# [OPTIONAL]
VESTING_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# [OPTIONAL]
REFERRAL_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# [OPTIONAL]
DISTRIBUTION_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# [OPTIONAL]
ADMIN_ROLES_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# [OPTIONAL]
NOVA_REWARDS_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# [OPTIONAL]
GOVERNANCE_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX


# =============================================================================
# ── Database (PostgreSQL) ────────────────────────────────────────────────────
# =============================================================================

# Full PostgreSQL connection string used by the backend and Prisma.
# Format: postgresql://<user>:<password>@<host>:<port>/<database>
# [REQUIRED]
DATABASE_URL=postgresql://nova:changeme@localhost:5432/nova_rewards

# Individual connection components (used by Docker Compose and pg_dump scripts).
POSTGRES_USER=nova
POSTGRES_PASSWORD=changeme
POSTGRES_DB=nova_rewards

# Migration-only connection string (limited privileges — CREATE TABLE, ALTER TABLE).
# In production, sourced from AWS Secrets Manager via DB_MIGRATE_SECRET_ARN.
# [OPTIONAL] Falls back to DATABASE_URL if unset.
DATABASE_MIGRATE_URL=postgresql://nova_migrate:changeme@localhost:5432/nova_rewards

# AWS Secrets Manager ARN for the migration password (production only).
# [OPTIONAL]
# DB_MIGRATE_SECRET_ARN=arn:aws:secretsmanager:us-east-1:123456789012:secret:nova/db-migrate


# =============================================================================
# ── Redis ────────────────────────────────────────────────────────────────────
# =============================================================================

# Redis connection URL.
# Local development:  redis://localhost:6379
# Production (TLS):   rediss://:<auth_token>@<elasticache-endpoint>:6379
#   The "rediss://" scheme enables TLS automatically (ioredis).
# [REQUIRED]
REDIS_URL=redis://localhost:6379

# Redis host and port (used by BullMQ queue configuration).
# [OPTIONAL] Derived from REDIS_URL if not set explicitly.
REDIS_HOST=localhost
REDIS_PORT=6379

# Maximum memory Redis is allowed to use before eviction kicks in.
# [OPTIONAL] Default: 256mb
REDIS_MAXMEMORY=256mb


# =============================================================================
# ── Authentication (JWT RS256) ───────────────────────────────────────────────
# =============================================================================
#
# Nova Rewards uses RS256 asymmetric JWT signing (ADR-0007).
# JWT_SECRET is no longer used; it has been replaced by the RS256 key pair.
#
# Generate a new key pair:
#   node novaRewards/backend/scripts/generate-jwt-keys.js
#
# Store the real keys in AWS Secrets Manager in production.
# Newlines in the PEM must be escaped as \n when stored in a single-line env var.

# RSA private key (2048-bit) — used to SIGN tokens. Keep secret.
# [REQUIRED]
JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7...<replace>\n-----END PRIVATE KEY-----"

# RSA public key — used to VERIFY tokens. Safe to distribute to other services.
# [REQUIRED]
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu...<replace>\n-----END PUBLIC KEY-----"


# =============================================================================
# ── Field-Level Encryption (AES-256-GCM) ────────────────────────────────────
# =============================================================================
#
# Used to encrypt PII fields (user email, webhook secrets) before writing to
# PostgreSQL (ADR-0013). The database never stores plaintext PII.
#
# Generate a new key:
#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
#
# The output is a 64-character hex string (32 bytes = 256-bit key).
# Store the real key in AWS Secrets Manager in production.

# [REQUIRED]
FIELD_ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000

# Previous encryption key — set during key rotation so existing rows can still
# be decrypted. Remove after all rows have been re-encrypted.
# [OPTIONAL]
# FIELD_ENCRYPTION_KEY_PREVIOUS=<old-64-char-hex-key>


# =============================================================================
# ── Email ────────────────────────────────────────────────────────────────────
# =============================================================================

# SMTP configuration for transactional email (local development / staging).
# [OPTIONAL] Required if SENDGRID_API_KEY is not set.
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-smtp-username@example.com
SMTP_PASSWORD=your-smtp-password

# Sender address shown in the From header.
# [OPTIONAL] Default: noreply@novarewards.com
EMAIL_FROM=noreply@novarewards.com

# SendGrid API key (production alternative to SMTP).
# [OPTIONAL] Takes precedence over SMTP settings when set.
SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx


# =============================================================================
# ── Webhooks ─────────────────────────────────────────────────────────────────
# =============================================================================

# Timeout for outbound webhook HTTP requests (milliseconds).
# [OPTIONAL] Default: 10000
WEBHOOK_TIMEOUT_MS=10000

# Interval between webhook retry attempts (milliseconds).
# [OPTIONAL] Default: 60000
WEBHOOK_RETRY_INTERVAL_MS=60000

# Maximum number of delivery attempts before a webhook is moved to the DLQ.
# [OPTIONAL] Default: 5
WEBHOOK_MAX_ATTEMPTS=5


# =============================================================================
# ── Rate Limiting ────────────────────────────────────────────────────────────
# =============================================================================

# Comma-separated IP addresses exempt from rate limiting (health checks, monitors).
# [OPTIONAL] Default: 127.0.0.1,::1
RATE_LIMIT_WHITELIST=127.0.0.1,::1

# Per-window request caps (requests per 60-second window).
# Override the defaults defined in backend/config/constants.js.
# [OPTIONAL]
RL_GLOBAL_MAX=100
RL_AUTH_MAX=5
RL_USER_MAX=200
RL_SEARCH_MAX=30
RL_WEBHOOK_MAX=60
RL_REWARDS_MAX=20
RL_ADMIN_MAX=120


# =============================================================================
# ── Rewards & Referrals ──────────────────────────────────────────────────────
# =============================================================================

# Idempotency HMAC secret — used by reward issuance engine (#1138).
# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Must be set in production; never commit the real value.
# [REQUIRED in production]
IDEMPOTENCY_HMAC_SECRET=replace-with-64-char-hex-string-generated-by-command-above

# Points awarded for each successful referral.
# [OPTIONAL] Default: 100
REFERRAL_BONUS_POINTS=100

# Points awarded for the daily login bonus.
# [OPTIONAL] Default: 10
DAILY_BONUS_POINTS=10


# =============================================================================
# ── Elasticsearch (Search) ───────────────────────────────────────────────────
# =============================================================================

# Elasticsearch endpoint for full-text search (campaigns, merchants, users).
# [OPTIONAL] Search features are disabled if unset.
ELASTICSEARCH_URL=http://localhost:9200

# API key for Elastic Cloud authentication.
# [OPTIONAL] Used instead of username/password for cloud deployments.
# ELASTICSEARCH_API_KEY=your-elastic-cloud-api-key

# CA certificate for TLS verification (PEM string or file path).
# [OPTIONAL]
# ELASTICSEARCH_CA_CERT=


# =============================================================================
# ── AWS ──────────────────────────────────────────────────────────────────────
# =============================================================================

# AWS region for Secrets Manager, CloudWatch, and S3.
# [OPTIONAL] Required when using AWS services.
AWS_REGION=us-east-1

# AWS credentials (not needed when running on EC2/ECS with an IAM role).
# [OPTIONAL]
# AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
# AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY


# =============================================================================
# ── Logging ──────────────────────────────────────────────────────────────────
# =============================================================================

# Minimum log level emitted by Winston.
# Values: error | warn | info | http | verbose | debug | silly
# [OPTIONAL] Default: info
LOG_LEVEL=info

# Docker log driver. Set to "awslogs" to ship container logs to CloudWatch.
# [OPTIONAL] Default: json-file (local development)
# LOG_DRIVER=awslogs

# CloudWatch log group for the backend container.
# [OPTIONAL] Required when LOG_DRIVER=awslogs.
# CLOUDWATCH_LOG_GROUP=/nova-rewards/production/backend


# =============================================================================
# ── Database Backups ─────────────────────────────────────────────────────────
# =============================================================================

# Number of days to retain PostgreSQL backup files.
# [OPTIONAL] Default: 7
BACKUP_RETAIN_DAYS=7

# Enable automated PostgreSQL backups.
# [OPTIONAL] Default: false
BACKUP_ENABLED=false

# S3 bucket for backup storage.
# [OPTIONAL] Required when BACKUP_ENABLED=true.
# BACKUP_S3_BUCKET=nova-rewards-backups

# Passphrase used to encrypt backup archives (GPG symmetric encryption).
# [OPTIONAL] Required when BACKUP_ENABLED=true.
BACKUP_PASSPHRASE=replace-with-strong-random-passphrase


# =============================================================================
# ── PWA Push Notifications (VAPID) ──────────────────────────────────────────
# =============================================================================
#
# Generate VAPID keys:
#   npx web-push generate-vapid-keys

# VAPID public key — embedded in the browser service worker.
# [OPTIONAL] Required to enable push notifications.
VAPID_PUBLIC_KEY=your-vapid-public-key-base64url

# VAPID private key — used by the backend to sign push requests. Keep secret.
# [OPTIONAL] Required to enable push notifications.
VAPID_PRIVATE_KEY=your-vapid-private-key-base64url

# Contact email included in VAPID requests (required by push services).
# [OPTIONAL] Default: admin@novarewards.com
VAPID_EMAIL=admin@novarewards.com


# =============================================================================
# ── Frontend (Next.js — NEXT_PUBLIC_* vars are exposed to the browser) ───────
# =============================================================================
#
# NEXT_PUBLIC_* variables are embedded in the browser bundle at build time.
# Never put secrets or private keys in NEXT_PUBLIC_* variables.
#
# Validated by: novaRewards/frontend/lib/env.js (Zod schema)

# Backend API base URL.
# [REQUIRED by frontend]
NEXT_PUBLIC_API_URL=http://localhost:3001

# Stellar Horizon endpoint used by the frontend for balance and trustline checks.
# [REQUIRED by frontend]
NEXT_PUBLIC_HORIZON_URL=https://horizon-testnet.stellar.org

# Stellar issuer public key (safe to expose — public key only).
# Must match ISSUER_PUBLIC above.
# [REQUIRED by frontend]
NEXT_PUBLIC_ISSUER_PUBLIC=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Stellar network identifier.
# Values: testnet | mainnet | public
# [REQUIRED by frontend]
NEXT_PUBLIC_STELLAR_NETWORK=testnet

# Soroban multisig contract ID (optional — not deployed in all environments).
# [OPTIONAL]
NEXT_PUBLIC_MULTISIG_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# Feature flags — enable/disable platform features per environment.
# [OPTIONAL] Default: false
NEXT_PUBLIC_STAKING_ENABLED=false
NEXT_PUBLIC_REFERRAL_ENABLED=false

# VAPID public key for the browser service worker (must match VAPID_PUBLIC_KEY above).
# [OPTIONAL] Required to enable push notifications in the browser.
NEXT_PUBLIC_VAPID_PUBLIC_KEY=your-vapid-public-key-base64url

# Sentry DSN for frontend error tracking.
# [OPTIONAL] Error tracking is disabled if unset.
NEXT_PUBLIC_SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0

# Environment label sent to Sentry with each event.
# [OPTIONAL] Default: development
NEXT_PUBLIC_ENVIRONMENT=development

# Sentry organisation slug (used by the Sentry CLI for source map uploads).
# [OPTIONAL] Required for source map uploads in CI.
SENTRY_ORG=your-sentry-org-slug

# Sentry project slug.
# [OPTIONAL] Required for source map uploads in CI.
SENTRY_PROJECT=nova-rewards-frontend

# Sentry auth token for source map uploads (CI only — not needed at runtime).
# [OPTIONAL]
SENTRY_AUTH_TOKEN=sntrys_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx