@celilo/cli 1.11.0 → 1.13.0

package/src/module/packaging/audit.ts

@@ -2,9 +2,15 @@ import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { eq } from 'drizzle-orm';
-import { getDb } from '../../db/client';
+import { type DbClient, getDb } from '../../db/client';
 import { moduleIntegrity, modules } from '../../db/schema';
 import type { ModuleManifest } from '../../manifest/schema';
+import {
+  type InstanceRecord,
+  loadInstance,
+  submoduleSourcePath,
+  verifyInstanceLinks,
+} from '../../services/module-instances';
 import { computeFileChecksum } from './checksum';
 import type { IntegrityViolation } from './extract';
 import { compareVerbatimRoleAssets, readVerbatimRoleAssets } from './generated-plane';
@@ -49,6 +55,21 @@ async function scanDirectory(dir: string, baseDir: string): Promise<string[]> {
     const fullPath = join(dir, entry.name);
     const relativePath = relative(baseDir, fullPath);
 
+    // A symlink is SKIPPED, deliberately and in writing.
+    //
+    // An instance's authored source is symlinked in from its parent's
+    // `submodules/` tree (openspec/changes/submodules D4), so those bytes are
+    // the PARENT's and are covered by the parent's baseline. This module has no
+    // claim to make over them, and following the link would have it claim
+    // integrity over bytes whose checksums belong to somebody else.
+    //
+    // This already happened, by accident: `Dirent.isDirectory()` and
+    // `isFile()` are BOTH false for a symlink, so links fell through both
+    // branches below and vanished. Right answer, no reason. Stating it here
+    // means a later change that makes the walk follow links has to decide
+    // about instances on purpose rather than reverse this silently.
+    if (entry.isSymbolicLink()) continue;
+
     if (entry.isDirectory()) {
       // Prune whole derived subtrees rather than walking them. `generated/`
       // alone carries terraform provider binaries.
@@ -91,6 +112,18 @@ export async function auditModule(
       };
     }
 
+    // An instance has no integrity row of its own and never will
+    // (openspec/changes/submodules D4). Its authored bytes are its
+    // submodule's, its submodule's are its parent's, and the parent already
+    // carries a baseline covering `submodules/**`. So it resolves THROUGH to
+    // that rather than being excluded: excluding it would report nothing for
+    // forty rows, and erroring would report `No integrity data found` forty
+    // times for a fleet that is entirely healthy.
+    const instance = loadInstance(moduleId, db);
+    if (instance) {
+      return await auditInstance(instance, module.sourcePath, db, options);
+    }
+
     // Get integrity data
     const integrity = db
       .select()
@@ -242,3 +275,72 @@ export async function auditModule(
     };
   }
 }
