@rightkit/release 0.6.13 → 0.6.14

package/class-a-launch-guard.mjs

@@ -6,9 +6,23 @@
 // build: cargo, rustc, rustright, rightkit (broker client), tauri / cargo-tauri, tsc without --noEmit, tsup, esbuild, swc, rollup,
 // webpack, `vite build`, `next build`, or a package-manager run of a build / build:* script.
 //
+// Shell command text (exec, execSync, `shell: true`, `sh -c <text>`, `cmd /c <text>`, ...) is read by a small shell parser BEFORE the
+// shell starts, and it fails closed: text the guard cannot read to the end is refused, never passed on. Refused before launch:
+// command substitution `$( )` and backticks (also inside double quotes), process substitution, parameter expansions that evaluate
+// text (`${!x}`, `${x@P}`, zsh `${(e)x}`), ANSI-C quoting `$'..'`, unquoted parentheses and braces (subshells, functions, groups,
+// brace expansion), shell control forms (if/for/while/until/case/select/function/`!`), `eval`/`source`/`.`/`trap`/`alias`, programs
+// that launch a program they are told (xargs, parallel, concurrently, run-s, ...), a command word built by expansion or a glob,
+// and a shell that reads its commands from stdin. Newlines separate commands; backslash and quote joins are resolved before the
+// program is named; leading assignments and redirections never hide the program; wrappers (env, nice, timeout, command, nohup, sudo,
+// busybox, find, ...) have every following word checked as a possible program; shells nest to a bounded depth and a chain the guard
+// cannot finish reading is refused. Ordinary noncompiling commands (echo, test, node, git, ... with plain arguments, including
+// `$VAR` arguments and quoted text that merely names a compiler) are unchanged. Prefer an argv launch (spawn/execFile with an
+// array) for Class A rows: it never reaches the shell parser.
+//
 // Scope, exactly: launches from Node processes of the row. Not covered: a compiler API called inside a process
-// (typescript.createProgram().emit(), vite.build() / the rollup JS API), and launches by a non-Node program that does not load
-// this hook (rightkit#1240). esbuild's JS API is covered: it launches the esbuild service binary.
+// (typescript.createProgram().emit(), vite.build() / the rollup JS API), launches by a non-Node program that does not load
+// this hook (rightkit#1240: a shell script file, `python -c`, `perl -e`, `awk system()`), and the contents of a script file a shell
+// runs. esbuild's JS API is covered: it launches the esbuild service binary.
 //
 // A Node child handed a replacement environment keeps the guard (withGuard restores it). There is no exemption: a unit whose tests
 // launch stand-ins named like compilers (stub scripts can run anything) runs after class A instead (npm.<unit>.afterClassA).
