@celilo/cli 1.12.0 → 1.14.0

package/src/hooks/hook-state-dir.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'bun:test';
-import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { moduleStateDir } from '@celilo/capabilities';
 import { classifyModulePath } from '../module/packaging/package-rules';
 import { invokeHook } from './executor';
@@ -25,9 +25,21 @@ const silent: HookLogger = {
   success() {},
 };
 
+/** The workspace copy of the package every module bundles. */
+const CAPABILITIES_PACKAGE = resolve(import.meta.dir, '../../../../packages/capabilities');
+
 function scratchModule(script: string): string {
   const root = mkdtempSync(join(tmpdir(), 'celilo-statedir-'));
   Bun.write(join(root, 'hook.ts'), script);
+  // A real module in the store carries its OWN bundled @celilo/capabilities
+  // (modules run their bundled copy, celilo#173), and the hook jail binds the
+  // module's tree and nothing above it. This fixture used to resolve the
+  // import through the test runner's own tree, which worked only because hooks
+  // ran unjailed; `--chdir` into the module root removed that accident.
+  // Linking it here is what makes the fixture a module rather than a loose
+  // script.
+  mkdirSync(join(root, 'node_modules', '@celilo'), { recursive: true });
+  symlinkSync(CAPABILITIES_PACKAGE, join(root, 'node_modules', '@celilo', 'capabilities'));
   return root;
 }
 

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

