fix(recovery): add explicit PrismaModule import to RecoveryModule

.env.example

@@ -4,6 +4,9 @@
 # Never commit .env to version control.
 # ============================================================
 
+# Stellar Configuration
+STELLAR_HORIZON_TESTNET_URL=https://horizon-testnet.stellar.org
+STELLAR_HORIZON_MAINNET_URL=https://horizon.stellar.org
 # ------------------------------------------------------------
 # Database
 # Required: PostgreSQL connection string (Prisma)
@@ -16,21 +19,98 @@ DATABASE_URL=postgresql://user:password@localhost:5432/mux_db?sslmode=require
 # ------------------------------------------------------------
 PORT=3000
 
+# Git commit SHA of the running build, exposed via GET /health for build
+# identity/traceability. Injected by CI/Docker (--build-arg GIT_SHA=...);
+# defaults to "unknown" if not set.
+GIT_SHA=
+
+# Maximum JSON/form request body size in bytes (default: 102400 / 100 KiB).
+# Requests above this limit receive HTTP 413.
+JSON_BODY_LIMIT_BYTES=102400
+
+# Shared secret required in X-Maintenance-Secret when toggling maintenance mode.
+# Required in production (startup fails if unset); leave unset in dev/test to
+# disable remote maintenance-mode changes.
+MAINTENANCE_ADMIN_SECRET=
+
+# Shared secret required in the X-Cron-Secret header for internal cron/background
+# endpoints (e.g. POST /v1/transactions/internal/poll-pending).
+# Required in production (startup validation fails without it); in local/dev the
+# endpoints simply return 401 when unset.
+# Generate with: openssl rand -hex 32
+CRON_SECRET=
+
+# Optional: interval (ms) for the stale PROVISIONING wallet cleanup scheduler.
+# Default: 300000 (5 minutes)
+STALE_PROVISIONING_CLEANUP_INTERVAL_MS=300000
+
+# Optional: interval (ms) for the transaction polling scheduler that confirms
+# submitted transactions against Horizon. Default: 60000 (1 minute)
+TRANSACTION_POLL_INTERVAL_MS=60000
+
+# ---------------------------------------------------------------------------
+# Fee-bump sponsorship cap (issue #800)
+# ---------------------------------------------------------------------------
+# Maximum fee (in stroops) Mux will sponsor on a fee-bump transaction before
+# refusing to build/submit it. This prevents the relayer from being drained by
+# unbounded sponsorship of transaction fees.
+#   - 1 stroop = 0.0000001 XLM.
+#   - REQUIRED in production: the service refuses to start (fail-fast) if it is
+#     unset there. Outside production a bounded local default (10x the base fee)
+#     is used so dev/test remain functional.
+# FEE_BUMP_MAX_FEE=50000
+
+# ------------------------------------------------------------
+# Key Management (internal API)
+# ------------------------------------------------------------
+
+# Shared secret required in the `x-internal-api-key` header for every
+# /v1/internal/key-management/* route (issue #690). These routes custody
+# Stellar private keys and are internal-only.
+#   - Not set        → all key-management requests are denied (503, fail-closed).
+#   - Set            → requests must send a matching `x-internal-api-key` header.
+# Generate with: openssl rand -hex 32
+KEY_MANAGEMENT_INTERNAL_API_KEY=
+
+# Backend for the key-pair validation cache (issue #689).
+#   - memory   → in-process cache (per-replica, lost on restart)
+#   - disabled → no cache; every validation is recomputed (fail-closed)
+# Outside production this defaults to "memory". In production it MUST be set
+# explicitly — the app refuses to boot otherwise (no silent in-process stub).
+KEY_VALIDATION_CACHE_MODE=
+
 # ------------------------------------------------------------
 # Wallet Encryption
 # Required: Secret used to derive the AES-256-GCM encryption key
 # for Stellar private keys at rest. Use a long random string.
 # Generate with: openssl rand -hex 32
+# The documented placeholder below is rejected at startup — replace it.
 # ------------------------------------------------------------
 WALLET_ENCRYPTION_KEY=your-secret-encryption-key-min-32-chars
 
