fix: correct dependency/build ordering in deploy-staging.sh (#697)

.dockerignore

@@ -0,0 +1,38 @@
+# Dependencies — reinstalled inside the image
+node_modules/
+
+# TypeScript source — only dist/ is needed in the runtime stage
+src/
+
+# Test files
+tests/
+__mocks__/
+
+# Build artifacts already copied by the builder stage
+dist/
+
+# Environment secrets — never bake these into the image
+.env
+.env.*
+!.env.example
+
+# Git and CI
+.git/
+.github/
+.claude/
+
+# Dev tooling
+.eslintrc.cjs
+tsconfig.json
+
+# Docs and scripts (not needed at runtime)
+docs/
+scripts/
+contracts/
+db/
+*.md
+
+# OS / editor noise
+.DS_Store
+Thumbs.db
+*.log

.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{sql,yml,yaml,json}]
+indent_style = space
+indent_size = 2

.env.example

@@ -1,62 +1,287 @@
+# ============================================================
+# ScoutOff Backend — Environment Variables
+# Copy this file to .env and fill in real values for your setup.
+# Never commit .env — only .env.example should be tracked in git.
+# ============================================================
+
+# ----------------------------------------
 # Stellar / Soroban
+# ----------------------------------------
+# CONTRACT_ID — Required. Deployed Soroban contract address.
 CONTRACT_ID=
+
+# HORIZON_URL — Required. Stellar Horizon RPC endpoint.
 HORIZON_URL=https://horizon-testnet.stellar.org
+
+# SOROBAN_RPC_URL — Required. Soroban RPC endpoint for contract calls.
 SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
+
+# NETWORK — Required. Which Stellar network to target: "testnet" or "mainnet".
 NETWORK=testnet
-NETWORK_PASSPHRASE=Test SDF Network ; September 2015
 
-# Runtime
-NODE_ENV=development
-PORT=4000
+# NETWORK_PASSPHRASE — Required. Network passphrase matching NETWORK above.
+# Testnet: Test SDF Network ; September 2015
+# Mainnet: Public Global Stellar Network ; September 2015
+NETWORK_PASSPHRASE=Test SDF Network ; September 2015
 
+# ----------------------------------------
 # Auth
-JWT_SECRET=change-me-to-a-long-random-secret
+# ----------------------------------------
+# JWT_SECRET — Required. Minimum 32 characters. Rotate immediately on suspected compromise.
+# Generate locally: `openssl rand -hex 32`
+JWT_SECRET=change-me-to-a-long-random-secret-min-32-chars
+
+# JWT_SECRET_PREVIOUS — Optional. Used only during key rotation.
+# Rotation procedure:
+#   1. Copy JWT_SECRET value into JWT_SECRET_PREVIOUS
+#   2. Set JWT_SECRET to a new secret (openssl rand -hex 32)
+#   3. Deploy — old tokens still work via JWT_SECRET_PREVIOUS
+#   4. After all sessions expire, remove JWT_SECRET_PREVIOUS and redeploy
+JWT_SECRET_PREVIOUS=
+
+# ADMIN_WALLET — Optional. Single admin Stellar address, for backward compatibility.
+# Prefer ADMIN_WALLETS below.
 ADMIN_WALLET=
 
+# ADMIN_WALLETS — Optional. Comma-separated admin Stellar addresses.
+# Example: GABC123...,GDEF456...
+ADMIN_WALLETS=
+
+# ADMIN_THRESHOLD — Optional. Admin signatures required for high-value operations. Default: 1.
+ADMIN_THRESHOLD=1
+
+# ----------------------------------------
 # IPFS / Pinata
+# ----------------------------------------
+# PINATA_API_KEY — Required. Pinata IPFS upload credential.
 PINATA_API_KEY=
+
+# PINATA_SECRET — Required. Pinata IPFS upload credential — keep private, never commit.
 PINATA_SECRET=
+
+# PINATA_GATEWAY — Optional. IPFS gateway used to resolve pinned content.
 PINATA_GATEWAY=https://gateway.pinata.cloud
 
+# IPFS_GATEWAYS — Optional. Comma-separated fallback IPFS gateways
+# (defaults to Pinata/Cloudflare/ipfs.io when unset).
+IPFS_GATEWAYS=
+
+# PIN_JSON_CACHE_TTL_MS — Optional. TTL for IPFS pin dedup cache, in ms. Default: 300000.
+PIN_JSON_CACHE_TTL_MS=300000
+
+# ----------------------------------------
+# Runtime
+# ----------------------------------------
+# NODE_ENV — Required. "development", "production", or "test".
+NODE_ENV=development
+
+# PORT — Optional. API port. Default: 4000.
+PORT=4000
+
+# ----------------------------------------
 # Platform
+# ----------------------------------------
+# PLATFORM_FEE_BPS — Optional. Platform fee in basis points (1 bps = 0.01%). Default: 500 (5%).
 PLATFORM_FEE_BPS=500
