create-metamynd-agent 0.11.2 → 0.12.2

package/README.md

@@ -13,6 +13,8 @@ enforcement boundary — see [Separate tool gateway](#separate-tool-gateway-defa
 > **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.
+> This CLI always provisions **Testnet** agents; a mainnet agent is launched from the dashboard's
+> **Launchpad** (`/dashboard/launchpad`) once you are verified.
 
 ## Free local harness (no account, no network, `--harness`)
 

package/index.mjs

@@ -102,7 +102,7 @@ const MCP_GUARD_PKG = '@metamynd/agentsafe-mcp-guard';
 // 0.6.0 brings buildAuthMessage's `resource` field and buildLocalDecisionMessage into this
 // package's own bundled policy-core.mjs (alongside the guard's own 0.10.0) — no scaffolded
 // template code changes, but the floor must still cover the real current version.
-const MCP_GUARD_VERSION = '^0.11.0';
+const MCP_GUARD_VERSION = '^0.12.0';
 const GATEWAY_PKG = '@metamynd/agentsafe-http-gateway';
 // 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.
@@ -205,7 +205,7 @@ ${c.b('Options')}
   --gateway            --harness only: ALSO scaffold a second local process (still zero
                        network, zero account) that independently re-verifies every request
                        against the same rules file, using the real @metamynd/agentsafe-mcp-guard.
-                       Off by default. Does not close nonce replay/cumulative spend — see the
+                       Off by default. Refuses a replayed request; does not track cumulative spend — see the
                        generated README#--gateway for exactly what it does and does not.
   --gateway-port <n>   The gateway process's port, hosted flow or --harness --gateway (default 4401)
   --port <n>           --harness only: the local dashboard's port (default 4400)
@@ -216,6 +216,12 @@ ${c.b('Options')}
 ${c.b('Environment')}
   METAMYND_API, METAMYND_EMAIL, METAMYND_PASSWORD  — fallbacks for the flags above
 
+${c.b('Network')}
+  Every hosted agent this CLI provisions is a ${c.b('Testnet')} agent, whatever your verification status —
+  there is deliberately no mainnet flag. To launch a ${c.b('Mainnet')} agent, use the Launchpad in the
+  dashboard (https://metamynd.ai/dashboard/launchpad): its Mainnet option is available once your
+  owner verification (KYC/KYB) is complete.
+
 ${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
@@ -795,6 +801,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
@@ -1739,6 +1769,7 @@ function gatewayServerFile(scope, port, apiBase, policyKey) {
 // 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}';
@@ -1767,8 +1798,13 @@ 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
@@ -1779,7 +1815,7 @@ const routes = [{ method: 'POST', path: '/book-flight', action: '${scope}', valu
 // 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: true${policyKey ? `, policyPublicKey: '${policyKey}'` : ''} });
+const guard = createMcpGuard({ serviceDid: identity.serviceDid, serviceKey: identity.serviceKey ?? undefined, issuerApi: MAGP_API, requireAuthorization: true${policyKey ? `, policyPublicKey: '${policyKey}'` : ''} });
 
 const gateway = createHttpGateway({
   guard,
@@ -1855,7 +1891,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) {
@@ -1906,6 +1942,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
@@ -1949,6 +1989,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\` /
@@ -2012,7 +2071,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)}`);
@@ -2060,6 +2119,17 @@ function scaffoldProject({ outDir, config, slug, scope, perTxnMax, currency = 'U
     const policyKey = config.issuer?.policyKey ?? null;
     const gwDir = join(outDir, 'gateway');
     if (!existsSync(gwDir)) mkdirSync(gwDir, { recursive: true });
+    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);
@@ -2255,12 +2325,14 @@ function harnessRulesFile(mandate, sopDocument) {
 // that skips its own guardToolLocal() call, or calls bookFlight() directly, gets nothing —
 // the tool only runs in the gateway process now.
 //
+// Replay of the SAME signed request is refused too (REPLAY_DETECTED): the gateway remembers each nonce for as long as
+// the guard would accept it, in memory (a restart forgets them). An independent tester's rerun (2026-09-24) found the
+// same bytes accepted twice before this.
+//
 // What this does NOT close (be precise, this is a local demo, not the hosted platform):
-// nonce replay and cumulative-spend across many calls. Those need a STATEFUL authority — the
-// hosted gate's `requireAuthorization` claims a real, single-use authorizationId against a
-// database. A local harness has no such database (that is the whole point of --harness), so
-// this gateway does per-request re-evaluation only, same as the hosted gateway's baseline
-// before `requireAuthorization` is added. The README says so.
+// cumulative spend across many DIFFERENT calls. That needs a STATEFUL authority — the hosted gate's
+// `requireAuthorization` claims a real, single-use authorizationId against a database and holds the budget there. A
+// local harness has no such database (that is the whole point of --harness). The README says so.
 
 function harnessGatewayServerFile(scope, gatewayPort, agentDid, neutral = false) {
   return `#!/usr/bin/env node
@@ -2351,9 +2423,35 @@ function readBody(req) {
   });
 }
 
+// Replay: every signed request carries a fresh nonce, and the guard refuses one more than 5 minutes old. So a nonce
+// only has to be remembered for that long to refuse the SAME signed request twice. Checked and recorded in one
+// synchronous step, before anything awaits, so two simultaneous copies cannot both get through. In memory: restarting
+// this process forgets it (a replay inside the 5-minute window after a restart is not caught). Cumulative spend across
+// many DIFFERENT requests is still not tracked here — that needs the hosted gate.
+const NONCE_TTL_MS = 6 * 60 * 1000;
+const seenNonces = new Map(); // agentDid|nonce -> expiry
+function firstUseOfNonce(headers) {
+  let signed;
+  try { signed = JSON.parse(headers['x-magp-request'] ?? 'null'); } catch { return true; } // malformed: the guard refuses it
+  if (!signed || typeof signed.nonce !== 'string') return true; // no nonce: the guard refuses it
+  const now = Date.now();
+  if (seenNonces.size > 10000) for (const [k, exp] of seenNonces) if (exp <= now) seenNonces.delete(k);
+  const key = String(signed.agentDid) + '|' + signed.nonce;
+  const exp = seenNonces.get(key);
+  if (exp !== undefined && exp > now) return false;
+  seenNonces.set(key, now + NONCE_TTL_MS);
+  return true;
+}
+
 const server = http.createServer(async (req, res) => {
   try {
     const rawBody = await readBody(req);
+    if (!firstUseOfNonce(req.headers)) {
+      console.log('[harness-gateway] BLOCK ' + req.url + ' — REPLAY_DETECTED (this exact signed request already came through)');
+      res.writeHead(403, { 'content-type': 'application/json', 'x-agentsafe-decision': 'block' });
+      res.end(JSON.stringify({ decision: 'block', reasonCode: 'REPLAY_DETECTED' }));
+      return;
+    }
     const result = await gateway({ method: req.method, path: req.url, headers: req.headers, rawBody });
     const headers = { 'content-type': 'application/json' };
     const decision = result.governance?.decision;
@@ -2914,9 +3012,9 @@ console.log(bold('  Checked twice, by two processes.') + ' bookFlight() lives in
 console.log(dim('  not here. It independently re-verified every attempt above against the SAME'));
 console.log(dim('  ./metamynd-rules.json, over a signed request, before running your tool.'));
 console.log('');
-console.log(dim('  What --gateway does NOT close: nonce replay and cumulative spend across many'));
-console.log(dim('  calls. Those need a STATEFUL authority (the hosted gate\\'s requireAuthorization'));
-console.log(dim('  claims a real, single-use id against a database) - a local harness has none.'));
+console.log(dim('  It also refuses a replay of the same signed request. What --gateway does NOT close:'));
+console.log(dim('  cumulative spend across many different calls. That needs a STATEFUL authority (the'));
+console.log(dim('  hosted gate holds the budget in a database) - a local harness has none.'));
 console.log(dim('  See README.md#--gateway for exactly what this does and does not prove.'));
 console.log('');
 console.log('  Edit ./metamynd-rules.json (or the dashboard) and run again - the outcome');
@@ -3111,9 +3209,8 @@ console.log(dim('  ./metamynd-rules.json, over a signed request, before running
 console.log(dim('  It enforces scope and identity firmly; the rule inputs above are NOT signed, so an'));
 console.log(dim('  agent that can sign could omit or forge one and its rule would not fire.'));
 console.log('');
-console.log(dim('  What --gateway does NOT close: nonce replay across many calls. That needs a STATEFUL'));
-console.log(dim('  authority (the hosted gate claims a real, single-use id against a database) - a local'));
-console.log(dim('  harness has none. See README.md#--gateway for exactly what this does and does not prove.'));
+console.log(dim('  It also refuses a replay of the same signed request (remembered in memory, so a restart'));
+console.log(dim('  forgets). See README.md#--gateway for exactly what this does and does not prove.'));
 console.log('');
 console.log('  Edit ./metamynd-rules.json (or the dashboard) and run again - the outcome');
 console.log(dim('  changes, in BOTH processes, from the one file. That is the point.'));` : `
@@ -3232,13 +3329,19 @@ not cover. An agent that can sign could omit a field or send a different one, an
 it would not fire. The gateway enforces scope and identity firmly; an input-dependent rule is only as
 strong as whatever supplies its input.` : ''}
 
-**NOT closed:** nonce replay and cumulative spend across many calls. Those need a STATEFUL
-authority — the hosted gate's \`requireAuthorization\` atomically claims a real, single-use
-\`authorizationId\` against a database before a Service executes anything (see
-\`@metamynd/agentsafe-mcp-guard\`'s own README). A local harness has no database; that is the
-whole point of \`--harness\`. \`harness-gateway.mjs\` re-checks POLICY per request, which is
-real and worth having, but replaying the exact same signed request twice is NOT refused here
-the way it would be against the hosted gate.
+**Also closed — replaying the same signed request.** \`harness-gateway.mjs\` remembers every nonce for as long as
+the guard would accept the request (about 5 minutes) and refuses the second copy (\`REPLAY_DETECTED\`). The memory is
+in-process: restarting the gateway forgets it.
+
+${demo ? `**NOT closed:** anything that depends on history across many DIFFERENT calls (rate limits, circuit breakers,
+patterns). That needs a STATEFUL authority — the hosted gate's \`requireAuthorization\` atomically claims a real,
+single-use \`authorizationId\` against a database (see \`@metamynd/agentsafe-mcp-guard\`'s own README). A local
+harness has no database; that is the whole point of \`--harness\`. \`harness-gateway.mjs\` re-checks POLICY per
+request, which is real and worth having, but it does not remember what earlier calls did.` : `**NOT closed:** cumulative spend across many DIFFERENT calls. That needs a STATEFUL authority — the hosted gate's
+\`requireAuthorization\` atomically claims a real, single-use \`authorizationId\` against a database and holds the
+budget there (see \`@metamynd/agentsafe-mcp-guard\`'s own README). A local harness has no database; that is the
+whole point of \`--harness\`. \`harness-gateway.mjs\` re-checks POLICY per request, so each call is held to the
+per-transaction cap, but many calls under the cap are not added up here the way the hosted gate adds them up.`}
 
 Also not closed by \`--gateway\` alone: cross-party trust (nobody but you can verify this agent's
 identity or its decisions), evidence anyone but you can audit, a dashboard reachable when this
@@ -3673,6 +3776,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 } : {}),
@@ -3719,6 +3831,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).
@@ -3727,7 +3860,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-metamynd-agent",
-  "version": "0.11.2",
+  "version": "0.12.2",
   "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": {