fix: consume replay nonces atomically

[realmehmetali]

What changed

• add consumeNonce(nonce, expiresAt) to AgentKitStorage as an atomic replay-protection primitive
• prefer atomic nonce consumption after signature verification while retaining the legacy storage methods for compatibility
• expire in-memory nonce records at the end of the challenge validity window
• document a PostgreSQL INSERT ... ON CONFLICT DO NOTHING implementation and update the integration skill
• add storage and concurrent replay tests

Why

The existing optional replay flow performs hasUsedNonce and recordNonce as separate operations. Two concurrent requests can both pass the read before either records the nonce. A single atomic check-and-insert lets persistent storage implementations enforce one-time challenge use without a TOCTOU window.

Nonce consumption happens after signature verification so malformed or invalidly signed requests cannot consume valid challenges. Existing storage implementations continue to work and can migrate incrementally.

Validation

• bun test ./x402/tests — 12 tests passed
• bun run --cwd x402 build
• full monorepo build completed during development

AI assistance

This contribution was prepared with AI-assisted repository inspection, implementation, and test generation. The final diff and validation results were reviewed by the contributor.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 02ebcda586

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reject known replays before RPC signature verification

When storage exposes hasUsedNonce (including InMemoryAgentKitStorage and legacy persistent implementations), moving that lookup after verifyAgentkitSignature means a consumed but otherwise fresh header can be replayed repeatedly for up to five minutes and every request reaches EVM client.verifyMessage, which may perform configured RPC calls—particularly for ERC-1271 wallets. Retain the non-consuming early lookup as a fast rejection while still calling atomic consumeNonce only after successful signature verification, so invalid requests cannot consume new challenges.

Useful? React with 👍 / 👎.