@celilo/core 0.9.1 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/core",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Lightweight shared core for Celilo CLI tools — command registry, NDJSON API protocol, and remote SSH client. No Ink/React/drizzle/aws-sdk transitive deps, so an MCP server can reach the transport without installing the full CLI.",
   "type": "module",
   "main": "./src/index.ts",

package/src/command-registry.ts

@@ -1951,7 +1951,19 @@ export const COMMANDS: CommandDef[] = [
             completion: 'module_ids',
           },
         ],
-        flags: [{ name: 'limit', description: 'Number of backups to show', takesValue: true }],
+        flags: [
+          { name: 'limit', description: 'Number of backups to show', takesValue: true },
+          {
+            name: 'json',
+            description: 'Emit exact timestamps as JSON, for the console and other programs',
+            takesValue: false,
+          },
+          {
+            name: 'since',
+            description: 'Only attempts from the last N days',
+            takesValue: true,
+          },
+        ],
       },
       {
         name: 'restore',
@@ -2041,6 +2053,34 @@ export const COMMANDS: CommandDef[] = [
       },
     ],
   },
+  {
+    name: 'console',
+    description: 'Narrow read-only projections for the web console',
+    subcommands: [
+      // The subcommand token decides read/write classification (READ_VERBS in
+      // read-only-classifier.ts), and the console's API principal is granted
+      // read ops only. These are named from that vocabulary rather than for
+      // prose: `console roster` would read better and classify as a WRITE.
+      {
+        name: 'status',
+        description: 'Fleet roster with observed health, systems and backup age (dashboard poll)',
+        flags: [{ name: 'json', description: 'Emit JSON', takesValue: false }],
+      },
+      {
+        name: 'get',
+        description: "A module's bounded capability closure",
+        args: [{ name: 'module-id', description: 'Module to resolve the closure for' }],
+        flags: [
+          {
+            name: 'depth',
+            description: 'Maximum hops to walk (default 2; 0 walks the whole graph)',
+            takesValue: true,
+          },
+          { name: 'json', description: 'Emit JSON', takesValue: false },
+        ],
+      },
+    ],
+  },
   {
     name: 'completion',
     description: 'Generate shell completion scripts',

package/src/index.ts

@@ -1,3 +1,5 @@
 export * from './command-registry';
 export * from './protocol';
 export * from './remote-client';
+export * from './read-only-classifier';
+export * from './ssh-transport';

package/src/read-only-classifier.test.ts

@@ -0,0 +1,108 @@
+/**
+ * The gate that keeps a read-only principal read-only.
+ *
+ * The MCP server's RO key and the web console's API principal are both granted
+ * exactly `readOnlyGrants(COMMANDS)`. If a write op ever appears in that set,
+ * both of them quietly gain the ability to change the fleet, and nothing else in
+ * either codebase would notice: the grant is minted server-side from this list,
+ * and the server would be doing precisely what it was told.
+ *
+ * So this asserts the negative directly against the live registry.
+ */
+import { describe, expect, test } from 'bun:test';
+import { COMMANDS, type CommandDef } from './command-registry';
+import { isReadOnlyPath, opOf, readOnlyGrants } from './read-only-classifier';
+
+/** Every op the registry can run, read and write alike. */
+function allOps(commands: CommandDef[], prefix: string[] = []): string[] {
+  return commands.flatMap((cmd) => {
+    const path = [...prefix, cmd.name];
+    return cmd.subcommands?.length ? allOps(cmd.subcommands, path) : [opOf(path)];
+  });
+}
+
+/**
+ * Ops that are unambiguously mutating, written out by hand.
+ *
+ * Hand-maintained ON PURPOSE, and the one place in this file where that is
+ * right. The first version of this gate derived "the writes" from
+ * `isReadOnlyPath` and then asserted the grant set excluded them, which is the
+ * classifier agreeing with itself: mark `remove` as a read verb and both sides
+ * move together, so the test stays green while the console gains the ability to
+ * remove modules. Verified by doing exactly that (Rule 7.6). An assertion has to
+ * know something the code under test does not.
+ */
+const MUST_NEVER_BE_GRANTED = [
+  'module:deploy',
+  'module:remove',
+  'module:pause',
+  'module:unpause',
+  'module:import',
+  'module:update',
+  'module:config',
+  'module:secret',
+  'system:init',
+  'system:update',
+  'system:secret',
+  'machine:add',
+  'machine:remove',
+  'service:remove',
+  'backup:restore',
+  'api:grant',
+  'api:revoke',
+];
+
+describe('readOnlyGrants', () => {
+  test('grants none of the ops that change the fleet', () => {
+    const granted = new Set(readOnlyGrants(COMMANDS));
+    const leaked = MUST_NEVER_BE_GRANTED.filter((op) => granted.has(op));
+    expect(leaked).toEqual([]);
+  });
+
+  test('the list above names ops the registry actually has', () => {
+    // Otherwise the gate decays into asserting things about commands that no
+    // longer exist, which passes forever and checks nothing.
+    const real = new Set(allOps(COMMANDS));
+    const stale = MUST_NEVER_BE_GRANTED.filter((op) => !real.has(op));
+    expect(stale).toEqual([]);
+  });
+
+  test('a mutating verb added to the registry is NOT granted', () => {
+    // Rule 7.6: watch the gate work rather than trusting that it would. This is
+    // the registry shape a future command would introduce.
+    const withWrite: CommandDef[] = [
+      {
+        name: 'module',
+        description: 'module operations',
+        subcommands: [
+          { name: 'list', description: 'list modules' },
+          { name: 'obliterate', description: 'a new and very mutating verb' },
+        ],
+      } as CommandDef,
+    ];
+
+    const granted = readOnlyGrants(withWrite);
+    expect(granted).toContain('module:list');
+    expect(granted).not.toContain('module:obliterate');
+  });
+
+  test('a read verb added to the registry IS granted, with no list to edit', () => {
+    const withRead: CommandDef[] = [
+      {
+        name: 'console',
+        description: 'console reads',
+        subcommands: [{ name: 'status', description: 'a newly added read verb' }],
+      } as CommandDef,
+    ];
+
+    expect(readOnlyGrants(withRead)).toContain('console:status');
+  });
+
+  test('a mixed-verb op is classified as a write', () => {
+    // `module config` covers get AND set. Its token is `config`, which is not a
+    // read verb, so the whole op is a write. Collapsing it would hand a
+    // read-only principal the ability to set configuration.
+    expect(isReadOnlyPath(['module', 'config'])).toBe(false);
+    expect(readOnlyGrants(COMMANDS)).not.toContain('module:config');
+  });
+});

package/src/read-only-classifier.ts

@@ -0,0 +1,96 @@
+/**
+ * Which command-registry leaves are reads, and the authz ops a read-only
+ * principal therefore needs.
+ *
+ * This lives in `@celilo/core`, beside `COMMANDS`, because it is a property of
+ * the command registry rather than of any one consumer. Two now derive from it:
+ * the MCP server routes each tool to its RO or RW principal, and the web console
+ * enrols a principal granted exactly the read ops.
+ *
+ * That shared derivation is the point. A hand-maintained grant list goes stale
+ * in the dangerous direction: a newly added read verb is merely missing, while a
+ * newly added WRITE verb silently lands inside a principal that was supposed to
+ * be read-only. Deriving from the registry means a new read verb is covered
+ * automatically and a new write verb is not.
+ */
+
+import type { ArgDef, CommandDef, FlagDef } from './command-registry';
+
+/** A runnable leaf command flattened from the registry tree. */
+export interface Leaf {
+  /** Full path from a top-level command, e.g. `['module', 'list']`. */
+  path: string[];
+  description: string;
+  args: ArgDef[];
+  flags: FlagDef[];
+}
+
+/**
+ * Read-only verbs. The server's authz is 2-level (`command:subcommand`), so the
+ * read/write split is too: a leaf is read-only iff its *op token* — the
+ * subcommand (or, for a top-level leaf, the command) — is a read verb. This
+ * guarantees a read tool's op is exactly what the RO principal is granted, and
+ * never routes a mutating op onto the RO key. A mixed op like `module:config`
+ * (get + set) has a non-read token (`config`) → classified write → RW.
+ */
+export const READ_VERBS: ReadonlySet<string> = new Set([
+  'list',
+  'status',
+  'where',
+  'get',
+  // Reads a deployed module's daemon journal. Read-only by construction —
+  // the only remote command it can emit is `journalctl` (services/module-journal.ts).
+  'journal',
+  'audit',
+  'commands', // the MCP's own registry fetch rides the RO key
+]);
+
+/** The 2-level authz op a leaf runs as — `command:subcommand`, or bare command. */
+export function opOf(path: string[]): string {
+  return path.length >= 2 ? `${path[0]}:${path[1]}` : path[0];
+}
+
+/** Token that decides read vs write: the subcommand, or the bare command. */
+function opToken(path: string[]): string {
+  return path.length >= 2 ? path[1] : path[0];
+}
+
+/** Is this leaf read-only (→ RO principal)? See `READ_VERBS`. */
+export function isReadOnlyPath(path: string[]): boolean {
+  return READ_VERBS.has(opToken(path));
+}
+
+/** Flatten the registry tree into its runnable leaves (nodes with no subcommands). */
+export function flattenLeaves(commands: CommandDef[], prefix: string[] = []): Leaf[] {
+  const leaves: Leaf[] = [];
+  for (const cmd of commands) {
+    const path = [...prefix, cmd.name];
+    if (cmd.subcommands && cmd.subcommands.length > 0) {
+      leaves.push(...flattenLeaves(cmd.subcommands, path));
+    } else {
+      leaves.push({
+        path,
+        description: cmd.description,
+        args: cmd.args ?? [],
+        flags: cmd.flags ?? [],
+      });
+    }
+  }
+  return leaves;
+}
+
+/**
+ * Every authz op a read-only principal needs, derived from a command registry.
+ *
+ * Sorted and de-duplicated so the result is stable enough to compare in a test
+ * and to print in a grant line.
+ */
+export function readOnlyGrants(commands: CommandDef[]): string[] {
+  return [
+    ...new Set(
+      flattenLeaves(commands)
+        .filter((l) => isReadOnlyPath(l.path))
+        .map((l) => opOf(l.path)),
+    ),
+  ].sort();
+}

package/src/ssh-transport.ts

@@ -0,0 +1,111 @@
+/**
+ * Reaching a celilo management server over SSH.
+ *
+ * Lives here rather than in any one client because every client needs the same
+ * two things and one of them is load-bearing safety. The MCP server and the web
+ * console server both drive `celilo-api@<server>`, both select a principal by
+ * key, and both are long-running processes that get restarted freely.
+ *
+ * That last fact is why this is shared rather than copied: Node does not kill
+ * spawned children when it exits, so every restart used to orphan whatever ssh
+ * clients were in flight. 656 of them accumulated on one machine and threw
+ * celilo-mgr into MaxStartups throttling, which is an SSH lockout of the control
+ * plane (celilo#921). A second copy of this code is a second chance to
+ * reintroduce that, and the console server has exactly the same lifecycle.
+ */
+
+import { type ChildProcess, spawn } from 'node:child_process';
+import { Readable } from 'node:stream';
+import type { RemoteTransport } from './remote-client';
+
+/**
+ * Adapt a Node child process to the core `RemoteTransport` (web-stream) shape —
+ * plain `node:child_process`, no Bun runtime dependency, so published packages
+ * run on Node. Shared by the ssh transport (production) and by tests that spawn
+ * a local `api-serve`, so both exercise the same adapter.
+ */
+export function childProcessTransport(proc: ChildProcess): RemoteTransport {
+  if (!proc.stdout || !proc.stdin)
+    throw new Error('child process was not spawned with piped stdio');
+  return {
+    stdin: { write: (chunk: string) => void proc.stdin?.write(chunk) },
+    stdout: Readable.toWeb(proc.stdout) as unknown as ReadableStream<Uint8Array>,
+    kill: () => void proc.kill(),
+    exited: new Promise<number>((resolve) => proc.once('exit', (code) => resolve(code ?? 0))),
+  };
+}
+
+/**
+ * ssh args to select a principal by key with no connection sharing.
+ *
+ * -T: no pty (raw NDJSON pipe). -i: force the principal's key. -o
+ * IdentitiesOnly=yes so a loaded agent key can't shadow the one we mean.
+ * ControlMaster=no + ControlPath=none: the RO and RW principals share one dest
+ * (celilo-api@<server>) and differ only by key, so an operator ssh config that
+ * multiplexes (Host * ControlMaster auto — %C hashes user+host, not the key)
+ * would collapse both onto whichever master connected first (RO), silently
+ * running every write as RO -> denied (126). Refusing to use or create a shared
+ * master keeps the principals isolated regardless of the operator's ssh config.
+ * (ce-h86)
+ */
+export function sshArgs(identityFile: string, dest: string): string[] {
+  return [
+    '-T',
+    '-o',
+    'IdentitiesOnly=yes',
+    '-o',
+    'ControlMaster=no',
+    '-o',
+    'ControlPath=none',
+    '-i',
+    identityFile,
+    dest,
+  ];
+}
+
+/**
+ * ssh children this process has open, so exiting doesn't abandon them (celilo#921).
+ *
+ * Node does not kill spawned children when it exits, and these servers are
+ * restarted freely. Every restart therefore orphaned whatever ssh clients were
+ * in flight: they reparent to init, keep their sockets ESTABLISHED, and keep an
+ * `api-serve` resident on the far end. 656 of them accumulated on one machine
+ * and threw celilo-mgr into MaxStartups throttling, an SSH lockout of the
+ * control plane.
+ */
+const liveSshChildren = new Set<ChildProcess>();
+let reaperInstalled = false;
+
+function reapOnExit(proc: ChildProcess): ChildProcess {
+  liveSshChildren.add(proc);
+  proc.once('exit', () => liveSshChildren.delete(proc));
+  if (!reaperInstalled) {
+    reaperInstalled = true;
+    const killAll = () => {
+      for (const child of liveSshChildren) child.kill();
+    };
+    process.once('exit', killAll);
+    // Installing a signal handler suppresses node's default termination, so
+    // these have to exit for us — reaping and then staying alive would be a
+    // worse leak than the one we are fixing.
+    for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+      process.once(signal, () => {
+        killAll();
+        process.exit(128 + (signal === 'SIGINT' ? 2 : 15));
+      });
+    }
+  }
+  return proc;
+}
+
+/** Build a `runRemoteClient` transport factory that selects a principal by key. */
+export function sshTransportWith(identityFile: string): (dest: string) => RemoteTransport {
+  return (dest: string) =>
+    childProcessTransport(
+      reapOnExit(
+        spawn('ssh', sshArgs(identityFile, dest), {
+          stdio: ['pipe', 'pipe', 'inherit'],
+        }),
+      ),
+    );
+}