@ldgr/cli 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @ldgr/cli
 
-LDGR's self-custody terminal wallet. Version 0.4.0 creates or imports local wallets, lets you select between them, shows addresses and balances, sends native Ledra or a token, and persistently switches the selected wallet between mainnet and testnet.
+LDGR's self-custody terminal wallet. Version 0.5.0 creates or imports local wallets, lets you select between them, shows addresses and balances, sends native Ledra or a token, and persistently switches the selected wallet between mainnet and testnet. It also reviews prepared MCP requests for transfers, token creation and escrow creation in a separate interactive terminal.
 
 ```bash
 npm install -g @ldgr/cli
@@ -17,4 +17,16 @@ ldgr network show
 ldgr network set testnet
 ```
 
+## MCP approval requests
+
+The public `@ldgr/cli/mcp` module exposes `getMcpWalletInfo`, `validateMcpRequest`, and `saveMcpRequest`. Metadata is an explicit public projection: address, public key, network, ledger ID and protection mode. It never returns a recovery key, passphrase, encrypted vault or signer. Request preparation does not unlock, sign or submit.
+
+Run `ldgr approve <request-file>` yourself in an interactive terminal. Approval accepts the saved request envelope or a portable request JSON produced by hosted MCP. It checks the selected wallet's network, shows the destination, exact decimal amount and asset code, current balances and fee, or the complete token/escrow terms. Confirmation defaults to **No**. A protected wallet then prompts privately for its passphrase. Request expiry and signing-draft freshness are checked again after confirmation and unlock. A draft older than four minutes requires a new review, leaving submission headroom within the ledger's five-minute signature window; the CLI never silently changes the reviewed timestamp or derived token code. Terminal controls in live asset labels are escaped, and request text rejects terminal and Unicode formatting controls. API hosts are fixed to the official network endpoints; custom URLs and secret-bearing request fields are rejected.
+
+Supported requests use `{version:1, requestId:<lowercase UUID v4>, network:"mainnet"|"testnet", expiresAt:<ISO timestamp>, action, params}`. Actions are `transfer` (`asset`, `to`, `amount`, optional `memo`), `create_token` (`displayName`, `ticker`, `decimals`, `supplyMode`, `initialSupply`, optional `initialRecipient` and mintable `maxSupply`), and `open_escrow` (`asset`, `to`, `amount`, `expiresAt` as Unix milliseconds string, optional `reference`). Amounts and supplies are decimal strings. Token icons, arbitrary code and additional contract templates are not part of this request format.
+
+Prepared requests default to `~/.ldgr/requests`. Approval records live in `approvals` beside the selected wallet store. Before submission, the CLI durably saves the exact signed envelope and consumes the request ID. The same request cannot be approved again by copying or renaming its file. An interrupted or uncertain submission also blocks further approvals for that wallet. Inspect the retained envelope and ledger history to reconcile the result before manually removing the wallet's pending record or creating a replacement. Do not delete records merely to retry: a request may already have settled. There is no automatic re-signing or retry. Successful receipts contain the transaction hash. On Windows, these files rely on native directory ACLs, as the wallet store does.
+
+Applications can resolve the public `@ldgr/cli/cli` executable export to launch an explicit user-run CLI command with inherited terminal streams and `shell:false`. MCP stdio servers must never forward approval or wallet-unlock prompts through their protocol stream.
+
 The default owner-only wallet store lives at `~/.ldgr/wallet.json`. Pass `--wallet <path>` to any command to use a different store. On first use, an existing `~/.config/ldgr/wallet.json` store is validated, copied to the new owner-only location, and removed from its former location; an explicit `--wallet` path is never moved. On Windows, the CLI uses the native `USERPROFILE`/`APPDATA` locations and path separators, and relies on the file's native ACLs instead of POSIX mode bits. At creation/import you can choose passphrase protection or an **unprotected** wallet, which follows the extension model and relies only on the local file's permissions. `wallet list` shows one-based indexes and marks the active wallet; `wallet select <index>` changes it without exposing a secret. `wallet export <path>` writes an owner-only `ldgr-recovery-key.txt` file containing the raw recovery-key value accepted by the extension; `wallet import <path>` reads the same file. `--testnet` is available only when creating or importing a wallet; use `network set testnet` for an existing wallet. Testnet prints a warning on every wallet command and only uses `https://tst.ldgr.ltd`.

package/dist/cli.js

@@ -1,18 +1,30 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import * as p from "@clack/prompts";
-import { createLdgrClient, LdgrClientError } from "@ldgr/client";
+import * as p2 from "@clack/prompts";
+import { createLdgrClient as createLdgrClient2, LdgrClientError } from "@ldgr/client";
 import {
-  isBurnerWalletAddress,
-  nativeAssetDefinitionForLedger,
-  resolvePublicAssetCode
+  isBurnerWalletAddress as isBurnerWalletAddress2,
+  nativeAssetDefinitionForLedger as nativeAssetDefinitionForLedger3,
+  resolvePublicAssetCode as resolvePublicAssetCode3
 } from "@ldgr/protocol";
-import { readFile as readFile2 } from "node:fs/promises";
+import { readFile as readFile3 } from "node:fs/promises";
 
 // src/transfer.ts
 import { buildTransferSubmission } from "@ldgr/wallet-core";
 
+// src/mcp-approval.ts
+import * as p from "@clack/prompts";
+import { createLdgrClient } from "@ldgr/client";
+import { canonicalizeLedgerAddress as canonicalizeLedgerAddress3, deriveUserAssetCode, formatAtomicAmount, isBurnerWalletAddress, nativeAssetDefinitionForLedger as nativeAssetDefinitionForLedger2, parseDecimalAmount as parseDecimalAmount2, resolvePublicAssetCode as resolvePublicAssetCode2 } from "@ldgr/protocol";
+import { lstat as lstat2, mkdir as mkdir3, open as open3, readFile as readFile2, unlink as unlink2 } from "node:fs/promises";
+import { dirname as dirname3, join as join3, resolve as resolve2 } from "node:path";
+
+// src/mcp.ts
+import { assertAssetDecimals, assertAssetDisplayName, canonicalizeLedgerAddress as canonicalizeLedgerAddress2, nativeAssetDefinitionForLedger, normalizeAssetTicker, parseDecimalAmount, resolvePublicAssetCode } from "@ldgr/protocol";
+import { mkdir as mkdir2, open as open2 } from "node:fs/promises";
+import { dirname as dirname2, join as join2, resolve } from "node:path";
+
 // src/wallet-file.ts
 import { generateLocalWallet, loadLocalWallet } from "@ldgr/client";
 import { canonicalizeLedgerAddress, decodeEd25519RecoveryKey } from "@ldgr/protocol";
@@ -339,9 +351,302 @@ async function walletFileMetadata(path) {
   return store.wallets[store.activeWalletIndex];
 }
 
