@celilo/cli 1.13.0 → 2.0.0

package/src/hooks/unjailed-lint.ts

@@ -0,0 +1,395 @@
+/**
+ * The unjailed advisory lint (hook-process-boundary task 4.7, design D8).
+ *
+ * On a host with no jail backend the hook runs with ambient filesystem
+ * access, so a hook that reads outside its tree works on that host and fails
+ * on the fleet — a divergence otherwise found in production one deploy at a
+ * time. This file closes the gap by making the runner shim check each
+ * filesystem access against the SAME mount set the jail would have enforced.
+ * It is the derivation's second consumer, which is the point: one computation
+ * and two consumers cannot drift the way a consumer and a hand-maintained
+ * list can.
+ *
+ * **This is a lint, not a security boundary, and neither the code nor its
+ * output may describe it as one.** It observes `node:fs` calls from inside
+ * the hook's own process, and module code bypasses it trivially — a `Bun.file`
+ * call, a `dlopen`, or a subprocess never crosses a wrapper. What it claims,
+ * and all it claims, is: on a jailed host, this access would have failed.
+ *
+ * **Channel.** The mount set arrives in the child's environment
+ * (`HOOK_MOUNT_SET_ENV`), set only when the run is unjailed — presence is the
+ * signal to install, so a jailed run carries nothing and installs nothing.
+ *
+ * **WHY THIS MODULE SELF-INSTALLS AT EVALUATION, AND WHY IT MUST STAY A
+ * LEAF.** Measured on Bun 1.3: the first ESM import of `node:fs` anywhere in
+ * a process resolves the builtin's named exports and never revisits them, so
+ * a wrapper planted on `require('node:fs')` AFTER that first import is
+ * invisible to every later `import { readFileSync } from 'node:fs'`. The
+ * shim's other imports (`jail.ts`, `@celilo/capabilities`) ESM-import
+ * `node:fs`, so the wrappers must be in place before any of them load. Hence
+ * `hook-runner-entry.ts`: the executor spawns IT, its first statement forces
+ * this module's evaluation and the install, and only then does the real
+ * runner load. Import order inside the runner is therefore irrelevant — but
+ * this module still imports nothing but `node:path`, `zod` (through
+ * `hook-protocol.ts`, which pulls no other builtins), and type-only imports,
+ * because the entry's guarantee is only as good as this file's graph is
+ * shallow. Importing `jail.ts` from here would silently disarm the lint; the
+ * integration tests in `unjailed-lint.test.ts` go red if that happens (they
+ * did, while this was being landed).
+ *
+ * The self-install is guarded on the runner shim's own environment variable,
+ * so a parent celilo process that imports this module for
+ * `mountSetEnvValue` never wraps its own filesystem.
+ */
+
+import { basename, dirname, isAbsolute, resolve } from 'node:path';
+import {
+  HOOK_MOUNT_SET_ENV,
+  HOOK_SOCKET_ENV,
+  type MountSetWire,
+  MountSetWireSchema,
+} from './hook-protocol';
+import type { MountSet } from './mount-set';
+
+/**
+ * The two paths the jail's namespace itself provides — bubblewrap's
+ * `--proc /proc` and `--dev /dev` (`jail.ts`'s JAIL_NAMESPACE_ARGS is built
+ * from this constant, so the two cannot drift) — rather than derivation
+ * rows. Counting them absent would be a false warning on every hook that
+ * touched either.
+ */
+export const JAIL_PROVIDED_PATHS = ['/proc', '/dev'] as const;
+
+/**
+ * `realpathSync` captured at module load, before the wrappers go in.
+ * `classifyAccess` runs from INSIDE a wrapped call (a wrapper reports, report
+ * classifies), so reaching for the module property here would re-enter the
+ * wrapper and classify forever.
+ */
+const PRISTINE_REALPATH = (require('node:fs') as typeof import('node:fs')).realpathSync;
+
+/** The verdict for one access, against one mount set. */
+export type AccessVerdict = 'allowed' | 'absent' | 'read-only';
+
+/**
+ * Distinct paths warned about before the lint stops listing and summarises.
+ * A hook walking a directory outside the set would otherwise emit one line
+ * per file; after this many distinct paths the reader has the point.
+ */
+const WARN_CAP = 25;
+
+/**
+ * Serialise a derived mount set for `HOOK_MOUNT_SET_ENV`.
+ *
+ * The executor calls this with the set it just derived; `parseLintMountSet`
+ * is the only thing on the reading side.
+ */
+export function mountSetEnvValue(set: MountSet): string {
+  return JSON.stringify(set);
+}
+
+/**
+ * Read and validate the mount set out of the child's environment.
+ *
+ * `undefined` when the variable is absent — the jailed case, and every
+ * invocation with no module tree. A value that fails validation is reported
+ * to stderr (the executor forwards it through the logger) and the run
+ * proceeds WITHOUT the lint rather than failing the hook over a diagnostic:
+ * the lint must never be the reason a deploy breaks. A silent skip would be
+ * the one thing worse than that, hence the stderr line.
+ */
+export function parseLintMountSet(value: string | undefined): MountSetWire | undefined {
+  if (value === undefined || value === '') return undefined;
+  let json: unknown;
+  try {
+    json = JSON.parse(value);
+  } catch (error) {
+    process.stderr.write(
+      `hook runner: ${HOOK_MOUNT_SET_ENV} is not valid JSON (${error instanceof Error ? error.message : String(error)}); the unjailed advisory lint is off this run.\n`,
+    );
+    return undefined;
+  }
+  const parsed = MountSetWireSchema.safeParse(json);
+  if (parsed.success) return parsed.data;
+  process.stderr.write(
+    `hook runner: ${HOOK_MOUNT_SET_ENV} failed validation; the unjailed advisory lint is off this run.\n`,
+  );
+  return undefined;
+}
+
+/**
+ * Warnings emitted before the hook's logger exists are buffered here and
+ * flushed by `forwardLintWarnings`. In practice there are none — the shim
+ * does no filesystem work between load and hook start — but the lint must
+ * never assume that.
+ */
+const buffered: string[] = [];
+let emit: ((message: string) => void) | undefined;
+let installed = false;
+
+/**
+ * Install the wrappers now, if this process is an unjailed hook runner.
+ *
+ * Idempotent, and called from TWO places by design: this module's own
+ * evaluation, and `hook-runner-entry.ts`'s first statement. Which one lands
+ * first depends on Bun's import evaluation order, which is not a thing to
+ * reason about twice — the guard makes both orders correct, and the entry
+ * makes one of them certain before any other module in the child process can
+ * ESM-load `node:fs` (see the docblock at the top). No-op everywhere else: no
+ * runner socket in the environment means this is not a hook runner process.
+ */
+export function installUnjailedLintIfUnjailed(): void {
+  if (installed) return;
+  if (process.env[HOOK_SOCKET_ENV] === undefined) return;
+  const set = parseLintMountSet(process.env[HOOK_MOUNT_SET_ENV]);
+  if (!set) return;
+  installed = true;
+  install(set, (message) => (emit ? emit(message) : buffered.push(message)));
+}
+
+/**
+ * Hand the lint's output to the hook's logger, draining anything buffered.
+ * Call once the shim's logger exists, before the hook script is imported.
+ */
+export function forwardLintWarnings(to: (message: string) => void): void {
+  emit = to;
+  for (const message of buffered.splice(0)) to(message);
+}
+
+/**
+ * Classify one access against the mount set.
+ *
+ * Last matching row wins, in `entries` order — that is bubblewrap's own rule
+ * (`--ro-bind` then a later `--bind` overrides), and the derivation emits its
+ * rows in exactly that order. A path under no row is absent, which is what
+ * the jail actually produces (mount-set.ts: not "denied", ABSENT).
+ *
+ * Relative paths resolve against `set.chdir`, because that is the working
+ * directory the jailed hook runs in (`--chdir`, task 4.2i) — the child's real
+ * cwd is celilo's, which is a directory the jail does not contain.
+ */
+export function classifyAccess(set: MountSetWire, path: string, write: boolean): AccessVerdict {
+  const absolute = isAbsolute(path) ? path : resolve(set.chdir, path);
+  const candidates = realpathCandidates(absolute);
+  let verdict: AccessVerdict = 'absent';
+  for (const candidate of candidates) {
+    verdict = strongest(verdict, classifyOne(set, candidate, write));
+  }
+  return verdict;
+}
+
+/**
+ * The lexical path plus, when it can be resolved, its realpath.
+ *
+ * The mount set the lint compares against is the REALPATHED one
+ * (`realpathRequest`, task 4.2k — the jail binds real paths). A dev checkout
+ * on macOS reaches the hook through symlinked prefixes (`/tmp` →
+ * `/private/tmp`, `/var` → `/private/var`), so a hook writing the path celilo
+ * handed it and the same path as bound can disagree lexically. The lint
+ * accepts either form as "inside": the lint runs only where there is no jail
+ * to match byte-for-byte, and the alternative is a warning on every state
+ * write on a Mac.
+ *
+ * The realpath of the FULL path usually does not exist — the check fires
+ * before a create, and `realpathSync` fails on the file being created. So
+ * this resolves the longest existing ancestor and reattaches whatever is
+ * left: for `<state>/cursor`, where only `<state>` exists, the second
+ * candidate is the realpath of `<state>` plus `/cursor`.
+ */
+function realpathCandidates(path: string): string[] {
+  const candidates = [path];
+  let suffix = '';
+  let current = path;
+  for (;;) {
+    try {
+      const real = PRISTINE_REALPATH(current) + suffix;
+      if (!candidates.includes(real)) candidates.push(real);
+      return candidates;
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return candidates;
+      suffix = `/${basename(current)}${suffix}`;
+      current = parent;
+    }
+  }
+}
+
+function classifyOne(set: MountSetWire, absolute: string, write: boolean): AccessVerdict {
+  let verdict: AccessVerdict = 'absent';
+  for (const entry of set.entries) {
+    if (!covers(entry.path, absolute)) continue;
+    verdict = entry.mode === 'ro' && write ? 'read-only' : 'allowed';
+  }
+  for (const provided of JAIL_PROVIDED_PATHS) {
+    if (covers(provided, absolute)) verdict = 'allowed';
+  }
+  return verdict;
+}
+
+function covers(root: string, path: string): boolean {
+  const prefix = root.endsWith('/') ? root : `${root}/`;
+  return path === root || path.startsWith(prefix);
+}
+
+/** The more informative of two verdicts, for the realpath candidate pair. */
+function strongest(a: AccessVerdict, b: AccessVerdict): AccessVerdict {
+  if (a === 'allowed' || b === 'allowed') return 'allowed';
+  if (a === 'read-only' || b === 'read-only') return 'read-only';
+  return 'absent';
+}
+
+/**
+ * Wrap every path-taking function this file knows about on both `node:fs`
+ * and `node:fs/promises`. The wrap fires BEFORE the underlying call, so it
+ * observes attempts — including attempts that succeed locally only because
+ * there is no jail, which is exactly the divergence it exists to surface.
+ *
+ * Warnings dedupe per (verdict, path) and are capped at WARN_CAP distinct
+ * paths, with one notice when the cap bites.
+ */
+function install(set: MountSetWire, warn: (message: string) => void): void {
+  const warned = new Set<string>();
+  let suppressed = 0;
+
+  const report = (rawPath: string, write: boolean): void => {
+    if (typeof rawPath !== 'string' || rawPath === '') return;
+    const absolute = isAbsolute(rawPath) ? rawPath : resolve(set.chdir, rawPath);
+    const verdict = classifyAccess(set, absolute, write);
+    if (verdict === 'allowed') return;
+    const key = `${verdict}:${absolute}`;
+    if (warned.has(key)) return;
+    if (warned.size >= WARN_CAP) {
+      suppressed += 1;
+      if (suppressed === 1) {
+        warn(
+          `Hook advisory: further path(s) outside the hook's mount set will be suppressed after ${WARN_CAP}.`,
+        );
+      }
+      return;
+    }
+    warned.add(key);
+    warn(advisoryMessage(verdict, absolute));
+  };
+
+  for (const moduleId of ['node:fs', 'node:fs/promises'] as const) {
+    const mod = require(moduleId) as Record<string, unknown>;
+    for (const [name, pathArgsFor] of Object.entries(PATH_ARGS)) {
+      const original = mod[name];
+      if (typeof original !== 'function') continue;
+      mod[name] = function (this: unknown, ...call: unknown[]) {
+        const pathArgs = typeof pathArgsFor === 'function' ? pathArgsFor(call) : pathArgsFor;
+        for (const [index, write] of pathArgs) {
+          const value = call[index];
+          if (typeof value === 'string') report(value, write);
+          else if (value instanceof URL && value.protocol === 'file:') {
+            report(value.pathname, write);
+          }
+        }
+        return (original as (...args: unknown[]) => unknown).apply(this, call);
+      };
+    }
+  }
+}
+
+function advisoryMessage(verdict: AccessVerdict, path: string): string {
+  if (verdict === 'read-only') {
+    return [
+      `Hook advisory: '${path}' is read-only in the hook's mount set,`,
+      'so on a jailed host this write would fail.',
+      'Advisory lint, not a security boundary; module code bypasses it trivially.',
+    ].join(' ');
+  }
+  return [
+    `Hook advisory: '${path}' is outside the hook's mount set,`,
+    'so on a jailed host this access would fail (the path is absent there, ENOENT).',
+    'Advisory lint, not a security boundary; module code bypasses it trivially.',
+  ].join(' ');
+}
+
+/**
+ * Which arguments of which functions carry a path, and whether the access is
+ * a write. Read and write variants share the table; a name missing from a
+ * given module is simply skipped, so one table covers `node:fs`, its `Sync`
+ * variants and `node:fs/promises`.
+ *
+ * Deliberately a table of the common calls rather than an exhaustive census:
+ * a function missed here is a warning not emitted, never a behaviour change.
+ * The lint is advisory and module code bypasses it trivially (design D8);
+ * exhaustive coverage would buy a boundary-shaped guarantee it cannot keep.
+ */
+const READ0: readonly (readonly [number, boolean])[] = [[0, false]];
+const WRITE0: readonly (readonly [number, boolean])[] = [[0, true]];
+const TWO_PATH: readonly (readonly [number, boolean])[] = [
+  [0, false],
+  [1, true],
+];
+
+const PATH_ARGS: Record<
+  string,
+  | readonly (readonly [number, boolean])[]
+  | ((call: unknown[]) => readonly (readonly [number, boolean])[])
+> = {
+  // Reads.
+  readFile: READ0,
+  readFileSync: READ0,
+  readdir: READ0,
+  readdirSync: READ0,
+  stat: READ0,
+  statSync: READ0,
+  lstat: READ0,
+  lstatSync: READ0,
+  access: READ0,
+  accessSync: READ0,
+  existsSync: READ0,
+  realpath: READ0,
+  realpathSync: READ0,
+  readlink: READ0,
+  readlinkSync: READ0,
+  createReadStream: READ0,
+  opendir: READ0,
+  opendirSync: READ0,
+  // Writes.
+  writeFile: WRITE0,
+  writeFileSync: WRITE0,
+  appendFile: WRITE0,
+  appendFileSync: WRITE0,
+  mkdir: WRITE0,
+  mkdirSync: WRITE0,
+  mkdtemp: WRITE0,
+  mkdtempSync: WRITE0,
+  rm: WRITE0,
+  rmSync: WRITE0,
+  rmdir: WRITE0,
+  rmdirSync: WRITE0,
+  unlink: WRITE0,
+  unlinkSync: WRITE0,
+  chmod: WRITE0,
+  chmodSync: WRITE0,
+  chown: WRITE0,
+  chownSync: WRITE0,
+  truncate: WRITE0,
+  truncateSync: WRITE0,
+  utimes: WRITE0,
+  utimesSync: WRITE0,
+  createWriteStream: WRITE0,
+  symlink: [[1, true]],
+  // Both ends are paths.
+  rename: TWO_PATH,
+  renameSync: TWO_PATH,
+  copyFile: TWO_PATH,
+  copyFileSync: TWO_PATH,
+  cp: TWO_PATH,
+  cpSync: TWO_PATH,
+  // Flag-dependent: 'r' reads, everything else writes.
+  open: OPEN_FLAGS,
+  openSync: OPEN_FLAGS,
+};
+
+/** `open`'s flags argument decides read from write. */
+function OPEN_FLAGS(call: unknown[]): readonly (readonly [number, boolean])[] {
+  const flags = call[1];
+  const flag = typeof flags === 'string' ? flags : 'r';
+  return [[0, flag !== 'r']];
+}
+
+installUnjailedLintIfUnjailed();

