agent-coord-mcp 0.26.32 → 0.26.34

package/src/seat-identity.ts

@@ -0,0 +1,125 @@
+// ⟨q-0c5476ec⟩ — A SEAT'S IDENTITY IS STATED ONCE, AND THE TWO HALVES CANNOT DISAGREE SILENTLY.
+//
+// A seat's identity was typed twice: as an agent id at launch, and as a bearer inside a config.
+// Every HTTP identity failure so far is that duplication. Measured on the other machine: a seat
+// launched WITHOUT `--strict-mcp-config` took the GLOBAL config's bearer and came back as whoever
+// owned it — three times in two days on three seats, with no in-session recovery; and a config
+// holding a token `tokens.json` had since rotated returned a bare 401, with nothing in the config
+// saying it was stale.
+//
+// So the launcher derives BOTH halves from one statement (the agent id), and refuses before start
+// when a config on disk disagrees, NAMING WHICH HALF disagreed. Refusing at launch is the point: a
+// 401 later is the same fault read as a broken daemon.
+//
+// ⛔ NO SECRET IN ANY MESSAGE. Not the token, not a prefix, not a hash: a refusal a human pastes
+// into a bus message must not carry the bearer. The messages name AGENTS and FILES, never bytes.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+/** Must match store.ts ROOT/TOKENS_FILE resolution exactly, or we read a file the bus never wrote. */
+export function coordRoot({ dir, env = process.env }: { dir?: string; env?: NodeJS.ProcessEnv } = {}): string {
+  return dir ?? env.AGENT_COORD_DIR ?? env.CLAUDE_COORD_DIR ?? path.join(homedir(), "agent-coord");
+}
+export const tokensFile = (opts?: { dir?: string; env?: NodeJS.ProcessEnv }) => path.join(coordRoot(opts), "tokens.json");
+
+/** `{ "agent-id": "token" }`, or `{}` when absent. Throws on malformed, never on missing. */
+export function loadTokens(file: string): Record<string, string> {
+  if (!existsSync(file)) return {};
+  const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${file} must be a JSON object of { "agent-id": "token" }`);
+  }
+  return parsed as Record<string, string>;
+}
+
+/**
+ * Write a project-local `.mcp.json` (⟨q-8c23e5a3⟩ acceptance (a)) whose `agent-coord` entry embeds
+ * this seat's own token — never a shared default, so a project that gets its OWN config never
+ * depends on (or silently becomes) a global fallback. mode 600, same as tokens.json.
+ * `pane` is recorded under `_agentCoordPane`, a key no MCP client reads or writes: it exists so a
+ * re-run, or `coord-seat`, can recover the pane a config was minted for without re-asking.
+ */
+export function writeMcpConfig({ dir, agentId, server, token, pane }: { dir: string; agentId: string; server: string; token: string; pane?: string | null }): string {
+  mkdirSync(dir, { recursive: true });
+  const configPath = path.join(dir, ".mcp.json");
+  let existing: Record<string, any> = {};
+  if (existsSync(configPath)) {
+    try {
+      existing = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch (e) {
+      throw new Error(`${configPath} exists and is not valid JSON (${(e as Error).message}) — refusing to overwrite blindly`);
+    }
+  }
+  const config: Record<string, any> = {
+    ...existing,
+    mcpServers: {
+      ...(existing.mcpServers ?? {}),
+      "agent-coord": {
+        type: "http",
+        url: server,
+        headers: { Authorization: `Bearer ${token}` },
+        ...(pane ? { _agentCoordPane: pane } : {}),
+      },
+    },
+  };
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(configPath, 0o600);
+  return configPath;
+}
+
+/** The agent-coord entry a config states, or null when there is no config / no such entry. */
+export type ConfigIdentity = { token: string | null; url: string | null; pane: string | null };
+export function readConfigIdentity(configPath: string): ConfigIdentity | null {
+  if (!existsSync(configPath)) return null;
+  let parsed: any;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch (e) {
+    throw new Error(`${configPath} is not valid JSON (${(e as Error).message}) — refusing to read an identity out of it`);
+  }
+  const entry = parsed?.mcpServers?.["agent-coord"];
+  if (!entry) return null;
+  const auth = String(entry.headers?.Authorization ?? "");
+  const m = /^Bearer\s+(.+)$/.exec(auth);
+  return { token: m ? m[1].trim() : null, url: entry.url ?? null, pane: entry._agentCoordPane ?? null };
+}
+
+/**
+ * Does the config on disk state the same seat the launch claims?
+ *
+ * Returns null when they agree (or when there is no config to disagree — the launcher writes one
+ * from the single statement). Otherwise `{ half, message }`, where `half` names the side that is
+ * wrong relative to `tokens.json`, which is the bus's own map and therefore the authority.
+ */
+export type IdentityProblem = { half: "config" | "tokens"; message: string };
+export function identityProblem({ agentId, configPath, config, tokens, tokensPath }: { agentId: string; configPath: string; config: { token?: string | null } | null; tokens: Record<string, string>; tokensPath: string }): IdentityProblem | null {
+  const expected = tokens?.[agentId];
+  if (!config) return null;
+  if (!config.token) {
+    return {
+      half: "config",
+      message:
+        `${configPath} has an agent-coord entry with no bearer, so it states no identity, while the launch claims '${agentId}'. ` +
+        `Delete it and relaunch through coord-seat, which writes both halves from the one statement.`,
+    };
+  }
+  if (!expected) {
+    return {
+      half: "tokens",
+      message:
+        `${tokensPath} holds no token for '${agentId}', so the launch identity cannot be honoured, while ${configPath} carries a bearer. ` +
+        `Mint one with \`coord-token add ${agentId}\` (it rotates if one exists) and relaunch, or launch the agent whose token that config holds.`,
+    };
+  }
+  if (config.token === expected) return null;
+  const ownerOfConfigToken = Object.keys(tokens).find((a) => tokens[a] === config.token);
+  return {
+    half: "config",
+    message: ownerOfConfigToken
+      ? `${configPath} carries the bearer of '${ownerOfConfigToken}', but the launch claims '${agentId}' — the two halves of this seat's identity disagree. ` +
+        `Launch '${ownerOfConfigToken}', or let coord-seat rewrite the config for '${agentId}'.`
+      : `${configPath} carries a bearer that ${tokensPath} does not know — it was rotated or revoked since the config was written, while the launch claims '${agentId}'. ` +
+        `Relaunch through coord-seat, which rewrites the config from the token '${agentId}' has now.`,
+  };
+}

