feat: configuration for management

.env.example

@@ -1,20 +1,29 @@
-# Backend Environment Variables
-PORT=3001
+# Verinode Environment Configuration
+
+# Server Settings
+PORT=4000
 NODE_ENV=development
+ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001,http://localhost:4000
+REQUEST_SIZE_LIMIT=10mb
+
+# Blockchain Settings (RPC URLs)
+ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/YOUR_PROJECT_ID
+ETHEREUM_BRIDGE_ADDRESS=0x1234567890123456789012345678901234567890
 
-# Stellar Configuration
-STELLAR_NETWORK=testnet
-STELLAR_SECRET_KEY=your_stellar_secret_key_here
-STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
+POLYGON_RPC_URL=https://polygon-rpc.com
+POLYGON_BRIDGE_ADDRESS=0x1234567890123456789012345678901234567890
 
-# JWT Configuration
-JWT_SECRET=your_jwt_secret_here
-JWT_EXPIRES_IN=24h
+BSC_RPC_URL=https://bsc-dataseed.binance.org
+BSC_BRIDGE_ADDRESS=0x1234567890123456789012345678901234567890
 
-# Database Configuration (if using MongoDB)
-MONGODB_URI=mongodb://localhost:27017/verinode
+# Rate Limit Settings (max requests per window)
+RATE_LIMIT_STRICT=100
+RATE_LIMIT_AUTH=5
+RATE_LIMIT_API=60
+RATE_LIMIT_UPLOAD=10
 
-# Frontend Environment Variables
-REACT_APP_API_URL=http://localhost:3001
-REACT_APP_STELLAR_NETWORK=testnet
-REACT_APP_CONTRACT_ADDRESS=your_contract_address_here
+# Feature Flags (true/false)
+FEATURE_GRAPHQL_PLAYGROUND=true
+FEATURE_GRAPHQL_INTROSPECTION=true
+FEATURE_REAL_TIME_SUBSCRIPTIONS=true
+FEATURE_CROSS_CHAIN_BRIDGE=true

CONFIG.md

