agentic-wallet-mcp 0.3.1 → 0.4.2

package/README.md

@@ -20,20 +20,34 @@ VC issuance → identity proof → pay-per-use).
 
 | Tool | Does | Input | Output (shape) |
 |---|---|---|---|
-| `wallet_status` | Report holder DID/address/network + client-supplied held VCs | `{ heldCredentials? }` | `{ holderDid, zetrixAddress, network, credentials }` |
-| `prove_identity` | Answer an x401 `PROOF-REQUEST` → return the `PROOF-RESPONSE` header to replay | `{ proofRequest, vc, revealAttribute?, issuerKeys? }` | `{ proofResponseHeader, verified, presentationId }` |
+| `wallet_status` | Report holder DID/address/network + held VCs (client-supplied, or the local cache) | `{ heldCredentials? }` | `{ holderDid, zetrixAddress, network, credentials }` |
+| `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` | Build the signed payload → pay x402 → MBI issues → return the VC | `{ templateId, attributes, expirationDate? }` | `{ issued, vcId, vc, txHash }` |
-| `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 }` |
-
-> The wallet **never persists VCs** — the client holds them and passes them in (e.g. `vc` on
-> `prove_identity`, `heldCredentials` on `wallet_status`). All Ed25519 signing goes through
-> Wallet BE HSM; no plaintext private keys.
+| `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: 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).
+> `subscribe_and_issue` checks the cache before paying: a still-valid cached VC is returned
+> immediately with `fromCache: true` and **no payment made**; pass `forceReissue: true` to pay
+> and issue fresh regardless. `wallet_status`/`prove_identity` fall back to the cache
+> automatically when you don't pass `heldCredentials`/`vc` explicitly — `prove_identity` only
+> auto-selects when there's exactly one valid cached VC; with zero or several, it errors and
+> asks you to pass `vc` explicitly. Explicitly passing `vc`/`heldCredentials` (including `[]`)
+> always overrides the cache. Validity is read from the VC's own `validUntil` field, falling
+> back to the `expirationDate` requested at issuance; a VC with neither is cached indefinitely.
+> 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
@@ -92,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
@@ -126,8 +142,9 @@ network:
 
 Only set any of the four explicitly if you run your own instance of that service instead of the
 default one — an explicit value always wins over the network default. The `*.myegdev.com`
-(testnet) hosts are internal — unreachable without VPN; see "Network reachability &
-troubleshooting" below if any of them time out.
+(testnet) hosts are public endpoints — no VPN needed; if you're on a corporate VPN and one of
+them times out, disconnecting it is more likely to fix that than connecting it. See "Network
+reachability & troubleshooting" below.
 
 That's the complete list — no VC-MCP subprocess, no BaaS gateway key, no manually-configured
 BBS+ key to set up.
@@ -162,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"]`.
@@ -181,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).
 
@@ -191,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
@@ -220,13 +241,13 @@ Independent of Phases 2/3 — no VC or identity proof involved, just a fresh pay
 
 ## Network reachability & troubleshooting
 
-Several dependencies sit behind a corporate VPN or a CDN edge. When something that worked before
-suddenly times out or 403s, check this table before assuming a code regression — in every case
-observed so far, the code was correct and the network/edge state had changed.
+The `*.myegdev.com` testnet endpoints are public — no VPN needed to reach them. One dependency
+sits behind a CDN edge (see the ZID resolver row below). When something that worked before
+suddenly times out or 403s, check this table before assuming a code regression.
 
 | Symptom | Cause | Fix / status |
 |---|---|---|
