@gotgenes/pi-permission-system 27.0.1 → 27.1.1

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

@@ -3,13 +3,15 @@ import {
   forEachNestedExecution,
 } from "#src/access-intent/bash/nested-execution";
 import type { TSNode } from "#src/access-intent/bash/parser";
+import { redirectMayWriteFile } from "#src/access-intent/bash/redirect-analysis";
 import {
   type CommandWord,
   classifyWrapperWords,
   executedUnitOf,
+  isTransparentWrapper,
   type WrapperKind,
 } from "#src/access-intent/bash/wrapper-analysis";
-import type { BashCommandContext } from "#src/types";
+import type { BashCommandContext, FloorExemption } from "#src/types";
 
 export type { WrapperKind } from "#src/access-intent/bash/wrapper-analysis";
 
@@ -37,25 +39,55 @@ export interface BashCommand {
    */
   readonly wrapperKind?: WrapperKind;
   /**
-   * The command this wrapper unit actually runs (#713). Display-only — it is
-   * never gated on its own, so the wrapper floor still applies. Absent for an
-   * ordinary command, and for a wrapper whose inner command cannot be
-   * established.
+   * The command this wrapper unit actually runs (#713). Absent for an ordinary
+   * command, and for a wrapper whose inner command cannot be established.
+   *
+   * Display-only, and deliberately looks past an `sh -c` layer the gate must
+   * not look past — {@link floorExemption} is the gateable answer, established
+   * by its own walk rather than read off this string (#803).
    */
   readonly executedUnit?: string;
+  /**
+   * Set when this wrapper unit's floor has no reason left to hold, naming the
+   * reason (#803). Only ever present alongside `wrapperKind: "indirection"`
+   * and an established {@link executedUnit}.
+   */
+  readonly floorExemption?: FloorExemption;
+}
+
+/**
+ * What the statement enclosing a command unit establishes about it.
+ *
+ * Both facts flow down the walk together because both are the *statement's*,
+ * not the command's: a subshell's commands run in a subshell however they are
+ * spelled, and a redirected statement writes a file however read-only the
+ * command in front of the operator is.
+ */
+interface UnitScope {
+  /**
+   * Execution context for a nested command (substitution or subshell); absent
+   * for a current-shell (top-level) command.
+   */
+  readonly context?: BashCommandContext;
+  /**
+   * True when the enclosing statement redirects output into a real file, which
+   * withholds the floor exemption from any wrapper unit beneath it.
+   */
+  readonly writesViaRedirect: boolean;
 }
 
+/** A top-level command in the current shell, writing no file. */
+const TOP_LEVEL_SCOPE: UnitScope = { writesViaRedirect: false };
+
 // ── Command enumeration ──────────────────────────────────────────────────────
 
 /**
- * Container node types descended into when enumerating command units.
+ * Container node types descended into with the enclosing scope unchanged.
+ *
+ * `redirected_statement` is descended too, but has its own branch: it is the
+ * node that can establish a write, so it descends with a scope of its own.
  */