+
+# PLATFORM_SECRET_KEY — Required in staging/production. Platform signing keypair secret.
+# Generate with: stellar keys generate --network testnet
+PLATFORM_SECRET_KEY=
+
+# PLATFORM_SECRET — Legacy/deprecated, used by src/utils/contract.ts. Prefer PLATFORM_SECRET_KEY.
+PLATFORM_SECRET=
+
+# ----------------------------------------
+# Logging
+# ----------------------------------------
+# LOG_LEVEL — Optional. debug | info | warn | error. Default: info.
 LOG_LEVEL=info
 
+# LOG_SKIP_PATHS — Optional. Comma-separated paths requestLogger never logs
+# (default: health + metrics probes).
+LOG_SKIP_PATHS=/health,/health/liveness,/health/readiness,/ready,/metrics
+
+# LOG_SAMPLE_RATE — Optional. Float 0–1 sample rate for non-skipped paths. Default: 1 (log all).
+LOG_SAMPLE_RATE=1
+
+# ----------------------------------------
 # Database
+# ----------------------------------------
+# DB_PATH — Optional. SQLite file path. Default: scout-off.db.
 DB_PATH=scout-off.db
 
+# SLOW_QUERY_THRESHOLD_MS — Optional. Log queries slower than this, in ms. Default: 50.
+SLOW_QUERY_THRESHOLD_MS=50
+
+# ----------------------------------------
+# Security headers (optional overrides)
+# ----------------------------------------
+SECURITY_HSTS=max-age=31536000; includeSubDomains
+SECURITY_X_CONTENT_TYPE_OPTIONS=nosniff
+SECURITY_X_FRAME_OPTIONS=DENY
+SECURITY_REFERRER_POLICY=no-referrer
+SECURITY_CSP=default-src 'none'
+
+# ----------------------------------------
 # Feature flags
+# ----------------------------------------
+# STELLAR_HEALTH_CHECK — Optional. Set false in staging to skip the Stellar RPC health
+# check on startup. Default: true.
+# ⚠️ VERIFY: DEPLOYMENT.md currently calls this STELLAR_HEALTH_CHECK_ENABLED — confirm
+# the actual variable name against the code before merging, then fix whichever file is wrong.
 STELLAR_HEALTH_CHECK=true
+
+# JSON_PAYLOAD_LIMIT — Optional. Max size of JSON request bodies. Default: 1mb.
 JSON_PAYLOAD_LIMIT=1mb
 
+# COMPRESSION_THRESHOLD — Optional. Response compression threshold, in bytes. Default: 1024.
+COMPRESSION_THRESHOLD=1024
+
+# ----------------------------------------
+# Caching
+# ----------------------------------------
+# PLAYER_CACHE_TTL_MS — Optional. Cache TTL for player lookups, in ms. Default: 60000.
+PLAYER_CACHE_TTL_MS=60000
+
+# PLAYER_IMPORT_MAX_BATCH — Optional. Max rows accepted per bulk player
+# import request (POST /api/admin/players/import). Default: 500.
+PLAYER_IMPORT_MAX_BATCH=500
+
+# ----------------------------------------
+# CORS
+# ----------------------------------------
+# CORS_ALLOWED_ORIGINS — Comma-separated list of allowed origins.
+# Recommended values per environment:
+#   development: * (or http://localhost:3000,http://localhost:4000)
+#   staging:     https://staging.scoutoff.io
+#   production:  https://app.scoutoff.io,https://scoutoff.io
+# Falls back to environment-specific defaults if unset:
+#   development/test: *
+#   staging:          https://staging.scoutoff.io
+#   production:       https://app.scoutoff.io,https://scoutoff.io
+CORS_ALLOWED_ORIGINS=
+
+# ALLOWED_ORIGINS — Legacy alias for CORS_ALLOWED_ORIGINS.
+ALLOWED_ORIGINS=
+
+# ----------------------------------------
 # Rate limiting
+# ----------------------------------------
+# RATE_LIMIT_ENABLED — Optional. Default: true.
 RATE_LIMIT_ENABLED=true
+
+# RATE_LIMIT_WINDOW_MS / RATE_LIMIT_MAX — Optional. Defaults: 60000 / 60.
 RATE_LIMIT_WINDOW_MS=60000
 RATE_LIMIT_MAX=60
 
+# AUTH_RATE_LIMIT_WINDOW_MS / AUTH_RATE_LIMIT_MAX — Optional. Stricter limits on
+# /auth/challenge and /auth/token for brute-force protection. Defaults: 60000 / 5.
+AUTH_RATE_LIMIT_WINDOW_MS=60000
+AUTH_RATE_LIMIT_MAX=5
+
+# ----------------------------------------
 # Webhooks
+# ----------------------------------------
+# WEBHOOK_ENABLED — Optional. Default: false.
 WEBHOOK_ENABLED=false
+
+# WEBHOOK_URL — Required if WEBHOOK_ENABLED=true. Destination for webhook events.
+# Example: https://example.com/webhooks/scout-off
 WEBHOOK_URL=
+WEBHOOK_SECRET=
 