@@ -22,8 +36,18 @@ export const LAUNCH_GUARD_IMPORT = `--import=${pathToFileURL(fileURLToPath(impor
 export const REFUSAL_CODE = "RK_CLASS_A_COMPILE_LAUNCH";
 const COMPILERS = new Set(["cargo", "rustc", "rustright", "rightkit", "tauri", "cargo-tauri", "tsup", "esbuild", "swc", "rollup", "webpack"]);
 const PACKAGE_MANAGERS = new Set(["pnpm", "npm", "yarn", "bun"]);
-const SHELLS = new Set(["sh", "bash", "zsh", "dash", "cmd", "powershell", "pwsh"]);
-const WRAPPERS = new Set(["env", "npx", "pnpx", "exec", "time", "nice"]);
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ash", "ksh", "mksh", "fish", "csh", "tcsh", "cmd", "powershell", "pwsh"]);
+// Programs that run another program they are given: every later word is checked as a possible program (options and their values cannot
+// be told apart from the program without each tool's grammar, so the check is deliberately wide).
+const SCAN_WRAPPERS = new Set([
+  "env", "exec", "time", "nice", "npx", "pnpx", "command", "builtin", "nohup", "timeout", "setsid", "stdbuf", "ionice", "taskset", "chrt",
+  "flock", "sudo", "doas", "busybox", "xvfb-run", "unbuffer", "watch", "strace", "ltrace", "cross-env", "dotenv", "find", "call", "start", "arch", "script",
+]);
+// Programs whose job is to launch commands from text or arguments the guard cannot read: refused outright.
+const LAUNCHER_DYNAMIC = new Set(["xargs", "parallel", "concurrently", "npm-run-all", "run-s", "run-p", "iex", "invoke-expression", "invoke-command"]);
+// Shell builtins that run text (shell text only).
+const TEXT_DYNAMIC = new Set(["eval", "source", ".", "trap", "alias", "coproc"]);
+const CONTROL_WORDS = new Set(["if", "then", "else", "elif", "fi", "for", "while", "until", "do", "done", "case", "esac", "select", "function", "{", "}", "!"]);
 // Options that take a value, per package manager: pnpm's `-w` is `--workspace-root` (a flag), npm's `-w` is `--workspace <name>`.
 const OPTIONS_WITH_VALUES = Object.freeze({
   pnpm: new Set(["--filter", "-F", "--dir", "-C"]),
@@ -31,46 +55,243 @@ const OPTIONS_WITH_VALUES = Object.freeze({
   yarn: new Set(["--cwd"]),
   bun: new Set(["--cwd", "--filter"]),
 });
+const MAX_DEPTH = 12;
+const DYN = "\u0000"; // prefixes a shell-text word whose value is decided by expansion or a glob (never present in a real argv)
+const ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*\+?=/;
+const REDIRECT = /^(?:\d*|&)(?:<<<|<<-?|<>|<&|>&|>>|>\||<|>)/;
+const REDIRECT_ONLY = /^(?:\d*|&)(?:<<<|<<-?|<>|<&|>&|>>|>\||<|>)$/;
 
 const base = (p) => path.basename(String(p ?? "").replaceAll("\\", "/")).replace(/\.(exe|cmd|bat|ps1|js|mjs|cjs)$/i, "").toLowerCase();
+const isDyn = (w) => typeof w === "string" && w.startsWith(DYN);
+const plain = (w) => (isDyn(w) ? w.slice(1) : w);
 
-/** A shell command line split into commands (on && || ; |) and words, quotes removed: enough to read what a `sh -c` text launches. */
-export function shellWords(text) {
-  const commands = []; let words = []; let word = ""; let quote = null;
-  const end = () => { if (word) { words.push(word); word = ""; } };
+/**
+ * Reads shell command text into commands and words (quotes and escapes resolved), or reports why it cannot be read safely.
+ * dialect: "sh" (POSIX-like shells), "cmd" (cmd.exe: backslash is a path character, only double quotes quote), "pwsh" (backtick escapes).
+ * A word decided by an expansion or an unquoted glob is returned prefixed with DYN. Returns { commands, meta, hazard }: `hazard` is
+ * a string when the text uses syntax the guard refuses, and `commands` is then only what was read before it.
+ */
+function parseShell(text, dialect = "sh") {
   const s = String(text);
+  const posix = dialect === "sh";
+  const commands = []; const meta = [];
+  let words = []; let word = ""; let started = false; let dyn = false; let quote = null;
+  let cur = { piped: false, heredoc: false };
+  const end = () => {
+    if (word || started) {
+      if (dyn && !ASSIGN.test(word) && !REDIRECT.test(word) && word !== "[") word = DYN + word;
+      if (word) words.push(word);
+    }
+    word = ""; started = false; dyn = false;
+  };
+  const commit = () => { end(); if (words.length) { commands.push(words); meta.push(cur); cur = { piped: false, heredoc: false }; } words = []; };
+  const stop = (hazard) => { return { commands, meta, hazard }; };
+  const expands = (c) => c !== undefined && /[A-Za-z_0-9{@*#?$!-]/.test(c);
   for (let i = 0; i < s.length; i++) {
     const c = s[i];
-    if (quote) { if (c === quote) quote = null; else word += c; continue; }
-    if (c === "'" || c === "\"") { quote = c; continue; }
+    if (quote === "'") { if (c === "'") quote = null; else word += c; continue; }
+    if (quote === "\"") {
+      if (c === "\"") { quote = null; continue; }
+      if (c === "\\" && posix) {
+        const n = s[i + 1];
+        if (n !== undefined && "$`\"\\\n".includes(n)) { if (n !== "\n") word += n; i++; } else word += "\\";
+        continue;
+      }
+      if (c === "`" && posix) return stop("backtick command substitution");
+      if (c === "%" && dialect === "cmd") dyn = true;
+      if (c === "$") {
+        if (s[i + 1] === "(") return stop("command substitution $( )");
+        if (s[i + 1] === "{") {
+          const close = s.indexOf("}", i + 2);
+          if (close < 0) return stop("unterminated ${ }");
+          const inner = s.slice(i + 2, close);
+          if (/^[(!]/.test(inner) || inner.includes("@") || inner.includes("$(") || inner.includes("`")) return stop("parameter expansion that evaluates text");
+          word += s.slice(i, close + 1); dyn = true; i = close; continue;
+        }
+        if (expands(s[i + 1])) dyn = true;
+      }
+      word += c; continue;
+    }
+    if (c === "'" && dialect !== "cmd") { quote = "'"; started = true; continue; }
+    if (c === "\"") { quote = "\""; started = true; continue; }
+    if (c === "\\" && posix) {
+      const n = s[i + 1];
+      if (n === undefined) { word += "\\"; continue; }
+      if (n === "\n") { i++; continue; }
+      word += n; started = true; i++; continue;
+    }
+    if (c === "`") {
+      if (dialect === "pwsh") { word += s[i + 1] ?? ""; started = true; i++; continue; }
+      if (dialect === "cmd") { word += c; continue; }
+      return stop("backtick command substitution");
+    }
+    if (c === "$") {
+      if (s[i + 1] === "(") return stop("command substitution $( )");
+      if (s[i + 1] === "{") {
+        const close = s.indexOf("}", i + 2);
+        if (close < 0) return stop("unterminated ${ }");
+        const inner = s.slice(i + 2, close);
+        if (/^[(!]/.test(inner) || inner.includes("@") || inner.includes("$(") || inner.includes("`")) return stop("parameter expansion that evaluates text");
+        word += s.slice(i, close + 1); dyn = true; i = close; continue;
+      }
+      if (s[i + 1] === "'" && posix) return stop("ANSI-C quoting $'...'");
+      if (s[i + 1] === "\"" && posix) continue; // $"text": a locale-translated double-quoted string
+      if (expands(s[i + 1])) dyn = true;
+      word += c; continue;
+    }
+    if (c === "%" && dialect === "cmd") { dyn = true; word += c; continue; }
+    if (c === "^" && dialect === "cmd") return stop("cmd caret escape");
+    if (c === "(" || c === ")") return stop("unquoted parenthesis (subshell, function, process substitution or array)");
+    if (c === "{") {
+      if (s[i + 1] === "}") { word += "{}"; i++; continue; }
+      return stop("unquoted brace (group, function body or brace expansion)");
+    }
+    if ((c === "*" || c === "?" || c === "[") && !word && !started && c === "[" && (s[i + 1] === " " || s[i + 1] === undefined)) { word += c; continue; }
+    if (c === "*" || c === "?" || c === "[") { dyn = true; word += c; continue; }
+    if (c === "=" && !word && !started && posix) { dyn = true; word += c; continue; } // zsh `=cmd` expands to the path of cmd
+    if (c === "#" && !word && !started && dialect !== "cmd") { const nl = s.indexOf("\n", i); if (nl < 0) break; i = nl - 1; continue; }
+    if (c === "\n") { commit(); continue; }
     if (/\s/.test(c)) { end(); continue; }
-    if (c === ";" || c === "|" || c === "&") { end(); if (words.length) commands.push(words); words = []; continue; }
+    if (c === "&" && (/[<>]$/.test(word) || s[i + 1] === ">")) { word += c; continue; }
+    if (c === ";" || c === "|" || c === "&") {
+      const pipe = c === "|" && s[i + 1] !== "|" && s[i - 1] !== "|";
+      end(); commit(); if (pipe) cur.piped = true;
+      continue;
+    }
+    if (c === "<" && s[i + 1] === "<") cur.heredoc = true;
     word += c;
   }
