agentic-wallet-mcp 0.4.0 → 0.4.2

package/README.md

@@ -24,7 +24,7 @@ VC issuance → identity proof → pay-per-use).
 | `prove_identity` | Answer an x401 `PROOF-REQUEST` → return the `PROOF-RESPONSE` header to replay | `{ proofRequest, vc?, revealAttribute?, issuerKeys? }` | `{ proofResponseHeader, verified, presentationId }` |
 | `pay_and_fetch` | Fetch a URL, auto-pay with x402 (self-pay via Wallet BE) on `402` | `{ url, method?, headers?, body? }` | `{ status, body, paymentMade, amountPaid, amountPaidHuman, asset }` |
 | `subscribe_and_issue` | Reuse a cached VC if still valid, else pay x402 → MBI issues → return the VC | `{ templateId, attributes, expirationDate?, dryRun?, forceReissue? }` | `{ issued, vcId, vc, txHash, fromCache? }` |
-| `create_holder_account` | Onboarding: manually mint an additional/replacement HSM account (the MCP already auto-creates one at startup if `ZETRIX_ADDRESS` is omitted — see Environment below) | `{ password, label?, purpose? }` | `{ zetrixAddress, holderDid, publicKeyHex, message }` |
+| `create_holder_account` | Onboarding: mint an HSM account (the MCP already auto-creates one at startup if `ZETRIX_ADDRESS` is omitted — see Environment below). Always checks for an existing account first — if one is active for this session, returns `{ alreadyExists: true, existing }` without creating anything; pass `confirmNew: true` (after asking the user) to mint a new one anyway | `{ password, label?, purpose?, confirmNew? }` | `{ created, alreadyExists, existing?, zetrixAddress?, holderDid?, publicKeyHex?, message }` |
 
 > **VCs are cached locally**, keyed by `templateId`, under `~/.agentic-wallet-mcp/vc-cache/`
 > (scoped per network + holder — different identities or networks never share a cache).
@@ -39,9 +39,15 @@ VC issuance → identity proof → pay-per-use).
 > All Ed25519 signing still goes through Wallet BE HSM; no plaintext private keys.
 
 > `create_holder_account` mints a **brand-new** keypair — Wallet BE's `/account/create` has no
-> way to provision a pre-chosen address. It returns the new `zetrixAddress`/`holderDid` for you
-> to paste into `ZETRIX_ADDRESS`/`HSM_PASSWORD` yourself (`HOLDER_DID` is optional — see
-> Environment below); the tool never writes your MCP config or restarts the server for you.
+> way to provision a pre-chosen address. It always checks first whether an account is already
+> active for this session; if so, it returns `{ alreadyExists: true, existing }` and creates
+> nothing — ask the user whether to keep the existing account or replace it, then call again
+> with `confirmNew: true` only if they want a new one. A freshly minted account (address, DID,
+> **and** password) is saved to this MCP's own local account store
+> (`~/.agentic-wallet-mcp/account.json`, owner-only) and reused automatically on the next
+> restart — no manual config edit needed. An explicit `ZETRIX_ADDRESS`/`HSM_PASSWORD` still set
+> in your MCP config always overrides the saved account (see Environment below); the tool never
+> writes the MCP host's own config file or restarts the server for you.
 
 > `revealAttribute` on `prove_identity` is optional and usually should stay that way. Omitted,
 > it's derived automatically from the challenge's DCQL `credential_requirements` — each claim path
@@ -100,9 +106,11 @@ startup, in one of two ways:
 
 1. **First-time user — only `HSM_PASSWORD` set.** The MCP creates a brand-new HSM account on
    Wallet BE (`POST /wallet/hsm/account/create`) and derives the DID from the returned public
-   key. It logs the new `ZETRIX_ADDRESS` (and `HOLDER_DID`) to stderr on startup — copy it into
-   your MCP config for next time, since nothing is persisted to disk between runs (env vars only
-   load once, at process start).
+   key. It logs the new `ZETRIX_ADDRESS` (and `HOLDER_DID`) to stderr on startup, and saves the
+   address, DID, and password to a local account store
+   (`~/.agentic-wallet-mcp/account.json`, owner-only) — it's reused automatically next run, no
+   config edit required. An explicit `ZETRIX_ADDRESS`/`HSM_PASSWORD` set later in your MCP
+   config still overrides the saved account.
 2. **Existing user — `ZETRIX_ADDRESS` + `HSM_PASSWORD` set, `HOLDER_DID` optional.** The MCP
    always self-signs the address via the existing `POST /wallet/hsm/sign-message` call and
    derives the DID from the `publicKey` the response carries — no separate lookup endpoint
