fix(x402): harden replay and settlement binding

[EfeDurmaz16]

Summary

• makes x402 replay reservation atomic and fail-closed across TypeScript, Go, Rust, Python, and PHP
• preserves reservations after ambiguous broadcast/confirmation outcomes and releases only when non-landing is definitive
• binds Rust exact signature proofs to route and freshness, and makes batch settlement updates atomic across independent handlers
• preserves exact unsigned-u64 amounts and existing small-amount API behavior in PHP

Security invariants

• non-local deployments require an injected shared atomic replay store unless an explicit development-only override is set
• duplicate channel opens cannot reset cumulative state, and cumulative serve decisions use the committed store delta
• public Rust PayKit and Python framework paths can inject the required store without disabling x402-only configurations

Verification

• Rust: 970 tests with axum,client, Clippy -D warnings, rustfmt
• TypeScript: tests, workspace typecheck, ESLint, Prettier
• Go: affected paykit/x402 packages and vet
• Python: replay/framework suites, Ruff, Pyright
• PHP: PHPUnit, PHPStan, syntax and CS Fixer
• independent adversarial re-review: clean after follow-up fixes

Base is #219 per the protocol-split delivery plan. This is intentionally a protocol PR because the same replay and settlement invariant spans multiple SDKs.

[EfeDurmaz16]

@greptile-apps please review

[greptile-apps]

Greptile Summary

This PR hardens the x402 replay and settlement binding across TypeScript, Go, and PHP: it makes replay reservations atomic and fail-closed before broadcast, adds route/memo binding to the exact-scheme challenge, replaces process-local sync.Map with a shared mppcore.Store, and enforces a boot-time policy that rejects non-localnet deployments without a durable replay store.

• TypeScript: createX402ExactAdapter claims the replay reservation before settlement and releases only for a vetted set of provably pre-broadcast failure reasons; X402Upto.verifyOpen binds the channel's first route and marks it consumed; ChallengeBlockhashCache single-flights blockhash fetches per adapter instance.
• Go: Adapter.replay moves from sync.Map to mppcore.Store with PutIfAbsent; cosign gains tighter signer-slot validation; settlementNotLanded releases only after IsBlockhashValid + absent signature confirm the transaction never landed.
• PHP: Adapter::exactBaseUnits uses BigInteger for full u64 wire values; Verifier::readU64Le switches to two-limb reconstruction, fixing sign-bit corruption for amounts \u2265 2^63; replay reservation is claimed before broadcast and retained on any ambiguous outcome.

Confidence Score: 5/5

Safe to merge. The replay-and-settlement hardening is implemented consistently across all targeted SDKs with correct fail-closed semantics; the observations flagged are maintenance notes, not runtime defects.

The core invariants are correctly implemented and thoroughly tested across Go (970 tests), TypeScript, PHP, and the cross-SDK harness. The two flagged items are a hard-coded facilitator error-string whitelist that could silently block retries on unlisted pre-broadcast reasons, and a potential panic in cosign() if a malformed decoded transaction has NumRequiredSignatures larger than AccountKeys. Neither is a present defect in the changed paths.

typescript/packages/pay-kit/src/adapters/x402.ts (RELEASE_SAFE_SETTLE_REASONS coupling) and go/paykit/adapters/x402/exact.go (Signers() call order in cosign).

Important Files Changed

