@celilo/cli 1.12.0 → 1.13.0

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

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/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)