@absol-labs/agent 0.11.0 → 0.12.0-rc.2

package/docs/mcp-reference.md

@@ -36,11 +36,16 @@ an economic question, not a cryptographic one.
 | `reclaim_unspent`       | **yes**     | Closes the stream (**stops the meter**) and returns unspent USDC to the buyer.  |
 | `list_streams`          | no          | Lists the streams this server opened.                                           |
 | `prove_https_response`  | no          | Buyer-side zkTLS proof of a response. Registered only with Reclaim credentials. |
+| `x402_pay`              | **yes**     | Pays an x402 endpoint (opener path, docs/x402.md) under the spend mandate.      |
+| `refund_status`         | no          | Refund state of an x402 stream, from the seller's gasless refund relay.         |
+| `refund`                | **yes**     | Gasless close (payer-signed) and reclaim of an opener stream via the relay.     |
 
 ### `discover_services`
 
 `category?`, `limit?`. Returns `serviceRef`, `operator`, `publicUrl`, `access`,
-`accessUrl` per listing.
+`accessUrl` per listing, plus `ratePerSecondBand` (`minRatePerSecondUsdc` /
+`maxRatePerSecondUsdc`, atomic units, `null` for an unsigned side) when the
+operator's signed descriptor carries one.
 
 The registry is an **untrusted transport**: every `serviceRef` is re-derived
 from the signed record and the operator's signature recovered, so a compromised
@@ -80,6 +85,16 @@ warning on the result. It is operator-set input only — never a tool argument,
 because the caller being asked to relax a fund-safety check is the LLM the check
 exists to constrain — and it never overrides a positive contradiction.
 
+`ratePerSecondUsdc` must sit inside the listing's operator-signed rate band
+(inclusive). The descriptor is re-verified with the gateway's own check, and an
+out-of-band rate is refused before any approval or open is sent: the escrow
+accepts any non-zero rate, but the seller's gateway answers every request on
+such a stream with `403 stream-rate-out-of-bounds`. A descriptor that does not
+verify is a refusal. Under `METRIK_AGENT_ALLOW_UNVERIFIED_OPERATOR=true` an
+unverifiable pairing has no listing to read a band from, and the result's
+warning says the rate was not checked; the override never widens a band the
+server can read.
+
 The result carries a `metering` block: the rate, the budget, the maximum this
 stream can ever spend, and what starts and stops the clock.
 
@@ -151,6 +166,72 @@ evidence of a delivery that did not happen here.
 This is an L2 signal to be cross-checked with oracle/L1 evidence — not a
 substitute for it.
 
