@pentoshi/clai 0.10.5 → 0.11.0

package/dist/tools/web/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../../src/tools/web/budget.ts"],"names":[],"mappings":"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"}

package/dist/tools/web/capture.d.ts

@@ -0,0 +1,201 @@
+/**
+ * `Capture` — pure observation builder for a single `web.fetch` invocation.
+ *
+ * The fetch transport in `fetch-core.ts` feeds events into this builder
+ * (DNS resolution, TCP connect, TLS handshake, response headers, redirect
+ * hops, `Set-Cookie` lines) and the builder accumulates the structured
+ * fields the {@link WebFetchMetadata} envelope needs:
+ *
+ * - {@link TimingInfo}: `dnsMs`, `tcpMs`, `tlsMs`, `ttfbMs`, `totalMs`
+ * - {@link TlsInfo} from the final hop's `tls.TLSSocket`
+ *   (`getProtocol()`, `getCipher().name`, `getPeerCertificate(true)`)
+ * - response headers (lowercased keys, repeat values joined with `, `)
+ * - the redirect chain (capped at {@link MAX_REDIRECT_HOPS})
+ * - the resolved IP and the final hostname
+ * - `Set-Cookie` cookies (capped at {@link MAX_COOKIES_CAPTURED})
+ *
+ * The builder performs **no I/O** — it never touches the network, the
+ * filesystem, or `auditLog`. It is a pure data sink so the transport
+ * layer in `fetch-core.ts` can be tested independently of the
+ * Node `https`/`tls` machinery.
+ *
+ * Per-hop semantics:
+ * - `setHopContext(hostname)` is called by the transport at the start of
+ *   each hop; the value of the *last* hop becomes
+ *   {@link CapturedFields.finalHostname}.
+ * - {@link Capture.markDnsResolved} replaces the running `dnsMs` /
+ *   `resolvedIp` so the values surfaced in {@link CapturedFields}
+ *   correspond to the *final* hop. Same for `tcpMs`, `tlsMs`, and
+ *   `ttfbMs` — only the last hop's measurements are returned.
+ * - {@link Capture.addRedirectHop} appends one entry per intermediate
+ *   3xx hop; the array is bounded at {@link MAX_REDIRECT_HOPS}.
+ * - {@link Capture.addSetCookieHeader} parses every observed
+ *   `Set-Cookie` line via {@link parseSetCookie}; the resulting array is
+ *   bounded at {@link MAX_COOKIES_CAPTURED}.
+ *
+ * Redaction and 4096-char header-value truncation are applied later by
+ * `redact.applyToHeaders` / `redact.applyToCookies` and the 64 KiB
+ * metadata budget by `budget.enforce`. This module only collects.
+ */
+import type { IncomingHttpHeaders } from "node:http";
+import type { TLSSocket } from "node:tls";
+import { type CookieInfo, type HeaderMap, type RedirectChain, type TimingInfo, type TlsInfo } from "./types.js";
+/**
+ * Snapshot of the structured fields the builder has accumulated when
+ * `fetch-core.ts` finalises the response. The shape matches the slice of
+ * {@link WebFetchMetadata} that depends on per-hop transport
+ * observation; the fetch handler combines this with `requestedUrl`,
+ * `finalUrl`, `mode`, `bytesReceived`, `truncated`, etc. before applying
+ * `redact.applyToHeaders` / `redact.applyToCookies` and `budget.enforce`.
+ */
+export interface CapturedFields {
+    /** IP address contacted on the final hop. */
+    resolvedIp: string;
+    /** Hostname of the final hop (the one whose body is returned). */
+    finalHostname: string;
+    /** Integer HTTP status of the final response. */
+    status: number;
+    /** Lowercased response headers from the final hop, repeats joined. */
+    headers: HeaderMap;
+    /** TLS session details from the final hop, when the scheme was https. */
+    tls?: TlsInfo;
+    /** Per-phase timings; `tlsMs` is omitted on http:// requests. */
+    timing: TimingInfo;
+    /** Up to {@link MAX_REDIRECT_HOPS} hops in chronological order. */
+    redirectChain: RedirectChain;
+    /** Up to {@link MAX_COOKIES_CAPTURED} cookies parsed from `Set-Cookie`. */
+    cookies: CookieInfo[];
+}
+/**
+ * Pure builder that records the per-hop observations made by
+ * `fetch-core.ts` and assembles them into a {@link CapturedFields}
+ * snapshot via {@link Capture.finalize}.
+ *
+ * The builder is single-use: callers should construct one `Capture` per
+ * `web.fetch` invocation and discard it after `finalize`.
+ */
+export declare class Capture {
+    /** Final-hop DNS-resolution time in milliseconds. */
+    private dnsMs;
+    /** Final-hop TCP-connect time in milliseconds. */
+    private tcpMs;
+    /** Final-hop TLS-handshake time in milliseconds (https only). */
+    private tlsMs;
+    /** Final-hop time-to-first-byte in milliseconds. */
+    private ttfbMs;
+    /** Final-hop resolved IP, set by {@link markDnsResolved}. */
+    private resolvedIp;
+    /** Final-hop hostname, set by {@link setHopContext}. */
+    private finalHostname;
+    /** Final-hop HTTP status, set by {@link markResponse}. */
+    private status;
+    /** Final-hop normalised headers, set by {@link markResponse}. */
+    private headers;
+    /** Final-hop TLS info (https only), set by {@link markTlsHandshaked}. */
+    private tls;
+    /** Redirect hops, capped at {@link MAX_REDIRECT_HOPS}. */
+    private readonly redirectChain;
+    /** Captured cookies, capped at {@link MAX_COOKIES_CAPTURED}. */
+    private readonly cookies;
+    /**
+     * Whether the current invocation is an `https://` fetch. When `false`,
+     * `tlsMs` is omitted from {@link TimingInfo} and `tls` from
+     * {@link CapturedFields} per Requirements 2.16, 2.24, and 2.25.
+     */
+    private readonly isHttps;
+    /**
+     * Construct a fresh builder.
+     *
+     * @param opts.isHttps - Whether the request URL used `https://`.
+     *   Controls whether `timing.tlsMs` and `tls` are populated.
+     * @param opts.finalHostname - Optional initial hostname; the transport
+     *   will overwrite this via {@link setHopContext} as redirects are
+     *   followed.
+     */
+    constructor(opts: {
+        isHttps: boolean;
+        finalHostname?: string;
+    });
+    /**
+     * Record the hostname of the hop the transport is about to issue.
+     *
+     * Called once per hop, before {@link markDnsResolved}. The most-recent
+     * value becomes {@link CapturedFields.finalHostname}.
+     */
+    setHopContext(hostname: string): void;
+    /**
+     * Record the DNS-resolution outcome for the current hop.
+     *
+     * The most-recent values overwrite any earlier ones so the values
+     * surfaced in {@link TimingInfo.dnsMs} and
+     * {@link CapturedFields.resolvedIp} correspond to the final hop.
+     */
+    markDnsResolved(ms: number, ip: string): void;
+    /**
+     * Record the TCP-connect time for the current hop. The most-recent
+     * value wins (see class-level docstring for per-hop semantics).
+     */
+    markTcpConnected(ms: number): void;
+    /**
+     * Record the TLS handshake time and extract {@link TlsInfo} from the
+     * final-hop `tls.TLSSocket`.
+     *
+     * - `protocol`           ← `socket.getProtocol()` (`""` if null).
+     * - `cipher`             ← `socket.getCipher().name` (`""` if missing).
+     * - `subjectCN/issuerCN` ← `cert.subject.CN` / `cert.issuer.CN`.
+     * - `subjectAltNames`    ← parsed from `cert.subjectaltname`.
+     * - `notBefore/notAfter` ← `cert.valid_from` / `cert.valid_to` parsed
+     *                          to ISO 8601 (falls back to the raw value).
+     * - `fingerprintSha256`  ← lowercase, colon-separated SHA-256 of
+     *                          `cert.raw` via `node:crypto`.
+     *
+     * Calling this method on an http:// fetch is harmless but pointless —
+     * the constructor's `isHttps=false` flag suppresses the field in
+     * {@link finalize} regardless.
+     */
+    markTlsHandshaked(ms: number, socket: TLSSocket): void;
+    /**
+     * Record the final-hop response: HTTP status, raw headers
+     * (lowercased and joined into a {@link HeaderMap}), and TTFB.
+     *
+     * `Set-Cookie` is preserved in `headers` joined with `, ` like every
+     * other repeated header so the audit/redact passes can act on it.
+     * Per-cookie capture happens via {@link addSetCookieHeader}, which
+     * `fetch-core.ts` calls once per `Set-Cookie` line observed.
+     */
+    markResponse(status: number, rawHeaders: IncomingHttpHeaders, ttfbMs: number): void;
+    /**
+     * Append a redirect hop to the chronological chain.
+     *
+     * Hops in excess of {@link MAX_REDIRECT_HOPS} are silently dropped so
+     * the array always satisfies the cap from Requirement 2.26.
+     * `fetch-core.ts` is responsible for surfacing the
+     * `redirect-limit` error when the cap is reached; this builder just
+     * stops accumulating.
+     */
+    addRedirectHop(url: string, status: number, location?: string): void;
+    /**
+     * Parse one `Set-Cookie` header value via {@link parseSetCookie} and
+     * append the resulting {@link CookieInfo}, bounded at
+     * {@link MAX_COOKIES_CAPTURED}.
+     *
+     * Cookies in excess of the cap are silently dropped, matching
+     * Requirement 2.31.
+     */
+    addSetCookieHeader(value: string): void;
+    /**
+     * Produce the {@link CapturedFields} snapshot.
+     *
+     * @param totalMs - Wall-clock duration of the whole invocation, in
+     *   milliseconds. Stored in {@link TimingInfo.totalMs}.
+     *
+     * Optional fields obey the design's "include flags applied at the
+     * adapter, not at the builder" principle: this method always emits
+     * every field it observed, including `tls` (when `isHttps=true` and a
+     * handshake was captured). The fetch handler in `fetch.ts` is
+     * responsible for honouring `includeTls` / `includeTiming` /
+     * `includeRedirectChain` by stripping fields from the assembled
+     * {@link WebFetchMetadata} *after* this snapshot is produced.
+     */
+    finalize(totalMs: number): CapturedFields;
+}