+// src/mcp.ts
+function object(value, keys) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("Expected an object");
+  const record = value;
+  if (Object.keys(record).some((key) => !keys.includes(key)))
+    throw new TypeError("Unexpected request field");
+  return record;
+}
+function text(value, label, limit = 512) {
+  if (typeof value !== "string" || !value || /[\x00-\x1f\x7f-\x9f\p{Cf}\u2028\u2029]/u.test(value) || new TextEncoder().encode(value).length > limit)
+    throw new TypeError(`Invalid ${label}`);
+  return value;
+}
+function amount(value) {
+  const result = text(value, "decimal amount", 100);
+  if (!/^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$/.test(result))
+    throw new TypeError("Amounts must be nonnegative decimal strings without exponents");
+  return result;
+}
+function validateMcpRequest(input) {
+  const value = object(input, ["version", "requestId", "network", "expiresAt", "action", "params"]);
+  if (value.version !== 1 || !["mainnet", "testnet"].includes(String(value.network)))
+    throw new TypeError("Unsupported request version or network");
+  if (typeof value.requestId !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value.requestId))
+    throw new TypeError("requestId must be a lowercase UUID v4");
+  const expiry = text(value.expiresAt, "request expiry");
+  if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(expiry) || !Number.isFinite(Date.parse(expiry)) || Date.parse(expiry) <= Date.now())
+    throw new TypeError("Request has expired or has an invalid ISO expiry");
+  const ledgerId = value.network === "testnet" ? 0 : 1;
+  if (value.action === "transfer" || value.action === "open_escrow") {
+    const params = object(value.params, value.action === "transfer" ? ["asset", "to", "amount", "memo"] : ["asset", "to", "amount", "expiresAt", "reference"]);
+    resolvePublicAssetCode(text(params.asset, "asset"), ledgerId);
+    canonicalizeLedgerAddress2(text(params.to, "recipient"), ledgerId);
+    if (!/[1-9]/.test(amount(params.amount)))
+      throw new TypeError("Amount must be positive");
+    if (params.memo !== undefined)
+      text(params.memo, "memo", 128);
+    if (params.reference !== undefined)
+      text(params.reference, "reference", 128);
+    if (value.action === "open_escrow") {
+      if (typeof params.expiresAt !== "string" || !/^[1-9][0-9]{0,15}$/.test(params.expiresAt) || BigInt(params.expiresAt) <= BigInt(Date.now()) || BigInt(params.expiresAt) > BigInt(Number.MAX_SAFE_INTEGER))
+        throw new TypeError("Escrow expiry must be future Unix milliseconds as a string");
+    }
+  } else if (value.action === "create_token") {
+    const params = object(value.params, ["displayName", "ticker", "decimals", "supplyMode", "initialSupply", "initialRecipient", "maxSupply"]);
+    assertAssetDisplayName(text(params.displayName, "display name", 64));
+    if (normalizeAssetTicker(text(params.ticker, "ticker")) !== params.ticker)
+      throw new TypeError("Ticker must not have surrounding whitespace");
+    if (typeof params.decimals !== "number")
+      throw new TypeError("Invalid token decimals");
+    assertAssetDecimals(params.decimals);
+    if (params.supplyMode !== "fixed" && params.supplyMode !== "mintable")
+      throw new TypeError("Invalid supply mode");
+    const definition = { ...nativeAssetDefinitionForLedger(ledgerId), decimals: params.decimals };
+    const supply = parseDecimalAmount(amount(params.initialSupply), definition);
+    if (params.supplyMode === "fixed" && supply === 0n)
+      throw new TypeError("Fixed supply must be positive");
+    if (params.initialRecipient !== undefined)
+      canonicalizeLedgerAddress2(text(params.initialRecipient, "initial recipient"), ledgerId);
+    if (params.maxSupply !== undefined) {
+      if (params.supplyMode === "fixed")
+        throw new TypeError("maxSupply is only supported for mintable tokens");
+      const max = parseDecimalAmount(amount(params.maxSupply), definition);
+      if (max <= 0n || max < supply)
+        throw new TypeError("Max supply must be positive and at least initial supply");
+    }
+  } else
+    throw new TypeError("Unsupported MCP action");
+  return structuredClone(value);
+}
+async function getMcpWalletInfo(walletPath = defaultWalletPath()) {
+  const file = await walletFileMetadata(walletPath);
+  return { address: file.address, publicKey: file.publicKey, network: file.network, ledgerId: file.ledgerId, protection: file.protection === "none" ? "none" : "passphrase" };
+}
+async function saveMcpRequest(input, options = {}) {
+  const request = validateMcpRequest(input);
+  const walletPath = resolve(options.walletPath ?? defaultWalletPath());
+  const wallet = await getMcpWalletInfo(walletPath);
+  if (wallet.network !== request.network)
+    throw new TypeError("Request network does not match the selected CLI wallet");
+  const directory = resolve(options.directory ?? join2(dirname2(walletPath), "requests"));
+  await mkdir2(directory, { recursive: true, mode: 448 });
+  const requestPath = join2(directory, `${request.requestId}.json`);
+  const handle = await open2(requestPath, "wx", 384);
+  try {
+    await handle.writeFile(JSON.stringify({ format: "ldgr-mcp-request", request, wallet: { address: wallet.address, publicKey: wallet.publicKey } }, null, 2) + `
+`);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  return { requestPath, approvalArgs: ["approve", requestPath, "--wallet", walletPath] };
+}
+
+// src/mcp-approval.ts
+var MAX_REVIEWED_DRAFT_AGE_MS = 4n * 60n * 1000n;
+function assertFreshDraft(draft) {
+  const timestamp = draft.payload.timestamp;
+  const now = BigInt(Date.now());
+  if (typeof timestamp !== "bigint" || timestamp > now || now - timestamp >= MAX_REVIEWED_DRAFT_AGE_MS) {
+    throw new Error("The reviewed signing draft is stale. Run the approval command and review again; nothing was signed or submitted.");
+  }
+}
+function reviewText(value) {
+  if (typeof value !== "string")
+    throw new TypeError("Invalid asset display metadata");
+  return value.replace(/[\x00-\x1f\x7f-\x9f\p{Cf}\u2028\u2029]/gu, (character) => `\\u{${character.codePointAt(0).toString(16).padStart(4, "0")}}`);
+}
+async function writeExclusive(path, value) {
+  const handle = await open3(path, "wx", 384);
+  try {
+    await handle.writeFile(JSON.stringify(value, null, 2) + `
+`);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+async function readRequest(path) {
+  const info = await lstat2(path);
+  if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.size > 32768)
+    throw new TypeError("Request must be a regular file of at most 32 KiB without links");
+  const envelope = JSON.parse(await readFile2(path, "utf8"));
+  if (envelope?.format === undefined)
+    return { request: validateMcpRequest(envelope), wallet: undefined };
+  if (envelope?.format !== "ldgr-mcp-request" || typeof envelope.wallet?.address !== "string" || typeof envelope.wallet?.publicKey !== "string")
+    throw new TypeError("Invalid saved MCP request");
+  return { request: validateMcpRequest(envelope.request), wallet: envelope.wallet };
+}
+async function draftRequest(request, wallet, client) {
+  const asset = request.action === "create_token" ? "dng" : resolvePublicAssetCode2(request.params.asset, wallet.ledgerId);
+  const native = nativeAssetDefinitionForLedger2(wallet.ledgerId);
+  const definition = asset === "dng" ? native : await client.assets.get(asset);
+  if (definition.code !== asset || !definition.active)
+    throw new TypeError("Asset metadata does not match the active requested asset");
+  const displayName = reviewText(definition.displayName);
+  const ticker = reviewText(definition.ticker ?? asset);
+  const nonce = (await client.accounts.getNextNonce(wallet.address, asset)).nextNonce;
+  if (!/^(0|[1-9][0-9]*)$/.test(nonce))
+    throw new TypeError("Invalid ledger nonce");
+  const timestamp = Date.now();
+  const base = { version: 1, chain: "ldgr-v1", ledgerId: wallet.ledgerId, asset, from: wallet.address, publicKey: wallet.publicKey, nonce: BigInt(nonce), timestamp: BigInt(timestamp) };
+  const config = await client.ledger.getProtocolConfig();
+  const feeKey = request.action === "create_token" ? "assetCreateFeeAtomic" : request.action === "open_escrow" ? "contractOpenFeeAtomic" : "transferFeeAtomic";
+  const fee = config[feeKey];
+  if (typeof fee !== "string" || !/^(0|[1-9][0-9]*)$/.test(fee))
+    throw new TypeError("Live network fee unavailable");
+  const balances = await client.accounts.listBalances(wallet.address);
+  const balance = (code, metadata) => parseDecimalAmount2(balances.balances.find((row) => row.asset === code)?.amount ?? "0", metadata);
+  const nativeBalance = balance("dng", native);
+  const spend = request.action === "create_token" ? 0n : parseDecimalAmount2(request.params.amount, definition);
+  if (nativeBalance < BigInt(fee) + (asset === "dng" ? spend : 0n))
+    throw new Error("Insufficient Ledra balance for amount and network fee");
+  if (asset !== "dng" && balance(asset, definition) < spend)
+    throw new Error("Insufficient token balance");
+  const heading = `Network: ${wallet.network}${wallet.ledgerId === 0 ? " (test tokens, no real-world value)" : ""}
+From: ${wallet.address}
+Request: ${request.requestId}
+Approval expires: ${request.expiresAt}
+Balance: ${formatAtomicAmount(balance(asset, definition), definition)} ${ticker} (${asset})
+Fee balance: ${formatAtomicAmount(nativeBalance, native)} ${native.ticker} (dng)
+Current network fee: ${formatAtomicAmount(BigInt(fee), native)} ${native.ticker} (dng)
+The network applies its current fee at settlement.`;
+  let payload;
+  let wire;
+  let review;
+  let path;
+  if (request.action === "create_token") {
+    const params = request.params;
+    const token = { ...native, decimals: params.decimals };
+    const identity = { ...base, action: "asset_create", displayName: params.displayName, ticker: params.ticker, decimals: params.decimals, supplyMode: params.supplyMode, initialSupply: parseDecimalAmount2(params.initialSupply, token), initialRecipient: params.initialRecipient ?? wallet.address, ...params.maxSupply === undefined ? {} : { maxSupply: parseDecimalAmount2(params.maxSupply, token) } };
+    payload = { ...identity };
+    wire = { ...identity, initialSupply: formatAtomicAmount(identity.initialSupply, token), ...identity.maxSupply === undefined ? {} : { maxSupply: formatAtomicAmount(identity.maxSupply, token) } };
+    review = `${heading}
+
+Create token: ${params.displayName} (${params.ticker})
+Asset code: ${deriveUserAssetCode(identity)}
+Decimals: ${params.decimals}
+Supply mode: ${params.supplyMode}
+Initial supply: ${params.initialSupply} ${params.ticker}
+Initial recipient: ${identity.initialRecipient}
+Maximum supply: ${params.maxSupply ?? (params.supplyMode === "fixed" ? params.initialSupply : "UNLIMITED issuer minting")}`;
+    path = "/api/v1/assets";
+  } else {
+    const params = request.params;
+    const atomic = parseDecimalAmount2(params.amount, definition);
+    if (atomic <= 0n)
+      throw new TypeError("Amount must be positive");
+    const to = canonicalizeLedgerAddress3(params.to, wallet.ledgerId);
+    const common = { ...base, to, amount: atomic };
+    if (request.action === "transfer") {
+      payload = { ...common, action: "transfer", ...request.params.memo === undefined ? {} : { memo: request.params.memo } };
+      wire = { ...payload, amount: formatAtomicAmount(atomic, definition) };
+      path = "/api/v1/transfers";
+    } else {
+      payload = { ...common, action: "payment_open", template: "escrow_v1", contractId: request.requestId, expiresAt: BigInt(request.params.expiresAt), ...request.params.reference === undefined ? {} : { reference: request.params.reference } };
+      wire = { ...payload, amount: formatAtomicAmount(atomic, definition), expiresAt: request.params.expiresAt };
+      path = "/api/v1/payment-contracts";
+    }
+    review = `${heading}
+
+${request.action === "transfer" ? "Transfer" : "Create escrow_v1"}: ${params.amount} ${ticker} (${displayName})
+Asset code: ${asset}
+To: ${to}${isBurnerWalletAddress(to) ? `
+WARNING: irreversible burn address` : ""}
+${request.action === "transfer" ? `Memo: ${request.params.memo ?? "(none)"}` : `Escrow expiry: ${new Date(Number(request.params.expiresAt)).toISOString()}
+Reference: ${request.params.reference ?? "(none)"}
+Owner can release to this payee or reclaim after expiry.`}`;
+  }
+  return { path, payload, wire: { ...wire, nonce, timestamp: String(timestamp) }, review };
+}
+async function approveMcpRequest(requestPath, walletPath, options = {}) {
+  if (!(options.terminal ?? (process.stdin.isTTY && process.stdout.isTTY)))
+    throw new Error("Approval requires an interactive terminal; run ldgr approve yourself");
+  const saved = await readRequest(requestPath);
+  const wallet = await getMcpWalletInfo(walletPath);
+  if (wallet.network !== saved.request.network || saved.wallet && (wallet.address !== saved.wallet.address || wallet.publicKey !== saved.wallet.publicKey))
+    throw new TypeError("Request does not match the selected wallet identity and network");
+  const directory = join3(dirname3(resolve2(walletPath)), "approvals");
+  await mkdir3(directory, { recursive: true, mode: 448 });
+  const pendingPath = join3(directory, `${wallet.address}.pending.json`);
+  const pending = await lstat2(pendingPath).then(() => true, (error) => {
+    if (error.code === "ENOENT")
+      return false;
+    throw error;
+  });
+  if (pending)
+    throw new Error(`This wallet already has an interrupted or uncertain submission. Reconcile ${pendingPath} before preparing a replacement.`);
+  const lockPath = join3(directory, `${saved.request.requestId}.lock.json`);
+  try {
+    await writeExclusive(lockPath, { requestId: saved.request.requestId, status: "approval-started", requestPath: resolve2(requestPath) });
+  } catch (error) {
+    if (error.code === "EEXIST")
+      throw new Error("Request already approved or approval interrupted; inspect retained records before any new request");
+    throw error;
+  }
+  let signingStarted = false;
+  const signedPath = join3(directory, `${saved.request.requestId}.signed.json`);
+  const receiptPath = join3(directory, `${saved.request.requestId}.result.json`);
+  try {
+    const client = createLdgrClient({ network: wallet.ledgerId, ...options.fetch ? { fetch: options.fetch } : {} });
+    if ((await client.ledger.get()).ledgerId !== wallet.ledgerId)
+      throw new TypeError("Endpoint ledger network mismatch");
+    const draft = await draftRequest(saved.request, wallet, client);
+    let approved;
+    if (options.review)
+      approved = await options.review(draft.review);
+    else {
+      p.note(draft.review, "Review requested action");
+      const answer = await p.confirm({ message: "Approve, sign and submit this exact request?", initialValue: false });
+      approved = !p.isCancel(answer) && answer;
+    }
+    if (!approved)
+      throw new Error("Cancelled");
+    validateMcpRequest(saved.request);
+    assertFreshDraft(draft);
+    let passphrase;
+    if (wallet.protection === "passphrase") {
+      const answer = await p.password({ message: "Enter your wallet passphrase to sign" });
+      if (p.isCancel(answer))
+        throw new Error("Cancelled");
+      passphrase = answer;
+    }
+    const signer = await readEncryptedWalletFile(walletPath, passphrase);
+    if (signer.address !== wallet.address || signer.publicKey !== wallet.publicKey || signer.ledgerId !== wallet.ledgerId)
+      throw new Error("Wallet changed during review");
+    validateMcpRequest(saved.request);
+    assertFreshDraft(draft);
+    await writeExclusive(pendingPath, { requestId: saved.request.requestId, signedPath });
+    signingStarted = true;
+    const signed = { payload: draft.wire, signature: await signer.sign(draft.payload) };
+    await writeExclusive(signedPath, { request: saved.request, network: wallet.network, path: draft.path, signed });
+    try {
+      const result = await client.submitSigned(draft.path, signed);
+      const transactionHash = saved.request.action === "open_escrow" ? result.createdTransactionHash : result.transactionHash;
+      if (typeof transactionHash !== "string" || !/^[0-9a-f]{64}$/i.test(transactionHash))
+        throw new Error("Missing valid settlement hash");
+      await writeExclusive(receiptPath, { status: "settled", transactionHash, result });
+      await unlink2(pendingPath);
+      return { transactionHash, receiptPath };
+    } catch {
+      await writeExclusive(receiptPath, { status: "uncertain", signedPath }).catch(() => {
+        return;
+      });
+      throw new Error(`Submission outcome is uncertain. Do not create or sign a replacement until reconciled. Exact signed envelope retained at ${signedPath}`);
+    }
+  } finally {
+    if (!signingStarted)
+      await unlink2(lockPath);
+  }
+}
+
 // src/cli.ts
 var HELP = `
-LDGR CLI 0.4.0 — self-custody wallet
+LDGR CLI 0.5.0 — self-custody wallet
 
 Usage:
   ldgr wallet create [--testnet] [--wallet <path>]
@@ -353,6 +658,7 @@ Usage:
   ldgr balance [--wallet <path>]
   ldgr send <recipient> <amount> [--wallet <path>]
   ldgr send-token <asset> <recipient> <amount> [--wallet <path>]
+  ldgr approve <request-file> [--wallet <path>]
   ldgr network show [--wallet <path>]
   ldgr network set <mainnet|testnet> [--wallet <path>]
 
@@ -394,26 +700,26 @@ function networkLabel(file) {
 }
 function showNetworkWarning(file) {
   if (file.ledgerId === 0) {
-    p.log.warn("TESTNET — this wallet and every transaction here use test tokens with no real-world value.");
+    p2.log.warn("TESTNET — this wallet and every transaction here use test tokens with no real-world value.");
   }
 }
 async function askPassphrase(message) {
-  const answer = await p.password({
+  const answer = await p2.password({
     message,
     validate(value) {
       return value.length >= 12 ? undefined : "Use at least 12 characters";
     }
   });
-  if (p.isCancel(answer))
+  if (p2.isCancel(answer))
     throw new Error("Cancelled");
   return answer;
 }
 async function chooseWalletPassphrase() {
-  const protectedWallet = await p.confirm({ message: "Protect this wallet with a passphrase?", initialValue: true });
-  if (p.isCancel(protectedWallet))
+  const protectedWallet = await p2.confirm({ message: "Protect this wallet with a passphrase?", initialValue: true });
+  if (p2.isCancel(protectedWallet))
     throw new Error("Cancelled");
   if (!protectedWallet) {
-    p.log.warn("This wallet will be unprotected. Anyone who can read its owner-only local file can spend its funds.");
+    p2.log.warn("This wallet will be unprotected. Anyone who can read its owner-only local file can spend its funds.");
     return;
   }
   const passphrase = await askPassphrase("Choose a wallet passphrase");
@@ -425,20 +731,20 @@ async function chooseWalletPassphrase() {
 async function signingPassphrase(file, message) {
   return file.protection === "none" ? undefined : askPassphrase(message);
 }
-async function confirm2(message) {
-  const answer = await p.confirm({ message, initialValue: false });
-  if (p.isCancel(answer) || !answer)
+async function confirm3(message) {
+  const answer = await p2.confirm({ message, initialValue: false });
+  if (p2.isCancel(answer) || !answer)
     throw new Error("Cancelled");
 }
 async function selectedClient(file) {
-  const client = createLdgrClient({ network: file.ledgerId });
+  const client = createLdgrClient2({ network: file.ledgerId });
   const ledger = await client.ledger.get();
   if (ledger.ledgerId !== file.ledgerId)
     throw new Error("The selected LDGR endpoint returned a different ledger network");
   return client;
 }
 function nativeDefinition(ledgerId) {
-  return nativeAssetDefinitionForLedger(ledgerId);
+  return nativeAssetDefinitionForLedger3(ledgerId);
 }
 function assetDefinition(record) {
   if (!Number.isSafeInteger(record.decimals) || record.decimals < 0)
@@ -458,53 +764,53 @@ async function runCreate(path, testnet) {
   if (ledgerId === 0)
     showNetworkWarning({ ledgerId });
   const passphrase = await chooseWalletPassphrase();
-  const spinner2 = p.spinner();
+  const spinner2 = p2.spinner();
   spinner2.start("Generating your wallet");
   const created = await createEncryptedWalletFile({ ledgerId, passphrase });
   const index = await addWalletFile(path, created.file);
   spinner2.stop(passphrase === undefined ? "Unprotected wallet added" : "Protected wallet added");
-  p.note(`Address
+  p2.note(`Address
 ${created.file.address}
 
 Recovery key — save this offline now; it will not be shown again
 ${created.recoveryKey}`, "Your self-custody backup");
-  p.log.warn("This recovery key alone can restore and control this wallet. Export it as a file with `ldgr wallet export <path>` and keep it offline.");
-  p.outro(`Wallet #${index + 1} selected in ${path}`);
+  p2.log.warn("This recovery key alone can restore and control this wallet. Export it as a file with `ldgr wallet export <path>` and keep it offline.");
+  p2.outro(`Wallet #${index + 1} selected in ${path}`);
 }
 async function runImport(path, testnet, recoveryKeyPath) {
   const ledgerId = testnet ? 0 : 1;
   if (ledgerId === 0)
     showNetworkWarning({ ledgerId });
-  const enteredRecoveryKey = recoveryKeyPath === undefined ? await p.password({
+  const enteredRecoveryKey = recoveryKeyPath === undefined ? await p2.password({
     message: "Enter the recovery key to import",
     validate(value) {
       return value.trim() ? undefined : "Enter a recovery key";
     }
-  }) : (await readFile2(recoveryKeyPath, "utf8")).trim();
-  if (p.isCancel(enteredRecoveryKey) || !enteredRecoveryKey)
+  }) : (await readFile3(recoveryKeyPath, "utf8")).trim();
+  if (p2.isCancel(enteredRecoveryKey) || !enteredRecoveryKey)
     throw new Error("Cancelled");
   const recoveryKey = enteredRecoveryKey;
   const passphrase = await chooseWalletPassphrase();
-  const spinner2 = p.spinner();
+  const spinner2 = p2.spinner();
   spinner2.start("Validating and encrypting imported wallet");
   const imported = await importEncryptedWalletFile({ path, recoveryKey, ledgerId, passphrase });
   spinner2.stop("Imported wallet added");
-  p.note(`Address
+  p2.note(`Address
 ${imported.file.address}
 
 Network
 ${networkLabel(imported.file)}`, `Wallet #${imported.index + 1} selected`);
   if (ledgerId === 0)
     showNetworkWarning(imported.file);
-  p.outro(`Wallet #${imported.index + 1} added to ${path}`);
+  p2.outro(`Wallet #${imported.index + 1} added to ${path}`);
 }
 async function runExport(path, backupPath) {
   const file = await walletFileMetadata(path);
   showNetworkWarning(file);
   const passphrase = await signingPassphrase(file, "Enter your wallet passphrase to export");
   await exportRecoveryKeyFile({ walletPath: path, backupPath, passphrase });
-  p.log.warn("Anyone with this recovery-key file can control the wallet. Keep it offline and never share it.");
-  p.outro(`Recovery-key file saved at ${backupPath}`);
+  p2.log.warn("Anyone with this recovery-key file can control the wallet. Keep it offline and never share it.");
+  p2.outro(`Recovery-key file saved at ${backupPath}`);
 }
 async function runWalletList(path) {
   const wallets = await listWalletFileMetadata(path);
@@ -515,34 +821,34 @@ async function runWalletList(path) {
     wallet.address
   ].join(`
 `));
-  p.note(rows.join(`
+  p2.note(rows.join(`
 
 `), `${wallets.length} local wallet${wallets.length === 1 ? "" : "s"}`);
-  p.outro("Wallet list ready");
+  p2.outro("Wallet list ready");
 }
 async function runWalletSelect(path, rawIndex) {
   if (!/^[1-9][0-9]*$/.test(rawIndex))
     throw new TypeError("Wallet index must be a positive number");
   const selected = await selectWalletFile(path, Number(rawIndex) - 1);
   showNetworkWarning(selected);
-  p.note(`${selected.address}
+  p2.note(`${selected.address}
 
 Network: ${networkLabel(selected)}`, `Wallet #${rawIndex} selected`);
-  p.outro("Wallet selected");
+  p2.outro("Wallet selected");
 }
 async function runAddress(path) {
   const file = await walletFileMetadata(path);
   showNetworkWarning(file);
-  p.note(`${file.address}
+  p2.note(`${file.address}
 
 Network: ${networkLabel(file)}
 Wallet: ${path}`, "LDGR wallet address");
-  p.outro("Address ready");
+  p2.outro("Address ready");
 }
 async function runBalance(path) {
   const file = await walletFileMetadata(path);
   showNetworkWarning(file);
-  const spinner2 = p.spinner();
+  const spinner2 = p2.spinner();
   spinner2.start("Loading balances");
   const client = await selectedClient(file);
   const result = await client.accounts.listBalances(file.address);
@@ -552,16 +858,16 @@ async function runBalance(path) {
 ${balance.asset === "dng" ? `t${file.ledgerId}` : balance.asset}`;
   }));
   spinner2.stop("Balances loaded");
-  p.note(rows.length === 0 ? "No positive balances yet." : rows.join(`
+  p2.note(rows.length === 0 ? "No positive balances yet." : rows.join(`
 
 `), `${file.address} · ${networkLabel(file)}`);
-  p.outro("Balance ready");
+  p2.outro("Balance ready");
 }
 async function runSend(path, rawAsset, recipient, amount) {
   const file = await walletFileMetadata(path);
   showNetworkWarning(file);
   const client = await selectedClient(file);
-  const asset = resolvePublicAssetCode(rawAsset, file.ledgerId);
+  const asset = resolvePublicAssetCode3(rawAsset, file.ledgerId);
   const definition = await definitionForAsset(client, asset, file.ledgerId);
   const passphrase = await signingPassphrase(file, "Enter your wallet passphrase to sign");
   const wallet = await readEncryptedWalletFile(path, passphrase);
@@ -574,7 +880,7 @@ async function runSend(path, rawAsset, recipient, amount) {
     nextNonce: (await client.accounts.getNextNonce(wallet.address, asset)).nextNonce
   });
   let submission = await makeSubmission();
-  p.note(`${definition.displayName} (${definition.ticker})
+  p2.note(`${definition.displayName} (${definition.ticker})
 ${submission.payload.amount}
 
 To
@@ -582,11 +888,11 @@ ${submission.payload.to}
 
 Network
 ${networkLabel(file)}`, "Review transfer");
-  if (isBurnerWalletAddress(String(submission.payload.to))) {
-    p.log.warn("This recipient is the irreversible burn address. The transferred amount cannot be recovered.");
+  if (isBurnerWalletAddress2(String(submission.payload.to))) {
+    p2.log.warn("This recipient is the irreversible burn address. The transferred amount cannot be recovered.");
   }
-  await confirm2("Sign and submit this transfer?");
-  const spinner2 = p.spinner();
+  await confirm3("Sign and submit this transfer?");
+  const spinner2 = p2.spinner();
   spinner2.start("Submitting signed transfer");
   let transaction;
   try {
@@ -599,36 +905,36 @@ ${networkLabel(file)}`, "Review transfer");
   }
   spinner2.stop("Transfer settled");
   const hash = typeof transaction.transactionHash === "string" ? transaction.transactionHash : "(transaction hash unavailable)";
-  p.outro(`Sent ${String(submission.payload.amount)} ${definition.ticker}
+  p2.outro(`Sent ${String(submission.payload.amount)} ${definition.ticker}
 Transaction: ${hash}`);
 }
 async function runNetwork(path, target) {
   const file = await walletFileMetadata(path);
   showNetworkWarning(file);
   if (target === undefined) {
-    p.note(`${networkLabel(file)}
+    p2.note(`${networkLabel(file)}
 ${file.address}`, "Selected network");
-    p.outro("Network ready");
+    p2.outro("Network ready");
     return;
   }
   if (target !== "mainnet" && target !== "testnet")
     throw new TypeError("Choose mainnet or testnet");
   const ledgerId = target === "testnet" ? 0 : 1;
   if (file.ledgerId === ledgerId) {
-    p.outro(`Already using ${target}`);
+    p2.outro(`Already using ${target}`);
     return;
   }
   if (ledgerId === 0)
     showNetworkWarning({ ledgerId });
-  p.log.info("Switching networks derives a different address from the same self-custody key.");
+  p2.log.info("Switching networks derives a different address from the same self-custody key.");
   const passphrase = await signingPassphrase(file, "Enter your wallet passphrase to switch networks");
-  await confirm2(`Switch this wallet to ${target}?`);
-  const spinner2 = p.spinner();
+  await confirm3(`Switch this wallet to ${target}?`);
+  const spinner2 = p2.spinner();
   spinner2.start("Re-encrypting wallet for the selected network");
   const switched = await switchWalletNetwork(path, passphrase, ledgerId);
   spinner2.stop("Network switched");
   showNetworkWarning(switched);
-  p.outro(`${target} address: ${switched.address}`);
+  p2.outro(`${target} address: ${switched.address}`);
 }
 async function main() {
   let parsed;
@@ -645,11 +951,11 @@ async function main() {
     process.stdout.write(HELP);
     return;
   }
-  p.intro("LDGR CLI");
+  p2.intro("LDGR CLI");
   try {
     const resolved = parsed.walletPathExplicit ? { path: parsed.walletPath, migrated: false } : await migrateDefaultWalletPath();
     if (resolved.migrated)
-      p.log.info(`Moved legacy wallet store to ${resolved.path}`);
+      p2.log.info(`Moved legacy wallet store to ${resolved.path}`);
     if (first === "wallet" && second === "create" && third === undefined)
       await runCreate(resolved.path, parsed.walletOnTestnet);
     else if (first === "wallet" && second === "import" && fourth === undefined)
@@ -668,7 +974,11 @@ async function main() {
       await runSend(resolved.path, "dng", second, third);
     else if (first === "send-token" && second && third && fourth)
       await runSend(resolved.path, second, third, fourth);
-    else if (first === "network" && second === "show" && third === undefined)
+    else if (first === "approve" && second && third === undefined) {
+      const result = await approveMcpRequest(second, resolved.path);
+      p2.outro(`Settled transaction: ${result.transactionHash}
+Receipt: ${result.receiptPath}`);
+    } else if (first === "network" && second === "show" && third === undefined)
       await runNetwork(resolved.path);
     else if (first === "network" && second === "set" && third && fourth === undefined)
       await runNetwork(resolved.path, third);
@@ -676,9 +986,9 @@ async function main() {
       throw new TypeError("Unknown command. Run `ldgr --help` for available commands.");
   } catch (error) {
     if (error instanceof Error && error.message === "Cancelled")
-      p.cancel("Cancelled");
+      p2.cancel("Cancelled");
     else
-      p.cancel(error instanceof Error ? error.message : String(error));
+      p2.cancel(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;
   }
 }

package/dist/mcp-approval.d.ts

@@ -0,0 +1,12 @@
+type ApprovalOptions = {
+    /** Internal test seams, deliberately absent from @ldgr/cli/mcp exports. */
+    readonly terminal?: boolean;
+    readonly fetch?: typeof fetch;
+    readonly review?: (review: string) => Promise<boolean>;
+};
+/** Called only by the user-run CLI. No signer or approval function is exported by ./mcp. */
+export declare function approveMcpRequest(requestPath: string, walletPath: string, options?: ApprovalOptions): Promise<{
+    readonly transactionHash: string;
+    readonly receiptPath: string;
+}>;
+export {};

package/dist/mcp.d.ts

@@ -0,0 +1,54 @@
+type RequestBase = {
+    readonly version: 1;
+    readonly requestId: string;
+    readonly network: "mainnet" | "testnet";
+    readonly expiresAt: string;
+};
+export type McpRequest = RequestBase & ({
+    readonly action: "transfer";
+    readonly params: {
+        readonly asset: string;
+        readonly to: string;
+        readonly amount: string;
+        readonly memo?: string;
+    };
+} | {
+    readonly action: "create_token";
+    readonly params: {
+        readonly displayName: string;
+        readonly ticker: string;
+        readonly decimals: number;
+        readonly supplyMode: "fixed" | "mintable";
+        readonly initialSupply: string;
+        readonly initialRecipient?: string;
+        readonly maxSupply?: string;
+    };
+} | {
+    readonly action: "open_escrow";
+    readonly params: {
+        readonly asset: string;
+        readonly to: string;
+        readonly amount: string;
+        readonly expiresAt: string;
+        readonly reference?: string;
+    };
+});
+export type McpWalletInfo = {
+    readonly address: string;
+    readonly publicKey: string;
+    readonly network: "mainnet" | "testnet";
+    readonly ledgerId: 0 | 1;
+    readonly protection: "none" | "passphrase";
+};
+/** Strict allowlist: request files cannot carry credentials, code, URLs or custom endpoints. */
+export declare function validateMcpRequest(input: unknown): McpRequest;
+/** Never return LocalWalletFile: unprotected stores contain the recovery key. */
+export declare function getMcpWalletInfo(walletPath?: string): Promise<McpWalletInfo>;
+export declare function saveMcpRequest(input: McpRequest, options?: {
+    readonly walletPath?: string;
+    readonly directory?: string;
+}): Promise<{
+    readonly requestPath: string;
+    readonly approvalArgs: readonly string[];
+}>;
+export {};

package/dist/mcp.js

@@ -0,0 +1,430 @@
+// src/mcp.ts
+import { assertAssetDecimals, assertAssetDisplayName, canonicalizeLedgerAddress as canonicalizeLedgerAddress2, nativeAssetDefinitionForLedger, normalizeAssetTicker, parseDecimalAmount, resolvePublicAssetCode } from "@ldgr/protocol";
+import { mkdir as mkdir2, open as open2 } from "node:fs/promises";
+import { dirname as dirname2, join as join2, resolve } from "node:path";
+
+// src/wallet-file.ts
+import { generateLocalWallet, loadLocalWallet } from "@ldgr/client";
+import { canonicalizeLedgerAddress, decodeEd25519RecoveryKey } from "@ldgr/protocol";
+import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import { dirname, join, win32 } from "node:path";
+import { homedir } from "node:os";
+var KDF_ITERATIONS = 310000;
+var AES_GCM = "AES-GCM";
+function arrayBuffer(bytes) {
+  return bytes.slice().buffer;
+}
+function encodeBase64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function decodeBase64Url(value) {
+  if (!/^[A-Za-z0-9_-]+$/.test(value))
+    throw new TypeError("Wallet file contains invalid base64url data");
+  const padded = value.replaceAll("-", "+").replaceAll("_", "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+  return Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
+}
+function networkForLedger(ledgerId) {
+  return ledgerId === 0 ? "testnet" : "mainnet";
+}
+async function deriveEncryptionKey(passphrase, salt) {
+  if (passphrase.length < 12)
+    throw new RangeError("Passphrase must be at least 12 characters");
+  const material = await crypto.subtle.importKey("raw", new TextEncoder().encode(passphrase), "PBKDF2", false, ["deriveKey"]);
+  return crypto.subtle.deriveKey({ name: "PBKDF2", hash: "SHA-256", salt: arrayBuffer(salt), iterations: KDF_ITERATIONS }, material, { name: AES_GCM, length: 256 }, false, ["encrypt", "decrypt"]);
+}
+function parseWalletEntry(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("Wallet file is not a JSON object");
+  const file = value;
+  if (file.format !== "ldgr-cli-wallet" || file.version !== 1 || file.network !== "mainnet" && file.network !== "testnet" || file.ledgerId !== 0 && file.ledgerId !== 1 || typeof file.address !== "string" || typeof file.publicKey !== "string")
+    throw new TypeError("Unsupported wallet file format");
+  if (file.network !== networkForLedger(file.ledgerId))
+    throw new TypeError("Wallet file network does not match ledgerId");
+  canonicalizeLedgerAddress(file.address, file.ledgerId);
+  if (file.protection === "none") {
+    if (typeof file.recoveryKey !== "string")
+      throw new TypeError("Unsupported wallet file format");
+    decodeEd25519RecoveryKey(file.recoveryKey);
+    return file;
+  }
+  if (file.protection !== undefined && file.protection !== "passphrase")
+    throw new TypeError("Unsupported wallet file format");
+  if (typeof file.ciphertext !== "string" || typeof file.iv !== "string" || !file.kdf || file.kdf.name !== "PBKDF2" || file.kdf.hash !== "SHA-256" || file.kdf.iterations !== KDF_ITERATIONS || typeof file.kdf.salt !== "string")
+    throw new TypeError("Unsupported wallet file format");
+  return file;
+}
+function parseWalletStore(value) {
+  if (value && typeof value === "object" && !Array.isArray(value) && value.format === "ldgr-cli-wallet") {
+    return { format: "ldgr-cli-wallet-store", version: 1, activeWalletIndex: 0, wallets: [parseWalletEntry(value)] };
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("Wallet file is not a JSON object");
+  const store = value;
+  const activeWalletIndex = store.activeWalletIndex;
+  const wallets = store.wallets;
+  if (store.format !== "ldgr-cli-wallet-store" || store.version !== 1 || typeof activeWalletIndex !== "number" || !Number.isInteger(activeWalletIndex) || !Array.isArray(wallets) || wallets.length === 0 || activeWalletIndex < 0 || activeWalletIndex >= wallets.length)
+    throw new TypeError("Unsupported wallet file format");
+  return {
+    format: "ldgr-cli-wallet-store",
+    version: 1,
+    activeWalletIndex,
+    wallets: wallets.map(parseWalletEntry)
+  };
+}
+function newWalletStore(file) {
+  return { format: "ldgr-cli-wallet-store", version: 1, activeWalletIndex: 0, wallets: [file] };
+}
+function serializeWalletStore(store) {
+  return `${JSON.stringify(store, null, 2)}
+`;
+}
+function pathJoiner(platform) {
+  return platform === "win32" ? win32.join : join;
+}
+function homeDirectory(input, platform) {
+  if (input.home !== undefined)
+    return input.home;
+  if (platform === "win32")
+    return process.env.USERPROFILE?.trim() || process.env.HOME?.trim() || homedir();
+  return process.env.HOME?.trim() || homedir();
+}
+function defaultWalletPath(input = {}) {
+  const platform = input.platform ?? process.platform;
+  const home = homeDirectory(input, platform);
+  if (!home)
+    throw new Error("Could not determine your home directory; use --wallet <path>");
+  return pathJoiner(platform)(home, ".ldgr", "wallet.json");
+}
+function legacyDefaultWalletPath(input = {}) {
+  const platform = input.platform ?? process.platform;
+  const joinPath = pathJoiner(platform);
+  const home = homeDirectory(input, platform);
+  if (!home)
+    throw new Error("Could not determine your home directory; use --wallet <path>");
+  const configHome = input.configHome ?? (platform === "win32" ? process.env.APPDATA?.trim() || joinPath(home, "AppData", "Roaming") : process.env.XDG_CONFIG_HOME?.trim() || joinPath(home, ".config"));
+  return joinPath(configHome, "ldgr", "wallet.json");
+}
+async function createEncryptedWalletFile(input) {
+  const wallet = await generateLocalWallet({ ledgerId: input.ledgerId });
+  if (input.passphrase === undefined)
+    return createUnprotectedWallet({ wallet, recoveryKey: wallet.recoveryKey });
+  return encryptWallet({ wallet, recoveryKey: wallet.recoveryKey, passphrase: input.passphrase });
+}
+function createUnprotectedWallet(input) {
+  const file = {
+    format: "ldgr-cli-wallet",
+    version: 1,
+    protection: "none",
+    network: networkForLedger(input.wallet.ledgerId),
+    ledgerId: input.wallet.ledgerId,
+    address: input.wallet.address,
+    publicKey: input.wallet.publicKey,
+    recoveryKey: input.recoveryKey
+  };
+  return { file, serialized: `${JSON.stringify(file, null, 2)}
+`, recoveryKey: input.recoveryKey };
+}
+async function encryptWallet(input) {
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const key = await deriveEncryptionKey(input.passphrase, salt);
+  const plaintext = new TextEncoder().encode(JSON.stringify({ recoveryKey: input.recoveryKey }));
+  const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: AES_GCM, iv: arrayBuffer(iv) }, key, plaintext));
+  plaintext.fill(0);
+  const file = {
+    format: "ldgr-cli-wallet",
+    version: 1,
+    network: networkForLedger(input.wallet.ledgerId),
+    ledgerId: input.wallet.ledgerId,
+    address: input.wallet.address,
+    publicKey: input.wallet.publicKey,
+    ciphertext: encodeBase64Url(ciphertext),
+    iv: encodeBase64Url(iv),
+    kdf: { name: "PBKDF2", hash: "SHA-256", iterations: KDF_ITERATIONS, salt: encodeBase64Url(salt) }
+  };
+  return { file, serialized: `${JSON.stringify(file, null, 2)}
+`, recoveryKey: input.recoveryKey };
+}
+async function writeNewWalletStore(path, store) {
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  const handle = await open(path, "wx", 384).catch((error) => {
+    if (error.code === "EEXIST")
+      throw new Error(`Wallet file already exists: ${path}`);
+    throw error;
+  });
+  try {
+    await handle.writeFile(serializeWalletStore(store), "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+async function writeNewWalletFile(path, file) {
+  await writeNewWalletStore(path, newWalletStore(file));
+}
+async function readWalletStore(path) {
+  const details = await lstat(path).catch((error) => {
+    if (error.code === "ENOENT")
+      throw new Error(`Wallet file not found: ${path}`);
+    throw error;
+  });
+  if (!details.isFile() || details.isSymbolicLink() || details.nlink !== 1)
+    throw new Error("Wallet file must be a regular file with no links");
+  if (process.platform !== "win32" && (details.mode & 63) !== 0)
+    throw new Error("Wallet file must be owner-only (chmod 600)");
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    throw new TypeError("Wallet file is not valid JSON");
+  }
+  return parseWalletStore(parsed);
+}
+async function migrateDefaultWalletPath(input = {}) {
+  const path = defaultWalletPath(input);
+  try {
+    await lstat(path);
+    return { path, migrated: false };
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  const legacyPath = legacyDefaultWalletPath(input);
+  let legacyStore;
+  try {
+    legacyStore = await readWalletStore(legacyPath);
+  } catch (error) {
+    if (error instanceof Error && error.message === `Wallet file not found: ${legacyPath}`)
+      return { path, migrated: false };
+    throw error;
+  }
+  await writeNewWalletStore(path, legacyStore);
+  try {
+    await unlink(legacyPath);
+  } catch (error) {
+    throw new Error(`Migrated wallet to ${path}, but could not remove legacy wallet file ${legacyPath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return { path, migrated: true };
+}
+async function walletFromRecoveryKey(file, recoveryKey) {
+  const wallet = await loadLocalWallet({ recoveryKey, ledgerId: file.ledgerId });
+  if (wallet.address !== file.address || wallet.publicKey !== file.publicKey)
+    throw new Error("wallet identity mismatch");
+  return { wallet, recoveryKey };
+}
+async function unlockWalletFile(file, passphrase) {
+  if (file.protection === "none")
+    return walletFromRecoveryKey(file, file.recoveryKey);
+  if (passphrase === undefined)
+    throw new Error("This wallet requires a passphrase");
+  try {
+    const key = await deriveEncryptionKey(passphrase, decodeBase64Url(file.kdf.salt));
+    const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: AES_GCM, iv: arrayBuffer(decodeBase64Url(file.iv)) }, key, arrayBuffer(decodeBase64Url(file.ciphertext))));
+    const value = JSON.parse(new TextDecoder(undefined, { fatal: true }).decode(plaintext));
+    plaintext.fill(0);
+    if (typeof value.recoveryKey !== "string")
+      throw new Error("missing recovery key");
+    return await walletFromRecoveryKey(file, value.recoveryKey);
+  } catch {
+    throw new Error("Could not unlock wallet: check your passphrase or wallet file");
+  }
+}
+async function readEncryptedWalletFile(path, passphrase) {
+  const store = await readWalletStore(path);
+  const file = store.wallets[store.activeWalletIndex];
+  return (await unlockWalletFile(file, passphrase)).wallet;
+}
+async function exportRecoveryKeyFile(input) {
+  const store = await readWalletStore(input.walletPath);
+  const unlocked = await unlockWalletFile(store.wallets[store.activeWalletIndex], input.passphrase);
+  await mkdir(dirname(input.backupPath), { recursive: true, mode: 448 });
+  const handle = await open(input.backupPath, "wx", 384).catch((error) => {
+    if (error.code === "EEXIST")
+      throw new Error(`Recovery-key file already exists: ${input.backupPath}`);
+    throw error;
+  });
+  try {
+    await handle.writeFile(unlocked.recoveryKey, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+async function replaceWalletStore(path, store) {
+  await readWalletStore(path);
+  const temporaryPath = join(dirname(path), `.${crypto.randomUUID()}.wallet.tmp`);
+  const handle = await open(temporaryPath, "wx", 384);
+  try {
+    await handle.writeFile(serializeWalletStore(store), "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename(temporaryPath, path);
+  } catch (error) {
+    await unlink(temporaryPath).catch(() => {
+      return;
+    });
+    throw error;
+  }
+}
+async function addWalletFile(path, file) {
+  let store;
+  try {
+    store = await readWalletStore(path);
+  } catch (error) {
+    if (error instanceof Error && error.message === `Wallet file not found: ${path}`) {
+      await writeNewWalletFile(path, file);
+      return 0;
+    }
+    throw error;
+  }
+  if (store.wallets.some((entry) => entry.ledgerId === file.ledgerId && entry.publicKey === file.publicKey)) {
+    throw new Error("This wallet is already in the local wallet store for this network");
+  }
+  const index = store.wallets.length;
+  await replaceWalletStore(path, { ...store, activeWalletIndex: index, wallets: [...store.wallets, file] });
+  return index;
+}
+async function importEncryptedWalletFile(input) {
+  const wallet = await loadLocalWallet({ recoveryKey: input.recoveryKey, ledgerId: input.ledgerId });
+  const created = input.passphrase === undefined ? createUnprotectedWallet({ wallet, recoveryKey: input.recoveryKey }) : await encryptWallet({ wallet, recoveryKey: input.recoveryKey, passphrase: input.passphrase });
+  return { file: created.file, index: await addWalletFile(input.path, created.file) };
+}
+async function listWalletFileMetadata(path) {
+  const store = await readWalletStore(path);
+  return store.wallets.map((wallet, index) => ({ ...wallet, index, selected: index === store.activeWalletIndex }));
+}
+async function selectWalletFile(path, index) {
+  const store = await readWalletStore(path);
+  if (!Number.isInteger(index) || index < 0 || index >= store.wallets.length) {
+    throw new RangeError(`Wallet index must be between 1 and ${store.wallets.length}`);
+  }
+  if (index !== store.activeWalletIndex)
+    await replaceWalletStore(path, { ...store, activeWalletIndex: index });
+  return store.wallets[index];
+}
+async function switchWalletNetwork(path, passphrase, ledgerId) {
+  const store = await readWalletStore(path);
+  const existing = store.wallets[store.activeWalletIndex];
+  if (existing.ledgerId === ledgerId)
+    return existing;
+  const unlocked = await unlockWalletFile(existing, passphrase);
+  const wallet = await loadLocalWallet({ recoveryKey: unlocked.recoveryKey, ledgerId });
+  const updated = existing.protection === "none" ? createUnprotectedWallet({ wallet, recoveryKey: unlocked.recoveryKey }) : await encryptWallet({ wallet, recoveryKey: unlocked.recoveryKey, passphrase });
+  if (store.wallets.some((entry, index) => index !== store.activeWalletIndex && entry.ledgerId === ledgerId && entry.publicKey === wallet.publicKey)) {
+    throw new Error("This recovery key already has a wallet in the selected network; select that wallet instead");
+  }
+  const wallets = [...store.wallets];
+  wallets[store.activeWalletIndex] = updated.file;
+  await replaceWalletStore(path, { ...store, wallets });
+  return updated.file;
+}
+async function walletFileMetadata(path) {
+  const store = await readWalletStore(path);
+  return store.wallets[store.activeWalletIndex];
+}
+
+// src/mcp.ts
+function object(value, keys) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("Expected an object");
+  const record = value;
+  if (Object.keys(record).some((key) => !keys.includes(key)))
+    throw new TypeError("Unexpected request field");
+  return record;
+}
+function text(value, label, limit = 512) {
+  if (typeof value !== "string" || !value || /[\x00-\x1f\x7f-\x9f\p{Cf}\u2028\u2029]/u.test(value) || new TextEncoder().encode(value).length > limit)
+    throw new TypeError(`Invalid ${label}`);
+  return value;
+}
+function amount(value) {
+  const result = text(value, "decimal amount", 100);
+  if (!/^(0|[1-9][0-9]*)(\.[0-9]{1,18})?$/.test(result))
+    throw new TypeError("Amounts must be nonnegative decimal strings without exponents");
+  return result;
+}
+function validateMcpRequest(input) {
+  const value = object(input, ["version", "requestId", "network", "expiresAt", "action", "params"]);
+  if (value.version !== 1 || !["mainnet", "testnet"].includes(String(value.network)))
+    throw new TypeError("Unsupported request version or network");
+  if (typeof value.requestId !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value.requestId))
+    throw new TypeError("requestId must be a lowercase UUID v4");
+  const expiry = text(value.expiresAt, "request expiry");
+  if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(expiry) || !Number.isFinite(Date.parse(expiry)) || Date.parse(expiry) <= Date.now())
+    throw new TypeError("Request has expired or has an invalid ISO expiry");
+  const ledgerId = value.network === "testnet" ? 0 : 1;
+  if (value.action === "transfer" || value.action === "open_escrow") {
+    const params = object(value.params, value.action === "transfer" ? ["asset", "to", "amount", "memo"] : ["asset", "to", "amount", "expiresAt", "reference"]);
+    resolvePublicAssetCode(text(params.asset, "asset"), ledgerId);
+    canonicalizeLedgerAddress2(text(params.to, "recipient"), ledgerId);
+    if (!/[1-9]/.test(amount(params.amount)))
+      throw new TypeError("Amount must be positive");
+    if (params.memo !== undefined)
+      text(params.memo, "memo", 128);
+    if (params.reference !== undefined)
+      text(params.reference, "reference", 128);
+    if (value.action === "open_escrow") {
+      if (typeof params.expiresAt !== "string" || !/^[1-9][0-9]{0,15}$/.test(params.expiresAt) || BigInt(params.expiresAt) <= BigInt(Date.now()) || BigInt(params.expiresAt) > BigInt(Number.MAX_SAFE_INTEGER))
+        throw new TypeError("Escrow expiry must be future Unix milliseconds as a string");
+    }
+  } else if (value.action === "create_token") {
+    const params = object(value.params, ["displayName", "ticker", "decimals", "supplyMode", "initialSupply", "initialRecipient", "maxSupply"]);
+    assertAssetDisplayName(text(params.displayName, "display name", 64));
+    if (normalizeAssetTicker(text(params.ticker, "ticker")) !== params.ticker)
+      throw new TypeError("Ticker must not have surrounding whitespace");
+    if (typeof params.decimals !== "number")
+      throw new TypeError("Invalid token decimals");
+    assertAssetDecimals(params.decimals);
+    if (params.supplyMode !== "fixed" && params.supplyMode !== "mintable")
+      throw new TypeError("Invalid supply mode");
+    const definition = { ...nativeAssetDefinitionForLedger(ledgerId), decimals: params.decimals };
+    const supply = parseDecimalAmount(amount(params.initialSupply), definition);
+    if (params.supplyMode === "fixed" && supply === 0n)
+      throw new TypeError("Fixed supply must be positive");
+    if (params.initialRecipient !== undefined)
+      canonicalizeLedgerAddress2(text(params.initialRecipient, "initial recipient"), ledgerId);
+    if (params.maxSupply !== undefined) {
+      if (params.supplyMode === "fixed")
+        throw new TypeError("maxSupply is only supported for mintable tokens");
+      const max = parseDecimalAmount(amount(params.maxSupply), definition);
+      if (max <= 0n || max < supply)
+        throw new TypeError("Max supply must be positive and at least initial supply");
+    }
+  } else
+    throw new TypeError("Unsupported MCP action");
+  return structuredClone(value);
+}
+async function getMcpWalletInfo(walletPath = defaultWalletPath()) {
+  const file = await walletFileMetadata(walletPath);
+  return { address: file.address, publicKey: file.publicKey, network: file.network, ledgerId: file.ledgerId, protection: file.protection === "none" ? "none" : "passphrase" };
+}
+async function saveMcpRequest(input, options = {}) {
+  const request = validateMcpRequest(input);
+  const walletPath = resolve(options.walletPath ?? defaultWalletPath());
+  const wallet = await getMcpWalletInfo(walletPath);
+  if (wallet.network !== request.network)
+    throw new TypeError("Request network does not match the selected CLI wallet");
+  const directory = resolve(options.directory ?? join2(dirname2(walletPath), "requests"));
+  await mkdir2(directory, { recursive: true, mode: 448 });
+  const requestPath = join2(directory, `${request.requestId}.json`);
+  const handle = await open2(requestPath, "wx", 384);
+  try {
+    await handle.writeFile(JSON.stringify({ format: "ldgr-mcp-request", request, wallet: { address: wallet.address, publicKey: wallet.publicKey } }, null, 2) + `
+`);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  return { requestPath, approvalArgs: ["approve", requestPath, "--wallet", walletPath] };
+}
+export {
+  getMcpWalletInfo,
+  saveMcpRequest,
+  validateMcpRequest
+};

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@ldgr/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "bin": {
     "ldgr": "dist/cli.js"
   },
+  "exports": {
+    "./mcp": { "types": "./dist/mcp.d.ts", "import": "./dist/mcp.js" },
+    "./cli": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "README.md"
@@ -16,9 +20,9 @@
     "node": ">=20.19.0"
   },
   "dependencies": {
-    "@ldgr/client": "^0.4.0",
-    "@ldgr/protocol": "^0.4.0",
-    "@ldgr/wallet-core": "^0.2.0",
+    "@ldgr/client": "^0.6.0",
+    "@ldgr/protocol": "^0.5.1",
+    "@ldgr/wallet-core": "^0.3.1",
     "@clack/prompts": "^0.11.0"
   },
   "scripts": {
@@ -26,10 +30,10 @@
     "prepack": "bun run build",
     "start": "bun src/cli.ts",
     "test": "bun test",
-    "typecheck": "tsc -p tsconfig.json"
+    "typecheck": "tsrs --noEmit -p tsconfig.json && tsrs --noEmit -p test/tsconfig.json"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
-    "typescript": "^7.0.2"
+    "tsrs": "0.20.0-ts7.1.0-beta"
   }
 }