@node9/policy-engine 2.13.1 → 2.14.1

package/dist/index.mjs

@@ -1121,6 +1121,19 @@ function parseShared(command) {
   astCache.set(command, parsed);
   return parsed;
 }
+function byteOffsetToCharIndex(command) {
+  if (!/[^\u0000-\u007F]/.test(command)) return null;
+  const map = /* @__PURE__ */ new Map();
+  let byte = 0;
+  for (let i = 0; i < command.length; ) {
+    map.set(byte, i);
+    const cp = command.codePointAt(i);
+    byte += cp < 128 ? 1 : cp < 2048 ? 2 : cp < 65536 ? 3 : 4;
+    i += cp > 65535 ? 2 : 1;
+  }
+  map.set(byte, command.length);
+  return (b) => map.get(b) ?? -1;
+}
 function cachedNormalize(command, compute) {
   const hit = normalizeCache.get(command);
   if (hit !== void 0) {
@@ -1150,6 +1163,8 @@ function normalizeCommandForPolicyImpl(command) {
   const f = parseShared(command);
   if (f === PARSE_FAIL) return { posix: command, separator: command };
   try {
+    const toCharIndex = byteOffsetToCharIndex(command);
+    const at = (byteOffset) => toCharIndex === null ? byteOffset : toCharIndex(byteOffset);
     const strips = [];
     const rewrites = [];
     const quoteOnlyRewrites = [];
@@ -1170,8 +1185,9 @@ function normalizeCommandForPolicyImpl(command) {
         const quotedNode = nextParts[0];
         const nt = syntax.NodeType(quotedNode);
         const markStrip = () => {
-          const s = next.Pos().Offset();
-          const e = next.End().Offset();
+          const s = at(next.Pos().Offset());
+          const e = at(next.End().Offset());
+          if (s < 0 || e < 0) return;
           strips.push([s, e]);
           msgSpans.add(`${s}:${e}`);
         };
@@ -1188,8 +1204,9 @@ function normalizeCommandForPolicyImpl(command) {
         }
       }
       for (const arg of args) {
-        const s = arg.Pos().Offset();
-        const e = arg.End().Offset();
+        const s = at(arg.Pos().Offset());
+        const e = at(arg.End().Offset());
+        if (s < 0 || e < 0) continue;
         if (msgSpans.has(`${s}:${e}`)) continue;
         const resolved = resolveWordLiteral(arg);
         if (resolved === null) continue;
@@ -1312,12 +1329,410 @@ var FS_READ_TOOLS = /* @__PURE__ */ new Set([
   "nl",
   "dd"
 ]);
+var GREP_SHAPE = {
+  takesValue: /* @__PURE__ */ new Set([
+    "-A",
+    "-B",
+    "-C",
+    "-D",
+    "-d",
+    "-e",
+    "-f",
+    "-m",
+    "--after-context",
+    "--before-context",
+    "--binary-files",
+    "--context",
+    "--devices",
+    "--directories",
+    "--exclude",
+    "--exclude-dir",
+    "--exclude-from",
+    "--file",
+    "--include",
+    "--label",
+    "--max-count",
+    "--regexp"
+  ]),
+  noValue: /* @__PURE__ */ new Set([
+    "-E",
+    "-F",
+    "-G",
+    "-P",
+    "-i",
+    "-y",
+    "-v",
+    "-V",
+    "-w",
+    "-x",
+    "-c",
+    "-l",
+    "-L",
+    "-o",
+    "-q",
+    "-s",
+    "-b",
+    "-H",
+    "-h",
+    "-n",
+    "-T",
+    "-Z",
+    "-z",
+    "-R",
+    "-r",
+    "-U",
+    "-u",
+    "-I",
+    "-a",
+    "--basic-regexp",
+    "--binary",
+    "--byte-offset",
+    "--color",
+    "--colour",
+    "--count",
+    "--dereference-recursive",
+    "--extended-regexp",
+    "--files-with-matches",
+    "--files-without-match",
+    "--fixed-strings",
+    "--help",
+    "--ignore-case",
+    "--initial-tab",
+    "--invert-match",
+    "--line-buffered",
+    "--line-number",
+    "--line-regexp",
+    "--no-filename",
+    "--no-group-separator",
+    "--no-ignore-case",
+    "--no-messages",
+    "--null",
+    "--null-data",
+    "--only-matching",
+    "--perl-regexp",
+    "--quiet",
+    "--recursive",
+    "--silent",
+    "--text",
+    "--version",
+    "--with-filename",
+    "--word-regexp"
+  ]),
+  patternFlags: /* @__PURE__ */ new Set(["-e", "--regexp"]),
+  noPatternFlags: /* @__PURE__ */ new Set(["-f", "--file"])
+};
+var PATTERN_VERBS = {
+  grep: GREP_SHAPE,
+  // /usr/bin/egrep and /usr/bin/fgrep are 41-byte shell wrappers that exec
+  // `grep -E` and `grep -F`. Read in full, not assumed.
+  egrep: GREP_SHAPE,
+  fgrep: GREP_SHAPE,
+  // ripgrep 14.1.1, complete from its own --help. An earlier comment here said rg
+  // was not installed on the measuring machine; it is, and that stale claim is why
+  // this table shipped incomplete for two rounds, blocking ordinary searches like
+  // `rg --sort-files .env src` (/code-review round 4).
+  rg: {
+    takesValue: /* @__PURE__ */ new Set([
+      "-A",
+      "-B",
+      "-C",
+      "-d",
+      "-E",
+      "-e",
+      "-f",
+      "-g",
+      "-j",
+      "-M",
+      "-m",
+      "-r",
+      "-t",
+      "-T",
+      "--after-context",
+      "--before-context",
+      "--color",
+      "--colors",
+      "--context",
+      "--context-separator",
+      "--dfa-size-limit",
+      "--encoding",
+      "--engine",
+      "--field-context-separator",
+      "--field-match-separator",
+      "--file",
+      "--generate",
+      "--glob",
+      "--hostname-bin",
+      "--hyperlink-format",
+      "--iglob",
+      "--ignore-file",
+      "--max-columns",
+      "--max-count",
+      "--max-depth",
+      // An ALIAS of --max-depth, and it takes a value. The round-5 extraction read
+      // alias lines as plain switches and swept it into noValue, which hard-blocked
+      // `rg --maxdepth 2 .env src` while `--max-depth 2` ran (/code-review round 7).
+      "--maxdepth",
+      "--max-filesize",
+      "--path-separator",
+      "--pre",
+      "--pre-glob",
+      "--regexp",
+      "--regex-size-limit",
+      "--replace",
+      "--sort",
+      "--sortr",
+      "--threads",
+      "--type",
+      "--type-add",
+      "--type-clear",
+      "--type-not"
+    ]),
+    noValue: /* @__PURE__ */ new Set([
+      "-.",
+      "-0",
+      "-a",
+      "-b",
+      "-c",
+      "-F",
+      "-h",
+      "-H",
+      "-i",
+      "-I",
+      "-l",
+      "-L",
+      "-n",
+      "-N",
+      "-o",
+      "-p",
+      "-P",
+      "-q",
+      "-s",
+      "-S",
+      "-u",
+      "-U",
+      "-v",
+      "-V",
+      "-w",
+      "-x",
+      "-z",
+      "--auto-hybrid-regex",
+      "--binary",
+      "--block-buffered",
+      "--byte-offset",
+      "--case-sensitive",
+      "--column",
+      "--count",
+      "--count-matches",
+      "--crlf",
+      "--debug",
+      "--files",
+      "--files-with-matches",
+      "--files-without-match",
+      "--fixed-strings",
+      "--follow",
+      "--glob-case-insensitive",
+      "--heading",
+      "--help",
+      "--hidden",
+      "--ignore-case",
+      "--ignore-file-case-insensitive",
+      "--include-zero",
+      "--invert-match",
+      "--json",
+      "--line-buffered",
+      "--line-number",
+      "--line-regexp",
+      "--max-columns-preview",
+      "--mmap",
+      "--multiline",
+      "--multiline-dotall",
+      "--no-column",
+      "--no-config",
+      "--no-context-separator",
+      "--no-encoding",
+      "--no-filename",
+      "--no-ignore",
+      "--no-ignore-dot",
+      "--no-ignore-exclude",
+      "--no-ignore-files",
+      "--no-ignore-global",
+      "--no-ignore-messages",
+      "--no-ignore-parent",
+      "--no-ignore-vcs",
+      "--no-line-number",
+      "--no-messages",
+      "--no-pcre2-unicode",
+      "--no-pre",
+      "--no-require-git",
+      "--no-unicode",
+      "--null",
+      "--null-data",
+      "--one-file-system",
+      "--only-matching",
+      "--passthru",
+      "--pcre2",
+      "--pcre2-version",
+      "--pretty",
+      "--print0",
+      "--quiet",
+      "--search-zip",
+      "--smart-case",
+      "--sort-files",
+      "--stats",
+      "--stop-on-nonmatch",
+      "--text",
+      "--trace",
+      "--trim",
+      "--type-list",
+      "--unrestricted",
+      "--version",
+      "--vimgrep",
+      "--with-filename",
+      "--word-regexp",
+      // The COMPLETE remainder of `rg --help`, added after /code-review round 5
+      // found 40 documented switches in neither set. The table is now the whole
+      // option list: `rg --help` yields 149 long options, 35 of them value-taking.
+      "--ignore",
+      "--ignore-dot",
+      "--ignore-exclude",
+      "--ignore-files",
+      "--ignore-global",
+      "--ignore-messages",
+      "--ignore-parent",
+      "--ignore-vcs",
+      "--messages",
+      "--no-auto-hybrid-regex",
+      "--no-binary",
+      "--no-block-buffered",
+      "--no-byte-offset",
+      "--no-crlf",
+      "--no-fixed-strings",
+      "--no-follow",
+      "--no-glob-case-insensitive",
+      "--no-heading",
+      "--no-hidden",
+      "--no-ignore-file-case-insensitive",
+      "--no-include-zero",
+      "--no-invert-match",
+      "--no-json",
+      "--no-line-buffered",
+      "--no-max-columns-preview",
+      "--no-mmap",
+      "--no-multiline",
+      "--no-multiline-dotall",
+      "--no-one-file-system",
+      "--no-pcre2",
+      "--no-search-zip",
+      "--no-sort-files",
+      "--no-stats",
+      "--no-text",
+      "--no-trim",
+      "--passthrough",
+      "--pcre2-unicode",
+      "--require-git",
+      "--unicode"
+    ]),
+    patternFlags: /* @__PURE__ */ new Set(["-e", "--regexp"]),
+    // `--files` and `--type-list` list or enumerate without a pattern. Founder
+    // decision 2026-09-13: `rg --files ~/.ssh` stays BLOCKED, which this achieves
+    // by leaving the directory in the judged list.
+    noPatternFlags: /* @__PURE__ */ new Set(["-f", "--file", "--files", "--type-list", "--pcre2-version"])
+  }
+};
+var PATTERN_VERB_NAMES = Object.keys(PATTERN_VERBS);
+var patternShapeOf = (verb) => PATTERN_VERBS[verb];
+var fileOperandFlagsOf = (verb) => FILE_OPERAND_FLAGS[verb];
+var GREP_FILE_OPERANDS = /* @__PURE__ */ new Set(["-f", "--file", "--exclude-from", "--include"]);
+var READER_VALUE_LETTERS = {
+  awk: ["F", "v", "f"],
+  gawk: ["F", "v", "f", "e", "E", "i", "l", "o", "p", "D"],
+  sed: ["e", "f", "i", "l"],
+  sort: ["C", "k", "o", "S", "t", "T"]
+};
+var FILE_OPERAND_FLAGS = {
+  grep: GREP_FILE_OPERANDS,
+  egrep: GREP_FILE_OPERANDS,
+  fgrep: GREP_FILE_OPERANDS,
+  // rg and gawk are NOT installed on the measuring machine: these two rows are
+  // from the shipped documentation (ripgrep `-f/--file`, `--ignore-file`; gawk
+  // `-f/--file`) and are marked as such in the spec.
+  // `-g/--glob/--iglob` name which files ripgrep SEARCHES, so an operand naming
+  // a credential makes rg open it -- the same reason grep's `--include` is here.
+  // Measured (/code-review round 3): `rg --hidden -g .env AWS tree` opened .env
+  // and printed its contents.
+  rg: /* @__PURE__ */ new Set(["-f", "--file", "--ignore-file", "-g", "--glob", "--iglob"]),
+  sed: /* @__PURE__ */ new Set(["-f", "--file"]),
+  awk: /* @__PURE__ */ new Set(["-f", "--file"]),
+  gawk: /* @__PURE__ */ new Set(["-f", "--file"]),
+  sort: /* @__PURE__ */ new Set(["--files0-from"])
+};
+var SCP_VALUE_FLAGS = ["i", "F", "o", "c", "S", "P", "J", "D", "W", "l"];
+var TAR_VALUE_LETTERS = ["b", "C", "f", "F", "g", "H", "I", "K", "L", "N", "T", "V", "X"];
+var ZIP_VALUE_LETTERS = ["b", "n", "P", "t", "s", "O", "x", "i"];
+var RSYNC_VALUE_LETTERS = ["e", "f", "T", "B", "M"];
+var RSYNC_SKIP = [
+  "e",
+  "--rsh",
+  "--exclude",
+  "--exclude-from",
+  "--include",
+  "--include-from",
+  "--files-from",
+  "f",
+  "--filter"
+];
+var CP_VALUE_LETTERS = ["S", "t"];
+var INSTALL_VALUE_LETTERS = ["S", "t", "g", "m", "o"];
+var COPY_VERBS = {
+  cp: { source: "allButLast", targetDirFlag: true, valueLetters: CP_VALUE_LETTERS },
+  mv: { source: "allButLast", targetDirFlag: true, valueLetters: CP_VALUE_LETTERS },
+  install: { source: "allButLast", targetDirFlag: true, valueLetters: INSTALL_VALUE_LETTERS },
+  ln: { source: "first", targetDirFlag: true, valueLetters: CP_VALUE_LETTERS },
+  scp: { source: "allButLast", skipFlags: SCP_VALUE_FLAGS, valueLetters: SCP_VALUE_FLAGS },
+  rsync: { source: "allButLast", skipFlags: RSYNC_SKIP, valueLetters: RSYNC_VALUE_LETTERS },
+  tar: {
+    source: "archive",
+    archive: "tar",
+    skipFlags: ["f", "X", "T", "--file", "--exclude", "--exclude-from", "--files-from"],
+    valueLetters: TAR_VALUE_LETTERS
+  },
+  zip: {
+    source: "archive",
+    archive: "zip",
+    skipFlags: ["x", "i", "--exclude", "--include"],
+    valueLetters: ZIP_VALUE_LETTERS
+  },
+  ar: { source: "archive", archive: "ar" },
+  // 7z switches are INLINE only (`-mx9`, `-px`, `-x!pat`), so no following word is
+  // ever a switch's operand -- which is why the short `x` is NOT a skipFlag here
+  // and valueLetters is empty. Keeping the short `x` made `7z a out.7z -mx KEY`
+  // drop the credential as an exclusion operand (/code-review round 8), and the
+  // derived "every skipped letter is a value letter" row in jail-copy.spec.ts is
+  // what keeps the two tables honest about it.
+  "7z": { source: "archive", archive: "7z", skipFlags: ["--exclude"], valueLetters: [] },
+  gzip: { source: "all" },
+  bzip2: { source: "all" },
+  xz: { source: "all" },
+  "docker cp": { source: "allButLast" },
+  "kubectl cp": { source: "allButLast" },
+  "gsutil cp": { source: "allButLast" },
+  "gsutil rsync": { source: "allButLast" },
+  "rclone copy": { source: "allButLast" },
+  "rclone sync": { source: "allButLast" },
+  "aws s3 cp": { source: "allButLast" },
+  "aws s3 mv": { source: "allButLast" },
+  "aws s3 sync": { source: "allButLast" },
+  "gcloud storage cp": { source: "allButLast" },
+  "az storage blob upload": { source: "flagOperand", sourceFlags: ["f", "--file"] }
+};
+var TAR_MODE_WORD = /^[a-zA-Z]+$/;
+var COPY_VERB_HEADS = new Set(Object.keys(COPY_VERBS).map((k) => k.split(" ")[0]));
 var FS_OP_PRESCREEN_RE = new RegExp(
   // A quote is a separator too: `eval "cat X"` and `sh -c 'cat X'` put the
   // reader right after `"` / `'`, and without these two characters the
   // prescreen rejected every string-wrapped read before the parser ran.
   // Found 2026-09-11 by instrumenting the walk -- no CallExpr was ever visited.
-  `(?:^|[\\s|;&("'\`\\n])(?:rm|${[...FS_READ_TOOLS].map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b|(?<!<)<(?!<)`
+  `(?:^|[\\s|;&("'\`\\n/])(?:rm|${[...FS_READ_TOOLS, ...COPY_VERB_HEADS].map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b|(?<!<)<(?!<)`
 );
 var HOME_CACHE_ALLOWLIST = [
   ".cache",
@@ -1752,20 +2167,32 @@ function isProtectedHomePath(rawPath) {
   }
   return true;
 }
-function extractLiteralArgs(callExpr) {
-  const args = callExpr.Args || [];
-  if (args.length === 0) return { name: "", flags: [], paths: [], words: [] };
-  const words = args.map((a) => resolveWordLiteral(a));
-  const name = (words[0] ?? "").toLowerCase();
-  const flags = [];
-  const paths = [];
-  for (let i = 1; i < words.length; i++) {
+function positionedArgs(words, from = 1, to = words.length) {
+  const out = [];
+  let afterFlag = null;
+  for (let i = from; i < to; i++) {
     const v = words[i];
-    if (v === null) continue;
-    if (v.startsWith("-")) flags.push(v);
-    else paths.push(v);
+    if (v === null) {
+      afterFlag = null;
+      continue;
+    }
+    if (v.startsWith("-")) {
+      afterFlag = v;
+      continue;
+    }
+    out.push({ value: v, index: out.length, argv: i, afterFlag });
+    afterFlag = null;
   }
-  return { name, flags, paths, words };
+  return out;
+}
+function extractLiteralArgs(callExpr) {
+  const rawArgs = callExpr.Args || [];
+  if (rawArgs.length === 0) return { name: "", flags: [], paths: [], words: [], args: [] };
+  const words = rawArgs.map((a) => resolveWordLiteral(a));
+  const name = baseWord(words[0]);
+  const flags = words.slice(1).filter((w) => w !== null && w.startsWith("-"));
+  const args = positionedArgs(words);
+  return { name, flags, paths: args.map((a) => a.value), words, args };
 }
 var NET_BINARIES = /* @__PURE__ */ new Set([
   "curl",
@@ -2142,7 +2569,7 @@ function analyzeFsOperationImpl(command, depth = 0) {
         return result?.verdict !== "block";
       }
       if (nodeType !== "CallExpr") return true;
-      const { name, flags, paths, words } = extractLiteralArgs(n);
+      const { name, flags, paths, words, args } = extractLiteralArgs(n);
       if (!name) return true;
       if (name === "rm") {
         const flagStr = flags.join("").toLowerCase();
@@ -2182,13 +2609,16 @@ function analyzeFsOperationImpl(command, depth = 0) {
           return true;
         }
       }
-      const readPaths = FS_READ_TOOLS.has(name) ? paths : wrappedReadPaths(words, name);
+      const readPaths = FS_READ_TOOLS.has(name) ? [...readTargets(name, args, flags, words, 1), ...flagOperandFiles(name, words, 1)] : wrappedReadPaths(words, name);
       if (readPaths) {
         for (const p of readPaths) {
           result = stricter(result, matchSensitivePath2(p));
           if (result?.verdict === "block") return false;
         }
       }
+      for (const p of copySourcePaths(words)) {
+        result = stricter(result, copyVerdictOf(matchSensitivePath2(p)));
+      }
       return true;
     });
     return result;
@@ -2201,6 +2631,208 @@ function stricter(a, b) {
   if (!b) return a;
   return b.verdict === "block" && a.verdict !== "block" ? b : a;
 }
+function flagInfo(w) {
+  if (w.startsWith("--")) {
+    const eq = w.indexOf("=");
+    return eq < 0 ? { letter: null, long: w, attached: null } : { letter: null, long: w.slice(0, eq), attached: w.slice(eq + 1) };
+  }
+  const m = /^-([a-zA-Z]+)(.*)$/.exec(w);
+  if (!m) return { letter: null, long: null, attached: null };
+  return { letter: m[1][m[1].length - 1], long: null, attached: m[2] === "" ? null : m[2] };
+}
+function flagIs(w, names) {
+  if (w === null) return false;
+  const f = flagInfo(w);
+  return names.some((n) => n.startsWith("--") ? f.long === n : f.letter === n);
+}
+function operandOf(a, names, valueLetters) {
+  if (!names || a.afterFlag === null) return false;
+  const w = a.afterFlag;
+  if (!w.startsWith("--") && valueLetters) {
+    const letters = w.slice(1);
+    for (let i = 0; i < letters.length; i++) {
+      if (!valueLetters.includes(letters[i])) continue;
+      return i === letters.length - 1 && names.includes(letters[i]);
+    }
+    return false;
+  }
+  if (w.startsWith("--") && !w.includes("=")) {
+    const longs = names.filter((n) => n.startsWith("--"));
+    if (longs.some((n) => n === w || w.length >= 3 && n.startsWith(w))) return true;
+  }
+  return flagIs(w, names) && flagInfo(w).attached === null;
+}
+function resolveCopyShape(words, h) {
+  const verb = baseWord(words[h]);
+  if (!verb) return null;
+  const direct = COPY_VERBS[verb];
+  if (direct) return { shape: direct, last: h };
+  const slots = positionedArgs(words, h + 1);
+  for (let i = 0; i < slots.length; i++) {
+    for (let n = 3; n >= 1; n--) {
+      const part = slots.slice(i, i + n);
+      if (part.length < n) continue;
+      const key = [verb, ...part.map((a) => a.value.toLowerCase())].join(" ");
+      const shape = COPY_VERBS[key];
+      if (shape) return { shape, last: part[n - 1].argv };
+    }
+    if (slots[i].afterFlag === null) return null;
+  }
+  return null;
+}
+var FIND_OPTIONS = /* @__PURE__ */ new Set(["-H", "-L", "-P"]);
+function findStartPoints(words, h) {
+  const k = words.findIndex((w, i) => i > h && w !== null && FIND_EXEC_FLAGS.has(w));
+  if (k < 0) return { k, starts: [] };
+  const firstPredicate = words.findIndex(
+    (w, i) => i > h && w !== null && w !== "--" && w.startsWith("-") && !FIND_OPTIONS.has(w)
+  );
+  const end = firstPredicate > h ? firstPredicate : k;
+  return { k, starts: positionalAfter(words, h + 1, end) };
+}
+function copySourcePaths(words) {
+  const h = unwrapCommandHead(words);
+  const fi = words.findIndex((w, i) => i <= h && baseWord(w) === "find");
+  if (fi >= 0) {
+    const { k, starts } = findStartPoints(words, fi);
+    if (k < 0) return [];
+    const action = unwrapCommandHead(words.slice(k + 1));
+    return resolveCopyShape(words.slice(k + 1), action) ? starts : [];
+  }
+  if (!COPY_VERB_HEADS.has(baseWord(words[h]))) return [];
+  const r = resolveCopyShape(words, h);
+  if (!r) return [];
+  const { shape, last } = r;
+  const args = positionedArgs(words, last + 1);
+  const tail = words.slice(last + 1);
+  const copyOptionsEnd = tail.findIndex((w) => w === "--");
+  const copyPastOptions = (a) => copyOptionsEnd >= 0 && a.argv > last + 1 + copyOptionsEnd;
+  const skipped = (a) => !copyPastOptions(a) && operandOf(a, shape.skipFlags, shape.valueLetters);
+  const firstValueLetter = (w) => {
+    const letters = w.slice(1);
+    for (let i = 0; i < letters.length; i++) {
+      if ((shape.valueLetters ?? []).includes(letters[i]))
+        return { letter: letters[i], last: i === letters.length - 1 };
+    }
+    return null;
+  };
+  const isTargetDirFlag = (w) => {
+    if (w.startsWith("--")) {
+      const name = w.includes("=") ? w.slice(0, w.indexOf("=")) : w;
+      return name.length >= 3 && "--target-directory".startsWith(name);
+    }
+    return firstValueLetter(w)?.letter === "t";
+  };
+  const targetDir = shape.targetDirFlag === true && tail.some((w) => w !== null && w.startsWith("-") && isTargetDirFlag(w));
+  const targetTakesNextWord = (w) => {
+    if (w.startsWith("--"))
+      return !w.includes("=") && w.length >= 3 && "--target-directory".startsWith(w);
+    const f = firstValueLetter(w);
+    return f !== null && f.letter === "t" && f.last;
+  };
+  const targetOperand = (a) => targetDir && a.afterFlag !== null && !copyPastOptions(a) && targetTakesNextWord(a.afterFlag);
+  const lastOperand = [...tail].reverse().find((w) => w === null || !w.startsWith("-"));
+  const dynamicDest = lastOperand === null;
+  const destIsLastOperand = (shape.source === "allButLast" || shape.source === "first") && !targetDir && !dynamicDest;
+  let src;
+  switch (shape.source) {
+    case "all":
+      src = args;
+      break;
+    case "first":
+      src = targetDir ? args : args.slice(0, 1);
+      break;
+    case "flagOperand": {
+      const namesSource = (f) => {
+        const names = shape.sourceFlags ?? [];
+        if (f.long !== null)
+          return names.some(
+            (n) => n.startsWith("--") && (n === f.long || f.long.length >= 3 && n.startsWith(f.long))
+          );
+        return f.letter !== null && names.includes(f.letter);
+      };
+      const inline = tail.filter((w) => w !== null && w.startsWith("-")).map((w) => flagInfo(w)).filter((f) => f.attached !== null && namesSource(f)).map((f) => f.attached);
+      return [
+        ...args.filter((a) => !copyPastOptions(a) && operandOf(a, shape.sourceFlags, shape.valueLetters)).map((a) => a.value),
+        ...inline
+      ];
+    }
+    case "archive":
+      src = archiveInputs(shape.archive, args, tail);
+      break;
+    case "allButLast":
+      src = targetDir || dynamicDest ? args : args.slice(0, -1);
+      break;
+  }
+  const sources = src.filter((a) => !skipped(a) && !targetOperand(a)).map((a) => a.value);
+  if (destIsLastOperand && typeof lastOperand === "string" && matchSensitivePath2(lastOperand)) {
+    const jailedSources = sources.filter((p) => matchSensitivePath2(p));
+    const dirOf = (p) => /[\\/]/.test(p) ? p.replace(/[\\/][^\\/]*$/, "") : "";
+    if (jailedSources.length === 0) return [];
+    if (jailedSources.every((p) => dirOf(p) === dirOf(lastOperand))) return [];
+  }
+  return sources;
+}
+function archiveInputs(kind, args, tail) {
+  const first = args[0];
+  const bareKey = first && first.afterFlag === null && TAR_MODE_WORD.test(first.value);
+  if (kind === "tar") {
+    const flagsText = tail.filter((w) => w !== null && w.startsWith("-")).join(" ");
+    const mode = (bareKey ? first.value : "") + flagsText;
+    const extracting = /x|t/.test(bareKey ? first.value.replace(/f/g, "") : "") || /(^|\s)-[a-zA-Z]*[xt]|--extract|--list|--get/.test(flagsText);
+    const writing = /[cruA]/.test(bareKey ? first.value : "") || /(^|\s)-[a-zA-Z]*[cruA]|--create|--append|--update|--concatenate/.test(flagsText);
+    if (extracting && !writing) return [];
+    void mode;
+    if (!bareKey) return args;
+    let i = 1;
+    const fromDirs = [];
+    for (const ch of first.value) {
+      if (!TAR_VALUE_LETTERS.includes(ch)) continue;
+      const operand = args[i];
+      if (!operand || operand.afterFlag !== null) break;
+      i += 1;
+      if (ch === "C") fromDirs.push(operand);
+    }
+    return [...fromDirs, ...args.slice(i)];
+  }
+  if (kind === "zip") return first && first.afterFlag === "-" ? args : args.slice(1);
+  if (kind === "ar") return bareKey ? args.slice(2) : args.slice(1);
+  return args.slice(2);
+}
+function sampleCopyCommand(verb, src) {
+  const shape = COPY_VERBS[verb];
+  if (!shape) throw new Error(`not a copy verb: ${verb}`);
+  const remote = /^(scp|rsync|aws |gsutil|gcloud|rclone|docker|kubectl)/.test(verb);
+  switch (shape.source) {
+    case "first":
+      return `${verb} -s ${src} /tmp/n9-link`;
+    case "all":
+      return `${verb} -c ${src} > /tmp/n9-out`;
+    case "flagOperand":
+      return `${verb} -f ${src} -c n9`;
+    case "archive":
+      return shape.archive === "tar" ? `tar czf /tmp/n9-out.tgz ${src}` : shape.archive === "zip" ? `zip -r /tmp/n9-out.zip ${src}` : shape.archive === "ar" ? `ar rc /tmp/n9-out.a ${src}` : `7z a /tmp/n9-out.7z ${src}`;
+    case "allButLast":
+      return `${verb} ${src} ${remote ? verb.startsWith("scp") || verb === "rsync" ? "user@host.invalid:/tmp/" : verb.startsWith("docker") || verb.startsWith("kubectl") ? "ctr:/tmp/" : "remote:/n9/" : "/tmp/n9-copy"}`;
+  }
+}
+var COPY_RULE_OF = {
+  "shield:project-jail:block-read-ssh": "shield:project-jail:review-copy-ssh",
+  "shield:project-jail:block-read-aws": "shield:project-jail:review-copy-aws",
+  "shield:project-jail:block-read-env": "shield:project-jail:review-copy-env",
+  "shield:project-jail:review-read-credentials": "shield:project-jail:review-copy-credentials"
+};
+function copyVerdictOf(hit) {
+  if (!hit) return null;
+  const ruleName = COPY_RULE_OF[hit.ruleName];
+  if (!ruleName) return null;
+  return {
+    ruleName,
+    verdict: "review",
+    reason: `Copying ${hit.path} moves a credential out of its jail (project-jail shield)`,
+    path: hit.path
+  };
+}
 function matchSensitivePath2(p) {
   for (const sp of SENSITIVE_PATH_RULES) {
     if (sp.match(p))
@@ -2208,18 +2840,160 @@ function matchSensitivePath2(p) {
   }
   return null;
 }
-var isReaderWord = (w) => w !== null && FS_READ_TOOLS.has(w.split("/").pop()?.toLowerCase() ?? "");
-var positionalAfter = (words, from, to = words.length) => words.slice(from, to).filter((w) => w !== null && !w.startsWith("-"));
+function baseWord(w) {
+  return (w ?? "").split("/").pop()?.toLowerCase() ?? "";
+}
+var isReaderWord = (w) => w !== null && FS_READ_TOOLS.has(baseWord(w));
+var positionalAfter = (words, from, to = words.length) => positionedArgs(words, from, to).map((a) => a.value);
+function namesFlag(name, candidates, known) {
+  if (candidates.has(name)) return true;
+  if (!name.startsWith("--") || name.length < 3) return false;
+  if (known?.has(name)) return false;
+  for (const c of candidates) if (c.startsWith(name)) return true;
+  return false;
+}
+function knownLongFlags(verb) {
+  const out = /* @__PURE__ */ new Set();
+  const shape = PATTERN_VERBS[verb];
+  if (shape) {
+    for (const set of [shape.takesValue, shape.noValue, shape.patternFlags, shape.noPatternFlags])
+      for (const f of set) if (f.startsWith("--")) out.add(f);
+  }
+  for (const f of FILE_OPERAND_FLAGS[verb] ?? []) if (f.startsWith("--")) out.add(f);
+  return out;
+}
+function flagNamesOf(token, shape) {
+  if (token.startsWith("--")) {
+    const eq = token.indexOf("=");
+    return [eq > 0 ? token.slice(0, eq) : token];
+  }
+  const out = [];
+  for (const c of token.slice(1)) {
+    const name = `-${c}`;
+    out.push(name);
+    if (shape?.takesValue.has(name)) break;
+  }
+  return out;
+}
+var NONE = { kind: "none" };
+var UNKNOWN = { kind: "unknown" };
+function flagEffect(token, shape, known) {
+  if (token === "--") return NONE;
+  if (/^-+$/.test(token)) return UNKNOWN;
+  if (/^-\d+$/.test(token)) return NONE;
+  if (token.startsWith("--")) {
+    if (token.includes("=")) return NONE;
+    const takes = namesFlag(token, shape.takesValue, known);
+    const none = namesFlag(token, shape.noValue, known);
+    if (takes && none) return UNKNOWN;
+    if (takes) return { kind: "takes", flag: token };
+    if (none) return NONE;
+    return UNKNOWN;
+  }
+  const letters = token.slice(1);
+  if (!letters) return NONE;
+  for (let i = 0; i < letters.length; i++) {
+    const name = `-${letters[i]}`;
+    if (shape.takesValue.has(name)) {
+      return i === letters.length - 1 ? { kind: "takes", flag: name } : NONE;
+    }
+    if (!shape.noValue.has(name)) return UNKNOWN;
+  }
+  return NONE;
+}
+function readTargets(verb, args, flags, words = [], from = 1) {
+  const shape = PATTERN_VERBS[verb];
+  if (!shape) return args.map((a) => a.value);
+  const known = knownLongFlags(verb);
+  const names = flags.flatMap((f) => flagNamesOf(f, shape));
+  const patternElsewhere = names.some(
+    (n) => namesFlag(n, shape.patternFlags, known) || namesFlag(n, shape.noPatternFlags, known)
+  );
+  const excused = /* @__PURE__ */ new Set();
+  const fileFlags = FILE_OPERAND_FLAGS[verb];
+  const optionsEnd = words.findIndex((w, i) => i >= from && w === "--");
+  const pastOptions = (a) => optionsEnd >= 0 && a.argv > optionsEnd;
+  for (const a of args) {
+    if (a.afterFlag === null || pastOptions(a)) continue;
+    const e = flagEffect(a.afterFlag, shape, known);
+    if (e.kind !== "takes") continue;
+    if (fileFlags && namesFlag(e.flag, fileFlags, known)) continue;
+    excused.add(a);
+  }
+  const patternArgv = (() => {
+    for (let i = from; i < words.length; i++) {
+      const w = words[i];
+      if (w === null) return -1;
+      if (w === "--") return i + 1;
+      if (w.startsWith("-")) {
+        const e = flagEffect(w, shape, known);
+        if (e.kind === "takes") i += 1;
+        else if (e.kind === "unknown") return -1;
+        continue;
+      }
+      return i;
+    }
+    return -1;
+  })();
+  if (!patternElsewhere && patternArgv >= 0) {
+    const a = args.find((x) => x.argv === patternArgv);
+    if (a) excused.add(a);
+  }
+  return args.filter((a) => !excused.has(a)).map((a) => a.value);
+}
+function flagOperandFiles(verb, words, from) {
+  const flags = FILE_OPERAND_FLAGS[verb];
+  if (!flags) return [];
+  const known = knownLongFlags(verb);
+  const out = [];
+  for (let i = from; i < words.length; i++) {
+    const w = words[i];
+    if (w === null || !w.startsWith("-") || w === "--") continue;
+    if (w.startsWith("--")) {
+      const eq = w.indexOf("=");
+      if (eq <= 0) continue;
+      const name = w.slice(0, eq);
+      const value = w.slice(eq + 1);
+      if (!value) continue;
+      if (namesFlag(name, flags, known)) {
+        out.push(value);
+        continue;
+      }
+      const shape2 = PATTERN_VERBS[verb];
+      if (!shape2) continue;
+      const recognised = namesFlag(name, shape2.takesValue, known) || namesFlag(name, shape2.noValue, known) || namesFlag(name, shape2.patternFlags, known) || namesFlag(name, shape2.noPatternFlags, known);
+      if (!recognised) out.push(value);
+      continue;
+    }
+    const shape = PATTERN_VERBS[verb];
+    const letters = w.slice(1);
+    for (let j = 0; j < letters.length; j++) {
+      const name = `-${letters[j]}`;
+      const isFileFlag = flags.has(name);
+      const argTaking = isFileFlag || (shape?.takesValue.has(name) ?? false) || (READER_VALUE_LETTERS[verb] ?? []).includes(letters[j]);
+      if (!argTaking) continue;
+      const attached = letters.slice(j + 1);
+      if (isFileFlag && attached) out.push(attached);
+      break;
+    }
+  }
+  return out;
+}
 function wrappedReadPaths(words, name) {
   if (name === "find") {
-    const k = words.findIndex((w) => w !== null && FIND_EXEC_FLAGS.has(w));
-    if (k < 1 || !isReaderWord(words[k + 1] ?? null)) return null;
-    const firstPredicate = words.findIndex((w, i) => i > 0 && w !== null && w.startsWith("-"));
-    return positionalAfter(words, 1, firstPredicate > 0 ? firstPredicate : k);
+    const { k, starts } = findStartPoints(words, 0);
+    return k > 0 && isReaderWord(words[k + 1] ?? null) ? starts : null;
   }
   if (!COMMAND_WRAPPERS.has(name) && !RUNNER_WRAPPERS.has(name)) return null;
   const h = unwrapCommandHead(words);
-  return h > 0 && isReaderWord(words[h] ?? null) ? positionalAfter(words, h + 1) : null;
+  if (h <= 0 || !isReaderWord(words[h] ?? null)) return null;
+  const head = baseWord(words[h]);
+  const rest = words.slice(h + 1);
+  const restFlags = rest.filter((w) => w !== null && w.startsWith("-"));
+  return [
+    ...readTargets(head, positionedArgs(words, h + 1), restFlags, words, h + 1),
+    ...flagOperandFiles(head, words, h + 1)
+  ];
 }
 function literalShellPayload(words, name) {
   const h = COMMAND_WRAPPERS.has(name) || RUNNER_WRAPPERS.has(name) ? unwrapCommandHead(words) : 0;
@@ -3103,6 +3877,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
   const shellShaped = isBashTool(toolName) || inspectsShellCommand(toolName, config.policy.toolInspection);
   const shellShapedCommand = shellShaped ? isBashTool(toolName) && args && typeof args === "object" ? typeof args.command === "string" ? args.command : null : extractShellCommand(toolName, args, config.policy.toolInspection) : null;
   const bashCommand = agent !== "Terminal" ? shellShapedCommand : null;
+  let pendingAstReview;
   if (bashCommand !== null) {
     const pipeVerdict = pipeChainVerdict(
       bashCommand,
@@ -3114,7 +3889,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
     if (fsVerdict) {
       const isShieldRule = fsVerdict.ruleName.startsWith("shield:");
       const labelPrefix = isShieldRule ? "project-jail (AST)" : "Node9 (AST)";
-      return {
+      const astVerdict = {
         decision: fsVerdict.verdict,
         blockedByLabel: `${labelPrefix}: ${fsVerdict.ruleName}`,
         reason: fsVerdict.reason,
@@ -3122,6 +3897,8 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
         ruleName: fsVerdict.ruleName,
         ruleDescription: fsVerdict.reason
       };
+      if (fsVerdict.verdict === "block") return astVerdict;
+      pendingAstReview = astVerdict;
     }
     const sqlAction = resolveCheck(config.policy.commandChecks?.sqlDdl);
     const sqlVerdict = sqlAction === "off" ? null : analyzeSqlDestructive(bashCommand);
@@ -3164,7 +3941,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
     const matchedRule = resolvePinned(matches);
     if (matchedRule) {
       if (matchedRule.verdict === "allow")
-        return { decision: "allow", ruleName: matchedRule.name ?? matchedRule.tool };
+        return pendingAstReview ?? { decision: "allow", ruleName: matchedRule.name ?? matchedRule.tool };
       return {
         decision: matchedRule.verdict,
         blockedByLabel: `Smart Rule: ${matchedRule.name ?? matchedRule.tool}`,
@@ -3191,6 +3968,7 @@ async function evaluatePolicy(config, toolName, args, context = {}, hooks = {})
     allTokens = analyzed.allTokens;
     pathTokens = analyzed.paths;
     const candidates = [];
+    if (pendingAstReview) candidates.push(pendingAstReview);
     const evalVerdict = detectDangerousShellExec(shellCommand);
     if (evalVerdict === "block") {
       return {
@@ -4297,6 +5075,12 @@ function classifyRuleSeverity(name, verdict) {
     "read-ssh",
     "read-gcp",
     "read-cred",
+    // Stage 4 (2026-09-11): a copy of a credential file scores like a READ of it --
+    // read-ssh/aws/cred are critical, so copy-ssh/aws/cred are; read-env is high
+    // (below), so copy-env joins the high list, not this one (/code-review).
+    "copy-ssh",
+    "copy-aws",
+    "copy-cred",
     "delete-repo",
     "helm-uninstall",
     "drop-table",
@@ -4309,6 +5093,7 @@ function classifyRuleSeverity(name, verdict) {
   ];
   if (criticalPatterns.some((p) => n.includes(p))) return "critical";
   const highPatterns = [
+    "copy-env",
     "force-push",
     "force_push",
     "git-destructive",
@@ -4326,6 +5111,11 @@ function narrativeRuleLabel(name) {
   const map = {
     "read-aws": "AWS credentials read",
     "read-ssh": "SSH private key read",
+    // Stage 4 copy twins, so `scan --narrative` prints a label, not a raw slug.
+    "copy-ssh": "SSH private key copied out",
+    "copy-aws": "AWS credentials copied out",
+    "copy-env": ".env file copied out",
+    "copy-cred": "credential file copied out",
     "read-gcp": "GCP credentials read",
     "read-cred": "credential file read",
     "delete-repo": "GitHub repository deletion",
@@ -4723,8 +5513,8 @@ function matchCanaryArgs(args, values) {
 
 // src/scan/canonical.ts
 var LONG_OUTPUT_THRESHOLD_BYTES = 100 * 1024;
-var CANONICAL_EXTRACTOR_VERSION = "canonical-v13";
-var CANONICAL_EXTRACTOR_HASH = "4622a2f41696af04";
+var CANONICAL_EXTRACTOR_VERSION = "canonical-v15";
+var CANONICAL_EXTRACTOR_HASH = "5dad4c8f07121f6c";
 var DEDUPE_PREVIEW_LEN = 120;
 function extractCanonicalFindings(call, ctx) {
   const out = [];
@@ -5100,6 +5890,7 @@ export {
   CANONICAL_EXTRACTOR_HASH,
   CANONICAL_EXTRACTOR_VERSION,
   COMMAND_WRAPPERS,
+  COPY_VERBS,
   COST_PER_LOOP_ITER_USD,
   DEFAULT_EGRESS_ALLOWLIST,
   DESTINATION_ARGS,
@@ -5114,6 +5905,7 @@ export {
   LOOP_MAX_RECORDS,
   LOOP_THRESHOLD_FOR_WASTE,
   NET_BINARIES,
+  PATTERN_VERB_NAMES,
   PRIVILEGE_ESCALATION_RE,
   REALTIME_PII_PATTERNS,
   SCAN_SIGNAL_WEIGHTS,
@@ -5150,6 +5942,7 @@ export {
   extractSessionLevelFindings,
   extractShellDestTokens,
   extractShellDestinations,
+  fileOperandFlagsOf,
   getCompiledRegex,
   getNestedValue,
   hostMatches,
@@ -5169,9 +5962,12 @@ export {
   normalizeIpLiteral,
   parseAllSshHostsFromCommand,
   parseDestHost,
+  patternShapeOf,
+  positionedArgs,
   previewArgs,
   redactText,
   resolvePinned,
+  sampleCopyCommand,
   scanArgs,
   scanInjection,
   scanText,