feat(signing): PostgresReplayStore for distributed verifier deployments

[bokelley]

Summary

Adds a Postgres-backed ReplayStore so multi-instance verifier deployments share replay-protection state. Closes #1015.

The default InMemoryReplayStore is per-process. On a fleet, an attacker who captures a signed request can replay it against a sibling instance whose cache hasn't seen the nonce — RFC 9421's 5-minute expiry bounds the window but that's plenty of time for an in-flight replay. PostgresReplayStore closes the hole using a (keyid, scope, nonce) primary key the verifier checks on every signed request.

This PR's changeset accumulates into Release PR #1014, which currently bumps to 5.20.0 from #1017. Merging this lands the work on main; nothing publishes to npm until you merge the Release PR.

What's worth a second pair of eyes

1. The single-statement insert handles replay → cap → insert atomically

src/lib/signing/postgres-replay-store.ts:148 — one CTE that:

• Returns 'replayed' if an unexpired row already exists for (keyid, scope, nonce)
• Returns 'rate_abuse' if the active count for (keyid, scope) is at the cap
• Otherwise inserts (or refreshes an expired row in place) and returns 'ok'
• Falls through to 'replayed' on the concurrent-same-nonce loser branch

Result precedence matches InMemoryReplayStore: replay > rate_abuse > ok.

2. Expired-row recycling — the bug I caught with the integration test

The first version of the SQL used ON CONFLICT DO NOTHING and inferred 'replayed' from an empty RETURNING. That broke the "previously-expired same-nonce" case: the row was still on disk (sweeper hadn't run), ON CONFLICT fired, RETURNING was empty, adapter returned 'replayed' — but the InMemory store returns 'ok' for that case (it prunes-then-checks). Switched to ON CONFLICT DO UPDATE WHERE existing-is-expired, which refreshes the row in place when its previous TTL has elapsed. Now both stores agree.

3. Sweeper is an exported helper, not a background timer

sweepExpiredReplays(pool, options?) is exported and callers schedule it themselves (cron, app timer, pg_cron, etc.). Deliberately avoiding a constructor-injected timer — those surprise people in tests and serverless. Doc shows three ways to schedule.

4. Reuses PgQueryable structural type

Imports from src/lib/server/postgres-task-store.ts so the SDK stays free of a hard pg dependency. Matches the PostgresTaskStore / PostgresStateStore pattern already in the codebase.

Test plan

• npm run typecheck — clean
• npm run format:check — clean
• npm run build:lib — clean
• 13 new integration tests in test/lib/postgres-replay-store.test.js (run with DATABASE_URL=postgres://...):
  • Default migration + custom table names + SQL-injection-shaped name rejection
  • First insert 'ok', second insert same nonce 'replayed'
  • (keyid, scope) partitioning — same nonce on different scopes is not a replay
  • TTL boundary respected by has() and by insert() (expired same-nonce recycles correctly)
  • Cap precedence: replay > rate_abuse > ok
  • isCapHit reflects active count vs cap; expires-out properly
  • Sweeper: full sweep + batched sweep
  • Concurrency: 10 parallel same-nonce inserts produce exactly 1 'ok' and 9 'replayed'
  • E2E: signed request → verifier wired with PostgresReplayStore → first request verifies, second is rejected as request_signature_replayed
• All existing 175 signing tests still pass — no regressions

Deferred follow-ups

• Redis adapter (@upstash/redis or ioredis-shaped) as a sibling example — pattern is identical, no SDK interface change.
• pg_cron schema helper for users who'd rather have Postgres run the sweep — small follow-up doc, no code.

🤖 Generated with Claude Code

[bokelley]

Local two-instance validation (.context/work/two-instance-replay-check.mjs):

# Step 1: Send signed request to verifier instance A (fresh)
  → status=verified keyid=test-ed25519-2026

# Step 2: Replay same headers to verifier instance B (different process)
  → rejected with code=request_signature_replayed step=12

Distinct PostgresReplayStore instances backed by the same Postgres correctly enforce replay protection across what would be separate verifier processes. Verifier rejects at step 12 (the canonical replay-detection step).

Three-reviewer pass (security, code, protocol — same parallel pattern as #1017). No blockers, one consensus blocker from protocol (untested invariant), several worth-fixing items. All addressed in f759c532:

Item	Source	Done
Cap clears post-expiry without sweeper — untested invariant	protocol blocker	Test added (line 131)
now/ttlSeconds validation (NaN/Infinity → PG to_timestamp DoS surface)	security M2	assertFiniteSeconds at all three method boundaries
REPLAY_CACHE_MIGRATION constant for repo-style parity	code-review nit	Exported alongside getReplayStoreMigration
JSDoc: cap is best-effort under concurrency	security M1 + code-review	Added
Test: concurrent recycle of expired nonce (10 parallel)	security M1	Test added (line 151)
Test: batched sweep with batchSize > active expired count	code-review nit	Test added (line 167)
Test: rate-abuse rejection through verifier pipeline (vector 020)	protocol note	Test added (line 218)
setCapHitForTesting hook for white-box conformance grading	protocol note	Documented limitation (per reviewer's option a); white-box grading can use cap: small + real inserts
count(*)::bigint → >= bigint AS hit refactor	code-review nit	Skipped — works as-is

Test totals: 18/18 PostgresReplayStore integration tests (was 13) + 175 existing signing tests. All green.