+
+/**
+ * Audit an instance.
+ *
+ * Two questions, and only the second is the instance's own.
+ *
+ * Its BYTES belong to its parent, so the integrity verdict is the parent's:
+ * `submodules/**` classifies `package`, so the parent's baseline already covers
+ * every file an instance runs. Re-checksumming them here would be asking the
+ * same question a second time and inventing a second answer that can disagree.
+ *
+ * Its LINKS are its own, and nothing else in celilo checks them. A link
+ * repointed at another module's source is an instance running somebody else's
+ * code while every checksum in the fleet still reconciles, which is exactly the
+ * kind of quiet wrong answer the integrity plane exists to prevent.
+ */
+async function auditInstance(
+  instance: InstanceRecord,
+  instancePath: string,
+  db: DbClient,
+  options: AuditOptions,
+): Promise<AuditResult> {
+  const violations: IntegrityViolation[] = [];
+
+  const parent = db.select().from(modules).where(eq(modules.id, instance.parentId)).get();
+  if (!parent) {
+    // The FK makes this unreachable through SQL, so reaching it means the row
+    // was written around the schema. Reported rather than assumed away.
+    return {
+      success: false,
+      moduleId: instance.moduleId,
+      violations,
+      error: `Instance '${instance.moduleId}' names parent '${instance.parentId}', which does not exist.`,
+    };
+  }
+
+  const submodulePath = submoduleSourcePath(parent.sourcePath, instance.submodule);
+  for (const link of await verifyInstanceLinks({ instancePath, submodulePath })) {
+    violations.push({
+      type: 'modified',
+      path: link.entry,
+      message:
+        link.actual === null
+          ? `Link '${link.entry}' is missing or is not a link. It should point at ${link.expected}. Redeploy this instance to rebuild its links.`
+          : `Link '${link.entry}' points at ${link.actual}, not at ${link.expected}. This instance is running source it does not own.`,
+    });
+  }
+
+  // The parent's verdict, carried rather than recomputed. A parent whose
+  // baseline is stale or whose files are modified means every instance under it
+  // is running unverified code, and saying so here is what stops an operator
+  // reading a clean instance row as evidence.
+  const parentResult = await auditModule(instance.parentId, db, options);
+  if (!parentResult.success) {
+    violations.push({
+      type: 'stale-baseline',
+      path: `${instance.parentId}`,
+      message: `The bytes this instance runs belong to '${instance.parentId}', whose own audit is not clean (${parentResult.violations.length} violation(s)${parentResult.error ? `: ${parentResult.error}` : ''}). Fix the parent; this instance cannot be verified independently.`,
+    });
+  }
+
+  return {
+    success: violations.length === 0,
+    moduleId: instance.moduleId,
+    violations,
+    moduleVersion: parent.version,
+    baselineVersion: parentResult.baselineVersion,
+  };
+}

package/src/module/packaging/classify-module-path.test.ts

@@ -102,3 +102,39 @@ describe('classifyModulePath: composes with includeNodeModulesPath', () => {
     expect(classifyModulePath('node_modules/@celilo/cli/index.js')).toBe('unknown');
   });
 });
+
+describe('a submodule tree obeys the same rules as a module tree', () => {
+  // openspec/changes/submodules D1: a submodule declares everything an ordinary
+  // module declares, so it must be CLASSIFIED like one too. Every rule keys on
+  // segments[0], so without the recursion a nested tree gets different answers
+  // than the same file one level up.
+  test('authored source under a submodule is package', () => {
+    expect(classifyModulePath('submodules/runner/manifest.yml')).toBe('package');
+    expect(classifyModulePath('submodules/runner/ansible/site.yml')).toBe('package');
+    expect(classifyModulePath('submodules/runner/scripts/hook.ts')).toBe('package');
+  });
+
+  test("a submodule's e2e tree is excluded, exactly as a module's is", () => {
+    expect(classifyModulePath('e2e/thing.ts')).toBe('unknown');
+    expect(classifyModulePath('submodules/runner/e2e/thing.ts')).toBe('unknown');
+  });
+
+  test("a submodule's derived paths are derived", () => {
+    expect(classifyModulePath('submodules/runner/generated/terraform/x.tfstate')).toBe('derived');
+    expect(classifyModulePath('submodules/runner/celilo/types.d.ts')).toBe('derived');
+    expect(classifyModulePath('submodules/runner/cookies.json')).toBe('derived');
+    expect(classifyModulePath('submodules/runner/screenshots/a.png')).toBe('derived');
+  });
+
+  test('source-tree noise under a submodule is still a finding', () => {
+    expect(classifyModulePath('submodules/runner/.DS_Store')).toBe('unknown');
+    expect(classifyModulePath('submodules/runner/tsconfig.json')).toBe('unknown');
+    expect(classifyModulePath('submodules/runner/a.test.ts')).toBe('unknown');
+  });
+
+  // The directories themselves are shipped bytes and belong in the baseline.
+  test('the submodules directory itself is package', () => {
+    expect(classifyModulePath('submodules')).toBe('package');
+    expect(classifyModulePath('submodules/runner')).toBe('package');
+  });
+});

package/src/module/packaging/package-rules.ts