package/dist/tools/web/capture.js

@@ -0,0 +1,380 @@
+/**
+ * `Capture` — pure observation builder for a single `web.fetch` invocation.
+ *
+ * The fetch transport in `fetch-core.ts` feeds events into this builder
+ * (DNS resolution, TCP connect, TLS handshake, response headers, redirect
+ * hops, `Set-Cookie` lines) and the builder accumulates the structured
+ * fields the {@link WebFetchMetadata} envelope needs:
+ *
+ * - {@link TimingInfo}: `dnsMs`, `tcpMs`, `tlsMs`, `ttfbMs`, `totalMs`
+ * - {@link TlsInfo} from the final hop's `tls.TLSSocket`
+ *   (`getProtocol()`, `getCipher().name`, `getPeerCertificate(true)`)
+ * - response headers (lowercased keys, repeat values joined with `, `)
+ * - the redirect chain (capped at {@link MAX_REDIRECT_HOPS})
+ * - the resolved IP and the final hostname
+ * - `Set-Cookie` cookies (capped at {@link MAX_COOKIES_CAPTURED})
+ *
+ * The builder performs **no I/O** — it never touches the network, the
+ * filesystem, or `auditLog`. It is a pure data sink so the transport
+ * layer in `fetch-core.ts` can be tested independently of the
+ * Node `https`/`tls` machinery.
+ *
+ * Per-hop semantics:
+ * - `setHopContext(hostname)` is called by the transport at the start of
+ *   each hop; the value of the *last* hop becomes
+ *   {@link CapturedFields.finalHostname}.
+ * - {@link Capture.markDnsResolved} replaces the running `dnsMs` /
+ *   `resolvedIp` so the values surfaced in {@link CapturedFields}
+ *   correspond to the *final* hop. Same for `tcpMs`, `tlsMs`, and
+ *   `ttfbMs` — only the last hop's measurements are returned.
+ * - {@link Capture.addRedirectHop} appends one entry per intermediate
+ *   3xx hop; the array is bounded at {@link MAX_REDIRECT_HOPS}.
+ * - {@link Capture.addSetCookieHeader} parses every observed
+ *   `Set-Cookie` line via {@link parseSetCookie}; the resulting array is
+ *   bounded at {@link MAX_COOKIES_CAPTURED}.
+ *
+ * Redaction and 4096-char header-value truncation are applied later by
+ * `redact.applyToHeaders` / `redact.applyToCookies` and the 64 KiB
+ * metadata budget by `budget.enforce`. This module only collects.
+ */
+import { createHash } from "node:crypto";
+import { parseSetCookie } from "./readable.js";
+import { MAX_COOKIES_CAPTURED, MAX_REDIRECT_HOPS, } from "./types.js";
+/**
+ * Pure builder that records the per-hop observations made by
+ * `fetch-core.ts` and assembles them into a {@link CapturedFields}
+ * snapshot via {@link Capture.finalize}.
+ *
+ * The builder is single-use: callers should construct one `Capture` per
+ * `web.fetch` invocation and discard it after `finalize`.
+ */
+export class Capture {
+    /** Final-hop DNS-resolution time in milliseconds. */
+    dnsMs = 0;
+    /** Final-hop TCP-connect time in milliseconds. */
+    tcpMs = 0;
+    /** Final-hop TLS-handshake time in milliseconds (https only). */
+    tlsMs = undefined;
+    /** Final-hop time-to-first-byte in milliseconds. */
+    ttfbMs = 0;
+    /** Final-hop resolved IP, set by {@link markDnsResolved}. */
+    resolvedIp = "";
+    /** Final-hop hostname, set by {@link setHopContext}. */
+    finalHostname = "";
+    /** Final-hop HTTP status, set by {@link markResponse}. */
+    status = 0;
+    /** Final-hop normalised headers, set by {@link markResponse}. */
+    headers = {};
+    /** Final-hop TLS info (https only), set by {@link markTlsHandshaked}. */
+    tls = undefined;
+    /** Redirect hops, capped at {@link MAX_REDIRECT_HOPS}. */
+    redirectChain = [];
+    /** Captured cookies, capped at {@link MAX_COOKIES_CAPTURED}. */
+    cookies = [];
+    /**
+     * Whether the current invocation is an `https://` fetch. When `false`,
+     * `tlsMs` is omitted from {@link TimingInfo} and `tls` from
+     * {@link CapturedFields} per Requirements 2.16, 2.24, and 2.25.
+     */
+    isHttps;
+    /**
+     * Construct a fresh builder.
+     *
+     * @param opts.isHttps - Whether the request URL used `https://`.
+     *   Controls whether `timing.tlsMs` and `tls` are populated.
+     * @param opts.finalHostname - Optional initial hostname; the transport
+     *   will overwrite this via {@link setHopContext} as redirects are
+     *   followed.
+     */
+    constructor(opts) {
+        this.isHttps = opts.isHttps;
+        if (typeof opts.finalHostname === "string") {
+            this.finalHostname = opts.finalHostname;
+        }
+    }
+    /**
+     * Record the hostname of the hop the transport is about to issue.
+     *
+     * Called once per hop, before {@link markDnsResolved}. The most-recent
+     * value becomes {@link CapturedFields.finalHostname}.
+     */
+    setHopContext(hostname) {
+        if (typeof hostname === "string" && hostname.length > 0) {
+            this.finalHostname = hostname;
+        }
+    }
+    /**
+     * Record the DNS-resolution outcome for the current hop.
+     *
+     * The most-recent values overwrite any earlier ones so the values
+     * surfaced in {@link TimingInfo.dnsMs} and
+     * {@link CapturedFields.resolvedIp} correspond to the final hop.
+     */
+    markDnsResolved(ms, ip) {
+        this.dnsMs = sanitiseMs(ms);
+        if (typeof ip === "string" && ip.length > 0) {
+            this.resolvedIp = ip;
+        }
+    }
+    /**
+     * Record the TCP-connect time for the current hop. The most-recent
+     * value wins (see class-level docstring for per-hop semantics).
+     */
+    markTcpConnected(ms) {
+        this.tcpMs = sanitiseMs(ms);
+    }
+    /**
+     * Record the TLS handshake time and extract {@link TlsInfo} from the
+     * final-hop `tls.TLSSocket`.
+     *
+     * - `protocol`           ← `socket.getProtocol()` (`""` if null).
+     * - `cipher`             ← `socket.getCipher().name` (`""` if missing).
+     * - `subjectCN/issuerCN` ← `cert.subject.CN` / `cert.issuer.CN`.
+     * - `subjectAltNames`    ← parsed from `cert.subjectaltname`.
+     * - `notBefore/notAfter` ← `cert.valid_from` / `cert.valid_to` parsed
+     *                          to ISO 8601 (falls back to the raw value).
+     * - `fingerprintSha256`  ← lowercase, colon-separated SHA-256 of
+     *                          `cert.raw` via `node:crypto`.
+     *
+     * Calling this method on an http:// fetch is harmless but pointless —
+     * the constructor's `isHttps=false` flag suppresses the field in
+     * {@link finalize} regardless.
+     */
+    markTlsHandshaked(ms, socket) {
+        this.tlsMs = sanitiseMs(ms);
+        this.tls = extractTlsInfo(socket);
+    }
+    /**
+     * Record the final-hop response: HTTP status, raw headers
+     * (lowercased and joined into a {@link HeaderMap}), and TTFB.
+     *
+     * `Set-Cookie` is preserved in `headers` joined with `, ` like every
+     * other repeated header so the audit/redact passes can act on it.
+     * Per-cookie capture happens via {@link addSetCookieHeader}, which
+     * `fetch-core.ts` calls once per `Set-Cookie` line observed.
+     */
+    markResponse(status, rawHeaders, ttfbMs) {
+        this.status = Number.isInteger(status) ? status : 0;
+        this.ttfbMs = sanitiseMs(ttfbMs);
+        this.headers = normaliseHeaders(rawHeaders);
+    }
+    /**
+     * Append a redirect hop to the chronological chain.
+     *
+     * Hops in excess of {@link MAX_REDIRECT_HOPS} are silently dropped so
+     * the array always satisfies the cap from Requirement 2.26.
+     * `fetch-core.ts` is responsible for surfacing the
+     * `redirect-limit` error when the cap is reached; this builder just
+     * stops accumulating.
+     */
+    addRedirectHop(url, status, location) {
+        if (this.redirectChain.length >= MAX_REDIRECT_HOPS)
+            return;
+        if (typeof url !== "string" || url.length === 0)
+            return;
+        const hop = {
+            url,
+            status: Number.isInteger(status) ? status : 0,
+        };
+        if (typeof location === "string" && location.length > 0) {
+            hop.location = location;
+        }
+        this.redirectChain.push(hop);
+    }
+    /**
+     * Parse one `Set-Cookie` header value via {@link parseSetCookie} and
+     * append the resulting {@link CookieInfo}, bounded at
+     * {@link MAX_COOKIES_CAPTURED}.
+     *
+     * Cookies in excess of the cap are silently dropped, matching
+     * Requirement 2.31.
+     */
+    addSetCookieHeader(value) {
+        if (this.cookies.length >= MAX_COOKIES_CAPTURED)
+            return;
+        if (typeof value !== "string" || value.length === 0)
+            return;
+        this.cookies.push(parseSetCookie(value));
+    }
+    /**
+     * Produce the {@link CapturedFields} snapshot.
+     *
+     * @param totalMs - Wall-clock duration of the whole invocation, in
+     *   milliseconds. Stored in {@link TimingInfo.totalMs}.
+     *
+     * Optional fields obey the design's "include flags applied at the
+     * adapter, not at the builder" principle: this method always emits
+     * every field it observed, including `tls` (when `isHttps=true` and a
+     * handshake was captured). The fetch handler in `fetch.ts` is
+     * responsible for honouring `includeTls` / `includeTiming` /
+     * `includeRedirectChain` by stripping fields from the assembled
+     * {@link WebFetchMetadata} *after* this snapshot is produced.
+     */
+    finalize(totalMs) {
+        const timing = {
+            dnsMs: this.dnsMs,
+            tcpMs: this.tcpMs,
+            ttfbMs: this.ttfbMs,
+            totalMs: sanitiseMs(totalMs),
+        };
+        if (this.isHttps && this.tlsMs !== undefined) {
+            timing.tlsMs = this.tlsMs;
+        }
+        const fields = {
+            resolvedIp: this.resolvedIp,
+            finalHostname: this.finalHostname,
+            status: this.status,
+            headers: this.headers,
+            timing,
+            redirectChain: this.redirectChain.slice(),
+            cookies: this.cookies.slice(),
+        };
+        if (this.isHttps && this.tls !== undefined) {
+            fields.tls = this.tls;
+        }
+        return fields;
+    }
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+/**
+ * Coerce an arbitrary millisecond value into a non-negative finite
+ * integer. Used to keep timing arithmetic resilient to clock skew or
+ * non-numeric inputs from a stubbed transport.
+ */
+function sanitiseMs(ms) {
+    if (typeof ms !== "number" || !Number.isFinite(ms))
+        return 0;
+    if (ms < 0)
+        return 0;
+    return Math.round(ms);
+}
+/**
+ * Lower-case every header key and join repeat values per RFC 7230 with
+ * `, ` so the `redact`/`budget` passes downstream see a uniform
+ * `Record<string, string>` shape. Header-value length truncation is
+ * deferred to `redact.applyToHeaders` (4096-char cap from
+ * Requirement 2.21) so this builder stays purely observational.
+ */
+function normaliseHeaders(raw) {
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (value === undefined)
+            continue;
+        const lowerKey = key.toLowerCase();
+        if (Array.isArray(value)) {
+            out[lowerKey] = value.join(", ");
+        }
+        else {
+            out[lowerKey] = String(value);
+        }
+    }
+    return out;
+}
+/**
+ * Pull the TLS session details we surface from the leaf certificate.
+ *
+ * `getCipher()` returns `null` for sessions that have not completed the
+ * handshake — defensive `?? ""` keeps the field present rather than
+ * throwing when fed a half-initialised socket from a test stub.
+ */
+function extractTlsInfo(socket) {
+    const protocol = socket.getProtocol() ?? "";
+    const cipherInfo = socket.getCipher();
+    const cipher = cipherInfo?.name ?? "";
+    // `getPeerCertificate(true)` returns the detailed certificate object
+    // including the DER `raw` bytes we need for the SHA-256 fingerprint.
+    // Some test stubs return a plain object lacking `raw`; we guard for
+    // that with a typeof check below.
+    const cert = socket.getPeerCertificate(true);
+    const subjectCN = pickCN(cert?.subject?.CN);
+    const issuerCN = pickCN(cert?.issuer?.CN);
+    const subjectAltNames = parseSubjectAltName(cert?.subjectaltname);
+    const notBefore = isoFromCertDate(cert?.valid_from);
+    const notAfter = isoFromCertDate(cert?.valid_to);
+    const fingerprintSha256 = computeSha256Fingerprint(cert?.raw);
+    return {
+        protocol,
+        cipher,
+        subjectCN,
+        issuerCN,
+        subjectAltNames,
+        notBefore,
+        notAfter,
+        fingerprintSha256,
+    };
+}
+/**
+ * `tls.Certificate.CN` is typed as `string | string[] | undefined`.
+ * When multiple CN values are present, we take the first to keep the
+ * field shape simple; SAN expansion already covers the multi-name case.
+ */
+function pickCN(cn) {
+    if (typeof cn === "string")
+        return cn;
+    if (Array.isArray(cn) && cn.length > 0) {
+        return typeof cn[0] === "string" ? cn[0] : "";
+    }
+    return "";
+}
+/**
+ * Parse `cert.subjectaltname` (the comma-separated string emitted by
+ * Node's `getPeerCertificate`, e.g. `"DNS:example.com, IP Address:1.2.3.4"`)
+ * into a string array. The type prefix (`DNS:`, `IP Address:`, `URI:`,
+ * `email:`) is preserved so callers retain SAN-type information.
+ *
+ * Empty / undefined input yields an empty array.
+ */
+function parseSubjectAltName(san) {
+    if (typeof san !== "string" || san.length === 0)
+        return [];
+    return san
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Convert a certificate `valid_from`/`valid_to` date string (which uses
+ * the OpenSSL `MMM DD HH:mm:ss YYYY GMT` format) into ISO 8601. Falls
+ * back to the raw input when parsing fails so the field remains useful
+ * for forensic review even if the format is unexpected.
+ */
+function isoFromCertDate(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return "";
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms))
+        return value;
+    return new Date(ms).toISOString();
+}
+/**
+ * Compute the SHA-256 digest of the certificate's DER bytes via
+ * `node:crypto` and format it as a lowercase, colon-separated hex
+ * string (`"ab:cd:ef:..."`), matching the `cert.fingerprint256` shape
+ * Node exposes for SHA-1 digests.
+ *
+ * Returns `""` when `raw` is missing or not a Buffer-like value (e.g. a
+ * test stub that omitted the field).
+ */
+function computeSha256Fingerprint(raw) {
+    if (raw === undefined || raw === null)
+        return "";
+    let bytes;
+    if (Buffer.isBuffer(raw)) {
+        bytes = raw;
+    }
+    else if (raw instanceof Uint8Array) {
+        bytes = Buffer.from(raw);
+    }
+    else {
+        return "";
+    }
+    const hex = createHash("sha256").update(bytes).digest("hex");
+    // Pair-up the hex string into colon-separated bytes: `abcdef…` →
+    // `ab:cd:ef:…`. The regex match is bounded by the deterministic
+    // 64-char output of SHA-256 so there is no unbounded work here.
+    const pairs = hex.match(/.{2}/g) ?? [];
+    return pairs.join(":");
+}
+//# sourceMappingURL=capture.js.map

