feat(edge): community IP blocklist (Spamhaus DROP) at the gateway

Refuse a client whose IP is in a curated CIDR feed with 403 in the same
abuseGuard, before the fail2ban ban. Prod-only (keys by real client IP), off by
default.

- ratelimit.Blocklist: a sorted-range IPv4 matcher (binary search) with an
  allowlist checked first; ParseDROP reads the feed; ApplyRefresh keeps the
  last-good feed on a transient fetch failure and drops it fail-open once stale
  (better to under-block than block a legitimate client on a frozen feed). A
  separate static CIDR set, not the per-IP fail2ban store.
- gateway: a refresher goroutine re-fetches every few hours (bounded fetch + size
  cap); config GATEWAY_BLOCKLIST_{ENABLED,URL,ALLOW,REFRESH,MAX_STALENESS}.
  IPv6 is not matched (a v6 client is still covered by fail2ban / the honeypot).
- observability: gateway_blocklist_blocked_total + entries/age gauges; a Grafana
  alert warns before the feed is dropped; service-overview panels.
- deploy: compose env + write-prod-env.sh + prod-deploy/rollback wiring (opt-in
  via PROD_ vars).
- docs (ARCHITECTURE, deploy/README); unit tests (match, allowlist, IPv6 skip,
  parser, fault-tolerance) + a 403 abuse-guard integration test.

deploy/README.md

@@ -115,6 +115,9 @@ without it Docker's resolver handles `otelcol`, `gateway` and `api.telegram.org`
 | `GATEWAY_VK_APP_SECRET` | secret (shared) | _(empty)_ | The VK Mini App's protected key (`client_secret`): the gateway verifies the launch-parameter signature in-process under it (offline HMAC, no VK API call). Empty disables the VK auth path (`auth.vk`). One VK Mini App for all contours. |
 | `GATEWAY_VK_ID_CLIENT_SECRET` | secret (shared) | _(empty)_ | The VK ID "Web" app's protected key (`client_secret`) for the gateway's server-side confidential code exchange. A SEPARATE VK app from `GATEWAY_VK_APP_SECRET` (the Mini App). One VK ID "Web" app for all contours. |
 | `GATEWAY_HONEYTOKEN` | secret | _(empty)_ | Planted honeytoken bearer value: presenting it earns a 24h IP ban + a high-severity alarm where the IP ban is on (prod), or logs + a `gateway_abuse_banned_total{reason="honeytoken"}` metric (test, ban off). Plant the value somewhere an attacker would find it; empty disables the trap. Per-contour `TEST_`/`PROD_GATEWAY_HONEYTOKEN`. |
+| `GATEWAY_BLOCKLIST_ENABLED` | variable | `false` | Enable the community IP blocklist at the edge (prod-only, same real-client-IP reason as the ban). Requires `GATEWAY_BLOCKLIST_URL`. Opt-in via `PROD_GATEWAY_BLOCKLIST_ENABLED` after verifying the feed. |
+| `GATEWAY_BLOCKLIST_URL` | variable | _(empty)_ | The curated CIDR feed to fetch (Spamhaus DROP). Required when enabled; refreshed every few hours and dropped fail-open once stale (48h). `PROD_GATEWAY_BLOCKLIST_URL`. |
+| `GATEWAY_BLOCKLIST_ALLOW` | variable | _(empty)_ | Comma-separated never-block set (CIDRs / bare IPs — own infra, monitoring) the feed can never block. `PROD_GATEWAY_BLOCKLIST_ALLOW`. |
 | `VITE_GATEWAY_URL` | variable | _(empty)_ | UI build-arg: gateway origin; empty = same-origin (the usual single-origin deploy). |
 | `SMTP_RELAY_HOST` | variable (shared) | _(empty)_ | Selectel SMTP relay host for confirm-code email. Empty leaves the backend on the log mailer (email disabled) — the contour still boots. One relay for every contour (limit 100 msgs / 5 min). |
 | `SMTP_RELAY_PORT` | variable (shared) | `465` | Relay port. No client certificate is needed (the server cert is validated against the system roots). |

deploy/docker-compose.yml

@@ -254,6 +254,12 @@ services:
       # secret; empty (unset secret) leaves the trap off.
       GATEWAY_ABUSE_BAN_ENABLED: ${GATEWAY_ABUSE_BAN_ENABLED:-false}
       GATEWAY_HONEYTOKEN: ${GATEWAY_HONEYTOKEN:-}
