@absol-labs/agent 0.10.0 → 0.11.0

package/dist/cli/wallet.d.ts

@@ -1,4 +1,6 @@
-import type { LocalAccount } from "viem";
+import type { Account, LocalAccount, Transport } from "viem";
+import type { AutonomousWalletCredentialStore } from "../wallet/autonomous-wallet.js";
+import { type PrivyCliWalletSource, type PrivySpendPolicy } from "./privy.js";
 /**
  * The ONLY place the CLI resolves a signing wallet.
  *
@@ -13,36 +15,38 @@ import type { LocalAccount } from "viem";
  *  1. `METRIK_AGENT_PRIVATE_KEY` — a raw Base Sepolia test key.
  *  2. The `CDP_*` / `METRIK_AGENT_CDP_*` quartet — a Coinbase CDP Server Wallet
  *     v2 account, resolved through this package's own `resolveAgentWallet()`.
+ *  3. The `METRIK_AGENT_PRIVY_*` variables — a Privy wallet reached through a
+ *     broker, either agent-owned (`METRIK_AGENT_PRIVY_WALLET_KEY`) or a
+ *     user-owned broker session. See `./privy.ts`.
  *
- * The order matches `parseAgentWalletEnv()` (the MCP server's resolution), so
- * one environment configures every surface the same way. It is checked in a
- * FIXED order rather than "whichever is configured", because an environment
- * carrying both is ambiguous about which address funds the stream — and that
- * ambiguity is a fund-moving one. When both are present the private key wins
- * and `resolveCliWallet` says so on stderr rather than silently picking.
+ * The first two match `parseAgentWalletEnv()` (the MCP server's resolution), so
+ * one environment configures those surfaces the same way. The order is FIXED
+ * rather than "whichever is configured", because an environment carrying two is
+ * ambiguous about which address funds the stream — and that ambiguity is a
+ * fund-moving one. When more than one is present the earlier entry wins and
+ * `resolveCliWallet` says so on stderr rather than silently picking.
  *
- * ## Why CDP is wired and Privy is not
+ * ## What is different about Privy
  *
- * CDP is the only wallet path in this package with live CI evidence
- * (`scripts/e2e-cdp.ts` drives the full journey against the real Base Sepolia
- * escrow), and its account signs LOCALLY — `toAccount(cdpServerAccount)` is a
- * viem local account, so it drops straight into the CLI's existing
- * `http(rpcUrl)` transport with no other change.
+ * A private key and a CDP account both sign LOCALLY: `privateKeyToAccount()`
+ * and `toAccount(cdpServerAccount)` are viem local accounts, so they drop
+ * straight into the CLI's `http(rpcUrl)` transport with no other change.
  *
- * Privy does not. Both Privy adapters in `src/wallet/` produce a JSON-RPC
- * account with no `signTransaction`: they sign and broadcast by sending
- * `eth_sendTransaction` / `eth_signTypedData_v4` to a provider, so they need the
- * wallet client's TRANSPORT to be that provider rather than a plain RPC. Wiring
- * that into the CLI is not a matter of reading three more variables — it
- * changes the transport for every fund-moving command, and `metrik invoke`
- * additionally requires a local signer (`InvokeOptions.buyer: LocalAccount`).
- * `assertLocalSigner` below therefore REFUSES a non-local account with that
- * fact, instead of accepting one and failing later inside viem. See
- * `docs/cli.md` § Wallet.
+ * Privy does not. Its account is a JSON-RPC account with no `signTransaction`:
+ * it signs and broadcasts by sending `eth_sendTransaction` /
+ * `eth_signTypedData_v4` to a provider, so the wallet client's TRANSPORT must
+ * be that provider rather than a plain RPC. That is what {@link CliWallet.transport}
+ * carries, and the only reason this file knows Privy exists. The signer check
+ * below is therefore about CAPABILITY, not about locality: it refuses an
+ * account that genuinely cannot sign, and refuses a non-local account only on
+ * the paths that broadcast through `--rpc-url`.
+ *
+ * See `docs/cli.md` § Wallet.
  */
 export declare const PRIVATE_KEY_ENV = "METRIK_AGENT_PRIVATE_KEY";
 /** Every environment variable the CDP path reads. Named in errors, never printed. */
 export declare const CDP_ENV_VARS: readonly ["CDP_API_KEY_ID", "CDP_API_KEY_SECRET", "CDP_WALLET_SECRET", "METRIK_AGENT_CDP_OWNER_NAME"];
+export { PRIVY_ENV_VARS, PRIVY_SESSION_ENV_VARS, PRIVY_WALLET_KEY_ENV, } from "./privy.js";
 /**
  * What the key is for, in the words of the command that needs it. `invoke`
  * signs an EIP-712 invocation capability and broadcasts NOTHING; telling its
@@ -50,29 +54,77 @@ export declare const CDP_ENV_VARS: readonly ["CDP_API_KEY_ID", "CDP_API_KEY_SECR
  */
 export type KeyPurpose = "transaction" | "capability";
 /** Which environment configured the signer, for output and for error text. */
