@celilo/cli 1.7.0 → 1.9.0

package/src/hooks/capability-loader.ts

@@ -40,6 +40,7 @@ import {
 } from '../db/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
+import { recordCapabilityBinding, withBindingRecord } from '../services/capability-bindings';
 import { emitWebRoutesChangedAndWait } from '../services/celilo-events';
 import { getModuleSystems } from '../services/deployed-systems';
 import { withDnsInternalLedger } from '../services/dns-internal-records';
@@ -224,6 +225,11 @@ export async function loadCapabilityFunctions(
   logger: HookLogger,
 ): Promise<Record<string, unknown>> {
   const result: Record<string, unknown> = {};
+  // Which provider each injected capability came from, so the binding recorded
+  // at the return names the provider the consumer actually reached. Provider
+  // self-views (`firewall_registry`, `web_routes`) are deliberately absent —
+  // a module reading its own registry has not bound to anything.
+  const providerByCapability = new Map<string, string>();
 
   const masterKey = await getOrCreateMasterKey();
 
@@ -270,6 +276,11 @@ export async function loadCapabilityFunctions(
       );
       if (chain) {
         result[capName] = chain;
+        // The consumer talks to the OUTERMOST layer, which is not necessarily
+        // the edge provider. Every layer is `stampProvider`'d on the way out,
+        // so the one it was handed names itself.
+        const chainProvider = (chain as { providerModuleId?: string }).providerModuleId;
+        if (chainProvider) providerByCapability.set(capName, chainProvider);
       }
       // The chain hands a CONSUMER the innermost layer, which is not this
       // provider's own layer when it sits further out. `on_consumer_removed`
@@ -377,6 +388,7 @@ export async function loadCapabilityFunctions(
         // greenwave — true, useless, and a violation of the contract's
         // requirement to name the provider.
         result[capName] = withLedger(stampProvider(capabilityInterface, capability.moduleId));
+        providerByCapability.set(capName, capability.moduleId);
         debugLog(`${capName}: loaded via defineCapabilityFunction`);
         continue;
       }
@@ -403,6 +415,7 @@ export async function loadCapabilityFunctions(
         result[capName] = withLedger(
           wrapWithLogging(capabilityInterface as object, logger, capName),
         );
+        providerByCapability.set(capName, capability.moduleId);
         debugLog(`${capName}: loaded via legacy factory`);
         // Sole firewall provider running its OWN hook: the interface just built
         // IS its layer, so hand it back under the provider-view name too.
@@ -544,6 +557,10 @@ export async function loadCapabilityFunctions(
     }
 
     try {
+      // The name comes off the row rather than being restated here: core
+      // naming a capability is what `no-module-business-in-core` Scan B counts,
+      // and this is bookkeeping, not a branch.
+      providerByCapability.set(provider.capabilityName, provider.moduleId);
       result.public_web = createPublicWeb({
         moduleId: consumingModuleId,
         logger,
@@ -610,9 +627,12 @@ export async function loadCapabilityFunctions(
     // — symmetric with how consumers get the public_web capability. Consumers
     // never see this; only the provider does.
     if (consumingModuleId === provider.moduleId) {
+      // Async because the consumer is a hook, which now runs in its own
+      // process. `routeOps` itself stays synchronous: it is bun:sqlite and it
+      // is called in-process by `createPublicWeb`.
       const routeView: RouteReadView = {
-        getAllRoutes: () => routeOps.getAllRoutes(),
-        getRoutes: (m: string) => routeOps.getRoutes(m),
+        getAllRoutes: async () => routeOps.getAllRoutes(),
+        getRoutes: async (m: string) => routeOps.getRoutes(m),
       };
       result.web_routes = routeView;
       debugLog(`web_routes: read-only route view injected for provider ${consumingModuleId}`);
@@ -621,6 +641,32 @@ export async function loadCapabilityFunctions(
     debugLog('public_web: not registered in DB, skipping');
   }
 
+  // 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
+  // would name every provider on the fleet. A method invocation is the only
+  // event that separates the optional capability a module uses from the ones it
+  // merely declares.
+  for (const [capName, iface] of Object.entries(result)) {
+    const providerModuleId = providerByCapability.get(capName);
+    // A module that provides and consumes the same capability is not bound to
+    // itself, and a provider reading its own registry is not a consumer.
+    if (!providerModuleId || providerModuleId === consumingModuleId) continue;
+    if (!iface || typeof iface !== 'object') continue;
+    result[capName] = withBindingRecord(iface as object, () => {
+      try {
+        recordCapabilityBinding(db, consumingModuleId, capName, providerModuleId);
+      } catch (error) {
+        // Bookkeeping must never fail the call it is observing. Loud, not silent.
+        logger.warn(
+          `Could not record the ${capName} binding ${consumingModuleId} → ${providerModuleId}: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    });
+  }
+
   return result;
 }
 
@@ -674,6 +720,11 @@ function buildCapabilityInterface(
           trustedSubnets: zones?.trustedSubnets ?? [],
           controlPlaneSubnet: zones?.controlPlaneSubnet,
           frontedSubnets: zones?.frontedSubnets ?? [],
+          // Operator settings, forwarded verbatim. `parseStoredConfigValue`
+          // preserves each manifest-declared type, so the boolean arrives as a
+          // boolean and needs no coercion here.
+          defaultRouteZone: config.default_route_zone as string | undefined,
+          isolateTransitNetwork: config.isolate_transit_network as boolean | undefined,
         },
         store,
         undefined, // no upstream — the chain path handles that
@@ -1191,6 +1242,12 @@ async function buildFirewallChain(
         // Absent means the box has never converged cleanly, so an interface
         // celilo cannot attribute refuses rather than being disabled.
         interfaceBaseline: parseInterfaceBaseline(provConfig.interface_baseline),
+        // Which declared zone carries this firewall's default route, and
+        // whether fronted zones may initiate into it. Both are operator
+        // settings and both are read HERE or nowhere: the module declares them
+        // on `FirewallConfig`, and nothing else in celilo constructs one.
+        defaultRouteZone: provConfig.default_route_zone as string | undefined,
+        isolateTransitNetwork: provConfig.isolate_transit_network as boolean | undefined,
       },
       store,
       currentUpstream,

package/src/hooks/executor.ts

@@ -7,14 +7,28 @@
  * - Output validation
  * - Structured logging
  *
- * **Execution model:** hook scripts run *in-process* on the celilo CLI host.
- * `runScript` dynamically `import()`s the hook module and awaits its default
- * export. They do NOT execute on the target machine. A hook that needs to
- * touch the target initiates SSH outbound itself (see e.g.
- * modules/lunacycle/celilo/scripts/health-check.ts's `ssh()` helper). This
- * means hook scripts can freely use npm packages, make HTTP calls, read
- * local files, etc. — and conversely, anything they depend on (chromium,
+ * **Execution model:** a hook script is a program celilo RUNS, not a library
+ * celilo loads. `executeHookScript` spawns `bun hook-runner.ts <script>` and
+ * becomes a broker: it keeps the database, the master key and the live
+ * capability objects, and answers the child over a versioned NDJSON protocol
+ * on a Unix socket (`hook-protocol.ts`, `broker.ts`). See
+ * `openspec/changes/hook-process-boundary/design.md`.
+ *
+ * Three things follow, and they are the point:
+ *
+ *   - The child's environment is an ALLOW-LIST, not `...process.env`. celilo's
+ *     own paths and the operator's tokens stop being visible (design D5).
+ *   - A timeout is a real `proc.kill()`. The old implementation raced the
+ *     hook's promise against a timer and cancelled nothing, so a hook that
+ *     "timed out" kept its capability objects and went on registering DNS
+ *     records after celilo reported the deploy failed (celilo#1003).
+ *   - A hook's memory is its own process's, not celilo's heap.
+ *
+ * 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 2 of the change above jails the filesystem and stage 3 scopes that
+ * reachability; neither has landed.
  *
  * Execution function (Rule 10.1) - performs side effects (script execution)
  */
@@ -23,7 +37,6 @@ import { existsSync, mkdirSync, readdirSync, rmdirSync, statSync } from 'node:fs
 import { dirname, join, resolve } from 'node:path';
 import {
   type DeployedSystem,
-  isCompiledHook,
   isMissingProviderInputError,
   moduleArtifactDir,
 } from '@celilo/capabilities';
@@ -35,6 +48,14 @@ import {
 } from '../manifest/contracts';
 import { isPrivilegedCapability } from '../manifest/validate';
 import { pruneModuleArtifacts } from './artifact-retention';
+import { startBroker } from './broker';
+import {
+  HOOK_PROTOCOL_VERSION,
+  HOOK_PROTOCOL_VERSION_ENV,
+  HOOK_SOCKET_ENV,
+  createLineReader,
+  deserializeError,
+} from './hook-protocol';
 import type { HookContext, HookDefinition, HookLogger, HookResult } from './types';
 
 /** Default total timeout: 60 seconds */
@@ -51,6 +72,76 @@ const DEFAULT_TIMEOUT_MS = 60_000;
  */
 const IDLE_TIMEOUT_MS = 30_000;
 
+/** How often the idle tracker looks. Unchanged from the promise-based timer. */
+const IDLE_POLL_MS = 5_000;
+
+/**
+ * SIGTERM is a request. A hook that traps it and keeps working would leave the
+ * boundary buying nothing over the promise race it replaced, so SIGKILL
+ * follows. Short, because by this point celilo has already told the operator
+ * the hook failed.
+ */
+const SIGKILL_GRACE_MS = 2_000;
+
+/**
+ * Environment variables a hook inherits. Everything else is dropped (D5).
+ *
+ * Two kinds, and the distinction is the whole rule.
+ *
+ * **How to run** — `PATH`, `HOME`, `LANG`, `TZ`, `TMPDIR`. A hook that spawns
+ * anything needs these, and withholding them hides no path.
+ *
+ * **How to reach the network, and whom to trust** — the CA and proxy families.
+ * These configure the RUNTIME, not the module: they say which certificate
+ * authorities this host trusts and how it reaches the internet. They name no
+ * secret, they are not module-specific, and withholding them reduces a hook's
+ * authority by nothing at all. It only makes its TLS connections wrong.
+ *
+ * `NODE_EXTRA_CA_CERTS` is why this second group exists rather than being an
+ * afterthought. `packages/e2e/docker/Dockerfile.management:107` sets it because
+ * `bun fetch()` otherwise ignores `/etc/ssl/certs/ca-certificates.crt`
+ * entirely and rejects every certificate the simulated CA issues. Twelve
+ * hook-reachable module files make HTTPS requests. Dropping it would have
+ * broken all of them, in the rig only, as a TLS error naming no cause.
+ *
+ * The proxy family is not set anywhere today. It is here because it is the
+ * same kind of thing, it costs nothing when absent, and the alternative is
+ * discovering it the way `NODE_EXTRA_CA_CERTS` was discovered.
+ *
+ * **`TF_CLI_CONFIG_FILE` is deliberately NOT here.** It is toolchain
+ * configuration too, but no hook invokes the terraform binary — every mention
+ * of terraform in a module script is a `generated/terraform/` PATH. celilo runs
+ * terraform from its own process, which keeps its own environment. Recorded so
+ * the next reader does not have to re-derive it.
+ *
+ * What is NOT in either group: anything module-specific. A module that needs a
+ * value declares it (config) or is handed it (a hook input). See the note on
+ * `DDNS_ENDPOINT` in openspec/changes/hook-process-boundary/baseline.md for the
+ * one case that got this wrong and what was done about it.
+ */
+const FORWARDED_ENV = [
+  // How to run.
+  'PATH',
+  'HOME',
+  'LANG',
+  'TZ',
+  'TMPDIR',
+  // Whom to trust.
+  'NODE_EXTRA_CA_CERTS',
+  'SSL_CERT_FILE',
+  'SSL_CERT_DIR',
+  // How to reach the network.
+  'HTTP_PROXY',
+  'HTTPS_PROXY',
+  'NO_PROXY',
+  'http_proxy',
+  'https_proxy',
+  'no_proxy',
+] as const;
+
+/** 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');
+
 /**
  * Validate hook inputs against a contract signature.
  *
@@ -148,127 +239,159 @@ export async function executeHookScript(
     throw new Error(`Hook script not found: ${scriptPath}`);
   }
 
-  // Create an idle timeout tracker
+  // Activity is now ANY frame or ANY byte the child writes, rather than only a
+  // `ctx.logger` call. That is strictly more generous than the old tracker and
+  // it removes a class of false idle-kill: a hook that prints progress to
+  // stdout used to look silent (celilo#622 is the same family).
   let lastActivity = Date.now();
-  const originalLogger = context.logger;
-
-  // Wrap logger to track activity for idle timeout
-  const trackedLogger: HookLogger = {
-    info(message: string) {
-      lastActivity = Date.now();
-      originalLogger.info(message);
-    },
-    warn(message: string) {
-      lastActivity = Date.now();
-      originalLogger.warn(message);
-    },
-    error(message: string) {
-      lastActivity = Date.now();
-      originalLogger.error(message);
-    },
-    success(message: string) {
-      lastActivity = Date.now();
-      originalLogger.success(message);
-    },
+  const markActive = () => {
+    lastActivity = Date.now();
   };
 
-  const trackedContext: HookContext = {
-    ...context,
-    logger: trackedLogger,
-  };
+  const { logger, ...serializableContext } = context;
+  delete (serializableContext as Record<string, unknown>).capabilities;
 
-  // Execute with timeout — disable idle timeout in debug mode
-  const promises: Promise<Record<string, unknown>>[] = [
-    runScript(scriptPath, trackedContext),
-    createTimeoutPromise(timeoutMs, 'total'),
-  ];
-  if (!context.debug) {
-    promises.push(createIdleTimeoutPromise(() => Date.now() - lastActivity, idleTimeoutMs));
-  }
-  const result = await Promise.race(promises);
+  const broker = await startBroker({
+    capabilities: context.capabilities,
+    context: serializableContext as Record<string, unknown>,
+    scriptPath,
+    logger,
+    onActivity: markActive,
+  });
 
-  return result;
-}
+  try {
+    const child = Bun.spawn({
+      cmd: [process.execPath, HOOK_RUNNER_PATH],
+      env: hookChildEnv(broker.socketPath),
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+
+    // The child's stdout and stderr stay what they are — human output. They
+    // now reach `ctx.logger` instead of celilo's own stdout, which is the
+    // attribution: a `console.log` from an in-process hook landed unlabelled
+    // in the CLI's output with nothing saying which hook wrote it.
+    const forwarding = Promise.all([
+      forwardStream(child.stdout, logger.info.bind(logger), markActive),
+      forwardStream(child.stderr, logger.warn.bind(logger), markActive),
+    ]);
+
+    let killedFor: string | null = null;
+    const kill = (reason: string) => {
+      if (killedFor) return;
+      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.
+      broker.stop();
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), SIGKILL_GRACE_MS).unref();
+    };
 
-/**
- * Run a hook script by dynamically importing it.
- *
- * HOOK_API_V2 Phase 8 (D8): the executor only accepts hook scripts that
- * use `defineHook` from `@celilo/capabilities`. The compiled output
- * carries a brand symbol (`CELILO_HOOK_BRAND`) that this function
- * checks via `isCompiledHook`. Raw `async function(context)` exports are
- * rejected with a clear error pointing at the migration guide — no more
- * silent failures from forgotten brand registration.
- *
- * @param scriptPath - Absolute path to script
- * @param context - Hook context
- * @returns Script outputs
- */
-async function runScript(
-  scriptPath: string,
-  context: HookContext,
-): Promise<Record<string, unknown>> {
-  const module = await import(scriptPath);
+    const totalTimer = setTimeout(() => kill('total'), timeoutMs);
+    // Debug runs get no idle timer, same as before: an operator stepping
+    // through a browser hook is silent for minutes on purpose.
+    const idleTimer = context.debug
+      ? undefined
+      : setInterval(() => {
+          if (Date.now() - lastActivity >= idleTimeoutMs) kill('idle');
+        }, IDLE_POLL_MS);
+
+    let exitCode: number;
+    try {
+      exitCode = await child.exited;
+      // Both channels, not just the process: the terminal frame can still be
+      // in the socket buffer when the exit is observed.
+      await broker.drained();
+      await forwarding;
+    } finally {
+      clearTimeout(totalTimer);
+      if (idleTimer) clearInterval(idleTimer);
+    }
 
-  if (typeof module.default !== 'function') {
-    throw new Error(`Hook script must export a default function: ${scriptPath}`);
-  }
+    // Process exit is the ONE terminal event, so there is no race to lose and
+    // nothing keeps running past this line. That is the difference from the
+    // `Promise.race` this replaces (celilo#1003).
+    if (killedFor === 'total') {
+      throw new Error(`Hook total timeout exceeded (${Math.round(timeoutMs / 1000)}s)`);
+    }
+    if (killedFor === 'idle') {
+      throw new Error(
+        `Hook idle timeout exceeded (no log output for ${Math.round(idleTimeoutMs / 1000)}s)`,
+      );
+    }
 
-  if (!isCompiledHook(module.default)) {
-    throw new Error(
-      `Hook script ${scriptPath} does not use defineHook(). As of HOOK_API_V2 Phase 8, all hook scripts must wrap their handler with defineHook from @celilo/capabilities so the executor can verify the brand and apply pre-flight checks. See reference/MODULE_DEVELOPMENT_GUIDE.md "Hooks" section for the migration pattern.`,
-    );
+    const outcome = broker.outcome();
+    if (!outcome) {
+      const faults = broker.faults();
+      throw new Error(
+        `Hook process exited with code ${exitCode} without returning a result.${
+          faults.length > 0 ? ` ${faults.join('; ')}` : ''
+        }`,
+      );
+    }
+
+    if (!outcome.ok) throw deserializeError(outcome.error);
+    return outcome.outputs;
+  } finally {
+    broker.close();
   }
+}
 
-  const result = await module.default(context);
+/**
+ * The child's environment, built from an allow-list (design D5).
+ *
+ * NOT `...process.env`. `packages/event-bus/src/dispatcher.ts` spawns handlers
+ * that way and it grants a subprocess MORE than the in-process call did — the
+ * whole environment plus an explicit database path. Copying that pattern would
+ * buy the crash isolation and none of the authority reduction.
+ *
+ * Measured on the operator's own shell: what a hook inherited before this was
+ * 24 variables naming celilo state or carrying a credential, twenty of them
+ * third-party API tokens with nothing to do with celilo
+ * (`openspec/changes/hook-process-boundary/baseline.md`).
+ *
+ * This is not the boundary — a hook can still COMPUTE the default master-key
+ * path from `$HOME` and read it. It is the cheap half, and it is what stops the
+ * dispatcher's mistake repeating here. Stage 2's mount set is what makes the
+ * path unreachable.
+ *
+ * Planning function (Rule 10.4) — pure.
+ */
+export function hookChildEnv(socketPath: string): Record<string, string> {
+  const env: Record<string, string> = {};
 
-  if (result === null || result === undefined) {
-    return {};
+  for (const name of FORWARDED_ENV) {
+    const value = process.env[name];
+    if (value !== undefined) env[name] = value;
   }
 
-  if (typeof result !== 'object' || Array.isArray(result)) {
-    throw new Error('Hook script must return an object (or nothing)');
-  }
+  env[HOOK_SOCKET_ENV] = socketPath;
+  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.
+  if (process.env.CELILO_DEBUG !== undefined) env.CELILO_DEBUG = process.env.CELILO_DEBUG;
 
-  return result as Record<string, unknown>;
+  return env;
 }
 
-/**
- * Create a promise that rejects after a total timeout
- */
-function createTimeoutPromise(timeoutMs: number, type: string): Promise<never> {
-  return new Promise((_, reject) => {
-    setTimeout(() => {
-      reject(new Error(`Hook ${type} timeout exceeded (${Math.round(timeoutMs / 1000)}s)`));
-    }, timeoutMs);
+/** Read a piped stream line by line into the logger. */
+async function forwardStream(
+  stream: ReadableStream<Uint8Array>,
+  emit: (line: string) => void,
+  markActive: () => void,
+): Promise<void> {
+  const decoder = new TextDecoder();
+  const feed = createLineReader((line) => {
+    markActive();
+    emit(line);
   });
-}
 
-/**
- * Create a promise that rejects when idle timeout is exceeded
- * Polls every 5 seconds to check idle duration
- */
-function createIdleTimeoutPromise(
-  getIdleDuration: () => number,
-  idleTimeoutMs: number,
-): Promise<never> {
-  return new Promise((_, reject) => {
-    const interval = setInterval(() => {
-      if (getIdleDuration() >= idleTimeoutMs) {
-        clearInterval(interval);
-        reject(
-          new Error(
-            `Hook idle timeout exceeded (no log output for ${Math.round(idleTimeoutMs / 1000)}s)`,
-          ),
-        );
-      }
-    }, 5000);
-
-    // Don't block process exit
-    if (interval.unref) {
-      interval.unref();
-    }
-  });
+  for await (const chunk of stream) {
+    feed(decoder.decode(chunk, { stream: true }));
+  }
+  // A final line with no trailing newline would otherwise be dropped.
+  feed('\n');
 }
 
 export interface InvokeHookOptions {