@namzu/sdk 46.0.0 → 48.1.0

package/dist/authorization/program.js

@@ -0,0 +1,713 @@
+/**
+ * Where a command line actually execs a program.
+ *
+ * Three consumers each answered "what program does this command run" their
+ * own way — the live `bash` tool's escalation, the scheduled-run floor's
+ * `pkill`/`systemctl`/… detection, and a scheduled script's static check —
+ * and each guessed differently about a re-exec wrapper (`sudo`, `env`,
+ * `nice`, `timeout`, …) standing in front of the real program. A security
+ * review found that every one of them only ever looked at
+ * `command.words[command.assignments]`, so `env $(echo git) push`,
+ * `timeout 5 $(echo systemctl) stop …` and the rest ran unverified: the
+ * wrapper's own name is what each check saw, never the word it was actually
+ * about to run.
+ *
+ * `programPositions` is the one place that answer now lives. It unwraps a
+ * chain of re-exec wrappers — each with its OWN real option grammar, so
+ * `stdbuf -oL prog` and `timeout 5 prog` are read correctly rather than
+ * assumed to put the program right after the wrapper's name — and reports
+ * every position in the command where a program is actually named: the
+ * (possibly wrapped) head, and, for `find`, each `-exec`/`-execdir`/`-ok`/
+ * `-okdir` clause's own head.
+ *
+ * A position is `known` (the literal, non-expanding word that names the
+ * program) or `unknown` (why it could not be resolved: the word itself
+ * expands, an option this does not recognise stood in the way, or an
+ * `xargs` program that is a shell or a `{}` placeholder). Fail closed: an
+ * option this does not model makes the position unknown, never "assumed to
+ * be the program" and never "assumed harmless".
+ *
+ * `source`/`.` and `eval` are read the same way a nested `bash -c` payload
+ * already is, not as an automatic unknown: `source path`/`. path` with a
+ * LITERAL path is known — the position is the `source`/`.` word itself,
+ * exactly as `bash path` is known without anyone reading what `path`
+ * contains — and unknown only when the path itself expands (`source "$X"`).
+ * `eval`'s literal argument words are joined and lexed as a command line of
+ * their own, and every position in the commands that come out of that is
+ * folded into the result — unknown when that reading is opaque, when any
+ * argument word expands, or, transitively, when a position inside the
+ * lexed payload is itself unknown (`eval 'env $(echo git) push'`).
+ * Consistency review (2026-09-24): treating `eval`/`source`/`.` as
+ * automatically unknown "wherever they stand, even literal" made
+ * `source .venv/bin/activate` ask alongside `source "$X"`, which is exactly
+ * the asymmetry `bash script.sh` (known) versus `bash -c "$X"` (unknown)
+ * does not have — the same module read a literal argument two different
+ * ways depending only on which command carried it. An `unknown` position
+ * still carries `word` when a single word is the reason (the word itself
+ * expands, so its value is not known before the line runs) — a caller that
+ * only needs "is there a word here that could name any of several tools"
+ * (the scheduled-run floor's `pkill`/`systemctl`/… detection) reads that
+ * word whether the position is known or not; `unknown` with no `word` is a
+ * structural failure with no single culprit (too many wrappers, an
+ * unrecognised option, an opaque `eval` payload, a poisoned environment).
+ *
+ * `hasPoisoningPrefix`, `poisonsLaterCommands` and `poisonedProgramPosition`
+ * are the other half a caller iterating a whole script needs: a command
+ * that sets `PATH`, `LD_PRELOAD`, `LD_LIBRARY_PATH`, `BASH_ENV`, `ENV` or
+ * `IFS` — as a leading assignment (which affects that same command's own
+ * program position) or as an `export`/bare assignment (which affects every
+ * command after it in the same script) — makes a LATER literal program name
+ * unverifiable too: which binary a literal `ls` resolves to depends on
+ * `PATH` at the moment it runs, not on the text of the word `ls`.
+ * `resolveScriptPrograms` threads that state through a whole script's
+ * commands in one pass, for a caller that does not want to write the loop
+ * itself.
+ */
+import { RUNTIME_EVALUATORS } from './command-line.js';
+import { skipOneReexecWrapper } from './reexec-wrapper.js';
+import { NESTED_SHELLS, basename, lexShellCommandLine, nestedShellCommand, } from './shell-lexer.js';
+/** How many re-exec wrappers a chain unwraps before giving up (`sudo env nice … prog`). */
+const MAX_WRAPPER_DEPTH = 8;
+const LITERAL = (w) => !w.expands;
+/** `NAME=value` read off an assignment word's own text, or null. */
+function assignmentName(word) {
+    const text = word.text.replace(/\\\n/g, '');
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)\+?=/.exec(text);
+    return match && word.value.startsWith(match[0]) ? match[1] : null;
+}
+/**
+ * `wrapper NAME=value…` sets `NAME` for the wrapped command only (`env
+ * NAME=value prog`, `sudo NAME=value prog`) — the same taint a leading
+ * command-prefix assignment gives its own command, just spelled through the
+ * wrapper instead of in front of it.
+ */
+function poisonedByWrapperAssignment(wrapper, name) {
+    return `${wrapper} ${name}=… sets ${name} for the command that follows, so a literal name after it cannot be trusted to resolve to what its text says`;
+}
+/**
+ * Scan `words` for a bare `-c`/`--command COMMAND` pair among options this
+ * wrapper recognises (everything else validated against `flags`/`withArg`,
+ * the same as {@link skipOptions}). `--command=X` is not modelled — a
+ * documented, deliberately conservative gap: it falls through to the
+ * unrecognised-option path, `unknown` never a silent pass. Returns the `-c`
+ * payload when found, the words left after options when it is not (a valid
+ * outcome some callers use — `flock`'s positional form, `script`'s bare
+ * form), or `unknown` on a bad option or a `-c` given no argument.
+ */
+function findDashC(words, flags, withArg, optionalAttached = []) {
+    let i = 0;
+    while (i < words.length) {
+        const w = words[i];
+        if (!LITERAL(w))
+            return { rest: words.slice(i) };
+        if (w.value === '-c' || w.value === '--command') {
+            const payload = words[i + 1];
+            if (payload === undefined)
+                return { unknown: `${w.value} was given no command` };
+            return { payload };
+        }
+        if (w.value === '--')
+            return { rest: words.slice(i + 1) };
+        if (flags.has(w.value)) {
+            i += 1;
+            continue;
+        }
+        if (optionalAttached.some((option) => option.startsWith('--')
+            ? w.value.startsWith(`${option}=`)
+            : w.value.startsWith(option) && w.value.length > option.length)) {
+            i += 1;
+            continue;
+        }
+        if (withArg.has(w.value)) {
+            i += 2;
+            continue;
+        }
+        const eq = w.value.indexOf('=');
+        if (w.value.startsWith('--') && eq > 0 && withArg.has(w.value.slice(0, eq))) {
+            i += 1;
+            continue;
+        }
+        if (/^--?[A-Za-z]/.test(w.value)) {
+            return { unknown: `an option this does not read: ${w.value}` };
+        }
+        return { rest: words.slice(i) };
+    }
+    return { rest: words.slice(i) };
+}
+/**
+ * Skip a wrapper's own recognised, argument-taking or bare options over
+ * `words`, stopping at the first word that is not one of them (the
+ * boundary between the wrapper's own invocation and whatever runs next).
+ * An option-shaped word (`-x`, `--long`) this does not recognise is
+ * `unknown`, never treated as the program; a word this cannot classify
+ * because it expands is left for the caller, which already knows to call
+ * an expanding program word unknown. `explicit`, when given, names options
+ * that ARE recognised but never lead to a named program at all (`sudo -i`
+ * runs a runtime-chosen login shell) — checked before `flags`/`withArg`, so
+ * the reason is explicit rather than an accident of `flags` swallowing them.
+ */
+function skipOptions(words, flags, withArg, explicit) {
+    let i = 0;
+    while (i < words.length) {
+        const w = words[i];
+        if (!LITERAL(w))
+            return { rest: words.slice(i) };
+        if (w.value === '--')
+            return { rest: words.slice(i + 1) };
+        const reason = explicit?.get(w.value);
+        if (reason !== undefined)
+            return { unknown: reason };
+        if (flags.has(w.value)) {
+            i += 1;
+            continue;
+        }
+        if (withArg.has(w.value)) {
+            i += 2;
+            continue;
+        }
+        const eq = w.value.indexOf('=');
+        if (w.value.startsWith('--') && eq > 0 && withArg.has(w.value.slice(0, eq))) {
+            i += 1;
+            continue;
+        }
+        // A short option's value attached to its flag (`-c2`, `-n10`, `-oL`),
+        // the conventional form for `ionice`, `nice`, `stdbuf` and `taskset`'s
+        // `-c` list — one token, no separate argument word.
+        if (!w.value.startsWith('--') && w.value.length > 2 && withArg.has(w.value.slice(0, 2))) {
+            i += 1;
+            continue;
+        }
+        if (/^--?[A-Za-z]/.test(w.value)) {
+            return { unknown: `an option this does not read: ${w.value}` };
+        }
+        return { rest: words.slice(i) };
+    }
+    return { none: true };
+}
+/** `xargs`' own options, then its program (the first non-option word, `echo` when there is none). */
+function unwrapXargs(words) {
+    const flags = new Set(['-0', '-o', '-p', '-r', '-t', '-x', '--null', '--open-tty', '--verbose']);
+    const withArg = new Set(['-a', '-d', '-E', '-e', '-I', '-i', '-L', '-l', '-n', '-P', '-s']);
+    const skipped = skipOptions(words, flags, withArg);
+    if ('unknown' in skipped)
+        return skipped;
+    const rest = 'none' in skipped ? [] : skipped.rest;
+    const program = rest[0];
+    if (program === undefined) {
+        // No program named: xargs' own default is `echo`, always safe.
+        return {
+            rest: [{ text: 'echo', value: 'echo', expands: false, quoted: false, substitutes: false }],
+        };
+    }
+    if (!LITERAL(program))
+        return { rest };
+    if (program.value === '{}' || NESTED_SHELLS.has(basename(program.value))) {
+        return {
+            unknown: `xargs' program is built from its input, not named in the line: ${program.text}`,
+        };
+    }
+    return { rest };
+}
+/**
+ * Special command runners. Plain re-exec wrappers are all read by the
+ * shared skipOneReexecWrapper, also used by the shell lexer to find -c.
+ */
+function unwrapOnce(words) {
+    const head = words[0];
+    const name = basename(head.value);
+    const rest = words.slice(1);
+    switch (name) {
+        case 'xargs':
+            return unwrapXargs(rest);
+        case 'su':
+        case 'runuser': {
+            const found = findDashC(rest, new Set(['-p', '--preserve-environment', '-P', '--pty', '-l', '--login', '-']), new Set([
+                '-s',
+                '--shell',
+                '-g',
+                '--group',
+                '-G',
+                '--supp-group',
+                '-w',
+                '--whitelist-environment',
+            ]));
+            if ('unknown' in found)
+                return found;
+            if ('payload' in found)
+                return found;
+            // No `-c`/`--command` at all: both start the target user's login
+            // or default shell — an interactive session, not a fixed next
+            // command this can name.
+            return {
+                unknown: `${name} without -c/--command starts an interactive login shell, not a named program`,
+            };
+        }
+        case 'script': {
+            // Per util-linux `script --help`: `-t[<file>], --timing[=<file>]`
+            // is a DEPRECATED ALIAS for `-T`/`--log-timing` with an OPTIONAL
+            // value (default file is stderr when bare) — it never consumes a
+            // separate following word, unlike the real `-T <file>`. Modelling
+            // `-t` as taking one used to swallow a following `-c` as `-t`'s own
+            // value, reading `script` as known and never looking at `-c`'s
+            // argument at all.
+            const flags = new Set([
+                '-a',
+                '--append',
+                '-e',
+                '--return',
+                '-f',
+                '--flush',
+                '--force',
+                '-q',
+                '--quiet',
+                '-t',
+                '--timing',
+            ]);
+            const withArg = new Set([
+                '-I',
+                '--log-in',
+                '-O',
+                '--log-out',
+                '-B',
+                '--log-io',
+                '-T',
+                '--log-timing',
+                '-m',
+                '--logging-format',
+                '-E',
+                '--echo',
+                '-o',
+                '--output-limit',
+            ]);
+            // `script [options] [<file>] [-- <command> [<argument>...]]`: `--`
+            // is an alternative to `-c`, running the command directly as an
+            // argv (not a joined string re-lexed through a shell) rather than
+            // recording an interactive session.
+            const dashDash = rest.findIndex((w) => LITERAL(w) && w.value === '--');
+            if (dashDash >= 0) {
+                const before = skipOptions(rest.slice(0, dashDash), flags, withArg);
+                if ('unknown' in before)
+                    return before;
+                const after = rest.slice(dashDash + 1);
+                return after.length === 0 ? { none: true } : { rest: after };
+            }
+            const found = findDashC(rest, flags, withArg, ['-t', '--timing']);
+            if ('unknown' in found)
+                return found;
+            if ('payload' in found)
+                return found;
+            // No `-c` and no `--`: `script` itself is the program — it
+            // records a terminal session (an interactive shell as its own
+            // child), and its only other argument is a log file name, not a
+            // command to name.
+            return { none: true };
+        }
+        case 'flock': {
+            const found = findDashC(rest, new Set([
+                '-s',
+                '--shared',
+                '-x',
+                '-e',
+                '--exclusive',
+                '-n',
+                '--nb',
+                '--nonblock',
+                '-o',
+                '--close',
+                '-F',
+                '--no-fork',
+                '--verbose',
+            ]), new Set(['-w', '--timeout', '-E', '--conflict-exit-code']));
+            if ('unknown' in found)
+                return found;
+            if ('payload' in found)
+                return found;
+            // Positional form (`flock file|directory command [args…]`): what
+            // is left after options starts with the locked file/directory
+            // (or a bare fd, with no command — nothing execs), then the real
+            // argv, run directly — no shell, no joining.
+            const target = found.rest[0];
+            if (target === undefined)
+                return { none: true };
+            const remaining = found.rest.slice(1);
+            return remaining.length === 0 ? { none: true } : { rest: remaining };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * `source path [args…]` / `. path [args…]`: known at `head` (the
+ * `source`/`.` word itself) when `path` is a literal word, exactly as
+ * `bash path` is known without reading what `path` contains — trailing
+ * words are the sourced script's own positional parameters, not inspected
+ * either, the same as `bash path`'s do not name a second program. Unknown,
+ * naming `path` itself, when it expands or is absent.
+ */
+function resolveSourceOrDot(head, args) {
+    const path = args[0];
+    if (path === undefined) {
+        return { word: head, unknown: `${basename(head.value)} was given nothing to run` };
+    }
+    if (!LITERAL(path)) {
+        return { word: path, unknown: `the file this runs is decided at runtime: ${path.text}` };
+    }
+    return { word: head };
+}
+/**
+ * `eval word…`: bash joins `eval`'s arguments with a space and reads the
+ * result as a command line. When every argument word is literal, that joined
+ * text is lexed the same way a `bash -c` payload already is, and every
+ * position in the commands it contains (poisoning threaded across them,
+ * same as any script) is folded into the result — unknown when the reading
+ * is opaque or incomplete, and transitively unknown when a position inside
+ * it is. An expanding argument word is unknown outright: its value, and so
+ * what `eval` will even read, is not known before the line runs. `eval`
+ * with no arguments does nothing in bash and names no position at all.
+ */
+function resolveEvalPayload(args, dialect) {
+    if (args.length === 0)
+        return [];
+    for (const arg of args) {
+        if (!LITERAL(arg)) {
+            return [{ word: arg, unknown: `eval's payload is decided at runtime: ${arg.text}` }];
+        }
+    }
+    const payload = args.map((arg) => arg.value).join(' ');
+    const reading = lexShellCommandLine(payload, { dialect });
+    if (reading.opaque || !reading.complete) {
+        return [
+            {
+                unknown: `eval's payload cannot be read (${reading.reasons[0] ?? 'a construct the lexer does not model'}): ${payload}`,
+            },
+        ];
+    }
+    return resolveScriptPrograms(reading.commands, dialect).flatMap((entry) => entry.positions);
+}
+/** The final position a chain of re-exec wrappers resolves to, from `words` (already literal, non-empty). */
+function resolveChain(words, dialect) {
+    let current = words;
+    for (let depth = 0; depth < MAX_WRAPPER_DEPTH; depth += 1) {
+        const head = current[0];
+        if (head === undefined)
+            return [{ unknown: 'no program follows this wrapper' }];
+        if (!LITERAL(head)) {
+            return [{ word: head, unknown: `the program is decided at runtime: ${head.text}` }];
+        }
+        const name = basename(head.value);
+        if (name === 'eval')
+            return resolveEvalPayload(current.slice(1), dialect);
+        if (name === 'watch')
+            return resolveWatchArgs(current.slice(1), dialect);
+        if (RUNTIME_EVALUATORS.has(name)) {
+            // `source`/`.`: `eval` is handled above, on its own, since a
+            // literal `eval` reads its payload rather than being the position
+            // itself.
+            return [resolveSourceOrDot(head, current.slice(1))];
+        }
+        const wrapper = skipOneReexecWrapper(current);
+        if (wrapper !== null) {
+            if ('unknown' in wrapper)
+                return [{ unknown: wrapper.unknown }];
+            if ('none' in wrapper)
+                return [{ word: head }];
+            for (const assignment of wrapper.assignments) {
+                if (DYNAMIC_RESOLUTION_VARIABLES.has(assignment)) {
+                    return [{ unknown: poisonedByWrapperAssignment(name, assignment) }];
+                }
+            }
+            if (wrapper.rest.length === 0)
+                return [{ word: head }];
+            current = wrapper.rest;
+            continue;
+        }
+        const unwrapped = unwrapOnce(current);
+        if (unwrapped === null)
+            return [{ word: head }];
+        if ('unknown' in unwrapped)
+            return [{ unknown: unwrapped.unknown }];
+        if ('none' in unwrapped)
+            return [{ word: head }];
+        if ('payload' in unwrapped)
+            return resolveDashCPayload(unwrapped.payload, dialect);
+        if (unwrapped.rest.length === 0)
+            return [{ word: head }];
+        current = unwrapped.rest;
+    }
+    return [{ unknown: 'too many re-exec wrappers to follow' }];
+}
+/**
+ * A `-c COMMAND` payload (`su -c`, `runuser -c`, `script -c`, `flock -c`):
+ * known — recursed into, the same as a nested `bash -c '<literal>'` payload
+ * — when literal, unknown when it expands.
+ */
+function resolveDashCPayload(payload, dialect) {
+    if (!LITERAL(payload)) {
+        return [
+            { word: payload, unknown: `the command this runs is decided at runtime: ${payload.text}` },
+        ];
+    }
+    const reading = lexShellCommandLine(payload.value, { dialect });
+    if (reading.opaque || !reading.complete) {
+        return [
+            {
+                unknown: `this -c payload cannot be read (${reading.reasons[0] ?? 'a construct the lexer does not model'}): ${payload.value}`,
+            },
+        ];
+    }
+    return resolveScriptPrograms(reading.commands, dialect).flatMap((entry) => entry.positions);
+}
+/**
+ * `watch [options] command…` joins its trailing words with a space and runs
+ * them via a shell, exactly the way `eval` does — except with `-x`/`--exec`,
+ * which execs the argv directly, no shell, no joining, read the ordinary way.
+ */
+function resolveWatchArgs(rest, dialect) {
+    const usesExec = rest.some((w) => LITERAL(w) && (w.value === '-x' || w.value === '--exec'));
+    const skipped = skipOptions(rest, new Set([
+        '-d',
+        '--differences',
+        '-p',
+        '--precise',
+        '-t',
+        '--no-title',
+        '-b',
+        '--beep',
+        '-e',
+        '--errexit',
+        '-g',
+        '--chgexit',
+        '-c',
+        '--color',
+        '-x',
+        '--exec',
+    ]), new Set(['-n', '--interval']));
+    if ('unknown' in skipped)
+        return [{ unknown: skipped.unknown }];
+    const afterOptions = 'rest' in skipped ? skipped.rest : [];
+    if (afterOptions.length === 0)
+        return [];
+    return usesExec ? resolveChain(afterOptions, dialect) : resolveEvalPayload(afterOptions, dialect);
+}
+/** `find`'s own `-exec`/`-execdir`/`-ok`/`-okdir` clauses, each an independent program position. */
+function findExecPositions(words, dialect) {
+    const positions = [];
+    for (let i = 0; i < words.length; i += 1) {
+        const w = words[i];
+        if (!LITERAL(w) || !/^-(?:exec|execdir|ok|okdir)$/.test(w.value))
+            continue;
+        const clauseStart = i + 1;
+        let k = clauseStart;
+        while (k < words.length) {
+            const term = words[k];
+            if (LITERAL(term) && (term.value === ';' || term.value === '+'))
+                break;
+            k += 1;
+        }
+        const clause = words.slice(clauseStart, k);
+        if (clause.length === 0) {
+            positions.push({ unknown: `find's ${w.value} clause has no program` });
+        }
+        else {
+            // find execs the entire argv after -exec, including any re-exec
+            // wrappers. Inspecting only its first word would mistake `env` for
+            // the program and miss a dynamic name further into the clause.
+            for (const position of resolveChain(clause, dialect)) {
+                if (position.word && LITERAL(position.word) && position.word.value.includes('{}')) {
+                    positions.push({
+                        unknown: `find's own \`{}\` placeholder stands for the program, not a name in the line`,
+                    });
+                }
+                else {
+                    positions.push(position);
+                }
+            }
+            // The outer lexer only sees `find`, so it cannot read a shell -c
+            // payload inside this clause. Read it here with the same wrapper
+            // and shell-option grammar the lexer uses for a top-level shell.
+            const nested = nestedShellCommand(clause);
+            if (nested !== null) {
+                if ('opaque' in nested) {
+                    positions.push({ unknown: nested.opaque });
+                }
+                else if (nested.shell === 'zsh' || nested.shell === 'ksh' || nested.shell === 'mksh') {
+                    positions.push({ unknown: `nested ${nested.shell} is not modeled` });
+                }
+                else if (LITERAL(nested.payload) && nested.payload.value.includes('{}')) {
+                    positions.push({
+                        unknown: 'find substitutes `{}` into this shell payload before it runs',
+                    });
+                }
+                else {
+                    positions.push(...resolveDashCPayload(nested.payload, nested.shell === 'bash' ? 'bash' : 'sh'));
+                }
+            }
+        }
+        i = k;
+    }
+    return positions;
+}
+/**
+ * Every position in `command` where a program is actually exec'd: the
+ * (possibly re-exec-wrapped) head, and, for `find`, each `-exec`-family
+ * clause's own head. Empty for a command with no words at all. `dialect` is
+ * the shell that will run the line — needed only to read a literal `eval`
+ * payload the same way its own commands would be.
+ */
+export function programPositions(command, dialect) {
+    const head = command.words[command.assignments];
+    if (head === undefined)
+        return [];
+    const positions = [
+        ...resolveChain(command.words.slice(command.assignments), dialect),
+    ];
+    for (const position of positions.slice()) {
+        if (!position.word || !LITERAL(position.word) || basename(position.word.value) !== 'find')
+            continue;
+        const index = command.words.indexOf(position.word);
+        if (index >= 0)
+            positions.push(...findExecPositions(command.words.slice(index + 1), dialect));
+    }
+    return positions;
+}
+/** Variables whose value governs how a LATER literal program name resolves to a binary or to code. */
+export const DYNAMIC_RESOLUTION_VARIABLES = new Set([
+    'PATH',
+    'LD_PRELOAD',
+    'LD_LIBRARY_PATH',
+    'BASH_ENV',
+    'ENV',
+    'IFS',
+]);
+function assignsPoisoningVariable(words) {
+    for (const word of words) {
+        const name = assignmentName(word);
+        if (name !== null && DYNAMIC_RESOLUTION_VARIABLES.has(name))
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether `command`'s OWN leading assignment (`PATH=x prog`) sets one of
+ * {@link DYNAMIC_RESOLUTION_VARIABLES} — which affects only `prog`'s own
+ * position, the way a real command-prefix assignment is scoped to that one
+ * invocation and does not leak to later commands. A caller iterating a
+ * whole script applies this to THIS command's own {@link programPositions}.
+ */
+export function hasPoisoningPrefix(command) {
+    return assignsPoisoningVariable(command.words.slice(0, command.assignments));
+}
+/**
+ * Whether `command` sets one of {@link DYNAMIC_RESOLUTION_VARIABLES} for
+ * every command AFTER it in the same script: an `export NAME=value` (or a
+ * bare re-export, `export NAME`, of an already-set one), or a standalone
+ * assignment with no trailing command (`PATH=x` alone), both of which are
+ * real, persisting shell-variable assignments rather than a one-call
+ * prefix. A caller iterating a whole script applies this to every command
+ * that follows, not to `command` itself: a literal `ls` after either one
+ * cannot be trusted to resolve to what its text says, since which binary
+ * it runs — or what code a shell reads on startup (`BASH_ENV`, `ENV`) —
+ * depends on these variables' runtime value.
+ */
+export function poisonsLaterCommands(command) {
+    const head = command.words[command.assignments];
+    if (head === undefined)
+        return hasPoisoningPrefix(command);
+    if (!LITERAL(head))
+        return false;
+    const args = command.words.slice(command.assignments + 1);
+    if (head.value === 'export') {
+        // `export -n NAME` REMOVES the export attribute — the opposite of
+        // poisoning — for every name in the same invocation; bash reads it
+        // once for the whole command, not per name.
+        if (args.some((w) => LITERAL(w) && w.value === '-n'))
+            return false;
+        return args.some((arg) => namesPoisoningVariable(arg));
+    }
+    if (head.value === 'declare' || head.value === 'typeset') {
+        // `declare -x`/`typeset -x` (and a cluster with it, `-gx`, `-xg`, …,
+        // but never `+x`, which removes the attribute) marks a name exported,
+        // the same as `export`. `declare` without `-x` only sets a local
+        // attribute (type, read-only, …) and does not export anything.
+        const exports = args.some((w) => LITERAL(w) && /^-[a-zA-Z]*x[a-zA-Z]*$/.test(w.value));
+        if (!exports)
+            return false;
+        return args.some((arg) => {
+            if (LITERAL(arg) && /^[-+]/.test(arg.value))
+                return false; // an option, not a name
+            return namesPoisoningVariable(arg);
+        });
+    }
+    return false;
+}
+/**
+ * `assignmentName`'s prefix, or the word's own literal value for a bare
+ * name (`export PATH`, `declare -x PATH`) — read regardless of whether the
+ * word's VALUE expands, since only the `NAME` portion (always literal in an
+ * assignment word) or the bare word's exact text decides which variable is
+ * named.
+ */
+function namesPoisoningVariable(arg) {
+    const name = assignmentName(arg) ?? (LITERAL(arg) ? arg.value : null);
+    return name !== null && DYNAMIC_RESOLUTION_VARIABLES.has(name);
+}
+/**
+ * The `unknown` position a command's own program name becomes once
+ * {@link hasPoisoningPrefix} or an earlier {@link poisonsLaterCommands} is
+ * true for it, in place of whatever {@link programPositions} would
+ * otherwise resolve — a literal name is no longer trustworthy once the
+ * environment it resolves against is unknown.
+ */
+export function poisonedProgramPosition() {
+    return {
+        unknown: 'PATH, LD_PRELOAD, LD_LIBRARY_PATH, BASH_ENV, ENV or IFS was set earlier in this line, so a literal program name here cannot be trusted to resolve to what its text says',
+    };
+}
+/**
+ * {@link programPositions} for every command a script reads, in order,
+ * threading {@link hasPoisoningPrefix} and {@link poisonsLaterCommands}
+ * through so a literal program name after an earlier `PATH=`, `export
+ * PATH=`, … comes back {@link poisonedProgramPosition} rather than trusted
+ * at face value. This is the one loop the live `bash` tool's escalation, the
+ * scheduled-run floor and `verifyScheduledScript` would otherwise each write
+ * for themselves — exactly the duplication that let `env $(echo git) push`
+ * pass one consumer's check and not another's.
+ */
+export function resolveScriptPrograms(commands, dialect) {
+    let poisoned = false;
+    const out = [];
+    for (const command of commands) {
+        const selfPoisoned = poisoned || hasPoisoningPrefix(command);
+        const positions = selfPoisoned
+            ? [poisonedProgramPosition()]
+            : programPositions(command, dialect);
+        out.push({ command, positions });
+        if (poisonsLaterCommands(command))
+            poisoned = true;
+    }
+    return out;
+}
+/**
+ * Why a command line's own program name is not knowable ahead of running
+ * it, in one call: the line itself, unread whole (`bash -c "$X"`'s outer
+ * line is opaque — the lexer could not follow the payload at all, which is
+ * a stronger statement than any one position being unresolvable), or a
+ * specific command's unresolvable position via {@link resolveScriptPrograms}.
+ * The live `bash` tool's escalation (`executor.ts`) calls this directly
+ * rather than re-implementing it, so its own tests import the same function
+ * they are testing instead of a hand-written mirror that can drift from it.
+ */
+export function unknownProgramInLine(value, dialect) {
+    const reading = lexShellCommandLine(value, { dialect });
+    if (reading.opaque || !reading.complete) {
+        return `${value}: the line cannot be read (${reading.reasons[0] ?? 'a construct the lexer does not model'}), so its program cannot be verified`;
+    }
+    for (const { command, positions } of resolveScriptPrograms(reading.commands, dialect)) {
+        for (const position of positions) {
+            if (position.unknown !== undefined)
+                return `${command.text}: ${position.unknown}`;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=program.js.map