chore: update deps, CI pipeline, docs, and project configuration

Author: intellect4all

.env.example

@@ -1,9 +1,21 @@
 # Settla local development environment
 # Copy to .env: cp .env.example .env
+#
+# PRODUCTION SECURITY NOTICE:
+#   Variables marked with "# CHANGE IN PRODUCTION" MUST be replaced with strong
+#   random values before any production or staging deployment.
+#   In Kubernetes, secrets are injected via External Secrets Operator (ESO) from
+#   AWS Secrets Manager — see deploy/k8s/base/secrets/ for the ExternalSecret
+#   definitions.  Never commit real secrets to version control.
 
 # ── PostgreSQL ───────────────────────────────────────────────────
+# CHANGE IN PRODUCTION — set via settla/production/db in AWS Secrets Manager.
+# K8s: injected from settla-db-credentials ExternalSecret (secretKeyRef: app-password).
 POSTGRES_USER=settla
-POSTGRES_PASSWORD=settla
+POSTGRES_PASSWORD=settla  # CHANGE IN PRODUCTION
+# RLS application role password (used by init-rls-role.sh in Docker).
+# CHANGE IN PRODUCTION — set via settla/production/db in AWS Secrets Manager.
+SETTLA_APP_DB_PASSWORD=settla_app  # CHANGE IN PRODUCTION
 
 # DB URLs point to PgBouncer (pooled), NOT raw Postgres.
 # Raw Postgres ports (5433/5434/5435) are for migrations and admin only.
@@ -16,18 +28,29 @@ SETTLA_LEDGER_DB_MIGRATE_URL=postgres://settla:settla@localhost:5433/settla_ledg
 SETTLA_TRANSFER_DB_MIGRATE_URL=postgres://settla:settla@localhost:5434/settla_transfer?sslmode=disable
 SETTLA_TREASURY_DB_MIGRATE_URL=postgres://settla:settla@localhost:5435/settla_treasury?sslmode=disable
 
+# RLS-enforced DB URLs (settla_app role, subject to Row-Level Security).
+# Used by settla-server for tenant-scoped API operations. Optional — when unset,
+# all queries run as the owner role (settla) which bypasses RLS.
+# CHANGE IN PRODUCTION — set via settla/production/db in AWS Secrets Manager.
+SETTLA_TRANSFER_APP_DB_URL=postgres://settla_app:settla_app@localhost:6434/settla_transfer?sslmode=disable
+SETTLA_LEDGER_APP_DB_URL=postgres://settla_app:settla_app@localhost:6433/settla_ledger?sslmode=disable
+SETTLA_TREASURY_APP_DB_URL=postgres://settla_app:settla_app@localhost:6435/settla_treasury?sslmode=disable
+
 # ── TigerBeetle ─────────────────────────────────────────────────
 # Ledger write authority (1M+ TPS). Source of truth for balances.
 SETTLA_TIGERBEETLE_ADDRESSES=localhost:3001
 
 # ── Redis ────────────────────────────────────────────────────────
-SETTLA_REDIS_URL=redis://localhost:6379
+# CHANGE IN PRODUCTION — set via settla/production/app in AWS Secrets Manager.
+REDIS_PASSWORD=settla-dev  # CHANGE IN PRODUCTION
+SETTLA_REDIS_URL=redis://:settla-dev@localhost:6380
 
 # ── NATS ─────────────────────────────────────────────────────────
 SETTLA_NATS_URL=nats://localhost:4222
 
 # ── Settla Server (Go) ──────────────────────────────────────────
-SETTLA_SERVER_HTTP_PORT=8080
+# Tyk now owns external port 8080; settla-server HTTP exposed on 8081 for direct access
+SETTLA_SERVER_HTTP_PORT=8081
 SETTLA_SERVER_GRPC_PORT=9090
 SETTLA_PPROF_PORT=6060
 SETTLA_PPROF=true
@@ -37,13 +60,32 @@ SETTLA_PPROF=true
 SETTLA_TREASURY_FLUSH_INTERVAL_MS=100
 # Ledger: write-ahead batch window before flushing to TigerBeetle (ms)
 SETTLA_LEDGER_BATCH_WINDOW_MS=10
+# Ledger: maximum entries per write-ahead batch (increase for higher throughput)
+SETTLA_LEDGER_BATCH_MAX_SIZE=500
 
 # ── Settla Node (NATS Workers) ──────────────────────────────────
 # Total partitions for event stream (must match across all nodes)
 SETTLA_NODE_PARTITIONS=8
 # Which partition this instance handles (omit in dev = handle all)
 # SETTLA_NODE_PARTITION_ID=0
 
+# ── Outbox Relay Tuning ─────────────────────────────────────────
+# Batch size: entries fetched per poll cycle (higher = better throughput at peak)
+SETTLA_RELAY_BATCH_SIZE=200
+# Poll interval in milliseconds (lower = lower latency, higher CPU)
+SETTLA_RELAY_POLL_INTERVAL_MS=30
+
+# ── Worker Pool Sizes ───────────────────────────────────────────
+# Max concurrent handlers per worker type. Tuned for 5K TPS peak.
+# At 8 partitions, transfer workers handle ~625 events/sec per partition.
+SETTLA_WORKER_POOL_TRANSFER=8
+SETTLA_WORKER_POOL_PROVIDER=16
+SETTLA_WORKER_POOL_BLOCKCHAIN=16
+SETTLA_WORKER_POOL_LEDGER=8
+SETTLA_WORKER_POOL_TREASURY=8
+SETTLA_WORKER_POOL_WEBHOOK=32
+SETTLA_WORKER_POOL_INBOUND_WH=8
+
 # ── Settla Gateway (TypeScript) ─────────────────────────────────
 SETTLA_GATEWAY_PORT=3000
 # Number of persistent gRPC connections to settla-server
