agentic-wallet-mcp 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -8,6 +8,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Entries for 0.5.0 and earlier were reconstructed from commit history when this file was
 > introduced in 0.6.0, so they summarise each release rather than being exhaustive.
 
+## [0.8.0] — 17 August 2026
+
+### Added
+
+- **`request_ai_birthcert_verification` / `check_ai_birthcert_verification` tools** — a
+  **Verified** AI Birthcert flow via myid's SSIVC API, distinct from `subscribe_and_issue`'s
+  self-declared **Basic** AI Birthcert. `request_ai_birthcert_verification` starts a session and
+  returns a `verificationUrl` for the human owner to complete MyDigital ID verification;
+  `check_ai_birthcert_verification` polls that session and, once `status: "issued"`, fetches the
+  credential from MBI, verifies its subject against this wallet's `holderDid`, and caches it
+  locally (returned as `vc`, and from then on also visible via `wallet_status` and usable by
+  `prove_identity`) — a `cacheError` instead of `vc` means the credential was issued but could not
+  yet be fetched/verified/cached, which is not the same as issuance failing. Both tools are wired
+  whenever `SSIVC_BASE_URL` resolves — always on testnet; on mainnet only once set explicitly,
+  since the mainnet host was never actually confirmed reachable. `request_ai_birthcert_verification`'s
+  session creation is x402-payment-gated: the tool self-pays myid's 402 challenge, subject to the
+  wallet's `MAX_PAYMENT_AMOUNT` cap, the same as `pay_and_fetch`/`subscribe_and_issue`. A session
+  that goes terminal without minting a credential (owner never verifies, verification fails, etc.)
+  can be retried without paying again, since the payment stays valid until actually consumed —
+  concurrent requests are serialized so this can't double-pay, and switching to a different agent
+  name while a session is still pending is refused rather than silently losing track of it. New env
+  vars: `SSIVC_BASE_URL` (auto-derived on testnet only — `ssivc-api-uat.myegdev.com/api`; unset on
+  mainnet unless overridden) and `AI_BIRTHCERT_VERIFIED_TEMPLATE_ID` (same pattern — testnet only,
+  since the mainnet template id was never confirmed on-chain).
+
+### Fixed
+
+- **A malformed or unexpectedly-shaped response from MBI's credential-download endpoint no longer
+  crashes `check_ai_birthcert_verification` with a raw, undiagnosable error.** Found via live
+  testing against a real verification flow: MBI's response envelope turned out to be nested one
+  level deeper than expected. Both the crash and the actual envelope shape are now handled
+  correctly, confirmed end-to-end against a live credential issuance.
+- **A downloaded-but-not-yet-cached credential is no longer lost if it fails validation or the
+  process crashes before caching.** MBI's download is one-shot — a second attempt just fails — so
+  the raw response is now persisted immediately on arrival and re-validated from that copy on any
+  retry, instead of being discarded the moment a check (subject match, expiry) rejects it.
+- Fixed several smaller gaps found in the same review: an already-settled payment blob and an empty
+  payment-options response now return a clean error instead of an unhandled exception; a 409 with a
+  non-JSON body still reports the right error kind; an unrecognized session status is no longer
+  assumed safe to retry against; and switching agents no longer risks silently overwriting another
+  agent's still-unresolved payment.
+
+## [0.7.0] — 4 August 2026
+
+**Read the breaking change before upgrading if you make x402 payments.** This release lets the wallet
+provision itself, so it can start with no configuration at all — which is what makes an OpenClaw plugin
+install possible, and also why the payment cap now has to default to zero.
+
+### Changed (breaking)
+
+- **`MAX_PAYMENT_AMOUNT` now defaults to `{"*":"0"}` instead of being unset.** An unconfigured wallet
+  refuses every x402 payment rather than allowing any amount. Previously an unset cap disabled the
+  ceiling entirely, which was defensible only while every install required hand-written environment
+  variables; a wallet that can now start with no configuration must not be able to auto-pay a hostile
+  challenge. To keep paying, set the cap explicitly, e.g.
+  `MAX_PAYMENT_AMOUNT={"ZTX":"1000000000","*":"0"}`.
+
+- **`create_holder_account` no longer takes a `password` parameter.** The wallet uses the password
+  already active for the session, so a model can neither be asked for one nor supply one. A
+  `password` still passed by an old caller is **silently ignored** rather than rejected, because the
+  tool schema permits extra properties. Consequence: a newly minted account now inherits the session
+  password instead of taking a different one.
+
+### Added
+
+- **The wallet provisions itself.** `HSM_PASSWORD` and `ZETRIX_NETWORK` are both optional now.
+  With neither set, the wallet defaults to testnet, generates a random HSM password, creates a
+  holder account, and stores address, DID and password in its own state directory — so it starts
+  with no configuration at all. An explicit env var still wins over every other source, so an
+  existing `.mcp.json` behaves exactly as before.
+- **`npx agentic-wallet-mcp export-credentials`** prints the address, DID and HSM password for
+  backup. A generated password is the only thing that can authorize signing for the account, so
+  losing the state directory means losing the account. Interactive terminals only, and deliberately
+  not an MCP tool, so an agent can never read it.
+- **`--config <path>`** reads settings from a JSON file instead of the environment, for hosts that
+  cannot set env vars. It carries no secret: a `hsmPassword` key is a hard error, and so is any
+  unknown key, so a typo cannot silently start the wallet on the wrong network.
+- **`ZETRIX_WALLET_STATE_DIR`** moves `account.json` and the VC cache out of the home directory.
+  The default is unchanged.
+- `pay_and_fetch` and `subscribe_and_issue` now report a `not_activated` shortfall when the holder
+  address is not yet on chain, instead of reporting it as a low balance — the remedy is to send it
+  gas, not to top up a token.
+
+### Fixed
+
+- **A zero ZTX balance no longer reports `query_failed`.** The node omits the `balance` field
+  entirely when it is zero, and `wallet_status({ token: "ZTX" })` treated its absence as a failed
+  read — so every account holding no ZTX looked like a broken lookup. A successful RPC that omits a
+  zero-valued field is now read as `0`. A non-zero `errorCode`, or a response with no `result` at
+  all, still fails loudly rather than reporting a fabricated zero.
+
 ## [0.6.1] — 2026-07-29
 
 **Upgrade if you use testnet.** The testnet Wallet BE and MBI endpoints have moved to the Zetrix

package/README.md

@@ -27,6 +27,8 @@ VC issuance → identity proof → pay-per-use).
 | `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 }` |
 | `get_template_schema` | **Free** read of a VC template's declared attribute schema. Call before `subscribe_and_issue` to learn which attributes it requires | `{ templateId }` | `{ templateId, schema: { required, optional } }` or `{ templateId, error }` |
 | `query_contract` | Read-only query against any Zetrix contract — call an arbitrary method and return its raw result. No signing, no state change | `{ contractAddress, method, params? }` | `{ ok: true, result }` or `{ ok: false, error }` |
+| `request_ai_birthcert_verification` | Start a **Verified** AI Birthcert issuance session with myid (MyDigital ID owner verification) — distinct from `subscribe_and_issue`'s self-declared Basic AI Birthcert | `{ agentName, agentPurpose?, evidenceAssuranceLevel?, ownerType?, ownerVerified? }` | `{ sessionId, verificationUrl, expiresAt }` |
+| `check_ai_birthcert_verification` | Poll the most recently requested Verified AI Birthcert session; on `status: "issued"`, also fetches, verifies, and caches the credential | (none) | `{ status: "pending" \| "issued" \| "no_session", vcId?, vc?, cacheError? }` |
 
 > **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).
@@ -165,8 +167,8 @@ Node ≥ 18 required (built-in `fetch`).
 
 | Variable | Required | Description |
 |---|---|---|
