@wirebench/engine 2.1.1

package/dist/http/timings.js

@@ -0,0 +1,212 @@
+import diagnosticsChannel from 'node:diagnostics_channel';
+import { sslInfoForSocket } from './tls.js';
+/** Default timer, injectable for deterministic tests. */
+const defaultNow = () => performance.now();
+/**
+ * Number of `sendHttp` calls currently in flight, process-wide. `undici:client:*`
+ * connect-level diagnostics_channel events carry no per-exchange correlation id,
+ * so when more than one exchange is in flight we cannot tell which exchange a
+ * given connect event belongs to. Rather than risk mis-attributing connect/TLS
+ * timings to the wrong exchange, we only record them when exactly one exchange
+ * is in flight; concurrent exchanges leave `connectMs`/`tlsMs` undefined
+ * (a documented imprecision, not a bug).
+ *
+ * `tls` (the peer/protocol snapshot) is not subject to that restriction: it is
+ * correlated by origin instead — see `onSendHeaders`.
+ */
+let inFlightCount = 0;
+/** Narrows a diagnostics-channel payload to the TLS socket it carries, if it carries one. */
+function encryptedSocketOf(message) {
+    const socket = message?.socket;
+    return socket?.encrypted === true ? socket : undefined;
+}
+/** The `request` object a diagnostics-channel payload carries, when it carries one. */
+function requestOf(message) {
+    return message?.request;
+}
+/** The `origin` string undici stamps on the request the event belongs to, when it has one. */
+function requestOriginOf(message) {
+    const origin = message?.request?.origin;
+    if (typeof origin === 'string')
+        return origin;
+    // undici accepts a URL for `origin` too; both shapes normalise to the same string.
+    return origin instanceof URL ? origin.origin : undefined;
+}
+/**
+ * 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 class TimingTracker {
+    now;
+    startedAtMs;
+    startedAtIso;
+    connectStart;
+    connectEnd;
+    tlsEnd;
+    headersAt;
+    ssl;
+    /** The origin this exchange is currently talking to; a redirect moves it. */
+    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.
+     */
+    request;
+    onBeforeConnect;
+    onConnected;
+    onSendHeaders;
+    disposed = false;
+    constructor(now = defaultNow) {
+        this.now = now;
+        this.startedAtMs = now();
+        this.startedAtIso = new Date().toISOString();
+        inFlightCount += 1;
+        this.onBeforeConnect = () => {
+            if (inFlightCount !== 1)
+                return; // another exchange is concurrently in flight; can't attribute safely
+            if (this.connectStart === undefined)
+                this.connectStart = this.now();
+        };
+        this.onConnected = (message) => {
+            const socket = encryptedSocketOf(message);
+            // Warm the per-socket cache while the handshake is fresh, whatever else we
+            // can or cannot attribute: a *later* exchange reusing this very socket
+            // reads it back through `sendHeaders`.
+            if (socket !== undefined)
+                sslInfoForSocket(socket);
+            if (inFlightCount !== 1)
+                return; // another exchange is concurrently in flight; can't attribute safely
+            if (this.connectStart === undefined)
+                return; // beforeConnect for this exchange was never observed
+            this.connectEnd = this.now();
+            if (socket !== undefined) {
+                this.tlsEnd = this.connectEnd;
+                this.ssl = sslInfoForSocket(socket);
+            }
+        };
+        this.onSendHeaders = (message) => {
+            const socket = encryptedSocketOf(message);
+            if (socket === undefined)
+                return;
+            if (this.request !== undefined) {
+                // Correlate by the exact undici `Request` object identity: `captureRequestFor`
+                // records it synchronously from `undici:request:create`, which undici fires
+                // inside the very call that starts this attempt, before any other exchange's
+                // code can run (Node is single-threaded and nothing awaits in between). That
+                // makes this exact — unlike origin matching, which conflates two concurrent
+                // exchanges to the *same* origin on *different* sockets (they usually share a
+                // certificate, but not always: see the concurrent-same-origin integration test).
+                if (requestOf(message) !== this.request)
+                    return;
+                this.ssl = sslInfoForSocket(socket);
+                return;
+            }
+            // Fall back to origin matching only when no request identity was ever captured
+            // for this exchange (defensive: `client.ts` always wraps its `undiciRequest()`
+            // call in `captureRequestFor`, so in practice this branch is not expected to run).
+            const origin = requestOriginOf(message);
+            const matches = this.origin !== undefined && origin !== undefined ? origin === this.origin : inFlightCount === 1;
+            if (!matches)
+                return;
+            this.ssl = sslInfoForSocket(socket);
+        };
+        diagnosticsChannel.channel('undici:client:beforeConnect').subscribe(this.onBeforeConnect);
+        diagnosticsChannel.channel('undici:client:connected').subscribe(this.onConnected);
+        diagnosticsChannel.channel('undici:client:sendHeaders').subscribe(this.onSendHeaders);
+    }
+    /** Records which origin the next physical request goes to, so TLS events can be attributed to it. */
+    setOrigin(origin) {
+        this.origin = origin;
+    }
+    /**
+     * 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(fn) {
+        const channel = diagnosticsChannel.channel('undici:request:create');
+        const onCreate = (message) => {
+            const request = requestOf(message);
+            if (request !== undefined)
+                this.request = request;
+        };
+        channel.subscribe(onCreate);
+        try {
+            return fn();
+        }
+        finally {
+            channel.unsubscribe(onCreate);
+        }
+    }
+    /** Call when the response headers arrive (time-to-first-byte). */
+    markHeaders() {
+        this.headersAt = this.now();
+    }
+    /**
+     * 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() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        diagnosticsChannel.channel('undici:client:beforeConnect').unsubscribe(this.onBeforeConnect);
+        diagnosticsChannel.channel('undici:client:connected').unsubscribe(this.onConnected);
+        diagnosticsChannel.channel('undici:client:sendHeaders').unsubscribe(this.onSendHeaders);
+        inFlightCount -= 1;
+    }
+    /** Finalizes the timing record. Call once the response body is fully read (or the exchange failed). */
+    finish() {
+        const end = this.now();
+        const connectMs = this.connectStart !== undefined && this.connectEnd !== undefined
+            ? this.connectEnd - this.connectStart
+            : undefined;
+        const tlsMs = this.connectStart !== undefined && this.tlsEnd !== undefined ? this.tlsEnd - this.connectStart : undefined;
+        const ttfbMs = this.headersAt !== undefined ? this.headersAt - this.startedAtMs : undefined;
+        const downloadMs = this.headersAt !== undefined ? end - this.headersAt : undefined;
+        return {
+            startedAt: this.startedAtIso,
+            totalMs: end - this.startedAtMs,
+            ...(connectMs !== undefined ? { connectMs } : {}),
+            ...(tlsMs !== undefined ? { tlsMs } : {}),
+            ...(ttfbMs !== undefined ? { ttfbMs } : {}),
+            ...(downloadMs !== undefined ? { downloadMs } : {}),
+        };
+    }
+    /** The TLS peer/protocol snapshot for the connection this exchange used, if it was a TLS one. */
+    tlsInfo() {
+        return this.ssl;
+    }
+}