-const COMMAND_ENUM_DESCEND = new Set([
-  "program",
-  "list",
-  "pipeline",
-  "redirected_statement",
-]);
+const COMMAND_ENUM_DESCEND = new Set(["program", "list", "pipeline"]);
 
 /**
  * Named node types abandoned during command enumeration: they are neither
@@ -95,13 +127,13 @@ const COMMAND_ENUM_SKIP = new Set(["comment", "heredoc_end"]);
  */
 export function collectCommands(node: TSNode): BashCommand[] {
   const out: BashCommand[] = [];
-  collectCommandsInto(node, undefined, out);
+  collectCommandsInto(node, TOP_LEVEL_SCOPE, out);
   return out;
 }
 
 function collectCommandsInto(
   node: TSNode,
-  context: BashCommandContext | undefined,
+  scope: UnitScope,
   out: BashCommand[],
 ): void {
   // Anonymous tokens (operators `&&`/`;`/`|`, delimiters `$(`/`)`/`` ` ``/`(`)
@@ -110,13 +142,18 @@ function collectCommandsInto(
   if (COMMAND_ENUM_SKIP.has(node.type)) return;
 
   if (node.type === "command") {
-    out.push(makeCommandUnit(node, context));
+    out.push(makeCommandUnit(node, scope));
     // A command's text already contains any substitution; descend its subtree
     // to ALSO emit the inner commands of command/process substitutions.
     collectHostedCommands(node, out);
     return;
   }
 
+  if (node.type === "redirected_statement") {
+    descendCommandChildren(node, redirectedScope(node, scope), out);
+    return;
+  }
+
   if (EXECUTION_HOST_TYPES.has(node.type)) {
     // Not a command itself, but its subtree can host one that really runs
     // (`> $(rm x)`, `< <(rm c)`). Emit only what it hosts (#741).
@@ -125,48 +162,80 @@ function collectCommandsInto(
   }
 
   if (node.type === "subshell") {
-    out.push(makeUnit(node.text, context)); // never-weaker whole emit
-    descendCommandChildren(node, "subshell", out);
+    out.push(makeUnit(node.text, scope)); // never-weaker whole emit
+    descendCommandChildren(node, { ...scope, context: "subshell" }, out);
     return;
   }
 
   if (COMMAND_ENUM_DESCEND.has(node.type)) {
-    descendCommandChildren(node, context, out);
+    descendCommandChildren(node, scope, out);
     return;
   }
 
   // Any other named statement (compound_statement `{ … }`, if/while/for/case,
   // function_definition): emit whole, do not descend — deferred (#306).
-  out.push(makeUnit(node.text, context));
+  out.push(makeUnit(node.text, scope));
+}
+
+/** The wrapper facts a `command` node's words establish about its unit. */
+interface WrapperFacts {
+  readonly wrapperKind?: WrapperKind;
+  readonly executedUnit?: string;
+  readonly floorExemption?: FloorExemption;
 }
 
 function makeUnit(
   text: string,
-  context: BashCommandContext | undefined,
-  wrapperKind?: WrapperKind,
-  executedUnit?: string,
+  scope: UnitScope,
+  wrapper: WrapperFacts = {},
 ): BashCommand {
-  const unit: BashCommand = context ? { text, context } : { text };
-  const flagged = wrapperKind ? { ...unit, wrapperKind } : unit;
-  return executedUnit === undefined ? flagged : { ...flagged, executedUnit };
+  const { wrapperKind, executedUnit, floorExemption } = wrapper;
+  const scoped: BashCommand = scope.context
+    ? { text, context: scope.context }
+    : { text };
+  const flagged = wrapperKind ? { ...scoped, wrapperKind } : scoped;
+  const named =
+    executedUnit === undefined ? flagged : { ...flagged, executedUnit };
+  return floorExemption === undefined ? named : { ...named, floorExemption };
 }
 
 /**
- * Build the unit for a `command` node, reading its words once to answer both
- * wrapper questions: whether the unit is floored, and what it actually runs.
+ * Build the unit for a `command` node, reading its words once to answer all
+ * three wrapper questions: whether the unit is floored, what it actually runs,
+ * and whether the floor still has a reason to hold.
  */
-function makeCommandUnit(
-  node: TSNode,
-  context: BashCommandContext | undefined,
-): BashCommand {
+function makeCommandUnit(node: TSNode, scope: UnitScope): BashCommand {
   const text = commandUnitText(node);
   const words = readCommandWords(node);
-  return makeUnit(
-    text,
-    context,
-    classifyWrapperWords(words),
-    executedUnitOf(text, words) ?? undefined,
-  );
+  return makeUnit(text, scope, {
+    wrapperKind: classifyWrapperWords(words),
+    executedUnit: executedUnitOf(text, words) ?? undefined,
+    floorExemption: isTransparentWrapper(words, scope)
+      ? "core-reader"
+      : undefined,
+  });
+}
+
+/**
+ * The scope a `redirected_statement`'s children run under: the enclosing one,
+ * plus a write unless every one of its redirects provably only reads.
+ *
+ * The redirect belongs to the last element of a pipeline, but it hangs off the
+ * whole statement in the parse tree, so every command beneath it is marked.
+ * Over-attributing is the fail-closed direction — the flag can only withhold an
+ * exemption, never grant one — which is also why the question asked of each
+ * redirect is a refusal rather than a proof.
+ */
+function redirectedScope(node: TSNode, scope: UnitScope): UnitScope {
+  if (scope.writesViaRedirect) return scope;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child?.type !== "file_redirect") continue;
+    if (redirectMayWriteFile(child)) {
+      return { ...scope, writesViaRedirect: true };
+    }
+  }
+  return scope;
 }
 
 /**
@@ -213,12 +282,12 @@ function commandUnitText(node: TSNode): string {
 
 function descendCommandChildren(
   node: TSNode,
-  context: BashCommandContext | undefined,
+  scope: UnitScope,
   out: BashCommand[],
 ): void {
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (child) collectCommandsInto(child, context, out);
+    if (child) collectCommandsInto(child, scope, out);
   }
 }
 
@@ -232,6 +301,13 @@ function descendCommandChildren(
  */
 function collectHostedCommands(node: TSNode, out: BashCommand[]): void {
   forEachNestedExecution(node, (contextNode, context) => {
-    descendCommandChildren(contextNode, context, out);
+    // A nested execution starts fresh: an enclosing statement's redirect is
+    // that statement's, not the substitution's, exactly as #807 attributes a
+    // nested command's path tokens to its own command.
+    descendCommandChildren(
+      contextNode,
+      { context, writesViaRedirect: false },
+      out,
+    );
   });
 }

package/src/access-intent/bash/program.ts

@@ -1,5 +1,5 @@
-import type { AccessPath } from "#src/access-intent/access-path";
 import {
+  type BashExternalPath,
   BashPathResolver,
   type BashPathRuleCandidate,
 } from "#src/access-intent/bash/bash-path-resolver";
@@ -10,7 +10,7 @@ import {
 import { getParser } from "#src/access-intent/bash/parser";
 import type { PathNormalizer } from "#src/path-normalizer";
 
-export type { BashCommand, BashPathRuleCandidate };
+export type { BashCommand, BashExternalPath, BashPathRuleCandidate };
 
 /**
  * A bash command parsed once into a born-ready representation.
@@ -26,7 +26,7 @@ export class BashProgram {
   private constructor(
     private readonly sourceCommand: string,
     private readonly commandUnits: readonly BashCommand[],
-    private readonly resolvedExternalPaths: readonly AccessPath[],
+    private readonly resolvedExternalAccesses: readonly BashExternalPath[],
     private readonly resolvedRuleCandidates: readonly BashPathRuleCandidate[],
   ) {}
 
@@ -59,14 +59,14 @@ export class BashProgram {
     if (!tree) return new BashProgram(command, [], [], []);
 
     try {
-      const { externalPaths, ruleCandidates } = new BashPathResolver(
+      const { externalAccesses, ruleCandidates } = new BashPathResolver(
         normalizer,
         options?.workdir,
       ).resolve(tree.rootNode);
       return new BashProgram(
         command,
         collectCommands(tree.rootNode),
-        externalPaths,
+        externalAccesses,
         ruleCandidates,
       );
     } finally {
@@ -104,21 +104,25 @@ export class BashProgram {
   }
 
   /**
-   * Deduplicated paths that resolve outside `cwd`, as {@link AccessPath} value
-   * objects holding both the lexical (as-typed) and canonical (symlink-resolved)
-   * forms behind distinct accessors.
+   * Deduplicated accesses that resolve outside `cwd`: each an
+   * {@link AccessPath} value object holding both the lexical (as-typed) and
+   * canonical (symlink-resolved) forms behind distinct accessors, paired with
+   * the effect the command stream proved for it.
    *
    * Resolved eagerly at parse time through the `PathNormalizer` supplied to
    * `parse()` (platform + cwd baked in).
    * Use `.matchValues()` for `external_directory` pattern matching and
    * `.boundaryValue()` for containment checks; `.value()` for display and logs.
+   * Two attributions of the same resolved path fold rather than split, so the
+   * entry count is a function of the paths alone (#807).
    */
-  externalPaths(): AccessPath[] {
-    return [...this.resolvedExternalPaths];
+  externalAccesses(): BashExternalPath[] {
+    return [...this.resolvedExternalAccesses];
   }
 
   /**
-   * Path-rule candidates paired with their policy lookup values.
+   * Path-rule candidates paired with their policy lookup values and the
+   * effect the command stream proved for each (#807).
    *
    * Resolved eagerly at parse time through the `PathNormalizer` supplied to
    * `parse()` (platform + cwd baked in).

package/src/access-intent/bash/redirect-analysis.ts

@@ -0,0 +1,98 @@
+import { redirectDestinationEffect } from "#src/access-intent/bash/command-effects";
+import type { TSNode } from "#src/access-intent/bash/parser";
+import type { TokenEffect } from "#src/access-intent/effect";
+
+/**
+ * What a redirect node in the parse tree proves.
+ *
+ * `command-effects.ts` owns the operator *table* — which spelling means read,
+ * which means write — and this module owns reading a `file_redirect` node well
+ * enough to consult it: finding the operator among the node's children, and
+ * telling a destination that names a file from one that names a descriptor.
+ *
+ * The split exists because two callers need different answers from the same
+ * read, and — importantly — they need them under different burdens of proof.
+ * The token collector asks what effect to *attribute* to a destination it is
+ * about to emit, so it answers with a proof. The command enumerator asks
+ * whether it is safe to *remove* the wrapper floor, so it answers with a
+ * refusal: anything it cannot resolve counts against the exemption (#803).
+ * One reader of the node keeps the two from drifting on what a redirect is.
+ */
+
+/**
+ * The effect `redirect` proves for `destination`, or `null` when the redirect
+ * names no file and no token should be collected.
+ *
+ * `>&` and `<&` are the two operators that may name either a file descriptor
+ * (`2>&1`) or a real file (`cmd >& out`); the destination node's type is the
+ * parse-tree fact that tells them apart.
+ */
+export function redirectEffectForDestination(
+  redirect: TSNode,
+  destination: TSNode,
+): TokenEffect | null {
+  return redirectDestinationEffect(
+    redirectOperatorOf(redirect),
+    DESCRIPTOR_NODE_TYPES.has(destination.type),
+  );
+}
+
+/**
+ * True unless `redirect` provably only reads — the fail-closed question the
+ * floor exemption asks.
+ *
+ * Deliberately **not** the negation of a write proof. A destination this module
+ * cannot resolve counts as a write here, because the caller is deciding whether
+ * to remove a guard: `> $OUT`, `>${OUT}`, and `> $(mktemp)` name a file chosen
+ * at run time, and the parse can say nothing about which. Reading those as "no
+ * write proved, therefore no write" would hand the exemption to exactly the
+ * shapes least visible to every other surface — the path projection does not
+ * collect them either (#609).
+ *
+ * Only two things clear it: a descriptor duplication (`2>&1`), which names no
+ * file, and an operator that proves a read — reading a file alongside a pure
+ * reader leaves it a pure reader.
+ */
+export function redirectMayWriteFile(redirect: TSNode): boolean {
+  for (let i = 0; i < redirect.childCount; i++) {
+    const child = redirect.child(i);
+    // The operator itself is the redirect's only unnamed child.
+    if (!child?.isNamed) continue;
+    // A source or duplicated descriptor (`2`, `&1`) names no file.
+    if (DESCRIPTOR_NODE_TYPES.has(child.type)) continue;
+    // A shape the grammar could not resolve (`<>` degrades to one) says nothing
+    // about direction, so it cannot clear the check.
+    if (child.type === "ERROR") return true;
+    if (redirectEffectForDestination(redirect, child)?.effect !== "read") {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Destination node types that name a file descriptor rather than a file, so
+ * `>&` / `<&` duplicate a stream instead of touching the filesystem.
+ *
+ * Neither type is in {@link ARG_NODE_TYPES}, so `2>&1`'s `1` is already never
+ * collected; the check is what keeps that true if the argument set widens.
+ */
+const DESCRIPTOR_NODE_TYPES: ReadonlySet<string> = new Set([
+  "file_descriptor",
+  "number",
+]);
+
+/**
+ * The redirect operator of a redirect node.
+ *
+ * tree-sitter-bash emits it as an unnamed child whose `type` is the operator
+ * text itself, and a redirect's only unnamed child is that operator — so the
+ * syntax proof is a lookup on the first one found.
+ */
+function redirectOperatorOf(node: TSNode): string {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && !child.isNamed) return child.type;
+  }
+  return "";
+}

package/src/access-intent/bash/token-classification.ts

@@ -16,9 +16,17 @@
  * `docs/decisions/0009-bash-path-projection-completeness-contract.md`.
  *
  * All three classifiers share the private `rejectNonPathToken` predicate that
- * captures the six rejection cases common to them (the production clone this
+ * captures the five rejection cases common to them (the production clone this
  * module was extracted to eliminate).
  *
+ * None of them reads a token's glob or regex metacharacters. A shell bracket
+ * glob and a regex character class are spelled identically, so "contains a
+ * metacharacter" cannot decide path-hood — and it silently dropped tokens the
+ * shell really does expand into filesystem paths (`/etc/[p]asswd`,
+ * `rm -rf /tmp/tmp.*`, #821). What a pattern argument is instead settled by
+ * *position*: `PATTERN_FIRST_COMMANDS` in `token-collection.ts` skips a
+ * pattern-first command's inline pattern positional at collection time.
+ *
  * Both `classifyTokenAsPathCandidate` and `classifyTokenAsRuleCandidate` recognize
  * Windows drive-letter absolute paths (`C:/…`, `C:\…`) unconditionally on all
  * platforms. On POSIX the token resolves as a real in-CWD relative path and is
@@ -106,8 +114,8 @@ export function classifyTokenAsRuleCandidate(
  * *shape* name a path at all?
  *
  * It runs only the shared `rejectNonPathToken` prelude, so a flag,
- * env-assignment, URL, `@scope` token, or regex-shaped token is never a
- * candidate. Everything else is returned for the caller to probe.
+ * env-assignment, URL, or `@scope` token is never a candidate. Everything else
+ * is returned for the caller to probe.
  *
  * Deliberately consults no policy: candidacy is settled by the filesystem and
  * the decision by the ruleset, which keeps this module a pure shape function
@@ -137,19 +145,14 @@ const WINDOWS_DRIVE_PATH_PATTERN = /^[a-zA-Z]:[/\\]/;
  */
 const URL_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
 
-/**
- * Regex metacharacter sequences that are never found in real filesystem paths.
- * If a token contains any of these, it is almost certainly a regex pattern
- * (e.g. a grep argument) rather than a path.
- */
-const REGEX_METACHAR_PATTERN = /\.\*|\.\+|\\\||\\\(|\\\)|\[.*?\]|\^\//;
-
 /**
  * Shared rejection prelude: returns `true` when a token can never be a
  * filesystem path, regardless of which classifier is asking.
  *
  * Rejects: empty tokens, flags (leading `-`), env assignments (`FOO=/bar`),
- * URLs, `@scope/package` patterns, and regex metacharacter sequences.
+ * URLs, and `@scope/package` patterns. Each rules a token out by syntax; a
+ * glob or regex metacharacter does not, since the two are indistinguishable
+ * and the shell expands the former into real paths (#821).
  *
  * A bare `/` (or `//`, `///`) is NOT rejected: it denotes the filesystem root,
  * a deliberate external-directory access (`find /`, `ls /`), so it must reach
@@ -172,7 +175,5 @@ function rejectNonPathToken(token: string): boolean {
   // since it looks like an absolute-rooted path, not an npm scope.
   if (token.startsWith("@") && !token.startsWith("@/")) return true;
 
-  if (REGEX_METACHAR_PATTERN.test(token)) return true;
-
   return false;
 }