-| `ZETRIX_NETWORK` | yes | `zetrix:testnet` or `zetrix:mainnet` — also selects the default `WALLET_BE_URL`/`MBI_BASE_URL`/`OID4VP_BASE_URL`/`ZID_RESOLVER_BASE_URL` below |
-| `HSM_PASSWORD` | yes* | HSM password |
+| `ZETRIX_NETWORK` | no | `zetrix:testnet` or `zetrix:mainnet` — also selects the default `WALLET_BE_URL`/`MBI_BASE_URL`/`OID4VP_BASE_URL`/`ZID_RESOLVER_BASE_URL` below. **Defaults to `zetrix:testnet`**; mainnet is always a deliberate choice |
+| `HSM_PASSWORD` | no* | HSM password. Omit it and the wallet generates one on first run and stores it in its own state directory — see "Onboarding" below |
 | `ZETRIX_ADDRESS` | no | Holder Zetrix address (the HSM account). Omit on first run — see "Onboarding" below |
 | `HOLDER_DID` | no | Holder DID. Omit and the MCP derives it automatically — see "Onboarding" below |
 | `WALLET_BE_URL` | no | Wallet BE base URL override (HSM `/wallet/hsm/sign-blob`) — auto-derived from `ZETRIX_NETWORK` when not set |
@@ -174,22 +176,27 @@ Node ≥ 18 required (built-in `fetch`).
 | `OID4VP_BASE_URL` | no | OID4VP verifier base URL override — auto-derived from `ZETRIX_NETWORK` by the x401 SDK when not set |
 | `ZETRIX_NODE_HOST` / `ZETRIX_NODE_PORT` | no | RPC node override (auto-derived from network) |
 | `ZID_RESOLVER_BASE_URL` | no | ZID resolver override (auto-derived from network: sandbox for testnet, prod for mainnet) |
-| `MAX_PAYMENT_AMOUNT` | no** | Per-asset x402 auto-pay cap — JSON `{ "<asset>": "<maxRawUnits>", "*": "<fallback>" }`. `pay_and_fetch`/`subscribe_and_issue` are asset-agnostic: the resource server's 402 challenge may quote the native ZETRIX token (asset code `ZTX`) **or** a ZTP20 token (e.g. `JMYR`) — cap whichever assets you expect, e.g. `{"ZTX":"1000000000","JMYR":"5000000","*":"0"}`. Unset = no cap enforced. |
+| `MAX_PAYMENT_AMOUNT` | no** | Per-asset x402 auto-pay cap — JSON `{ "<asset>": "<maxRawUnits>", "*": "<fallback>" }`. `pay_and_fetch`/`subscribe_and_issue` are asset-agnostic: the resource server's 402 challenge may quote the native ZETRIX token (asset code `ZTX`) **or** a ZTP20 token (e.g. `JMYR`) — cap whichever assets you expect. **Key by contract address, not symbol** — the challenge identifies a ZTP20 token by its contract address, so `{"JMYR":...}` never matches and falls through to `"*"`. e.g. `{"ZTX":"1000000000","ZTX3WeinXtt28YMyr4vUZ14ddTgEMGeuc1e6b":"5000000","*":"0"}`. **Defaults to `{"*":"0"}` — every payment is refused until you set this.** |
+| `ZETRIX_WALLET_STATE_DIR` | no | Where the wallet keeps `account.json` and its VC cache. Defaults to `~/.agentic-wallet-mcp` |
+| `SSIVC_BASE_URL` | no | myid's SSIVC API base URL, for the Verified AI Birthcert flow (`request_ai_birthcert_verification`/`check_ai_birthcert_verification`). **Auto-derived per network** — testnet `https://ssivc-api-uat.myegdev.com/api`, mainnet `https://verifyid-api.zetrix.com/api`. Override only if either changes |
+| `AI_BIRTHCERT_VERIFIED_TEMPLATE_ID` | no | The Verified AI Birthcert's on-chain `did:zid:...` template id. Auto-derived per network by default — **the mainnet default is unverified**, so override this explicitly once the mainnet template id is confirmed |
 
-\* sensitive — never logged.
+\* sensitive — never logged, never returned in a tool result, and never a tool parameter.
 
 ### Onboarding: two ways to set up your holder identity
 
 `ZETRIX_ADDRESS` and `HOLDER_DID` are both optional — the MCP resolves your holder identity at
 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, 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.
+1. **First-time user — nothing set at all, or 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. If you did not set `HSM_PASSWORD`, it generates one for you first. 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.
+
+   **If the wallet generated your password, back it up — see below.**
 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
@@ -201,13 +208,28 @@ startup, in one of two ways:
 Either way, `wallet_status` always reports the resolved `zetrixAddress`/`holderDid` for the
 running session, so you can confirm what the MCP resolved to at any time.
 
-\*\* **strongly recommended before pointing this wallet at mainnet/real funds.** `pay_and_fetch`
-and `subscribe_and_issue` auto-pay whatever `maxAmountRequired` a remote server's 402 challenge
-demands, with no built-in ceiling — a prompt-injected or misled agent calling either tool against
-a hostile endpoint would pay whatever that endpoint asks for, bounded only by the HSM account
-balance. `MAX_PAYMENT_AMOUNT` is a hard, code-enforced cap that holds regardless of what the
-calling agent decides. Once set, it becomes an allowlist: an asset with no entry and no `"*"`
-fallback is **denied**, not passed through uncapped.
+### Backing up a self-provisioned wallet
+
+If you never set `HSM_PASSWORD`, the wallet generated one and stored it in
+`~/.agentic-wallet-mcp/account.json`. You never have to type it — but it is the only thing that
+can authorize signing for your account. Wallet BE holds the key and will not use it without this
+password, so if you lose the file the account cannot be recovered and any funds in it are gone.
+Back it up with:
+
+```bash
+npx agentic-wallet-mcp export-credentials
+```
+
+This only runs in an interactive terminal, so it can't be piped into a file or a log, and it is
+deliberately **not** available as an MCP tool — an AI agent can never read your password.
+
+\*\* **You must set this before the wallet will pay for anything.** It defaults to `{"*":"0"}`,
+which refuses every payment. `pay_and_fetch` and `subscribe_and_issue` auto-pay whatever
+`maxAmountRequired` a remote server's 402 challenge demands, so without a ceiling a prompt-injected
+or misled agent calling either tool against a hostile endpoint would pay whatever that endpoint
+asks for, bounded only by the account balance. `MAX_PAYMENT_AMOUNT` is a hard, code-enforced cap
+that holds regardless of what the calling agent decides. It is also an allowlist: an asset with no
+entry and no `"*"` fallback is **denied**, not passed through uncapped.
 
 You don't need to look up or fill in `WALLET_BE_URL`/`MBI_BASE_URL`/`OID4VP_BASE_URL`/
 `ZID_RESOLVER_BASE_URL` yourself — just pick `zetrix:testnet` or `zetrix:mainnet` for

package/dist/server-bundle.cjs