-export type CliWalletSource = "private-key" | "cdp";
+export type CliWalletSource = "private-key" | "cdp" | PrivyCliWalletSource;
+/**
+ * An account every CLI signing path can actually use.
+ *
+ * `signTypedData` is required rather than optional because it is the one
+ * capability EVERY path needs: fund-moving commands self-sign an EIP-712
+ * `SpendMandate`, and `invoke` signs an EIP-712 `InvocationCapability`. An
+ * account without it type-checks as a viem `Account` and then fails at the
+ * first signature with a `TypeError`.
+ */
+export type CliSignerAccount = Account & Pick<LocalAccount, "signTypedData">;
 export interface CliWallet {
     readonly source: CliWalletSource;
+    readonly account: CliSignerAccount;
     /**
-     * A LOCAL signer. Every CLI path either broadcasts through `http(rpcUrl)`
-     * (which cannot sign) or signs EIP-712 off-chain, so a signer that delegates
-     * to a remote provider is refused at resolution rather than mid-command.
+     * The transport fund-moving commands must broadcast through, when the wallet
+     * REQUIRES one. `undefined` means "a plain `http(--rpc-url)` is correct" —
+     * true for a local signer, false for Privy, whose provider IS the transport.
      */
-    readonly account: LocalAccount;
+    readonly transport?: Transport;
     /** One line naming the signer's origin. Safe to print: no secret in it. */
     readonly description: string;
+    /**
+     * Set when this wallet's spend ceiling is enforced where the CLI cannot reach
+     * it — i.e. by a Privy broker policy, not by a locally self-signed mandate.
+     *
+     * Its presence is the signal that the CLI should NOT self-sign a
+     * `SpendMandate` for this wallet, and should read and enforce the real
+     * ceiling instead. See `./spend-policy.ts` for why that substitution is
+     * strictly stronger than the mandate it replaces, and why re-adding the
+     * mandate "for consistency" would be a regression.
+     */
+    readonly readSpendPolicy?: () => Promise<PrivySpendPolicy>;
+}
+export interface ResolveCliWalletOptions {
+    readonly purpose?: KeyPurpose;
+    /**
+     * `--rpc-url`. Only the Privy paths use it at resolution time: their provider
+     * serves the wallet client's READS as well as its writes, so without this a
+     * Privy command would read from a different endpoint than `--rpc-url` names.
+     */
+    readonly rpcUrl?: string;
+    readonly note?: (line: string) => void;
+    /**
+     * Test seam, same role as `ResolveAgentWalletOptions.createCdpClient`: the
+     * credential store an agent-owned Privy wallet is read from. Unset in every
+     * real run, where the store is selected from the environment.
+     */
+    readonly store?: AutonomousWalletCredentialStore;
+    /** Test seam: the `fetch` the Privy broker is reached through. */
+    readonly fetchImpl?: typeof fetch;
 }
 /**
  * Resolves the signing wallet, or throws an actionable configuration error.
  *
- * `note` receives one line when the environment is ambiguous (both wallet
- * sources configured). It is optional so `resolveCliWallet` stays usable from a
- * context with no printer; commands always pass `out.note`.
+ * `note` receives one line when the environment is ambiguous (more than one
+ * wallet source configured). It is optional so `resolveCliWallet` stays usable
+ * from a context with no printer; commands always pass `out.note`.
  */
-export declare function resolveCliWallet(env: NodeJS.ProcessEnv, options?: {
-    readonly purpose?: KeyPurpose;
-    readonly note?: (line: string) => void;
-}): Promise<CliWallet>;
+export declare function resolveCliWallet(env: NodeJS.ProcessEnv, options?: ResolveCliWalletOptions): Promise<CliWallet>;
+/** True for both Privy shapes, which reach their key through a broker. */
+export declare function isPrivyWalletSource(source: CliWalletSource): source is PrivyCliWalletSource;
+/**
+ * Whether this wallet's ceiling is enforced somewhere the CLI cannot reach.
+ *
+ * The one question every fund-moving command asks before deciding whether to
+ * self-sign a `SpendMandate`. See `./spend-policy.ts`.
+ */
+export declare function isPolicyEnforced(wallet: CliWallet): wallet is CliWallet & {
+    readonly readSpendPolicy: () => Promise<PrivySpendPolicy>;
+};
 /**
  * The same resolution, but "nothing configured" is not an error. Used by
  * look-before-you-leap paths (`open --dry-run`, `streams --address`) that
@@ -82,14 +134,31 @@ export declare function resolveCliWallet(env: NodeJS.ProcessEnv, options?: {
  * A wallet that is PARTIALLY configured is still an error here: "you set three
  * of the four CDP variables" and "you configured no wallet" are different
  * facts, and rendering the first as the second sends the reader looking in the
- * wrong place.
+ * wrong place. The same rule applies to a partial Privy setup.
  */