+      # Community IP blocklist (Spamhaus DROP): prod-only, off unless the real client IP is visible
+      # (the shared-NAT test contour would self-block). Enabled + fed the feed URL + allowlist by the
+      # prod deploy (write-prod-env.sh); the refresh/staleness windows use the built-in defaults.
+      GATEWAY_BLOCKLIST_ENABLED: ${GATEWAY_BLOCKLIST_ENABLED:-false}
+      GATEWAY_BLOCKLIST_URL: ${GATEWAY_BLOCKLIST_URL:-}
+      GATEWAY_BLOCKLIST_ALLOW: ${GATEWAY_BLOCKLIST_ALLOW:-}
       GATEWAY_LOG_LEVEL: ${LOG_LEVEL:-info}
       GATEWAY_SERVICE_NAME: scrabble-gateway
       GATEWAY_OTEL_TRACES_EXPORTER: otlp

deploy/grafana/dashboards/service-overview.json

@@ -53,6 +53,31 @@
       "fieldConfig": { "defaults": { "unit": "bytes" }, "overrides": [] },
       "datasource": { "type": "prometheus", "uid": "prometheus" },
       "targets": [{ "refId": "A", "expr": "sum(go_memory_used) by (service_name)", "legendFormat": "{{service_name}}" }]
+    },
+    {
+      "type": "stat",
+      "title": "Blocklist entries",
+      "description": "CIDR ranges in the active community IP blocklist feed (0 when disabled or not yet fetched).",
+      "gridPos": { "h": 5, "w": 6, "x": 0, "y": 13 },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "max(gateway_blocklist_entries)" }]
+    },
+    {
+      "type": "stat",
+      "title": "Blocklist feed age",
+      "description": "Seconds since the community IP blocklist feed was last successfully fetched. Grows if the fetch is failing; the feed is dropped fail-open once stale.",
+      "gridPos": { "h": 5, "w": 6, "x": 6, "y": 13 },
+      "fieldConfig": { "defaults": { "unit": "s" }, "overrides": [] },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "max(gateway_blocklist_age_seconds)" }]
+    },
+    {
+      "type": "timeseries",
+      "title": "Blocklist blocks/s",
+      "description": "Requests refused at the edge by the community IP blocklist (gateway_blocklist_blocked_total).",
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 13 },
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "targets": [{ "refId": "A", "expr": "sum(rate(gateway_blocklist_blocked_total[5m]))" }]
     }
   ]
 }

deploy/grafana/provisioning/alerting/rules.yaml

@@ -108,6 +108,32 @@ groups:
         labels: { severity: critical }
         annotations: { summary: 'Edge TLS cert has under 20 days left — Caddy ACME renewal may have failed.' }
 
+      # The community IP blocklist feed has not refreshed in over a day (the gateway re-fetches every
+      # few hours). Absent/NaN-safe: the age gauge appears only once a feed has loaded, so a disabled
+      # or never-fetched blocklist stays quiet. The feed itself is dropped (fail-open) at its
+      # max-staleness window; this warns well before that so the operator can fix the fetch.
+      - uid: blocklist_stale
+        title: IP blocklist feed not refreshing
+        condition: C
+        for: 15m
+        noDataState: OK
+        execErrState: OK
+        data:
+          - refId: A
+            relativeTimeRange: { from: 300, to: 0 }
+            datasourceUid: prometheus
+            model: { refId: A, expr: gateway_blocklist_age_seconds, instant: true }
+          - refId: C
+            datasourceUid: __expr__
+            model:
+              refId: C
+              type: threshold
+              expression: A
+              conditions:
+                - evaluator: { type: gt, params: [86400] }
+        labels: { severity: warning }
+        annotations: { summary: 'The community IP blocklist feed has not refreshed in over 24h — the fetch is failing; it will be dropped (fail-open) once stale. Check the gateway blocklist refresher logs and the feed URL.' }
+
   - orgId: 1
     name: scrabble-host
     folder: Alerts

deploy/write-prod-env.sh

@@ -77,6 +77,11 @@ export GF_SMTP_ENABLED='$GF_SMTP_ENABLED'
 export PUBLIC_BASE_URL='$PUBLIC_BASE_URL'
 export GATEWAY_HONEYTOKEN='$GATEWAY_HONEYTOKEN'
 export GATEWAY_ABUSE_BAN_ENABLED='true'
+# Community IP blocklist (Spamhaus DROP): opt-in — the operator enables it and sets the feed URL +
+# allowlist via PROD_GATEWAY_BLOCKLIST_* vars once the feed is verified. Unset ⇒ off (safe).
+export GATEWAY_BLOCKLIST_ENABLED='${GATEWAY_BLOCKLIST_ENABLED:-false}'
+export GATEWAY_BLOCKLIST_URL='$GATEWAY_BLOCKLIST_URL'
+export GATEWAY_BLOCKLIST_ALLOW='$GATEWAY_BLOCKLIST_ALLOW'
 # Continuous WAL archiving (pgBackRest -> S3) for point-in-time recovery. The artifact
 # ships disarmed: PGBACKREST_ARCHIVE_MODE defaults off, so archiving stays inert until the
 # operator sets the S3 repository values + secrets, creates the stanza and flips the switch