package/dist/http/tls.d.ts

@@ -0,0 +1,111 @@
+/**
+ * TLS peer inspection: turns a live `tls.TLSSocket` into the serialisable
+ * {@link SslInfo} the SSL Info inspector renders. Kept apart from `timings.ts`
+ * so the certificate walk can be unit-tested against a plain object, with no
+ * sockets and no network.
+ */
+/**
+ * Splits a PEM bundle into its individual certificates.
+ *
+ * Node's `ca` option accepts an array of PEM strings; handing it one blob that happens to hold
+ * several certificates works by accident of OpenSSL's parser rather than by contract, and
+ * silently ignores everything after the first block on some builds. Splitting here makes a
+ * multi-root corporate bundle behave the way the user expects, and makes "how many anchors did
+ * we actually load?" answerable.
+ *
+ * Anything outside a `BEGIN/END CERTIFICATE` block (comments, `Bag Attributes` preambles,
+ * stray whitespace) is dropped.
+ *
+ * @param bundle the file's text
+ * @returns one PEM string per certificate, in file order; empty when the text holds none
+ */
+export declare function splitPemBundle(bundle: string): string[];
+/**
+ * The subset of Node's `tls.PeerCertificate` this module reads. Declared
+ * structurally (rather than importing `node:tls`) so tests can hand in a plain
+ * object and so a Node version that drops an optional field still type-checks.
+ */
+export interface PeerCertificateLike {
+    readonly subject?: Readonly<Record<string, string | readonly string[]>> | undefined;
+    readonly issuer?: Readonly<Record<string, string | readonly string[]>> | undefined;
+    /** OpenSSL's `DNS:a, IP Address:1.2.3.4` rendering of the subjectAltName extension. */
+    readonly subjectaltname?: string | undefined;
+    readonly valid_from?: string | undefined;
+    readonly valid_to?: string | undefined;
+    readonly serialNumber?: string | undefined;
+    readonly fingerprint256?: string | undefined;
+    readonly ca?: boolean | undefined;
+    readonly issuerCertificate?: PeerCertificateLike | undefined;
+}
+/** The subset of `tls.TLSSocket` this module reads; every accessor is optional but `getPeerCertificate`. */
+export interface TlsSocketLike {
+    getPeerCertificate(detailed?: boolean): PeerCertificateLike | undefined | null;
+    /** The *local* certificate, i.e. the client identity this side presented (Node >= 11.4). */
+    getCertificate?: () => PeerCertificateLike | undefined | null;
+    getProtocol?: () => string | null | undefined;
+    getCipher?: () => {
+        readonly name?: string | undefined;
+    } | undefined;
+    readonly authorized?: boolean | undefined;
+    readonly authorizationError?: Error | string | null | undefined;
+    /** `false` when the client sent no SNI. */
+    readonly servername?: string | false | null | undefined;
+    /** `false` when no protocol was negotiated. */
+    readonly alpnProtocol?: string | false | null | undefined;
+}
+/** One certificate of the peer's chain, flattened to strings so it can cross IPC unchanged. */
+export interface PeerCert {
+    /** Distinguished name, rendered `CN=…, O=…` in the certificate's own attribute order. */
+    readonly subject: string;
+    readonly issuer: string;
+    /** ISO 8601, or the certificate's own `valid_from` text when it cannot be parsed. */
+    readonly validFrom: string;
+    readonly validTo: string;
+    readonly serialNumber?: string;
+    /** SAN entries with OpenSSL's `DNS:` / `IP Address:` type prefix stripped. */
+    readonly sans: readonly string[];
+    /** SHA-256 fingerprint as 64 lower-case hex characters (OpenSSL's colons removed). */
+    readonly fingerprint256: string;
+    readonly isCA?: boolean;
+}
+/** Everything known about the TLS connection one exchange travelled over. */
+export interface SslInfo {
+    /** e.g. `TLSv1.3`. */
+    readonly protocol?: string;
+    /** Cipher suite name, e.g. `TLS_AES_256_GCM_SHA384`. */
+    readonly cipher?: string;
+    /** Whether the peer chain verified against the trust store in use. */
+    readonly authorized?: boolean;
+    /** OpenSSL's reason the chain did not verify, e.g. `SELF_SIGNED_CERT_IN_CHAIN`. */
+    readonly authorizationError?: string;
+    /** The SNI name sent on the handshake. */
+    readonly servername?: string;
+    /** Leaf first, then each issuer up to (and including) the root the peer presented. */
+    readonly peerChain: readonly PeerCert[];
+    /** Negotiated ALPN protocol, e.g. `http/1.1`. */
+    readonly alpn?: string;
+    /** The client identity this side presented, when a keystore supplied one. */
+    readonly clientCertificate?: {
+        readonly subject: string;
+        readonly issuer: string;
+    };
+}
+/**
+ * Snapshots everything the SSL Info inspector shows about one TLS connection:
+ * negotiated protocol/cipher/ALPN, whether the peer chain verified, and the
+ * chain itself walked from the leaf to the root the peer presented.
+ *
+ * Pure and synchronous — safe to call from a diagnostics-channel subscriber.
+ *
+ * @param socket a connected `tls.TLSSocket` (only the accessors in {@link TlsSocketLike} are used)
+ * @returns the serialisable snapshot; `peerChain` is empty when the socket has no peer certificate
+ */
+export declare function captureSslInfo(socket: TlsSocketLike): SslInfo;
+/**
+ * {@link captureSslInfo}, memoised per socket. Use this on the hot path
+ * (every request that goes out on a connection), not just on a fresh connect.
+ *
+ * @param socket the socket the request was written to
+ * @returns the cached or freshly captured snapshot
+ */
+export declare function sslInfoForSocket(socket: TlsSocketLike): SslInfo;