+### `x402_pay`
+
+Arguments: `url` (https; http only for localhost), optional `method`, `headers`,
+`body`, `maxAmountUsdc`, `maxRatePerSecondUsdc` (base units; these can only TIGHTEN
+the server mandate), `minDurationSeconds` and `maxUpfrontAmountUsdc` (the cap on the
+non-refundable part of an upfront quote, passed to the SDK as `maxUpfrontAmount`;
+default 100000 = 0.10 USDC, `"0"` refuses any upfront charge). Pays through `@absol-labs/sdk/x402`'s
+`payWithX402` with every SDK protection intact, and is gated exactly like
+`hire_verified_service`: the same server mandate, the same cumulative spend, the
+same per-owner serialization. The payment's opener terms are checked by
+`checkMandate()` before anything is signed — `amount` (the deposit) against the
+per-stream and total caps, `ratePerSecond`, `maxDuration` and `operator` against
+theirs — and the stream it opens is recorded, so it counts against `maxTotalUsdc`.
+A caller-supplied `PAYMENT-SIGNATURE` / `X-PAYMENT` header is refused. The result
+carries the response (bounded), `streamId`, `opener`, `refundUrl`, the deposit and
+rate, and `refundIsAutomatic: false`.
+
+**Upfront ("minimum charge") quotes.** The price splits into a non-refundable per-call
+charge (`upfrontAmount`, paid to the seller at settlement) and a metered, refundable
+deposit (`price - upfrontAmount`). The mandate counts the WHOLE price as spend; the
+upfront part is non-recoverable. The result describes the split (`openerKind`,
+`priceUsdc`, `nonRefundableUsdc`, `refundableUsdc`, `upfrontFeeUsdc`, `upfrontOnly`) and
+the stream record carries `nonRefundableUsdc`. An **upfront-only** payment
+(`upfrontAmount == price`) opens no stream: `streamId` is `null`, no stream (and no
+reservation) is recorded — only a non-stream charge that keeps counting against
+`maxTotalUsdc` and shows in `list_streams` as such — and the payment is final.
+
+### `refund_status` / `refund`
+
+Arguments: `streamId`, optional `refundUrl` (not needed for a stream this server
+paid for — it was recorded); `refund` also takes `close` (stop the stream first;
+this wallet signs the opener's `Close`, authorized on the mandate owner's signature
+alone like `reclaim_unspent`) and `reclaim` (default `true`; the permissionless
+reclaim, the refund always goes to the payer). Every relay success is verified
+against the transaction receipt. A settlement window that is still open is reported
+with when to retry. Nothing is refunded automatically. For an upfront-only payment —
+`streamId` 0, or the charge key `x402_pay` recorded — both tools answer "nothing to
+refund" (not an error) without contacting a relay or signing anything. The default
+refund client is given read-only chain access, so it can prove an opener's kind
+on-chain and sign an upfront opener's `Close` under its own EIP-712 domain.
+
+The three x402 tools are **opt-in**: set `METRIK_AGENT_X402=1` to register them
+(any other value, or none, leaves them off).
+
+**Spend is reserved before anything is signed.** When the mandate approves a
+quote, `x402_pay` records a reservation for its amount in the stream registry
+— inside the same per-owner queue as `hire_verified_service` — before the SDK
+signs the EIP-3009 authorization. If anything fails after the signature has
+been handed out (a malformed or missing `PAYMENT-RESPONSE`, an unconfirmed
+settlement, a dropped connection), the outcome is established from the chain,
+never from the seller: USDC `authorizationState(from, nonce)` and the opener's
+`StreamOpenedFor(streamId, payer, authorizationNonce, …)` log. The reservation
+is released only if the authorization was never used AND has expired; a stream
+found on-chain replaces it under its real `streamId`; otherwise it stays
+counted, and the tool says the money may have moved — never "not settled".
+
+**Outbound requests are guarded.** The URLs the payment tool, `refund` and
+`refund_status` contact come from the model, so every request must be `https:`
+to a host whose every resolved address is public (loopback, private,
+link-local, unique-local, CGNAT, multicast and reserved ranges are refused),
+redirects are never followed, and `METRIK_AGENT_X402_ALLOWED_HOSTS`
+(comma-separated, exact or `*.domain`) restricts it further — list the seller
+AND its refund relay. A response that did not ask for payment is not returned
+(status only). The address is checked at lookup time; use the allowlist where
+DNS rebinding matters.
+
 ## Configuration
 
 `metrik mcp --print-config` prints the `mcpServers` block to paste into an MCP
@@ -159,11 +240,15 @@ in it are placeholders by design.
 
 | Variable                                 | Required | Meaning                                                                                         |
 | ---------------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
-| `METRIK_AGENT_RPC_URL`                   | **yes**  | Base Sepolia RPC.                                                                               |
-| `METRIK_AGENT_ESCROW`                    | **yes**  | The **StreamEscrowV2** address. The retired V1 escrow is refused.                               |
+| `METRIK_AGENT_RPC_URL`                   | **yes**  | RPC of the selected network.                                                                    |
+| `METRIK_AGENT_ESCROW`                    | **yes**  | The network's registered **StreamEscrowV2**. Anything else is refused (see below).              |
 | `METRIK_AGENT_USDC`                      | **yes**  | Settlement token.                                                                               |
 | `METRIK_AGENT_ESCROW_GENERATION`         | no       | `v2` (default, and the only supported value). Declared, not probed.                             |
-| `METRIK_AGENT_CHAIN_ID`                  | no       | Defaults to `84532`; nothing else is accepted.                                                  |
+| `METRIK_NETWORK`                         | no       | Registry id, chain id or CAIP-2 id; default the registry's default network. Testnets only.      |
+| `METRIK_AGENT_CHAIN_ID`                  | no       | Alternative selector; must agree with `METRIK_NETWORK` when both are set.                       |
+| `METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW` | no       | `true` accepts an escrow the registry does not record (a deliberate private deployment).        |
+| `METRIK_AGENT_X402`                      | no       | `1` registers `x402_pay`, `refund_status`, `refund`. **Off by default.**                        |
+| `METRIK_AGENT_X402_ALLOWED_HOSTS`        | no       | Comma-separated hosts (`*.domain` allowed) the x402 tools may contact. Unset = any public host. |
 | `METRIK_AGENT_REGISTRY_URL`              | no       | Registry the invocation origin is verified against.                                             |
 | `METRIK_AGENT_ALLOW_UNVERIFIED_OPERATOR` | no       | `true` downgrades an unverifiable operator pairing from a refusal to a warning. Off by default. |
 | `METRIK_AGENT_MCP_STATE_FILE`            | no       | Persists the stream registry across restarts.                                                   |
