@celestea/tools 2.7.1

package/dist/guard/paths.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Path canonicalization helpers for the guard.
+ *
+ * Every decision is made on the *canonical* path (`realpath`, i.e. symlinks
+ * resolved), never on the string the caller supplied:
+ * - reads/list: the canonical target must exist inside a read root; an
+ *   unresolvable target passes through so the tool reports its own error;
+ * - writes: an existing file canonicalizes directly; a not-yet-created file
+ *   canonicalizes its nearest existing ancestor and re-appends the missing
+ *   suffix, so a new file is arbitrated by the directory it would land in.
+ *
+ * This closes `..` traversal and symlink escape at once: both are collapsed by
+ * canonicalization before the containment test (parity:
+ * `crates/tools/src/guard.rs`).
+ */
+/** `realpath` or `null` when the path does not exist / cannot be resolved. */
+export declare function canonicalExisting(target: string): string | null;
+/** Resolve `target` against `workspace` (absolute targets are kept as given). */
+export declare function absolutize(target: string, workspace: string): string;
+/** Containment test on canonical paths (segment-aware, not string-prefix). */
+export declare function isInside(child: string, root: string): boolean;
+export declare function isDirectory(target: string): boolean;
+/** Canonical path of an existing read/list target, or `null`. */
+export declare function resolveExistingTarget(target: string, workspace: string): string | null;
+/**
+ * Canonical path a write would land on, or null when no ancestor exists.
+ *
+ * W824 (W812 P0-1): the FINAL component must never be treated as a plain
+ * missing file when it is a symlink. realpath fails for a dangling link, and
+ * the lexical re-append below would then hand back the link's own
+ * (in-workspace) path while fs.writeFile follows the link out of the
+ * workspace. Resolve the link target first - even when that target does not
+ * exist yet - so containment is decided on where the bytes would actually land.
+ */
+export declare function resolveWriteTarget(target: string, workspace: string): string | null;

package/dist/guard/paths.js

