agentic-wallet-mcp 0.1.0

package/README.md

@@ -0,0 +1,165 @@
+# Zetrix Agentic Wallet MCP
+
+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.
+
+- **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)
+- **VC presentation** (BBS+ VP derivation) → MBI RS (`/v1/vp/ext/create` + `/v1/vp/ext/submit`, `includeVp: true` — BT-2357)
+- **issuer key resolution** (for the OID4VP submit body) → the Zetrix ZID resolver (`https://zid-resolver[-sandbox].zetrix.com`)
+- **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 →
+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? }` |
+
+> 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.
+
+> `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.
+
+> `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
+> `bbs_public_key`/`ed25519_public_key` it's sent — and its own DID-resolution fallback isn't
+> implemented server-side, so it needs the real issuer keys, not a holder key. The wallet now
+> 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
+> source that led to this.
+
+## Install & build
+
+```bash
+npm install
+npm test          # 85 tests
+npm run build     # tsc + esbuild → dist/server-bundle.cjs (the bin)
+```
+
+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.
+
+## 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) |
+| `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) |
+| `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>" }`, e.g. `{"ZTX":"1000000000","*":"0"}`. Unset = no cap enforced. |
+
+\* sensitive — never logged.
+
+\*\* **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.
+
+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:
+
+| 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` |
+
+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.
+
+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`).
+
+## Configuring in Claude Desktop / Claude Code
+
+> **Deployment model: single-holder, config-based.** One MCP instance serves one holder;
+> all setup (infra URLs, holder identity, `HSM_PASSWORD`, VC-backend key) is set once in the
+> `env` block below. Per-transaction data (the VC to present, attributes to request) is passed
+> by the agent at call time. (Multi-user — passing secrets/identity per tool-call — is a future
+> option, not built.)
+
+A ready-to-edit template lives at [`mcp.json`](mcp.json) — copy it into your client config and fill
+the `<...>` placeholders (don't commit a filled copy; `mcp.local.json` is gitignored). Add to
+`claude_desktop_config.json` (Desktop) or `~/.claude/settings.json` (Code):
+
+```json
+{
+  "mcpServers": {
+    "agentic-wallet": {
+      "command": "node",
+      "args": ["/absolute/path/to/zetrix-agentic-wallet/dist/server-bundle.cjs"],
+      "env": {
+        "ZETRIX_NETWORK": "zetrix:testnet",
+        "HOLDER_ADDRESS": "ZTX3...",
+        "HOLDER_DID": "did:zid:...",
+        "HSM_PASSWORD": "your-hsm-password"
+      }
+    }
+  }
+}
+```
+
+> 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).
+
+## Example prompts
+
+- *"Check my wallet status."* → `wallet_status`
+- *"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)
+
+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).

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "agentic-wallet-mcp",
+  "version": "0.1.0",
+  "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "agentic-wallet-mcp": "dist/server-bundle.cjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && esbuild src/index.ts --bundle --platform=node --target=node18 --format=cjs --external:zetrix-sdk-nodejs --outfile=dist/server-bundle.cjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "x401-zetrix-client": "^0.2.1",
+    "x402-zetrix-client": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "esbuild": "^0.24.0",
+    "typescript": "^5.9.0",
+    "vitest": "^1.6.0"
+  }
+}