@wirebench/engine 2.1.1

package/dist/http/heredoc.js

@@ -0,0 +1,74 @@
+/**
+ * Finds the heredoc or here-string body embedded in a pasted `curl` command.
+ *
+ * Both cURL parsers (`http/curl.ts` for SOAP, `rest/curl.ts` for REST) need this and nothing else
+ * in common, so it lives here rather than in either. It scans instead of matching a regex: the
+ * pattern this replaces, `/<<\\s*'?(\\w+)'?\\r?\\n([\\s\\S]*?)\\r?\\n\\1/`, backtracks its lazy body against a
+ * backreference for every candidate `<<`, which is O(n²) on a command that a user pastes and can
+ * therefore be anything.
+ */
+/** Offset just past a `\n` or `\r\n` at `at`, or -1 when `at` is not a line end. */
+function lineEndAfter(text, at) {
+    if (text.startsWith('\r\n', at)) {
+        return at + 2;
+    }
+    return text[at] === '\n' ? at + 1 : -1;
+}
+/**
+ * Locates a POSIX heredoc: `<<EOF` or `<<'EOF'`, a newline, the body, a newline and `EOF` on a line
+ * of its own. The body is everything between the opening line and the first line that is exactly
+ * the delimiter; an opener with no such closing line is not a heredoc.
+ */
+export function findHeredoc(text) {
+    let from = 0;
+    for (;;) {
+        const open = text.indexOf('<<', from);
+        if (open === -1) {
+            return undefined;
+        }
+        let cursor = open + 2;
+        while (text[cursor] === ' ' || text[cursor] === '\t') {
+            cursor += 1;
+        }
+        const quoted = text[cursor] === "'";
+        if (quoted) {
+            cursor += 1;
+        }
+        const wordStart = cursor;
+        while (cursor < text.length && /\w/.test(text[cursor])) {
+            cursor += 1;
+        }
+        const delimiter = text.slice(wordStart, cursor);
+        if (quoted && text[cursor] === "'") {
+            cursor += 1;
+        }
+        const bodyStart = lineEndAfter(text, cursor);
+        if (delimiter === '' || bodyStart === -1) {
+            from = open + 2;
+            continue;
+        }
+        const closeAt = text.indexOf(`\n${delimiter}`, bodyStart);
+        if (closeAt === -1) {
+            return undefined;
+        }
+        const bodyEnd = text[closeAt - 1] === '\r' ? closeAt - 1 : closeAt;
+        return { body: text.slice(bodyStart, bodyEnd), start: open, end: closeAt + 1 + delimiter.length };
+    }
+}
+/** Locates a PowerShell here-string: `@'`, a newline, the body, a newline and `'@`. */
+export function findHereString(text) {
+    const open = text.indexOf("@'");
+    if (open === -1) {
+        return undefined;
+    }
+    const bodyStart = lineEndAfter(text, open + 2);
+    if (bodyStart === -1) {
+        return undefined;
+    }
+    const closeAt = text.indexOf("\n'@", bodyStart);
+    if (closeAt === -1) {
+        return undefined;
+    }
+    const bodyEnd = text[closeAt - 1] === '\r' ? closeAt - 1 : closeAt;
+    return { body: text.slice(bodyStart, bodyEnd), start: open, end: closeAt + 3 };
+}

