v1.0: Extensibility — key format versioning, HMAC, plugin model, edge validation

[bntvllnt]

Context

Deferred from v0.2.0 Production Hardening spec. These are Phase 4 (ecosystem/extensibility) items from docs/ROADMAP.md.

Scope

• Type-safe metadata generics (4.2) — ApiKeys<TMeta> client wrapper. Small effort.
• Key format versioning (4.3) — Version byte in key string for future-proofing format changes. Large effort.
• HMAC-SHA256 with server-side pepper (4.4) — Defense against DB leak. Replaces plain SHA-256 with keyed hash. Large effort.
• onEvent dispatch hook (4.1) — Webhook/streaming dispatch for key lifecycle events. Medium effort.
• Middleware/plugin composition (4.5) — Replace monolithic ApiKeys class with composable model. Large effort.
• Admin cross-owner listing (4.6) — System-level queries across all owners for admin dashboards. Medium effort.
• Offline/edge validation (4.7) — HMAC-based local verify without Convex round-trip. Large effort.

Priority

These items enable ecosystem growth. No individual item blocks production use.

Item	Effort	Impact
Type-safe metadata	Small	High DX
Key format versioning	Large	Future-proofing
HMAC-SHA256 pepper	Large	Security depth
onEvent hook	Medium	Extensibility
Plugin model	Large	Architecture
Admin queries	Medium	Observability
Edge validation	Large	Performance

Dependencies

• Requires v0.3 shipped first
• HMAC-SHA256 requires key format versioning (4.3 before 4.4)
• Edge validation requires HMAC (4.4 before 4.7)