create-metamynd-agent 0.6.0 → 0.7.0

package/README.md

@@ -2,8 +2,13 @@
 
 Scaffold a **MetaMynd/AgentSafe-governed** AI agent in one command. It logs you in, provisions the
 agent in a **single call** (identity + mandate + starter SOP + all enforced Standards), writes a
-portable `agent.metamynd.json`, and drops a runnable example that gates a tool through the
-[`@metamynd/agentsafe-guard`](https://www.npmjs.com/package/@metamynd/agentsafe-guard).
+portable `agent.metamynd.json`, and drops a runnable agent that gates a tool through the
+[`@metamynd/agentsafe-guard`](https://www.npmjs.com/package/@metamynd/agentsafe-guard) — **plus, by
+default, a second `gateway/` process** built on
+[`@metamynd/agentsafe-mcp-guard`](https://www.npmjs.com/package/@metamynd/agentsafe-mcp-guard) and
+[`@metamynd/agentsafe-http-gateway`](https://www.npmjs.com/package/@metamynd/agentsafe-http-gateway).
+The agent's own `guardTool()` call is a fast, local, client-side check; the gateway is the real
+enforcement boundary — see [Separate tool gateway](#separate-tool-gateway-default) below.
 
 > **Prerequisite:** an agent is always owned by a **KYB-verified owner** — a person/org with a
 > MetaMynd account. If that's you and you're verified, you're ready. Verify once in the dashboard if
@@ -41,6 +46,18 @@ rewrite**: the exact same `guardTool()` call your harness project already makes
 `bundleUrl`/`api` pointed at a real gate (provision normally, without `--harness`) instead of a rules
 file you authored yourself. Nothing about how you wrote your agent changes.
 
+It is also **not a separate enforcement boundary**, and this matters more than the list above.
+`guardToolLocal()` is a cooperative library your own process embeds — call the raw handler directly
+instead of the guarded one and nothing stops you, because there is no second party in the loop to
+disagree with you. Confirmed by direct testing: a bypass attempt (skip the guard, call the tool
+function underneath it) succeeds every time, structurally, not as a bug. What actually closes this
+is a **counterparty** — a separate process holding the tool, that independently re-verifies the
+agent's signed authority for itself rather than trusting that the agent's own guard ran. `--harness`
+never has one, by design (there's no second party on one machine with no network). **Just dropping
+`--harness` is not enough on its own to get one either** — see
+[Separate tool gateway](#separate-tool-gateway-default) below for what actually provides it, and
+`--no-gateway`'s own caveat for what happens if you opt out of it.
+
 Works with `--config` too — its `rules` become the harness's starter rules file, same as the hosted
 flow. See [Policy config file](#policy-config-file---config) below.
 
@@ -62,6 +79,10 @@ call the hosted API (a shared demo identity) — it's a first look at the *hoste
 local/offline mode. Great for a first look; use the full flow below when you want your own governed
 agent with your own limits.
 
+`--sandbox` always scaffolds the single-process shape (no `gateway/`) — it's a shared identity never
+meant to hold real credentials, so there's nothing here worth a separate enforcement boundary for.
+The generated project's own README says so. The full flow below is what scaffolds one by default.
+
 ## Use
 
 ```bash
@@ -70,18 +91,32 @@ npm create metamynd-agent@latest
 npx create-metamynd-agent
 ```
 
-Answer a few prompts (API, owner email/password, agent name, scope, per-transaction cap) and you get:
+Answer a few prompts (API, owner email/password, agent name, scope, per-transaction cap) and you get
+**two** scaffolded projects — the agent, and its tool gateway:
 
 ```
 my-agent/
 ├─ agent.metamynd.json   # portable guard config — HOLDS THE AGENT SECRET KEY (gitignored)
-├─ index.mjs             # runnable example: ALLOW · BLOCK (over cap) · ESCALATE (high risk)
+├─ index.mjs             # runnable example: signs + calls ./gateway; guardTool() here is a
+│                         # fast local pre-check, NOT the enforcement boundary
 ├─ package.json          # depends on @metamynd/agentsafe-guard
 ├─ .gitignore
-└─ README.md
+├─ README.md
+└─ gateway/               # a SEPARATE process — the real enforcement boundary. Read its
+    ├─ server.mjs         # README first if you only read one.
+    ├─ package.json       # depends on @metamynd/agentsafe-mcp-guard + @metamynd/agentsafe-http-gateway
+    ├─ .env.example       # real tool credentials go here, never in the agent directory
+    ├─ .gitignore
+    └─ README.md
 ```
 
-Then:
+Then, in **two terminals** — the gateway first:
+
+```bash
+cd my-agent/gateway
+npm install
+npm start
+```
 
 ```bash
 cd my-agent
@@ -89,6 +124,27 @@ npm install
 npm start
 ```
 
+### Separate tool gateway (default)
+
+`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.
+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
+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.
+
+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. The generated project's own
+README says plainly that this is *not* a separate enforcement boundary if you do.
+
 ## Non-interactive
 
 Every prompt has a flag or environment-variable fallback, so it scripts cleanly in CI:
@@ -111,6 +167,8 @@ METAMYND_PASSWORD='…' npx create-metamynd-agent --yes …
 | `--harness` | — | off (no login/KYB/network at all; free local governance — see above) |
 | `--sandbox` | — | off (skips login/KYB; shared sandbox agent, still hosted) |
 | `--config <file>` | — | a JSON policy file — see [Policy config file](#policy-config-file---config) |
+| `--no-gateway` | — | off — hosted flow only; skips the default separate tool gateway (see above) |
+| `--gateway-port <n>` | — | `4401` — hosted flow only, the gateway process's port |
 | `--port <n>` | — | `4400` — `--harness` only, the local dashboard's port |
 | `--api <url>` | `METAMYND_API` | `https://metamynd.ai/api/v1` |
 | `--email <email>` | `METAMYND_EMAIL` | — (required) |
@@ -188,14 +246,19 @@ npx create-metamynd-agent --claim --watch
 ```
 
 `--request` submits the request (as your own authed user) and stores the claim token locally; `--claim`
-polls until the owner approves, then scaffolds the project. With `--byok` the keypair is generated
-locally and control is proven on claim — MetaMynd never sees the private key.
+polls until the owner approves, then scaffolds the project (the same default two-process shape as
+the full flow above — `--no-gateway`/`--gateway-port` work here too). With `--byok` the keypair is
+generated locally and control is proven on claim — MetaMynd never sees the private key.
 
 ## Security
 
 `agent.metamynd.json` contains the agent's **secret key** (a managed key, or — with `--byok` — the one
 generated locally). The scaffolded project gitignores it. Never commit it or paste it anywhere public.
 
+Any REAL tool credential (an airline API key, a payment key, ...) belongs in `gateway/.env` — never
+in the agent directory. That's the whole point of the default two-process shape: the agent process
+should never be able to hold, or leak, a credential it doesn't have.
+
 ## Full guide
 
 `docs/integration/INTEGRATE-WITH-METAMYND.md` — the complete integration front-door (payments,

package/index.mjs

@@ -3,8 +3,10 @@
 //
 // Logs a KYB-verified owner in, provisions the agent in ONE call
 // (POST /onboarding/agent → identity + mandate + starter SOP + enforced Standards),
-// writes the portable `agent.metamynd.json`, and drops a runnable example that gates a
-// tool through the guard (allow / block / escalate).
+// writes the portable `agent.metamynd.json` and a runnable agent example, PLUS (by default)
+// a separate `gateway/` process — a second, independent guard that re-verifies every request
+// and holds the real tool, so the agent's own guardTool() call is a convenience, not the
+// enforcement boundary. `--no-gateway` skips it (see README#separate-tool-gateway-default).
 //
 // ZERO dependencies: Node ≥ 18 built-ins only (fetch, readline).
 //
@@ -22,7 +24,13 @@ const GUARD_PKG = '@metamynd/agentsafe-guard';
 // >=0.4.0 <0.5.0, so leaving this at ^0.4.0 would scaffold an agent whose `npm test` runs
 // `agentsafe-guard verify` against a guard that has no such command.
 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';
+const GATEWAY_PKG = '@metamynd/agentsafe-http-gateway';
+const GATEWAY_VERSION = '^0.1.0';
 const DEFAULT_API = 'https://metamynd.ai/api/v1';
+const DEFAULT_GATEWAY_PORT = 4401; // distinct from --harness's dashboard (4400)
 
 // ---------- tiny ANSI ----------
 const c = {
@@ -88,6 +96,10 @@ ${c.b('Options')}
                        (MetaMynd never sees the private key). Overridden by --public-key.
   --public-key <hex>   BYOK with a key you already hold (SPKI/raw hex); you prove control yourself
   --out <dir>          Output project directory (default ./<agent-slug>)
+  --no-gateway         Hosted flow only: skip the separate tool-gateway process (see
+                       README#separate-tool-gateway-default) and scaffold the old
+                       single-process example instead. Not a separate enforcement boundary.
+  --gateway-port <n>   Hosted flow only: the gateway process's port (default 4401)
   --port <n>           --harness only: the local dashboard's port (default 4400)
   --yes, -y            Non-interactive: use flags/env/defaults, never prompt
   -h, --help           Show this help
@@ -99,7 +111,9 @@ ${c.b('Environment')}
 ${c.b('What it does')}
   1. Logs in as a KYB-verified owner       → owner access token
   2. POST /onboarding/agent (one call)      → identity + mandate + SOP + Standards
-  3. Writes agent.metamynd.json + a runnable example that gates a tool through the guard.
+  3. Writes agent.metamynd.json + index.mjs, PLUS (by default) a separate gateway/ process —
+     the real enforcement boundary, not index.mjs's own guard.guardTool() call. --no-gateway
+     skips it.
 `;
 
 // ---------- prompts ----------
@@ -257,7 +271,17 @@ async function apiPost(base, path, body, token) {
 }
 
 // ---------- scaffolding ----------
-function exampleIndex(scope, perTxnMax) {
+/**
+ * The --no-gateway / --sandbox variant: the tool is a local function in the SAME process as
+ * guard.guardTool(). Fine for a demo with nothing real behind it (--sandbox always uses this —
+ * it's a shared identity, never meant to hold real credentials). For anything that touches a
+ * real credential, guard.guardTool() alone is a client-side convenience, not a boundary: it
+ * still calls this handler in-process regardless of where the decision came from, so an agent
+ * that skips it and calls bookFlight() directly gets the same result the gate would have given
+ * it — the same shape of gap --harness's README documents. See exampleIndex() below, which is
+ * what the real (non-sandbox) flow scaffolds by default instead.
+ */
+function exampleIndexNoGateway(scope, perTxnMax) {
   const under = Math.max(1, Math.round(perTxnMax * 0.5));
   const over = Math.round(perTxnMax + 100);
   return `// index.mjs — your agent, governed by MetaMynd/AgentSafe.
@@ -268,6 +292,11 @@ import { createGuardFromConfig } from '${GUARD_PKG}';
 const guard = await createGuardFromConfig('./agent.metamynd.json'); // no env vars
 
 // --- Your real tool. Replace the body with your actual implementation. ---
+// --- If that implementation touches a real credential, this in-process call is NOT an
+// --- enforcement boundary: guard.guardTool() below still calls this function directly in
+// --- THIS process regardless of the decision's source, so anything that can call it directly
+// --- gets the same result the gate would have given it. A real (non --sandbox) scaffold
+// --- without --no-gateway moves this behind a separate process instead. See README.
 async function bookFlight(args) {
   return { pnr: 'PNR-DEMO', ...args };
 }
@@ -397,6 +426,186 @@ console.log('');
 `;
 }
 
+/**
+ * The DEFAULT hosted scaffold: the tool lives in a separate process (./gateway), not here.
+ * guard.guardTool() below is still called — it is a fast, local, client-side pre-check that
+ * gives good UX (fail fast, no round trip for an obviously-blocked call) — but it is not what
+ * stops a bypass. What stops a bypass is that there is no bookFlight() in THIS process to call
+ * directly: it only exists in ./gateway, which independently re-verifies every request against
+ * this agent's own policy bundle before it runs, and holds any real credentials the tool needs.
+ */
+function exampleIndex(scope, perTxnMax, gatewayPort) {
+  const under = Math.max(1, Math.round(perTxnMax * 0.5));
+  const over = Math.round(perTxnMax + 100);
+  return `// index.mjs — your agent, governed by MetaMynd/AgentSafe.
+// Every governed tool call is checked TWICE before it runs: once here (fast, local, client-side),
+// and independently again by ./gateway — a SEPARATE process that holds the real tool and its
+// credentials. That second check is the actual enforcement boundary; see ./gateway/README.md.
+import { createGuardFromConfig } from '${GUARD_PKG}';
+
+// Loads agent.metamynd.json: the agent's DID, its signing key, and the gate to call.
+const guard = await createGuardFromConfig('./agent.metamynd.json'); // no env vars
+
+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) {
+  const signed = guard.buildSignedRequest({
+    action: '${scope}',
+    amount: args.amount,
+    currency: 'USD',
+    merchant: args.merchant,
+    context: { tool: 'book-flight', riskLevel: args.riskLevel ?? 'low' },
+  });
+  const res = await fetch(GATEWAY + '/book-flight', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-magp-request': JSON.stringify(signed) },
+    body: JSON.stringify(args),
+  });
+  const body = await res.json().catch(() => null);
+  if (!res.ok) {
+    const err = new Error('gateway ' + res.status + ': ' + (body?.reasonCode ?? 'refused'));
+    err.name = 'GovernanceBlocked';
+    err.governance = { decision: body?.decision ?? 'block', reasonCode: body?.reasonCode ?? 'GATEWAY_ERROR' };
+    throw err;
+  }
+  return body;
+}
+
+// --- The GATED version. Register THIS with your agent instead of calling the gateway directly.
+// --- This local check and the gateway's own re-check are independent; neither trusts the other.
+const gatedBookFlight = guard.guardTool(
+  '${scope}',                                   // = your mandate scope
+  bookFlightViaGateway,
+  (a) => ({                                     // map tool args → gate inputs
+    amount: a.amount,
+    currency: 'USD',
+    merchant: a.merchant,
+    context: { tool: 'book-flight', riskLevel: a.riskLevel ?? 'low' },
+  }),
+);
+
+// --- A tool the agent was NEVER granted. Wrapping it is the demonstration: there is no
+// --- rule anywhere forbidding this. The mandate simply never mentioned the action.
+async function raiseOwnLimit(args) {
+  return { updated: true, ...args };          // never runs, and that is the point
+}
+
+const gatedRaiseOwnLimit = guard.guardTool(
+  'permissions.update',                       // an action NOT in the mandate
+  raiseOwnLimit,
+  (a) => ({
+    amount: a.amount,
+    currency: 'USD',
+    merchant: a.merchant,
+    context: { tool: 'permissions-update' },
+  }),
+);
+
+const dim = (t) => '\\x1b[2m' + t + '\\x1b[0m';
+const bold = (t) => '\\x1b[1m' + t + '\\x1b[0m';
+const rule = (n) => '  ' + '-'.repeat(n);
+
+// Plain-English meaning for the reason codes this demo can produce. The gateway re-evaluates
+// the SAME policy bundle with the SAME evaluator the gate uses, so it produces these same codes.
+const WHY = {
+  AUTHORIZED: 'inside the mandate and under the SOP spend cap',
+  SOP_SPEND_CAP: 'your SOP caps a single transaction at $${perTxnMax}',
+  RISK_REVIEW: 'your SOP sends high-risk actions to a human first',
+  MERCHANT_NOT_ALLOWED: 'the mandate lists which merchants this agent may pay',
+  // Both say the same thing from where you are standing: the mandate does not cover that
+  // action. Which one you see depends on whether the verdict was reached here or at the
+  // gate, and neither of them depends on the amount.
+  NO_PERMISSION_FOR_ACTION: 'the mandate never granted this action - at any amount',
+  NO_MANDATE: 'there is no mandate for this action at all',
+};
+
+// ---------------------------------------------------------------- 1. CONTEXT
+console.log('');
+console.log(bold('  What this simulation shows'));
+console.log('');
+console.log('  An agent should not be the thing that decides what it is allowed to do — and');
+console.log('  it should not be the thing that RUNS what it decided, either. This run makes');
+console.log('  both concrete. Three attempts take the SAME code path and produce three');
+console.log('  different outcomes. The fourth asks for something the agent was never granted');
+console.log('  at all - and that is the one a prompt could not have stopped, because the');
+console.log('  decision is not made inside your program, and the tool is not either.');
+
+// ---------------------------------------------------------------- 2. MECHANISM
+console.log('');
+console.log(bold('  How it does that'));
+console.log('');
+console.log(dim('   1. this project holds an agent identity (a DID) and its signing key'));
+console.log(dim('   2. that agent has a mandate - a scope it may act in, and a spend cap'));
+console.log(dim('   3. guardTool() wraps your tool call, giving a fast local pre-check'));
+console.log(dim('   4. each attempt is ALSO signed and sent to ./gateway - a separate process'));
+console.log(dim('   5. the gateway independently re-verifies before your tool runs there'));
+console.log(dim('   6. there is no local bookFlight() to call directly - only the gateway has it'));
+console.log('');
+console.log(dim('  scope    ${scope}'));
+console.log(dim('  cap      $${perTxnMax} per transaction, set by your SOP'));
+console.log(dim('  gateway  ' + GATEWAY + '  (run it in a separate terminal - see ./gateway)'));
+
+// ---------------------------------------------------------------- 3. THE STEPS
+async function attempt(n, intent, args, tool = gatedBookFlight) {
+  console.log('');
+  console.log(bold('  Step ' + n + ' of 4') + ' - ' + intent);
+  console.log(dim('     signing the request locally, then asking the gate to decide...'));
+  try {
+    const r = await tool(args);
+    console.log('\\x1b[32m     ALLOWED\\x1b[0m  your tool ran (in ./gateway) and returned ' + (r.pnr ?? 'ok'));
+    console.log(dim('     ' + WHY.AUTHORIZED));
+  } catch (e) {
+    const g = e.governance ?? {};
+    const why = WHY[g.reasonCode] ?? e.message;
+    if (g.decision === 'escalate') {
+      console.log('\\x1b[33m     ESCALATED\\x1b[0m  held for a human - ' + g.reasonCode);
+      console.log(dim('     ' + why));
+      console.log(dim('     not a failure: approve it in the dashboard and the action resumes.'));
+    } else {
+      console.log('\\x1b[31m     BLOCKED\\x1b[0m  ' + (g.reasonCode ?? 'refused'));
+      console.log(dim('     ' + why));
+      console.log(dim('     your tool never ran - refused before execution.'));
+    }
+  }
+}
+
+console.log('');
+console.log(rule(66));
+await attempt(1, 'a $${under} booking, low risk. Expected to pass.', { amount: ${under}, merchant: 'skyward-air', riskLevel: 'low' });
+await attempt(2, 'a $${over} booking, deliberately over the cap.', { amount: ${over}, merchant: 'skyward-air', riskLevel: 'low' });
+await attempt(3, 'a $${under} booking, but flagged high risk.', { amount: ${under}, merchant: 'skyward-air', riskLevel: 'high' });
+await attempt(
+  4,
+  'the agent stops booking flights and asks to raise its OWN limit.',
+  { amount: 100000, merchant: 'skyward-air' },
+  gatedRaiseOwnLimit,
+);
+console.log('');
+console.log(rule(66));
+
+// ---------------------------------------------------------------- 4. RESULT
+console.log('');
+console.log(bold('  What this proved'));
+console.log('');
+console.log(dim('   - one code path, three outcomes. The rules decided, not this file'));
+console.log(dim('     and not the model driving it.'));
+console.log(dim('   - step 1 ran in ./gateway, a process this file cannot reach into. There'));
+console.log(dim('     is no rawBookFlight() here to call instead - that is what actually'));
+console.log(dim('     stops a bypass, not the guardTool() call above it.'));
+console.log(dim('   - step 4 needed no rule to stop it. The agent could not widen its own'));
+console.log(dim('     authority, because it cannot name an action nobody delegated to it.'));
+console.log(dim('   - every blocked/escalated call never reached a real tool at all.'));
+console.log(dim('   - if the gate were unreachable the guard fails CLOSED: it blocks.'));
+console.log('');
+console.log('  Change the cap in the dashboard (Legal Entity -> SOPs) and run again.');
+console.log(dim('  The outcome changes. This file does not. That is the point.'));
+console.log('');
+`;
+}
+
 function examplePackageJson(slug) {
   return JSON.stringify(
     {
@@ -415,12 +624,41 @@ function examplePackageJson(slug) {
   ) + '\n';
 }
 
-function exampleReadme(slug, scope) {
-  return `# ${slug}
+function exampleReadme(slug, scope, withGateway, gatewayPort) {
+  const gatewaySection = withGateway
+    ? `## Run
 
-A MetaMynd/AgentSafe-governed agent, scaffolded with \`create-metamynd-agent\`.
+Two processes — start the gateway first, in its own terminal:
 
-## Run
+\`\`\`bash
+cd gateway && npm install && npm start   # the REAL enforcement boundary — see gateway/README.md
+\`\`\`
+
+Then, in this directory:
+
+\`\`\`bash
+npm install
+npm start
+\`\`\`
+
+You should see an ALLOW (fulfilled by \`./gateway\`), a BLOCK (over the per-transaction cap), and
+an ESCALATE (high risk). The BLOCK and ESCALATE never reach the gateway at all — this file's own
+\`guard.guardTool()\` refuses them first. Only the ALLOW crosses into the other process.
+
+## Files
+
+- \`agent.metamynd.json\` — your portable guard config (identity, mandate scope \`${scope}\`, issuer keys).
+  **Contains the agent's secret key — never commit it.** It is already in \`.gitignore\`.
+- \`index.mjs\` — signs each request and calls \`./gateway\` for it; \`guard.guardTool()\` here is a
+  fast local pre-check, not the enforcement boundary.
+- \`gateway/\` — a **separate process**. It holds the real tool and independently re-verifies every
+  request against this agent's own policy before running it. See \`gateway/README.md\` — read that
+  one first if you're only going to read one.
+
+## What this is not
+
+`
+    : `## Run
 
 \`\`\`bash
 npm install
@@ -435,6 +673,34 @@ You should see an ALLOW, a BLOCK (over the per-transaction cap), and an ESCALATE
   **Contains the agent's secret key — never commit it.** It is already in \`.gitignore\`.
 - \`index.mjs\` — wraps a tool with \`guard.guardTool(...)\`; the tool only runs when the gate allows.
 
+## What this is not
+
+`;
+  return `# ${slug}
+
+A MetaMynd/AgentSafe-governed agent, scaffolded with \`create-metamynd-agent\`.
+
+${gatewaySection}${
+    withGateway
+      ? `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 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 itself. That is a client-side convenience, not a boundary — it
+still runs your tool's handler in-process regardless of where the decision came from, so
+anything able to call \`bookFlight()\` directly gets the same result the gate would have given
+it. If this tool ever holds a real credential, provision for real (drop \`--sandbox\`) without
+\`--no-gateway\` for the default shape, which puts the tool behind a separate process instead.
+This is the same structural gap \`--harness\`'s README documents, for the same reason: a
+cooperative in-process check has no counterparty to disagree with a caller that skips it.`
+  }
+
 ## Change the rules
 
 Edit the agent's SOPs in the dashboard (Legal Entity → SOPs). The agent's behaviour changes live —
@@ -448,6 +714,172 @@ function gitignore() {
   return `node_modules/\nagent.metamynd.json\n.env\n`;
 }
 
+// ---------- the default hosted scaffold's second process: a separate tool gateway ----------
+//
+// Not a new protocol — @metamynd/agentsafe-mcp-guard (trustless verifyRequest, already public)
+// and @metamynd/agentsafe-http-gateway (the generic reverse-proxy built on it, already public)
+// do the real work. This just wires up the smallest useful shape: one protected route, one
+// tool, re-verified independently of the agent that's calling it. See demo/duffel-mcp-gateway
+// in the AgentSafe repo for the full pattern (mutual handshake, x402 payment, capability
+// binding) this is a minimal slice of.
+
+function gatewayServerFile(scope, port, apiBase) {
+  return `#!/usr/bin/env node
+// gateway/server.mjs — the REAL enforcement boundary for this agent's tool(s).
+//
+// This is a SEPARATE process from the agent. It holds the tool's real credentials (the agent
+// process never does), and it independently re-verifies every request against this agent's OWN
+// published policy bundle — it does not trust the agent's own guard.guardTool() check. A
+// compromised or dishonest agent calling its own local function gets nothing here, because
+// there is no local function: the tool only runs in this process.
+import http from 'node:http';
+import { createMcpGuard } from '${MCP_GUARD_PKG}';
+import { createHttpGateway } from '${GATEWAY_PKG}';
+
+const PORT = Number(process.env.PORT || ${port});
+const MAGP_API = process.env.MAGP_API || '${apiBase}';
+
+// --- Your real tool. Real credentials (an airline API key, a payment key, ...) belong ONLY
+// --- here, read from process.env (see .env.example) — never in the agent process.
+async function bookFlight(args) {
+  return { pnr: 'PNR-DEMO', ...args };
+}
+
+// One protected route: only a request signed by this agent, for exactly this action, and
+// re-verified against this agent's own mandate/SOP, reaches bookFlight() below.
+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 });
+
+const gateway = createHttpGateway({
+  guard,
+  routes,
+  forward: async (req) => {
+    let args = {};
+    try { args = JSON.parse(req.rawBody?.toString('utf8') || '{}'); } catch { /* empty body */ }
+    const result = await bookFlight(args);
+    return { status: 200, body: result };
+  },
+  // This gateway IS the tool, not a proxy in front of one — an unmatched path has nothing to
+  // pass through TO. Without this, any path a route doesn't match falls through ungoverned
+  // straight to forward() above, which would run bookFlight() with no check at all.
+  denyByDefault: true,
+});
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+const server = http.createServer(async (req, res) => {
+  try {
+    const rawBody = await readBody(req);
+    const result = await gateway({ method: req.method, path: req.url, headers: req.headers, rawBody });
+    const headers = { 'content-type': 'application/json' };
+    if (result.governance) headers['x-agentsafe-decision'] = result.governance.decision;
+    res.writeHead(result.status, headers);
+    res.end(JSON.stringify(result.body ?? {}));
+  } catch (err) {
+    // Fail CLOSED on any gateway error.
+    res.writeHead(502, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ decision: 'block', reasonCode: 'GATEWAY_ERROR', error: String(err?.message ?? err) }));
+  }
+});
+
+server.listen(PORT, () => {
+  console.log('[gateway] listening on :' + PORT + ' -> the only place bookFlight() runs.');
+  console.log('[gateway] every request is independently re-verified against this agent\\'s own policy.');
+});
+`;
+}
+
+function gatewayPackageJson(slug) {
+  return JSON.stringify(
+    {
+      name: slug + '-gateway',
+      version: '0.1.0',
+      private: true,
+      type: 'module',
+      scripts: { start: 'node server.mjs' },
+      dependencies: { [MCP_GUARD_PKG]: MCP_GUARD_VERSION, [GATEWAY_PKG]: GATEWAY_VERSION },
+    },
+    null,
+    2,
+  ) + '\n';
+}
+
+function gatewayEnvExample() {
+  return `# Real tool credentials belong HERE, read from process.env in server.mjs — never in the
+# agent process one directory up.
+# AIRLINE_API_KEY=
+`;
+}
+
+function gatewayGitignore() {
+  return `node_modules/\n.env\n`;
+}
+
+function gatewayReadme(slug, scope, port) {
+  return `# ${slug}-gateway
+
+This is the **real enforcement boundary** for \`${slug}\`'s tool(s) — not \`../index.mjs\`.
+
+## Why this exists
+
+\`guard.guardTool()\` in the agent's \`index.mjs\` is a client-side convenience: it gives fast,
+local ALLOW/BLOCK/ESCALATE feedback, but it still runs its handler in the SAME process
+regardless of where that decision came from. Anything able to call the agent's tool function
+directly — a bug, a compromised dependency, a dishonest fork of the agent's own code — gets the
+same result the gate would have given it. That is not a defect in \`guardTool()\`; a cooperative
+in-process check has no counterparty to disagree with a caller that skips it. See \`--harness\`'s
+own README for the same structural point in the free local-demo mode.
+
+This process closes that gap by being a **separate** one. The agent has no way to reach into it
+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.
+
+## Run
+
+\`\`\`bash
+npm install
+npm start
+\`\`\`
+
+Listens on \`:${port}\` by default (\`PORT\` env var to change it — keep \`../index.mjs\`'s
+\`GATEWAY_URL\` in sync if you do).
+
+## Add real credentials
+
+Edit \`server.mjs\`'s \`bookFlight()\` with your real implementation, reading any credentials it
+needs from \`process.env\` (see \`.env.example\`). Load \`.env\` however you prefer (e.g.
+\`node --env-file=.env server.mjs\`, Node ≥ 20.6) — it is already in \`.gitignore\`. The agent
+directory one level up must never hold these credentials; if it needs to call a DIFFERENT tool,
+add another protected route here rather than adding a local function back in \`index.mjs\`.
+
+## Files
+
+- \`server.mjs\` — the gateway: one protected route (\`POST /book-flight\`, action \`${scope}\`),
+  \`@metamynd/agentsafe-mcp-guard\`'s \`verifyRequest()\` re-checking every request, and the real
+  \`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.
+`;
+}
+
 function writeFileSafe(dir, name, content, force = false) {
   const p = join(dir, name);
   const exists = existsSync(p);
@@ -480,16 +912,32 @@ function assertScaffoldTarget(outDir, force) {
   );
 }
 
-/** Write the scaffolded project + print next steps. Shared by the provision and sandbox paths. */
-function scaffoldProject({ outDir, config, slug, scope, perTxnMax, sandbox, force = false }) {
+/**
+ * Write the scaffolded project + print next steps. Shared by the provision and sandbox paths.
+ * `withGateway`: scaffold the default two-process shape (agent + ./gateway) — the real
+ * enforcement boundary. Off for --sandbox (shared demo identity, never real credentials
+ * anyway) and --no-gateway (opt out, e.g. you're already running your own separate gateway).
+ */
+function scaffoldProject({ outDir, config, slug, scope, perTxnMax, sandbox, withGateway, gatewayPort = DEFAULT_GATEWAY_PORT, force = false }) {
   assertScaffoldTarget(outDir, force);
   console.log(`\n  ${c.b('Scaffolding')} ${c.dim(outDir)}`);
   if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
   writeFileSafe(outDir, 'agent.metamynd.json', JSON.stringify(config, null, 2) + '\n', force);
-  writeFileSafe(outDir, 'index.mjs', exampleIndex(scope, perTxnMax), force);
+  writeFileSafe(outDir, 'index.mjs', withGateway ? exampleIndex(scope, perTxnMax, gatewayPort) : exampleIndexNoGateway(scope, perTxnMax), force);
   writeFileSafe(outDir, 'package.json', examplePackageJson(slug), force);
   writeFileSafe(outDir, '.gitignore', gitignore(), force);
-  writeFileSafe(outDir, 'README.md', exampleReadme(slug, scope), force);
+  writeFileSafe(outDir, 'README.md', exampleReadme(slug, scope, withGateway, gatewayPort), force);
+
+  if (withGateway) {
+    const apiBase = config.apiBase ?? config.api ?? DEFAULT_API;
+    const gwDir = join(outDir, 'gateway');
+    if (!existsSync(gwDir)) mkdirSync(gwDir, { recursive: true });
+    writeFileSafe(gwDir, 'server.mjs', gatewayServerFile(scope, gatewayPort, apiBase), force);
+    writeFileSafe(gwDir, 'package.json', gatewayPackageJson(slug), force);
+    writeFileSafe(gwDir, '.env.example', gatewayEnvExample(), force);
+    writeFileSafe(gwDir, '.gitignore', gatewayGitignore(), force);
+    writeFileSafe(gwDir, 'README.md', gatewayReadme(slug, scope, gatewayPort), force);
+  }
 
   const rel = outDir.replace(resolve('.'), '.').replace(/\\/g, '/');
   console.log(`\n${c.green(c.b('  ✓ Done.'))} Your governed agent is ready.\n`);
@@ -498,7 +946,13 @@ function scaffoldProject({ outDir, config, slug, scope, perTxnMax, sandbox, forc
   } else if (config.agentKey) {
     console.log(`  ${c.yellow('⚠ agent.metamynd.json holds the agent secret key')} — it is gitignored; never commit it.\n`);
   }
+  if (withGateway) {
+    console.log(`  ${c.yellow('⚠ two processes now')} — \`gateway/\` is the real enforcement boundary, not \`index.mjs\`. Read \`gateway/README.md\`.\n`);
+  }
   console.log(`  Next:`);
+  if (withGateway) {
+    console.log(c.cyan(`    cd ${rel}/gateway && npm install && npm start`) + c.dim('   (separate terminal — start this first)'));
+  }
   console.log(c.cyan(`    cd ${rel}`));
   console.log(c.cyan(`    npm install`));
   // The example runs FOUR attempts. This summary promised three, so the one carrying the
@@ -524,7 +978,7 @@ async function runSandbox(args) {
   console.log(`  ${c.green('✓')} sandbox agent ${c.b(config.agentDid)} ${c.dim('(shared test identity)')}`);
   const scope = config.mandate?.scope || 'flight-purchase';
   const perTxnMax = Number(config.perTxnMax) || 500;
-  scaffoldProject({ outDir, config, slug: 'metamynd-sandbox', scope, perTxnMax, sandbox: true, force: !!args.force });
+  scaffoldProject({ outDir, config, slug: 'metamynd-sandbox', scope, perTxnMax, sandbox: true, withGateway: false, force: !!args.force });
 }
 
 // ---------- --harness: a free, local, zero-network governance harness ----------
@@ -1157,6 +1611,14 @@ No anchored/verifiable identity, no cross-party trust, no evidence anyone but yo
 no dashboard reachable when this machine is off, no owner queue someone else can approve from.
 That's the hosted platform (\`npx create-metamynd-agent\`, without \`--harness\`) — same
 \`guardTool()\` call, same rules shape, so upgrading later is a config change, not a rewrite.
+
+It is also **not a separate enforcement boundary**. \`guardToolLocal()\` (in \`index.mjs\`) is a
+cooperative library this process embeds — call the tool handler directly instead of the guarded
+one and nothing stops you, because there is no second party in the loop to disagree with you.
+That's structural, not a bug: use this harness to govern your own agent's own honest behavior,
+not as a defense against an agent (or a person) actively trying to get around it. The hosted
+platform's \`guardTool()\` doesn't have this gap, because the MCP/tool service re-verifies the
+agent's signed authority for itself instead of trusting that the agent's own guard ran.
 `;
 }
 
@@ -1328,7 +1790,7 @@ async function runClaim(args) {
 
   const slug = slugify(state.name || 'metamynd-agent');
   const outDir = resolve(String(args.out || `./${slug}`));
-  scaffoldProject({ outDir, config, slug, scope: state.scope || config.mandate?.scope || 'flight-purchase', perTxnMax: Number(state.perTxnMax) || 500, sandbox: false, force: !!args.force });
+  scaffoldProject({ outDir, config, slug, scope: state.scope || config.mandate?.scope || 'flight-purchase', perTxnMax: Number(state.perTxnMax) || 500, sandbox: false, withGateway: !args['no-gateway'], gatewayPort: Number(args['gateway-port']) || DEFAULT_GATEWAY_PORT, force: !!args.force });
 }
 
 // ---------- main ----------
@@ -1451,7 +1913,7 @@ async function main() {
   }
 
   // 4. Scaffold + next steps
-  scaffoldProject({ outDir, config, slug, scope, perTxnMax, sandbox: false, force: !!args.force });
+  scaffoldProject({ outDir, config, slug, scope, perTxnMax, sandbox: false, withGateway: !args['no-gateway'], gatewayPort: Number(args['gateway-port']) || DEFAULT_GATEWAY_PORT, force: !!args.force });
 }
 
 main().catch((e) => fail(e?.stack || e?.message || String(e)));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-metamynd-agent",
-  "version": "0.6.0",
-  "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, and drops a runnable example. --harness scaffolds a free, local, zero-network governance harness instead.",
+  "version": "0.7.0",
+  "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.",
   "type": "module",
   "bin": {
     "create-metamynd-agent": "index.mjs"