package/src/manifest/contracts/v1.ts

@@ -45,7 +45,8 @@ export interface ContractField {
    * A field carrying a path-shaped value with no annotation here is a defect.
    * `db_path` was one for months — passed by `backup-create.ts` and declared
    * nowhere, so anything reasoning from this table was wrong about what a
-   * backup hook receives.
+   * backup hook receives. It is gone: design D9b replaced it with the staged
+   * `system_state_root` below, which is declared and annotated.
    */
   path?: { access: PathAccess };
 }
@@ -152,6 +153,26 @@ export const V1_HOOKS: ContractHooks = {
        *           terraform.tfstate.backup
        */
       cross_module_root: { required: false, path: { access: 'read' } },
+      /**
+       * Path to a directory holding copies of celilo's OWN state: a
+       * WAL-correct `celilo.db` snapshot, `master.key`, the fleet `ssh/`
+       * keypair, and `module_src/<id>/` for every module's lean source.
+       * Populated by the framework under the same `cross_module_read`
+       * allow-list as `cross_module_root`; only celilo-mgmt receives it.
+       *
+       * This input is what makes celilo's own backup possible WITHOUT
+       * exempting celilo-mgmt from the hook jail (design D9b). The hook
+       * never read those bytes — it copied them into `backup_dir` — so the
+       * framework copies them into a directory it creates and hands over,
+       * and the data directory itself stays out of every mount set.
+       *
+       * It replaces `db_path`, which `backup-create.ts` passed for months
+       * while the contract declared nothing about it. That is the omission
+       * the docblock on `ContractField.path` names: anything reasoning from
+       * this table was wrong about what a backup hook receives, and a
+       * mount-set derivation walking the declared inputs could not see it.
+       */
+      system_state_root: { required: false, path: { access: 'read' } },
     },
     outputs: {
       artifact_count: { required: true },

package/src/manifest/validate.ts

@@ -202,14 +202,35 @@ const PRIVILEGED_CAPABILITY_ALLOW_LIST: Record<string, readonly string[]> = {
   cross_module_read: ['celilo-mgmt'],
 };
 
+/**
+ * Framework-granted capabilities that any module may declare.
+ *
+ * Same satisfaction path as the allow-list above — celilo supplies them, so no
+ * module provides them and the resolver must not go looking for one — but a
+ * different authorization story, and the two were welded together while
+ * `cross_module_read` was the only entry.
+ *
+ * `cross_module_read` hands a module every OTHER module's terraform state, so
+ * who may hold it is a per-module trust decision and the list is the gate.
+ * `control_plane_api` mints a principal whose grants are derived from
+ * `readOnlyGrants(COMMANDS)` and cannot be widened by the caller, so the worst
+ * a wrongly-declared consumer obtains is celilo's own read verbs. The gate is
+ * the `requires` line, which a reviewer reads before the module is ever
+ * imported (web-ui-console D7b).
+ *
+ * An allow-list here was considered and rejected: it would put consumer module
+ * ids in core, so every new console-shaped consumer would need a core change
+ * and a `.deb` release before it could be imported at all.
+ */
+const FRAMEWORK_GRANTED_CAPABILITIES: ReadonlySet<string> = new Set(['control_plane_api']);
+
 /**
  * Whether `name` is a framework-granted privilege rather than a normal
- * provider-backed capability. Privileges are satisfied by the framework
- * (gated by the allow-list above), so the capability-provider resolver
- * must NOT expect a module to "provide" them.
+ * provider-backed capability. Privileges are satisfied by the framework, so
+ * the capability-provider resolver must NOT expect a module to "provide" them.
  */
 export function isPrivilegedCapability(name: string): boolean {
-  return name in PRIVILEGED_CAPABILITY_ALLOW_LIST;
+  return name in PRIVILEGED_CAPABILITY_ALLOW_LIST || FRAMEWORK_GRANTED_CAPABILITIES.has(name);
 }
 
 /**

package/src/module/web-root.ts

@@ -0,0 +1,35 @@
+/**
+ * Where a module's built web site lives on this host.
+ *
+ * ONE application of the `site/dist` convention. It is deliberately not applied
+ * inside the providers: `public_web` is framework-provided, but `private_web`
+ * and `external_web` are implemented by modules (`caddy-internal`,
+ * `generic-cpanel-hosting-provider`), and three copies of one convention is how
+ * the copies drift.
+ *
+ * Core is also the only party that CAN resolve it in the case that matters.
+ * When the `public_web` provider converges a rebuilt host, no consumer is
+ * running to be asked where its bytes are (design D10). So the path has to come
+ * from the module id, and `modules.source_path` is what core already holds.
+ */
+
+import { join } from 'node:path';
+import { MODULE_WEB_ROOT } from '@celilo/capabilities';
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { modules } from '../db/schema';
+
+/**
+ * Absolute path to `<module root>/site/dist`, or undefined when no such module
+ * is installed.
+ *
+ * Does NOT check that the directory exists. Resolving a path and deciding
+ * whether it is usable are different jobs, and the second one belongs where the
+ * error can name the caller (Rule 10.1). `createPublicWeb`'s `requireWebRoot`
+ * does the existence check and says what to ship.
+ */
+export function resolveModuleWebRoot(moduleId: string, db: DbClient): string | undefined {
+  const module = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+  if (!module) return undefined;
+  return join(module.sourcePath, MODULE_WEB_ROOT);
+}

package/src/policy/module-business-baseline.ts

@@ -255,6 +255,18 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: "PERMANENT — validating a manifest's declared capability names against the registry is core's job",
   },