package/dist/http/proxy.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Proxy resolution: turns the user's stored {@link ProxyConfig} into the per-request
+ * {@link ProxyOptions} the transport hands to undici's `ProxyAgent`, or `undefined` when the
+ * request must go direct.
+ *
+ * Three things live here and nowhere else: the exclude-list matcher (hostname globs, CIDR
+ * blocks and the `localhost` shorthand), the parser for the PAC-style string Chromium's
+ * `session.resolveProxy` answers with, and the precedence between the two. Everything is pure
+ * — no Electron, no DNS, no sockets — so the whole table is unit-testable, and the desktop's
+ * main process only has to inject `resolveSystem` and the resolved password.
+ */
+import type { ProxyOptions } from './types.js';
+/**
+ * How the user configured the proxy. `passwordRef` is an opaque handle into the OS keychain:
+ * the password itself never appears here, and never crosses IPC — main resolves it and passes
+ * it to {@link resolveProxyFor} separately.
+ */
+export type ProxyConfig = {
+    readonly mode: 'none';
+} | {
+    readonly mode: 'system';
+    /** Hosts that go direct even when the system says to proxy them. */
+    readonly excludes?: readonly string[];
+} | {
+    readonly mode: 'manual';
+    readonly host: string;
+    readonly port: number;
+    readonly username?: string;
+    /** Opaque reference into the OS-keychain-backed secret store. Never a password. */
+    readonly passwordRef?: string;
+    /** Hostname globs (`*.corp.test`), CIDR blocks (`10.0.0.0/8`) or `localhost`. */
+    readonly excludes: readonly string[];
+};
+/** Everything {@link resolveProxyFor} needs that the stored config cannot carry itself. */
+export interface ResolveProxyOptions {
+    /**
+     * Answers Chromium's PAC-style proxy string for a URL (`DIRECT`, `PROXY host:port`, …).
+     * Supplied by the desktop main process as a wrapper around `session.resolveProxy`; without
+     * it, `mode: 'system'` resolves to no proxy rather than guessing.
+     */
+    readonly resolveSystem?: (url: string) => string | undefined;
+    /** The password behind `passwordRef`, already decrypted by main. */
+    readonly password?: string;
+}
+/**
+ * Whether `hostname` is covered by one entry of an exclude list.
+ *
+ * An entry matches when it is the host verbatim, a glob the host matches, a CIDR block the
+ * host's IPv4 literal falls in, or the `localhost` shorthand and the host is any loopback
+ * spelling. A leading `.` (`.corp.test`) is read as "this domain and its subdomains", which
+ * is how `no_proxy` and the usual proxy exclude lists spell it.
+ *
+ * @param hostname the host being connected to, without port or brackets
+ * @param excludes the configured exclude entries
+ */
+export declare function isExcluded(hostname: string, excludes: readonly string[]): boolean;
+/**
+ * What the system (PAC) answer amounts to, once read most-preferred-entry-first.
+ *
+ * `unsupported` exists because undici's `ProxyAgent` cannot speak SOCKS: a SOCKS-only answer is
+ * neither a proxy we can dial nor a licence to connect directly (the direct route is usually
+ * exactly what the firewall drops), so it is reported and the send fails with a message naming
+ * the scheme rather than hanging or timing out for no visible reason.
+ */
+export type SystemProxyResolution = {
+    readonly kind: 'direct';
+} | {
+    readonly kind: 'proxy';
+    readonly url: string;
+} | {
+    readonly kind: 'unsupported';
+    readonly scheme: string;
+};
+/**
+ * Parses the PAC-style string `session.resolveProxy` answers with — a `;`-separated list of
+ * `DIRECT`, `PROXY host:port`, `HTTPS host:port` or `SOCKS…` entries, most-preferred first —
+ * into what the transport should do.
+ *
+ * Only the first usable HTTP(S) entry is taken: the transport has one connection to make and
+ * no way to fail over. A SOCKS entry is skipped in favour of anything usable after it (and of a
+ * `DIRECT` the user's own PAC file offered as a fallback); a SOCKS-only answer yields
+ * `unsupported`, which the caller turns into a `proxy-unsupported` failure.
+ *
+ * @param pacResult the raw string from `session.resolveProxy`
+ * @returns `direct`, the `http(s)://host:port` proxy to dial, or the unsupported scheme
+ */
+export declare function parseSystemProxy(pacResult: string | undefined): SystemProxyResolution;
+/**
+ * The proxy a request to `url` must go through, or `undefined` for a direct connection.
+ *
+ * Excludes are honoured for both `manual` and `system`: a host the user listed goes direct
+ * even when the OS would proxy it, which is the only way to reach a machine on the local
+ * network from behind a corporate PAC file. `system` needs `options.resolveSystem` — without
+ * it there is nothing to ask, and guessing from environment variables would silently disagree
+ * with what the rest of the app (and Electron's own network stack) does.
+ *
+ * @param url the absolute request URL
+ * @param config the user's stored proxy configuration
+ * @param options the system resolver and the password behind `passwordRef`
+ * @returns the proxy to dial, or `undefined` to connect directly
+ * @throws WirebenchError `proxy-unsupported` when the system answers with a SOCKS-only proxy
+ */
+export declare function resolveProxyFor(url: string, config: ProxyConfig, options?: ResolveProxyOptions): ProxyOptions | undefined;

