Make the allowance a ladder: free, signed in, sponsored

[ralyodio]

Builds on #166. The directory stays open to everyone — no key, no account, same data, no field withheld. What changes is rate: money buys throughput, never access.

Tier	Burst/min	Budget/hour	How you get it
anon	120 (unchanged)	600	default
session	300	6,000 (10x)	sign in — free, magic link
sponsor	2,000	120,000	a verified API key

All five numbers are env-overridable (TIER_FREE_HOURLY, TIER_AUTH_MULTIPLIER, TIER_SPONSOR_HOURLY, TIER_FREE_BURST, TIER_AUTH_BURST, TIER_SPONSOR_BURST) because they were chosen against roughly one hour of measurement.

Why an hourly budget on top of the per-minute one

crawlThrottle meters a 60-second window. That's a burst control — it stops a caller taking the machine in one second, and it's sized against what a person does. It is not a sustained-rate control: a crawler pacing itself at 119/min never trips it and still takes 7,200 requests an hour.

Each tier now carries both. A reader browsing hard is bursty and nowhere near the hourly figure; a crawler walking the directory is the reverse. Together they separate the two where either alone doesn't.

An exhausted budget is not an exhausted burst. It earns no strike and no escalating lock — the caller is just told when it rolls over. A burst is misbehaviour happening now, and the doubling penalty makes a runaway loop expensive. Spending an hourly allowance is a pricing question, and answering it with escalating punishment would treat a crawler politely sitting at its limit like one hammering the door.

Signed in is no longer unmetered

This is the behavioural change to review most carefully. Signed-in callers previously skipped metering entirely. That was fine while a session was the only rung above anonymous; it stops being fine the moment signing in is a tier, because an unmetered rung means the ladder tops out at "make a free account" — which is free and unlimited — and nothing above it can ever be worth paying for.

So this is a tightening for signed-in users: 6,000/hour instead of unlimited. With 14 accounts and one active, the blast radius is small.

Deciding the tier without a database

The proxy stays synchronous and keeps lookups out of the request path.

• Session — cookie presence only, exactly as the throttle already decided it. A forged cookie buys the authenticated allowance and nothing else; it reads no data an anonymous caller can't already read.
• Key — answered from an in-memory cache, refreshed behind the request. The first call from a newly-issued key is metered one rung down while the lookup lands, then settles. An unverified key is always metered down, never up — otherwise anyone mints sponsor throughput by inventing a token.

The sponsor ceiling is finite on purpose. A runaway loop on a customer's key is still a runaway loop, and an unbounded tier means their bad deploy takes the directory down with it. 120,000/hour is ~33/sec sustained.

The 429 now says where to go

It carries tier, hourlyLimit, and an upgrade line naming the next rung (/login, then an API key at /account), plus x-ratelimit-tier and x-ratelimit-limit-hour headers. A limiter that only says "slow down" leaves a caller with nothing to do but retry, and the point of a ladder is that there's somewhere to go — an agent reading this is exactly the caller who can act on it without a human.

Compatibility

attempt(identity, now) keeps its old behaviour exactly: the default allowance is the existing 120/min burst with no hourly budget. Only the proxy passes a real tier. That's what lets the 322 pre-existing tests pass untouched.

Testing

• 20 new tests in apps/web/test/tiers.test.js; full suite 342 passing, 0 failures; pnpm build clean.
• Worth noting: my first draft of the key tests used plausible-looking tokens of the wrong shape, so looksLikeApiKey rejected them before the cache was ever consulted and the tests passed without exercising the key path at all — they'd have gone on passing if the sponsor tier were unreachable. Now pinned by "the sponsor tier is actually reachable with a verified key", using the real rsa_<8 hex>_<20+> shape.

Interaction with apiguard

Unchanged and deliberately so. apiguard still applies each key's own hourly_limit (default 5,000) on /api/feeds and /api/search. The tighter of the two wins, which is right: the key's own limit is the deal. Selling sponsorship means issuing a key with a raised hourly_limit — already visible in the /account UI.

Not in this PR

Per-bucket cost weighting. reader fetches and extracts a third-party page and can pay for a translation, so it's worth orders of magnitude more than a directory page, and a flat per-request ceiling prices them identically. #166's data shows reader running near 1,000/hour. That's the next lever and it's a bigger semantic change (budgets stop being "queries" and become "units"), so it deserves its own review.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SisjDW4F1zwTeySnUM6VbB