+  {
+    file: 'apps/celilo/src/manifest/validate.ts',
+    capability: 'control_plane_api',
+    count: 1,
+    why: 'PERMANENT — framework-granted, so celilo satisfies it and no module provides it; the resolver has to be told that by name (web-ui-console D7b)',
+  },
+  {
+    file: 'apps/celilo/src/hooks/capability-loader.ts',
+    capability: 'control_plane_api',
+    count: 4,
+    why: "PERMANENT — framework-granted like web_routes above; core builds the method table because enrolment writes celilo's own api_principals row, which no module script can reach (web-ui-console D7b)",
+  },
   {
     file: 'apps/celilo/src/services/alerting/inbound-poller.ts',
     capability: 'notification',
@@ -297,6 +309,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 2,
     why: "S16 — two more copies of S15's decision; fixing S15 removes all three (#938)",
   },
+  {
+    file: 'apps/celilo/src/services/module-deploy.ts',
+    capability: 'public_web',
+    count: 1,
+    why: "D10 (capability-owned-tables stage 4): the public_web PROVIDER's own deploy writes the static-content release set into its generated inventory, so a rebuilt host recovers with no consumer involvement. The branch checks the deploying module's manifest `provides`, not a module name; the capability-loader callback is the other half of the same seam.",
+  },
   {
     file: 'apps/celilo/src/services/zone-policy.ts',
     capability: 'public_web',
@@ -420,8 +438,8 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
   {
     file: 'packages/capabilities/src/firewall.ts',
     capability: 'firewall',
-    count: 2,
-    why: 'PERMANENT — X10, the firewall capability contract',
+    count: 3,
+    why: 'PERMANENT — X10, the firewall capability contract. The third is FIREWALL_CAPABILITY_NAME, exported so core queries the provider registry without spelling the literal; it moved a name OUT of apps/celilo/src/console/projection.ts rather than adding one',
   },
   {
     file: 'packages/capabilities/src/public-web.ts',
@@ -476,7 +494,13 @@ export const PROVIDER_LITERAL_BASELINE: readonly ProviderLiteralRow[] = [
   {
     file: 'packages/capabilities/src/public-web.ts',
     literal: '/srv/www',
-    count: 4,
+    count: 3,
     why: "X8 — the Caddyfile generator knows caddy's on-disk asset layout (#940)",
   },
+  {
+    file: 'apps/celilo/src/services/static-content-converge.ts',
+    literal: '/srv/www',
+    count: 1,
+    why: "D10 (capability-owned-tables stage 4): the converge's slug-collision error names the on-disk release path an operator must fix. The role under modules/caddy owns the real path handling; this is message text, not path logic.",
+  },
 ];

package/src/policy/module-script-scan.test.ts

@@ -38,6 +38,28 @@ describe('module script scan — SSH rules', () => {
   });
 });
 
