docs(platform): design the native cotal connector renderer

implementations/cli/smoke/mint-reuse.smoke.ts

@@ -0,0 +1,225 @@
+/**
+ * `cotal mint` identity-reuse smoke (hermetic — no broker). Exercises the REAL mint() command against
+ * a tmp `.cotal/` root laid out exactly as `cotal up` writes it (auth.json via saveSpaceAuth + a
+ * persona file), and asserts the reuse-unless-force contract end to end. Run with:
+ *   pnpm --filter @cotal-ai/cli exec tsx smoke/mint-reuse.smoke.ts
+ *
+ * The load-bearing regression: re-minting an AGENT keeps the SAME nkey id (so its durable ACL row +
+ * dm/dlv durables, all id-keyed, stay valid) — the old unconditional newIdentity() rotated the id on
+ * every mint and orphaned them, leaving the agent @mention-wake-blind. --force rotates deliberately;
+ * a persona ACL change refreshes the baked channels WITHOUT rotating; observer/admin always rotate
+ * (reuse is agent-only — no durable footprint to orphan, and re-signing a privileged key would
+ * silently extend its lifetime); and a present-but-unparseable creds file fails loud (never a silent
+ * fresh-mint that would orphan the id its predecessor may still own).
+ *
+ * mint() resolves its root via findCotalRoot() walking up from process.cwd(), so the harness chdir's
+ * into the tmp root and restores cwd in the finally.
+ */
+import { strict as assert } from "node:assert";
+import { randomUUID } from "node:crypto";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createSpaceAuth, idFromCreds } from "@cotal-ai/core";
+import { authDir, saveSpaceAuth } from "@cotal-ai/workspace";
+import { mint } from "../src/commands/mint.js";
+
+let failures = 0;
+function check(label: string, cond: boolean, extra?: unknown): void {
+  console.log(`${cond ? "✓" : "✗"} ${label}${cond ? "" : ` — ${JSON.stringify(extra)}`}`);
+  if (!cond) failures++;
+}
+
+// The chat-read channels a minted creds file grants (decode the JWT's nats.sub.allow, keep chat.*.<ch>
+// entries). Same JWT-decode shape as manager/smoke/persona-identity-acl.smoke.ts.
+function credSubChat(path: string): string[] {
+  const jwt = readFileSync(path, "utf8").split("\n").find((l) => l && !l.startsWith("-") && l.split(".").length === 3)!;
+  const claims = JSON.parse(Buffer.from(jwt.split(".")[1], "base64url").toString("utf8"));
+  const allow: string[] = claims.nats?.sub?.allow ?? [];
+  return allow.filter((s) => s.includes(".chat."));
+}
+
+// mint() logs its result to stdout; silence it (restored even on throw) so the check output stays
+// legible — the ids we assert on are read straight from the written creds file, not from the log.
+async function mintQuiet(argv: string[]): Promise<void> {
+  const orig = console.log;
+  console.log = () => {};
+  try {
+    await mint(argv);
+  } finally {
+    console.log = orig;
+  }
+}
+
+// A tmp `.cotal/` root with real space trust material (auth.json, exactly as `cotal up` persists it)
+// and a `scout` agent persona reading/posting the `general` channel.
+const space = `mint-reuse-${randomUUID().slice(0, 8)}`;
+const auth = await createSpaceAuth(space);
+const root = mkdtempSync(join(tmpdir(), "cotal-mint-reuse-"));
+const agentsDir = join(root, ".cotal", "agents");
+mkdirSync(agentsDir, { recursive: true });
+saveSpaceAuth(authDir(root), auth);
+const scoutPersona = join(agentsDir, "scout.md");
+writeFileSync(scoutPersona, "---\nname: scout\nsubscribe: [general]\nallowSubscribe: [general]\nallowPublish: [general]\n---\nbody\n");
+const scoutCreds = join(authDir(root), "creds", "scout.creds");
+const credsDir = join(authDir(root), "creds");
+
+const prevCwd = process.cwd();
+process.chdir(root); // findCotalRoot() walks up from cwd — anchor it at our tmp root
+try {
+  // 1) THE regression: re-minting an agent twice reuses the SAME id (before the fix, two mints gave
+  //    two different ids and orphaned the id-keyed durables).
+  await mintQuiet(["scout"]);
+  const id1 = idFromCreds(readFileSync(scoutCreds, "utf8"));
+  await mintQuiet(["scout"]);
+  const id2 = idFromCreds(readFileSync(scoutCreds, "utf8"));
+  check("re-mint of an agent reuses the same id", id1 === id2, { id1, id2 });
+
+  // 2) --force is the deliberate-rotation escape hatch: a fresh id despite an existing creds file.
+  await mintQuiet(["scout", "--force"]);
+  const id3 = idFromCreds(readFileSync(scoutCreds, "utf8"));
+  check("mint --force rotates to a different id", id3 !== id2, { id2, id3 });
+
+  // 3) A persona ACL change is applied on re-mint (refreshed channels) WITHOUT rotating the id —
+  //    the whole point: an agent's read scope is refreshed while its mesh id stays stable.
+  const beforeChans = credSubChat(scoutCreds); // channels baked before the persona change
+  writeFileSync(scoutPersona, "---\nname: scout\nsubscribe: [general]\nallowSubscribe: [general, review]\nallowPublish: [general]\n---\nbody\n");
+  await mintQuiet(["scout"]);
+  const id4 = idFromCreds(readFileSync(scoutCreds, "utf8"));
+  const afterChans = credSubChat(scoutCreds);
+  check("re-mint after an ACL change keeps the identity", id4 === id3, { id3, id4 });
+  check(
+    "re-mint bakes the NEW channel into sub.allow (review added, was absent before)",
+    afterChans.some((s) => s.endsWith(".chat.*.review")) && !beforeChans.some((s) => s.endsWith(".chat.*.review")),
+    { beforeChans, afterChans },
+  );
+
+  // 4) First-ever mint of a brand-new name has no creds file — the reuse=false path must mint a fresh
+  //    identity and write valid creds, not crash on the absent-file read.
+  writeFileSync(join(agentsDir, "newbie.md"), "---\nname: newbie\nsubscribe: [general]\nallowSubscribe: [general]\n---\nbody\n");
+  const newbieCreds = join(credsDir, "newbie.creds");
+  await mintQuiet(["newbie"]);
+  const idNew = idFromCreds(readFileSync(newbieCreds, "utf8"));
+  check("first mint of a brand-new name mints a fresh identity (absent-creds path, no crash)", idNew !== id4 && idNew.startsWith("U"), { idNew, id4 });
+
+  // 5) Reuse is AGENT-ONLY: re-minting an observer or admin creds file ROTATES the id (a privileged
+  //    key must not silently extend its lifetime across re-mints).
+  for (const profile of ["observer", "admin"] as const) {
+    const pOut = join(credsDir, `${profile}-dash.creds`);
+    await mintQuiet([`${profile}-dash`, "--profile", profile]);
+    const a = idFromCreds(readFileSync(pOut, "utf8"));
+    await mintQuiet([`${profile}-dash`, "--profile", profile]);
+    const b = idFromCreds(readFileSync(pOut, "utf8"));
+    check(`re-mint of an ${profile} creds rotates the id (reuse is agent-only)`, a !== b, { profile, a, b });
+  }
+
+  // 6) A present-but-unparseable creds file at the out path fails LOUD naming --force — never a raw
+  //    parse crash, and never a silent fresh-mint (which would orphan the predecessor id's durables).
+  mkdirSync(credsDir, { recursive: true });
+  const corruptCreds = join(credsDir, "corrupt.creds");
+  writeFileSync(corruptCreds, ""); // present but no seed block
+  let msg = "";
+  try {
+    await mintQuiet(["corrupt"]);
+  } catch (e) {
+    msg = e instanceof Error ? e.message : String(e);
+  }
+  check(
+    "unparseable existing creds → actionable error naming --force (no silent rotate, no raw crash)",
+    /could not be parsed/.test(msg) && /--force/.test(msg),
+    { msg },
+  );
+  // Assert the FILESYSTEM state, not just the message: the failed mint must not have written fresh
+  // creds over the corrupt file. A future refactor that mints-then-throws would still surface a
+  // parse error yet silently rotate the id — this catches that by proving the file is untouched.
+  check(
+    "failed corrupt-creds mint left the file untouched (no silent fresh-mint)",
+    readFileSync(corruptCreds, "utf8") === "",
+    { content: readFileSync(corruptCreds, "utf8").slice(0, 40) },
+  );
+
+  // 7) Cross-identity --out guard (greptile P1). Creds carry the nkey id, NOT the agent name, so the
+  //    only name↔identity binding is the canonical creds/<name>.creds path. Reuse is therefore
+  //    canonical-path-only: `cotal mint <name> --out <another agent's creds>` must never reuse (re-sign
+  //    that file's id with <name>'s ACLs) nor silently clobber it (overwrite its id, orphaning its
+  //    durables). Without --force it fails loud; --force is the deliberate-overwrite escape hatch.
+  writeFileSync(join(agentsDir, "victim.md"), "---\nname: victim\nsubscribe: [general]\nallowSubscribe: [general]\n---\nbody\n");
+  writeFileSync(join(agentsDir, "raider.md"), "---\nname: raider\nsubscribe: [general]\nallowSubscribe: [general, review, ops]\n---\nbody\n");
+  const victimCreds = join(credsDir, "victim.creds");
+  await mintQuiet(["victim"]);
+  const victimBefore = readFileSync(victimCreds, "utf8");
+  const victimIdBefore = idFromCreds(victimBefore);
+  let raiderMsg = "";
+  try {
+    await mintQuiet(["raider", "--out", victimCreds]);
+  } catch (e) {
+    raiderMsg = e instanceof Error ? e.message : String(e);
+  }
+  check(
+    "mint <name> --out <another agent's creds> fails loud naming --force (no cross-identity reuse)",
+    /--force/.test(raiderMsg) && /belong/.test(raiderMsg),
+    { raiderMsg },
+  );
+  check(
+    "refused cross-identity mint left the target creds byte-identical (no re-sign of its id, no clobber)",
+    readFileSync(victimCreds, "utf8") === victimBefore && idFromCreds(readFileSync(victimCreds, "utf8")) === victimIdBefore,
+    { changed: readFileSync(victimCreds, "utf8") !== victimBefore },
+  );
+  // --force is the explicit escape hatch: it rotates to a FRESH identity and overwrites the target.
+  await mintQuiet(["raider", "--out", victimCreds, "--force"]);
+  check(
+    "mint --out <existing creds> --force overwrites with a fresh identity (escape hatch intact)",
+    idFromCreds(readFileSync(victimCreds, "utf8")) !== victimIdBefore,
+    { victimIdBefore, after: idFromCreds(readFileSync(victimCreds, "utf8")) },
+  );
+
+  // 8) Symlinked canonical creds path (greptile P1). `out === canonicalOut` is a STRING compare — it
+  //    does not prove the file at that path belongs to <name>. If creds/<name>.creds is a symlink to
+  //    another agent's creds, existsSync/readFileSync/writeSecretFile all FOLLOW it, so a plain
+  //    `cotal mint <name>` would read the target's id and write <name>'s ACLs back THROUGH the link,
+  //    clobbering the pointed-to agent. A creds file must be a real file at its own path: mint refuses
+  //    a symlinked out path (canonical or custom, with or without --force), leaving the target intact.
+  writeFileSync(join(agentsDir, "keeper.md"), "---\nname: keeper\nsubscribe: [general]\nallowSubscribe: [general]\n---\nbody\n");
+  writeFileSync(join(agentsDir, "decoy.md"), "---\nname: decoy\nsubscribe: [general]\nallowSubscribe: [general, ops]\n---\nbody\n");
+  const keeperCreds = join(credsDir, "keeper.creds");
+  await mintQuiet(["keeper"]);
+  const keeperBefore = readFileSync(keeperCreds, "utf8");
+  const keeperIdBefore = idFromCreds(keeperBefore);
+  symlinkSync(keeperCreds, join(credsDir, "decoy.creds")); // canonical decoy path → keeper's real creds
+  let symlinkMsg = "";
+  try {
+    await mintQuiet(["decoy"]); // canonical path, no --out, no --force
+  } catch (e) {
+    symlinkMsg = e instanceof Error ? e.message : String(e);
+  }
+  check(
+    "mint <name> whose canonical creds is a symlink fails loud (no read/write through the link)",
+    /symlink/.test(symlinkMsg),
+    { symlinkMsg },
+  );
+  check(
+    "refused symlink mint left the link target byte-identical (no clobber of the pointed-to agent)",
+    readFileSync(keeperCreds, "utf8") === keeperBefore && idFromCreds(readFileSync(keeperCreds, "utf8")) === keeperIdBefore,
+    { changed: readFileSync(keeperCreds, "utf8") !== keeperBefore },
+  );
+  // --force must NOT bypass the guard: rotating a fresh id straight through the link still clobbers the
+  // target. The escape hatch is to remove the link, never to write through it.
+  let symlinkForceMsg = "";
+  try {
+    await mintQuiet(["decoy", "--force"]);
+  } catch (e) {
+    symlinkForceMsg = e instanceof Error ? e.message : String(e);
+  }
+  check(
+    "mint --force does NOT write through a symlinked creds path (still refuses, target intact)",
+    /symlink/.test(symlinkForceMsg) && readFileSync(keeperCreds, "utf8") === keeperBefore,
+    { symlinkForceMsg, changed: readFileSync(keeperCreds, "utf8") !== keeperBefore },
+  );
+} finally {
+  process.chdir(prevCwd);
+  rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\nmint-reuse smoke: ${failures === 0 ? "OK ✅" : "FAILED ❌"} (${failures} failing)`);
+assert.equal(failures, 0, `${failures} check(s) failed`);
+process.exit(0);

implementations/cli/src/commands/mint.ts

@@ -1,14 +1,16 @@
-import { existsSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { resolve, join, dirname } from "node:path";
 import { parseArgs } from "node:util";
 import {
   agentFilePath,
+  identityFromCreds,
   loadAgentFile,
   mintCreds,
   mkSecretDir,
   newIdentity,
   stripSpaceAuth,
   writeSecretFile,
+  type Identity,
   type Profile,
 } from "@cotal-ai/core";
 import { authDir, loadSpaceAuth } from "@cotal-ai/workspace";
@@ -28,7 +30,7 @@ export async function mint(argv: string[]): Promise<void> {
       profile: { type: "string" },
       out: { type: "string" },
       signer: { type: "boolean" }, // emit a stripped signer file instead of agent/observer creds
-      force: { type: "boolean" }, // (--signer) overwrite an existing signer file
+      force: { type: "boolean" }, // overwrite an existing --signer file; or (agent) rotate to a fresh id instead of reusing the existing creds'
       "allow-subscribe": { type: "string" }, // read ACL override (comma-separated)
       "allow-publish": { type: "string" }, // post ACL override (comma-separated)
     },
@@ -85,12 +87,72 @@ export async function mint(argv: string[]): Promise<void> {
     allowPublish = splitList(values["allow-publish"]) ?? def?.allowPublish;
     role = def?.role;
   }
-  const identity = newIdentity();
+  // Re-mint reuses the SAME identity by default — but only for the `agent` profile. mint's read/post
+  // ACLs come from the persona file, so re-minting is how an agent's channels get refreshed; and the
+  // mesh id, its durable ACL row, and its dm/dlv durables are all keyed by the nkey public key, so
+  // rotating the id on every mint (the old behavior) orphaned that row + those durables, leaving the
+  // agent @mention-wake-blind until re-provisioned. Observer/admin creds carry no persona-refresh
+  // workflow and no durable footprint to orphan, and silently extending a privileged admin key's
+  // lifetime across re-mints would be surprising — so they always rotate. Reuse only when: agent
+  // profile, a creds file already exists here, and --force did not ask for deliberate rotation
+  // (a compromised key / intentional new identity).
+  const canonicalOut = resolve(join(dir, "creds", `${name}.creds`));
+  const out = resolve(values.out ?? canonicalOut);
+  // A creds file must be a REAL file at its own path. `out === canonicalOut` below is a string compare
+  // (resolve() normalizes the path but does NOT follow symlinks), so it cannot prove the file at the
+  // canonical path belongs to <name>. If creds/<name>.creds is a symlink, existsSync/readFileSync/
+  // writeSecretFile all FOLLOW it — mint would read the link target's id and write <name>'s ACLs back
+  // THROUGH the link, clobbering the pointed-to agent (and --force would rotate a fresh id straight
+  // through it). Refuse a symlinked out path outright — canonical or custom, with or without --force.
+  let outIsSymlink = false;
+  try {
+    outIsSymlink = lstatSync(out).isSymbolicLink(); // lstat does NOT follow the link (unlike existsSync)
+  } catch {
+    // ENOENT: nothing at `out`, not even a dangling link — not a symlink, leave false.
+  }
+  if (outIsSymlink) {
+    throw new Error(
+      `cotal mint: ${out} is a symlink — a creds file must be a real file at its own path, not a link ` +
+        `to another agent's creds (following it would read or overwrite the wrong identity). Remove the ` +
+        `symlink and mint to a real path.`,
+    );
+  }
+  // The canonical `creds/<name>.creds` path is the ONLY binding between an agent name and a creds
+  // file: the file bakes an nkey id, not the name (`identity.ts`), so a creds file at a custom
+  // `--out` cannot be attributed to <name>. A custom `--out` onto an EXISTING creds file must
+  // therefore never be silently reused (re-signing another agent's id with this name's ACLs) nor
+  // overwritten (rotating that id, orphaning its id-keyed ACL row + dm/dlv durables) — fail loud
+  // unless --force asks for the overwrite deliberately. Identity reuse is thus canonical-path-only.
+  if (!values.force && out !== canonicalOut && existsSync(out)) {
+    throw new Error(
+      `cotal mint: --out ${out} already holds a creds file that may not belong to "${name}" — creds ` +
+        `identify an agent by nkey id, not by name, so this file cannot be safely reused or ` +
+        `overwritten for "${name}". Pass --force to overwrite it with a fresh identity, or point ` +
+        `--out at a path that does not exist yet.`,
+    );
+  }
+  const reuse = profile === "agent" && !values.force && out === canonicalOut && existsSync(out);
+  let identity: Identity;
+  if (reuse) {
+    try {
+      identity = identityFromCreds(readFileSync(out, "utf8"));
+    } catch (e) {
+      // A present-but-unreadable creds file (empty, truncated, or not a user creds file) must fail
+      // loud, not silently rotate — silently minting a fresh id here would orphan the durable row
+      // the existing id may still own. Point the operator at the deliberate-rotation escape hatch.
+      throw new Error(
+        `cotal mint: creds already exist at ${out} but could not be parsed to reuse the identity ` +
+          `(${e instanceof Error ? e.message : String(e)}). Pass --force to mint a fresh identity ` +
+          `(rotates the id), or remove the file if it is stale.`,
+      );
+    }
+  } else {
+    identity = newIdentity();
+  }
   const creds = await mintCreds(auth, identity, profile, { allowSubscribe, allowPublish, role });
-  const out = resolve(values.out ?? join(dir, "creds", `${name}.creds`));
   mkSecretDir(dirname(out));
   writeSecretFile(out, creds);
   console.log(c.green(`✓ minted ${profile} creds for "${name}"`));
-  console.log(c.dim(`  id:    ${identity.id}`));
+  console.log(c.dim(`  id:    ${identity.id}${reuse ? " (reused — re-mint kept the identity)" : " (new)"}`));
   console.log(c.dim(`  creds: ${out}`));
 }