agentic-wallet-mcp 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyEG Services Berhad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -3,7 +3,8 @@
 An agent-facing **MCP server** that gives an AI agent a Zetrix wallet: it **proves identity**
 (x401), **pays** (x402), and **obtains verifiable credentials** (via the MBI issuer) — by
 orchestrating existing SDKs/MCPs. It is a thin composer: all heavy crypto and payment logic
-lives in the imported libraries.
+lives in the imported libraries. No private key ever exists in this process — everything signs
+through Wallet BE's HSM.
 
 - **x401** proof → [`x401-zetrix-client`](https://www.npmjs.com/package/x401-zetrix-client) (npm)
 - **x402** payment → [`x402-zetrix-client`](https://www.npmjs.com/package/x402-zetrix-client) (npm)
@@ -12,8 +13,6 @@ lives in the imported libraries.
 - **holder key custody + signing** → Wallet BE softHSM (`/wallet/hsm/*`)
 - **VC issuance** → MBI RS (`/v1/vc/pay/*`)
 
-See [`docs/INTEGRATION_GUIDE.md`](docs/INTEGRATION_GUIDE.md) for the full config reference, tool
-contracts, a live-verified usage flow, and a troubleshooting table for real-infra errors.
 [`docs/CONTRACT_RECONCILIATION.md`](docs/CONTRACT_RECONCILIATION.md) has the authoritative
 endpoint/contract map, [`docs/DEVELOPMENT_CHECKLIST.md`](docs/DEVELOPMENT_CHECKLIST.md) has status,
 and [`docs/USAGE_FLOW.md`](docs/USAGE_FLOW.md) has a full end-to-end prompt script (onboarding →
@@ -21,13 +20,13 @@ VC issuance → identity proof → pay-per-use).
 
 ## Tools
 
-| Tool | Does | Input |
-|---|---|---|
-| `wallet_status` | Report holder DID/address/network + client-supplied held VCs | `{ heldCredentials? }` |
-| `prove_identity` | Answer an x401 `PROOF-REQUEST` → return the `PROOF-RESPONSE` header to replay | `{ proofRequest, vc, revealAttribute?, issuerKeys? }` |
-| `pay_and_fetch` | Fetch a URL, auto-pay with x402 (self-pay via Wallet BE) on `402` | `{ url, method?, headers?, body? }` |
-| `subscribe_and_issue` | Build the signed payload → pay x402 → MBI issues → return the VC | `{ templateId, attributes, expirationDate? }` |
-| `create_holder_account` | Onboarding: create a new HSM account if `HOLDER_ADDRESS` isn't provisioned yet | `{ password, label?, purpose? }` |
+| 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 }` |
+| `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
@@ -35,8 +34,14 @@ VC issuance → identity proof → pay-per-use).
 
 > `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 `HOLDER_ADDRESS`/`HOLDER_DID`/`HSM_PASSWORD` yourself; the tool never writes your
-> MCP config or restarts the server 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.
+
+> `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
+> is resolved against the presented VC's `credentialSubject` (e.g. a DCQL leaf name `agentName`
+> resolves to the VC's actual nested path `agentIdentityCredential.agentName`). Only pass it
+> explicitly to reveal a narrower or different set of claims than the challenge asked for.
 
 > `prove_identity` no longer takes a `bbsPublicKey` input at all. The OID4VP verifier
 > (`openid4vp-verifier-be`) checks each VC's own issuer-signed proof(s) against the
@@ -45,28 +50,35 @@ VC issuance → identity proof → pay-per-use).
 > resolves them itself: it reads the VC's `issuer` DID and each `proof[].verificationMethod`,
 > resolves the issuer's DID document via the Zetrix ZID resolver, and matches the BBS+
 > (`publicKeyMultibase`) and Ed25519 (`publicKeyHex`) verification methods referenced by the VC's