+describe('module script scan — namespace tools (hygiene, not a boundary)', () => {
+  const NS = 'namespace escape (bwrap/unshare/nsenter)';
+
+  // Each token asserted separately and by name. An alternation that silently
+  // loses one leg still passes a test that only ever exercises the first.
+  it.each([
+    ['bwrap', 'run(`bwrap --dev-bind / / ${cmd}`);'],
+    ['unshare', "run('unshare --user --map-root-user id');"],
+    ['nsenter', "run('nsenter -t 1 -m -- ls /');"],
+    ['CLONE_NEWUSER', 'const flags = CLONE_NEWUSER | CLONE_NEWNS;'],
+  ])('catches %s', (_token, src) => {
+    expect(rules(src)).toContain(NS);
+  });
+
+  // The word boundaries are the whole of this rule's false-positive defence, so
+  // the negative case has to be a word that CONTAINS a token. `buildSharedConfig`
+  // would pass whether or not the `\b`s are there, which makes it no test at all.
+  it('does not fire on an identifier that merely contains a token', () => {
+    expect(rules('const unshared = pending.filter((p) => !p.shared);')).toEqual([]);
+  });
+});
+
 describe('module script scan — raw-exec escape hatch', () => {
   it('flags a runAppCommand call with no justification', () => {
     expect(rules('const r = runAppCommand(system, "rm -f /tmp/x", run);')).toContain(