@@ -171,5 +256,6 @@ in it are placeholders by design.
 | wallet vars                              | **yes**  | `METRIK_AGENT_PRIVATE_KEY`, or the CDP/Privy set.                                               |
 
 The escrow generation is a **declared fact, not an inference**: the server
-refuses the retired V1 address by name, because a wrong-generation read does not
+refuses any escrow that is not the network's registered `StreamEscrowV2` (the
+retired V1 escrow included) unless `METRIK_AGENT_ALLOW_UNREGISTERED_ESCROW=true`, because a wrong-generation read does not
 revert — it returns confident nonsense about someone's money.

package/docs/probe-capability.md

@@ -0,0 +1,191 @@
+# `ProbeCapability` — letting the verifier check a gated paid route
+
+> **What this changes for you as a seller:** if your listing is `gated`, the
+> Metrik oracle currently cannot call your paid route at all. It can only reach
+> your health route. Adopting `ProbeCapability` is what turns "the health
+> endpoint answered" into "the paid route delivered". It is **opt-in**, and a
+> gateway that does not adopt it is reported by the oracle as **unverifiable**
+> for the paid route — never as passing.
+
+## The problem
+
+A gated listing's paid route requires an `InvocationCapability` (see
+[`../src/capability/invocation-capability.ts`](../src/capability/invocation-capability.ts))
+signed by **the stream's buyer**: 60s TTL, single-use nonce, bound to one method
+and one path. The gateway recovers that signature and checks it against
+`stream.buyer` on-chain.
+
+The oracle is not a buyer. It holds no buyer key and has no stream. So for a
+gated listing there is no credential a regional probe worker could safely
+present, and the paid route goes unprobed by anybody — not remotely, and not
+even by the coordinator.
+
+That is a real gap in a claim the product makes. "The seller earns only for
+intervals that verified" must not quietly mean "the health endpoint answered".
+
+## The mechanism
+
+A second EIP-712 type, `ProbeCapability`, signed by an **oracle signer**:
+
+```
+ProbeCapability {
+  bytes32 serviceRef;   // the service being probed
+  address oracle;       // the minting signer; must equal the recovered signer
+  string  method;       // exactly one HTTP method
+  bytes32 pathHash;     // keccak256 of exactly one request path
+  bytes32 nonce;        // single-use
+  uint64  expiry;       // ~30s
+}
+```
+
+EIP-712 domain: `name = "Metrik Probe Capability"`, `version = "1"`, the
+gateway's `chainId`, and `verifyingContract` = the `StreamEscrowV2` the gateway
+already checks streams against. The domain name is deliberately **different**
+from `"Metrik Invocation Capability"`, so a buyer's invocation signature can
+never be replayed as a free probe and vice versa.
+
+Transport: base64url in the `x-metrik-probe-capability` request header.
+
+### Authority is public, not a shared secret
+
+The gateway authorizes the probe iff the recovered signer is in
+`StreamEscrowV2.getOracleSigners()` — a **public `view`** on the escrow. On the
+live Base Sepolia deployment (`0x0f09f36Ccc05A7c9882F438721C08De314dFd46C`) that
+returns three addresses today.
+
+This is the whole reason the design beats "give the workers a credential":
+
+- **Nothing to distribute.** No API key, no registration, no onboarding call.
+  A third-party seller performs the identical on-chain read and reaches the
+  identical verdict, with no trust in the oracle's say-so.
+- **Nothing to leak.** The only secret is the oracle coordinator's signing key,
+  which never leaves it.
+- **Revocation is already solved.** Remove a signer on the escrow and it stops
+  being able to probe within one signer-cache TTL (60s by default).
+
+### No signing key leaves the coordinator
+
+The oracle coordinator mints **one fresh capability per probe, per vantage** and
+hands the encoded header to the worker alongside the nonce. Workers hold a
+bearer token for the coordinator and nothing else. Compromising every regional
+worker yields no ability to mint a capability, and no ability to probe anything
+the coordinator did not already ask for — the capability is bound to one
+service, one method, one path, one nonce and ~30 seconds.
+
+One capability **per vantage**, not one per probe, because the nonce is
+single-use: two vantages sharing a capability would see the second rejected as a
+replay.
+
+### A probe never consumes a buyer's budget
+
+Three independent reasons, all structural rather than conventional:
+
+1. A `ProbeCapability` carries **no `streamId` and no `buyer`**. There is no
+   stream identified for it to be billed against.
+2. Accrual is only ever produced by an **oracle checkpoint keyed to a stream**.
+   A gateway call produces none, ever — the gateway is an authorizer and proxy,
+   not a meter.
+3. In the reference gateway the probe branch is evaluated **first and returns
+   unconditionally**, so it can never fall through into the stream branch. An
+   authorized probe decision carries only the probe — no `stream`, no
+   capability, nothing billable. A test asserts the stream reader is never even
+   called.
+
+The gateway additionally sets `x-metrik-probe: 1` on the **upstream** request so
+your own metering and analytics can exclude verification traffic. It is
+gateway-asserted: any inbound copy from a client is stripped first, so a paying
+caller cannot mark its own billable request as a probe.
+
+### Rate limiting: why 60/minute
+
+Without a bound, an oracle-signed capability is a licence to consume your
+service indefinitely for free.
+
+The oracle checkpoints every ~15–22 seconds, so **one** vantage probes a given
+service at most ~4 times a minute. T1 multi-vantage fans that out across at most
+9 vantages (the coordinator plus the oracle's 8-worker cap), giving a worst-case
+honest load of **~36 probes/minute**. The default budget is **60 per minute**:
+comfortable headroom for a re-execution sample and clock jitter, while capping
+the free-service surface at one request per second — far below anything
+economically interesting as a way to get the service for nothing.
+
+Tune it with `METRIK_GATEWAY_PROBE_MAX_PER_MINUTE`. A useful side effect: since
+every capability is single-use and ~30s-lived, the rate limit is also what
+bounds the replay cache — at most `maxPerMinute × ttl/60` probe nonces live at
+once.
+
+### Replay protection reuses the existing cache
+
+The probe path calls the **same** `NonceReplayCache` the buyer path uses, so a
+nonce can never be spent once as a probe and once as an invocation. The nonce is
+consumed _before_ the rate-limit check, so a captured capability replayed at
+volume is rejected as a replay rather than eating the honest probe budget, and
+_before_ the on-chain signer read, so a flood cannot amplify into RPC load.
+
+## Enabling it
+
+```bash
+METRIK_GATEWAY_PROBE_CAPABILITY=true          # off by default
+METRIK_GATEWAY_PROBE_MAX_PER_MINUTE=60        # optional
+METRIK_GATEWAY_PROBE_SIGNER_CACHE_SECONDS=60  # optional
+```
+
+There is **no credential to configure**. The signer set is read from the
+`METRIK_GATEWAY_RPC_URL` and escrow the gateway already uses.
+
+Not using the reference gateway? Implement the verification in this exact order
+— cheapest and most local first, so an unsigned or replayed flood cannot amplify
+into RPC load:
+
+1. Decode the `x-metrik-probe-capability` header; malformed → `403`.
+2. `now >= expiry` → `403`.
+3. Recover the EIP-712 signer; it must equal `capability.oracle` → else `403`.
+4. `capability.method` must equal the request method → else `403`.
+5. `keccak256(path)` must equal `capability.pathHash` (path only — no query, no
+   fragment, no trailing slash except root) → else `403`.
+6. `capability.serviceRef` must be one you front → else `403`.
+7. Consume `capability.nonce` single-use → replay is `403`.
+8. Rate-limit → `429`.
+9. `capability.oracle` must be in `getOracleSigners()` → else `403`. If you
+   cannot read the set, **deny** (`403`); do not serve on a stale set.
+
+Then proxy upstream and **do not meter, bill or settle the call**.
+
+## Failure modes, and what each one means to the oracle
+
+Every denial is a distinct machine-readable `reason` in the JSON body:
+
+| Reason                                          | Status | What it means                                                                                            |
+| ----------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------- |
+| `probe-not-enabled`                             | 403    | This gateway has not adopted `ProbeCapability`. The oracle reports the paid route **unverifiable**.      |
+| `malformed-probe-capability`                    | 403    | Header was not a decodable signed capability.                                                            |
+| `probe-capability-expired`                      | 403    | Past `expiry`.                                                                                           |
+| `probe-invalid-signature`                       | 403    | Signature does not recover to the claimed `oracle`.                                                      |
+| `probe-method-mismatch` / `probe-path-mismatch` | 403    | Capability was not minted for this route.                                                                |
+| `probe-service-ref-mismatch`                    | 403    | Minted for another service.                                                                              |
+| `probe-nonce-replayed`                          | 403    | Nonce already spent.                                                                                     |
+| `probe-rate-limited`                            | 429    | Free-probe budget for this window is spent.                                                              |
+| `probe-signer-not-authorized`                   | 403    | Signer is not in `getOracleSigners()`.                                                                   |
+| `probe-signer-set-unavailable`                  | 403    | The set could not be read fresh enough. Fail closed.                                                     |
+| `ambiguous-probe-mode`                          | 400    | Request carried a probe capability _and_ a buyer capability or `X-PAYMENT`. Refused rather than guessed. |
+
+## Honest limitations
+
+- **This is an adoption ask.** We ship the reference implementation because we
+  run the reference gateway, but a third-party seller has to adopt it. Until
+  they do, their gated paid route stays health-route-only and the oracle says so
+  out loud rather than implying coverage it does not have.
+- **A gated seller can stay unverifiable on purpose.** A hostile gateway can
+  simply answer `403` to every probe and remain in the "unverifiable" bucket.
+  That gains it nothing it does not already have today — under the oracle's
+  `strict` enforcement an unverifiable paid route accrues nothing, and under
+  `eligible` it is exactly today's health-route-only behaviour, counted and
+  surfaced. What it can never do is be counted as _passing_.
+- **Delivery, not correctness.** A passing probe is evidence the paid route
+  produced a fresh, spec-conforming response for _this_ challenge. It is not a
+  proof the output is correct. See
+  [`../../streamproof-protocol/docs/verification-model.md`](https://github.com/Absol-Labs/metrik-protocol/blob/main/docs/verification-model.md).
+- **The signer set is federated today.** All three addresses in
+  `getOracleSigners()` are keys held by one process, and one of them operates
+  the live listings. `ProbeCapability` inherits that posture exactly — it makes
+  the _paid route_ checkable, not the verifier independent.

package/docs/quickstart.md

@@ -111,7 +111,7 @@ const account = wallet.account;
 const mandate = spendMandateSchema.parse({
   maxPerStreamUsdc: 100_000n, // 0.1 USDC (6 decimals) — max deposit per stream
   maxTotalUsdc: 100_000n, // cumulative cap across all streams
-  maxRatePerSecondUsdc: 1n, // max accrual rate the agent may agree to
+  maxRatePerSecondUsdc: 100n, // max accrual rate the agent may agree to (0.0001 USDC/s)
   maxDurationSeconds: 3600, // max stream lifetime
   allowedOperators: [account.address as `0x${string}`], // omit/empty ⇒ any operator
   expiresAt: nowSeconds + 365 * 24 * 60 * 60,
@@ -228,7 +228,7 @@ const hire = await agent.openVerifiedStream({
   operator: target.operator, // seller payout wallet from discovery
   serviceRef: target.serviceRef, // bytes32 the oracle verifies delivery against
   budgetUsdc: 100_000n,
-  ratePerSecondUsdc: 1n,
+  ratePerSecondUsdc: 100n, // must sit inside the listing's signed rate band
   maxDurationSeconds: 3600,
   signedMandate,
   spentSoFarUsdc: 0n,
@@ -293,6 +293,40 @@ const { reclaimResult } = await agent.reclaimStream({
 escape-window rules, and `claimed + fees + reclaimed == deposit` conserves the escrowed
 funds exactly.
 
+### 7b. Or pay a seller over x402 (no gas needed)
+
+A Metrik x402 seller (an HTTP `402` with an x402 v2 `exact` quote) can be paid in one
+call. The payment opens the same kind of stream — `deposit = price`, earned per verified
+second — and the same spend mandate bounds it before anything is signed:
+
+```ts
+import { defaultNetwork } from "@absol-labs/agent";
+import { payX402WithMandate } from "@absol-labs/agent/x402-buyer";
+
+const paid = await payX402WithMandate({
+  url: "https://x402.137.23.50.249.sslip.io/transform",
+  init: {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: '{"text":"# hi"}',
+  },
+  signer: account, // USDC only, no ETH
+  network: defaultNetwork(),
+  signedMandate,
+  spentSoFarUsdc: 0n,
+  nowSeconds: Math.floor(Date.now() / 1000),
+});
+console.log(paid.metrikStreamOpener); // streamId, opener, refundUrl, deposit, rate
+```
+
+Getting the unearned part back is not automatic: close, then reclaim, through the seller's
+gasless relay (the `metrik refund` command below, or the SDK's `refundClient`).
+
+Full details, including the mandate mapping: [the buyer section](./x402.md).
+
+From a terminal: `metrik pay <url> --json '{"text":"# hi"}' --max-amount 0.1`, then
+`metrik refund <streamId> --refund-url <url> --close --reclaim`.
+
 ---
 
 ## 8. Five ways to integrate
@@ -306,7 +340,7 @@ loop (`discover -> open -> invoke -> watch -> close -> reclaim`):
 ```bash
 npx --package @absol-labs/agent metrik discover --min-tier 2
 npx --package @absol-labs/agent metrik open --service <serviceRef> \
-  --rate 0.000001 --budget 0.27 --duration 1h --dry-run
+  --rate 0.0001 --budget 0.36 --duration 1h --dry-run
 ```
 
 Testnet-only, key read from `METRIK_AGENT_PRIVATE_KEY`, `--json` for scripting. Full
@@ -394,4 +428,5 @@ Metrik proves **verified delivery** (responded, correctly-shaped, within SLA to
 traffic) — **not output correctness** (that the model's answer is right). Pitch and treat
 it accordingly. The full journey, run live against the real deployed escrow on Base
 Sepolia, is [`scripts/e2e-cdp.ts`](../scripts/e2e-cdp.ts) (`pnpm build:e2e && pnpm
-e2e:cdp`) — the working reference for everything above.
+e2e:cdp`) — the working reference for everything above; its x402 leg is
+[`scripts/e2e-x402.ts`](../scripts/e2e-x402.ts) (`pnpm e2e:x402`).

package/docs/threat-model.md

@@ -22,6 +22,9 @@ In scope:
 - the mandate-gated SDK wrapper in [`src/sdk/client.ts`](../src/sdk/client.ts)
 - Metrik `402` verified-stream opens in [`src/x402/facilitator.ts`](../src/x402/facilitator.ts)
   (a Metrik-native challenge flow, not the x402 protocol — see [docs/x402.md](./x402.md))
+- the x402 v2 opener facilitator in [`src/x402-opener/`](../src/x402-opener/) and the
+  gateway's x402 v2 mode in [`src/gateway/x402-opener-mode.ts`](../src/gateway/x402-opener-mode.ts)
+  (both off by default — see [docs/x402.md](./x402.md))
 - MCP fund-moving tools in [`src/mcp/server.ts`](../src/mcp/server.ts)
 - zkTLS consumer delivery proofs in [`src/zktls/reclaim.ts`](../src/zktls/reclaim.ts)
 - wallet custody in [`src/wallet/provider.ts`](../src/wallet/provider.ts)
@@ -43,6 +46,23 @@ Out of scope:
 | Mandate replay                  | A previously valid signed mandate is replayed after revocation or outside the intended lifetime.                               | Mandates are EIP-712 signed over `mandateId`, `owner`, `chainId`, `issuedAt`, expiry, and policy hashes. `checkMandate()` verifies signature, revocation, expiry, then policy. Integrators can revoke by `mandateId` and track cumulative spend.                                                                        | [`src/mandates/mandate.ts`](../src/mandates/mandate.ts), [`test/mandate.test.ts`](../test/mandate.test.ts), [`test/mcp.test.ts`](../test/mcp.test.ts)                                                                                                                                              | Replay protection is only as strong as revocation and cumulative-spend state freshness. The signed payload itself is bound to one chain and one owner, but revocation is local state today.                                                |
 | False or weak delivery evidence | A consumer submits a proof that is validly signed by the zkTLS system but not bound to the intended request or stream context. | The Reclaim adapter re-verifies every proof locally against the exact URL/method/body/match/redaction spec supplied by the caller, and binds the proof context to buyer/stream metadata before returning it. MCP only exposes the public-request subset so secrets do not leak through tool arguments.                  | [`src/zktls/reclaim.ts`](../src/zktls/reclaim.ts), [`src/x402/facilitator.ts`](../src/x402/facilitator.ts), [`src/mcp/server.ts`](../src/mcp/server.ts), [`test/reclaim.test.ts`](../test/reclaim.test.ts), [`test/x402.test.ts`](../test/x402.test.ts), [`test/mcp.test.ts`](../test/mcp.test.ts) | L2 is still consumer-supplied evidence. A malicious consumer can withhold proofs, and settlement must still treat L1/oracle evidence as authoritative on failure, ambiguity, and expiry.                                                   |
 
+## x402 v2 opener threats
+
+The opener path moves a buyer's USDC only under that buyer's own EIP-3009
+signature, so no agent-held key spends and no spend mandate applies; the
+threats are about where the signed payment can end up.
+
+| Threat                                                                                                                                            | Mitigation                                                                                                                                                                                                                                                                                                                                                            | Code / tests                                                                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| A stock x402 facilitator (or anyone holding the signed payload) submits `transferWithAuthorization` to the opener directly, stranding the payment | Only `MetrikOpenerExactScheme` settles, via `deployAndSettle`; its stock verifier gets a signer that cannot broadcast. The gateway refuses to start, and fails closed (503) later, unless the facilitator's `/supported` marker names its exact factory/escrow/token/chain. `PAYMENT-SIGNATURE` is never forwarded upstream. No discovery extension is ever declared. | `src/x402-opener/scheme.ts`, `src/gateway/x402-opener-mode.ts`; `test/x402-opener-gateway.test.ts`, `test/x402-opener.fork.int.test.ts` |
+| A forged or tampered `payTo`, terms or listing redirects funds                                                                                    | `payTo` must equal `factory.predict(terms)` read on-chain (never code/codehash); `(operator, serviceRef)` must resolve to exactly one operator-signed listing via discovery signature verification; amount bounded by `rate × maxDuration`                                                                                                                            | `test/x402-opener-scheme.test.ts`, `test/x402-opener-config.test.ts`                                                                    |
+| Success reported without a stream                                                                                                                 | `settle` returns `success: true` only from a mined receipt carrying the escrow `StreamOpened` (buyer = opener) and the opener `StreamOpenedFor` for this payer/nonce/amount                                                                                                                                                                                           | `test/x402-opener-scheme.test.ts`                                                                                                       |
+| One payment buys several served responses (a replayed `PAYMENT-SIGNATURE`)                                                                        | At most one successful settle per authorization (chain + asset + payer + nonce) per facilitator instance; the gateway refuses an in-flight or settled authorization with `409` before the upstream runs. In-memory, per instance: run one instance                                                                                                                    | `test/x402-opener-scheme.test.ts`, `test/x402-opener-gateway.test.ts`, `test/x402-opener-regressions.fork.int.test.ts`                  |
+| Concurrent payers fail on the relayer nonce after being served                                                                                    | Relayer submissions are serialized                                                                                                                                                                                                                                                                                                                                    | same                                                                                                                                    |
+| Dust payments drain relayer gas; unauthenticated `/verify` amplifies RPC load                                                                     | Minimum amount (default 0.01 USDC, advertised; the gateway refuses a lower price), `/settle` rate limit per token, `/verify` requires the token by default                                                                                                                                                                                                            | `test/x402-opener-config.test.ts`, fork regressions                                                                                     |
+| A failed upstream still charges the buyer                                                                                                         | The gateway settles only when the upstream status is `< 400`, and a failed settle sends no body                                                                                                                                                                                                                                                                       | `test/x402-opener-gateway.test.ts`, fork E2E                                                                                            |
+| Relayer key or facilitator token leaks                                                                                                            | Env only, never logged or echoed in errors; `/settle` requires the bearer token (constant-time compared)                                                                                                                                                                                                                                                              | `src/x402-opener/facilitator-server.ts`; `test/x402-opener-config.test.ts`                                                              |
+
 ## Fund-Moving Paths
 
 These are the autonomous fund-moving paths in the current agent layer: