ADR 0042 — Rate-limit principal and trusted proxy
Accepted · 2026-11-03
Refines the Worker bucket key of ADR 0018; the rest of ADR 0018 stands.
Context
Section titled “Context”ADR 0018 puts request-rate limiting on the Worker’s /api/* routes. The bucket key was the client IP plus a fingerprint of whichever credential header the request carried (X-Restura-Proxy-Token, else Authorization, else Cf-Access-Jwt-Assertion), and the IP came from CF-Connecting-IP, then True-Client-IP. Two holes followed from that:
- Self-host Node never stripped the forwarding headers. On Cloudflare the edge sets
CF-Connecting-IP; the Node server (worker/node-entry.ts) passed whatever the client sent. A client could send a freshCF-Connecting-IPorTrue-Client-IPon each request and get a fresh bucket every time. - The credential part of the key could be client-chosen. The fingerprint came from the first credential header present, not from the credential that was verified. In Cloudflare Access mode no proxy token is configured, so a client could add an arbitrary
X-Restura-Proxy-Tokenand land in a new bucket while still authenticating with its Access assertion.
Decision
Section titled “Decision”- Bucket key is
${ip}|${authPrincipal}(buildBucketKeyinshared/protocol/rate-limiter.ts), used by both the binding and the in-memory limiter. - The principal comes only from a verified credential.
proxyAuthMiddleware(worker/app.ts) runs before the rate limiter and setsauthPrincipalafter it has checked the credential:proxy-tokenfor a matchingWORKER_PROXY_TOKEN(only one value can pass, so the principal is constant), oraccess:<sub>, falling back toaccess:<email>and thenaccess, for a verified Cloudflare Access assertion. No client header is read for it; an unset principal isanon. - Self-host Node pins the IP to the socket peer unless
TRUST_PROXY=true.socketClientIpMiddleware(worker/middleware/rateLimiter.ts), mounted only inworker/node-entry.ts, sets theclientIpcontext variable from the TCP peer address, andresolveClientIpuses it ahead of any header. WithTRUST_PROXY=truethe middleware does nothing and the IP falls throughCF-Connecting-IP,True-Client-IP,X-Real-IP(only withENVIRONMENT=developmentorDEV_BYPASS_AUTH=true), then aSec-WebSocket-Key/User-Agenthash. The Cloudflare Worker is unchanged: the edge setsCF-Connecting-IP.
Alternatives considered
Section titled “Alternatives considered”- Trust forwarding headers by default on Node. Rejected: it is only safe behind a proxy that overwrites them, and nothing in a bare
docker rundoes. The safe default is the socket peer; operators who run a proxy opt in. - Keep a token fingerprint in the key, but only after verification. With a single configured proxy token the fingerprint is a constant, so it adds nothing over
proxy-token. For Access, the verifiedsub/emailclaim identifies the user directly, without depending on the raw assertion string.
Consequences
Section titled “Consequences”Positive
- A client can no longer choose its own bucket on self-host Node (without
TRUST_PROXY) or in Access mode. - The key is built from values the server set (socket peer, verified principal), not raw credential strings, so no credential material is hashed into it.
Negative
- Behind a reverse proxy without
TRUST_PROXY=true, every client shares the proxy’s address bucket. Operators must setTRUST_PROXY=trueand have the proxy overwriteTrue-Client-IPand strip a client-sentCF-Connecting-IP(read first), or overwriteCF-Connecting-IP; a proxy that passes the client’s value through reopens the bucket-choice hole. Docker and Reverse proxy say so. - With
TRUST_PROXY=true,X-Real-IPandX-Forwarded-Forare still not read outside development, so the common nginxX-Real-IPline alone does not identify clients.
References
Section titled “References”- Code:
shared/protocol/rate-limiter.ts(buildBucketKey,resolveClientIp),worker/middleware/rateLimiter.ts(socketClientIpMiddleware),worker/node-entry.ts,worker/app.ts(proxyAuthMiddleware) - Tests:
worker/__tests__/rate-limit-principal.test.ts - Related: ADR 0009 (shared Hono app factory), ADR 0018