@absol-labs/agent 0.8.0 → 0.9.1

package/docs/threat-model.md

@@ -0,0 +1,160 @@
+# Agent Threat Model
+
+This document is the agent-layer security review for Phase 2. It covers the
+autonomous spend surface in `streamproof-agent` and maps each threat to the
+current mitigation, code path, and test coverage.
+
+It complements the cross-repo rules in
+[`Absol-Labs/.github/CONTRIBUTING.md`](../../streamproof-dotgithub/CONTRIBUTING.md)
+and the per-repo security pass in [`AGENTS.md`](../AGENTS.md). The same
+non-negotiables apply here:
+
+- no fake green paths
+- no secrets in git or logs
+- fail-closed autonomous spend
+- explicit signing only through the configured account or wallet
+
+## Scope
+
+In scope:
+
+- signed spend mandates in [`src/mandates/mandate.ts`](../src/mandates/mandate.ts)
+- the mandate-gated SDK wrapper in [`src/sdk/client.ts`](../src/sdk/client.ts)
+- x402 verified-stream opens in [`src/x402/facilitator.ts`](../src/x402/facilitator.ts)
+- 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)
+
+Out of scope:
+
+- oracle correctness
+- escrow correctness
+- decentralized verifier / slashing / dispute work
+
+## Threat Map
+
+| Threat                          | Why it matters                                                                                                                 | Current mitigation                                                                                                                                                                                                                                                                                                      | Test / evidence                                                                                                                                                                                                                                                                                    | Residual risk                                                                                                                                                                                                                              |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Runaway spend                   | A prompt or tool call opens streams beyond the owner's intent.                                                                 | Every autonomous fund-moving path calls `checkMandate()` before the SDK can write: `openVerifiedStream()`, `claimStream()`, `closeStream()`, `reclaimStream()`, MCP `hire_verified_service`, and MCP `reclaim_unspent`. Mandates cap per-stream, cumulative spend, rate, duration, and operator. Denial is a hard stop. | [`test/mandate.test.ts`](../test/mandate.test.ts), [`test/sdk-client.test.ts`](../test/sdk-client.test.ts), [`test/mcp.test.ts`](../test/mcp.test.ts), [`test/x402.int.test.ts`](../test/x402.int.test.ts)                                                                                         | `spentSoFarUsdc` and revocation data are resolver inputs. If an integrator provides stale values, the agent still fails closed on signature/expiry/operator checks, but cumulative-cap freshness depends on the integrator's state source. |
+| Mandate bypass                  | A caller skips the mandate layer and reaches the SDK write path directly from the agent layer.                                 | The agent wrapper no longer exposes ungated autonomous write helpers. Existing-stream actions re-read the stream and authorize against the actual operator before `claim`, `close`, or `reclaim`. MCP also prechecks before dispatch.                                                                                   | [`src/sdk/client.ts`](../src/sdk/client.ts), [`test/sdk-client.test.ts`](../test/sdk-client.test.ts), [`test/mcp.test.ts`](../test/mcp.test.ts)                                                                                                                                                    | A caller can still use `@absol-labs/sdk` directly outside this repo. That is expected; this document only claims the agent layer itself is mandate-gated.                                                                                  |
+| Key exposure                    | The agent leaks a private key through logs, env parsing, tool args, or local persistence.                                      | No MCP tool accepts a raw key. Wallet selection is explicit: injected viem account, CDP Server Wallet v2, or an authenticated Privy embedded EOA provider. CDP/Privy paths remote-sign and never export private keys into Metrik code. `.env.example` contains names only.                                              | [`src/wallet/provider.ts`](../src/wallet/provider.ts), [`test/wallet.test.ts`](../test/wallet.test.ts), [`test/privy-wallet.test.ts`](../test/privy-wallet.test.ts), [`README.md`](../README.md)                                                                                                   | Injected-key mode is still as safe as the caller's own host. Privy authentication/session revocation remains the host/provider's responsibility.                                                                                           |
+| Prompt-injection-driven spend   | A hostile response or tool output tries to coerce the agent into paying a different operator or budget.                        | Structured inputs are validated, x402 settlement targets must match the configured chain/escrow, and any spend still must satisfy the owner's signed mandate.                                                                                                                                                           | [`src/x402/facilitator.ts`](../src/x402/facilitator.ts), [`test/x402.test.ts`](../test/x402.test.ts), [`test/sdk-client.test.ts`](../test/sdk-client.test.ts)                                                                                                                                      | Prompt injection can still trigger tool invocation attempts. The safety claim is not "the prompt cannot be attacked"; it is "the attack cannot exceed the mandate or redirect settlement silently."                                        |
+| 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.                                                   |
+
+## Fund-Moving Paths
+
+These are the autonomous fund-moving paths in the current agent layer:
+
+1. `VerifiedStreamAgentClient.openVerifiedStream()`
+2. `VerifiedStreamAgentClient.claimStream()`
+3. `VerifiedStreamAgentClient.closeStream()`
+4. `VerifiedStreamAgentClient.reclaimStream()`
+5. MCP `hire_verified_service`
+6. MCP `reclaim_unspent`
+7. x402 `open()` via `VerifiedStreamX402Facilitator`
+
+All of them now pass a signed mandate check before the SDK can send a write.
+
+Read-only paths are not mandate-gated:
+
+- `getStreamStatus()`
+- MCP `check_stream_status`
+- MCP `list_streams`
+- MCP `prove_https_response`
+
+## Key Custody Options
+
+### Injected caller account
+
+- Source: `METRIK_AGENT_PRIVATE_KEY`
+- Trust model: the caller hosts the signer locally.
+- Safety properties:
+  - the agent layer does not request the key through tool args
+  - the key is not logged or written to disk by agent code
+  - every autonomous write still needs a valid signed mandate
+
+### Coinbase CDP Server Wallet v2
+
+- Source: `CDP_API_KEY_ID`, `CDP_API_KEY_SECRET`, `CDP_WALLET_SECRET`
+- Trust model: Coinbase holds signing material inside its remote signing boundary.
+- Safety properties:
+  - Metrik only receives a signing-capable account object
+  - the private key is never exported into this repo
+  - the same mandate checks apply before any autonomous write
+
+### Privy embedded user-owned EOA
+
+- Source: an authenticated Privy EIP-1193 wallet provider supplied by the host application
+- Trust model: the user owns/authenticates the embedded EOA through Privy; the agent package
+  sees only the provider and public wallet address
+- Safety properties:
+  - no Privy app secret or wallet key is accepted by the adapter
+  - chain and account identity are checked before construction and before each signature
+  - every autonomous write still requires the signed Metrik spend mandate
+- Headless boundary:
+  - the user attaches a Privy additional signer under a non-empty provider policy
+  - the broker stores only a hash of the short-lived agent token and rechecks a signed
+    Metrik mandate, decoded calldata, stream ownership/state, expiry, and revocation
+  - the first successful write requests provider gas sponsorship; later writes do not
+- Limitations: ERC-4337/EIP-1271 smart accounts are not supported
+
+### Autonomous agent-owned Privy EOA
+
+- Source: a P-256 key generated by the agent process and persisted only through
+  an injected secure store or the host OS credential manager
+- Trust model: the agent owns the authorization key; the broker owns only the
+  Privy app credentials and wallet identifier
+- Safety properties:
+  - provisioning sends the broker a public SPKI key and proof-of-possession,
+    never the PKCS8 private key
+  - a fixed approved Metrik policy is required when the broker creates the EOA
+  - provisioning fails closed on a credential store that does not survive a host
+    reboot (process memory, or the Linux kernel keyring the OS keyring silently
+    falls back to when no Secret Service provider answers), because losing the
+    owner key makes any funds the wallet holds permanently unspendable
+  - every write uses prepare → local P-256 signature → one-time execute; the
+    broker verifies the exact canonical Privy request before forwarding it
+  - nonce/public-key binding, short proof/request expiry, strict P-256 parsing,
+    idempotency, and restricted Metrik calldata prevent replay and arbitrary RPC
+- Limitations: the broker must provide persistent idempotency/replay storage and
+  a real Privy integration. This path does not claim smart-account/EIP-1271 or
+  gas sponsorship support. A failed secure store is a hard stop; plaintext
+  persistence is intentionally unsupported.
+
+### CDP-owned smart account + paymaster limits
+
+- Source: optional smart-account provisioning in the wallet layer plus SDK
+  `gasAbstraction`
+- Trust model: the owner signer controls a smart account, and the bundler/paymaster
+  can impose additional sponsorship policy.
+- Safety properties:
+  - approvals remain bounded to the requested stream budget
+  - the SDK exposes a policy hook for session/per-merchant limits
+  - paymaster allowlists can restrict sponsored targets such as the escrow and
+    EntryPoint
+
+### Session keys
+
+`PrivySessionBroker` issues a random, short-lived bearer credential after verifying the
+user's Privy access token, embedded-wallet ownership, and owner-signed Metrik mandate.
+The credential never contains a wallet key. `createPrivySessionProvider` turns it into a
+restricted EIP-1193 boundary for an external agent; revocation and expiry fail closed.
+
+## Security Pass Alignment
+
+The current implementation satisfies the agent-layer security pass this way:
+
+- Every autonomous fund-moving path calls `checkMandate()` before the SDK write.
+- No private key is silently held, logged, or embedded; signing is explicit via
+  the configured injected signer or CDP signer.
+- Budget, rate, duration, and operator limits are enforced in code, not
+  merely documented.
+- Secrets stay in env / repo-secret surfaces; `.env.example` is names only.
+
+## Residual Risks
+
+- Revocation and cumulative-spend state are still local/integrator-provided.
+- CDP and paymaster trust are external dependencies.
+- zkTLS proofs depend on Reclaim as an external attestation system.
+- L2 remains supplemental evidence; it must not override L1 failure or ambiguity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absol-labs/agent",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Metrik agent layer: x402 verified-streaming payments, an MCP server, framework tools, and spend mandates so AI agents can hire and pay verified services safely.",
   "license": "MIT",
   "author": "Absol Labs",