Filename	Overview
typescript/packages/pay-kit/src/adapters/x402.ts	Adds replay reservation with fail-closed settle exception handling and RELEASE_SAFE_SETTLE_REASONS whitelist tightly coupled to @x402/core/facilitator error strings.
go/paykit/adapters/x402/exact.go	Replaces sync.Map with mppcore.Store PutIfAbsent; cosign calls Signers() before the bounds guard that would catch mismatched signer vectors.
typescript/packages/pay-kit/src/adapters/x402-upto.ts	Adds channel-route binding and consumed-key reservation; TTL correctly capped; TOCTOU gap documented in method docstring.
typescript/packages/pay-kit/src/adapters/x402-shared.ts	Introduces resolveX402ReplayStore (fail-closed off localnet), assertPaymentHeaderWithinCap (16 KB cap), and ChallengeBlockhashCache. Logic is sound.
typescript/packages/pay-kit/src/replay-store.ts	Adds ReservingReplayStore interface, isReservingReplayStore predicate, and createMemoryReplayStore with correct atomic reserve semantics and TTL-based expiry.
php/src/Protocols/X402/Adapter.php	Replay marker moved to pre-broadcast; exactBaseUnits uses BigInteger; boot guard rejects non-durable stores off localnet.
php/src/Protocols/X402/Exact/Verifier.php	Fixes u64 overflow: readU64Le uses two-limb unpack returning BigInteger, eliminating sign-bit corruption for amounts ≥ 2^63.
go/paykit/types.go	Adds X402Config.ReplayStore and ReplayStoreCapability interface with clear multi-replica documentation.
go/paykit/middleware.go	Propagates r.URL.Path into x402Gate.Desc for the challenge memo, matching what VerifyAndSettle receives via AdapterRequest.Path.
harness/php-server/HarnessReplayStore.php	New harness-only Store wrapper; only declares putIfAbsent from the Store interface.
harness/src/process.ts	Creates a shared temporary replay-store directory, wires it for all child processes, and cleans it up on exit/signal.
harness/test/boot-policy.test.ts	Adds native-guard probe suite for PHP/Ruby/Lua; removes them from the env-var skip list now that they enforce native fail-closed contracts.
php/src/Frameworks/Laravel/PayKitServiceProvider.php	Registers X402Adapter singleton with injected replay store and wires RequirePaymentMiddleware correctly.
go/paykit/adapters/x402/replay_test.go	Comprehensive replay test suite covering concurrent claim, confirmation timeout, ambiguous send failure, definitive preflight release, cross-replica shared store, and not-landed release.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client
    participant Middleware
    participant Adapter as x402 Adapter
    participant Store as Replay Store
    participant Facilitator

    Client->>Middleware: POST /pay (X-Payment credential)
    Middleware->>Adapter: VerifyAndSettle(req)
    Adapter->>Adapter: assertPaymentHeaderWithinCap()
    Adapter->>Facilitator: verify(payload, requirements)
    Facilitator-->>Adapter: isValid true
    Adapter->>Adapter: payloadKey(header, payload, requirements)
    Adapter->>Store: reserve(consumed-key, true, 300s)
    alt key already exists
        Store-->>Adapter: false
        Adapter-->>Client: 402 x402_payment_replayed
    else key reserved
        Store-->>Adapter: true
        Adapter->>Facilitator: settle(payload, requirements)
        alt settle throws
            note over Adapter,Store: Reservation KEPT fail-closed
            Adapter-->>Client: 402 settlement_failed
        else failure in RELEASE_SAFE_SETTLE_REASONS
            Adapter->>Store: delete(consumed-key)
            Adapter-->>Client: 402 reason
        else success
            Adapter-->>Client: 200 OK with x-payment-response
        end
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Client
    participant Middleware
    participant Adapter as x402 Adapter
    participant Store as Replay Store
    participant Facilitator

    Client->>Middleware: POST /pay (X-Payment credential)
    Middleware->>Adapter: VerifyAndSettle(req)
    Adapter->>Adapter: assertPaymentHeaderWithinCap()
    Adapter->>Facilitator: verify(payload, requirements)
    Facilitator-->>Adapter: isValid true
    Adapter->>Adapter: payloadKey(header, payload, requirements)
    Adapter->>Store: reserve(consumed-key, true, 300s)
    alt key already exists
        Store-->>Adapter: false
        Adapter-->>Client: 402 x402_payment_replayed
    else key reserved
        Store-->>Adapter: true
        Adapter->>Facilitator: settle(payload, requirements)
        alt settle throws
            note over Adapter,Store: Reservation KEPT fail-closed
            Adapter-->>Client: 402 settlement_failed
        else failure in RELEASE_SAFE_SETTLE_REASONS
            Adapter->>Store: delete(consumed-key)
            Adapter-->>Client: 402 reason
        else success
            Adapter-->>Client: 200 OK with x-payment-response
        end
    end

Loading

_{Reviews (8): Last reviewed commit: "Merge remote-tracking branch 'origin/fix..." | Re-trigger Greptile}

[EfeDurmaz16]

@greptile-apps please review

[EfeDurmaz16]

@greptile-apps please re-review the updated replay hardening.

[EfeDurmaz16]

@greptileai review