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.

gateway/internal/config/config.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"os"
 	"strconv"
+	"strings"
 	"time"
 
 	pkgtel "scrabble/pkg/telemetry"
@@ -57,6 +58,8 @@ type Config struct {
 	RateLimit RateLimitConfig
 	// Abuse configures the temporary IP ban and the honeytoken (prod-only).
 	Abuse AbuseConfig
+	// Blocklist configures the community IP blocklist (Spamhaus DROP) enforced at the edge (prod-only).
+	Blocklist BlocklistConfig
 	// Telemetry configures the OpenTelemetry providers (shared bootstrap).
 	Telemetry pkgtel.Config
 }
@@ -166,6 +169,42 @@ func DefaultAbuse() AbuseConfig {
 	}
 }
 
+// BlocklistConfig configures the community IP blocklist (a curated CIDR feed such as Spamhaus DROP)
+// enforced at the edge alongside the fail2ban ban. Disabled by default and prod-only, for the same
+// reason as the ban: it is only safe where the real client IP is visible (not behind the shared-NAT
+// test contour). Only IPv4 is matched.
+type BlocklistConfig struct {
+	// Enabled turns edge blocklisting on. Off by default (prod-only).
+	Enabled bool
+	// URL is the CIDR feed to fetch (e.g. the Spamhaus DROP list). Required when Enabled; the
+	// operator sets it explicitly so no feed URL is assumed.
+	URL string
+	// Refresh is how often the feed is re-fetched.
+	Refresh time.Duration
+	// MaxStaleness is how long a stale feed (no successful refresh) is tolerated before it is dropped
+	// (fail-open — a legitimate client is never blocked on a frozen feed).
+	MaxStaleness time.Duration
+	// Allow is the never-block set: CIDRs or bare IPs (own infrastructure, monitoring, known-good) that
+	// the feed can never block. Parsed at startup.
+	Allow []string
+}
+
+// Blocklist defaults; the feed URL has no default (the operator sets it).
+const (
+	defaultBlocklistRefresh      = 6 * time.Hour
+	defaultBlocklistMaxStaleness = 48 * time.Hour
+)
+
+// DefaultBlocklist returns the built-in blocklist settings: disabled (prod-only), no feed URL, and
+// the agreed refresh / staleness windows.
+func DefaultBlocklist() BlocklistConfig {
+	return BlocklistConfig{
+		Enabled:      false,
+		Refresh:      defaultBlocklistRefresh,
+		MaxStaleness: defaultBlocklistMaxStaleness,
+	}
+}
+
 // VKIDConfig holds the VK ID web-login credentials for the confidential
 // authorization-code exchange. AppID is the VK "Web" app's client id; ClientSecret is
 // its protected key; RedirectURI must exactly match the trusted redirect URL registered
@@ -203,6 +242,7 @@ func Load() (Config, error) {
 		SessionCacheMax: defaultSessionCacheMax,
 		RateLimit:       DefaultRateLimit(),
 		Abuse:           DefaultAbuse(),
+		Blocklist:       DefaultBlocklist(),
 		BotLink: BotLinkConfig{
 			Addr:      os.Getenv("GATEWAY_BOTLINK_ADDR"),
 			RelayAddr: os.Getenv("GATEWAY_BOTLINK_RELAY_ADDR"),
@@ -244,6 +284,17 @@ func Load() (Config, error) {
 	if c.Abuse.BanDuration, err = envDuration("GATEWAY_ABUSE_BAN_DURATION", c.Abuse.BanDuration); err != nil {
 		return Config{}, err
 	}
+	if c.Blocklist.Enabled, err = envBool("GATEWAY_BLOCKLIST_ENABLED", c.Blocklist.Enabled); err != nil {
+		return Config{}, err
+	}
+	c.Blocklist.URL = os.Getenv("GATEWAY_BLOCKLIST_URL")
+	if c.Blocklist.Refresh, err = envDuration("GATEWAY_BLOCKLIST_REFRESH", c.Blocklist.Refresh); err != nil {
+		return Config{}, err
+	}
+	if c.Blocklist.MaxStaleness, err = envDuration("GATEWAY_BLOCKLIST_MAX_STALENESS", c.Blocklist.MaxStaleness); err != nil {
+		return Config{}, err
+	}
+	c.Blocklist.Allow = splitList(os.Getenv("GATEWAY_BLOCKLIST_ALLOW"))
 	if c.BotLink.SendTimeout, err = envDuration("GATEWAY_BOTLINK_SEND_TIMEOUT", defaultBotLinkSendTimeout); err != nil {
 		return Config{}, err
 	}
@@ -284,6 +335,9 @@ func (c Config) validate() error {
 	if c.Abuse.BanEnabled && (c.Abuse.BanThreshold <= 0 || c.Abuse.BanWindow <= 0 || c.Abuse.BanDuration <= 0) {
 		return fmt.Errorf("config: GATEWAY_ABUSE_BAN_THRESHOLD/_WINDOW/_DURATION must be positive when GATEWAY_ABUSE_BAN_ENABLED")
 	}
+	if c.Blocklist.Enabled && (c.Blocklist.URL == "" || c.Blocklist.Refresh <= 0 || c.Blocklist.MaxStaleness <= 0) {
+		return fmt.Errorf("config: GATEWAY_BLOCKLIST_URL must be set and _REFRESH/_MAX_STALENESS positive when GATEWAY_BLOCKLIST_ENABLED")
+	}
 	if c.BotLink.Addr != "" {
 		if c.BotLink.CertFile == "" || c.BotLink.KeyFile == "" || c.BotLink.CAFile == "" {
 			return fmt.Errorf("config: GATEWAY_BOTLINK_ADDR requires GATEWAY_BOTLINK_TLS_CERT, _KEY and _CA")
@@ -304,6 +358,21 @@ func envOr(key, fallback string) string {
 	return fallback
 }
 
+// splitList splits a comma-separated environment value into trimmed, non-empty items.
+func splitList(v string) []string {
+	if v == "" {
+		return nil
+	}
+	parts := strings.Split(v, ",")
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		if p = strings.TrimSpace(p); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
 // envBool parses the environment variable named key as a bool, returning fallback
 // when it is unset and an error when it is set but malformed.
 func envBool(key string, fallback bool) (bool, error) {