@celilo/cli 0.10.0 → 0.11.0

package/src/api/serve.ts

@@ -0,0 +1,159 @@
+/**
+ * Remote API server — `celilo api-serve --principal=<id>` (Slices 1–3).
+ *
+ * Invoked as the sshd forced command for an enrolled key, so it starts already
+ * authenticated as `principal`. Reads `command`/`answer` messages as NDJSON on
+ * stdin/stdout, authorizes each command against the principal's grants
+ * (deny-by-default), and — if allowed — runs it as a child `celilo` process,
+ * translating the child's protocol-mode output into `progress`/`log` and a
+ * terminal `result`. While a command runs, a remote responder bridges the event
+ * bus to the wire so mid-run `interview`s are answered by the client. Every
+ * attempt is audited to stderr.
+ */
+
+import { createInterface } from 'node:readline';
+import { parseArguments } from '../cli/parser';
+import { getEventBusPath } from '../config/paths';
+import { isAuthorized } from '../services/api-access';
+import { type WireInterview, startRemoteResponder } from '../services/remote-responder';
+import {
+  API_PROTOCOL_VERSION,
+  ClientMessageSchema,
+  type ServerMessage,
+  translateOutputLine,
+} from './protocol';
+
+/** Exit code returned to the client when authz denies a command. */
+const EXIT_PERMISSION_DENIED = 126;
+
+function send(msg: ServerMessage): void {
+  process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+
+function audit(principal: string, op: string, decision: string, exitCode?: number): void {
+  const suffix = exitCode === undefined ? '' : ` exit=${exitCode}`;
+  process.stderr.write(
+    `[api-audit] principal=${principal} op=${op} decision=${decision}${suffix}\n`,
+  );
+}
+
+/** Derive the `command`/`subcommand` an argv would run, via the real parser. */
+function opOf(argv: string[]): { command: string; subcommand?: string; label: string } {
+  const parsed = parseArguments(['bun', 'celilo', ...argv]);
+  const label = parsed.subcommand ? `${parsed.command}:${parsed.subcommand}` : parsed.command;
+  return { command: parsed.command, subcommand: parsed.subcommand, label };
+}
+
+/** Drain a child stream line-by-line, forwarding each line as a message. */
+async function pumpLines(stream: ReadableStream<Uint8Array>): Promise<void> {
+  const decoder = new TextDecoder();
+  let buffer = '';
+  for await (const chunk of stream) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let nl = buffer.indexOf('\n');
+    while (nl >= 0) {
+      const line = buffer.slice(0, nl);
+      buffer = buffer.slice(nl + 1);
+      send(translateOutputLine(line));
+      nl = buffer.indexOf('\n');
+    }
+  }
+  if (buffer.length > 0) {
+    send(translateOutputLine(buffer));
+  }
+}
+
+/** Run an authorized command as a child; returns its exit code. */
+async function runCommand(argv: string[]): Promise<number> {
+  // Re-invoke this same CLI as a child. The child is non-TTY (piped stdout) so
+  // ProgressDisplay resolves to protocol mode and emits `[progress:*]` markers.
+  const child = Bun.spawn([process.execPath, Bun.main, ...argv], {
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  await Promise.all([pumpLines(child.stdout), pumpLines(child.stderr)]);
+  const exitCode = await child.exited;
+  send({ type: 'result', success: exitCode === 0, exitCode });
+  return exitCode;
+}
+
+async function handleCommand(
+  principal: string,
+  argv: string[],
+  busDbPath: string,
+  ask: (interview: WireInterview) => Promise<unknown>,
+): Promise<void> {
+  const { command, subcommand, label } = opOf(argv);
+
+  if (!(await isAuthorized(principal, command, subcommand))) {
+    send({ type: 'error', error: `permission denied: "${principal}" is not granted "${label}"` });
+    send({ type: 'result', success: false, exitCode: EXIT_PERMISSION_DENIED });
+    audit(principal, label, 'deny');
+    return;
+  }
+
+  // Bridge the bus to the wire so mid-run interviews reach the client.
+  const responder = startRemoteResponder({ busDbPath, ask, emittedBy: `api:${principal}` });
+  try {
+    const exitCode = await runCommand(argv);
+    audit(principal, label, 'allow', exitCode);
+  } finally {
+    responder.close();
+  }
+}
+
+export async function apiServeMode(principal: string): Promise<void> {
+  send({ type: 'ready', protocolVersion: API_PROTOCOL_VERSION });
+
+  const busDbPath = getEventBusPath();
+  const pendingAnswers = new Map<string, (value: unknown) => void>();
+
+  const ask = (interview: WireInterview): Promise<unknown> =>
+    new Promise((resolve) => {
+      pendingAnswers.set(interview.id, resolve);
+      send({
+        type: 'interview',
+        id: interview.id,
+        kind: interview.kind,
+        message: interview.message,
+        description: interview.description,
+        defaultValue: interview.defaultValue,
+        placeholder: interview.placeholder,
+        options: interview.options,
+        required: interview.required,
+      });
+    });
+
+  const rl = createInterface({ input: process.stdin, terminal: false });
+
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+
+    let msg: ReturnType<typeof ClientMessageSchema.parse>;
+    try {
+      msg = ClientMessageSchema.parse(JSON.parse(line));
+    } catch (error) {
+      send({ type: 'error', error: error instanceof Error ? error.message : String(error) });
+      continue;
+    }
+
+    if (msg.type === 'answer') {
+      const resolve = pendingAnswers.get(msg.id);
+      if (resolve) {
+        pendingAnswers.delete(msg.id);
+        resolve(msg.value);
+      }
+      continue;
+    }
+
+    if (msg.type === 'command') {
+      // Fire-and-forget so the read loop keeps consuming `answer` messages while
+      // the command runs — mid-run interviews are answered in-flight.
+      void handleCommand(principal, msg.argv, busDbPath, ask);
+    }
+  }
+
+  process.exit(0);
+}

package/src/cli/command-registry.ts

@@ -92,6 +92,51 @@ export const COMMANDS: CommandDef[] = [
       },
     ],
   },
