fix(mpp): require atomic shared replay stores

[EfeDurmaz16]

Summary

• requires an atomic shared/durable MPP replay store across TypeScript, Go, Rust, Python, and PHP
• makes process-local memory an explicit unsafe development opt-in rather than an implicit localnet default
• forwards stores through high-level SDK and framework configuration paths
• keeps x402-only deployments independent from MPP construction

Security invariants

• unknown or wrapped stores are unsafe unless they affirm atomic shared durability
• TypeScript charge and subscription use the same atomic reservation contract across independent adapters
• Python file-backed reservations are atomic across processes
• framework boot paths fail closed without making secure production configuration impossible

Verification

• TypeScript focused replay tests and workspace typecheck
• Go server/adapter tests and vet
• Python replay, two-process, middleware, framework, Ruff and Pyright checks
• Rust constructor/gate tests, rustfmt and Clippy
• PHP PHPUnit, real Symfony container resolution, syntax and CS Fixer
• multiple adversarial review/fix rounds; final public FastAPI request-path review clean

Base is #219. This is a protocol PR because the same replay-store capability contract spans multiple SDKs.

[EfeDurmaz16]

@greptile-apps please review the current head.

[greptile-apps]

Greptile Summary

This PR enforces atomic shared replay stores as a hard security invariant across TypeScript, Go, PHP, Python, and Rust SDKs for MPP, replacing the previous implicit process-local-memory default with an explicit unsafe development opt-in (allowUnsafeMemoryStore/AllowUnsafeMemoryStore). The putIfAbsent operation is now the single-winner atomic gate for all replay prevention, and the marker is committed only after successful on-chain verification rather than before confirmation polling.

• TypeScript: resolveReplayStore / assertReplayStorePolicy enforce production stores must be registered via declareProductionReplayStore(); verifyTransaction and verifySignature now use Errors.VerificationFailedError on replay collision so mppx maps them to 402 rather than 500.
• Go: Config.AllowUnsafeMemoryStore replaces the permissive localnet/env-var backdoor; injected stores on non-localnet networks must implement core.SharedStore with IsShared() == true.
• PHP: ReplayStoreValidator::isDurableShared centralises the fail-closed capability check; RequirePayment gains a lazy mppFor() factory so x402-only paths never construct an MPP adapter.

Confidence Score: 5/5

Safe to merge; the replay-store security invariant is correctly enforced across all five SDKs with no regressions in the core charge/session verification paths.

The core security change is implemented correctly and covered by targeted tests. The two findings are a minor env-var acceptance asymmetry between the replay-store and session-store escape hatches in TypeScript, and a less strict identity check for allowUnsafeMemoryStore in PHP. Neither affects correctness in the common deployment model.

typescript/packages/pay-kit/src/config.ts (env-var acceptance inconsistency) and php/src/Protocols/Mpp/Adapter.php + php/src/Protocols/Mpp/Server/SolanaChargeHandler.php (MemoryStore identity check less strict than TypeScript).

Important Files Changed