+# Optional: the PREVIOUS WALLET_ENCRYPTION_KEY, set only while a master-key
+# rotation is in flight. When present it must be a real secret (>= 32 chars)
+# distinct from WALLET_ENCRYPTION_KEY. The internal job
+#   POST /v1/internal/key-management/re-encrypt-wallet-keys
+# re-encrypts stored wallet keys under the new key; remove this once a run
+# reports reEncrypted=0 and failed=0.
+WALLET_ENCRYPTION_KEY_PREVIOUS=
+
+# Required for signed export download links. Never use a default fallback in production.
+# Generate with: openssl rand -hex 32
+EXPORT_SIGNING_SECRET=your-export-signing-secret-min-32-chars
+
 # ------------------------------------------------------------
 # Stellar / Horizon
 # Required: Horizon RPC endpoint for the target network
 # Testnet:  https://horizon-testnet.stellar.org
 # Mainnet:  https://horizon.stellar.org
 # ------------------------------------------------------------
 STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
+STELLAR_NETWORK=TESTNET
+STELLAR_HORIZON_MAX_RETRIES=3
+STELLAR_HORIZON_RETRY_BACKOFF_MS=500
+STELLAR_HORIZON_RETRY_JITTER_MS=250
 
 # ------------------------------------------------------------
 # Balance Indexer
@@ -39,6 +119,17 @@ STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
 # ------------------------------------------------------------
 BALANCE_STALE_THRESHOLD_MS=300000
 
+# Optional: Interval between scheduled balance sync runs, in ms (default: 600000 / 10 minutes)
+BALANCE_SYNC_INTERVAL_MS=600000
+# Optional: Max retries for a failed balance sync run (default: 3)
+BALANCE_SYNC_MAX_RETRIES=3
+
+# ------------------------------------------------------------
+# CORS
+# Optional: Comma-separated list of allowed origins (default: http://localhost:3000)
+# ------------------------------------------------------------
+CORS_ORIGINS=http://localhost:3000
+
 # ------------------------------------------------------------
 # Webhooks
 # Optional: Delivery retry configuration
@@ -47,9 +138,85 @@ WEBHOOK_MAX_RETRIES=5
 WEBHOOK_RETRY_BACKOFF_MS=1000
 WEBHOOK_TIMEOUT_MS=10000
 WEBHOOK_MAX_CONSECUTIVE_FAILURES=10
+WEBHOOK_QUEUE_INTERVAL_MS=30000
+
+# Secret for verifying incoming webhooks (HMAC-SHA256 signature verification)
+WEBHOOK_INBOUND_SECRET=your-inbound-webhook-secret
+
+# ------------------------------------------------------------
+# Recovery
+# Optional: Time-to-live for recovery requests before they are expired
+# Default: 604800000 (7 days)
+# ------------------------------------------------------------
+RECOVERY_REQUEST_TTL_MS=604800000
 
 # Auth Rate Limiting Configuration
 # Maximum number of authentication attempts per IP address per window
 AUTH_RATE_LIMIT_MAX=10
 # Time window in milliseconds for auth rate limiting (default: 60 seconds)
 AUTH_RATE_LIMIT_WINDOW_MS=60000
