@jaw.id/cli 0.1.26 → 0.2.1

package/dist/commands/session/setup.js

@@ -1,9 +1,11 @@
 import { Command, Flags } from '@oclif/core';
-import * as fs from 'fs';
+import * as fs4 from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
 import WebSocket from 'ws';
+import { parseUnits, formatUnits, erc20Abi, createPublicClient, http } from 'viem';
+import { polygonAmoy, polygon, baseSepolia, base } from 'viem/chains';
 
 // src/commands/session/setup.ts
 var JAW_DIR = path.join(os.homedir(), ".jaw");
@@ -13,13 +15,15 @@ var PATHS = {
   session: path.join(JAW_DIR, "session.json"),
   relay: path.join(JAW_DIR, "relay.json"),
   keystore: path.join(JAW_DIR, "keystore.json"),
-  sessionConfig: path.join(JAW_DIR, "session-config.json")
+  sessionConfig: path.join(JAW_DIR, "session-config.json"),
+  x402Log: path.join(JAW_DIR, "x402-log.jsonl"),
+  paymentLock: path.join(JAW_DIR, "x402-payment.lock")
 };
 
 // src/lib/validation.ts
 var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 var SELECTOR_RE = /^0x[0-9a-fA-F]{8}$/;
-var HEX_RE = /^0x[0-9a-fA-F]+$/;
+var ALLOWANCE_RE = /^(0x[0-9a-fA-F]+|[0-9]+)$/;
 var VALID_SPEND_UNITS = /* @__PURE__ */ new Set(["minute", "hour", "day", "week", "month", "year", "forever"]);
 function parsePermissionsConfig(raw) {
   const errors = [];
@@ -64,8 +68,8 @@ function parsePermissionsConfig(raw) {
         if (typeof s.token !== "string" || !ADDRESS_RE.test(s.token)) {
           errors.push(`spends.${i}.token: Must be a valid 0x address (40 hex chars)`);
         }
-        if (typeof s.allowance !== "string" || !HEX_RE.test(s.allowance)) {
-          errors.push(`spends.${i}.allowance: Must be a non-empty 0x hex value`);
+        if (typeof s.allowance !== "string" || !ALLOWANCE_RE.test(s.allowance)) {
+          errors.push(`spends.${i}.allowance: Must be a decimal or 0x hex integer`);
         }
         if (typeof s.unit !== "string" || !VALID_SPEND_UNITS.has(s.unit)) {
           errors.push(`spends.${i}.unit: Must be one of: ${[...VALID_SPEND_UNITS].join(", ")}`);
@@ -106,8 +110,8 @@ function isValidRelayUrl(url) {
 
 // src/lib/config.ts
 function ensureDir(dir) {
-  fs.mkdirSync(dir, { recursive: true, mode: 448 });
-  fs.chmodSync(dir, 448);
+  fs4.mkdirSync(dir, { recursive: true, mode: 448 });
+  fs4.chmodSync(dir, 448);
 }
 function migrateConfig(config) {
   if (config.paymasterUrl && !config.paymasters) {
@@ -119,10 +123,10 @@ function migrateConfig(config) {
   return config;
 }
 function loadConfig() {
-  if (!fs.existsSync(PATHS.config)) {
+  if (!fs4.existsSync(PATHS.config)) {
     return {};
   }
-  const raw = fs.readFileSync(PATHS.config, "utf-8");
+  const raw = fs4.readFileSync(PATHS.config, "utf-8");
   try {
     const config = JSON.parse(raw);
     return migrateConfig(config);
@@ -134,7 +138,7 @@ function loadConfig() {
 }
 function saveConfig(config) {
   ensureDir(PATHS.root);
-  fs.writeFileSync(PATHS.config, JSON.stringify(config, null, 2) + "\n", {
+  fs4.writeFileSync(PATHS.config, JSON.stringify(config, null, 2) + "\n", {
     encoding: "utf-8",
     mode: 384
   });
@@ -288,7 +292,18 @@ function bufferToBase64(buf) {
 }
 
 // src/lib/ws-bridge.ts
+function buildInitPayload(config) {
+  return {
+    type: "init",
+    apiKey: config.apiKey,
+    chainId: config.chainId,
+    ens: config.ens,
+    paymasterUrl: config.paymasterUrl,
+    ...config.paymasterUrl && config.paymasterContext ? { paymasterContext: config.paymasterContext } : {}
+  };
+}
 var DEFAULT_TIMEOUT_MS = 12e4;
+var DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
 var MAX_MESSAGE_BYTES = 5 * 1024 * 1024;
 var BROWSER_REOPEN_COOLDOWN_MS = 5e3;
 var MAX_RECONNECT_ATTEMPTS = 3;
@@ -297,6 +312,7 @@ var WSBridge = class {
   relayUrl;
   session;
   timeout;
+  connectTimeout;
   config;
   privateKeyHex;
   publicKeyHex;
@@ -318,6 +334,7 @@ var WSBridge = class {
     this.relayUrl = options.relayUrl;
     this.session = options.session;
     this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.connectTimeout = options.connectTimeout ?? DEFAULT_CONNECT_TIMEOUT_MS;
     this.config = options.config;
     this.privateKeyHex = options.privateKeyHex;
     this.publicKeyHex = options.publicKeyHex;
@@ -346,17 +363,16 @@ var WSBridge = class {
       let expectingKeyExchange = !this.peerPublicKeyHex;
       const timer = setTimeout(() => {
         ws.close();
-        reject(new Error("Browser did not connect in time.\nRun `jaw disconnect` then try again."));
-      }, 3e4);
+        reject(
+          new Error(
+            `Browser did not connect within ${Math.round(this.connectTimeout / 1e3)}s.
+Run \`jaw disconnect\` then try again, or raise JAW_BRIDGE_TIMEOUT_MS.`
+          )
+        );
+      }, this.connectTimeout);
       const sendEncryptedInit = async () => {
         if (!this.sharedSecret) return;
-        const envelope = await encryptMessage(this.sharedSecret, {
-          type: "init",
-          apiKey: this.config.apiKey,
-          chainId: this.config.chainId,
-          ens: this.config.ens,
-          paymasterUrl: this.config.paymasterUrl
-        });
+        const envelope = await encryptMessage(this.sharedSecret, buildInitPayload(this.config));
         this.sendRaw(ws, JSON.stringify({ type: "encrypted", ...envelope }));
       };
       const waitForReady = () => {
@@ -604,8 +620,8 @@ function safeParse(data) {
 }
 function loadRelaySession() {
   try {
-    if (!fs.existsSync(PATHS.relay)) return null;
-    const raw = fs.readFileSync(PATHS.relay, "utf-8");
+    if (!fs4.existsSync(PATHS.relay)) return null;
+    const raw = fs4.readFileSync(PATHS.relay, "utf-8");
     const parsed = JSON.parse(raw);
     if (!parsed.session || !parsed.relayUrl || !parsed.privateKey || !parsed.publicKey) {
       return null;
@@ -617,14 +633,14 @@ function loadRelaySession() {
 }
 function saveRelaySession(info) {
   ensureDir(PATHS.root);
-  fs.writeFileSync(PATHS.relay, JSON.stringify(info, null, 2) + "\n", {
+  fs4.writeFileSync(PATHS.relay, JSON.stringify(info, null, 2) + "\n", {
     encoding: "utf-8",
     mode: 384
   });
 }
 function deleteRelaySession() {
   try {
-    if (fs.existsSync(PATHS.relay)) fs.unlinkSync(PATHS.relay);
+    if (fs4.existsSync(PATHS.relay)) fs4.unlinkSync(PATHS.relay);
   } catch {
   }
 }
@@ -634,6 +650,10 @@ var DEFAULT_KEYS_URL = "https://keys.jaw.id";
 var DEFAULT_RELAY_URL = "wss://relay.jaw.id";
 async function getBridge(options) {
   const config = loadConfig();
+  const envTimeout = Number(process.env["JAW_BRIDGE_TIMEOUT_MS"]);
+  const fromEnv = Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : void 0;
+  const timeout = options.timeout ?? fromEnv;
+  const connectTimeout = options.connectTimeout ?? fromEnv;
   const keysUrl = options.keysUrl ?? config.keysUrl ?? DEFAULT_KEYS_URL;
   const relayUrl = options.relayUrl ?? config.relayUrl ?? DEFAULT_RELAY_URL;
   const chainId = options.chainId ?? config.defaultChain ?? 1;
@@ -646,7 +666,7 @@ async function getBridge(options) {
   let relaySession = loadRelaySession();
   if (relaySession && relaySession.relayUrl === relayUrl && relaySession.peerPublicKey) {
     try {
-      return await connectBridge(relaySession, options, chainId, keysUrl, relayUrl, false);
+      return await connectBridge({ ...options, timeout }, relaySession, chainId, keysUrl, relayUrl, false);
     } catch {
       deleteRelaySession();
       relaySession = null;
@@ -656,7 +676,7 @@ async function getBridge(options) {
   }
   const session = await createNewSession(relayUrl);
   saveRelaySession(session);
-  return await connectBridge(session, options, chainId, keysUrl, relayUrl, true);
+  return await connectBridge({ ...options, timeout, connectTimeout }, session, chainId, keysUrl, relayUrl, true);
 }
 async function createNewSession(relayUrl) {
   const kp = await generateKeyPair();
@@ -671,17 +691,20 @@ async function createNewSession(relayUrl) {
     startedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-async function connectBridge(relaySession, options, chainId, keysUrl, relayUrl, openBrowser) {
+async function connectBridge(options, relaySession, chainId, keysUrl, relayUrl, openBrowser) {
   const config = loadConfig();
+  const paymaster = config.paymasters?.[chainId];
   const bridge = new WSBridge({
     relayUrl,
     session: relaySession.session,
     timeout: options.timeout,
+    connectTimeout: options.connectTimeout,
     config: {
       apiKey: options.apiKey,
       chainId,
       ens: options.ens ?? config.ens,
-      paymasterUrl: options.paymasterUrl ?? config.paymasters?.[chainId]?.url
+      paymasterUrl: paymaster?.url,
+      paymasterContext: paymaster?.context
     },
     privateKeyHex: relaySession.privateKey,
     publicKeyHex: relaySession.publicKey,
@@ -691,6 +714,12 @@ async function connectBridge(relaySession, options, chainId, keysUrl, relayUrl,
     // onBrowserNeeded — only open a browser for new sessions
     openBrowser ? async () => {
       const bridgeUrl = buildBridgeUrl(keysUrl, relaySession.session, relayUrl, relaySession.publicKey);
+      if (process.env["JAW_NO_BROWSER"]) {
+        process.stderr.write(`Open this URL to approve:
+${bridgeUrl}
+`);
+        return;
+      }
       const { default: open } = await import('open');
       await open(bridgeUrl);
     } : void 0,
@@ -721,17 +750,17 @@ function saveKeystore(privateKeyHex, address) {
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   ensureDir(PATHS.root);
-  fs.writeFileSync(PATHS.keystore, JSON.stringify(keystore, null, 2) + "\n", {
+  fs4.writeFileSync(PATHS.keystore, JSON.stringify(keystore, null, 2) + "\n", {
     encoding: "utf-8",
     mode: 384
   });
-  fs.chmodSync(PATHS.keystore, 384);
+  fs4.chmodSync(PATHS.keystore, 384);
 }
 function loadSessionKey() {
-  if (!fs.existsSync(PATHS.keystore)) {
+  if (!fs4.existsSync(PATHS.keystore)) {
     throw new Error("No session configured. Run `jaw session setup` first.");
   }
-  const contents = fs.readFileSync(PATHS.keystore, "utf-8");
+  const contents = fs4.readFileSync(PATHS.keystore, "utf-8");
   let parsed;
   try {
     parsed = JSON.parse(contents);
@@ -740,37 +769,370 @@ function loadSessionKey() {
   }
   return parsed.privateKey;
 }
+function tryLoadKeystoreAddress() {
+  try {
+    if (!fs4.existsSync(PATHS.keystore)) return null;
+    const parsed = JSON.parse(fs4.readFileSync(PATHS.keystore, "utf-8"));
+    return parsed.address ?? null;
+  } catch {
+    return null;
+  }
+}
 function keystoreExists() {
-  return fs.existsSync(PATHS.keystore);
+  return fs4.existsSync(PATHS.keystore);
+}
+var ADDRESS_RE2 = /^0x[0-9a-fA-F]{40}$/;
+var SELECTOR_RE2 = /^0x[0-9a-fA-F]{8}$/;
+var HEX_RE = /^0x[0-9a-fA-F]+$/;
+var ALLOWANCE_RE2 = /^(0x[0-9a-fA-F]+|[0-9]+)$/;
+var SPEND_UNITS = /* @__PURE__ */ new Set(["minute", "hour", "day", "week", "month", "year", "forever"]);
+function isPositiveInt(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function parseGrantedPermission(raw) {
+  if (typeof raw !== "object" || raw === null) return void 0;
+  const r = raw;
+  const { account, spender, salt } = r;
+  if (typeof account !== "string" || !ADDRESS_RE2.test(account)) return void 0;
+  if (typeof spender !== "string" || !ADDRESS_RE2.test(spender)) return void 0;
+  if (typeof salt !== "string" || !HEX_RE.test(salt)) return void 0;
+  if (!isPositiveInt(r.start) || !isPositiveInt(r.end)) return void 0;
+  if (!Array.isArray(r.calls) || r.calls.length === 0) return void 0;
+  const calls = [];
+  for (const entry of r.calls) {
+    if (typeof entry !== "object" || entry === null) return void 0;
+    const { target, selector } = entry;
+    if (typeof target !== "string" || !ADDRESS_RE2.test(target)) return void 0;
+    if (typeof selector !== "string" || !SELECTOR_RE2.test(selector)) return void 0;
+    calls.push({ target, selector });
+  }
+  if (!Array.isArray(r.spends)) return void 0;
+  const spends = [];
+  for (const entry of r.spends) {
+    if (typeof entry !== "object" || entry === null) return void 0;
+    const { token, allowance, unit, multiplier } = entry;
+    if (typeof token !== "string" || !ADDRESS_RE2.test(token)) return void 0;
+    if (typeof allowance !== "string" || !ALLOWANCE_RE2.test(allowance)) return void 0;
+    if (typeof unit !== "string" || !SPEND_UNITS.has(unit)) return void 0;
+    if (!isPositiveInt(multiplier) || multiplier > 65535) return void 0;
+    spends.push({ token, allowance, unit, multiplier });
+  }
+  return { account, spender, start: r.start, end: r.end, salt, calls, spends };
+}
+function liveOrphans(orphans, now = Date.now() / 1e3) {
+  return (orphans ?? []).filter((orphan) => orphan.expiry > now);
 }
 function saveSessionConfig(input) {
-  const config = {
-    ...input,
-    createdAt: (/* @__PURE__ */ new Date()).toISOString()
-  };
+  writeSessionConfig({ ...input, createdAt: input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString() });
+}
+function writeSessionConfig(config) {
   ensureDir(PATHS.root);
-  fs.writeFileSync(PATHS.sessionConfig, JSON.stringify(config, null, 2) + "\n", {
-    encoding: "utf-8",
-    mode: 384
-  });
-  fs.chmodSync(PATHS.sessionConfig, 384);
+  const temp = `${PATHS.sessionConfig}.${process.pid}.tmp`;
+  fs4.writeFileSync(temp, JSON.stringify(config, null, 2) + "\n", { encoding: "utf-8", mode: 384 });
+  fs4.chmodSync(temp, 384);
+  fs4.renameSync(temp, PATHS.sessionConfig);
 }
 function loadSessionConfig() {
-  if (!fs.existsSync(PATHS.sessionConfig)) {
+  if (!fs4.existsSync(PATHS.sessionConfig)) {
     throw new Error("No session configured. Run `jaw session setup` first.");
   }
-  const raw = fs.readFileSync(PATHS.sessionConfig, "utf-8");
+  const raw = fs4.readFileSync(PATHS.sessionConfig, "utf-8");
   try {
     return JSON.parse(raw);
   } catch {
     throw new Error(`Session config at ${PATHS.sessionConfig} is corrupted. Run \`jaw session setup\` to recreate it.`);
   }
 }
+function tryLoadSessionConfig() {
+  try {
+    return loadSessionConfig();
+  } catch {
+    return null;
+  }
+}
+
+// src/x402/asset-registry.ts
+var USDC_BY_NETWORK = {
+  "eip155:8453": {
+    address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    chainId: 8453,
+    wireNetwork: "eip155:8453",
+    usdcName: "USD Coin",
+    usdcVersion: "2",
+    decimals: 6
+  },
+  "eip155:84532": {
+    address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    chainId: 84532,
+    wireNetwork: "eip155:84532",
+    usdcName: "USDC",
+    usdcVersion: "2",
+    decimals: 6
+  },
+  "eip155:137": {
+    address: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+    chainId: 137,
+    wireNetwork: "eip155:137",
+    usdcName: "USD Coin",
+    usdcVersion: "2",
+    decimals: 6
+  },
+  "eip155:80002": {
+    address: "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
+    chainId: 80002,
+    wireNetwork: "eip155:80002",
+    usdcName: "USDC",
+    usdcVersion: "2",
+    decimals: 6
+  }
+};
+function usdcForNetwork(network) {
+  return Object.hasOwn(USDC_BY_NETWORK, network) ? USDC_BY_NETWORK[network] : void 0;
+}
+
+// src/x402/grant-preset.ts
+var TRANSFER_SIGNATURE = "transfer(address,uint256)";
+var MAX_ALLOWANCE = 2n ** 160n - 1n;
+var LIMIT_PERIODS = ["minute", "hour", "day", "week", "month", "year", "forever"];
+var DEFAULT_X402_LIMIT = "10/day";
+function parseLimit(input) {
+  const trimmed = input.trim();
+  if (!trimmed) throw new Error("Limit is empty. Use --limit <amount>/<period>, for example 10/day.");
+  const [rawAmount, rawPeriod = "day", ...rest] = trimmed.split("/");
+  if (rest.length > 0) {
+    throw new Error(`Invalid limit "${input}". Expected <amount>/<period>, for example 10/day.`);
+  }
+  const amount = rawAmount.trim();
+  if (!/^\d+(\.\d+)?$/.test(amount)) {
+    throw new Error(`Invalid limit amount "${rawAmount}". Expected a positive number, for example 10 or 2.5.`);
+  }
+  const period = rawPeriod.trim().toLowerCase();
+  if (!LIMIT_PERIODS.includes(period)) {
+    throw new Error(`Invalid limit period "${rawPeriod}". Expected one of: ${LIMIT_PERIODS.join(", ")}.`);
+  }
+  return { amount, period };
+}
+function buildX402Permissions(chainId, limit = DEFAULT_X402_LIMIT) {
+  const usdc = Object.values(USDC_BY_NETWORK).find((asset) => asset.chainId === chainId);
+  if (!usdc) {
+    const supported = Object.values(USDC_BY_NETWORK).map((a) => a.chainId).sort((a, b) => a - b).join(", ");
+    throw new Error(`No USDC configured for chain ${chainId}. x402 payments are supported on: ${supported}.`);
+  }
+  const { amount, period } = parseLimit(limit);
+  let allowance;
+  try {
+    allowance = parseUnits(amount, usdc.decimals);
+  } catch {
+    throw new Error(`Invalid limit amount "${amount}" for a token with ${usdc.decimals} decimals.`);
+  }
+  if (allowance <= 0n) {
+    throw new Error(`Limit "${limit}" resolves to zero, which would refuse every payment.`);
+  }
+  if (allowance > MAX_ALLOWANCE) {
+    throw new Error(`Limit "${limit}" is larger than a spend allowance can hold (max ${MAX_ALLOWANCE}).`);
+  }
+  return {
+    calls: [{ target: usdc.address, functionSignature: TRANSFER_SIGNATURE }],
+    spends: [{ token: usdc.address, allowance: allowance.toString(), unit: period, multiplier: 1 }]
+  };
+}
+function describeX402Grant(limit = DEFAULT_X402_LIMIT) {
+  const { amount, period } = parseLimit(limit);
+  const per = period === "forever" ? "in total" : `per ${period}`;
+  return `${amount} USDC ${per}, transfers only`;
+}
+var JAW_RPC_URL = "https://api.justaname.id/proxy/v1/rpc";
+var CHAINS = {
+  [base.id]: base,
+  [baseSepolia.id]: baseSepolia,
+  [polygon.id]: polygon,
+  [polygonAmoy.id]: polygonAmoy
+};
+for (const chainId of Object.values(USDC_BY_NETWORK).map((a) => a.chainId)) {
+  if (!CHAINS[chainId]) {
+    throw new Error(
+      `x402 balance: USDC registry has chain ${chainId} but no viem chain is mapped for it in balance.ts`
+    );
+  }
+}
+var clients = /* @__PURE__ */ new Map();
+function rpcTransport(chainId, apiKey) {
+  if (!apiKey) return http();
+  return http(`${JAW_RPC_URL}?chainId=${chainId}&api-key=${apiKey}`);
+}
+function publicClientFor(chainId) {
+  const chain = CHAINS[chainId];
+  if (!chain) throw new Error(`x402: no viem chain configured for chainId ${chainId}`);
+  const apiKey = loadConfig().apiKey;
+  const key = `${chainId}:${apiKey ?? ""}`;
+  let client = clients.get(key);
+  if (!client) {
+    client = createPublicClient({ chain, transport: rpcTransport(chainId, apiKey) });
+    clients.set(key, client);
+  }
+  return client;
+}
+var readOnChain = (asset, owner) => publicClientFor(asset.chainId).readContract({
+  address: asset.address,
+  abi: erc20Abi,
+  functionName: "balanceOf",
+  args: [owner]
+});
+async function usdcBalance(network, owner, read = readOnChain) {
+  const asset = usdcForNetwork(network);
+  if (!asset) throw new Error(`Unsupported x402 network: ${network}`);
+  const raw = await read(asset, owner);
+  return { network, asset: asset.address, raw: raw.toString(), formatted: formatUnits(raw, asset.decimals) };
+}
+
+// src/x402/gas-reserve.ts
+function gasReserve(asset) {
+  return 10n ** BigInt(asset.decimals) / 10n;
+}
+function firstOperationCost(asset) {
+  return 10n ** BigInt(asset.decimals) / 100n;
+}
+
+// src/x402/amount.ts
+function parseBigInt(value) {
+  if (value === void 0 || value === null || value === "") return null;
+  try {
+    return BigInt(value);
+  } catch {
+    return null;
+  }
+}
+
+// src/lib/terminal.ts
+var INVISIBLE_AND_BIDI = /[\u200B-\u200F\u2028\u2029\u202A-\u202E\u2066-\u2069\uFEFF]/g;
+var LINE_CONTROLS = /[\u0000-\u001F\u007F-\u009F]/g;
+var REPLACEMENT = "\uFFFD";
+var DEFAULT_LINE_LENGTH = 200;
+function bound(text, maxLength) {
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength)}\u2026 (${text.length - maxLength} more characters)`;
+}
+function sanitizeLine(value, maxLength = DEFAULT_LINE_LENGTH) {
+  const text = typeof value === "string" ? value : String(value);
+  return bound(text.replace(LINE_CONTROLS, REPLACEMENT).replace(INVISIBLE_AND_BIDI, REPLACEMENT), maxLength);
+}
+
+// src/x402/status-report.ts
+function formatUsdc(base2, decimals) {
+  if (base2 === void 0) return "unlimited";
+  const value = parseBigInt(base2);
+  if (value === null) return `${sanitizeLine(base2, 32)} (invalid)`;
+  const scale = 10n ** BigInt(decimals);
+  const whole = value / scale;
+  const frac = (value % scale).toString().padStart(decimals, "0").replace(/0+$/, "");
+  return `${whole}${frac ? `.${frac}` : ""} USDC`;
+}
+
+// src/x402/funded-owner.ts
+async function whyOwnerCannotFundSession(check) {
+  const asset = usdcForNetwork(`eip155:${check.chainId}`);
+  if (!asset) return null;
+  const accounts = await check.request("eth_requestAccounts");
+  const owner = accounts?.[0];
+  if (!owner) return null;
+  const read = check.readBalance ?? (async (network, address) => BigInt((await usdcBalance(network, address)).raw));
+  let held;
+  try {
+    held = await read(asset.wireNetwork, owner);
+  } catch {
+    return null;
+  }
+  const needed = gasReserve(asset);
+  if (held >= needed) return null;
+  return `${owner} holds ${formatUsdc(held.toString(), asset.decimals)} on chain ${check.chainId}, and setting up a session needs at least ${formatUsdc(needed.toString(), asset.decimals)} there. That much rides along in the grant so the session can pay for its own first transaction. Fund the account and run this again.`;
+}
+async function whySpenderCannotPay(check) {
+  const asset = usdcForNetwork(`eip155:${check.chainId}`);
+  if (!asset) return null;
+  const read = check.readBalance ?? (async (network, address) => BigInt((await usdcBalance(network, address)).raw));
+  let held;
+  let timer;
+  try {
+    const expired = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error("timed out")), check.timeoutMs ?? 5e3);
+    });
+    held = await Promise.race([read(asset.wireNetwork, check.spender), expired]);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+  const needed = firstOperationCost(asset);
+  if (held >= needed) return null;
+  return `${check.spender} holds ${formatUsdc(held.toString(), asset.decimals)} on chain ${check.chainId}, which is not enough to pay for its first operation. The session pays its own gas, and the grant asked this wallet to send it a little along with the permission. Nothing usable arrived: the wallet may not implement that yet, or it could not price the transfer, or the granted allowance was too small to cover one. Send ${formatUsdc(needed.toString(), asset.decimals)} to that address and the session works from there.`;
+}
+
+// src/x402/period.ts
+function describeSpendPeriod(unit, multiplier) {
+  const n = Math.max(1, Math.floor(multiplier ?? 1));
+  return n === 1 ? unit : `${n} ${unit}s`;
+}
+function periodLengthSeconds(unit, multiplier, bound2) {
+  const lengths = {
+    minute: 60,
+    hour: 3600,
+    day: 86400,
+    week: 604800,
+    month: (bound2 === "min" ? 28 : 31) * 86400,
+    year: (bound2 === "min" ? 365 : 366) * 86400,
+    forever: Number.POSITIVE_INFINITY
+  };
+  if (!Object.hasOwn(lengths, unit)) return null;
+  return lengths[unit] * Math.max(1, Math.floor(multiplier));
+}
+
+// src/x402/grant-ceiling.ts
+function whyGrantExceedsCeiling(permissions, chainId, ceiling) {
+  if (!ceiling) return null;
+  let parsed;
+  try {
+    parsed = parseLimit(ceiling);
+  } catch {
+    return `The grant ceiling in your config is not a valid limit: ${ceiling}. Fix it with \`jaw config set grantCeiling <amount>/<period>\`, or remove it.`;
+  }
+  const usdc = Object.values(USDC_BY_NETWORK).find((asset) => asset.chainId === chainId);
+  if (!usdc) {
+    return (permissions.spends ?? []).length > 0 ? `The grant ceiling is set to ${ceiling}, and chain ${chainId} has no USDC in the registry to measure a spend against it. Grant on a supported chain, or remove the ceiling with \`jaw config set grantCeiling ""\`.` : null;
+  }
+  const maxAllowance = parseUnits(parsed.amount, usdc.decimals);
+  const ceilingSeconds = periodLengthSeconds(parsed.period, 1, "max");
+  if (ceilingSeconds === null) return null;
+  for (const spend of permissions.spends ?? []) {
+    if (spend.token.toLowerCase() !== usdc.address.toLowerCase()) {
+      return `The grant ceiling is set to ${ceiling}, and this permission spends ${spend.token}, which cannot be measured against it. Grant USDC, or remove the ceiling with \`jaw config set grantCeiling ""\`.`;
+    }
+    let allowance;
+    try {
+      allowance = BigInt(spend.allowance);
+    } catch {
+      return `This permission asks for an allowance that cannot be read: ${spend.allowance}.`;
+    }
+    if (allowance > maxAllowance) {
+      return `This grant asks for ${formatUsdc(allowance.toString(), usdc.decimals)} per period, over the ${ceiling} ceiling set on this machine. Lower it, or raise the ceiling with \`jaw config set grantCeiling <amount>/<period>\`.`;
+    }
+    const grantSeconds = periodLengthSeconds(spend.unit, spend.multiplier ?? 1, "min");
+    if (grantSeconds === null) {
+      return `This permission uses a spend period this CLI does not recognise: ${spend.unit}.`;
+    }
+    const sameUnit = spend.unit === parsed.period;
+    if (!sameUnit && grantSeconds < ceilingSeconds) {
+      return `This grant resets its allowance every ${describeSpendPeriod(spend.unit, spend.multiplier ?? 1)}, which is more often than the ${ceiling} ceiling set on this machine allows. A shorter period is more money over the same time, even at the same allowance.`;
+    }
+  }
+  return null;
+}
 
 // src/commands/session/setup.ts
 var SessionSetup = class _SessionSetup extends BaseCommand {
   static description = "Generate a session key and grant scoped on-chain permissions (one-time browser approval).";
   static examples = [
+    "<%= config.bin %> session setup --chain 8453 --x402",
+    "<%= config.bin %> session setup --chain 8453 --x402 --limit 25/day --expiry 14",
     "<%= config.bin %> session setup --chain 84532",
     `<%= config.bin %> session setup --permissions '{"calls":[...]}' --expiry 14`,
     "<%= config.bin %> session setup --permissions ./permissions.json"
@@ -778,7 +1140,18 @@ var SessionSetup = class _SessionSetup extends BaseCommand {
   static flags = {
     ...BaseCommand.baseFlags,
     permissions: Flags.string({
-      description: "Permission scope (inline JSON or file path). Overrides config.permissions."
+      description: "Permission scope (inline JSON or file path). Overrides config.permissions.",
+      exclusive: ["x402"]
+    }),
+    x402: Flags.boolean({
+      description: "Grant exactly what x402 payments need on this chain: a USDC transfer capped per period. Builds the permission from the asset registry so the USDC address and function signature do not have to be written by hand. Tune the cap with --limit.",
+      default: false,
+      exclusive: ["permissions"]
+    }),
+    limit: Flags.string({
+      description: `Spend cap for --x402, as <amount>/<period> (default ${DEFAULT_X402_LIMIT}). Examples: 25/day, 2.5/week, 100/month.`
+      // No `dependsOn: ['x402']`: a boolean flag with a default always reads as
+      // provided, so oclif would never fire it. Checked in run() instead.
     }),
     expiry: Flags.integer({
       description: "Permission expiry in days. Overrides config.sessionExpiry."
@@ -790,21 +1163,46 @@ var SessionSetup = class _SessionSetup extends BaseCommand {
     const format = flags.output;
     const apiKey = this.resolveApiKey(flags);
     const chainId = this.resolveChainId(flags);
+    if (flags.limit && !flags.x402) {
+      this.error("--limit only applies to --x402. Re-run with --x402, or set the cap inside --permissions.");
+    }
+    const resolvedPermissions = this.resolvePermissions(flags.permissions, config.permissions, {
+      x402: flags.x402,
+      limit: flags.limit,
+      chainId
+    });
+    const overCeiling = whyGrantExceedsCeiling(resolvedPermissions, chainId, config.grantCeiling);
+    if (overCeiling) this.error(overCeiling);
     let reuseKey = null;
     let oldPermissionRevoked = false;
+    let orphaned = [];
     if (keystoreExists()) {
-      const existing = loadSessionConfig();
-      const isActive = existing.expiry > Date.now() / 1e3;
+      const existing = tryLoadSessionConfig();
+      const isActive = existing !== null && existing.expiry > Date.now() / 1e3;
+      orphaned = liveOrphans(existing?.orphanedPermissions);
       if (!flags.yes && !process.stdin.isTTY) {
         this.error(
-          "Existing session found, but stdin is not a terminal (piped, redirected, or running in CI). Re-run with --yes to overwrite the existing session non-interactively."
+          "Existing session key found, but stdin is not a terminal (piped, redirected, or running in CI). Re-run with --yes to overwrite the existing session non-interactively."
         );
       }
       if (!flags.yes) {
         const readline = await import('readline');
         const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
         const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
-        if (isActive) {
+        if (!existing) {
+          const orphanAddress = tryLoadKeystoreAddress();
+          this.log("Session key found, but no session config alongside it.\n");
+          if (orphanAddress) {
+            this.log(`  Key address:      ${orphanAddress}`);
+          }
+          this.log(
+            "\nIf that key still holds a live on-chain permission it cannot be revoked\nautomatically, because the permission id lived in the missing config.\nReusing the key keeps a single key in play instead of leaving two.\n"
+          );
+          const reuseAnswer = await ask("Reuse existing session key? (Y/n) ");
+          if (reuseAnswer.toLowerCase() !== "n") {
+            reuseKey = loadSessionKey();
+          }
+        } else if (isActive) {
           const remaining = Math.floor((existing.expiry - Date.now() / 1e3) / 86400);
           this.log("Active session found:\n");
           this.log(`  Session address:  ${existing.sessionAddress}`);
@@ -818,13 +1216,11 @@ var SessionSetup = class _SessionSetup extends BaseCommand {
           const revokeAnswer = await ask("Revoke old permission on-chain first? (Y/n) ");
           if (revokeAnswer.toLowerCase() !== "n") {
             this.log("Opening browser to revoke old permission...");
-            const pm = config.paymasters?.[existing.chainId];
             const revokeBridge = await getBridge({
               keysUrl: config.keysUrl,
               apiKey,
               chainId: existing.chainId,
-              ens: config.ens,
-              paymasterUrl: pm?.url
+              ens: config.ens
             });
             try {
               await revokeBridge.request("wallet_revokePermissions", [{ id: existing.permissionId }]);
@@ -833,6 +1229,11 @@ var SessionSetup = class _SessionSetup extends BaseCommand {
             }
             oldPermissionRevoked = true;
             this.log("Old permission revoked.");
+          } else {
+            orphaned = [orphanOf(existing), ...orphaned];
+            this.log(
+              "Keeping the old permission. It stays live until it expires, and the new session will not name it, so `jaw session revoke` will revoke both."
+            );
           }
           const reuseAnswer = await ask("Reuse existing session key? (Y/n) ");
           if (reuseAnswer.toLowerCase() !== "n") {
@@ -847,14 +1248,20 @@ var SessionSetup = class _SessionSetup extends BaseCommand {
           }
         }
         rl.close();
+      } else if (!existing) {
+        const orphanAddress = tryLoadKeystoreAddress();
+        this.logToStderr(
+          `Warning: session key${orphanAddress ? ` ${orphanAddress}` : ""} has no session config. Generating a new key; any permission the old one still holds cannot be revoked automatically because the permission id is unknown.`
+        );
       } else if (isActive) {
+        orphaned = [orphanOf(existing), ...orphaned];
         this.logToStderr(
-          `Warning: overwriting active session without revoking. Old permission ${existing.permissionId} on chain ${existing.chainId} remains live until ${new Date(existing.expiry * 1e3).toISOString()}.`
+          `Warning: overwriting active session without revoking. Old permission ${existing.permissionId} on chain ${existing.chainId} remains live until ${new Date(existing.expiry * 1e3).toISOString()}. Recorded on the new session, so \`jaw session revoke\` will revoke it too.`
         );
       }
     }
     try {
-      const permissions = this.resolvePermissions(flags.permissions, config.permissions);
+      const permissions = resolvedPermissions;
       const expiryDays = flags.expiry ?? config.sessionExpiry ?? 7;
       const expiryTimestamp = Math.floor(Date.now() / 1e3) + expiryDays * 86400;
       const privateKeyHex = reuseKey ?? generateSessionKey();
@@ -862,6 +1269,7 @@ var SessionSetup = class _SessionSetup extends BaseCommand {
       const localAccount = privateKeyToAccount(privateKeyHex);
       const { Account } = await import('@jaw.id/core');
       const pm = config.paymasters?.[chainId];
+      const mode = "eip7702";
       const account = await Account.fromLocalAccount(
         {
           chainId,
@@ -869,52 +1277,84 @@ var SessionSetup = class _SessionSetup extends BaseCommand {
           paymasterUrl: pm?.url,
           paymasterContext: pm?.context
         },
-        localAccount
+        localAccount,
+        { eip7702: true }
       );
       const sessionAddress = account.address;
       if (!flags.quiet) {
+        if (flags.x402) {
+          this.log(
+            `Connect with an account that holds USDC on chain ${chainId}.
+Payments pull from it through the permission, and the grant carries 0.1 USDC
+to the session so it can pay for its own first transaction.
+`
+          );
+        }
         this.log("Opening browser to approve permissions...");
       }
       const bridge = await getBridge({
         keysUrl: config.keysUrl,
         apiKey,
         chainId,
-        ens: config.ens,
-        paymasterUrl: pm?.url
+        ens: config.ens
       });
-      let grantResponse;
+      let granted;
       try {
-        grantResponse = await bridge.request("wallet_grantPermissions", [
+        if (flags.x402) {
+          const blocked = await whyOwnerCannotFundSession({ chainId, request: (m, p) => bridge.request(m, p) });
+          if (blocked) this.error(blocked);
+        }
+        granted = await bridge.request("wallet_grantPermissions", [
           {
             spender: sessionAddress,
             expiry: expiryTimestamp,
             permissions,
-            chainId
+            chainId,
+            // The session account sends every op the permission authorises, and
+            // the ERC-20 paymaster charges the sender, so its first one has
+            // nothing to be charged. The wallet rides a small transfer along in
+            // this same transaction; it decides the amount.
+            capabilities: { prefundSpender: true }
           }
         ]);
       } finally {
         bridge.close();
       }
+      const grantResponse = granted;
+      const permission = parseGrantedPermission(granted);
       saveKeystore(privateKeyHex, sessionAddress);
       saveSessionConfig({
         ownerAddress: grantResponse.account,
         sessionAddress,
         permissionId: grantResponse.permissionId,
         chainId,
-        expiry: expiryTimestamp
+        expiry: expiryTimestamp,
+        mode,
+        ...permission ? { permission } : {},
+        ...orphaned.length > 0 ? { orphanedPermissions: orphaned } : {}
       });
+      if (flags.x402) {
+        const unfunded = await whySpenderCannotPay({ chainId, spender: sessionAddress });
+        if (unfunded) this.logToStderr(`
+Warning: ${unfunded}`);
+      }
       const summary = {
         ownerAddress: grantResponse.account,
         sessionAddress,
         permissionId: grantResponse.permissionId,
-        expiry: expiryTimestamp
+        expiry: expiryTimestamp,
+        mode
       };
       if (flags.quiet) {
         this.outputResult(summary, format);
       } else {
         this.log("\nSession created successfully.\n");
         this.log(`  Session address:  ${sessionAddress}`);
+        this.log("                    (the session key EOA, and the x402 payer)");
         this.log(`  Owner address:    ${grantResponse.account}`);
+        if (flags.x402) {
+          this.log(`                    (payments pull from here, capped at ${describeX402Grant(flags.limit)})`);
+        }
         this.log(`  Permission ID:    ${grantResponse.permissionId}`);
         this.log(`  Chain:            ${chainId}`);
         this.log(`  Expires:          ${new Date(expiryTimestamp * 1e3).toISOString()} (${expiryDays} days)`);
@@ -929,9 +1369,15 @@ var SessionSetup = class _SessionSetup extends BaseCommand {
       throw error;
     }
   }
-  resolvePermissions(flagValue, configValue) {
+  resolvePermissions(flagValue, configValue, preset) {
     let raw;
-    if (flagValue) {
+    if (preset.x402) {
+      try {
+        raw = buildX402Permissions(preset.chainId, preset.limit);
+      } catch (err) {
+        this.error(err instanceof Error ? err.message : String(err));
+      }
+    } else if (flagValue) {
       if (flagValue.trimStart().startsWith("{")) {
         try {
           raw = JSON.parse(flagValue);
@@ -939,7 +1385,7 @@ var SessionSetup = class _SessionSetup extends BaseCommand {
           this.error(`--permissions is not valid JSON: ${flagValue}`);
         }
       } else {
-        const content = fs.readFileSync(flagValue, "utf-8");
+        const content = fs4.readFileSync(flagValue, "utf-8");
         try {
           raw = JSON.parse(content);
         } catch {
@@ -949,11 +1395,16 @@ var SessionSetup = class _SessionSetup extends BaseCommand {
     } else if (configValue) {
       raw = configValue;
     } else {
-      this.error('Permissions required. Set via --permissions flag or add "permissions" to ~/.jaw/config.json');
+      this.error(
+        'Permissions required. For x402 payments run `jaw session setup --x402` and the scope is built for you. Otherwise pass --permissions or add "permissions" to ~/.jaw/config.json.'
+      );
     }
     return parsePermissionsConfig(raw);
   }
 };
+function orphanOf(session) {
+  return { id: session.permissionId, chainId: session.chainId, expiry: session.expiry };
+}
 
 export { SessionSetup as default };
 //# sourceMappingURL=setup.js.map