feat(security): origin-side rate limiter — PR1 (shared-store limiter + tiering, flag-off)

[jung-thomas]

What & why

First PR of the origin-side abuse-protection series (plan: assume Akamai Bot Manager removal, since its UA/behavioral checks 403 our agentic MCP/A2A clients). Moves the protection those edge rules provided onto our side, as defense-in-depth. Ships flag-OFF (RATE_LIMIT_ENABLED / ImsConfig flag.ratelimit, default false) — no behavior change until enabled on DEV.

Scope (PR1 of 4)

Cross-instance rate limiting on the anonymous/expensive surface + a zero-consumer-setup trusted-caller tier system + observability. (PR2 Fast-Purge, PR3 input validation, PR4 load-shedding to follow.)

New

• srv/lib/rate-limit/shared-limiter.js — fixed-window counter keyed by (routeClass, tier, clientKey), backed by the shared cds-caching store (cross-instance in hybrid/prod). Window governed by windowStart inside the value; TTL is GC-only (a mid-window write can't slide the window). Fail-open: any store fault → per-instance in-memory Map; if that throws, request is allowed. Non-atomic RMW can under-count → effective limit is looser, never tighter (documented; not for exactness).
• srv/lib/rate-limit/agent-identity.js — resolveTier(req):
  • trusted — valid HMAC-SHA256 header (keyId\nmethod\npath\nts, ±5-min replay window), secret via credstore (AGENT_HMAC_SECRET, rotatable in /admin-ui/#secrets).
  • auth — a bearer token / api-key is already present (keyed off a hash — zero new setup).
  • anon — everyone else (IP floor).
  • Identity is a tier, not a gate — unknown callers are limited, never blocked.
• srv/lib/runtime-config/rate-limit-settings.js — ImsConfig-backed numeric thresholds (window, per-routeClass limits, tier multipliers, abuse threshold), 5s cache, defaults on any failure. Env-free.
• srv/lib/rate-limit/register.js — middleware + metrics counters (ratelimit.hits, ratelimit.blocked[route=,tier=]) + debounced RateLimitAbuse alert. Mounted in cds.on('bootstrap') on /content, /build, /graph, /feedback, /homepage, /api, and the agentic /mcp*, /a2a, /chat/stream, /graphql/public.

Modified

• srv/server.js — call registerRateLimit(app) in bootstrap. Legacy always-on /search limiter left intact (intentionally not superseded while this flag defaults OFF — avoids dropping an always-on floor).
• srv/lib/feature-flags/registry.js — RATE_LIMIT_ENABLED entry (kind:db, category Security, dev-only).
• package.json — RateLimitAbuse alert eventType (⚠️ needs manual ANS cockpit condition + subscription wiring per ops runbook before it delivers).

Tests

test/unit/rate-limit.test.js — 15 tests: window allow/block/reset + retryAfter, fail-open fallback counting, key isolation, IP derivation, tier resolution (anon/auth/trusted), HMAC replay + tamper + wrong-path rejection, config defaulting. Registry drift test passes. Full unit suite: only pre-existing env failures (missing island deps / srv-qa bundle / a JWT-exp flake), none related.

Notes

• Fail-open everywhere; never throws into a request path.
• srv-qa cp list unaffected — new modules aren't reachable from content-store.js.
• Rollout: merge flag-OFF → enable on DEV via setFeatureFlag('RATE_LIMIT_ENABLED', true), observe ratelimit.* metrics → then PROD.