feat(server): Redis backend for the idempotency store

[bokelley]

Summary

Adds redisBackend alongside memoryBackend and pgBackend. Redis is a natural substrate for AdCP v3's idempotency cache — SET … NX EX maps directly to the putIfAbsent claim semantic, and key expiry is enforced by the engine without a sweeper job.

import { createClient } from 'redis';
import { createIdempotencyStore, redisBackend, createAdcpServer } from '@adcp/sdk/server';

const redis = createClient({ url: process.env.REDIS_URL });
redis.on('error', err => console.error('redis error', err));
await redis.connect();

createAdcpServer({
  idempotency: createIdempotencyStore({ backend: redisBackend(redis), ttlSeconds: 86400 }),
  // ...
});

Design decisions worth reviewing

• Client shape: RedisClientType<any,any,any> | RedisLikeClient union. Node-redis users pass createClient(...) straight in — no as unknown as casts. The narrow RedisLikeClient interface (4 methods) stays available for ioredis/Upstash/test doubles, with a worked ioredis adapter example in the JSDoc. RedisClientType is imported via import type (erased at emit), so redis stays a true optional peer dep with zero runtime coupling.
• expired vs miss parity. Postgres rows linger past expires_at until cleanup; Redis evicts at the second TTL hits. The backend holds keys alive expiredGraceSeconds (default 120s — store's default 60s clock skew + 60s margin) past expiresAt so the store layer can still return IDEMPOTENCY_EXPIRED within the skew window. Buyer-observable semantics match the Postgres backend.
• Reclaim semantics. A crashed in-flight claim is naturally reclaimable on retry — Redis auto-deletes expired keys, so SET … NX EX just succeeds. No WHERE expires_at < NOW() dance like pg needs.
• keyPrefix default "adcp:idem:". Fine for a dedicated Redis or a dedicated db index. The JSDoc explicitly calls out the same-default-different-deployments collision risk and recommends per-deployment prefixes when sharing a Redis db (the principal segment is per-tenant, not per-deployment).
• ttlFor throws on past expiresAt rather than silently clamping to EX 1 (which would let the entry vanish in 1s and let the next caller re-execute the side effect).
• Error hygiene. Probe and corrupt-value errors attach the underlying detail to Error.cause; public messages are generic to avoid leaking infra shape (ECONNREFUSED 10.0.x.x, WRONGPASS …) or scoped keys (which contain the principal) into adopter-facing error bodies.
• clearAll intentionally omitted. Same rationale as pg — a shared Redis is a production resource; an accidental compliance-reset FLUSHDB would nuke unrelated keys. Tests run against a dedicated db index (REDIS_URL=…/15) and call FLUSHDB themselves.

Pre-PR review

Ran in parallel through DX, ad-tech-protocol, code-reviewer, and security-reviewer agents. Folded in all fix-before-merge findings:

• DX caught that the original RedisLikeClient-only signature didn't accept a real createClient() result (node-redis's set is an overloaded RedisCommandSignature, not structurally assignable). Fixed via the union type above; verified with an out-of-tree typecheck smoke.
• Code review caught the silent Math.max(1, …) clamp in ttlFor and a missing reclaim-expired test. Both fixed.
• Security caught two error-message leak vectors (probe + corrupt-value). Both fixed with Error.cause.
• Protocol expert flagged the cross-deployment keyPrefix collision risk. JSDoc tightened.

Two security findings deferred as pre-existing protocol-store issues (not Redis-introduced regressions): cached responses can contain credentials if a handler returns them (#3), and cache-fill DoS via unbounded distinct keys (#4). Will file follow-up issues.

Test plan

• tsc --noEmit clean
• npm run build:lib clean
• npm run format:check clean
• 17 new Redis integration tests pass against local Redis (REDIS_URL=redis://127.0.0.1:6379/15)
• 93/93 idempotency tests pass overall (17 Redis + 76 pre-existing)
• DX smoke: out-of-tree redisBackend(createClient(...)) typechecks without cast; deliberate type error (passing a string) is correctly rejected by tsc
• CI green
• Manual review of the expiredGraceSeconds = 120 default (tied to the store's default 60s clockSkewSeconds + 60s margin — if anyone ever raises the store-level skew, this default needs to keep up; JSDoc says so)

🤖 Generated with Claude Code

[bokelley]

Folded in feedback from review.

Added (commit 1beaa5a): one-time console.warn at redisBackend construction when the default keyPrefix is used against a node-redis client we can confidently identify as being on db 0. Best-effort introspection via client.options.database or parsed from options.url. Stays silent for escape-hatch clients (ioredis, Upstash, test doubles) where we can't read the db index, stays silent when keyPrefix is set explicitly (even to the default value), and stays silent with suppressDefaultPrefixWarning: true. Fires at most once per process across all backend instances. 11 new tests cover the matrix, no live Redis needed for them.

Filed as follow-up issues (deferred from this PR's security review — both are pre-existing protocol-store issues, not Redis-introduced regressions):

• Idempotency store: cached responses may contain credentials returned by handlers #1856 — cached responses may contain credentials returned by handlers
• Idempotency store: cache-fill DoS via unbounded distinct idempotency_key values #1857 — cache-fill DoS via unbounded distinct idempotency_key values

ReplayStore + AdcpStateStore on Redis: ReplayStore is the near-mechanical port — same access pattern (set-with-TTL + check existence), reusable structure. AdcpStateStore needs more careful work for putIfMatch semantics on WATCH/MULTI/EXEC — the silent-data-corruption failure mode (lost writes) makes it categorically different from idempotency's clean "duplicate claim returns cached." Will file as separate issues once this lands.