@gotgenes/pi-permission-system 27.0.0 → 27.1.0

package/src/access-intent/bash/bash-path-resolver.ts

@@ -14,7 +14,13 @@ import {
   collectPathCandidateTokens,
   collectRedirectTokens,
   extractCommandName,
+  type PathToken,
 } from "#src/access-intent/bash/token-collection";
+import {
+  mergeTokenEffects,
+  type TokenEffect,
+  UNPROVEN_EFFECT,
+} from "#src/access-intent/effect";
 import { normalizePathPolicyLiteral } from "#src/access-intent/path-normalization";
 import type { PathNormalizer } from "#src/path-normalizer";
 import { isSafeSystemPath } from "#src/safe-system-paths";
@@ -37,11 +43,19 @@ type EffectiveBase =
 
 /**
  * A path-candidate token paired with the effective working directory projected
- * onto the point in the command stream where it appears.
+ * onto the point in the command stream where it appears, and the effect its
+ * position proved.
  */
 interface PathCandidate {
   readonly token: string;
   readonly base: EffectiveBase;
+  readonly effect: TokenEffect;
+}
+
+/** A promoted bare token and its resolved path, before an effect is attached. */
+interface ProbedToken {
+  readonly token: string;
+  readonly path: AccessPath;
 }
 
 // ── Public output types ──────────────────────────────────────────────────────
@@ -51,6 +65,14 @@ export interface BashPathRuleCandidate {
   readonly token: string;
   /** The path's lexical and canonical forms for permission policy matching. */
   readonly path: AccessPath;
+  /** The attributed effect that routes the token to a directional surface. */
+  readonly effect: TokenEffect;
+}
+
+/** A path resolving outside the working directory, with its attributed effect. */
+export interface BashExternalPath {
+  readonly path: AccessPath;
+  readonly effect: TokenEffect;
 }
 
 /**
@@ -58,8 +80,8 @@ export interface BashPathRuleCandidate {
  * directory and platform — the two typed slices {@link BashProgram} exposes.
  */
 export interface ResolvedBashPaths {
-  /** Deduplicated paths resolving outside the working directory (#418). */
-  readonly externalPaths: readonly AccessPath[];
+  /** Deduplicated accesses resolving outside the working directory (#418). */
+  readonly externalAccesses: readonly BashExternalPath[];
   /** Every path-rule token paired with its cd-aware policy values (#393). */
   readonly ruleCandidates: readonly BashPathRuleCandidate[];
 }
