@crewhaus/tool-proc 0.7.0 → 0.8.1

package/dist/lib/addr.js

@@ -0,0 +1,391 @@
+/**
+ * What WaitForPort may dial (C144).
+ *
+ * WaitForPort is read-only, so plan and auto mode run it unasked, and it
+ * used to connect() to any host a call named: the cloud metadata address,
+ * the LAN, any port on loopback in an inet_aton spelling — a port-scan
+ * oracle, and a DNS query for any name the model chose. Its purpose is
+ * waiting for a server the harness just started, which is loopback. So
+ * loopback is allowed without configuration, and anything else only when
+ * the operator lists it in `tool_config.proc.wait_for_port_hosts`.
+ *
+ * Addresses are classified NUMERICALLY by the repository's shared
+ * private-address classifier, carried here as the byte-identical block
+ * apps/cli/src/tool-registry.test.ts hashes across every copy (so
+ * `0x7f.1`, `2130706433` and `::ffff:127.0.0.1` are all loopback, and
+ * `::ffff:169.254.169.254` is link-local).
+ */
+// BEGIN SYNCHRONISED BLOCK — private-address classifier
+//
+// This block is BYTE-IDENTICAL across every package that guards an outbound
+// request. Do not edit one copy: `apps/cli/src/tool-registry.test.ts` hashes
+// them all and fails if any differs, and it asserts how many it found, because
+// a copy-scanning guard that matches nothing reports green.
+//
+// It exists in copies rather than a shared package because these files are
+// otherwise independent per-package networking layers; a guard proving the
+// copies are identical is cheaper and safer than the import graph a shared
+// package would need across `crawler`, `computer-use-driver` and ten tools.
+//
+// WHY IT PARSES INSTEAD OF MATCHING TEXT. Six copies were confirmed
+// exploitable on 2026-09-18 because they compared address STRINGS. The WHATWG
+// URL parser rewrites `[::ffff:169.254.169.254]` to `[::ffff:a9fe:a9fe]`, so a
+// text check never sees the spelling it was written for; and `64:ff9b::a9fe:a9fe`
+// IS 169.254.169.254 on any network running DNS64/NAT64. Parsing numerically and
+// recursing into the embedded IPv4 is the only form that holds.
+//
+// WHAT IT CANNOT DO. RFC 6052 lets an operator choose any Network-Specific
+// Prefix for NAT64, so an embedded IPv4 behind an arbitrary NSP is undecidable
+// from the address alone. That case is configuration, and the callers that need
+// it resolve the host and re-check the ANSWER before dialling.
+// ---------------------------------------------------------------------------
+/**
+ * Canonicalise an IPv4 literal.
+ *
+ * `inet_aton` forms are the classic allow-list bypass: `0177.0.0.1`,
+ * `0x7f.0.0.1`, `2130706433` and `127.1` are all 127.0.0.1, and a check that
+ * only understands dotted-decimal waves every one of them through. Returns
+ * `null` when the string is not an IPv4 literal at all.
+ */
+export function normalizeIpv4(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "" || /[^0-9a-fA-FxX.]/.test(trimmed))
+        return null;
+    const parts = trimmed.split(".");
+    if (parts.length === 0 || parts.length > 4)
+        return null;
+    const values = [];
+    for (const part of parts) {
+        if (part === "")
+            return null;
+        let value;
+        if (/^0[xX][0-9a-fA-F]+$/.test(part))
+            value = Number.parseInt(part.slice(2), 16);
+        else if (/^0[0-7]+$/.test(part))
+            value = Number.parseInt(part.slice(1), 8);
+        else if (/^\d+$/.test(part))
+            value = Number.parseInt(part, 10);
+        else
+            return null;
+        if (!Number.isFinite(value) || value < 0)
+            return null;
+        values.push(value);
+    }
+    // The short forms pack the remaining octets into the last part: `127.1` is
+    // 127.0.0.1, not 127.1.0.0. Getting this backwards is how a bypass survives.
+    const last = values[values.length - 1];
+    const leading = values.slice(0, -1);
+    if (leading.some((v) => v > 255))
+        return null;
+    const remaining = 4 - leading.length;
+    if (last >= 2 ** (8 * remaining))
+        return null;
+    const octets = [...leading];
+    for (let i = remaining - 1; i >= 0; i--)
+        octets.push((last >>> (8 * i)) & 0xff);
+    return octets.join(".");
+}
+/**
+ * Expand an IPv6 literal to its eight 16-bit groups, or `null` when the string
+ * is not one.
+ *
+ * Classifying IPv6 by its TEXT is where the bypasses live, because one address
+ * has many spellings and the one a check was written against is rarely the one
+ * that arrives. `http://[::ffff:169.254.169.254]/` never reaches a guard in
+ * that form: the WHATWG URL parser re-serialises the embedded quad as hex
+ * pieces, so what the guard sees is `::ffff:a9fe:a9fe`. Normalising to numbers
+ * first means the prefix tests below are arithmetic, and spelling stops
+ * mattering.
+ */
+export function parseIpv6(raw) {
+    let text = raw.trim().toLowerCase();
+    if (text.startsWith("["))
+        text = text.slice(1);
+    if (text.endsWith("]"))
+        text = text.slice(0, -1);
+    const zone = text.indexOf("%"); // fe80::1%eth0
+    if (zone !== -1)
+        text = text.slice(0, zone);
+    if (!text.includes(":"))
+        return null;
+    // A trailing dotted quad is the last two groups written in IPv4. Require all
+    // three dots: without that, `::1` parses as a one-part inet_aton address and
+    // takes a path that has nothing to do with what was written.
+    const dotted = /^(.*:)(\d+(?:\.\d+){3})$/.exec(text);
+    if (dotted !== null) {
+        const quad = normalizeIpv4(dotted[2]);
+        if (quad === null)
+            return null;
+        const o = quad.split(".").map((n) => Number.parseInt(n, 10));
+        const hi = (o[0] << 8) | o[1];
+        const lo = (o[2] << 8) | o[3];
+        text = `${dotted[1]}${hi.toString(16)}:${lo.toString(16)}`;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const pieces = (part) => (part === "" ? [] : part.split(":"));
+    const head = pieces(halves[0]);
+    const tail = halves.length === 2 ? pieces(halves[1]) : [];
+    if (halves.length === 1 && head.length !== 8)
+        return null;
+    if (head.length + tail.length > 8)
+        return null;
+    const groups = [];
+    for (const piece of head) {
+        if (!/^[0-9a-f]{1,4}$/.test(piece))
+            return null;
+        groups.push(Number.parseInt(piece, 16));
+    }
+    for (let i = head.length + tail.length; i < 8; i++)
+        groups.push(0);
+    for (const piece of tail) {
+        if (!/^[0-9a-f]{1,4}$/.test(piece))
+            return null;
+        groups.push(Number.parseInt(piece, 16));
+    }
+    return groups.length === 8 ? groups : null;
+}
+/**
+ * The IPv4 address an IPv6 address carries, when it carries one.
+ *
+ * Every transition mechanism embeds a v4 address somewhere, and every one of
+ * them is a way to reach a v4 destination while wearing a v6 spelling that no
+ * v4 range check looks at. The NAT64 well-known prefix is the sharpest: a
+ * DNS64 resolver answers an IPv4-only name with `64:ff9b::<the v4>`, so
+ * `64:ff9b::a9fe:a9fe` IS the metadata service on any network that runs one.
+ */
+function embeddedIpv4(g) {
+    const quad = (hi, lo) => `${(hi >>> 8) & 0xff}.${hi & 0xff}.${(lo >>> 8) & 0xff}.${lo & 0xff}`;
+    const zeros = (from, to) => g.slice(from, to).every((x) => x === 0);
+    const last = quad(g[6], g[7]);
+    if (zeros(0, 5) && g[5] === 0xffff)
+        return last; // ::ffff:0:0/96, IPv4-mapped
+    if (zeros(0, 4) && g[4] === 0xffff && g[5] === 0)
+        return last; // ::ffff:0:0:0/96, translated
+    if (g[0] === 0x64 && g[1] === 0xff9b)
+        return last; // 64:ff9b::/96 and 64:ff9b:1::/48, NAT64
+    if (g[0] === 0x2002)
+        return quad(g[1], g[2]); // 2002::/16, 6to4
+    // ::a.b.c.d, IPv4-compatible: deprecated, still routed by some stacks, and
+    // not to be confused with `::` or `::1`, which are handled before this.
+    if (zeros(0, 6))
+        return last;
+    return null;
+}
+/** Ranges that are never a public RPC endpoint. */
+export function isPrivateIp(address) {
+    const v4 = normalizeIpv4(address);
+    if (v4 !== null) {
+        const [a = 0, b = 0, c = 0, d = 0] = v4.split(".").map((n) => Number.parseInt(n, 10));
+        if (a === 0 || a === 10 || a === 127)
+            return true;
+        if (a === 169 && b === 254)
+            return true; // link-local, and the metadata service
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 192 && b === 0 && c === 0)
+            return true;
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // carrier-grade NAT
+        if (a === 198 && (b === 18 || b === 19))
+            return true; // benchmarking
+        if (a >= 224)
+            return true; // multicast, reserved, broadcast
+        return a === 255 && b === 255 && c === 255 && d === 255;
+    }
+    const groups = parseIpv6(address);
+    if (groups === null)
+        return false;
+    if (groups.every((g) => g === 0))
+        return true; // ::, the unspecified address
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
+        return true; // ::1
+    const carried = embeddedIpv4(groups);
+    if (carried !== null)
+        return isPrivateIp(carried);
+    const head = groups[0];
+    if ((head & 0xfe00) === 0xfc00)
+        return true; // fc00::/7, unique-local
+    if ((head & 0xffc0) === 0xfe80)
+        return true; // fe80::/10, link-local
+    return (head & 0xff00) === 0xff00; // ff00::/8, multicast
+}
+// END SYNCHRONISED BLOCK
+/** True for 127.0.0.0/8, ::1, and a v6 spelling that carries a 127/8 address. */
+export function isLoopbackIp(address) {
+    const v4 = normalizeIpv4(address);
+    if (v4 !== null)
+        return v4.startsWith("127.");
+    const groups = parseIpv6(address);
+    if (groups === null)
+        return false;
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
+        return true;
+    return embeddedIpv4(groups)?.startsWith("127.") === true;
+}
+/**
+ * True for link-local addresses, where cloud metadata services live:
+ * 169.254.0.0/16, fe80::/10, AWS's fd00:ec2::254, and a v6 spelling that
+ * carries a 169.254/16 address.
+ */
+export function isLinkLocalIp(address) {
+    const v4 = normalizeIpv4(address);
+    if (v4 !== null)
+        return v4.startsWith("169.254.");
+    const groups = parseIpv6(address);
+    if (groups === null)
+        return false;
+    const carried = embeddedIpv4(groups);
+    if (carried !== null)
+        return carried.startsWith("169.254.");
+    if ((groups[0] & 0xffc0) === 0xfe80)
+        return true;
+    const ec2 = [0xfd00, 0x0ec2, 0, 0, 0, 0, 0, 0x254];
+    return groups.every((g, i) => g === ec2[i]);
+}
+/** The canonical spelling of an IP literal (dotted quad, or v6 as written), or null. */
+export function canonicalIp(address) {
+    const v4 = normalizeIpv4(address);
+    if (v4 !== null)
+        return v4;
+    return parseIpv6(address) === null ? null : address.toLowerCase();
+}
+const systemLookup = async (host) => {
+    const { lookup } = await import("node:dns/promises");
+    const answers = await lookup(host, { all: true, verbatim: true });
+    return answers.map((a) => a.address);
+};
+let dnsLookup = systemLookup;
+/** Test seam: replace the resolver; `undefined` restores the system one. */
+export function _setDnsLookup(fn) {
+    dnsLookup = fn ?? systemLookup;
+}
+/**
+ * True for the unspecified address in any spelling (0.0.0.0, ::, an
+ * IPv4-mapped 0.0.0.0). A server that binds it prints it ("running on
+ * http://0.0.0.0:8000"), and dialling it reaches only this machine on Linux
+ * and macOS, so WaitForPort treats it as loopback and dials loopback itself,
+ * which also works where connecting to 0.0.0.0 does not (Windows).
+ */
+export function unspecifiedDial(address) {
+    const v4 = normalizeIpv4(address);
+    if (v4 !== null)
+        return v4 === "0.0.0.0" ? "127.0.0.1" : null;
+    const groups = parseIpv6(address);
+    if (groups === null)
+        return null;
+    if (groups.every((g) => g === 0))
+        return "::1";
+    const mapped = groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff;
+    return mapped && groups[6] === 0 && groups[7] === 0 ? "127.0.0.1" : null;
+}
+/**
+ * An IPv6 literal in the form WaitForPort dials it, or `null` when it is not
+ * one or may not be dialled.
+ *
+ * The form is the URL parser's (`0:0:0:0:0:ffff:127.0.0.1` is
+ * `::ffff:7f00:1`), which is how a permission rule reads a host too, so the
+ * probe goes to the address classified here and decided on there, and no
+ * resolver reads the string again. A spelling the URL parser does not read
+ * as the address {@link parseIpv6} does has no one reading, and is not
+ * dialled: an IPv4 part with a leading zero is octal to parseIpv6, decimal
+ * to macOS's resolver and invalid to the URL parser, so `::ffff:0177.0.0.1`
+ * was classified as loopback and reached 177.0.0.1.
+ */
+export function ipv6Dial(address) {
+    const groups = parseIpv6(address);
+    if (groups === null)
+        return null;
+    const inner = address.trim().replace(/^\[(.*)\]$/, "$1");
+    let host;
+    try {
+        host = new URL(`http://[${inner}]/`).hostname.slice(1, -1);
+    }
+    catch {
+        return null;
+    }
+    const read = parseIpv6(host);
+    return read?.every((g, i) => g === groups[i]) ? host : null;
+}
+/**
+ * Decide what one WaitForPort call dials for `host`, or why it may not.
+ * Nothing here touches DNS.
+ *
+ * - `localhost`, and any IP literal that is loopback in any spelling, is
+ *   allowed with no configuration (a literal is dialled in its canonical
+ *   form, so `0x7f.1` dials 127.0.0.1, and an IPv6 one in the URL parser's,
+ *   see {@link ipv6Dial}). So is the unspecified address (0.0.0.0, ::),
+ *   dialled as 127.0.0.1 / ::1.
+ * - An IPv6 literal with no one reading (`::ffff:0177.0.0.1`) is refused,
+ *   listed or not.
+ * - Any other host must be listed in `allowed` (the operator's
+ *   `tool_config.proc.wait_for_port_hosts`), and is refused BEFORE any DNS
+ *   query, so an unlisted name is not a way to send one either.
+ * - A listed literal is dialled in that canonical form; a listed NAME is
+ *   resolved at probe time (`resolveListedHost`).
+ */
+export function portTarget(host, allowed, configKey) {
+    const lower = host.toLowerCase();
+    if (lower === "localhost" || lower === "localhost.")
+        return { ok: true, dial: "localhost" };
+    let literal = normalizeIpv4(host);
+    if (literal === null && parseIpv6(host) !== null) {
+        literal = ipv6Dial(host);
+        if (literal === null) {
+            return {
+                ok: false,
+                message: `[WaitForPort error] "${host}" is an IPv6 address written in a form resolvers read as different addresses. Write it the standard way, such as ::1 or ::ffff:127.0.0.1.`,
+            };
+        }
+    }
+    if (literal !== null && isLoopbackIp(literal))
+        return { ok: true, dial: literal };
+    const unspecified = literal === null ? null : unspecifiedDial(literal);
+    if (unspecified !== null)
+        return { ok: true, dial: unspecified };
+    const listed = allowed.includes(lower) || (literal !== null && allowed.includes(literal));
+    if (!listed) {
+        return {
+            ok: false,
+            message: `[WaitForPort error] "${host}" is not a loopback address. WaitForPort probes loopback (localhost, 127.0.0.1, ::1) unless the operator lists the host in ${configKey}.`,
+        };
+    }
+    if (literal !== null)
+        return { ok: true, dial: literal };
+    return { ok: true, resolve: host };
+}
+/**
+ * Resolve a listed name for one probe. An empty answer, or a failed lookup,
+ * is "not accepting connections" for that probe, not a refusal: a compose
+ * service's name exists only once its container does, and a torn-down one
+ * stops resolving — which is exactly "closed". Every answer is checked: a
+ * name that resolves to a link-local address (the cloud metadata service) is
+ * refused unless that address itself is listed. The caller dials the address
+ * returned, and keeps dialling it for the rest of the call, so a resolver
+ * that answers differently later cannot move the probe.
+ */
+export async function resolveListedHost(host, allowed, configKey) {
+    let answers;
+    try {
+        answers = await dnsLookup(host);
+    }
+    catch {
+        answers = [];
+    }
+    const first = answers[0];
+    if (first === undefined)
+        return { ok: true, unresolved: true };
+    for (const address of answers) {
+        const canonical = canonicalIp(address) ?? address.toLowerCase();
+        if (isLinkLocalIp(address) && !allowed.includes(canonical)) {
+            return {
+                ok: false,
+                message: `[WaitForPort error] "${host}" resolves to a link-local address, where cloud metadata services live; list that address itself in ${configKey} to probe it.`,
+            };
+        }
+    }
+    return { ok: true, dial: canonicalIp(first) ?? first };
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,34 @@
+/** The spec key a refusal names. */
+export declare const ENV_REVEAL_KEY = "tool_config.proc.env_reveal";
+/** The spec key WaitForPort's refusal names. */
+export declare const PORT_HOSTS_KEY = "tool_config.proc.wait_for_port_hosts";
+/**
+ * Parse `wait_for_port_hosts` (or `waitForPortHosts`): host names or IP
+ * literals, compared case-insensitively. Throws with a sentence naming the key.
+ */
+export declare function parsePortHosts(config: unknown): readonly string[];
+/** Parse a `tool_config.proc` block's `env_reveal`; throws with a sentence naming the key. */
+export declare function parseProcConfig(config: unknown): readonly string[];
+/**
+ * The boot registrar: `tool_config.proc`. A block under the own key of a
+ * tool that reads it — `tool_config.envInspect` or `tool_config.waitForPort`
+ * — reaches it too, when that tool is listed (the builtin table's boot rule;
+ * no other tool-proc tool names this registrar). Both keys are parsed before either is stored,
+ * so a block with one bad key changes nothing.
+ */
+export declare function registerProcConfig(config: unknown): void;
+/**
+ * The extra hosts ONE WaitForPort call may probe: the serving candidate's
+ * block when it declares one, else the boot registration. A candidate block
+ * that does not parse allows nothing beyond loopback.
+ */
+export declare function portHostsFor(override: unknown): readonly string[];
+/**
+ * The reveal list ONE call runs under: the serving candidate's block when it
+ * declares one (replacing the boot registration, as every package's
+ * per-call override does), else the boot registration. A candidate block
+ * that does not parse reveals nothing rather than falling back.
+ */
+export declare function revealAllowFor(override: unknown): readonly string[];
+/** Test-only: back to the default, which reveals nothing and probes loopback only. */
+export declare function _resetProcConfig(): void;

package/dist/lib/config.js

@@ -0,0 +1,133 @@
+/**
+ * `tool_config.proc` — what an operator configures for this package.
+ *
+ * `wait_for_port_hosts` (C144): the hosts WaitForPort may probe besides
+ * loopback — a compose service (`db`), a LAN address. With none listed it
+ * probes loopback only; see ./addr.
+ *
+ * `env_reveal`: the environment variables whose VALUES
+ * EnvInspect may show. Before 0.7.1 the tool showed any value the CALL named
+ * in `reveal`, so a model (or the text steering it) could read
+ * ANTHROPIC_API_KEY into its own context from a read-only tool that plan and
+ * auto mode run unasked (C052: docs-claims#6, flag-truth-4#1, security-8#3).
+ * Now the list comes from the operator, never from the call, and a name that
+ * looks like a credential is never shown even when listed
+ * (`@crewhaus/tool-safety/env`'s checkEnvReveal).
+ *
+ * The block reaches the package through the builtin table's boot registrar
+ * (`registerProcConfig`), which every emitter, `crewhaus run` and `crewhaus
+ * eval` call; a model pool candidate's own block replaces it for that
+ * candidate's calls (`ToolExecuteContext.toolConfig`).
+ */
+import { credentialShapeOf, isEnvName } from "@crewhaus/tool-safety/env";
+/** The spec key a refusal names. */
+export const ENV_REVEAL_KEY = "tool_config.proc.env_reveal";
+/** The spec key WaitForPort's refusal names. */
+export const PORT_HOSTS_KEY = "tool_config.proc.wait_for_port_hosts";
+let envReveal = [];
+let portHosts = [];
+/** A host WaitForPort may be named: the tool's own hostname shape. */
+const HOST_SHAPE = /^[A-Za-z0-9._:-]{1,255}$/;
+/**
+ * Parse `wait_for_port_hosts` (or `waitForPortHosts`): host names or IP
+ * literals, compared case-insensitively. Throws with a sentence naming the key.
+ */
+export function parsePortHosts(config) {
+    if (config === undefined || config === null)
+        return [];
+    if (typeof config !== "object" || Array.isArray(config))
+        return [];
+    const block = config;
+    const snake = block["wait_for_port_hosts"];
+    const camel = block["waitForPortHosts"];
+    if (snake !== undefined && camel !== undefined) {
+        throw new Error("tool_config.proc sets both wait_for_port_hosts and waitForPortHosts; keep one");
+    }
+    const list = snake ?? camel;
+    if (list === undefined)
+        return [];
+    if (!Array.isArray(list) || list.some((h) => typeof h !== "string" || !HOST_SHAPE.test(h))) {
+        throw new Error(`${PORT_HOSTS_KEY} must be a list of host names or IP addresses (for example [db, 10.0.0.5])`);
+    }
+    return Object.freeze([...new Set(list.map((h) => h.toLowerCase()))].sort());
+}
+/** Parse a `tool_config.proc` block's `env_reveal`; throws with a sentence naming the key. */
+export function parseProcConfig(config) {
+    if (config === undefined || config === null)
+        return [];
+    if (typeof config !== "object" || Array.isArray(config)) {
+        throw new Error("tool_config.proc must be a mapping (for example `env_reveal: [NODE_ENV]`)");
+    }
+    const block = config;
+    const snake = block["env_reveal"];
+    const camel = block["envReveal"];
+    if (snake !== undefined && camel !== undefined) {
+        throw new Error("tool_config.proc sets both env_reveal and envReveal; keep one");
+    }
+    const list = snake ?? camel;
+    if (list === undefined)
+        return [];
+    if (!Array.isArray(list) || list.some((n) => typeof n !== "string")) {
+        throw new Error(`${ENV_REVEAL_KEY} must be a list of environment variable names`);
+    }
+    const names = list;
+    for (const name of names) {
+        if (!isEnvName(name)) {
+            throw new Error(`${ENV_REVEAL_KEY} lists ${JSON.stringify(String(name).slice(0, 64))}, which is not an environment variable name`);
+        }
+        const shape = credentialShapeOf(name);
+        if (shape !== undefined) {
+            throw new Error(`${ENV_REVEAL_KEY} lists ${name}, whose name looks like a credential (${shape}); EnvInspect never shows such a value, so remove it`);
+        }
+    }
+    return Object.freeze([...new Set(names)].sort());
+}
+/**
+ * The boot registrar: `tool_config.proc`. A block under the own key of a
+ * tool that reads it — `tool_config.envInspect` or `tool_config.waitForPort`
+ * — reaches it too, when that tool is listed (the builtin table's boot rule;
+ * no other tool-proc tool names this registrar). Both keys are parsed before either is stored,
+ * so a block with one bad key changes nothing.
+ */
+export function registerProcConfig(config) {
+    const reveal = parseProcConfig(config);
+    const hosts = parsePortHosts(config);
+    envReveal = reveal;
+    portHosts = hosts;
+}
+/**
+ * The extra hosts ONE WaitForPort call may probe: the serving candidate's
+ * block when it declares one, else the boot registration. A candidate block
+ * that does not parse allows nothing beyond loopback.
+ */
+export function portHostsFor(override) {
+    if (override === undefined)
+        return portHosts;
+    try {
+        return parsePortHosts(override);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The reveal list ONE call runs under: the serving candidate's block when it
+ * declares one (replacing the boot registration, as every package's
+ * per-call override does), else the boot registration. A candidate block
+ * that does not parse reveals nothing rather than falling back.
+ */
+export function revealAllowFor(override) {
+    if (override === undefined)
+        return envReveal;
+    try {
+        return parseProcConfig(override);
+    }
+    catch {
+        return [];
+    }
+}
+/** Test-only: back to the default, which reveals nothing and probes loopback only. */
+export function _resetProcConfig() {
+    envReveal = [];
+    portHosts = [];
+}

package/dist/lib/env.d.ts

@@ -27,21 +27,34 @@ export declare function buildSpawnEnv(parent: Readonly<Record<string, string | u
     readonly forward?: readonly string[];
     readonly set?: Readonly<Record<string, string>>;
 }): SpawnEnvResult;
-/** One variable as EnvInspect reports it. `value` is present only for names
- *  the caller explicitly asked to reveal. */
+/** Why a value named in `reveal` was not shown. */
+export type WithheldReason = "credential-shaped" | "not-allowed";
+/** One variable as EnvInspect reports it. `value` is present only for a
+ *  name the call asked to reveal AND the reveal policy allowed; `withheld`
+ *  says why a value asked for was not shown. */
 export type EnvView = {
     readonly name: string;
     readonly present: boolean;
     readonly chars: number;
     readonly value?: string;
+    readonly withheld?: WithheldReason;
 };
+/** Whether `name`'s value may be shown: the operator's list, never a credential. */
+export type RevealPolicy = (name: string) => {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: string;
+};
+/** The default policy: nothing is ever shown. */
+export declare const REVEAL_NOTHING: RevealPolicy;
 /**
  * Inspect named variables and nothing else. There is deliberately no way to
  * enumerate the environment: a caller must know the name to learn anything,
- * and learns only whether it is set and how long it is unless it names the
- * variable in `reveal`.
+ * and learns only whether it is set and how long it is — a value only for a
+ * name in `reveal` that `mayReveal` allows (C052).
  */
-export declare function inspectEnv(parent: Readonly<Record<string, string | undefined>>, names: readonly string[], reveal?: readonly string[]): {
+export declare function inspectEnv(parent: Readonly<Record<string, string | undefined>>, names: readonly string[], reveal?: readonly string[], mayReveal?: RevealPolicy): {
     readonly views: EnvView[];
     readonly invalid: readonly string[];
 };

package/dist/lib/env.js

@@ -55,13 +55,15 @@ export function buildSpawnEnv(parent, options = {}) {
         env[name] = out.get(name);
     return { env, missing, invalid };
 }
+/** The default policy: nothing is ever shown. */
+export const REVEAL_NOTHING = () => ({ ok: false, code: "not-allowed" });
 /**
  * Inspect named variables and nothing else. There is deliberately no way to
  * enumerate the environment: a caller must know the name to learn anything,
- * and learns only whether it is set and how long it is unless it names the
- * variable in `reveal`.
+ * and learns only whether it is set and how long it is — a value only for a
+ * name in `reveal` that `mayReveal` allows (C052).
  */
-export function inspectEnv(parent, names, reveal = []) {
+export function inspectEnv(parent, names, reveal = [], mayReveal = REVEAL_NOTHING) {
     const revealSet = new Set(reveal);
     const invalid = [];
     const views = [];
@@ -80,7 +82,19 @@ export function inspectEnv(parent, names, reveal = []) {
             present: value !== undefined,
             chars: value === undefined ? 0 : value.length,
         };
-        views.push(value !== undefined && revealSet.has(name) ? { ...base, value } : base);
+        if (!revealSet.has(name)) {
+            views.push(base);
+            continue;
+        }
+        const decision = mayReveal(name);
+        if (!decision.ok) {
+            views.push({
+                ...base,
+                withheld: decision.code === "credential-shaped" ? "credential-shaped" : "not-allowed",
+            });
+            continue;
+        }
+        views.push(value !== undefined ? { ...base, value } : base);
     }
     // Sorted by name so two calls with the same names in a different order
     // return the same bytes.

package/dist/lib/format.d.ts

@@ -1,8 +1,3 @@
-/**
- * Pure formatting helpers for the process tools. Nothing here spawns,
- * reads the filesystem or looks at a clock, so the behaviour that these
- * back can be unit-tested without a world.
- */
 export type CappedText = {
     readonly text: string;
     readonly truncated: boolean;
@@ -26,8 +21,18 @@ export declare function formatArgv(argv: readonly string[]): string;
 /**
  * Compile a caller-supplied regular expression, refusing the shapes behind
  * catastrophic backtracking. The pattern reaches us from a model, and a
- * waiting tool applies it repeatedly to a growing buffer, so an exponential
- * pattern would pin a core for the whole deadline.
+ * waiting tool applies it repeatedly to a growing buffer.
+ *
+ * The screen is @crewhaus/tool-safety's `compileUserRegex`, the one every
+ * tool shares (C079). 0.7.0 kept a scanner here that counted only `*` and
+ * `+` inside a group, so `(\w{1,})*$`, `(\w{1,64})*$` and `(\w\w?)*$`
+ * passed it and JavaScriptCore then gave up on them — a false "no match"
+ * after pinning the event loop. The shared screen models `{n,m}` and `?`
+ * too, accepts a repetition only when each pass ends in exactly one place,
+ * and is fuzzed; it also admits safe alternations the old scanner refused
+ * wholesale, such as `(a|b)*`. WaitForOutput still runs the match in the
+ * regex worker under a deadline: the screen is the second layer, not the
+ * first.
  */
 export declare function compileSafePattern(source: string, flags: string): {
     readonly ok: true;