@@ -74,8 +74,7 @@ describe('hook timeout is a kill, not a race', () => {
       executeHookScript(
         join(FIXTURES, 'runaway-hook.ts'),
         contextFor({ sleep_ms: 1500, marker_path: marker }),
-        400,
-        400,
+        { timeoutMs: 400, idleTimeoutMs: 400 },
       ),
     ).rejects.toThrow(/timeout/i);
 
@@ -92,8 +91,7 @@ describe('hook timeout is a kill, not a race', () => {
       executeHookScript(
         join(FIXTURES, 'sigterm-ignoring-hook.ts'),
         contextFor({ sleep_ms: 6000, marker_path: marker }),
-        400,
-        400,
+        { timeoutMs: 400, idleTimeoutMs: 400 },
       ),
     ).rejects.toThrow(/timeout/i);
 

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

@@ -22,9 +22,15 @@
 
 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 { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import {
+  applyFallbacksToPackageJson,
+  isPublished,
+  listUnpublishedWorkspacePackages,
+  planFallbacks,
+} from '../../../../scripts/workspace-fallback';
 import { executeHookScript, hookChildEnv } from './executor';
 import { createCapturingLogger } from './logger';
 import type { HookContext } from './types';
@@ -75,9 +81,45 @@ let realHome: string | undefined;
 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' });
+
+  // On a version-packages PR the pin names a version that CANNOT be on the
+  // registry yet, because only merging that PR lets it publish. So a plain
+  // install here fails with `No version matching "^3.3.0" found`, and the
+  // version PR can never go green on its own.
+  //
+  // This is celilo#642 exactly, and check-modules.sh already solves it. Reuse
+  // that rather than resolving from the workspace unconditionally: doing it
+  // unconditionally would check the fixture against a copy it does not bundle,
+  // which is the celilo#173 property this module's scripts/ dir is kept out of
+  // the root workspace globs to preserve. The fallback fires only when the pin
+  // names a version the registry lacks AND the workspace holds exactly that
+  // version — where the workspace IS the artifact about to be published, same
+  // bytes by definition.
+  //
+  // The probe is scoped to this module's own dependencies: packages it does not
+  // depend on are reported published without asking the network, so this costs
+  // one registry call rather than one per publishable workspace package.
+  const pkgPath = join(scriptsDir, 'package.json');
+  const original = readFileSync(pkgPath, 'utf-8');
+  const dependencies =
+    (JSON.parse(original) as { dependencies?: Record<string, string> }).dependencies ?? {};
+  const unpublished = listUnpublishedWorkspacePackages((name, version) =>
+    name in dependencies ? isPublished(name, version) : true,
+  );
+  const fallbacks = planFallbacks(dependencies, unpublished);
+  if (fallbacks.length > 0)
+    writeFileSync(pkgPath, applyFallbacksToPackageJson(original, fallbacks));
+
+  try {
+    // `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' });
+  } finally {
+    // Restore even when the install failed. A `file:` pin left in the tree
+    // points the fixture at one machine's checkout and would be swept up by the
+    // next `git add -A` — the same reason check-modules.sh restores from a trap.
+    if (fallbacks.length > 0) writeFileSync(pkgPath, original);
+  }
 }
 
 beforeAll(() => {
@@ -121,7 +163,10 @@ async function runTrespass(): Promise<{ report: TrespassReport; lines: string[]
     capabilities: {},
   };
 
-  const outputs = await executeHookScript(TRESPASS_SCRIPT, context, 60_000, 60_000);
+  const outputs = await executeHookScript(TRESPASS_SCRIPT, context, {
+    timeoutMs: 60_000,
+    idleTimeoutMs: 60_000,
+  });
   return {
     report: outputs as unknown as TrespassReport,
     lines: messages.map((m) => m.message),

package/src/hooks/jail.test.ts

@@ -0,0 +1,370 @@
+/**
+ * Hermetic guards on the hook jail's CALLER (design D8, D9).
+ *
+ * `mount-set.test.ts` covers what the derivation computes. This covers what
+ * celilo does with it, and it is deliberately hermetic: the host running these
+ * tests usually has no jail at all (a Mac has none until task 4.8), so a suite
+ * that needed one would skip everywhere and prove nothing. `planJailedSpawn`
+ * is pure and takes the backend and the existence check as arguments for
+ * exactly that reason.
+ *
+ * The live half — a hook that actually cannot reach a path — is
+ * `hook-jail-unreachability.test.ts`, which skips loudly when there is no
+ * backend rather than passing quietly.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  type JailAvailability,
+  type JailPlan,
+  jailModeStorePath,
+  jailPolicy,
+  planJailedSpawn,
+  readJailMode,
+  realpathRequest,
+  recordJailMode,
+  runtimeModulePathsFor,
+} from './jail';
+import { deriveMountSet } from './mount-set';
+
+const AVAILABLE: JailAvailability = { backend: 'bubblewrap' };
+const UNAVAILABLE: JailAvailability = {
+  backend: 'none',
+  reason: 'bubblewrap is not installed, so hooks run unjailed.',
+};
+
+const MODULE = '/var/celilo/modules/caddy';
+const CMD = ['/usr/local/bin/bun', '/opt/celilo/src/hooks/hook-runner.ts'];
+
+const REQUEST = {
+  modulePath: MODULE,
+  stateDir: `${MODULE}/state`,
+  socketDir: '/tmp/celilo-hook-a1b2c3',
+  runtimePath: CMD[0] as string,
+  runnerPath: CMD[1] as string,
+  pathInputs: [],
+};
+
+/** Every path exists, so nothing is dropped and the argv is the full set. */
+const allPresent = () => true;
+
+function plan(): JailPlan {
+  return planJailedSpawn(CMD, deriveMountSet(REQUEST), AVAILABLE, 'auto', allPresent);
+}
+
+describe('the shim is spawned under bwrap', () => {
+  test('bwrap leads, and the unjailed command follows the -- terminator', () => {
+    const { cmd, mode } = plan();
+    expect(mode).toBe('jailed');
+    expect(cmd[0]).toBe('bwrap');
+    expect(cmd.slice(cmd.indexOf('--') + 1)).toEqual(CMD);
+  });
+
+  test('the derived mount set reaches the argv, at the mode it derived', () => {
+    const { cmd } = plan();
+    const args = cmd.join(' ');
+    // The module's own tree read-only, then its writable directory carved on
+    // top of it. Order is what makes the carve-out work, so assert the order
+    // and not merely the presence.
+    expect(args).toContain(`--ro-bind ${MODULE} ${MODULE}`);
+    expect(args).toContain(`--bind ${MODULE}/state ${MODULE}/state`);
+    expect(args.indexOf(`--ro-bind ${MODULE} `)).toBeLessThan(
+      args.indexOf(`--bind ${MODULE}/state`),
+    );
+  });
+
+  test('the jail names its own working directory (task 4.2i)', () => {
+    // The spawn sets no `cwd`, so without this the child inherits celilo's —
+    // whatever directory the operator's shell was in, which need not exist
+    // inside the namespace. bubblewrap then fails on a path nobody chose.
+    const { cmd } = plan();
+    expect(cmd[cmd.indexOf('--chdir') + 1]).toBe(MODULE);
+  });
+
+  test('the network is NOT namespaced, which D9 says on purpose', () => {
+    // Reachability is scoped by withholding the credential (D12), not by
+    // filtering packets. An --unshare-net here would break every hook that
+    // reaches its own systems and would look like a DNS bug.
+    expect(plan().cmd).not.toContain('--unshare-net');
+  });
+
+  test('a fresh /proc comes with the pid namespace', () => {
+    // --unshare-pid without a fresh /proc leaves the host's process table
+    // visible, and /proc/1/root is a well-worn way to read out of a jail.
+    const { cmd } = plan();
+    expect(cmd).toContain('--unshare-pid');
+    expect(cmd[cmd.indexOf('--proc') + 1]).toBe('/proc');
+  });
+});
+
+describe('what the jailed argv must never name', () => {
+  // These are the acceptance criterion of the whole change, asserted at the
+  // caller rather than in the derivation: whatever else the wrapping does, it
+  // must not smuggle a path back in.
+  test("celilo's data directory, its master key and a sibling module are absent", () => {
+    const args = plan().cmd.join(' ');
+    expect(args).not.toContain('/var/celilo/master.key');
+    expect(args).not.toContain('/var/celilo/celilo.db');
+    expect(args).not.toContain('/var/celilo/modules ');
+    expect(args).not.toContain('/modules/technitium');
+  });
+
+  test('bwrap binds no bwrap, so the jail cannot build a jail', () => {
+    // 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
+    // inside a namespace of its own. bwrap is the FIRST word of this command
+    // and must not be an argument of it.
+    expect(plan().cmd.slice(1).join(' ')).not.toContain('/bwrap');
+  });
+});
+
+describe('a mount whose source is missing is dropped, not fatal', () => {
+  // bubblewrap fails the whole jail on a bind with no source, and several rows
+  // are legitimately absent: /lib64 does not exist on arm64, and
+  // <module>/generated appears only once celilo has generated something.
+  const missing = `${MODULE}/generated`;
+  const exists = (path: string) => path !== missing;
+
+  test('it is filtered out of the argv and named in `skipped`', () => {
+    const { cmd, skipped } = planJailedSpawn(
+      CMD,
+      deriveMountSet(REQUEST),
+      AVAILABLE,
+      'auto',
+      exists,
+    );
+    expect(skipped).toContain(missing);
+    expect(cmd.join(' ')).not.toContain(missing);
+  });
+
+  test('a tmpfs is never dropped, because it has no source to be missing', () => {
+    const { cmd, skipped } = planJailedSpawn(
+      CMD,
+      deriveMountSet(REQUEST),
+      AVAILABLE,
+      'auto',
+      () => false,
+    );
+    expect(skipped).not.toContain('/tmp');
+    expect(cmd.join(' ')).toContain('--tmpfs /tmp');
+  });
+});
+
+describe("celilo's own dependencies reach the jail, and nothing else does", () => {
+  // The shim is not self-contained: it imports `isCompiledHook` from
+  // @celilo/capabilities and Zod through hook-protocol.ts, and both resolve
+  // ABOVE its own directory. Measured — the jail built correctly and the shim
+  // died on `Cannot find module '@celilo/capabilities'`.
+  const NPM_SHIM = '/var/celilo/node_modules/@celilo/cli/src/hooks/hook-runner.ts';
+
+  test('an npm install finds its node_modules, nearest first', () => {
+    const exists = (p: string) => p === '/var/celilo/node_modules';
+    expect(runtimeModulePathsFor(NPM_SHIM, exists)).toEqual(['/var/celilo/node_modules']);
+  });
+
+  test('the data directory holding master.key is NEVER collected', () => {
+    // This is the whole safety property. `/var/celilo` is the ancestor that
+    // holds the shim's dependencies, and it also holds master.key and
+    // celilo.db. Only a path literally named `node_modules` is ever kept, so
+    // the ancestor itself cannot be bound however the walk is refactored.
+    const everythingExists = () => true;
+    const found = runtimeModulePathsFor(NPM_SHIM, everythingExists);
+    expect(found).not.toContain('/var/celilo');
+    expect(found.every((p) => p.endsWith('/node_modules'))).toBe(true);
+  });
+
+  test('the walk stops at the filesystem root rather than looping', () => {
+    expect(runtimeModulePathsFor('/hook-runner.ts', () => false)).toEqual([]);
+  });
+
+  test('they are bound read-only, and the derivation puts them in the argv', () => {
+    const { cmd } = planJailedSpawn(
+      CMD,
+      deriveMountSet({ ...REQUEST, runtimeModulePaths: ['/var/celilo/node_modules'] }),
+      AVAILABLE,
+      'auto',
+      allPresent,
+    );
+    expect(cmd.join(' ')).toContain('--ro-bind /var/celilo/node_modules /var/celilo/node_modules');
+  });
+});
+
+describe('the three policies', () => {
+  test("'auto' with no backend runs the hook and records why", () => {
+    const p = planJailedSpawn(CMD, deriveMountSet(REQUEST), UNAVAILABLE, 'auto', allPresent);
+    expect(p.mode).toBe('unjailed');
+    expect(p.cmd).toEqual(CMD);
+    expect(p.reason).toBe(UNAVAILABLE.reason);
+  });
+
+  test("'off' declines a jail that IS available", () => {
+    const p = planJailedSpawn(CMD, deriveMountSet(REQUEST), AVAILABLE, 'off', allPresent);
+    expect(p.mode).toBe('unjailed');
+    expect(p.cmd).toEqual(CMD);
+  });
+
+  test("'required' turns an unavailable jail into a hard failure (task 4.5)", () => {
+    expect(() =>
+      planJailedSpawn(CMD, deriveMountSet(REQUEST), UNAVAILABLE, 'required', allPresent),
+    ).toThrow(/CELILO_HOOK_JAIL=required/);
+  });
+
+  test("'required' names the reason, so the operator can act on it", () => {
+    expect(() =>
+      planJailedSpawn(CMD, deriveMountSet(REQUEST), UNAVAILABLE, 'required', allPresent),
+    ).toThrow(/not installed/);
+  });
+
+  test('an invocation with no mount set runs unjailed rather than in an empty jail', () => {
+    // An empty mount set is a hook that cannot read its own script. Absent
+    // means "do not jail this one", never "jail it with nothing".
+    const p = planJailedSpawn(CMD, undefined, AVAILABLE, 'auto', allPresent);
+    expect(p.mode).toBe('unjailed');
+    expect(p.cmd).toEqual(CMD);
+  });
+});
+
+describe('jailPolicy reads the operator’s switch', () => {
+  const withEnv = <T>(value: string | undefined, fn: () => T): T => {
+    const saved = process.env.CELILO_HOOK_JAIL;
+    if (value === undefined) delete process.env.CELILO_HOOK_JAIL;
+    else process.env.CELILO_HOOK_JAIL = value;
+    try {
+      return fn();
+    } finally {
+      if (saved === undefined) delete process.env.CELILO_HOOK_JAIL;
+      else process.env.CELILO_HOOK_JAIL = saved;
+    }
+  };
+
+  test('unset is auto', () => {
+    expect(withEnv(undefined, jailPolicy)).toBe('auto');
+  });
+
+  test('a typo is refused rather than silently meaning auto', () => {
+    // `CELILO_HOOK_JAIL=requried` reading as `auto` would look exactly like
+    // the jail being enforced when it is not — the one mistake this variable
+    // exists to prevent (Rule 4.2).
+    expect(() => withEnv('requried', jailPolicy)).toThrow(/is not a hook jail policy/);
+  });
+});
+
+describe('realpath at the caller (task 4.2k)', () => {
+  test('a symlinked module root is resolved before it becomes a bind', () => {
+    // `mod.sourcePath` comes out of the database, and a database restored from
+    // another box carries that box's absolute paths (ISS-0052).
+    const scratch = mkdtempSync(join(tmpdir(), 'celilo-jail-realpath-'));
+    try {
+      const real = join(scratch, 'real-module');
+      mkdirSync(join(real, 'state'), { recursive: true });
+      const link = join(scratch, 'linked-module');
+      symlinkSync(real, link);
+
+      const resolved = realpathRequest({
+        ...REQUEST,
+        modulePath: link,
+        stateDir: join(link, 'state'),
+      });
+      expect(resolved.modulePath).not.toContain('linked-module');
+      expect(resolved.modulePath).toBe(resolved.stateDir.replace(/\/state$/, ''));
+    } finally {
+      rmSync(scratch, { recursive: true, force: true });
+    }
+  });
+
+  test('a path that does not exist keeps its lexical form', () => {
+    // It cannot be resolved, and it is dropped by the existence filter anyway.
+    expect(realpathRequest(REQUEST).modulePath).toBe(MODULE);
+  });
+});
+
+describe('the mode is recorded state, not a log line (design D8)', () => {
+  const withStore = <T>(fn: (path: string) => T): T => {
+    const scratch = mkdtempSync(join(tmpdir(), 'celilo-jail-mode-'));
+    const path = join(scratch, 'nested', 'hook-jail-mode.json');
+    const saved = process.env.CELILO_HOOK_JAIL_MODE_PATH;
+    process.env.CELILO_HOOK_JAIL_MODE_PATH = path;
+    try {
+      return fn(path);
+    } finally {
+      if (saved === undefined) delete process.env.CELILO_HOOK_JAIL_MODE_PATH;
+      else process.env.CELILO_HOOK_JAIL_MODE_PATH = saved;
+      rmSync(scratch, { recursive: true, force: true });
+    }
+  };
+
+  const jailed: JailPlan = { cmd: CMD, mode: 'jailed', backend: 'bubblewrap', skipped: [] };
+  const unjailed: JailPlan = {
+    cmd: CMD,
+    mode: 'unjailed',
+    backend: 'none',
+    reason: 'bubblewrap is not installed',
+    skipped: [],
+  };
+
+  test('the first run writes the mode and had nothing to replace', () => {
+    withStore(() => {
+      expect(recordJailMode(jailed).previous).toBeUndefined();
+      expect(readJailMode()?.mode).toBe('jailed');
+    });
+  });
+
+  test('a jailed-to-unjailed transition is readable from the record (task 4.4)', () => {
+    withStore(() => {
+      recordJailMode(jailed);
+      const { previous } = recordJailMode(unjailed);
+      // This is the third of D8's three states, the only one that is an event:
+      // a host that used to jail and has stopped. The self-monitor is task
+      // 4.4; this is the state it reads.
+      expect(previous?.mode).toBe('jailed');
+      expect(readJailMode()?.mode).toBe('unjailed');
+      expect(readJailMode()?.reason).toContain('not installed');
+    });
+  });
+
+  test('an unchanged mode keeps the timestamp of the last CHANGE', () => {
+    withStore(() => {
+      recordJailMode(jailed);
+      const first = readJailMode()?.recordedAt;
+      recordJailMode(jailed);
+      expect(readJailMode()?.recordedAt).toBe(first as string);
+    });
+  });
+
+  test('the record names the host, because a transition is per host', () => {
+    withStore(() => {
+      recordJailMode(jailed);
+      expect(readJailMode()?.host).toBeTruthy();
+    });
+  });
+
+  test('a corrupt file reads as absent rather than failing the hook', () => {
+    withStore((path) => {
+      mkdirSync(join(path, '..'), { recursive: true });
+      writeFileSync(path, 'not json');
+      expect(readJailMode()).toBeUndefined();
+    });
+  });
+
+  test('an unwritable store does not fail the hook', () => {
+    // Diagnostic state. celilo must not refuse to run a hook because it could
+    // not write down how it ran it.
+    withStore(() => {
+      process.env.CELILO_HOOK_JAIL_MODE_PATH = '/proc/celilo-cannot-write-here/mode.json';
+      expect(() => recordJailMode(jailed)).not.toThrow();
+    });
+  });
+
+  test('the store sits beside the rest of celilo’s per-machine state', () => {
+    const saved = process.env.CELILO_HOOK_JAIL_MODE_PATH;
+    delete process.env.CELILO_HOOK_JAIL_MODE_PATH;
+    try {
+      expect(jailModeStorePath()).toMatch(/hook-jail-mode\.json$/);
+    } finally {
+      if (saved !== undefined) process.env.CELILO_HOOK_JAIL_MODE_PATH = saved;
+    }
+  });
+});