-export declare function optionalCliWallet(env: NodeJS.ProcessEnv, options?: {
-    readonly note?: (line: string) => void;
-}): Promise<CliWallet | null>;
+export declare function optionalCliWallet(env: NodeJS.ProcessEnv, options?: Omit<ResolveCliWalletOptions, "purpose">): Promise<CliWallet | null>;
 /**
  * The raw `METRIK_AGENT_PRIVATE_KEY` read, kept separate so the wallet-source
  * precedence above reads as one list rather than as nested conditionals.
  */
 export declare function optionalCliAccount(env: NodeJS.ProcessEnv): LocalAccount | null;
+/**
+ * Refuses an account that genuinely cannot sign — and nothing else.
+ *
+ * Two distinct capabilities are checked, because two distinct things fail:
+ *
+ *  - `signTypedData` is needed by EVERY command. Fund-moving commands self-sign
+ *    an EIP-712 `SpendMandate`; `invoke` signs an EIP-712
+ *    `InvocationCapability`. Without it the run dies at the first signature
+ *    with a `TypeError` from inside viem.
+ *  - A LOCAL account is needed only where the CLI broadcasts through
+ *    `http(--rpc-url)`, which cannot sign. A Privy account is deliberately NOT
+ *    local: its provider is the transport and performs `eth_sendTransaction`
+ *    itself, so demanding locality there would reject a wallet that works.
+ *
+ * The earlier version of this guard collapsed both into "must be local", which
+ * is why Privy was refused. Deleting the guard outright was not the fix: it
+ * exists so a broken wallet fails here, named, instead of deep inside viem.
+ */
+export declare function assertCliSigner(account: Account, source: CliWalletSource): CliSignerAccount;
 //# sourceMappingURL=wallet.d.ts.map

package/dist/cli/wallet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../src/cli/wallet.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAW,YAAY,EAAE,MAAM,MAAM,CAAC;AAKlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAE1D,qFAAqF;AACrF,eAAO,MAAM,YAAY,uGAKf,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,YAAY,CAAC;AAQtD,8EAA8E;AAC9E,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,KAAK,CAAC;AAEpD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAMD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,GAAE;IACP,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC,GACL,OAAO,CAAC,SAAS,CAAC,CASpB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GACvD,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAqE3B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,YAAY,GAAG,IAAI,CASrB"}
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../src/cli/wallet.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAE7D,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,gCAAgC,CAAC;AAGtF,OAAO,EAKL,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAE1D,qFAAqF;AACrF,eAAO,MAAM,YAAY,uGAKf,CAAC;AAEX,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,YAAY,CAAC;AAQtD,8EAA8E;AAC9E,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,KAAK,GAAG,oBAAoB,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC;AAE7E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;OASG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC5D;AAOD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,+BAA+B,CAAC;IACjD,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,SAAS,CAAC,CASpB;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,eAAe,GACtB,MAAM,IAAI,oBAAoB,CAEhC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,IAAI,SAAS,GAAG;IACzE,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC3D,CAEA;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,GAAE,IAAI,CAAC,uBAAuB,EAAE,SAAS,CAAM,GACrD,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CA6C3B;AAuDD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,YAAY,GAAG,IAAI,CASrB;AAWD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,eAAe,GACtB,gBAAgB,CAclB"}

package/dist/cli/wallet.js

@@ -1,6 +1,7 @@
 import { privateKeyToAccount } from "viem/accounts";
 import { resolveAgentWallet } from "../wallet/provider.js";
 import { configError } from "./errors.js";
