From 7155726c6134d62c468e7b09046430b47a8d4b8d Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Thu, 24 Sep 2026 13:29:00 +0200
Subject: [PATCH 01/23] Add a permission audit script for generating LavaMoat
 configs

Writing `lavamoat/scripts.*.json` by hand means guessing which
permissions a script needs, then loosening the config whenever the
guess turns out to be too strict. `yarn audit <script>` instead runs
the script under `--permission-audit`, collects every permission it
actually exercises, and prints a config granting exactly those.

The collector is embedded in the script itself and injected as a data
URL through `NODE_OPTIONS`, so it reaches child processes at any
depth and reports back over an append-only log that every process
shares.

Paths are generalised so the result is portable rather than a
description of one machine: anything inside the project becomes `./`,
known locations become `$TMPDIR`, `$HOME`, or a `$GITHUB_*` variable,
and the upward directory walk that module and config resolution
performs is recognised as such. Any grant that still reaches outside
the project is reported with the path that caused it, so a widened
config is never silent about why it was widened.

Node.js is pinned to 26.9.0 because audit mode is only usable from
that release onwards. Earlier versions still enforce `lstat`,
`symlink`, and addon loading despite documenting audit mode as
non-blocking, so any script touching those dies part-way through the
audit and the resulting config is incomplete (nodejs/node#65419).
---
 .nvmrc           |   2 +-
 package.json     |   8 +-
 scripts/audit.ts | 935 +++++++++++++++++++++++++++++++++++++++++++++++
 yarn.lock        | 139 ++++++-
 4 files changed, 1071 insertions(+), 13 deletions(-)
 create mode 100644 scripts/audit.ts

diff --git a/.nvmrc b/.nvmrc
index b009dfb9..4806896a 100644
--- a/.nvmrc
+++ b/.nvmrc
@@ -1 +1 @@
-lts/*
+v26.9.0
diff --git a/package.json b/package.json
index f1353546..e8d50f68 100644
--- a/package.json
+++ b/package.json
@@ -27,6 +27,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
+    "audit": "node ./scripts/audit.ts",
     "build": "tsc --project tsconfig.build.json",
     "build:docs": "typedoc",
     "lint": "yarn lint:oxlint && yarn lint:constraints && yarn lint:misc --check && yarn lint:dependencies --check && yarn lint:changelog",
@@ -52,7 +53,8 @@
     "@metamask/oxlint-config-nodejs": "^0.1.1",
     "@metamask/oxlint-config-typescript": "^0.1.1",
     "@metamask/oxlint-config-vitest": "^0.1.1",
-    "@types/node": "^18.18",
+    "@types/node": "^26.6.2",
+    "@types/yargs": "^17.0.35",
     "@typescript/native": "npm:typescript@^7.0.2",
     "@vitest/coverage-istanbul": "^4.1.4",
     "@vitest/eslint-plugin": "^1.1.4",
@@ -65,7 +67,8 @@
     "typedoc": "^0.26.11",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vite": "^8.0.8",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.4",
+    "yargs": "^18.2.0"
   },
   "resolutions": {
     "fflate": "0.8.2"
@@ -88,6 +91,7 @@
   },
   "scriptsConfig": {
     "#default": "lavamoat/scripts.strict.json",
+    "audit": "lavamoat/scripts.yarn.json",
     "build": "lavamoat/scripts.build.json",
     "lint": "lavamoat/scripts.yarn.json",
     "lint:changelog": "lavamoat/scripts.lint.json",
diff --git a/scripts/audit.ts b/scripts/audit.ts
new file mode 100644
index 00000000..50ac9284
--- /dev/null
+++ b/scripts/audit.ts
@@ -0,0 +1,935 @@
+/* eslint-disable n/no-sync */
+
+import { spawn } from 'node:child_process';
+import type { ChannelListener } from 'node:diagnostics_channel';
+import {
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+// Permissions that are a plain on/off switch in the generated config, keyed by
+// the permission name the audit channels report.
+const BOOLEAN_FLAGS = {
+  ChildProcess: '--allow-child-process',
+  Net: '--allow-net',
+  WorkerThreads: '--allow-worker',
+  Addon: '--allow-addons',
+  WASI: '--allow-wasi',
+  Inspector: '--allow-inspector',
+  FFI: '--allow-ffi',
+};
+
+// Environment variables worth expressing paths in terms of, most specific
+// first. Anything matching one of these keeps the config portable across
+// machines and CI runners.
+const ENV_TOKENS = [
+  'GITHUB_STEP_SUMMARY',
+  'GITHUB_OUTPUT',
+  'GITHUB_ENV',
+  'GITHUB_PATH',
+  'GITHUB_WORKSPACE',
+  'RUNNER_TEMP',
+  'RUNNER_TOOL_CACHE',
+  'XDG_CACHE_HOME',
+  'XDG_CONFIG_HOME',
+  'npm_config_cache',
+  'YARN_CACHE_FOLDER',
+  'TMPDIR',
+  'HOME',
+];
+
+// `lavamoat/.runner-plugin.js` expands an environment variable only when it is
+// the entire value (`/^\$([A-Z_][A-Z0-9_]*)$/i`), so `$HOME/.cache` would reach
+// Node as a literal path. Grants are therefore always a bare token, even though
+// that is broader than the path that earned it. The causing path is reported
+// alongside, so the widening is reviewable.
+
+// The runner plugin sets `--allow-fs-tmp` whenever `--permission` is on, which
+// appends the temporary directory to `--allow-fs-write` cross-platform. Emitting
+// it again here would be redundant noise.
+const RUNNER_PROVIDED_WRITES = new Set(['$TMPDIR']);
+
+// Files that module and workspace resolution probes for while walking from the
+// project directory up to the file system root. The hits are almost all misses,
+// but they are still audited, and granting each one would bake this machine's
+// directory layout into the config.
+const RESOLUTION_MARKERS = new Set([
+  // Module and workspace resolution.
+  '.git',
+  '.npmrc',
+  '.yarnrc.yml',
+  'jsconfig.json',
+  'lerna.json',
+  'node_modules',
+  'package-lock.json',
+  'package.json',
+  'pnpm-lock.yaml',
+  'pnpm-workspace.yaml',
+  'tsconfig.json',
+  'yarn.lock',
+  // Tools that search for their own configuration the same way.
+  '.browserslistrc',
+  '.editorconfig',
+  'browserslist',
+  'browserslist.config.js',
+  'browserslist.config.mjs',
+]);
+
+const AUDIT_DIRECTORY = mkdtempSync(join(tmpdir(), 'permission-audit-'));
+const AUDIT_LOG = join(AUDIT_DIRECTORY, 'permissions.ndjson');
+
+// macOS and Windows resolve paths case-insensitively, and tools like
+// TypeScript probe with inconsistent casing. Comparing case-sensitively there
+// would leak absolute machine paths into the config as unmatched outsiders.
+const CASE_INSENSITIVE =
+  process.platform === 'darwin' || process.platform === 'win32';
+
+/**
+ * The command line options this script was invoked with.
+ */
+type Options = {
+  /**
+   * The `package.json` script to audit.
+   */
+  scriptName: string;
+
+  /**
+   * Where to write the generated config, or `undefined` to write it to
+   * standard output.
+   */
+  outPath: string | undefined;
+
+  /**
+   * Whether to show the audited script's own output and explain how each grant
+   * was chosen, rather than printing the config alone.
+   */
+  verbose: boolean;
+};
+
+/**
+ * A directory that absolute paths are rewritten relative to, turning a machine
+ * specific path into a portable grant.
+ */
+type Prefix = {
+  /**
+   * The absolute path to match, normalised for comparison.
+   */
+  prefix: string;
+
+  /**
+   * What to rewrite a matching path to, such as `./` or `$HOME`.
+   */
+  token: string;
+};
+
+/**
+ * The payload published on a `node:permission-model:*` channel. Unlike
+ * {@link AuditRecord}, the permission arrives as a bare string, since the
+ * channel makes no guarantee about which names it may add.
+ */
+type PermissionMessage = {
+  /**
+   * Which permission was checked.
+   */
+  permission: string;
+
+  /**
+   * The resource it applied to, if any.
+   */
+  resource: string;
+};
+
+/**
+ * A single permission grant, along with why it ended up that broad.
+ */
+type Grant = {
+  /**
+   * The grant as it will appear in the generated config.
+   */
+  grant: string;
+
+  /**
+   * Where the path sits: `project`, `token`, `probe`, or `outside`.
+   */
+  kind: string;
+};
+
+/**
+ * One permission check, as published by the audit channels and appended to the
+ * log by the collector.
+ */
+type AuditRecord = {
+  /**
+   * The process that exercised the permission.
+   */
+  pid: string;
+
+  /**
+   * That process's arguments, used to attribute the record when reporting.
+   */
+  argv: string;
+
+  /**
+   * Which permission was checked.
+   */
+  permission:
+    | 'Addon'
+    | 'ChildProcess'
+    | 'FFI'
+    | 'FileSystemRead'
+    | 'FileSystemWrite'
+    | 'FileSystem'
+    | 'Inspector'
+    | 'Net'
+    | 'WorkerThreads'
+    | 'WASI';
+
+  /**
+   * The path, host, or command it applied to. Empty for the permissions that
+   * are a plain on/off switch, such as `WorkerThreads`.
+   */
+  resource: string;
+};
+
+/**
+ * A grant that had to reach outside the project, kept so that a widened config
+ * is never silent about why it was widened.
+ */
+type Escape = {
+  /**
+   * Whether the grant was needed for reading or for writing.
+   */
+  action: 'read' | 'write';
+
+  /**
+   * The grant that was emitted.
+   */
+  grant: string;
+
+  /**
+   * How many audited paths collapsed into this same grant.
+   */
+  count: number;
+
+  /**
+   * One of the paths responsible, shown as an example.
+   */
+  cause: string;
+};
+
+/**
+ * What the audit records add up to: a description of everything the script
+ * actually did, before any of it is turned into a config.
+ */
+type Summary = {
+  /**
+   * The paths the script read, already generalised into portable grants.
+   */
+  reads: Set<string>;
+
+  /**
+   * The paths the script wrote, already generalised into portable grants.
+   */
+  writes: Set<string>;
+
+  /**
+   * The `--allow-*` flags for the permissions that are a plain on/off switch.
+   */
+  flags: Set<string>;
+
+  /**
+   * The hosts the script connected to. Not expressible in the config, which
+   * treats networking as a single switch, but useful when reviewing it.
+   */
+  hosts: Set<string>;
+
+  /**
+   * The commands the script spawned, useful for the same reason as the hosts.
+   */
+  commands: Set<string>;
+
+  /**
+   * Every grant that reached outside the project, keyed by action and grant.
+   */
+  escapes: Map<string, Escape>;
+};
+
+/**
+ * A generated LavaMoat script config.
+ */
+type Config = {
+  /**
+   * How the config was produced and how far it can be trusted.
+   */
+  notes: string;
+
+  /**
+   * The flags to run the script with.
+   */
+  nodeOptions: Record<string, string | boolean | string[]>;
+};
+
+/**
+ * Normalise a path for comparison on the current platform. Length is
+ * preserved, so offsets taken from a comparison key still apply to the
+ * original path.
+ *
+ * @param path - The path to normalise.
+ * @returns The comparison key.
+ */
+function comparable(path: string): string {
+  return CASE_INSENSITIVE ? path.toLowerCase() : path;
+}
+
+/**
+ * Compare two strings by code unit, for sorting.
+ *
+ * `localeCompare` is deliberately not used here. It orders by locale rules,
+ * which weight punctuation and case differently from one machine to the next,
+ * so `/` and `$TMPDIR` can swap places depending on who ran the script. Both
+ * the generated config and the report get committed and diffed, so their
+ * ordering has to be identical everywhere rather than merely readable.
+ *
+ * @param a - The first string.
+ * @param b - The second string.
+ * @returns A negative number if `a` sorts first, a positive number if `b`
+ * does, and zero if they are equal.
+ */
+function compareStrings(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+
+  return a < b ? -1 : 1;
+}
+
+/**
+ * Resolve a path to its canonical form, tolerating paths that no longer exist.
+ *
+ * @param path - The path to resolve.
+ * @returns The canonical path, or the original on failure.
+ */
+function canonical(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+/**
+ * Build the prefix table used to rewrite absolute paths into portable tokens,
+ * longest first so the most specific prefix wins.
+ *
+ * @returns The prefix table.
+ */
+function buildPrefixes(): Prefix[] {
+  const prefixes: Prefix[] = [];
+
+  /**
+   * Register a path and its canonical form under the same token.
+   *
+   * @param path - The path to register.
+   * @param token - The token to rewrite it to.
+   */
+  const add = (path: string | undefined, token: string): void => {
+    if (!path || !isAbsolute(path)) {
+      return;
+    }
+
+    for (const variant of new Set([resolve(path), canonical(path)])) {
+      prefixes.push({ prefix: comparable(variant), token });
+    }
+  };
+
+  // The project directory has to win over `$HOME`, which contains it. Ordering
+  // by length below takes care of that.
+  add(process.cwd(), './');
+
+  for (const name of ENV_TOKENS) {
+    // eslint-disable-next-line n/no-process-env
+    add(process.env[name], `$${name}`);
+  }
+
+  add(tmpdir(), '$TMPDIR');
+  add(homedir(), '$HOME');
+
+  return prefixes.toSorted((a, b) => b.prefix.length - a.prefix.length);
+}
+
+const PREFIXES = buildPrefixes();
+
+/**
+ * Build the set of directories between the project and the filesystem root.
+ *
+ * @returns Every strict ancestor of the project directory.
+ */
+function buildAncestors(): Set<string> {
+  const ancestors = new Set<string>();
+
+  let directory = process.cwd();
+  let parent = dirname(directory);
+
+  while (parent !== directory) {
+    ancestors.add(comparable(parent)).add(comparable(canonical(parent)));
+    directory = parent;
+    parent = dirname(directory);
+  }
+
+  return ancestors;
+}
+
+const ANCESTORS = buildAncestors();
+
+/**
+ * Decide whether a path is module resolution walking up the directory tree
+ * rather than a genuine dependency of the script.
+ *
+ * @param target - The resolved path from an audit record.
+ * @returns True if the path is a resolution probe.
+ */
+function isResolutionProbe(target: string): boolean {
+  const key = comparable(target);
+
+  if (ANCESTORS.has(key)) {
+    return true;
+  }
+
+  if (
+    ANCESTORS.has(comparable(dirname(target))) &&
+    RESOLUTION_MARKERS.has(comparable(basename(target)))
+  ) {
+    return true;
+  }
+
+  // Node walks every ancestor's `node_modules` looking for a dependency, so
+  // those hits describe the machine's directory layout rather than the script.
+  for (const ancestor of ANCESTORS) {
+    const modules = join(ancestor, 'node_modules');
+    if (key === modules || key.startsWith(modules + sep)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Rewrite an absolute path into a portable, generalised grant.
+ *
+ * @param path - The absolute path from an audit record.
+ * @returns The classified grant,
+ * or undefined if the path is unusable.
+ */
+function generalise(path: string): Grant | undefined {
+  if (!path || !isAbsolute(path)) {
+    return undefined;
+  }
+
+  const target = resolve(path);
+
+  if (isResolutionProbe(target)) {
+    return { grant: '/', kind: 'probe' };
+  }
+
+  const key = comparable(target);
+  for (const { prefix, token } of PREFIXES) {
+    if (key !== prefix && !key.startsWith(prefix + sep)) {
+      continue;
+    }
+
+    if (token === './') {
+      return { grant: './', kind: 'project' };
+    }
+
+    // A variable pointing at a single file (a GitHub summary, say) is the whole
+    // grant on its own.
+    if (key === prefix) {
+      return { grant: token, kind: 'token' };
+    }
+
+    return { grant: token, kind: 'token' };
+  }
+
+  // Outside anything recognisable, grant the top-level directory rather than a
+  // machine-specific path.
+  const [, top] = target.split(sep);
+  return { grant: top ? `/${top}` : '/', kind: 'outside' };
+}
+
+/**
+ * Subscribe to the permission audit channels and append everything they report
+ * to the log named by `PERMISSION_AUDIT_LOG`.
+ *
+ * This runs in the audited process, not in this one. It is serialised with
+ * `Function.prototype.toString` and injected via `--import`, so it must be
+ * entirely self-contained: it cannot reference anything declared outside its
+ * own body, and it has to reach for built-ins with dynamic `import` rather
+ * than the static imports at the top of this file. Keeping it here as real
+ * code, rather than as a string, is what lets it be linted and formatted
+ * alongside everything else.
+ *
+ * @returns A promise that resolves once the channels are subscribed.
+ */
+async function collect(): Promise<void> {
+  // eslint-disable-next-line n/no-process-env
+  const logPath = process.env.PERMISSION_AUDIT_LOG;
+
+  // Without a log path there is nothing to report to, so stay out of the way
+  // entirely rather than half-instrumenting the process.
+  if (!logPath) {
+    return;
+  }
+
+  const { channel } = await import('node:diagnostics_channel');
+  const { closeSync, openSync, writeSync } = await import('node:fs');
+
+  const fd = openSync(logPath, 'a');
+
+  // The collector's own bookkeeping shows up on the very channels it listens
+  // to. Drop those events so the report describes the audited script, not the
+  // auditor.
+  const ignored = new Set([logPath]);
+
+  let writing = false;
+
+  /**
+   * Append a single permission record to the shared audit log.
+   *
+   * @param permission - The permission being exercised.
+   * @param resource - The resource it applies to, if any.
+   */
+  const write = (permission: string, resource: string): void => {
+    if (writing || ignored.has(resource)) {
+      return;
+    }
+
+    writing = true;
+    try {
+      // O_APPEND writes below PIPE_BUF are atomic, so sibling processes can
+      // share this file without locking. Synchronous keeps the record durable
+      // even if the process dies before `exit` handlers run.
+      writeSync(
+        fd,
+        `${JSON.stringify({
+          pid: process.pid,
+          argv: process.argv.slice(1),
+          permission,
+          resource,
+        })}\n`,
+      );
+    } catch {
+      // A broken audit log must never take down the audited script.
+    } finally {
+      writing = false;
+    }
+  };
+
+  /**
+   * Forward a published permission check to the audit log. The same listener
+   * serves every channel, since the payload identifies the permission.
+   *
+   * @param message - The payload the channel published.
+   */
+  const listener: ChannelListener = (message: unknown): void => {
+    const { permission, resource } = message as PermissionMessage;
+
+    write(permission, resource);
+  };
+
+  for (const name of [
+    'fs',
+    'net',
+    'child',
+    'worker',
+    'inspector',
+    'wasi',
+    'addon',
+    'ffi',
+  ]) {
+    channel(`node:permission-model:${name}`).subscribe(listener);
+  }
+
+  process.on('exit', () => {
+    closeSync(fd);
+  });
+}
+
+// `--import` evaluates this before the entry point, and awaits top-level await,
+// so the channels are subscribed before the audited script can touch anything.
+const COLLECTOR_URL = `data:text/javascript,${encodeURIComponent(
+  `await (${collect.toString()})()`,
+)}`;
+
+/**
+ * Run the audited script and resolve with its exit status.
+ *
+ * @param scriptName - The name of the script to run.
+ * @param verbose - Whether to include verbose output.
+ * @param logPath - Where the collector should append records.
+ * @returns The exit code.
+ */
+async function runScript(
+  scriptName: string,
+  verbose: boolean,
+  logPath: string,
+): Promise<number> {
+  return new Promise((resolveRun) => {
+    const flags = [
+      '--permission-audit',
+      '--disable-warning=SecurityWarning',
+      `--import ${COLLECTOR_URL}`,
+    ];
+
+    const child = spawn('node', ['--run', scriptName], {
+      // The audited script's output is noise next to the generated config, so
+      // it is discarded unless it was asked for. Nothing is buffered, so a
+      // chatty script cannot blow up memory here.
+      stdio: verbose ? 'inherit' : 'ignore',
+      env: {
+        // eslint-disable-next-line n/no-process-env
+        ...process.env,
+        PERMISSION_AUDIT_LOG: logPath,
+        NODE_OPTIONS: flags.join(' '),
+      },
+    });
+
+    child.on('close', (code, signal) => resolveRun(signal ? 1 : (code ?? 0)));
+  });
+}
+
+/**
+ * Read every record written during a pass.
+ *
+ * @param logPath - The log to read.
+ * @returns The parsed records.
+ */
+function readRecords(logPath: string): AuditRecord[] {
+  let contents;
+  try {
+    contents = readFileSync(logPath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  return contents
+    .split('\n')
+    .filter(Boolean)
+    .flatMap((line) => {
+      // A process killed mid-write can leave a partial final line behind.
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+}
+
+/**
+ * Collapse a set of grants, dropping entries made redundant by a broader one.
+ *
+ * @param grants - The grants to collapse.
+ * @returns The sorted, collapsed grants.
+ */
+function collapse(grants: Set<string>): string[] {
+  if (grants.has('/')) {
+    return ['/'];
+  }
+
+  // Prefer the project-relative grant first; it is the one reviewers care about.
+  const sorted = [...grants].toSorted((a, b) => {
+    if (a === './') {
+      return -1;
+    }
+
+    if (b === './') {
+      return 1;
+    }
+
+    return compareStrings(a, b);
+  });
+
+  return sorted.filter(
+    (grant) =>
+      !sorted.some((other) => other !== grant && grant.startsWith(`${other}/`)),
+  );
+}
+
+/**
+ * Parse the command line arguments.
+ *
+ * @returns The options the script was invoked with.
+ */
+async function parseArgv(): Promise<Options> {
+  const {
+    script: scriptName,
+    out: outPath,
+    verbose,
+  } = await yargs(hideBin(process.argv))
+    .command('$0 <script>', 'Audit the permissions a package script needs.')
+    .positional('script', {
+      describe: 'The `package.json` script to audit.',
+      type: 'string',
+      demandOption: true,
+    })
+    .option('out', {
+      describe: 'Write the config to this file instead of standard output.',
+      type: 'string',
+    })
+    .option('verbose', {
+      describe:
+        "Show the audited script's own output, and explain how each grant was chosen.",
+      type: 'boolean',
+      default: false,
+    })
+    .strict()
+    .parseAsync();
+
+  return {
+    scriptName,
+    outPath,
+    verbose,
+  };
+}
+
+/**
+ * Reduce the raw audit records to the set of permissions the script exercised.
+ *
+ * This describes what happened, and deliberately stops short of deciding what
+ * to grant, which {@link buildConfig} handles.
+ *
+ * @param records - Every record the collector wrote.
+ * @returns The summarised permissions.
+ */
+function summarise(records: AuditRecord[]): Summary {
+  const summary: Summary = {
+    reads: new Set<string>(),
+    writes: new Set<string>(),
+    flags: new Set<string>(),
+    hosts: new Set<string>(),
+    commands: new Set<string>(),
+    escapes: new Map<string, Escape>(),
+  };
+
+  /**
+   * Note that a grant reached outside the project.
+   *
+   * @param action - Whether the grant was for reading or writing.
+   * @param grant - The grant that was emitted.
+   * @param cause - The path responsible.
+   */
+  const noteEscape = (
+    action: 'read' | 'write',
+    grant: string,
+    cause: string,
+  ): void => {
+    const key = `${action} ${grant}`;
+    const existing = summary.escapes.get(key);
+
+    summary.escapes.set(key, {
+      action,
+      grant,
+      count: (existing?.count ?? 0) + 1,
+      cause: existing?.cause ?? cause,
+    });
+  };
+
+  for (const { permission, resource } of records) {
+    switch (permission) {
+      case 'FileSystemRead': {
+        const read = generalise(resource);
+        if (read) {
+          summary.reads.add(read.grant);
+          if (read.kind !== 'project') {
+            noteEscape('read', read.grant, resource);
+          }
+        }
+        break;
+      }
+
+      case 'FileSystemWrite': {
+        const written = generalise(resource);
+        if (written) {
+          summary.writes.add(written.grant);
+          if (written.kind !== 'project') {
+            noteEscape('write', written.grant, resource);
+          }
+        }
+        break;
+      }
+
+      case 'FileSystem':
+        // `fs.symlink` publishes this alongside ordinary read and write records
+        // for both of its paths, so the specific grants above already cover it.
+        break;
+
+      default:
+        break;
+    }
+
+    const flag = BOOLEAN_FLAGS[permission as keyof typeof BOOLEAN_FLAGS];
+    if (flag) {
+      summary.flags.add(flag);
+    }
+
+    if (permission === 'Net' && resource) {
+      summary.hosts.add(resource);
+    }
+
+    if (permission === 'ChildProcess' && resource) {
+      summary.commands.add(resource);
+    }
+  }
+
+  return summary;
+}
+
+/**
+ * Turn a summary into the config that grants exactly those permissions.
+ *
+ * @param summary - What the audited script exercised.
+ * @param scriptName - The script that was audited, named in the notes.
+ * @param exitCode - The script's exit code, since a script that stopped early
+ * cannot have exercised everything it needs.
+ * @returns The config.
+ */
+function buildConfig(
+  summary: Summary,
+  scriptName: string,
+  exitCode: number,
+): Config {
+  // Reads have to cover writes, and the project directory is always readable.
+  const reads = new Set([...summary.reads, ...summary.writes, './']);
+
+  // The runner grants the temporary directory for writing only, so a tmp read
+  // still has to be requested above.
+  const writes = new Set(summary.writes);
+  for (const grant of RUNNER_PROVIDED_WRITES) {
+    writes.delete(grant);
+  }
+
+  const nodeOptions: Config['nodeOptions'] = {
+    '--disable-warning': 'SecurityWarning',
+    '--permission': true,
+    '--allow-fs-read': collapse(reads),
+    '--allow-fs-write': collapse(writes),
+  };
+
+  for (const flag of Object.values(BOOLEAN_FLAGS)) {
+    nodeOptions[flag] = summary.flags.has(flag);
+  }
+
+  const incomplete =
+    exitCode === 0
+      ? ''
+      : ` The audited run exited with ${exitCode} before completing, so these permissions are likely incomplete.`;
+
+  return {
+    notes: `Generated from a --permission-audit run of \`${scriptName}\`. Review before use: grants are widened to the nearest portable path, so they may be broader than strictly required.${incomplete}`,
+    nodeOptions,
+  };
+}
+
+/**
+ * Report the detail that does not fit the config format, but matters when
+ * reviewing it.
+ *
+ * @param summary - What the audited script exercised.
+ */
+function report(summary: Summary): void {
+  const details: [label: string, values: Set<string>][] = [
+    ['network hosts', summary.hosts],
+    ['child commands', summary.commands],
+  ];
+
+  if (details.some(([, values]) => values.size > 0)) {
+    console.error('\nObserved detail behind the boolean flags:');
+
+    for (const [label, values] of details) {
+      if (values.size > 0) {
+        console.error(
+          `  ${label}: ${[...values].toSorted(compareStrings).join(', ')}`,
+        );
+      }
+    }
+  }
+
+  if (summary.escapes.size > 0) {
+    console.error(
+      '\nGrants reaching outside the project, with an example of the',
+    );
+    console.error('path that caused each one:');
+
+    // Sorted by the same key the map is built from, so reads group before
+    // writes and grants read in a stable order.
+    const sorted = [...summary.escapes.entries()]
+      .toSorted(([a], [b]) => compareStrings(a, b))
+      .map(([, value]) => value);
+
+    for (const { action, grant, count, cause } of sorted) {
+      const more = count > 1 ? ` (+${count - 1} more)` : '';
+      const provided =
+        action === 'write' && RUNNER_PROVIDED_WRITES.has(grant)
+          ? ' [omitted; the runner grants this]'
+          : '';
+
+      console.error(`  ${action} ${grant}  ${cause}${more}${provided}`);
+    }
+  }
+}
+
+/**
+ * Audit the permissions a package script needs, and print or write a config
+ * granting exactly those.
+ */
+async function main(): Promise<void> {
+  const { scriptName, outPath, verbose } = await parseArgv();
+  const exitCode = await runScript(scriptName, verbose, AUDIT_LOG);
+  const records = readRecords(AUDIT_LOG);
+
+  rmSync(AUDIT_DIRECTORY, { recursive: true, force: true });
+
+  // A non-zero exit is not necessarily a problem with the audit: a linter
+  // reporting findings or a failing test exits non-zero too. Either way the
+  // script stopped early, so whatever it had not reached yet is missing from
+  // the config.
+  const complete = exitCode === 0;
+  if (!complete) {
+    console.error(
+      `Script exited with ${exitCode}, so it may not have exercised every ` +
+        `permission it needs. Fix the failure and re-run for a complete config.`,
+    );
+
+    // The output that would explain the failure was discarded, so point at the
+    // flag that keeps it.
+    if (!verbose) {
+      console.error(
+        `Re-run with --verbose to see the script's output and diagnose it.`,
+      );
+    }
+  }
+
+  const summary = summarise(records);
+  const config = buildConfig(summary, scriptName, exitCode);
+  const json = `${JSON.stringify(config, undefined, 2)}\n`;
+
+  if (outPath) {
+    writeFileSync(outPath, json);
+    console.error(`Wrote ${outPath}`);
+  } else {
+    process.stdout.write(json);
+  }
+
+  if (verbose) {
+    report(summary);
+  }
+}
+
+await main();
diff --git a/yarn.lock b/yarn.lock
index 8d8fb1fa..3ff50b7a 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -369,7 +369,8 @@ __metadata:
     "@metamask/oxlint-config-nodejs": "npm:^0.1.1"
     "@metamask/oxlint-config-typescript": "npm:^0.1.1"
     "@metamask/oxlint-config-vitest": "npm:^0.1.1"
-    "@types/node": "npm:^18.18"
+    "@types/node": "npm:^26.6.2"
+    "@types/yargs": "npm:^17.0.35"
     "@typescript/native": "npm:typescript@^7.0.2"
     "@vitest/coverage-istanbul": "npm:^4.1.4"
     "@vitest/eslint-plugin": "npm:^1.1.4"
@@ -383,6 +384,7 @@ __metadata:
     typescript: "npm:@typescript/typescript6@^6.0.2"
     vite: "npm:^8.0.8"
     vitest: "npm:^4.1.4"
+    yargs: "npm:^18.2.0"
   languageName: unknown
   linkType: soft
 
@@ -1218,12 +1220,12 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/node@npm:^18.18":
-  version: 18.19.34
-  resolution: "@types/node@npm:18.19.34"
+"@types/node@npm:^26.6.2":
+  version: 26.6.2
+  resolution: "@types/node@npm:26.6.2"
   dependencies:
-    undici-types: "npm:~5.26.4"
-  checksum: 10/5c8daed0c672e824c36d31312377fc4dddf3e91006fadad719527bb2bd710d4207193c1c7034da9d2d6cbc03da89d3693c86207f751540c18a7d38802040fbd9
+    undici-types: "npm:~8.9.0"
+  checksum: 10/757d598381b690e4429b9fab3adcf48f88ac7ed17488b47724cf3df9d6d38bcac17ab61c10cabecc5dbda5717f3f819208549ba3cef4cd941300440282a2a1a8
   languageName: node
   linkType: hard
 
@@ -1241,6 +1243,22 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/yargs-parser@npm:*":
+  version: 21.0.3
+  resolution: "@types/yargs-parser@npm:21.0.3"
+  checksum: 10/a794eb750e8ebc6273a51b12a0002de41343ffe46befef460bdbb57262d187fdf608bc6615b7b11c462c63c3ceb70abe2564c8dd8ee0f7628f38a314f74a9b9b
+  languageName: node
+  linkType: hard
+
+"@types/yargs@npm:^17.0.35":
+  version: 17.0.35
+  resolution: "@types/yargs@npm:17.0.35"
+  dependencies:
+    "@types/yargs-parser": "npm:*"
+  checksum: 10/47bcd4476a4194ea11617ea71cba8a1eddf5505fc39c44336c1a08d452a0de4486aedbc13f47a017c8efbcb5a8aa358d976880663732ebcbc6dbcbbecadb0581
+  languageName: node
+  linkType: hard
+
 "@typescript/native@npm:typescript@^7.0.2":
   version: 7.0.2
   resolution: "typescript@npm:7.0.2"
@@ -1705,6 +1723,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ansi-regex@npm:^6.2.2":
+  version: 6.3.0
+  resolution: "ansi-regex@npm:6.3.0"
+  checksum: 10/85e15deee80d6e52e75864897b6f7b8a8cfc5befe1868f03e3b6bf8925b9b667cf67d4aeafc6d038398f2f11c3813e7b40ad79affdd29a9c491b3585bfa125d5
+  languageName: node
+  linkType: hard
+
 "ansi-styles@npm:^4.0.0":
   version: 4.2.1
   resolution: "ansi-styles@npm:4.2.1"
@@ -1715,6 +1740,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ansi-styles@npm:^6.2.1":
+  version: 6.2.3
+  resolution: "ansi-styles@npm:6.2.3"
+  checksum: 10/c49dad7639f3e48859bd51824c93b9eb0db628afc243c51c3dd2410c4a15ede1a83881c6c7341aa2b159c4f90c11befb38f2ba848c07c66c9f9de4bcd7cb9f30
+  languageName: node
+  linkType: hard
+
 "aproba@npm:^1.0.3 || ^2.0.0":
   version: 2.0.0
   resolution: "aproba@npm:2.0.0"
@@ -1985,6 +2017,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"cliui@npm:^9.0.1":
+  version: 9.0.1
+  resolution: "cliui@npm:9.0.1"
+  dependencies:
+    string-width: "npm:^7.2.0"
+    strip-ansi: "npm:^7.1.0"
+    wrap-ansi: "npm:^9.0.0"
+  checksum: 10/df43d8d1c6e3254cbb64b1905310d5f6672c595496a3cbe76946c6d24777136886470686f2772ac9edfe547a74bb70e8017530b3554715aee119efd7752fc0d9
+  languageName: node
+  linkType: hard
+
 "cmd-shim@npm:^6.0.0":
   version: 6.0.1
   resolution: "cmd-shim@npm:6.0.1"
@@ -2193,6 +2236,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"emoji-regex@npm:^10.3.0":
+  version: 10.6.0
+  resolution: "emoji-regex@npm:10.6.0"
+  checksum: 10/98cc0b0e1daed1ed25afbf69dcb921fee00f712f51aab93aa1547e4e4e8171725cc4f0098aaa645b4f611a19da11ec9f4623eb6ff2b72314b39a8f2ae7c12bf2
+  languageName: node
+  linkType: hard
+
 "emoji-regex@npm:^8.0.0":
   version: 8.0.0
   resolution: "emoji-regex@npm:8.0.0"
@@ -2504,6 +2554,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"get-east-asian-width@npm:^1.0.0, get-east-asian-width@npm:^1.5.0":
+  version: 1.7.0
+  resolution: "get-east-asian-width@npm:1.7.0"
+  checksum: 10/8d8d96b54d1cfb6510f1b6dce51c4a6000b4d122757780d519d0147d968a6f5401421dbeff2e6bd3dc742e9b502fbcdbb98a50bf7f62730a6a8d6749a632279c
+  languageName: node
+  linkType: hard
+
 "get-stream@npm:^6.0.0":
   version: 6.0.1
   resolution: "get-stream@npm:6.0.1"
@@ -4400,6 +4457,27 @@ __metadata:
   languageName: node
   linkType: hard
 
+"string-width@npm:^7.0.0, string-width@npm:^7.2.0":
+  version: 7.2.0
+  resolution: "string-width@npm:7.2.0"
+  dependencies:
+    emoji-regex: "npm:^10.3.0"
+    get-east-asian-width: "npm:^1.0.0"
+    strip-ansi: "npm:^7.1.0"
+  checksum: 10/42f9e82f61314904a81393f6ef75b832c39f39761797250de68c041d8ba4df2ef80db49ab6cd3a292923a6f0f409b8c9980d120f7d32c820b4a8a84a2598a295
+  languageName: node
+  linkType: hard
+
+"string-width@npm:^8.2.1":
+  version: 8.2.2
+  resolution: "string-width@npm:8.2.2"
+  dependencies:
+    get-east-asian-width: "npm:^1.5.0"
+    strip-ansi: "npm:^7.1.2"
+  checksum: 10/18da8c8e5247bedd8a379272b9fccebd16ec22132486344a4a5bf3bd2acf4b12fda9b2be9192eba59c5dc1484f2d36dbfb5fd5e66950fe7167fa00876078196f
+  languageName: node
+  linkType: hard
+
 "string_decoder@npm:^1.1.1":
   version: 1.3.0
   resolution: "string_decoder@npm:1.3.0"
@@ -4428,6 +4506,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"strip-ansi@npm:^7.1.0, strip-ansi@npm:^7.1.2":
+  version: 7.2.0
+  resolution: "strip-ansi@npm:7.2.0"
+  dependencies:
+    ansi-regex: "npm:^6.2.2"
+  checksum: 10/96da3bc6d73cfba1218625a3d66cf7d37a69bf0920d8735b28f9eeaafcdb6c1fe8440e1ae9eb1ba0ca355dbe8702da872e105e2e939fa93e7851b3cb5dd7d316
+  languageName: node
+  linkType: hard
+
 "strip-final-newline@npm:^2.0.0":
   version: 2.0.0
   resolution: "strip-final-newline@npm:2.0.0"
@@ -4599,10 +4686,10 @@ __metadata:
   languageName: node
   linkType: hard
 
-"undici-types@npm:~5.26.4":
-  version: 5.26.5
-  resolution: "undici-types@npm:5.26.5"
-  checksum: 10/0097779d94bc0fd26f0418b3a05472410408877279141ded2bd449167be1aed7ea5b76f756562cb3586a07f251b90799bab22d9019ceba49c037c76445f7cddd
+"undici-types@npm:~8.9.0":
+  version: 8.9.0
+  resolution: "undici-types@npm:8.9.0"
+  checksum: 10/8785591929de2b71d281c684e915c4a8c41becc225adbf42a3e89148f8b384724a21533494c30a1cbb85b4cbccd088d020788ff4f2d605013eb2863cd47a1639
   languageName: node
   linkType: hard
 
@@ -4924,6 +5011,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"wrap-ansi@npm:^9.0.0":
+  version: 9.0.2
+  resolution: "wrap-ansi@npm:9.0.2"
+  dependencies:
+    ansi-styles: "npm:^6.2.1"
+    string-width: "npm:^7.0.0"
+    strip-ansi: "npm:^7.1.0"
+  checksum: 10/f3907e1ea9717404ca53a338fa5a017c2121550c3a5305180e2bc08c03e21aa45068df55b0d7676bf57be1880ba51a84458c17241ebedea485fafa9ef16b4024
+  languageName: node
+  linkType: hard
+
 "wrappy@npm:1":
   version: 1.0.2
   resolution: "wrappy@npm:1.0.2"
@@ -4999,6 +5097,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"yargs-parser@npm:^22.0.0":
+  version: 22.0.0
+  resolution: "yargs-parser@npm:22.0.0"
+  checksum: 10/f13c42bad6ebed1a587a72f2db5694f5fa772bcaf409a701691d13cf74eb5adfcf61a2611de08807e319b829d3e5e6e1578b16ebe174cae8e8be3bf7b8e7a19e
+  languageName: node
+  linkType: hard
+
 "yargs@npm:17.7.3, yargs@npm:^17.0.1":
   version: 17.7.3
   resolution: "yargs@npm:17.7.3"
@@ -5029,6 +5134,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"yargs@npm:^18.2.0":
+  version: 18.2.0
+  resolution: "yargs@npm:18.2.0"
+  dependencies:
+    cliui: "npm:^9.0.1"
+    escalade: "npm:^3.1.1"
+    get-caller-file: "npm:^2.0.5"
+    string-width: "npm:^8.2.1"
+    y18n: "npm:^5.0.5"
+    yargs-parser: "npm:^22.0.0"
+  checksum: 10/a780cc1fa693028baa50c0c88bcc2c59c92817f0f8e2dfbd226aa1c27cf0dbfb1743511012b73a4f415119d9caa22a6de19350c781d5ef75f874359ae7601ac3
+  languageName: node
+  linkType: hard
+
 "zwitch@npm:^2.0.4":
   version: 2.0.4
   resolution: "zwitch@npm:2.0.4"

From e6b294ff3be981670d7f0e59ea953fbb4e9329ae Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Thu, 24 Sep 2026 15:31:56 +0200
Subject: [PATCH 02/23] Only classify reads as resolution probes

Module and workspace resolution walks from the project directory up to
the file system root, and the paths it probes for describe the machine
rather than the script, so they are generalised to `/` rather than
named. That classification was applied to writes as well, which it
should never be: resolution only ever reads.

The effect was worse than an overly broad entry. A write to an
ancestor directory, or to a file such as `~/.npmrc`, was read as a
probe and granted `/`, and collapsing the grants then short-circuits
on `/` and discards everything else. A single misclassified write
therefore turned the whole write list into unrestricted file system
access, silently. Recursive `mkdir` checks write access on ancestor
directories, so this was reachable in ordinary use.

`generalise` now takes the action and only consults the probe rules
for reads. Reads are unaffected.

Also repairs two breakages from the surrounding work: `toSorted` is
ES2023 and the target is now ES2022, and Oxlint reports the `any` that
`JSON.parse` returns as an unsafe return.
---
 scripts/audit.ts | 30 +++++++++++++++++++-----------
 1 file changed, 19 insertions(+), 11 deletions(-)

diff --git a/scripts/audit.ts b/scripts/audit.ts
index 50ac9284..3d5ebd99 100644
--- a/scripts/audit.ts
+++ b/scripts/audit.ts
@@ -361,7 +361,7 @@ function buildPrefixes(): Prefix[] {
   add(tmpdir(), '$TMPDIR');
   add(homedir(), '$HOME');
 
-  return prefixes.toSorted((a, b) => b.prefix.length - a.prefix.length);
+  return prefixes.sort((a, b) => b.prefix.length - a.prefix.length);
 }
 
 const PREFIXES = buildPrefixes();
@@ -425,17 +425,19 @@ function isResolutionProbe(target: string): boolean {
  * Rewrite an absolute path into a portable, generalised grant.
  *
  * @param path - The absolute path from an audit record.
- * @returns The classified grant,
- * or undefined if the path is unusable.
+ * @param action - Whether the path was read or written. Resolution only ever
+ * reads, so a write to one of those paths is a genuine write and must not be
+ * widened to the whole file system.
+ * @returns The classified grant, or undefined if the path is unusable.
  */
-function generalise(path: string): Grant | undefined {
+function generalise(path: string, action: 'read' | 'write'): Grant | undefined {
   if (!path || !isAbsolute(path)) {
     return undefined;
   }
 
   const target = resolve(path);
 
-  if (isResolutionProbe(target)) {
+  if (action === 'read' && isResolutionProbe(target)) {
     return { grant: '/', kind: 'probe' };
   }
 
@@ -460,6 +462,12 @@ function generalise(path: string): Grant | undefined {
 
   // Outside anything recognisable, grant the top-level directory rather than a
   // machine-specific path.
+  //
+  // On Windows this drops the drive, so `C:\Windows` becomes `/Windows`. That
+  // is knowingly left alone: keeping the drive would put a path in the config
+  // that means nothing on any other machine, and Windows has no portable
+  // top-level namespace to rewrite it to. Such a grant needs a human anyway,
+  // and it is reported as an escape so that it gets one.
   const [, top] = target.split(sep);
   return { grant: top ? `/${top}` : '/', kind: 'outside' };
 }
@@ -625,7 +633,7 @@ function readRecords(logPath: string): AuditRecord[] {
     .flatMap((line) => {
       // A process killed mid-write can leave a partial final line behind.
       try {
-        return [JSON.parse(line)];
+        return [JSON.parse(line) as AuditRecord];
       } catch {
         return [];
       }
@@ -644,7 +652,7 @@ function collapse(grants: Set<string>): string[] {
   }
 
   // Prefer the project-relative grant first; it is the one reviewers care about.
-  const sorted = [...grants].toSorted((a, b) => {
+  const sorted = [...grants].sort((a, b) => {
     if (a === './') {
       return -1;
     }
@@ -744,7 +752,7 @@ function summarise(records: AuditRecord[]): Summary {
   for (const { permission, resource } of records) {
     switch (permission) {
       case 'FileSystemRead': {
-        const read = generalise(resource);
+        const read = generalise(resource, 'read');
         if (read) {
           summary.reads.add(read.grant);
           if (read.kind !== 'project') {
@@ -755,7 +763,7 @@ function summarise(records: AuditRecord[]): Summary {
       }
 
       case 'FileSystemWrite': {
-        const written = generalise(resource);
+        const written = generalise(resource, 'write');
         if (written) {
           summary.writes.add(written.grant);
           if (written.kind !== 'project') {
@@ -855,7 +863,7 @@ function report(summary: Summary): void {
     for (const [label, values] of details) {
       if (values.size > 0) {
         console.error(
-          `  ${label}: ${[...values].toSorted(compareStrings).join(', ')}`,
+          `  ${label}: ${[...values].sort(compareStrings).join(', ')}`,
         );
       }
     }
@@ -870,7 +878,7 @@ function report(summary: Summary): void {
     // Sorted by the same key the map is built from, so reads group before
     // writes and grants read in a stable order.
     const sorted = [...summary.escapes.entries()]
-      .toSorted(([a], [b]) => compareStrings(a, b))
+      .sort(([a], [b]) => compareStrings(a, b))
       .map(([, value]) => value);
 
     for (const { action, grant, count, cause } of sorted) {

From 1b31f3df00fe1303cc3970db3281516a097a244d Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Thu, 24 Sep 2026 15:46:32 +0200
Subject: [PATCH 03/23] Run each CI command through the audit when debugging

The permissions a script needs on a CI runner are not the ones it
needs on a developer's machine: the paths, the environment variables,
and the tool cache all differ. Generating a config locally and hoping
it holds in CI is guesswork.

Re-running a workflow with debug logging enabled now runs each command
through `yarn audit` instead of directly, so the job reports what it
actually needed where it actually runs. `RUN` defaults to `yarn` and
is overridden to `yarn audit` only for those runs, which keeps one
copy of each command rather than a pair behind opposing conditions.

`runner.debug` is not available to a job-level `if`, so the override
is a step. It is also limited to Node 26.x: Node 22 rejects
`--permission-audit` outright, and auditing every version in the
matrix would produce several configs for no gain.

This depends on the audit passing the script's exit code on, which it
previously swallowed. Wrapping a command in something that always
succeeds would have turned every job green regardless of whether the
tests passed.

The changelog steps keep calling `yarn` directly, since they pass
arguments and the audit does not forward those to the audited script.
---
 .github/workflows/build-lint-test.yml | 28 +++++++++++++++++++++++----
 scripts/audit.ts                      |  5 +++++
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/build-lint-test.yml b/.github/workflows/build-lint-test.yml
index 050b0bd6..6485dc9f 100644
--- a/.github/workflows/build-lint-test.yml
+++ b/.github/workflows/build-lint-test.yml
@@ -6,6 +6,12 @@ on:
 permissions:
   contents: read
 
+env:
+  # How each command below is invoked. Jobs override this when debug logging is
+  # enabled, so that commands run through the permission audit rather than
+  # directly, without every step needing a second copy of itself.
+  RUN: yarn
+
 jobs:
   prepare:
     name: Prepare
@@ -36,7 +42,10 @@ jobs:
           is-high-risk-environment: false
           persist-credentials: false
           node-version: ${{ matrix.node-version }}
-      - run: yarn build
+      - name: Enable permission audit for debug runs
+        if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
+        run: echo 'RUN=yarn audit' >> "$GITHUB_ENV"
+      - run: $RUN build
       - name: Require clean working directory
         shell: bash
         run: |
@@ -59,7 +68,12 @@ jobs:
           is-high-risk-environment: false
           persist-credentials: false
           node-version: ${{ matrix.node-version }}
-      - run: yarn lint
+      - name: Enable permission audit for debug runs
+        if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
+        run: echo 'RUN=yarn audit' >> "$GITHUB_ENV"
+      - run: $RUN lint
+        # The changelog steps below pass arguments, which `yarn audit` does not
+        # forward to the audited script, so they stay on plain `yarn`.
       - name: Validate RC changelog
         if: ${{ startsWith(github.head_ref, 'release/') }}
         run: yarn lint:changelog --rc
@@ -88,7 +102,10 @@ jobs:
           is-high-risk-environment: false
           persist-credentials: false
           node-version: ${{ matrix.node-version }}
-      - run: yarn test
+      - name: Enable permission audit for debug runs
+        if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
+        run: echo 'RUN=yarn audit' >> "$GITHUB_ENV"
+      - run: $RUN test
       - name: Require clean working directory
         shell: bash
         run: |
@@ -113,7 +130,10 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - name: Install dependencies via Yarn
         run: rm yarn.lock && YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn
-      - run: yarn test
+      - name: Enable permission audit for debug runs
+        if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
+        run: echo 'RUN=yarn audit' >> "$GITHUB_ENV"
+      - run: $RUN test
       - name: Restore lockfile
         run: git restore yarn.lock
       - name: Require clean working directory
diff --git a/scripts/audit.ts b/scripts/audit.ts
index 3d5ebd99..3731456e 100644
--- a/scripts/audit.ts
+++ b/scripts/audit.ts
@@ -938,6 +938,11 @@ async function main(): Promise<void> {
   if (verbose) {
     report(summary);
   }
+
+  // Pass the script's own failure on, so that auditing a command can stand in
+  // for running it without turning a failure into a success. Set rather than
+  // exited, so that the config above is flushed first.
+  process.exitCode = exitCode;
 }
 
 await main();

From 5854f0c0400954e643ec3968bdf0147b76478df6 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Thu, 24 Sep 2026 15:50:25 +0200
Subject: [PATCH 04/23] Name the build, lint, and test steps

These steps had no name, so GitHub labelled them with the command
itself. That read fine as `yarn build`, but now that the command is
`$RUN build` the label shows the variable rather than what the step
does, and it is identical in both of the jobs that run tests.
---
 .github/workflows/build-lint-test.yml | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/build-lint-test.yml b/.github/workflows/build-lint-test.yml
index 6485dc9f..41d3a2af 100644
--- a/.github/workflows/build-lint-test.yml
+++ b/.github/workflows/build-lint-test.yml
@@ -45,7 +45,8 @@ jobs:
       - name: Enable permission audit for debug runs
         if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
         run: echo 'RUN=yarn audit' >> "$GITHUB_ENV"
-      - run: $RUN build
+      - name: Build
+        run: $RUN build
       - name: Require clean working directory
         shell: bash
         run: |
@@ -71,7 +72,8 @@ jobs:
       - name: Enable permission audit for debug runs
         if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
         run: echo 'RUN=yarn audit' >> "$GITHUB_ENV"
-      - run: $RUN lint
+      - name: Lint
+        run: $RUN lint
         # The changelog steps below pass arguments, which `yarn audit` does not
         # forward to the audited script, so they stay on plain `yarn`.
       - name: Validate RC changelog
@@ -105,7 +107,8 @@ jobs:
       - name: Enable permission audit for debug runs
         if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
         run: echo 'RUN=yarn audit' >> "$GITHUB_ENV"
-      - run: $RUN test
+      - name: Test
+        run: $RUN test
       - name: Require clean working directory
         shell: bash
         run: |
@@ -133,7 +136,8 @@ jobs:
       - name: Enable permission audit for debug runs
         if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
         run: echo 'RUN=yarn audit' >> "$GITHUB_ENV"
-      - run: $RUN test
+      - name: Test
+        run: $RUN test
       - name: Restore lockfile
         run: git restore yarn.lock
       - name: Require clean working directory

From 1c8343d8a18a9e6ab585eaba8210cca90c4ddf8e Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Thu, 24 Sep 2026 15:56:56 +0200
Subject: [PATCH 05/23] Show the audited command's output in debug runs

The audit is silent by default, so routing commands through it meant
that turning debug logging on removed the build, lint, and test output
a normal run shows. Enabling debug gave strictly less to look at, which
is backwards.

`--verbose` restores that output and adds the report of which grants
reached outside the project and the path that earned each one, which is
the part worth reading on a runner.
---
 .github/workflows/build-lint-test.yml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/build-lint-test.yml b/.github/workflows/build-lint-test.yml
index 41d3a2af..cfa33da5 100644
--- a/.github/workflows/build-lint-test.yml
+++ b/.github/workflows/build-lint-test.yml
@@ -44,7 +44,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - name: Enable permission audit for debug runs
         if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
-        run: echo 'RUN=yarn audit' >> "$GITHUB_ENV"
+        run: echo 'RUN=yarn audit --verbose' >> "$GITHUB_ENV"
       - name: Build
         run: $RUN build
       - name: Require clean working directory
@@ -71,7 +71,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - name: Enable permission audit for debug runs
         if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
-        run: echo 'RUN=yarn audit' >> "$GITHUB_ENV"
+        run: echo 'RUN=yarn audit --verbose' >> "$GITHUB_ENV"
       - name: Lint
         run: $RUN lint
         # The changelog steps below pass arguments, which `yarn audit` does not
@@ -106,7 +106,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - name: Enable permission audit for debug runs
         if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
-        run: echo 'RUN=yarn audit' >> "$GITHUB_ENV"
+        run: echo 'RUN=yarn audit --verbose' >> "$GITHUB_ENV"
       - name: Test
         run: $RUN test
       - name: Require clean working directory
@@ -135,7 +135,7 @@ jobs:
         run: rm yarn.lock && YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn
       - name: Enable permission audit for debug runs
         if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
-        run: echo 'RUN=yarn audit' >> "$GITHUB_ENV"
+        run: echo 'RUN=yarn audit --verbose' >> "$GITHUB_ENV"
       - name: Test
         run: $RUN test
       - name: Restore lockfile

From a0292b227157244e35d53302c19feff6dffb52f9 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Thu, 24 Sep 2026 16:27:43 +0200
Subject: [PATCH 06/23] Print the report on the same stream as the config
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A CI runner reads standard output and standard error as two separate
pipes and merges them into one log by arrival, with no ordering
guarantee between them. The report was written to standard error
immediately after the config went to standard output, so the runner was
free to place it anywhere — in practice, in the middle of the JSON.

Flushing cannot fix that: ordering is only guaranteed within a single
descriptor. Writing both to standard output is what makes the sequence
deterministic, since the kernel serialises writes to one descriptor and
no reader can reorder them afterwards.

That makes standard output human-facing under `--verbose`, which is
what the flag is for; `--out` remains the way to get the config on its
own. Simulating the runner — separate pipes merged by arrival — the
JSON stayed contiguous across 23 runs of two different scripts.
---
 scripts/audit.ts | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/scripts/audit.ts b/scripts/audit.ts
index 3731456e..82c9b12d 100644
--- a/scripts/audit.ts
+++ b/scripts/audit.ts
@@ -598,8 +598,11 @@ async function runScript(
 
     const child = spawn('node', ['--run', scriptName], {
       // The audited script's output is noise next to the generated config, so
-      // it is discarded unless it was asked for. Nothing is buffered, so a
-      // chatty script cannot blow up memory here.
+      // it is discarded unless it was asked for. Inheriting hands over this
+      // process's own descriptors, so the script's output keeps its place in
+      // the stream rather than arriving through a second pipe that a reader
+      // would have to interleave. Nothing is buffered either, so a chatty
+      // script cannot blow up memory here.
       stdio: verbose ? 'inherit' : 'ignore',
       env: {
         // eslint-disable-next-line n/no-process-env
@@ -849,6 +852,13 @@ function buildConfig(
  * Report the detail that does not fit the config format, but matters when
  * reviewing it.
  *
+ * Written to standard output, alongside the config rather than beside it. A
+ * reader merging two streams — a CI runner, say — orders them by arrival and
+ * can drop this report into the middle of the JSON. One stream keeps it in
+ * the order it was written. That leaves standard output human-facing under
+ * `--verbose`, which is the point of the flag; use `--out` when the config
+ * needs to be machine-readable.
+ *
  * @param summary - What the audited script exercised.
  */
 function report(summary: Summary): void {
@@ -858,11 +868,11 @@ function report(summary: Summary): void {
   ];
 
   if (details.some(([, values]) => values.size > 0)) {
-    console.error('\nObserved detail behind the boolean flags:');
+    console.log('\nObserved detail behind the boolean flags:');
 
     for (const [label, values] of details) {
       if (values.size > 0) {
-        console.error(
+        console.log(
           `  ${label}: ${[...values].sort(compareStrings).join(', ')}`,
         );
       }
@@ -870,10 +880,10 @@ function report(summary: Summary): void {
   }
 
   if (summary.escapes.size > 0) {
-    console.error(
+    console.log(
       '\nGrants reaching outside the project, with an example of the',
     );
-    console.error('path that caused each one:');
+    console.log('path that caused each one:');
 
     // Sorted by the same key the map is built from, so reads group before
     // writes and grants read in a stable order.
@@ -888,7 +898,7 @@ function report(summary: Summary): void {
           ? ' [omitted; the runner grants this]'
           : '';
 
-      console.error(`  ${action} ${grant}  ${cause}${more}${provided}`);
+      console.log(`  ${action} ${grant}  ${cause}${more}${provided}`);
     }
   }
 }

From e53dec92eb8e7d62e10d58528eaf832416ac0743 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Thu, 24 Sep 2026 21:04:02 +0200
Subject: [PATCH 07/23] Forward unrecognised arguments to the audited script

Unrecognised arguments are now treated as the audited script's and
handed straight to it. With that, the changelog steps run through `RUN` like
everything else, and every command in the workflow is audited on a debug run.
---
 .github/workflows/build-lint-test.yml |  6 ++--
 scripts/audit.ts                      | 43 +++++++++++++++++++--------
 2 files changed, 33 insertions(+), 16 deletions(-)

diff --git a/.github/workflows/build-lint-test.yml b/.github/workflows/build-lint-test.yml
index cfa33da5..3b425ccf 100644
--- a/.github/workflows/build-lint-test.yml
+++ b/.github/workflows/build-lint-test.yml
@@ -74,14 +74,12 @@ jobs:
         run: echo 'RUN=yarn audit --verbose' >> "$GITHUB_ENV"
       - name: Lint
         run: $RUN lint
-        # The changelog steps below pass arguments, which `yarn audit` does not
-        # forward to the audited script, so they stay on plain `yarn`.
       - name: Validate RC changelog
         if: ${{ startsWith(github.head_ref, 'release/') }}
-        run: yarn lint:changelog --rc
+        run: $RUN lint:changelog --rc
       - name: Validate changelog
         if: ${{ !startsWith(github.head_ref, 'release/') }}
-        run: yarn lint:changelog
+        run: $RUN lint:changelog
       - name: Require clean working directory
         shell: bash
         run: |
diff --git a/scripts/audit.ts b/scripts/audit.ts
index 82c9b12d..b5a30a27 100644
--- a/scripts/audit.ts
+++ b/scripts/audit.ts
@@ -111,6 +111,13 @@ type Options = {
    * was chosen, rather than printing the config alone.
    */
   verbose: boolean;
+
+  /**
+   * Anything this script does not recognise, handed to the audited script
+   * rather than interpreted here, so that auditing a command that takes
+   * arguments reads the same as running it: `audit test --coverage`.
+   */
+  passthrough: string[];
 };
 
 /**
@@ -582,12 +589,14 @@ const COLLECTOR_URL = `data:text/javascript,${encodeURIComponent(
  * @param scriptName - The name of the script to run.
  * @param verbose - Whether to include verbose output.
  * @param logPath - Where the collector should append records.
+ * @param passthrough - Arguments to hand to the script itself.
  * @returns The exit code.
  */
 async function runScript(
   scriptName: string,
   verbose: boolean,
   logPath: string,
+  passthrough: string[],
 ): Promise<number> {
   return new Promise((resolveRun) => {
     const flags = [
@@ -596,7 +605,14 @@ async function runScript(
       `--import ${COLLECTOR_URL}`,
     ];
 
-    const child = spawn('node', ['--run', scriptName], {
+    // `node --run` forwards everything after its own `--` to the script, so
+    // auditing a command with arguments works the same as running it.
+    const args = ['--run', scriptName];
+    if (passthrough.length > 0) {
+      args.push('--', ...passthrough);
+    }
+
+    const child = spawn('node', args, {
       // The audited script's output is noise next to the generated config, so
       // it is discarded unless it was asked for. Inheriting hands over this
       // process's own descriptors, so the script's output keeps its place in
@@ -679,11 +695,10 @@ function collapse(grants: Set<string>): string[] {
  * @returns The options the script was invoked with.
  */
 async function parseArgv(): Promise<Options> {
-  const {
-    script: scriptName,
-    out: outPath,
-    verbose,
-  } = await yargs(hideBin(process.argv))
+  const argv = await yargs(hideBin(process.argv))
+    // Anything this script does not recognise belongs to the script being
+    // audited, so auditing a command reads the same as running it.
+    .parserConfiguration({ 'unknown-options-as-args': true })
     .command('$0 <script>', 'Audit the permissions a package script needs.')
     .positional('script', {
       describe: 'The `package.json` script to audit.',
@@ -700,13 +715,17 @@ async function parseArgv(): Promise<Options> {
       type: 'boolean',
       default: false,
     })
-    .strict()
+    .example('$0 test --coverage', 'Audit `test`, passing `--coverage` to it.')
+    .strictCommands()
     .parseAsync();
 
   return {
-    scriptName,
-    outPath,
-    verbose,
+    scriptName: argv.script,
+    outPath: argv.out,
+    verbose: argv.verbose,
+    // Unrecognised arguments belong to the audited script. Mapped because the
+    // parser types them loosely, having no way to know they are strings.
+    passthrough: argv._.map(String),
   };
 }
 
@@ -908,8 +927,8 @@ function report(summary: Summary): void {
  * granting exactly those.
  */
 async function main(): Promise<void> {
-  const { scriptName, outPath, verbose } = await parseArgv();
-  const exitCode = await runScript(scriptName, verbose, AUDIT_LOG);
+  const { scriptName, outPath, verbose, passthrough } = await parseArgv();
+  const exitCode = await runScript(scriptName, verbose, AUDIT_LOG, passthrough);
   const records = readRecords(AUDIT_LOG);
 
   rmSync(AUDIT_DIRECTORY, { recursive: true, force: true });

From a9d9e4df31c78d4c5d563ea271254b5a25a14376 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Mon, 28 Sep 2026 13:36:33 +0200
Subject: [PATCH 08/23] Rename script to `audit-script`

---
 .github/workflows/build-lint-test.yml | 8 ++++----
 package.json                          | 4 ++--
 scripts/{audit.ts => audit-script.ts} | 0
 3 files changed, 6 insertions(+), 6 deletions(-)
 rename scripts/{audit.ts => audit-script.ts} (100%)

diff --git a/.github/workflows/build-lint-test.yml b/.github/workflows/build-lint-test.yml
index 3b425ccf..6217964a 100644
--- a/.github/workflows/build-lint-test.yml
+++ b/.github/workflows/build-lint-test.yml
@@ -44,7 +44,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - name: Enable permission audit for debug runs
         if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
-        run: echo 'RUN=yarn audit --verbose' >> "$GITHUB_ENV"
+        run: echo 'RUN=yarn audit-script --verbose' >> "$GITHUB_ENV"
       - name: Build
         run: $RUN build
       - name: Require clean working directory
@@ -71,7 +71,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - name: Enable permission audit for debug runs
         if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
-        run: echo 'RUN=yarn audit --verbose' >> "$GITHUB_ENV"
+        run: echo 'RUN=yarn audit-script --verbose' >> "$GITHUB_ENV"
       - name: Lint
         run: $RUN lint
       - name: Validate RC changelog
@@ -104,7 +104,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - name: Enable permission audit for debug runs
         if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
-        run: echo 'RUN=yarn audit --verbose' >> "$GITHUB_ENV"
+        run: echo 'RUN=yarn audit-script --verbose' >> "$GITHUB_ENV"
       - name: Test
         run: $RUN test
       - name: Require clean working directory
@@ -133,7 +133,7 @@ jobs:
         run: rm yarn.lock && YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn
       - name: Enable permission audit for debug runs
         if: ${{ runner.debug == '1' && matrix.node-version == '26.x' }}
-        run: echo 'RUN=yarn audit --verbose' >> "$GITHUB_ENV"
+        run: echo 'RUN=yarn audit-script --verbose' >> "$GITHUB_ENV"
       - name: Test
         run: $RUN test
       - name: Restore lockfile
diff --git a/package.json b/package.json
index e8d50f68..52570a2c 100644
--- a/package.json
+++ b/package.json
@@ -27,7 +27,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "audit": "node ./scripts/audit.ts",
+    "audit-script": "node ./scripts/audit-script.ts",
     "build": "tsc --project tsconfig.build.json",
     "build:docs": "typedoc",
     "lint": "yarn lint:oxlint && yarn lint:constraints && yarn lint:misc --check && yarn lint:dependencies --check && yarn lint:changelog",
@@ -91,7 +91,7 @@
   },
   "scriptsConfig": {
     "#default": "lavamoat/scripts.strict.json",
-    "audit": "lavamoat/scripts.yarn.json",
+    "audit-script": "lavamoat/scripts.yarn.json",
     "build": "lavamoat/scripts.build.json",
     "lint": "lavamoat/scripts.yarn.json",
     "lint:changelog": "lavamoat/scripts.lint.json",
diff --git a/scripts/audit.ts b/scripts/audit-script.ts
similarity index 100%
rename from scripts/audit.ts
rename to scripts/audit-script.ts

From 0e2be29c32b03d0158a9a9adcbfe03b2596fdfaf Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Mon, 28 Sep 2026 13:39:28 +0200
Subject: [PATCH 09/23] Fix JSDoc for constants

---
 scripts/audit-script.ts | 44 +++++++++++++++++++++--------------------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index b5a30a27..14906e99 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -14,8 +14,10 @@ import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
-// Permissions that are a plain on/off switch in the generated config, keyed by
-// the permission name the audit channels report.
+/**
+ * Permissions that are a plain on/off switch in the generated config, keyed by
+ * the permission name the audit channels report.
+ */
 const BOOLEAN_FLAGS = {
   ChildProcess: '--allow-child-process',
   Net: '--allow-net',
@@ -26,9 +28,11 @@ const BOOLEAN_FLAGS = {
   FFI: '--allow-ffi',
 };
 
-// Environment variables worth expressing paths in terms of, most specific
-// first. Anything matching one of these keeps the config portable across
-// machines and CI runners.
+/**
+ * Environment variables worth expressing paths in terms of, most specific
+ * first. Anything matching one of these keeps the config portable across
+ * machines and CI runners.
+ */
 const ENV_TOKENS = [
   'GITHUB_STEP_SUMMARY',
   'GITHUB_OUTPUT',
@@ -45,21 +49,17 @@ const ENV_TOKENS = [
   'HOME',
 ];
 
-// `lavamoat/.runner-plugin.js` expands an environment variable only when it is
-// the entire value (`/^\$([A-Z_][A-Z0-9_]*)$/i`), so `$HOME/.cache` would reach
-// Node as a literal path. Grants are therefore always a bare token, even though
-// that is broader than the path that earned it. The causing path is reported
-// alongside, so the widening is reviewable.
-
-// The runner plugin sets `--allow-fs-tmp` whenever `--permission` is on, which
-// appends the temporary directory to `--allow-fs-write` cross-platform. Emitting
-// it again here would be redundant noise.
+/**
+ * Write permissions that are added implicitly by `lavamoat/.runner-plugin.js`.
+ */
 const RUNNER_PROVIDED_WRITES = new Set(['$TMPDIR']);
 
-// Files that module and workspace resolution probes for while walking from the
-// project directory up to the file system root. The hits are almost all misses,
-// but they are still audited, and granting each one would bake this machine's
-// directory layout into the config.
+/**
+ * Files that module and workspace resolution probes for while walking from the
+ * project directory up to the file system root. The hits are almost all misses,
+ * but they are still audited, and granting each one would bake this machine's
+ * directory layout into the config.
+ */
 const RESOLUTION_MARKERS = new Set([
   // Module and workspace resolution.
   '.git',
@@ -85,9 +85,11 @@ const RESOLUTION_MARKERS = new Set([
 const AUDIT_DIRECTORY = mkdtempSync(join(tmpdir(), 'permission-audit-'));
 const AUDIT_LOG = join(AUDIT_DIRECTORY, 'permissions.ndjson');
 
-// macOS and Windows resolve paths case-insensitively, and tools like
-// TypeScript probe with inconsistent casing. Comparing case-sensitively there
-// would leak absolute machine paths into the config as unmatched outsiders.
+/**
+ * macOS and Windows resolve paths case-insensitively, and tools like
+ * TypeScript probe with inconsistent casing. Comparing case-sensitively there
+ * would leak absolute machine paths into the config as unmatched outsiders.
+ */
 const CASE_INSENSITIVE =
   process.platform === 'darwin' || process.platform === 'win32';
 

From 2a1b04d72fc39dcdf2706618bc342acf0cb3dc36 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Mon, 28 Sep 2026 13:40:12 +0200
Subject: [PATCH 10/23] Rename `CASE_INSENSITIVE` to
 `USE_CASE_INSENSITIVE_PATHS`

---
 scripts/audit-script.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index 14906e99..f6b1f9b1 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -90,7 +90,7 @@ const AUDIT_LOG = join(AUDIT_DIRECTORY, 'permissions.ndjson');
  * TypeScript probe with inconsistent casing. Comparing case-sensitively there
  * would leak absolute machine paths into the config as unmatched outsiders.
  */
-const CASE_INSENSITIVE =
+const USE_CASE_INSENSITIVE_PATHS =
   process.platform === 'darwin' || process.platform === 'win32';
 
 /**
@@ -294,7 +294,7 @@ type Config = {
  * @returns The comparison key.
  */
 function comparable(path: string): string {
-  return CASE_INSENSITIVE ? path.toLowerCase() : path;
+  return USE_CASE_INSENSITIVE_PATHS ? path.toLowerCase() : path;
 }
 
 /**

From 7e693aca980f8cc960799548cd0da848ff61f896 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Mon, 28 Sep 2026 13:41:13 +0200
Subject: [PATCH 11/23] Rename grant properties

---
 scripts/audit-script.ts | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index f6b1f9b1..a7a460ef 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -162,12 +162,12 @@ type Grant = {
   /**
    * The grant as it will appear in the generated config.
    */
-  grant: string;
+  type: string;
 
   /**
    * Where the path sits: `project`, `token`, `probe`, or `outside`.
    */
-  kind: string;
+  location: string;
 };
 
 /**
@@ -447,7 +447,7 @@ function generalise(path: string, action: 'read' | 'write'): Grant | undefined {
   const target = resolve(path);
 
   if (action === 'read' && isResolutionProbe(target)) {
-    return { grant: '/', kind: 'probe' };
+    return { type: '/', location: 'probe' };
   }
 
   const key = comparable(target);
@@ -457,16 +457,16 @@ function generalise(path: string, action: 'read' | 'write'): Grant | undefined {
     }
 
     if (token === './') {
-      return { grant: './', kind: 'project' };
+      return { type: './', location: 'project' };
     }
 
     // A variable pointing at a single file (a GitHub summary, say) is the whole
     // grant on its own.
     if (key === prefix) {
-      return { grant: token, kind: 'token' };
+      return { type: token, location: 'token' };
     }
 
-    return { grant: token, kind: 'token' };
+    return { type: token, location: 'token' };
   }
 
   // Outside anything recognisable, grant the top-level directory rather than a
@@ -478,7 +478,7 @@ function generalise(path: string, action: 'read' | 'write'): Grant | undefined {
   // top-level namespace to rewrite it to. Such a grant needs a human anyway,
   // and it is reported as an escape so that it gets one.
   const [, top] = target.split(sep);
-  return { grant: top ? `/${top}` : '/', kind: 'outside' };
+  return { type: top ? `/${top}` : '/', location: 'outside' };
 }
 
 /**
@@ -778,9 +778,9 @@ function summarise(records: AuditRecord[]): Summary {
       case 'FileSystemRead': {
         const read = generalise(resource, 'read');
         if (read) {
-          summary.reads.add(read.grant);
-          if (read.kind !== 'project') {
-            noteEscape('read', read.grant, resource);
+          summary.reads.add(read.type);
+          if (read.location !== 'project') {
+            noteEscape('read', read.type, resource);
           }
         }
         break;
@@ -789,9 +789,9 @@ function summarise(records: AuditRecord[]): Summary {
       case 'FileSystemWrite': {
         const written = generalise(resource, 'write');
         if (written) {
-          summary.writes.add(written.grant);
-          if (written.kind !== 'project') {
-            noteEscape('write', written.grant, resource);
+          summary.writes.add(written.type);
+          if (written.location !== 'project') {
+            noteEscape('write', written.type, resource);
           }
         }
         break;

From f51191ccfb6de415404e217008feac72b56aa6bc Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Mon, 28 Sep 2026 13:45:19 +0200
Subject: [PATCH 12/23] Rename functions

---
 scripts/audit-script.ts | 47 +++++++++++++++++++++++------------------
 1 file changed, 26 insertions(+), 21 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index a7a460ef..1177834d 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -293,7 +293,7 @@ type Config = {
  * @param path - The path to normalise.
  * @returns The comparison key.
  */
-function comparable(path: string): string {
+function buildComparablePath(path: string): string {
   return USE_CASE_INSENSITIVE_PATHS ? path.toLowerCase() : path;
 }
 
@@ -325,7 +325,7 @@ function compareStrings(a: string, b: string): number {
  * @param path - The path to resolve.
  * @returns The canonical path, or the original on failure.
  */
-function canonical(path: string): string {
+function canonicalisePath(path: string): string {
   try {
     return realpathSync(path);
   } catch {
@@ -339,7 +339,7 @@ function canonical(path: string): string {
  *
  * @returns The prefix table.
  */
-function buildPrefixes(): Prefix[] {
+function buildPortableSubstitutes(): Prefix[] {
   const prefixes: Prefix[] = [];
 
   /**
@@ -353,8 +353,8 @@ function buildPrefixes(): Prefix[] {
       return;
     }
 
-    for (const variant of new Set([resolve(path), canonical(path)])) {
-      prefixes.push({ prefix: comparable(variant), token });
+    for (const variant of new Set([resolve(path), canonicalisePath(path)])) {
+      prefixes.push({ prefix: buildComparablePath(variant), token });
     }
   };
 
@@ -373,7 +373,7 @@ function buildPrefixes(): Prefix[] {
   return prefixes.sort((a, b) => b.prefix.length - a.prefix.length);
 }
 
-const PREFIXES = buildPrefixes();
+const PREFIXES = buildPortableSubstitutes();
 
 /**
  * Build the set of directories between the project and the filesystem root.
@@ -387,7 +387,9 @@ function buildAncestors(): Set<string> {
   let parent = dirname(directory);
 
   while (parent !== directory) {
-    ancestors.add(comparable(parent)).add(comparable(canonical(parent)));
+    ancestors
+      .add(buildComparablePath(parent))
+      .add(buildComparablePath(canonicalisePath(parent)));
     directory = parent;
     parent = dirname(directory);
   }
@@ -405,15 +407,15 @@ const ANCESTORS = buildAncestors();
  * @returns True if the path is a resolution probe.
  */
 function isResolutionProbe(target: string): boolean {
-  const key = comparable(target);
+  const key = buildComparablePath(target);
 
   if (ANCESTORS.has(key)) {
     return true;
   }
 
   if (
-    ANCESTORS.has(comparable(dirname(target))) &&
-    RESOLUTION_MARKERS.has(comparable(basename(target)))
+    ANCESTORS.has(buildComparablePath(dirname(target))) &&
+    RESOLUTION_MARKERS.has(buildComparablePath(basename(target)))
   ) {
     return true;
   }
@@ -439,7 +441,10 @@ function isResolutionProbe(target: string): boolean {
  * widened to the whole file system.
  * @returns The classified grant, or undefined if the path is unusable.
  */
-function generalise(path: string, action: 'read' | 'write'): Grant | undefined {
+function tryCreatingGrant(
+  path: string,
+  action: 'read' | 'write',
+): Grant | undefined {
   if (!path || !isAbsolute(path)) {
     return undefined;
   }
@@ -450,7 +455,7 @@ function generalise(path: string, action: 'read' | 'write'): Grant | undefined {
     return { type: '/', location: 'probe' };
   }
 
-  const key = comparable(target);
+  const key = buildComparablePath(target);
   for (const { prefix, token } of PREFIXES) {
     if (key !== prefix && !key.startsWith(prefix + sep)) {
       continue;
@@ -640,7 +645,7 @@ async function runScript(
  * @param logPath - The log to read.
  * @returns The parsed records.
  */
-function readRecords(logPath: string): AuditRecord[] {
+function readAuditLog(logPath: string): AuditRecord[] {
   let contents;
   try {
     contents = readFileSync(logPath, 'utf8');
@@ -740,7 +745,7 @@ async function parseArgv(): Promise<Options> {
  * @param records - Every record the collector wrote.
  * @returns The summarised permissions.
  */
-function summarise(records: AuditRecord[]): Summary {
+function summariseAudit(records: AuditRecord[]): Summary {
   const summary: Summary = {
     reads: new Set<string>(),
     writes: new Set<string>(),
@@ -757,7 +762,7 @@ function summarise(records: AuditRecord[]): Summary {
    * @param grant - The grant that was emitted.
    * @param cause - The path responsible.
    */
-  const noteEscape = (
+  const addEscape = (
     action: 'read' | 'write',
     grant: string,
     cause: string,
@@ -776,22 +781,22 @@ function summarise(records: AuditRecord[]): Summary {
   for (const { permission, resource } of records) {
     switch (permission) {
       case 'FileSystemRead': {
-        const read = generalise(resource, 'read');
+        const read = tryCreatingGrant(resource, 'read');
         if (read) {
           summary.reads.add(read.type);
           if (read.location !== 'project') {
-            noteEscape('read', read.type, resource);
+            addEscape('read', read.type, resource);
           }
         }
         break;
       }
 
       case 'FileSystemWrite': {
-        const written = generalise(resource, 'write');
+        const written = tryCreatingGrant(resource, 'write');
         if (written) {
           summary.writes.add(written.type);
           if (written.location !== 'project') {
-            noteEscape('write', written.type, resource);
+            addEscape('write', written.type, resource);
           }
         }
         break;
@@ -931,7 +936,7 @@ function report(summary: Summary): void {
 async function main(): Promise<void> {
   const { scriptName, outPath, verbose, passthrough } = await parseArgv();
   const exitCode = await runScript(scriptName, verbose, AUDIT_LOG, passthrough);
-  const records = readRecords(AUDIT_LOG);
+  const records = readAuditLog(AUDIT_LOG);
 
   rmSync(AUDIT_DIRECTORY, { recursive: true, force: true });
 
@@ -955,7 +960,7 @@ async function main(): Promise<void> {
     }
   }
 
-  const summary = summarise(records);
+  const summary = summariseAudit(records);
   const config = buildConfig(summary, scriptName, exitCode);
   const json = `${JSON.stringify(config, undefined, 2)}\n`;
 

From 58cd8e141359c1320463f61110079640671772f8 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Mon, 28 Sep 2026 13:51:06 +0200
Subject: [PATCH 13/23] Further improve naming of prefixes

---
 scripts/audit-script.ts | 26 ++++++++++++--------------
 1 file changed, 12 insertions(+), 14 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index 1177834d..a8992061 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -125,8 +125,12 @@ type Options = {
 /**
  * A directory that absolute paths are rewritten relative to, turning a machine
  * specific path into a portable grant.
+ *
+ * Matching is anchored at the start of the path, which is what makes the
+ * longest entry the most specific one: every token names a place to start
+ * from, never a segment that could appear part way along.
  */
-type Prefix = {
+type PortablePrefix = {
   /**
    * The absolute path to match, normalised for comparison.
    */
@@ -334,13 +338,13 @@ function canonicalisePath(path: string): string {
 }
 
 /**
- * Build the prefix table used to rewrite absolute paths into portable tokens,
- * longest first so the most specific prefix wins.
+ * Build the table used to rewrite absolute paths into portable tokens, longest
+ * first so the most specific prefix wins.
  *
- * @returns The prefix table.
+ * @returns The prefixes, most specific first.
  */
-function buildPortableSubstitutes(): Prefix[] {
-  const prefixes: Prefix[] = [];
+function buildPortablePrefixes(): PortablePrefix[] {
+  const prefixes: PortablePrefix[] = [];
 
   /**
    * Register a path and its canonical form under the same token.
@@ -373,7 +377,7 @@ function buildPortableSubstitutes(): Prefix[] {
   return prefixes.sort((a, b) => b.prefix.length - a.prefix.length);
 }
 
-const PREFIXES = buildPortableSubstitutes();
+const PORTABLE_PREFIXES = buildPortablePrefixes();
 
 /**
  * Build the set of directories between the project and the filesystem root.
@@ -456,7 +460,7 @@ function tryCreatingGrant(
   }
 
   const key = buildComparablePath(target);
-  for (const { prefix, token } of PREFIXES) {
+  for (const { prefix, token } of PORTABLE_PREFIXES) {
     if (key !== prefix && !key.startsWith(prefix + sep)) {
       continue;
     }
@@ -465,12 +469,6 @@ function tryCreatingGrant(
       return { type: './', location: 'project' };
     }
 
-    // A variable pointing at a single file (a GitHub summary, say) is the whole
-    // grant on its own.
-    if (key === prefix) {
-      return { type: token, location: 'token' };
-    }
-
     return { type: token, location: 'token' };
   }
 

From 94f32fe48ee00cdb8c7df5f5e76afc9b48a51c94 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Mon, 28 Sep 2026 13:54:44 +0200
Subject: [PATCH 14/23] Rename `passthrough` to `scriptArgs` and reorder
 parameters

---
 scripts/audit-script.ts | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index a8992061..0942f645 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -102,6 +102,13 @@ type Options = {
    */
   scriptName: string;
 
+  /**
+   * Anything this script does not recognise, handed to the audited script
+   * rather than interpreted here, so that auditing a command that takes
+   * arguments reads the same as running it: `audit test --coverage`.
+   */
+  scriptArgs: string[];
+
   /**
    * Where to write the generated config, or `undefined` to write it to
    * standard output.
@@ -113,13 +120,6 @@ type Options = {
    * was chosen, rather than printing the config alone.
    */
   verbose: boolean;
-
-  /**
-   * Anything this script does not recognise, handed to the audited script
-   * rather than interpreted here, so that auditing a command that takes
-   * arguments reads the same as running it: `audit test --coverage`.
-   */
-  passthrough: string[];
 };
 
 /**
@@ -592,16 +592,16 @@ const COLLECTOR_URL = `data:text/javascript,${encodeURIComponent(
  * Run the audited script and resolve with its exit status.
  *
  * @param scriptName - The name of the script to run.
+ * @param scriptArgs - Arguments to hand to the script.
  * @param verbose - Whether to include verbose output.
  * @param logPath - Where the collector should append records.
- * @param passthrough - Arguments to hand to the script itself.
  * @returns The exit code.
  */
 async function runScript(
   scriptName: string,
+  scriptArgs: string[],
   verbose: boolean,
   logPath: string,
-  passthrough: string[],
 ): Promise<number> {
   return new Promise((resolveRun) => {
     const flags = [
@@ -613,8 +613,8 @@ async function runScript(
     // `node --run` forwards everything after its own `--` to the script, so
     // auditing a command with arguments works the same as running it.
     const args = ['--run', scriptName];
-    if (passthrough.length > 0) {
-      args.push('--', ...passthrough);
+    if (scriptArgs.length > 0) {
+      args.push('--', ...scriptArgs);
     }
 
     const child = spawn('node', args, {
@@ -726,11 +726,11 @@ async function parseArgv(): Promise<Options> {
 
   return {
     scriptName: argv.script,
-    outPath: argv.out,
-    verbose: argv.verbose,
     // Unrecognised arguments belong to the audited script. Mapped because the
     // parser types them loosely, having no way to know they are strings.
-    passthrough: argv._.map(String),
+    scriptArgs: argv._.map(String),
+    outPath: argv.out,
+    verbose: argv.verbose,
   };
 }
 
@@ -932,8 +932,8 @@ function report(summary: Summary): void {
  * granting exactly those.
  */
 async function main(): Promise<void> {
-  const { scriptName, outPath, verbose, passthrough } = await parseArgv();
-  const exitCode = await runScript(scriptName, verbose, AUDIT_LOG, passthrough);
+  const { scriptName, outPath, verbose, scriptArgs } = await parseArgv();
+  const exitCode = await runScript(scriptName, scriptArgs, verbose, AUDIT_LOG);
   const records = readAuditLog(AUDIT_LOG);
 
   rmSync(AUDIT_DIRECTORY, { recursive: true, force: true });

From bf6f53f0797ce29096a5f30ec401490747b65972 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Mon, 28 Sep 2026 13:56:31 +0200
Subject: [PATCH 15/23] Remove redundant comments

---
 scripts/audit-script.ts | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index 0942f645..b6bd056e 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -840,12 +840,9 @@ function buildConfig(
   scriptName: string,
   exitCode: number,
 ): Config {
-  // Reads have to cover writes, and the project directory is always readable.
   const reads = new Set([...summary.reads, ...summary.writes, './']);
-
-  // The runner grants the temporary directory for writing only, so a tmp read
-  // still has to be requested above.
   const writes = new Set(summary.writes);
+
   for (const grant of RUNNER_PROVIDED_WRITES) {
     writes.delete(grant);
   }
@@ -949,8 +946,6 @@ async function main(): Promise<void> {
         `permission it needs. Fix the failure and re-run for a complete config.`,
     );
 
-    // The output that would explain the failure was discarded, so point at the
-    // flag that keeps it.
     if (!verbose) {
       console.error(
         `Re-run with --verbose to see the script's output and diagnose it.`,

From 5410c2a20d6d18d5d73b179cc85606fb2a95cd9f Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Wed, 30 Sep 2026 09:57:26 +0200
Subject: [PATCH 16/23] Rename `buildAncestors` and add explicit path parameter

---
 scripts/audit-script.ts | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index b6bd056e..bfb9d2a0 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -382,26 +382,27 @@ const PORTABLE_PREFIXES = buildPortablePrefixes();
 /**
  * Build the set of directories between the project and the filesystem root.
  *
+ * @param projectPath - The path to the project.
  * @returns Every strict ancestor of the project directory.
  */
-function buildAncestors(): Set<string> {
+function buildProjectAncestors(projectPath: string): Set<string> {
   const ancestors = new Set<string>();
 
-  let directory = process.cwd();
-  let parent = dirname(directory);
+  let currentDirectory = projectPath;
+  let parentDirectory = dirname(currentDirectory);
 
-  while (parent !== directory) {
+  while (parentDirectory !== currentDirectory) {
     ancestors
-      .add(buildComparablePath(parent))
-      .add(buildComparablePath(canonicalisePath(parent)));
-    directory = parent;
-    parent = dirname(directory);
+      .add(buildComparablePath(parentDirectory))
+      .add(buildComparablePath(canonicalisePath(parentDirectory)));
+    currentDirectory = parentDirectory;
+    parentDirectory = dirname(currentDirectory);
   }
 
   return ancestors;
 }
 
-const ANCESTORS = buildAncestors();
+const PROJECT_ANCESTORS = buildProjectAncestors(process.cwd());
 
 /**
  * Decide whether a path is module resolution walking up the directory tree
@@ -413,12 +414,12 @@ const ANCESTORS = buildAncestors();
 function isResolutionProbe(target: string): boolean {
   const key = buildComparablePath(target);
 
-  if (ANCESTORS.has(key)) {
+  if (PROJECT_ANCESTORS.has(key)) {
     return true;
   }
 
   if (
-    ANCESTORS.has(buildComparablePath(dirname(target))) &&
+    PROJECT_ANCESTORS.has(buildComparablePath(dirname(target))) &&
     RESOLUTION_MARKERS.has(buildComparablePath(basename(target)))
   ) {
     return true;
@@ -426,7 +427,7 @@ function isResolutionProbe(target: string): boolean {
 
   // Node walks every ancestor's `node_modules` looking for a dependency, so
   // those hits describe the machine's directory layout rather than the script.
-  for (const ancestor of ANCESTORS) {
+  for (const ancestor of PROJECT_ANCESTORS) {
     const modules = join(ancestor, 'node_modules');
     if (key === modules || key.startsWith(modules + sep)) {
       return true;

From 4a5fc0e7023282e1b0163fbf830e9a43c34f7ab1 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Wed, 30 Sep 2026 10:02:12 +0200
Subject: [PATCH 17/23] Clean up collect function

---
 scripts/audit-script.ts | 45 ++++++++++++-----------------------------
 1 file changed, 13 insertions(+), 32 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index bfb9d2a0..21368100 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -486,18 +486,11 @@ function tryCreatingGrant(
 }
 
 /**
- * Subscribe to the permission audit channels and append everything they report
- * to the log named by `PERMISSION_AUDIT_LOG`.
+ * Collect the permissions that a script accesses via Node's diagnostics
+ * channel, writing them to the log named by `PERMISSION_AUDIT_LOG`.
  *
- * This runs in the audited process, not in this one. It is serialised with
- * `Function.prototype.toString` and injected via `--import`, so it must be
- * entirely self-contained: it cannot reference anything declared outside its
- * own body, and it has to reach for built-ins with dynamic `import` rather
- * than the static imports at the top of this file. Keeping it here as real
- * code, rather than as a string, is what lets it be linted and formatted
- * alongside everything else.
- *
- * @returns A promise that resolves once the channels are subscribed.
+ * Note that this function does not run in this process, but the process
+ * responsible for auditing permissions (see {@link runScript}).
  */
 async function collect(): Promise<void> {
   // eslint-disable-next-line n/no-process-env
@@ -509,6 +502,8 @@ async function collect(): Promise<void> {
     return;
   }
 
+  // Because this function runs in a separate process, it cannot reference
+  // imports outside of itself.
   const { channel } = await import('node:diagnostics_channel');
   const { closeSync, openSync, writeSync } = await import('node:fs');
 
@@ -521,13 +516,8 @@ async function collect(): Promise<void> {
 
   let writing = false;
 
-  /**
-   * Append a single permission record to the shared audit log.
-   *
-   * @param permission - The permission being exercised.
-   * @param resource - The resource it applies to, if any.
-   */
-  const write = (permission: string, resource: string): void => {
+  const listener: ChannelListener = (message: unknown): void => {
+    const { permission, resource } = message as PermissionMessage;
     if (writing || ignored.has(resource)) {
       return;
     }
@@ -553,18 +543,6 @@ async function collect(): Promise<void> {
     }
   };
 
-  /**
-   * Forward a published permission check to the audit log. The same listener
-   * serves every channel, since the payload identifies the permission.
-   *
-   * @param message - The payload the channel published.
-   */
-  const listener: ChannelListener = (message: unknown): void => {
-    const { permission, resource } = message as PermissionMessage;
-
-    write(permission, resource);
-  };
-
   for (const name of [
     'fs',
     'net',
@@ -583,8 +561,11 @@ async function collect(): Promise<void> {
   });
 }
 
-// `--import` evaluates this before the entry point, and awaits top-level await,
-// so the channels are subscribed before the audited script can touch anything.
+/**
+ * Holds a mini-script that simply runs the `collect` function. This script is
+ * loaded alongside the script that we want to audit so that we can collect
+ * its accessed permissions (see {@link runScript}).
+ */
 const COLLECTOR_URL = `data:text/javascript,${encodeURIComponent(
   `await (${collect.toString()})()`,
 )}`;

From 44532a6efef9db7bc47f608d388919287d242df0 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Wed, 30 Sep 2026 10:03:56 +0200
Subject: [PATCH 18/23] Add comment to `PERMISSION_AUDIT_LOG` usage

---
 scripts/audit-script.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index 21368100..c84e8030 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -610,8 +610,11 @@ async function runScript(
       env: {
         // eslint-disable-next-line n/no-process-env
         ...process.env,
-        PERMISSION_AUDIT_LOG: logPath,
         NODE_OPTIONS: flags.join(' '),
+
+        // The `collect` function (which we are loading alongside the script
+        // we want to audit) uses this log file to capture detected permissions.
+        PERMISSION_AUDIT_LOG: logPath,
       },
     });
 

From c1964b886eebbe98a3cc37200b89392bcc9550e4 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Wed, 30 Sep 2026 10:05:35 +0200
Subject: [PATCH 19/23] Clean up compareStrings function

---
 scripts/audit-script.ts | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index c84e8030..5364c9fe 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -302,13 +302,9 @@ function buildComparablePath(path: string): string {
 }
 
 /**
- * Compare two strings by code unit, for sorting.
- *
- * `localeCompare` is deliberately not used here. It orders by locale rules,
- * which weight punctuation and case differently from one machine to the next,
- * so `/` and `$TMPDIR` can swap places depending on who ran the script. Both
- * the generated config and the report get committed and diffed, so their
- * ordering has to be identical everywhere rather than merely readable.
+ * Compare two strings alphabetically. This is the same comparator `sort` uses
+ * by default. We define it here so that we can use it in places where we are
+ * using a more complex sorting strategy, and we need a default fallback.
  *
  * @param a - The first string.
  * @param b - The second string.
@@ -878,9 +874,7 @@ function report(summary: Summary): void {
 
     for (const [label, values] of details) {
       if (values.size > 0) {
-        console.log(
-          `  ${label}: ${[...values].sort(compareStrings).join(', ')}`,
-        );
+        console.log(`  ${label}: ${[...values].sort().join(', ')}`);
       }
     }
   }

From bb92e92e6839f3ba1461e7d84a2a758c23438c55 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Wed, 30 Sep 2026 10:05:58 +0200
Subject: [PATCH 20/23] Rename `report` to `reportSummary`

---
 scripts/audit-script.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index 5364c9fe..e35f947f 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -863,7 +863,7 @@ function buildConfig(
  *
  * @param summary - What the audited script exercised.
  */
-function report(summary: Summary): void {
+function reportSummary(summary: Summary): void {
   const details: [label: string, values: Set<string>][] = [
     ['network hosts', summary.hosts],
     ['child commands', summary.commands],
@@ -944,7 +944,7 @@ async function main(): Promise<void> {
   }
 
   if (verbose) {
-    report(summary);
+    reportSummary(summary);
   }
 
   // Pass the script's own failure on, so that auditing a command can stand in

From 5a666e68c7a9fabc2275e25cdbdc593ee3266fb4 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Wed, 30 Sep 2026 10:06:47 +0200
Subject: [PATCH 21/23] Update `reportSummary` documentation

---
 scripts/audit-script.ts | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index e35f947f..9606b4bf 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -851,15 +851,7 @@ function buildConfig(
 }
 
 /**
- * Report the detail that does not fit the config format, but matters when
- * reviewing it.
- *
- * Written to standard output, alongside the config rather than beside it. A
- * reader merging two streams — a CI runner, say — orders them by arrival and
- * can drop this report into the middle of the JSON. One stream keeps it in
- * the order it was written. That leaves standard output human-facing under
- * `--verbose`, which is the point of the flag; use `--out` when the config
- * needs to be machine-readable.
+ * Surfaces details from the permission audit that are helpful for review.
  *
  * @param summary - What the audited script exercised.
  */

From fd3a99b25fab9a143403dec3a0a5519cd6c03ea9 Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Wed, 30 Sep 2026 10:22:53 +0200
Subject: [PATCH 22/23] Rename `isResolutionProbe` to `isAncestorSearchPath`
 and clarify purpose

---
 scripts/audit-script.ts | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index 9606b4bf..e1cbc6aa 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -169,9 +169,9 @@ type Grant = {
   type: string;
 
   /**
-   * Where the path sits: `project`, `token`, `probe`, or `outside`.
+   * Where the path sits.
    */
-  location: string;
+  location: 'project' | 'token' | 'ancestor' | 'outside';
 };
 
 /**
@@ -401,13 +401,13 @@ function buildProjectAncestors(projectPath: string): Set<string> {
 const PROJECT_ANCESTORS = buildProjectAncestors(process.cwd());
 
 /**
- * Decide whether a path is module resolution walking up the directory tree
- * rather than a genuine dependency of the script.
+ * Decide whether a path was read only because a tool searched upwards from the
+ * project for a dependency or a configuration file.
  *
  * @param target - The resolved path from an audit record.
- * @returns True if the path is a resolution probe.
+ * @returns True if the path is a by-product of such a search.
  */
-function isResolutionProbe(target: string): boolean {
+function isAncestorSearchPath(target: string): boolean {
   const key = buildComparablePath(target);
 
   if (PROJECT_ANCESTORS.has(key)) {
@@ -452,8 +452,8 @@ function tryCreatingGrant(
 
   const target = resolve(path);
 
-  if (action === 'read' && isResolutionProbe(target)) {
-    return { type: '/', location: 'probe' };
+  if (action === 'read' && isAncestorSearchPath(target)) {
+    return { type: '/', location: 'ancestor' };
   }
 
   const key = buildComparablePath(target);

From 118563fe700113ab6671dbd06dd1596a5b0ca3ed Mon Sep 17 00:00:00 2001
From: Maarten Zuidhoorn <maarten@zuidhoorn.com>
Date: Wed, 30 Sep 2026 17:14:49 +0200
Subject: [PATCH 23/23] Clean up report output

---
 scripts/audit-script.ts | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/scripts/audit-script.ts b/scripts/audit-script.ts
index e1cbc6aa..df630263 100644
--- a/scripts/audit-script.ts
+++ b/scripts/audit-script.ts
@@ -856,26 +856,25 @@ function buildConfig(
  * @param summary - What the audited script exercised.
  */
 function reportSummary(summary: Summary): void {
+  console.log('');
   const details: [label: string, values: Set<string>][] = [
-    ['network hosts', summary.hosts],
-    ['child commands', summary.commands],
+    ['Network hosts', summary.hosts],
+    ['Child commands', summary.commands],
   ];
 
   if (details.some(([, values]) => values.size > 0)) {
-    console.log('\nObserved detail behind the boolean flags:');
-
     for (const [label, values] of details) {
       if (values.size > 0) {
-        console.log(`  ${label}: ${[...values].sort().join(', ')}`);
+        console.log(`${label}:`);
+        for (const value of [...values].sort()) {
+          console.log(`  - ${value}`);
+        }
       }
     }
   }
 
   if (summary.escapes.size > 0) {
-    console.log(
-      '\nGrants reaching outside the project, with an example of the',
-    );
-    console.log('path that caused each one:');
+    console.log('\nGrants reaching outside the project:');
 
     // Sorted by the same key the map is built from, so reads group before
     // writes and grants read in a stable order.
@@ -884,13 +883,13 @@ function reportSummary(summary: Summary): void {
       .map(([, value]) => value);
 
     for (const { action, grant, count, cause } of sorted) {
-      const more = count > 1 ? ` (+${count - 1} more)` : '';
+      const more = count > 1 ? `, +${count - 1} more` : '';
       const provided =
         action === 'write' && RUNNER_PROVIDED_WRITES.has(grant)
-          ? ' [omitted; the runner grants this]'
+          ? ' [implicit]'
           : '';
 
-      console.log(`  ${action} ${grant}  ${cause}${more}${provided}`);
+      console.log(`  ${action} ${grant} (e.g. ${cause}${more})${provided}`);
     }
   }
 }