approval-md 0.4.6 → 0.4.7

package/dist/src/cli/hook.d.ts

@@ -1281,6 +1281,35 @@ export declare const POST_TOOL_CODES: readonly [
 export type PostToolCode = (typeof POST_TOOL_CODES)[number];
 /** The environment variable that turns the sandbox requirement on (APRV-193). */
 export declare const REQUIRE_SANDBOX_ENV = "APPROVAL_HOOK_REQUIRE_SANDBOX";
+/**
+ * The fixed remedy a `fetch-output-unknown` refusal carries when a `$`-first
+ * word in curl's or wget's option slot caused it (0.4.7, EDGEOS-BLOCK).
+ *
+ * Core 0.4.6 (APRV-511) holds `curl "${BASE:-https://h}/x"`: the expansion
+ * could be `-o <organ path>`, so the download's output is unknown, the class is
+ * `policy.core`, and a policy that reserves that class denies outright. The
+ * refusal said why and nothing about the shape that runs. The same word as
+ * `--url`'s value sits in a value slot, where curl reads it as the URL whatever
+ * it starts with, and classifies by its method. wget has no `--url`, so the
+ * line names curl for both.
+ *
+ * Text only: the class, the rule and the code are unchanged, and nothing here
+ * widens a verdict.
+ */
+export declare const FETCH_DOLLAR_WORD_REMEDY = "Remedy: a word that starts with `$` stands where curl and wget read options, so its value could turn it into `-o <path>` and the download's output cannot be known. If that word is the URL, pass it as the value of `--url` (`curl --url \"$VAR/...\"`), which keeps the output known; wget has no `--url`, so use `curl --url` instead.";
+/**
+ * {@link FETCH_DOLLAR_WORD_REMEDY}, prefixed with a space, when a segment that
+ * earned `reserved` did so by rule `fetch-output-unknown` on a word that
+ * starts with `$`; otherwise the empty string, so every other cause of the rule
+ * (an unknown option, a config source, an ambiguous prefix, an unplaceable
+ * output value) keeps its refusal byte for byte.
+ *
+ * `fetchOutputs` reports the first unknowable word verbatim, and only its
+ * option-slot test reports a positional word; every other cause reports the
+ * option as spelled, which starts with `-`. So a bound path starting with `$`
+ * is exactly the `$`-first option-slot cause.
+ */
+export declare function fetchOutputRemedy(segments: readonly ClassifiedSegment[] | undefined, reserved: string): string;
 /**
  * Must this command have been written `approval sandbox -- …`? (APRV-193.)
  *

package/dist/src/cli/hook.js

@@ -2409,6 +2409,109 @@ const NON_OPENING_BINS = new Set([
 ]);
 /** Of those, the ones whose words reach a pipe's next command as text. */
 const PRINTING_BINS = new Set(["echo", "printf"]);
+/**
+ * A first character the shell may still expand into something else (a
+ * parameter, a substitution, a tilde, an escape, a glob or extended glob, a
+ * brace list, zsh's `=cmd`, `^`, `<N-M>` and `(a|b)` patterns, a process
+ * substitution), so the value curl finally receives may open with `@`. A
+ * leading `-` is here too: a word this walk takes for a value may be an option
+ * curl reads instead (`-K.env`), because the walk does not know every option
+ * that takes a value.
+ */
+const CURL_VALUE_UNKNOWN_OPENING = /^[\s\-$`~\\*?[\]{}()!+^<>=#%|&;'"]/u;
+/** Is this option value one curl (or wget) sends as written and never opens? */
+function curlValueSentAsWritten(value, opensFileWithAt) {
+    if (value.length === 0)
+        return false;
+    // curl reads `-H @FILE` as a file of headers and `--url @FILE` (8.13+) as a
+    // file of URLs. wget has no such spelling; the rule is the same anyway.
+    if (opensFileWithAt && value.startsWith("@"))
+        return false;
+    if (CURL_VALUE_UNKNOWN_OPENING.test(value))
+        return false;
+    // A `file:` URL opens a local file. Which file it reads is the network
+    // classifier's to say, never this pass's; such a value keeps the judgement
+    // it had, and a header that opens `file:` is judged with it, since the walk
+    // may have taken a positional URL for a header value.
+    return !/^file:/iu.test(value);
+}
+/**
+ * The curl and wget option values that are not file reads (EDGEOS-BLOCK,
+ * APRV-533), taken out of the argv the credential pass judges.
+ *
+ * Every resident box runs its terminal in `$HERMES_HOME`, which holds
+ * credential material, and the pass reads a word with an unexpanded `$` as a
+ * read of the directory it may land in. So a header carrying `$EDGEOS_API_KEY`
+ * and a `--url "${EDGEOS_API_BASE:-…}/…"` were each a credential read there.
+ * curl opens neither: it reads a header from a file only for `-H @FILE`, and a
+ * URL from a file only for `--url @FILE`. What is taken out:
+ *
+ * - curl's `-H`/`--header` value (separate, or attached as `-HVALUE`) and
+ *   wget's `--header` value (separate, or `--header=VALUE`), when it opens
+ *   with neither `@` nor a character the shell may still expand
+ *   ({@link CURL_VALUE_UNKNOWN_OPENING}). `-H "$X"` and `-H @"$F"` are judged
+ *   as before: the expansion may open with `@`.
+ * - curl's `--url` value under the same rule, and additionally only when it
+ *   holds no unexpanded span, or names a literal scheme other than `file:`
+ *   before its first one (`https://h/${P}`).
+ * - curl's `--url` value opening with an unexpanded span moves to
+ *   `spannedUrls`, which the caller judges as the path an `@` or `file:`
+ *   expansion would read; a value whose last component is the span (`"$U"`)
+ *   stays a read of the working directory, as before.
+ *
+ * Everything else stays: every other option (`-d`, `--data*`, `-F`, `-T`,
+ * `-K`, `-o`, `-b`, `-c`, `--cacert`, `--cert`, `--key`, `-E`,
+ * `--netrc-file`, `--proxy-header`, `--variable`, …), a short-option cluster
+ * ending in `H` (`-sH`), curl's `--header=…` (curl takes no `=` spelling), and
+ * every word after `--`. The pure classifier's text rule
+ * ({@link credentialReadWords}) still reads every one of these words.
+ */
+function curlValuesNotRead(bin, args) {
+    if (bin !== "curl" && bin !== "wget")
+        return { args, spannedUrls: [] };
+    const curl = bin === "curl";
+    const kept = [];
+    const spannedUrls = [];
+    for (let at = 0; at < args.length; at += 1) {
+        const arg = args[at];
+        if (arg === "--") {
+            kept.push(...args.slice(at));
+            break;
+        }
+        const next = args[at + 1];
+        if ((curl ? arg === "-H" || arg === "--header" : arg === "--header") && next !== undefined) {
+            kept.push(arg);
+            if (curlValueSentAsWritten(next, true))
+                at += 1;
+            continue;
+        }
+        if (curl && arg.startsWith("-H") && arg.length > 2) {
+            if (!curlValueSentAsWritten(arg.slice(2), true))
+                kept.push(arg);
+            continue;
+        }
+        if (!curl && arg.startsWith("--header=")) {
+            if (!curlValueSentAsWritten(arg.slice("--header=".length), true))
+                kept.push(arg);
+            continue;
+        }
+        if (curl && arg === "--url" && next !== undefined) {
+            kept.push(arg);
+            const span = next.search(/[$`]/u);
+            const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):/u.exec(next);
+            if (span === 0) {
+                spannedUrls.push(next);
+                at += 1;
+            }
+            else if (curlValueSentAsWritten(next, true) && (span === -1 || (scheme !== null && scheme[0].length <= span))) {
+                at += 1;
+            }
+            continue;
+        }
+        kept.push(arg);
+    }
+    return { args: kept, spannedUrls };
+}
 /**
  * Every existing path a glob matches, any component of it a pattern
  * (APRV-522), or `null` when a directory on the way cannot be listed or the
@@ -2673,7 +2776,9 @@ export function credentialReadLandings(command, cwd, env = process.env) {
                 return steered.some((tail) => words.some((segments) => steeredReadCouldNameCredential(tail, segments, hermesNames)));
             };
             // `steeredToo` is false only for git's verb word, which git never opens.
-            const judgeOne = (word, recursive, steeredToo = true) => {
+            // `homeSpelled` is false only for a curl `--url` value that opens with an
+            // unexpanded span ({@link curlValuesNotRead}); see its use below.
+            const judgeOne = (word, recursive, steeredToo = true, homeSpelled = true) => {
                 // `$PWD` is the directory the segment runs in, which is each of `cwds`.
                 const pwdRef = /^\$(?:\{PWD\}|PWD)(?=\/|$)/u;
                 if (pwdRef.test(word)) {
@@ -2682,7 +2787,7 @@ export function credentialReadLandings(command, cwd, env = process.env) {
                         return;
                     }
                     for (const from of cwds)
-                        judgeOne(word.replace(pwdRef, from), recursive, steeredToo);
+                        judgeOne(word.replace(pwdRef, from), recursive, steeredToo, homeSpelled);
                     if (steeredToo && steered.length > 0 && steeredRead(word.replace(pwdRef, "."), recursive))
                         hit(word);
                     return;
@@ -2749,7 +2854,7 @@ export function credentialReadLandings(command, cwd, env = process.env) {
                         const lexical = resolvePathSegments(from, prefix);
                         for (const landed of new Set([lexical, canonicalPath(lexical), physicalLanding(from, prefix)])) {
                             if ((lastComponent && lands(landed, true)) ||
-                                landedSpellings(landed, rest, configuredHome).some(unresolvedReadCouldNameCredential)) {
+                                landedSpellings(landed, rest, homeSpelled ? configuredHome : null).some(unresolvedReadCouldNameCredential)) {
                                 hit(word);
                                 return;
                             }
@@ -2799,7 +2904,7 @@ export function credentialReadLandings(command, cwd, env = process.env) {
                         hit(physical);
                 }
             };
-            const judge = (word, recursive, steeredToo = true) => {
+            const judge = (word, recursive, steeredToo = true, homeSpelled = true) => {
                 // APRV-524 (review-b M1): a word holding the substitution sentinel is
                 // judged a second time with every sentinel removed. That is how the
                 // release before APRV-511 read it, its lexer adding nothing for a
@@ -2811,7 +2916,7 @@ export function credentialReadLandings(command, cwd, env = process.env) {
                 // name, and one after a glob that matches such a directory on disk are
                 // judged too. Both judgements only record, so the stricter stands.
                 if (word.includes(SUBSTITUTION_SENTINEL)) {
-                    judge(word.split(SUBSTITUTION_SENTINEL).join(""), recursive, steeredToo);
+                    judge(word.split(SUBSTITUTION_SENTINEL).join(""), recursive, steeredToo, homeSpelled);
                 }
                 const spellings = new Set();
                 for (const parameter of parameterSpellings(word)) {
@@ -2826,7 +2931,7 @@ export function credentialReadLandings(command, cwd, env = process.env) {
                         spellings.add(spelling);
                 }
                 for (const spelling of spellings)
-                    judgeOne(spelling, recursive, steeredToo);
+                    judgeOne(spelling, recursive, steeredToo, homeSpelled);
             };
             for (const target of shape.reads)
                 judge(target, false);
@@ -2838,7 +2943,10 @@ export function credentialReadLandings(command, cwd, env = process.env) {
             if (NON_OPENING_BINS.has(bin) && !(PRINTING_BINS.has(bin) && (feedsPipe || substituted)))
                 continue;
             const recursive = RECURSIVE_READERS.has(bin) || DIRECTORY_COPIERS.has(bin) || DIRECTORY_READING_BINS.has(bin);
-            const words = credentialReadWords(bin, shape.args);
+            // EDGEOS-BLOCK (APRV-533): the curl and wget option values the tool sends
+            // and never opens are not read words ({@link curlValuesNotRead}).
+            const sent = curlValuesNotRead(bin, shape.args);
+            const words = credentialReadWords(bin, sent.args);
             // A copy's destination is WRITTEN, and the write half (the protected
             // scan, the Hermes organ pass) prices it; judged as a read it would make
             // `cp /tmp/x .` in a home a credential read of the home.
@@ -2863,6 +2971,15 @@ export function credentialReadLandings(command, cwd, env = process.env) {
             const verb = verbAt === null ? undefined : shape.args[verbAt];
             for (const [at, word] of words.entries())
                 judge(word, recursive, !(at === 0 && verb !== undefined && word === verb));
+            // A `--url` value opening with an unexpanded span may expand to `@FILE`
+            // (curl 8.13+ reads a URL list from FILE) or to a `file:` URL, and either
+            // reads the path the rest of the word spells. It is judged as that path
+            // from every working directory, the configured home not re-spelled as
+            // `$HERMES_HOME`: that spelling makes the known home one more unknown
+            // segment, and two unknowns in a row then read as an approval home's
+            // `vault*`, which the literal landing already rules in or out.
+            for (const word of sent.spannedUrls)
+                judge(word, false, true, false);
             // M-E: a recursive search reads the working directory.
             if (readsWorkingDirectory(bin, shape.args, words))
                 judge(".", true);
@@ -6399,17 +6516,20 @@ function resolvedPathClasses(raw, segments, cwd, protectedPaths, readRoots = [],
                     add("policy.core");
             }
         };
-        const judgeRead = (word, recursive) => {
+        // `homeSpelled` is false only for a curl `--url` value that opens with an
+        // unexpanded span (EDGEOS-BLOCK, APRV-533; {@link curlValuesNotRead}).
+        const judgeRead = (word, recursive, homeSpelled = true) => {
             const braced = braceCandidates(word);
             if (braced === null) {
                 add("account.credential");
                 return;
             }
-            for (const each of braced)
+            for (const each of braced) {
                 for (const spelling of tildeReadings(each))
-                    judgeReadWord(spelling, recursive);
+                    judgeReadWord(spelling, recursive, homeSpelled);
+            }
         };
-        const judgeReadWord = (word, recursive) => {
+        const judgeReadWord = (word, recursive, homeSpelled = true) => {
             const target = expand(word);
             // Fix round 1 (M-C): an unexpanded tilde prefix lands somewhere unknown.
             if (target.hermesUnknown || target.landingUnknown) {
@@ -6442,7 +6562,7 @@ function resolvedPathClasses(raw, segments, cwd, protectedPaths, readRoots = [],
                     if (landing.unknown)
                         add("account.credential");
                     for (const landed of [resolvePathSegments(spelled), ...landing.paths]) {
-                        for (const spelling of landedSpellings(landed, rest, configuredHome)) {
+                        for (const spelling of landedSpellings(landed, rest, homeSpelled ? configuredHome : null)) {
                             if (unresolvedReadCouldNameCredential(spelling))
                                 add("account.credential");
                         }
@@ -6708,8 +6828,16 @@ function resolvedPathClasses(raw, segments, cwd, protectedPaths, readRoots = [],
         const readWords = credentialReadWords(bin, shape.args);
         const recursive = RECURSIVE_READERS.has(bin) || (DIRECTORY_READING_BINS.has(bin) && readWords.length > 0);
         if (segment.class.startsWith("read.") || recursive) {
-            for (const operand of operands)
+            // EDGEOS-BLOCK (APRV-533): the curl and wget option values the tool
+            // sends and never opens are not read here either, and a span-led curl
+            // `--url` value is judged as the path an `@` or `file:` expansion would
+            // read, as the credential pass judges it ({@link curlValuesNotRead}).
+            const sent = curlValuesNotRead(bin, shape.args);
+            const readOperands = sent.args === shape.args ? operands : sent.args.filter((arg) => !arg.startsWith("-"));
+            for (const operand of readOperands)
                 judgeRead(operand, recursive);
+            for (const url of sent.spannedUrls)
+                judgeRead(url, recursive, false);
             // APRV-511 (cred-asymmetry round 3, N2): a recursive reader that no
             // argument proves names a path walks the working directory.
             if (walksWorkingDirectory(bin, shape.args))
@@ -7509,6 +7637,41 @@ function landingPaths(spelled, volatile = null) {
 }
 /** The environment variable that turns the sandbox requirement on (APRV-193). */
 export const REQUIRE_SANDBOX_ENV = "APPROVAL_HOOK_REQUIRE_SANDBOX";
+/**
+ * The fixed remedy a `fetch-output-unknown` refusal carries when a `$`-first
+ * word in curl's or wget's option slot caused it (0.4.7, EDGEOS-BLOCK).
+ *
+ * Core 0.4.6 (APRV-511) holds `curl "${BASE:-https://h}/x"`: the expansion
+ * could be `-o <organ path>`, so the download's output is unknown, the class is
+ * `policy.core`, and a policy that reserves that class denies outright. The
+ * refusal said why and nothing about the shape that runs. The same word as
+ * `--url`'s value sits in a value slot, where curl reads it as the URL whatever
+ * it starts with, and classifies by its method. wget has no `--url`, so the
+ * line names curl for both.
+ *
+ * Text only: the class, the rule and the code are unchanged, and nothing here
+ * widens a verdict.
+ */
+export const FETCH_DOLLAR_WORD_REMEDY = 'Remedy: a word that starts with `$` stands where curl and wget read options, so its value could turn it into `-o <path>` and the download\'s output cannot be known. If that word is the URL, pass it as the value of `--url` (`curl --url "$VAR/..."`), which keeps the output known; wget has no `--url`, so use `curl --url` instead.';
+/**
+ * {@link FETCH_DOLLAR_WORD_REMEDY}, prefixed with a space, when a segment that
+ * earned `reserved` did so by rule `fetch-output-unknown` on a word that
+ * starts with `$`; otherwise the empty string, so every other cause of the rule
+ * (an unknown option, a config source, an ambiguous prefix, an unplaceable
+ * output value) keeps its refusal byte for byte.
+ *
+ * `fetchOutputs` reports the first unknowable word verbatim, and only its
+ * option-slot test reports a positional word; every other cause reports the
+ * option as spelled, which starts with `-`. So a bound path starting with `$`
+ * is exactly the `$`-first option-slot cause.
+ */
+export function fetchOutputRemedy(segments, reserved) {
+    const fired = (segments ?? []).some((segment) => segment.class === reserved &&
+        segment.rule === "fetch-output-unknown" &&
+        segment.path !== undefined &&
+        segment.path.startsWith("$"));
+    return fired ? ` ${FETCH_DOLLAR_WORD_REMEDY}` : "";
+}
 /**
  * Must this command have been written `approval sandbox -- …`? (APRV-193.)
  *
@@ -7692,7 +7855,7 @@ decidedOn) {
         }
         const reserved = classes.find((cls) => resolvePolicy(load, cls).autonomy === "human-only");
         if (reserved !== undefined) {
-            return deny(streams, "hook-class-human-only", `${humanOnlyRefusal(reserved, "this command may not run under an agent")} An open window does not reach it: the window suspends what the policy DECIDES, and a human-only class is one the policy reserves to human hands, which a window opened by a human does not lend to an agent (SPEC.md §11.1 invariant 9).`, adapter.kind);
+            return deny(streams, "hook-class-human-only", `${humanOnlyRefusal(reserved, "this command may not run under an agent")} An open window does not reach it: the window suspends what the policy DECIDES, and a human-only class is one the policy reserves to human hands, which a window opened by a human does not lend to an agent (SPEC.md §11.1 invariant 9).${fetchOutputRemedy(described.segments, reserved)}`, adapter.kind);
         }
     }
     // APRV-227, resolved here because here is where a record is written. The
@@ -8276,7 +8439,7 @@ function* decideHarnessSteps(decide) {
         return {
             permission: "deny",
             code: "hook-class-human-only",
-            detail: `${humanOnlyRefusal(reserved, "this command may not run under an agent")} The gate's own code for this fact is \`class-human-only\`.`,
+            detail: `${humanOnlyRefusal(reserved, "this command may not run under an agent")} The gate's own code for this fact is \`class-human-only\`.${fetchOutputRemedy(described.segments, reserved)}`,
         };
     }
     // APRV-193, and BELOW the human-only deny for the same reason that one sits