ssrf-lab 0.0.0-stage → 0.1.0

package/dist/adapters/guardedFetch.d.ts

@@ -0,0 +1,13 @@
+import { type HttpClient } from './types.js';
+/**
+ * A client with the 4 controls the range tests.
+ *
+ * 1. Every hop is judged, not only the first URL.
+ * 2. The address is judged where the socket connects, so a second answer
+ *    cannot differ from the one that passed the check.
+ * 3. The body is capped while it is read, after decompression.
+ * 4. ONE deadline covers the whole request, the body read included. A socket
+ *    timeout is not a deadline: a target that sends 1 byte per second keeps
+ *    the socket busy and holds the connection for as long as it likes.
+ */
+export declare const guardedFetch: HttpClient;

package/dist/adapters/guardedFetch.js

@@ -0,0 +1,110 @@
+import { lookup as systemLookup } from 'node:dns';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { isIP } from 'node:net';
+import { classifyAddress, isForbiddenAddress } from '../util/addresses.js';
+import { assertAllowedProtocol, guardedLookup, readCapped, redact } from './internal.js';
+import { PolicyRefusal } from './types.js';
+const DEFAULT_MAX_REDIRECTS = 3;
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 3000;
+/**
+ * A client with the 4 controls the range tests.
+ *
+ * 1. Every hop is judged, not only the first URL.
+ * 2. The address is judged where the socket connects, so a second answer
+ *    cannot differ from the one that passed the check.
+ * 3. The body is capped while it is read, after decompression.
+ * 4. ONE deadline covers the whole request, the body read included. A socket
+ *    timeout is not a deadline: a target that sends 1 byte per second keeps
+ *    the socket busy and holds the connection for as long as it likes.
+ */
+export const guardedFetch = {
+    name: 'guarded client (this repo)',
+    supportsConnectHook: true,
+    async fetch(url, options = {}) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const deadline = AbortSignal.timeout(timeoutMs);
+        try {
+            return await follow(url, options, deadline);
+        }
+        catch (error) {
+            throw asDeadline(error, timeoutMs, deadline);
+        }
+    },
+};
+async function follow(url, options, deadline) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const lookup = guardedLookup(options.lookup);
+    const hops = [];
+    let target = new URL(url);
+    for (let hop = 0; hop <= DEFAULT_MAX_REDIRECTS; hop += 1) {
+        const trusted = target.origin === options.trustedOrigin;
+        assertAllowedProtocol(target);
+        if (!trusted)
+            refuseForbiddenLiteral(target);
+        hops.push(redact(target));
+        const response = await send(target, trusted ? systemLookup : lookup, deadline);
+        const location = response.headers.location;
+        if (isRedirect(response.statusCode ?? 0) && typeof location === 'string') {
+            response.resume();
+            target = new URL(location, target);
+            continue;
+        }
+        const body = await readCapped(response, maxBytes);
+        return {
+            status: response.statusCode ?? 0,
+            bytesRead: body.bytes,
+            bodySample: body.sample,
+            hops,
+            stoppedByHarness: false,
+        };
+    }
+    throw new PolicyRefusal('too-many-redirects', `more than ${DEFAULT_MAX_REDIRECTS} hops`);
+}
+function isRedirect(status) {
+    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+/**
+ * Refuse an address literal before any resolver runs.
+ *
+ * `http://2130706433/` carries no name to resolve, and the URL parser has
+ * already turned it into 127.0.0.1 by the time this reads the hostname.
+ */
+function refuseForbiddenLiteral(url) {
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    if (isIP(host) === 0)
+        return;
+    if (isForbiddenAddress(host)) {
+        throw new PolicyRefusal('forbidden-address', `${host} is ${classifyAddress(host)}`);
+    }
+}
+function send(url, lookup, signal) {
+    const transport = url.protocol === 'https:' ? httpsRequest : httpRequest;
+    return new Promise((resolve, reject) => {
+        const request = transport(url, {
+            lookup,
+            signal,
+            headers: { 'user-agent': 'ssrf-lab/0.1 (+https://github.com/roshan-amble/ssrf-lab)' },
+        }, resolve);
+        request.on('error', reject);
+        request.end();
+    });
+}
+/**
+ * Turn an abort into the refusal it represents.
+ *
+ * The deadline is ours, so an abort caused by it is a decision this client
+ * made, not a network failure. Reporting it as a failure would hide a control.
+ */
+function asDeadline(error, timeoutMs, deadline) {
+    if (error instanceof PolicyRefusal)
+        return error;
+    // The signal is the evidence, not the error code. Destroying a socket that
+    // is mid-read surfaces as ECONNRESET, and reading only the code turns this
+    // client's own deadline into a network failure.
+    if (deadline.aborted)
+        return new PolicyRefusal('deadline', `${timeoutMs} ms elapsed`);
+    return error;
+}
+//# sourceMappingURL=guardedFetch.js.map

package/dist/adapters/guardedFetch.js.map

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

package/dist/adapters/internal.d.ts

@@ -0,0 +1,30 @@
+import type { IncomingMessage } from 'node:http';
+import type { LookupFunction } from 'node:net';
+export declare const SAMPLE_BYTES = 4096;
+export interface ReadResult {
+    bytes: number;
+    sample: string;
+}
+/** Protocols a fetcher of untrusted URLs may speak. */
+export declare function assertAllowedProtocol(url: URL): void;
+/**
+ * A URL that is safe to print.
+ *
+ * A redirect target chosen by the remote host may carry credentials, and a
+ * message that quotes it puts them in a log file.
+ */
+export declare function redact(url: URL): string;
+/**
+ * Resolve a name and judge EVERY address in the answer.
+ *
+ * A mixed answer is refused whole. One public address beside one loopback
+ * address is the attack; connecting to the survivor is what it wants.
+ */
+export declare function guardedLookup(base?: LookupFunction): LookupFunction;
+/**
+ * Read a body against a byte cap, and count the DECOMPRESSED bytes.
+ *
+ * The cap is applied while reading. A length check after `await body()` is not
+ * a cap, because the bytes are already in memory when it runs.
+ */
+export declare function readCapped(response: IncomingMessage, maxBytes: number): Promise<ReadResult>;

package/dist/adapters/internal.js

@@ -0,0 +1,95 @@
+import { lookup as systemLookup } from 'node:dns';
+import { createGunzip } from 'node:zlib';
+import { classifyAddress, isForbiddenAddress } from '../util/addresses.js';
+import { PolicyRefusal } from './types.js';
+export const SAMPLE_BYTES = 4096;
+/** Protocols a fetcher of untrusted URLs may speak. */
+export function assertAllowedProtocol(url) {
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new PolicyRefusal('scheme-not-allowed', url.protocol);
+    }
+}
+/**
+ * A URL that is safe to print.
+ *
+ * A redirect target chosen by the remote host may carry credentials, and a
+ * message that quotes it puts them in a log file.
+ */
+export function redact(url) {
+    const copy = new URL(url.toString());
+    if (copy.username !== '' || copy.password !== '') {
+        copy.username = '***';
+        copy.password = '';
+    }
+    return copy.toString();
+}
+/**
+ * Resolve a name and judge EVERY address in the answer.
+ *
+ * A mixed answer is refused whole. One public address beside one loopback
+ * address is the attack; connecting to the survivor is what it wants.
+ */
+export function guardedLookup(base = systemLookup) {
+    return ((hostname, options, callback) => {
+        const done = (typeof options === 'function' ? options : callback);
+        // Node asks for every address when it selects a family itself. Answering
+        // with a single string there fails with ERR_INVALID_IP_ADDRESS, and the
+        // guard then looks like a network fault instead of a control.
+        const wantsAll = typeof options === 'object' &&
+            options !== null &&
+            options.all === true;
+        base(hostname, { all: true }, (error, addresses) => {
+            if (error) {
+                done(error);
+                return;
+            }
+            const list = Array.isArray(addresses) ? addresses : [{ address: String(addresses), family: 4 }];
+            const forbidden = list.find((entry) => isForbiddenAddress(entry.address));
+            if (forbidden !== undefined) {
+                done(new PolicyRefusal('forbidden-address', `${hostname} resolved to ${forbidden.address} (${classifyAddress(forbidden.address)})`));
+                return;
+            }
+            const first = list[0];
+            if (first === undefined) {
+                done(new PolicyRefusal('forbidden-address', `${hostname} resolved to nothing`));
+                return;
+            }
+            // The socket gets the address this guard judged, and no later answer can
+            // replace it. That pinning is what closes the rebinding window.
+            if (wantsAll)
+                done(null, list);
+            else
+                done(null, first.address, first.family);
+        });
+    });
+}
+/**
+ * Read a body against a byte cap, and count the DECOMPRESSED bytes.
+ *
+ * The cap is applied while reading. A length check after `await body()` is not
+ * a cap, because the bytes are already in memory when it runs.
+ */
+export async function readCapped(response, maxBytes) {
+    const gunzip = response.headers['content-encoding'] === 'gzip' ? createGunzip() : null;
+    const source = gunzip === null ? response : response.pipe(gunzip);
+    let bytes = 0;
+    let sample = Buffer.alloc(0);
+    try {
+        for await (const chunk of source) {
+            bytes += chunk.byteLength;
+            if (sample.byteLength < SAMPLE_BYTES) {
+                sample = Buffer.concat([sample, chunk.subarray(0, SAMPLE_BYTES - sample.byteLength)]);
+            }
+            if (bytes > maxBytes) {
+                response.destroy();
+                gunzip?.destroy();
+                throw new PolicyRefusal('body-too-large', `stopped after ${bytes} bytes, cap is ${maxBytes}`);
+            }
+        }
+    }
+    finally {
+        gunzip?.destroy();
+    }
+    return { bytes, sample: sample.toString('utf8') };
+}
+//# sourceMappingURL=internal.js.map