@@ -171,8 +179,9 @@ the `<...>` placeholders (don't commit a filled copy; `mcp.local.json` is gitign
 ```
 
 > First run, no account yet? Omit `ZETRIX_ADDRESS` (and `HOLDER_DID`) entirely — the MCP creates
-> one for you at startup and logs it to stderr; copy it back into `env` for next time. See
-> "Onboarding" under Environment above.
+> one for you at startup, logs it to stderr, and saves it (address, DID, password) to
+> `~/.agentic-wallet-mcp/account.json` for automatic reuse next run. See "Onboarding" under
+> Environment above.
 
 > Working on this repo locally instead of the published package? Point `command`/`args` at the
 > local build directly: `"command": "node"`, `"args": ["/absolute/path/to/zetrix-agentic-wallet/dist/server-bundle.cjs"]`.
@@ -190,7 +199,7 @@ the `<...>` placeholders (don't commit a filled copy; `mcp.local.json` is gitign
 - *"I got a 401 with this PROOF-REQUEST header — prove my identity and give me the PROOF-RESPONSE to replay."* → `prove_identity`
 - *"Fetch `https://api.example/data` and pay automatically if it asks."* → `pay_and_fetch`
 - *"Apply for the agent-identity credential with these attributes and pay for it."* → `subscribe_and_issue`
-- *"My wallet_status call is failing — I don't have a holder account yet. Set one up."* → `create_holder_account` (asks you for a password, then returns the new address/DID to save)
+- *"My wallet_status call is failing — I don't have a holder account yet. Set one up."* → `create_holder_account` (asks you for a password; if an account already exists it reports that instead of creating — confirm with the user, then re-call with `confirmNew: true` to replace it)
 
 For the full ordered script (onboarding → check → issue → prove → pay), see [`docs/USAGE_FLOW.md`](docs/USAGE_FLOW.md).
 
@@ -200,9 +209,12 @@ Full narrative version with example prompts: [`docs/USAGE_FLOW.md`](docs/USAGE_F
 
 **Step 0 — onboarding (once).** Only if `ZETRIX_ADDRESS` isn't set yet: the MCP creates an HSM
 account automatically at startup from `HSM_PASSWORD` alone (see "Onboarding" under Environment
-above) — copy the logged `zetrixAddress` into your MCP config for next time. Alternatively, call
-`create_holder_account { password }` manually and paste the returned `zetrixAddress` in yourself;
-either way, restart the server afterward (env vars load once, at process start).
+above) and saves it locally for automatic reuse. Alternatively, call `create_holder_account
+{ password }` manually — it always checks for an existing account first and reports it instead
+of creating (pass `confirmNew: true`, after asking the user, to replace it anyway). Either way,
+the account is saved to `~/.agentic-wallet-mcp/account.json` and picked up automatically on the
+next restart; no manual config edit needed unless your MCP config also sets `ZETRIX_ADDRESS`/
+`HSM_PASSWORD` via env, in which case those still take precedence and should be updated too.
 
 **Phase 1 — `wallet_status` — pre-check.** Pass any VCs the caller already holds via
 `heldCredentials`; the response tells you whether the agent-identity credential you need is

package/dist/server-bundle.cjs

@@ -12542,12 +12542,12 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 var import_node_crypto2 = require("node:crypto");
 var import_node_os = require("node:os");
-var import_node_path2 = require("node:path");
+var import_node_path3 = require("node:path");
 
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.4.0",
+  version: "0.4.2",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: ["mcp", "model-context-protocol", "zetrix", "wallet", "x401", "x402", "blockchain"],
   license: "MIT",
@@ -21809,14 +21809,22 @@ var MbiError = class extends Error {
     this.httpStatus = httpStatus;
   }
 };
