jochen
4295aad88e
Awaited at import, a bucket not yet on the bus — or a grant the bus had not reloaded — answered after the runtime's 10s handshake, and the module was left unserved on its first assignment. Also cites module state as ADR 0201, as hq main numbers it (folds #256).
272 lines
13 KiB
TypeScript
272 lines
13 KiB
TypeScript
// What claude-code does on a node, written against two things it is handed — a way to ask a tool on the
|
|
// bus and a way to emit an event — so every path is tested without a bus (novox/hq design 36 §4–§5,
|
|
// ADR 0183, ADR 0198).
|
|
//
|
|
// **Over NATS, in two kinds** (design 32 §10): an event says that something happened and carries no
|
|
// secret, because a stream keeps it; a token travels on a request, which nothing keeps. So:
|
|
// - the licence manager's `licence.rotated` and `licence.switched` events tell this module to ask the
|
|
// seat for its current token, sealed to the key it sends with the request;
|
|
// - a login a person made here — a refresh token this module never writes — is offered to the seat at
|
|
// once, sealed to the seat's key: the one moment a refresh token travels, because the login made the
|
|
// manager's stale;
|
|
// - an MCP server registered through this module is **state, not an event** (novox/hq ADR 0201): one
|
|
// key per server in the module's `servers` bucket — `all.<server>` for every node, `<node>.<server>`
|
|
// for one — which every node watches. A node that joins later, or was off, reads the whole current set
|
|
// at start; unregistering is a delete. A secret never goes in an entry: the runtime refuses one.
|
|
|
|
import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
import { join } from "node:path";
|
|
|
|
import { render, entryProblem, MANAGED_DIR, type Binding, type Facts, type Settings, type Servers } from "./render.js";
|
|
import { generateKeyPair, open, seal, type SealedBox } from "./seal.js";
|
|
import { decideApply, grantOf, holdsLogin, readCredentials, replacedBy, withGrant, writeCredentials, type Grant } from "./grant.js";
|
|
import { readIdentity, writeIdentity, type Identity } from "./identity.js";
|
|
|
|
export const SEAT = "anthropic-licence-manager";
|
|
|
|
export interface Paths {
|
|
state: string;
|
|
facts: string;
|
|
settings: string;
|
|
home: string;
|
|
node: string;
|
|
}
|
|
|
|
/** A tool on the bus: its address and arguments in, its JSON answer out. */
|
|
export type Ask = (address: string, args: Record<string, unknown>) => Promise<unknown>;
|
|
/** An event of this module's, by its local name. */
|
|
export type Emit = (type: string, body: unknown) => Promise<void>;
|
|
/** Write one managed file; answers what happened. */
|
|
export type WriteManaged = (name: string, content: string) => string;
|
|
|
|
export 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 accountPath = (p: Paths) => join(p.home, ".claude.json");
|
|
const bindingPath = (p: Paths) => join(p.state, "licence.json");
|
|
const apiKeyPath = (p: Paths) => join(p.state, "api-key");
|
|
export 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 registryPath = (p: Paths) => join(p.state, "mcp-servers.json");
|
|
|
|
export 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") };
|
|
}
|
|
|
|
export function registered(p: Paths): Servers {
|
|
return readJson<Servers>(registryPath(p), {});
|
|
}
|
|
|
|
export function renderNow(p: Paths, write: WriteManaged): 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 files = render(facts, readJson<Settings>(p.settings, {}), readJson<Binding | null>(bindingPath(p), null),
|
|
helperPath(p), registered(p));
|
|
return Object.entries(files).map(([name, content]) => write(name, content));
|
|
}
|
|
|
|
// ---- the licence ----------------------------------------------------------------------------------
|
|
|
|
/** What the seat answers to `current`: the licence this node is bound to and its token, sealed. */
|
|
export interface Current {
|
|
licence: string;
|
|
kind: "subscription" | "api-key";
|
|
sealed: SealedBox;
|
|
identity?: Identity | null;
|
|
}
|
|
|
|
/** Ask the seat for this node's current token and apply it. */
|
|
export async function pull(p: Paths, ask: Ask, write: WriteManaged): Promise<Record<string, unknown>> {
|
|
const answer = (await ask(`${SEAT}.current`, { node: p.node, public_key: keypair(p).publicKey })) as Current | null;
|
|
if (!answer?.sealed) return { applied: false, reason: "the seat holds no licence for this node" };
|
|
return apply(p, answer, write);
|
|
}
|
|
|
|
/** Apply what the seat handed over. A switch replaces the grant whole and cleans up after the old licence. */
|
|
export function apply(p: Paths, handed: Current, write: WriteManaged): Record<string, unknown> {
|
|
const plain = open(handed.sealed, keypair(p).privateKey);
|
|
const previous = readJson<Binding | null>(bindingPath(p), null);
|
|
const switched = previous?.licence !== handed.licence;
|
|
let outcome: Record<string, unknown> = { applied: true, licence: handed.licence, kind: handed.kind, switched };
|
|
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, switched ? "switch" : "rotation");
|
|
if (d.apply) writeCredentials(credentialsPath(p), switched ? replacedBy(local, grant) : withGrant(local, grant));
|
|
else outcome = { applied: false, licence: handed.licence, reason: "reason" in d ? d.reason : undefined }; // narrowed by hand: the build compiles without strict
|
|
// Away from the API key: it goes, with its helper.
|
|
rmSync(apiKeyPath(p), { force: true });
|
|
rmSync(helperPath(p), { force: true });
|
|
}
|
|
if (switched && handed.identity?.accountUuid) {
|
|
outcome.account = writeIdentity(accountPath(p), handed.identity) ? "updated" : "unchanged";
|
|
}
|
|
writeFileSync(bindingPath(p), JSON.stringify({ licence: handed.licence, kind: handed.kind }) + "\n", { mode: 0o600 });
|
|
try {
|
|
outcome.rendered = renderNow(p, write); // the key-helper comes or goes with the licence's kind
|
|
} catch (err) {
|
|
outcome.rendered = { failed: err instanceof Error ? err.message : String(err) };
|
|
}
|
|
return outcome;
|
|
}
|
|
|
|
/** A licence event from the manager: is it for this node? */
|
|
export function concerns(p: Paths, type: string, body: { licence?: string; node?: string }): boolean {
|
|
if (type.endsWith("licence.switched")) return body.node === p.node;
|
|
if (type.endsWith("licence.rotated")) return body.licence === readJson<Binding | null>(bindingPath(p), null)?.licence;
|
|
return false;
|
|
}
|
|
|
|
/** A refresh token in the credentials file is a login: this module never writes one. Offer it to the seat. */
|
|
export async function offerLogin(p: Paths, ask: Ask): Promise<Record<string, unknown> | null> {
|
|
const creds = readCredentials(credentialsPath(p));
|
|
if (!holdsLogin(creds)) return null;
|
|
const key = (await ask(`${SEAT}.public_key`, {})) as { public_key?: string } | null;
|
|
if (!key?.public_key) throw new Error("the licence manager did not say what key to seal a login to");
|
|
return (await ask(`${SEAT}.adopt`, {
|
|
node: p.node,
|
|
identity: readIdentity(accountPath(p)),
|
|
sealed: seal(JSON.stringify(creds!.claudeAiOauth), key.public_key),
|
|
})) as Record<string, unknown>;
|
|
}
|
|
|
|
// ---- MCP servers ----------------------------------------------------------------------------------
|
|
|
|
export interface Registration {
|
|
name: string;
|
|
entry?: Record<string, unknown>;
|
|
/** Which nodes: this one (absent), every node running the module ("all"), or a list. */
|
|
nodes?: "all" | string[];
|
|
}
|
|
|
|
/** The `servers` state, as this module reaches it through the runtime (`state("servers")` in the SDK). */
|
|
export interface ServerState {
|
|
put(key: string, value: Record<string, unknown>): Promise<number>;
|
|
delete(key: string): Promise<void>;
|
|
keys(): Promise<string[]>;
|
|
}
|
|
|
|
/** One change to the `servers` state, as a watch hands it over. */
|
|
export interface ServerChange {
|
|
key: string;
|
|
op: "put" | "delete";
|
|
value?: Record<string, unknown>;
|
|
}
|
|
|
|
/** The key a registration lives at: `all.<server>` for every node, `<node>.<server>` for one. */
|
|
export const keyOf = (scope: string, name: string) => `${scope}.${name}`;
|
|
|
|
/**
|
|
* What this node takes from the `servers` state: the entries for every node and for this one, by key —
|
|
* kept in memory from the watch, and written through to the module's own file whenever what applies here
|
|
* changes, so the managed directory can be rendered without the bus.
|
|
*/
|
|
export class ServerView {
|
|
private readonly entries = new Map<string, Record<string, unknown>>();
|
|
constructor(private readonly p: Paths) {}
|
|
|
|
/** Take one change; answers whether what applies to this node changed. */
|
|
take(c: ServerChange): boolean {
|
|
const dot = c.key.indexOf(".");
|
|
const scope = c.key.slice(0, dot), name = c.key.slice(dot + 1);
|
|
if (dot <= 0 || (scope !== "all" && scope !== this.p.node)) return false;
|
|
if (c.op === "put" && c.value && entryProblem(name, c.value) === null) this.entries.set(c.key, c.value);
|
|
else this.entries.delete(c.key);
|
|
return this.writeThrough();
|
|
}
|
|
|
|
/** What applies here: every node's entries, with this node's own laid over them by server name. */
|
|
effective(): Servers {
|
|
const out: Record<string, Record<string, unknown>> = {};
|
|
for (const scope of ["all", this.p.node]) {
|
|
for (const [key, entry] of [...this.entries].sort(([a], [b]) => a.localeCompare(b))) {
|
|
if (key.startsWith(scope + ".")) out[key.slice(scope.length + 1)] = entry;
|
|
}
|
|
}
|
|
return out;
|
|
}
|
|
|
|
private writeThrough(): boolean {
|
|
const now = JSON.stringify(this.effective(), null, 2) + "\n";
|
|
let before = "";
|
|
try {
|
|
before = readFileSync(registryPath(this.p), "utf8");
|
|
} catch {
|
|
/* none yet */
|
|
}
|
|
if (now === before) return false;
|
|
writeFileSync(registryPath(this.p), now, { mode: 0o600 });
|
|
return true;
|
|
}
|
|
}
|
|
|
|
/** A change from the watch: take it, and render when what applies here changed. */
|
|
export function onServerChange(view: ServerView, c: ServerChange, p: Paths, write: WriteManaged): string | null {
|
|
if (!view.take(c)) return null;
|
|
renderNow(p, write);
|
|
return `${c.op === "put" ? "registered" : "unregistered"} ${c.key}`;
|
|
}
|
|
|
|
const scopesOf = (p: Paths, nodes: Registration["nodes"]): string[] =>
|
|
nodes === undefined ? [p.node] : nodes === "all" ? ["all"] : nodes;
|
|
|
|
/**
|
|
* Register (or with no entry, unregister) a server: a put (or delete) per scope in the `servers` state.
|
|
* Taken into this node's view at once, so the answer says what it did here; every other node takes it
|
|
* from its watch, and a node that joins later from the current state.
|
|
*/
|
|
export async function registerServer(p: Paths, r: Registration, servers: ServerState, view: ServerView,
|
|
write: WriteManaged, others: () => Promise<string[]>): Promise<Record<string, unknown>> {
|
|
if (r.entry) {
|
|
const problem = entryProblem(r.name, r.entry);
|
|
if (problem) return { registered: false, reason: problem };
|
|
}
|
|
const scopes = scopesOf(p, r.nodes);
|
|
// Compared before and after rather than read from take(): this node's own watch may hand the view the
|
|
// same change first, and then take() here finds nothing new although this call made it.
|
|
const before = JSON.stringify(view.effective());
|
|
for (const scope of scopes) {
|
|
const key = keyOf(scope, r.name);
|
|
if (r.entry) await servers.put(key, r.entry);
|
|
else await servers.delete(key);
|
|
view.take({ key, op: r.entry ? "put" : "delete", value: r.entry });
|
|
}
|
|
const changedHere = JSON.stringify(view.effective()) !== before;
|
|
const here = scopes.includes("all") || scopes.includes(p.node);
|
|
const answer: Record<string, unknown> = {
|
|
[r.entry ? "registered" : "unregistered"]: r.name,
|
|
on: r.nodes === undefined ? [p.node] : r.nodes,
|
|
here: here ? (changedHere ? "changed" : "already so") : "not this node",
|
|
rendered: changedHere ? renderNow(p, write) : [],
|
|
};
|
|
if (!r.entry && view.effective()[r.name]) {
|
|
answer.still = `${r.name} still applies here from another registration (for every node, or for this one); unregister that too`;
|
|
}
|
|
if (r.nodes === undefined) {
|
|
// The question the operator wanted asked: here only, or more?
|
|
const elsewhere = (await others().catch(() => [] as string[])).filter((n) => n !== p.node);
|
|
answer.also = elsewhere.length
|
|
? `claude-code also runs on ${elsewhere.join(", ")}. To ${r.entry ? "register" : "unregister"} it there too, call again with nodes: "all" or a list of those nodes.`
|
|
: `To do the same on every node running claude-code, call again with nodes: "all".`;
|
|
}
|
|
return answer;
|
|
}
|
|
|
|
export { MANAGED_DIR };
|