run402 4.120.0 → 4.121.0

package/core-dist/wallet-auth.js

@@ -6,7 +6,7 @@ import { randomBytes } from "node:crypto";
 import { secp256k1 } from "@noble/curves/secp256k1.js";
 import { keccak_256 } from "@noble/hashes/sha3.js";
 import { bytesToHex } from "@noble/hashes/utils.js";
-import { readWallet } from "./wallet.js";
+import { isSignerWallet, readWallet } from "./wallet.js";
 import { getApiBase } from "./config.js";
 /**
  * EIP-55 mixed-case checksum encoding.
@@ -57,6 +57,33 @@ function personalSign(privateKeyHex, address, message) {
     const vHex = (recovery + 27).toString(16).padStart(2, "0");
     return "0x" + r + s + vHex;
 }
+export function prepareSIWx(opts) {
+    const message = formatSIWEMessage(opts, opts.address);
+    return {
+        message,
+        finish(signature) {
+            const payload = {
+                domain: opts.domain,
+                address: toChecksumAddress(opts.address),
+                statement: opts.statement,
+                uri: opts.uri,
+                version: opts.version ?? "1",
+                chainId: payloadChainId(opts.chainId),
+                type: opts.type ?? "eip191",
+                nonce: opts.nonce,
+                issuedAt: opts.issuedAt,
+                expirationTime: opts.expirationTime,
+                signature,
+            };
+            if (opts.resources !== undefined) {
+                payload.resources = opts.resources;
+            }
+            return {
+                "SIGN-IN-WITH-X": Buffer.from(JSON.stringify(payload)).toString("base64"),
+            };
+        },
+    };
+}
 /**
  * Format an EIP-4361 (SIWE) message. Must be byte-for-byte compatible
  * with the `siwe` library's message format used server-side for verification.
@@ -85,29 +112,54 @@ export function formatSIWEMessage(opts, address) {
     }
     return lines.join("\n");
 }
+/** SIWX headers signed with a local private key (synchronous). */
 export function buildSIWxAuthHeaders(opts) {
-    const message = formatSIWEMessage(opts, opts.wallet.address);
-    const signature = personalSign(opts.wallet.privateKey, opts.wallet.address, message);
-    const payload = {
-        domain: opts.domain,
-        address: toChecksumAddress(opts.wallet.address),
-        statement: opts.statement,
-        uri: opts.uri,
-        version: opts.version ?? "1",
-        chainId: payloadChainId(opts.chainId),
-        type: opts.type ?? "eip191",
-        nonce: opts.nonce,
-        issuedAt: opts.issuedAt,
-        expirationTime: opts.expirationTime,
-        signature,
-    };
-    if (opts.resources !== undefined) {
-        payload.resources = opts.resources;
+    if (!opts.wallet.privateKey) {
+        throw new SignerWalletError();
     }
+    const prepared = prepareSIWx({ ...opts, address: opts.wallet.address });
+    return prepared.finish(personalSign(opts.wallet.privateKey, opts.wallet.address, prepared.message));
+}
+/**
+ * Thrown where a synchronous signature is required but the wallet signs
+ * through a signer (`wallet.json` `signer`). Callers that can wait use
+ * `getWalletAuthHeadersAsync` with the SDK's signer instead.
+ */
+export class SignerWalletError extends Error {
+    code = "SIGNER_WALLET_ASYNC";
+    constructor() {
+        super("This wallet signs through a signer (wallet.json 'signer'), which this synchronous path cannot use.");
+        this.name = "SignerWalletError";
+    }
+}
+function walletSIWxOptions(path) {
+    const apiBase = getApiBase();
+    const url = new URL(apiBase);
+    const now = new Date();
     return {
-        "SIGN-IN-WITH-X": Buffer.from(JSON.stringify(payload)).toString("base64"),
+        domain: url.hostname,
+        uri: `${apiBase}${path}`,
+        statement: "Sign in to Run402",
+        chainId: "eip155:84532",
+        nonce: randomBytes(16).toString("hex"),
+        issuedAt: now.toISOString(),
+        expirationTime: new Date(now.getTime() + 5 * 60 * 1000).toISOString(),
     };
 }
+/**
+ * SIWX headers for any wallet: a key-backed wallet signs locally; a
+ * signer-backed one through `signerFor(wallet)`. Null when no wallet exists.
+ */
+export async function getWalletAuthHeadersAsync(path, walletPath, signerFor) {
+    const localWallet = readWallet(walletPath);
+    if (!localWallet || !localWallet.address)
+        return null;
+    if (!isSignerWallet(localWallet))
+        return getWalletAuthHeaders(path, walletPath);
+    const prepared = prepareSIWx({ ...walletSIWxOptions(path), address: localWallet.address });
+    const sign = await signerFor(localWallet);
+    return prepared.finish(await sign(prepared.message));
+}
 /**
  * Get SIWX auth headers for the Run402 API.
  * Returns null if no local wallet is configured.
@@ -121,26 +173,13 @@ export function getWalletAuthHeaders(path, walletPath) {
     // this helper returns SIWxAuthHeaders | null. Re-throw so callers above
     // the CLI's wrapper (e.g. SDK paid-fetch) can decide whether to swallow it.
     const localWallet = readWallet(walletPath);
-    if (!localWallet || !localWallet.address || !localWallet.privateKey)
+    if (!localWallet || !localWallet.address)
         return null;
-    const apiBase = getApiBase();
-    const url = new URL(apiBase);
-    const domain = url.hostname;
-    const uri = `${apiBase}${path}`;
-    const nonce = randomBytes(16).toString("hex");
-    const now = new Date();
-    const issuedAt = now.toISOString();
-    const expirationTime = new Date(now.getTime() + 5 * 60 * 1000).toISOString();
-    return buildSIWxAuthHeaders({
-        wallet: localWallet,
-        domain,
-        uri,
-        statement: "Sign in to Run402",
-        chainId: "eip155:84532",
-        nonce,
-        issuedAt,
-        expirationTime,
-    });
+    if (isSignerWallet(localWallet))
+        throw new SignerWalletError();
+    if (!localWallet.privateKey)
+        return null;
+    return buildSIWxAuthHeaders({ wallet: localWallet, ...walletSIWxOptions(path) });
 }
 function messageChainId(chainId) {
     if (typeof chainId === "number")

package/core-dist/wallet.js

@@ -6,6 +6,12 @@ import { getWalletPath } from "./config.js";
 const ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
 // 0x-prefixed 64-hex secp256k1 private key (32 bytes).
 const PRIVATE_KEY_RE = /^0x[a-fA-F0-9]{64}$/;
+// arn:aws:kms:<region>:<account>:key/<id>
+export const KMS_KEY_ARN_RE = /^arn:aws[a-z-]*:kms:([a-z0-9-]+):\d{12}:key\/[A-Za-z0-9-]+$/;
+/** True when the wallet signs through a signer instead of a local key. */
+export function isSignerWallet(wallet) {
+    return wallet.signer !== undefined;
+}
 /**
  * Load the agent wallet from disk.
  *
@@ -78,6 +84,21 @@ export function readWallet(path) {
         throw new Error("wallet.json missing valid 'address' (expected 0x-prefixed 40-hex string). " +
             "Back up the file and run 'run402 init' to recreate it.");
     }
+    if (data.privateKey !== undefined && data.signer !== undefined) {
+        throw new Error(`${p} has both 'privateKey' and 'signer'; a wallet is backed by exactly one. ` +
+            "Remove the one that does not belong to this wallet.");
+    }
+    if (data.signer !== undefined) {
+        const signer = data.signer;
+        if (!signer || typeof signer !== "object" || signer.kind !== "aws_kms" ||
+            typeof signer.key_arn !== "string" || !KMS_KEY_ARN_RE.test(signer.key_arn) ||
+            typeof signer.region !== "string" || signer.region.length === 0 ||
+            (signer.aws_profile !== undefined && (typeof signer.aws_profile !== "string" || signer.aws_profile.length === 0))) {
+            throw new Error(`${p} has a malformed 'signer' (expected { kind: "aws_kms", key_arn, region, aws_profile? }). ` +
+                "Re-import the wallet with 'run402 wallets import <name> --kms <key-arn>'.");
+        }
+        return data;
+    }
     if (typeof data.privateKey !== "string" || !PRIVATE_KEY_RE.test(data.privateKey)) {
         throw new Error("wallet.json missing valid 'privateKey' (expected 0x-prefixed 64-hex string). " +
             "Back up the file and run 'run402 init' to recreate it.");

package/lib/ci.mjs

@@ -325,7 +325,7 @@ async function linkGithub(args) {
 
   let signedDelegation;
   try {
-    signedDelegation = signCiDelegation(values, { apiBase: API });
+    signedDelegation = await signCiDelegation(values, { apiBase: API });
   } catch (err) {
     fail({
       code: "NO_WALLET",

package/lib/config.mjs

@@ -81,7 +81,15 @@ export function saveWallet(data) {
   coreSaveWallet(data);
 }
 
+/**
+ * The wallet's SIWX headers for `path`, or the NO_WALLET failure. Most
+ * callers use this only as a "a wallet is configured" check before handing
+ * the request to the SDK. A signer-backed wallet (KMS) signs asynchronously
+ * inside the SDK, so here it only proves the wallet exists and returns no
+ * headers; callers that need its signature use the SDK.
+ */
 export function walletAuthHeaders(path) {
+  if (readWallet()?.signer) return {};
   const headers = coreGetWalletAuthHeaders(path);
   if (!headers) {
     fail({

package/lib/contacts.mjs

@@ -104,7 +104,7 @@ async function preferences(args) {
     }
   }
   try {
-    const data = await getSdk().admin.setNotificationPreferences(patch, sessionProofs("/agent/v1/notifications/preferences"));
+    const data = await getSdk().admin.setNotificationPreferences(patch, await sessionProofs("/agent/v1/notifications/preferences"));
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -185,7 +185,7 @@ async function channelsConnect(args) {
     fail({ code: "BAD_USAGE", message: `Unexpected argument for notifications channels connect: ${positionals[1]}` });
   }
 
-  const proofs = sessionProofs("/agent/v1/notifications/channels/telegram");
+  const proofs = await sessionProofs("/agent/v1/notifications/channels/telegram");
   let pending;
   try {
     pending = await getSdk().admin.channels.connectTelegram(label ? { label } : {}, proofs);
@@ -234,7 +234,7 @@ async function channelsRevoke(args) {
   });
   walletAuthHeaders("/agent/v1/notifications/channels/telegram");
   try {
-    console.log(JSON.stringify(await getSdk().admin.channels.revokeTelegram(bindingId, sessionProofs("/agent/v1/notifications/channels/telegram")), null, 2));
+    console.log(JSON.stringify(await getSdk().admin.channels.revokeTelegram(bindingId, await sessionProofs("/agent/v1/notifications/channels/telegram")), null, 2));
   } catch (err) {
     reportSdkError(err);
   }

package/lib/session-proofs.mjs

@@ -9,13 +9,17 @@
  * signed in once is never asked to enroll a second passkey. With no live cached
  * session this returns `undefined` and the verb uses wallet auth alone.
  */
-import { walletAuthHeaders } from "./config.mjs";
+import { walletAuthHeaders, walletFile } from "./config.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
+import { getWalletAuthHeadersAsync } from "../core-dist/wallet-auth.js";
+import { personalMessageSignerFor } from "#sdk/node";
 
 /** `{ siwx, token }` for `path`, or `undefined` when no live sign-in session is cached. */
-export function sessionProofs(path) {
-  const siwx = walletAuthHeaders(path)["SIGN-IN-WITH-X"];
+export async function sessionProofs(path) {
+  walletAuthHeaders(path); // NO_WALLET when none is configured
   const live = loadLiveControlPlaneSession();
   if (!live || !live.control_plane_session_token) return undefined;
-  return { siwx, token: live.control_plane_session_token };
+  // A key-backed wallet signs locally; a signer-backed one (KMS) through its signer.
+  const headers = await getWalletAuthHeadersAsync(path, walletFile(), (w) => personalMessageSignerFor(w));
+  return { siwx: headers["SIGN-IN-WITH-X"], token: live.control_plane_session_token };
 }

package/lib/subscriptions.mjs

@@ -136,7 +136,7 @@ async function rulesAdd(args) {
 
   walletAuthHeaders("/agent/v1/notifications/rules");
   try {
-    console.log(JSON.stringify(await getSdk().admin.rules.create(input, sessionProofs("/agent/v1/notifications/rules")), null, 2));
+    console.log(JSON.stringify(await getSdk().admin.rules.create(input, await sessionProofs("/agent/v1/notifications/rules")), null, 2));
   } catch (err) {
     reportSdkError(err);
   }
@@ -162,7 +162,7 @@ async function rulesRm(args) {
   });
   walletAuthHeaders("/agent/v1/notifications/rules");
   try {
-    console.log(JSON.stringify(await getSdk().admin.rules.delete(ruleId, sessionProofs("/agent/v1/notifications/rules")), null, 2));
+    console.log(JSON.stringify(await getSdk().admin.rules.delete(ruleId, await sessionProofs("/agent/v1/notifications/rules")), null, 2));
   } catch (err) {
     reportSdkError(err);
   }

package/lib/wallets.mjs

@@ -20,7 +20,7 @@ import { ALL_ON_CHAIN_BALANCE_KEYS, readOnChainBalances, TEMPO_MODERATO } from "
 const HELP = `run402 wallets — manage named wallets (profiles)
 
 Usage:
-  run402 wallets list                 List all wallets (local_label, server_label, address, rail, active)
+  run402 wallets list                 List all wallets (local_label, server_label, address, rail, signer, active)
   run402 wallets current              Show the active wallet: how it was selected, address, rail, file path, faucet use
   run402 wallets fund                 Request testnet funds from the faucet into the active wallet (Base Sepolia or Tempo)
   run402 wallets balance              The active wallet's on-chain balances, plus its organization's allowance
@@ -30,6 +30,11 @@ Usage:
   run402 wallets bind [<name>]        Write ./.run402.json binding this directory to a wallet
   run402 wallets unbind               Remove ./.run402.json
   run402 wallets import <name> --key <path|->   Adopt an existing private key as a named wallet
+  run402 wallets import <name> --kms <key-arn> [--aws-profile <p>]
+                                      Adopt an AWS KMS key by reference (no secret on disk)
+  run402 wallets send <amount> --to <address> [--from <smart-account>] [--network <n>] [--confirm]
+                                      Send USDC (base, base-sepolia) or pathUSD (tempo, tempo-moderato)
+                                      from the active wallet; previews without --confirm
   run402 wallets rm <name> --yes      Delete a wallet and its keys (requires --yes)
   run402 wallets lightning status     The active wallet's Lightning wallet (balance, budget, custody)
   run402 wallets lightning mint       Mint the Lightning wallet for the active wallet (same as init lightning)
@@ -43,6 +48,12 @@ Options:
   --rail <rail>   (new) x402 (default), mpp, or lightning; a lightning wallet
                   is minted on the platform by: run402 --wallet <name> init lightning
   --key <path|->  (import) read the private key from a file, or '-' for stdin
+  --kms <arn>     (import) a KMS key ARN (ECC_SECG_P256K1, SIGN_VERIFY); the key never leaves KMS
+  --aws-profile <p>  (import) the AWS profile the key is reached through (e.g. an SSO profile)
+  --to <address>  (send) the recipient
+  --from <addr>   (send) a CoinbaseSmartWallet the wallet owns, to send from (Base only)
+  --network <n>   (send) base (default), base-sepolia, tempo, or tempo-moderato
+  --confirm       (send) sign and send; without it, print the checked preview only
   --yes           (rm) confirm deletion
 
 Notes:
@@ -97,6 +108,14 @@ const cmdBind = (args) => call((w) => w.bind(firstPositional(args)));
 const cmdUnbind = () => call((w) => w.unbind());
 
 function cmdImport(args) {
+  const kms = flagVal(args, "--kms");
+  if (kms) {
+    if (args.includes("--key")) {
+      fail({ code: "BAD_USAGE", message: "Pass either --key or --kms, not both." });
+    }
+    const awsProfile = flagVal(args, "--aws-profile") ?? undefined;
+    return call((w) => w.import(firstPositional(args), { kms: { keyId: kms, awsProfile } }));
+  }
   // The key is read only after the SDK has accepted the name.
   return call((w) => w.import(firstPositional(args), () => {
     const keyArg = flagVal(args, "--key");
@@ -113,6 +132,26 @@ function cmdImport(args) {
 
 const cmdRm = (args) => call((w) => w.remove(firstPositional(args), { confirm: args.includes("--yes") }));
 
+function cmdSend(args) {
+  const valueFlags = new Set(["--to", "--from", "--network"]);
+  const amount = args.find((a, i) => a && !a.startsWith("-") && !valueFlags.has(args[i - 1]));
+  const to = flagVal(args, "--to");
+  if (!amount || !to) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 wallets send <amount> --to <address> [--from <smart-account>] [--network <n>] [--confirm]" });
+  }
+  const opts = {
+    amount,
+    to,
+    from: flagVal(args, "--from") ?? undefined,
+    network: flagVal(args, "--network") ?? undefined,
+    confirm: args.includes("--confirm"),
+  };
+  return call(async (w) => {
+    const result = await w.send(opts);
+    return result.preview ? { ...result, hint: "Nothing was signed. Re-run with --confirm to sign and send." } : result;
+  });
+}
+
 export async function run(sub, args = []) {
   const rest = Array.isArray(args) ? args : [];
   if (!sub || sub === "--help" || sub === "-h" || rest.includes("--help") || rest.includes("-h")) {
@@ -129,6 +168,7 @@ export async function run(sub, args = []) {
     case "unbind": return cmdUnbind();
     case "import": return cmdImport(rest);
     case "rm": return cmdRm(rest);
+    case "send": return cmdSend(rest);
     case "fund": return cmdFund();
     case "balance": return cmdBalance();
     case "lightning": return cmdLightning(rest);

package/lib/webhook-secret.mjs

@@ -39,7 +39,7 @@ export async function run(sub, args = []) {
   }
   const parsedArgs = normalizeArgv(args);
   assertKnownFlags(parsedArgs, ["--help", "-h"]);
-  const proofs = sessionProofs("/agent/v1/webhook-secret/rotate");
+  const proofs = await sessionProofs("/agent/v1/webhook-secret/rotate");
   try {
     const data = await getSdk().admin.rotateWebhookSecret(proofs);
     console.log(JSON.stringify(data, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.120.0",
+  "version": "4.121.0",
   "description": "CLI for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.",
   "type": "module",
   "bin": {
@@ -23,6 +23,7 @@
     "vault-surface.json"
   ],
   "dependencies": {
+    "@aws-sdk/client-kms": "^3.1147.0",
     "@hpke/chacha20poly1305": "^1.8.0",
     "@hpke/core": "^1.9.0",
     "@humanwhocodes/momoa": "3.3.10",

package/sdk/core-dist/wallet-auth.js

@@ -6,7 +6,7 @@ import { randomBytes } from "node:crypto";
 import { secp256k1 } from "@noble/curves/secp256k1.js";
 import { keccak_256 } from "@noble/hashes/sha3.js";
 import { bytesToHex } from "@noble/hashes/utils.js";
-import { readWallet } from "./wallet.js";
+import { isSignerWallet, readWallet } from "./wallet.js";
 import { getApiBase } from "./config.js";
 /**
  * EIP-55 mixed-case checksum encoding.
@@ -57,6 +57,33 @@ function personalSign(privateKeyHex, address, message) {
     const vHex = (recovery + 27).toString(16).padStart(2, "0");
     return "0x" + r + s + vHex;
 }
+export function prepareSIWx(opts) {
+    const message = formatSIWEMessage(opts, opts.address);
+    return {
+        message,
+        finish(signature) {
+            const payload = {
+                domain: opts.domain,
+                address: toChecksumAddress(opts.address),
+                statement: opts.statement,
+                uri: opts.uri,
+                version: opts.version ?? "1",
+                chainId: payloadChainId(opts.chainId),
+                type: opts.type ?? "eip191",
+                nonce: opts.nonce,
+                issuedAt: opts.issuedAt,
+                expirationTime: opts.expirationTime,
+                signature,
+            };
+            if (opts.resources !== undefined) {
+                payload.resources = opts.resources;
+            }
+            return {
+                "SIGN-IN-WITH-X": Buffer.from(JSON.stringify(payload)).toString("base64"),
+            };
+        },
+    };
+}
 /**
  * Format an EIP-4361 (SIWE) message. Must be byte-for-byte compatible
  * with the `siwe` library's message format used server-side for verification.
@@ -85,29 +112,54 @@ export function formatSIWEMessage(opts, address) {
     }
     return lines.join("\n");
 }
+/** SIWX headers signed with a local private key (synchronous). */
 export function buildSIWxAuthHeaders(opts) {
-    const message = formatSIWEMessage(opts, opts.wallet.address);
-    const signature = personalSign(opts.wallet.privateKey, opts.wallet.address, message);
-    const payload = {
-        domain: opts.domain,
-        address: toChecksumAddress(opts.wallet.address),
-        statement: opts.statement,
-        uri: opts.uri,
-        version: opts.version ?? "1",
-        chainId: payloadChainId(opts.chainId),
-        type: opts.type ?? "eip191",
-        nonce: opts.nonce,
-        issuedAt: opts.issuedAt,
-        expirationTime: opts.expirationTime,
-        signature,
-    };
-    if (opts.resources !== undefined) {
-        payload.resources = opts.resources;
+    if (!opts.wallet.privateKey) {
+        throw new SignerWalletError();
     }
+    const prepared = prepareSIWx({ ...opts, address: opts.wallet.address });
+    return prepared.finish(personalSign(opts.wallet.privateKey, opts.wallet.address, prepared.message));
+}
+/**
+ * Thrown where a synchronous signature is required but the wallet signs
+ * through a signer (`wallet.json` `signer`). Callers that can wait use
+ * `getWalletAuthHeadersAsync` with the SDK's signer instead.
+ */
+export class SignerWalletError extends Error {
+    code = "SIGNER_WALLET_ASYNC";
+    constructor() {
+        super("This wallet signs through a signer (wallet.json 'signer'), which this synchronous path cannot use.");
+        this.name = "SignerWalletError";
+    }
+}
+function walletSIWxOptions(path) {
+    const apiBase = getApiBase();
+    const url = new URL(apiBase);
+    const now = new Date();
     return {
-        "SIGN-IN-WITH-X": Buffer.from(JSON.stringify(payload)).toString("base64"),
+        domain: url.hostname,
+        uri: `${apiBase}${path}`,
+        statement: "Sign in to Run402",
+        chainId: "eip155:84532",
+        nonce: randomBytes(16).toString("hex"),
+        issuedAt: now.toISOString(),
+        expirationTime: new Date(now.getTime() + 5 * 60 * 1000).toISOString(),
     };
 }
+/**
+ * SIWX headers for any wallet: a key-backed wallet signs locally; a
+ * signer-backed one through `signerFor(wallet)`. Null when no wallet exists.
+ */
+export async function getWalletAuthHeadersAsync(path, walletPath, signerFor) {
+    const localWallet = readWallet(walletPath);
+    if (!localWallet || !localWallet.address)
+        return null;
+    if (!isSignerWallet(localWallet))
+        return getWalletAuthHeaders(path, walletPath);
+    const prepared = prepareSIWx({ ...walletSIWxOptions(path), address: localWallet.address });
+    const sign = await signerFor(localWallet);
+    return prepared.finish(await sign(prepared.message));
+}
 /**
  * Get SIWX auth headers for the Run402 API.
  * Returns null if no local wallet is configured.
@@ -121,26 +173,13 @@ export function getWalletAuthHeaders(path, walletPath) {
     // this helper returns SIWxAuthHeaders | null. Re-throw so callers above
     // the CLI's wrapper (e.g. SDK paid-fetch) can decide whether to swallow it.
     const localWallet = readWallet(walletPath);
-    if (!localWallet || !localWallet.address || !localWallet.privateKey)
+    if (!localWallet || !localWallet.address)
         return null;
-    const apiBase = getApiBase();
-    const url = new URL(apiBase);
-    const domain = url.hostname;
-    const uri = `${apiBase}${path}`;
-    const nonce = randomBytes(16).toString("hex");
-    const now = new Date();
-    const issuedAt = now.toISOString();
-    const expirationTime = new Date(now.getTime() + 5 * 60 * 1000).toISOString();
-    return buildSIWxAuthHeaders({
-        wallet: localWallet,
-        domain,
-        uri,
-        statement: "Sign in to Run402",
-        chainId: "eip155:84532",
-        nonce,
-        issuedAt,
-        expirationTime,
-    });
+    if (isSignerWallet(localWallet))
+        throw new SignerWalletError();
+    if (!localWallet.privateKey)
+        return null;
+    return buildSIWxAuthHeaders({ wallet: localWallet, ...walletSIWxOptions(path) });
 }
 function messageChainId(chainId) {
     if (typeof chainId === "number")

package/sdk/core-dist/wallet.js

@@ -6,6 +6,12 @@ import { getWalletPath } from "./config.js";
 const ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
 // 0x-prefixed 64-hex secp256k1 private key (32 bytes).
 const PRIVATE_KEY_RE = /^0x[a-fA-F0-9]{64}$/;
+// arn:aws:kms:<region>:<account>:key/<id>
+export const KMS_KEY_ARN_RE = /^arn:aws[a-z-]*:kms:([a-z0-9-]+):\d{12}:key\/[A-Za-z0-9-]+$/;
+/** True when the wallet signs through a signer instead of a local key. */
+export function isSignerWallet(wallet) {
+    return wallet.signer !== undefined;
+}
 /**
  * Load the agent wallet from disk.
  *
@@ -78,6 +84,21 @@ export function readWallet(path) {
         throw new Error("wallet.json missing valid 'address' (expected 0x-prefixed 40-hex string). " +
             "Back up the file and run 'run402 init' to recreate it.");
     }
+    if (data.privateKey !== undefined && data.signer !== undefined) {
+        throw new Error(`${p} has both 'privateKey' and 'signer'; a wallet is backed by exactly one. ` +
+            "Remove the one that does not belong to this wallet.");
+    }
+    if (data.signer !== undefined) {
+        const signer = data.signer;
+        if (!signer || typeof signer !== "object" || signer.kind !== "aws_kms" ||
+            typeof signer.key_arn !== "string" || !KMS_KEY_ARN_RE.test(signer.key_arn) ||
+            typeof signer.region !== "string" || signer.region.length === 0 ||
+            (signer.aws_profile !== undefined && (typeof signer.aws_profile !== "string" || signer.aws_profile.length === 0))) {
+            throw new Error(`${p} has a malformed 'signer' (expected { kind: "aws_kms", key_arn, region, aws_profile? }). ` +
+                "Re-import the wallet with 'run402 wallets import <name> --kms <key-arn>'.");
+        }
+        return data;
+    }
     if (typeof data.privateKey !== "string" || !PRIVATE_KEY_RE.test(data.privateKey)) {
         throw new Error("wallet.json missing valid 'privateKey' (expected 0x-prefixed 64-hex string). " +
             "Back up the file and run 'run402 init' to recreate it.");

package/sdk/dist/credentials.d.ts

@@ -31,9 +31,23 @@ export interface ProjectCredentialCacheInfo {
     wallet?: string;
     profile?: string;
 }
+/**
+ * A wallet is backed by exactly one of: a local private key (`privateKey`),
+ * or a signer reference (`signer`) naming where the key lives (an AWS KMS
+ * key). A signer reference holds no secret.
+ */
 export interface WalletData {
     address: string;
-    privateKey: string;
+    /** Local signing key. Absent on a signer-backed wallet. */
+    privateKey?: string;
+    /** Where a signer-backed wallet's key lives. Absent on a key-backed wallet. */
+    signer?: {
+        kind: "aws_kms";
+        key_arn: string;
+        region: string;
+        /** The AWS profile the key is reached through; the default credential chain when absent. */
+        aws_profile?: string;
+    };
     created?: string;
     funded?: boolean;
     lastFaucet?: string;

package/sdk/dist/credentials.d.ts.map

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

package/sdk/dist/errors.d.ts

@@ -266,6 +266,20 @@ export declare class ProjectCredentialNotFound extends LocalError {
  * `run_cli_command` next action naming the CLI command that performs the
  * same operation, where the secret prints once to a person's terminal.
  */
+/**
+ * `VALUE_TRANSFER_REQUIRES_CLI` — a method that moves money out of a wallet
+ * (`wallets.send`) was called on a client whose `capabilities.returnSecrets`
+ * is false: the `sandbox` surface an MCP `run` snippet executes on. Thrown
+ * before any signature is requested. Paying a priced route from the sandbox is
+ * unaffected (it is bounded by the client's spend controls); a transfer to an
+ * arbitrary address is not, so it belongs to a person at the CLI. Carries one
+ * `run_cli_command` next action naming the equivalent command.
+ */
+export declare class ValueTransferRequiresCliError extends LocalError {
+    /** The exact CLI command line for the same transfer. */
+    readonly command: string;
+    constructor(command: string);
+}
 export declare class SecretRequiresCliError extends LocalError {
     /** The exact CLI command line for the same operation. */
     readonly command: string;