package/dist/adapters/internal.js.map

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

package/dist/adapters/libraries.d.ts

@@ -0,0 +1,14 @@
+import type { HttpClient } from './types.js';
+/**
+ * Third-party npm packages whose stated purpose is to stop SSRF.
+ *
+ * A library that never claimed to block anything is not interesting here.
+ * These 3 do claim it, so a probe that reaches the internal service through
+ * one of them is a finding, not a configuration mistake.
+ *
+ * Each package is loaded on the first request, not at import time, so that
+ * ssrf-lab runs without them. See `optional.ts`.
+ */
+export declare const requestFilteringAgent: HttpClient;
+export declare const ssrfReqFilter: HttpClient;
+export declare const ssrfAgentClient: HttpClient;

package/dist/adapters/libraries.js

@@ -0,0 +1,47 @@
+import { agentClient } from './agentClient.js';
+import { loadOptional } from './optional.js';
+/**
+ * Third-party npm packages whose stated purpose is to stop SSRF.
+ *
+ * A library that never claimed to block anything is not interesting here.
+ * These 3 do claim it, so a probe that reaches the internal service through
+ * one of them is a finding, not a configuration mistake.
+ *
+ * Each package is loaded on the first request, not at import time, so that
+ * ssrf-lab runs without them. See `optional.ts`.
+ */
+export const requestFilteringAgent = lazyAgentClient('request-filtering-agent (npm)', /not allowed|private|reserved|blocked/i, 'request-filtering-agent', async () => {
+    const { useAgent } = await import('request-filtering-agent');
+    return (url) => useAgent(url);
+});
+export const ssrfReqFilter = lazyAgentClient('ssrf-req-filter (npm)', /not allowed|private|reserved|blocked|call.*blocked/i, 'ssrf-req-filter', async () => {
+    const ssrfFilter = (await import('ssrf-req-filter')).default;
+    return (url) => ssrfFilter(url);
+});
+export const ssrfAgentClient = lazyAgentClient('ssrf-agent (npm)', /not allowed|private|reserved|blocked|forbidden/i, 'ssrf-agent', async () => {
+    const ssrfAgent = (await import('ssrf-agent')).default;
+    return (url) => ssrfAgent(url);
+});
+function lazyAgentClient(name, refusalPattern, packageName, load) {
+    let makeAgent;
+    const client = agentClient({
+        name,
+        refusalPattern,
+        makeAgent: (url) => {
+            if (makeAgent === undefined)
+                throw new Error(`${packageName} was not loaded before the request`);
+            return makeAgent(url);
+        },
+    });
+    return {
+        name: client.name,
+        supportsConnectHook: client.supportsConnectHook,
+        async fetch(url, options) {
+            // Load outside agentClient's error mapping: a missing package must not be
+            // mistaken for the library's own refusal wording.
+            makeAgent ??= await loadOptional(packageName, load);
+            return client.fetch(url, options);
+        },
+    };
+}
+//# sourceMappingURL=libraries.js.map