@@ -69,10 +69,28 @@ export type ModulePathClass = 'package' | 'derived' | 'unknown';
  * composes this function with `includeNodeModulesPath` rather than restating
  * either rule.
  */
+export const SUBMODULES_DIR = 'submodules';
+
 export function classifyModulePath(relPath: string): ModulePathClass {
   const segments = relPath.split('/');
   const name = segments[segments.length - 1] ?? '';
 
+  // A submodule's tree obeys exactly the same rules as a module's tree
+  // (openspec/changes/submodules D1: a submodule declares everything an
+  // ordinary module declares). Every rule below keys on `segments[0]`, so
+  // without this a nested tree silently gets different answers: a submodule's
+  // own `e2e/` would be checksummed where a module's is excluded, because
+  // `segments[0]` reads `submodules` rather than `e2e`.
+  //
+  // Recursing on the remainder means one set of rules rather than two that
+  // drift, and every rule applies at both levels: a submodule's `e2e/` is
+  // excluded, its `celilo/types.d.ts` and `cookies.json` are derived, its
+  // `.DS_Store` is a finding. `submodules/` and `submodules/<name>` themselves
+  // stay `package`, which is right: the directories ARE shipped bytes.
+  if (segments[0] === SUBMODULES_DIR && segments.length > 2) {
+    return classifyModulePath(segments.slice(2).join('/'));
+  }
+
   // The module's own e2e/ tree is tests plus their deps, including a
   // node_modules of its own. Excluded whole, before anything below.
   if (segments[0] === 'e2e') return 'unknown';

package/src/policy/capability-shape-baseline.ts

@@ -77,6 +77,10 @@ export const CAPABILITY_SHAPE_BASELINE: Readonly<Record<string, CapabilityShape>
     version: '1.0.0',
     hash: '2f7f81d0b3ecb2ab6822dbc9bf837a933b25e0e157eb94d0b9b8e801417f8f14',
   },
+  control_plane_api: {
+    version: '1.0.0',
+    hash: '2c5d41d37a9a828a8b9a6dc633a2d48f24670d0831d879ec18426f0f9f8e5be5',
+  },
   private_web: {
     version: '1.0.0',
     hash: '0eddb82f821fe3c7fbd503d55a24c3d5a22369af8b22de06570a371d5f485c03',
@@ -85,6 +89,10 @@ export const CAPABILITY_SHAPE_BASELINE: Readonly<Record<string, CapabilityShape>
     version: '1.0.0',
     hash: 'e152f0738c88a7105b6057037f350ce0bbcbfc5c4ccbccc3af60f1cf3f1904af',
   },
+  celilo_module_deploy_worker: {
+    version: '1.0.0',
+    hash: '0b0e1f26aab0ebcf5d28283b9c5ba711f6d182f8f7ad474379c4ab02c354a2b8',
+  },
   web_routes: {
     version: '1.0.0',
     hash: 'bbf6435528a799e205270681e0ffc34f4007efbf04240138d4b69594a2515dbb',

package/src/policy/module-business-baseline.ts

@@ -111,6 +111,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: 'PERMANENT — the public_web implementation naming its own table; the capability package doing its job',
   },
+  {
+    file: 'packages/capabilities/src/capability-contract.ts',
+    capability: 'control_plane_api',
+    count: 1,
+    why: 'PERMANENT — a contract declaration with no implementation; this is the package doing its job',
+  },
   {
     file: 'packages/capabilities/src/capability-contract.ts',
     capability: 'web_routes',
@@ -327,6 +333,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: 'PERMANENT — the name-keyed aggregate of capability TABLE declarations, same shape and same justification as capability-contract.ts: a declaration with no implementation. Naming the capability IS the mapping; core reads it to avoid naming any (openspec/changes/capability-owned-tables D2)',
   },
