security: atomic Durable Object rate limiter (completes GHSA-v7qc-7qh8-h69g fix)

[schmug]

Summary

Completes the fix for the confirmed rate-limiter race condition tracked in the private advisory GHSA-v7qc-7qh8-h69g by replacing the non-atomic Cache-API counter with a per-identity Durable Object atomic counter.

PR #539 shipped a partial mitigation — it awaits the Cache-API write before returning, closing only the intra-isolate window. This PR implements the complete fix: an atomic primitive that holds across isolates and colos.

The problem

checkRateLimitCache was a non-atomic read-modify-write on the Cloudflare Cache API: cache.match → count++ → cache.put. The Cache API offers no atomic increment/CAS, so a concurrent burst under one identity could all read the same stale count and each write count + 1, letting the effective ceiling exceed the configured limit (free 10/60s, pro 60/3600s).

The fix

• src/rate-limit-do.ts — new RateLimiterDO (SQLite-backed). One instance per identity bucket (ip:<x> / user:<id>) via getByName. The increment(limit, windowSec) RPC does the whole read-modify-write synchronously, so the DO's single-threaded execution serializes overlapping calls — no interleaving, no lost updates.
• src/rate-limit.ts — checkRateLimit(identity, config, namespace?) routes to the DO when the binding is present and falls back to the existing in-memory limiter when it isn't (self-host deploys that strip the binding, and the Node test pool). The racy Cache-API path and pendingWrite are removed.
• src/index.ts — re-exports the DO class from the Worker entry (required for the binding to resolve class_name); middleware passes c.env.RATE_LIMITER.
• wrangler.toml / src/env.ts — RATE_LIMITER binding + v1 new_sqlite_classes migration.
• vitest.config.ts / test/shims/ — Node-pool stub for the cloudflare:workers virtual module (the Node tests import src/index.ts, which now pulls in the DO base class; the Workers pool uses the real module).

Why not the native Rate Limiting binding? It returns only { success } (no remaining/resetAt for the X-RateLimit-* headers) and supports only 10s/60s periods, which breaks the pro 3600s tier. A Durable Object is the correct primitive.

Testing (TDD — failing concurrency test first)

test/integration/rate-limit-do.test.ts runs in the real workerd runtime:

• Atomicity / no burst bypass: 30 simultaneous increments to one identity → the stored count reaches exactly 30 with no lost updates, and exactly limit are allowed.
• Both tiers (free 10/60, pro 60/3600), X-RateLimit-* headers, resetAt stability within a window, ip: vs user: bucket isolation, and the window-roll reset branch (via runInDurableObject).

Gates (fresh run):

• npm test → 1307 passed (78 files, incl. 8 new DO tests)
• npm run typecheck → pass (exit 0)
• npm run lint → pass (161 files, no diagnostics)
• wrangler deploy --dry-run → binding recognized as env.RATE_LIMITER (RateLimiterDO), migration accepted

Acceptance criteria

• Concurrency test fires N simultaneous checkRateLimit calls for one identity and asserts the stored count reaches N (no burst bypass)
• Headers and both tiers behave as before for sequential requests
• wrangler.toml has the DO binding + migration; typecheck passes against the generated binding type
• Existing rate-limit tests still pass (unchanged — they force the in-memory path)

Notes

• Touches CODEOWNERS-gated paths (wrangler.toml, rate limiting) — expects code-owner review; auto-merge intentionally not enabled.
• The advisory GHSA-v7qc-7qh8-h69g remains private/unpublished.

Refs: GHSA-v7qc-7qh8-h69g · completes #539

Co-Authored-By: Claude Opus 4.8 (1M context) noreply@anthropic.com