@celilo/cli 1.12.0 → 1.14.0

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/module/web-root.ts

@@ -0,0 +1,35 @@
+/**
+ * Where a module's built web site lives on this host.
+ *
+ * ONE application of the `site/dist` convention. It is deliberately not applied
+ * inside the providers: `public_web` is framework-provided, but `private_web`
+ * and `external_web` are implemented by modules (`caddy-internal`,
+ * `generic-cpanel-hosting-provider`), and three copies of one convention is how
+ * the copies drift.
+ *
+ * Core is also the only party that CAN resolve it in the case that matters.
+ * When the `public_web` provider converges a rebuilt host, no consumer is
+ * running to be asked where its bytes are (design D10). So the path has to come
+ * from the module id, and `modules.source_path` is what core already holds.
+ */
+
+import { join } from 'node:path';
+import { MODULE_WEB_ROOT } from '@celilo/capabilities';
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { modules } from '../db/schema';
+
+/**
+ * Absolute path to `<module root>/site/dist`, or undefined when no such module
+ * is installed.
+ *
+ * Does NOT check that the directory exists. Resolving a path and deciding
+ * whether it is usable are different jobs, and the second one belongs where the
+ * error can name the caller (Rule 10.1). `createPublicWeb`'s `requireWebRoot`
+ * does the existence check and says what to ship.
+ */
+export function resolveModuleWebRoot(moduleId: string, db: DbClient): string | undefined {
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) return undefined;
+  return join(module.sourcePath, MODULE_WEB_ROOT);
+}

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',
@@ -249,6 +255,18 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: "PERMANENT — validating a manifest's declared capability names against the registry is core's job",
   },
+  {
+    file: 'apps/celilo/src/manifest/validate.ts',
+    capability: 'control_plane_api',
+    count: 1,
+    why: 'PERMANENT — framework-granted, so celilo satisfies it and no module provides it; the resolver has to be told that by name (web-ui-console D7b)',
+  },
+  {
+    file: 'apps/celilo/src/hooks/capability-loader.ts',
+    capability: 'control_plane_api',
+    count: 4,
+    why: "PERMANENT — framework-granted like web_routes above; core builds the method table because enrolment writes celilo's own api_principals row, which no module script can reach (web-ui-console D7b)",
+  },
   {
     file: 'apps/celilo/src/services/alerting/inbound-poller.ts',
     capability: 'notification',
@@ -327,6 +345,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',
@@ -408,8 +432,8 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
   {
     file: 'packages/capabilities/src/firewall.ts',
     capability: 'firewall',
-    count: 2,
-    why: 'PERMANENT — X10, the firewall capability contract',
+    count: 3,
+    why: 'PERMANENT — X10, the firewall capability contract. The third is FIREWALL_CAPABILITY_NAME, exported so core queries the provider registry without spelling the literal; it moved a name OUT of apps/celilo/src/console/projection.ts rather than adding one',
   },
   {
     file: 'packages/capabilities/src/public-web.ts',

package/src/policy/module-script-scan.test.ts

@@ -38,6 +38,28 @@ describe('module script scan — SSH rules', () => {
   });
 });
 
