create-metamynd-agent 0.10.16 → 0.12.0

package/README.md

@@ -10,9 +10,9 @@ default, a second `gateway/` process** built on
 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
-> not; it's the only gate.
+> **Prerequisite:** an agent is always owned by a person/org with a **MetaMynd account**. Verification
+> is *reported*, not required, to get started: an unverified owner works on Testnet within the
+> free-tier limits, and verifying once in the dashboard (KYC/KYB) is what unlocks mainnet.
 
 ## Free local harness (no account, no network, `--harness`)
 
@@ -170,6 +170,15 @@ the whole protocol.
 Named precisely, not left implicit:
 
 - **Direct call.** `bookFlight()` doesn't exist in the agent's process.
+- **Payload binding is ON by default (0.11.0, MAGP §8.3.9).** The generated agent signs the COMPLETE body it sends as a payload, the
+  authorization it gets from the gate is bound to that same body, and the generated gateway sets `requirePayloadBinding: true`: it
+  digests the body it is about to run and the issuer refuses the claim unless that is the digest the agent signed. The eight
+  signed fields only ever covered amount and merchant; this covers the value of every field the route allows (a payee, a passenger
+  list you add). A request that bound no payload is refused (`PAYLOAD_BINDING_REQUIRED`) rather than run unbound. If you add a body
+  field, add it to `allowedFields` **and** to the `payload` the agent signs (both sit next to each other in the generated files).
+  A scaffold that signs through the signer daemon (`--byok --daemon-socket`) needs `@metamynd/agentsafe-signer` 0.15.0 or later. The
+  hosted non-financial scaffold reads nothing from its body, so there is nothing for it to bind, and a scaffold with no gateway
+  (`--no-gateway`, or `--sandbox`'s in-process demo) has no separate executor to hold to the digest, so it stays as it was.
 - **Confused deputy (payload).** Signing a cheap request while executing an expensive one (a
   different amount/merchant in the body than what was signed) is refused before the tool runs —
   payload binding (`@metamynd/agentsafe-http-gateway` ≥ 0.4.0). The default binder requires

package/index.mjs

@@ -53,7 +53,7 @@ const GUARD_PKG = '@metamynd/agentsafe-guard';
 // requires request inputs blocks a bare baseline request).
 // 0.12.4 makes `verify` probe in the currency the mandate's caps name (it assumed USD), which a scaffolded
 // non-USD agent's `npm test` needs.
-const GUARD_VERSION = '^0.14.0';
+const GUARD_VERSION = '^0.15.0';
 /** The harness entry point's config load, shared by both harness templates: a fresh clone has no
  *  agent.metamynd.json (it is gitignored), so say what to do instead of a bare ENOENT (BR-004). */
 function harnessConfigLoad() {
@@ -795,6 +795,30 @@ async function apiPost(base, path, body, token) {
   return json;
 }
 
+/**
+ * POST /policy/counterparties for the gateway's own DID — best-effort, unlike apiPost above: a
+ * hosted financial gateway works fine on testnet with no registration at all (open by default), so
+ * a failure here (network blip, an older backend without the endpoint) should not abort scaffolding
+ * the way a failed agent provisioning does. Always sends confirmEnforcementChange: true — this CLI
+ * IS the confirmation (the caller is reading this exact terminal output live, the same way a
+ * dashboard registration shows its own dialog before setting the flag); see the printed message
+ * either way.
+ */
+async function registerGatewayCounterparty(base, token, did, label) {
+  try {
+    const res = await fetch(`${base}/policy/counterparties`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ did, label, confirmEnforcementChange: true }),
+    });
+    const json = await res.json().catch(() => null);
+    if (!res.ok || json?.success === false) return { ok: false, message: json?.message ?? `HTTP ${res.status}` };
+    return { ok: true, message: json?.message ?? 'registered' };
+  } catch (e) {
+    return { ok: false, message: String(e?.message ?? e) };
+  }
+}
+
 // ---------- scaffolding ----------
 /**
  * The --no-gateway / --sandbox variant: the tool is a local function in the SAME process as
@@ -987,18 +1011,23 @@ const GATEWAY = process.env.GATEWAY_URL || 'http://localhost:${gatewayPort}';
 // --- 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) {
+  // The COMPLETE body the tool receives. It is signed as a payload (MAGP 8.3.9): the eight signed fields cover amount and
+  // merchant, not anything else a real tool takes (a payee, a passenger list). The digest covers ALL of it, and the gateway
+  // refuses to run the tool on a body that is not exactly this one.
+  const payload = { amount: args.amount, merchant: args.merchant, currency: args.currency ?? '${currency}' };
   const signed = await guard.buildSignedRequest({
     action: '${scope}',
     amount: args.amount,
     currency: args.currency ?? '${currency}',
     merchant: args.merchant,
     context: { tool: 'book-flight', riskLevel: args.riskLevel ?? 'low' },
+    payload,
   });
   signed.authorizationId = decision?.authorizationId;
   const res = await fetch(GATEWAY + '/book-flight', {
     method: 'POST',
     headers: { 'content-type': 'application/json', 'x-magp-request': JSON.stringify(signed) },
-    body: JSON.stringify({ amount: args.amount, merchant: args.merchant, currency: args.currency ?? '${currency}' }),
+    body: JSON.stringify(payload),
   });
   const body = await res.json().catch(() => null);
   if (!res.ok) {
@@ -1020,6 +1049,9 @@ const gatedBookFlight = guard.guardTool(
     currency: a.currency ?? '${currency}',
     merchant: a.merchant,
     context: { tool: 'book-flight', riskLevel: a.riskLevel ?? 'low' },
+    // The authorization is bound to the SAME body bookFlightViaGateway() sends, so the gate records what this agent
+    // signed and the gateway can prove it is running exactly that. Keep the two in step if you add a field.
+    payload: { amount: a.amount, merchant: a.merchant, currency: a.currency ?? '${currency}' },
   }),
 );
 
@@ -1330,7 +1362,7 @@ console.log('');
  * allowed value-less request would be refused AUTHORIZATION_REQUIRED. The README states what that
  * leaves open (replay) rather than implying the financial scaffold's guarantees.
  */