-> own proofs. See `docs/CONTRACT_RECONCILIATION.md §8` for the full trace through the verifier's
+> own proofs. `issuerKeys` is still accepted as a manual escape hatch if the resolver is ever
+> unreachable. See `docs/CONTRACT_RECONCILIATION.md §8` for the full trace through the verifier's
 > source that led to this.
 
-## Install & build
+## Install
+
+Run it directly via `npx` — no install step needed (see "Configuring in Claude Desktop / Claude
+Code" below for wiring it into an MCP client):
 
 ```bash
-npm install
-npm test          # 85 tests
-npm run build     # tsc + esbuild → dist/server-bundle.cjs (the bin)
+npx agentic-wallet-mcp
 ```
 
-Node ≥ 18 (built-in `fetch`). `x401-zetrix-client` is consumed as a normal npm dependency; the
-`bin` runs the **esbuild bundle** (`dist/server-bundle.cjs`), which inlines it.
+Or install [`agentic-wallet-mcp`](https://www.npmjs.com/package/agentic-wallet-mcp) directly:
+
+```bash
+npm i agentic-wallet-mcp
+```
+
+Node ≥ 18 required (built-in `fetch`).
 
 ## Environment
 
 | Variable | Required | Description |
 |---|---|---|
-| `ZETRIX_NETWORK` | yes | `zetrix:testnet` or `zetrix:mainnet` — also selects the default `WALLET_BE_URL`/`MBI_BASE_URL`/`OID4VP_BASE_URL` below |
-| `HOLDER_ADDRESS` | yes | Holder Zetrix address (the HSM account) |
-| `HOLDER_DID` | yes | Holder DID |
-| `HSM_PASSWORD` | no* | HSM password (may instead be supplied per tool-call) |
+| `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_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 |
 | `MBI_BASE_URL` | no | MBI RS base URL override (`/v1/vc/pay/apply`) — auto-derived from `ZETRIX_NETWORK` when not set |
 | `OID4VP_BASE_URL` | no | OID4VP verifier base URL override — auto-derived from `ZETRIX_NETWORK` by the x401 SDK when not set (BT-2368) |
@@ -76,6 +88,27 @@ Node ≥ 18 (built-in `fetch`). `x401-zetrix-client` is consumed as a normal npm
 
 \* sensitive — never logged.
 
+### 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 — 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).
+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
+   needed. A supplied `HOLDER_DID` is never trusted blindly: it's compared against this derived
+   value, and if they don't match, the derived (correct) one wins — the mismatch is logged to
+   stderr so you know to fix your config. Omit `HOLDER_DID` entirely and the derived value is
+   just used directly.
+
+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
@@ -84,18 +117,20 @@ balance. `MAX_PAYMENT_AMOUNT` is a hard, code-enforced cap that holds regardless
 calling agent decides. Once set, it becomes 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` yourself —
-just pick `zetrix:testnet` or `zetrix:mainnet` for `ZETRIX_NETWORK` and the MCP (and the x401 SDK
-it wires up) uses the built-in default for that network:
+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
+`ZETRIX_NETWORK` and the MCP (and the x401 SDK it wires up) uses the built-in default for that
+network:
 
-| Network | `WALLET_BE_URL` default | `MBI_BASE_URL` default | `OID4VP_BASE_URL` default |
-|---|---|---|---|
-| `zetrix:testnet` | `https://wallet-api.myegdev.com/server` | `https://mbi-vc.myegdev.com` | `https://zid-oid4vp-sandbox.zetrix.com/api` |
-| `zetrix:mainnet` | `https://wallet-api.zetrix.com/server` | `https://mbi-vc.zetrix.com` | `https://zid-oid4vp.zetrix.com/api` |
+| Network | `WALLET_BE_URL` default | `MBI_BASE_URL` default | `OID4VP_BASE_URL` default | `ZID_RESOLVER_BASE_URL` default |
+|---|---|---|---|---|
+| `zetrix:testnet` | `https://wallet-api.myegdev.com/server` | `https://mbi-vc.myegdev.com` | `https://zid-oid4vp-sandbox.zetrix.com/api` | `https://zid-resolver-sandbox.zetrix.com` |
+| `zetrix:mainnet` | `https://wallet-api.zetrix.com/server` | `https://mbi-vc.zetrix.com` | `https://zid-oid4vp.zetrix.com/api` | `https://zid-resolver.zetrix.com` |
 
-Only set `WALLET_BE_URL`/`MBI_BASE_URL`/`OID4VP_BASE_URL` explicitly if you run your own instance
-of that service instead of the default one — an explicit value always wins over the network
-default.
+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.
 
 That's the complete list — no VC-MCP subprocess, no BaaS gateway key, no manually-configured
 BBS+ key to set up (BT-2357 replaced that whole path — see `docs/CONTRACT_RECONCILIATION.md §8`).
@@ -116,24 +151,32 @@ the `<...>` placeholders (don't commit a filled copy; `mcp.local.json` is gitign
 {
   "mcpServers": {
     "agentic-wallet": {
-      "command": "node",
-      "args": ["/absolute/path/to/zetrix-agentic-wallet/dist/server-bundle.cjs"],
+      "command": "npx",
+      "args": ["-y", "agentic-wallet-mcp"],
       "env": {
         "ZETRIX_NETWORK": "zetrix:testnet",
-        "HOLDER_ADDRESS": "ZTX3...",
-        "HOLDER_DID": "did:zid:...",
-        "HSM_PASSWORD": "your-hsm-password"
+        "HSM_PASSWORD": "your-hsm-password",
+        "ZETRIX_ADDRESS": "ZTX3...",
+        "HOLDER_DID": "did:zid:..."
       }
     }
   }
 }
 ```
 
+> 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.
+
+> 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"]`.
+
 > Prefer environment/secret managers over inline secrets for `HSM_PASSWORD` in production.
 >
-> Only add `WALLET_BE_URL` / `MBI_BASE_URL` / `OID4VP_BASE_URL` to the `env` block if you run your
-> own instance of that service — otherwise leave them out and the MCP (and the x401 SDK) use the
-> default for whichever `ZETRIX_NETWORK` you picked (see the table above).
+> Only add `WALLET_BE_URL` / `MBI_BASE_URL` / `OID4VP_BASE_URL` / `ZID_RESOLVER_BASE_URL` to the
+> `env` block if you run your own instance of that service — otherwise leave them out and the MCP
+> (and the x401 SDK) use the default for whichever `ZETRIX_NETWORK` you picked (see the table
+> above).
 
 ## Example prompts
 
@@ -145,21 +188,61 @@ the `<...>` placeholders (don't commit a filled copy; `mcp.local.json` is gitign
 
 For the full ordered script (onboarding → check → issue → prove → pay), see [`docs/USAGE_FLOW.md`](docs/USAGE_FLOW.md).
 
-## Status
-
-Milestone 2 (WBS 4.1–4.5) is code-complete **and live-verified end-to-end against the real
-sandbox** — not just unit-tested. `subscribe_and_issue` issued a real VC and settled a real
-payment; `prove_identity` got a real OID4VP verifier to return `VERIFIED`; `pay_and_fetch`
-completed a real x402 payment against `ms-zetrix` (via `ms-public-proxy`) and got real chain data
-back. This closed out the remaining G-checks from `docs/CONTRACT_RECONCILIATION.md §7`: the
-OID4VP `ResponseWrapper`/wallet-auth submit contract (G6), the MBI `data` hex form (G3), and the
-DCQL→`revealAttribute` mapping (G4, now VC-aware — resolves DCQL claim paths against the
-presented VC's actual nested structure). See
-[`docs/INTEGRATION_GUIDE.md`](docs/INTEGRATION_GUIDE.md) — its "Live verification record" section
-has the exact evidence (VC ids, tx hashes, presentation ids), and its "Network reachability &
-troubleshooting" section covers every real-infra error hit along the way and its fix.
-
-One known item remains open, tracked as a follow-up (not a blocker): `verifiedClaims` came back
-empty on a `VERIFIED` proof (likely a verifier echo behavior, not a wallet bug). Also unconfirmed:
-Wallet BE's `/account/create` `publicKeyHex` format (raw vs Zetrix `b001…`-encoded —
-`deriveHolderDid` handles both, but only one is real).
+## End-to-end usage flow
+
+Full narrative version with example prompts: [`docs/USAGE_FLOW.md`](docs/USAGE_FLOW.md).
+
+**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).
+
+**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
+already there. Skip to Phase 3 if so.
+
+**Phase 2 — `subscribe_and_issue` — VC issuance (✅ live-verified).**
+`{ templateId, attributes }` → holder-signs the payload via Wallet BE → MBI's x402 `402` →
+self-pay → MBI settles **and** issues the VC in one call. **Hold onto the returned `vc`** — it's
+what you pass into every future `prove_identity` call.
+
+**Phase 3 — `prove_identity` — x401 identity proof (✅ live-verified, `VERIFIED`).**
+`{ proofRequest, vc }` (omit `revealAttribute`/`issuerKeys` — both now resolve automatically).
+Internally: fetch the OID4VP presentation definition → derive the BBS+ selective-disclosure VP
+via MBI (`/vp/ext/create` + `/vp/ext/submit`, `includeVp: true`) → resolve the issuer's
+verification keys via the ZID resolver → submit to the verifier with wallet-auth headers →
+package the signed result as a `PROOF-RESPONSE`. Replaying that header back to the original
+resource server happens outside this MCP, in whatever drove the conversation. See "The
+`PROOF-REQUEST` header" section in [`docs/USAGE_FLOW.md`](docs/USAGE_FLOW.md) for the exact wire
+structure and field semantics.
+
+**Phase 4 — `pay_and_fetch` — pay-per-use (✅ live-verified).**
+`{ url, method?, headers?, body? }` → fetch → on `402`, self-pay → retry with `X-PAYMENT`.
+Independent of Phases 2/3 — no VC or identity proof involved, just a fresh payment per call.
+
+## 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.
+
+| 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` |
+| `VP derivation failed <- ZID resolver HTTP 403 ... cf-mitigated: challenge` | ZID resolver (`zid-resolver-sandbox.zetrix.com`) was behind a Cloudflare **managed challenge** that blocked plain server-to-server `fetch` | **Fixed 2026-07-17** — DevOps allowlisted server-to-server access; the resolver now returns `200` directly (verified: `curl https://zid-resolver-sandbox.zetrix.com/1.0/identifiers/<did>` → real DID document, keys byte-identical to a browser-fetched copy). If it ever regresses, `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. |
+| `MBI /vp/ext/submit did not return vp` | MBI's `includeVp` opt-in (BT-2357) not deployed on the target instance | Confirmed deployed on the sandbox (`mbi-vc.myegdev.com`). If you see this against a different MBI instance, that instance needs the same rollout. |
+
+## Security notes
+
+- **No plaintext private key ever exists in this process.** All Ed25519 signing routes through
+  Wallet BE's HSM (`/wallet/hsm/*`); `walletCfg.privateKey` is always `''`.
+- **`MAX_PAYMENT_AMOUNT` is the real control against unbounded auto-spend** — see Environment
+  above. Without it, `pay_and_fetch`/`subscribe_and_issue` will pay whatever a server's `402`
+  challenge demands, up to the HSM account's balance. This was raised in code review (finding
+  AWL-M01) specifically because an agent-side "confirm before paying" step is not a real security
+  boundary: the same prompt injection or bad instruction that drove the call in the first place
+  could just as easily drive the confirmation.
+