+import { PRIVY_ENV_VARS, PRIVY_SESSION_ENV_VARS, PRIVY_WALLET_KEY_ENV, resolvePrivyCliWallet, } from "./privy.js";
 /**
  * The ONLY place the CLI resolves a signing wallet.
  *
@@ -15,32 +16,33 @@ import { configError } from "./errors.js";
  *  1. `METRIK_AGENT_PRIVATE_KEY` — a raw Base Sepolia test key.
  *  2. The `CDP_*` / `METRIK_AGENT_CDP_*` quartet — a Coinbase CDP Server Wallet
  *     v2 account, resolved through this package's own `resolveAgentWallet()`.
+ *  3. The `METRIK_AGENT_PRIVY_*` variables — a Privy wallet reached through a
+ *     broker, either agent-owned (`METRIK_AGENT_PRIVY_WALLET_KEY`) or a
+ *     user-owned broker session. See `./privy.ts`.
  *
- * The order matches `parseAgentWalletEnv()` (the MCP server's resolution), so
- * one environment configures every surface the same way. It is checked in a
- * FIXED order rather than "whichever is configured", because an environment
- * carrying both is ambiguous about which address funds the stream — and that
- * ambiguity is a fund-moving one. When both are present the private key wins
- * and `resolveCliWallet` says so on stderr rather than silently picking.
+ * The first two match `parseAgentWalletEnv()` (the MCP server's resolution), so
+ * one environment configures those surfaces the same way. The order is FIXED
+ * rather than "whichever is configured", because an environment carrying two is
+ * ambiguous about which address funds the stream — and that ambiguity is a
+ * fund-moving one. When more than one is present the earlier entry wins and
+ * `resolveCliWallet` says so on stderr rather than silently picking.
  *
- * ## Why CDP is wired and Privy is not
+ * ## What is different about Privy
  *
- * CDP is the only wallet path in this package with live CI evidence
- * (`scripts/e2e-cdp.ts` drives the full journey against the real Base Sepolia
- * escrow), and its account signs LOCALLY — `toAccount(cdpServerAccount)` is a
- * viem local account, so it drops straight into the CLI's existing
- * `http(rpcUrl)` transport with no other change.
+ * A private key and a CDP account both sign LOCALLY: `privateKeyToAccount()`
+ * and `toAccount(cdpServerAccount)` are viem local accounts, so they drop
+ * straight into the CLI's `http(rpcUrl)` transport with no other change.
  *
- * Privy does not. Both Privy adapters in `src/wallet/` produce a JSON-RPC
- * account with no `signTransaction`: they sign and broadcast by sending
- * `eth_sendTransaction` / `eth_signTypedData_v4` to a provider, so they need the
- * wallet client's TRANSPORT to be that provider rather than a plain RPC. Wiring
- * that into the CLI is not a matter of reading three more variables — it
- * changes the transport for every fund-moving command, and `metrik invoke`
- * additionally requires a local signer (`InvokeOptions.buyer: LocalAccount`).
- * `assertLocalSigner` below therefore REFUSES a non-local account with that
- * fact, instead of accepting one and failing later inside viem. See
- * `docs/cli.md` § Wallet.
+ * Privy does not. Its account is a JSON-RPC account with no `signTransaction`:
+ * it signs and broadcasts by sending `eth_sendTransaction` /
+ * `eth_signTypedData_v4` to a provider, so the wallet client's TRANSPORT must
+ * be that provider rather than a plain RPC. That is what {@link CliWallet.transport}
+ * carries, and the only reason this file knows Privy exists. The signer check
+ * below is therefore about CAPABILITY, not about locality: it refuses an
+ * account that genuinely cannot sign, and refuses a non-local account only on
+ * the paths that broadcast through `--rpc-url`.
+ *
+ * See `docs/cli.md` § Wallet.
  */
 export const PRIVATE_KEY_ENV = "METRIK_AGENT_PRIVATE_KEY";
 /** Every environment variable the CDP path reads. Named in errors, never printed. */
@@ -50,26 +52,41 @@ export const CDP_ENV_VARS = [
     "CDP_WALLET_SECRET",
     "METRIK_AGENT_CDP_OWNER_NAME",
 ];
+export { PRIVY_ENV_VARS, PRIVY_SESSION_ENV_VARS, PRIVY_WALLET_KEY_ENV, } from "./privy.js";
 const PURPOSE_TEXT = {
     transaction: "signs a transaction",
     capability: "signs an off-chain EIP-712 invocation capability (no transaction is broadcast)",
 };
-const WALLET_HINT = `export ${PRIVATE_KEY_ENV}=0x… (a funded Base Sepolia test key), or configure a Coinbase CDP wallet with ` +
-    `${CDP_ENV_VARS.join(", ")}. Both are read from the environment only — never pass a credential as a command-line flag.`;
+const WALLET_HINT = `export ${PRIVATE_KEY_ENV}=0x… (a funded Base Sepolia test key), configure a Coinbase CDP wallet with ` +
+    `${CDP_ENV_VARS.join(", ")}, or configure a Privy wallet with ${PRIVY_WALLET_KEY_ENV} (agent-owned) or ` +
+    `${PRIVY_SESSION_ENV_VARS.join(", ")} (broker session). All are read from the environment only — never pass a credential as a command-line flag.`;
 /**
  * Resolves the signing wallet, or throws an actionable configuration error.
  *
- * `note` receives one line when the environment is ambiguous (both wallet
- * sources configured). It is optional so `resolveCliWallet` stays usable from a
- * context with no printer; commands always pass `out.note`.
+ * `note` receives one line when the environment is ambiguous (more than one
+ * wallet source configured). It is optional so `resolveCliWallet` stays usable
+ * from a context with no printer; commands always pass `out.note`.
  */
 export async function resolveCliWallet(env, options = {}) {
     const wallet = await optionalCliWallet(env, options);
     if (wallet === null) {
-        throw configError(`this command ${PURPOSE_TEXT[options.purpose ?? "transaction"]} and needs a wallet: neither ${PRIVATE_KEY_ENV} nor the CDP variables are set`, WALLET_HINT);
+        throw configError(`this command ${PURPOSE_TEXT[options.purpose ?? "transaction"]} and needs a wallet: none of ${PRIVATE_KEY_ENV}, the CDP variables or the Privy variables are set`, WALLET_HINT);
     }
     return wallet;
 }