+  {
+    file: 'packages/capabilities/src/capability-contract.ts',
+    capability: 'celilo_module_deploy_worker',
+    count: 1,
+    why: 'PERMANENT — X10, a contract declaration with no implementation; this is the package doing its job',
+  },
   {
     file: 'packages/capabilities/src/capability-contract.ts',
     capability: 'control_plane_vpn',

package/src/registry/client.ts

@@ -28,6 +28,8 @@ export interface SearchResult {
   name: string;
   max_version: string;
   description: string;
+  /** The module's declared glyph, absent when it declared none. */
+  icon?: string;
 }
 
 export interface SearchResponse {
@@ -130,6 +132,12 @@ export class RegistryClient {
      * apps/celilo/designs/REGISTRY_BROWSE_UI.md (Phase 2 step 0).
      */
     description?: string;
+    /**
+     * The module's `manifest.yml#icon`, when it declares one. Optional and
+     * server-tolerated in its absence, exactly like `description`
+     * (openspec/changes/module-icons, D4).
+     */
+    icon?: string;
   }): Promise<{ ok: boolean; name: string; vers: string }> {
     const fileData = await readFile(opts.netappPath);
     const cksum = `sha256:${createHash('sha256').update(fileData).digest('hex')}`;
@@ -140,6 +148,7 @@ export class RegistryClient {
       deps: [],
       cksum,
       ...(opts.description ? { description: opts.description } : {}),
+      ...(opts.icon ? { icon: opts.icon } : {}),
     });
     const metaBuf = Buffer.from(meta, 'utf-8');
 

package/src/services/alerting/observed-health.ts

@@ -0,0 +1,71 @@
+/**
+ * Observed health per module, derived from live alerts and enabled monitors.
+ *
+ * Extracted from `module list` because it now has a second consumer. The web
+ * console shows the same column, and celilo has already decided how this is
+ * computed: `nextModuleState()` documents why observation must NOT drive a
+ * module's lifecycle state, since letting a recurring check write it would
+ * redefine VERIFIED from "someone verified this" to "it was up recently" and
+ * churn it on every transient failure.
+ *
+ * So this stays a derivation and never a stored field, and both consumers read
+ * it here rather than each growing a copy.
+ */
+
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../../db/client';
+import { modules as modulesTable, monitors } from '../../db/schema';
+import { moduleHealthCell } from './format';
+import { loadAllLiveAlerts, summariseByModule } from './store';
+
+/** The structured form. `cell` is the display string the CLI column prints. */
+export interface ObservedHealth {
+  cell: string;
+  monitored: boolean;
+  firingCount: number;
+  suppressed: boolean;
+}
+
+/**
+ * Observed health per module: `ok`, `N firing`, `suppressed`, or
+ * `not observed`.
+ *
+ * Only computed for DEPLOYED modules — a module still being imported has
+ * nothing to observe, and reporting it as unwatched would be noise rather
+ * than a finding.
+ */
+export function loadObservedHealth(db: DbClient): Map<string, string> {
+  return new Map([...loadObservedHealthDetail(db)].map(([id, h]) => [id, h.cell]));
+}
+
+/**
+ * The same derivation, with the inputs kept rather than collapsed into a
+ * string. The console needs the firing COUNT and the not-observed case as
+ * separate facts: it renders them differently, and parsing them back out of a
+ * terminal column would be a second, worse implementation.
+ */
+export function loadObservedHealthDetail(db: DbClient): Map<string, ObservedHealth> {
+  const monitored = new Set(
+    db
+      .select({ target: monitors.target })
+      .from(monitors)
+      .where(eq(monitors.enabled, true))
+      .all()
+      .map((m) => m.target),
+  );
+  const byModule = summariseByModule(loadAllLiveAlerts(db));
+
+  const result = new Map<string, ObservedHealth>();
+  for (const module of db.select().from(modulesTable).all()) {
+    if (module.state !== 'INSTALLED' && module.state !== 'VERIFIED') continue;
+
+    const summary = byModule.get(module.id) ?? [];
+    const input = {
+      monitored: monitored.has(module.id),
+      firingCount: summary.filter((s) => !s.suppressed).length,
+      suppressed: summary.length > 0 && summary.every((s) => s.suppressed),
+    };
+    result.set(module.id, { ...input, cell: moduleHealthCell(input) });
+  }
+  return result;
+}

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

@@ -0,0 +1,179 @@
+/**
+ * `control_plane_api`, and the one property that has to hold forever.
+ *
+ * The console reads celilo's own state. What it must never acquire is the
+ * ability to change it — and the way that would happen is not somebody adding
+ * `module:deploy` on purpose. It is a new verb appearing in the registry and
+ * quietly falling on the wrong side of a grant list nobody re-reads.
+ *
+ * So the grants are DERIVED, and these assert the derivation rather than a
+ * snapshot of its output. A test that pinned today's list would pass forever
+ * while the thing it protects rotted.
+ */
+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 { COMMANDS, readOnlyGrants } from '@celilo/core';
+import { closeDb } from '../db/client';
+import { getPrincipalByName, isAuthorized } from './api-access';
+import {
+  controlPlaneReadGrants,
+  enrolControlPlanePrincipal,
+  revokeControlPlanePrincipal,
+} from './api-principal-enrolment';
+
+/** A syntactically real ed25519 public key. Nothing here ever sees a private one. */
+const PUBLIC_KEY =
+  'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIB7cWlXqPn+aGaNKm2Rt1cwj6cVy0hL0hVXHhWJKtLZ9 celilo-web-console';
+const OTHER_KEY =
+  'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILlqL4YQ1MDe0J0X2ZQ4pXFqNbXK9y7dQe2Vd1kZ8sWq rotated';
+
+describe('the grant set', () => {
+  test('is exactly the read-only ops the classifier derives', () => {
+    // Not a snapshot. If this were a literal list it would pass forever while a
+    // newer celilo added verbs it no longer covered.
+    expect(controlPlaneReadGrants()).toEqual(readOnlyGrants(COMMANDS));
+  });
+
+  test('is not empty, so the derivation is doing something', () => {
+    // The failure mode a derived list has that a literal one does not: a
+    // classifier change makes it return nothing and every read starts failing
+    // closed. That is safe and completely broken, so it is asserted.
+    expect(controlPlaneReadGrants().length).toBeGreaterThan(10);
+  });
+
+  test('contains no obviously mutating op', () => {
+    // A coarse net on purpose. The classifier is the real gate; this catches the
+    // case where the classifier itself is changed to admit writes, which no test
+    // of the classifier's own output would notice.
+    const mutating = /:(deploy|remove|delete|create|set|add|uninstall|restore|grant|revoke|pause)$/;
+    expect(controlPlaneReadGrants().filter((op) => mutating.test(op))).toEqual([]);
+  });
+});
+
+describe('enrolment', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    // The service reaches for the global `getDb()`, so isolation is by
+    // CELILO_DB_PATH rather than by passing a client around.
+    dir = mkdtempSync(join(tmpdir(), 'celilo-cpa-'));
+    process.env.CELILO_DB_PATH = join(dir, 'test.db');
+    closeDb();
+  });
+
+  afterEach(() => {
+    closeDb();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('creates a principal carrying the derived grants', async () => {
+    const result = await enrolControlPlanePrincipal({
+      name: 'celilo-web-console',
+      publicKey: PUBLIC_KEY,
+    });
+    expect(result.created).toBe(true);
+    expect(result.grants).toEqual(controlPlaneReadGrants());
+
+    const stored = await getPrincipalByName('celilo-web-console');
+    expect(stored?.publicKey).toBe(PUBLIC_KEY);
+  });
+
+  test('is idempotent, because a redeploy presents the same name again', async () => {
+    await enrolControlPlanePrincipal({ name: 'celilo-web-console', publicKey: PUBLIC_KEY });
+    const second = await enrolControlPlanePrincipal({
+      name: 'celilo-web-console',
+      publicKey: PUBLIC_KEY,
+    });
+    expect(second.created).toBe(false);
+  });
+
+  test('a new key for an existing name ROTATES rather than duplicating', async () => {
+    // What a module that regenerated its keypair needs. Refusing it would leave
+    // a console that cannot authenticate and no way to fix it from the module.
+    await enrolControlPlanePrincipal({ name: 'celilo-web-console', publicKey: PUBLIC_KEY });
+    await enrolControlPlanePrincipal({ name: 'celilo-web-console', publicKey: OTHER_KEY });
+    expect((await getPrincipalByName('celilo-web-console'))?.publicKey).toBe(OTHER_KEY);
+  });
+
+  test('a malformed public key is refused here, not at login', async () => {
+    // Otherwise it lands in authorized_keys and fails later with a message
+    // about SSH rather than about the thing that was wrong.
+    await expect(
+      enrolControlPlanePrincipal({ name: 'celilo-web-console', publicKey: 'not-a-key' }),
+    ).rejects.toThrow();
+  });
+});
+
+describe('what the enrolled principal may actually do', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    // The service reaches for the global `getDb()`, so isolation is by
+    // CELILO_DB_PATH rather than by passing a client around.
+    dir = mkdtempSync(join(tmpdir(), 'celilo-cpa-'));
+    process.env.CELILO_DB_PATH = join(dir, 'test.db');
+    closeDb();
+    await enrolControlPlanePrincipal({ name: 'celilo-web-console', publicKey: PUBLIC_KEY });
+  });
+
+  afterEach(() => {
+    closeDb();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('may run the console reads it exists for', async () => {
+    expect(await isAuthorized('celilo-web-console', 'console', 'status')).toBe(true);
+    expect(await isAuthorized('celilo-web-console', 'console', 'get')).toBe(true);
+  });
+
+  test('may run the other reads the console polls', async () => {
+    // `alerts:list`, not bare `alerts`. The API authorises command:subcommand,
+    // so a caller that omits the subcommand is refused — which is what the
+    // console server did until this test caught it.
+    expect(await isAuthorized('celilo-web-console', 'alerts', 'list')).toBe(true);
+    expect(await isAuthorized('celilo-web-console', 'alerts')).toBe(false);
+    expect(await isAuthorized('celilo-web-console', 'backup', 'list')).toBe(true);
+  });
+
+  test('may NOT deploy a module', async () => {
+    // The whole point. Everything above is convenience; this is the boundary.
+    expect(await isAuthorized('celilo-web-console', 'module', 'deploy')).toBe(false);
+  });
+
+  test('may NOT uninstall, restore, or grant', async () => {
+    expect(await isAuthorized('celilo-web-console', 'module', 'remove')).toBe(false);
+    expect(await isAuthorized('celilo-web-console', 'backup', 'restore')).toBe(false);
+    expect(await isAuthorized('celilo-web-console', 'api', 'grant')).toBe(false);
+  });
+});
+
+describe('revocation', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    // The service reaches for the global `getDb()`, so isolation is by
+    // CELILO_DB_PATH rather than by passing a client around.
+    dir = mkdtempSync(join(tmpdir(), 'celilo-cpa-'));
+    process.env.CELILO_DB_PATH = join(dir, 'test.db');
+    closeDb();
+  });
+
+  afterEach(() => {
+    closeDb();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('removes the principal, so an uninstalled console leaves no working key', async () => {
+    await enrolControlPlanePrincipal({ name: 'celilo-web-console', publicKey: PUBLIC_KEY });
+    expect(await revokeControlPlanePrincipal('celilo-web-console')).toBe(true);
+    expect(await getPrincipalByName('celilo-web-console')).toBeNull();
+  });
+
+  test('revoking one that is already gone is false, not a throw', async () => {
+    // An uninstall that fails on tidy-up is worse than one finding nothing to
+    // tidy, and a hook that throws here leaves the module half-removed.
+    expect(await revokeControlPlanePrincipal('never-existed')).toBe(false);
+  });
+});

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

@@ -0,0 +1,103 @@
+/**
+ * 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 { 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);
+}

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);
 }