@celilo/cli 1.12.0 → 1.14.0

package/src/services/api-principal-enrolment.ts

@@ -0,0 +1,158 @@
+/**
+ * Enrol a module's read-only principal on the remote API.
+ *
+ * Named for the MECHANISM, not for the capability it backs. A core service
+ * named after one capability is core doing that provider's work, which is the
+ * pattern `no-module-business-in-core` Scan C exists to stop — and it caught
+ * this file under its first name. Enrolling an API principal is celilo's own
+ * job: the row lands in celilo's `api_principals` table and the grants come
+ * from celilo's command registry. `control_plane_api` is one caller of it.
+ *
+ * The consuming module generates an ed25519 keypair on its own system and
+ * presents the public half here. The private half never crosses this boundary,
+ * which is what makes "the console holds no credential celilo issued it"
+ * checkable rather than merely intended.
+ *
+ * ## The grant set is derived, never passed in
+ *
+ * `readOnlyGrants(COMMANDS)` is the same classifier that decides whether a CLI
+ * leaf is a read. Two consequences, both wanted:
+ *
+ * A new read verb is picked up WITHOUT anyone editing a list — but only at the
+ * next enrolment. The grants are MATERIALISED into the principal row here, so a
+ * celilo-mgr that is upgraded without the consumer being redeployed keeps
+ * serving the grant set that existed when the consumer last installed. Measured:
+ * 27 literal ops in the row, and a read verb celilo gains afterwards is denied.
+ *
+ * That is a limitation rather than a hole. It fails CLOSED, and it heals on the
+ * next redeploy. Making it dynamic means a `ro:*` token resolved at check time,
+ * which is a change to the authorization core and a real trade — a principal's
+ * authority would then move whenever celilo reclassifies a verb, with nobody
+ * re-granting anything. celilo#1153 carries that decision.
+ *
+ * A new WRITE verb is never granted, however it is named, because the
+ * classifier reads the verb token rather than a list somebody maintains. A
+ * hand-written list would drift in exactly one direction — wider — because
+ * widening it is what unblocks whoever is stuck.
+ *
+ * There is deliberately no `grants` parameter. The widest thing this can issue
+ * is the widest thing it should ever issue, and an argument would turn that
+ * into a negotiation with the caller.
+ */
+
+import type { ControlPlaneApiCapability } from '@celilo/capabilities';
+import { COMMANDS, readOnlyGrants } from '@celilo/core';
+import { grantPrincipal, revokePrincipal } from './api-access';
+
+export interface EnrolResult {
+  name: string;
+  grants: string[];
+  created: boolean;
+}
+
+/**
+ * Every read-only op, sorted.
+ *
+ * Computed on each call rather than cached at module load. It is derived from a
+ * static registry so the answer does not change within a process, but a cached
+ * copy is one more thing that can be stale in a long-lived server and the
+ * computation is a filter over a few hundred leaves.
+ */
+export function controlPlaneReadGrants(): string[] {
+  return readOnlyGrants(COMMANDS);
+}
+
+/**
+ * Enrol a consuming module's principal. Idempotent on `name`.
+ *
+ * Re-presenting the same name and key is a no-op reporting `created: false`,
+ * which is what a redeploy does. Presenting a NEW key for an existing name
+ * rotates it — the case a module that regenerated its keypair needs, and one a
+ * module that did not will never hit.
+ *
+ * `grantPrincipal` validates the name and the key, so a malformed public key is
+ * refused here rather than written into `authorized_keys` and failing at login
+ * with a message about the wrong thing.
+ */
+export async function enrolControlPlanePrincipal(params: {
+  name: string;
+  publicKey: string;
+}): Promise<EnrolResult> {
+  const grants = controlPlaneReadGrants();
+  const { principal, created } = await grantPrincipal({
+    name: params.name,
+    publicKey: params.publicKey,
+    grants,
+  });
+
+  // `grantPrincipal` already reports false for a principal that existed, and a
+  // re-grant that rotates a key is correctly not-a-creation. Re-deriving that
+  // here with a second lookup would be two sources for one answer.
+  return { name: principal.name, grants, created };
+}
+
+/**
+ * Remove a principal. Idempotent.
+ *
+ * Called from a consumer's `on_uninstall` so an uninstalled module does not
+ * leave a working key behind. Revoking one that is already gone returns false
+ * rather than throwing: an uninstall that fails on tidy-up is worse than one
+ * that finds nothing to tidy.
+ */
+export async function revokeControlPlanePrincipal(name: string): Promise<boolean> {
+  return revokePrincipal(name);
+}
+
+/**
+ * The `control_plane_api` method table handed to one consuming module.
+ *
+ * ## Why celilo builds this and no module provides it
+ *
+ * Every other function capability is implemented by a provider module's script,
+ * which the loader imports and calls. That is structurally impossible here.
+ * Enrolment writes celilo's own `api_principals` row and derives its grants from
+ * celilo's own command registry, and a module script may import nothing but
+ * `@celilo/capabilities` — its scripts are copied to a data directory at deploy,
+ * so a relative import into the backend breaks. celilo-mgmt has exactly the same
+ * limit as any other module here; being the management server's module does not
+ * give its SCRIPTS a database handle.
+ *
+ * The only shape that would let celilo-mgmt "provide" it is core injecting
+ * enrol/revoke into a factory context so the module's script forwards them
+ * unchanged. Core would still do all the work, and the enrolment would newly
+ * depend on the deployed copy of that script being current — a way to fail that
+ * does not exist today. So this is framework-granted, like `cross_module_read`.
+ *
+ * ## Why the caller cannot name someone else's principal
+ *
+ * `name` is on the request because the contract puts it there, and the only
+ * value accepted is the calling module's id. Without that check any module with
+ * the capability could rotate another module's key by enrolling under its name,
+ * or delete it outright by revoking it — the console's read access removed by a
+ * module that has nothing to do with the console.
+ *
+ * The parameter should come off the contract entirely, the same argument that
+ * kept `grants` off it: a caller that can negotiate WHOSE authority this is has
+ * the same problem as one that can negotiate how much. That is a breaking change
+ * to `@celilo/capabilities`' exported types, so it waits for the next major
+ * rather than forcing one (celilo#1196).
+ */
+export function buildControlPlaneApi(consumerModuleId: string): ControlPlaneApiCapability {
+  function requireOwnPrincipal(name: string, verb: string): void {
+    if (name === consumerModuleId) return;
+    throw new Error(
+      `Module '${consumerModuleId}' tried to ${verb} the API principal '${name}'. A module may only ${verb} its own principal, named for its module id.`,
+    );
+  }
+
+  return {
+    async enrol_principal(request) {
+      requireOwnPrincipal(request.name, 'enrol');
+      return enrolControlPlanePrincipal(request);
+    },
+    async revoke_principal(request) {
+      requireOwnPrincipal(request.name, 'revoke');
+      return { revoked: await revokeControlPlanePrincipal(request.name) };
+    },
+  };
+}

