@provian/mcp 1.2.3 → 1.3.0

package/dist/core/guarded-fetch.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOH_RESOLVERS = exports.EgressRefusedError = void 0;
+exports.clearDohCache = clearDohCache;
+exports.resolveViaDoh = resolveViaDoh;
+exports.isFakeIpAnswer = isFakeIpAnswer;
+exports.egressResolver = egressResolver;
+exports.guardedFetch = guardedFetch;
+exports.guardedFetcher = guardedFetcher;
+/** The sole SDK HTTP egress transport: validated DNS bound to the socket, redirects refused. */
+const pinned_connection_1 = require("./pinned-connection");
+const pinned_agent_1 = require("./pinned-agent");
+const node_net_1 = require("node:net");
+const promises_1 = require("node:dns/promises");
+const egress_guard_1 = require("./egress-guard");
+/** The guard refused the destination before any byte left the machine. */
+class EgressRefusedError extends Error {
+    constructor(code, reason) {
+        super(`egress refused: ${code}: ${reason}`);
+        this.name = 'EgressRefusedError';
+        this.code = `EGRESS_${code ?? 'REFUSED'}`;
+    }
+}
+exports.EgressRefusedError = EgressRefusedError;
+function abortable(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener('abort', abort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    });
+}
+/**
+ * DNS-over-HTTPS resolvers, addressed by IP so reaching them needs no DNS. Each serves the
+ * dns-json shape at the path named here, and each certificate carries its IP as a SAN.
+ */
+exports.DOH_RESOLVERS = [
+    'https://1.1.1.1/dns-query',
+    'https://8.8.8.8/resolve',
+];
+const DOH_TIMEOUT_MS = 8000;
+/**
+ * Resolve `hostname` over DNS-over-HTTPS, carried by the same forward proxy as the request.
+ *
+ * A box whose only egress is a forward proxy often has no DNS of its own (a hosted agent's
+ * runtime cell: `getaddrinfo` answers EAI_AGAIN). curl hands the name to the proxy; the guard
+ * cannot, because it must check the destination's addresses and pin the tunnel to them
+ * (Security Invariant #6). So the guard asks a public resolver, through the proxy, over TLS —
+ * and the answer is checked against the blocklist and pinned exactly like a local answer.
+ * Returns [] when no resolver answers (the guard then refuses: unknown = block).
+ */
+/** Successful DNS-over-HTTPS answers, kept for their TTL (at most 5 minutes). */
+const DOH_CACHE_MAX_MS = 5 * 60 * 1000;
+const dohCache = new Map();
+/** Test seam: forget cached DNS-over-HTTPS answers. */
+function clearDohCache() { dohCache.clear(); }
+async function resolveViaDoh(hostname, fetchFn) {
+    const key = hostname.toLowerCase();
+    const cached = dohCache.get(key);
+    if (cached && cached.untilMs > Date.now())
+        return [...cached.ips];
+    for (const base of exports.DOH_RESOLVERS) {
+        for (const type of ['A', 'AAAA']) {
+            try {
+                const res = await guardedFetch(`${base}?name=${encodeURIComponent(hostname)}&type=${type}`, { headers: { accept: 'application/dns-json' }, signal: AbortSignal.timeout(DOH_TIMEOUT_MS) }, { fetchFn });
+                if (!res.ok) {
+                    void res.body?.cancel().catch(() => undefined);
+                    continue;
+                }
+                const body = await res.json();
+                if (body.Status !== 0 || !Array.isArray(body.Answer))
+                    continue;
+                const want = type === 'A' ? 1 : 28;
+                const records = body.Answer
+                    .filter((a) => typeof a === 'object' && a !== null
+                    && a.type === want && typeof a.data === 'string')
+                    .filter(a => (0, node_net_1.isIP)(a.data) === (type === 'A' ? 4 : 6));
+                const ips = records.map(a => a.data);
+                if (ips.length) {
+                    const ttls = records.map(a => (typeof a.TTL === 'number' && a.TTL >= 0 ? a.TTL * 1000 : 0));
+                    const ttlMs = Math.min(DOH_CACHE_MAX_MS, ...ttls);
+                    if (ttlMs > 0)
+                        dohCache.set(key, { ips: [...ips], untilMs: Date.now() + ttlMs });
+                    return ips;
+                }
+            }
+            catch { /* next resolver */ }
+        }
+    }
+    return [];
+}
+/**
+ * A fake-IP gateway's answer: every name resolves into 198.18.0.0/15 (the benchmark range,
+ * RFC 2544), and the gateway maps that address back to the name when the box connects. Such an
+ * answer says nothing about where the name really points, so the guard cannot check it.
+ */
+function isFakeIpAnswer(ips) {
+    if (ips.length === 0)
+        return false;
+    return ips.every((ip) => {
+        const m = /^(?:::ffff:)?198\.(18|19)\.(\d{1,3})\.(\d{1,3})$/i.exec(ip);
+        return m !== null;
+    });
+}
+/**
+ * The resolver the guard uses for `url`, so a destination's REAL addresses are what it checks
+ * and pins (Security Invariant #6):
+ *  - the box's own DNS answer, when it is a real answer (any blocked address in it refuses);
+ *  - DNS-over-HTTPS when that answer is a fake-IP gateway's (all in 198.18.0.0/15): the real
+ *    addresses are checked and the connection is pinned to them, never to the gateway's
+ *    stand-in address;
+ *  - DNS-over-HTTPS through the forward proxy when the box has no DNS at all and a proxy
+ *    carries the request. With no proxy and no DNS: no address, refused (unknown = block).
+ */
+function egressResolver(url, fetchFn) {
+    let proxied = false;
+    let schemeProxySet = false;
+    // The variable names in effect, as proxyFor reads them (lowercase wins), so a message names
+    // the one the person must change.
+    let proxyVar = 'HTTPS_PROXY';
+    const noProxyVar = process.env.no_proxy ? 'no_proxy' : 'NO_PROXY';
+    try {
+        const parsed = new URL(url);
+        proxied = Boolean((0, pinned_connection_1.proxyFor)(parsed));
+        const https = parsed.protocol === 'https:';
+        proxyVar = https ? (process.env.https_proxy ? 'https_proxy' : 'HTTPS_PROXY') : (process.env.http_proxy ? 'http_proxy' : 'HTTP_PROXY');
+        // The proxy that would carry this scheme (as proxyFor reads it), before NO_PROXY applies.
+        schemeProxySet = Boolean(https
+            ? process.env.https_proxy || process.env.HTTPS_PROXY
+            : process.env.http_proxy || process.env.HTTP_PROXY);
+    }
+    catch {
+        proxied = false;
+    }
+    const proxyExcluded = !proxied && schemeProxySet;
+    return async (hostname) => {
+        let local = [];
+        try {
+            local = (await (0, promises_1.lookup)(hostname, { all: true })).map(r => r.address);
+        }
+        catch {
+            local = [];
+        }
+        if (local.length && !isFakeIpAnswer(local))
+            return local;
+        if (local.length === 0 && !proxied) {
+            throw new Error(proxyExcluded
+                ? `no answer from this machine's DNS; a proxy is set but ${noProxyVar} sends this host direct, so no DNS-over-HTTPS lookup was tried`
+                : 'no answer from this machine\'s DNS; no proxy set, so no DNS-over-HTTPS lookup was tried');
+        }
+        if (proxied && !(0, pinned_connection_1.proxyUrlOf)((0, pinned_connection_1.proxyFor)(new URL(url)) ?? '')) {
+            throw new Error(`${local.length ? 'this machine\'s DNS gave only a gateway stand-in address (198.18.0.0/15)' : 'no answer from this machine\'s DNS'}; the proxy setting (${proxyVar}) is not an http:// or https:// proxy, so no DNS-over-HTTPS lookup was tried`);
+        }
+        const real = await resolveViaDoh(hostname, fetchFn);
+        if (real.length === 0) {
+            throw new Error(local.length
+                ? 'this machine\'s DNS gave only a gateway stand-in address (198.18.0.0/15); the DNS-over-HTTPS lookup (1.1.1.1, 8.8.8.8) got no answer'
+                : 'no answer from this machine\'s DNS; the DNS-over-HTTPS lookup through the proxy (1.1.1.1, 8.8.8.8) got no answer');
+        }
+        return real;
+    };
+}
+/**
+ * No ambient dispatcher or later DNS lookup can change the approved destination.
+ *
+ * The pinned dispatcher is a `PinnedAgent` (`pinned-agent.ts`), which every Node's built-in fetch
+ * from 20 through 26 accepts — so the default (built-in) fetch, an injected one, and a caller's own
+ * wrapper that delegates to the built-in fetch all carry it, on every supported Node.
+ */
+async function guardedFetch(input, init, options = {}) {
+    const url = input instanceof Request ? input.url : String(input);
+    const signal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
+    const resolveHost = options.resolveHost ?? egressResolver(url, options.fetchFn);
+    const guard = await abortable((0, egress_guard_1.validateEgressTarget)(url, { resolveHost }), signal);
+    if (!guard.ok || !guard.resolvedIps?.length)
+        throw new EgressRefusedError(guard.code, guard.reason);
+    const connect = await abortable((0, pinned_connection_1.pinnedConnector)(new URL(url), guard.resolvedIps, options.resolveHost), signal);
+    const dispatcher = new pinned_agent_1.PinnedAgent({ connect });
+    const cleanup = () => {
+        signal?.removeEventListener('abort', cleanup);
+        void dispatcher.destroy().catch(() => undefined);
+    };
+    signal?.addEventListener('abort', cleanup, { once: true });
+    if (signal?.aborted)
+        cleanup();
+    try {
+        const f = options.fetchFn ?? globalThis.fetch;
+        const requestInit = { ...init, redirect: 'manual', dispatcher };
+        const res = await abortable(f(input, requestInit), signal);
+        if (res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400)) {
+            void res.body?.cancel().catch(() => undefined);
+            throw new Error('egress redirect refused');
+        }
+        if (!res.body) {
+            cleanup();
+            return res;
+        }
+        const reader = res.body.getReader();
+        const body = new ReadableStream({
+            async pull(controller) {
+                try {
+                    const next = await abortable(reader.read(), signal);
+                    if (next.done) {
+                        controller.close();
+                        cleanup();
+                    }
+                    else
+                        controller.enqueue(next.value);
+                }
+                catch (err) {
+                    controller.error(err);
+                    cleanup();
+                    void reader.cancel().catch(() => undefined);
+                }
+            },
+            cancel(reason) { cleanup(); return reader.cancel(reason); },
+        });
+        const response = new Response(body, { status: res.status, statusText: res.statusText, headers: res.headers });
+        Object.defineProperty(response, 'url', { value: res.url || url });
+        return response;
+    }
+    catch (err) {
+        cleanup();
+        throw err;
+    }
+}
+/** Wrap an injected HTTP implementation as well as the native default. */
+function guardedFetcher(fetchFn, resolveHost) {
+    if (fetchFn === guardedFetch && !resolveHost)
+        return guardedFetch;
+    return (input, init) => guardedFetch(input, init, { fetchFn, resolveHost });
+}
+//# sourceMappingURL=guarded-fetch.js.map