package/dist/adapters/libraries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"libraries.js","sourceRoot":"","sources":["../../src/adapters/libraries.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAwB,MAAM,eAAe,CAAA;AAGlE;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAe,eAAe,CAC9D,+BAA+B,EAC/B,uCAAuC,EACvC,yBAAyB,EACzB,KAAK,IAAI,EAAE;IACT,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAA;IAC5D,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAU,CAAA;AACxC,CAAC,CACF,CAAA;AAED,MAAM,CAAC,MAAM,aAAa,GAAe,eAAe,CACtD,uBAAuB,EACvB,qDAAqD,EACrD,iBAAiB,EACjB,KAAK,IAAI,EAAE;IACT,MAAM,UAAU,GAAG,CAAC,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,OAAO,CAAA;IAC5D,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAU,CAAA;AAC1C,CAAC,CACF,CAAA;AAED,MAAM,CAAC,MAAM,eAAe,GAAe,eAAe,CACxD,kBAAkB,EAClB,iDAAiD,EACjD,YAAY,EACZ,KAAK,IAAI,EAAE;IACT,MAAM,SAAS,GAAG,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAA;IACtD,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAU,CAAA;AACzC,CAAC,CACF,CAAA;AAID,SAAS,eAAe,CACtB,IAAY,EACZ,cAAsB,EACtB,WAA4B,EAC5B,IAA8B;IAE9B,IAAI,SAAgC,CAAA;IAEpC,MAAM,MAAM,GAAG,WAAW,CAAC;QACzB,IAAI;QACJ,cAAc;QACd,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE;YACjB,IAAI,SAAS,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,GAAG,WAAW,oCAAoC,CAAC,CAAA;YAChG,OAAO,SAAS,CAAC,GAAG,CAAC,CAAA;QACvB,CAAC;KACF,CAAC,CAAA;IAEF,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,KAAK,CAAC,KAAK,CAAC,GAAW,EAAE,OAAuB;YAC9C,0EAA0E;YAC1E,kDAAkD;YAClD,SAAS,KAAK,MAAM,YAAY,CAAC,WAAW,EAAE,IAAI,CAAC,CAAA;YACnD,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QACnC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/adapters/optional.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Packages ssrf-lab compares but does not depend on.
+ *
+ * Installing ssrf-lab must never install a package under test: `ssrf-agent`
+ * pulls in `ip` 1.1.9, which carries CVE-2024-29415, and a security tool that
+ * makes `npm audit` fail for its users has its priorities backwards. These are
+ * devDependencies of this repository and loaded only when a scan selects them.
+ */
+export declare const OPTIONAL_PACKAGES: {
+    readonly 'request-filtering-agent': "3.2.1";
+    readonly 'ssrf-agent': "1.0.5";
+    readonly 'ssrf-req-filter': "1.1.1";
+    readonly 'guarded-fetch': "0.1.5";
+};
+export type OptionalPackage = keyof typeof OPTIONAL_PACKAGES;
+/**
+ * A compared package is not installed.
+ *
+ * The checker lets this error end a scan instead of turning it into a verdict:
+ * a client that never ran has neither blocked nor reached anything.
+ */
+export declare class MissingOptionalPackage extends Error {
+    readonly packages: readonly OptionalPackage[];
+    constructor(packages: readonly OptionalPackage[]);
+}
+/** Load one compared package, or explain how to install it. */
+export declare function loadOptional<T>(name: OptionalPackage, load: () => Promise<T>): Promise<T>;
+/** The compared packages from `names` that cannot be loaded here. */
+export declare function missingOptionalPackages(names: readonly OptionalPackage[]): Promise<OptionalPackage[]>;
+/**
+ * True for Node's "package not found" error about `name` itself.
+ *
+ * Any other failure, including a missing dependency OF that package, is a real
+ * error and must surface as one.
+ */
+export declare function isMissing(error: unknown, name: string): boolean;
+export declare function installHint(packages: readonly OptionalPackage[]): string;

package/dist/adapters/optional.js

@@ -0,0 +1,84 @@
+/**
+ * Packages ssrf-lab compares but does not depend on.
+ *
+ * Installing ssrf-lab must never install a package under test: `ssrf-agent`
+ * pulls in `ip` 1.1.9, which carries CVE-2024-29415, and a security tool that
+ * makes `npm audit` fail for its users has its priorities backwards. These are
+ * devDependencies of this repository and loaded only when a scan selects them.
+ */
+export const OPTIONAL_PACKAGES = {
+    'request-filtering-agent': '3.2.1',
+    'ssrf-agent': '1.0.5',
+    'ssrf-req-filter': '1.1.1',
+    'guarded-fetch': '0.1.5',
+};
+/**
+ * A compared package is not installed.
+ *
+ * The checker lets this error end a scan instead of turning it into a verdict:
+ * a client that never ran has neither blocked nor reached anything.
+ */
+export class MissingOptionalPackage extends Error {
+    packages;
+    constructor(packages) {
+        super(installHint(packages));
+        this.packages = packages;
+        this.name = 'MissingOptionalPackage';
+    }
+}
+/** Load one compared package, or explain how to install it. */
+export async function loadOptional(name, load) {
+    try {
+        return await load();
+    }
+    catch (error) {
+        if (isMissing(error, name))
+            throw new MissingOptionalPackage([name]);
+        throw error;
+    }
+}
+/** The compared packages from `names` that cannot be loaded here. */
+export async function missingOptionalPackages(names) {
+    const missing = [];
+    for (const name of new Set(names)) {
+        try {
+            await import(name);
+        }
+        catch (error) {
+            if (!isMissing(error, name))
+                throw error;
+            missing.push(name);
+        }
+    }
+    return missing;
+}
+/**
+ * True for Node's "package not found" error about `name` itself.
+ *
+ * Any other failure, including a missing dependency OF that package, is a real
+ * error and must surface as one.
+ */
+export function isMissing(error, name) {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code;
+    if (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'MODULE_NOT_FOUND')
+        return false;
+    return error.message.includes(`'${name}'`);
+}
+export function installHint(packages) {
+    const specs = packages.map((name) => `${name}@${OPTIONAL_PACKAGES[name]}`);
+    const npx = specs.map((spec) => `-p ${spec}`).join(' ');
+    return [
+        `Not installed: ${specs.join(', ')}.`,
+        'ssrf-lab compares these packages but does not depend on them, so installing',
+        'ssrf-lab never installs a package under test. Install them beside ssrf-lab:',
+        '',
+        `  npm install --save-dev ${specs.join(' ')}`,
+        '',
+        'or, with npx:',
+        '',
+        `  npx -p ssrf-lab ${npx} ssrf-lab scan ...`,
+    ].join('\n');
+}
+//# sourceMappingURL=optional.js.map

package/dist/adapters/optional.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional.js","sourceRoot":"","sources":["../../src/adapters/optional.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,yBAAyB,EAAE,OAAO;IAClC,YAAY,EAAE,OAAO;IACrB,iBAAiB,EAAE,OAAO;IAC1B,eAAe,EAAE,OAAO;CAChB,CAAA;AAIV;;;;;GAKG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC1B;IAArB,YAAqB,QAAoC;QACvD,KAAK,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAA;QADT,aAAQ,GAAR,QAAQ,CAA4B;QAEvD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAA;IACtC,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,IAAqB,EAAE,IAAsB;IACjF,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,EAAE,CAAA;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC;YAAE,MAAM,IAAI,sBAAsB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;QACpE,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC;AAED,qEAAqE;AACrE,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,KAAiC;IAEjC,MAAM,OAAO,GAAsB,EAAE,CAAA;IACrC,KAAK,MAAM,IAAI,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAA;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC;gBAAE,MAAM,KAAK,CAAA;YACxC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACpB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc,EAAE,IAAY;IACpD,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAC3C,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAA;IAClD,IAAI,IAAI,KAAK,sBAAsB,IAAI,IAAI,KAAK,kBAAkB;QAAE,OAAO,KAAK,CAAA;IAChF,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,GAAG,CAAC,CAAA;AAC5C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,QAAoC;IAC9D,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC1E,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACvD,OAAO;QACL,kBAAkB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QACrC,6EAA6E;QAC7E,6EAA6E;QAC7E,EAAE;QACF,4BAA4B,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;QAC7C,EAAE;QACF,eAAe;QACf,EAAE;QACF,qBAAqB,GAAG,oBAAoB;KAC7C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC"}

package/dist/adapters/plainFetch.d.ts

@@ -0,0 +1,9 @@
+import type { HttpClient } from './types.js';
+/**
+ * Node's built-in `fetch`, with its defaults.
+ *
+ * This is the control case. It follows redirects, resolves names once,
+ * enforces no size cap and exposes no connect hook. The harness applies its
+ * own deadline so a probe cannot hang the run, and reports when it had to.
+ */
+export declare const plainFetch: HttpClient;

package/dist/adapters/plainFetch.js

@@ -0,0 +1,65 @@
+/** How much of the body the harness keeps for canary detection. */
+const SAMPLE_BYTES = 4096;
+/**
+ * Node's built-in `fetch`, with its defaults.
+ *
+ * This is the control case. It follows redirects, resolves names once,
+ * enforces no size cap and exposes no connect hook. The harness applies its
+ * own deadline so a probe cannot hang the run, and reports when it had to.
+ */
+export const plainFetch = {
+    name: 'node-fetch (global, defaults)',
+    supportsConnectHook: false,
+    async fetch(url, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 6000;
+        const controller = new AbortController();
+        const deadline = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(url, { redirect: 'follow', signal: controller.signal });
+            const { bytesRead, sample, stoppedByHarness } = await drain(response, controller.signal);
+            return {
+                status: response.status,
+                bytesRead,
+                bodySample: sample,
+                // Built-in fetch follows redirects inside itself, so the hops it took
+                // are not observable from here. That opacity is the finding.
+                hops: [url],
+                stoppedByHarness,
+            };
+        }
+        finally {
+            clearTimeout(deadline);
+        }
+    },
+};
+async function drain(response, signal) {
+    if (response.body === null)
+        return { bytesRead: 0, sample: '', stoppedByHarness: false };
+    const reader = response.body.getReader();
+    const sample = [];
+    let sampleBytes = 0;
+    let bytesRead = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytesRead += value.byteLength;
+            if (sampleBytes < SAMPLE_BYTES) {
+                sample.push(value.subarray(0, SAMPLE_BYTES - sampleBytes));
+                sampleBytes += Math.min(value.byteLength, SAMPLE_BYTES - sampleBytes);
+            }
+        }
+    }
+    catch (error) {
+        if (signal.aborted) {
+            return { bytesRead, sample: decode(sample), stoppedByHarness: true };
+        }
+        throw error;
+    }
+    return { bytesRead, sample: decode(sample), stoppedByHarness: false };
+}
+function decode(chunks) {
+    return Buffer.concat(chunks).toString('utf8');
+}
+//# sourceMappingURL=plainFetch.js.map

