@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/gates/credentials.d.ts

@@ -0,0 +1,233 @@
+import type { GateStatus } from "./result.ts";
+/** What one source probe concluded. */
+export interface SourceProbe {
+    /** The credential source's stable name. */
+    source: string;
+    outcome: "clean" | "resolvable" | "error";
+    detail: string;
+}
+/**
+ * THIS VOCABULARY IS NOW READ BY THE KERNEL AS WELL AS BY THIS GATE
+ * (M4-P8 step 4, and this comment IS the record that step requires).
+ *
+ * `src/exec/env.ts` imports `GH_TOKEN_VARIABLES` and `isDangerousEnvName`
+ * from here to refuse a per-invocation allowlist extension naming one of
+ * them. The plan offered two shapes, move the vocabulary to a third module
+ * or export it from here, and the choice taken is EXPORT FROM HERE: the
+ * walk above, the per-name sources below and the constants stay in one
+ * file, so a future editor extending the vocabulary cannot extend it
+ * somewhere the other reader does not see. What is forbidden is a second
+ * copy: two lists drift, and they drift silently toward the permissive
+ * side.
+ *
+ * NOTHING ABOUT WHAT EITHER GATE DECIDES CHANGES WITH THAT IMPORT. The
+ * constants, the pattern and `isDangerousEnvName` are byte-identical to
+ * their M2-P8 form; the only difference is that a second module now reads
+ * them.
+ */
+/**
+ * gh's documented token vocabulary (see the module comment for the walk).
+ * Never permitted in a child environment, allowlisted or not.
+ */
+export declare const GH_TOKEN_VARIABLES: readonly string[];
+/**
+ * The credential- or code-execution-capable environment vocabulary of the
+ * programs a scrubbed child runs, walked from each program's own
+ * documentation. A child environment must contain NONE of these,
+ * allowlisted or not; the environment probe reddens if any is present.
+ * This is a BOUNDED denylist (it cannot list every dangerous name any
+ * program will ever read); the allowlist in src/exec/env.ts remains the
+ * real defense. Per-name source:
+ *
+ *   git (git-config(1), git(1)):
+ *     GIT_ASKPASS       - program git runs to obtain a password.
+ *     GIT_SSH_COMMAND   - shell command git uses for its ssh transport.
+ *     GIT_PROXY_COMMAND - external program for git:// connections.
+ *     GIT_CONFIG_COUNT  - trigger of the environment config-injection
+ *                         family; with GIT_CONFIG_KEY_n / GIT_CONFIG_VALUE_n
+ *                         it injects arbitrary config (e.g. a
+ *                         credential.helper) at a scope --global/--system
+ *                         cannot see. The numbered KEY_n / VALUE_n members
+ *                         are matched by isDangerousEnvName's pattern.
+ *   ssh (ssh(1), ssh-add(1)):
+ *     SSH_ASKPASS       - program ssh runs to obtain a passphrase.
+ *     SSH_AUTH_SOCK     - the agent socket. ADDED BY THE DR-0047 SWEEP FIX
+ *                         ROUND, and the basis is stated here rather than
+ *                         implied because HALF OF IT IS UNVERIFIED. What was
+ *                         MEASURED in this container: the name sat in neither
+ *                         walked vocabulary, so the audited route ACCEPTED it
+ *                         (clean-room-final-credential-criteria CR-F-CRED-004),
+ *                         and buildChildEnv's default child does not carry it,
+ *                         so refusing an extension that names it withdraws
+ *                         nothing the default grants. What could NOT be
+ *                         verified here: this container has no ssh binary and
+ *                         no man page (`ssh -V` -> command not found, `man 1
+ *                         ssh` -> nothing), so the claim that ssh(1)'s own
+ *                         ENVIRONMENT section documents it was NOT read from
+ *                         the page. The row therefore rests on capability
+ *                         reasoning, not on the walk: the socket is a SIGNING
+ *                         channel (any holder can authenticate as the owner to
+ *                         any host the agent holds a key for), which is
+ *                         strictly stronger than SSH_ASKPASS, a passphrase
+ *                         PROMPT, which the same row already refuses. A later
+ *                         round with the page should either confirm this row
+ *                         from ssh(1) or move it and say why.
+ *   node / dynamic loader / shell startup (node(1), ld.so(8), bash(1)):
+ *     NODE_OPTIONS       - options node applies at startup (can require
+ *                          arbitrary modules), arbitrary code execution.
+ *     NODE_EXTRA_CA_CERTS- extra CAs node trusts, a TLS-trust channel.
+ *     LD_PRELOAD         - shared objects the loader injects into every
+ *                          dynamically linked program, arbitrary code.
+ *     BASH_ENV           - script bash sources at non-interactive startup.
+ *     ENV                - script the POSIX shell sources at startup.
+ *
+ * GIT_CONFIG_GLOBAL and GIT_CONFIG_SYSTEM are DELIBERATELY absent: they are
+ * redirected (CREDENTIAL_STORE_REDIRECTIONS) to empty harness-owned targets
+ * and the override runs last in buildChildEnv, so their mere presence is
+ * expected and neutralized; flagging them would false-positive on every
+ * real run.
+ */
+export declare const DANGEROUS_ENV_VOCABULARY: readonly string[];
+/**
+ * THE EGRESS VOCABULARY (M4-P29, and this comment is the record of why it
+ * exists as a SEPARATE list rather than as more rows of the one above).
+ *
+ * WHAT WAS MEASURED. delivery/verification/m4-prototype-probes.md:46
+ * recorded that this gate's verdict is INVERTED with respect to real
+ * capability: it reddens `GIT_CONFIG_*`, which in that container bought
+ * only URL rewriting, and it greens `HTTPS_PROXY`, which bought full
+ * GitHub reach. M4-P8 then measured the same thing from the other side,
+ * four arms through `spawnTask` differing only in the allowlist extension
+ * (delivery/work-history/m4-p8.md:116): arm A, ten variables, HTTP 403
+ * from `api.github.com/user`; arm B, the same ten plus `HTTPS_PROXY`,
+ * HTTP 200. One variable, and it is the one nothing in this module knew
+ * about. A gate that cannot go red for the case that matters is the shape
+ * this repository keeps paying for.
+ *
+ * WHAT THIS FIXES AND WHAT IT DOES NOT, stated here rather than left to be
+ * discovered. It closes the case where the DEFAULT allowlist in
+ * src/exec/env.ts gains an egress name: this tripwire is
+ * allowlist-INDEPENDENT, exactly like the two above it, so the widening
+ * costs a red instead of buying a green. It does NOT close the case
+ * M4-P8's arm B actually used, which is a PER-INVOCATION
+ * `extraAllowlist`: that argument is runtime data of one spawn, this gate
+ * probes the constructed default child, and no probe of a default can see
+ * an argument a caller has not passed yet. Closing that half means
+ * auditing the extension record a task writes, which is a different gate
+ * and a different phase.
+ *
+ * WHY A SEPARATE LIST, AND WHAT DR-0048 CHANGED ABOUT ITS CONSEQUENCE.
+ * M4-P29 kept these names out of `DANGEROUS_ENV_VOCABULARY` so that a data
+ * edit in this file would not, as a side effect, refuse M4-P8's audited
+ * extension in a module that phase did not touch. It named the underlying
+ * question (whether an egress name may ever be extended) as a kernel design
+ * question with an owner-facing cost, and routed it onward rather than
+ * taking it by accident.
+ *
+ * DR-0048 answered that question: the audited route REFUSES egress names.
+ * The two lists still stay separate, because they are walked from different
+ * programs' documentation and their per-name evidence is different, and
+ * `isDangerousEnvName` is still byte-for-byte what it was. What changed is
+ * that the refusal in src/exec/env.ts no longer walks a HAND-PICKED PAIR of
+ * vocabularies: it walks `REFUSED_CHILD_ENV_VOCABULARIES` below, which is
+ * the declared list of every vocabulary in this module, this one included.
+ *
+ * THE WALK, per name, from the consuming programs' own documentation
+ * (curl(1) "ENVIRONMENT", git(1) "http_proxy", wget(1) "ENVIRONMENT"):
+ * each of these names a proxy a child's HTTP client will route through,
+ * in both the upper-case and lower-case spellings those pages document.
+ *
+ *   HTTP_PROXY / http_proxy   - proxy for http:// requests.
+ *   HTTPS_PROXY / https_proxy - proxy for https:// requests. THE MEASURED
+ *                               NAME: arm A 403 against arm B 200.
+ *   ALL_PROXY / all_proxy     - proxy for every scheme.
+ *   FTP_PROXY / ftp_proxy     - proxy for ftp:// requests.
+ *
+ * TWO NAMES ARE DELIBERATELY ABSENT, and both absences are measured rather
+ * than assumed. `NO_PROXY` / `no_proxy` NARROW reach instead of granting
+ * it, so listing them would redden a child that is strictly less capable.
+ * `CURL_CA_BUNDLE` is a TLS-trust channel and not an egress grant: M4-P8's
+ * arm C added it on top of arm B and measured the same HTTP 200 arm B
+ * already had (delivery/work-history/m4-p8.md:117), so it buys no reach,
+ * and its node-side sibling `NODE_EXTRA_CA_CERTS` is already covered by
+ * `DANGEROUS_ENV_VOCABULARY` above.
+ *
+ * LIKE THE LIST ABOVE THIS IS A BOUNDED DENYLIST. The allowlist in
+ * src/exec/env.ts is still the real defense; this makes a widening cost a
+ * red for the names walked here, it does not enumerate every way a child
+ * could be handed network reach.
+ */
+export declare const EGRESS_ENV_VOCABULARY: readonly string[];
+/** Whether a variable name is in the walked egress vocabulary. */
+export declare function isEgressEnvName(name: string): boolean;
+/** Whether a variable name is in the walked dangerous vocabulary. */
+export declare function isDangerousEnvName(name: string): boolean;
+/** One walked vocabulary, as a refusal walks it. */
+export interface RefusedEnvVocabulary {
+    /** Stable id, used in tests and in nothing an operator reads. */
+    id: string;
+    /** The exported constant this row stands for, named for the drift test. */
+    constantName: string;
+    /** Whether this vocabulary claims the name. */
+    includes: (name: string) => boolean;
+    /**
+     * The middle of the refusal sentence: "the allowlist extension entry X "
+     * + this + " and may never cross into a child environment".
+     */
+    clause: string;
+}
+/**
+ * EVERY VOCABULARY A CHILD-ENVIRONMENT REFUSAL MUST WALK, IN ONE PLACE.
+ *
+ * THE MECHANISM THIS EXISTS AGAINST (CH-001 high, CR-F-CRED-003, CR-F-CRED-004;
+ * DR-0048): a refusal that walks ONE vocabulary, or a hand-picked subset of
+ * them, while several exist. `refuseExtraAllowlist` (src/exec/env.ts) named
+ * `GH_TOKEN_VARIABLES` and `isDangerousEnvName` as two literal `if` arms and
+ * therefore could not see `EGRESS_ENV_VOCABULARY`, which this module had held
+ * since M4-P29. The defect is not that the third name was forgotten once; it
+ * is that ADDING a vocabulary to this module left every consumer's coverage
+ * unchanged and silent, so the subset could only be discovered by probing a
+ * name.
+ *
+ * So the list of vocabularies is data, exported from the module that owns
+ * them, and a consumer walks the LIST rather than naming members of it. A
+ * fourth vocabulary added below is walked by every consumer of this array the
+ * moment it gains a row here, and `test/payload-credentials.test.ts` reddens
+ * if a `*_VOCABULARY` or `*_VARIABLES` export of this module has NO row,
+ * which is the case a reader cannot see by reading either file alone.
+ *
+ * `probeCredentialSources` deliberately does NOT walk this array: it reports a
+ * different sentence per vocabulary in one fixed order, strongest first, and the three
+ * sentences are read by operators. It is covered by the same drift test from
+ * the other side.
+ */
+export declare const REFUSED_CHILD_ENV_VOCABULARIES: readonly RefusedEnvVocabulary[];
+/**
+ * The first vocabulary claiming `name`, or undefined. The ORDER of
+ * `REFUSED_CHILD_ENV_VOCABULARIES` is the order the refusal reports, and it
+ * is narrowest-first so that a name in two vocabularies is reported as the
+ * more specific one.
+ */
+export declare function refusedEnvVocabulary(name: string): RefusedEnvVocabulary | undefined;
+/** The names credential-scrub probes, in probe order. */
+export declare const CREDENTIAL_SOURCES: readonly string[];
+export interface ProbeOptions {
+    /**
+     * The variable names the environment source accepts. Defaults to the
+     * constructed contract (allowlist plus redirections). Passed explicitly
+     * by tests staging dangerous states.
+     */
+    permittedNames?: ReadonlySet<string>;
+}
+/**
+ * Probe every credential source FROM INSIDE the given child environment.
+ * The environment is the one under test: every subprocess probe below runs
+ * with `env` as its entire environment, so what is asserted is what a
+ * child launched with this environment could actually resolve.
+ */
+export declare function probeCredentialSources(env: Record<string, string | undefined>, options?: ProbeOptions): SourceProbe[];
+/** Fold probes into a gate verdict. Any error wins over any red. */
+export declare function verdictFromProbes(probes: SourceProbe[]): {
+    status: GateStatus;
+    detail: string;
+};