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

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

@@ -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
@@ -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: