@celilo/cli 1.8.0 → 1.9.1

package/src/hooks/hook-timeout.test.ts

@@ -0,0 +1,104 @@
+/**
+ * celilo#1003: a hook that times out must be KILLED, not abandoned.
+ *
+ * `module-lifecycle`'s spec has always required this:
+ *
+ * > WHEN a hook produces no output for longer than the idle timeout
+ * > THEN celilo SHALL terminate it rather than hang indefinitely
+ *
+ * The old executor raced the hook's promise against a timer and cancelled
+ * nothing, because a promise cannot be cancelled. The existing suite asserted
+ * the rejection, which held, and the requirement did not.
+ *
+ * So these tests assert the harm rather than the rejection: a marker file the
+ * hook writes only after its bound has passed. Both of them fail against the
+ * in-process executor and neither says anything about how the kill is
+ * implemented.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { execSync } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { executeHookScript } from './executor';
+import { createCapturingLogger } from './logger';
+import type { HookContext } from './types';
+
+const FIXTURES = join(__dirname, 'test-fixtures');
+const dirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function scratch(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'celilo-timeout-'));
+  dirs.push(dir);
+  return dir;
+}
+
+function contextFor(config: Record<string, unknown>): HookContext {
+  return {
+    config,
+    secrets: {},
+    systems: [],
+    logger: createCapturingLogger().logger,
+    debug: false,
+    screenshotDir: scratch(),
+    stateDir: scratch(),
+    capabilities: {},
+  };
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Hook processes still parented to this one. By ppid rather than by script
+ * name: matching the name picks up whatever shell has the filename in its own
+ * command line, which is a false positive that looks exactly like a real leak.
+ */
+function survivingHookProcesses(): string[] {
+  return execSync('ps -Ao ppid=,args=', { encoding: 'utf-8' })
+    .split('\n')
+    .filter(
+      (line) => Number.parseInt(line.trim(), 10) === process.pid && line.includes('hook-runner'),
+    );
+}
+
+describe('hook timeout is a kill, not a race', () => {
+  test('a hook that outruns its total timeout stops doing work', async () => {
+    const marker = join(scratch(), 'kept-running');
+
+    await expect(
+      executeHookScript(
+        join(FIXTURES, 'runaway-hook.ts'),
+        contextFor({ sleep_ms: 1500, marker_path: marker }),
+        400,
+        400,
+      ),
+    ).rejects.toThrow(/timeout/i);
+
+    // Past when the abandoned hook would have written it.
+    await sleep(2000);
+    expect(existsSync(marker)).toBe(false);
+    expect(survivingHookProcesses()).toEqual([]);
+  }, 15_000);
+
+  test('a hook that declines SIGTERM is killed anyway', async () => {
+    const marker = join(scratch(), 'survived');
+
+    await expect(
+      executeHookScript(
+        join(FIXTURES, 'sigterm-ignoring-hook.ts'),
+        contextFor({ sleep_ms: 6000, marker_path: marker }),
+        400,
+        400,
+      ),
+    ).rejects.toThrow(/timeout/i);
+
+    await sleep(6500);
+    expect(existsSync(marker)).toBe(false);
+    expect(survivingHookProcesses()).toEqual([]);
+  }, 20_000);
+});

package/src/hooks/hook-trespass.test.ts

@@ -0,0 +1,202 @@
+/**
+ * The recurrence gate for openspec/changes/hook-process-boundary (celilo#1001).
+ *
+ * Runs `modules/hello-trespass`'s hook through `executeHookScript` and asserts
+ * exactly what the stage that has landed claims, and nothing more.
+ *
+ * **Stage 1 claims the environment. It does not claim the filesystem and it
+ * does not claim the network.** So this file asserts the sensitive environment
+ * is empty, and asserts the other three trespasses STILL SUCCEED. A gate that
+ * claimed more than its stage delivers would go green for the wrong reason and
+ * would have to be rewritten — quietly weakening it — the first time somebody
+ * noticed. Stage 2 flips the two filesystem rows and stage 3 flips the SSH row;
+ * each stage edits the assertion it earns.
+ *
+ * `HOME` is redirected to a scratch directory holding a planted master key and
+ * a planted SSH key, so the trespasses are deterministic and the operator's
+ * real key is never read (CLAUDE.md: never test against live data). `HOME` is
+ * on design D5's allow-list, so the child resolves the same planted paths the
+ * parent planted — which is the point of D5's own caveat: removing
+ * `CELILO_DATA_DIR` does not hide a path a hook can compute.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { executeHookScript, hookChildEnv } from './executor';
+import { createCapturingLogger } from './logger';
+import type { HookContext } from './types';
+
+const TRESPASS_SCRIPT = resolve(
+  __dirname,
+  '../../../../modules/hello-trespass/scripts/trespass.ts',
+);
+
+interface TrespassOutcome {
+  attempted: boolean;
+  succeeded: boolean;
+  target: string;
+  detail: string;
+}
+
+interface TrespassReport {
+  master_key: TrespassOutcome;
+  sibling_write: TrespassOutcome;
+  ssh_key: TrespassOutcome;
+  remote_exec: TrespassOutcome;
+  sensitive_env: string[];
+}
+
+let scratchHome: string;
+let realHome: string | undefined;
+
+/**
+ * Install the fixture module's own dependencies if they are not there.
+ *
+ * A `modules/<id>/scripts` directory is a standalone package, deliberately
+ * outside the root workspace globs so that a module resolves the PUBLISHED
+ * `@celilo/capabilities` it will actually run on the fleet rather than the
+ * workspace copy. bun links workspace dependencies into each package's own
+ * `node_modules` and never into the repo root, so there is nothing here for
+ * the fixture to walk up to: with no install of its own the hook dies with
+ * `Cannot find module '@celilo/capabilities'`.
+ *
+ * `bun run setup` does this for every module, and CI does it in its
+ * check-modules step — which runs LAST on purpose, because twenty-two installs
+ * is the slowest thing in that job. This gate is the first test to reach into
+ * a module's script tree, so it prepares the one fixture it needs instead of
+ * making every PR pay for all of them up front.
+ *
+ * It installs rather than skipping. A gate that quietly does not run is the
+ * exact failure this whole change exists to make impossible.
+ */
+function ensureFixtureInstalled(): void {
+  const scriptsDir = dirname(TRESPASS_SCRIPT);
+  if (existsSync(join(scriptsDir, 'node_modules', '@celilo', 'capabilities'))) return;
+  // `process.execPath`, not `bun` on PATH: this is the bun already running the
+  // suite, so it works wherever the suite does.
+  execFileSync(process.execPath, ['install'], { cwd: scriptsDir, stdio: 'pipe' });
+}
+
+beforeAll(() => {
+  ensureFixtureInstalled();
+  scratchHome = mkdtempSync(join(tmpdir(), 'celilo-trespass-home-'));
+
+  // The master key at getMasterKeyPath()'s DEFAULT location for this platform.
+  // Both branches are planted rather than the current one only, so the fixture
+  // reads a planted key whichever host runs the suite.
+  for (const dir of [
+    join(scratchHome, 'Library', 'Application Support', 'celilo'),
+    join(scratchHome, '.local', 'share', 'celilo'),
+  ]) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'master.key'), 'not-the-real-key\n');
+  }
+
+  mkdirSync(join(scratchHome, '.ssh'), { recursive: true });
+  writeFileSync(join(scratchHome, '.ssh', 'id_ed25519'), 'not-a-real-key\n');
+
+  realHome = process.env.HOME;
+  process.env.HOME = scratchHome;
+});
+
+afterAll(() => {
+  if (realHome === undefined) delete process.env.HOME;
+  else process.env.HOME = realHome;
+  rmSync(scratchHome, { recursive: true, force: true });
+});
+
+async function runTrespass(): Promise<{ report: TrespassReport; lines: string[] }> {
+  const { logger, messages } = createCapturingLogger();
+  const context: HookContext = {
+    config: { sibling_module_id: 'hello-foo', other_system_ip: '' },
+    secrets: {},
+    systems: [],
+    logger,
+    debug: false,
+    screenshotDir: mkdtempSync(join(tmpdir(), 'celilo-trespass-artifacts-')),
+    stateDir: mkdtempSync(join(tmpdir(), 'celilo-trespass-artifacts-')),
+    capabilities: {},
+  };
+
+  const outputs = await executeHookScript(TRESPASS_SCRIPT, context, 60_000, 60_000);
+  return {
+    report: outputs as unknown as TrespassReport,
+    lines: messages.map((m) => m.message),
+  };
+}
+
+describe('the child environment is an allow-list', () => {
+  // The trespass gate below proves nothing sensitive gets through. This is the
+  // complement: the six things that MUST get through, because a hook with no
+  // `PATH` cannot spawn anything and one with no `HOME` breaks more than it
+  // protects.
+  test('forwards the allow-list and the channel, and nothing else', () => {
+    process.env.CELILO_TEST_SECRET = 'must-not-cross';
+    try {
+      const env = hookChildEnv('/tmp/celilo-hook-x/s');
+
+      expect(env.CELILO_HOOK_SOCKET).toBe('/tmp/celilo-hook-x/s');
+      expect(env.CELILO_HOOK_PROTOCOL_VERSION).toBe('1');
+      expect(env.PATH).toBe(process.env.PATH as string);
+      expect(env.HOME).toBe(process.env.HOME as string);
+      expect(env.CELILO_TEST_SECRET).toBeUndefined();
+
+      const allowed = new Set([
+        'PATH',
+        'HOME',
+        'LANG',
+        'TZ',
+        'TMPDIR',
+        'CELILO_DEBUG',
+        'CELILO_HOOK_SOCKET',
+        'CELILO_HOOK_PROTOCOL_VERSION',
+      ]);
+      expect(Object.keys(env).filter((name) => !allowed.has(name))).toEqual([]);
+    } finally {
+      delete process.env.CELILO_TEST_SECRET;
+    }
+  });
+
+  test('omits an allow-listed variable the parent does not have', () => {
+    const saved = process.env.TZ;
+    delete process.env.TZ;
+    try {
+      // Absent, not the string "undefined" — which is what a naive copy
+      // produces and what a shell then happily uses as a timezone.
+      expect('TZ' in hookChildEnv('/tmp/s')).toBe(false);
+    } finally {
+      if (saved !== undefined) process.env.TZ = saved;
+    }
+  });
+});
+
+describe('hook process boundary — hello-trespass gate', () => {
+  test('stage 1: the environment is clean, and nothing else has changed', async () => {
+    const { report, lines } = await runTrespass();
+
+    // The evidence, printed whether the assertions pass or fail. Without it a
+    // red run says which assertion broke and not what the hook actually saw.
+    console.log(['', 'hello-trespass:', ...lines.slice(1)].join('\n'));
+
+    // What stage 1 claims. Empty because the child's environment is an
+    // allow-list, not `...process.env` (design D5).
+    expect(report.sensitive_env).toEqual([]);
+
+    // What stage 1 deliberately does NOT claim. The master key is still
+    // readable, because the hook computes the default path rather than
+    // reading it out of the environment. Stage 2's mount set is what removes
+    // it, by not binding the data directory at all.
+    expect(report.master_key.succeeded).toBe(true);
+
+    // Nor the sibling's tree: the module store is still one `..` away.
+    expect(report.sibling_write.succeeded).toBe(true);
+
+    // Nor the SSH key, which is what scopes reachability in stage 3 (D12).
+    // `attempted: false` means the host has no private key at all — a bare CI
+    // runner — which is an absent precondition, not a refusal.
+    expect(report.ssh_key.attempted && !report.ssh_key.succeeded).toBe(false);
+  });
+});

package/src/hooks/injected-capabilities.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Every name the loader can put in `ctx.capabilities` must be a registered
+ * capability.
+ *
+ * This is the gate for the class of bug, not for its instances. Twice now a
+ * capability has been injected under a literal name that appeared in no
+ * registry and, in one case, had no declared type anywhere:
+ *
+ *   - `web_routes`, whose two methods were synchronous. The hook process
+ *     boundary's D2 measured the hook-facing surface as uniformly async by
+ *     reading `CapabilityRegistry`, so it never saw them. caddy's `on_install`
+ *     died on `{} is not iterable` when the async proxy handed it a Promise.
+ *   - `firewall_registry`, which had no `FirewallRegistryCapability` type, no
+ *     registry entry, and no contract version. It happens to be async, so it
+ *     broke nothing, which is exactly why nobody found it.
+ *
+ * `type-invariants.test.ts` proves every REGISTERED capability's methods are
+ * async. That proof is only worth as much as the registry's completeness, and
+ * completeness is what this file checks. Together they close the loop: the
+ * registry names everything injected, and everything named is async.
+ *
+ * It reads the loader's source because the property is about what the code can
+ * assign, not about what one run happens to produce. A runtime test would need
+ * every provider deployed in every combination to see all the branches.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { KNOWN_CAPABILITY_NAMES } from '@celilo/capabilities';
+
+const LOADER = join(__dirname, 'capability-loader.ts');
+
+/**
+ * Literal names assigned into the capability map, e.g. `result.web_routes =`.
+ *
+ * Computed assignments (`result[capName] =`) are deliberately not matched:
+ * `capName` is already a registry name, since it comes from the capability
+ * table keyed by the same list.
+ */
+function injectedCapabilityNames(source: string): string[] {
+  const names = new Set<string>();
+  for (const match of source.matchAll(/^\s*result\.([A-Za-z_][A-Za-z0-9_]*)\s*=/gm)) {
+    names.add(match[1]);
+  }
+  return [...names].sort();
+}
+
+describe('capabilities injected into the hook context', () => {
+  test('every literally-named injection is a registered capability', () => {
+    const injected = injectedCapabilityNames(readFileSync(LOADER, 'utf-8'));
+
+    // If this is empty the regex has drifted and the gate is checking nothing,
+    // which is the failure mode that makes a green test worse than no test.
+    expect(injected.length).toBeGreaterThan(0);
+
+    const known: readonly string[] = KNOWN_CAPABILITY_NAMES;
+    const unregistered = injected.filter((name) => !known.includes(name));
+
+    expect(unregistered).toEqual([]);
+  });
+
+  test('PROVE IT FAILS: an unregistered name is caught', () => {
+    const withNewInjection = `
+      result.public_web = createPublicWeb({});
+      result.brand_new_view = somethingUndeclared;
+    `;
+    const known: readonly string[] = KNOWN_CAPABILITY_NAMES;
+    const unregistered = injectedCapabilityNames(withNewInjection).filter(
+      (name) => !known.includes(name),
+    );
+
+    expect(unregistered).toEqual(['brand_new_view']);
+  });
+});

package/src/hooks/mount-set.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Hermetic guards on the hook jail's mount set (design D9).
+ *
+ * `deriveMountSet` is pure, so every property D9 asserts is checkable here
+ * without spawning anything. The two that matter most are absence properties:
+ * what the jail does NOT contain is the acceptance criterion.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { deriveMountSet, forbiddenPaths, isForbidden, toBwrapArgs } from './mount-set';
+
+const BASE = {
+  modulePath: '/var/celilo/modules/caddy',
+  stateDir: '/var/celilo/modules/caddy/state',
+  socketDir: '/tmp/celilo-hook-a1b2c3',
+  runtimePath: '/usr/local/bin/bun',
+  runnerPath: '/opt/celilo/src/hooks/hook-runner.ts',
+  pathInputs: [],
+};
+
+const pathsOf = (r: Parameters<typeof deriveMountSet>[0]) =>
+  deriveMountSet(r).entries.map((e) => e.path);
+
+describe('bwrap is never in the mount set', () => {
+  // The AppArmor profile grants userns to /usr/bin/bwrap for anyone on the
+  // box. A jailed hook that could exec it would be uid 0 with CAP_SYS_ADMIN in
+  // its own namespace. bwrap runs OUTSIDE the jail because it creates the
+  // jail, so withholding it costs nothing.
+  test('is absent from an ordinary derivation', () => {
+    expect(pathsOf(BASE).filter(isForbidden)).toEqual([]);
+  });
+
+  test('is dropped even when a contract input names it', () => {
+    // The realistic route back in is a developer debugging `bwrap: command not
+    // found` and adding it. This asserts the derivation refuses, rather than
+    // trusting nobody will ask.
+    const set = deriveMountSet({
+      ...BASE,
+      pathInputs: [{ name: 'evil', value: '/usr/bin/bwrap', access: 'read' }],
+    });
+    expect(set.entries.map((e) => e.path)).not.toContain('/usr/bin/bwrap');
+  });
+
+  test('every forbidden path is actually recognised', () => {
+    for (const p of forbiddenPaths()) expect(isForbidden(p)).toBe(true);
+  });
+});
+
+describe('what the jail must not contain', () => {
+  test("celilo's data directory and its secrets are absent", () => {
+    const paths = pathsOf(BASE);
+    // Absence, not a check. These simply do not exist inside the jail.
+    expect(paths).not.toContain('/var/celilo');
+    expect(paths).not.toContain('/var/celilo/master.key');
+    expect(paths).not.toContain('/var/celilo/celilo.db');
+  });
+
+  test("a sibling module's tree is absent", () => {
+    const paths = pathsOf(BASE);
+    expect(paths).not.toContain('/var/celilo/modules');
+    expect(paths.some((p) => p.includes('/modules/technitium'))).toBe(false);
+  });
+
+  test('the celilo CLI is absent, so a hook cannot re-enter it (celilo#1121)', () => {
+    expect(pathsOf(BASE)).not.toContain('/usr/local/bin/celilo');
+  });
+});
+
+describe('ordering is semantic', () => {
+  test('the tmpfs leads, so it cannot erase the socket or a staged input', () => {
+    // Every staged contract input and the broker socket live under os.tmpdir().
+    // Bind them before the tmpfs and they vanish — and a hook whose backup_dir
+    // is silently empty SUCCEEDS and produces a backup containing nothing.
+    const set = deriveMountSet({
+      ...BASE,
+      pathInputs: [
+        { name: 'backup_dir', value: '/tmp/celilo-backup-9f/envelope/data', access: 'write' },
+      ],
+    });
+    const tmpfsAt = set.entries.findIndex((e) => e.mode === 'tmpfs' && e.path === '/tmp');
+    const socketAt = set.entries.findIndex((e) => e.path === BASE.socketDir);
+    const inputAt = set.entries.findIndex((e) => e.path.startsWith('/tmp/celilo-backup-'));
+
+    expect(tmpfsAt).toBeGreaterThanOrEqual(0);
+    expect(socketAt).toBeGreaterThan(tmpfsAt);
+    expect(inputAt).toBeGreaterThan(tmpfsAt);
+  });
+
+  test('writable directories come after the read-only module tree', () => {
+    const set = deriveMountSet({ ...BASE, screenshotDir: `${BASE.modulePath}/screenshots/run1` });
+    const treeAt = set.entries.findIndex((e) => e.path === BASE.modulePath && e.mode === 'ro');
+    for (const carved of ['state', 'generated', 'screenshots/run1']) {
+      const at = set.entries.findIndex((e) => e.path === `${BASE.modulePath}/${carved}`);
+      expect(at).toBeGreaterThan(treeAt);
+      expect(set.entries[at]?.mode).toBe('rw');
+    }
+  });
+});
+
+describe('contract inputs are bound at their declared access', () => {
+  test("'write' is read-write and 'read' is read-only", () => {
+    const set = deriveMountSet({
+      ...BASE,
+      pathInputs: [
+        { name: 'backup_dir', value: '/tmp/stage/data', access: 'write' },
+        { name: 'artifact_path', value: '/tmp/stage/db.sqlite', access: 'read' },
+      ],
+    });
+    expect(set.entries.find((e) => e.path === '/tmp/stage/data')?.mode).toBe('rw');
+    expect(set.entries.find((e) => e.path === '/tmp/stage/db.sqlite')?.mode).toBe('ro');
+  });
+
+  test('an undeclared input contributes nothing', () => {
+    // db_path was passed for months without being declared. A derivation that
+    // walks declarations cannot see it, which is the correct outcome here and
+    // the reason the contract has to declare what it passes (celilo#1118).
+    expect(pathsOf(BASE)).not.toContain('/var/celilo/celilo.db');
+  });
+});
+
+describe('paths are identical inside and outside', () => {
+  test('no entry is remapped', () => {
+    const args = toBwrapArgs(deriveMountSet(BASE));
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--bind' || args[i] === '--ro-bind') {
+        expect(args[i + 1]).toBe(args[i + 2] as string);
+      }
+    }
+  });
+
+  test('the jail names its own working directory', () => {
+    // The spawn sets no cwd, so the child inherits celilo's — a directory that
+    // usually does not exist inside the jail.
+    expect(deriveMountSet(BASE).chdir).toBe(BASE.modulePath);
+    expect(toBwrapArgs(deriveMountSet(BASE))).toContain('--chdir');
+  });
+});
+
+describe('~/.ssh is stage 2 only', () => {
+  test('bound read-only when supplied', () => {
+    const set = deriveMountSet({ ...BASE, sshDir: '/var/celilo/.ssh' });
+    expect(set.entries.find((e) => e.path === '/var/celilo/.ssh')?.mode).toBe('ro');
+  });
+
+  test('absent when not supplied, which is what stage 3 does', () => {
+    expect(pathsOf(BASE).some((p) => p.endsWith('/.ssh'))).toBe(false);
+  });
+});