-| `Wallet BE /wallet/hsm/sign-blob request failed <- fetch failed <- UND_ERR_CONNECT_TIMEOUT` (or same for `mbi-vc.myegdev.com`) | `*.myegdev.com` hosts are internal — unreachable without VPN | Connect/reconnect your VPN, then retry. Verify first: `curl -I https://wallet-api.myegdev.com/server` |
+| `Wallet BE /wallet/hsm/sign-blob request failed <- fetch failed <- UND_ERR_CONNECT_TIMEOUT` (or same for `mbi-vc.myegdev.com`) | Transient network issue, or (if you're on a corporate VPN) the VPN routing away from the public internet | If you're on a VPN, try disconnecting it and retrying. Verify reachability directly: `curl -I https://wallet-api.myegdev.com/server` |
 | `VP derivation failed <- ZID resolver HTTP 403 ... cf-mitigated: challenge` | ZID resolver (`zid-resolver-sandbox.zetrix.com`) sitting behind a Cloudflare **managed challenge** that blocks plain server-to-server `fetch` | Server-to-server access to the resolver must be allowlisted so it returns `200` directly. If the challenge is active, `prove_identity`'s `issuerKeys` input is the fallback — fetch the DID document via a real browser (it clears the JS challenge) and pass its `verificationMethod` entries' `publicKeyMultibase` (BBS+) / `publicKeyHex` (Ed25519) directly. |
 | `OID4VP backend returned a malformed presentation definition` | Historical SDK bug: the live sandbox's `GET /v1/presentation/{id}` response has no `expires_at` field, but the SDK guard required one | **Fixed** in `x401-zetrix-client` — `expiresAt` is now optional on `PresentationDefinition`. If you see this, you're on a stale cached `npx` install — clear it (`npx clear-npx-cache` or bump the version) to pick up the current published `agentic-wallet-mcp`. |
 | `SUBMIT_FAILED: OID4VP backend returned 401 ... Missing X-Wallet-Public-Key header` | Historical SDK gap: `POST /v1/presentation/submit` requires wallet-auth headers (`X-Wallet-Public-Key` / `X-Wallet-Signed-Data`, holder signs their own address) that the SDK didn't send | **Fixed** — `X401Wallet` now accepts an injected `submitAuth` provider and the wallet wires it automatically; nothing to configure. |

package/dist/server-bundle.cjs

@@ -2233,8 +2233,8 @@ var require_resolve = __commonJS({
       }
       return count;
     }
-    function getFullPath(resolver, id = "", normalize) {
-      if (normalize !== false)
+    function getFullPath(resolver, id = "", normalize2) {
+      if (normalize2 !== false)
         id = normalizeId(id);
       const p = resolver.parse(id);
       return _getFullPath(resolver, p);
@@ -3630,7 +3630,7 @@ var require_fast_uri = __commonJS({
     "use strict";
     var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, escapePreservingEscapes, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
     var { SCHEMES, getSchemeHandler } = require_schemes();
-    function normalize(uri, options) {
+    function normalize2(uri, options) {
       if (typeof uri === "string") {
         uri = /** @type {T} */
         normalizeString(uri, options);
@@ -3897,7 +3897,7 @@ var require_fast_uri = __commonJS({
     }
     var fastUri = {
       SCHEMES,
-      normalize,
+      normalize: normalize2,
       resolve,
       resolveComponent,
       equal,
@@ -8541,13 +8541,13 @@ var require_path = __commonJS({
         return /^(?:\/|\w+:)/.test(path2);
       }
     );
-    var normalize = (
+    var normalize2 = (
       /**
        * Normalizes the specified path.
        * @param {string} path Path to normalize
        * @returns {string} Normalized path
        */
-      path.normalize = function normalize2(path2) {
+      path.normalize = function normalize3(path2) {
         path2 = path2.replace(/\\/g, "/").replace(/\/{2,}/g, "/");
         var parts = path2.split("/"), absolute = isAbsolute(path2), prefix = "";
         if (absolute)
@@ -8570,12 +8570,12 @@ var require_path = __commonJS({
     );
     path.resolve = function resolve(originPath, includePath, alreadyNormalized) {
       if (!alreadyNormalized)
-        includePath = normalize(includePath);
+        includePath = normalize2(includePath);
       if (isAbsolute(includePath))
         return includePath;
       if (!alreadyNormalized)
-        originPath = normalize(originPath);
-      return (originPath = originPath.replace(/(?:\/|^)[^/]+$/, "")).length ? normalize(originPath + "/" + includePath) : includePath;
+        originPath = normalize2(originPath);
+      return (originPath = originPath.replace(/(?:\/|^)[^/]+$/, "")).length ? normalize2(originPath + "/" + includePath) : includePath;
     };
   }
 });
@@ -12540,11 +12540,14 @@ __export(index_exports, {
   buildToolList: () => buildToolList
 });
 module.exports = __toCommonJS(index_exports);
+var import_node_crypto2 = require("node:crypto");
+var import_node_os = require("node:os");
+var import_node_path3 = require("node:path");
 
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.3.1",
+  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",
@@ -21607,7 +21610,7 @@ async function resolveAssetSymbol(asset, query) {
 }
 
 // src/clients/template-info-client.ts
-async function fetchTemplateRequiredFields(templateId, registryAddress, nodeBaseUrl, query) {
+async function fetchTemplateFields(templateId, registryAddress, nodeBaseUrl, query) {
   const key = `template__${templateId}`;
   const url = `${nodeBaseUrl.replace(/\/+$/, "")}/getAccountMetaData?address=${encodeURIComponent(registryAddress)}&key=${encodeURIComponent(key)}`;
   let res;
@@ -21621,10 +21624,16 @@ async function fetchTemplateRequiredFields(templateId, registryAddress, nodeBase
   if (!value) return null;
   try {
     const parsed = JSON.parse(value);
-    if (parsed.applyFormat === void 0 || parsed.applyFormat === null) return [];
+    if (parsed.applyFormat === void 0 || parsed.applyFormat === null) return { required: [], allKeys: [] };
     const format = typeof parsed.applyFormat === "string" ? JSON.parse(parsed.applyFormat) : parsed.applyFormat;
     if (!Array.isArray(format)) return null;
-    return format.filter((e) => e && e.mandatory === 1 && typeof e.key === "string" && e.key !== "").map((e) => e.key);
+    const entries = format.filter(
+      (e) => !!e && typeof e.key === "string" && e.key !== ""
+    );
+    return {
+      required: entries.filter((e) => e.mandatory === 1).map((e) => e.key),
+      allKeys: entries.map((e) => e.key)
+    };
   } catch {
     return null;
   }
@@ -21721,6 +21730,10 @@ function findLeafPath(obj, key) {
   }
   return null;
 }
+function flattenLeafPaths(obj, prefix = []) {
+  if (!isRecord2(obj)) return prefix.length ? [prefix.join(".")] : [];
+  return Object.entries(obj).flatMap(([k, v]) => flattenLeafPaths(v, [...prefix, k]));
+}
 function dcqlToRevealAttributes(credentialQuery, vc) {
   if (!isRecord2(credentialQuery) || !Array.isArray(credentialQuery.credentials)) return [];
   const subject = isRecord2(vc) && isRecord2(vc.credentialSubject) ? vc.credentialSubject : void 0;
@@ -21743,7 +21756,9 @@ function dcqlToRevealAttributes(credentialQuery, vc) {
       }
     }
   }
-  return out;
+  if (!subject) return out;
+  const canonicalIndex = new Map(flattenLeafPaths(subject).map((path, i) => [path, i]));
+  return out.map((path, i) => ({ path, key: canonicalIndex.get(path) ?? Number.MAX_SAFE_INTEGER, i })).sort((a, b) => a.key - b.key || a.i - b.i).map((entry) => entry.path);
 }
 var MbiVpAdapter = class {
   constructor(mbi, signHexBlob, signMessage, holderAddress, resolveIssuerKeys, present) {
@@ -21794,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");
     }
@@ -21849,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);
@@ -21950,17 +21975,92 @@ function zetrixHexStringToBytes(s) {
   return out;
 }
 
+// src/clients/vc-cache.ts
+var import_node_crypto = require("node:crypto");
+var import_promises = require("node:fs/promises");
+var import_node_path = require("node:path");
+function cacheFileName(templateId) {
+  return `${(0, import_node_crypto.createHash)("sha256").update(templateId).digest("hex")}.json`;
+}
+function isCachedVcShape(value) {
+  return typeof value === "object" && value !== null && typeof value.templateId === "string" && "vc" in value && typeof value.issuedAt === "string";
+}
+function createFsVcCache(baseDir) {
+  return {
+    async get(templateId) {
+      try {
+        const raw = await (0, import_promises.readFile)((0, import_node_path.join)(baseDir, cacheFileName(templateId)), "utf8");
+        const parsed = JSON.parse(raw);
+        return isCachedVcShape(parsed) ? parsed : null;
+      } catch {
+        return null;
+      }
+    },
+    async set(templateId, entry) {
+      await (0, import_promises.mkdir)(baseDir, { recursive: true, mode: 448 });
+      await (0, import_promises.writeFile)((0, import_node_path.join)(baseDir, cacheFileName(templateId)), JSON.stringify(entry), { encoding: "utf8", mode: 384 });
+    },
+    async list() {
+      let files;
+      try {
+        files = await (0, import_promises.readdir)(baseDir);
+      } catch {
+        return [];
+      }
+      const entries = await Promise.all(
+        files.filter((f) => f.endsWith(".json")).map(async (f) => {
+          try {
+            const parsed = JSON.parse(await (0, import_promises.readFile)((0, import_node_path.join)(baseDir, f), "utf8"));
+            return isCachedVcShape(parsed) ? parsed : null;
+          } catch {
+            return null;
+          }
+        })
+      );
+      return entries.filter((e) => e !== null);
+    }
+  };
+}
+function isVcValid(entry, now = /* @__PURE__ */ new Date()) {
+  if (!entry.validUntil) return true;
+  const expiry = new Date(entry.validUntil);
+  if (Number.isNaN(expiry.getTime())) return false;
+  return expiry.getTime() > now.getTime();
+}
+function extractValidUntil(vc, fallback) {
+  if (typeof vc === "object" && vc !== null && "validUntil" in vc) {
+    const v = vc.validUntil;
+    if (typeof v === "string") return v;
+  }
+  return fallback;
+}
+
 // src/orchestrator/subscribe.ts
 async function subscribeAndIssue(deps, opts) {
   if (!/^did:zid:/.test(opts.templateId)) {
     return { issued: false, reason: `templateId must be a did:zid:... credential-definition id, got "${opts.templateId}"` };
   }
+  if (deps.cache && !opts.forceReissue && !opts.dryRun) {
+    const cached2 = await deps.cache.get(opts.templateId);
+    if (cached2 && isVcValid(cached2)) {
+      return {
+        issued: true,
+        vcId: cached2.vcId,
+        vc: cached2.vc,
+        txHash: cached2.txHash,
+        paidAsset: cached2.paidAsset,
+        amountPaid: cached2.amountPaid,
+        fromCache: true
+      };
+    }
+  }
+  const fields = deps.resolveTemplateFields ? await deps.resolveTemplateFields(opts.templateId) : null;
   const { agentDid, ...rest } = opts.attributes ?? {};
-  const attributes = agentDid ? opts.attributes : { agentDid: deps.holderDid, ...rest };
-  const required2 = deps.resolveRequiredFields ? await deps.resolveRequiredFields(opts.templateId) : null;
-  if (!opts.dryRun && required2) {
+  const shouldAutoFillAgentDid = !agentDid && fields !== null && fields.allKeys.includes("agentDid");
+  const attributes = shouldAutoFillAgentDid ? { agentDid: deps.holderDid, ...rest } : opts.attributes ?? {};
+  if (!opts.dryRun && fields) {
     const attrs = attributes;
-    const missing = required2.filter((k) => attrs[k] === void 0 || attrs[k] === null || attrs[k] === "");
+    const missing = fields.required.filter((k) => attrs[k] === void 0 || attrs[k] === null || attrs[k] === "");
     if (missing.length > 0) {
       return {
         issued: false,
@@ -21974,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) {
@@ -21986,7 +22110,7 @@ async function subscribeAndIssue(deps, opts) {
         asset: quotedAsset,
         maxAmountRequired: accept.maxAmountRequired,
         payTo: accept.payTo,
-        ...required2 ? { requiredAttributes: required2 } : {}
+        ...fields ? { requiredAttributes: fields.required } : {}
       }
     };
   }
@@ -21994,13 +22118,26 @@ async function subscribeAndIssue(deps, opts) {
   const issued = await deps.mbi.applySettle({ ...body, paymentId: challenge.paymentId }, xPayment);
   const rawAsset = String(accept.asset ?? "");
   const paidAsset = deps.resolveSymbol ? await deps.resolveSymbol(rawAsset) : rawAsset;
+  const amountPaid = String(accept.maxAmountRequired ?? "");
+  if (deps.cache) {
+    await deps.cache.set(opts.templateId, {
+      templateId: opts.templateId,
+      vc: issued.verifiableCredential,
+      vcId: issued.vcId,
+      txHash: issued.txHash,
+      paidAsset,
+      amountPaid,
+      issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      validUntil: extractValidUntil(issued.verifiableCredential, opts.expirationDate)
+    });
+  }
   return {
     issued: true,
     vcId: issued.vcId,
     vc: issued.verifiableCredential,
     txHash: issued.txHash,
     paidAsset,
-    amountPaid: String(accept.maxAmountRequired ?? "")
+    amountPaid
   };
 }
 
@@ -22011,29 +22148,76 @@ 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
+var TEMPLATE_ALIASES = [
+  {
+    match: "birthcert",
+    testnet: "did:zid:d6b783559acf6ba0f7ef6e1365bdaf0774d622d8d22728ca6323677f49ee94f8",
+    mainnet: "did:zid:032cb99be3577beccfc6252783c49c83673af38f8456d73462043654d7764e83"
+  }
+];
+function normalize(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function resolveTemplateAlias(input, network) {
+  if (/^did:zid:/.test(input)) return void 0;
+  const normalized = normalize(input);
+  const entry = TEMPLATE_ALIASES.find((e) => normalized.includes(e.match));
+  if (!entry) return void 0;
+  return network.includes("testnet") ? entry.testnet : entry.mainnet;
 }
 
 // src/mcp-tools.ts
+async function loadValidCachedCredentials(cache) {
+  if (!cache) return [];
+  const all = await cache.list();
+  return all.filter((entry) => isVcValid(entry));
+}
 function createTools(deps) {
   return {
     async wallet_status(input = {}) {
       const balances = deps.getBalances ? await deps.getBalances() : void 0;
+      const credentials = input.heldCredentials ?? (await loadValidCachedCredentials(deps.cache)).map((entry) => entry.vc);
       return {
         holderDid: deps.config.holderDid,
         zetrixAddress: deps.config.zetrixAddress,
         network: deps.config.network,
-        credentials: input.heldCredentials ?? [],
+        credentials,
         ...balances !== void 0 ? { balances } : {}
       };
     },
-    prove_identity(input) {
+    async prove_identity(input) {
+      let vc = input.vc;
+      if (vc === void 0) {
+        const cached2 = await loadValidCachedCredentials(deps.cache);
+        if (cached2.length === 0) {
+          throw new Error("prove_identity: no vc supplied and no valid credential is cached \u2014 call subscribe_and_issue first, or pass vc explicitly.");
+        }
+        if (cached2.length > 1) {
+          const ids = cached2.map((entry) => entry.templateId).join(", ");
+          throw new Error(`prove_identity: no vc supplied and multiple credentials are cached (templateIds: ${ids}) \u2014 pass vc explicitly to select one.`);
+        }
+        vc = cached2[0].vc;
+      }
       const wallet = deps.makeWallet({
-        vc: input.vc,
+        vc,
         revealAttribute: input.revealAttribute,
         issuerKeys: input.issuerKeys
       });
@@ -22043,10 +22227,18 @@ function createTools(deps) {
       return payAndFetch(deps.payer, input);
     },
     subscribe_and_issue(input) {
-      return subscribeAndIssue(deps.subscribeDeps, input);
+      const resolved = resolveTemplateAlias(input.templateId, deps.config.network);
+      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
+      );
     }
   };
 }
@@ -22063,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() {
@@ -22073,7 +22289,7 @@ function buildToolList() {
       inputSchema: {
         type: "object",
         properties: {
-          heldCredentials: { type: "array", items: { type: "object" }, description: "VCs the client holds (the wallet does not persist them)." }
+          heldCredentials: { type: "array", items: { type: "object" }, description: "VCs the client holds. Omit to report whatever the wallet has cached locally from prior subscribe_and_issue calls instead." }
         }
       }
     },
@@ -22084,7 +22300,7 @@ function buildToolList() {
         type: "object",
         properties: {
           proofRequest: { type: "string", description: "The PROOF-REQUEST header value from the 401 challenge." },
-          vc: { type: "object", description: "The client-held VerifiableCredential to present." },
+          vc: { type: "object", description: "The VerifiableCredential to present. Omit to use the wallet's single locally-cached credential, if there is exactly one \u2014 the call fails with a clear error if none or several are cached." },
           revealAttribute: { type: "array", items: { type: "string" }, description: "Dotted disclosure paths to reveal. Omit to reveal exactly the claims the challenge (DCQL) requests; a challenge naming no claims reveals all." },
           issuerKeys: {
             type: "object",
@@ -22095,7 +22311,7 @@ function buildToolList() {
             description: "Optional issuer verification keys to bypass the ZID resolver when it is unreachable (e.g. Cloudflare-gated). When set, resolution is skipped."
           }
         },
-        required: ["proofRequest", "vc"]
+        required: ["proofRequest"]
       }
     },
     {
@@ -22114,13 +22330,13 @@ function buildToolList() {
     },
     {
       name: "subscribe_and_issue",
-      description: "Obtain a VC from MBI: build the signed payload, pay x402, and return the issued credential. Payment is asset-agnostic \u2014 MBI's 402 challenge may quote the native ZETRIX token or a ZTP20 token (e.g. JMYR); pass dryRun:true first to see the quoted asset/amount for free before committing to pay.",
+      description: "Obtain a VC from MBI: build the signed payload, pay x402, and return the issued credential. If a still-valid credential for this templateId is already cached locally, it is returned directly with no payment (fromCache: true) \u2014 pass forceReissue:true to pay and issue fresh regardless. Payment is asset-agnostic \u2014 MBI's 402 challenge may quote the native ZETRIX token or a ZTP20 token (e.g. JMYR); pass dryRun:true first to see the quoted asset/amount for free before committing to pay.",
       inputSchema: {
         type: "object",
         properties: {
           templateId: {
             type: "string",
-            description: `The MBI credential-definition id to issue, e.g. "did:zid:...". Take this from the x401 challenge's credential_requirements.query.credentials[].id \u2014 NOT from requirementsId (that's just a label for the requirement set, e.g. "agent-identity").`
+            description: `The MBI credential-definition id to issue, e.g. "did:zid:...". Take this from the x401 challenge's credential_requirements.query.credentials[].id \u2014 NOT from requirementsId (that's just a label for the requirement set, e.g. "agent-identity"). A known template's natural-language name (e.g. "AI Birthcert") is also accepted and resolved to the right did:zid:... for the configured network.`
           },
           attributes: {
             type: "object",
@@ -22130,6 +22346,10 @@ function buildToolList() {
           dryRun: {
             type: "boolean",
             description: "Stop after MBI's free phase-1 quote and return { quote: { asset, maxAmountRequired, payTo, requiredAttributes? } } without paying or issuing \u2014 use this to check the payment requirement AND the template's required attributes (read from chain) before spending funds."
+          },
+          forceReissue: {
+            type: "boolean",
+            description: "Skip the local cache and pay + issue a fresh credential regardless of what is already cached."
           }
         },
         required: ["templateId", "attributes"]
@@ -22137,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"]
       }
@@ -22155,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(
@@ -22166,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.
 `
     );
   }
@@ -22186,7 +22422,9 @@ async function main() {
   const resolveSymbol = (asset) => resolveAssetSymbol(asset, contractQuery);
   const nodeBaseUrl = `https://${config2.nodeHost}${config2.nodePort ? `:${config2.nodePort}` : ""}`;
   const nodeMetaQuery = (url) => fetch(url, { headers: { Accept: "application/json" } }).then((r) => r.json());
-  const resolveRequiredFields = (templateId) => fetchTemplateRequiredFields(templateId, config2.templateRegistryAddress, nodeBaseUrl, nodeMetaQuery);
+  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_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);
@@ -22229,8 +22467,10 @@ async function main() {
     config: { holderDid, zetrixAddress, network: config2.network },
     makeWallet,
     payer,
-    subscribeDeps: { mbi, sign: subscribeSign, pay, resolveSymbol, holderDid, resolveRequiredFields },
-    createAccount: (password, label, purpose) => be.createAccount(password, label, purpose)
+    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);
   const server = new Server({ name: "agentic-wallet-mcp", version: packageVersion }, { capabilities: { tools: {} } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-wallet-mcp",
-  "version": "0.3.1",
+  "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",