@@ -0,0 +1,72 @@
+# Verinode Configuration Guide
+
+This document explains how to configure the Verinode backend and GraphQL server.
+
+## Overview
+
+Verinode uses a centralized configuration system built with `dotenv` for environment variable loading and `zod` for type-safe validation. All configurations are located in `src/config/`.
+
+## Setup
+
+1. Copy `.env.example` to `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+2. Edit `.env` with your specific settings.
+
+## Configuration Options
+
+### Server Settings
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | The port the server listens on | `4000` |
+| `NODE_ENV` | Environment (`development`, `production`, `test`, `staging`) | `development` |
+| `ALLOWED_ORIGINS` | Comma-separated list of allowed CORS origins | Localhost defaults |
+| `REQUEST_SIZE_LIMIT` | Maximum request body size | `10mb` |
+
+### Blockchain Settings (EVM)
+
+Provide RPC URLs and Bridge contract addresses for supported chains:
+
+- `ETHEREUM_RPC_URL` / `ETHEREUM_BRIDGE_ADDRESS`
+- `POLYGON_RPC_URL` / `POLYGON_BRIDGE_ADDRESS`
+- `BSC_RPC_URL` / `BSC_BRIDGE_ADDRESS`
+
+### Rate Limits
+
+Configure the maximum number of requests allowed per window (e.g., 15 minutes for strict/auth):
+
+- `RATE_LIMIT_STRICT`: Used for sensitive endpoints (default: 100)
+- `RATE_LIMIT_AUTH`: Used for authentication (default: 5)
+- `RATE_LIMIT_API`: Used for general API calls (default: 60)
+- `RATE_LIMIT_UPLOAD`: Used for file uploads (default: 10)
+
+### Feature Flags
+
+Toggle specific functionalities without changing code:
+
+- `FEATURE_GRAPHQL_PLAYGROUND`: Enable/disable GraphQL Playground (default: `true`)
+- `FEATURE_GRAPHQL_INTROSPECTION`: Enable/disable Schema Introspection (default: `true`)
+- `FEATURE_REAL_TIME_SUBSCRIPTIONS`: Enable/disable Subscription server (default: `true`)
+- `FEATURE_CROSS_CHAIN_BRIDGE`: Enable/disable Bridge initialization (default: `true`)
+
+## Validation
+
+The application will fail to start if required environment variables are missing or invalid in `production` mode. This ensures that configuration errors are caught early.
+
+```bash
+❌ Invalid configuration: {
+  "server": {
+    "port": {
+      "_errors": ["Expected number, received string"]
+    }
+  }
+}
+```
+
+## Adding New Configs
+
+1. Update `src/config/schema.ts` to include the new field in the `ConfigSchema`.
+2. Update `src/config/index.ts` to map the environment variable to the schema field.
+3. Add the new variable to `.env.example`.

backend/.env.example

@@ -1 +1,144 @@
-PORT=3000
+# =============================================================================
+# Verinode Backend — Environment Variable Reference
+# =============================================================================
+# Copy this file to .env and fill in the values for your environment.
+# DO NOT commit .env to version control.
+#
+# Environment-specific overrides are loaded automatically in this order:
+#   .env.{NODE_ENV}.local  (highest priority, never commit)
+#   .env.{NODE_ENV}
+#   .env.local
+#   .env                   (this file's copy)
+# =============================================================================
+
+# ── Server ────────────────────────────────────────────────────────────────────
+PORT=3001
+HOST=0.0.0.0
+NODE_ENV=development                 # development | production | test | staging
+API_PREFIX=/api
+REQUEST_SIZE_LIMIT=10mb
+SHUTDOWN_TIMEOUT_MS=5000
+
+# ── Database ──────────────────────────────────────────────────────────────────
+MONGODB_URI=mongodb://localhost:27017/verinode
+DB_MAX_POOL_SIZE=10
+DB_CONNECT_TIMEOUT_MS=30000
+DB_SOCKET_TIMEOUT_MS=45000
+
+# ── Authentication ────────────────────────────────────────────────────────────
+# REQUIRED in production. Must be ≥ 32 characters.
+JWT_SECRET=change-me-before-going-to-production-must-be-32-chars-min
+JWT_EXPIRES_IN=24h
+JWT_ISSUER=verinode
+JWT_AUDIENCE=verinode-users
+BCRYPT_ROUNDS=12
+SESSION_SECRET=change-me-session-secret
+
+# ── Stellar / Blockchain ──────────────────────────────────────────────────────
+STELLAR_NETWORK=testnet              # testnet | mainnet
+STELLAR_SECRET_KEY=                  # Your Stellar account secret key (Sxxx...)
+# Optional override — derived from STELLAR_NETWORK if not set
+# STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
+
+# ── Cross-chain / EVM (only needed when FEATURE_CROSS_CHAIN=true) ─────────────
+ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID
+ETHEREUM_BRIDGE_ADDRESS=
+POLYGON_RPC_URL=https://polygon-rpc.com
+POLYGON_BRIDGE_ADDRESS=
+BSC_RPC_URL=https://bsc-dataseed1.binance.org
+BSC_BRIDGE_ADDRESS=
+
+# ── Redis / Cache ─────────────────────────────────────────────────────────────
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=                      # Leave blank for no auth (dev only)
+REDIS_DB=0
+REDIS_DEFAULT_TTL=3600               # Default TTL in seconds
+
+# ── IPFS ──────────────────────────────────────────────────────────────────────
+IPFS_HOST=localhost
+IPFS_PORT=5001
+IPFS_PROTOCOL=http
+IPFS_REPO=./ipfs-repo
+IPFS_GATEWAY_HOST=0.0.0.0
+IPFS_GATEWAY_PORT=8080
+
+# ── Pinning Services (at least one recommended for production) ────────────────
+# Pinata
+PINATA_API_KEY=
+PINATA_SECRET_API_KEY=
+PINATA_ENDPOINT=https://api.pinata.cloud
+PINATA_TIMEOUT=30000
+
+# Infura IPFS
+INFURA_PROJECT_ID=
+INFURA_PROJECT_SECRET=
+INFURA_IPFS_ENDPOINT=https://ipfs.infura.io:5001
+INFURA_TIMEOUT=30000
+
+# Filebase
+FILEBASE_ACCESS_KEY=
+FILEBASE_SECRET_KEY=
+FILEBASE_BUCKET=verinode-backup
+FILEBASE_ENDPOINT=https://s3.filebase.com
+FILEBASE_TIMEOUT=30000
+
+# Pinning retry settings
+PINNING_MAX_RETRIES=3
+PINNING_RETRY_DELAY=5000
+
+# ── Frontend / URLs ───────────────────────────────────────────────────────────
+FRONTEND_URL=http://localhost:3000
+API_URL=http://localhost:3001
+# Comma-separated list of allowed CORS origins (required in production)
+ALLOWED_ORIGINS=http://localhost:3000
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+LOG_LEVEL=info                       # error | warn | info | debug
+LOG_TO_FILE=false
+LOG_FILE_PATH=./logs/app.log
+LOG_MAX_SIZE=100MB
+LOG_MAX_FILES=5
+
+# ── Media / Signing ───────────────────────────────────────────────────────────
+MEDIA_SIGNING_KEY=                   # Private key for media signing
+MEDIA_VERIFICATION_PUBLIC_KEY=       # Public key for media verification
+
+# ── Webhooks / Alerts ─────────────────────────────────────────────────────────
+SLACK_WEBHOOK_URL=
+SECURITY_WEBHOOK_URL=
+WEBHOOK_AUTH_TOKEN=
+ADMIN_EMAIL=
+
+# =============================================================================
+# Feature Flags
+# Set to "true" to enable, any other value (or absent) disables.
+# =============================================================================
+
+# ── Core features ─────────────────────────────────────────────────────────────
+FEATURE_AI_VALIDATION=false          # AI/ML proof validation (requires ML service)
+FEATURE_IPFS_STORAGE=true            # Store proofs on IPFS
+FEATURE_CROSS_CHAIN=false            # Cross-chain bridge (Ethereum/Polygon/BSC)
+FEATURE_ZK_PROOFS=false              # Zero-knowledge proof privacy
+
+# ── User-facing features ──────────────────────────────────────────────────────
+FEATURE_MARKETPLACE=true             # Proof marketplace
+FEATURE_SOCIAL_SHARING=true          # Social sharing of proofs
+FEATURE_GAMIFICATION=false           # Points, achievements, leaderboards
+FEATURE_COMPLIANCE=true              # GDPR/SOC2 compliance reporting
+FEATURE_TEAM_ANALYTICS=true          # Team analytics dashboard
+
+# ── Infrastructure features ───────────────────────────────────────────────────
+FEATURE_RESPONSE_CACHE=true          # Redis response caching
+FEATURE_PROOF_EXPIRATION=false       # Proof TTL / expiration
+FEATURE_BATCH_OPERATIONS=true        # Batch proof operations
+FEATURE_REAL_TIME_STATS=false        # Real-time stats (WebSocket/SSE)
+
+# ── Security features ─────────────────────────────────────────────────────────
+FEATURE_RATE_LIMITING=true           # Rate limit enforcement
+FEATURE_MEDIA_AUTHENTICITY=false     # Video/image fingerprinting
+FEATURE_VOICE_BIOMETRICS=false       # Voice identity verification
+
+# ── Developer / debug flags ───────────────────────────────────────────────────
+FEATURE_CONFIG_ENDPOINT=false        # Expose GET /api/config (dev only)
+FEATURE_VERBOSE_LOGGING=false        # Verbose request/response logging