novox/mesh-catalog
6
0
Fork 0
Code Issues Pull Requests 3 Packages Projects Releases Wiki Activity

claude-code over NATS: licence events, a token by request, a login pushed to the manager, MCP servers registered per node or mesh-wide

Browse Source 
Events carry what happened and no secret; tokens travel on requests (design 32 §10). The manager's
licence.rotated/switched events make the module ask anthropic-licence-manager.current; at start it
asks once to catch up. A refresh token appearing in the credentials file is a login: it is pushed to
the manager's adopt at once, sealed to the manager's key — the one time a refresh token travels. A
switch replaces the old licence's grant whole, removes the API key and its helper, and rewrites
oauthAccount in ~/.claude.json. New tools register and unregister MCP servers on this node, or with
nodes: all / a list via an mcp.registered event every node consumes; called for one node, the
answer names the other nodes running claude-code. 26 tests.
This commit is contained in:
jochen
2026-10-04 02:23:23 +02:00
parent 03e729d103
commit 6a7e4ebd5e
10 changed files with 548 additions and 167 deletions
Download Patch File Download Diff File Expand all files Collapse all files
modules/claude-code/tools/index.ts
+119 -155
View File
@@ -1,142 +1,77 @@
// claude-code's tools (novox/hq design 36, ADR 0183). A bundle the node's runtime launches and speaks MCP
// to over stdio (ADR 0193), as the operator account; it is given its state directory and two files the
// mesh renders into it (ADR 0192), and the runtime's own words — the operator's account and home among
// them. **stdout is the MCP channel**: everything this module says, it says on stderr.
// claude-code's bundle (novox/hq design 36, ADR 0183). The node's runtime launches it over stdio, as the
// operator account (ADR 0193), and is its bus (ADR 0198): it asks tools, emits and consumes through the
// runtime. It is given its state directory and two files the mesh renders into it (ADR 0192), beside the
// runtime's own words. **stdout is the MCP channel**: everything this module says, it says on stderr.
//
// Every time the runtime collects these tools, the managed directory is rendered: written only when its
// content changed, through the account's escalation, because /etc is root's. The credentials file under
// the home is written only when the licence manager hands this node a token (`claude_code_apply`); this
// module calls nothing, the manager starts every exchange (ADR 0183's dated note).
// At start it renders the agent's managed directory, asks the licence manager for this node's token,
// begins watching the credentials file for a login, and takes the module's events: the manager's
// licence events and every node's MCP server registrations. node.ts holds the logic.
import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
import { createHash } from "node:crypto";
import { readFileSync, watchFile } from "node:fs";
import { spawnSync } from "node:child_process";
import { join } from "node:path";
import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
import { broker } from "@novox/mesh-sdk/messaging";
import { emit, on } from "@novox/mesh-sdk/events";
import { MANAGED_DIR, render, type Binding, type Facts, type Settings } from "../render.js";
import { generateKeyPair, open, seal, type SealedBox } from "../seal.js";
import { decideApply, grantOf, holdsLogin, readCredentials, withGrant, writeCredentials, type Grant } from "../grant.js";
import { readIdentity } from "../identity.js";
import {
MANAGED_DIR, SEAT, concerns, keypair, offerLogin, onServerEvent, pull, readJson, registerServer,
registered, renderNow, type Ask, type Paths, type Registration, type WriteManaged,
} from "../node.js";
import { grantOf, holdsLogin, readCredentials } from "../grant.js";
import { createHash } from "node:crypto";
interface Paths {
state: string;
facts: string;
settings: string;
home: string;
account: string;
}
function pathsFrom(env: NodeJS.ProcessEnv): Paths | null {
const state = env.MESH_CLAUDE_CODE_STATE;
const facts = env.MESH_CLAUDE_CODE_FACTS;
const settings = env.MESH_CLAUDE_CODE_SETTINGS;
const home = env.MESH_OPERATOR_HOME;
if (!state || !facts || !settings || !home) return null;
return { state, facts, settings, home, account: env.MESH_OPERATOR_ACCOUNT ?? "" };
}
const readJson = <T>(p: string, fallback: T): T => {
try {
return JSON.parse(readFileSync(p, "utf8")) as T;
} catch {
return fallback;
}
};
const credentialsPath = (p: Paths) => join(p.home, ".claude", ".credentials.json");
const identityPath = (p: Paths) => join(p.home, ".claude.json");
const bindingPath = (p: Paths) => join(p.state, "binding.json");
const apiKeyPath = (p: Paths) => join(p.state, "api-key");
const helperPath = (p: Paths) => join(p.state, "api-key-helper");
const keyPath = (p: Paths) => join(p.state, "key.pem");
const pubPath = (p: Paths) => join(p.state, "key.pub.pem");
const say = (line: string) => console.error(`[claude-code] ${line}`);
const fingerprint = (s: string) => "sha256:" + createHash("sha256").update(s).digest("hex").slice(0, 16);
function keypair(p: Paths): { publicKey: string; privateKey: string } {
if (!existsSync(keyPath(p))) {
const k = generateKeyPair();
writeFileSync(keyPath(p), k.privateKey, { mode: 0o600 });
writeFileSync(pubPath(p), k.publicKey, { mode: 0o644 });
}
return { privateKey: readFileSync(keyPath(p), "utf8"), publicKey: readFileSync(pubPath(p), "utf8") };
function pathsFrom(env: NodeJS.ProcessEnv): Paths | null {
const state = env.MESH_CLAUDE_CODE_STATE, facts = env.MESH_CLAUDE_CODE_FACTS;
const settings = env.MESH_CLAUDE_CODE_SETTINGS, home = env.MESH_OPERATOR_HOME, node = env.MESH_NODE;
if (!state || !facts || !settings || !home || !node) return null;
return { state, facts, settings, home, node };
}
/** Write one managed file as root when its content changed. Returns what happened, in words. */
function writeManaged(name: string, content: string, asRoot: boolean): string {
/** Write one managed file as root, only when its content changed. */
const writeManaged: WriteManaged = (name, content) => {
const path = join(MANAGED_DIR, name);
let current: string | null = null;
try {
current = readFileSync(path, "utf8");
if (readFileSync(path, "utf8") === content) return `${name}: unchanged`;
} catch {
/* absent */
}
if (current === content) return `${name}: unchanged`;
const asRoot = process.getuid?.() === 0;
const cmd = asRoot ? ["install", "-D", "-m", "0644", "/dev/stdin", path] : ["sudo", "-n", "install", "-D", "-m", "0644", "/dev/stdin", path];
const r = spawnSync(cmd[0], cmd.slice(1), { input: content, encoding: "utf8" });
if (r.status !== 0) {
throw new Error(
`${name}: could not be written to ${MANAGED_DIR} (${(r.stderr || r.error?.message || "").trim()}). ` +
`The module writes there through the operator account's passwordless sudo; this machine does not give it.`,
);
throw new Error(`${name}: could not be written to ${MANAGED_DIR} (${(r.stderr || r.error?.message || "").trim()}); ` +
`the module writes there through the operator account's passwordless sudo`);
}
return `${name}: written`;
}
};
function renderNow(p: Paths): string[] {
const facts = readJson<Facts | null>(p.facts, null);
if (!facts?.console) throw new Error(`the mesh has not rendered ${p.facts} yet; nothing to write`);
const settings = readJson<Settings>(p.settings, {});
const binding = readJson<Binding | null>(bindingPath(p), null);
const files = render(facts, settings, binding, helperPath(p));
const asRoot = process.getuid?.() === 0;
return Object.entries(files).map(([name, content]) => writeManaged(name, content, asRoot));
}
interface Handed {
licence: string;
kind: "subscription" | "api-key";
source: "rotation" | "switch";
sealed: SealedBox;
}
function apply(p: Paths, args: Record<string, unknown>): Record<string, unknown> {
const handed = args as unknown as Handed;
if (!handed?.licence || !handed.sealed || (handed.kind !== "subscription" && handed.kind !== "api-key")) {
return { applied: false, reason: "a hand-over names a licence, its kind and a sealed token" };
}
const plain = open(handed.sealed, keypair(p).privateKey);
const previous = readJson<Binding | null>(bindingPath(p), null);
const source = previous?.licence === handed.licence ? (handed.source ?? "rotation") : "switch";
if (handed.kind === "api-key") {
writeFileSync(apiKeyPath(p), plain.trim() + "\n", { mode: 0o600 });
writeFileSync(helperPath(p), `#!/bin/sh\nexec cat '${apiKeyPath(p)}'\n`, { mode: 0o700 });
chmodSync(helperPath(p), 0o700);
} else {
const grant = JSON.parse(plain) as Grant;
const local = readCredentials(credentialsPath(p));
const d = decideApply(grantOf(local), grant, source);
if (!d.apply) {
writeFileSync(bindingPath(p), JSON.stringify({ licence: handed.licence, kind: handed.kind }) + "\n", { mode: 0o600 });
return { applied: false, licence: handed.licence, reason: d.reason };
}
writeCredentials(credentialsPath(p), withGrant(local, grant));
}
writeFileSync(bindingPath(p), JSON.stringify({ licence: handed.licence, kind: handed.kind }) + "\n", { mode: 0o600 });
// An API-key binding adds the key-helper to the managed settings; a subscription takes it away. The
// licence is applied whatever the render says; a render that fails is reported beside it, not instead.
let rendered: string[] | { failed: string };
/** A tool on the bus, through the runtime; its MCP answer read back as JSON where it is JSON. */
const ask: Ask = async (address, args) => {
const answer = (await broker().request<Record<string, unknown>, { content?: { text?: string }[]; isError?: boolean }>(address, args)) ?? {};
const text = answer.content?.map((c) => c.text ?? "").join("") ?? "";
if (answer.isError) throw new Error(`${address}: ${text}`);
try {
rendered = renderNow(p);
} catch (err) {
rendered = { failed: err instanceof Error ? err.message : String(err) };
return JSON.parse(text);
} catch {
return text;
}
return { applied: true, licence: handed.licence, kind: handed.kind, source, rendered };
};
/** The nodes claude-code runs on, from the controller's list of modules — for the register tool's question. */
async function nodesRunningMe(): Promise<string[]> {
const out = await ask("mesh-controller.modules", {});
const text = typeof out === "string" ? out : String((out as { output?: string })?.output ?? "");
const line = text.split("\n").find((l) => /^claude-code\s/.test(l)) ?? "";
const on = line.split(" on ")[1] ?? "";
return on.trim() === "nothing" ? [] : on.split(",").map((s) => s.trim()).filter(Boolean);
}
function status(p: Paths): Record<string, unknown> {
const binding = readJson<Binding | null>(bindingPath(p), null);
const creds = readCredentials(credentialsPath(p));
const creds = readCredentials(join(p.home, ".claude", ".credentials.json"));
const grant = grantOf(creds);
const managed = ["managed-mcp.json", "managed-settings.json", "CLAUDE.md"].map((f) => {
try {
@@ -146,67 +81,68 @@ function status(p: Paths): Record<string, unknown> {
}
});
return {
node: readJson<Facts | null>(p.facts, null)?.node ?? null,
licence: binding,
token: grant
? { fingerprint: fingerprint(grant.accessToken), expiresAt: new Date(grant.expiresAt).toISOString(), refreshTokenOnDisk: holdsLogin(creds) }
: null,
node: p.node,
licence: readJson(join(p.state, "licence.json"), null),
token: grant ? { fingerprint: fingerprint(grant.accessToken), expiresAt: new Date(grant.expiresAt).toISOString(),
loginWaiting: holdsLogin(creds) } : null,
managed,
publicKey: existsSync(pubPath(p)) ? fingerprint(readFileSync(pubPath(p), "utf8")) : null,
registered: Object.keys(registered(p)),
};
}
function pendingLogin(p: Paths, args: Record<string, unknown>): Record<string, unknown> {
const managerKey = typeof args.public_key === "string" ? args.public_key : "";
if (!managerKey) return { waiting: false, reason: "the caller names the public key to seal a login to" };
const creds = readCredentials(credentialsPath(p));
if (!holdsLogin(creds)) return { waiting: false };
const identity = readIdentity(identityPath(p));
return { waiting: true, identity, sealed: seal(JSON.stringify(creds!.claudeAiOauth), managerKey) };
}
export function getClaudeCodeTools(p: Paths): ToolDefinition[] {
function tools(p: Paths): ToolDefinition[] {
const nodesArg = { type: "string", description: 'more nodes: "all" for every node running claude-code, or a comma-separated list; absent is this node only' };
const nodesOf = (v: unknown): Registration["nodes"] =>
v === undefined || v === "" ? undefined : v === "all" ? "all" : String(v).split(",").map((s) => s.trim()).filter(Boolean);
return [
{
name: "claude_code_status",
description:
"This machine's agent as the mesh configured it: the node, the licence it holds and when its token expires, " +
"and the managed files it rendered. Fingerprints only — never a token.",
description: "Claude Code on this machine as the mesh configured it: the licence it holds and when its token expires, the managed files, the MCP servers registered here. Fingerprints only, never a token.",
input: {},
run: async () => status(p),
},
{
name: "claude_code_render",
description: "Write the agent's managed directory now from the mesh's facts and this module's settings; says which files changed.",
description: "Write Claude Code's managed directory now, from the mesh's facts, this module's settings and the servers registered here.",
input: {},
run: async () => ({ rendered: renderNow(p) }),
run: async () => ({ rendered: renderNow(p, writeManaged) }),
},
{
name: "claude_code_public_key",
description: "The public half of this node's key, which the licence manager seals a token to.",
name: "claude_code_pull",
description: "Ask the licence manager for this node's current token now and apply it, rather than waiting for its next event.",
input: {},
run: async () => ({ public_key: keypair(p).publicKey }),
run: async () => pull(p, ask, writeManaged),
},
{
name: "claude_code_apply",
description:
"The licence manager's hand-over: a token sealed to this node's key, with its licence and kind. Applied by the " +
"lineage rule; the answer says applied or refused and why, never the token.",
name: "claude_code_mcp_list",
description: "The MCP servers registered on this node through this module, beside the console (`mesh`) and those set in the module's settings.",
input: {},
run: async () => ({ registered: registered(p) }),
},
{
name: "claude_code_mcp_register",
description: "Register an MCP server with Claude Code on this node — an http/sse server by url, or a stdio server by command — and say which other nodes run claude-code, so it can be registered there too.",
input: {
licence: { type: "string", description: "the licence's name" },
kind: { type: "string", description: "subscription or api-key" },
source: { type: "string", description: "rotation or switch" },
sealed: { type: "object", description: "the sealed box" },
name: { type: "string", description: "the server's name: letters, digits, - and _" },
type: { type: "string", description: "http, sse or stdio (default stdio when a command is given, http when a url is)" },
url: { type: "string", description: "an http or sse server's url" },
command: { type: "string", description: "a stdio server's program" },
args: { type: "array", description: "a stdio server's arguments" },
env: { type: "object", description: "a stdio server's environment" },
headers: { type: "object", description: "an http server's headers" },
nodes: nodesArg,
},
run: async (a) => {
const entry: Record<string, unknown> = { type: a.type ?? (a.url ? "http" : "stdio") };
for (const k of ["url", "command", "args", "env", "headers"]) if (a[k] !== undefined) entry[k] = a[k];
return registerServer(p, { name: String(a.name ?? ""), entry, nodes: nodesOf(a.nodes) }, emit, writeManaged, nodesRunningMe);
},
run: async (args) => apply(p, args),
},
{
name: "claude_code_pending_login",
description:
"A login a person made on this machine, waiting to be adopted: the grant sealed to the key the caller gives, and " +
"the account it belongs to. Nothing when no login is waiting.",
input: { public_key: { type: "string", description: "the caller's public key, PEM" } },
run: async (args) => pendingLogin(p, args),
name: "claude_code_mcp_unregister",
description: "Remove an MCP server registered through this module, on this node or more.",
input: { name: { type: "string", description: "the server's name" }, nodes: nodesArg },
run: async (a) => registerServer(p, { name: String(a.name ?? ""), nodes: nodesOf(a.nodes) }, emit, writeManaged, nodesRunningMe),
},
];
}
@@ -216,10 +152,38 @@ registerModuleTools("claude-code", (env) => {
if (!p) return [];
try {
keypair(p);
for (const line of renderNow(p)) if (!line.endsWith("unchanged")) console.error(`[claude-code] ${line}`);
for (const line of renderNow(p, writeManaged)) if (!line.endsWith("unchanged")) say(line);
} catch (err) {
// Said, and the tools still served: claude_code_status and claude_code_render say what is wrong.
console.error(`[claude-code] ${err instanceof Error ? err.message : String(err)}`);
say(err instanceof Error ? err.message : String(err));
}
return getClaudeCodeTools(p);
return tools(p);
});
// Launched by the runtime: the bus is there from the first line (ADR 0198). Outside it — a test, a
// build — nothing below runs.
const p = process.env.MESH_SERVED_MODULE ? pathsFrom(process.env) : null;
if (p) {
const loud = (what: string) => (err: unknown) => say(`${what}: ${err instanceof Error ? err.message : String(err)}`);
void on<{ licence?: string; node?: string }>("claude-licence-manager.licence.*", async (event) => {
if (!concerns(p, event.type, event.body ?? {})) return;
say(`${event.type} — asking ${SEAT} for this node's token`);
say(JSON.stringify(await pull(p, ask, writeManaged).catch((e) => ({ failed: String(e) }))));
}).catch(loud("the licence events"));
void on<Registration>("claude-code.mcp.*", async (event) => {
const done = onServerEvent(p, event.type, event.body, writeManaged);
if (done) say(done);
}).catch(loud("the MCP server events"));
// Catch up once at start: a node that was off takes its current token now.
void pull(p, ask, writeManaged).then((r) => say(`at start: ${JSON.stringify(r)}`), loud("asking for this node's token at start"));
// A login: a refresh token appears in the credentials file. Polled, because the file is replaced by
// rename and a watch on the old inode would go quiet.
const credentials = join(p.home, ".claude", ".credentials.json");
watchFile(credentials, { interval: 5000 }, () => {
void offerLogin(p, ask).then((r) => { if (r) say(`a login here was offered to ${SEAT}: ${JSON.stringify(r)}`); },
loud("offering a login to the licence manager"));
});
}