@sema-agent/core 7.44.0 → 7.46.0

package/dist/tools/fs/removal-targets.js

@@ -0,0 +1,236 @@
+import { planShellReads } from "./shell-read-plan.js";
+import { literalTextOf } from "../../shell/lex.js";
+import { createShellReadEstablisher, establishShellReadsLexically } from "./shell-read-establish.js";
+import { isAbsolutePathForm, isWinFormPath, normalizeAbsPathLexically } from "./safety.js";
+import { reentryText } from "./shell-reentry-text.js";
+import { bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
+import { programArgs } from "./shell-read-write-targets.js";
+import { implementationsOf, programRow, runsShellText, selectedOptions, writeReadings } from "./program-read-model.js";
+import { inlineUntrusted } from "../../core/untrusted-text.js";
+export const SHELL_REMOVAL_COMMANDS = Object.freeze(["rm", "rmdir"]);
+const REMOVAL_COMMAND_SET = new Set(SHELL_REMOVAL_COMMANDS);
+function removalKey(path) {
+    let k = normalizeAbsPathLexically(path.normalize("NFC")).replace(/\\/g, "/").toLowerCase();
+    k = k.replace(/(?:\/+\*+)+\/*$/, "");
+    const drive = driveOf(path, k);
+    let rest = k.slice(drive.length);
+    if (rest === "")
+        rest = "/";
+    if (rest.length > 1)
+        rest = rest.replace(/\/+$/, "");
+    return drive + rest.replace(/^\/private\/(etc|var|tmp|home)(?=\/|$)/, "/$1");
+}
+function driveOf(path, key) {
+    return isWinFormPath(path) && key.length >= 2 && key[1] === ":" ? key.slice(0, 2) : "";
+}
+export function dangerousRemovalOf(path, seat) {
+    if (!isAbsolutePathForm(path))
+        return undefined;
+    const k = removalKey(path);
+    const rest = k.slice(driveOf(path, k).length);
+    if (rest === "/" || /^\/\/[^/]+\/[^/]+$/.test(k))
+        return "filesystem_root";
+    if (seat.homes.some((h) => isAbsolutePathForm(h) && removalKey(h) === k))
+        return "home";
+    const prefix = k.endsWith("/") ? k : `${k}/`;
+    if (seat.workspace.some((w) => isAbsolutePathForm(w) && (removalKey(w) === k || removalKey(w).startsWith(prefix))))
+        return "workspace";
+    if (/^\/[^/]+$/.test(rest))
+        return "top_level";
+    return undefined;
+}
+function tildeNamesAHome(spelled) {
+    const m = /^~([^/]*)(\/.*)?$/.exec(spelled);
+    if (m === null)
+        return false;
+    const key = removalKey(`/~home${m[2] ?? ""}`);
+    return key === "/~home" || !key.startsWith("/~home/");
+}
+function removalKindOf(read, seat) {
+    const floors = read.established === "unestablishable" && read.candidate.bases === "unmodelled" ? read.spellings : [];
+    for (const view of [read.target, read.origin, ...floors]) {
+        const kind = view === undefined ? undefined : dangerousRemovalOf(view, seat);
+        if (kind !== undefined)
+            return kind;
+    }
+    return read.established === "unestablishable" && tildeNamesAHome(read.candidate.spelled) ? "home" : undefined;
+}
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const NAME_BINDERS = new Set(["unset", "local", "declare", "typeset", "readonly", "export", "read"]);
+function bindingsOf(plan) {
+    const out = new Map();
+    const bind = (name, value) => {
+        out.set(name, [...(out.get(name) ?? []), value]);
+    };
+    for (const segment of plan.segments) {
+        for (const w of segment.argv)
+            if (w.assignment !== undefined)
+                bind(w.assignment.name, w.assignment.settlesWholeName ? literalTextOf(w.assignment.value.pieces) : undefined);
+        const [head, name] = segment.argv;
+        if ((head?.folded === "for" || head?.folded === "select") && name !== undefined && NAME.test(name.folded)) {
+            const at = segment.argv.findIndex((w, i) => i > 1 && w.folded === "in");
+            const words = at < 0 ? [undefined] : segment.argv.slice(at + 1).map((w) => literalTextOf(w.pieces));
+            for (const v of words.length > 0 ? words : [undefined])
+                bind(name.folded, v);
+        }
+        if (head !== undefined && NAME_BINDERS.has(head.folded))
+            for (const w of segment.argv.slice(1))
+                if (w.assignment === undefined && NAME.test(w.folded))
+                    bind(w.folded, undefined);
+    }
+    return out;
+}
+const BOUND_SPELLINGS_MAX = 64;
+function boundSpellingsOf(word, bindings) {
+    const named = word.pieces.filter((q) => q.literal === undefined);
+    if (named.length === 0 || !named.some((q) => q.expansion?.kind === "parameter" && q.expansion.name !== undefined && bindings.has(q.expansion.name)))
+        return undefined;
+    let spellings = [""];
+    for (const q of word.pieces) {
+        if (q.literal !== undefined) {
+            spellings = spellings.map((sp) => sp + q.literal);
+            continue;
+        }
+        const name = q.expansion?.kind === "parameter" && (q.expansion.body === undefined || q.expansion.body === q.expansion.name) ? q.expansion.name : undefined;
+        const values = name !== undefined ? bindings.get(name) : undefined;
+        if (name === undefined || values === undefined)
+            return { unreadable: q.expansion?.name ?? word.raw };
+        if (values.some((v) => v === undefined || (q.quotedBy === undefined && /\s/.test(v))))
+            return { unreadable: name };
+        spellings = spellings.flatMap((sp) => values.map((v) => sp + v));
+        if (spellings.length > BOUND_SPELLINGS_MAX)
+            return { unreadable: name };
+    }
+    return { spellings };
+}
+function recursiveForce(row, args) {
+    return implementationsOf(row).some((view) => {
+        const selected = selectedOptions(view, args, "one-implementation");
+        return selected.some((o) => o.selects === "traversal") && selected.some((o) => o.mode === "forced");
+    });
+}
+export function removalFindingsOf(established, seat) {
+    const out = [];
+    const bindings = bindingsOf(established.plan);
+    for (const segment of established.plan.segments) {
+        const program = segment.verb?.basename;
+        const row = program !== undefined && REMOVAL_COMMAND_SET.has(program) ? programRow(program) : undefined;
+        if (program !== undefined && row !== undefined) {
+            const args = programArgs(segment);
+            const spelled = args.map((w) => w.spelled);
+            const removed = new Set(writeReadings(row, spelled).flatMap((r) => r.written.map((w) => w.at)));
+            const options = new Set(args.filter((_, at) => !removed.has(at)).map((w) => w.raw));
+            for (const read of established.reads.get(segment) ?? []) {
+                if (read.candidate.face !== "write" || options.has(read.candidate.raw))
+                    continue;
+                const kind = removalKindOf(read, seat);
+                if (kind !== undefined) {
+                    out.push({ guard: "dangerous_delete", kind, program, operand: read.candidate.raw, target: read.target ?? read.candidate.floorSpelled ?? read.candidate.spelled });
+                    continue;
+                }
+                if (read.established !== "unestablishable")
+                    continue;
+                const word = segment.argv.find((w) => w.raw === read.candidate.raw);
+                const bound = word === undefined ? undefined : boundSpellingsOf(word, bindings);
+                if (bound === undefined)
+                    continue;
+                if ("unreadable" in bound) {
+                    if (recursiveForce(row, spelled))
+                        out.push({ guard: "unverifiable_delete", program, operand: read.candidate.raw, name: bound.unreadable });
+                    continue;
+                }
+                const bases = segment.bases === "unmodelled" ? (read.candidate.floorBases ?? []) : segment.bases;
+                for (const spelled of bound.spellings) {
+                    const views = isAbsolutePathForm(spelled) ? [spelled] : bases.map((base) => `${base}/${spelled}`);
+                    for (const view of views) {
+                        const hit = dangerousRemovalOf(view, seat);
+                        if (hit === undefined)
+                            continue;
+                        out.push({ guard: "dangerous_delete", kind: hit, program, operand: read.candidate.raw, target: normalizeAbsPathLexically(view) });
+                        break;
+                    }
+                }
+            }
+        }
+        const script = runtimeScriptOf(segment);
+        if (script !== undefined && program !== undefined)
+            out.push({ guard: "dangerous_delete", kind: "runtime_script", program, operand: script, target: script });
+        for (const nested of segment.nested) {
+            const sub = established.nested.get(nested);
+            if (sub !== undefined)
+                out.push(...removalFindingsOf(sub, seat));
+        }
+    }
+    return out;
+}
+function runtimeScriptOf(segment) {
+    const program = segment.verb;
+    if (segment.reentry !== "shell" || program === undefined || !runsShellText(program.basename))
+        return undefined;
+    const at = segment.argv.findIndex((w) => w.folded === program.name);
+    const MARK = "\u0000";
+    const words = at < 0 ? [] : segment.argv.slice(at + 1).map((w) => literalTextOf(w.pieces) ?? `${MARK}${w.raw}`);
+    const texts = [reentryText(program.basename, words), ...(segment.stdin ?? []).map((s) => reentryText(program.basename, words, s.literal ?? `${MARK}${s.from}`))];
+    const text = texts.find((t) => t?.includes(MARK) === true);
+    return text === undefined ? undefined : text.split(MARK).join("");
+}
+export function planRunsRemoval(plan) {
+    return plan.segments.some((s) => (s.verb !== undefined && REMOVAL_COMMAND_SET.has(s.verb.basename)) || runtimeScriptOf(s) !== undefined || s.nested.some(planRunsRemoval));
+}
+const DANGEROUS_REMOVAL_SENTENCE = {
+    filesystem_root: (p, t) => `\`${p}\` would remove the filesystem root (${t})`,
+    home: (p, t) => `\`${p}\` would remove a home directory (${t})`,
+    workspace: (p, t) => `\`${p}\` would remove a workspace directory — the task root, the working directory or an additional working directory — or one of its ancestors (${t})`,
+    top_level: (p, t) => `\`${p}\` would remove a top-level system directory (${t})`,
+    runtime_script: (p, t) => `\`${p}\` runs a script built only when the command runs (${t}), and it may remove the filesystem root, a home directory or the task's directories before anyone can read it`,
+};
+function verdictOf(findings) {
+    for (const f of findings)
+        if (f.guard === "dangerous_delete")
+            return { guard: f.guard, text: DANGEROUS_REMOVAL_SENTENCE[f.kind](f.program, inlineUntrusted(f.target, 200)) };
+    for (const f of findings)
+        if (f.guard === "unverifiable_delete")
+            return { guard: f.guard, text: `\`${f.program}\` recursive+force target ${inlineUntrusted(f.operand, 200)} takes ${f.name}'s value, which this command sets in a form the guard cannot read (an expansion, an unset or bare declaration, a \`read\`, a loop over unread words) — the deleted path cannot be verified from this command` };
+    return undefined;
+}
+const REMOVAL_RESOLVE_TIMEOUT_MS = 10_000;
+export function removalReadingOf(command, req, seat) {
+    const homeDir = seat?.env?.homeDir;
+    const cwd = req.cwd ?? req.root ?? "";
+    const roots = req.root !== undefined ? [req.root] : cwd !== "" ? [cwd] : [];
+    const boundary = { roots, ...(cwd !== "" ? { cwd } : {}), ...(homeDir !== undefined ? { homeDir } : {}) };
+    const plan = planShellReads(command, { readers: new Set(bashClassifyDefaultAllow()), cwd, roots, ...(homeDir !== undefined ? { homeDir } : {}) });
+    if (!planRunsRemoval(plan))
+        return undefined;
+    return {
+        async judge(signal) {
+            const env = seat?.env;
+            const resolved = env !== undefined && homeDir !== undefined ? await resolvedOrUndefined(env.canonicalPath(homeDir, signal), signal) : undefined;
+            const removalSeat = {
+                homes: [...(homeDir !== undefined ? [homeDir] : []), ...(resolved !== undefined && resolved.ok ? [resolved.value] : [])],
+                workspace: [...(req.root !== undefined ? [req.root] : []), ...(req.cwd !== undefined ? [req.cwd] : []), ...(seat?.additionalRoots?.() ?? [])],
+            };
+            const lexical = removalFindingsOf(establishShellReadsLexically(plan, boundary), removalSeat);
+            if (lexical.some((f) => f.guard === "dangerous_delete") || env === undefined || roots.length === 0)
+                return verdictOf(lexical);
+            const established = await resolvedOrUndefined(createShellReadEstablisher(env, roots, { rootsCanonical: true }).establish(plan, boundary, signal), signal);
+            return verdictOf(established === undefined ? lexical : [...removalFindingsOf(established, removalSeat), ...lexical]);
+        },
+    };
+}
+async function resolvedOrUndefined(leg, signal) {
+    let timer;
+    try {
+        return await Promise.race([
+            leg.catch(() => undefined),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(undefined), REMOVAL_RESOLVE_TIMEOUT_MS);
+                signal?.addEventListener("abort", () => resolve(undefined), { once: true });
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}

package/dist/tools/fs/safety.d.ts

@@ -129,6 +129,9 @@ export interface FsViolation {
  * lands it outside every POSIX/drive root, i.e. a location the working directory does not contain.
  */
 export declare function isAbsolutePathForm(p: string): boolean;
+/** Does this absolute spelling name the opening process's STANDARD INPUT (`/dev/stdin`, `/dev/fd/0`, `/proc/<pid>/fd/0`),
+ *  folded lexically first (`/dev/./stdin`, `/dev//fd/0`)? */
+export declare function namesStandardInput(path: string): boolean;
 /**
  * Windows-FAMILY spelling of a path (extracted here so {@link canonicalizeTarget} judges
  * the UNC family by the same rule): drive-rooted (`C:\…`/`C:/…`), UNC-backslash (`\\host\share`), or a

package/dist/tools/fs/safety.js

@@ -3,6 +3,7 @@ import { readDenySentence } from "./read-deny.js";
 import { homeViewsOf } from "./read-deny-home.js";
 import { sliceHeadSafe } from "../../core/surrogate-safe-slice.js";
 import { pathTargetValue, protectivePathTargetOf } from "../../core/tool-registry.js";
+import { readPathViews } from "../../core/effective-path-target.js";
 import { withGateTimeout, DEFAULT_GATE_AWAIT_TIMEOUT_MS } from "../../core/gate-bounded-await.js";
 import { thrownText } from "../../core/thrown-value.js";
 export function fileArgPath(args) {
@@ -41,6 +42,10 @@ const BLOCKED_DEVICE_PATHS = new Set([
 function isProcStdioFd(key) {
     return key.startsWith("/proc/") && (key.endsWith("/fd/0") || key.endsWith("/fd/1") || key.endsWith("/fd/2"));
 }
+export function namesStandardInput(path) {
+    const k = path.startsWith("/") ? normalizeAbsPathLexically(path) : "";
+    return k === "/dev/stdin" || k === "/dev/fd/0" || (k.startsWith("/proc/") && k.endsWith("/fd/0"));
+}
 const PROC_SENSITIVE_SUFFIXES = ["/environ", "/cmdline", "/auxv", "/maps", "/mem", "/stat"];
 function isProcSensitiveFile(key) {
     return key.startsWith("/proc/") && PROC_SENSITIVE_SUFFIXES.some((suf) => key.endsWith(suf));
@@ -457,7 +462,8 @@ function within(rootCanonical, p) {
     return pN.identity.startsWith(rootN.identity.endsWith(SEP) ? rootN.identity : rootN.identity + SEP);
 }
 export async function resolveKey(env, rootCanonical, path, signal, baseCwd, additionalRoots, exactFileReadExemption, readDeny, containmentFace) {
-    const canon = await canonicalizeTarget(env, path, signal, pathFamilyOf({ root: rootCanonical }), baseCwd);
+    const views = await readPathViews(env, path, baseCwd ?? rootCanonical, { root: rootCanonical, ...(baseCwd !== undefined ? { cwd: baseCwd } : {}) }, signal, { hops: readDeny !== undefined });
+    const canon = views.canonical ?? (await canonicalizeTarget(env, path, signal, pathFamilyOf({ root: rootCanonical }), baseCwd));
     if (!canon.ok)
         return { ok: false, violation: { code: "invalid", message: canon.message } };
     const key = canon.key;
@@ -466,8 +472,9 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
         return { ok: false, violation: { code: "invalid", message: `path "${path}" is a blocked device/special file (reading it can hang the process); refused.` } };
     }
     if (readDeny !== undefined) {
-        const judged = { aliasResolved: canon.aliasResolved === true };
-        let hit = readDeny.matchTarget(key, lexicalViewOf(path, baseCwd ?? rootCanonical), judged);
+        const judged = { aliasResolved: canon.aliasResolved === true, hops: views.hops };
+        const lexical = views.lexical?.kind === "path" ? spellingOfIdentity(views.lexical.identity, pathFamilyOf({ root: rootCanonical })) : undefined;
+        let hit = readDeny.matchTarget(key, lexical, judged);
         if (hit === null) {
             const homeView = await homeViewsOf(env, readDeny, signal).of(key);
             if (homeView !== undefined)

package/dist/tools/fs/shell-read-argv.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The candidates ONE program's words hand the read station — the program read model's rows read word by word: a
+ * listed reader's operands and option-value slots, an unlisted program's words (its own row read where it has one,
+ * read the speculative way where it has none), a subcommand's words by the subcommand's row, a module's program text,
+ * an assignment word's value. `shell-read-plan.ts` threads the segments and their bases; this module is what one
+ * segment's argv offers.
+ */
+import { type LexedWord } from "../../shell/lex.js";
+import { type Read } from "./shell-read-word.js";
+import { type BindingTable, type BoundValue } from "./shell-read-bindings.js";
+import { subcommandOf, type ArgRole, type ProgramRow } from "./program-read-model.js";
+import type { ReadCandidate, ReadCandidateProvenance } from "./shell-read-plan.js";
+/** A candidate before the threading fills its bases. `alternatives`: the other spellings its word may expand to (a name
+ *  bound to several values) — one candidate each once the segment's reads are read. */
+export type Bare = Omit<ReadCandidate, "bases"> & {
+    readonly alternatives?: readonly string[];
+    readonly floors?: readonly BoundValue[];
+};
+/** What reading a segment's words found beside its candidates. */
+export interface WordContext {
+    /** The names at this segment. */
+    readonly table: BindingTable;
+    /** Shell text the arithmetic evaluator runs (a substitution in a subscript it evaluates): the segment re-enters it. */
+    readonly reentered: string[];
+    /** Program text the station does not read — inline text in a language that may open files, or a program read from
+     *  standard input: why the segment's reads are not established. */
+    programText?: string;
+    /** Some program text was found in a slot (whether or not it may open files). */
+    programTextSeen: boolean;
+}
+/** The subcommand whose row says how ITS words name paths (operands or a traversal of its own), or `undefined`: a
+ *  subcommand whose row states only its grammar — its message slots, read by {@link messageWords} — leaves its words to
+ *  the program's own reading. */
+export declare function pathSubcommandOf(row: ProgramRow | undefined, args: readonly string[]): ReturnType<typeof subcommandOf>;
+/** The sentence of inline program text the station does not read. */
+export declare const programTextSentence: (language: string) => string;
+/** One candidate without its bases (filled by the threading pass): the word's spelling — or `spelled`, a caller's
+ *  reading of PART of it (an option payload, a `key=value` value) — with the word's own expansion facts. A word whose
+ *  names may hold several values offers each as its whole spelling; a PART of such a word is not followed through them
+ *  (it is unresolvable). */
+export declare function bare(r: Read, provenance: ReadCandidateProvenance, spelled?: string): Bare;
+/** The reads one value of a declared role hands over: a candidate per file it names, or — a value the program expands
+ *  past the listed bound — the word itself, unresolvable. A mount source is a read the daemon makes of the whole tree
+ *  under it (a read and a traversal root); an object path
+ *  `<rev>:<path>` offers the word as a path and the `<path>` it spells to the deny judge; program text is never a path
+ *  ({@link programTextReads}). `alsoOperand`: the walk read the option past the first operand, where the program may
+ *  have stopped reading options — a path role is still offered (more candidates), but no program text is read there:
+ *  the word is the operands' (the script's own argument), as the program's delivery reading says. */
+export declare function roleReads(r: Read, provenance: ReadCandidateProvenance, value: string, role: ArgRole, globs: "expanded" | "literal", ctx: WordContext, alsoOperand?: boolean): Bare[];
+/**
+ * The candidates a `NAME=value` word hands the judge, both facts about its VALUE (the word is a path to nobody):
+ * what path it NAMES, and what the text cannot SETTLE — placed as an operand is wherever an environment value
+ * names ONE path (a leading tilde against the declared home; a `:` joins a second). Where the text runs nothing able
+ * to open a file, {@link planShellReads} drops them: the value names a path to nobody.
+ *
+ * Bash applies its assignment-word expansion to such a word even when it is an ARGUMENT to a simple command, so
+ * the program receives `NAME=<expanded value>`, and a program that reads its value as a path (`dd if=…`, a build
+ * or tool variable, a launcher's environment word) opens what the value names. Two facts of the lexer's
+ * {@link AssignmentFact} are read: a tilde the shell EXPANDS in the value (at its start and after each `:`, where
+ * unquoted — `value.expansions`) leaves the path unsettled, and the append form (`NAME+=value`) names `<whatever
+ * NAME held>` + value, so the whole value is not in the text — but the text it appends IS, and an unset or empty
+ * NAME makes it the whole value, so it is a candidate too. A value that is a substitution is the nested plan
+ * its body already is, never a candidate of its own text (its placeholder is not a path).
+ */
+export declare function pushAssignment(reads: Bare[], w: LexedWord, provenance: ReadCandidateProvenance): void;
+/** Every word of a segment whose program's grammar this parser does not model, from `from` onward: option
+ *  payloads and path-shaped option words included, the launcher chain's own words excluded, a program declared
+ *  to open no path operand handing only the environment words in front of it. A program with NO row is read the
+ *  speculative way: every word is still handed over, but the filesystem decides it
+ *  ({@link ReadCandidate.speculative}). */
+export declare function unlistedWords(reads: Bare[], toks: readonly Read[], from: number, launcherIndices: ReadonlySet<number>, provenance: ReadCandidateProvenance, ctx: WordContext, program?: {
+    readonly index: number;
+    readonly basename: string;
+}): void;
+/** The positional operands and declared option-value slots of a listed reader — the program read model's argv walk,
+ *  one candidate per word the program may open, plus the traversal roots of a recursive form. A subcommand's words
+ *  are read by its own row; the words a module takes as its program text are program text. */
+export declare function listedVerbCandidates(name: string, argReads: readonly Read[], reads: Bare[], ctx: WordContext): void;
+/** The subscript of a variable-name word (`a[…]`), as the arithmetic text that is evaluated; the empty text for a plain
+ *  name. */
+export declare function subscriptOnly(word: string): string;
+/** An assignment word's arithmetic: its own subscript (`a[$(…)]=1`, quoted or not — not for a builtin that takes the
+ *  name `asWritten`), and its value where the name carries the integer attribute (`declare -i n; n='a[$(…)]'`, bash's
+ *  own `OPTIND` / `RANDOM` / …). */
+export declare function assignmentArithmetic(w: LexedWord, integer: boolean, ctx: WordContext, asWritten?: boolean): void;