+/** True for both Privy shapes, which reach their key through a broker. */
+export function isPrivyWalletSource(source) {
+    return source === "privy-autonomous" || source === "privy-session";
+}
+/**
+ * Whether this wallet's ceiling is enforced somewhere the CLI cannot reach.
+ *
+ * The one question every fund-moving command asks before deciding whether to
+ * self-sign a `SpendMandate`. See `./spend-policy.ts`.
+ */
+export function isPolicyEnforced(wallet) {
+    return wallet.readSpendPolicy !== undefined;
+}
 /**
  * The same resolution, but "nothing configured" is not an error. Used by
  * look-before-you-leap paths (`open --dry-run`, `streams --address`) that
@@ -79,14 +96,19 @@ export async function resolveCliWallet(env, options = {}) {
  * A wallet that is PARTIALLY configured is still an error here: "you set three
  * of the four CDP variables" and "you configured no wallet" are different
  * facts, and rendering the first as the second sends the reader looking in the
- * wrong place.
+ * wrong place. The same rule applies to a partial Privy setup.
  */
 export async function optionalCliWallet(env, options = {}) {
     const privateKeyAccount = optionalCliAccount(env);
     const cdpConfigured = CDP_ENV_VARS.some((name) => isSet(env[name]));
+    const privyConfigured = PRIVY_ENV_VARS.some((name) => isSet(env[name]));
     if (privateKeyAccount !== null) {
-        if (cdpConfigured) {
-            options.note?.(`warning: both ${PRIVATE_KEY_ENV} and CDP wallet variables are set; using ${PRIVATE_KEY_ENV} (${privateKeyAccount.address}). Unset it to sign with the CDP wallet.`);
+        const shadowed = [
+            ...(cdpConfigured ? ["CDP"] : []),
+            ...(privyConfigured ? ["Privy"] : []),
+        ];
+        if (shadowed.length > 0) {
+            options.note?.(`warning: both ${PRIVATE_KEY_ENV} and ${shadowed.join(" and ")} wallet variables are set; using ${PRIVATE_KEY_ENV} (${privateKeyAccount.address}). Unset it to sign with the ${shadowed[0]} wallet.`);
         }
         return {
             source: "private-key",
@@ -94,8 +116,29 @@ export async function optionalCliWallet(env, options = {}) {
             description: `${privateKeyAccount.address} (from ${PRIVATE_KEY_ENV})`,
         };
     }
-    if (!cdpConfigured)
+    if (cdpConfigured) {
+        if (privyConfigured) {
+            options.note?.("warning: both CDP and Privy wallet variables are set; using the CDP wallet. Unset the CDP variables to sign with the Privy wallet.");
+        }
+        return await resolveCdpWallet(env);
+    }
+    if (!privyConfigured)
         return null;
+    const privy = await resolvePrivyCliWallet(env, options);
+    // Unreachable: `privyConfigured` is exactly the condition under which
+    // `resolvePrivyCliWallet` returns non-null or throws. Kept so a future change
+    // to either predicate fails loudly here rather than as a null deref.
+    if (privy === null)
+        return null;
+    return {
+        source: privy.source,
+        account: assertCliSigner(privy.account, privy.source),
+        transport: privy.transport,
+        description: privy.description,
+        readSpendPolicy: privy.readSpendPolicy,
+    };
+}
+async function resolveCdpWallet(env) {
     const missing = CDP_ENV_VARS.filter((name) => !isSet(env[name]));
     if (missing.length > 0) {
         throw configError(`the CDP wallet is partially configured: ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not set`, `a CDP wallet needs all of ${CDP_ENV_VARS.join(", ")}. Set the missing one${missing.length === 1 ? "" : "s"}, or unset the others and use ${PRIVATE_KEY_ENV} instead.`);
@@ -130,7 +173,7 @@ export async function optionalCliWallet(env, options = {}) {
     }
     return {
         source: "cdp",
-        account: assertLocalSigner(account, "cdp"),
+        account: assertCliSigner(account, "cdp"),
         description: `${account.address} (CDP account "${ownerName}")`,
     };
 }
@@ -148,17 +191,39 @@ export function optionalCliAccount(env) {
     return privateKeyToAccount(raw);
 }
 /**
- * Every CLI signing path needs a LOCAL signer: fund-moving commands broadcast
- * through `http(--rpc-url)`, which cannot sign, and `invoke` needs a
- * `LocalAccount` to sign the EIP-712 capability. A JSON-RPC account (Privy's
- * adapters) would type-check as an `Account` and then fail somewhere inside
- * viem with a message about a missing method, so it is rejected here with the
- * actual reason.
+ * Whether this wallet source broadcasts through the CLI's own
+ * `http(--rpc-url)` transport, and therefore needs an account that can produce
+ * a signed raw transaction by itself.
+ */
+function broadcastsLocally(source) {
+    return source === "private-key" || source === "cdp";
+}
+/**
+ * Refuses an account that genuinely cannot sign — and nothing else.
+ *
+ * Two distinct capabilities are checked, because two distinct things fail:
+ *
+ *  - `signTypedData` is needed by EVERY command. Fund-moving commands self-sign
+ *    an EIP-712 `SpendMandate`; `invoke` signs an EIP-712
+ *    `InvocationCapability`. Without it the run dies at the first signature
+ *    with a `TypeError` from inside viem.
+ *  - A LOCAL account is needed only where the CLI broadcasts through
+ *    `http(--rpc-url)`, which cannot sign. A Privy account is deliberately NOT
+ *    local: its provider is the transport and performs `eth_sendTransaction`
+ *    itself, so demanding locality there would reject a wallet that works.
+ *
+ * The earlier version of this guard collapsed both into "must be local", which
+ * is why Privy was refused. Deleting the guard outright was not the fix: it
+ * exists so a broken wallet fails here, named, instead of deep inside viem.
  */
-function assertLocalSigner(account, source) {
-    if (account.type === "local")
-        return account;
-    throw configError(`the ${source} wallet returned a ${account.type} account, which cannot sign locally`, "the CLI broadcasts through --rpc-url and signs EIP-712 capabilities in-process, so it needs a local signer.");
+export function assertCliSigner(account, source) {
+    if (typeof account.signTypedData !== "function") {
+        throw configError(`the ${source} wallet (${account.address}) cannot sign EIP-712 typed data`, "every command signs typed data: fund-moving commands self-sign a spend mandate, and `invoke` signs an invocation capability.");
+    }
+    if (broadcastsLocally(source) && account.type !== "local") {
+        throw configError(`the ${source} wallet returned a ${account.type} account, which cannot sign locally`, "this wallet source broadcasts through --rpc-url, which cannot sign, so it needs a local signer.");
+    }
+    return account;
 }
 function isSet(value) {
     return value !== undefined && value.length > 0;

package/dist/cli/wallet.js.map

@@ -1 +1 @@
-{"version":3,"file":"wallet.js","sourceRoot":"","sources":["../../src/cli/wallet.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wallet.js","sourceRoot":"","sources":["../../src/cli/wallet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAIpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,GAGtB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,0BAA0B,CAAC;AAE1D,qFAAqF;AACrF,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,gBAAgB;IAChB,oBAAoB;IACpB,mBAAmB;IACnB,6BAA6B;CACrB,CAAC;AAEX,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AASpB,MAAM,YAAY,GAA+B;IAC/C,WAAW,EAAE,qBAAqB;IAClC,UAAU,EACR,gFAAgF;CACnF,CAAC;AAwCF,MAAM,WAAW,GACf,UAAU,eAAe,8EAA8E;IACvG,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,sCAAsC,oBAAoB,oBAAoB;IACxG,GAAG,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,6GAA6G,CAAC;AAqBpJ;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAsB,EACtB,UAAmC,EAAE;IAErC,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACrD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,WAAW,CACf,gBAAgB,YAAY,CAAC,OAAO,CAAC,OAAO,IAAI,aAAa,CAAC,gCAAgC,eAAe,oDAAoD,EACjK,WAAW,CACZ,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB,CACjC,MAAuB;IAEvB,OAAO,MAAM,KAAK,kBAAkB,IAAI,MAAM,KAAK,eAAe,CAAC;AACrE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAiB;IAGhD,OAAO,MAAM,CAAC,eAAe,KAAK,SAAS,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAsB,EACtB,UAAoD,EAAE;IAEtD,MAAM,iBAAiB,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,aAAa,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,eAAe,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAExE,IAAI,iBAAiB,KAAK,IAAI,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG;YACf,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACjC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACtC,CAAC;QACF,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,EAAE,CACZ,iBAAiB,eAAe,QAAQ,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,oCAAoC,eAAe,KAAK,iBAAiB,CAAC,OAAO,gCAAgC,QAAQ,CAAC,CAAC,CAAC,UAAU,CACrM,CAAC;QACJ,CAAC;QACD,OAAO;YACL,MAAM,EAAE,aAAa;YACrB,OAAO,EAAE,iBAAiB;YAC1B,WAAW,EAAE,GAAG,iBAAiB,CAAC,OAAO,UAAU,eAAe,GAAG;SACtE,CAAC;IACJ,CAAC;IAED,IAAI,aAAa,EAAE,CAAC;QAClB,IAAI,eAAe,EAAE,CAAC;YACpB,OAAO,CAAC,IAAI,EAAE,CACZ,oIAAoI,CACrI,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC;IAElC,MAAM,KAAK,GAAG,MAAM,qBAAqB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACxD,sEAAsE;IACtE,8EAA8E;IAC9E,qEAAqE;IACrE,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,eAAe,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC;QACrD,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,eAAe,EAAE,KAAK,CAAC,eAAe;KACvC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,GAAsB;IACpD,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,WAAW,CACf,2CAA2C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,UAAU,EAC9G,6BAA6B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,wBAAwB,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,iCAAiC,eAAe,WAAW,CACvK,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,2EAA2E;IAC3E,8EAA8E;IAC9E,0EAA0E;IAC1E,2DAA2D;IAC3D,IACE,KAAK,CAAC,GAAG,CAAC,mCAAmC,CAAC;QAC9C,QAAQ,CAAC,GAAG,CAAC,qCAAqC,CAAC,EACnD,CAAC;QACD,MAAM,WAAW,CACf,kIAAkI,EAClI,4SAA4S,CAC7S,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,GAAG,CAAC,2BAAqC,CAAC;IAC5D,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC;YACxC,GAAG,EAAE;gBACH,QAAQ,EAAE,GAAG,CAAC,cAAwB;gBACtC,YAAY,EAAE,GAAG,CAAC,kBAA4B;gBAC9C,YAAY,EAAE,GAAG,CAAC,iBAA2B;gBAC7C,SAAS;aACV;SACF,CAAC,CAAC;QACH,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0EAA0E;QAC1E,2EAA2E;QAC3E,mDAAmD;QACnD,MAAM,WAAW,CACf,qCAAqC,SAAS,GAAG,EACjD,SAAS,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,gGAAgG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACzL,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM,EAAE,KAAK;QACb,OAAO,EAAE,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC;QACxC,WAAW,EAAE,GAAG,OAAO,CAAC,OAAO,kBAAkB,SAAS,IAAI;KAC/D,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAsB;IAEtB,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,WAAW,CACf,GAAG,eAAe,gDAAgD,CACnE,CAAC;IACJ,CAAC;IACD,OAAO,mBAAmB,CAAC,GAAoB,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,MAAuB;IAChD,OAAO,MAAM,KAAK,aAAa,IAAI,MAAM,KAAK,KAAK,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAgB,EAChB,MAAuB;IAEvB,IAAI,OAAO,OAAO,CAAC,aAAa,KAAK,UAAU,EAAE,CAAC;QAChD,MAAM,WAAW,CACf,OAAO,MAAM,YAAY,OAAO,CAAC,OAAO,kCAAkC,EAC1E,8HAA8H,CAC/H,CAAC;IACJ,CAAC;IACD,IAAI,iBAAiB,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC1D,MAAM,WAAW,CACf,OAAO,MAAM,sBAAsB,OAAO,CAAC,IAAI,qCAAqC,EACpF,iGAAiG,CAClG,CAAC;IACJ,CAAC;IACD,OAAO,OAA2B,CAAC;AACrC,CAAC;AAED,SAAS,KAAK,CAAC,KAAyB;IACtC,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,QAAQ,CAAC,KAAyB;IACzC,OAAO,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,GAAG,CAAC;AAC3C,CAAC"}

package/dist/gateway/caller-auth-gateway.d.ts

@@ -1,4 +1,6 @@
 import { type Address, type Hex } from "viem";
+import { type AcceptedX402Payment, type GatewayX402Mode } from "./x402-mode.js";
+import type { X402PaymentRequiredBody } from "../x402/payment-requirements.js";
 import { type SignedInvocationCapability } from "../capability/invocation-capability.js";
 /**
  * Seller-side caller-auth gateway (metrik-agent#63, impl of #62 part 1/2).
@@ -43,7 +45,21 @@ import { type SignedInvocationCapability } from "../capability/invocation-capabi
  *    direction here: negative, never positive.
  */
 /** Machine-readable, closed set of rejection reasons - every failure mode is distinct. */
-export type CallerAuthDenialReason = "missing-capability-header" | "malformed-capability-header" | "capability-expired" | "invalid-signature" | "method-mismatch" | "path-mismatch" | "service-ref-mismatch" | "nonce-replayed" | "stream-not-found" | "buyer-mismatch" | "stream-not-active" | "stream-expired" | "stream-not-funded" | "stream-state-stale";
+export type CallerAuthDenialReason = "missing-capability-header" | "malformed-capability-header" | "capability-expired" | "invalid-signature" | "method-mismatch" | "path-mismatch" | "service-ref-mismatch" | "nonce-replayed" | "stream-not-found" | "buyer-mismatch" | "stream-not-active" | "stream-expired" | "stream-not-funded" | "stream-state-stale"
+/**
+ * No Metrik capability, and x402 mode is enabled: the caller may pay per call
+ * instead. Carries an x402 `402` body in
+ * {@link CallerAuthDecision.x402PaymentRequired}. Emitted ONLY when
+ * {@link CallerAuthGatewayConfig.x402} is configured — without it, a missing
+ * capability is still `missing-capability-header` / `403`, unchanged.
+ */
+ | "x402-payment-required"
+/**
+ * The request carried BOTH a Metrik capability and an `X-PAYMENT` header.
+ * Refused rather than guessed: serving it would charge the caller through one
+ * path while they believe they paid through the other.
+ */
+ | "ambiguous-payment-mode";
 /**
  * Default freshness bound for on-chain stream state, in seconds. Base blocks
  * are ~2s, so a healthy endpoint is a few seconds stale at most; this is a
@@ -57,11 +73,22 @@ export interface CallerAuthDecision {
     readonly authorized: boolean;
     readonly reason?: CallerAuthDenialReason;
     /** Set only when `authorized === false`. */
-    readonly httpStatus?: 402 | 403;
-    /** Set only when `authorized === true`. */
+    readonly httpStatus?: 400 | 402 | 403;
+    /** Set only when `authorized === true` via the Metrik stream path. */
     readonly stream?: GatewayStreamView;
     /** The decoded (but not necessarily valid) capability, when one was present. */
     readonly capability?: SignedInvocationCapability;
+    /**
+     * The x402 `402` body to return verbatim. Set only with
+     * `reason === "x402-payment-required"`.
+     */
+    readonly x402PaymentRequired?: X402PaymentRequiredBody;
+    /**
+     * A verified x402 payment. Set only when `authorized === true` via the x402
+     * path. The caller MUST settle it (see `./x402-mode.ts`) — verification alone
+     * moves no money.
+     */
+    readonly x402Payment?: AcceptedX402Payment;
 }
 /** The minimal on-chain stream fields the gateway needs to authorize a call. */
 export interface GatewayStreamView {
@@ -178,6 +205,13 @@ export interface CallerAuthGatewayConfig {
     readonly nonceCache?: NonceReplayCache;
     /** Injectable clock (unix seconds), for tests. */
     readonly now?: () => number;
+    /**
+     * Optional standard-x402 mode. When set, a request with NO Metrik capability
+     * gets a real x402 `402` challenge instead of a `403`, so a caller holding
+     * only `x402-fetch` can pay per call. Leaving it unset preserves today's
+     * behaviour byte for byte.
+     */
+    readonly x402?: GatewayX402Mode;
 }
 export interface CallerAuthRequestInput {
     /** Lower-cased-lookup-safe header map (e.g. Node's `IncomingMessage.headers`). */
@@ -201,6 +235,7 @@ export declare class CallerAuthGateway {
     private readonly domain;
     private readonly serviceRefs;
     private readonly now;
+    private readonly x402;
     constructor(config: CallerAuthGatewayConfig);
     authorize(request: CallerAuthRequestInput): Promise<CallerAuthDecision>;
     /** Returns the denial reason this single view produces, or `undefined` if it authorizes. */

package/dist/gateway/caller-auth-gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"caller-auth-gateway.d.ts","sourceRoot":"","sources":["../../src/gateway/caller-auth-gateway.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"caller-auth-gateway.d.ts","sourceRoot":"","sources":["../../src/gateway/caller-auth-gateway.ts"],"names":[],"mappings":"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"}

package/dist/gateway/caller-auth-gateway.js

@@ -1,5 +1,6 @@
 import { MetrikClient } from "@absol-labs/sdk";
 import { isAddress, isHex } from "viem";
+import { evaluateX402Request, X402_PAYMENT_HEADER, } from "./x402-mode.js";
 import { CAPABILITY_HEADER_NAME, decodeCapabilityHeader, hashInvocationPath, InvalidCapabilityHeaderError, recoverInvocationCapabilitySigner, } from "../capability/invocation-capability.js";
 /**
  * Default freshness bound for on-chain stream state, in seconds. Base blocks
@@ -149,6 +150,7 @@ export class CallerAuthGateway {
     domain;
     serviceRefs;
     now;
+    x402;
     constructor(config) {
         if (!isAddress(config.escrowAddress)) {
             throw new Error("escrowAddress must be an EVM address");
@@ -191,10 +193,32 @@ export class CallerAuthGateway {
             verifyingContract: config.escrowAddress,
         };
         this.now = config.now ?? (() => Math.floor(Date.now() / 1000));
+        this.x402 = config.x402;
     }
     async authorize(request) {
         const headerValue = lookupHeader(request.headers, this.headerName);
-        if (headerValue === undefined || headerValue.length === 0) {
+        const hasCapabilityHeader = headerValue !== undefined && headerValue.length > 0;
+        if (this.x402 !== undefined) {
+            const paymentHeader = lookupHeader(request.headers, X402_PAYMENT_HEADER);
+            const hasPaymentHeader = paymentHeader !== undefined && paymentHeader.trim().length > 0;
+            // Exactly one payment mode per request. See `./x402-mode.ts`.
+            if (hasCapabilityHeader && hasPaymentHeader) {
+                return deny("ambiguous-payment-mode", 400);
+            }
+            if (!hasCapabilityHeader) {
+                const evaluated = await evaluateX402Request({ method: request.method, path: request.path }, paymentHeader, this.x402);
+                if (evaluated.outcome === "accepted") {
+                    return { authorized: true, x402Payment: evaluated.payment };
+                }
+                return {
+                    authorized: false,
+                    reason: "x402-payment-required",
+                    httpStatus: 402,
+                    x402PaymentRequired: evaluated.body,
+                };
+            }
+        }
+        if (!hasCapabilityHeader) {
             return deny("missing-capability-header", 403);
         }
         let capability;