create-metamynd-agent 0.7.1 → 0.7.3

package/README.md

@@ -135,23 +135,53 @@ npm start
 ### Separate tool gateway (default)
 
 This is the other half of **without MetaMynd, you can be bypassed**: WITH it — specifically, with
-`gateway/`, the second process this scaffolds by default — you can't be, the same way the hosted
-platform's own MCP counterparty can't be talked around by a compromised agent.
+`gateway/`, the second process this scaffolds by default — calling the tool directly instead of
+through the check no longer works, the same way the hosted platform's own MCP counterparty can't
+be talked around by a compromised agent. See [What this closes, precisely](#what-this-closes-precisely)
+below for exactly what that covers, including the one gap found while building it that isn't
+closed yet.
 
 `guard.guardTool()` in `index.mjs` still runs — it's a fast, local, client-side pre-check that gives
 good UX (fail fast on an obviously-blocked call, no round trip) — but it is **not** what stops a
 bypass. It still calls its handler in the SAME process regardless of where the decision came from,
 so anything able to call that handler directly gets the same result the gate would have given it.
 
-What actually stops a bypass is that `bookFlight()` doesn't exist in the agent's process at all.
+What actually stops that bypass is that `bookFlight()` doesn't exist in the agent's process at all.
 It exists only in `gateway/server.mjs` — a separate process, started separately, holding any real
 tool credentials the agent process never sees — which independently re-verifies every request
-against the agent's own published policy bundle before running it (same shape as the mutual
+against the agent's own published policy bundle before running it, **binds that request to the
+actual body being executed** (`@metamynd/agentsafe-http-gateway` ≥ 0.2.0), and requires the
+agent's `authorizationId` to atomically claim single-use execution against the real stateful gate
+(`requireAuthorization`, `@metamynd/agentsafe-mcp-guard` ≥ 0.2.0) — closing a confused-deputy gap
+and a replay/cumulative-spend gap, both found during independent testing. Same shape as the mutual
 counterparty check in [`@metamynd/agentsafe-mcp-guard`](https://www.npmjs.com/package/@metamynd/agentsafe-mcp-guard),
-built with [`@metamynd/agentsafe-http-gateway`](https://www.npmjs.com/package/@metamynd/agentsafe-http-gateway)).
-It's a minimal slice of the same pattern proven end to end in `demo/duffel-mcp-gateway` in the
-AgentSafe repo (mutual handshake, x402 payment binding, capability tokens) — this scaffold gives you
-just the part that closes the bypass, not the whole protocol.
+built with [`@metamynd/agentsafe-http-gateway`](https://www.npmjs.com/package/@metamynd/agentsafe-http-gateway).
+It's a minimal slice of the fuller pattern proven end to end in `demo/duffel-mcp-gateway` in the
+AgentSafe repo (mutual handshake, x402 payment binding, capability tokens) — this scaffold gives
+you the parts that close direct-call, confused-deputy, replay, and cumulative-spend bypasses, not
+the whole protocol.
+
+#### What this closes, precisely
+
+Named precisely, not left implicit:
+
+- **Direct call.** `bookFlight()` doesn't exist in the agent's process.
+- **Confused deputy (payload).** Signing a cheap request while executing an expensive one (a
+  different amount/currency/merchant in the body than what was signed) is refused before the tool
+  runs — payload binding.
+- **Replay.** A captured, resent request fails to atomically claim single-use execution the second
+  time — `requireAuthorization`.
+- **Cumulative spend.** The claimed authorization only exists because the real stateful gate
+  already checked it against the mandate's TOTAL budget when minted, not just this one request's
+  amount — so many small legal-looking calls can't add up past the cap this way.
+
+**One narrower gap, found while building this and disclosed rather than left implicit:** the claim
+above verifies the claimed authorization's own `agentDid`/`amount`/`currency` match the request —
+not `merchant`, because the backend's hold record doesn't currently store it. A same-amount,
+same-currency authorization legitimately obtained for one merchant could in principle unlock a
+booking with a different merchant. Closing this needs a small backend change (storing `merchant`
+on the hold); it isn't done here. `gateway/README.md`'s own "What this closes, precisely" section
+has the same disclosure.
 
 Pass `--no-gateway` to opt out and get the old single-process scaffold instead — e.g. if you're
 already running your own separate gateway and don't need this one. **You are back to being

package/index.mjs

@@ -26,9 +26,13 @@ const GUARD_PKG = '@metamynd/agentsafe-guard';
 const GUARD_VERSION = '^0.5.0';
 // The default hosted scaffold's SECOND process — the tool gateway (see scaffoldProject).
 const MCP_GUARD_PKG = '@metamynd/agentsafe-mcp-guard';
-const MCP_GUARD_VERSION = '^0.1.0';
+// 0.2.0 adds requireAuthorization (closes replay + cumulative spend) — this scaffold sets that
+// option, so a range that could resolve below 0.2.0 would silently scaffold a no-op.
+const MCP_GUARD_VERSION = '^0.2.0';
 const GATEWAY_PKG = '@metamynd/agentsafe-http-gateway';
-const GATEWAY_VERSION = '^0.1.0';
+// 0.2.0 fixes a confused-deputy gap (payload not bound to the signed request) — the CLI must
+// never scaffold a range that could resolve below it.
+const GATEWAY_VERSION = '^0.2.0';
 const DEFAULT_API = 'https://metamynd.ai/api/v1';
 const DEFAULT_GATEWAY_PORT = 4401; // distinct from --harness's dashboard (4400)
 
@@ -455,7 +459,11 @@ const GATEWAY = process.env.GATEWAY_URL || 'http://localhost:${gatewayPort}';
 // --- Calls the gateway process instead of a local function. There is no raw bookFlight() in
 // --- this file to call directly — the tool, and any real credentials it needs, live only in
 // --- ./gateway, which independently re-verifies this signed request itself.
-async function bookFlightViaGateway(args) {
+// --- \`decision\` is guardTool()'s own verdict, already produced by the REAL remote gate for any
+// --- value-bearing action (sealValueActions, on by default) — its authorizationId is what lets
+// --- the gateway atomically claim single-use execution, closing replay + cumulative spend, not
+// --- just re-checking policy. See ./gateway/README.md.
+async function bookFlightViaGateway(args, decision) {
   const signed = guard.buildSignedRequest({
     action: '${scope}',
     amount: args.amount,
@@ -463,6 +471,7 @@ async function bookFlightViaGateway(args) {
     merchant: args.merchant,
     context: { tool: 'book-flight', riskLevel: args.riskLevel ?? 'low' },
   });
+  signed.authorizationId = decision?.authorizationId;
   const res = await fetch(GATEWAY + '/book-flight', {
     method: 'POST',
     headers: { 'content-type': 'application/json', 'x-magp-request': JSON.stringify(signed) },
@@ -690,14 +699,17 @@ A MetaMynd/AgentSafe-governed agent, scaffolded with \`create-metamynd-agent\`.
 ${gatewaySection}${
     withGateway
       ? `**With MetaMynd's gateway, you can't be bypassed** — that's what this section is about.
-This scaffold's default shape (agent + separate gateway process, port ${gatewayPort} by
-default) is the actual enforcement boundary: \`guard.guardTool()\` in \`index.mjs\` is a
-client-side convenience, not a boundary — it still runs its handler in-process regardless of
-where the decision came from. What actually stops a bypass is that \`bookFlight()\` itself only
-exists in \`./gateway\`, a process this one cannot reach into, which independently re-verifies
-every request against this agent's own policy bundle. Re-scaffold with \`--no-gateway\` for the
-old single-process shape — it is NOT a separate enforcement boundary; see its own generated
-README for why.`
+This scaffold's default shape (agent + separate gateway process, port ${gatewayPort} by default)
+is the actual enforcement boundary: \`guard.guardTool()\` in \`index.mjs\` is a client-side
+convenience, not a boundary — it still runs its handler in-process regardless of where the
+decision came from. What actually stops direct-call and confused-deputy bypasses is that
+\`bookFlight()\` itself only exists in \`./gateway\`, a process this one cannot reach into, which
+independently re-verifies every request against this agent's own policy bundle AND binds it to
+the actual body being executed. Replay and cumulative spend are closed too, via
+\`requireAuthorization\` — see \`./gateway/README.md\`'s "What this closes, precisely" section for
+exactly what that covers, including the one narrower gap disclosed there. Re-scaffold with
+\`--no-gateway\` for the old single-process shape — it is NOT a separate enforcement boundary at
+all; see its own generated README for why.`
       : `**Without MetaMynd, you can be bypassed** — this is that case. This scaffold has no
 separate gateway process (either \`--sandbox\`, which never provisions real credentials, or
 \`--no-gateway\` was passed): \`guard.guardTool()\` wraps a tool in the SAME process as the check
@@ -760,7 +772,11 @@ const routes = [{ method: 'POST', path: '/book-flight', action: '${scope}' }];
 
 // No serviceKey: this minimal gateway only calls verifyRequest() (re-check a signed request),
 // not the mutual-handshake methods, which are the only thing that needs it.
-const guard = createMcpGuard({ serviceDid: 'did:local:${scope}-gateway', issuerApi: MAGP_API });
+//
+// requireAuthorization: true is what closes replay and cumulative spend, not just per-request
+// policy — it requires the agent's authorizationId (from a REAL guard.authorize() call) to
+// atomically claim single-use execution against the issuer before this gateway runs the tool.
+const guard = createMcpGuard({ serviceDid: 'did:local:${scope}-gateway', issuerApi: MAGP_API, requireAuthorization: true });
 
 const gateway = createHttpGateway({
   guard,
@@ -838,7 +854,8 @@ function gatewayReadme(slug, scope, port) {
   return `# ${slug}-gateway
 
 **With MetaMynd, you can't be bypassed.** This process is why. It is the **real enforcement
-boundary** for \`${slug}\`'s tool(s) — not \`../index.mjs\`.
+boundary** for \`${slug}\`'s tool(s) — not \`../index.mjs\`. See
+[What this closes, precisely](#what-this-closes-precisely) below for exactly what that covers.
 
 ## Why this exists
 
@@ -854,7 +871,9 @@ This process closes that gap by being a **separate** one. The agent has no way t
 and call \`bookFlight()\` directly, because \`bookFlight()\` doesn't exist in the agent's process —
 it exists only here, and every request that reaches it has already been independently
 re-verified against this agent's OWN published policy bundle, fetched over the network by THIS
-process, not trusted from the agent's say-so.
+process, not trusted from the agent's say-so — AND bound to the actual body being executed
+(payload binding) AND to a real, single-use, stateful authorization (\`requireAuthorization\`) —
+see below for what each of those means precisely.
 
 ## Run
 
@@ -881,12 +900,36 @@ add another protected route here rather than adding a local function back in \`i
   \`bookFlight()\`.
 - \`.env.example\` — where real tool credentials go (copy to \`.env\`, fill in, never commit).
 
-## Beyond this minimal slice
-
-This gateway only re-verifies a signed request (§9.3/§9.6 of the MAGP spec). It does not do the
-mutual DID handshake, x402 payment binding, or commitment-bound capability tokens that a
-production Service integration would add — see \`@metamynd/agentsafe-mcp-guard\`'s own README for
-those, and \`demo/duffel-mcp-gateway\` in the AgentSafe repo for a full worked example.
+## What this closes, precisely
+
+Four independent checks, each closing a different bypass an agent (or anything able to call its
+own code, or a network attacker) might attempt:
+
+- **Direct call.** \`bookFlight()\` doesn't exist in the agent's process. There's nothing to call.
+- **Confused deputy (payload).** The gateway re-verifies the signed request against this agent's
+  own policy AND binds it to the actual request body (payload binding,
+  \`@metamynd/agentsafe-http-gateway\` ≥ 0.2.0) — signing a cheap request while executing an
+  expensive one is refused before the tool ever runs.
+- **Replay.** \`requireAuthorization: true\` (set in \`server.mjs\`) requires the agent's
+  \`authorizationId\` — from a REAL \`guard.authorize()\` call, which \`index.mjs\` already makes for
+  any value-bearing action by default — to atomically claim single-use execution against the
+  issuer. A captured, replayed request fails the claim the second time.
+- **Cumulative spend.** The same \`authorizationId\` only exists because the real stateful gate
+  already checked it against the mandate's TOTAL budget when it was minted — not just this one
+  request's amount. Many small legal-looking calls can't add up past the mandate cap this way,
+  because each needed its own real authorization first.
+
+**One narrower gap, found while building this and disclosed rather than left implicit:** the
+claim above verifies the claimed authorization's own \`agentDid\`/\`amount\`/\`currency\` match the
+request being executed — but not \`merchant\`, because the backend's hold record doesn't currently
+store it. A same-amount, same-currency authorization legitimately obtained for one merchant could
+in principle be presented to unlock a booking with a different merchant. Closing this needs a
+small backend change (storing \`merchant\` on the hold so it can be compared too); it isn't done
+here. See \`@metamynd/agentsafe-mcp-guard\`'s own README (\`requireAuthorization\`) for the full
+mechanism, and \`demo/duffel-mcp-gateway\` in the AgentSafe repo for the fuller pattern this is a
+slice of (mutual DID handshake, x402 payment binding, commitment-bound capability tokens — which
+WOULD close the merchant gap too, by binding the whole transaction to a cryptographic commitment
+rather than comparing individual stored fields).
 `;
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-metamynd-agent",
-  "version": "0.7.1",
-  "description": "Scaffold a MetaMynd/AgentSafe-governed AI agent in one command — logs in, provisions the agent (identity + mandate + SOP + Standards) in a single call, writes agent.metamynd.json plus a runnable agent + separate tool-gateway process (the real enforcement boundary). --harness scaffolds a free, local, zero-network governance harness instead.",
+  "version": "0.7.3",
+  "description": "Scaffold a MetaMynd/AgentSafe-governed AI agent in one command — logs in, provisions the agent (identity + mandate + SOP + Standards) in a single call, writes agent.metamynd.json plus a runnable agent + separate tool-gateway process that closes direct-call, confused-deputy, replay, and cumulative-spend bypasses. --harness scaffolds a free, local, zero-network governance harness instead.",
   "type": "module",
   "bin": {
     "create-metamynd-agent": "index.mjs"