+
+# ------------------------------------------------------------
+# OpenTelemetry / Tracing
+# Optional: Set OTEL_ENABLED=true to activate distributed tracing.
+# When omitted or set to any other value, tracing is a no-op.
+# ------------------------------------------------------------
+OTEL_ENABLED=false
+# OTLP HTTP endpoint for the trace exporter (Jaeger, Tempo, Honeycomb, etc.)
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces
+# Service name reported in spans
+OTEL_SERVICE_NAME=mux-backend
+# Service version reported in spans
+OTEL_SERVICE_VERSION=1.0.0
+# JWT Verification (Identity Provider Configuration)
+# CRITICAL: POST /auth/authenticate now requires a signed JWT token.
+# Identity (authId, authProvider) is extracted ONLY from verified JWT claims,
+# never from client-supplied request body fields.
+# ------------------------------------------------------------
+
+# Identity provider to verify tokens against (CLERK or BETTER_AUTH)
+# Required for production deployment. If not set, JWT verification will fail
+# in production (fail-closed behavior).
+AUTH_IDENTITY_PROVIDER=CLERK
+
+# CLERK configuration: Public key for verifying Clerk JWTs
+# Obtain from Clerk dashboard (Settings > API Keys > Verification keys)
+# Required only if AUTH_IDENTITY_PROVIDER=CLERK
+CLERK_JWT_PUBLIC_KEY=
+
+# BETTER_AUTH configuration: JWKS URL for verifying Better Auth tokens
+# The application will fetch and cache the JWKS for signature verification
+# Required only if AUTH_IDENTITY_PROVIDER=BETTER_AUTH
+BETTER_AUTH_JWKS_URL=
+
+# Dev/test mode: Skip JWT verification for local development without live provider credentials
+# MUST be unset or false in production. If enabled in production, POST /auth/authenticate
+# will require tokens in format: dev-<provider>-<userid> (e.g., dev-clerk-user123)
+AUTH_SKIP_JWT_VERIFICATION=
+
+# ------------------------------------------------------------
+# OpenTelemetry / Tracing (optional)
+# Set OTEL_ENABLED=true to enable distributed tracing.
+# When enabled, OTEL_EXPORTER_OTLP_ENDPOINT is required and must be a valid
+# http/https URL; the application will fail to start if it is missing or
+# malformed to prevent silent trace loss.
+# ------------------------------------------------------------
+
+# Enable OpenTelemetry tracing (default: false)
+OTEL_ENABLED=false
+
+# OTLP collector endpoint — required when OTEL_ENABLED=true
+# Example: http://localhost:4318 (Jaeger / any OTLP-compatible backend)
+OTEL_EXPORTER_OTLP_ENDPOINT=
+
+# Wire protocol for OTLP export: http/protobuf (default) or grpc
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+
+# Logical service name that appears in traces (default: mux-backend)
+OTEL_SERVICE_NAME=mux-backend
+
+# Optional additional OTEL standard variables (not validated at startup):
+# OTEL_SERVICE_VERSION=
+# OTEL_SERVICE_NAMESPACE=
+# OTEL_TRACES_SAMPLER=always_on
+# OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production

.github/workflows/ci.yml

@@ -0,0 +1,155 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - staging
+  pull_request:
+    branches:
+      - main
+      - staging
+
+jobs:
+  test:
+    name: Build and test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: latest
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run ESLint
+        run: pnpm lint
+
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: latest
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Generate Prisma client
+        run: pnpm prisma:generate
+
+      - name: Run unit tests
+        run: pnpm test
+        env:
+          NODE_ENV: test
+          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/mux_test
+          WALLET_ENCRYPTION_KEY: ci-test-encryption-key-min-32-chars-long!!
+
+  e2e-tests:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: mux_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      NODE_ENV: test
+      DATABASE_URL: postgresql://postgres:postgres@localhost:5432/mux_test
+      WALLET_ENCRYPTION_KEY: ci-test-encryption-key-min-32-chars-long!!
+      STELLAR_HORIZON_URL: https://horizon-testnet.stellar.org
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: latest
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Generate Prisma client
+        run: pnpm prisma:generate
+
+      - name: Run database migrations
+        run: pnpm prisma:migrate:prod
+
+      - name: Run e2e tests
+        run: pnpm test:e2e
+      - name: Check Prisma migration naming
+        run: pnpm run prisma:check-migrations
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Generate OpenAPI spec
+        run: pnpm run openapi:generate
+        env:
+          DATABASE_URL: postgresql://stub:stub@localhost:5432/stub
+          WALLET_ENCRYPTION_KEY: ${{ secrets.WALLET_ENCRYPTION_KEY || '0000000000000000000000000000000000000000000000000000000000000000' }}
+          STELLAR_HORIZON_URL: https://horizon-testnet.stellar.org
+          STELLAR_NETWORK: TESTNET
+          STELLAR_HORIZON_TESTNET_URL: https://horizon-testnet.stellar.org
+          STELLAR_HORIZON_MAINNET_URL: https://horizon.stellar.org
+          STELLAR_HORIZON_MAX_RETRIES: 3
+          STELLAR_HORIZON_RETRY_BACKOFF_MS: 500
+          STELLAR_HORIZON_RETRY_JITTER_MS: 250
+          BALANCE_STALE_THRESHOLD_MS: 300000
+          WEBHOOK_MAX_RETRIES: 5
+          WEBHOOK_RETRY_BACKOFF_MS: 1000
+          WEBHOOK_TIMEOUT_MS: 10000
+          WEBHOOK_MAX_CONSECUTIVE_FAILURES: 10
+          AUTH_RATE_LIMIT_MAX: 10
+          AUTH_RATE_LIMIT_WINDOW_MS: 60000
+
+      - name: Lint OpenAPI spec
+        run: pnpm run openapi:lint
+
+      - name: Test
+        run: pnpm test
+
+      - name: Test scripts
+        run: pnpm run test:scripts