@celilo/cli 1.13.0 → 1.14.0

package/src/cli/index.ts

@@ -124,6 +124,7 @@ import { handleSystemAudit } from './commands/system-audit';
 import { handleSystemConfigGet, handleSystemConfigSet } from './commands/system-config';
 import { handleSystemDiscoverNetwork } from './commands/system-discover-network';
 import { handleSystemDoctor } from './commands/system-doctor';
+import { handleSystemEnsureFleetKey } from './commands/system-ensure-fleet-key';
 import { handleSystemInit } from './commands/system-init';
 import { handleSystemMigrate } from './commands/system-migrate';
 import { handleSystemSecretGet } from './commands/system-secret-get';
@@ -1122,6 +1123,7 @@ Subcommands:
                                        to define, not a module's.
 
   discover-network                     Record the network this box sits on, from its own routing table (idempotent)
+  ensure-fleet-key                     Mint celilo's fleet SSH key if absent, record ssh.public_key, print the public half
 
   config set <key> <value>             Set system-wide configuration value
   config get [key]                     Get system configuration value(s)
@@ -2221,6 +2223,10 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
       return handleSystemDiscoverNetwork();
     }
 
+    if (parsed.subcommand === 'ensure-fleet-key') {
+      return handleSystemEnsureFleetKey();
+    }
+
     if (parsed.subcommand === 'config') {
       const configSubcommand = parsed.args[0];
       if (!configSubcommand) {

package/src/console/closure.test.ts

@@ -232,6 +232,82 @@ describe('the walk follows real bindings, not declarations', () => {
     expect(result.nodes.map((n) => n.moduleId)).toEqual(['iptables']);
   });
 
+  test('a delegated provider is reached, though no manifest names it', () => {
+    // The case the whole chain exists for. `app` is BOUND to iptables, so the
+    // manifest walk stops there and the ISP router the packet actually leaves
+    // through never appears — even though iptables cannot reach the internet
+    // without it. celilo wires that edge at hook time; nothing declares it.
+    const multi: ProviderRow[] = [
+      { moduleId: 'iptables', capabilityName: 'firewall' },
+      { moduleId: 'axon', capabilityName: 'firewall' },
+    ];
+    const result = computeClosure({
+      rootModuleId: 'app',
+      manifests: new Map([
+        ['app', manifest({ requires: ['firewall'] })],
+        ['iptables', manifest({})],
+        ['axon', manifest({})],
+      ]),
+      providerRows: multi,
+      providerStates: deployed('iptables', 'axon'),
+      bindings: new Map([['app', new Map([['firewall', 'iptables']])]]),
+      chains: [{ capability: 'firewall', moduleIds: ['iptables', 'axon'] }],
+    });
+
+    expect(result.nodes.map((n) => n.moduleId)).toEqual(['iptables', 'axon']);
+    // Hop 2, because it is reached THROUGH iptables. Not a second hop-1
+    // dependency of the selection, which is what a fan would say.
+    expect(result.nodes.find((n) => n.moduleId === 'axon')?.hop).toBe(2);
+    // A packet has no alternative route to the internet.
+    expect(result.nodes.find((n) => n.moduleId === 'axon')?.optional).toBe(false);
+    expect(result.chains).toEqual([{ capability: 'firewall', moduleIds: ['iptables', 'axon'] }]);
+  });
+
+  test('a chain the walk never touched is not reported', () => {
+    // The chain is a fleet fact and the closure is about one module. A selection
+    // that consumes no firewall stands on none of it.
+    const result = computeClosure({
+      rootModuleId: 'site',
+      manifests,
+      providerRows: rows,
+      providerStates: deployed('cpanel', 'caddy', 'forgejo'),
+      chains: [{ capability: 'firewall', moduleIds: ['iptables', 'axon'] }],
+    });
+
+    expect(result.chains).toEqual([]);
+  });
+
+  test('the depth bound cuts a delegated provider like any other', () => {
+    // Three layers, bounded at two, so the LAST link is the one the bound cuts.
+    // The delegation edges are walked inside the same loop as the declared ones
+    // and get the same bound; a rule applied after the walk would smuggle the
+    // whole chain into a two-hop answer.
+    //
+    // A two-layer chain would not test this. `iptables` is the only declared
+    // dependency, so the walk exhausts at hop 2 whether or not the delegation
+    // is followed, and the assertion would hold for the wrong reason.
+    const result = computeClosure({
+      rootModuleId: 'app',
+      manifests: new Map([
+        ['app', manifest({ requires: ['firewall'] })],
+        ['iptables', manifest({})],
+        ['mid', manifest({})],
+        ['axon', manifest({})],
+      ]),
+      providerRows: [{ moduleId: 'iptables', capabilityName: 'firewall' }],
+      providerStates: deployed('iptables', 'mid', 'axon'),
+      depth: 2,
+      chains: [{ capability: 'firewall', moduleIds: ['iptables', 'mid', 'axon'] }],
+    });
+
+    expect(result.nodes.map((n) => n.moduleId)).toEqual(['iptables', 'mid']);
+    expect(result.truncated).toBe(true);
+    // Still reported WHOLE, including the member past the bound. Half a path is
+    // not a path, and the operator asked to see less, not to be told the packet
+    // stops at `mid`.
+    expect(result.chains[0]?.moduleIds).toEqual(['iptables', 'mid', 'axon']);
+  });
+
   test('a module with no bindings at all depends on nothing', () => {
     const result = computeClosure({
       rootModuleId: 'site',

package/src/console/closure.ts

@@ -57,6 +57,32 @@ export interface ClosureRequest {
    * without a database, not so the distinction is optional.
    */
   bindings?: ReadonlyMap<string, ReadonlyMap<string, string>>;
+  /**
+   * Ordered provider chains, most downstream first.
+   *
+   * These are edges NO MANIFEST DECLARES. celilo wires the `firewall`
+   * providers into a chain at hook time from `has_external`, so `iptables`
+   * genuinely stands on `axon` while neither manifest says a word about the
+   * other. A walk over manifests alone stops at `iptables`, and the box the
+   * packet actually leaves through never appears in the answer.
+   *
+   * Supplied by the caller rather than derived here so this stays pure. The CLI
+   * reads them with `loadFirewallChain`.
+   */
+  chains?: readonly DelegationChain[];
+}
+
+/**
+ * One capability's providers in delegation order.
+ *
+ * Ordered because for `firewall` they are not alternatives: the order is the
+ * packet's path. Same shape as the console protocol's `DelegationChain`, so the
+ * server hands it on rather than translating it.
+ */
+export interface DelegationChain {
+  capability: string;
+  /** Module ids, most downstream first. */
+  moduleIds: string[];
 }
 
 export interface ClosureNode {
@@ -78,6 +104,15 @@ export interface ClosureNode {
 
 export interface ClosureResult {
   nodes: ClosureNode[];
+  /**
+   * The delegation chains this closure touched, whole.
+   *
+   * A chain is emitted when the walk reached ANY of its members, and it carries
+   * every member rather than only the reached ones, because half a path is not
+   * a path. Empty means the closure touched no chain — which, now that
+   * something computes them, is an answer rather than a gap.
+   */
+  chains: DelegationChain[];
   /** Hops actually walked. Echoes the request so the console can say what it bounded. */
   depth: number;
   /**
@@ -107,10 +142,35 @@ function optionalCapabilityNames(manifest: ConsumedCapabilities): Set<string> {
   );
 }
 
+/**
+ * A chain's consecutive pairs, as edges out of each member.
+ *
+ * `[iptables, axon]` becomes one edge `iptables -> axon`. The last member has
+ * no edge out of it: it is the internet-facing end and delegates to nothing.
+ */
+function delegationEdgesByModule(
+  chains: readonly DelegationChain[],
+): Map<string, { to: string; capability: string }[]> {
+  const byModule = new Map<string, { to: string; capability: string }[]>();
+  for (const chain of chains) {
+    for (let i = 0; i + 1 < chain.moduleIds.length; i += 1) {
+      const from = chain.moduleIds[i];
+      const to = chain.moduleIds[i + 1];
+      if (from === undefined || to === undefined) continue;
+      const out = byModule.get(from) ?? [];
+      out.push({ to, capability: chain.capability });
+      byModule.set(from, out);
+    }
+  }
+  return byModule;
+}
+
 export function computeClosure(request: ClosureRequest): ClosureResult {
   const depth = request.depth ?? DEFAULT_CLOSURE_DEPTH;
   const providerRows = [...request.providerRows];
   const providerStates = [...request.providerStates];
+  const chains = request.chains ?? [];
+  const delegationsOut = delegationEdgesByModule(chains);
 
   const edges: Edge[] = [];
   // The root counts as visited from the start, so a cycle back to it terminates
@@ -165,10 +225,36 @@ export function computeClosure(request: ClosureRequest): ClosureResult {
         }
       }
     }
+
+    // The edges the manifests do not carry. Followed here, inside the same loop,
+    // so a delegated provider gets its hop, its cycle check and its depth bound
+    // from the one walk rather than from a second rule applied afterwards.
+    //
+    // Never optional: a packet has no alternative route to the internet, so a
+    // delegation is the strongest kind of dependency there is.
+    for (const moduleId of frontier) {
+      for (const edge of delegationsOut.get(moduleId) ?? []) {
+        if (edge.to === request.rootModuleId) continue;
+        edges.push({ to: edge.to, hop, capability: edge.capability, optional: false });
+        if (!visited.has(edge.to)) {
+          visited.add(edge.to);
+          next.push(edge.to);
+        }
+      }
+    }
+
     frontier = next;
   }
 
-  return { nodes: collectNodes(edges), depth, truncated };
+  const nodes = collectNodes(edges);
+  const reached = new Set([request.rootModuleId, ...nodes.map((node) => node.moduleId)]);
+
+  return {
+    nodes,
+    chains: chains.filter((chain) => chain.moduleIds.some((id) => reached.has(id))),
+    depth,
+    truncated,
+  };
 }
 
 /**

package/src/console/projection.test.ts

@@ -8,7 +8,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import type { DbClient } from '../db/client';
 import { NETWORK_ZONES } from '../db/schema';
 import { cleanupTestDatabase, setupTestDatabase } from '../test-utils/database';
-import { consoleStatus } from './projection';
+import { consoleStatus, loadClosureInputs } from './projection';
 
 /** A manifest big enough to notice if it ever leaked into the payload. */
 const FAT_MANIFEST = JSON.stringify({
@@ -229,3 +229,65 @@ describe('consoleStatus derived facts', () => {
     expect(moduleOf('forgejo').backupStale).toBe(true);
   });
 });
+
+/**
+ * The reach probe for the chain (CLAUDE.md, "a check that cannot reach the
+ * thing it is checking").
+ *
+ * `orderFirewallChain` is unit-tested against hand-built rows. That says
+ * nothing about whether the closure's loader queries the right table with the
+ * right filter, and a wrong query here returns a well-formed empty list that
+ * reads exactly like a fleet with one firewall. So this drives the REAL loader
+ * against real `capabilities` rows.
+ */
+describe('loadClosureInputs, and the chain it carries', () => {
+  let db: DbClient;
+
+  beforeEach(async () => {
+    db = await setupTestDatabase();
+    for (const id of ['iptables', 'axon', 'caddy']) {
+      db.$client.run(
+        `INSERT INTO modules (id, name, version, source_path, manifest_data, state)
+         VALUES ('${id}', '${id}', '1.0.0', '/path', '{}', 'VERIFIED')`,
+      );
+    }
+  });
+
+  afterEach(async () => {
+    await cleanupTestDatabase(db);
+  });
+
+  function firewallProvider(moduleId: string, data: string) {
+    db.$client.run(
+      `INSERT INTO capabilities (module_id, capability_name, version, data)
+       VALUES ('${moduleId}', 'firewall', '1.0.0', '${data}')`,
+    );
+  }
+
+  test('reads the live registration and orders it, iptables first', () => {
+    firewallProvider('iptables', '{"firewall_ip":"192.168.0.254","nat_ip":"192.168.0.253"}');
+    firewallProvider('axon', '{"has_external":true,"router_ip":"192.168.0.1"}');
+
+    expect(loadClosureInputs(db).chains).toEqual([
+      { capability: 'firewall', moduleIds: ['iptables', 'axon'] },
+    ]);
+  });
+
+  test('a non-firewall capability is not swept into the chain', () => {
+    // `axon` provides dhcp_server too. A loader that read every row would put a
+    // module in the packet's path on the strength of an unrelated capability.
+    firewallProvider('iptables', '{"firewall_ip":"192.168.0.254","nat_ip":"192.168.0.253"}');
+    firewallProvider('axon', '{"has_external":true}');
+    db.$client.run(
+      `INSERT INTO capabilities (module_id, capability_name, version, data)
+       VALUES ('caddy', 'public_web', '1.0.0', '{}')`,
+    );
+
+    expect(loadClosureInputs(db).chains[0]?.moduleIds).toEqual(['iptables', 'axon']);
+  });
+
+  test('a fleet with one firewall has no chain', () => {
+    firewallProvider('axon', '{"has_external":true}');
+    expect(loadClosureInputs(db).chains).toEqual([]);
+  });
+});

package/src/console/projection.ts

@@ -14,16 +14,25 @@
  * succeed quietly.
  */
 
+import { FIREWALL_CAPABILITY_NAME, orderFirewallChain } from '@celilo/capabilities';
 import { desc, eq } from 'drizzle-orm';
 import { z } from 'zod';
 import type { DbClient } from '../db/client';
-import { NETWORK_ZONES, backups, moduleSystems, modules, monitors } from '../db/schema';
+import {
+  NETWORK_ZONES,
+  backups,
+  capabilities,
+  moduleSystems,
+  modules,
+  monitors,
+} from '../db/schema';
 import { loadObservedHealthDetail } from '../services/alerting/observed-health';
 import { loadBackupAuditInfo } from '../services/audit/backup-source';
 import { backupStaleThresholdMs, moduleHasBackupHook } from '../services/audit/backups';
 import { effectiveBackupSchedule } from '../services/backup-schedule';
 import { listCapabilityBindings } from '../services/capability-bindings';
 import type { ConsumedCapabilities } from '../services/consumer-cleanup';
+import type { DelegationChain } from './closure';
 
 /**
  * Just the capability lists, validated at the boundary.
@@ -302,10 +311,18 @@ export function loadBindings(db: DbClient, moduleId: string): Map<string, string
   );
 }
 
-/** Everything the closure walk needs, read in one place. */
+/**
+ * Everything the closure walk needs, read in ONE place.
+ *
+ * The chains are in here rather than beside it deliberately. A separate loader
+ * a caller has to remember is a caller that forgets, and the answer when it
+ * forgets is an empty chain list that reads exactly like a fleet with no
+ * delegation. There is one call site, and it cannot get a partial set.
+ */
 export function loadClosureInputs(db: DbClient): {
   manifests: Map<string, ConsumedCapabilities>;
   providerStates: { moduleId: string; state: string }[];
+  chains: DelegationChain[];
 } {
   return {
     manifests: new Map(
@@ -316,9 +333,29 @@ export function loadClosureInputs(db: DbClient): {
         .map((row) => [row.id, CONSUMED_CAPABILITIES.parse(row.manifestData)] as const),
     ),
     providerStates: db.select({ moduleId: modules.id, state: modules.state }).from(modules).all(),
+    chains: loadFirewallChain(db),
   };
 }
 
+/**
+ * The `firewall` providers in delegation order, as at most one chain.
+ *
+ * At most one because `firewall` is the only capability celilo chains, and
+ * `orderFirewallChain` — the SAME function the hook loader wires the live
+ * providers with — is what decides the order. A fleet with one firewall, or
+ * with none that reaches the internet, yields no chain at all.
+ */
+export function loadFirewallChain(db: DbClient): DelegationChain[] {
+  const providers = db
+    .select({ moduleId: capabilities.moduleId, data: capabilities.data })
+    .from(capabilities)
+    .where(eq(capabilities.capabilityName, FIREWALL_CAPABILITY_NAME))
+    .all();
+
+  const ordered = orderFirewallChain(providers).map((provider) => provider.moduleId);
+  return ordered.length === 0 ? [] : [{ capability: FIREWALL_CAPABILITY_NAME, moduleIds: ordered }];
+}
+
 /** A module's row, or undefined. Used to reject a closure request for a module that is gone. */
 export function moduleExists(db: DbClient, moduleId: string): boolean {
   return (

package/src/hooks/capability-loader-control-plane-api.test.ts

@@ -0,0 +1,124 @@
+/**
+ * `control_plane_api` reaches a consuming module, and only a consuming module.
+ *
+ * The rest of `loadCapabilityFunctions` hands over every capability it can
+ * build, declared or not — its own comment says "not just required ones", and
+ * `capability-loader-bindings.test.ts` asserts that shape deliberately. That is
+ * fine for a capability whose worst outcome is an unused OIDC client.
+ *
+ * This one mints an SSH principal into celilo's own control plane, so it is
+ * gated on the `requires` line instead. These pin both halves, because the
+ * failure that matters is silent in both directions: a console that declared it
+ * and got nothing fails at install with "no provider is loaded" for a capability
+ * no module ever provides, and a module that declared nothing and got it anyway
+ * holds control-plane read that no manifest review would have shown.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import type { HookLogger } from '@celilo/capabilities';
+import type { DbClient } from '../db/client';
+import { cleanupTestDatabase, setupTestDatabase } from '../test-utils/database';
+import { loadCapabilityFunctions } from './capability-loader';
+
+const noopLogger: HookLogger = {
+  info() {},
+  warn() {},
+  error() {},
+  success() {},
+};
+
+function installModule(db: DbClient, moduleId: string, manifest: Record<string, unknown>): void {
+  db.$client.run(
+    `INSERT INTO modules (id, name, version, source_path, manifest_data) VALUES (?, ?, '1.0.0', '/tmp/${moduleId}', ?)`,
+    [moduleId, moduleId, JSON.stringify(manifest)],
+  );
+}
+
+const DECLARES = {
+  requires: { capabilities: [{ name: 'control_plane_api', version: '1.0.0' }] },
+};
+
+describe('control_plane_api injection', () => {
+  let db: DbClient;
+
+  beforeEach(async () => {
+    db = await setupTestDatabase();
+  });
+
+  afterEach(async () => {
+    await cleanupTestDatabase(db);
+  });
+
+  test('a module that requires it gets it, with no provider module deployed', async () => {
+    // The point of the whole decision: nothing provides this capability, and it
+    // is still there. A test that first deployed a provider would be measuring
+    // the ordinary path.
+    installModule(db, 'celilo-web-console', DECLARES);
+
+    const capabilities = await loadCapabilityFunctions('celilo-web-console', db, noopLogger);
+
+    expect(capabilities.control_plane_api).toBeTruthy();
+    const api = capabilities.control_plane_api as Record<string, unknown>;
+    expect(typeof api.enrol_principal).toBe('function');
+    expect(typeof api.revoke_principal).toBe('function');
+  });
+
+  test('a module that declares it as optional gets it too', async () => {
+    // `optional` is a declaration a reviewer reads on the same line of the same
+    // file. Treating it as no declaration would fail the module at runtime for a
+    // capability its manifest names.
+    installModule(db, 'someday-console', {
+      optional: { capabilities: [{ name: 'control_plane_api', version: '1.0.0' }] },
+    });
+
+    const capabilities = await loadCapabilityFunctions('someday-console', db, noopLogger);
+
+    expect(capabilities.control_plane_api).toBeTruthy();
+  });
+
+  test('a module that declares nothing does NOT get it', async () => {
+    installModule(db, 'hello-foo', { requires: { capabilities: [] } });
+
+    const capabilities = await loadCapabilityFunctions('hello-foo', db, noopLogger);
+
+    expect(capabilities.control_plane_api).toBeUndefined();
+  });
+
+  test('a module that requires something ELSE does NOT get it', async () => {
+    // The near miss: a manifest with a populated `requires` block is the shape a
+    // too-loose check ("does this module require anything?") would wave through.
+    installModule(db, 'hello-bar', {
+      requires: { capabilities: [{ name: 'idp', version: '1.0.0' }] },
+    });
+
+    const capabilities = await loadCapabilityFunctions('hello-bar', db, noopLogger);
+
+    expect(capabilities.control_plane_api).toBeUndefined();
+  });
+
+  test('a module celilo has no record of does NOT get it', async () => {
+    // A hook can run for a module id with no row (a removal path, a typo). The
+    // manifest lookup returns nothing, and "no manifest" must read as "declared
+    // nothing" rather than throwing or defaulting open.
+    const capabilities = await loadCapabilityFunctions('never-imported', db, noopLogger);
+
+    expect(capabilities.control_plane_api).toBeUndefined();
+  });
+
+  test('the injected object is scoped to the module it was built for', async () => {
+    // Scoping is what stops a module rotating a neighbour's key. It is asserted
+    // through the loader rather than only on `buildControlPlaneApi`, because the
+    // loader is where the wrong argument (a provider id, a hook name) would be
+    // passed.
+    installModule(db, 'hello-foo', DECLARES);
+
+    const capabilities = await loadCapabilityFunctions('hello-foo', db, noopLogger);
+    const api = capabilities.control_plane_api as {
+      revoke_principal(request: { name: string }): Promise<unknown>;
+    };
+
+    await expect(api.revoke_principal({ name: 'celilo-web-console' })).rejects.toThrow(
+      /only revoke its own principal/,
+    );
+  });
+});

package/src/hooks/capability-loader.ts

@@ -15,6 +15,7 @@ import { join } from 'node:path';
 import {
   createPublicWeb,
   isCompiledCapabilityFactory,
+  orderFirewallChain,
   wrapWithLogging,
 } from '@celilo/capabilities';
 import type {
@@ -38,8 +39,10 @@ import {
   systemConfig,
   webRoutes,
 } from '../db/schema';
+import { resolveModuleWebRoot } from '../module/web-root';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
+import { buildControlPlaneApi } from '../services/api-principal-enrolment';
 import { recordCapabilityBinding, withBindingRecord } from '../services/capability-bindings';
 import { emitWebRoutesChangedAndWait } from '../services/celilo-events';
 import { getModuleSystems } from '../services/deployed-systems';
@@ -219,6 +222,26 @@ export async function resolveCaddyZoneIp(db: DbClient): Promise<string | undefin
   return undefined;
 }
 
+/**
+ * Does this module's manifest declare `capabilityName`, under `requires` or
+ * `optional`?
+ *
+ * Reads the manifest stored at import rather than the one on disk, so the
+ * answer is the one the operator's `module import` actually validated.
+ */
+function consumerDeclares(db: DbClient, moduleId: string, capabilityName: string): boolean {
+  const row = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  const manifest = row?.manifestData;
+  if (!manifest) return false;
+
+  type Declarations = { capabilities?: { name?: string }[] } | undefined;
+  const declared = [
+    ...((manifest.requires as Declarations)?.capabilities ?? []),
+    ...((manifest.optional as Declarations)?.capabilities ?? []),
+  ];
+  return declared.some((cap) => cap?.name === capabilityName);
+}
+
 export async function loadCapabilityFunctions(
   consumingModuleId: string,
   db: DbClient,
@@ -380,6 +403,11 @@ export async function loadCapabilityFunctions(
           // which made a module-provided capability structurally unable to
           // offer `unregisterRoutes()`-style methods.
           consumerModuleId: consumingModuleId,
+          // WHERE THE CALLER'S BYTES ARE, for the same reason and by the same
+          // seam. `private_web` and `external_web` publish static sites too, and
+          // without this they could not find the caller's web root now that
+          // `sourceDir` has left the request (D10 amendment).
+          consumerWebRoot: resolveModuleWebRoot(consumingModuleId, db),
         });
         // Stamp here too, not only on the legacy path: a consumer that cannot
         // get what it needs must be able to name WHICH provider could not give
@@ -563,6 +591,9 @@ export async function loadCapabilityFunctions(
       providerByCapability.set(provider.capabilityName, provider.moduleId);
       result.public_web = createPublicWeb({
         moduleId: consumingModuleId,
+        // Resolved here, not in the capability: on a converge there is no
+        // consumer process to ask (D10 amendment).
+        webRoot: resolveModuleWebRoot(consumingModuleId, db),
         logger,
         config: providerConfig,
         secrets: providerSecrets,
@@ -641,6 +672,30 @@ export async function loadCapabilityFunctions(
     debugLog('public_web: not registered in DB, skipping');
   }
 
+  // Framework-granted, so unlike everything above there is no provider row to
+  // look up and no script to import — celilo IS the management server whose
+  // principals these are (web-ui-console D7b).
+  //
+  // Gated on the DECLARATION, which the rest of this function deliberately is
+  // not: the loop injects every capability it can build "not just required
+  // ones", so a module that never asked still gets `idp` and `firewall`. That is
+  // fine for a capability whose worst outcome is an unused OIDC client. This one
+  // mints an SSH principal into celilo's own control plane, so the `requires`
+  // line is the authorization and a module that did not write one does not get
+  // the object at all.
+  if (consumerDeclares(db, consumingModuleId, 'control_plane_api')) {
+    // Wrapped like every other capability, so an enrolment that fails mid-deploy
+    // leaves a `✗ control_plane_api.enrol_principal` in the hook log rather than
+    // only a thrown error further up. The `defineCapabilityFunction` path wraps
+    // itself; a framework-built table has to be wrapped here.
+    result.control_plane_api = wrapWithLogging(
+      buildControlPlaneApi(consumingModuleId),
+      logger,
+      'control_plane_api',
+    );
+    debugLog(`control_plane_api: framework-granted, injected for ${consumingModuleId}`);
+  }
+
   // celilo#1072: the CALL is the binding, not the resolution. Everything above
   // is injected whether or not the consumer declared it — the loop's own
   // comment says "not just required ones" — so recording what was resolved
@@ -1104,20 +1159,19 @@ async function buildFirewallChain(
   // attributable. Only the layers that render their own ruleset receive it.
   const trustedSourceStore = buildTrustedSourceStore(db, consumingModuleId);
 
-  // Find the provider with has_external (the leaf — has direct internet access)
-  const hasExternal = allProviders.find((p) => {
-    const data = (typeof p.data === 'string' ? JSON.parse(p.data) : p.data) as Record<
-      string,
-      unknown
-    >;
-    return data.has_external === true;
-  });
+  // The delegation order, most downstream first. Shared with the console's
+  // closure so the wiring and the picture cannot disagree about which firewall
+  // stands on which — see `orderFirewallChain`.
+  const chainOrder = orderFirewallChain(allProviders);
 
-  if (!hasExternal) {
+  if (chainOrder.length === 0) {
     debugLog('firewall chain: no provider with external interface found');
     return { chain: null, self: null };
   }
 
+  // The leaf is the upstream end: the provider with the direct internet leg.
+  const hasExternal = chainOrder[chainOrder.length - 1] as (typeof chainOrder)[number];
+
   // Build the leaf (external) firewall first
   const leafModule = db.select().from(modules).where(eq(modules.id, hasExternal.moduleId)).get();
   if (!leafModule) return { chain: null, self: null };
@@ -1173,7 +1227,10 @@ async function buildFirewallChain(
   // Build downstream providers, wiring each to the upstream. iptables
   // remains a legacy factory because its second arg (upstreamFirewall)
   // doesn't fit defineCapabilityFunction's single-context shape.
-  const downstream = allProviders.filter((p) => p.moduleId !== hasExternal.moduleId);
+  // Back into wiring order: each layer is built taking the previous one as its
+  // upstream, so the build runs from the leaf outwards while the chain reads
+  // from the consumer inwards.
+  const downstream = chainOrder.slice(0, -1).reverse();
 
   // Each layer as its OWN provider sees it, so `on_consumer_removed` converges
   // the firewall that declares the hook rather than whichever layer a consumer