agentic-wallet-mcp 0.2.0 → 0.3.0

package/README.md

@@ -8,14 +8,12 @@ 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)
-- **VC presentation** (BBS+ VP derivation) → MBI RS (`/v1/vp/ext/create` + `/v1/vp/ext/submit`, `includeVp: true` — BT-2357)
+- **VC presentation** (BBS+ VP derivation) → MBI RS (`/v1/vp/ext/create` + `/v1/vp/ext/submit`, `includeVp: true`)
 - **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/*`)
 
-[`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 →
+[`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
@@ -51,8 +49,7 @@ VC issuance → identity proof → pay-per-use).
 > 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. `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.
+> unreachable.
 
 ## Install
 
@@ -81,10 +78,10 @@ Node ≥ 18 required (built-in `fetch`).
 | `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) |
+| `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>" }`, e.g. `{"ZTX":"1000000000","*":"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, e.g. `{"ZTX":"1000000000","JMYR":"5000000","*":"0"}`. Unset = no cap enforced. |
 
 \* sensitive — never logged.
 
@@ -129,11 +126,12 @@ network:
 
 Only set any of the four explicitly if you run your own instance of that service instead of the
 default one — an explicit value always wins over the network default. The `*.myegdev.com`
-(testnet) hosts are internal — unreachable without VPN; see "Network reachability &
-troubleshooting" below if any of them time out.
+(testnet) hosts are public endpoints — no VPN needed; if you're on a corporate VPN and one of
+them times out, disconnecting it is more likely to fix that than connecting it. See "Network
+reachability & troubleshooting" below.
 
 That's the complete list — no VC-MCP subprocess, no BaaS gateway key, no manually-configured
-BBS+ key to set up (BT-2357 replaced that whole path — see `docs/CONTRACT_RECONCILIATION.md §8`).
+BBS+ key to set up.
 
 ## Configuring in Claude Desktop / Claude Code
 
@@ -202,12 +200,12 @@ either way, restart the server afterward (env vars load once, at process start).
 `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).**
+**Phase 2 — `subscribe_and_issue` — VC issuance.**
 `{ 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`).**
+**Phase 3 — `prove_identity` — x401 identity proof.**
 `{ 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
@@ -217,23 +215,23 @@ resource server happens outside this MCP, in whatever drove the conversation. Se
 `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).**
+**Phase 4 — `pay_and_fetch` — pay-per-use.**
 `{ 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.
+The `*.myegdev.com` testnet endpoints are public — no VPN needed to reach them. One dependency
+sits behind a CDN edge (see the ZID resolver row below). When something that worked before
+suddenly times out or 403s, check this table before assuming a code regression.
 
 | Symptom | Cause | Fix / status |
 |---|---|---|
-| `Wallet BE /wallet/hsm/sign-blob request failed <- fetch failed <- UND_ERR_CONNECT_TIMEOUT` (or same for `mbi-vc.myegdev.com`) | `*.myegdev.com` hosts are internal — unreachable without VPN | Connect/reconnect your VPN, then retry. Verify first: `curl -I https://wallet-api.myegdev.com/server` |
-| `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. |
+| `Wallet BE /wallet/hsm/sign-blob request failed <- fetch failed <- UND_ERR_CONNECT_TIMEOUT` (or same for `mbi-vc.myegdev.com`) | Transient network issue, or (if you're on a corporate VPN) the VPN routing away from the public internet | If you're on a VPN, try disconnecting it and retrying. Verify reachability directly: `curl -I https://wallet-api.myegdev.com/server` |
+| `VP derivation failed <- ZID resolver HTTP 403 ... cf-mitigated: challenge` | ZID resolver (`zid-resolver-sandbox.zetrix.com`) sitting behind a Cloudflare **managed challenge** that blocks plain server-to-server `fetch` | Server-to-server access to the resolver must be allowlisted so it returns `200` directly. If the challenge is active, `prove_identity`'s `issuerKeys` input is the fallback — fetch the DID document via a real browser (it clears the JS challenge) and pass its `verificationMethod` entries' `publicKeyMultibase` (BBS+) / `publicKeyHex` (Ed25519) directly. |
 | `OID4VP backend returned a malformed presentation definition` | Historical SDK bug: the live sandbox's `GET /v1/presentation/{id}` response has no `expires_at` field, but the SDK guard required one | **Fixed** in `x401-zetrix-client` — `expiresAt` is now optional on `PresentationDefinition`. If you see this, you're on a stale cached `npx` install — clear it (`npx clear-npx-cache` or bump the version) to pick up the current published `agentic-wallet-mcp`. |
 | `SUBMIT_FAILED: OID4VP backend returned 401 ... Missing X-Wallet-Public-Key header` | Historical SDK gap: `POST /v1/presentation/submit` requires wallet-auth headers (`X-Wallet-Public-Key` / `X-Wallet-Signed-Data`, holder signs their own address) that the SDK didn't send | **Fixed** — `X401Wallet` now accepts an injected `submitAuth` provider and the wallet wires it automatically; nothing to configure. |
-| `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. |
+| `MBI /vp/ext/submit did not return vp` | MBI's `includeVp` opt-in not deployed on the target instance | 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
 
@@ -241,8 +239,7 @@ observed so far, the code was correct and the network/edge state had changed.
   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.
+  challenge demands, up to the HSM account's balance. 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.
 

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "agentic-wallet-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
   "keywords": ["mcp", "model-context-protocol", "zetrix", "wallet", "x401", "x402", "blockchain"],
   "license": "MIT",
   "author": "MyEG Services Berhad",
-  "homepage": "https://git.myeg.com.my/genesis/zetrix-agentic-wallet",
+  "homepage": "https://github.com/Zetrix-Chain/zetrix-agentic-wallet",
   "repository": {
     "type": "git",
-    "url": "https://git.myeg.com.my/genesis/zetrix-agentic-wallet.git"
+    "url": "https://github.com/Zetrix-Chain/zetrix-agentic-wallet.git"
   },
   "bugs": {
-    "url": "https://git.myeg.com.my/genesis/zetrix-agentic-wallet/-/issues"
+    "url": "https://github.com/Zetrix-Chain/zetrix-agentic-wallet/issues"
   },
   "type": "module",
   "engines": {
@@ -34,7 +34,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "x401-zetrix-client": "^0.2.1",
-    "x402-zetrix-client": "^0.2.2"
+    "x402-zetrix-client": "^0.2.2",
+    "zetrix-sdk-nodejs": "^1.0.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",