+describe('module script scan — namespace tools (hygiene, not a boundary)', () => {
+  const NS = 'namespace escape (bwrap/unshare/nsenter)';
+
+  // Each token asserted separately and by name. An alternation that silently
+  // loses one leg still passes a test that only ever exercises the first.
+  it.each([
+    ['bwrap', 'run(`bwrap --dev-bind / / ${cmd}`);'],
+    ['unshare', "run('unshare --user --map-root-user id');"],
+    ['nsenter', "run('nsenter -t 1 -m -- ls /');"],
+    ['CLONE_NEWUSER', 'const flags = CLONE_NEWUSER | CLONE_NEWNS;'],
+  ])('catches %s', (_token, src) => {
+    expect(rules(src)).toContain(NS);
+  });
+
+  // The word boundaries are the whole of this rule's false-positive defence, so
+  // the negative case has to be a word that CONTAINS a token. `buildSharedConfig`
+  // would pass whether or not the `\b`s are there, which makes it no test at all.
+  it('does not fire on an identifier that merely contains a token', () => {
+    expect(rules('const unshared = pending.filter((p) => !p.shared);')).toEqual([]);
+  });
+});
+
 describe('module script scan — raw-exec escape hatch', () => {
   it('flags a runAppCommand call with no justification', () => {
     expect(rules('const r = runAppCommand(system, "rm -f /tmp/x", run);')).toContain(

package/src/policy/module-script-scan.ts

@@ -3,6 +3,11 @@
  * **modules never hand-build SSH, and the one sanctioned raw-exec path is
  * always justified in writing.**
  *
+ * It carries a second, weaker rule class as well — the namespace-tool rule
+ * below. Read that rule's own comment before touching it: it is hygiene and it
+ * is **not** a boundary, and the two classes in this file are not the same kind
+ * of thing.
+ *
  * ONE definition of the rules, used by both enforcement points:
  *
  *   - `apps/celilo/src/policy/no-hand-built-ssh.test.ts` — every in-repo module,
@@ -63,6 +68,33 @@ const PATTERN_RULES: Array<{ rule: string; re: RegExp; hint: string }> = [
     re: /(?:from|require\()\s*['"]ssh2['"]/,
     hint: 'Modules never open their own SSH connection — use the primitives. See MODULE_PRIMITIVES.md.',
   },
+  /**
+   * HYGIENE, NOT A MITIGATION (openspec/changes/hook-process-boundary, task 4.2e,
+   * design D9). The boundary is the jail; this line is a courtesy to an honest
+   * author, and describing it as a security control would be a lie in three
+   * separate ways:
+   *
+   *   - a hook runs arbitrary code, so anything this pattern catches can be
+   *     spelled another way by anyone who wants to;
+   *   - the scan walks in-repo `scripts/` and staged `.netapp` payloads, so it
+   *     never sees a registry module or an out-of-repo one at all;
+   *   - celilo#1014 is a live example of an exemption in this very file reading
+   *     wider than its author intended.
+   *
+   * What it is for: a module that shells out to `bwrap`/`unshare`/`nsenter`
+   * gets a namespace it is uid 0 in, and under the jail that either fails or
+   * nests badly. Telling the author at package time beats a confusing runtime
+   * failure on the fleet. Task 4.2d is the related-but-different guarantee, and
+   * it IS load-bearing: `bwrap` is never in the derived mount set.
+   */
+  {
+    rule: 'namespace escape (bwrap/unshare/nsenter)',
+    re: /\b(?:bwrap|unshare|nsenter)\b|CLONE_NEWUSER/,
+    hint:
+      'Hooks already run inside a namespace celilo builds; a module creating its own is ' +
+      'not supported and will not survive the jail. This is a hygiene check, not a security ' +
+      'boundary. If you need isolation the framework does not give you, say what for.',
+  },
 ];
 
 /** A `runAppCommand(` / `runAppCommandWithSecret(` CALL — not the import. */

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,252 @@
+/**
+ * `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 {
+  buildControlPlaneApi,
+  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);
+  });
+});
+
+describe('the capability handed to a consuming module', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    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('enrols the caller and reports the grants it may use', async () => {
+    const api = buildControlPlaneApi('celilo-web-console');
+    const result = await api.enrol_principal({
+      name: 'celilo-web-console',
+      publicKey: PUBLIC_KEY,
+    });
+
+    expect(result.created).toBe(true);
+    expect(result.grants).toEqual(controlPlaneReadGrants());
+    expect(await getPrincipalByName('celilo-web-console')).not.toBeNull();
+  });
+
+  test('a module may NOT enrol under a neighbour’s name', async () => {
+    // Otherwise any module holding this capability rotates the console's key by
+    // presenting its own public half under the console's name — the console then
+    // holds a principal whose authorized_keys entry it cannot log in with, and
+    // the attacker holds one that works.
+    const api = buildControlPlaneApi('hello-foo');
+
+    await expect(
+      api.enrol_principal({ name: 'celilo-web-console', publicKey: PUBLIC_KEY }),
+    ).rejects.toThrow(/only enrol its own principal/);
+    expect(await getPrincipalByName('celilo-web-console')).toBeNull();
+  });
+
+  test('a module may NOT revoke a neighbour’s principal', async () => {
+    // The denial-of-service half of the same hole: revocation is idempotent and
+    // returns false for a name that never existed, so an unguarded revoke gives
+    // no signal at all that a module just deleted someone else's access.
+    await enrolControlPlanePrincipal({ name: 'celilo-web-console', publicKey: PUBLIC_KEY });
+    const api = buildControlPlaneApi('hello-foo');
+
+    await expect(api.revoke_principal({ name: 'celilo-web-console' })).rejects.toThrow(
+      /only revoke its own principal/,
+    );
+    expect(await getPrincipalByName('celilo-web-console')).not.toBeNull();
+  });
+
+  test('withdraws its own principal, and finding nothing is not an error', async () => {
+    const api = buildControlPlaneApi('celilo-web-console');
+    await api.enrol_principal({ name: 'celilo-web-console', publicKey: PUBLIC_KEY });
+
+    expect(await api.revoke_principal({ name: 'celilo-web-console' })).toEqual({ revoked: true });
+    expect(await api.revoke_principal({ name: 'celilo-web-console' })).toEqual({ revoked: false });
+  });
+
+  test('what it enrols cannot write, whatever the caller asked for', async () => {
+    // The grant set is not a parameter, so there is nothing to ask for. This
+    // asserts the consequence rather than the absence: the principal the
+    // capability produces is refused a deploy.
+    const api = buildControlPlaneApi('celilo-web-console');
+    await api.enrol_principal({ name: 'celilo-web-console', publicKey: PUBLIC_KEY });
+
+    expect(await isAuthorized('celilo-web-console', 'module', 'list')).toBe(true);
+    expect(await isAuthorized('celilo-web-console', 'module', 'deploy')).toBe(false);
+  });
+});