@@ -77,6 +119,78 @@ SETTLA_ETHEREUM_RPC_URL=https://rpc.sepolia.org
 SETTLA_BASE_RPC_URL=https://sepolia.base.org
 SETTLA_SOLANA_RPC_URL=https://api.devnet.solana.com
 
+# ── Ops Dashboard Auth ────────────────────────────────────────────
+# API key for the internal ops routes (/v1/ops/*). Must be set to a strong
+# random value in production. Requests without this key receive HTTP 403.
+# CHANGE IN PRODUCTION — generate: openssl rand -hex 32
+SETTLA_OPS_API_KEY=settla-ops-secret-change-me  # CHANGE IN PRODUCTION
+
+# ── Tyk API Gateway ─────────────────────────────────────────────
+# Tyk handles external traffic (auth, rate limiting, circuit breaking).
+# CHANGE IN PRODUCTION — set via settla/production/app → tyk-secret in AWS Secrets Manager.
+# K8s: injected from settla-app-secrets ExternalSecret (secretKeyRef: tyk-secret).
+# Generate: openssl rand -hex 32
+TYK_SECRET=settla-tyk-secret-change-me  # CHANGE IN PRODUCTION
+TYK_GATEWAY_PORT=8080
+
+# ── Dashboard ──────────────────────────────────────────────────────
+# API key for the ops dashboard. Must be set to a valid tenant API key.
+# In dev, use a seed tenant key. In production, use a dedicated admin key.
+NUXT_PUBLIC_DASHBOARD_API_KEY=
+
+# ── Webhook Secrets (required in production) ──────────────────────
+# HMAC-SHA256 secrets for outbound webhook signatures per seed tenant.
+# In dev, defaults are used. In production, these MUST be set.
+# CHANGE IN PRODUCTION — set via settla/production/webhooks in AWS Secrets Manager.
+# K8s: injected from settla-webhook-secrets ExternalSecret.
+# Generate: openssl rand -hex 32
+# LEMFI_WEBHOOK_SECRET=    # CHANGE IN PRODUCTION — min 32 chars random string
+# FINCRA_WEBHOOK_SECRET=   # CHANGE IN PRODUCTION — min 32 chars random string
+
+# ── Inbound Provider Webhook Signing Secrets ──────────────────────
+# HMAC-SHA256 secrets used to verify signatures on webhooks received FROM
+# payment providers. Pattern: PROVIDER_{SLUG_UPPER}_WEBHOOK_SECRET
+# The slug is the provider identifier in the URL path, with hyphens replaced
+# by underscores and uppercased.
+#
+# Examples:
+#   PROVIDER_YELLOW_CARD_WEBHOOK_SECRET=whsec_...   (slug: yellow-card)
+#   PROVIDER_KOTANI_PAY_WEBHOOK_SECRET=whsec_...    (slug: kotani-pay)
+#   PROVIDER_SETTLA_TESTNET_WEBHOOK_SECRET=whsec_... (slug: settla-testnet)
+#
+# Behaviour:
+#   - Secret configured + signature present   -> verified with HMAC-SHA256
+#   - Secret configured + signature missing   -> warning logged, request proceeds
+#   - Secret configured + signature invalid   -> 401 returned
+#   - No secret configured                    -> warning logged, request proceeds
+#
+# Optional: override the signature header name (defaults to x-webhook-signature):
+#   PROVIDER_YELLOW_CARD_SIGNATURE_HEADER=x-yc-signature
+
+# ── Observability Credentials ─────────────────────────────────────
+# Grafana admin password for the ops dashboard.
+# CHANGE IN PRODUCTION — set via settla/production/app → grafana-admin-password.
+# K8s: injected from settla-app-secrets ExternalSecret (secretKeyRef: grafana-admin-password).
+# Generate: openssl rand -hex 16
+GRAFANA_ADMIN_PASSWORD=settla-dev-local  # CHANGE IN PRODUCTION
+
+# Slack webhook URL for AlertManager notifications.
+# CHANGE IN PRODUCTION — set via settla/production/alertmanager → slack-webhook-url.
+# K8s: injected from alertmanager-secrets ExternalSecret.
+# Create at: https://api.slack.com/apps → Incoming Webhooks
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/placeholder  # CHANGE IN PRODUCTION
+
+# PagerDuty Events API v2 Integration Key for critical alerts.
+# CHANGE IN PRODUCTION — set via settla/production/alertmanager → pagerduty-service-key.
+# K8s: injected from alertmanager-secrets ExternalSecret.
+PAGERDUTY_SERVICE_KEY=placeholder  # CHANGE IN PRODUCTION (leave blank for non-production)
+
+# Remediation webhook auth token — used by the AlertManager remediation sidecar.
+# CHANGE IN PRODUCTION — set via settla/production/alertmanager → remediation-webhook-token.
+# K8s: injected from alertmanager-secrets ExternalSecret.
+# Generate: openssl rand -hex 32
+REMEDIATION_WEBHOOK_TOKEN=dev-token  # CHANGE IN PRODUCTION
+
 # ── General ──────────────────────────────────────────────────────
 SETTLA_LOG_LEVEL=debug
 SETTLA_ENV=development