@@ -12540,14 +12540,15 @@ __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");
+var import_node_crypto5 = require("node:crypto");
+var import_node_fs = require("node:fs");
+var import_node_os2 = require("node:os");
+var import_node_path6 = require("node:path");
 
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.6.1",
+  version: "0.8.0",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   keywords: [
     "mcp",
@@ -21489,6 +21490,10 @@ var X401Wallet = class {
 // src/index.ts
 var import_zetrix_sdk_nodejs = __toESM(require("zetrix-sdk-nodejs"), 1);
 
+// src/config.ts
+var import_node_os = require("node:os");
+var import_node_path = require("node:path");
+
 // src/payment-guard.ts
 var PaymentCapError = class extends Error {
   constructor(message) {
@@ -21556,6 +21561,12 @@ function deriveMbiBaseUrl(network) {
 function deriveTemplateRegistryAddress(network) {
   return network.includes("testnet") ? "ZTX3JszqPgRUx743SAp7q7zURfjvkWuH2FMEz" : "ZTX3GqJM1U6ifMPonwD4fGvrgoTKJua7b2cKX";
 }
+function deriveSsivcBaseUrl(network) {
+  return network.includes("testnet") ? "https://ssivc-api-uat.myegdev.com/api" : void 0;
+}
+function deriveAiBirthcertVerifiedTemplateId(network) {
+  return network.includes("testnet") ? "did:zid:9641ee92552e9bcec672f300b071ff86d340ac78c83c225e95971cab8108fb80" : void 0;
+}
 var TOKEN_REGISTRY = {
   JMYR: { testnet: "ZTX3WeinXtt28YMyr4vUZ14ddTgEMGeuc1e6b", mainnet: "ZTX3NCkXBqbyJWjZZxciQez945Lu6tGAcjNJr" }
 };
@@ -21574,24 +21585,33 @@ function loadConfig(env) {
     const v = env[key];
     return v && v.trim() ? v.trim() : void 0;
   };
-  const network = req("ZETRIX_NETWORK");
+  const network = opt("ZETRIX_NETWORK") ?? "zetrix:testnet";
   const oid4vpBaseUrlOverride = opt("OID4VP_BASE_URL");
   return {
     walletBeUrl: stripTrailingSlash(opt("WALLET_BE_URL") ?? deriveWalletBeUrl(network)),
     oid4vpBaseUrl: oid4vpBaseUrlOverride ? stripTrailingSlash(oid4vpBaseUrlOverride) : void 0,
     mbiBaseUrl: stripTrailingSlash(opt("MBI_BASE_URL") ?? deriveMbiBaseUrl(network)),
     network,
+    stateDir: stripTrailingSlash(opt("ZETRIX_WALLET_STATE_DIR") ?? (0, import_node_path.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp")),
     zetrixAddress: opt("ZETRIX_ADDRESS"),
     holderDid: opt("HOLDER_DID"),
     hsmPassword: req(
       "HSM_PASSWORD",
-      "set your own HSM password in the MCP config before starting the server \u2014 this MCP never generates, invents, or infers a password on your behalf"
+      "the server is normally started through main(), which generates a password when none exists \u2014 reaching this error means loadConfig was called directly without one"
     ),
     nodeHost: opt("ZETRIX_NODE_HOST") ?? deriveNodeHost(network),
     nodePort: opt("ZETRIX_NODE_PORT") ?? "",
     templateRegistryAddress: opt("ZETRIX_TEMPLATE_REGISTRY_ADDRESS") ?? deriveTemplateRegistryAddress(network),
     zidResolverBaseUrl: stripTrailingSlash(opt("ZID_RESOLVER_BASE_URL") ?? deriveZidResolverBaseUrl(network)),
-    maxPaymentAmount: parsePaymentCaps(opt("MAX_PAYMENT_AMOUNT"))
+    // Fail closed: an unset cap means "spend nothing", not "spend anything". A wallet that starts
+    // with no configuration at all must not be able to auto-pay a hostile x402 challenge. Raising
+    // it is a deliberate act.
+    maxPaymentAmount: parsePaymentCaps(opt("MAX_PAYMENT_AMOUNT")) ?? { "*": "0" },
+    ssivcBaseUrl: (() => {
+      const v = opt("SSIVC_BASE_URL") ?? deriveSsivcBaseUrl(network);
+      return v ? stripTrailingSlash(v) : void 0;
+    })(),
+    aiBirthcertVerifiedTemplateId: opt("AI_BIRTHCERT_VERIFIED_TEMPLATE_ID") ?? deriveAiBirthcertVerifiedTemplateId(network)
   };
 }
 
@@ -21654,6 +21674,15 @@ async function queryContract(input, query) {
 
 // src/clients/token-balance-client.ts
 var ZTX_DECIMALS = 6;
+function parseNativeBalance(res) {
+  if (res?.errorCode !== 0) throw new Error(`getInfo failed with errorCode ${res?.errorCode}`);
+  if (res.result === void 0 || res.result === null) throw new Error("getInfo returned no result");
+  const balance = res.result.balance;
+  if (typeof balance === "string") return balance;
+  if (typeof balance === "number" && Number.isFinite(balance)) return String(balance);
+  if (balance === void 0 || balance === null) return "0";
+  throw new Error(`getInfo returned an unusable balance of type ${typeof balance}`);
+}
 async function fetchZTP20BalanceStrict(contractAddress, address, query) {
   const result = await query({
     contractAddress,
@@ -21984,6 +22013,18 @@ var MbiClient = class _MbiClient {
     if (!res.ok) throw await this.error(res, "vp/ext/submit failed");
     return this.unwrap(res);
   }
+  /** POST /v1/vc/ext/download — holder-authenticated; returns EVERY VC for the address, not one. */
+  async downloadVcs(body, auth) {
+    const res = await this.fetch("POST", "/v1/vc/ext/download", body, { signedData: auth.signedData, publicKey: auth.publicKey });
+    if (!res.ok) throw await this.error(res, "vc/ext/download failed");
+    const raw = await this.unwrap(res);
+    const nested = raw !== null && typeof raw === "object" ? raw.data : void 0;
+    const data = Array.isArray(raw) ? raw : Array.isArray(nested) ? nested : void 0;
+    if (!data) {
+      throw new MbiError(`MBI vc/ext/download succeeded (2xx) but returned a non-array data envelope: ${JSON.stringify(raw)}`, res.status);
+    }
+    return data;
+  }
   fetch(method, path, body, extraHeaders) {
     const headers = { Accept: "application/json", ...extraHeaders ?? {} };
     if (body !== void 0) headers["Content-Type"] = "application/json";
@@ -22109,7 +22150,7 @@ function zetrixHexStringToBytes(s) {
 // 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");
+var import_node_path2 = require("node:path");
 function cacheFileName(templateId) {
   return `${(0, import_node_crypto.createHash)("sha256").update(templateId).digest("hex")}.json`;
 }
@@ -22120,7 +22161,7 @@ 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 raw = await (0, import_promises.readFile)((0, import_node_path2.join)(baseDir, cacheFileName(templateId)), "utf8");
         const parsed = JSON.parse(raw);
         return isCachedVcShape(parsed) ? parsed : null;
       } catch {
@@ -22129,7 +22170,7 @@ function createFsVcCache(baseDir) {
     },
     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 });
+      await (0, import_promises.writeFile)((0, import_node_path2.join)(baseDir, cacheFileName(templateId)), JSON.stringify(entry), { encoding: "utf8", mode: 384 });
     },
     async list() {
       let files;
@@ -22141,7 +22182,7 @@ function createFsVcCache(baseDir) {
       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"));
+            const parsed = JSON.parse(await (0, import_promises.readFile)((0, import_node_path2.join)(baseDir, f), "utf8"));
             return isCachedVcShape(parsed) ? parsed : null;
           } catch {
             return null;
@@ -22189,8 +22230,14 @@ var PaymentReadinessError = class extends Error {
     this.shortfall = shortfall;
   }
 };
-function toPaymentReadinessError(err, requestedAsset) {
+function toPaymentReadinessError(err, requestedAsset, activated) {
   if (!(err instanceof import_x402_zetrix_client.InsufficientBalanceError)) return null;
+  if (activated === false) {
+    return new PaymentReadinessError(
+      `payment blocked: this wallet's address has not been activated on chain yet \u2014 send ZTX to it from a funded account, then retry`,
+      { asset: err.asset, required: err.required, available: err.available, reason: "not_activated" }
+    );
+  }
   const reason = err.asset === "ZTX" && requestedAsset !== "ZTX" ? "gas" : "resource_payment";
   return new PaymentReadinessError(err.message, {
     asset: err.asset,
@@ -22199,11 +22246,11 @@ function toPaymentReadinessError(err, requestedAsset) {
     reason
   });
 }
-async function payWithReadinessCheck(requestedAsset, rawPay) {
+async function payWithReadinessCheck(requestedAsset, rawPay, activated) {
   try {
     return await rawPay();
   } catch (err) {
-    const readinessError = toPaymentReadinessError(err, requestedAsset);
+    const readinessError = toPaymentReadinessError(err, requestedAsset, activated);
     if (readinessError) throw readinessError;
     throw err;
   }
@@ -22412,9 +22459,9 @@ async function createHolderAccount(deps, input) {
       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, activated } = await deps.create(input.password, input.label, input.purpose);
+  const { zetrixAddress, publicKeyHex, activated } = await deps.create(input.label, input.purpose);
   const holderDid = deriveHolderDid(publicKeyHex);
-  await deps.saveAccount({ zetrixAddress, holderDid, hsmPassword: input.password, label: input.label, purpose: input.purpose });
+  await deps.saveAccount({ zetrixAddress, holderDid, label: input.label, purpose: input.purpose });
   const finalActivated = activated || await waitForActivation(deps.checkActivationStatus, zetrixAddress, deps.sleep);
   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).` + (finalActivated ? "" : ` Note: on-chain activation has not completed yet \u2014 balance/on-chain calls for this address may fail until it does; check again later.`);
   return { created: true, alreadyExists: Boolean(existing), zetrixAddress, holderDid, publicKeyHex, activated: finalActivated, message };
@@ -22796,6 +22843,7 @@ async function loadValidCachedCredentials(cache) {
   const all = await cache.list();
   return all.filter((entry) => isVcValid(entry));
 }
+var AI_BIRTHCERT_NOT_CONFIGURED_ERROR = "AI Birthcert verification is not configured on this wallet. On mainnet this is expected until SSIVC_BASE_URL is set explicitly (the mainnet host was never confirmed reachable \u2014 APP-M04); on testnet it means verifyAiBirthcert was not wired at all.";
 function createTools(deps) {
   return {
     async wallet_status(input = {}) {
@@ -22898,6 +22946,18 @@ function createTools(deps) {
         },
         input
       );
+    },
+    request_ai_birthcert_verification(input) {
+      if (!deps.verifyAiBirthcert) {
+        return { error: AI_BIRTHCERT_NOT_CONFIGURED_ERROR };
+      }
+      return deps.verifyAiBirthcert.request(input);
+    },
+    check_ai_birthcert_verification() {
+      if (!deps.verifyAiBirthcert) {
+        return { error: AI_BIRTHCERT_NOT_CONFIGURED_ERROR };
+      }
+      return deps.verifyAiBirthcert.check();
     }
   };
 }
@@ -22914,17 +22974,131 @@ async function resolveHolder(deps, input) {
         finalActivated = false;
       }
     }
-    return { zetrixAddress, holderDid: deriveHolderDid(publicKeyHex), created: true, didMismatch: false, activated: finalActivated };
+    return { zetrixAddress, holderDid: deriveHolderDid(publicKeyHex), publicKeyHex, created: true, didMismatch: false, activated: finalActivated };
   }
   const { publicKey } = await deps.signMessage(input.zetrixAddress, input.zetrixAddress, input.hsmPassword);
   const derivedDid = deriveHolderDid(publicKey);
   const didMismatch = input.holderDid !== void 0 && input.holderDid !== derivedDid;
-  return { zetrixAddress: input.zetrixAddress, holderDid: derivedDid, created: false, didMismatch };
+  return { zetrixAddress: input.zetrixAddress, holderDid: derivedDid, publicKeyHex: publicKey, created: false, didMismatch };
+}
+
+// src/startup-env.ts
+function resolveStartupEnv(input) {
+  const env = { ...input.fileEnv, ...input.processEnv };
+  const stored = input.storedAccount;
+  if (!env.ZETRIX_ADDRESS && stored) env.ZETRIX_ADDRESS = stored.zetrixAddress;
+  if (!env.HOLDER_DID && stored) env.HOLDER_DID = stored.holderDid;
+  if (!env.HSM_PASSWORD && stored) env.HSM_PASSWORD = stored.hsmPassword;
+  let passwordGenerated = false;
+  if (!env.HSM_PASSWORD) {
+    env.HSM_PASSWORD = input.generatePassword();
+    passwordGenerated = true;
+  }
+  return { env, passwordGenerated };
+}
+
+// src/config-file.ts
+var KEY_TO_ENV = {
+  network: "ZETRIX_NETWORK",
+  zetrixAddress: "ZETRIX_ADDRESS",
+  holderDid: "HOLDER_DID",
+  maxPaymentAmount: "MAX_PAYMENT_AMOUNT",
+  stateDir: "ZETRIX_WALLET_STATE_DIR",
+  walletBeUrl: "WALLET_BE_URL",
+  mbiBaseUrl: "MBI_BASE_URL"
+};
+var FORBIDDEN_KEYS = ["hsmPassword", "password", "HSM_PASSWORD"];
+function configPathFrom(argv) {
+  const inline = argv.find((a) => a.startsWith("--config="));
+  if (inline) {
+    const path2 = inline.slice("--config=".length);
+    if (!path2) throw new Error("agentic-wallet-mcp: --config requires a file path");
+    return path2;
+  }
+  const i = argv.indexOf("--config");
+  if (i === -1) return null;
+  const path = argv[i + 1];
+  if (!path || path.startsWith("--")) throw new Error("agentic-wallet-mcp: --config requires a file path");
+  return path;
+}
+function loadConfigFileEnv(argv, readFile5) {
+  const path = configPathFrom(argv);
+  if (path === null) return {};
+  let raw;
+  try {
+    raw = readFile5(path);
+  } catch (e) {
+    throw new Error(`agentic-wallet-mcp: cannot read config file ${path}: ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`agentic-wallet-mcp: config file ${path} is not valid JSON: ${e.message}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`agentic-wallet-mcp: config file ${path} must contain a JSON object`);
+  }
+  const env = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (FORBIDDEN_KEYS.includes(key)) {
+      throw new Error(
+        `agentic-wallet-mcp: config file ${path} must not contain a secret ("${key}") \u2014 the wallet generates and stores its own HSM password, so no credential belongs in this file.`
+      );
+    }
+    const envKey = KEY_TO_ENV[key];
+    if (!envKey) {
+      throw new Error(
+        `agentic-wallet-mcp: unknown config key "${key}" in ${path} \u2014 allowed: ${Object.keys(KEY_TO_ENV).join(", ")}`
+      );
+    }
+    env[envKey] = typeof value === "string" ? value : JSON.stringify(value);
+  }
+  return env;
+}
+
+// src/hsm-password.ts
+var import_node_crypto2 = require("node:crypto");
+function generateHsmPassword() {
+  return (0, import_node_crypto2.randomBytes)(24).toString("base64url");
+}
+
+// src/export-credentials.ts
+async function exportCredentials(deps) {
+  if (!deps.isTty) {
+    deps.writeErr(
+      "agentic-wallet-mcp: export-credentials only runs in an interactive terminal, so the password cannot be piped into a file or a log. Run it directly in your shell.\n"
+    );
+    return { exitCode: 1 };
+  }
+  const account = await deps.getAccount();
+  if (!account) {
+    deps.writeErr(
+      "agentic-wallet-mcp: no account has been created yet \u2014 start the wallet once to provision one, then run this again.\n"
+    );
+    return { exitCode: 1 };
+  }
+  deps.write(
+    `
+Zetrix Agentic Wallet \u2014 credentials for backup
+
+  Address:      ${account.zetrixAddress}
+  Holder DID:   ${account.holderDid}
+  HSM password: ${account.hsmPassword}
+
+Store these somewhere safe and private, such as a password manager.
+The HSM password is the only thing that can authorize signing for this wallet. If you lose it
+and lose this machine's wallet state, the account cannot be recovered and any funds in it are
+permanently inaccessible.
+
+`
+  );
+  return { exitCode: 0 };
 }
 
 // src/clients/account-store.ts
 var import_promises2 = require("node:fs/promises");
-var import_node_path2 = require("node:path");
+var import_node_path3 = require("node:path");
 function isStoredAccountShape(value) {
   return typeof value === "object" && value !== null && typeof value.zetrixAddress === "string" && typeof value.holderDid === "string" && typeof value.hsmPassword === "string";
 }
@@ -22940,12 +23114,369 @@ function createFsAccountStore(filePath) {
       }
     },
     async set(account) {
-      await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(filePath), { recursive: true, mode: 448 });
+      await (0, import_promises2.mkdir)((0, import_node_path3.dirname)(filePath), { recursive: true, mode: 448 });
       await (0, import_promises2.writeFile)(filePath, JSON.stringify(account, null, 2), { encoding: "utf8", mode: 384 });
     }
   };
 }
 
+// src/clients/ssivc-client.ts
+var SsivcError = class extends Error {
+  httpStatus;
+  /** SSIVC's own `status_code` string (distinct from the HTTP status) — e.g. "50" signature invalid, "55" expired timestamp, "23" not found. */
+  statusCode;
+  /** Classifies the x402-era error responses — see ADDENDUM_X402_SESSION_GATING.md §6. Undefined for the older 400/404/malformed-envelope cases. */
+  kind;
+  constructor(message, httpStatus, statusCode, kind) {
+    super(message);
+    this.name = "SsivcError";
+    this.httpStatus = httpStatus;
+    this.statusCode = statusCode;
+    this.kind = kind;
+  }
+};
+var SESSIONS_PATH = "/v2/verify/ai-birthcert/sessions";
+var SsivcClient = class {
+  baseUrl;
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+  }
+  /** Phase 1 — POST with no payment headers. SSIVC always responds 402 with the raw x402 envelope. */
+  async createSessionChallenge(body) {
+    const res = await this.fetch("POST", SESSIONS_PATH, body);
+    if (res.status !== 402) throw await this.error(res, "createSessionChallenge: expected 402 payment_required");
+    const raw = await res.json();
+    return { x402Version: raw.x402Version, accepts: raw.accepts ?? [] };
+  }
+  /** Fresh pay — retry with `X-Payment`. Returns the session plus the settlement receipt to persist. */
+  createSessionSettle(body, xPayment) {
+    return this.createSessionPaid(body, { "X-Payment": xPayment });
+  }
+  /** Retry after a failed-issuance terminal session — replays a still-unconsumed settlement receipt. Never sent alongside `X-Payment`. */
+  createSessionWithReceipt(body, paymentReceipt) {
+    return this.createSessionPaid(body, { "X-Payment-Response": paymentReceipt });
+  }
+  async createSessionPaid(body, paymentHeader) {
+    const res = await this.fetch("POST", SESSIONS_PATH, body, paymentHeader);
+    if (!res.ok) throw await this.error(res, "createSession (paid) failed");
+    const env = await res.json();
+    const data = env.data;
+    if (!data || typeof data !== "object" || !data.sessionId || !data.verification_url || !data.expiresAt) {
+      throw new SsivcError("SSIVC createSession succeeded (2xx) but returned a malformed data envelope", res.status);
+    }
+    const paymentReceipt = res.headers.get("x-payment-response");
+    if (!paymentReceipt) {
+      throw new SsivcError("SSIVC createSession succeeded (2xx) but returned no X-Payment-Response settlement receipt header", res.status);
+    }
+    return {
+      session: { sessionId: data.sessionId, verificationUrl: data.verification_url, expiresAt: data.expiresAt },
+      paymentReceipt
+    };
+  }
+  async getSession(sessionId) {
+    const res = await this.fetch("GET", `${SESSIONS_PATH}/${encodeURIComponent(sessionId)}`);
+    if (!res.ok) throw await this.error(res);
+    const env = await res.json();
+    const data = env.data;
+    if (!data || typeof data !== "object" || typeof data.sessionId !== "string" || typeof data.status !== "string") {
+      throw new SsivcError("SSIVC getSession succeeded (2xx) but returned a malformed data envelope", res.status);
+    }
+    return data;
+  }
+  fetch(method, path, body, extraHeaders) {
+    const headers = { Accept: "application/json", ...extraHeaders ?? {} };
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    return fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+    }).catch((e) => {
+      throw new SsivcError(`SSIVC ${path} request failed: ${e.message}`);
+    });
+  }
+  async error(res, context) {
+    const text = await res.text().catch(() => "");
+    let msg = text;
+    let statusCode;
+    let kind;
+    if (res.status === 409) kind = "blob_already_settled";
+    else if (res.status === 400 || res.status === 422) kind = "validation";
+    try {
+      const j = JSON.parse(text);
+      statusCode = j.status_code;
+      msg = j.errors?.length ? j.errors.join("; ") : j.message ?? j.error ?? text;
+      if (res.status === 402 && j.error === "payment_invalid") kind = "payment_invalid";
+      else if (res.status === 503 && j.error === "facilitator_unavailable") kind = "facilitator_unavailable";
+    } catch {
+    }
+    const prefix = context ? `${context} \u2014 ` : "";
+    return new SsivcError(`${prefix}SSIVC request failed \u2014 HTTP ${res.status}: ${msg}`, res.status, statusCode, kind);
+  }
+};
+
+// src/clients/ssivc-session-store.ts
+var import_promises3 = require("node:fs/promises");
+var import_node_path4 = require("node:path");
+function isStoredSessionShape(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.sessionId === "string" && typeof v.agentName === "string" && typeof v.createdAt === "string" && typeof v.verificationUrl === "string" && typeof v.paymentReceipt === "string";
+}
+function createFsSsivcSessionStore(filePath) {
+  return {
+    async get() {
+      try {
+        const raw = await (0, import_promises3.readFile)(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        return isStoredSessionShape(parsed) ? parsed : null;
+      } catch {
+        return null;
+      }
+    },
+    async set(session) {
+      await (0, import_promises3.mkdir)((0, import_node_path4.dirname)(filePath), { recursive: true, mode: 448 });
+      const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+      await (0, import_promises3.writeFile)(tmpPath, JSON.stringify(session, null, 2), { encoding: "utf8", mode: 384 });
+      await (0, import_promises3.rename)(tmpPath, filePath);
+    }
+  };
+}
+
+// src/clients/ssivc-download-quarantine-store.ts
+var import_node_crypto3 = require("node:crypto");
+var import_promises4 = require("node:fs/promises");
+var import_node_path5 = require("node:path");
+function quarantineFileName(vcId) {
+  return `${(0, import_node_crypto3.createHash)("sha256").update(vcId).digest("hex")}.json`;
+}
+function isQuarantinedDownloadShape(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.vcId === "string" && "entries" in v && typeof v.downloadedAt === "string";
+}
+function createFsDownloadQuarantineStore(baseDir) {
+  const pathFor = (vcId) => (0, import_node_path5.join)(baseDir, quarantineFileName(vcId));
+  return {
+    filePathFor: pathFor,
+    async get(vcId) {
+      try {
+        const raw = await (0, import_promises4.readFile)(pathFor(vcId), "utf8");
+        const parsed = JSON.parse(raw);
+        return isQuarantinedDownloadShape(parsed) ? parsed : null;
+      } catch {
+        return null;
+      }
+    },
+    async set(entry) {
+      await (0, import_promises4.mkdir)(baseDir, { recursive: true, mode: 448 });
+      const filePath = pathFor(entry.vcId);
+      const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+      await (0, import_promises4.writeFile)(tmpPath, JSON.stringify(entry, null, 2), { encoding: "utf8", mode: 384 });
+      await (0, import_promises4.rename)(tmpPath, filePath);
+    }
+  };
+}
+
+// src/orchestrator/verify-ai-birthcert.ts
+var import_node_crypto4 = require("node:crypto");
+
+// src/canonical-json.ts
+function canonicalizeJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => canonicalizeJson(v)).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    const record2 = value;
+    const keys = Object.keys(record2).filter((k) => record2[k] !== void 0).sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalizeJson(record2[k])}`);
+    return `{${parts.join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+// src/orchestrator/verify-ai-birthcert.ts
+function subjectMatches(vc, holderDid) {
+  if (typeof vc !== "object" || vc === null) return false;
+  const subject = vc.credentialSubject;
+  const subjectId = typeof subject === "object" && subject !== null ? subject.id : void 0;
+  return subjectId === holderDid;
+}
+function observedSubjectId(vc) {
+  if (typeof vc !== "object" || vc === null) return "missing";
+  const subject = vc.credentialSubject;
+  const subjectId = typeof subject === "object" && subject !== null ? subject.id : void 0;
+  return typeof subjectId === "string" && subjectId ? subjectId : "missing";
+}
+function isoSeconds(date3) {
+  return date3.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+async function getConfirmedStatus(deps, sessionId) {
+  try {
+    return await deps.ssivc.getSession(sessionId);
+  } catch (err) {
+    if (!(err instanceof SsivcError) || err.httpStatus !== 404) throw err;
+    return "gone";
+  }
+}
+async function decidePriorSession(deps, agentName) {
+  const stored = await deps.sessionStore.get();
+  if (!stored) return { kind: "pay_fresh" };
+  if (stored.agentName !== agentName) {
+    const otherStatus = await getConfirmedStatus(deps, stored.sessionId);
+    if (otherStatus === "gone") return { kind: "replay_receipt", receipt: stored.paymentReceipt };
+    if (otherStatus.status !== "issued") {
+      return {
+        kind: "blocked",
+        message: `a verification session for a different agent ("${stored.agentName}") is still in progress (status: "${otherStatus.status}") and its payment has not been consumed yet \u2014 starting a new session for "${agentName}" would lose track of it. Call check_ai_birthcert_verification to resolve or confirm it first.`
+      };
+    }
+    return { kind: "pay_fresh" };
+  }
+  const status = await getConfirmedStatus(deps, stored.sessionId);
+  if (status === "gone") return { kind: "replay_receipt", receipt: stored.paymentReceipt };
+  if (status.status === "pending") {
+    return {
+      kind: "still_pending",
+      result: { sessionId: stored.sessionId, verificationUrl: stored.verificationUrl, expiresAt: status.expiresAt }
+    };
+  }
+  if (status.status === "issued") return { kind: "pay_fresh" };
+  throw new Error(
+    `requestAiBirthcertVerification: unrecognized prior session status "${status.status}" for session ${stored.sessionId} \u2014 refusing to guess whether its settlement receipt is safe to replay (see SPEC.md D8)`
+  );
+}
+var requestQueue = Promise.resolve();
+function withRequestLock(fn) {
+  const run = requestQueue.then(fn, fn);
+  requestQueue = run.then(
+    () => void 0,
+    () => void 0
+  );
+  return run;
+}
+var NoPaymentOptionsError = class extends Error {
+};
+async function payAndCreateSession(deps, body) {
+  const challenge = await deps.ssivc.createSessionChallenge(body);
+  const accept = challenge.accepts[0];
+  if (!accept) throw new NoPaymentOptionsError("SSIVC 402 returned no payment options");
+  const xPayment = await deps.pay(accept);
+  return deps.ssivc.createSessionSettle(body, xPayment);
+}
+async function requestAiBirthcertVerification(deps, input) {
+  if (!input.agentName || !input.agentName.trim()) {
+    throw new Error("requestAiBirthcertVerification: agentName is required");
+  }
+  const agentName = input.agentName.trim();
+  return withRequestLock(() => requestAiBirthcertVerificationLocked(deps, agentName, input));
+}
+async function requestAiBirthcertVerificationLocked(deps, agentName, input) {
+  const decision = await decidePriorSession(deps, agentName);
+  if (decision.kind === "still_pending") return decision.result;
+  if (decision.kind === "blocked") return { error: decision.message };
+  const fields = {
+    publicKey: deps.publicKeyHex,
+    address: deps.address,
+    timestamp: isoSeconds(deps.now()),
+    agentName,
+    id: agentName,
+    ownerReference: deps.holderDid
+  };
+  if (input.agentPurpose) fields.agentPurpose = input.agentPurpose;
+  if (input.evidenceAssuranceLevel) fields.evidenceAssuranceLevel = input.evidenceAssuranceLevel;
+  if (input.ownerType) fields.ownerType = input.ownerType;
+  if (input.ownerVerified) fields.ownerVerified = input.ownerVerified;
+  const digestHex = (0, import_node_crypto4.createHash)("sha256").update(canonicalizeJson(fields), "utf8").digest("hex");
+  const { signBlob: signedData } = await deps.signHexBlob(digestHex);
+  const body = { ...fields, signedData };
+  let paid;
+  try {
+    paid = decision.kind === "replay_receipt" ? await deps.ssivc.createSessionWithReceipt(body, decision.receipt) : await payAndCreateSession(deps, body);
+  } catch (err) {
+    if (err instanceof PaymentReadinessError) return { error: `insufficient funds: ${err.message}` };
+    if (err instanceof PaymentCapError) return { error: err.message };
+    if (err instanceof NoPaymentOptionsError) return { error: err.message };
+    if (err instanceof SsivcError && err.kind === "blob_already_settled") {
+      return { error: `payment already settled for this attempt: ${err.message}` };
+    }
+    throw err;
+  }
+  await deps.sessionStore.set({
+    sessionId: paid.session.sessionId,
+    agentName,
+    createdAt: deps.now().toISOString(),
+    verificationUrl: paid.session.verificationUrl,
+    paymentReceipt: paid.paymentReceipt
+  });
+  return paid.session;
+}
+async function checkAiBirthcertVerification(deps) {
+  const stored = await deps.sessionStore.get();
+  if (!stored) {
+    return {
+      status: "no_session",
+      message: "No verification session found for this wallet \u2014 call request_ai_birthcert_verification first."
+    };
+  }
+  const status = await deps.ssivc.getSession(stored.sessionId);
+  if (status.status !== "issued" || !status.vcId) return status;
+  if (deps.verifiedTemplateId && deps.cache) {
+    const cached2 = await deps.cache.get(deps.verifiedTemplateId);
+    if (cached2 && cached2.vcId === status.vcId && isVcValid(cached2)) return { ...status, vc: cached2.vc };
+  }
+  if (!deps.verifiedTemplateId || !deps.cache) {
+    return { ...status, cacheError: "AI Birthcert verified-template id is not configured \u2014 cannot fetch or cache the credential yet." };
+  }
+  const quarantined = await deps.quarantine.get(status.vcId);
+  const quarantineFilePath = deps.quarantine.filePathFor(status.vcId);
+  let entries;
+  if (quarantined) {
+    entries = quarantined.entries;
+  } else {
+    const auth = await deps.messageSigner(deps.address).then((r) => ({ signedData: r.signBlob, publicKey: r.publicKey }));
+    try {
+      entries = await deps.mbi.downloadVcs({ address: deps.address }, auth);
+    } catch (err) {
+      return { ...status, cacheError: `failed to fetch credential from MBI: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    await deps.quarantine.set({ vcId: status.vcId, entries, downloadedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  }
+  const match = entries.find((e) => typeof e.vc === "object" && e.vc !== null && e.vc.id === status.vcId);
+  if (!match) {
+    return {
+      ...status,
+      cacheError: `no matching credential found in MBI's download for vcId ${status.vcId} \u2014 raw response preserved for recovery at ${quarantineFilePath}`
+    };
+  }
+  if (!subjectMatches(match.vc, deps.holderDid)) {
+    return {
+      ...status,
+      cacheError: `downloaded credential subject (${observedSubjectId(match.vc)}) does not match this wallet's holderDid (${deps.holderDid}) \u2014 refusing to cache; raw response preserved for recovery at ${quarantineFilePath}`
+    };
+  }
+  const validUntil = extractValidUntil(match.vc);
+  if (!validUntil) {
+    return {
+      ...status,
+      cacheError: `downloaded credential has no validUntil \u2014 refusing to cache indefinitely; raw response preserved for recovery at ${quarantineFilePath}`
+    };
+  }
+  if (!isVcValid({ validUntil })) {
+    return {
+      ...status,
+      cacheError: `downloaded credential expired at ${validUntil} \u2014 refusing to cache or return; raw response preserved for recovery at ${quarantineFilePath}`
+    };
+  }
+  await deps.cache.set(deps.verifiedTemplateId, {
+    templateId: deps.verifiedTemplateId,
+    vc: match.vc,
+    vcId: status.vcId,
+    issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    validUntil
+  });
+  return { ...status, vc: match.vc };
+}
+
 // src/index.ts
 var packageVersion = package_default.version;
 function buildToolList() {
@@ -23025,13 +23556,13 @@ function buildToolList() {
     },
     {
       name: "subscribe_and_issue",
-      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. What a call actually cost is reported precisely: paidAsset/amountPaid are set ONLY when this call paid, a cache hit reports the earlier charge under originalPayment instead (never as amountPaid, so summing spend cannot double-count), and any failure after the payment has settled on chain reports paymentAttempted: { asset, amount, paymentId }. Two such failures exist and mean different things: MBI 4006 is a definitive facilitator rejection, while 4012 (HTTP 502) means the outcome is INDETERMINATE \u2014 the payment may well have landed. On 4012 the wallet automatically polls MBI's recovery endpoint and reports recovery: { status, txHash?, vcId?, polls }, where status is ISSUED (the credential exists after all \u2014 fetch it by vcId, since recovery returns no VC body), FAILED, or REQUIRED/SETTLED (still unresolved) / UNKNOWN (recovery itself unreachable). NEVER retry a payment after either failure: the funds may already be gone, and a retry charges the full amount again \u2014 look the paymentId up instead. Every response except a cache hit also includes { schema: { required, optional } } \u2014 the template's full declared attribute schema read from chain \u2014 so you see the complete field list, not just what went wrong; a cache hit skips the chain lookup and omits it.",
+      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. What a call actually cost is reported precisely: paidAsset/amountPaid are set ONLY when this call paid, a cache hit reports the earlier charge under originalPayment instead (never as amountPaid, so summing spend cannot double-count), and any failure after the payment has settled on chain reports paymentAttempted: { asset, amount, paymentId }. Two such failures exist and mean different things: MBI 4006 is a definitive facilitator rejection, while 4012 (HTTP 502) means the outcome is INDETERMINATE \u2014 the payment may well have landed. On 4012 the wallet automatically polls MBI's recovery endpoint and reports recovery: { status, txHash?, vcId?, polls }, where status is ISSUED (the credential exists after all \u2014 fetch it by vcId, since recovery returns no VC body), FAILED, or REQUIRED/SETTLED (still unresolved) / UNKNOWN (recovery itself unreachable). NEVER retry a payment after either failure: the funds may already be gone, and a retry charges the full amount again \u2014 look the paymentId up instead. Every response except a cache hit also includes { schema: { required, optional } } \u2014 the template's full declared attribute schema read from chain \u2014 so you see the complete field list, not just what went wrong; a cache hit skips the chain lookup and omits it. For the AI Birthcert specifically: this issues the BASIC one \u2014 self-declared by the agent, agent-paid via x402, owner identity NOT identity-verified. If the user asked for a "verified" AI birthcert (owner identity confirmed via MyDigital ID), use request_ai_birthcert_verification instead \u2014 this tool cannot produce that credential.`,
       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"). 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.`
+            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. This resolves to the BASIC (self-declared, non-verified) template \u2014 for the Verified AI Birthcert, use request_ai_birthcert_verification, not this tool.`
           },
           attributes: {
             type: "object",
@@ -23050,21 +23581,42 @@ function buildToolList() {
         required: ["templateId", "attributes"]
       }
     },
+    {
+      name: "request_ai_birthcert_verification",
+      description: `Start a Verified AI Birthcert issuance session with myid (MyDigital ID owner verification). Returns { sessionId, verificationUrl, expiresAt } \u2014 show verificationUrl to the human owner and ask them to open it and complete MyDigital ID verification (typically finishes in seconds). Once they confirm they are done, call check_ai_birthcert_verification to see whether the credential was issued. IMPORTANT: agentName must be unique \u2014 if this exact name has already been used to request a Verified AI Birthcert, issuance will fail. Before calling, ask the human owner whether they want to supply any of the optional fields \u2014 agentPurpose, evidenceAssuranceLevel, ownerType, ownerVerified \u2014 do not silently omit them; they only need to say no. Calling this again with the SAME agentName while a prior session is still pending returns that same session unchanged \u2014 no new session is started and nothing is paid again. This tool spends real funds: it self-pays an x402 challenge, subject to the wallet's configured MAX_PAYMENT_AMOUNT cap, the same as pay_and_fetch/subscribe_and_issue. It can return { error: "..." } instead of a session if that payment fails (insufficient funds, or the payment cap blocked it) \u2014 nothing is created in that case. If the user did NOT ask for a "verified" credential specifically, they most likely want the self-declared, non-verified Basic AI Birthcert instead \u2014 use subscribe_and_issue for that.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          agentName: {
+            type: "string",
+            description: "A unique, human-readable name for this agent. Must not already be in use for a Verified AI Birthcert, or issuance will fail."
+          },
+          agentPurpose: { type: "string", description: 'Optional \u2014 what this agent does, e.g. "Negotiate and settle supplier invoices".' },
+          evidenceAssuranceLevel: { type: "string", description: 'Optional \u2014 assurance level of the identity evidence, e.g. "high".' },
+          ownerType: { type: "string", description: `Optional \u2014 the owner's type, e.g. "Individual".` },
+          ownerVerified: { type: "string", description: 'Optional \u2014 whether the owner is already verified, as the string "true" or "false".' }
+        },
+        required: ["agentName"]
+      }
+    },
+    {
+      name: "check_ai_birthcert_verification",
+      description: 'Check the status of the most recently requested Verified AI Birthcert session (see request_ai_birthcert_verification). Returns { status: "pending" } while the owner has not yet completed MyDigital ID verification, or { status: "issued", vcId } once myid has minted the credential \u2014 myid returns vcId ONLY when status is "issued", never otherwise. On { status: "issued" }, the wallet also fetches the credential from MBI, verifies it, and caches it locally, returning it as `vc` \u2014 it is then also visible via wallet_status and usable by prove_identity without any further call. If `cacheError` is present instead of `vc`, the credential WAS issued successfully but could not be fetched/verified/cached yet (e.g. a transient MBI error) \u2014 this is NOT the same as issuance failing, so do not retry request_ai_birthcert_verification; call check_ai_birthcert_verification again instead. Returns { status: "no_session" } if request_ai_birthcert_verification has never been called.',
+      inputSchema: { type: "object", properties: {} }
+    },
     {
       name: "create_holder_account",
-      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.",
+      description: "Create a new holder HSM account on Wallet BE (onboarding). 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. The wallet manages its own credentials; you neither need nor can supply any. 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" },
           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"]
+        }
       }
     }
   ];
@@ -23074,17 +23626,30 @@ function asPayRequest(accept) {
   return { ...accept, extra: { gasModel: "client", ...extra } };
 }
 async function main() {
-  const accountStore = createFsAccountStore((0, import_node_path3.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp", "account.json"));
+  const fileEnv = loadConfigFileEnv(process.argv, (p) => (0, import_node_fs.readFileSync)(p, "utf8"));
+  const stateDir = (process.env.ZETRIX_WALLET_STATE_DIR ?? fileEnv.ZETRIX_WALLET_STATE_DIR ?? (0, import_node_path6.join)((0, import_node_os2.homedir)(), ".agentic-wallet-mcp")).replace(/\/+$/, "");
+  const accountStore = createFsAccountStore((0, import_node_path6.join)(stateDir, "account.json"));
+  if (process.argv[2] === "export-credentials") {
+    const { exitCode } = await exportCredentials({
+      getAccount: () => accountStore.get(),
+      isTty: Boolean(process.stdout.isTTY),
+      write: (s) => process.stdout.write(s),
+      writeErr: (s) => process.stderr.write(s)
+    });
+    process.exit(exitCode);
+  }
   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 { env, passwordGenerated } = resolveStartupEnv({
+    processEnv: process.env,
+    storedAccount,
+    fileEnv,
+    generatePassword: generateHsmPassword
+  });
   const config2 = loadConfig(env);
   const hsmPassword = config2.hsmPassword;
   const be = new WalletBeClient(config2.walletBeUrl);
   const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-  const { zetrixAddress, holderDid, created, didMismatch, activated } = await resolveHolder(
+  const { zetrixAddress, holderDid, publicKeyHex, created, didMismatch, activated } = await resolveHolder(
     {
       createAccount: (password) => be.createAccount(password),
       signMessage: (message, address, password) => be.signMessage(message, address, password),
@@ -23096,8 +23661,9 @@ async function main() {
   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).
-`
+      `agentic-wallet-mcp: no ZETRIX_ADDRESS was set \u2014 created a new HSM account and saved it 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).` + (passwordGenerated ? ` An HSM password was generated for this account \u2014 you never need to enter it, but it is the ONLY thing that can authorize signing for this wallet. If this file is lost the account cannot be recovered. Back it up with: npx agentic-wallet-mcp export-credentials
+` : `
+`)
     );
   } else if (storedAccount && config2.zetrixAddress === storedAccount.zetrixAddress) {
     process.stderr.write(
@@ -23124,13 +23690,7 @@ async function main() {
   const sdk = new import_zetrix_sdk_nodejs.default({ host: config2.nodeHost, port: config2.nodePort });
   const contractQuery = (a) => sdk.contract.call(a);
   const resolveSymbol = (asset) => resolveAssetSymbol(asset, contractQuery);
-  const fetchNativeBalance = async (address) => {
-    const res = await sdk.account.getInfo(address);
-    if (res.errorCode !== 0) throw new Error(`getInfo failed with errorCode ${res.errorCode}`);
-    const balance = res.result?.balance;
-    if (typeof balance !== "string") throw new Error("getInfo returned no balance");
-    return balance;
-  };
+  const fetchNativeBalance = async (address) => parseNativeBalance(await sdk.account.getInfo(address));
   const tokenBalanceDeps = {
     address: zetrixAddress,
     fetchNativeBalance,
@@ -23141,15 +23701,42 @@ async function main() {
   const nodeBaseUrl = `https://${config2.nodeHost}${config2.nodePort ? `:${config2.nodePort}` : ""}`;
   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_path3.join)((0, import_node_os.homedir)(), ".agentic-wallet-mcp", "vc-cache", cacheScope));
+  const cacheScope = (0, import_node_crypto5.createHash)("sha256").update(`${config2.network}:${zetrixAddress}`).digest("hex");
+  const vcCache = createFsVcCache((0, import_node_path6.join)(config2.stateDir, "vc-cache", cacheScope));
+  const mbi = new MbiClient(config2.mbiBaseUrl);
+  const messageSigner = (message) => be.signMessage(message, zetrixAddress, hsmPassword);
   const pay = (accept) => {
     assertWithinPaymentCap(accept, config2.maxPaymentAmount);
     return payWithReadinessCheck(
       String(accept.asset ?? ""),
-      () => import_x402_zetrix_client2.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn)
+      () => import_x402_zetrix_client2.PaymentEngine.pay(asPayRequest(accept), walletCfg, node, {}, walletBeSignerFn),
+      activated
     );
   };
+  const verifyAiBirthcert = config2.ssivcBaseUrl ? (() => {
+    const ssivcSessionStore = createFsSsivcSessionStore((0, import_node_path6.join)(config2.stateDir, "ssivc-session.json"));
+    const downloadQuarantine = createFsDownloadQuarantineStore((0, import_node_path6.join)(config2.stateDir, "ssivc-download-quarantine"));
+    const ssivc = new SsivcClient(config2.ssivcBaseUrl);
+    const verifyAiBirthcertDeps = {
+      ssivc,
+      signHexBlob: walletBeSignerFn,
+      messageSigner,
+      mbi,
+      pay,
+      publicKeyHex,
+      address: zetrixAddress,
+      holderDid,
+      now: () => /* @__PURE__ */ new Date(),
+      sessionStore: ssivcSessionStore,
+      verifiedTemplateId: config2.aiBirthcertVerifiedTemplateId,
+      cache: vcCache,
+      quarantine: downloadQuarantine
+    };
+    return {
+      request: (input) => requestAiBirthcertVerification(verifyAiBirthcertDeps, input),
+      check: () => checkAiBirthcertVerification(verifyAiBirthcertDeps)
+    };
+  })() : void 0;
   const payer = async (req) => {
     const init = { method: req.method ?? "GET", headers: req.headers, body: req.body };
     const res = await fetch(req.url, init);
@@ -23180,8 +23767,6 @@ async function main() {
     };
   };
   const subscribeSign = (blob) => be.signBlob(blob, zetrixAddress, hsmPassword);
-  const mbi = new MbiClient(config2.mbiBaseUrl);
-  const messageSigner = (message) => be.signMessage(message, zetrixAddress, hsmPassword);
   const zidResolver = new ZidResolverClient(config2.zidResolverBaseUrl);
   const resolveIssuerKeys = (vc) => resolveIssuerProofKeys(vc, zidResolver);
   const submitAuth = async () => {
@@ -23199,11 +23784,14 @@ async function main() {
     subscribeDeps: { mbi, sign: subscribeSign, pay, resolveSymbol, holderDid, resolveTemplateFields, cache: vcCache },
     queryContract: (input) => queryContract(input, contractQuery),
     queryTokenBalance: queryTokenBalance2,
-    createAccount: (password, label, purpose) => be.createAccount(password, label, purpose),
-    saveAccount: (account) => accountStore.set({ ...account, createdAt: (/* @__PURE__ */ new Date()).toISOString() }),
+    // The session password is bound here, in the wiring, so it never crosses into the tool
+    // layer — create_holder_account has no password parameter for a model to be asked for.
+    createAccount: (label, purpose) => be.createAccount(hsmPassword, label, purpose),
+    saveAccount: (account) => accountStore.set({ ...account, hsmPassword, createdAt: (/* @__PURE__ */ new Date()).toISOString() }),
     checkActivationStatus: (address) => be.checkActivationStatus(address),
     sleep,
-    cache: vcCache
+    cache: vcCache,
+    verifyAiBirthcert
   };
   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.6.1",
+  "version": "0.8.0",
   "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   "keywords": [
     "mcp",