@celilo/cli 0.9.1 → 0.11.0-alpha.0

package/src/cli/generate-zsh-completion.ts

@@ -9,14 +9,18 @@
  * should never be hand-edited.
  */
 
-import type { ArgDef, CommandDef, FlagDef } from './command-registry';
+import type { ArgDef, CommandDef, FlagDef } from '@celilo/core';
 
 /**
  * Escape a string for use in zsh completion descriptions.
- * Colons and backslashes need escaping in _describe arrays.
+ * Descriptions are emitted inside single-quoted zsh strings, so:
+ *  - backslash and colon need escaping in _describe / _arguments specs
+ *  - a literal apostrophe must close-quote, emit an escaped quote, and reopen
+ *    ('...'\''...') — otherwise it terminates the string early and the rest of
+ *    the file mis-parses (e.g. "account's" broke completion at the next `->`).
  */
 function escapeZshDescription(text: string): string {
-  return text.replace(/\\/g, '\\\\').replace(/:/g, '\\:');
+  return text.replace(/\\/g, '\\\\').replace(/:/g, '\\:').replace(/'/g, "'\\''");
 }
 
 /**

package/src/cli/index.ts

@@ -4,11 +4,20 @@
  * Orchestration function (Rule 10.1) - routes commands to handlers
  */
 
+import { COMMANDS, type CommandDef, resolveRemote, runRemoteClient } from '@celilo/core';
 import * as p from '@clack/prompts';
 import { CLIServerRequestSchema, parseJsonWithValidation } from '../validation/schemas';
-import { COMMANDS, type CommandDef } from './command-registry';
+import {
+  handleApiAuthorizedKeys,
+  handleApiGrant,
+  handleApiKeyNew,
+  handleApiList,
+  handleApiRevoke,
+} from './commands/api';
+import { handleAptUpgrade } from './commands/apt-upgrade';
 import { handleCapabilityInfo } from './commands/capability-info';
 import { handleCapabilityList } from './commands/capability-list';
+import { handleCommands } from './commands/commands-json';
 import { handleCompletion } from './commands/completion';
 import { handleDnsRegistrations } from './commands/dns';
 import {
@@ -180,14 +189,20 @@ Commands:
   restore                  Restore a celilo-mgmt backup from a local file (fresh-bootstrap path)
   machine                  Manage machine pool (bring-your-own-hardware)
   system                   Manage system configuration
+  apt-upgrade              Upgrade the deb-installed celilo packages + apply migrations
   ipam                     Manage IP address and VMID allocations and reservations
   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)
+  commands                 Print the CLI command registry as JSON (drives @celilo/mcp)
 
   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 +1030,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 {
@@ -1066,11 +1099,20 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
     return handleStatus();
   }
 
+  // Handle commands command (serialize the registry; drives @celilo/mcp)
+  if (parsed.command === 'commands') {
+    return handleCommands(parsed.args, parsed.flags);
+  }
+
   // Top-level alias: `celilo audit` → `celilo system audit`
   if (parsed.command === 'audit') {
     return handleSystemAudit(parsed.args, parsed.flags);
   }
 
+  if (parsed.command === 'apt-upgrade') {
+    return handleAptUpgrade(parsed.args, parsed.flags);
+  }
+
   // Route commands
   if (parsed.command === 'package') {
     // Handle package --help
@@ -1261,7 +1303,7 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       case 'import':
         return handleModuleImport(parsed.args, parsed.flags);
       case 'list':
-        return handleModuleList();
+        return handleModuleList(parsed.flags);
       case 'status':
         return handleModuleStatus(parsed.args);
       case 'logs':
@@ -1673,6 +1715,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 +2184,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

@@ -4,7 +4,7 @@
  * Policy functions (Rule 10.1) - parsing and validation only
  */
 
-import type { CommandDef } from './command-registry';
+import type { CommandDef } from '@celilo/core';
 import type { ParsedCommand } from './types';
 
 /**
@@ -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;

package/src/hooks/capability-loader.test.ts

@@ -126,4 +126,81 @@ describe('Capability Loader', () => {
     const consumer = await loadCapabilityFunctions('apt-repo', db, noopLogger);
     expect(consumer).not.toHaveProperty('web_routes');
   });
+
+  // ce-iku regression: public_web's managed-domain check must reflect the
+  // registrar's DECLARED `domain_list` computed field (namecheap:
+  // keys(secret.ddns_passwords)) — the same live set DDNS validation sees —
+  // NOT a stale `config.domains` row that survived an older manifest version.
+  // Without the fix the config-shape heuristic short-circuits on the stale
+  // config.domains and a just-added domain (present only in the secret) is
+  // silently excluded, dead-ending register_route forever.
+  test('public_web managed-domains come from the registrar domain_list computed field, not a stale config.domains', async () => {
+    const { encryptSecret } = await import('../secrets/encryption');
+    const { getOrCreateMasterKey } = await import('../secrets/master-key');
+    const { isMissingProviderInputError } = await import('@celilo/capabilities');
+    const masterKey = await getOrCreateMasterKey();
+
+    // Provider: caddy (public_web). Needs ≥1 configured hostname + target_ip
+    // for createPublicWeb to build.
+    const caddyPath = join(tempDir, 'caddy');
+    mkdirSync(caddyPath, { recursive: true });
+    db.$client.run(
+      `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('caddy', 'Caddy', '1.0.0', '${caddyPath}', '{}')`,
+    );
+    db.$client.run(
+      `INSERT INTO capabilities (module_id, capability_name, version, data, registered_at) VALUES ('caddy', 'public_web', '1.0.0', '{}', unixepoch())`,
+    );
+    upsertModuleConfig(db, 'caddy', 'hostnames', ['seed.celilo.computer']);
+    upsertModuleConfig(db, 'caddy', 'target_ip', '10.0.20.10');
+
+    // Provider: namecheap (dns_registrar). Its `data` declares the canonical
+    // domain_list computed field. config.domains is STALE (missing the newly
+    // onboarded domain); the SECRET holds the real, current set.
+    const ncPath = join(tempDir, 'namecheap');
+    mkdirSync(ncPath, { recursive: true });
+    const registrarData = JSON.stringify({
+      provider: 'namecheap',
+      domain_list: { __celilo_computed__: 'keys(secret.ddns_passwords)' },
+    });
+    db.$client.run(
+      `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES ('namecheap', 'Namecheap', '3.2.0', '${ncPath}', '{}')`,
+    );
+    db.$client.run(
+      `INSERT INTO capabilities (module_id, capability_name, version, data, registered_at) VALUES ('namecheap', 'dns_registrar', '4.0.0', '${registrarData}', unixepoch())`,
+    );
+    // Stale config that must be IGNORED — omits buildyourowninternet.dev.
+    upsertModuleConfig(db, 'namecheap', 'domains', ['celilo.computer']);
+    // Live secret — the source of truth — includes the new domain.
+    const ddnsEnc = encryptSecret(
+      JSON.stringify({ 'celilo.computer': 'pw1', 'buildyourowninternet.dev': 'pw2' }),
+      masterKey,
+    );
+    db.$client.run(
+      `INSERT INTO secrets (module_id, name, encrypted_value, iv, auth_tag) VALUES ('namecheap', 'ddns_passwords', '${ddnsEnc.encryptedValue}', '${ddnsEnc.iv}', '${ddnsEnc.authTag}')`,
+    );
+
+    const consumer = await loadCapabilityFunctions('byoi', db, noopLogger);
+    const publicWeb = consumer.public_web as {
+      register_route: (r: { type: string; path: string; hostname: string }) => Promise<unknown>;
+    };
+    expect(publicWeb).toBeTruthy();
+
+    // Does register_route reject specifically because the hostname's apex
+    // isn't in any managed domain? (Later reconcile errors are a different
+    // failure — the domain check already passed by then.)
+    async function rejectsAsMissingProvider(hostname: string): Promise<boolean> {
+      try {
+        await publicWeb.register_route({ type: 'static', path: '/', hostname });
+        return false;
+      } catch (err) {
+        return isMissingProviderInputError(err);
+      }
+    }
+
+    // In the secret (domain_list) but NOT in the stale config.domains — must
+    // pass the managed-domain check.
+    expect(await rejectsAsMissingProvider('www.buildyourowninternet.dev')).toBe(false);
+    // In neither the secret nor config — control: must still be rejected.
+    expect(await rejectsAsMissingProvider('app.notmanaged.example')).toBe(true);
+  });
 });

package/src/hooks/capability-loader.ts

@@ -33,6 +33,9 @@ import { emitWebRoutesChangedAndWait } from '../services/celilo-events';
 import { getModuleSystems } from '../services/deployed-systems';
 import { withDnsInternalLedger } from '../services/dns-internal-records';
 import { withDnsRegistrationLedger } from '../services/dns-registrations';
+import { resolveComputedFields } from '../variables/computed/evaluate';
+import { containsComputedMarker } from '../variables/computed/marker';
+import { buildProviderLookup } from '../variables/computed/provider-lookup';
 import { loadHookConfigMap } from './load-hook-config';
 
 /**
@@ -351,6 +354,27 @@ export async function loadCapabilityFunctions(
       // First registrar wins — multi-registrar setups can't be auto-extended
       // since we'd have to pick which one to add the new domain to.
       if (!dnsRegistrarModuleId) dnsRegistrarModuleId = drp.moduleId;
+
+      // Canonical source: the registrar's DECLARED `domain_list` computed
+      // field, resolved LIVE in the provider's context — the exact value
+      // `$capability:dns_registrar.domain_list` resolves to and the same set
+      // the registrar's own DDNS validation iterates (for namecheap,
+      // keys(secret.ddns_passwords)). The manifest calls this "never
+      // persisted, never stale"; deriving domains any other way drifts. In
+      // particular a leftover `config.domains` row (from an older registrar
+      // manifest — module config survives version bumps) would otherwise be
+      // preferred by the heuristic below over the live secret keys and
+      // silently exclude a just-added domain, dead-ending new-domain
+      // onboarding forever (ce-iku).
+      const declaredDomains = await resolveRegistrarDomainList(drp.data, drp.moduleId, db);
+      if (declaredDomains) {
+        dnsManagedDomains.push(...declaredDomains);
+        continue;
+      }
+
+      // Fallback for registrars that DON'T declare a `domain_list` computed
+      // field (older/archived static-config providers): read the config
+      // shape directly.
       const drConfig = await loadModuleConfig(drp.moduleId, db);
       // dns_registrar 4.0.0+ exposes a single `domains` array (the
       // primary_domain/additional_domains split was collapsed — see
@@ -555,6 +579,38 @@ async function loadModuleSecrets(
   return result;
 }
 
+/**
+ * Resolve a dns_registrar provider's DECLARED `domain_list` computed field
+ * (e.g. namecheap's `keys(secret.ddns_passwords)`) in the PROVIDER's context —
+ * the canonical, always-live set of zones it manages. Returns the string list,
+ * or null when the provider declares no such computed field so the caller
+ * falls back to reading the config shape directly.
+ *
+ * This is the same value `$capability:dns_registrar.domain_list` resolves to
+ * and the same set the registrar's own DDNS validation iterates, so
+ * public_web's hostname check can never drift from what the registrar actually
+ * manages (ce-iku).
+ */
+async function resolveRegistrarDomainList(
+  rawData: unknown,
+  moduleId: string,
+  db: DbClient,
+): Promise<string[] | null> {
+  try {
+    const data = typeof rawData === 'string' ? JSON.parse(rawData) : rawData;
+    if (!containsComputedMarker(data)) return null;
+    const lookup = await buildProviderLookup(moduleId, db);
+    const resolved = resolveComputedFields(data, lookup) as Record<string, unknown>;
+    const list = resolved.domain_list;
+    if (!Array.isArray(list)) return null;
+    return list.filter((d): d is string => typeof d === 'string' && d.length > 0);
+  } catch {
+    // Provider context couldn't resolve (e.g. undecryptable secret) — let the
+    // caller fall back to the config-shape heuristic.
+    return null;
+  }
+}
+
 /**
  * Build a firewall capability chain from multiple providers.
  *

package/src/services/api-access.test.ts

@@ -0,0 +1,138 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '@/db/client';
+import {
+  getPrincipalByName,
+  grantPrincipal,
+  grantsAllow,
+  isAuthorized,
+  listPrincipals,
+  renderAuthorizedKeys,
+  revokePrincipal,
+  validateGrant,
+  validatePrincipalName,
+  validatePublicKey,
+} from './api-access';
+
+const VALID_KEY = 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI test@laptop';
+
+describe('grantsAllow (pure, deny-by-default)', () => {
+  test('exact command:subcommand', () => {
+    expect(grantsAllow(['module:deploy'], 'module', 'deploy')).toBe(true);
+    expect(grantsAllow(['module:deploy'], 'module', 'remove')).toBe(false);
+  });
+
+  test('command:* wildcard', () => {
+    expect(grantsAllow(['service:*'], 'service', 'add')).toBe(true);
+    expect(grantsAllow(['service:*'], 'service', 'remove')).toBe(true);
+    expect(grantsAllow(['service:*'], 'module', 'deploy')).toBe(false);
+  });
+
+  test('global *', () => {
+    expect(grantsAllow(['*'], 'anything', 'goes')).toBe(true);
+  });
+
+  test('bare command for a subcommand-less command', () => {
+    expect(grantsAllow(['status'], 'status')).toBe(true);
+    expect(grantsAllow(['status'], 'module', 'deploy')).toBe(false);
+  });
+
+  test('empty grants deny everything', () => {
+    expect(grantsAllow([], 'module', 'deploy')).toBe(false);
+  });
+});
+
+describe('validators', () => {
+  test('principal name must be kebab-case', () => {
+    expect(() => validatePrincipalName('alice')).not.toThrow();
+    expect(() => validatePrincipalName('ci-deployer')).not.toThrow();
+    expect(() => validatePrincipalName('Alice')).toThrow();
+    expect(() => validatePrincipalName('a b')).toThrow();
+    expect(() => validatePrincipalName('under_score')).toThrow();
+  });
+
+  test('public key must look like an SSH key', () => {
+    expect(() => validatePublicKey(VALID_KEY)).not.toThrow();
+    expect(() => validatePublicKey('ssh-ed25519 AAAAC3NzaC1lZDI1NTE5')).not.toThrow();
+    expect(() => validatePublicKey('not a key')).toThrow();
+    expect(() => validatePublicKey('ssh-ed25519')).toThrow();
+    expect(() => validatePublicKey('rsa-bogus AAAA')).toThrow();
+  });
+
+  test('grant syntax', () => {
+    expect(() => validateGrant('module:deploy')).not.toThrow();
+    expect(() => validateGrant('service:*')).not.toThrow();
+    expect(() => validateGrant('*')).not.toThrow();
+    expect(() => validateGrant('status')).not.toThrow();
+    expect(() => validateGrant('Module:Deploy')).toThrow();
+    expect(() => validateGrant('a:b:c')).toThrow();
+  });
+});
+
+describe('api-access (DB-backed)', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-api-access-'));
+    process.env.CELILO_DB_PATH = join(dir, 'test.db');
+    closeDb(); // drop any cached handle so getDb() reopens at the new path
+  });
+
+  afterEach(() => {
+    closeDb();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('grant → list → getByName → isAuthorized → render → revoke', async () => {
+    const { created } = await grantPrincipal({
+      name: 'alice',
+      publicKey: VALID_KEY,
+      grants: ['module:deploy', 'service:*'],
+    });
+    expect(created).toBe(true);
+
+    expect((await listPrincipals()).map((p) => p.name)).toEqual(['alice']);
+
+    const alice = await getPrincipalByName('alice');
+    expect(alice?.grants).toEqual(['module:deploy', 'service:*']);
+
+    expect(await isAuthorized('alice', 'module', 'deploy')).toBe(true);
+    expect(await isAuthorized('alice', 'service', 'add')).toBe(true);
+    expect(await isAuthorized('alice', 'secret', 'read')).toBe(false);
+    expect(await isAuthorized('nobody', 'module', 'deploy')).toBe(false);
+
+    const authKeys = await renderAuthorizedKeys();
+    expect(authKeys).toContain('command="celilo api-serve --principal=alice"');
+    expect(authKeys).toContain('no-pty,no-port-forwarding');
+    expect(authKeys).toContain(VALID_KEY);
+
+    expect(await revokePrincipal('alice')).toBe(true);
+    expect(await listPrincipals()).toHaveLength(0);
+    expect(await revokePrincipal('alice')).toBe(false);
+    expect(await renderAuthorizedKeys()).toBe('');
+  });
+
+  test('grant is an upsert (replaces key + grants)', async () => {
+    await grantPrincipal({ name: 'bob', publicKey: VALID_KEY, grants: ['status'] });
+    const second = await grantPrincipal({
+      name: 'bob',
+      publicKey: VALID_KEY,
+      grants: ['module:deploy'],
+    });
+    expect(second.created).toBe(false);
+    expect((await getPrincipalByName('bob'))?.grants).toEqual(['module:deploy']);
+    expect(await listPrincipals()).toHaveLength(1);
+  });
+
+  test('invalid inputs are rejected before write', async () => {
+    await expect(
+      grantPrincipal({ name: 'Bad Name', publicKey: VALID_KEY, grants: ['status'] }),
+    ).rejects.toThrow();
+    await expect(
+      grantPrincipal({ name: 'good', publicKey: 'garbage', grants: ['status'] }),
+    ).rejects.toThrow();
+    expect(await listPrincipals()).toHaveLength(0);
+  });
+});