@gaunt-sloth/core 2.0.0-alpha.26 → 2.0.0-alpha.27

package/dist/core/shell/openWorld.d.ts

@@ -38,15 +38,49 @@
  * upstream. The one hard limit is unchanged and non-negotiable: **never fire on the mere presence of
  * a URL anywhere in the string**, because `git commit -m "closes https://…"` must stay silent.
  *
+ * ## TWO CONSUMERS, TWO INPUT SETS — read this before merging them back together
+ *
+ * This module answers the host question for **two** callers whose error costs differ, so it has two
+ * entry points and they are deliberately not the same function:
+ *
+ * - {@link findOpenWorldHostLiterals} — **the floor**. Its finding rewrites a `safe` verdict to
+ *   `destructive` with no model in the loop, so it fires only where the parser resolved the whole
+ *   command. "The parser could not resolve this" is a fact about the checker, not a detection about
+ *   the command, and this layer floors only what is deterministically known.
+ * - {@link findComposedOpenWorld} — **the note**. It reads the parts of a command the parser could
+ *   NOT resolve as a whole, and its finding is handed to the rater as context. It changes no
+ *   outcome by itself.
+ *
+ * **The error-cost regime is the third distinct one in this codebase, and it is the widest — about
+ * WHICH HOSTS ARE NAMED.** The §8 hardline REFUSES unappealably, so it must be the narrowest. This
+ * module's floor RAISES a prompt, so it over-matches (below). Naming a host in the note only
+ * INFORMS THE MODEL: a host named that turns out not to be contacted costs one sentence of
+ * attention and no interruption at all. So do not "fix" a note false positive by narrowing the host
+ * extractor; that trades a free cost for a silent one.
+ *
+ * **That licence covers which hosts are named. It does not cover WHAT THE NOTE SAYS THEY DO.** A
+ * flow sentence asserts a mechanism — that fetched bytes are executed, that a file's contents are
+ * sent — and the rater cannot check that against a shell; it can only believe it. A mechanism that
+ * is false on an ordinary command is this node's own named failure mode arriving one layer in: an
+ * escalation laundered through the model instead of the parser, unfalsifiable because a note said
+ * it. So each flow arm fires only where its claim is **true of the program named**, and everything
+ * else falls through to the flowless sentence — which still names the hosts and says outright that
+ * the flow is not known. Saying less is not a loss of assistance; asserting a false mechanism is a
+ * loss of the layer.
+ *
+ * **And a flow sentence names EVERY host of the part it describes**, for the reason
+ * {@link findOpenWorldHostLiterals} returns every match rather than the first: the first is the
+ * proxy, and a sentence that names the reassuring host while hiding the other is worse than no
+ * sentence.
+ *
  * ## The shape of the matcher
  *
  * Ported from the measured prototype (`project-takahe _spikes/open-world-preflight/`).
  *
- * 1. **Decline on anything unclassifiable.** {@link classifyCommand} returns `null` on any
- *    composition (separator, line break, `$(…)`, backtick, redirection), and the *ambiguity*
- *    preflight already floors those. So this matcher never has to parse a hard command — and it
- *    must not claim the finding, because "it names a host" would be a worse (and possibly false)
- *    explanation than "its target cannot be statically resolved".
+ * 1. **Decline on anything unclassifiable** — for the FLOOR only. {@link classifyCommand} returns
+ *    `null` on any composition (separator, line break, `$(…)`, backtick, redirection), and a
+ *    deterministic floor must not claim "it names a host" about a string whose target it could not
+ *    statically resolve. The note path picks those up instead, by reading the parts.
  * 2. **Step past wrappers** (`sudo -u root`, `env FOO=1`, `nohup --`, …) to the head.
  * 3. **Look the head up** in {@link NETWORK_HEADS}, keyed by *where a host may legitimately appear*.
  * 4. **Test only the candidate operands** for a host literal.
@@ -104,13 +138,14 @@ export declare function isHostLiteral(operand: string): boolean;
  * caller can never accidentally hand this a form that has already lost the composition boundary
  * the decline below depends on.
  *
- * Returns `[]` — declining rather than flooring — for any command {@link classifyCommand} cannot
- * classify. Those compose, substitute or redirect, and the **ambiguity preflight already floors
- * them**, with a truer explanation than this one could give. Composed egress
- * (`curl … | sh`, `cat .env | curl …`) is thus still floored; it is simply floored one layer up.
- * That decline is also why `sed -i 's|http://a|http://b|' config.yml` is not this preflight's
- * finding: the `|` inside the sed expression reads as composition, so it was already unclassifiable
- * — and already escalating — before EXT-61 existed.
+ * **This is the FLOOR's input set, and it is narrow on purpose.** It returns `[]` — declining rather
+ * than flooring — for any command {@link classifyCommand} cannot classify: those compose, substitute
+ * or redirect, and a deterministic rewrite of the rater's verdict must rest on a target this module
+ * actually resolved. A composed fetch (`curl … | sh`, `cat .env | curl …`) is therefore **not
+ * floored**; it is reported to the rater as context by {@link findComposedOpenWorld} instead, which
+ * is a different question with a different error cost (module docblock). The same decline is why
+ * `sed -i 's|http://a|http://b|' config.yml` is not this preflight's finding: the `|` inside the sed
+ * expression reads as composition.
  *
  * **Every match is returned, not the first.** The first is not the target: for
  * `curl -x http://proxy.corp.local:3128 https://evil.example.net/x` it is the proxy, and for