Filename	Overview
typescript/packages/mpp/src/server/store.ts	New file introducing ReplayStore type, createUnsafeMemoryReplayStore, createAtomicReplayStoreView, and resolveReplayStore; the view correctly forwards putIfAbsent and preserves isDurable/isShared capability flags.
typescript/packages/pay-kit/src/replay-store.ts	New pay-kit module that wraps the mpp-package store utilities; uses a WeakSet to restrict the development escape to SDK-created stores only, preventing a user-injected store from impersonating the unsafe flag.
typescript/packages/pay-kit/src/config.ts	assertReplayStorePolicy added and called at end of configure() and from createMppAdapter(); feePayer default changed from true to signer.isFeePayer; env-var acceptance for allowUnsafeMemoryStore inconsistent with Session.ts.
typescript/packages/mpp/src/server/Charge.ts	putIfAbsent now the single-winner gate after on-chain verification; all four replay-collision throws use Errors.VerificationFailedError so mppx maps them to 402; receipt is built before the commit call.
typescript/packages/mpp/src/server/Session.ts	resolveSessionStore fails closed for mainnet without sessionStoreDurability='durable-shared'; ConfigurationError exported; devnet opt-in uses PAY_KIT_ALLOW_INMEMORY_REPLAY_STORE accepting both '1' and 'true'.
go/protocols/mpp/server/server.go	AllowUnsafeMemoryStore replaces the env-var backdoor; injected stores on non-localnet must implement core.SharedStore with IsShared()=true; mainnet forbids the unsafe flag regardless of whether a store is also provided.
go/protocols/mpp/core/store.go	SharedStore interface added; MemoryStore.IsShared() returns false; PutIfAbsent added under a mutex for atomic localnet/test use.
php/src/Store/ReplayStoreValidator.php	New centralised isDurableShared() that fails closed when a store implements neither DurableStore nor ReplayStoreCapability.
php/src/Protocols/Mpp/Adapter.php	allowUnsafeMemoryStore bypass accepts any MemoryStore instance (not just SDK-created) when the flag is set; less strict than TypeScript's WeakSet approach.
php/src/Middleware/RequirePayment.php	MppAdapter construction deferred to mppFor() so x402-only gates never trigger MPP adapter construction; mppFactory closure enables framework-controlled injection.
php/src/Protocols/Mpp/Server/SolanaChargeHandler.php	allowUnsafeMemoryStore added; mainnet guard uses a hard-coded string list; bypasses durable check for any MemoryStore instance when flag is true.
typescript/packages/pay-kit/src/adapters/mpp.ts	createMppAdapter validates replayStore presence and atomicity before building the atomic view; tokenProgram now derives from defaultTokenProgramForCurrency instead of a hardcoded constant.
harness/test/boot-policy.test.ts	Boot-policy probes updated to treat go, typescript, and python as required SDKs; auto-detect guard marker via git-grep so future SDK PRs promote themselves without manual edits.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client
    participant ChargeHandler
    participant Solana RPC
    participant ReplayStore

    Client->>ChargeHandler: credential (signed tx bytes)
    ChargeHandler->>ChargeHandler: resolveReplayStore (fails closed without shared store)
    ChargeHandler->>ChargeHandler: co-sign transaction
    ChargeHandler->>Solana RPC: broadcastTransaction(signedTx)
    Solana RPC-->>ChargeHandler: signature
    ChargeHandler->>Solana RPC: waitForConfirmation(signature)
    Solana RPC-->>ChargeHandler: confirmed
    ChargeHandler->>Solana RPC: verifyOnChain(signature, challenge, recipient)
    Solana RPC-->>ChargeHandler: instructions verified
    ChargeHandler->>ReplayStore: putIfAbsent("solana-charge:consumed:sig", true)
    alt first winner
        ReplayStore-->>ChargeHandler: true
        ChargeHandler-->>Client: Receipt (200)
    else replay / concurrent race
        ReplayStore-->>ChargeHandler: false
        ChargeHandler-->>Client: VerificationFailedError → 402
    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 ChargeHandler
    participant Solana RPC
    participant ReplayStore

    Client->>ChargeHandler: credential (signed tx bytes)
    ChargeHandler->>ChargeHandler: resolveReplayStore (fails closed without shared store)
    ChargeHandler->>ChargeHandler: co-sign transaction
    ChargeHandler->>Solana RPC: broadcastTransaction(signedTx)
    Solana RPC-->>ChargeHandler: signature
    ChargeHandler->>Solana RPC: waitForConfirmation(signature)
    Solana RPC-->>ChargeHandler: confirmed
    ChargeHandler->>Solana RPC: verifyOnChain(signature, challenge, recipient)
    Solana RPC-->>ChargeHandler: instructions verified
    ChargeHandler->>ReplayStore: putIfAbsent("solana-charge:consumed:sig", true)
    alt first winner
        ReplayStore-->>ChargeHandler: true
        ChargeHandler-->>Client: Receipt (200)
    else replay / concurrent race
        ReplayStore-->>ChargeHandler: false
        ChargeHandler-->>Client: VerificationFailedError → 402
    end

Loading

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

[EfeDurmaz16]

@greptile-apps please re-review — the exact-head Rust build break, Windows import portability, and typed replay rejection findings are fixed with focused regressions.

[EfeDurmaz16]

@greptile-apps please re-review the current head; the optional Rust MPP accessor, replay-store contracts, and mainnet alias guards now have focused regression coverage.

[EfeDurmaz16]

@greptile-apps please re-review the exact current head; CI-derived replay capability and harness boot fixes are now covered, while the remaining conformance dependencies are owned by #214 and #236.

[EfeDurmaz16]

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

[greptile-apps]

Plain Error on replay collision may reach mppx as a 500

verifyTransaction now calls store.putIfAbsent() directly and throws new Error('Transaction signature already consumed') when a replay is detected. The atomicReplayStoreView.put() interception (in store.ts) throws Errors.VerificationFailedError, which mppx converts to a 402. But that interception path is only exercised if mppx internally calls store.put() for a consumed key — Charge.ts's direct putIfAbsent() call bypasses it entirely. If verifyTransaction's caller (within Charge.ts) does not explicitly catch a plain Error and convert it to a VerificationFailedError before returning to mppx, a concurrent duplicate-spend attempt will surface as an unhandled error rather than the expected 402 challenge. The same pattern appears in verifySignature at the other call site in this file. Consider replacing both throw new Error(...) instances with throw new Errors.VerificationFailedError({ reason: '...' }) to stay consistent with the view's interception path and ensure mppx handles the rejection correctly regardless of which code path is active.

[EfeDurmaz16]

Resolved on the current head. All four replay-collision throws in Charge.ts use Errors.VerificationFailedError({ reason: 'Transaction signature already consumed' }) (verifyTransaction commit, verifySignature pre-lock read, in-lock recheck, in-lock commit), so mppx returns a 402, not a 500.

[EfeDurmaz16]

@greptileai review

[EfeDurmaz16]

@greptileai review