package/src/services/audit/backups.ts

@@ -65,7 +65,16 @@ export function backupStaleThresholdMs(cadence: Cadence): number | null {
   return interval + Math.max(HOUR, interval * 0.1);
 }
 
-function moduleHasBackupHook(manifest: ModuleManifest): boolean {
+/**
+ * Whether celilo can back this module up at all.
+ *
+ * Exported because it is the gate `backup-create.ts` actually applies, and the
+ * console has to draw the same distinction. On the live fleet five of 23
+ * deployed modules declare the hook: the other eighteen are not overdue and not
+ * failing, there is simply nothing to run (celilo#1131). A second copy of this
+ * test elsewhere would eventually disagree about which eighteen.
+ */
+export function moduleHasBackupHook(manifest: ModuleManifest): boolean {
   return Boolean(manifest.hooks?.on_backup);
 }
 

package/src/services/backup-create.ts

@@ -6,7 +6,7 @@
 import { copyFileSync, existsSync, mkdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
-import { getDbPath } from '../config/paths';
+import { getDbPath, getMasterKeyPath } from '../config/paths';
 import { getDb } from '../db/client';
 import { moduleConfigs, modules, secrets as secretsTable } from '../db/schema';
 import { invokeHook } from '../hooks/executor';
@@ -41,6 +41,7 @@ import {
   refuseIfInFlight,
   startOperation,
 } from './module-operations';
+import { stageSystemState } from './system-state-stage';
 
 export interface BackupCreateOptions {
   storageId?: string;
@@ -345,19 +346,44 @@ export async function createModuleBackup(
     const { configMap, secretMap } = await buildModuleContext(moduleId);
     const logger = createConsoleLogger(moduleId, 'on_backup');
 
-    // Inject the framework-resolved DB path so the hook need not re-derive the
-    // data dir from an env var the CLI may not export (ISS-0014). getDbPath()
-    // is celilo's single source of truth for where the DB lives, regardless of
-    // CELILO_DATA_DIR / XDG / explicit override; the hook derives the data dir
-    // (master.key, fleet .ssh) as dirname(db_path) from this.
     const hookInputs: Record<string, unknown> = {
       backup_dir: dataDir,
-      db_path: getDbPath(),
     };
+    // Both privileged inputs ride the same allow-list. `cross_module_root`
+    // mirrors OTHER modules' terraform state; `system_state_root` stages
+    // celilo's own — the DB snapshot, master.key, the fleet key, and every
+    // module's lean source.
+    //
+    // Staging is what lets celilo back ITSELF up without exempting
+    // celilo-mgmt from the hook jail (design D9b). The hook used to receive
+    // `db_path` and walk out from `dirname(db_path)` into celilo's data
+    // directory; it never read those bytes, it copied them, so the framework
+    // does the copying and the data directory stays out of the mount set.
     if (moduleHasCrossModuleRead(manifest)) {
       const crossModuleRoot = join(tempDir, 'cross-module-read');
       materializeCrossModuleRoot(crossModuleRoot, moduleId);
       hookInputs.cross_module_root = crossModuleRoot;
+
+      const staged = stageSystemState(join(tempDir, 'system-state'));
+      hookInputs.system_state_root = staged.root;
+      if (!staged.masterKeyStaged) {
+        logger.warn(
+          `master.key not found at ${getMasterKeyPath()} — secrets in the DB snapshot will be unreadable on restore.`,
+        );
+      }
+      if (!staged.fleetSshStaged) {
+        logger.info(
+          'No fleet SSH keypair on this box — none staged (celilo-mgmt may not have been deployed yet).',
+        );
+      }
+      logger.info(`Staged celilo state: ${staged.moduleSourceCount} module source tree(s)`);
+      if (staged.skippedLarge.length > 0) {
+        // No silent caps: name what was dropped. These are build artifacts the
+        // target rebuilds on deploy.
+        logger.info(
+          `Skipped ${staged.skippedLarge.length} large/non-source file(s) (rebuilt on deploy): ${staged.skippedLarge.join(', ')}`,
+        );
+      }
     }
 
     // Execute on_backup hook — it writes artifacts to dataDir (envelope/data/)

package/src/services/backup-metadata.ts

@@ -4,7 +4,7 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { and, desc, eq, gt, isNotNull, like } from 'drizzle-orm';
+import { and, desc, eq, gt, gte, isNotNull, like } from 'drizzle-orm';
 import { getDb } from '../db/client';
 import { type Backup, type BackupStatus, type BackupType, backups } from '../db/schema';
 import type { BackupHistory } from './backup-schedule';
@@ -140,21 +140,29 @@ export function getBackup(id: string): Backup | null {
 export function listBackups(options?: {
   moduleId?: string;
   limit?: number;
+  /**
+   * Only attempts started at or after this instant (epoch ms).
+   *
+   * A WINDOW rather than a bigger `limit`, because the two answer different
+   * questions and only one of them is stable. "The last 500 attempts" spans a
+   * week for a module failing hourly and a year for one succeeding daily, so a
+   * caller asking for a fixed period cannot express it as a count. The console
+   * needs a period: it draws days, and a row missing from its answer renders as
+   * a day on which nothing ran.
+   */
+  since?: number;
 }): Backup[] {
   const db = getDb();
   const limit = options?.limit ?? 20;
 
-  if (options?.moduleId) {
-    return db
-      .select()
-      .from(backups)
-      .where(eq(backups.moduleId, options.moduleId))
-      .orderBy(desc(backups.startedAt))
-      .limit(limit)
-      .all();
-  }
+  const filters = [
+    options?.moduleId ? eq(backups.moduleId, options.moduleId) : undefined,
+    options?.since !== undefined ? gte(backups.startedAt, new Date(options.since)) : undefined,
+  ].filter((clause) => clause !== undefined);
 
-  return db.select().from(backups).orderBy(desc(backups.startedAt)).limit(limit).all();
+  const query = db.select().from(backups);
+  const filtered = filters.length > 0 ? query.where(and(...filters)) : query;
+  return filtered.orderBy(desc(backups.startedAt)).limit(limit).all();
 }
 
 /**

package/src/services/celilo-mgmt-hooks.test.ts

@@ -1,19 +1,3 @@
-/**
- * Behavior tests for the celilo-mgmt module's on_backup / on_restore
- * hooks (Phase 3 of openspec/specs/management-server-backup/spec.md).
- *
- * We import the hook scripts directly and call their handlers with a
- * synthesized HookContext, then assert on the side-effects (files
- * written to backup_dir / restore staging dirs). This catches
- * regressions in the hook bodies without spinning up the full
- * deploy/backup pipeline.
- *
- * What this DOESN'T test: invokeHook validation, end-to-end backup
- * envelope round-trip. Those live in backup-envelope-roundtrip.test.ts
- * and (eventually) a fresh-box e2e.
- */
-
-import { Database } from 'bun:sqlite';
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -82,13 +66,13 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
   let dir: string;
   let backupDir: string;
   let crossModuleRoot: string;
-  let dbPath: string;
-  let keyPath: string;
+  let systemStateRoot: string;
 
   beforeEach(() => {
     dir = mkdtempSync(join(tmpdir(), 'celilo-mgmt-backup-test-'));
     backupDir = join(dir, 'backup-dir');
     mkdirSync(backupDir, { recursive: true });
+
     crossModuleRoot = join(dir, 'cross-module-root');
     mkdirSync(join(crossModuleRoot, 'modules', 'caddy', 'terraform'), { recursive: true });
     writeFileSync(
@@ -104,25 +88,20 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
       }),
     );
 
-    dbPath = join(dir, 'celilo.db');
-    // A REAL (minimal) SQLite DB. on_backup snapshots it via bun:sqlite
-    // serialize(), which requires a valid database file — a plain byte blob
-    // makes the serializer read a garbage page count and OOM. One table with a
-    // row is enough to exercise the snapshot path.
-    const seed = new Database(dbPath);
-    seed.run('CREATE TABLE backup_probe (id INTEGER PRIMARY KEY, v TEXT)');
-    seed.run("INSERT INTO backup_probe (v) VALUES ('hello')");
-    seed.close();
-    process.env.CELILO_DB_PATH = dbPath;
-
-    keyPath = join(dir, 'master.key');
-    writeFileSync(keyPath, 'fake-master-key-32-bytes-padding!');
-    process.env.CELILO_MASTER_KEY_PATH = keyPath;
+    // celilo's own state, as the framework stages it before invoking the hook
+    // (services/system-state-stage.ts). The hook reads nothing outside this
+    // directory and cross_module_root — that is what design D9b bought, and
+    // it is why there is no CELILO_DB_PATH or master.key on disk here.
+    systemStateRoot = join(dir, 'system-state');
+    mkdirSync(join(systemStateRoot, 'ssh'), { recursive: true });
+    mkdirSync(join(systemStateRoot, 'module_src', 'caddy'), { recursive: true });
+    writeFileSync(join(systemStateRoot, 'celilo.db'), 'SQLite format 3\u0000snapshot');
+    writeFileSync(join(systemStateRoot, 'master.key'), 'fake-master-key-32-bytes-padding!');
+    writeFileSync(join(systemStateRoot, 'ssh', 'id_ed25519'), 'PRIVATE');
+    writeFileSync(join(systemStateRoot, 'module_src', 'caddy', 'manifest.yml'), 'id: caddy');
   });
 
   afterEach(() => {
-    process.env.CELILO_DB_PATH = undefined;
-    process.env.CELILO_MASTER_KEY_PATH = undefined;
     try {
       rmSync(dir, { recursive: true, force: true });
     } catch {
@@ -130,16 +109,20 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
     }
   });
 
-  it('writes celilo.db, master.key, machine-pool.json, and cross_module_state into backup_dir', async () => {
+  it('lays the staged celilo state into backup_dir alongside the cross-module state', async () => {
     const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
-    const ctx = buildContext({
-      backup_dir: backupDir,
-      cross_module_root: crossModuleRoot,
-    });
-    const result = (await hook(ctx)) as BackupHookOutput;
+    const result = (await hook(
+      buildContext({
+        backup_dir: backupDir,
+        cross_module_root: crossModuleRoot,
+        system_state_root: systemStateRoot,
+      }),
+    )) as BackupHookOutput;
 
     expect(existsSync(join(backupDir, 'celilo.db'))).toBe(true);
     expect(existsSync(join(backupDir, 'master.key'))).toBe(true);
+    expect(existsSync(join(backupDir, 'ssh', 'id_ed25519'))).toBe(true);
+    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'manifest.yml'))).toBe(true);
     expect(existsSync(join(backupDir, 'machine-pool.json'))).toBe(true);
     expect(
       existsSync(
@@ -153,39 +136,27 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
     expect(result.size_bytes).toBeGreaterThan(0);
   });
 
-  it('captures LEAN module source (excludes generated/, node_modules/, large build artifacts)', async () => {
-    // stateDir = dirname(db_path) = dir; on_backup reads dir/modules/<id>.
-    const modSrc = join(dir, 'modules', 'caddy');
-    mkdirSync(join(modSrc, 'scripts', 'node_modules', '@celilo'), { recursive: true });
-    mkdirSync(join(modSrc, 'generated', 'terraform'), { recursive: true });
-    mkdirSync(join(modSrc, 'ansible', 'files'), { recursive: true });
-    writeFileSync(join(modSrc, 'manifest.yml'), 'id: caddy');
-    writeFileSync(join(modSrc, 'scripts', 'hook.ts'), '// hook');
-    writeFileSync(join(modSrc, 'generated', 'terraform', 'main.tf'), 'resource {}');
-    writeFileSync(join(modSrc, 'scripts', 'node_modules', '@celilo', 'dep.js'), '// vendored');
-    // A >2MB "compiled binary" sitting in source — must be skipped by size.
-    writeFileSync(join(modSrc, 'ansible', 'files', 'server-bin'), Buffer.alloc(3 * 1024 * 1024));
-
+  it('refuses when the framework did not stage celilo state', async () => {
     const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
-    await hook(buildContext({ backup_dir: backupDir, cross_module_root: crossModuleRoot }));
 
-    // Source files captured...
-    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'manifest.yml'))).toBe(true);
-    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'scripts', 'hook.ts'))).toBe(true);
-    // ...but build/vendored content excluded (keeps the backup small enough to
-    // not OOM the in-memory tar+encrypt — turnip's full dirs were ~1.6GB).
-    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'generated'))).toBe(false);
-    expect(existsSync(join(backupDir, 'module_src', 'caddy', 'scripts', 'node_modules'))).toBe(
-      false,
-    );
+    // Silence is the dangerous outcome here. Without the DB and the master
+    // key an envelope restores to nothing, and a hook that shrugged and
+    // returned success would report artifact_count > 0 for the machine-pool
+    // and cross-module files alone. Found at restore, which is too late.
     expect(
-      existsSync(join(backupDir, 'module_src', 'caddy', 'ansible', 'files', 'server-bin')),
-    ).toBe(false);
+      hook(buildContext({ backup_dir: backupDir, cross_module_root: crossModuleRoot })),
+    ).rejects.toThrow(/system_state_root was not provided/);
   });
 
   it('machine-pool.json is valid JSON (array)', async () => {
     const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
-    await hook(buildContext({ backup_dir: backupDir, cross_module_root: crossModuleRoot }));
+    await hook(
+      buildContext({
+        backup_dir: backupDir,
+        cross_module_root: crossModuleRoot,
+        system_state_root: systemStateRoot,
+      }),
+    );
 
     const machinePool = JSON.parse(readFileSync(join(backupDir, 'machine-pool.json'), 'utf-8'));
     expect(Array.isArray(machinePool)).toBe(true);
@@ -194,25 +165,13 @@ describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_backup', ()
   it('proceeds (with a warning) when cross_module_root is missing', async () => {
     const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
     const result = (await hook(
-      buildContext({ backup_dir: backupDir }), // no cross_module_root
+      buildContext({ backup_dir: backupDir, system_state_root: systemStateRoot }),
     )) as BackupHookOutput;
 
     expect(existsSync(join(backupDir, 'celilo.db'))).toBe(true);
     expect(existsSync(join(backupDir, 'cross_module_state'))).toBe(false);
     expect(result.schema_version).toBe('1.1');
   });
-
-  it('proceeds (with a warning) when master.key is missing on disk', async () => {
-    rmSync(keyPath);
-    const { default: hook } = await import(`${HOOK_DIR}/on_backup.ts`);
-    const result = (await hook(
-      buildContext({ backup_dir: backupDir, cross_module_root: crossModuleRoot }),
-    )) as BackupHookOutput;
-
-    expect(existsSync(join(backupDir, 'master.key'))).toBe(false);
-    expect(existsSync(join(backupDir, 'celilo.db'))).toBe(true);
-    expect(result.artifact_count).toBeGreaterThan(0);
-  });
 });
 
 describe.skipIf(skipIntegration({ tools: ['wg'] }))('celilo-mgmt on_restore', () => {

package/src/services/consumer-cleanup.ts

@@ -48,6 +48,21 @@ export interface CleanupTarget {
   skip?: CleanupSkipReason;
 }
 
+/**
+ * The only part of a manifest this plan reads.
+ *
+ * Narrower than `ModuleManifest` on purpose. A full manifest is a large,
+ * strictly-validated shape, and the console reads manifests straight out of the
+ * `modules` table where they are stored as opaque JSON. Asking for the whole
+ * shape would force either a full re-validation on every poll or a cast, and a
+ * cast at a trust boundary is the thing that eventually bites. `ModuleManifest`
+ * satisfies this structurally, so existing callers are unaffected.
+ */
+export interface ConsumedCapabilities {
+  requires?: { capabilities?: readonly { name: string }[] };
+  optional?: { capabilities?: readonly { name: string }[] };
+}
+
 export interface ProviderRow {
   moduleId: string;
   capabilityName: string;
@@ -76,7 +91,7 @@ export interface ProviderState {
  */
 export function planConsumerCleanup(
   consumer: string,
-  manifest: ModuleManifest,
+  manifest: ConsumedCapabilities,
   providerRows: ProviderRow[],
   providerStates: ProviderState[],
 ): CleanupTarget[] {
@@ -112,16 +127,27 @@ export function planConsumerCleanup(
     .sort((a, b) => a.providerId.localeCompare(b.providerId));
 }
 
+/**
+ * Every (module, capability) provider row.
+ *
+ * Exported because the console's closure walk needs the same edge this plan
+ * does, and reads it for many modules rather than one. Two copies of this query
+ * would be two definitions of what a provider is.
+ */
+export function loadCapabilityProviderRows(db: DbClient): ProviderRow[] {
+  return db
+    .select({ moduleId: capabilities.moduleId, capabilityName: capabilities.capabilityName })
+    .from(capabilities)
+    .all();
+}
+
 /** Read the plan's inputs out of the DB. */
 export function loadConsumerCleanupPlan(
   consumer: string,
   manifest: ModuleManifest,
   db: DbClient,
 ): CleanupTarget[] {
-  const providerRows = db
-    .select({ moduleId: capabilities.moduleId, capabilityName: capabilities.capabilityName })
-    .from(capabilities)
-    .all();
+  const providerRows = loadCapabilityProviderRows(db);
   const providerStates = db
     .select({ moduleId: modules.id, state: modules.state })
     .from(modules)

package/src/services/fleet-key.test.ts

@@ -0,0 +1,47 @@
+/**
+ * celilo's fleet SSH keypair, minted by the framework rather than by
+ * celilo-mgmt's on_install (design D9b of
+ * openspec/changes/hook-process-boundary).
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ensureFleetKey, getFleetSshDir } from './fleet-key';
+
+describe('ensureFleetKey', () => {
+  let dataDir: string;
+
+  beforeEach(() => {
+    dataDir = mkdtempSync(join(tmpdir(), 'celilo-fleet-key-'));
+    process.env.CELILO_DB_PATH = join(dataDir, 'celilo.db');
+  });
+
+  afterEach(() => {
+    process.env.CELILO_DB_PATH = undefined;
+    rmSync(dataDir, { recursive: true, force: true });
+  });
+
+  it('mints an ed25519 keypair next to the DB and returns the public half', () => {
+    const key = ensureFleetKey();
+
+    expect(key.created).toBe(true);
+    expect(key.publicKey.startsWith('ssh-ed25519 ')).toBe(true);
+    expect(existsSync(join(dataDir, '.ssh', 'id_ed25519'))).toBe(true);
+    expect(readFileSync(join(dataDir, '.ssh', 'id_ed25519.pub'), 'utf-8').trim()).toBe(
+      key.publicKey,
+    );
+    expect(getFleetSshDir()).toBe(join(dataDir, '.ssh'));
+  });
+
+  it('reuses an existing key instead of re-keying', () => {
+    const first = ensureFleetKey();
+    const second = ensureFleetKey();
+
+    // Re-keying would strand every machine whose authorized_keys holds the
+    // old public half, and a redeploy calls this every time.
+    expect(second.created).toBe(false);
+    expect(second.publicKey).toBe(first.publicKey);
+  });
+});

package/src/services/fleet-key.ts

@@ -0,0 +1,75 @@
+/**
+ * celilo's fleet SSH keypair — the key celilo authenticates to managed
+ * machines with. The DB carries only the public half (`ssh.public_key`);
+ * the private half lives on disk and never leaves the management box.
+ *
+ * It used to be minted by celilo-mgmt's `on_install`, which derived
+ * `dirname(config.db_path)` and wrote into celilo's data directory from
+ * inside a module hook. That is a write into the one directory the hook
+ * jail exists to keep out of the mount set
+ * (openspec/changes/hook-process-boundary, design D9b): staging covers
+ * copies OUT of celilo's state, and nothing covers writes IN.
+ *
+ * So minting moved here. celilo owns the key's lifecycle, and "create it
+ * if absent" wants to be idempotent and tested once rather than in each
+ * module that reaches for it.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getDbPath } from '../config/paths';
+
+/**
+ * Where the fleet keypair lives.
+ *
+ * Next to the DB, not under `getDataDir()`. Those are the same directory
+ * on a deb install (`CELILO_DATA_DIR=/var/celilo`, db at
+ * `/var/celilo/celilo.db`) and differ only when `CELILO_DB_PATH` points
+ * somewhere custom. Following the DB is what `on_install` did, so it is
+ * where every existing box's key already sits, and restore has followed
+ * the same rule since it was written (`applyStagedSystemFiles`).
+ *
+ * One exported helper rather than two hand-derived joins is the point:
+ * mint and restore can no longer drift to different directories.
+ */
+export function getFleetSshDir(): string {
+  return join(dirname(getDbPath()), '.ssh');
+}
+
+export interface FleetKey {
+  /** The public half, as it goes into `ssh.public_key` and authorized_keys. */
+  publicKey: string;
+  /** True when this call minted the key; false when it was already there. */
+  created: boolean;
+}
+
+/**
+ * Ensure the fleet keypair exists and return its public half.
+ *
+ * Idempotent: an existing key is reused, never regenerated. Re-keying
+ * would silently strand every machine whose authorized_keys holds the old
+ * public half, and a redeploy must not do that.
+ *
+ * Permissions are left to `mkdirSync`'s mode and to ssh-keygen, which
+ * `fchmod`s the private half to 0600 itself. An explicit chmod pass was
+ * written here first and then removed: umask only ever REMOVES mode bits, so
+ * neither the directory nor the key can come out wider than asked for, and no
+ * test could be made to fail without it.
+ */
+export function ensureFleetKey(): FleetKey {
+  const sshDir = getFleetSshDir();
+  const keyPath = join(sshDir, 'id_ed25519');
+  const publicKeyPath = `${keyPath}.pub`;
+
+  if (existsSync(publicKeyPath)) {
+    return { publicKey: readFileSync(publicKeyPath, 'utf-8').trim(), created: false };
+  }
+
+  mkdirSync(sshDir, { recursive: true, mode: 0o700 });
+  execFileSync('ssh-keygen', ['-t', 'ed25519', '-N', '', '-f', keyPath, '-C', 'celilo-fleet'], {
+    stdio: 'pipe',
+  });
+
+  return { publicKey: readFileSync(publicKeyPath, 'utf-8').trim(), created: true };
+}