package/dist/adapters/plainFetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plainFetch.js","sourceRoot":"","sources":["../../src/adapters/plainFetch.ts"],"names":[],"mappings":"AAEA,mEAAmE;AACnE,MAAM,YAAY,GAAG,IAAI,CAAA;AAEzB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAe;IACpC,IAAI,EAAE,+BAA+B;IACrC,mBAAmB,EAAE,KAAK;IAE1B,KAAK,CAAC,KAAK,CAAC,GAAW,EAAE,UAAyB,EAAE;QAClD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAA;QAC3C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QACxC,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAA;QAEhE,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAA;YACpF,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,CAAA;YAExF,OAAO;gBACL,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,SAAS;gBACT,UAAU,EAAE,MAAM;gBAClB,sEAAsE;gBACtE,6DAA6D;gBAC7D,IAAI,EAAE,CAAC,GAAG,CAAC;gBACX,gBAAgB;aACjB,CAAA;QACH,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,QAAQ,CAAC,CAAA;QACxB,CAAC;IACH,CAAC;CACF,CAAA;AAED,KAAK,UAAU,KAAK,CAClB,QAAkB,EAClB,MAAmB;IAEnB,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAA;IAExF,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAA;IACxC,MAAM,MAAM,GAAiB,EAAE,CAAA;IAC/B,IAAI,WAAW,GAAG,CAAC,CAAA;IACnB,IAAI,SAAS,GAAG,CAAC,CAAA;IAEjB,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;YAC3C,IAAI,IAAI;gBAAE,MAAK;YACf,SAAS,IAAI,KAAK,CAAC,UAAU,CAAA;YAC7B,IAAI,WAAW,GAAG,YAAY,EAAE,CAAC;gBAC/B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC,CAAC,CAAA;gBAC1D,WAAW,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,YAAY,GAAG,WAAW,CAAC,CAAA;YACvE,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAA;QACtE,CAAC;QACD,MAAM,KAAK,CAAA;IACb,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAA;AACvE,CAAC;AAED,SAAS,MAAM,CAAC,MAAoB;IAClC,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;AAC/C,CAAC"}