package/dist/http/tls.js

@@ -0,0 +1,167 @@
+/**
+ * TLS peer inspection: turns a live `tls.TLSSocket` into the serialisable
+ * {@link SslInfo} the SSL Info inspector renders. Kept apart from `timings.ts`
+ * so the certificate walk can be unit-tested against a plain object, with no
+ * sockets and no network.
+ */
+/** Matches each `-----BEGIN CERTIFICATE-----`…`-----END CERTIFICATE-----` block of a PEM bundle. */
+const PEM_BLOCK = /-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g;
+/**
+ * Splits a PEM bundle into its individual certificates.
+ *
+ * Node's `ca` option accepts an array of PEM strings; handing it one blob that happens to hold
+ * several certificates works by accident of OpenSSL's parser rather than by contract, and
+ * silently ignores everything after the first block on some builds. Splitting here makes a
+ * multi-root corporate bundle behave the way the user expects, and makes "how many anchors did
+ * we actually load?" answerable.
+ *
+ * Anything outside a `BEGIN/END CERTIFICATE` block (comments, `Bag Attributes` preambles,
+ * stray whitespace) is dropped.
+ *
+ * @param bundle the file's text
+ * @returns one PEM string per certificate, in file order; empty when the text holds none
+ */
+export function splitPemBundle(bundle) {
+    return bundle.match(PEM_BLOCK) ?? [];
+}
+/** How far up the issuer chain we walk before giving up, as a defence against pathological chains. */
+const MAX_CHAIN_DEPTH = 16;
+/** Renders a Node DN object (`{ CN: 'x', OU: ['a','b'] }`) as `CN=x, OU=a, OU=b`. */
+function renderDn(dn) {
+    if (dn === undefined)
+        return '';
+    const parts = [];
+    for (const [key, value] of Object.entries(dn)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                parts.push(`${key}=${item}`);
+        }
+        else {
+            parts.push(`${key}=${String(value)}`);
+        }
+    }
+    return parts.join(', ');
+}
+/** `DNS:localhost, IP Address:127.0.0.1` → `['localhost', '127.0.0.1']`. */
+function parseSans(subjectAltName) {
+    if (subjectAltName === undefined || subjectAltName.length === 0)
+        return [];
+    return subjectAltName
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0)
+        .map((entry) => {
+        const colon = entry.indexOf(':');
+        return colon === -1 ? entry : entry.slice(colon + 1).trim();
+    });
+}
+/** ISO 8601 when the certificate's date text parses, the original text when it does not. */
+function toIsoDate(text) {
+    if (text === undefined || text.length === 0)
+        return '';
+    const parsed = new Date(text);
+    return Number.isNaN(parsed.getTime()) ? text : parsed.toISOString();
+}
+/** OpenSSL prints `AB:CD:…`; the UI wants a copyable 64-character hex string. */
+function normalizeFingerprint(fingerprint) {
+    return (fingerprint ?? '').replace(/:/g, '').toLowerCase();
+}
+/** True when Node returned the empty object it uses for "this socket has no peer certificate". */
+function isEmptyCertificate(cert) {
+    return cert === undefined || cert === null || Object.keys(cert).length === 0;
+}
+function toPeerCert(cert) {
+    return {
+        subject: renderDn(cert.subject),
+        issuer: renderDn(cert.issuer),
+        validFrom: toIsoDate(cert.valid_from),
+        validTo: toIsoDate(cert.valid_to),
+        ...(cert.serialNumber !== undefined ? { serialNumber: cert.serialNumber } : {}),
+        sans: parseSans(cert.subjectaltname),
+        fingerprint256: normalizeFingerprint(cert.fingerprint256),
+        ...(cert.ca !== undefined ? { isCA: cert.ca } : {}),
+    };
+}
+/**
+ * Walks `issuerCertificate` from the leaf upwards. Node makes a self-signed
+ * root point at itself, so identity is the natural stop; a `Set` guards against
+ * a cross-signed pair that would otherwise loop forever, and `MAX_CHAIN_DEPTH`
+ * against anything stranger than that.
+ */
+function walkChain(leaf) {
+    const chain = [];
+    const seen = new Set();
+    let current = leaf;
+    while (current !== undefined && !seen.has(current) && chain.length < MAX_CHAIN_DEPTH) {
+        seen.add(current);
+        chain.push(toPeerCert(current));
+        const issuer = current.issuerCertificate;
+        current = issuer === null ? undefined : issuer;
+    }
+    return chain;
+}
+/** The authorization failure as a plain string; Node hands back an `Error` on modern versions. */
+function toAuthorizationError(error) {
+    if (error === null || error === undefined)
+        return undefined;
+    const message = typeof error === 'string' ? error : error.message;
+    return message.length > 0 ? message : undefined;
+}
+/**
+ * Snapshots everything the SSL Info inspector shows about one TLS connection:
+ * negotiated protocol/cipher/ALPN, whether the peer chain verified, and the
+ * chain itself walked from the leaf to the root the peer presented.
+ *
+ * Pure and synchronous — safe to call from a diagnostics-channel subscriber.
+ *
+ * @param socket a connected `tls.TLSSocket` (only the accessors in {@link TlsSocketLike} are used)
+ * @returns the serialisable snapshot; `peerChain` is empty when the socket has no peer certificate
+ */
+export function captureSslInfo(socket) {
+    const leaf = socket.getPeerCertificate(true);
+    const protocol = socket.getProtocol?.() ?? undefined;
+    const cipher = socket.getCipher?.()?.name;
+    const servername = typeof socket.servername === 'string' ? socket.servername : undefined;
+    const alpn = typeof socket.alpnProtocol === 'string' ? socket.alpnProtocol : undefined;
+    const authorizationError = toAuthorizationError(socket.authorizationError);
+    const local = socket.getCertificate?.();
+    // The SSL inspector shows this so "did my keystore actually get used?" is answerable without
+    // reading the server's logs; only the DNs are kept, never any key material.
+    const clientCertificate = isEmptyCertificate(local)
+        ? undefined
+        : {
+            subject: renderDn(local.subject),
+            issuer: renderDn(local.issuer),
+        };
+    return {
+        ...(protocol !== null && protocol !== undefined ? { protocol } : {}),
+        ...(cipher !== undefined ? { cipher } : {}),
+        ...(socket.authorized !== undefined ? { authorized: socket.authorized } : {}),
+        ...(authorizationError !== undefined ? { authorizationError } : {}),
+        ...(servername !== undefined ? { servername } : {}),
+        peerChain: isEmptyCertificate(leaf) ? [] : walkChain(leaf),
+        ...(alpn !== undefined ? { alpn } : {}),
+        ...(clientCertificate !== undefined ? { clientCertificate } : {}),
+    };
+}
+/**
+ * Per-socket cache of {@link captureSslInfo}. A keep-alive connection carries
+ * many exchanges but only ever one handshake, so the chain walk runs once per
+ * socket; the `WeakMap` keeps nothing alive after the socket is collected.
+ */
+const bySocket = new WeakMap();
+/**
+ * {@link captureSslInfo}, memoised per socket. Use this on the hot path
+ * (every request that goes out on a connection), not just on a fresh connect.
+ *
+ * @param socket the socket the request was written to
+ * @returns the cached or freshly captured snapshot
+ */
+export function sslInfoForSocket(socket) {
+    const cached = bySocket.get(socket);
+    if (cached !== undefined)
+        return cached;
+    const info = captureSslInfo(socket);
+    bySocket.set(socket, info);
+    return info;
+}