-var MbiClient = class {
+var MbiClient = class _MbiClient {
   baseUrl;
   constructor(baseUrl) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
   }
-  /** Phase 1 — POST /v1/vc/pay/apply without X-PAYMENT; expects the 402 challenge. */
+  /**
+   * Phase 1 — POST /v1/vc/pay/apply without X-PAYMENT; expects the 402 challenge.
+   * A free template short-circuits this: MBI issues the VC synchronously and returns
+   * 200 instead, with no phase-2 settle to follow — surfaced via the `issued` field.
+   */
   async applyChallenge(body) {
     const res = await this.fetch("POST", "/v1/vc/pay/apply", body);
+    if (res.status === 200) {
+      const issued = await this.unwrap(res);
+      return { x402Version: 1, accepts: [], issued };
+    }
     if (res.status !== 402) {
       throw await this.error(res, "apply (phase 1) expected 402");
     }
@@ -21864,12 +21872,14 @@ var MbiClient = class {
     const body = await res.json();
     return body.data;
   }
+  static ERROR_BODY_MAX_LEN = 500;
   async error(res, context) {
     const text = await res.text().catch(() => "");
     let msg = text;
     try {
       const j = JSON.parse(text);
-      msg = j.message ?? j.error ?? text;
+      const truncated = text.length > _MbiClient.ERROR_BODY_MAX_LEN ? `${text.slice(0, _MbiClient.ERROR_BODY_MAX_LEN)}\u2026 (truncated, ${text.length} bytes total)` : text;
+      msg = `${j.message ?? j.error ?? text} | full body: ${truncated}`;
     } catch {
     }
     return new MbiError(`MBI ${context} \u2014 HTTP ${res.status}: ${msg}`, res.status);
@@ -22064,6 +22074,30 @@ async function subscribeAndIssue(deps, opts) {
   const body = { data, signData, publicKey };
   if (opts.expirationDate) body.expirationDate = opts.expirationDate;
   const challenge = await deps.mbi.applyChallenge(body);
+  if (challenge.issued) {
+    const issued2 = challenge.issued;
+    if (deps.cache) {
+      await deps.cache.set(opts.templateId, {
+        templateId: opts.templateId,
+        vc: issued2.verifiableCredential,
+        vcId: issued2.vcId,
+        txHash: issued2.txHash,
+        paidAsset: "none",
+        amountPaid: "0",
+        issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        validUntil: extractValidUntil(issued2.verifiableCredential, opts.expirationDate)
+      });
+    }
+    return {
+      issued: true,
+      vcId: issued2.vcId,
+      vc: issued2.verifiableCredential,
+      txHash: issued2.txHash,
+      paidAsset: "none",
+      amountPaid: "0",
+      ...opts.dryRun ? { reason: "this template requires no payment \u2014 MBI issues synchronously at phase 1, so dryRun could not prevent this issuance" } : {}
+    };
+  }
   const accept = challenge.accepts[0];
   if (!accept) return { issued: false, reason: "MBI 402 returned no payment options" };
   if (opts.dryRun) {
@@ -22114,11 +22148,21 @@ function deriveHolderDid(publicKeyHex) {
   if (hex.length === 76 && hex.slice(0, 4).toLowerCase() === "b001") return `did:zid:${hex.slice(4, 68)}`;
   throw new Error(`onboard: unrecognized public key hex format (length ${hex.length})`);
 }
-async function createHolderAccount(create, input) {
-  const { zetrixAddress, publicKeyHex } = await create(input.password, input.label, input.purpose);
+async function createHolderAccount(deps, input) {
+  const existing = await deps.getExistingAccount();
+  if (existing && !input.confirmNew) {
+    return {
+      created: false,
+      alreadyExists: true,
+      existing,
+      message: `An account already exists for this wallet (zetrixAddress=${existing.zetrixAddress}, holderDid=${existing.holderDid}). Ask the user whether to keep using it or create a brand-new one \u2014 call create_holder_account again with confirmNew:true to mint a new account.`
+    };
+  }
+  const { zetrixAddress, publicKeyHex } = await deps.create(input.password, input.label, input.purpose);
   const holderDid = deriveHolderDid(publicKeyHex);
-  const message = `New holder HSM account created. Update your MCP config and restart the server: ZETRIX_ADDRESS=${zetrixAddress}, HSM_PASSWORD=<the password you just provided>. (HOLDER_DID=${holderDid} is optional \u2014 omit it and the MCP re-derives it from the account's public key at startup.)`;
-  return { zetrixAddress, holderDid, publicKeyHex, message };
+  await deps.saveAccount({ zetrixAddress, holderDid, hsmPassword: input.password, label: input.label, purpose: input.purpose });
+  const message = `New holder HSM account created \u2014 address, DID, and password saved to the wallet's local account store. Both will be used automatically on the next server restart; no manual config edit needed. If your MCP config also sets ZETRIX_ADDRESS/HSM_PASSWORD via environment variables, update or remove those too: an explicit env ZETRIX_ADDRESS/HSM_PASSWORD always takes precedence over the saved account. ZETRIX_ADDRESS=${zetrixAddress} (HOLDER_DID=${holderDid} is optional \u2014 it re-derives automatically).`;
+  return { created: true, alreadyExists: Boolean(existing), zetrixAddress, holderDid, publicKeyHex, message };
 }
 
 // src/template-aliases.ts
@@ -22187,7 +22231,14 @@ function createTools(deps) {
       return subscribeAndIssue(deps.subscribeDeps, resolved ? { ...input, templateId: resolved } : input);
     },
     create_holder_account(input) {
-      return createHolderAccount(deps.createAccount, input);
+      return createHolderAccount(
+        {
+          create: deps.createAccount,
+          getExistingAccount: () => Promise.resolve(deps.config.zetrixAddress ? { zetrixAddress: deps.config.zetrixAddress, holderDid: deps.config.holderDid } : null),
+          saveAccount: deps.saveAccount
+        },
+        input
+      );
     }
   };
 }
@@ -22204,6 +22255,30 @@ async function resolveHolder(deps, input) {
   return { zetrixAddress: input.zetrixAddress, holderDid: derivedDid, created: false, didMismatch };
 }
 
+// src/clients/account-store.ts
+var import_promises2 = require("node:fs/promises");
+var import_node_path2 = require("node:path");
+function isStoredAccountShape(value) {
+  return typeof value === "object" && value !== null && typeof value.zetrixAddress === "string" && typeof value.holderDid === "string" && typeof value.hsmPassword === "string";
+}
+function createFsAccountStore(filePath) {
+  return {
+    async get() {
+      try {
+        const raw = await (0, import_promises2.readFile)(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        return isStoredAccountShape(parsed) ? parsed : null;
+      } catch {
+        return null;
+      }
+    },
+    async set(account) {
+      await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(filePath), { recursive: true, mode: 448 });
+      await (0, import_promises2.writeFile)(filePath, JSON.stringify(account, null, 2), { encoding: "utf8", mode: 384 });
+    }
+  };
+}
+
 // src/index.ts
 var packageVersion = package_default.version;
 function buildToolList() {
@@ -22282,13 +22357,17 @@ function buildToolList() {
     },
     {
       name: "create_holder_account",
-      description: "Create a new holder HSM account on Wallet BE (onboarding, when ZETRIX_ADDRESS is not yet provisioned). Ask the user for a password first \u2014 never invent one. Returns the new address/DID for the user to save into their MCP config and restart the server; this tool does not persist anything itself.",
+      description: "Create a new holder HSM account on Wallet BE (onboarding). Ask the user for a password first \u2014 never invent one. ALWAYS check first: if an account already exists for this session, this returns { alreadyExists: true, existing: {...} } WITHOUT creating anything \u2014 ask the user whether to keep using the existing account or create a new one, then call again with confirmNew:true only if they choose new. A freshly created account is saved to this MCP's local account store and reused automatically on the next restart; an explicit ZETRIX_ADDRESS in the MCP config still overrides it.",
       inputSchema: {
         type: "object",
         properties: {
           password: { type: "string", description: "HSM password to protect the new account. Must come from the user." },
           label: { type: "string" },
-          purpose: { type: "string" }
+          purpose: { type: "string" },
+          confirmNew: {
+            type: "boolean",
+            description: "Set true to mint a new account even though one already exists for this session \u2014 only after the user has confirmed they want a new one."
+          }
         },
         required: ["password"]
       }
@@ -22300,7 +22379,13 @@ function asPayRequest(accept) {
   return { ...accept, extra: { gasModel: "client", ...extra } };
 }
 async function main() {
-  const config2 = loadConfig(process.env);
+  const accountStore = createFsAccountStore((0, import_node_path3.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp", "account.json"));
+  const storedAccount = process.env.ZETRIX_ADDRESS ? null : await accountStore.get();
+  const env = { ...process.env };
+  if (!env.ZETRIX_ADDRESS && storedAccount) env.ZETRIX_ADDRESS = storedAccount.zetrixAddress;
+  if (!env.HOLDER_DID && storedAccount) env.HOLDER_DID = storedAccount.holderDid;
+  if (!env.HSM_PASSWORD && storedAccount) env.HSM_PASSWORD = storedAccount.hsmPassword;
+  const config2 = loadConfig(env);
   const hsmPassword = config2.hsmPassword;
   const be = new WalletBeClient(config2.walletBeUrl);
   const { zetrixAddress, holderDid, created, didMismatch } = await resolveHolder(
@@ -22311,8 +22396,14 @@ async function main() {
     { zetrixAddress: config2.zetrixAddress, holderDid: config2.holderDid, hsmPassword }
   );
   if (created) {
+    await accountStore.set({ zetrixAddress, holderDid, hsmPassword, createdAt: (/* @__PURE__ */ new Date()).toISOString() });
+    process.stderr.write(
+      `agentic-wallet-mcp: no ZETRIX_ADDRESS was set \u2014 created a new HSM account and saved it (address, DID, and password) to ~/.agentic-wallet-mcp/account.json; it will be reused automatically next run. ZETRIX_ADDRESS=${zetrixAddress} (HOLDER_DID=${holderDid} is optional; it re-derives automatically).
+`
+    );
+  } else if (storedAccount && config2.zetrixAddress === storedAccount.zetrixAddress) {
     process.stderr.write(
-      `agentic-wallet-mcp: no ZETRIX_ADDRESS was set \u2014 created a new HSM account. Save this for next run: ZETRIX_ADDRESS=${zetrixAddress} (HOLDER_DID=${holderDid} is optional; it re-derives automatically).
+      `agentic-wallet-mcp: using the holder account saved in ~/.agentic-wallet-mcp/account.json (ZETRIX_ADDRESS=${zetrixAddress}) \u2014 no ZETRIX_ADDRESS/HSM_PASSWORD was set in the MCP config.
 `
     );
   }
@@ -22333,7 +22424,7 @@ async function main() {
   const nodeMetaQuery = (url) => fetch(url, { headers: { Accept: "application/json" } }).then((r) => r.json());
   const resolveTemplateFields = (templateId) => fetchTemplateFields(templateId, config2.templateRegistryAddress, nodeBaseUrl, nodeMetaQuery);
   const cacheScope = (0, import_node_crypto2.createHash)("sha256").update(`${config2.network}:${zetrixAddress}`).digest("hex");
-  const vcCache = createFsVcCache((0, import_node_path2.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp", "vc-cache", cacheScope));
+  const vcCache = createFsVcCache((0, import_node_path3.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp", "vc-cache", cacheScope));
   const pay = (accept) => {
     assertWithinPaymentCap(accept, config2.maxPaymentAmount);
     return import_x402_zetrix_client.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn);
@@ -22378,6 +22469,7 @@ async function main() {
     payer,
     subscribeDeps: { mbi, sign: subscribeSign, pay, resolveSymbol, holderDid, resolveTemplateFields, cache: vcCache },
     createAccount: (password, label, purpose) => be.createAccount(password, label, purpose),
+    saveAccount: (account) => accountStore.set({ ...account, createdAt: (/* @__PURE__ */ new Date()).toISOString() }),
     cache: vcCache
   };
   const tools = createTools(deps);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-wallet-mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   "keywords": ["mcp", "model-context-protocol", "zetrix", "wallet", "x401", "x402", "blockchain"],
   "license": "MIT",