package/dist/adapters/types.d.ts

@@ -0,0 +1,55 @@
+import type { LookupFunction } from 'node:net';
+/** Why a client refused a request. Each reason names the control that fired. */
+export type RefusalReason = 'forbidden-address' | 'too-many-redirects' | 'redirect-not-allowed' | 'body-too-large' | 'deadline' | 'scheme-not-allowed';
+/**
+ * A refusal the CLIENT decided on.
+ *
+ * This is the type that separates a control from luck. A connection error is
+ * not one of these, however convenient its timing.
+ */
+export declare class PolicyRefusal extends Error {
+    readonly reason: RefusalReason;
+    readonly detail: string;
+    constructor(reason: RefusalReason, detail: string);
+}
+export interface FetchOutcome {
+    status: number;
+    /** Bytes of body the client accepted, after any decompression. */
+    bytesRead: number;
+    /** First bytes of the body, kept so the checker can look for a canary. */
+    bodySample: string;
+    /** Observed URLs in order. Opaque clients may expose only entry and final URLs. */
+    hops: string[];
+    /** True when the harness stopped the read because the client would not. */
+    stoppedByHarness: boolean;
+}
+export interface ClientOptions {
+    /**
+     * Replaces name resolution for this request.
+     *
+     * A probe uses this to answer a public address to the check and a loopback
+     * address to the socket, which is DNS rebinding in one process.
+     */
+    lookup?: LookupFunction;
+    timeoutMs?: number;
+    maxBytes?: number;
+    /**
+     * One origin that is treated as the public internet for the FIRST hop only.
+     *
+     * The range lives on loopback, so without this a guard refuses the range
+     * itself and every probe passes while testing nothing. Redirect targets are
+     * never covered by it. A production fetcher has no such option.
+     */
+    trustedOrigin?: string;
+}
+export interface HttpClient {
+    readonly name: string;
+    /**
+     * Whether the adapter can exercise this lab's injected-resolver probe.
+     * False does not mean the underlying client lacks its own DNS protection.
+     */
+    readonly supportsConnectHook: boolean;
+    /** False when the adapter cannot exempt the lab's loopback entry origin. */
+    readonly supportsLoopbackOrigin?: boolean;
+    fetch(url: string, options?: ClientOptions): Promise<FetchOutcome>;
+}