-# Security headers
-SECURITY_HSTS=max-age=31536000; includeSubDomains
-SECURITY_X_CONTENT_TYPE_OPTIONS=nosniff
-SECURITY_X_FRAME_OPTIONS=DENY
-SECURITY_REFERRER_POLICY=no-referrer
+# WEBHOOK_SECRET — Optional. HMAC secret used to sign the X-Webhook-Signature
+# header for the legacy single-subscriber webhook (WEBHOOK_URL).
+WEBHOOK_SECRET=
 
+# ----------------------------------------
 # API versioning
+# ----------------------------------------
+# API_PREFIX — Optional. Default: /api.
 API_PREFIX=/api
+
+# API_V — Optional. Default: v1.
 API_V=v1
 
+# ----------------------------------------
 # Metrics
+# ----------------------------------------
+# METRICS_ENABLED — Optional. Expose a /metrics endpoint. Default: false.
 METRICS_ENABLED=false
 
+# ----------------------------------------
 # Milestone rate limiting
+# ----------------------------------------
+# MILESTONE_RATE_WINDOW_MS / MILESTONE_RATE_MAX — Optional. Defaults: 60000 / 10.
 MILESTONE_RATE_WINDOW_MS=60000
 MILESTONE_RATE_MAX=10
 
-# Redis (optional — used for distributed caching)
+# ----------------------------------------
+# Redis (optional — distributed caching)
+# ----------------------------------------
+# REDIS_URL — Optional. Falls back to in-memory caching when unset.
+# Format: redis://<user>:<password>@<host>:<port>
 REDIS_URL=
 
+# ----------------------------------------
 # Proxy
-TRUSTED_PROXY_COUNT=0
+# ----------------------------------------
+# TRUSTED_PROXY_COUNT — Optional. Number of trusted reverse-proxy hops in front of
+# this server, used to resolve real client IPs.
+# ⚠️ VERIFY: DEPLOYMENT.md says default 1; this file currently ships 0 — confirm the
+# real default against the code before merging.
+TRUSTED_PROXY_COUNT=0
+
+# ----------------------------------------
+# Indexer
+# ----------------------------------------
+# INDEXER_BACKFILL_FROM_LEDGER — Optional. Replay indexing from this ledger if earlier
+# than the stored last_ledger. Leave unset to disable.
+INDEXER_BACKFILL_FROM_LEDGER=
+
+# INDEXER_LAG_WARN_THRESHOLD — Optional. Ledgers behind tip before a lag warning logs.
+# Default: 100.
+INDEXER_LAG_WARN_THRESHOLD=100
+
+# ----------------------------------------
+# Subscriptions
+# ----------------------------------------
+# SUBSCRIPTION_GRACE_PERIOD_HOURS — Optional. Grace period after expiry during which
+# access is still granted. Default: 24.
+SUBSCRIPTION_GRACE_PERIOD_HOURS=24
+
+# ----------------------------------------
+# Requests
+# ----------------------------------------
+# REQUEST_TIMEOUT_MS — Optional. Global request timeout before responding 503.
+# Default: 30000.
+REQUEST_TIMEOUT_MS=30000
+
+# ----------------------------------------
+# Admin
+# ----------------------------------------
+# ADMIN_IP_ALLOWLIST — Optional. Comma-separated IPs/CIDRs allowed on admin routes.
+# Leave unset to allow all.
+ADMIN_IP_ALLOWLIST=
+# TTL for admin actions (milliseconds). Controls how long admin actions (like multisig approvals)
+# remain valid before expiring. Default: 1 hour.
+ADMIN_ACTION_TTL_MS=3600000
+
+# ADMIN_ACTION_TTL_MS — Optional. Time-to-live for pending admin multi-sig actions, in ms.
+# Default: 3600000 (1 hour).
+ADMIN_ACTION_TTL_MS=3600000
+
+# ----------------------------------------
+# Tracing (OpenTelemetry)
+# ----------------------------------------
+# OTEL_EXPORTER_OTLP_ENDPOINT — Optional. Leave unset to disable tracing export.
+OTEL_EXPORTER_OTLP_ENDPOINT=
+
+# OTEL_SERVICE_NAME — Optional. Service name reported to the tracing backend.
+OTEL_SERVICE_NAME=scout-off-backend
+
+# ----------------------------------------
+# System / Build
+# ----------------------------------------
+# GIT_COMMIT — Optional. Overrides the build commit hash returned by the version endpoint.
+GIT_COMMIT=

.eslintrc.cjs

@@ -14,6 +14,22 @@ module.exports = {
     es2021: true
   },
   rules: {
-    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }]
-  }
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+    'no-console': 'error'
+  },
+  overrides: [
+    {
+      files: ['src/utils/logger.ts'],
+      rules: { 'no-console': 'off' }
+    }
+    ,
+    {
+      // Tests sometimes import helpers or types that are intentionally unused
+      // during setup; treat unused vars as warnings in tests to avoid CI failures
+      files: ['tests/**/*.ts'],
+      rules: {
+        '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }]
+      }
+    }
+  ]
 };