Make API quota admission atomic

[GunsNR]

Problem

API quota admission was a read-then-write race. authenticateApiKey read the key row, compared usageCount against dailyQuota in application code, and then wrote the incremented count back. Two requests that read the same row before either wrote were both admitted. The window is small but it is exactly the window an attacker controls: fire N requests concurrently and N are admitted regardless of the limit.

The count also lived on the ApiKey row, so a rotated key started a fresh budget — rotation reset the quota rather than continuing it.

Measured against the pre-change algorithm on PostgreSQL 16:

• limit 3, 12 concurrent requests → 12 admitted
• shared rotation budget 6, 20 concurrent requests → 20 admitted

With this change: exactly 3 and exactly 6.

What changed

A new ApiQuotaCounter table holds the authoritative count, keyed by (orgId, quotaGroupId, usageDay) with a unique constraint. Admission is one statement ($limit is the bound parameter carrying dailyQuota):

INSERT INTO "ApiQuotaCounter" (...) VALUES (..., 1, NOW())
ON CONFLICT ("orgId", "quotaGroupId", "usageDay")
DO UPDATE SET "used" = "ApiQuotaCounter"."used" + 1, "updatedAt" = NOW()
  WHERE $limit = 0 OR "ApiQuotaCounter"."used" < $limit
RETURNING "used"

The limit is enforced inside the same statement that increments. ON CONFLICT DO UPDATE takes a row lock, so concurrent updaters serialize on it; the WHERE re-evaluates against the locked, committed row. A refused request returns zero rows and spends nothing.

Keying on quotaGroupId rather than key id means a rotated key and its predecessor share one counter — rotation no longer resets the budget. Keying on the UTC usage day gives a clean rollover with no reset job.

The per-key usageCount / usageDay columns are kept as bookkeeping for the UI but are no longer consulted for admission.

Migration

Hand-written (20260830022346_atomic_api_quota_counter): creates the table and unique index, then backfills from existing ApiKey rows, summing usageCount per (orgId, quotaGroupId, usageDay) so today's in-flight budgets carry over rather than resetting to zero.

Tests

supertool/tests/apikey-quota.test.ts (new, 19 tests) against a real PostgreSQL database:

• 20 concurrent admissions against a limit of 5 → exactly 5 admitted, and the 5 successes report distinct positions
• 12 concurrent requests through the full authenticateApiKey path against a limit of 3 → exactly 3
• exact-limit boundary: the Nth request succeeds, the N+1th is refused
• dailyQuota = 0 means unlimited
• a refused admission does not increment the counter
• a rotated key and its predecessor draw on one shared budget
• two quota groups in one org, and two orgs sharing a group id, do not interfere
• UTC day rollover starts a fresh budget and leaves the prior day's row intact

One structural assertion in apikey-rotation.test.ts pinned the old query shape; it is updated to the new one rather than removed.

Verification

Run locally against PostgreSQL 16:

• prisma migrate deploy on a fresh database, then migrate diff → no drift
• npm run typecheck → clean
• npm run lint → clean
• npm test → 733 passed / 733 (41 files)
• npm run build → compiled
• npm run db:rehearse → passed

Phase 2 status

This closes criterion 7 ("API keys carry scopes, quotas and a rotation flow"). Of the nine Phase 2 acceptance criteria, six are now satisfied — 1, 5, 6, 7, 8, 9 — and three remain open:

• 2 — a migration run against a representative copy of real data. Externally blocked: no real data exists.
• 3 — restoration and rollback or forward-fix rehearsed. Restoration is rehearsed and runs in CI; no rollback or forward-fix drill exists.
• 4 — runs durable and resumable through a real job system. The queue is built and tested, but no worker entrypoint exists, so nothing drains it.

Phase 2 is therefore not complete, and roadmap.ts is unchanged: phase-2 remains in-progress.

Scope

Nothing is deployed. Railway is untouched. No capability flag is activated — public_api stays beta.

docs/release-truth-audit.md and src/lib/capabilities.ts are updated to say that admission is now atomic, replacing the previous accurate note that it was not. The "never exercised by a third-party integrator against a real deployment" caveat is retained.