package/src/server.ts

@@ -18,6 +18,8 @@ import { capabilitiesSchema, capabilitiesTool } from "./capabilities.js";
 import {
   ensureDirs,
   getTokenMap,
+  agentForBearer,
+  tokenMapCensusLine,
   TOKENS_FILE,
   reloadTokenMapSync,
   refreshTokenMapIfChanged,
@@ -264,7 +266,8 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
   async function guardFirstClaim(claimed: string, args: Record<string, unknown>): Promise<string> {
     const token = typeof args["token"] === "string" ? (args["token"] as string) : undefined;
     if (token !== undefined) {
-      if (getTokenMap()?.get(token) === claimed) return "token";
+      // ⟨q-4b9cdeab⟩ through agentForBearer, which hashes: the map holds hashes, never the secret.
+      if (agentForBearer(token) === claimed) return "token";
       throw new Error(
         `token presented for '${claimed}' does not match tokens.json (or no token map is loaded). ` +
           `Mint one with scripts/coord-token.mjs add ${claimed} (then SIGHUP the bus), or pass force:true if you are certain.`,
@@ -844,6 +847,10 @@ function loadTokenMap(initial: boolean): void {
   }
   if (!initial) {
     console.error(`[agent-coord-mcp] SIGHUP: token map reloaded (${getTokenMap()?.size ?? 0} agents)`);
+    // ⟨q-4b9cdeab⟩ say how many entries are still plaintext, so the migration is visible without
+    // anyone reading the file — and without this line ever naming a bearer, a prefix or a hash.
+    const hupCensus = tokenMapCensusLine();
+    if (hupCensus) console.error(hupCensus);
   }
 }
 
@@ -1096,6 +1103,8 @@ async function startHttp(port: number): Promise<void> {
   function reportTokenRefresh(r: TokenMapRefresh): void {
     if (r.changed) {
       console.error(`[agent-coord-mcp] token map reloaded (${r.count} agents) — ${TOKENS_FILE} ${r.reason}`);
+      const census = tokenMapCensusLine();
+      if (census) console.error(census);
       return;
     }
     if (r.refused) {
@@ -1117,12 +1126,12 @@ async function startHttp(port: number): Promise<void> {
     reportTokenRefresh(refreshTokenMapIfChanged());
     const tokenMap = getTokenMap();
     if (tokenMap) {
-      let agent = tokenMap.get(bearer);
+      let agent = agentForBearer(bearer);
       if (!agent) {
         // An unknown bearer is exactly the symptom of a token minted since the last check, so it
         // forces one check past the rate limit. It cannot grant anything the file does not hold.
         reportTokenRefresh(refreshTokenMapIfChanged({ force: true }));
-        agent = getTokenMap()?.get(bearer);
+        agent = agentForBearer(bearer);
       }
       // ⛔ THE ONLY PLACE A PRE-BOUND SEAT CAN GET A TAIL. The `startTailOnBind` sites in the tool
       // path all sit behind `bound === undefined` — the TOFU claim. Here identity arrives already
@@ -1205,6 +1214,10 @@ async function startHttp(port: number): Promise<void> {
   };
 
   const mode = bound ? `pre-bound (${getTokenMap()?.size ?? 0} agents)` : "TOFU";
+  {
+    const startupCensus = tokenMapCensusLine();
+    if (startupCensus) console.error(startupCensus);
+  }
   await Promise.all(
     bindAddrs.map(
       (addr) =>

package/src/store.ts

@@ -153,10 +153,86 @@ export function ensureDirs(): void {
   }
 }
 
-// Synchronous, deliberate. The result feeds the server's bearer→agent
-// reverse-lookup map; we want startup to fail loudly on a malformed file
-// rather than silently degrade to advisory mode. Returns null if the file
-// is absent (operator hasn't configured binding yet).
+// ⟨q-4b9cdeab⟩ RELEASE A — THE READER ACCEPTS BOTH FORMS AND WRITES NEITHER.
+//
+// `tokens.json` holds every seat's bearer in the clear, so one readable file is the whole fleet's
+// identity. The fix is that the file stores a HASH while the seat's config keeps the secret. Because
+// 13 live HTTP seats depend on this file's shape, the migration is two-form first (David's ruling,
+// 2026-09-23, docs/notes/Q_4B9CDEAB_HASHED_TOKENS_PLAN.md): this release READS both forms and writes
+// NEITHER. No migration command, no hashed file written, no cutover. `coord-token` keeps minting
+// plaintext.
+//
+//   v1 (today):  { "alice": "tk_<secret>" }
+//   v2 (hashed): { "alice": { "alg": "sha256", "hash": "<hex>", "createdAt": "…", "previous": {…} } }
+//
+// The two are told apart by the VALUE TYPE, so an untouched file keeps working with no version field.
+//
+// ⭐ ONE LOOKUP PATH FOR BOTH FORMS: a v1 entry is HASHED AT LOAD, so the in-process map is always
+// hash → agentId and `agentForBearer` hashes whatever is presented. There is no second comparison to
+// drift, and no branch where a plaintext file authenticates differently from a hashed one.
+//
+// ⛔ AN ENTRY THIS BUILD CANNOT EVALUATE REFUSES THE WHOLE FILE, BY NAME. An unknown `alg` is never
+// ignored (which would silently drop a seat) and never treated as plaintext (which would compare a
+// bearer against a hash and lock that seat out while looking fine). Same for a missing or malformed
+// hash. The refusal names the AGENT and the ALG — never any part of a bearer, and never the hash.
+//
+// ⚠ `previous` (the rotation grace window) is NOT honoured in release A: it is written by nothing in
+// this release, so accepting it would be accepting a shape no tool here produces. A bearer that
+// matches only `previous` does not authenticate, and that is asserted rather than left implicit.
+//
+// Synchronous, deliberate: startup fails loudly on a malformed file rather than silently degrading
+// to advisory mode. Returns null if the file is absent (binding not configured).
+/** The hash algorithms this build can evaluate. An entry naming anything else refuses the file. */
+export const TOKEN_HASH_ALGS = Object.freeze(["sha256"] as const);
+const HEX64 = /^[0-9a-f]{64}$/;
+/**
+ * ⛔ sha256 OF THE EMPTY STRING. v1 refused an empty token STRUCTURALLY (`value.length === 0`); the
+ * hashed form has no such shape, because this hex is as well-formed as any other. It is the exact
+ * artefact of an ordinary shell slip during the hand migration this release exists for —
+ * `printf '%s' "$TOK" | shasum -a 256` with `$TOK` unset or mistyped writes precisely this — and an
+ * entry holding it authenticates an `Authorization: Bearer ` header with nothing after it.
+ */
+const EMPTY_BEARER_HASH = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+
+/** sha256 hex of a bearer. Unsalted on purpose: a bearer is 24 CSPRNG bytes, so there is no
+ * dictionary to run, and a per-entry salt would force a linear scan of every entry on every
+ * request. See §2 of the plan for the condition that would make that choice wrong. */
+export function bearerHash(bearer: string): string {
+  return createHash("sha256").update(bearer, "utf8").digest("hex");
+}
+
+/** How many entries of each form the loaded map came from — what the census line reports. */
+export type TokenMapCensus = { total: number; hashed: number; plaintext: number };
+let tokenMapCensus: TokenMapCensus = { total: 0, hashed: 0, plaintext: 0 };
+export function getTokenMapCensus(): TokenMapCensus {
+  return { ...tokenMapCensus };
+}
+
+function refuse(detail: string): never {
+  throw new Error(`[agent-coord-mcp] ${TOKENS_FILE}: ${detail}`);
+}
+
+/**
+ * Insert a hash → agentId claim, REFUSING a hash two agents both claim.
+ *
+ * ⛔ LAST-WINS WOULD RE-ATTRIBUTE A LIVE BEARER. Under v1 a collision meant two identical plaintext
+ * strings, visible to anyone reading the file. With one side hashed it is invisible on inspection —
+ * a property this release removed, so the reader has to put it back. The invariant this keeps is
+ * `map.size === census.total`: every entry claims its own key or the file is refused.
+ */
+function claim(out: Map<string, string>, hash: string, agentId: string): void {
+  const held = out.get(hash);
+  if (held !== undefined) {
+    refuse(
+      `agents "${held}" and "${agentId}" both resolve to the SAME token hash. One bearer cannot ` +
+        `authenticate two identities: whichever entry loaded last would silently take the other's ` +
+        `traffic, and with one side hashed the clash is invisible in the file. Give each agent its own token.`,
+    );
+  }
+  out.set(hash, agentId);
+}
+
+/** Read the file into a hash → agentId map, accepting v1 and v2 entries. NEVER writes. */
 export function readTokenMapSync(): Map<string, string> | null {
   if (!existsSync(TOKENS_FILE)) return null;
   const raw = readFileSync(TOKENS_FILE, "utf8");
@@ -171,21 +247,89 @@ export function readTokenMapSync(): Map<string, string> | null {
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error(
-      `[agent-coord-mcp] ${TOKENS_FILE} must be a JSON object mapping agentId → token.`,
+      `[agent-coord-mcp] ${TOKENS_FILE} must be a JSON object mapping agentId → token or hashed entry.`,
     );
   }
   const out = new Map<string, string>();
-  for (const [agentId, token] of Object.entries(parsed as Record<string, unknown>)) {
-    if (typeof token !== "string" || token.length === 0) {
-      throw new Error(
-        `[agent-coord-mcp] ${TOKENS_FILE}: agent "${agentId}" has a non-string/empty token.`,
+  const census: TokenMapCensus = { total: 0, hashed: 0, plaintext: 0 };
+  for (const [agentId, value] of Object.entries(parsed as Record<string, unknown>)) {
+    census.total += 1;
+    if (typeof value === "string") {
+      // v1: the secret itself is on disk. Hash it here so the map has ONE shape.
+      if (value.length === 0) refuse(`agent "${agentId}" has a non-string/empty token.`);
+      claim(out, bearerHash(value), agentId);
+      census.plaintext += 1;
+      continue;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      refuse(`agent "${agentId}" has a non-string/empty token.`);
+    }
+    const entry = value as { alg?: unknown; hash?: unknown };
+    const alg = entry.alg;
+    if (typeof alg !== "string" || !(TOKEN_HASH_ALGS as readonly string[]).includes(alg)) {
+      refuse(
+        `agent "${agentId}" uses hash alg ${JSON.stringify(alg ?? null)}, which this build cannot evaluate ` +
+          `(known: ${TOKEN_HASH_ALGS.join(", ")}). Refusing the whole file: ignoring the entry would drop that ` +
+          `seat silently, and treating it as a plaintext token would compare a bearer against a hash and lock ` +
+          `the seat out while every file on disk looked correct.`,
       );
     }
-    out.set(token, agentId);
+    if (typeof entry.hash !== "string" || !HEX64.test(entry.hash)) {
+      refuse(`agent "${agentId}" has a ${alg} entry whose hash is not 64 lowercase hex characters.`);
+    }
+    if (entry.hash === EMPTY_BEARER_HASH) {
+      refuse(
+        `agent "${agentId}" has a ${alg} entry whose hash is sha256 of the EMPTY STRING. An empty ` +
+          `Authorization bearer would authenticate as that agent. The plaintext form refused an empty ` +
+          `token by its shape; this hex is well-formed, so it is refused by name instead. It is what ` +
+          `hashing an unset or mistyped shell variable produces — re-hash the real token.`,
+      );
+    }
+    claim(out, entry.hash, agentId);
+    census.hashed += 1;
   }
+  tokenMapCensus = census;
   return out;
 }
 
+/** The agent a presented bearer belongs to, or undefined. The ONE place a bearer is compared. */
+export function agentForBearer(bearer: string): string | undefined {
+  // ⚠ NO SEPARATE EMPTY-BEARER GUARD HERE, DELIBERATELY. An empty `Authorization: Bearer ` slices to
+  // "" and hashes to sha256(""), and the reader REFUSES any entry carrying that hash — so the map can
+  // never hold the only key an empty bearer could match. A guard here would therefore be unkillable
+  // by any test: I added one, the mutation matrix showed removing it changed nothing, and a conjunct
+  // no test can fire belongs in a comment rather than in the code. The enforcement point is the
+  // reader's refusal, and it is tested.
+  //
+  // ⛔ WHAT THAT DELETION COSTS, NAMED BECAUSE NOTHING ASSERTS IT: the guarantee is no longer local to
+  // this function. It holds only while `readTokenMapSync` is the map's ONLY PRODUCER — true today at
+  // all three assignments to `tokenMapCache` (the lazy first load, `reloadTokenMapSync`, and the
+  // refresh, which reads through `readTokenMapSync`). TWO changes void it, and BOTH are silent because
+  // the guard that would have caught them was deleted for being unfireable:
+  //   1. LOOSENING THE REFUSAL — if an entry carrying sha256("") stops being refused;
+  //   2. ⛔ A SECOND PRODUCER — anything that populates or mutates the map outside `readTokenMapSync`.
+  //      This is the one release B actually SCHEDULES: `coord-token migrate` writes hashed entries, and
+  //      a migrate path that seeds or patches the in-process map rather than re-reading the file
+  //      reintroduces the empty-bearer key with nothing between it and the auth path.
+  // Either one is where the guard goes back — with a test that can fail. If you are here writing
+  // `coord-token migrate`, this paragraph is addressed to you.
+  return getTokenMap()?.get(bearerHash(bearer));
+}
+
+/** One line an operator can act on. Says nothing about any bearer, prefix or hash. */
+export function tokenMapCensusLine(): string | null {
+  const map = getTokenMap();
+  if (!map) return null;
+  const c = getTokenMapCensus();
+  const tail =
+    c.total === 0
+      ? " — no entries: every bearer will be refused"
+      : c.plaintext > 0
+        ? ` — ${c.plaintext} still plaintext, run coord-token migrate`
+        : " — all hashed";
+  return `[agent-coord-mcp] token map: ${c.total} entries (${c.hashed} hashed, ${c.plaintext} plaintext)${tail}`;
+}
+
 // In-process cache of the token map, shared by the HTTP identity-binding
 // layer (server.ts) and rotateAgentToken below. A module-level cache (rather
 // than each caller re-reading the file) is what lets a rename refresh the