@@ -116,7 +138,7 @@ export class BashPathResolver {
         : this.deriveBaseFromCdTarget(CWD_BASE, this.workdir);
     const candidates = this.collectPathCandidates(rootNode, initialBase);
     return {
-      externalPaths: this.withWorkdirExternal(
+      externalAccesses: this.withWorkdirExternal(
         this.projectExternalPaths(candidates),
       ),
       ruleCandidates: this.projectRuleCandidates(candidates),
@@ -128,10 +150,15 @@ export class BashPathResolver {
    * resolves outside the cwd. A real `cd /etc` flags `/etc` via its argument
    * token; the seeded base carries no such token, so it is added explicitly and
    * deduplicated against the command's own external tokens (#574).
+   *
+   * It carries {@link UNPROVEN_EFFECT}: no command word was observed for it and
+   * no redirect proved it. When the command's own tokens already named it, the
+   * token's attribution stands — an implicit base is not evidence against a
+   * proof.
    */
   private withWorkdirExternal(
-    tokenExternals: readonly AccessPath[],
-  ): AccessPath[] {
+    tokenExternals: readonly BashExternalPath[],
+  ): BashExternalPath[] {
     if (this.workdir === undefined) return [...tokenExternals];
     const wdPath = this.normalizer.forBashToken(this.workdir);
     const canonical = wdPath.boundaryValue();
@@ -141,9 +168,11 @@ export class BashPathResolver {
     if (!isExternal) return [...tokenExternals];
     const key = canonical || wdPath.value();
     const alreadyPresent = tokenExternals.some(
-      (p) => (p.boundaryValue() || p.value()) === key,
+      ({ path }) => (path.boundaryValue() || path.value()) === key,
     );
-    return alreadyPresent ? [...tokenExternals] : [wdPath, ...tokenExternals];
+    return alreadyPresent
+      ? [...tokenExternals]
+      : [{ path: wdPath, effect: UNPROVEN_EFFECT }, ...tokenExternals];
   }
 
   // ── AST walk — collect PathCandidates ──────────────────────────────────
@@ -414,18 +443,20 @@ export class BashPathResolver {
    */
   private projectExternalPaths(
     candidates: readonly PathCandidate[],
-  ): AccessPath[] {
-    const seen = new Set<string>();
-    const externalPaths: AccessPath[] = [];
+  ): BashExternalPath[] {
+    const seen = new Map<string, number>();
+    const externalPaths: BashExternalPath[] = [];
 
-    for (const { token, base } of candidates) {
+    for (const { token, base, effect } of candidates) {
       const candidate = classifyTokenAsPathCandidate(token);
       if (!candidate) {
         // A bare token the strict shape gate rejects can still escape the tree
         // through a symlink, so probe it and apply the ordinary boundary
         // decision to whatever it resolves to (#645).
         const probed = this.probeBareToken(token, base);
-        if (probed) this.collectIfExternal(probed.path, seen, externalPaths);
+        if (probed) {
+          this.collectIfExternal(probed.path, effect, seen, externalPaths);
+        }
         continue;
       }
 
@@ -436,9 +467,8 @@ export class BashPathResolver {
       if (base.kind === "unknown" && this.isRelativeCandidate(candidate)) {
         const accessPath = this.normalizer.forPath(candidate);
         const canonical = accessPath.boundaryValue();
-        if (canonical && !isSafeSystemPath(canonical) && !seen.has(canonical)) {
-          seen.add(canonical);
-          externalPaths.push(accessPath);
+        if (canonical && !isSafeSystemPath(canonical)) {
+          recordExternal(accessPath, effect, canonical, seen, externalPaths);
         }
         continue;
       }
@@ -449,6 +479,7 @@ export class BashPathResolver {
           : undefined;
       this.collectIfExternal(
         this.normalizer.forBashToken(candidate, { resolveBase }),
+        effect,
         seen,
         externalPaths,
       );
@@ -475,8 +506,9 @@ export class BashPathResolver {
    */
   private collectIfExternal(
     accessPath: AccessPath,
-    seen: Set<string>,
-    out: AccessPath[],
+    effect: TokenEffect,
+    seen: Map<string, number>,
+    out: BashExternalPath[],
   ): void {
     const lexical = accessPath.value();
     if (!lexical) return;
@@ -484,11 +516,8 @@ export class BashPathResolver {
     const isExternal = canonical
       ? this.normalizer.isBoundaryOutsideWorkingDirectory(canonical)
       : true;
-    const dedupKey = canonical || lexical;
-    if (isExternal && !seen.has(dedupKey)) {
-      seen.add(dedupKey);
-      out.push(accessPath);
-    }
+    if (!isExternal) return;
+    recordExternal(accessPath, effect, canonical || lexical, seen, out);
   }
 
   /**
@@ -511,27 +540,38 @@ export class BashPathResolver {
   private projectRuleCandidates(
     candidates: readonly PathCandidate[],
   ): BashPathRuleCandidate[] {
-    const seen = new Set<string>();
+    const seen = new Map<string, number>();
     const result: BashPathRuleCandidate[] = [];
 
-    for (const { token, base } of candidates) {
+    for (const { token, base, effect } of candidates) {
       const shaped = classifyTokenAsRuleCandidate(
         token,
         this.normalizer.flavor,
       );
-      const candidate =
+      const probed =
         shaped === null
           ? this.probeBareToken(token, base)
           : { token: shaped, path: this.buildRuleCandidatePath(shaped, base) };
-      if (!candidate) continue;
+      if (!probed) continue;
 
-      const matchValues = candidate.path.matchValues();
+      const matchValues = probed.path.matchValues();
       if (matchValues.length === 0) continue;
 
       const key = matchValues.join("\0");
-      if (seen.has(key)) continue;
-      seen.add(key);
-      result.push(candidate);
+      const index = seen.get(key);
+      if (index !== undefined) {
+        // The same resolved path, reached again with its own attribution: fold
+        // rather than split, so `cat ~/a > ~/a` stays one entry in the prompt's
+        // evidence and two disagreeing proofs land on the bare family.
+        const existing = result[index];
+        result[index] = {
+          ...existing,
+          effect: mergeTokenEffects(existing.effect, effect),
+        };
+        continue;
+      }
+      seen.set(key, result.length);
+      result.push({ ...probed, effect });
     }
 
     return result;
@@ -558,7 +598,7 @@ export class BashPathResolver {
   private probeBareToken(
     token: string,
     base: EffectiveBase,
-  ): BashPathRuleCandidate | null {
+  ): ProbedToken | null {
     const bare = classifyBareTokenCandidate(token);
     if (bare === null) return null;
     if (base.kind !== "known") return null;
@@ -618,11 +658,41 @@ function isBackgrounded(seqNode: TSNode, index: number): boolean {
 }
 
 function tagTokens(
-  tokens: readonly string[],
+  tokens: readonly PathToken[],
   base: EffectiveBase,
   out: PathCandidate[],
 ): void {
-  for (const token of tokens) out.push({ token, base });
+  for (const { token, effect } of tokens) out.push({ token, base, effect });
+}
+
+/**
+ * Record an external access under `dedupKey`, merging into the entry already
+ * there rather than adding a second one.
+ *
+ * Keeping the effect out of the dedup key is deliberate: `cat ~/a > ~/a` is one
+ * path, and splitting it would show `~/a` twice in the ask prompt. Two
+ * disagreeing proofs fold to unproven, which routes to the bare family —
+ * precisely "consult both" — so the fold loses nothing the gates would have
+ * used.
+ */
+function recordExternal(
+  accessPath: AccessPath,
+  effect: TokenEffect,
+  dedupKey: string,
+  seen: Map<string, number>,
+  out: BashExternalPath[],
+): void {
+  const index = seen.get(dedupKey);
+  if (index === undefined) {
+    seen.set(dedupKey, out.length);
+    out.push({ path: accessPath, effect });
+    return;
+  }
+  const existing = out[index];
+  out[index] = {
+    path: existing.path,
+    effect: mergeTokenEffects(existing.effect, effect),
+  };
 }
 
 /**

package/src/access-intent/bash/command-effects.ts

@@ -0,0 +1,305 @@
+import { type TokenEffect, UNPROVEN_EFFECT } from "#src/access-intent/effect";
+
+// ── Public surface ─────────────────────────────────────────────────────────
+
+/**
+ * The effect a command's head word proves for the path tokens that command
+ * owns, from the built-in pure-reader core (ADR 0013 §7).
+ *
+ * A word is core only as a **bare basename**: `./grep` and `/tmp/evil/grep`
+ * prove nothing, because a path-qualified head word names a program the core's
+ * audit never saw. Rejecting on the separator characters directly — rather
+ * than asking a `PathFlavor` — keeps the rule fail-closed on both platforms
+ * without reading the host's path language.
+ *
+ * A guarded word's claim is withdrawn when an argument names one of its
+ * write-capable options, yielding `retracted` rather than a write: the command
+ * may still only read, so the fail-closed base case is the honest answer and
+ * `retracted` is the blame line that says why.
+ *
+ * Pure and word-based by design — the AST walk that produces the words lives
+ * in `token-collection.ts`, the same split `wrapper-analysis.ts` documents.
+ */
+export function proveCommandEffect(
+  headWord: string,
+  argWords: readonly string[],
+): TokenEffect {
+  if (!isBareCoreWord(headWord)) return UNPROVEN_EFFECT;
+  const guard = RETRACTION_GUARDS.get(headWord);
+  if (guard && argWords.some((word) => retractsClaim(word, guard))) {
+    return RETRACTED_EFFECT;
+  }
+  return CORE_READ_EFFECT;
+}
+
+/**
+ * The frozen v1 pure-reader core: 21 command words that are read-only for any
+ * arguments, in any implementation.
+ *
+ * Exported so `docs/configuration.md`'s published roster is held to it by a
+ * parity test — a listed roster drifts from the code otherwise.
+ */
+export const PURE_READER_CORE: ReadonlySet<string> = new Set(
+  coreAdmissions().flatMap(({ words }) => words),
+);
+
+/**
+ * The effect a redirect operator proves for its destination token, or `null`
+ * when the redirect names no file at all and no token should be collected.
+ *
+ * The operator is the whole proof: `> out.txt` writes `out.txt` whatever the
+ * command in front of it does, and `< in.txt` reads it. A syntax proof is
+ * therefore absolute — it is applied to the destination after the owning
+ * command's attribution and is never retracted by it.
+ *
+ * `>&` and `<&` are the two operators that may name either a file descriptor
+ * (`2>&1`, a duplication that touches no file) or a real file (`cmd >& out`).
+ * `destinationIsDescriptor` is the parse-tree fact that tells them apart; the
+ * `null` it produces is what keeps `2>&1`'s `1` out of the path surface.
+ *
+ * An operator outside the table proves nothing rather than dropping the token:
+ * dropping it would remove a path from the gates entirely, which is the one
+ * fail-open direction available here.
+ */
+export function redirectDestinationEffect(
+  operator: string,
+  destinationIsDescriptor: boolean,
+): TokenEffect | null {
+  if (DESCRIPTOR_CAPABLE_OPERATORS.has(operator)) {
+    if (destinationIsDescriptor) return null;
+    return operator === ">&" ? SYNTAX_WRITE_EFFECT : SYNTAX_READ_EFFECT;
+  }
+  if (OUTPUT_REDIRECT_OPERATORS.has(operator)) return SYNTAX_WRITE_EFFECT;
+  if (INPUT_REDIRECT_OPERATORS.has(operator)) return SYNTAX_READ_EFFECT;
+  return UNPROVEN_EFFECT;
+}
+
+// ── The redirect operator table ────────────────────────────────────────────
+
+/** Operators whose destination the shell truncates, appends to, or creates. */
+const OUTPUT_REDIRECT_OPERATORS: ReadonlySet<string> = new Set([
+  ">",
+  ">>",
+  ">|",
+  "&>",
+  "&>>",
+]);
+
+/**
+ * Operators whose destination the shell reads.
+ *
+ * `<<<` is a herestring, whose `herestring_redirect` node carries the same
+ * shape; its destination is a literal rather than a file in practice, and
+ * reading it proves no more than a read either way.
+ */
+const INPUT_REDIRECT_OPERATORS: ReadonlySet<string> = new Set(["<", "<<<"]);
+
+/** The two operators that may duplicate a descriptor instead of naming a file. */
+const DESCRIPTOR_CAPABLE_OPERATORS: ReadonlySet<string> = new Set([">&", "<&"]);
+
+// ── The roster ─────────────────────────────────────────────────────────────
+
+/** A group of core words admitted for one shared structural reason. */
+interface CoreAdmission {
+  readonly words: readonly string[];
+  /** Why the group clears the bar — the audit, kept beside what it admits. */
+  readonly reason: string;
+}
+
+/**
+ * The roster, grouped by admission reason.
+ *
+ * The bar is **structural**, never popularity: implementation-independent
+ * read-only-ness across GNU and BSD alike, no option that redirects output to
+ * a file, and effects stable under argument content. A word that fails any of
+ * the three is excluded even when it is overwhelmingly used to read.
+ *
+ * Deliberately excluded, so the audit is auditable:
+ *
+ * | Word                                            | Why not                                                        |
+ * | ----------------------------------------------- | -------------------------------------------------------------- |
+ * | `awk`, `gawk`, `nawk`                           | The program text can `print > "file"` — not stable under args  |
+ * | `sed`                                           | `-i` is in-place, and BSD needs a separate argument where GNU attaches one, so the guard is dialect-variant |
+ * | `uniq`                                          | `uniq IN OUT` writes its second positional                     |
+ * | `tee`, `dd`, `split`, `csplit`, `xxd`, `tree`, `curl`, `wget` | Each has a positional or option that writes a file |
+ * | `less`, `more`                                  | Interactive shell escape (`!cmd`) and `LESSOPEN` preprocessing |
+ * | `file`                                          | `-C`/`--compile` writes a `magic.mgc` file — it reports on its arguments, but not only |
+ * | `git`, `pnpm`, `npm`, `node`, `python3`, `gh`   | Subcommand- and argument-dependent — the `commandEffects` long tail |
+ *
+ * Widening the roster only ever loosens, so evidence can add a word as a
+ * non-breaking change; a wrong admission is a fail-open, which is why the bar
+ * is stated rather than assumed.
+ */
+function coreAdmissions(): readonly CoreAdmission[] {
+  return [
+    {
+      words: ["cat", "head", "tail", "wc", "grep", "egrep", "fgrep", "rg"],
+      reason:
+        "Content readers: no output-file option in any surveyed dialect; output is stdout only",
+    },
+    {
+      words: ["diff"],
+      reason: "Writes nothing; `-D` emits merged output to stdout",
+    },
+    {
+      words: ["ls", "stat", "pwd"],
+      reason: "Metadata and listing: report only",
+    },
+    {
+      words: ["basename", "dirname", "realpath"],
+      reason:
+        "Path-string transforms: `realpath` reads the filesystem and writes nothing; the other two touch it at all only to resolve",
+    },
+    {
+      words: ["echo", "which", "cd"],
+      reason:
+        "No filesystem write: `echo` writes to stdout (a redirect destination is the syntax proof's job, not `echo`'s); `cd` reads a directory to enter it",
+    },
+    {
+      words: ["find", "fd", "sort"],
+      reason:
+        "Read-only until an argument says otherwise — see RETRACTION_GUARDS",
+    },
+  ];
+}
+
+// ── The retraction guards ──────────────────────────────────────────────────
+
+/**
+ * The option forms that withdraw a guarded word's read claim.
+ *
+ * Matching is fail-closed over the forms ADR 0013 §7 names: a long stem
+ * matches bare, with an attached `=value`, or as any prefix of itself, and a
+ * short letter matches anywhere in a single-dash cluster, which covers the
+ * attached-value form (`-oFILE`) too. Over-retraction costs one ask;
+ * under-retraction misses a write.
+ *
+ * The prefix rule exists because GNU `getopt_long` accepts any unambiguous
+ * abbreviation, so `sort --out=/tmp/x` reaches the same code `--output` does.
+ * Matching every prefix also retracts on an abbreviation the real program
+ * would reject as ambiguous — the affordable direction.
+ */
+interface RetractionGuard {
+  /** Whole argument words, for options that neither cluster nor take `=`. */
+  readonly exactWords?: ReadonlySet<string>;
+  /** Long stems, matched bare (`--output`) or attached (`--output=/tmp/x`). */
+  readonly longStems?: ReadonlySet<string>;
+  /** Short letters, matched anywhere in a single-dash cluster (`-uo`). */
+  readonly shortLetters?: ReadonlySet<string>;
+}
+
+/**
+ * The three guarded words and what withdraws each one's claim.
+ *
+ * All three were chosen because their write options spell identically in GNU
+ * and BSD — which is exactly why `sed` is excluded outright rather than
+ * guarded. `find`'s options are single-dash long words that never cluster, so
+ * they match as exact words; `sort`'s only short option containing `o` is `-o`
+ * itself, so the cluster rule cannot over-retract there.
+ */
+const RETRACTION_GUARDS: ReadonlyMap<string, RetractionGuard> = new Map([
+  [
+    "find",
+    {
+      exactWords: new Set([
+        "-exec",
+        "-execdir",
+        "-ok",
+        "-okdir",
+        "-delete",
+        "-fprint",
+        "-fprint0",
+        "-fprintf",
+        "-fls",
+      ]),
+    },
+  ],
+  [
+    "fd",
+    {
+      longStems: new Set(["--exec", "--exec-batch"]),
+      shortLetters: new Set(["x", "X"]),
+    },
+  ],
+  [
+    "sort",
+    {
+      longStems: new Set(["--output"]),
+      shortLetters: new Set(["o"]),
+    },
+  ],
+]);
+
+// ── Private helpers ────────────────────────────────────────────────────────
+
+/** A core word's proven attribution. */
+const CORE_READ_EFFECT: TokenEffect = { effect: "read", source: "core" };
+
+/** A guarded word whose claim an argument withdrew (ADR 0013 §7's blame line). */
+const RETRACTED_EFFECT: TokenEffect = {
+  effect: "unproven",
+  source: "retracted",
+};
+
+/** A redirect destination the operator proves the shell reads. */
+const SYNTAX_READ_EFFECT: TokenEffect = { effect: "read", source: "syntax" };
+
+/** A redirect destination the operator proves the shell writes. */
+const SYNTAX_WRITE_EFFECT: TokenEffect = { effect: "write", source: "syntax" };
+
+/** The path separators that disqualify a head word from the core, both flavors. */
+const PATH_SEPARATORS = ["/", "\\"];
+
+function isBareCoreWord(headWord: string): boolean {
+  if (PATH_SEPARATORS.some((separator) => headWord.includes(separator))) {
+    return false;
+  }
+  return PURE_READER_CORE.has(headWord);
+}
+
+function retractsClaim(word: string, guard: RetractionGuard): boolean {
+  if (guard.exactWords?.has(word)) return true;
+  if (matchesLongStem(word, guard.longStems)) return true;
+  return matchesShortCluster(word, guard.shortLetters);
+}
+
+/**
+ * A long option, bare, carrying its value inline, or abbreviated.
+ *
+ * The name is taken before the first `=`, so `--out=/tmp/x` is tested as
+ * `--out` — an abbreviation of `--output` that GNU `getopt_long` resolves to
+ * it. A bare `--` abbreviates nothing.
+ */
+function matchesLongStem(
+  word: string,
+  stems: ReadonlySet<string> | undefined,
+): boolean {
+  if (!stems) return false;
+  const name = word.split("=")[0];
+  if (!name.startsWith("--") || name.length <= 2) return false;
+  for (const stem of stems) {
+    if (stem.startsWith(name)) return true;
+  }
+  return false;
+}
+
+/**
+ * A guarded letter anywhere in a single-dash cluster.
+ *
+ * The scan runs past the letters into an attached value, which is what makes
+ * `-oFILE` retract as surely as `-o FILE` does.
+ */
+function matchesShortCluster(
+  word: string,
+  letters: ReadonlySet<string> | undefined,
+): boolean {
+  if (!letters) return false;
+  if (!word.startsWith("-") || word.startsWith("--") || word.length < 2) {
+    return false;
+  }
+  const cluster = word.slice(1);
+  for (const letter of letters) {
+    if (cluster.includes(letter)) return true;
+  }
+  return false;
+}