@@ -47,6 +47,7 @@
   "sideEffects": false,
   "files": [
     "dist",
+    "docs",
     "src"
   ],
   "repository": {
@@ -66,38 +67,50 @@
     "pnpm": "9.15.x"
   },
   "dependencies": {
-    "@absol-labs/sdk": "^0.7.0",
+    "@absol-labs/sdk": "^0.9.0",
     "@absol-labs/shared": "^0.12.1",
-    "@coinbase/cdp-sdk": "^1.51.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@napi-rs/keyring": "1.3.0",
     "@privy-io/node": "0.33.0",
-    "@reclaimprotocol/js-sdk": "^5.6.0",
-    "@reclaimprotocol/zk-fetch": "^1.0.0",
     "reflect-metadata": "^0.2.2",
     "viem": "^2.21.0",
     "zod": "^3.24.0"
   },
   "peerDependencies": {
     "@coinbase/agentkit": "^0.10.4",
+    "@coinbase/cdp-sdk": "^1.51.2",
     "@elizaos/core": "^1.7.2",
-    "@langchain/core": "^1.2.0"
+    "@langchain/core": "^1.2.0",
+    "@reclaimprotocol/js-sdk": "^5.6.0",
+    "@reclaimprotocol/zk-fetch": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "@coinbase/agentkit": {
       "optional": true
     },
+    "@coinbase/cdp-sdk": {
+      "optional": true
+    },
     "@elizaos/core": {
       "optional": true
     },
     "@langchain/core": {
       "optional": true
+    },
+    "@reclaimprotocol/js-sdk": {
+      "optional": true
+    },
+    "@reclaimprotocol/zk-fetch": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@coinbase/agentkit": "^0.10.4",
+    "@coinbase/cdp-sdk": "^1.51.2",
     "@elizaos/core": "^1.7.2",
     "@langchain/core": "^1.2.0",
+    "@reclaimprotocol/js-sdk": "^5.6.0",
+    "@reclaimprotocol/zk-fetch": "^1.0.0",
     "@swc/core": "^1.10.0",
     "@types/node": "^20.17.0",
     "prettier": "^3.4.0",