jules-orchestrator-kit 0.74.0 → 0.75.1

package/scripts/ci-scope-guard.mjs

@@ -16,14 +16,18 @@
  */
 import { execFileSync } from "node:child_process";
 import { checkScope } from "../src/security.mjs";
-import { normalizePath } from "../src/config.mjs";
+import { normalizePath, canonicalizePath } from "../src/config.mjs";
 
 /** Exit code 3 in the kit's registry: scope violation. */
 const EXIT_SCOPE_VIOLATION = 3;
 const EXIT_ERROR = 1;
 
-/** Label that lets a human consciously land a protected-path change. */
-export const BYPASS_LABEL = "allow-protected-paths";
+/**
+ * Primary label prefix that lets a human consciously land a protected-path change bound to commit SHA.
+ * Conforms to GitHub's 50-character maximum label limit: "allow-p:<40-hex-SHA>" is 48 characters.
+ */
+export const BYPASS_LABEL = "allow-p";
+export const LEGACY_BYPASS_LABEL = "allow-protected-paths";
 
 function gitShow(ref, path, cwd) {
   return execFileSync("git", ["show", `${ref}:${path}`], {
@@ -70,45 +74,228 @@ export function loadProtectedPatterns(opts = {}) {
   );
 }
 
+/** Where a symlink at `link` pointing at `target` lands, as a repo-relative or absolute path. */
+export function resolveLinkTarget(link, target) {
+  const normLink = normalizePath(link);
+  const normTarget = normalizePath(target);
+  if (normTarget.startsWith("/") || /^[a-zA-Z]:[/\\]/.test(target)) {
+    return normTarget;
+  }
+  const linkDir = normLink.split("/").slice(0, -1).join("/");
+  return canonicalizePath(linkDir ? `${linkDir}/${normTarget}` : normTarget);
+}
+
+/**
+ * Parses `git diff --raw -z` output into structured file change entries.
+ *
+ * Each record emitted by `--raw -z` is:
+ *   ":<srcmode> <dstmode> <srcsha> <dstsha> <status>\0<path>\0"
+ * (or two paths if renames were enabled). With `--no-renames`, it is always 1 path.
+ *
+ * For symlinks (mode 120000), retrieves the link target blob via `git cat-file blob <dstSha>`
+ * without checking out the branch to disk.
+ *
+ * @param {string} raw - raw stdout from git diff --raw -z
+ * @param {string} [root] - repo root cwd
+ * @returns {Array<{ file: string, srcMode: string, dstMode: string, srcSha: string, dstSha: string, status: string, symlinkTarget?: string, symlinkUnreadable?: boolean }>}
+ */
+export function parseRawDiffEntries(raw, root = process.cwd()) {
+  if (!raw || typeof raw !== "string") return [];
+  const fields = raw.split("\0").filter((f) => f !== "");
+  const entries = [];
+
+  for (let i = 0; i < fields.length; i++) {
+    const meta = fields[i];
+    if (!meta.startsWith(":")) continue;
+    const parts = meta.slice(1).split(/\s+/);
+    const file = fields[i + 1];
+    i += 1;
+    if (!file) continue;
+
+    const srcMode = parts[0] || "";
+    const dstMode = parts[1] || "";
+    const srcSha = parts[2] || "";
+    const dstSha = parts[3] || "";
+    const status = (parts[4] || "").charAt(0);
+
+    let symlinkTarget = null;
+    let symlinkUnreadable = false;
+
+    if (dstMode === "120000") {
+      if (dstSha && !/^0+$/.test(dstSha)) {
+        try {
+          const rawTarget = execFileSync("git", ["cat-file", "blob", dstSha], {
+            cwd: root,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+          }).trim();
+          if (rawTarget) {
+            symlinkTarget = resolveLinkTarget(file, rawTarget);
+          } else {
+            symlinkUnreadable = true;
+          }
+        } catch (_) {
+          symlinkUnreadable = true;
+        }
+      } else {
+        symlinkUnreadable = true;
+      }
+    }
+
+    entries.push({
+      file: normalizePath(file),
+      srcMode,
+      dstMode,
+      srcSha,
+      dstSha,
+      status,
+      symlinkTarget,
+      symlinkUnreadable,
+    });
+  }
+
+  return entries;
+}
+
 /**
  * Lists the paths a pull request changes.
  *
- * `-z` and `core.quotePath=false` matter here: without them git splits on
- * whitespace and octal-escapes non-ASCII names, so `docs/min plan.md` and
- * `säkerhet/nyckel.pem` arrive as tokens that match no pattern — a protected
- * file walking past the guard because of how it is spelled.
+ * Inspects `git diff --raw -z --no-renames` to capture all paths while
+ * preserving spaces and non-ASCII characters without quoting corruption.
  *
  * @param {{ baseSha: string, headSha: string, root?: string }} opts
  * @returns {string[]}
  */
 export function listChangedFiles(opts = {}) {
+  return listChangedEntries(opts).map((e) => e.file);
+}
+
+/**
+ * Returns raw diff entries including blob mode and symlink resolution.
+ *
+ * @param {{ baseSha: string, headSha: string, root?: string }} opts
+ * @returns {Array<{ file: string, srcMode: string, dstMode: string, srcSha: string, dstSha: string, status: string, symlinkTarget?: string, symlinkUnreadable?: boolean }>}
+ */
+export function listChangedEntries(opts = {}) {
   const root = opts.root || process.cwd();
   const raw = execFileSync(
     "git",
-    ["-c", "core.quotePath=false", "diff", "-z", "--name-only", opts.baseSha, opts.headSha],
+    ["-c", "core.quotePath=false", "diff", "-z", "--raw", "--no-renames", opts.baseSha, opts.headSha],
     { cwd: root, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 10 * 1024 * 1024 }
   );
-  return raw.split("\0").map(normalizePath).filter(Boolean);
+  return parseRawDiffEntries(raw, root);
 }
 
 /**
  * Pure evaluation core, so the decision is testable without a git repository.
  *
- * @param {string[]} files
+ * Evaluates changed files and entries against protected patterns:
+ * - Rejects Git submodules (mode 160000)
+ * - Evaluates symlinks (mode 120000): rejects traversal / root escape, fails closed on unreadable targets,
+ *   and fails if the resolved symlink target points to a protected file.
+ *
+ * @param {Array<string|object>} filesOrEntries
  * @param {string[]} patterns
- * @param {{ labels?: string[] }} [opts]
+ * @param {{ labels?: string[], headSha?: string, symlinks?: Array<{ link: string, target: string }> }} [opts]
  * @returns {{ ok: boolean, bypassed: boolean, violations: Array<object> }}
  */
-export function evaluateScopeGuard(files = [], patterns = [], opts = {}) {
+export function evaluateScopeGuard(filesOrEntries = [], patterns = [], opts = {}) {
   const labels = (opts.labels || []).map((l) => String(l).toLowerCase().trim());
-  const bypassed = labels.includes(BYPASS_LABEL);
+  const headSha = String(opts.headSha || "").trim().toLowerCase();
+
+  let bypassed = false;
+  if (headSha) {
+    if (/^[0-9a-f]{40}$/i.test(headSha)) {
+      const boundLabel = `${BYPASS_LABEL}:${headSha}`;
+      const legacyBoundLabel = `${LEGACY_BYPASS_LABEL}:${headSha}`;
+      bypassed = labels.includes(boundLabel) || labels.includes(legacyBoundLabel);
+    }
+  } else {
+    bypassed = labels.includes(BYPASS_LABEL) || labels.includes(LEGACY_BYPASS_LABEL);
+  }
+
+  const normalizedEntries = [];
+  for (const item of filesOrEntries) {
+    if (typeof item === "string") {
+      normalizedEntries.push({ file: item });
+    } else if (item && typeof item === "object") {
+      normalizedEntries.push(item);
+    }
+  }
+
+  if (Array.isArray(opts.symlinks)) {
+    for (const s of opts.symlinks) {
+      if (s && s.link) {
+        normalizedEntries.push({
+          file: s.link,
+          dstMode: "120000",
+          symlinkTarget: s.target || null,
+        });
+      }
+    }
+  }
+
+  const explicitViolations = [];
+  const scopeCandidates = [];
+  const symlinkTargetOf = new Map();
+
+  for (const entry of normalizedEntries) {
+    const file = entry.file || "";
+    if (file) {
+      scopeCandidates.push(file);
+    }
+
+    // 1. Refuse Git submodules (mode 160000)
+    if (entry.dstMode === "160000") {
+      explicitViolations.push({
+        file,
+        reason: "Git submodule (mode 160000) is forbidden in agent pull requests",
+        rule: "deny",
+        pattern: "<submodule>",
+      });
+      continue;
+    }
+
+    // 2. Inspect Symlinks (mode 120000)
+    if (entry.dstMode === "120000") {
+      if (entry.symlinkUnreadable || !entry.symlinkTarget) {
+        explicitViolations.push({
+          file,
+          reason: "Unreadable or empty symlink target cannot be verified",
+          rule: "deny",
+          pattern: "<unreadable-symlink>",
+        });
+        continue;
+      }
+
+      const target = entry.symlinkTarget;
+      scopeCandidates.push(target);
+      symlinkTargetOf.set(target, file);
+    }
+  }
 
   // Matching always runs at full strength; the label only decides whether a
   // match blocks. Passing `allowProtected` into checkScope instead would make
   // a bypassed run report zero violations, and the job log is the record of
   // what a human waved through.
-  const res = checkScope(files, { protect: patterns }, { allowProtected: false });
-  return { ok: bypassed || res.ok, bypassed, violations: res.violations };
+  const res = checkScope(scopeCandidates, { protect: patterns }, { allowProtected: false });
+
+  const mappedScopeViolations = (res.violations || []).map((v) => {
+    const link = symlinkTargetOf.get(v.file);
+    if (link) {
+      return {
+        ...v,
+        link,
+        file: link,
+        target: v.file,
+        reason: `Symlink "${link}" -> "${v.file}": ${v.reason}`,
+      };
+    }
+    return v;
+  });
+
+  const allViolations = [...explicitViolations, ...mappedScopeViolations];
+  return { ok: bypassed || allViolations.length === 0, bypassed, violations: allViolations };
 }
 
 /**
@@ -142,27 +329,43 @@ function main() {
   }
 
   let patterns;
-  let files;
+  let entries = [];
   try {
     patterns = loadProtectedPatterns({ baseSha, baseRef, root });
-    files = listChangedFiles({ baseSha, headSha, root });
+    entries = listChangedEntries({ baseSha, headSha, root });
   } catch (err) {
     console.error(`::error::Agent Scope Guard could not evaluate this pull request: ${err.message}`);
     process.exit(EXIT_ERROR);
   }
 
   const labels = parseLabels(process.env.PR_LABELS);
-  const result = evaluateScopeGuard(files, patterns, { labels });
+  const result = evaluateScopeGuard(entries, patterns, { labels, headSha });
 
   console.log(`Protected patterns (${patterns.length}): ${patterns.join(", ")}`);
-  console.log(`Changed files (${files.length}):`);
-  for (const f of files) console.log(`  ${f}`);
+  console.log(`Changed files (${entries.length}):`);
+  for (const e of entries) {
+    if (e.dstMode === "120000") {
+      console.log(`  ${e.file} -> ${e.symlinkTarget || "(unresolved)"} [symlink]`);
+    } else if (e.dstMode === "160000") {
+      console.log(`  ${e.file} [submodule]`);
+    } else {
+      console.log(`  ${e.file}`);
+    }
+  }
+
+  const labelName = headSha ? `${BYPASS_LABEL}:${headSha}` : BYPASS_LABEL;
+  const legacyLabelName = headSha ? `${LEGACY_BYPASS_LABEL}:${headSha}` : LEGACY_BYPASS_LABEL;
+  const activeLabel = labels.includes(labelName)
+    ? labelName
+    : labels.includes(legacyLabelName)
+      ? legacyLabelName
+      : labelName;
 
   if (result.bypassed && result.violations.length > 0) {
     for (const v of result.violations) {
-      console.log(`::warning file=${v.file}::Protected path modified under "${BYPASS_LABEL}": ${v.reason}`);
+      console.log(`::warning file=${v.file}::Protected path modified under "${activeLabel}": ${v.reason}`);
     }
-    console.log(`\nLabel "${BYPASS_LABEL}" is present — ${result.violations.length} protected-path match(es) allowed by human review.`);
+    console.log(`\nLabel "${activeLabel}" is present — ${result.violations.length} protected-path match(es) allowed by human review.`);
     process.exit(0);
   }
 
@@ -176,7 +379,7 @@ function main() {
   }
   console.error(
     `::error::PR modifies ${result.violations.length} protected file(s). ` +
-      `Apply the "${BYPASS_LABEL}" label after human review to land this intentionally.`
+      `Apply the "${labelName}" label after human review to land this intentionally.`
   );
   process.exit(EXIT_SCOPE_VIOLATION);
 }

package/scripts/run-tests.mjs

@@ -101,18 +101,22 @@ function reap(signal = "SIGKILL") {
 
 // Ctrl-C, a CI cancellation and a harness teardown all arrive as signals; each
 // must take the tree with it rather than detaching it from its parent.
+let shuttingDown = false;
 for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
   process.on(sig, () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
     reap("SIGTERM");
     // Give the group a moment to unwind, then make sure.
     setTimeout(() => {
       reap("SIGKILL");
-      process.exit(130);
+      process.exit(sig === "SIGINT" ? 130 : 143);
     }, 2000).unref();
   });
 }
 
 child.on("exit", (code, signal) => {
+  if (shuttingDown) return;
   // Stragglers outlive a clean exit too: a test that spawned a server and
   // failed before its teardown leaves it running.
   reap("SIGKILL");

package/src/bidi-guard.mjs

@@ -1,36 +1,211 @@
 /**
- * Trojan Source (CVE-2021-42574) BiDi override detection.
+ * Unicode security detection for diffs and source text.
+ *
+ * Covers Trojan Source BiDi overrides (CVE-2021-42574), invisible/zero-width
+ * obfuscation characters, Unicode Plane 14 tags, and mixed-script confusable
+ * identifiers (Latin mixed with vetted Cyrillic/Greek lookalikes).
  *
- * Split out of src/security.mjs (P05). A Unicode directional override can make
- * the line an agent reads differ from the line the parser executes, so the
- * check runs on every added line of every non-markdown file before anything
- * else looks at the diff.
+ * Split out of src/security.mjs (P05). A Unicode directional override — or an
+ * invisible filler mid-token — can make the line an agent reads differ from
+ * the line the parser executes, so these checks run on every added line of
+ * every non-markdown file before anything else looks at the diff.
+ *
+ * Zero third-party deps; Node ESM builtins + the shared confusable table from
+ * secret-scanner.mjs only.
  */
 
-export function checkTrojanSource(diffOrText = "", _options = {}) {
-  if (!diffOrText || typeof diffOrText !== "string") return { ok: true, violations: [] };
+import { CONFUSABLE_TO_ASCII } from "./secret-scanner.mjs";
 
-  const violations = [];
-  const bidiRegex = /[\u202A\u202B\u202C\u202D\u202E\u2066\u2067\u2068\u2069\u061C\u200E\u200F]/;
+/**
+ * BiDi directional controls — the CVE-2021-42574 Trojan Source set (12 chars).
+ * Exported so scanDiff can locate the offending line without duplicating the set.
+ */
+export const BIDI_CONTROL_REGEX =
+  /[\u202A\u202B\u202C\u202D\u202E\u2066\u2067\u2068\u2069\u061C\u200E\u200F]/;
+
+/**
+ * Invisible ZW / Hangul fillers used to obfuscate identifiers on added lines:
+ * U+00AD, U+200B–U+200D, U+2060–U+2064, U+FEFF, U+034F, U+3164, U+FFA0,
+ * U+115F, U+1160.
+ */
+export const INVISIBLE_OBFUSCATION_REGEX =
+  /[\u00AD\u200B-\u200D\u2060-\u2064\uFEFF\u034F\u3164\uFFA0\u115F\u1160]/;
+
+/** Unicode Plane 14 language tags U+E0000–U+E007F. */
+export const PLANE14_TAG_REGEX = /[\u{E0000}-\u{E007F}]/u;
+
+/**
+ * Cyrillic/Greek entries from the secret-scanner confusable table.
+ * Latin lookalikes outside those scripts (ſ, K) are intentionally excluded —
+ * they are not mixed-script substitutions.
+ */
+const MIXED_SCRIPT_CONFUSABLE_CHARS = [...CONFUSABLE_TO_ASCII.keys()].filter((ch) => {
+  const cp = ch.codePointAt(0);
+  return (cp >= 0x0370 && cp <= 0x03ff) || (cp >= 0x0400 && cp <= 0x04ff);
+});
 
+const CONFUSABLE_CLASS = MIXED_SCRIPT_CONFUSABLE_CHARS.map(
+  (ch) => `\\u${ch.codePointAt(0).toString(16).padStart(4, "0")}`,
+).join("");
+
+/** Identifier-like tokens built from ASCII id chars and vetted confusables. */
+export const MIXED_SCRIPT_TOKEN_REGEX = new RegExp(
+  `[A-Za-z0-9_${CONFUSABLE_CLASS}]+`,
+  "g",
+);
+
+const HAS_LATIN_ID = /[A-Za-z0-9_]/;
+const HAS_CONFUSABLE = new RegExp(`[${CONFUSABLE_CLASS}]`);
+
+/**
+ * True when a line contains an identifier token that mixes Latin [A-Za-z0-9_]
+ * with at least one Cyrillic/Greek confusable (e.g. Cyrillic i or a in an ASCII token).
+ * Pure Cyrillic / Greek / multilingual text without intra-token Latin mixing
+ * does not match.
+ *
+ * @param {string} line
+ * @returns {boolean}
+ */
+export function hasMixedScriptConfusable(line) {
+  if (!line || typeof line !== "string") return false;
+  MIXED_SCRIPT_TOKEN_REGEX.lastIndex = 0;
+  let match;
+  while ((match = MIXED_SCRIPT_TOKEN_REGEX.exec(line)) !== null) {
+    const token = match[0];
+    if (HAS_LATIN_ID.test(token) && HAS_CONFUSABLE.test(token)) return true;
+  }
+  return false;
+}
+
+/**
+ * Select the lines to scan: added lines of a unified diff, or every line of
+ * plain text.
+ *
+ * @param {string} diffOrText
+ * @returns {string[]}
+ */
+function targetLines(diffOrText) {
   const lines = diffOrText.split("\n");
-  // Only filter diff syntax if we actually start with typical diff headers
+  // Only filter diff syntax if we actually start with typical diff headers.
   // This avoids treating text containing "+++ b/" as a diff mistakenly.
-  const isDiff = diffOrText.startsWith("--- a/") || diffOrText.startsWith("+++ b/") || diffOrText.includes("\n+++ b/");
+  const isDiff =
+    diffOrText.startsWith("--- a/") ||
+    diffOrText.startsWith("+++ b/") ||
+    diffOrText.includes("\n+++ b/");
 
-  const targetLines = lines.filter((line) => {
+  return lines.filter((line) => {
     if (isDiff) {
       return line.startsWith("+") && !line.startsWith("+++");
     }
     return true;
   });
+}
 
-  for (const line of targetLines) {
-    if (bidiRegex.test(line)) {
-      violations.push({ reason: "Trojan Source BiDi override detected: contains invisible directional control characters (CVE-2021-42574)." });
+/**
+ * Trojan Source (CVE-2021-42574) BiDi override detection.
+ * Backward-compatible: returns `{ ok, violations }` and only reports BiDi
+ * controls. Broader Unicode checks live in {@link checkUnicodeSecurity}.
+ *
+ * @param {string} [diffOrText=""]
+ * @param {object} [_options={}]
+ * @returns {{ ok: boolean, violations: Array<{ reason: string }> }}
+ */
+export function checkTrojanSource(diffOrText = "", _options = {}) {
+  if (!diffOrText || typeof diffOrText !== "string") return { ok: true, violations: [] };
+
+  const violations = [];
+  for (const line of targetLines(diffOrText)) {
+    if (BIDI_CONTROL_REGEX.test(line)) {
+      violations.push({
+        reason:
+          "Trojan Source BiDi override detected: contains invisible directional control characters (CVE-2021-42574).",
+      });
       break; // One violation is enough for the file/diff block
     }
   }
 
   return { ok: violations.length === 0, violations };
 }
+
+/**
+ * Full Unicode security pass over a diff or plain text.
+ *
+ * Categories (at most one finding each):
+ *   - TROJAN_SOURCE_DETECTED — BiDi controls (CVE-2021-42574)
+ *   - UNICODE_OBFUSCATION_DETECTED — ZW/Hangul fillers or Plane 14 tags
+ *   - MIXED_SCRIPT_CONFUSABLE_DETECTED — Latin+confusable identifier tokens
+ *
+ * @param {string} [diffOrText=""]
+ * @param {object} [_options={}]
+ * @returns {{
+ *   ok: boolean,
+ *   violations: Array<{ reason: string, type: string }>
+ * }}
+ */
+export function checkUnicodeSecurity(diffOrText = "", _options = {}) {
+  if (!diffOrText || typeof diffOrText !== "string") return { ok: true, violations: [] };
+
+  const violations = [];
+  let sawBidi = false;
+  let sawObfuscation = false;
+  let sawMixed = false;
+
+  for (const line of targetLines(diffOrText)) {
+    if (!sawBidi && BIDI_CONTROL_REGEX.test(line)) {
+      sawBidi = true;
+      violations.push({
+        type: "TROJAN_SOURCE_DETECTED",
+        reason:
+          "Trojan Source BiDi override detected: contains invisible directional control characters (CVE-2021-42574).",
+      });
+    }
+    if (
+      !sawObfuscation &&
+      (INVISIBLE_OBFUSCATION_REGEX.test(line) || PLANE14_TAG_REGEX.test(line))
+    ) {
+      sawObfuscation = true;
+      violations.push({
+        type: "UNICODE_OBFUSCATION_DETECTED",
+        reason:
+          "Unicode obfuscation detected: invisible zero-width, Hangul filler, or Plane 14 tag characters on an added line.",
+      });
+    }
+    if (!sawMixed && hasMixedScriptConfusable(line)) {
+      sawMixed = true;
+      violations.push({
+        type: "MIXED_SCRIPT_CONFUSABLE_DETECTED",
+        reason:
+          "Mixed-script confusable identifier detected: Latin characters combined with Cyrillic/Greek lookalikes in one token.",
+      });
+    }
+    if (sawBidi && sawObfuscation && sawMixed) break;
+  }
+
+  return { ok: violations.length === 0, violations };
+}
+
+/**
+ * Locate the first added-line number that triggers a given Unicode finding type.
+ * Shared by scanDiff so it does not re-embed detection regexes.
+ *
+ * @param {Array<{ text: string, no: number|null }>} lines
+ * @param {string} type
+ * @returns {number|null}
+ */
+export function locateUnicodeFindingLine(lines, type) {
+  if (!Array.isArray(lines)) return null;
+  for (const l of lines) {
+    if (!l || typeof l.text !== "string") continue;
+    const text = l.text;
+    let hit = false;
+    if (type === "TROJAN_SOURCE_DETECTED") {
+      hit = BIDI_CONTROL_REGEX.test(text);
+    } else if (type === "UNICODE_OBFUSCATION_DETECTED") {
+      hit = INVISIBLE_OBFUSCATION_REGEX.test(text) || PLANE14_TAG_REGEX.test(text);
+    } else if (type === "MIXED_SCRIPT_CONFUSABLE_DETECTED") {
+      hit = hasMixedScriptConfusable(text);
+    }
+    if (hit) return l.no ?? null;
+  }
+  return null;
+}