package/dist/core/guarded-fetch.js.map

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

package/dist/core/pinned-agent.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The SDK's pinned dispatcher, accepted by every Node's built-in fetch from 20 through 26.
+ *
+ * The egress guard pins each request to the addresses it approved by handing fetch a `dispatcher`:
+ * an `Agent` from the `undici` package whose connector resolves only to those addresses
+ * (`pinned-connection.ts`, Security Invariant #6). Node's built-in fetch is a different undici,
+ * bundled with Node, and it calls `dispatcher.dispatch(options, handler)`:
+ *  - Node 20 / 22 / 24 (undici 6 and 7) hand over a handler with the classic callbacks
+ *    (`onConnect`, `onHeaders`, `onData`, `onComplete`, `onError`) — the `undici@6` Agent's own API;
+ *  - Node 26 (undici 8) hands over a handler with only the controller callbacks
+ *    (`onRequestStart`, `onResponseStart`, `onResponseData`, `onResponseEnd`, `onResponseError`),
+ *    which `undici@6` refuses (`UND_ERR_INVALID_ARG`, "invalid onError method") — so before this
+ *    module every SDK egress through the built-in fetch, or through a caller's wrapper of it,
+ *    failed on Node 26.
+ *
+ * `PinnedAgent` is that same `undici@6` Agent, connector and all, whose `dispatch` translates a
+ * controller-style handler into the classic one — exactly the bridge `undici@7`'s own dispatcher
+ * applies (`lib/handler/unwrap-handler.js`, MIT), with a header parser that never writes through a
+ * prototype. A classic handler passes through untouched, so Node 20–24 behave byte-for-byte as before.
+ * Nothing about WHERE a request may connect changes here: the connector is the pinned one.
+ */
+import type { Duplex } from 'node:stream';
+import { Agent, type Dispatcher } from 'undici';
+/** A parsed header block: lowercase name → value(s), on an object with no prototype to write through. */
+export type ParsedHeaders = Record<string, string | string[]>;
+/** The controller a controller-style handler drives the request with (undici ≥7 / Node 26 fetch). */
+export interface DispatchController {
+    abort(reason?: Error): void;
+    pause(): void;
+    resume(): void;
+    readonly aborted: boolean;
+    readonly paused: boolean;
+    readonly reason: Error | null;
+    rawHeaders: Buffer[] | string[] | null;
+    rawTrailers: string[] | Buffer[] | null;
+}
+/** The controller-style callbacks (undici ≥7's handler API). */
+export interface ControllerDispatchHandler {
+    onRequestStart?(controller: DispatchController, context: unknown): void;
+    onRequestUpgrade?(controller: DispatchController, statusCode: number, headers: ParsedHeaders, socket: Duplex): void;
+    onResponseStarted?(): void;
+    onResponseStart?(controller: DispatchController, statusCode: number, headers: ParsedHeaders, statusMessage?: string): void;
+    onResponseData?(controller: DispatchController, chunk: Buffer): void;
+    onResponseEnd?(controller: DispatchController, trailers: ParsedHeaders): void;
+    onResponseError?(controller: DispatchController, error: Error): void;
+}
+/** True when `handler` speaks the controller API (undici ≥7's own test: an `onRequestStart`). */
+export declare function isControllerHandler(handler: unknown): handler is ControllerDispatchHandler;
+/**
+ * Raw header pairs → `{ name: value | values }`, decoded latin1 as undici ≥7 does. The result has no
+ * prototype and every name is defined as an own property, so `__proto__`, `constructor` or any other
+ * name from a server can neither pollute a prototype nor break the parse.
+ */
+export declare function parseRawHeaderPairs(raw: ReadonlyArray<Buffer | string | (Buffer | string)[]> | null | undefined): ParsedHeaders;
+/** A controller-style handler as the classic callbacks the `undici@6` Agent drives (undici ≥7's UnwrapHandler). */
+export declare function classicHandlerFor(handler: ControllerDispatchHandler): Dispatcher.DispatchHandlers;
+/** The pinned `undici@6` Agent, speaking both handler APIs (see the module comment). */
+export declare class PinnedAgent extends Agent {
+    dispatch(options: Agent.DispatchOptions, handler: Dispatcher.DispatchHandlers): boolean;
+}
+//# sourceMappingURL=pinned-agent.d.ts.map

package/dist/core/pinned-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-agent.d.ts","sourceRoot":"","sources":["../../src/core/pinned-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEhD,yGAAyG;AACzG,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;AAE9D,qGAAqG;AACrG,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAC5B,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACvC,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;CACzC;AAED,gEAAgE;AAChE,MAAM,WAAW,yBAAyB;IACxC,cAAc,CAAC,CAAC,UAAU,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACxE,gBAAgB,CAAC,CAAC,UAAU,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACpH,iBAAiB,CAAC,IAAI,IAAI,CAAC;IAC3B,eAAe,CAAC,CAAC,UAAU,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3H,cAAc,CAAC,CAAC,UAAU,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrE,aAAa,CAAC,CAAC,UAAU,EAAE,kBAAkB,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9E,eAAe,CAAC,CAAC,UAAU,EAAE,kBAAkB,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACtE;AAED,iGAAiG;AACjG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,yBAAyB,CAG1F;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,CAgB/H;AA2BD,mHAAmH;AACnH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,yBAAyB,GAAG,UAAU,CAAC,gBAAgB,CAoCjG;AAED,wFAAwF;AACxF,qBAAa,WAAY,SAAQ,KAAK;IAC3B,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,eAAe,EAAE,OAAO,EAAE,UAAU,CAAC,gBAAgB,GAAG,OAAO;CAGjG"}

package/dist/core/pinned-agent.js

@@ -0,0 +1,125 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _BridgeController_paused, _BridgeController_aborted, _BridgeController_reason, _BridgeController_abort;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PinnedAgent = void 0;
+exports.isControllerHandler = isControllerHandler;
+exports.parseRawHeaderPairs = parseRawHeaderPairs;
+exports.classicHandlerFor = classicHandlerFor;
+const undici_1 = require("undici");
+/** True when `handler` speaks the controller API (undici ≥7's own test: an `onRequestStart`). */
+function isControllerHandler(handler) {
+    return typeof handler === 'object' && handler !== null
+        && typeof handler.onRequestStart === 'function';
+}
+/**
+ * Raw header pairs → `{ name: value | values }`, decoded latin1 as undici ≥7 does. The result has no
+ * prototype and every name is defined as an own property, so `__proto__`, `constructor` or any other
+ * name from a server can neither pollute a prototype nor break the parse.
+ */
+function parseRawHeaderPairs(raw) {
+    const out = Object.create(null);
+    if (!raw)
+        return out;
+    const text = (v) => (typeof v === 'string' ? v : v.toString('latin1'));
+    for (let i = 0; i + 1 < raw.length; i += 2) {
+        const nameRaw = raw[i], valueRaw = raw[i + 1];
+        if (Array.isArray(nameRaw))
+            continue;
+        const name = text(nameRaw).toLowerCase();
+        const values = Array.isArray(valueRaw) ? valueRaw.map(text) : [text(valueRaw)];
+        const prior = Object.prototype.hasOwnProperty.call(out, name) ? out[name] : undefined;
+        const next = prior === undefined
+            ? (values.length === 1 ? values[0] : values)
+            : [...(typeof prior === 'string' ? [prior] : prior), ...values];
+        Object.defineProperty(out, name, { value: next, enumerable: true, configurable: true, writable: true });
+    }
+    return out;
+}
+class BridgeController {
+    constructor(abort) {
+        _BridgeController_paused.set(this, false);
+        _BridgeController_aborted.set(this, false);
+        _BridgeController_reason.set(this, null);
+        _BridgeController_abort.set(this, void 0);
+        this.resumeRead = null;
+        this.rawHeaders = null;
+        this.rawTrailers = null;
+        __classPrivateFieldSet(this, _BridgeController_abort, abort, "f");
+    }
+    pause() { __classPrivateFieldSet(this, _BridgeController_paused, true, "f"); }
+    resume() {
+        if (__classPrivateFieldGet(this, _BridgeController_paused, "f")) {
+            __classPrivateFieldSet(this, _BridgeController_paused, false, "f");
+            this.resumeRead?.();
+        }
+    }
+    abort(reason) {
+        if (__classPrivateFieldGet(this, _BridgeController_aborted, "f"))
+            return;
+        __classPrivateFieldSet(this, _BridgeController_aborted, true, "f");
+        __classPrivateFieldSet(this, _BridgeController_reason, reason ?? null, "f");
+        __classPrivateFieldGet(this, _BridgeController_abort, "f").call(this, reason);
+    }
+    get aborted() { return __classPrivateFieldGet(this, _BridgeController_aborted, "f"); }
+    get paused() { return __classPrivateFieldGet(this, _BridgeController_paused, "f"); }
+    get reason() { return __classPrivateFieldGet(this, _BridgeController_reason, "f"); }
+}
+_BridgeController_paused = new WeakMap(), _BridgeController_aborted = new WeakMap(), _BridgeController_reason = new WeakMap(), _BridgeController_abort = new WeakMap();
+/** A controller-style handler as the classic callbacks the `undici@6` Agent drives (undici ≥7's UnwrapHandler). */
+function classicHandlerFor(handler) {
+    let controller = null;
+    const live = () => (controller ?? (controller = new BridgeController(() => undefined)));
+    return {
+        onConnect(abort, context) {
+            controller = new BridgeController(abort);
+            handler.onRequestStart?.(controller, context);
+        },
+        onResponseStarted() { handler.onResponseStarted?.(); },
+        onUpgrade(statusCode, rawHeaders, socket) {
+            const c = live();
+            c.rawHeaders = rawHeaders;
+            handler.onRequestUpgrade?.(c, statusCode, parseRawHeaderPairs(rawHeaders), socket);
+        },
+        onHeaders(statusCode, rawHeaders, resume, statusText) {
+            const c = live();
+            c.resumeRead = resume;
+            c.rawHeaders = rawHeaders;
+            handler.onResponseStart?.(c, statusCode, parseRawHeaderPairs(rawHeaders), statusText);
+            return !c.paused;
+        },
+        onData(chunk) {
+            const c = live();
+            handler.onResponseData?.(c, chunk);
+            return !c.paused;
+        },
+        onComplete(rawTrailers) {
+            const c = live();
+            c.rawTrailers = rawTrailers;
+            handler.onResponseEnd?.(c, parseRawHeaderPairs(rawTrailers));
+        },
+        onError(err) {
+            if (typeof handler.onResponseError !== 'function')
+                throw new Error('invalid onError method');
+            handler.onResponseError(live(), err);
+        },
+    };
+}
+/** The pinned `undici@6` Agent, speaking both handler APIs (see the module comment). */
+class PinnedAgent extends undici_1.Agent {
+    dispatch(options, handler) {
+        return super.dispatch(options, isControllerHandler(handler) ? classicHandlerFor(handler) : handler);
+    }
+}
+exports.PinnedAgent = PinnedAgent;
+//# sourceMappingURL=pinned-agent.js.map

package/dist/core/pinned-agent.js.map

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

package/dist/core/pinned-connection.d.ts

@@ -0,0 +1,15 @@
+import type { LookupFunction } from 'node:net';
+import { buildConnector } from 'undici';
+import type { HostResolver } from './egress-guard';
+export declare function pinnedLookup(hostname: string, addresses: readonly string[]): LookupFunction;
+/** The forward proxy that carries a request to `url`, honouring NO_PROXY; undefined when none. */
+export declare function proxyFor(url: URL): string | undefined;
+/**
+ * The forward proxy as a URL, read as curl reads it: a value with no scheme
+ * (`proxy.local:3128`, `127.0.0.1:3128`) means http://. Null for anything other than an
+ * http:// or https:// proxy (Provian speaks only HTTP CONNECT to a proxy).
+ */
+export declare function proxyUrlOf(value: string): URL | null;
+/** The target is approved and the proxy socket pinned; CONNECT names an IP, never remote DNS. */
+export declare function pinnedConnector(url: URL, addresses: readonly string[], resolveHost?: HostResolver): Promise<buildConnector.connector>;
+//# sourceMappingURL=pinned-connection.d.ts.map

package/dist/core/pinned-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-connection.d.ts","sourceRoot":"","sources":["../../src/core/pinned-connection.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAS3F;AAED,kGAAkG;AAClG,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAYrD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAMpD;AAqBD,iGAAiG;AACjG,wBAAsB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,CAkC3I"}

package/dist/core/pinned-connection.js

@@ -0,0 +1,172 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pinnedLookup = pinnedLookup;
+exports.proxyFor = proxyFor;
+exports.proxyUrlOf = proxyUrlOf;
+exports.pinnedConnector = pinnedConnector;
+/** Fresh, DNS-pinned sockets, including approved forward-proxy CONNECT tunnels. */
+const http = __importStar(require("node:http"));
+const https = __importStar(require("node:https"));
+const node_net_1 = require("node:net");
+const undici_1 = require("undici");
+const promises_1 = require("node:dns/promises");
+function pinnedLookup(hostname, addresses) {
+    return (host, opts, callback) => {
+        if (host.replace(/^\[|\]$/g, '') !== hostname.replace(/^\[|\]$/g, '')) {
+            callback(new Error('egress lookup host mismatch'), '', 4);
+            return;
+        }
+        const matches = addresses.map(address => ({ address, family: (0, node_net_1.isIP)(address) }))
+            .filter(a => !opts.family || opts.family === a.family);
+        if (!matches.length) {
+            callback(new Error('egress address family unavailable'), '', 4);
+            return;
+        }
+        if (opts.all)
+            callback(null, matches);
+        else
+            callback(null, matches[0].address, matches[0].family);
+    };
+}
+/** The forward proxy that carries a request to `url`, honouring NO_PROXY; undefined when none. */
+function proxyFor(url) {
+    const excluded = (process.env.no_proxy || process.env.NO_PROXY || '').split(',').some(raw => {
+        const entry = raw.trim().toLowerCase();
+        if (!entry)
+            return false;
+        if (entry === '*')
+            return true;
+        const host = url.hostname.toLowerCase();
+        if (entry === host || entry === url.host.toLowerCase())
+            return true;
+        const suffix = entry.replace(/^\*?\./, '');
+        return host === suffix || host.endsWith(`.${suffix}`);
+    });
+    if (excluded)
+        return undefined;
+    return url.protocol === 'https:' ? process.env.https_proxy || process.env.HTTPS_PROXY : process.env.http_proxy || process.env.HTTP_PROXY;
+}
+/**
+ * The forward proxy as a URL, read as curl reads it: a value with no scheme
+ * (`proxy.local:3128`, `127.0.0.1:3128`) means http://. Null for anything other than an
+ * http:// or https:// proxy (Provian speaks only HTTP CONNECT to a proxy).
+ */
+function proxyUrlOf(value) {
+    const raw = value.trim();
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `http://${raw}`);
+    }
+    catch {
+        return null;
+    }
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:' ? parsed : null;
+}
+/**
+ * The proxy's addresses. The forward proxy is the OPERATOR's own egress hop — an environment
+ * variable only the box's operator sets, and commonly a host on the local network — so the SSRF
+ * block does not apply to it: what the guard approved is the TARGET, and CONNECT names the approved
+ * target IP. The proxy host is still resolved here, once, and the proxy socket pinned to that
+ * answer, so nothing re-resolves it in transit. (Before 2026-10-17 the proxy went through the
+ * target guard, which refused every private-network proxy — the corporate deployment.)
+ */
+async function resolveProxyAddresses(hostname, resolveHost) {
+    const bare = hostname.replace(/^\[|\]$/g, '');
+    if ((0, node_net_1.isIP)(bare))
+        return [bare];
+    try {
+        const ips = resolveHost ? await resolveHost(bare) : (await (0, promises_1.lookup)(bare, { all: true })).map(r => r.address);
+        return ips.filter(ip => (0, node_net_1.isIP)(ip) !== 0);
+    }
+    catch {
+        return [];
+    }
+}
+/** The target is approved and the proxy socket pinned; CONNECT names an IP, never remote DNS. */
+async function pinnedConnector(url, addresses, resolveHost) {
+    const direct = (0, undici_1.buildConnector)({ lookup: pinnedLookup(url.hostname, addresses) });
+    const proxyValue = proxyFor(url);
+    if (!proxyValue)
+        return direct;
+    const proxy = proxyUrlOf(proxyValue);
+    if (!proxy)
+        throw new Error('egress proxy protocol refused');
+    const proxyIps = await resolveProxyAddresses(proxy.hostname, resolveHost);
+    if (proxyIps.length === 0)
+        throw new Error('egress proxy refused');
+    return (options, callback) => {
+        const agent = proxy.protocol === 'https:' ? new https.Agent({ keepAlive: false }) : new http.Agent({ keepAlive: false });
+        const address = addresses[0], port = options.port || (url.protocol === 'https:' ? '443' : '80');
+        const authority = `${(0, node_net_1.isIP)(address) === 6 ? `[${address}]` : address}:${port}`;
+        const headers = { host: authority };
+        if (proxy.username || proxy.password)
+            headers['proxy-authorization'] = `Basic ${Buffer.from(`${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`).toString('base64')}`;
+        const transport = proxy.protocol === 'https:' ? https : http;
+        const request = transport.request(proxy, { method: 'CONNECT', path: authority, headers, agent, lookup: pinnedLookup(proxy.hostname, proxyIps), timeout: 10000 });
+        let finished = false;
+        const finish = (err, socket) => {
+            if (finished)
+                return;
+            finished = true;
+            if (err) {
+                agent.destroy();
+                callback(err, null);
+            }
+            else
+                callback(null, socket);
+        };
+        request.on('timeout', () => request.destroy(new Error('egress proxy connection timed out')));
+        request.on('error', err => finish(err, null));
+        request.on('connect', (response, socket, head) => {
+            if (response.statusCode !== 200 || head.length) {
+                socket.destroy();
+                finish(new Error('egress proxy tunnel refused'), null);
+                return;
+            }
+            // An IP-literal target (the DNS-over-HTTPS resolvers) sends no SNI (RFC 6066) and is
+            // verified against the certificate's IP SAN instead.
+            const bare = url.hostname.replace(/^\[|\]$/g, '');
+            if (url.protocol === 'https:')
+                direct({ ...options, httpSocket: socket, ...((0, node_net_1.isIP)(bare) ? {} : { servername: url.hostname }) }, finish);
+            else
+                finish(null, socket);
+        });
+        request.end();
+    };
+}
+//# sourceMappingURL=pinned-connection.js.map