package/dist/tools/web/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../../src/tools/web/capture.ts"],"names":[],"mappings":"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"}

package/dist/tools/web/fetch-core.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `web.fetch` core orchestration.
+ *
+ * This module is the deterministic, dependency-injected pipeline that
+ * `src/tools/web/fetch.ts` (added in task 4.x) wraps in a `ToolResult`
+ * adapter and audit-log emitter. The core itself returns a typed
+ * {@link WebFetchOutcome} and never touches the registry, the safety
+ * classifier, or `auditLog`.
+ *
+ * The pipeline implements the design's "Pipeline steps in detail"
+ * sequence (`.kiro/specs/web-search-and-fetch/design.md`):
+ *
+ *   1. argument validation
+ *   2. URL parse + SSRF pre-check on hostname literal
+ *   3. DNS resolve + IP pin
+ *   4. SSRF check on resolved IP
+ *   5. pinned `https.request` (or `http.request`) with custom `lookup`
+ *   6. TLS handshake capture
+ *   7. response headers + body stream with `maxBytes` cap
+ *   8. redirect handling (≤ {@link MAX_REDIRECT_HOPS}, re-running
+ *      validation + SSRF + DNS at each hop)
+ *   9. body classification (binary / raw / readable)
+ *  10. metadata assembly + 64 KiB budget enforcement
+ *
+ * Every outbound transport call (DNS, HTTP, HTTPS) is injectable via
+ * {@link WebFetchCoreOptions} so tests in epics 3.x, 4.x and 6.x can
+ * stub the network deterministically without spinning up a real server.
+ */
+import { lookup as defaultDnsLookup } from "node:dns/promises";
+import type { ClientRequest, IncomingMessage, RequestOptions } from "node:http";
+import { type WebFetchArgs, type WebFetchErrorKind, type WebFetchOutcome } from "./types.js";
+/** Signature of `node:dns/promises.lookup`. */
+export type DnsLookupFn = typeof defaultDnsLookup;
+/** Signature of `node:http.request` (the overload accepting URL + options). */
+export type HttpRequestFn = (url: string | URL, options: RequestOptions, callback?: (res: IncomingMessage) => void) => ClientRequest;
+/** Signature of `node:https.request` (same shape as {@link HttpRequestFn}). */
+export type HttpsRequestFn = HttpRequestFn;
+/**
+ * Injection points for {@link webFetchCore}. Each defaults to the
+ * corresponding `node:` built-in so production code does not need to
+ * supply anything; tests stub these to drive the pipeline without
+ * touching the network.
+ */
+export interface WebFetchCoreOptions {
+    /** HTTPS transport. Defaults to `https.request`. */
+    httpsRequest?: HttpsRequestFn;
+    /** HTTP transport. Defaults to `http.request`. */
+    httpRequest?: HttpRequestFn;
+    /** DNS resolver. Defaults to `dns/promises.lookup`. */
+    dnsLookup?: DnsLookupFn;
+    /** Wall-clock source for timing fields. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Run the full `web.fetch` pipeline for the given arguments.
+ *
+ * Returns a typed {@link WebFetchOutcome}. The outcome is never thrown
+ * — argument validation failures, SSRF blocks, network errors, HTTP
+ * errors, and timeouts all surface as `ok=false` with a categorical
+ * `error.kind` and a human-readable message. The `metadata` field is
+ * always populated: pipeline stages that completed before the failure
+ * are surfaced (e.g. `resolvedIp` when DNS succeeded but a 4xx came
+ * back), and stages that did not run carry default zero/empty values.
+ */
+export declare function webFetchCore(args: WebFetchArgs, options?: WebFetchCoreOptions): Promise<WebFetchOutcome>;
+export type { WebFetchErrorKind };