package/dist/http/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Wire-level types for the HTTP transport (Task 10). These are transport
+ * concerns only: no auth, no MIME/SOAP semantics. Auth (Task 49) and WS-Security
+ * layer on top by producing headers/body before `sendHttp` is called.
+ */
+import type { SslInfo } from './tls.js';
+/** An HTTP request as fully resolved bytes/headers, ready to send. */
+export interface HttpRequest {
+    readonly url: string;
+    readonly method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'PATCH';
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: Uint8Array;
+    readonly timeoutMs: number;
+    readonly followRedirects: boolean;
+    /** Maximum number of redirects to follow. Default 5. */
+    readonly maxRedirects?: number;
+    /**
+     * Keep the method and body across a 301 or 302 that would otherwise become a bodyless `GET`.
+     *
+     * Browsers downgrade those two, which is why the default does too (RFC 9110 §15.4.3 notes the
+     * practice), but a REST client talking to an API that answers a `POST` with a 302 to the created
+     * resource needs the choice. 303 always becomes a `GET`: that is what the status means.
+     */
+    readonly preserveMethodOnRedirect?: boolean;
+    /** Maximum response body size to buffer, in bytes. Undefined = unlimited. */
+    readonly maxSizeBytes?: number;
+    readonly signal?: AbortSignal;
+    /**
+     * Local interface address to bind the outgoing socket to. Passed straight to the connector;
+     * an address the host does not own makes the connection fail, which is the intended feedback.
+     */
+    readonly localAddress?: string;
+    readonly tls?: TlsOptions;
+    readonly proxy?: ProxyOptions;
+    /** Whether to transparently decompress a gzip/deflate/br response body. Default true. */
+    readonly decompress?: boolean;
+    /**
+     * Offer HTTP/2 in the TLS ALPN handshake. Off by default: HTTP/2 changes how headers reach
+     * the wire (and so what the raw view can faithfully reconstruct), so it is opt-in. Plain
+     * HTTP is always HTTP/1.1 — there is no ALPN to negotiate over.
+     */
+    readonly allowH2?: boolean;
+}
+/**
+ * TLS options, passed through to undici's connector. The Task 49 UI will
+ * populate these; this task only wires the pass-through.
+ */
+export interface TlsOptions {
+    readonly rejectUnauthorized?: boolean;
+    readonly ca?: readonly string[];
+    readonly cert?: string;
+    readonly key?: string;
+    readonly passphrase?: string;
+    readonly minVersion?: 'TLSv1.2' | 'TLSv1.3';
+    readonly servername?: string;
+}
+/**
+ * Proxy options, passed through to undici's `ProxyAgent`. The Task 49 UI
+ * will populate these; this task only wires the pass-through.
+ */
+export interface ProxyOptions {
+    readonly url: string;
+    readonly auth?: {
+        readonly username: string;
+        readonly password: string;
+    };
+}
+/** Timing breakdown for one HTTP exchange. Every field but `totalMs` is best-effort. */
+export interface Timings {
+    readonly startedAt: string;
+    readonly totalMs: number;
+    readonly dnsMs?: number;
+    readonly connectMs?: number;
+    readonly tlsMs?: number;
+    readonly ttfbMs?: number;
+    readonly downloadMs?: number;
+}
+/** The full record of one HTTP request/response exchange, including raw wire bytes. */
+export interface HttpExchange {
+    readonly request: {
+        readonly url: string;
+        readonly method: string;
+        readonly headers: Readonly<Record<string, string>>;
+    };
+    readonly status: number;
+    readonly statusText: string;
+    /** Lower-cased header names; multi-values joined with ', ' except `set-cookie`, which keeps only the first. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly rawHeaders: readonly (readonly [string, string])[];
+    /** Decoded response body (decompressed when `decompress` was requested). */
+    readonly body: Uint8Array;
+    /** Response body exactly as received on the wire, possibly still compressed. */
+    readonly rawBody: Uint8Array;
+    /**
+     * The protocol the exchange actually travelled over, from the negotiated ALPN: `2` only when
+     * the caller offered HTTP/2 and the server took it. Labels the raw view.
+     */
+    readonly httpVersion: '1.1' | '2';
+    /** True when the body was cut short because it exceeded `maxSizeBytes`. */
+    readonly truncated: boolean;
+    /**
+     * Set when the response body failed to decompress (e.g. malformed gzip).
+     * When present, `body` equals `rawBody` (decompression was not applied)
+     * rather than throwing.
+     */
+    readonly decodeError?: string;
+    readonly timings: Timings;
+    /** Reconstructed request line + headers + body, as it was (or would be) sent on the wire. */
+    readonly rawRequest: Uint8Array;
+    /** Reconstructed status line + headers + body, as received on the wire. */
+    readonly rawResponse: Uint8Array;
+    readonly redirects: readonly {
+        readonly url: string;
+        readonly status: number;
+    }[];
+    /**
+     * The TLS connection this exchange travelled over: protocol, cipher, whether the
+     * peer chain verified, and the chain itself. Absent for plain HTTP.
+     */
+    readonly tls?: SslInfo;
+}
+/** Stable, machine-readable classification for {@link HttpError}. */
+export type HttpErrorCode = 'timeout' | 'aborted' | 'connection-refused' | 'dns' | 'tls'
+/** The peer chain did not verify against the trust store in use; `details.peerSubject` names the leaf. */
+ | 'tls-untrusted' | 'too-large' | 'too-many-redirects' | 'invalid-url' | 'proxy' | 'network';