@@ -0,0 +1,100 @@
+/**
+ * Path canonicalization helpers for the guard.
+ *
+ * Every decision is made on the *canonical* path (`realpath`, i.e. symlinks
+ * resolved), never on the string the caller supplied:
+ * - reads/list: the canonical target must exist inside a read root; an
+ *   unresolvable target passes through so the tool reports its own error;
+ * - writes: an existing file canonicalizes directly; a not-yet-created file
+ *   canonicalizes its nearest existing ancestor and re-appends the missing
+ *   suffix, so a new file is arbitrated by the directory it would land in.
+ *
+ * This closes `..` traversal and symlink escape at once: both are collapsed by
+ * canonicalization before the containment test (parity:
+ * `crates/tools/src/guard.rs`).
+ */
+import { lstatSync, readlinkSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, resolve, sep } from "node:path";
+/** `realpath` or `null` when the path does not exist / cannot be resolved. */
+export function canonicalExisting(target) {
+    try {
+        return realpathSync(target);
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve `target` against `workspace` (absolute targets are kept as given). */
+export function absolutize(target, workspace) {
+    return isAbsolute(target) ? resolve(target) : resolve(workspace, target);
+}
+/** Containment test on canonical paths (segment-aware, not string-prefix). */
+export function isInside(child, root) {
+    if (child === root)
+        return true;
+    const prefix = root.endsWith(sep) ? root : `${root}${sep}`;
+    return child.startsWith(prefix);
+}
+export function isDirectory(target) {
+    try {
+        return statSync(target).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Canonical path of an existing read/list target, or `null`. */
+export function resolveExistingTarget(target, workspace) {
+    return canonicalExisting(absolutize(target, workspace));
+}
+/**
+ * The target of a symlink at p (resolved against its own directory), or null
+ * when p is missing / not a symlink. lstat does NOT follow the final component,
+ * so a DANGLING link still reports as a link here.
+ */
+function symlinkTarget(p) {
+    try {
+        if (!lstatSync(p).isSymbolicLink())
+            return null;
+        const link = readlinkSync(p);
+        return isAbsolute(link) ? resolve(link) : resolve(dirname(p), link);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Canonical path a write would land on, or null when no ancestor exists.
+ *
+ * W824 (W812 P0-1): the FINAL component must never be treated as a plain
+ * missing file when it is a symlink. realpath fails for a dangling link, and
+ * the lexical re-append below would then hand back the link's own
+ * (in-workspace) path while fs.writeFile follows the link out of the
+ * workspace. Resolve the link target first - even when that target does not
+ * exist yet - so containment is decided on where the bytes would actually land.
+ */
+export function resolveWriteTarget(target, workspace) {
+    let absolute = absolutize(target, workspace);
+    // Walk the final component through any symlink chain (bounded: ELOOP parity).
+    for (let hops = 0; hops < 40; hops += 1) {
+        const direct = canonicalExisting(absolute);
+        if (direct !== null)
+            return direct;
+        const link = symlinkTarget(absolute);
+        if (link === null)
+            break;
+        absolute = link;
+    }
+    const missing = [];
+    let current = absolute;
+    for (;;) {
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        missing.push(basename(current));
+        const canonicalParent = canonicalExisting(parent);
+        if (canonicalParent !== null)
+            return resolve(canonicalParent, ...missing.reverse());
+        current = parent;
+    }
+}

package/dist/http/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `http_request` error contract (`crates/tools/src/http.rs`).
+ *
+ * Transport failures are *categorized*, never prose-only:
+ * `timeout | dns | connect | redirect | invalid_url | invalid_arg |
+ * target_forbidden` — so callers and agents branch on the code. An HTTP error
+ * status is NOT a failure: it comes back in `status` for the caller to judge.
+ */
+import { ToolFailure } from "../tool-failure.js";
+export declare const HTTP_ERROR_PREFIX = "http_request";
+/** `http_request: code=<code> msg=<message>` (legacy `contract_err` shape). */
+export declare function httpFailure(code: string, message: string): ToolFailure;
+/** Marker thrown by the transport so classification can see *why* it failed. */
+export declare class TransportError extends Error {
+    readonly timedOut: boolean;
+    readonly cause: unknown;
+    constructor(cause: unknown, timedOut: boolean);
+}
+/**
+ * Categorize a transport failure. DNS vs connect refusal is separated with a
+ * best-effort lookup: a name that cannot resolve at all is `dns`, otherwise the
+ * connection itself failed (`connect`).
+ */
+export declare function classifyTransportError(e: unknown, host: string): Promise<ToolFailure>;

package/dist/http/errors.js

@@ -0,0 +1,64 @@
+/**
+ * `http_request` error contract (`crates/tools/src/http.rs`).
+ *
+ * Transport failures are *categorized*, never prose-only:
+ * `timeout | dns | connect | redirect | invalid_url | invalid_arg |
+ * target_forbidden` — so callers and agents branch on the code. An HTTP error
+ * status is NOT a failure: it comes back in `status` for the caller to judge.
+ */
+import { lookup } from "node:dns/promises";
+import { ToolFailure } from "../tool-failure.js";
+export const HTTP_ERROR_PREFIX = "http_request";
+const DNS_CODES = new Set(["ENOTFOUND", "EAI_AGAIN", "EAI_FAIL", "EAI_NODATA"]);
+const CONNECT_CODES = new Set(["ECONNREFUSED", "ECONNRESET", "EHOSTUNREACH", "ENETUNREACH", "EPIPE", "ETIMEDOUT"]);
+/** `http_request: code=<code> msg=<message>` (legacy `contract_err` shape). */
+export function httpFailure(code, message) {
+    return new ToolFailure(code, `${HTTP_ERROR_PREFIX}: code=${code} msg=${message}`);
+}
+/** Marker thrown by the transport so classification can see *why* it failed. */
+export class TransportError extends Error {
+    timedOut;
+    cause;
+    constructor(cause, timedOut) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.name = "TransportError";
+        this.cause = cause;
+        this.timedOut = timedOut;
+    }
+}
+function errnoOf(e) {
+    if (typeof e !== "object" || e === null)
+        return null;
+    const code = e.code;
+    return typeof code === "string" ? code : null;
+}
+/**
+ * Categorize a transport failure. DNS vs connect refusal is separated with a
+ * best-effort lookup: a name that cannot resolve at all is `dns`, otherwise the
+ * connection itself failed (`connect`).
+ */
+export async function classifyTransportError(e, host) {
+    const timedOut = e instanceof TransportError && e.timedOut;
+    const cause = e instanceof TransportError ? e.cause : e;
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    if (timedOut)
+        return httpFailure("timeout", detail);
+    const errno = errnoOf(cause);
+    if (errno !== null && DNS_CODES.has(errno))
+        return httpFailure("dns", detail);
+    if (errno !== null && CONNECT_CODES.has(errno))
+        return httpFailure("connect", detail);
+    const resolved = await resolves(host);
+    return httpFailure(resolved ? "connect" : "dns", detail);
+}
+async function resolves(host) {
+    if (host === "")
+        return false;
+    try {
+        const addresses = await lookup(host, { all: true });
+        return addresses.length > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/http/headers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Header handling for `http_request`: a validated request-header set and the
+ * response-header subset echoed back to the caller (legacy `HEADER_SUBSET`).
+ *
+ * Request headers are validated once and re-applied on every redirect hop;
+ * response headers are filtered to the subset that actually carries protocol
+ * information (blindly echoing `set-cookie` or auth headers would leak
+ * credentials into the transcript).
+ */
+import type { IncomingHttpHeaders } from "node:http";
+/** Response headers echoed back to the caller (values joined with ", "). */
+export declare const HEADER_SUBSET: readonly string[];
+export type HeaderPairs = ReadonlyArray<readonly [string, string]>;
+/** Validate `{name: value}` request headers (throws `invalid_arg`). */
+export declare function validateHeaderPairs(value: unknown): HeaderPairs;
+/** The subset of response headers the tool reports, in contract order. */
+export declare function pickHeaders(raw: IncomingHttpHeaders): Record<string, string>;
+/** `Content-Length`, when the server sent a usable one. */
+export declare function headerLookup(raw: IncomingHttpHeaders, name: string): string | null;

package/dist/http/headers.js

@@ -0,0 +1,62 @@
+/**
+ * Header handling for `http_request`: a validated request-header set and the
+ * response-header subset echoed back to the caller (legacy `HEADER_SUBSET`).
+ *
+ * Request headers are validated once and re-applied on every redirect hop;
+ * response headers are filtered to the subset that actually carries protocol
+ * information (blindly echoing `set-cookie` or auth headers would leak
+ * credentials into the transcript).
+ */
+import { isPlainObject } from "../schema.js";
+import { httpFailure } from "./errors.js";
+/** Response headers echoed back to the caller (values joined with ", "). */
+export const HEADER_SUBSET = [
+    "content-type",
+    "content-length",
+    "content-encoding",
+    "cache-control",
+    "etag",
+    "last-modified",
+    "location",
+    "server",
+    "www-authenticate",
+    "retry-after",
+    "date",
+];
+const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** Validate `{name: value}` request headers (throws `invalid_arg`). */
+export function validateHeaderPairs(value) {
+    if (value === undefined)
+        return [];
+    if (!isPlainObject(value))
+        throw httpFailure("invalid_arg", "'headers' must be an object of strings");
+    const pairs = [];
+    for (const [name, raw] of Object.entries(value)) {
+        if (typeof raw !== "string")
+            throw httpFailure("invalid_arg", `header '${name}' value must be a string`);
+        if (!HEADER_NAME.test(name))
+            throw httpFailure("invalid_arg", `bad header name '${name}'`);
+        if (/[\r\n]/.test(raw))
+            throw httpFailure("invalid_arg", `header '${name}' value must not contain CR/LF`);
+        pairs.push([name, raw]);
+    }
+    return pairs;
+}
+/** The subset of response headers the tool reports, in contract order. */
+export function pickHeaders(raw) {
+    const out = {};
+    for (const name of HEADER_SUBSET) {
+        const value = raw[name];
+        if (value === undefined)
+            continue;
+        out[name] = Array.isArray(value) ? value.join(", ") : value;
+    }
+    return out;
+}
+/** `Content-Length`, when the server sent a usable one. */
+export function headerLookup(raw, name) {
+    const value = raw[name];
+    if (value === undefined)
+        return null;
+    return Array.isArray(value) ? (value[0] ?? null) : value;
+}

package/dist/http/redirects.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Bounded, policy-checked redirect following (`crates/tools/src/http.rs`).
+ *
+ * The tool always follows redirects itself instead of letting the transport do
+ * it, for one security reason: every hop is re-authorized against the SSRF
+ * policy, so a permitted host cannot bounce the request into a denied network.
+ * 301/302/303 degrade to `GET` without a body (parity); the chain is
+ * capped at [MAX_REDIRECT_HOPS], and a non-http(s) hop target is rejected.
+ *
+ * **Authorize then PIN (W738 P1)**: the check and the connect are one step. The
+ * policy call returns the addresses it approved ([HttpTargetPolicy.resolveChecked])
+ * and those exact addresses are handed to the transport, which connects to them
+ * without resolving again — and it is repeated for EVERY hop. A host name whose
+ * DNS answer changes between the check and the connect (rebinding) therefore
+ * cannot be used to reach an address the policy refused.
+ */
+import type { HeaderPairs } from "./headers.js";
+import type { HttpTargetPolicy } from "./ssrf.js";
+import { type TransportResult } from "./transport.js";
+/** Redirect hops the tool follows before failing with `code=redirect`. */
+export declare const MAX_REDIRECT_HOPS = 5;
+export interface FetchOptions {
+    method: string;
+    headers: HeaderPairs;
+    body: string | null;
+    timeoutMs: number;
+    maxBodyBytes: number;
+    policy: HttpTargetPolicy;
+}
+/** Follow up to [MAX_REDIRECT_HOPS] redirects; returns the final response. */
+export declare function fetchWithPolicy(url: URL, options: FetchOptions): Promise<TransportResult>;

package/dist/http/redirects.js

@@ -0,0 +1,76 @@
+/**
+ * Bounded, policy-checked redirect following (`crates/tools/src/http.rs`).
+ *
+ * The tool always follows redirects itself instead of letting the transport do
+ * it, for one security reason: every hop is re-authorized against the SSRF
+ * policy, so a permitted host cannot bounce the request into a denied network.
+ * 301/302/303 degrade to `GET` without a body (parity); the chain is
+ * capped at [MAX_REDIRECT_HOPS], and a non-http(s) hop target is rejected.
+ *
+ * **Authorize then PIN (W738 P1)**: the check and the connect are one step. The
+ * policy call returns the addresses it approved ([HttpTargetPolicy.resolveChecked])
+ * and those exact addresses are handed to the transport, which connects to them
+ * without resolving again — and it is repeated for EVERY hop. A host name whose
+ * DNS answer changes between the check and the connect (rebinding) therefore
+ * cannot be used to reach an address the policy refused.
+ */
+import { classifyTransportError, httpFailure } from "./errors.js";
+import { requestOnce } from "./transport.js";
+/** Redirect hops the tool follows before failing with `code=redirect`. */
+export const MAX_REDIRECT_HOPS = 5;
+/** Follow up to [MAX_REDIRECT_HOPS] redirects; returns the final response. */
+export async function fetchWithPolicy(url, options) {
+    let current = url;
+    let method = options.method;
+    let body = options.body;
+    for (let hop = 0; hop <= MAX_REDIRECT_HOPS; hop += 1) {
+        const checked = await options.policy.resolveChecked(current.toString());
+        if (checked.reason !== null)
+            throw httpFailure("target_forbidden", checked.reason);
+        const result = await sendOnce(current, method, body, options, checked.ips);
+        if (!isRedirect(result.status) || result.location === null)
+            return result;
+        if (hop === MAX_REDIRECT_HOPS) {
+            throw httpFailure("redirect", `redirect chain longer than ${MAX_REDIRECT_HOPS} hops`);
+        }
+        const next = nextHop(current, result.location);
+        if (result.status === 301 || result.status === 302 || result.status === 303) {
+            method = "GET";
+            body = null;
+        }
+        current = next;
+    }
+    throw httpFailure("redirect", `redirect chain longer than ${MAX_REDIRECT_HOPS} hops`);
+}
+async function sendOnce(url, method, body, options, pinnedIps) {
+    try {
+        return await requestOnce({
+            url,
+            method,
+            headers: options.headers,
+            body,
+            timeoutMs: options.timeoutMs,
+            maxBodyBytes: options.maxBodyBytes,
+            pinnedIps,
+        });
+    }
+    catch (e) {
+        throw await classifyTransportError(e, url.hostname);
+    }
+}
+function nextHop(current, location) {
+    let next;
+    try {
+        next = new URL(location, current);
+    }
+    catch {
+        throw httpFailure("redirect", `unparseable redirect location '${location}'`);
+    }
+    if (next.protocol !== "http:" && next.protocol !== "https:") {
+        throw httpFailure("invalid_url", `redirect to scheme '${next.protocol.replace(":", "")}' not allowed`);
+    }
+    return next;
+}
+function isRedirect(status) {
+    return status >= 300 && status < 400;
+}

package/dist/http/ssrf.d.ts

@@ -0,0 +1,105 @@
+/**
+ * SSRF target policy for `http_request` (`crates/tools/src/http.rs`, W249 P0-3).
+ *
+ * `CELESTEA_HTTP_ALLOW` / `CELESTEA_HTTP_DENY` carry comma-separated IP/CIDR
+ * entries. Both unset ⇒ the policy is inactive and every target is allowed
+ * (status quo, surfaced as `active === false` so the caller can decide to log
+ * it). When a policy is active, EVERY resolved IP of the target — and of every
+ * redirect hop — must pass it (`allow` is a whitelist when non-empty, `deny`
+ * always wins).
+ *
+ * **Fail closed**: a malformed entry makes the policy deny everything until the
+ * operator fixes the configuration — a typo can never silently widen access.
+ *
+ * **No check-then-use (W738 P1)**: [HttpTargetPolicy.checkUrl] is a verdict only.
+ * The *authorizing* call is [HttpTargetPolicy.resolveChecked], which returns the
+ * exact addresses it approved so the transport can PIN them: between the check
+ * and the connect there is no second `getaddrinfo`, so a host name that answers
+ * with a public address during the check and with `127.0.0.1`/`169.254.169.254`
+ * at connect time (DNS rebinding) can no longer reach an address the policy
+ * refused. Never connect by name after a check.
+ *
+ * W516 (session grants): a host may pass an [SsrfGrantView] with the session's
+ * `net_hosts` entries. They are UNIONed into the allow side only, and only when
+ * the env policy is active: neither the deny list nor the fail-closed verdict
+ * can be reached by a grant, and an inactive policy (both env vars unset) stays
+ * inactive — a grant must never *tighten* a deployment into a whitelist
+ * (`netHostsIneffective` reports exactly that case to the host's audit).
+ */
+export declare const ENV_HTTP_ALLOW = "CELESTEA_HTTP_ALLOW";
+export declare const ENV_HTTP_DENY = "CELESTEA_HTTP_DENY";
+export interface IpRange {
+    /** 4 or 6 — an IPv4 range never matches an IPv6 address. */
+    family: 4 | 6;
+    base: bigint;
+    prefix: number;
+}
+/** Parse `1.2.3.4`, `10.0.0.0/8`, `::1` or `fd00::/8` (throws on nonsense). */
+export declare function parseIpRange(entry: string): IpRange;
+/** Containment test on the masked network prefix. */
+export declare function ipInRange(range: IpRange, ip: string): boolean;
+/** Session-grant view of the SSRF policy (W516): allow-side widening only. */
+export interface SsrfGrantView {
+    /** `net_hosts` scope: IP/CIDR entries and/or host names. */
+    netHosts?: readonly string[];
+}
+/**
+ * Host -> addresses resolver. Returns the address list, or a failure reason
+ * string (which becomes the denial reason). Default: `node:dns/promises`
+ * `lookup` (all families, verbatim order).
+ */
+export type HostResolver = (host: string, port: number) => Promise<readonly string[] | string>;
+/** Injectable seams of the policy (tests, custom DNS, W738 pinning harnesses). */
+export interface HttpTargetPolicyOptions {
+    resolver?: HostResolver;
+}
+/** Verdict + the exact approved addresses of ONE target. */
+export interface CheckedTarget {
+    /** `null` when the target is authorized, else the denial reason. */
+    reason: string | null;
+    /** Approved addresses to pin; empty whenever `reason !== null`. */
+    ips: string[];
+}
+export declare class HttpTargetPolicy {
+    private readonly allow;
+    private readonly deny;
+    private readonly failClosed;
+    private readonly hostAllow;
+    private readonly hostsIneffective;
+    private readonly resolver;
+    private constructor();
+    /** Parse the two lists; a malformed entry throws (see [fromEnv] for env use). */
+    static parse(allowSpec?: string | null, denySpec?: string | null, options?: HttpTargetPolicyOptions): HttpTargetPolicy;
+    /**
+     * Policy from the environment; malformed config ⇒ fail closed. Session grants
+     * are merged on the allow side ONLY (see the module docs): the env policy must
+     * be active for them to count at all.
+     */
+    static fromEnv(env?: NodeJS.ProcessEnv, grants?: SsrfGrantView, options?: HttpTargetPolicyOptions): HttpTargetPolicy;
+    /** Whether the policy constrains targets at all. */
+    get active(): boolean;
+    /** Allow/deny entry counts (diagnostics). */
+    get sizes(): {
+        allow: number;
+        deny: number;
+        failClosed: boolean;
+    };
+    /** true when `net_hosts` grants were dropped because the env policy is off. */
+    get netHostsIneffective(): boolean;
+    /**
+     * Verdict only (`null` = authorized). NEVER sufficient on its own: the caller
+     * must connect to the addresses returned by [resolveChecked] instead of
+     * letting the transport resolve the name again (W738 check-then-use).
+     */
+    checkUrl(url: string): Promise<string | null>;
+    /**
+     * Authorize a target and return the addresses it approved. `reason !== null`
+     * ⇒ `ips` is empty and nothing may be connected; `reason === null` ⇒ `ips` is
+     * non-empty and is the COMPLETE set of addresses the caller may use (pin them
+     * on every hop).
+     */
+    resolveChecked(url: string): Promise<CheckedTarget>;
+    private ipAllowed;
+}
+/** Every address a target host resolves to, or a failure reason string. */
+export declare function resolveTargets(host: string, port: number): Promise<string[] | string>;