-  end(); if (words.length) commands.push(words);
-  return commands;
+  if (quote) return stop("unterminated quote");
+  commit();
+  return { commands, meta, hazard: null };
 }
 
-/** Why `[program, ...args]` is a compile or an emitting build, or null. */
-export function compileLaunch(program, args = []) {
-  let words = [String(program), ...args.map(String)];
-  for (let guard = 0; guard < 8 && words.length; guard++) {
-    const name = base(words[0]);
-    if (name === "node" && words[1] && !String(words[1]).startsWith("-")) { words = words.slice(1); continue; }
-    if (WRAPPERS.has(name)) { words = words.slice(1).filter((w, i, a) => !(i === 0 && /^[A-Z_][A-Z0-9_]*=/.test(w))); continue; }
-    if (SHELLS.has(name)) {
-      const at = words.findIndex((w, i) => i > 0 && /^(-c|\/c|\/s|-Command|-command)$/i.test(w));
-      if (at < 0 || !words[at + 1]) return null;
-      for (const cmd of shellWords(words.slice(at + 1).join(" "))) { const why = compileLaunch(cmd[0], cmd.slice(1)); if (why) return why; }
+/** A shell command line split into commands (on && || ; | & and newlines) and words, quotes and escapes resolved: enough to read what a `sh -c` text launches. */
+export function shellWords(text) {
+  return parseShell(text).commands.map((c) => c.map(plain));
+}
+
+const dialectOfShell = (name) => (name === "cmd" ? "cmd" : name === "powershell" || name === "pwsh" ? "pwsh" : "sh");
+function dialectOfOptions(options) {
+  if (typeof options?.shell === "string") return dialectOfShell(base(options.shell));
+  return process.platform === "win32" ? "cmd" : "sh";
+}
+
+/** Drops leading assignments (`CC=x`) and redirections (`>out`, `2>&1`, `> file`) from a shell-text command: neither hides the program. */
+function stripPrefixes(words) {
+  let w = words;
+  while (w.length) {
+    const first = plain(w[0]);
+    if (ASSIGN.test(first)) { w = w.slice(1); continue; }
+    if (!isDyn(w[0]) && REDIRECT.test(w[0])) { w = REDIRECT_ONLY.test(w[0]) ? w.slice(2) : w.slice(1); continue; }
+    break;
+  }
+  return w;
+}
+
+/** Why one command of shell text is a compile (or cannot be read safely), or null. */
+function commandWhy(cmd, dialect, depth) {
+  const words = stripPrefixes(cmd);
+  if (!words.length) return null;
+  if (isDyn(words[0])) return "shell command word is built by an expansion or a glob";
+  if (CONTROL_WORDS.has(words[0])) return `shell control/function syntax (${words[0]})`;
+  return launchWhy(words, { text: true, strict: true, dialect }, depth);
+}
+
+/**
+ * cmd.exe delayed expansion (`!var!`, `!var:~0,5!`) builds words after the guard has read the text, so it fails closed: text that turns
+ * it on (`setlocal enabledelayedexpansion`) or holds a `!name!` pair is refused, because the registry default can leave it on and the
+ * guard cannot tell. A lone `!` (an echoed "wow!") is not a reference and stays allowed, like a lone `%`-free word.
+ */
+function cmdDelayedExpansionWhy(text) {
+  if (/enabledelayedexpansion/i.test(text)) return "cmd.exe delayed expansion (setlocal EnableDelayedExpansion)";
+  if (/![^!\r\n]+!/.test(text)) return "cmd.exe delayed expansion (!name! reference)";
+  return null;
+}
+
+/** Whether a cmd.exe option word (`/v`, `/V:ON`, `/q/v:on`) enables delayed expansion; `/v:off` does not. */
+const cmdSwitchEnablesDelay = (w) => w.startsWith("/") && /\/v(?!:off$)/i.test(w) && !/^\/v:off$/i.test(w);
+
+/** Why shell text is a compile or unreadable, or null. */
+function shellTextWhy(text, dialect = "sh", depth = 0) {
+  if (dialect === "cmd") { const delayed = cmdDelayedExpansionWhy(String(text)); if (delayed) return `shell syntax refused before launch: ${delayed}`; }
+  const parsed = parseShell(text, dialect);
+  if (parsed.hazard) return `shell syntax refused before launch: ${parsed.hazard}`;
+  for (const cmd of parsed.commands) { const why = commandWhy(cmd, dialect, depth); if (why) return why; }
+  return null;
+}
+
+/** A shell invoked as `[name, ...args]`: reads its `-c` text, and refuses a shell that would read its commands from stdin. */
+function shellLaunchWhy(name, words, ctx, depth) {
+  const dialect = dialectOfShell(name);
+  const rest = words.slice(1);
+  const flag = dialect === "cmd" ? /^\/[ckr]$/i : dialect === "pwsh" ? /^-(c|command)$/i : /^-[A-Za-z]*c[A-Za-z]*$/;
+  const at = rest.findIndex((w) => flag.test(w));
+  if (dialect === "pwsh" && rest.some((w) => /^-(e|ec|enc|encodedcommand)$/i.test(w))) return `${name} -EncodedCommand (text the guard cannot read)`;
+  if (dialect === "cmd") {
+    // Options come before the command text (after /c, /k or /r everything is text); a /V switch in any spelling is refused.
+    for (let k = 0; k < rest.length && (at < 0 || k < at); k++) {
+      if (!rest[k].startsWith("/") && !isDyn(rest[k])) break;
+      if (cmdSwitchEnablesDelay(plain(rest[k]))) return `shell syntax refused before launch: cmd.exe delayed expansion (${plain(rest[k])})`;
+    }
+  }
+  if (at >= 0) {
+    let j = at + 1;
+    if (dialect === "sh") { while (rest[j] === "--") j++; }
+    if (rest[j] === undefined) return null;
+    if (ctx.text && rest.slice(0, j + 1).some(isDyn)) return `${name} is given options or command text built by an expansion or a glob`;
+    const text = dialect === "sh" ? rest[j] : rest.slice(j).join(" ");
+    return shellTextWhy(text, dialect, depth + 1);
+  }
+  if (ctx.text && rest.some(isDyn)) return `${name} is given arguments built by an expansion or a glob`;
+  if (!ctx.strict) return null;
+  // No -c text: the shell runs a script file (not readable here, out of scope) or reads commands from stdin (refused).
+  const valueOptions = new Set(["-o", "-O", "+o", "+O", "--rcfile", "--init-file"]);
+  let operand = false; let stdin = false;
+  for (let k = 0; k < rest.length; k++) {
+    const w = rest[k];
+    if (dialect === "sh" && valueOptions.has(w)) { k++; continue; }
+    if (REDIRECT.test(w)) { if (/^\d*</.test(w)) stdin = true; if (REDIRECT_ONLY.test(w)) k++; continue; }
+    if (w === "-" || (dialect === "sh" && /^-[A-Za-z]*s[A-Za-z]*$/.test(w))) { stdin = true; continue; }
+    if (dialect === "pwsh" && /^-file$/i.test(w)) { operand = true; break; }
+    if (dialect === "cmd" ? w.startsWith("/") : w.startsWith("-") || w.startsWith("+")) continue;
+    operand = true; break;
+  }
+  if (stdin || !operand) return `${name} reading its commands from standard input (text the guard cannot read)`;
+  return null;
+}
+
+/** Why `words` (a program and its arguments) is a compile or an unreadable launch, or null. */
+function launchWhy(words, ctx, depth) {
+  if (depth > MAX_DEPTH) return "launch nests too deeply to inspect";
+  let w = words.map(String);
+  for (let hop = 0; hop < MAX_DEPTH && w.length; hop++) {
+    if (ctx.text && isDyn(w[0])) return "a program word is built by an expansion or a glob";
+    const name = base(w[0]);
+    if (name === "node" && w[1] && !String(w[1]).startsWith("-")) { w = w.slice(1); continue; }
+    if (SHELLS.has(name)) return shellLaunchWhy(name, w, ctx, depth);
+    if (LAUNCHER_DYNAMIC.has(name)) return `${name} (runs a command the guard cannot read)`;
+    if (ctx.text && (TEXT_DYNAMIC.has(name) || TEXT_DYNAMIC.has(w[0]))) return `${w[0]} (runs shell text the guard cannot read)`;
+    const rest = w.slice(1);
+    if (SCAN_WRAPPERS.has(name)) {
+      if (name === "command" && /^-[vV]$/.test(rest[0] ?? "")) return null;
+      for (let i = 0; i < rest.length; i++) {
+        if (ctx.text && isDyn(rest[i]) && !ASSIGN.test(plain(rest[i]))) return `${name} is followed by a word built by an expansion or a glob`;
+        const why = launchWhy(rest.slice(i), ctx, depth + 1);
+        if (why) return why;
+      }
       return null;
     }
-    const rest = words.slice(1);
     if (COMPILERS.has(name)) return name;
-    if (name === "tsc") return rest.some((w) => /^--?noEmit(=true)?$/i.test(w)) ? null : "tsc (emits)";
-    if (name === "vite" || name === "next") return rest.find((w) => !w.startsWith("-")) === "build" ? `${name} build` : null;
+    if (name === "tsc") return rest.some((x) => /^--?noEmit(=true)?$/i.test(x)) ? null : "tsc (emits)";
+    if (name === "vite" || name === "next") {
+      if (rest.some(isDyn)) return `${name} is given a word built by an expansion or a glob`;
+      return rest.find((x) => !x.startsWith("-")) === "build" ? `${name} build` : null;
+    }
     if (PACKAGE_MANAGERS.has(name)) {
       let next = null;
       for (let j = 0; j < rest.length; j++) {
+        if (isDyn(rest[j])) return `${name} is given a script or command built by an expansion or a glob`;
         if (OPTIONS_WITH_VALUES[name].has(rest[j])) { j++; continue; }
         if (rest[j].startsWith("-") || rest[j] === "run" || rest[j] === "run-script") continue;
         if (/^build(:|$)/.test(rest[j])) return `${name} ${rest[j]}`;
@@ -78,11 +299,16 @@ export function compileLaunch(program, args = []) {
         break;
       }
       if (!next || !next.length) return null;
-      words = next; continue;
+      w = next; continue;
     }
     return null;
   }
-  return null;
+  return w.length ? "launch chain too long to inspect" : null;
+}
+
+/** Why `[program, ...args]` is a compile or an emitting build, or null. A shell given a `-c` text is read by the shell parser (fail closed). */
+export function compileLaunch(program, args = []) {
+  return launchWhy([String(program), ...args.map(String)], { text: false, strict: false }, 0);
 }
 
 function refuse(why, program, args) {
@@ -94,11 +320,18 @@ function refuse(why, program, args) {
 
 function check(program, args, options) {
   const argv = Array.isArray(args) ? args : [];
-  if (options?.shell) { for (const cmd of shellWords([program, ...argv].join(" "))) { const why = compileLaunch(cmd[0], cmd.slice(1)); if (why) refuse(why, program, argv); } return; }
-  const why = compileLaunch(program, argv);
+  const why = options?.shell
+    ? shellTextWhy([program, ...argv].join(" "), dialectOfOptions(options), 0)
+    : launchWhy([String(program), ...argv.map(String)], { text: false, strict: true }, 0);
   if (why) refuse(why, program, argv);
 }
 
+function checkShellText(cmd, a) {
+  const options = a.find((x) => x && typeof x === "object");
+  const why = shellTextWhy(String(cmd), dialectOfOptions(options ?? {}), 0);
+  if (why) refuse(why, cmd, []);
+}
+
 /** `env` with the guard switched on and loaded (NODE_OPTIONS appended, never replaced). */
 export function withGuard(env) {
   const current = String(env.NODE_OPTIONS ?? "");
@@ -117,8 +350,8 @@ export function installLaunchGuard() {
   childProcess.spawnSync = function (...a) { const [p, v, opt] = split(a); check(p, v, opt); return o.spawnSync.apply(this, keep(a)); };
   childProcess.execFile = function (...a) { const [p, v, opt] = split(a); check(p, v, opt); return o.execFile.apply(this, keep(a)); };
   childProcess.execFileSync = function (...a) { const [p, v, opt] = split(a); check(p, v, opt); return o.execFileSync.apply(this, keep(a)); };
-  childProcess.exec = function (cmd, ...a) { for (const c of shellWords(cmd)) { const why = compileLaunch(c[0], c.slice(1)); if (why) refuse(why, cmd, []); } return o.exec.call(this, cmd, ...keep(a)); };
-  childProcess.execSync = function (cmd, ...a) { for (const c of shellWords(cmd)) { const why = compileLaunch(c[0], c.slice(1)); if (why) refuse(why, cmd, []); } return o.execSync.call(this, cmd, ...keep(a)); };
+  childProcess.exec = function (cmd, ...a) { checkShellText(cmd, a); return o.exec.call(this, cmd, ...keep(a)); };
+  childProcess.execSync = function (cmd, ...a) { checkShellText(cmd, a); return o.execSync.call(this, cmd, ...keep(a)); };
   childProcess.fork = function (modulePath, ...a) { const v = Array.isArray(a[0]) ? a[0] : []; check(modulePath, v, {}); return o.fork.call(this, modulePath, ...keep(a)); };
   syncBuiltinESMExports();
 }

package/cli/right-release.mjs

@@ -425,6 +425,8 @@ Commands:
   disk run-root --release <name>                     End a run-root lease
   disk schedule install|uninstall|status             Hourly launchd job (Mac) / hidden Task Scheduler entry (Windows) running "disk run --auto", bound to the stable per-user copy; status fails when no full pass finished in 26 h
   deps --check|--audit|--update                      Shared dependency lane
+  deps --cargo-lock --manifest <Cargo.toml> --pin <crate>=<version> [--pin <crate>=<version>]...
+                                                      Refresh one workspace's Cargo.lock (cargo update -p <crate> --precise <version>, one request per pin): the broker in the primary checkout on Mac and Dell, plain cargo on Linux; never a build. Refuses, and restores the lock, if any other file changes
   update check|apply|gate|land|discard|run|schedule [--repo <path>]
                                                       Run the pinned @rightkit/outdated updater (right-update) that moves stale pins; reads .rightkit/update.json
   hardening <artifact...>                            Run the Right Suite hardening scan

package/clippy-route.mjs

@@ -31,6 +31,8 @@ import { resolveExecutor as defaultResolveExecutor } from "./gate-executor.mjs";
 import { directPlatform } from "./managed-cargo.mjs";
 import { defaultSpawnAsync, sidecarBoundCrate } from "./deterministic-scans.mjs";
 import { gateStateDir } from "./gate-stages.mjs";
+import { ProvenanceError, verifyAttributionDetail } from "./provenance-verify.mjs";
+import { isToolchainUnknown } from "./snapshot-request.mjs";
 
 export const ROUTE_RECEIPT_SCHEMA = "rightkit.gate-clippy-route-receipt/1";
 export const ROUTE_DIAGNOSTICS_SCHEMA = "rightkit.gate-clippy-route-diagnostics/1";
@@ -261,26 +263,36 @@ export function summarizeRun({ messages, stderr = "", exit = null, signal = null
 // ---- the broker's half of the receipt: attribution and toolchain (rows 8.9, 8.16) ------------------------------------------------------
 
 /**
- * The gate's reading of a broker receipt for a Clippy request (BROKER-CONTRACT B4 to B6; the gate side only, wired when the carrier
- * is). Missing attribution, a truncated or unavailable one, or a missing toolchain identity makes the route result FAILED, never a
- * partial success: `{ aggregate, code, units, problems, toolchain, complete }`. The units are the receipt's per package and per
- * target `attribution` rows.
+ * The gate's reading of a broker receipt for a Clippy request (BROKER-CONTRACT B4 to B6; the gate side only, wired when the carrier is). The receipt's
+ * `attribution` is COMPACT (counts and a `detail` descriptor `{path, sha256}`); the per package and per target rows live in the evidence file the descriptor names
+ * (`detailBytes`, read by the caller from that path). GB-50: the per-unit result is derived only through `verifyAttributionDetail` (RustRight's
+ * verify_attribution_detail, vector attribution-detail-vectors.v1.json): the file's bytes hash to the signed descriptor, its schema, request id and toolchain are
+ * this receipt's, it is available and not truncated, every row is well formed and the compact counts equal the rows. Counts alone never pass (`units: 2` with exit 0
+ * and no matching detail is FAILED). Missing or unverifiable evidence makes the route result FAILED, never a partial success:
+ * `{ aggregate, code, units, failedUnits, problems, toolchain, complete }`. A unit with errors, or a nonzero exit, is a failure.
+ * The Clippy carrier stays explicitly refused (RK_CLIPPY_BROKER_CARRIER_NOT_WIRED) until the whole route is wired.
  */
-export function routeFromBrokerReceipt(receipt) {
+export function routeFromBrokerReceipt(receipt, detailBytes = null) {
   const problems = [];
   const attribution = receipt?.attribution;
   const toolchain = typeof receipt?.toolchain === "string" && receipt.toolchain.trim() ? receipt.toolchain : null;
+  let rows = null; let failedUnits = 0;
   if (!attribution || typeof attribution !== "object") problems.push("the receipt carries no attribution");
   else if (attribution.available !== true) problems.push(`the receipt's attribution is unavailable (${attribution.reason ?? "no reason"})`);
-  else if (!Array.isArray(attribution.units)) problems.push("the receipt's attribution lists no units");
-  else if (Number(attribution.truncated ?? 0) > 0) problems.push(`the receipt's attribution is truncated (${attribution.truncated} unit(s) not listed)`);
-  if (toolchain === null) problems.push("the receipt carries no toolchain identity");
-  const units = Array.isArray(attribution?.units) ? attribution.units.map((u) => ({ package: u.package, packageId: u.packageId ?? null, target: u.target, kind: u.kind ?? "", errors: Number(u.errors ?? 0), warnings: Number(u.warnings ?? 0), status: Number(u.errors ?? 0) > 0 ? "failed" : "clean", fresh: u.fresh ?? null })) : [];
+  else if (detailBytes === null || detailBytes === undefined) problems.push("the receipt's attribution is compact counts only and no detail file was supplied: counts alone cannot satisfy attribution");
+  else {
+    try { ({ rows, failedUnits } = verifyAttributionDetail(receipt, detailBytes)); } catch (e) {
+      if (!(e instanceof ProvenanceError)) throw e;
+      problems.push(`the receipt's attribution is not verified against its detail rows (${e.code}: ${e.message})`);
+    }
+  }
+  if (toolchain === null) problems.push(isToolchainUnknown(receipt?.toolchain) ? `the broker could not name the toolchain (${receipt.toolchain.reason}; RK_TOOLCHAIN_IDENTITY_UNAVAILABLE): the identity is UNKNOWN, not evidence` : "the receipt carries no toolchain identity");
+  const units = rows ? rows.map((u) => ({ package: u.package, packageId: u.packageId ?? null, target: u.target, kind: u.kind ?? "", errors: Number(u.errors ?? 0), warnings: Number(u.warnings ?? 0), status: Number(u.errors ?? 0) > 0 ? "failed" : "clean", fresh: u.fresh ?? null })) : [];
   const exit = receipt?.exit;
   const exitCode = typeof exit === "number" ? exit : typeof exit?.code === "number" ? exit.code : typeof exit?.status === "number" ? exit.status : null;
   if (exitCode === null) problems.push("the receipt carries no exit status");
-  const aggregate = problems.length || exitCode !== 0 || units.some((u) => u.status === "failed") ? "FAILED" : "PASSED";
-  return { aggregate, code: problems.length ? ROUTE_CODES.receiptEvidence : null, units, problems, toolchain, complete: aggregate === "PASSED" };
+  const aggregate = problems.length || exitCode !== 0 || failedUnits > 0 ? "FAILED" : "PASSED";
+  return { aggregate, code: problems.length ? ROUTE_CODES.receiptEvidence : null, units, failedUnits, problems, toolchain, complete: aggregate === "PASSED" };
 }
 
 // ---- sidecar-bound scope (row 8.8) -----------------------------------------------------------------------------------------------------

package/compile-inputs.mjs

@@ -7,8 +7,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
 import { SECRET_PATTERNS } from "./publish-cargo.mjs";
+import { COMPILE_INPUTS_CANONICAL, COMPILE_INPUTS_LEGACY, SnapshotRequestError, readDeclaredInputs } from "./snapshot-request.mjs";
 
-export const COMPILE_INPUTS_FILE = ".rightkit/compile-inputs.json";
+/** The canonical declaration (GB-49); the legacy `.rightkit/compile-inputs.json` is read only when it is absent (snapshot-request.mjs readDeclaredInputs, the one reader). */
+export const COMPILE_INPUTS_FILE = COMPILE_INPUTS_CANONICAL;
+export { COMPILE_INPUTS_LEGACY };
 
 /** Files of one declared input in the broker's order (children by name), refusing links; [{ name, abs }]. */
 function inputFiles(root, input) {
@@ -32,20 +35,14 @@ function inputFiles(root, input) {
  */
 export function judgeCompileInputs(root, { spawn = spawnSync, execPath = process.execPath } = {}) {
   const findings = [];
-  let declared = [];
-  const file = path.join(root, COMPILE_INPUTS_FILE);
-  if (!fs.existsSync(file)) return { inputs: [], findings };
-  try {
-    declared = JSON.parse(fs.readFileSync(file, "utf8")).inputs;
-    if (!Array.isArray(declared) || declared.some((p) => typeof p !== "string")) throw new Error("`inputs` must be a list of paths");
-  } catch (e) {
-    return { inputs: [], findings: [`${COMPILE_INPUTS_FILE}: ${e.message}`] };
-  }
+  // One reader for every consumer: canonical first, legacy only when the canonical file is absent, shared link, size, path and overlap checks.
+  let declared;
+  try { declared = readDeclaredInputs(root); } catch (e) { if (e instanceof SnapshotRequestError) return { inputs: [], findings: [e.message] }; throw e; }
+  if (declared.length === 0) return { inputs: [], findings };
   const inputs = [];
   for (const input of declared) {
-    if (path.isAbsolute(input) || input.split(/[\\/]/).some((part) => part === ".." || part === "." || part === "")) { findings.push(`${input}: not a plain relative path`); continue; }
     let files;
-    try { files = inputFiles(root, input); } catch (e) { findings.push(`${input}: ${e.code === "ENOENT" ? "missing from the captured tree" : e.message}`); continue; }
+    try { files = inputFiles(root, input.split(/[\\/]/).join("/")); } catch (e) { findings.push(`${input}: ${e.code === "ENOENT" ? "missing from the captured tree" : e.message}`); continue; }
     const hash = crypto.createHash("sha256");
     for (const f of files) {
       const bytes = fs.readFileSync(f.abs);

package/control-plane.mjs

@@ -0,0 +1,18 @@
+// GB-07 (BROKER-CONTRACT section 16): where a unit publication's control plane may run. One definition for the gate's release (unit-gate.mjs) and the coordinator's in-gate entry
+// (scripts/ci/rk-pipeline.mjs runPipeline), so neither can drift from the broker's own rule.
+import path from "node:path";
+
+/**
+ * Why the control-plane checkout (the primary checkout, where the coordinator's uncarried root requests are admitted) is not apart from the managed snapshots, or null. The broker refuses a root
+ * request whose working directory is inside a managed snapshot or a path a live snapshot lease holds (RK_CHECK_ERROR: "a root request cannot run inside a managed snapshot"), so the control plane may
+ * not be inside the managed snapshots root; with a `root` (the source: the snapshot where the carried build and pack steps stay bound) it may not be inside the source either, and a source that is
+ * itself a snapshot may not be its own control plane. A direct, unsnapshotted source keeps one root for both. `pathApi` is the platform's path module; comparison folds case on Windows.
+ */
+export function controlPlaneProblem({ root = null, checkout, snapshotsRoot = null, pathApi = path }) {
+  const fold = (p) => { const n = pathApi.normalize(String(p)); return pathApi === path.win32 ? n.toLowerCase() : n; };
+  const inside = (child, parent) => { const rel = pathApi.relative(fold(parent), fold(child)); return rel === "" || (!rel.startsWith("..") && !pathApi.isAbsolute(rel)); };
+  if (typeof checkout !== "string" || !pathApi.isAbsolute(checkout)) return `the control-plane checkout ${JSON.stringify(checkout)} must be an absolute path`;
+  if (snapshotsRoot && inside(checkout, snapshotsRoot)) return `the control-plane checkout ${checkout} is inside the managed snapshots root ${snapshotsRoot}: the broker refuses an uncarried root request there (RK_CHECK_ERROR: a root request cannot run inside a managed snapshot); the coordinator runs from the primary checkout, apart from the source snapshot`;
+  if (root !== null && fold(checkout) !== fold(root) && inside(checkout, root)) return `the control-plane checkout ${checkout} is inside the source root ${root}: the source (the snapshot) and the control plane (the primary checkout) are separate roots`;
+  return null;
+}