package/dist/http/types.js

@@ -0,0 +1,6 @@
+/**
+ * Wire-level types for the HTTP transport (Task 10). These are transport
+ * concerns only: no auth, no MIME/SOAP semantics. Auth (Task 49) and WS-Security
+ * layer on top by producing headers/body before `sendHttp` is called.
+ */
+export {};

package/dist/import-detect.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Format detection for API definition imports: WSDL, OpenAPI / Swagger, Postman Collections,
+ * Protocol Buffers (`.proto`) and legacy single-XML SOAP projects.
+ *
+ * Inspects document text, file names, or URLs to classify definition formats before or during import.
+ */
+export type ImportFormatKind = 'openapi' | 'postman' | 'wsdl' | 'proto' | 'legacy-soap-project' | 'unknown';
+export interface DetectedImportFormat {
+    readonly kind: ImportFormatKind;
+    readonly label: string;
+    readonly confidence: 'definite' | 'probable' | 'unknown';
+}
+export interface ImportDetectInput {
+    readonly text?: string | undefined;
+    readonly filename?: string | undefined;
+    readonly url?: string | undefined;
+}
+/**
+ * `text` with the whitespace and `//` / `/* *\/` comments a `.proto` may open with removed, by a
+ * linear scan: a regex with a repeated comment group backtracks badly on crafted input.
+ */
+export declare function stripLeadingProtoComments(text: string): string;
+/**
+ * Detects the API definition format from text content, filename, or URL.
+ */
+export declare function detectImportFormat(input: ImportDetectInput): DetectedImportFormat;