package/dist/http/proxy.js

@@ -0,0 +1,168 @@
+/**
+ * Proxy resolution: turns the user's stored {@link ProxyConfig} into the per-request
+ * {@link ProxyOptions} the transport hands to undici's `ProxyAgent`, or `undefined` when the
+ * request must go direct.
+ *
+ * Three things live here and nowhere else: the exclude-list matcher (hostname globs, CIDR
+ * blocks and the `localhost` shorthand), the parser for the PAC-style string Chromium's
+ * `session.resolveProxy` answers with, and the precedence between the two. Everything is pure
+ * — no Electron, no DNS, no sockets — so the whole table is unit-testable, and the desktop's
+ * main process only has to inject `resolveSystem` and the resolved password.
+ */
+import { WirebenchError } from '../errors.js';
+/** True when `text` is an IPv4 dotted quad. */
+function isIpv4(text) {
+    const parts = text.split('.');
+    return (parts.length === 4 && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) >= 0 && Number(part) <= 255));
+}
+/** An IPv4 dotted quad as a 32-bit unsigned integer. */
+function ipv4ToInt(text) {
+    return text.split('.').reduce((accumulated, part) => accumulated * 256 + Number(part), 0);
+}
+/** Whether `host` (an IPv4 literal) falls inside the `a.b.c.d/bits` block `cidr`. */
+function matchesCidr(host, cidr) {
+    const slash = cidr.indexOf('/');
+    if (slash === -1)
+        return false;
+    const network = cidr.slice(0, slash);
+    const bits = Number(cidr.slice(slash + 1));
+    if (!isIpv4(network) || !isIpv4(host) || !Number.isInteger(bits) || bits < 0 || bits > 32) {
+        return false;
+    }
+    if (bits === 0)
+        return true;
+    // `>>> 0` keeps the shift unsigned; JS bitwise operators work on signed 32-bit ints.
+    const mask = (0xffffffff << (32 - bits)) >>> 0;
+    return (ipv4ToInt(host) & mask) >>> 0 === (ipv4ToInt(network) & mask) >>> 0;
+}
+/** The loopback spellings the `localhost` shorthand stands for in a proxy exclude list. */
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+/** Turns a hostname glob (`*.corp.test`) into an anchored, case-insensitive regular expression. */
+function globToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`, 'i');
+}
+/**
+ * Whether `hostname` is covered by one entry of an exclude list.
+ *
+ * An entry matches when it is the host verbatim, a glob the host matches, a CIDR block the
+ * host's IPv4 literal falls in, or the `localhost` shorthand and the host is any loopback
+ * spelling. A leading `.` (`.corp.test`) is read as "this domain and its subdomains", which
+ * is how `no_proxy` and the usual proxy exclude lists spell it.
+ *
+ * @param hostname the host being connected to, without port or brackets
+ * @param excludes the configured exclude entries
+ */
+export function isExcluded(hostname, excludes) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    for (const raw of excludes) {
+        const entry = raw.trim().toLowerCase();
+        if (entry.length === 0)
+            continue;
+        if (entry === '*')
+            return true;
+        if (entry === 'localhost' && LOOPBACK.has(host))
+            return true;
+        if (entry === host)
+            return true;
+        if (entry.startsWith('.') && (host === entry.slice(1) || host.endsWith(entry)))
+            return true;
+        if (entry.includes('/') && matchesCidr(host, entry))
+            return true;
+        if (entry.includes('*') && globToRegExp(entry).test(host))
+            return true;
+    }
+    return false;
+}
+/** The PAC keywords that name a SOCKS proxy, lower-cased as {@link SystemProxyResolution.scheme}. */
+const SOCKS_KEYWORDS = new Set(['socks', 'socks4', 'socks5']);
+/**
+ * Parses the PAC-style string `session.resolveProxy` answers with — a `;`-separated list of
+ * `DIRECT`, `PROXY host:port`, `HTTPS host:port` or `SOCKS…` entries, most-preferred first —
+ * into what the transport should do.
+ *
+ * Only the first usable HTTP(S) entry is taken: the transport has one connection to make and
+ * no way to fail over. A SOCKS entry is skipped in favour of anything usable after it (and of a
+ * `DIRECT` the user's own PAC file offered as a fallback); a SOCKS-only answer yields
+ * `unsupported`, which the caller turns into a `proxy-unsupported` failure.
+ *
+ * @param pacResult the raw string from `session.resolveProxy`
+ * @returns `direct`, the `http(s)://host:port` proxy to dial, or the unsupported scheme
+ */
+export function parseSystemProxy(pacResult) {
+    if (pacResult === undefined)
+        return { kind: 'direct' };
+    let socksScheme;
+    for (const raw of pacResult.split(';')) {
+        const entry = raw.trim();
+        if (entry.length === 0)
+            continue;
+        const match = /^([A-Za-z][A-Za-z0-9]*)(?:\s+(\S+))?$/.exec(entry);
+        if (match === null)
+            continue;
+        const keyword = (match[1] ?? '').toUpperCase();
+        const authority = match[2];
+        if (keyword === 'DIRECT')
+            return { kind: 'direct' };
+        if (SOCKS_KEYWORDS.has(keyword.toLowerCase())) {
+            socksScheme ??= keyword.toLowerCase();
+            continue;
+        }
+        if (keyword !== 'PROXY' && keyword !== 'HTTP' && keyword !== 'HTTPS')
+            continue;
+        if (authority === undefined || authority.length === 0)
+            continue;
+        return { kind: 'proxy', url: `${keyword === 'HTTPS' ? 'https' : 'http'}://${authority}` };
+    }
+    return socksScheme === undefined ? { kind: 'direct' } : { kind: 'unsupported', scheme: socksScheme };
+}
+/** The `ProxyOptions` for a proxy URL plus optional credentials, dropping an empty username. */
+function withAuth(url, username, password) {
+    if (username === undefined || username.length === 0) {
+        return { url };
+    }
+    return { url, auth: { username, password: password ?? '' } };
+}
+/**
+ * The proxy a request to `url` must go through, or `undefined` for a direct connection.
+ *
+ * Excludes are honoured for both `manual` and `system`: a host the user listed goes direct
+ * even when the OS would proxy it, which is the only way to reach a machine on the local
+ * network from behind a corporate PAC file. `system` needs `options.resolveSystem` — without
+ * it there is nothing to ask, and guessing from environment variables would silently disagree
+ * with what the rest of the app (and Electron's own network stack) does.
+ *
+ * @param url the absolute request URL
+ * @param config the user's stored proxy configuration
+ * @param options the system resolver and the password behind `passwordRef`
+ * @returns the proxy to dial, or `undefined` to connect directly
+ * @throws WirebenchError `proxy-unsupported` when the system answers with a SOCKS-only proxy
+ */
+export function resolveProxyFor(url, config, options) {
+    if (config.mode === 'none')
+        return undefined;
+    let hostname;
+    try {
+        hostname = new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+    const excludes = config.excludes ?? [];
+    if (isExcluded(hostname, excludes))
+        return undefined;
+    if (config.mode === 'system') {
+        const resolved = parseSystemProxy(options?.resolveSystem?.(url));
+        if (resolved.kind === 'unsupported') {
+            throw new WirebenchError('proxy-unsupported', `Your system proxy is ${resolved.scheme.toUpperCase()}, which Wirebench cannot use`, { details: { scheme: resolved.scheme } });
+        }
+        return resolved.kind === 'direct' ? undefined : { url: resolved.url };
+    }
+    if (config.host.trim().length === 0 || !Number.isInteger(config.port) || config.port <= 0) {
+        return undefined;
+    }
+    const host = config.host.trim();
+    const authority = host.includes('://') ? host : `http://${host}`;
+    const base = `${authority.replace(/\/+$/, '')}:${config.port}`;
+    return withAuth(base, config.username, options?.password);
+}

package/dist/http/raw-capture.d.ts

@@ -0,0 +1,23 @@
+import type { HttpRequest } from './types.js';
+/**
+ * Reconstructs the request as bytes approximating what was put on the wire:
+ * `METHOD path HTTP/1.1\r\nHeader: value\r\n...\r\n\r\n<body>`.
+ *
+ * This is a reconstruction, not a wire capture: undici does not expose the
+ * literal bytes it sends. The reconstruction mirrors exactly the headers
+ * undici sends and nothing else — `host` (from the URL) and `content-length`
+ * (when there's a body), plus whatever headers the caller set — so it
+ * intentionally omits headers undici doesn't add by default (e.g.
+ * `Connection`, which undici's `request()` does not send).
+ * `finalHeaders` should include any headers undici adds itself (e.g.
+ * `content-length`, `host`) so the reconstruction is as faithful as practical.
+ */
+export declare function buildRawRequest(req: HttpRequest, finalHeaders: Readonly<Record<string, string>>, body?: Uint8Array): Uint8Array;
+/**
+ * Reconstructs the response as bytes approximating what was received on the
+ * wire: `HTTP/1.1 <status> <text>\r\nHeader: value\r\n...\r\n\r\n<body>`.
+ *
+ * This is a reconstruction, not a wire capture: undici does not expose the
+ * literal bytes it received.
+ */
+export declare function buildRawResponse(status: number, statusText: string, rawHeaders: readonly (readonly [string, string])[], rawBody: Uint8Array, httpVersion?: '1.1' | '2'): Uint8Array;

package/dist/http/raw-capture.js

@@ -0,0 +1,57 @@
+const CRLF = '\r\n';
+/**
+ * Reconstructs the request as bytes approximating what was put on the wire:
+ * `METHOD path HTTP/1.1\r\nHeader: value\r\n...\r\n\r\n<body>`.
+ *
+ * This is a reconstruction, not a wire capture: undici does not expose the
+ * literal bytes it sends. The reconstruction mirrors exactly the headers
+ * undici sends and nothing else — `host` (from the URL) and `content-length`
+ * (when there's a body), plus whatever headers the caller set — so it
+ * intentionally omits headers undici doesn't add by default (e.g.
+ * `Connection`, which undici's `request()` does not send).
+ * `finalHeaders` should include any headers undici adds itself (e.g.
+ * `content-length`, `host`) so the reconstruction is as faithful as practical.
+ */
+export function buildRawRequest(req, finalHeaders, body) {
+    let path;
+    try {
+        const parsed = new URL(req.url);
+        path = `${parsed.pathname}${parsed.search}` || '/';
+    }
+    catch {
+        path = req.url;
+    }
+    const lines = [`${req.method} ${path} HTTP/1.1`];
+    for (const [name, value] of Object.entries(finalHeaders)) {
+        lines.push(`${name}: ${value}`);
+    }
+    const head = `${lines.join(CRLF)}${CRLF}${CRLF}`;
+    const headBytes = new TextEncoder().encode(head);
+    if (body === undefined || body.length === 0)
+        return headBytes;
+    const out = new Uint8Array(headBytes.length + body.length);
+    out.set(headBytes, 0);
+    out.set(body, headBytes.length);
+    return out;
+}
+/**
+ * Reconstructs the response as bytes approximating what was received on the
+ * wire: `HTTP/1.1 <status> <text>\r\nHeader: value\r\n...\r\n\r\n<body>`.
+ *
+ * This is a reconstruction, not a wire capture: undici does not expose the
+ * literal bytes it received.
+ */
+export function buildRawResponse(status, statusText, rawHeaders, rawBody, httpVersion = '1.1') {
+    const lines = [`HTTP/${httpVersion} ${status} ${statusText}`];
+    for (const [name, value] of rawHeaders) {
+        lines.push(`${name}: ${value}`);
+    }
+    const head = `${lines.join(CRLF)}${CRLF}${CRLF}`;
+    const headBytes = new TextEncoder().encode(head);
+    if (rawBody.length === 0)
+        return headBytes;
+    const out = new Uint8Array(headBytes.length + rawBody.length);
+    out.set(headBytes, 0);
+    out.set(rawBody, headBytes.length);
+    return out;
+}

package/dist/http/timings.d.ts

@@ -0,0 +1,79 @@
+import { type SslInfo } from './tls.js';
+import type { Timings } from './types.js';
+/**
+ * Tracks timings for one physical HTTP exchange. `connectMs`/`tlsMs` still rely on
+ * this module never issuing concurrent requests through the same dispatcher call (so
+ * "the next connect event" can only be this exchange's) — but `tls`, the peer/protocol
+ * snapshot, does not get that luxury: two exchanges can easily be concurrently in
+ * flight to the *same* origin on *different* sockets, and `undici:client:sendHeaders`
+ * carries no correlation id of its own beyond the undici `Request` object reference.
+ * `captureRequestFor` threads that reference through explicitly, so `onSendHeaders`
+ * can match on it exactly instead of guessing from origin.
+ *
+ * Sources:
+ * - `connectMs`/`tlsMs`: `undici:client:beforeConnect` / `undici:client:connected`.
+ *   Only observed when a *new* socket is opened for this exchange; a reused
+ *   keep-alive connection leaves both undefined.
+ * - `tls` (the {@link SslInfo} snapshot): `undici:client:sendHeaders`, which carries
+ *   the request, and the socket its bytes were written to — so a request that reuses a
+ *   warm keep-alive connection still gets the peer chain, which `undici:client:connected`
+ *   alone (fresh connections only) cannot give. Correlated by request identity (see
+ *   {@link captureRequestFor}); origin matching is a fallback for the case where no
+ *   identity was captured, not the primary mechanism.
+ * - `ttfbMs`: `undici:request:headers` (response headers received).
+ * - `downloadMs`: measured after headers, ended by our own body-read loop
+ *   (not a diagnostics channel — undici doesn't expose a clean "body fully
+ *   read" timestamp before trailers, and we already know when we finish reading).
+ * - `dnsMs`: left undefined. Wiring a custom `connect.lookup` timer for this
+ *   would require plumbing through every dispatcher construction path
+ *   (including caller-supplied dispatchers for Task 35's NTLM `Client`), which
+ *   is more invasive than this task's payoff justifies. Documented, not silently dropped.
+ */
+export declare class TimingTracker {
+    private readonly now;
+    private readonly startedAtMs;
+    private readonly startedAtIso;
+    private connectStart;
+    private connectEnd;
+    private tlsEnd;
+    private headersAt;
+    private ssl;
+    /** The origin this exchange is currently talking to; a redirect moves it. */
+    private origin;
+    /**
+     * The exact undici `Request` object this physical attempt is using, captured via
+     * {@link captureRequestFor}. Compared by identity (`===`) in `onSendHeaders` — see
+     * that handler for why this, rather than origin, is the correlation key.
+     */
+    private request;
+    private readonly onBeforeConnect;
+    private readonly onConnected;
+    private readonly onSendHeaders;
+    private disposed;
+    constructor(now?: () => number);
+    /** Records which origin the next physical request goes to, so TLS events can be attributed to it. */
+    setOrigin(origin: string): void;
+    /**
+     * Runs `fn` — a call that synchronously triggers undici's `undici:request:create`
+     * diagnostics event, as every plain `undiciRequest()` call does — while listening for
+     * that event, so `this.request` becomes the exact undici `Request` object this
+     * physical attempt is using. Call this wrapping the `undiciRequest()` call itself
+     * (not a `.then()`/`await` of it): the create event fires inside the synchronous
+     * portion of that call, before it returns a pending promise, which is what makes the
+     * capture race-free even when another exchange's own send is interleaved via
+     * `Promise.all` — no other code runs between this subscribe and unsubscribe.
+     */
+    captureRequestFor<T>(fn: () => T): T;
+    /** Call when the response headers arrive (time-to-first-byte). */
+    markHeaders(): void;
+    /**
+     * Stops listening to diagnostics channels and decrements the in-flight
+     * counter. Always call this, even on error paths — idempotent, so it is
+     * safe to call more than once (e.g. from a `finally` after an early throw).
+     */
+    dispose(): void;
+    /** Finalizes the timing record. Call once the response body is fully read (or the exchange failed). */
+    finish(): Timings;
+    /** The TLS peer/protocol snapshot for the connection this exchange used, if it was a TLS one. */
+    tlsInfo(): SslInfo | undefined;
+}