package/dist/adapters/types.js

@@ -0,0 +1,17 @@
+/**
+ * A refusal the CLIENT decided on.
+ *
+ * This is the type that separates a control from luck. A connection error is
+ * not one of these, however convenient its timing.
+ */
+export class PolicyRefusal extends Error {
+    reason;
+    detail;
+    constructor(reason, detail) {
+        super(`${reason}: ${detail}`);
+        this.reason = reason;
+        this.detail = detail;
+        this.name = 'PolicyRefusal';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/adapters/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAWA;;;;;GAKG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAE3B;IACA;IAFX,YACW,MAAqB,EACrB,MAAc;QAEvB,KAAK,CAAC,GAAG,MAAM,KAAK,MAAM,EAAE,CAAC,CAAA;QAHpB,WAAM,GAAN,MAAM,CAAe;QACrB,WAAM,GAAN,MAAM,CAAQ;QAGvB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAA;IAC7B,CAAC;CACF"}

package/dist/adapters/vercelGuardedFetch.d.ts

@@ -0,0 +1,7 @@
+import { type HttpClient } from './types.js';
+/**
+ * Use the package's real dispatcher and exported bounded body reader.
+ *
+ * The package is loaded on the first request, so ssrf-lab runs without it.
+ */
+export declare const vercelGuardedFetch: HttpClient;