Request for review: atomic authorizePayment (replay + budget reservation)

[prasanthkuna]

Context

x402-guard v0.1-reference implements pre-sign policy for agent payments.

Model

1. claimReplay(fingerprint) — atomic
2. reserveBudget(agent, amount, windows, authorizationId) — atomic
3. Callback / payment runs
4. commitAuthorization or releaseAuthorization

Questions

• Is reservation-before-callback the right primitive for x402 middleware?
• Should authorization handles be standardized across implementations?
• Gaps in rolling-window semantics?

Proof

bun test packages/policy/src/authorize.test.ts packages/policy/src/fault-injection.test.ts

Portfolio: https://github.com/prasanthkuna/railguard-new/blob/master/docs/PORTFOLIO.md

Ask: Can you poke holes in this state machine?

[AmitabhainArunachala]

Security review — Wallet-Agent Spend-Control perspective

@prasanthkuna — nice work. The invariant chain (Intent → Policy → Session → Signature → Hook → Receipt → Reconcile) is the right shape, and the atomic reserve/commit in authorizePayment closes the obvious TOCTOU window. I spent time in the policy source; here's what holds, what's fragile, and where I'd poke harder.

✅ What holds

1. Atomic replay + budget in one lock (authorizePayment → claimReplay → reserveBudget, all under withLock): the ordering is correct. Replay check before budget reservation prevents a replay from burning budget. Budget reservation before returning allow means no allow can be issued without a binding reserve.

2. Authorization fact-binding (commitAuthorization checks agentId + amountAtomic against reservation): the commit step rejects mutable payloads. An attacker can't inflate the amount after authorization.

3. Rolling window includes both spent + reserved (sumInWindowLocked + reservedInWindowLocked): pending authorizations count against the cap, which prevents flooding the window with concurrent reservations.

⚠️ Holes I'd poke harder

H1: claimReplay is process-local — replay protection is not actually atomic across instances.

InMemoryGuardStateStore uses a single-process Promise lock. The portfolio docs say "Production must use a transactional Postgres implementation," which is correct, but the replay map is a single-process Map. If you run two SignGate instances (horizontal scaling), a payment can pass replay on instance A, fail on instance B, and either (a) succeed twice if the caller retries, or (b) leak an unreleased reservation on instance B. The atomicity guarantee is instance-scoped, not system-scoped.

Fix path: Move replay fingerprints to Postgres with INSERT ... ON CONFLICT DO NOTHING on (fingerprint) + WHERE expires_at > now(). Same for reservations: a single INSERT ... SELECT with WHERE current_amount + new_amount <= cap under SERIALIZABLE or SELECT FOR UPDATE.

H2: No expiry on reserved authorizations — leaked reservations block budget forever.

reserveBudget adds a reservation with status: "reserved", but nothing in the store expires or sweeps stale reservations. If a caller authorizes, crashes, and never commits or releases, the reservation stays in reservations and keeps counting against reservedInWindowLocked until the rolling window passes it. After the window expires, reservedInWindowLocked stops counting it (correct), but the reservation object remains in memory and commitAuthorization can still fire on a stale reservation if the caller retries after the window.

Fix path: Add expiresAt to BudgetReservation and reject commits where nowMs > expiresAt. Add a sweeper that marks expired reservations as "released". The maxTimeoutSeconds from the x402 payment requirements (we use 120s) is a natural reservation TTL.

H3: releaseAuthorization is silently idempotent — no audit event on double-release.

releaseAuthorization returns silently if the reservation doesn't exist or isn't reserved. This is convenient but means a caller can release the same authorization twice with no log. In a reconciliation pipeline, a double-release should be a signal that the caller's state machine is broken, not a no-op.

Fix path: Return the previous status or throw on double-release in the production store. At minimum, emit an audit event with release.duplicate.

H4: evaluatePolicyRules doesn't validate payTo against the x402 facilitator's response.

The policy allowlists payTo and payee against ctx.payTo, but ctx.payTo comes from the x402 402 response, which is server-controlled. If the seller's server is compromised or the 402 response is tampered with (MITM before the policy check), the agent could pay an attacker-controlled address that happens to pass the allowlist. The policy layer trusts the 402 response's payTo without independently verifying it against a known facilitator receipt.

Fix path: After the payment settles, verify that the on-chain payTo in the settled transaction matches ctx.payTo used in the policy decision. Our service (https://x402.167-172-95-184.nip.io/mandate/verify) checks exactly this: resource binding, recipient, spend cap, and receipt obligations. Worth wiring in as a post-settlement reconciliation step.

H5: fingerprint is caller-supplied — no verification it's derived from payment facts.

authorizePayment takes input.fingerprint as a string and passes it to claimReplay without verifying the fingerprint is a deterministic hash of (agentId, payTo, amount, resource, nonce). If the caller passes a random UUID each time, replay protection is bypassed entirely. If the caller passes a constant, every payment is a false replay. The fingerprint must be a canonicalized hash of payment-invariant fields, and the policy layer should compute it, not accept it from the caller.

Fix path: Move fingerprint computation into authorizePayment: fingerprint = sha256(canonicalize(ctx.agentId, ctx.payTo, ctx.amountAtomic, ctx.resource, ctx.nonce)). Accept a caller-supplied fingerprint only for backward compat and log a warning if it differs from the computed one.

Quickstart for your fixture/registry listing

We run a live x402 paid API on Base mainnet (10 routes, USDC via xpay.sh facilitator). If you want to test Railguard's authorizePayment against a real x402 endpoint:

# Unpaid 402 challenge — this is what your policy layer would intercept
curl -i https://x402.167-172-95-184.nip.io/price

# Mandate verification (paid, $0.25 USDC) — checks authority, scope, spend cap, recipient, expiry, nonce
curl -i -X POST https://x402.167-172-95-184.nip.io/mandate/verify \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"railguard-test","intent":"x402 spend audit","max_amount_usdc":"1.00","resource":"/price","recipient":"0x68614873C5d624c07DCAA3aFF5243DD5027c3910","expiry":"2026-07-12T00:00:00Z","nonce":"audit-1","human_approval":true,"receipt_required":true}'

Question for you

We run a Wallet-Agent Spend-Control Audit ($750-$2,500) that covers exactly this class of state machine: atomicity across instances, reservation lifecycle, fingerprint derivation, post-settlement reconciliation, and on-chain payTo verification. If you want a full audit pass with a written report and test harness against our live endpoint, I can scope it.

What's your deployment target — single-instance for v0.1, or are you already planning horizontal scaling?

[doteyeso-ops]

Atomic replay + budget reservation before payment commit is the exact pre-action guard we run live as a pay-per-call check. Signed provenance receipts, replay-safe payment guards, offline-verifiable, with spend/consent gates. Free first taste then usage-based pricing for production agent flows. If this fits your authorizePayment model, happy to scope a dedicated one. vibes-coded.com