-function gatewayServerFileNeutral(scope, port, apiBase) {
+function gatewayServerFileNeutral(scope, port, apiBase, policyKey) {
   return `#!/usr/bin/env node
 // gateway/server.mjs — the enforcement boundary for this agent's tool(s).
 //
@@ -1369,7 +1401,12 @@ const routes = [{ method: 'POST', path: '/perform', action: '${scope}', valueFie
 // would be refused AUTHORIZATION_REQUIRED. What that leaves open (a signed request is reusable for
 // the guard's 5-minute freshness window; the issuer's stateful rate/circuit-breaker floors; and the
 // rule inputs, which are not covered by the signature) is spelled out in README.md.
-const guard = createMcpGuard({ serviceDid: 'did:local:${scope}-gateway', issuerApi: MAGP_API, requireAuthorization: false });
+// policyPublicKey pins the bundle to MetaMynd's OWN signing key (from your provisioning response,
+// baked in here — never fetched at runtime, so a compromised network can't swap it out alongside a
+// forged bundle). Without it, verifyBundle() never runs at all: an attacker who can intercept the
+// fetch to \`\${MAGP_API}/policy/bundle/...\` — a MITM, a compromised DNS/proxy — can hand this gateway
+// a bundle with a higher cap or no rules, and it would be trusted the same as the real one.
+const guard = createMcpGuard({ serviceDid: 'did:local:${scope}-gateway', issuerApi: MAGP_API, requireAuthorization: false${policyKey ? `, policyPublicKey: '${policyKey}'` : ''} });
 
 const gateway = createHttpGateway({
   guard,
@@ -1450,7 +1487,10 @@ This is narrower than it sounds, so read it before relying on it.
 **Closed:** no tool call without a validly signed request from THIS agent for an action in its
 mandate. The agent's Ed25519 signature is checked against its DID, the action must be granted, and a
 suspended or quarantined agent is refused. Code that skips the agent's own guard and cannot sign as
-the agent gets nothing, and there is no local function to call directly.
+the agent gets nothing, and there is no local function to call directly. The policy bundle itself is
+pinned to MetaMynd's own signing key (\`policyPublicKey\`, baked in from your provisioning response) —
+a party that can intercept the bundle fetch (a MITM, a compromised DNS/proxy) cannot hand this gateway
+a forged bundle with a higher cap or no rules; \`server.mjs\` refuses an unsigned or tampered one outright.
 
 **NOT closed — be precise about this:**
 
@@ -1608,7 +1648,7 @@ function exampleReadme(slug, scope, withGateway, gatewayPort, daemonKey = false)
   const configFileLine = daemonKey
     ? `- \`agent.metamynd.json\` — your portable guard config (identity, mandate scope \`${scope}\`, issuer keys).
   **Holds no secret key.** Signing goes through your already-running agentsafe-signer daemon
-  (\`daemonSocketPath\`) instead — see \`docs/integration/INSTALL-AGENTSAFE-SIGNER.md\`.`
+  (\`daemonSocketPath\`) instead — see \`docs/integration/INSTALL-AGENTSAFE-SIGNER.md\`.${withGateway ? ' Payload binding is on by default and signs through the daemon too, which needs agentsafe-signer 0.15.0 or later.' : ''}`
     : `- \`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\`.`;
   const gatewaySection = withGateway
@@ -1714,7 +1754,7 @@ function gitignore() {
 // 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) {
+function gatewayServerFile(scope, port, apiBase, policyKey) {
   return `#!/usr/bin/env node
 // gateway/server.mjs — the REAL enforcement boundary for this agent's tool(s).
 //
@@ -1723,6 +1763,7 @@ function gatewayServerFile(scope, port, apiBase) {
 // 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 { readFileSync } from 'node:fs';
 import http from 'node:http';
 import { createMcpGuard } from '${MCP_GUARD_PKG}';
 import { createHttpGateway } from '${GATEWAY_PKG}';
@@ -1751,17 +1792,33 @@ async function bookFlight(args) {
 // signed context, not the tool body.
 const routes = [{ method: 'POST', path: '/book-flight', action: '${scope}', valueFields: ['amount', 'merchant'], allowedFields: ['amount', 'currency', 'merchant'] }];
 
-// 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.
+// This gateway's OWN identity — separate from the agent's on purpose (an agent must not be able to
+// release or lower-settle a hold it authorized itself; only the SERVICE that claimed it may). Real
+// and registered as a trusted counterparty when \`npx create-metamynd-agent\` provisioned it (see
+// README.md); a real serviceKey is what lets serviceAuthHeaders() sign an AUTHENTICATED claim
+// (MAGP-SERVICE-v1) instead of relying on the bearer claimToken alone — required for a MAINNET
+// hold (MAGP §8.7.10), and strictly better than an anonymous claim on testnet too.
+const identity = JSON.parse(readFileSync(new URL('./service.metamynd.json', import.meta.url)));
 //
 // 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 });
+//
+// policyPublicKey pins the bundle to MetaMynd's OWN signing key (from your provisioning response,
+// baked in here — never fetched at runtime, so a compromised network can't swap it out alongside a
+// forged bundle). Without it, verifyBundle() never runs at all: an attacker who can intercept the
+// fetch to \`\${MAGP_API}/policy/bundle/...\` — a MITM, a compromised DNS/proxy — can hand this gateway
+// a bundle with a higher cap or no rules, and it would be trusted the same as the real one.
+const guard = createMcpGuard({ serviceDid: identity.serviceDid, serviceKey: identity.serviceKey ?? undefined, issuerApi: MAGP_API, requireAuthorization: true${policyKey ? `, policyPublicKey: '${policyKey}'` : ''} });
 
 const gateway = createHttpGateway({
   guard,
   routes,
+  // Payload binding (MAGP 8.3.9): the agent signs a digest of the WHOLE body, this gateway digests the body it is about to
+  // run, and the issuer refuses the claim unless the two are the digest the agent signed at authorize time. allowedFields
+  // above lists which keys may appear; this makes the VALUES of every one of them (a payee, a passenger list) the agent's too.
+  // A request whose authorization bound no payload is refused (PAYLOAD_BINDING_REQUIRED) rather than run unbound.
+  requirePayloadBinding: true,
   forward: async (req) => {
     let args = {};
     try { args = JSON.parse(req.rawBody?.toString('utf8') || '{}'); } catch { /* empty body */ }
@@ -1828,7 +1885,7 @@ function gatewayEnvExample() {
 }
 
 function gatewayGitignore() {
-  return `node_modules/\n.env\n`;
+  return `node_modules/\n.env\nservice.metamynd.json\n`;
 }
 
 function gatewayReadme(slug, scope, port) {
@@ -1879,6 +1936,10 @@ add another protected route here rather than adding a local function back in \`i
 - \`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()\`.
+- \`service.metamynd.json\` — this gateway's OWN identity (\`serviceDid\`/\`serviceKey\`), gitignored
+  like \`agent.metamynd.json\` one directory up. \`npx create-metamynd-agent\` generated it and
+  registered its DID as a trusted counterparty (see "Who may claim this agent's holds" below); a
+  clone needs its own, the same way it needs its own \`agent.metamynd.json\`.
 - \`.env.example\` — where real tool credentials go (copy to \`.env\`, fill in, never commit).
 
 ## What this closes, precisely
@@ -1887,6 +1948,10 @@ Four independent checks, each closing a different bypass an agent (or anything a
 own code, or a network attacker) might attempt:
 
 - **Direct call.** \`bookFlight()\` doesn't exist in the agent's process. There's nothing to call.
+- **Forged policy bundle.** \`server.mjs\` bakes in \`policyPublicKey\` (from your provisioning
+  response) and refuses an unsigned or tampered bundle outright — a party that can intercept the
+  fetch (a MITM, a compromised DNS/proxy) cannot hand this gateway a bundle with a higher cap or
+  no rules and have it trusted the same as the real one.
 - **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.4.5) — signing a cheap request while executing an
@@ -1918,6 +1983,25 @@ own code, or a network attacker) might attempt:
   the gateway will release that hold. Only the gateway that claimed the hold can do either — the agent
   cannot capture it lower or void it, which is what stopped it recovering the budget of a purchase it
   had just had executed.
+
+### Who may claim this agent's holds
+
+This gateway claims with its own real identity (\`service.metamynd.json\`, above) — not the agent's,
+on purpose: an agent must never be able to release or lower-settle a hold it authorized itself. On
+provisioning, \`npx create-metamynd-agent\` registered that DID as a trusted counterparty for you
+(\`POST /policy/counterparties\`). A **MAINNET** hold is *always* registered-only, regardless of your
+registry (MAGP §8.7.10) — a testnet hold stays open unless you have registered anything at all.
+Manage the registry at \`/dashboard/counterparties\`, or:
+
+\`\`\`bash
+curl -X POST $MAGP_API/policy/counterparties \\
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \\
+  -d '{ "did": "'"$(node -e "console.log(JSON.parse(require('fs').readFileSync('./service.metamynd.json')).serviceDid)")"'", "confirmEnforcementChange": true }'
+\`\`\`
+
+\`confirmEnforcementChange: true\` is required only for your account's FIRST-EVER registration —
+it switches EVERY one of your holds (not just this agent's) from open to registered-only, so the
+API refuses a first registration without it.
 - **Amount unknown.** \`amount-unknown\` (\`@metamynd/agentsafe-mcp-guard\` ≥ 0.3.0) blocks a
   platform tool by default when its raw bytes or a nested payload hide the amount from a naive
   spend cap — AND this agent's OWN starter SOP (see \`agent.metamynd.json\` /
@@ -1981,7 +2065,7 @@ function assertScaffoldTarget(outDir, force) {
  */
 // `demo` (from buildPolicyCases) selects the NON-financial project; without it this is the historical
 // payment scaffold. `merchant` defaults to a payment demo's merchant only in that financial branch.
-function scaffoldProject({ outDir, config, slug, scope, perTxnMax, currency = 'USD', merchant, sandbox, withGateway, gatewayPort = DEFAULT_GATEWAY_PORT, force = false, demo = null }) {
+function scaffoldProject({ outDir, config, slug, scope, perTxnMax, currency = 'USD', merchant, sandbox, withGateway, gatewayPort = DEFAULT_GATEWAY_PORT, force = false, demo = null, gatewayIdentity = null }) {
   const neutral = !!demo;
   assertScaffoldTarget(outDir, force);
   console.log(`\n  ${c.b('Scaffolding')} ${c.dim(outDir)}`);
@@ -2021,9 +2105,26 @@ function scaffoldProject({ outDir, config, slug, scope, perTxnMax, currency = 'U
 
   if (withGateway) {
     const apiBase = config.apiBase ?? config.api ?? DEFAULT_API;
+    // The key that signs every policy bundle (magp.policy-signer.ts) — present on every provisioning
+    // response that talks to a real backend (full account, sandbox, delegated-claim). Baked into the
+    // generated gateway so it pins the bundle rather than trusting whatever the fetch returns; absent
+    // only for a config predating this field (an older scaffold's saved agent.metamynd.json), where
+    // the generated gateway is unchanged from before rather than baking in nothing and crashing.
+    const policyKey = config.issuer?.policyKey ?? null;
     const gwDir = join(outDir, 'gateway');
     if (!existsSync(gwDir)) mkdirSync(gwDir, { recursive: true });
-    writeFileSafe(gwDir, 'server.mjs', neutral ? gatewayServerFileNeutral(scope, gatewayPort, apiBase) : gatewayServerFile(scope, gatewayPort, apiBase), force);
+    if (!neutral) {
+      // The gateway's OWN identity — the one that claims and settles this agent's holds (MAGP §8.7.6/
+      // §8.7.10), separate from the agent's own DID on purpose (an agent must not be able to release or
+      // lower-settle a hold it authorized itself). `gatewayIdentity` is real and registered when the
+      // caller generated + registered one (main()'s hosted-financial path); a caller that didn't
+      // (an older code path, or a direct scaffoldProject() call in a test) falls back to the historical
+      // non-cryptographic placeholder — same shape as before this field existed, still parses and runs,
+      // just unable to claim a MAINNET hold or sign an authenticated claim on any network.
+      const identity = gatewayIdentity ?? { did: `did:local:${scope}-gateway`, keyHex: null };
+      writeFileSafe(gwDir, 'service.metamynd.json', JSON.stringify({ serviceDid: identity.did, serviceKey: identity.keyHex }, null, 2) + '\n', force, 0o600);
+    }
+    writeFileSafe(gwDir, 'server.mjs', neutral ? gatewayServerFileNeutral(scope, gatewayPort, apiBase, policyKey) : gatewayServerFile(scope, gatewayPort, apiBase, policyKey), force);
     writeFileSafe(gwDir, 'package.json', gatewayPackageJson(slug), force);
     writeFileSafe(gwDir, '.env.example', neutral ? gatewayEnvExampleNeutral() : gatewayEnvExample(), force);
     writeFileSafe(gwDir, '.gitignore', gatewayGitignore(), force);
@@ -2292,6 +2393,10 @@ const gateway = createHttpGateway({
   guard,
   routes: ROUTES,
   denyByDefault: true,
+  // Payload binding (MAGP 8.3.9): the agent signs a digest of the WHOLE body and this gateway refuses to run a tool on a
+  // body that is not exactly that one — the values of every allowed field, not only amount and merchant. A request that
+  // bound no payload is refused (PAYLOAD_BINDING_REQUIRED) instead of run unbound.
+  requirePayloadBinding: true,
   // Reached ONLY after the guard allowed the request AND the body was bound to what was signed.
   forward: async (req) => {
     const route = matchRoute(ROUTES, req.method, req.path);
@@ -2751,8 +2856,11 @@ const GATEWAY = process.env.HARNESS_GATEWAY_URL || 'http://localhost:${gatewayPo
 // issuer): it builds and signs the same canonical message a real gate would verify, entirely
 // offline, using this agent's own did:key — the gateway verifies that signature for itself.
 async function callGateway(path, action, args) {
-  const signed = await guard.buildSignedRequest({ action, amount: args.amount, currency: args.currency ?? '${currency}', merchant: args.merchant, context: { tool: '${scope}', riskLevel: args.riskLevel ?? 'low' } });
-  const res = await fetch(GATEWAY + path, { method: 'POST', headers: { 'content-type': 'application/json', 'x-magp-request': JSON.stringify(signed) }, body: JSON.stringify({ amount: args.amount, merchant: args.merchant, currency: args.currency ?? '${currency}' }) });
+  // The COMPLETE body the tool receives, signed as a payload (MAGP 8.3.9): the eight signed fields cover amount and merchant
+  // only, and this gateway refuses to run the tool on a body that is not exactly the one signed here.
+  const payload = { amount: args.amount, merchant: args.merchant, currency: args.currency ?? '${currency}' };
+  const signed = await guard.buildSignedRequest({ action, amount: args.amount, currency: args.currency ?? '${currency}', merchant: args.merchant, context: { tool: '${scope}', riskLevel: args.riskLevel ?? 'low' }, payload });
+  const res = await fetch(GATEWAY + path, { method: 'POST', headers: { 'content-type': 'application/json', 'x-magp-request': JSON.stringify(signed) }, body: JSON.stringify(payload) });
   const body = await res.json().catch(() => null);
   if (!res.ok) {
     const err = new Error('gateway ' + res.status + ': ' + (body?.reasonCode ?? 'refused'));
@@ -2953,7 +3061,9 @@ ${withGateway ? `const GATEWAY = process.env.HARNESS_GATEWAY_URL || 'http://loca
 // file to call directly. buildSignedRequest() is pure (no network, no issuer): it signs the request
 // offline with this agent's own did:key, and the gateway verifies that signature for itself.
 async function callGateway(path, action, args) {
-  const signed = await guard.buildSignedRequest({ action, merchant: MERCHANT, context: args });
+  // The body is empty on purpose (this tool reads nothing from it), and it is signed as the payload so the gateway can
+  // require binding on every route: a body with anything in it is not the one signed (MAGP 8.3.9).
+  const signed = await guard.buildSignedRequest({ action, merchant: MERCHANT, context: args, payload: {} });
   const res = await fetch(GATEWAY + path, { method: 'POST', headers: { 'content-type': 'application/json', 'x-magp-request': JSON.stringify(signed) }, body: '{}' });
   const body = await res.json().catch(() => null);
   if (!res.ok) {
@@ -3627,6 +3737,15 @@ async function main() {
   }
   const body = {
     name, scope,
+    // Explicit, not left to the backend's own eligibility-based default (mainnet for a KYB-verified
+    // owner, testnet otherwise) — an owner who happens to be verified would otherwise silently get a
+    // REAL mainnet agent from a plain `npx create-metamynd-agent` with no signal that anything
+    // changed. The generated financial gateway CAN now satisfy mainnet's registry enforcement (a
+    // real, registered did:key — see the gateway identity step below), but this CLI has no flag to
+    // opt into mainnet yet; that is a separate decision (exposing it safely — KYB status, spend
+    // caps — is more than a network toggle) from giving the gateway a real identity, which is what
+    // this fixes. docs/design/release-blockers-open-items.md, "Registry default".
+    network: 'testnet',
     ...(financial ? { currency, maxAmount, perTxnMax } : {}),
     merchants,
     ...(publicKey ? { publicKey } : {}),
@@ -3673,6 +3792,27 @@ async function main() {
     console.log(c.dim(`      POST ${base}/agent-identity/${config.identityId}/verify-key  { "signature": "<hex>" }  (owner token)`));
   }
 
+  // 3c. The gateway's OWN identity — a real did:key, separate from the agent's own (an agent must
+  // never be able to release or lower-settle a hold it authorized itself; only the SERVICE that
+  // claimed it may). Only the financial, with-gateway shape ever claims a hold at all; the
+  // non-financial gateway never calls claimAuthorization() (requireAuthorization is off there), so
+  // it has no counterparty identity to register.
+  let gatewayIdentity = null;
+  if (financial && !args['no-gateway']) {
+    const gwKeypair = generateAgentKeypair();
+    const gatewayDid = buildDidKey(rawPublicKeyFromSpkiHex(gwKeypair.publicKeyHex));
+    gatewayIdentity = { did: gatewayDid, keyHex: gwKeypair.privateKeyHex };
+    console.log(c.dim(`\n  → registering the gateway's identity as a trusted counterparty (so it can claim this agent's holds) …`));
+    const reg = await registerGatewayCounterparty(base, token, gatewayDid, `${scope}-gateway`);
+    if (reg.ok) {
+      console.log(`  ${c.green('✓')} gateway DID ${c.b(gatewayDid)} — ${reg.message}`);
+    } else {
+      console.log(`  ${c.yellow('!')} could not register the gateway as a trusted counterparty: ${reg.message}`);
+      console.log(c.dim(`     it still works on testnet (open by default with no registry entries); a MAINNET hold cannot be`));
+      console.log(c.dim(`     claimed until it is registered — POST ${base}/policy/counterparties { "did": "${gatewayDid}", "confirmEnforcementChange": true }`));
+    }
+  }
+
   // 4. Scaffold + next steps
   // The demo comes from the rules actually provisioned: the caller's own, else the backend's default
   // for a non-financial agent (the same amount-free review harnessDefaultSopNeutral describes).
@@ -3681,7 +3821,7 @@ async function main() {
     console.log(`  ${c.green('✓')} derived ${demo.cases.length} demo case(s) from your rules`);
     for (const n of demo.notDemonstrated) console.log(`  ${c.yellow('!')} not staged in the demo: ${n.rule} ${c.dim('— ' + n.why + '; still enforced')}`);
   }
-  scaffoldProject({ demo, outDir, config, slug, scope, perTxnMax, currency, merchant: financial ? merchants[0] || 'demo-merchant' : merchants[0], sandbox: false, withGateway: !args['no-gateway'], gatewayPort: Number(args['gateway-port']) || DEFAULT_GATEWAY_PORT, force: !!args.force });
+  scaffoldProject({ demo, outDir, config, slug, scope, perTxnMax, currency, merchant: financial ? merchants[0] || 'demo-merchant' : merchants[0], sandbox: false, withGateway: !args['no-gateway'], gatewayPort: Number(args['gateway-port']) || DEFAULT_GATEWAY_PORT, force: !!args.force, gatewayIdentity });
 }
 
 // Exported so the smoke tests can exercise the generators directly. Importing this file must not
@@ -3689,6 +3829,6 @@ async function main() {
 export {
   buildPolicyCases, resolveFinancial, policyMolecules, ruleToMolecule,
   generateAgentKeypair, harnessAgentDid, harnessMandate, harnessRulesFile, harnessDefaultSopNeutral,
-  scaffoldProject, exampleIndexNeutral, exampleReadmeNeutral, gatewayServerFileNeutral, gatewayReadmeNeutral,
+  scaffoldProject, defaultNeutralDemo, exampleIndexNeutral, exampleReadmeNeutral, gatewayServerFileNeutral, gatewayReadmeNeutral,
 };
 if (!process.env.CREATE_METAMYND_AGENT_NO_MAIN) main().catch((e) => fail(e?.stack || e?.message || String(e)));

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "create-metamynd-agent",
-  "version": "0.10.16",
+  "version": "0.12.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 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"
   },
   "scripts": {
-    "test": "node harness-gateway.smoke.mjs && node harness-gateway-bind.smoke.mjs && node policy-demo.smoke.mjs && node hosted-nonfinancial.smoke.mjs && node modes-nonfinancial.smoke.mjs && node byok-daemon.smoke.mjs"
+    "test": "node generated-code-parses.smoke.mjs && node harness-gateway.smoke.mjs && node harness-gateway-bind.smoke.mjs && node policy-demo.smoke.mjs && node hosted-nonfinancial.smoke.mjs && node modes-nonfinancial.smoke.mjs && node byok-daemon.smoke.mjs"
   },
   "files": [
     "index.mjs",