@celilo/cli 1.13.0 → 2.0.0

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,
@@ -574,6 +605,20 @@ export async function loadCapabilityFunctions(
         caddyModuleId: provider.moduleId,
         dnsManagedDomains,
         dnsRegistrarModuleId,
+        // Design D10: the bytes move through the provider's Ansible converge,
+        // not a hand-built ssh tar pipe. Core implements it over
+        // executeAnsible against the provider's generated project (task 4.3);
+        // awaited with everything else, so a publish returns only once the
+        // host matches. A failure here fails the deploy loudly — a publish
+        // that reports ready while the host never received the bytes is the
+        // exact "served but silently unreachable" anti-pattern.
+        convergeStaticContent: async () => {
+          const { convergeStaticContent } = await import('../services/static-content-converge');
+          const result = await convergeStaticContent(db, provider.moduleId);
+          if (!result.success) {
+            throw new Error(result.error ?? 'static-content converge failed');
+          }
+        },
         // ISS-0035: register_route/unregister_routes emit this coarse signal
         // instead of SSHing caddy; the caddy provider's reconcile_routes
         // subscription re-renders the Caddyfile from web_routes. We await the
@@ -641,6 +686,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 +1173,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 +1241,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

package/src/hooks/executor.ts

@@ -31,17 +31,19 @@
  * exists (a Mac today, task 4.8) the hook runs unjailed and the mode is
  * RECORDED, so a host that quietly stops jailing is visible rather than silent.
  *
- * Hooks still do NOT execute on the target machine. One that needs to touch a
- * target initiates SSH outbound itself, so anything it depends on (chromium,
- * system binaries, credentials) must be available on the celilo CLI host.
- * Stage 3 scopes that reachability and has not landed, which is why `~/.ssh`
- * is still bound into the jail read-only.
+ * Hooks still do NOT execute on the target machine — a remote operation is
+ * initiated from the celilo host. **Stage 3 has landed and scopes that
+ * reachability by the credential (design D12):** `~/.ssh` is not bound into
+ * the jail, so a hand-built `ssh` cannot authenticate, and the remote
+ * primitives cross to the remote-ops broker (`remote-broker.ts`), which holds
+ * the key and checks every target against the policy in
+ * `services/remote-access.ts` — the module's own systems, or the module's own
+ * credential.
  *
  * Execution function (Rule 10.1) - performs side effects (script execution)
  */
 
 import { existsSync, mkdirSync, readdirSync, rmdirSync, statSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import {
   type DeployedSystem,
@@ -59,8 +61,10 @@ import { isPrivilegedCapability } from '../manifest/validate';
 import { pruneModuleArtifacts } from './artifact-retention';
 import { startBroker } from './broker';
 import {
+  HOOK_MOUNT_SET_ENV,
   HOOK_PROTOCOL_VERSION,
   HOOK_PROTOCOL_VERSION_ENV,
+  HOOK_REMOTE_SOCKET_ENV,
   HOOK_SOCKET_ENV,
   createLineReader,
   deserializeError,
@@ -74,8 +78,15 @@ import {
   recordJailMode,
   runtimeModulePathsFor,
 } from './jail';
-import { type DeclaredPathInput, type MountSetRequest, deriveMountSet } from './mount-set';
+import {
+  type DeclaredPathInput,
+  type MountSet,
+  type MountSetRequest,
+  deriveMountSet,
+} from './mount-set';
+import { type RemoteAccessPolicy, startRemoteBroker } from './remote-broker';
 import type { HookContext, HookDefinition, HookLogger, HookResult } from './types';
+import { mountSetEnvValue } from './unjailed-lint';
 
 /** Default total timeout: 60 seconds */
 const DEFAULT_TIMEOUT_MS = 60_000;
@@ -160,6 +171,14 @@ const FORWARDED_ENV = [
 
 /** The shim celilo spawns. Resolved from here so an npm install finds it too. */
 const HOOK_RUNNER_PATH = join(import.meta.dir, 'hook-runner.ts');
+/**
+ * What celilo actually SPAWNS: the entry that installs the advisory lint
+ * before the runner shim's own import graph can load `node:fs` (task 4.7).
+ * The runner path above is still what the mount set binds — the entry and the
+ * shim live in the same directory and resolve through the same
+ * `node_modules`.
+ */
+const HOOK_RUNNER_SPAWN_PATH = join(import.meta.dir, 'hook-runner-entry.ts');
 
 /**
  * Validate hook inputs against a contract signature.
@@ -265,6 +284,13 @@ export interface ExecuteHookOptions {
   idleTimeoutMs?: number;
   /** What to jail this run with. Absent runs the hook unjailed. */
   jail?: HookJailInputs;
+  /**
+   * D12's target policy for this run's remote operations, built by the caller
+   * (`services/remote-access.ts`) so the executor stays decoupled from the
+   * database the same way it is for `systems`. Absent means every
+   * fleet-credential operation is REFUSED, naming the gap (Rule 6.4).
+   */
+  remoteAccess?: RemoteAccessPolicy;
 }
 
 /**
@@ -308,12 +334,27 @@ export async function executeHookScript(
     logger,
     onActivity: markActive,
   });
+  let remoteBroker: Awaited<ReturnType<typeof startRemoteBroker>> | undefined;
 
   try {
+    // The remote-ops socket lives beside the capability socket, so the jail's
+    // one socket-directory mount covers both channels (design D12).
+    const roots = remoteRoots(context, options.jail);
+    remoteBroker = await startRemoteBroker({
+      socketDir: dirname(broker.socketPath),
+      policy: options.remoteAccess,
+      readableRoots: roots.readable,
+      writableRoots: roots.writable,
+      logger,
+      onActivity: markActive,
+    });
+
+    const mountSet = options.jail
+      ? deriveMountSet(realpathRequest(jailRequest(options.jail, context, broker.socketPath)))
+      : undefined;
     const jail = planJailedSpawn(
-      [process.execPath, HOOK_RUNNER_PATH],
-      options.jail &&
-        deriveMountSet(realpathRequest(jailRequest(options.jail, context, broker.socketPath))),
+      [process.execPath, HOOK_RUNNER_SPAWN_PATH],
+      mountSet,
       detectJailBackend(),
       jailPolicy(),
     );
@@ -326,7 +367,13 @@ export async function executeHookScript(
 
     const child = Bun.spawn({
       cmd: [...jail.cmd],
-      env: hookChildEnv(broker.socketPath),
+      env: hookChildEnv(
+        broker.socketPath,
+        remoteBroker.socketPath,
+        // The lint rides only on an unjailed run — its presence in the child's
+        // environment is the shim's signal to install it (task 4.7).
+        jail.mode === 'unjailed' ? mountSet : undefined,
+      ),
       stdout: 'pipe',
       stderr: 'pipe',
     });
@@ -346,8 +393,10 @@ export async function executeHookScript(
       killedFor = reason;
       // Refuse capability calls FIRST. A hook between `kill` and its own death
       // can still have a call in flight, and answering it is exactly the
-      // failure this replaces.
+      // failure this replaces. The remote channel refuses for the same reason:
+      // a killed hook must not go on reaching systems (celilo#1003, D12).
       broker.stop();
+      remoteBroker?.stop();
       child.kill('SIGTERM');
       setTimeout(() => child.kill('SIGKILL'), SIGKILL_GRACE_MS).unref();
     };
@@ -398,10 +447,41 @@ export async function executeHookScript(
     if (!outcome.ok) throw deserializeError(outcome.error);
     return outcome.outputs;
   } finally {
+    // Remote first: its socket file lives inside the directory the capability
+    // broker's close removes.
+    remoteBroker?.close();
     broker.close();
   }
 }
 
+/**
+ * The local directories this run's stream primitives may touch (design D12).
+ *
+ * Derived from the same inputs as the jail's mount set, which is what keeps
+ * the two views from drifting: everything writable here is writable there,
+ * and a path outside these roots is a path the jailed hook could not see
+ * anyway — the broker writing to it would produce a file the hook cannot
+ * read, reported as success.
+ *
+ * Planning function (Rule 10.4) — pure.
+ */
+function remoteRoots(
+  context: HookContext,
+  jail: HookJailInputs | undefined,
+): { readable: string[]; writable: string[] } {
+  const writable: string[] = [context.stateDir, context.screenshotDir];
+  const readable: string[] = [];
+  if (jail) {
+    readable.push(jail.modulePath);
+    writable.push(join(jail.modulePath, 'generated'));
+    for (const input of jail.pathInputs) {
+      (input.access === 'write' ? writable : readable).push(input.value);
+    }
+  }
+  // Whatever a hook may write, it may also read back.
+  return { readable: [...readable, ...writable], writable };
+}
+
 /**
  * The child's environment, built from an allow-list (design D5).
  *
@@ -422,7 +502,11 @@ export async function executeHookScript(
  *
  * Planning function (Rule 10.4) — pure.
  */
-export function hookChildEnv(socketPath: string): Record<string, string> {
+export function hookChildEnv(
+  socketPath: string,
+  remoteSocketPath: string,
+  mountSet: MountSet | undefined,
+): Record<string, string> {
   const env: Record<string, string> = {};
 
   for (const name of FORWARDED_ENV) {
@@ -431,6 +515,10 @@ export function hookChildEnv(socketPath: string): Record<string, string> {
   }
 
   env[HOOK_SOCKET_ENV] = socketPath;
+  env[HOOK_REMOTE_SOCKET_ENV] = remoteSocketPath;
+  // The unjailed advisory lint's input (task 4.7). Absent when jailed — the
+  // shim installs the lint when and only when this variable is set.
+  if (mountSet) env[HOOK_MOUNT_SET_ENV] = mountSetEnvValue(mountSet);
   env[HOOK_PROTOCOL_VERSION_ENV] = String(HOOK_PROTOCOL_VERSION);
   // Forwarded when the operator set it, not synthesised from `debug` — a hook
   // reads the flag off `ctx.debug`, which crosses in the context frame.
@@ -465,10 +553,6 @@ function jailRequest(
     runnerPath: HOOK_RUNNER_PATH,
     runtimeModulePaths: runtimeModulePathsFor(HOOK_RUNNER_PATH),
     pathInputs: inputs.pathInputs,
-    // Stage 2 only. `remote.ts` still runs inside the hook and needs the key;
-    // stage 3 brokers those calls and drops this row (D9, D12). Dropping it
-    // early hardens nothing — it stops every hook reaching its own systems.
-    sshDir: join(homedir(), '.ssh'),
   };
 }
 
@@ -544,6 +628,14 @@ export interface InvokeHookOptions {
    * manifest hook's own `timeout`, being the more specific declaration.
    */
   timeoutMs?: number;
+  /**
+   * D12's target policy for the hook's remote operations, built by the caller
+   * via `remoteAccessPolicy(moduleId, db)` — the same caller-loads-it pattern
+   * as `systems`, and for the same reason: the executor stays decoupled from
+   * the database. Absent means every fleet-credential remote operation is
+   * refused (Rule 6.4).
+   */
+  remoteAccess?: RemoteAccessPolicy;
 }
 
 /**
@@ -846,6 +938,7 @@ export async function invokeHook(
       timeoutMs,
       idleTimeoutMs,
       jail: { modulePath, pathInputs: declaredPathInputs(signature, inputs) },
+      remoteAccess: options.remoteAccess,
     });
 
     // Validate outputs against the contract signature