@gotgenes/pi-permission-system 36.2.0 → 37.0.0

package/src/access-intent/bash/shell-variable-expansion.ts

@@ -17,24 +17,98 @@
  * See `docs/decisions/0009-bash-path-projection-completeness-contract.md`.
  */
 import { homedir } from "node:os";
+import { hasHomePrefix } from "#src/path/expand-home";
 
 import type { TSNode } from "./parser";
 
 /**
- * The value of a plain `$NAME` / `${NAME}` reference, or `null` when the node
- * is not a plain reference or names a variable outside the resolvable set.
+ * The resolvable variables as one program sees them: which of them the program
+ * rebinds, so that a reference to a rebound one no longer reads as its startup
+ * value.
  *
- * Plainness is decided structurally, not by matching the node's text: a plain
- * reference carries exactly one `variable_name` child and nothing else but
- * delimiters. An operator form (`${HOME:-/tmp}`, `${#HOME}`, `${HOME%/*}`)
- * carries additional children and is therefore rejected without this module
- * needing to enumerate bash's expansion operators.
+ * A closed set of rebound names, never their values — tracking what a program
+ * assigns is the dataflow ADR 0009 declines.
  */
-export function resolvePlainVariableExpansion(node: TSNode): string | null {
-  const name = plainVariableName(node);
-  return name === null ? null : (RESOLVABLE_VARIABLES.get(name)?.() ?? null);
+export class ShellVariables {
+  /** A program that rebinds none of the resolvable variables. */
+  static readonly UNREBOUND = new ShellVariables(new Set());
+
+  /**
+   * The resolvable variables `roots` rebind: the primary parse and every
+   * salvaged region, since an assignment in one governs a reference in another.
+   *
+   * A resolvable name rebinds when a `variable_name` carries it anywhere but as
+   * a plain reference's name: an assignment (a prefix one too), a declaration, a
+   * `for` variable, `unset`, an arithmetic assignment, `${HOME:=x}`. It also
+   * rebinds when a name-binding builtin is handed it as an argument (`read`,
+   * `printf -v`, `let`, a quoted `export "HOME=…"`), and both rebind under a
+   * command running code the walk never parses (`eval`, `source`, `.`, `trap`). Position is
+   * ignored, because a loop or a function body can run a later assignment
+   * first; a prefix assignment and an operator read (`${HOME:-x}`) count
+   * although neither rebinds the current shell, which costs only the
+   * projection of a program already spelling the name oddly.
+   */
+  static scan(roots: readonly TSNode[]): ShellVariables {
+    const rebound = new Set<string>();
+    for (const root of roots) collectRebound(root, rebound, false);
+    return rebound.size === 0
+      ? ShellVariables.UNREBOUND
+      : new ShellVariables(rebound);
+  }
+
+  private constructor(private readonly rebound: ReadonlySet<string>) {}
+
+  /**
+   * The value of a plain `$NAME` / `${NAME}` reference, or `null` when the
+   * node is not a plain reference or names a variable outside the resolvable
+   * set.
+   *
+   * Plainness is decided structurally, not by matching the node's text: a
+   * plain reference carries exactly one `variable_name` child and nothing else
+   * but delimiters. An operator form (`${HOME:-/tmp}`, `${#HOME}`,
+   * `${HOME%/*}`) carries additional children and is therefore rejected without
+   * this module needing to enumerate bash's expansion operators.
+   */
+  resolveReference(node: TSNode): string | null {
+    const name = plainVariableName(node);
+    if (name === null || this.rebound.has(name)) return null;
+    return RESOLVABLE_VARIABLES.get(name)?.() ?? null;
+  }
+
+  /**
+   * Whether a collected path token is spelled from a `HOME` this program
+   * rebinds (`$HOME/x`, `${HOME}`, `~/x`).
+   *
+   * Such a token names no path the projection can know, yet path normalization
+   * expands its prefix to the startup home exactly as it does for a config
+   * pattern, so it must leave the path surfaces before it reaches them.
+   */
+  spellsReboundHome(token: string): boolean {
+    return this.rebound.has("HOME") && hasHomePrefix(token);
+  }
+
+  /**
+   * How a word's leading unquoted text expands when it opens with a tilde
+   * prefix that reads `HOME` (`~` or `~/…`; `~user` reads the password
+   * database instead), or `undefined` when it does not.
+   *
+   * Unknown once the program rebinds `HOME`: bash 3.2, which Pi runs as
+   * `/bin/bash` on macOS, expands it from the reassigned value. Otherwise it is
+   * the inherited `HOME`, which `homedir()` returns verbatim, so the word leads
+   * with whatever that does.
+   */
+  readTilde(leadingText: string): TildeReading | undefined {
+    if (leadingText !== "~" && !leadingText.startsWith("~/")) return undefined;
+    if (this.rebound.has("HOME")) return { known: false };
+    return { known: true, leadsWithDash: homedir().startsWith("-") };
+  }
 }
 
+/** What a leading tilde prefix expands to, as far as the program shows. */
+export type TildeReading =
+  | { readonly known: false }
+  | { readonly known: true; readonly leadsWithDash: boolean };
+
 /**
  * How each resolvable variable is spelled as a path.
  *
@@ -50,6 +124,129 @@ const RESOLVABLE_VARIABLES: ReadonlyMap<string, () => string> = new Map([
   ["PWD", () => "."],
 ]);
 
+/**
+ * Record each resolvable name `node` binds.
+ *
+ * `bindsNames` holds beneath a builtin that binds the names it is handed
+ * (`read HOME`, `export "HOME=/etc"`, `declare -n r=HOME`), and only there does
+ * an argument spelling a name count: `grep HOME ~/.bashrc` binds nothing, and
+ * reading it as a rebinding would drop the `~/.bashrc` it does read.
+ */
+function collectRebound(
+  node: TSNode,
+  rebound: Set<string>,
+  inheritedBindsNames: boolean,
+): void {
+  if (REFERENCE_TYPES.has(node.type) && plainVariableName(node) !== null) {
+    return;
+  }
+  const bindsNames = bindsNamesBeneath(node, inheritedBindsNames);
+  if (node.type === "variable_name" && RESOLVABLE_VARIABLES.has(node.text)) {
+    rebound.add(node.text);
+  }
+  if (bindsNames && NAME_ARGUMENT_TYPES.has(node.type)) {
+    const name = NAMED_ARGUMENT.exec(node.text.replace(QUOTING, ""))?.[1];
+    if (name) rebound.add(name);
+  }
+  if (node.type === "command" && UNSEEN_CODE_COMMANDS.has(commandName(node))) {
+    for (const name of RESOLVABLE_VARIABLES.keys()) rebound.add(name);
+  }
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) collectRebound(child, rebound, bindsNames);
+  }
+}
+
+/**
+ * Whether the arguments beneath `node` are names its command binds. A command
+ * decides for itself; a `declare`-family or `unset` statement always binds;
+ * anything else inherits.
+ */
+function bindsNamesBeneath(node: TSNode, inherited: boolean): boolean {
+  if (node.type === "declaration_command" || node.type === "unset_command") {
+    return true;
+  }
+  if (node.type !== "command") return inherited;
+  const name = commandName(node);
+  if (name === "printf") return hasArgument(node, "-v");
+  return NAME_BINDING_COMMANDS.has(name);
+}
+
+/**
+ * Builtins that bind a name passed as an argument. `declare` and its family
+ * parse as a `declaration_command` when spelled plainly and as a `command`
+ * when quoted, so they are listed here too; `printf` binds only under `-v`.
+ */
+const NAME_BINDING_COMMANDS: ReadonlySet<string> = new Set([
+  "read",
+  "mapfile",
+  "readarray",
+  "getopts",
+  "let",
+  "unset",
+  "declare",
+  "typeset",
+  "local",
+  "export",
+  "readonly",
+]);
+
+/**
+ * Argument nodes that can spell a name a builtin binds, whole or as the head
+ * of an assignment (`HOME=…`, `HOME+=…`, `HOME[0]=…`, `let HOME++`).
+ */
+const NAME_ARGUMENT_TYPES: ReadonlySet<string> = new Set([
+  "word",
+  "string",
+  "raw_string",
+  "concatenation",
+]);
+
+/** A resolvable name leading an argument, not followed by more of an identifier. */
+const NAMED_ARGUMENT = new RegExp(
+  `^(${[...RESOLVABLE_VARIABLES.keys()].join("|")})(?![A-Za-z0-9_])`,
+);
+
+/** Quote and escape characters, which the shell removes before a builtin sees the name. */
+const QUOTING = /["'\\]/g;
+
+/** A command's name as the shell reads it, quotes and escapes removed. */
+function commandName(command: TSNode): string {
+  for (let i = 0; i < command.childCount; i++) {
+    const child = command.child(i);
+    if (child?.type === "command_name") return child.text.replace(QUOTING, "");
+  }
+  return "";
+}
+
+/** Whether a command carries `flag` as one of its own arguments. */
+function hasArgument(command: TSNode, flag: string): boolean {
+  for (let i = 0; i < command.childCount; i++) {
+    const child = command.child(i);
+    if (child && child.type !== "command_name" && child.text === flag) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Commands that run code the walk never parses, which may rebind anything:
+ * `eval`'s joined arguments, a file `source`/`.` reads, and a `trap` action.
+ */
+const UNSEEN_CODE_COMMANDS: ReadonlySet<string> = new Set([
+  "eval",
+  "source",
+  ".",
+  "trap",
+]);
+
+/** The node types a variable reference parses as. */
+const REFERENCE_TYPES: ReadonlySet<string> = new Set([
+  "simple_expansion",
+  "expansion",
+]);
+
 /** Node types that delimit an expansion without altering what it evaluates to. */
 const EXPANSION_DELIMITERS: ReadonlySet<string> = new Set(["$", "${", "}"]);
 

package/src/access-intent/bash/sync-commands.ts

@@ -3,7 +3,9 @@ import {
   collectCommands,
   collectSalvagedCommands,
 } from "./command-enumeration";
+import { WordReader } from "./node-text";
 import { getWarmBashParser } from "./parser";
+import { ShellVariables } from "./shell-variable-expansion";
 import { withSalvagedRoots } from "./unresolved-salvage";
 
 /**
@@ -26,10 +28,15 @@ export function parseBashCommandsSync(command: string): BashCommand[] | null {
   const tree = parser.parse(command);
   if (!tree) return [];
   try {
-    return withSalvagedRoots(tree.rootNode, parser, (salvaged) => [
-      ...collectCommands(tree.rootNode),
-      ...salvaged.flatMap(collectSalvagedCommands),
-    ]);
+    return withSalvagedRoots(tree.rootNode, parser, (salvaged) => {
+      const words = new WordReader(
+        ShellVariables.scan([tree.rootNode, ...salvaged]),
+      );
+      return [
+        ...collectCommands(tree.rootNode, words),
+        ...salvaged.flatMap((root) => collectSalvagedCommands(root, words)),
+      ];
+    });
   } finally {
     tree.delete();
   }

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

@@ -5,10 +5,8 @@ import { EXECUTION_HOST_TYPES, forEachExecutionIn } from "./nested-execution";
 import {
   ARG_NODE_TYPES,
   type ArgWord,
-  hasComputedPart,
-  readArgWord,
-  resolveNodeText,
   SKIP_SUBTREE_TYPES,
+  type WordReader,
 } from "./node-text";
 import type { TSNode } from "./parser";
 import {
@@ -63,24 +61,27 @@ export interface PathToken {
  * `script`-role flag's argument for an interpreter. For all other commands,
  * collects all arguments generically.
  */
-export function collectPathCandidateTokens(node: TSNode): PathToken[] {
-  if (node.type === "command") return collectCommandTokens(node);
-  if (node.type === "file_redirect") return collectRedirectTokens(node);
+export function collectPathCandidateTokens(
+  node: TSNode,
+  words: WordReader,
+): PathToken[] {
+  if (node.type === "command") return collectCommandTokens(node, words);
+  if (node.type === "file_redirect") return collectRedirectTokens(node, words);
   if (node.type === "for_statement") {
-    return collectStatementOperandTokens(node, "after-in");
+    return collectStatementOperandTokens(node, "after-in", words);
   }
   if (node.type === "case_statement") {
-    return collectStatementOperandTokens(node, "before-in");
+    return collectStatementOperandTokens(node, "before-in", words);
   }
   if (EXECUTION_HOST_TYPES.has(node.type)) {
-    return collectHostedExecutionTokens(node);
+    return collectHostedExecutionTokens(node, words);
   }
   if (SKIP_SUBTREE_TYPES.has(node.type)) return [];
 
   const tokens: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (child) tokens.push(...collectPathCandidateTokens(child));
+    if (child) tokens.push(...collectPathCandidateTokens(child, words));
   }
   return tokens;
 }
@@ -95,19 +96,22 @@ export function collectPathCandidateTokens(node: TSNode): PathToken[] {
  * spelling proves nothing. A nested execution collected along the way keeps
  * its own command's attribution instead.
  */
-export function collectCommandTokens(node: TSNode): PathToken[] {
+export function collectCommandTokens(
+  node: TSNode,
+  words: WordReader,
+): PathToken[] {
   const effect = proveCommandEffect(
-    extractCommandWord(node) ?? "",
-    commandArgumentWords(node),
+    extractCommandWord(node, words) ?? "",
+    commandArgumentWords(node, words),
   );
-  const commandName = extractCommandName(node);
+  const commandName = extractCommandName(node, words);
   const config = commandName
     ? PATTERN_FIRST_COMMANDS.get(commandName)
     : undefined;
-  if (config) return collectPatternCommandTokens(node, config, effect);
+  if (config) return collectPatternCommandTokens(node, config, effect, words);
   return [
-    ...collectGenericCommandTokens(node, effect),
-    ...collectEmbeddedOptionValues(node, effect),
+    ...collectGenericCommandTokens(node, effect, words),
+    ...collectEmbeddedOptionValues(node, effect, words),
   ];
 }
 
@@ -139,7 +143,10 @@ export function collectCommandTokens(node: TSNode): PathToken[] {
  * Reading the redirect node itself belongs to `redirect-analysis.ts`, which
  * the command enumerator consults for the same fact (#803).
  */
-export function collectRedirectTokens(node: TSNode): PathToken[] {
+export function collectRedirectTokens(
+  node: TSNode,
+  words: WordReader,
+): PathToken[] {
   const target = redirectTargetIndex(node);
   const tokens: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
@@ -148,15 +155,15 @@ export function collectRedirectTokens(node: TSNode): PathToken[] {
     if (ARG_NODE_TYPES.has(child.type)) {
       const effect = redirectEffectForDestination(node, child);
       if (effect) {
-        const token = resolveNodeText(child);
+        const token = words.text(child);
         const role: TokenRole =
-          i === target && provesTarget(effect, child, token)
+          i === target && provesTarget(effect, child, token, words)
             ? "redirect-destination"
             : "operand";
         tokens.push({ token, effect, role });
       }
     }
-    tokens.push(...collectHostedExecutionTokens(child));
+    tokens.push(...collectHostedExecutionTokens(child, words));
   }
   return tokens;
 }
@@ -174,9 +181,10 @@ function provesTarget(
   effect: TokenEffect,
   destination: TSNode,
   token: string,
+  words: WordReader,
 ): boolean {
   return (
-    effect.source === "syntax" && !hasComputedPart(destination) && token !== ""
+    effect.source === "syntax" && !words.isComputed(destination) && token !== ""
   );
 }
 
@@ -193,10 +201,13 @@ function provesTarget(
  * (`> ${DIR}/$(cmd)`), so the traversal is the root-inclusive
  * `forEachExecutionIn`.
  */
-function collectHostedExecutionTokens(node: TSNode): PathToken[] {
+function collectHostedExecutionTokens(
+  node: TSNode,
+  words: WordReader,
+): PathToken[] {
   const tokens: PathToken[] = [];
   forEachExecutionIn(node, (contextNode) => {
-    tokens.push(...collectPathCandidateTokens(contextNode));
+    tokens.push(...collectPathCandidateTokens(contextNode, words));
   });
   return tokens;
 }
@@ -244,6 +255,7 @@ type OperandSide = "before-in" | "after-in";
 function collectStatementOperandTokens(
   node: TSNode,
   operandSide: OperandSide,
+  words: WordReader,
 ): PathToken[] {
   const tokens: PathToken[] = [];
   let seenIn = false;
@@ -256,15 +268,15 @@ function collectStatementOperandTokens(
     }
     const side: OperandSide = seenIn ? "after-in" : "before-in";
     if (side !== operandSide || !ARG_NODE_TYPES.has(child.type)) {
-      tokens.push(...collectPathCandidateTokens(child));
+      tokens.push(...collectPathCandidateTokens(child, words));
       continue;
     }
     tokens.push({
-      token: resolveNodeText(child),
+      token: words.text(child),
       effect: UNPROVEN_EFFECT,
       role: "operand",
     });
-    tokens.push(...collectHostedExecutionTokens(child));
+    tokens.push(...collectHostedExecutionTokens(child, words));
   }
   return tokens;
 }
@@ -279,8 +291,11 @@ function collectStatementOperandTokens(
  * capability claim, where the directory prefix is the whole point — use
  * {@link extractCommandWord} there.
  */
-export function extractCommandName(node: TSNode): string | undefined {
-  const word = extractCommandWord(node);
+export function extractCommandName(
+  node: TSNode,
+  words: WordReader,
+): string | undefined {
+  const word = extractCommandWord(node, words);
   return word === undefined ? undefined : basename(word);
 }
 
@@ -294,12 +309,15 @@ export function extractCommandName(node: TSNode): string | undefined {
  * Documented against {@link extractCommandName}, which answers the other
  * question.
  */
-export function extractCommandWord(node: TSNode): string | undefined {
+export function extractCommandWord(
+  node: TSNode,
+  words: WordReader,
+): string | undefined {
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child) continue;
     if (child.type === "command_name") {
-      const text = resolveNodeText(child);
+      const text = words.text(child);
       return text === "" ? undefined : text;
     }
   }
@@ -319,16 +337,16 @@ export function extractCommandWord(node: TSNode): string | undefined {
  * reaches the program as an argument too, and a proof that never saw it could
  * not know it might spell `-i`.
  */
-function commandArgumentWords(node: TSNode): ArgWord[] {
-  const words: ArgWord[] = [];
+function commandArgumentWords(node: TSNode, words: WordReader): ArgWord[] {
+  const argWords: ArgWord[] = [];
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
     if (!child?.isNamed) continue;
     if (COMMAND_PREFIX_TYPES.has(child.type)) continue;
     if (REDIRECT_NODE_TYPES.has(child.type)) continue;
-    words.push(readArgWord(child));
+    argWords.push(words.argWord(child));
   }
-  return words;
+  return argWords;
 }
 
 /**
@@ -376,6 +394,7 @@ const OPTION_VALUE_PATTERN = /^-{1,2}[^=\s]+=(.+)$/;
 function collectEmbeddedOptionValues(
   node: TSNode,
   effect: TokenEffect,
+  words: WordReader,
 ): PathToken[] {
   const values: PathToken[] = [];
   for (let i = 0; i < node.childCount; i++) {
@@ -384,7 +403,7 @@ function collectEmbeddedOptionValues(
     if (COMMAND_PREFIX_TYPES.has(child.type)) continue;
     if (!ARG_NODE_TYPES.has(child.type)) continue;
 
-    const value = OPTION_VALUE_PATTERN.exec(resolveNodeText(child))?.[1];
+    const value = OPTION_VALUE_PATTERN.exec(words.text(child))?.[1];
     if (value !== undefined) {
       values.push({ token: value, effect, role: "operand" });
     }
@@ -768,6 +787,7 @@ function collectPatternCommandTokens(
   node: TSNode,
   config: PatternCommandConfig,
   effect: TokenEffect,
+  words: WordReader,
 ): PathToken[] {
   const patternPositionals = config.patternPositionals ?? 1;
   let hasExplicitScript = false;
@@ -782,12 +802,12 @@ function collectPatternCommandTokens(
 
     if (COMMAND_PREFIX_TYPES.has(child.type)) {
       // Supplies no operand of its own, but may host one that really runs.
-      tokens.push(...collectHostedExecutionTokens(child));
+      tokens.push(...collectHostedExecutionTokens(child, words));
       continue;
     }
 
     const isArgNode = ARG_NODE_TYPES.has(child.type);
-    const text = resolveNodeText(child);
+    const text = words.text(child);
 
     // An argument is read for its text below, and its text alone — but a
     // quoted substitution sitting there really runs, and its own operands are
@@ -796,7 +816,7 @@ function collectPatternCommandTokens(
     // recursions below; the quoted one parses as a `string` and would
     // otherwise stop here, whichever role the argument turns out to have
     // (#945).
-    if (isArgNode) tokens.push(...collectHostedExecutionTokens(child));
+    if (isArgNode) tokens.push(...collectHostedExecutionTokens(child, words));
 
     // Handle the argument a previous flag consumed. The consumption discharges
     // on whatever node type follows, not only on an ARG_NODE_TYPES one: a bare
@@ -810,7 +830,7 @@ function collectPatternCommandTokens(
       if (!isArgNode) {
         // Contributes no operand text of its own, but may host a nested
         // execution whose operands are candidates (#741).
-        tokens.push(...collectPathCandidateTokens(child));
+        tokens.push(...collectPathCandidateTokens(child, words));
         continue;
       }
       const discharge = dischargePendingConsumption(consumption, text, effect);
@@ -838,7 +858,7 @@ function collectPatternCommandTokens(
         positionalsSeen++;
       }
       // Recurse for nested commands (e.g. command_substitution).
-      tokens.push(...collectPathCandidateTokens(child));
+      tokens.push(...collectPathCandidateTokens(child, words));
       continue;
     }
 
@@ -963,6 +983,7 @@ function dischargePendingConsumption(
 function collectGenericCommandTokens(
   node: TSNode,
   effect: TokenEffect,
+  words: WordReader,
 ): PathToken[] {
   const tokens: PathToken[] = [];
   let seenCommandName = false;
@@ -974,7 +995,7 @@ function collectGenericCommandTokens(
     if (COMMAND_PREFIX_TYPES.has(child.type)) {
       // Supplies no operand of its own, but may host one that really runs.
       if (child.type === "command_name") seenCommandName = true;
-      tokens.push(...collectHostedExecutionTokens(child));
+      tokens.push(...collectHostedExecutionTokens(child, words));
       continue;
     }
 
@@ -983,7 +1004,7 @@ function collectGenericCommandTokens(
     // sits (ADR 0009's positional invariance, #945). The unquoted spelling
     // reaches the nested command through the trailing recursion.
     if (ARG_NODE_TYPES.has(child.type))
-      tokens.push(...collectHostedExecutionTokens(child));
+      tokens.push(...collectHostedExecutionTokens(child, words));
 
     // If there was no explicit command_name node, the first word-like
     // child is the command name itself — skip it.
@@ -994,12 +1015,12 @@ function collectGenericCommandTokens(
 
     // Argument nodes: resolve their text and collect.
     if (ARG_NODE_TYPES.has(child.type)) {
-      tokens.push({ token: resolveNodeText(child), effect, role: "operand" });
+      tokens.push({ token: words.text(child), effect, role: "operand" });
       continue;
     }
 
     // Recurse into other children (e.g. command_substitution nested in args)
-    tokens.push(...collectPathCandidateTokens(child));
+    tokens.push(...collectPathCandidateTokens(child, words));
   }
 
   return tokens;