+  {
+    name: 'api',
+    description: 'Manage remote-API access (principals, grants, authorized_keys)',
+    subcommands: [
+      {
+        name: 'grant',
+        description: 'Grant or replace API access for a principal',
+        args: [{ name: 'principal', description: 'Principal name (kebab-case)' }],
+        flags: [
+          {
+            name: 'key',
+            description: 'SSH public key, or path to a .pub file',
+            takesValue: true,
+            valueHint: '_files',
+          },
+          {
+            name: 'can',
+            description: 'Comma-separated grants (e.g. module:deploy,service:*)',
+            takesValue: true,
+          },
+        ],
+      },
+      { name: 'list', description: 'List API principals and their grants' },
+      {
+        name: 'revoke',
+        description: 'Revoke API access for a principal',
+        args: [{ name: 'principal', description: 'Principal name' }],
+      },
+      {
+        name: 'authorized-keys',
+        description: "Print the API account's authorized_keys (forced-command lines)",
+      },
+      {
+        name: 'key',
+        description: 'Client-side key management',
+        subcommands: [
+          {
+            name: 'new',
+            description: 'Generate a new API keypair and print enrollment steps',
+            args: [{ name: 'name', description: 'Principal name for the key' }],
+          },
+        ],
+      },
+    ],
+  },
   {
     name: 'events',
     description: 'SQLite event-bus operations (status, tail, run dispatcher, etc.)',

package/src/cli/commands/api.ts

@@ -0,0 +1,194 @@
+/**
+ * `celilo api ...` — manage remote-API principals (Slice 2a).
+ *
+ * grant / list / revoke operate on the api_principals table; authorized-keys
+ * renders the forced-command file for the API account. See v2/API_COMMUNICATION.md.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import {
+  grantPrincipal,
+  listPrincipals,
+  renderAuthorizedKeys,
+  revokePrincipal,
+  validatePrincipalName,
+} from '../../services/api-access';
+import { celiloIntro } from '../prompts';
+import type { CommandResult } from '../types';
+
+function errMsg(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** `celilo api grant <principal> --key <pubkey|path> --can <grant[,grant...]>` */
+export async function handleApiGrant(
+  args: string[],
+  flags: Record<string, boolean | string> = {},
+): Promise<CommandResult> {
+  try {
+    const name = args[0];
+    if (!name) {
+      return {
+        success: false,
+        error: 'Usage: celilo api grant <principal> --key <pubkey|path> --can <grant[,grant...]>',
+      };
+    }
+
+    const keyArg = typeof flags.key === 'string' ? flags.key : '';
+    if (!keyArg) {
+      return {
+        success: false,
+        error: '--key <public-key-or-path> is required (e.g. ~/.ssh/id_ed25519.pub)',
+      };
+    }
+
+    const canArg = typeof flags.can === 'string' ? flags.can : '';
+    if (!canArg) {
+      return {
+        success: false,
+        error: '--can <grant[,grant...]> is required (e.g. --can module:deploy,service:*)',
+      };
+    }
+
+    const publicKey = existsSync(keyArg) ? readFileSync(keyArg, 'utf8').trim() : keyArg.trim();
+    const grants = canArg
+      .split(',')
+      .map((g) => g.trim())
+      .filter(Boolean);
+
+    const { principal, created } = await grantPrincipal({ name, publicKey, grants });
+
+    return {
+      success: true,
+      message: `${created ? 'Granted' : 'Updated'} API access for "${principal.name}" → ${grants.join(', ')}\n\nInstall the forced-command line on celilo-mgr with:\n  celilo api authorized-keys >> ~celilo-api/.ssh/authorized_keys`,
+    };
+  } catch (error) {
+    return { success: false, error: `Failed to grant API access: ${errMsg(error)}` };
+  }
+}
+
+/** `celilo api list` */
+export async function handleApiList(): Promise<CommandResult> {
+  try {
+    celiloIntro('API Principals');
+    const principals = await listPrincipals();
+
+    if (principals.length === 0) {
+      console.log('No API principals.\n');
+      console.log('Grant access:');
+      console.log('  celilo api grant <name> --key ~/.ssh/id_ed25519.pub --can module:deploy');
+      return { success: true, message: 'No API principals found' };
+    }
+
+    console.log('');
+    for (const p of principals) {
+      const parts = p.publicKey.split(/\s+/);
+      const keyType = parts[0] ?? '';
+      const comment = parts.length > 2 ? parts.slice(2).join(' ') : '';
+      console.log(`${p.name}`);
+      console.log(`  Grants: ${p.grants.join(', ') || '(none)'}`);
+      console.log(`  Key:    ${keyType}${comment ? ` (${comment})` : ''}`);
+      console.log('');
+    }
+
+    console.log(`Total: ${principals.length} principal${principals.length === 1 ? '' : 's'}\n`);
+    return { success: true, message: `Found ${principals.length} principal(s)` };
+  } catch (error) {
+    return { success: false, error: `Failed to list API principals: ${errMsg(error)}` };
+  }
+}
+
+/** `celilo api revoke <principal>` */
+export async function handleApiRevoke(args: string[]): Promise<CommandResult> {
+  try {
+    const name = args[0];
+    if (!name) {
+      return { success: false, error: 'Usage: celilo api revoke <principal>' };
+    }
+
+    const removed = await revokePrincipal(name);
+    if (!removed) {
+      return { success: false, error: `No API principal named "${name}".` };
+    }
+
+    return {
+      success: true,
+      message: `Revoked API access for "${name}".\n\nRe-render celilo-mgr's authorized_keys to drop the line:\n  celilo api authorized-keys > ~celilo-api/.ssh/authorized_keys`,
+    };
+  } catch (error) {
+    return { success: false, error: `Failed to revoke API access: ${errMsg(error)}` };
+  }
+}
+
+/** `celilo api authorized-keys` — print the forced-command file for the API account. */
+export async function handleApiAuthorizedKeys(): Promise<CommandResult> {
+  try {
+    const content = await renderAuthorizedKeys();
+    return { success: true, message: content, rawOutput: true };
+  } catch (error) {
+    return { success: false, error: `Failed to render authorized_keys: ${errMsg(error)}` };
+  }
+}
+
+/** `celilo api key new <name>` — generate a client-side keypair for API access. */
+export async function handleApiKeyNew(args: string[]): Promise<CommandResult> {
+  try {
+    const name = args[0];
+    if (!name) {
+      return { success: false, error: 'Usage: celilo api key new <name>' };
+    }
+    validatePrincipalName(name);
+
+    // Prefer $HOME (operator shell always sets it, and it's test-controllable);
+    // homedir() is the fallback for the rare unset case.
+    const keyPath = join(process.env.HOME || homedir(), '.ssh', `celilo-api-${name}`);
+    if (existsSync(keyPath) || existsSync(`${keyPath}.pub`)) {
+      return {
+        success: false,
+        error: `A key already exists at ${keyPath}. Remove it or choose another name.`,
+      };
+    }
+
+    mkdirSync(dirname(keyPath), { recursive: true, mode: 0o700 });
+
+    const gen = Bun.spawnSync([
+      'ssh-keygen',
+      '-t',
+      'ed25519',
+      '-N',
+      '',
+      '-C',
+      `celilo-api-${name}`,
+      '-f',
+      keyPath,
+    ]);
+    if (gen.exitCode !== 0) {
+      return {
+        success: false,
+        error: `ssh-keygen failed: ${gen.stderr.toString().trim() || `exit ${gen.exitCode}`}`,
+      };
+    }
+
+    const pubkey = readFileSync(`${keyPath}.pub`, 'utf8').trim();
+    return {
+      success: true,
+      message: [
+        `Generated API keypair for "${name}":`,
+        `  private: ${keyPath}  (keep secret — never share)`,
+        `  public:  ${keyPath}.pub`,
+        '',
+        `Public key: ${pubkey}`,
+        '',
+        'Enroll the public key on celilo-mgr:',
+        `  celilo api grant ${name} --key ${keyPath}.pub --can module:deploy`,
+        '',
+        'Then run commands remotely (configure a Host alias in ~/.ssh/config as needed):',
+        '  celilo --remote celilo-api@celilo-mgr <command>',
+      ].join('\n'),
+    };
+  } catch (error) {
+    return { success: false, error: `Failed to generate API key: ${errMsg(error)}` };
+  }
+}

package/src/cli/completion.ts

@@ -7,6 +7,7 @@ import { eq } from 'drizzle-orm';
 import { getDb } from '../db/client';
 import { capabilities, modules } from '../db/schema';
 import type { ModuleManifest } from '../manifest/schema';
+import { listPrincipals } from '../services/api-access';
 import { listBackups } from '../services/backup-metadata';
 import { listBackupStorages } from '../services/backup-storage';
 import { listContainerServices } from '../services/container-service';
@@ -28,6 +29,7 @@ export async function getCompletions(words: string[], current: number): Promise<
   // currentIndex === 0 means we're completing the first word (the command)
   if (currentIndex === 0) {
     const commands = [
+      'api',
       'audit',
       'backup',
       'capability',
@@ -332,6 +334,26 @@ export async function getCompletions(words: string[], current: number): Promise<
     return filterSuggestions(configKeys, args[4] || '');
   }
 
+  // API subcommands
+  if (command === 'api' && currentIndex === 1) {
+    const subcommands = ['grant', 'list', 'revoke', 'authorized-keys', 'key'];
+    return filterSuggestions(subcommands, args[1] || '');
+  }
+
+  // API revoke - complete with principal names
+  if (command === 'api' && args[1] === 'revoke' && currentIndex === 2) {
+    const principals = await listPrincipals();
+    return filterSuggestions(
+      principals.map((p) => p.name),
+      args[2] || '',
+    );
+  }
+
+  // API key subcommands
+  if (command === 'api' && args[1] === 'key' && currentIndex === 2) {
+    return filterSuggestions(['new'], args[2] || '');
+  }
+
   // Machine subcommands
   if (command === 'machine' && currentIndex === 1) {
     const subcommands = ['add', 'list', 'status', 'remove', 'earmark', 'detect'];

package/src/cli/index.ts

@@ -5,8 +5,16 @@
  */
 
 import * as p from '@clack/prompts';
+import { resolveRemote, runRemoteClient } from '../api/remote-client';
 import { CLIServerRequestSchema, parseJsonWithValidation } from '../validation/schemas';
 import { COMMANDS, type CommandDef } from './command-registry';
+import {
+  handleApiAuthorizedKeys,
+  handleApiGrant,
+  handleApiKeyNew,
+  handleApiList,
+  handleApiRevoke,
+} from './commands/api';
 import { handleCapabilityInfo } from './commands/capability-info';
 import { handleCapabilityList } from './commands/capability-list';
 import { handleCompletion } from './commands/completion';
@@ -184,10 +192,14 @@ Commands:
   proxmox                  Proxmox cluster introspection (proxmox node list)
   publish                  Publish workspace packages to npm and modules to celilo.computer
   subscribers              Manage build-bus subscribers (cross-machine publish-event delivery)
+  api                      Manage remote-API access (principals, grants, authorized_keys)
   completion               Generate shell completion scripts (bash/zsh)
 
   help, --help, -h         Show this help message
 
+Run any command on a remote celilo-mgr over SSH:
+  celilo --remote <ssh-dest> <command>     (or set CELILO_REMOTE=<ssh-dest>)
+
 For command-specific help:
   celilo package --help
   celilo module --help
@@ -1015,6 +1027,24 @@ Using Vault Password:
 export async function runCli(argv: string[]): Promise<CommandResult> {
   const parsed = parseArguments(argv);
 
+  // Remote API server: the sshd forced-command entry point
+  // (`celilo api-serve --principal=<id>`). Not an operator command — kept out
+  // of the registry/completion on purpose. Runs a persistent NDJSON protocol
+  // loop until stdin closes, then exits the process; never returns here.
+  if (parsed.command === 'api-serve') {
+    const principal = typeof parsed.flags.principal === 'string' ? parsed.flags.principal : '';
+    if (!principal) {
+      return {
+        success: false,
+        error:
+          'api-serve requires --principal <name> (normally supplied by the forced command in authorized_keys)',
+      };
+    }
+    const { apiServeMode } = await import('../api/serve');
+    await apiServeMode(principal);
+    return { success: true, message: '' };
+  }
+
   // Handle --get-completions for shell completion (must be before other processing)
   if (parsed.flags['get-completions']) {
     try {
@@ -1673,6 +1703,64 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     return handleRestore(restoreArgs, parsed.flags);
   }
 
+  if (parsed.command === 'api') {
+    if (parsed.flags.help || parsed.flags.h) {
+      return {
+        success: true,
+        message: [
+          'celilo api — manage remote-API access',
+          '',
+          'Usage:',
+          '  celilo api grant <principal> --key <pubkey|path> --can <grant[,grant...]>',
+          '  celilo api list',
+          '  celilo api revoke <principal>',
+          '  celilo api authorized-keys',
+          '  celilo api key new <name>',
+          '',
+          'Grants are command:subcommand (module:deploy), command:* (service:*), or * (all).',
+        ].join('\n'),
+      };
+    }
+
+    if (!parsed.subcommand) {
+      return {
+        success: false,
+        error: 'API subcommand required\n\nRun "celilo api --help" for usage',
+      };
+    }
+
+    const apiFlagError = checkFlags('api', parsed.subcommand, parsed.flags, parsed.args);
+    if (apiFlagError) return apiFlagError;
+
+    if (parsed.subcommand === 'grant') {
+      return handleApiGrant(parsed.args, parsed.flags);
+    }
+
+    if (parsed.subcommand === 'list') {
+      return handleApiList();
+    }
+
+    if (parsed.subcommand === 'revoke') {
+      return handleApiRevoke(parsed.args);
+    }
+
+    if (parsed.subcommand === 'authorized-keys') {
+      return handleApiAuthorizedKeys();
+    }
+
+    if (parsed.subcommand === 'key') {
+      if (parsed.args[0] === 'new') {
+        return handleApiKeyNew(parsed.args.slice(1));
+      }
+      return { success: false, error: 'Usage: celilo api key new <name>' };
+    }
+
+    return {
+      success: false,
+      error: `Unknown api subcommand: ${parsed.subcommand}\n\nRun "celilo api --help" for usage`,
+    };
+  }
+
   if (parsed.command === 'machine') {
     // Handle machine --help
     if (parsed.flags.help || parsed.flags.h) {
@@ -2084,6 +2172,13 @@ export async function main(): Promise<void> {
     return;
   }
 
+  // Remote execution: `celilo --remote <dest> <cmd>` or CELILO_REMOTE=<dest>.
+  // SSH to the remote celilo-mgr and drive its api-serve over the wire.
+  const remote = resolveRemote(process.argv);
+  if (remote) {
+    process.exit(await runRemoteClient(remote.dest, remote.commandArgv));
+  }
+
   // Normal single-command execution
   try {
     const result = await runCli(process.argv);

package/src/cli/parser.test.ts

@@ -107,6 +107,19 @@ describe('CLI Parser', () => {
       expect(result.flags).toEqual({ json: true, verbose: true });
     });
 
+    test('should parse --flag=value inline form', () => {
+      const result = parseArguments([
+        'node',
+        'celilo',
+        'api-serve',
+        '--principal=alice',
+        '--empty=',
+      ]);
+
+      expect(result.command).toBe('api-serve');
+      expect(result.flags).toEqual({ principal: 'alice', empty: '' });
+    });
+
     test('should not consume key=value args as flag values', () => {
       const result = parseArguments([
         'node',

package/src/cli/parser.ts

@@ -82,8 +82,17 @@ export function parseArguments(argv: string[]): ParsedCommand {
     if (!arg) continue;
 
     if (arg.startsWith('--')) {
-      // Long flag (--help, --output, etc.)
-      const flagName = arg.slice(2);
+      const body = arg.slice(2);
+      const eqIndex = body.indexOf('=');
+
+      // Inline-value form: --flag=value (everything after the first `=`).
+      if (eqIndex >= 0) {
+        flags[body.slice(0, eqIndex)] = body.slice(eqIndex + 1);
+        continue;
+      }
+
+      // Space-separated form: --flag value
+      const flagName = body;
       const nextArg = restArgs[i + 1];
 
       // Check if next arg is a value (not another flag, not a key=value pair)

package/src/db/schema.ts

@@ -654,6 +654,34 @@ export const aspectApprovals = sqliteTable(
   }),
 );
 
+/**
+ * Remote API principals (see v2/API_COMMUNICATION.md).
+ *
+ * Each row is one API identity: a name, one SSH public key, and the set of
+ * operations it may run. celilo renders these into the API account's
+ * `authorized_keys` (one forced-command line per row) and authz keys off the
+ * principal → `grants`.
+ *
+ * ponytail: one key per principal (a person wanting a second device makes a
+ * second principal, e.g. `alice-laptop`). If multiple keys per identity is ever
+ * needed, split into an `api_keys` child table — not worth it yet.
+ */
+export const apiPrincipals = sqliteTable('api_principals', {
+  id: text('id').primaryKey(), // UUID
+  /** Human-readable principal name, kebab-case (e.g. "alice", "ci-deployer"). */
+  name: text('name').notNull().unique(),
+  /** SSH public key line: `<type> <base64> [comment]`. */
+  publicKey: text('public_key').notNull(),
+  /**
+   * Operations this principal may run, as `command:subcommand` grants
+   * (`module:deploy`), `command:*` wildcards (`service:*`), or `*` (all).
+   * Deny-by-default: an operation not matched by any grant is refused.
+   */
+  grants: text('grants', { mode: 'json' }).$type<string[]>().notNull().default(sql`'[]'`),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
 /**
  * Type exports for use in application code
  */
@@ -695,3 +723,5 @@ export type ModuleOperation = typeof moduleOperations.$inferSelect;
 export type NewModuleOperation = typeof moduleOperations.$inferInsert;
 export type AspectApproval = typeof aspectApprovals.$inferSelect;
 export type NewAspectApproval = typeof aspectApprovals.$inferInsert;
+export type ApiPrincipal = typeof apiPrincipals.$inferSelect;
+export type NewApiPrincipal = typeof apiPrincipals.$inferInsert;