feat: make signatures single-use with a nonce

[thomas-waite]

Stacked on #39. Adds the nonce that #39 deferred, making every AgentKit signature valid for exactly one request.

Why

#39's bindings already prevent replay against a different service, endpoint, payload, or after 5 minutes. The remaining gap: a byte-identical request replays successfully within the window — anyone inside the receiving side's boundary (logs, middleware, a compromised component) can re-execute it, burning the human's shared free-trial quota and duplicating non-idempotent side effects. expires bounds replay in time; the nonce bounds it in count — to one.

Design

• Wire: every signature carries a random 16-byte nonce in its signed params (created;expires;nonce;keyid;tag). Generated automatically by createSignatureHeaders — no CLI or client interface change.
• Mandatory on the wire, optional to enforce: the closed parser requires the nonce, so every signature in the ecosystem is enforcement-ready; servers opt into strictness by providing storage. Zero-config verify(request) stays stateless (replay bounded by the 5-minute window, as before).
• One atomic call, not v1's racy pair: enforcement is tryRecordNonce(nonce, expiresAt): Promise<boolean> — check and record in one atomic step (Redis: SET nonce 1 NX EX 300), fixing the TOCTOU in v1's hasUsedNonce/recordNonce where two concurrent replays could both pass. expiresAt lets stores TTL entries, so a nonce store only ever holds the last five minutes of nonces (v1's grew unboundedly).
• Ordering: core records the nonce only after the signature is proven (junk can't poison the store) and before the AgentBook lookup (replays cost no RPC). The x402 hooks enforce via AgentKitStorage.tryRecordNonce right after verification; InMemoryAgentKitStorage implements it with expiry pruning for single-process servers.

Changes

• core: nonce param in the profile (serialize/parse/generate); verifyRequest returns it and accepts an atomic tryRecordNonce dependency (NONCE_REUSED on replay).
• x402: optional AgentKitStorage.tryRecordNonce(nonce, expiresAt); hooks reject replays with a validation_failed event; in-memory reference implementation.
• docs/skills: single-use guarantees restored everywhere; storage docs spell out the atomicity contract and the no-storage fallback behavior.

Testing

102 tests (68 core / 24 x402 / 10 cli): nonce parser adversarial cases, record-once semantics with details, no-store-poisoning on failed signatures, hooks replay rejection, storage pruning, and an e2e where an identical replay is rejected while the first use and a tampered-body attempt behave correctly.

🤖 Generated with Claude Code