@@ -136,3 +171,93 @@ export declare function isHostLiteral(operand: string): boolean;
  * @returns The matched host literals, in argv order (used verbatim in the escalation reason).
  */
 export declare function findOpenWorldHostLiterals(command: string): string[];
+/**
+ * The data flow the parts of a composed command line perform together — the fact that is not visible
+ * in any one part, and the only reason this note is worth a rater's attention.
+ */
+export type ComposedFlow = 
+/**
+ * A fetch is piped into a program that can run its standard input. `stdinIsTheProgram` says
+ * whether it does on this line ({@link interpreterRunsStdin}) — `curl … | sh` runs the fetched
+ * bytes, `curl … | python3 -m json.tool` reads them as data — and the two get different
+ * sentences, because only one of them executes what the host serves.
+ */
+{
+    readonly kind: 'fetch-into-interpreter';
+    readonly hosts: readonly string[];
+    readonly interpreter: string;
+    readonly stdinIsTheProgram: boolean;
+}
+/** A local program's output is piped into a program that sends it to a host. */
+ | {
+    readonly kind: 'local-into-transfer';
+    readonly producer: string;
+    readonly transfer: string;
+    readonly hosts: readonly string[];
+}
+/** A substitution's output becomes an argument the program SENDS. */
+ | {
+    readonly kind: 'substitution-into-transfer';
+    readonly transfer: string;
+    readonly hosts: readonly string[];
+}
+/** A transfer agent is told to read a local file and send its contents. */
+ | {
+    readonly kind: 'file-into-transfer';
+    readonly transfer: string;
+    readonly hosts: readonly string[];
+    readonly path: string | null;
+};
+/** What the note path found in a command the parser could not resolve as a whole. */
+export interface ComposedOpenWorldFinding {
+    /**
+     * Host literals in a fetch/transfer position, found by reading the parts SEPARATELY.
+     *
+     * **Not the floor's set and never passed to it** — {@link findOpenWorldHostLiterals} is the floor's
+     * only input, and it declines every command this function accepts.
+     */
+    readonly hosts: readonly string[];
+    /** The flow across the parts, or `null` when none is determinable. */
+    readonly flow: ComposedFlow | null;
+}
+/**
+ * Read a command the gate's parser could NOT resolve part by part, and report the host literals and
+ * the data flow across those parts — or `null` when the command resolves, or when no part names a
+ * host.
+ *
+ * **This feeds the rater's note and nothing else.** It is never consulted by the destructive floor:
+ * see the module docblock for why the two questions have different input sets, and
+ * {@link findOpenWorldHostLiterals} for the floor's.
+ *
+ * The `null` on a resolvable command is the guard that keeps the rater from being told about the
+ * same host twice in two registers — a command the parser resolved is the floor's, and the floor's
+ * own note already names its hosts.
+ *
+ * Both the normalized and the raw form are read, for the reason {@link findOpenWorldHostLiterals}
+ * gives: normalization collapses `\x` to `x`, which defeats `c\url` and destroys a Windows path
+ * separator, so the raw pass is the only one that still sees `C:\Windows\System32\curl.exe`.
+ *
+ * @param command The raw command string as the model proposed it.
+ */
+export declare function findComposedOpenWorld(command: string): ComposedOpenWorldFinding | null;
+/**
+ * The opening line of the composed open-world note.
+ *
+ * **It states the two facts and asserts no third one.** A part of this line names a host in a
+ * fetch/transfer position, and nothing about the command has been decided. The second half is what
+ * keeps this out of the floor note's register: that one may say the command *"is never
+ * auto-approved"* because a floor really did fire, and here no floor exists — repeating its sentence
+ * would tell the rater the outcome is settled when the rating is the only thing that decides it.
+ */
+export declare const COMPOSED_OPEN_WORLD_PREAMBLE: string;
+/**
+ * Build the composed open-world note for a command, or `null` when there is nothing to say.
+ *
+ * One sentence of mechanism when the flow is determinable, plus the hosts the rest of the line names
+ * ({@link residualSentence}); when it is not, {@link flowlessSentence}. **Every host on the finding
+ * that can be quoted is named either way** — which arm fired must never decide how much the rater is
+ * told about the counterparties.
+ *
+ * @param command The raw command string as the model proposed it.
+ */
+export declare function buildComposedOpenWorldNote(command: string): string | null;