@uncefact/untp-utils 0.1.0 → 0.2.0

package/build/resolvers/resolve-document.d.ts

@@ -0,0 +1,86 @@
+import { MultibaseDigest } from '../multibase-digest/index.js';
+/**
+ * Defaults applied by {@link resolveDocument} (and, via composition,
+ * by {@link import('./resolve-document-if-changed.js').resolveDocumentIfChanged})
+ * when the caller does not supply a value.
+ */
+export declare const RESOLVER_DEFAULTS: {
+    /** Body-size cap in bytes; exceeding throws {@link ResolverTooLargeError}. */
+    readonly maxResponseBytes: 1048576;
+    /** Total request timeout in milliseconds (DNS + connect + TLS + first byte + body). */
+    readonly totalTimeoutMs: 10000;
+    /** Maximum additional hops after the initial request; exceeding throws {@link ResolverTooManyRedirectsError}. */
+    readonly maxRedirects: 3;
+    /** Multibase digest algorithm used to hash response bodies. */
+    readonly digestAlgorithm: "sha2-256";
+    /** Multibase encoding used for response body digests. */
+    readonly digestEncoding: "base58btc";
+};
+/**
+ * Result of a fetch that produced a final response (any non-redirect status,
+ * including `304 Not Modified`).
+ *
+ * Only an allowlisted subset of response headers is exposed (the ones
+ * downstream consumers need: `etag` and `last-modified` for the conditional-
+ * fetch skip chain, `content-type` for body-type checks).
+ *
+ * All fields are `readonly`: a `LoadResult` is a frozen snapshot of one
+ * fetch and must not be mutated by consumers.
+ */
+export interface LoadResult {
+    /** Final URL after redirect chasing (matches `url` when there were no redirects). */
+    readonly finalUrl: string;
+    /** HTTP status code of the final response (the redirect chain terminator, or `304`). */
+    readonly status: number;
+    /** Raw response body bytes. */
+    readonly body: Uint8Array;
+    /** Multibase digest of {@link body} (algorithm/encoding per {@link RESOLVER_DEFAULTS}). */
+    readonly bodyDigest: MultibaseDigest;
+    /** The response's `ETag` header if present. */
+    readonly etag?: string;
+    /** The response's `Last-Modified` header if present. */
+    readonly lastModified?: string;
+    /** The response's `Content-Type` header if present. */
+    readonly contentType?: string;
+}
+/**
+ * Options accepted by {@link resolveDocument} and
+ * {@link import('./resolve-document-if-changed.js').resolveDocumentIfChanged}.
+ *
+ * Header keys are case-insensitive on the wire; `resolveDocumentIfChanged`
+ * lowercases all keys before merging and reserves `if-none-match` /
+ * `if-modified-since` for its conditional-fetch wiring.
+ */
+export interface ResolveDocumentOptions {
+    /** Override {@link RESOLVER_DEFAULTS.maxResponseBytes}. */
+    maxResponseBytes?: number;
+    /** Override {@link RESOLVER_DEFAULTS.totalTimeoutMs}. */
+    totalTimeoutMs?: number;
+    /** Override {@link RESOLVER_DEFAULTS.maxRedirects}. */
+    maxRedirects?: number;
+    /** Additional headers to send with the request (e.g. `Accept`). */
+    headers?: Record<string, string>;
+    /** Allowed URL schemes (forwarded to {@link import('../node/index.js').validatePublicUrl}). */
+    allowedSchemes?: readonly string[];
+}
+/**
+ * Fetches `url` with the standard SSRF / size / timeout / redirect guards
+ * applied, returning the response body + metadata as a {@link LoadResult}.
+ *
+ * Each redirect hop is re-validated through
+ * {@link import('../node/index.js').validatePublicUrl}, and the connection
+ * to each hop is pinned to the IP that validation resolved, so an upstream
+ * cannot redirect to a private URL or rebind its hostname between check
+ * and connect.
+ *
+ * @throws {UrlValidationError} for URL / scheme / hostname / DNS / private-address rejections from `validatePublicUrl`.
+ * @throws {ResolverNetworkError} when fetch rejects before producing a response.
+ * @throws {ResolverHttpError} on a non-2xx response status (with `.status`).
+ * @throws {ResolverTooLargeError} when the body exceeds the size cap (with `.limit`).
+ * @throws {ResolverTooManyRedirectsError} when the redirect chain exceeds the hop cap (with `.limit`).
+ * @throws {ResolverTimedOutError} when the total timeout fires (with `.timeoutMs`).
+ * @throws {ResolverRedirectMissingLocationError} for a 3xx with no / unparseable Location header.
+ *
+ * @see https://owasp.org/www-community/attacks/Server_Side_Request_Forgery
+ */
+export declare function resolveDocument(url: string, options?: ResolveDocumentOptions): Promise<LoadResult>;

package/build/resolvers/resolve-document.js

@@ -0,0 +1,239 @@
+import { parseEntityTag, parseImfDate, parseMediaType, DEFAULT_USER_AGENT, USER_AGENT_ENV_VAR, } from '../http-headers/index.js';
+import { MultibaseDigest } from '../multibase-digest/index.js';
+import { validatePublicUrl } from '../node/index.js';
+import { ResolverHttpError, ResolverNetworkError, ResolverRedirectMissingLocationError, ResolverTimedOutError, ResolverTooLargeError, ResolverTooManyRedirectsError, } from './errors.js';
+/**
+ * Defaults applied by {@link resolveDocument} (and, via composition,
+ * by {@link import('./resolve-document-if-changed.js').resolveDocumentIfChanged})
+ * when the caller does not supply a value.
+ */
+export const RESOLVER_DEFAULTS = {
+    /** Body-size cap in bytes; exceeding throws {@link ResolverTooLargeError}. */
+    maxResponseBytes: 1_048_576,
+    /** Total request timeout in milliseconds (DNS + connect + TLS + first byte + body). */
+    totalTimeoutMs: 10_000,
+    /** Maximum additional hops after the initial request; exceeding throws {@link ResolverTooManyRedirectsError}. */
+    maxRedirects: 3,
+    /** Multibase digest algorithm used to hash response bodies. */
+    digestAlgorithm: 'sha2-256',
+    /** Multibase encoding used for response body digests. */
+    digestEncoding: 'base58btc',
+};
+/**
+ * Merges the resolved `User-Agent` into the caller's headers. A caller-supplied
+ * `user-agent` (any casing) wins; otherwise the `RI_HTTP_USER_AGENT` env
+ * override (blank treated as unset), then the default. The override is not
+ * validated here: deployments validate it at boot via
+ * {@link isValidHttpUserAgent} (the RI does, in instrumentation.node.ts),
+ * and a value that slips through with control characters makes the fetch
+ * itself fail loudly rather than being silently replaced.
+ */
+function withUserAgent(headers) {
+    const hasExplicit = Object.keys(headers ?? {}).some((key) => key.toLowerCase() === 'user-agent');
+    if (hasExplicit)
+        return headers;
+    const fromEnv = process.env[USER_AGENT_ENV_VAR];
+    const userAgent = fromEnv !== undefined && fromEnv.trim() !== '' ? fromEnv : DEFAULT_USER_AGENT;
+    return { ...headers, 'User-Agent': userAgent };
+}
+/**
+ * Fetches `url` with the standard SSRF / size / timeout / redirect guards
+ * applied, returning the response body + metadata as a {@link LoadResult}.
+ *
+ * Each redirect hop is re-validated through
+ * {@link import('../node/index.js').validatePublicUrl}, and the connection
+ * to each hop is pinned to the IP that validation resolved, so an upstream
+ * cannot redirect to a private URL or rebind its hostname between check
+ * and connect.
+ *
+ * @throws {UrlValidationError} for URL / scheme / hostname / DNS / private-address rejections from `validatePublicUrl`.
+ * @throws {ResolverNetworkError} when fetch rejects before producing a response.
+ * @throws {ResolverHttpError} on a non-2xx response status (with `.status`).
+ * @throws {ResolverTooLargeError} when the body exceeds the size cap (with `.limit`).
+ * @throws {ResolverTooManyRedirectsError} when the redirect chain exceeds the hop cap (with `.limit`).
+ * @throws {ResolverTimedOutError} when the total timeout fires (with `.timeoutMs`).
+ * @throws {ResolverRedirectMissingLocationError} for a 3xx with no / unparseable Location header.
+ *
+ * @see https://owasp.org/www-community/attacks/Server_Side_Request_Forgery
+ */
+export async function resolveDocument(url, options) {
+    // Dynamic import: undici's module initialisation needs web globals
+    // (TextDecoder) that jsdom test environments lack, so it loads at fetch
+    // time to keep this module, and the resolvers barrel, importable there.
+    // Same pattern as validate-jsonld.ts's lazy jsonld import.
+    const { Agent, fetch: undiciFetch } = await import('undici');
+    const maxBytes = options?.maxResponseBytes ?? RESOLVER_DEFAULTS.maxResponseBytes;
+    const totalTimeoutMs = options?.totalTimeoutMs ?? RESOLVER_DEFAULTS.totalTimeoutMs;
+    const maxRedirects = options?.maxRedirects ?? RESOLVER_DEFAULTS.maxRedirects;
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), totalTimeoutMs);
+    try {
+        let currentUrl = url;
+        for (let hop = 0; hop <= maxRedirects; hop += 1) {
+            const { address: pinnedAddress, family: pinnedFamily } = await validatePublicUrl(currentUrl, {
+                allowedSchemes: options?.allowedSchemes,
+            });
+            const dispatcher = new Agent({
+                connect: {
+                    // undici resolves the connect target with `all: true` to support
+                    // happy-eyeballs; the callback receives a `LookupAddress[]`.
+                    // Return a single-entry array containing the IP we pinned via
+                    // `validatePublicUrl`, so the connection target is exactly the
+                    // address that the SSRF check validated.
+                    lookup: (_hostname, _opts, cb) => cb(null, [{ address: pinnedAddress, family: pinnedFamily }]),
+                },
+            });
+            // The entire request lifecycle (fetch + status-check + body read +
+            // digest) sits inside one try/finally with the dispatcher close:
+            // `undici.Agent.close()` waits for active requests to drain, and a
+            // request is "drained" only once its body has been consumed. Closing
+            // before `readWithLimit` deadlocks the close on the unconsumed body.
+            try {
+                const response = await undiciFetch(currentUrl, {
+                    method: 'GET',
+                    redirect: 'manual',
+                    signal: controller.signal,
+                    headers: withUserAgent(options?.headers),
+                    dispatcher,
+                });
+                // 304 Not Modified: body is intentionally empty; the caller maps it
+                // to `unchanged` in `resolveDocumentIfChanged`.
+                if (response.status === 304) {
+                    const headerView = extractHeaders(response.headers);
+                    const empty = new Uint8Array(0);
+                    const bodyDigest = await computeDigest(empty);
+                    return {
+                        finalUrl: currentUrl,
+                        status: 304,
+                        body: empty,
+                        bodyDigest,
+                        etag: headerView.etag,
+                        lastModified: headerView.lastModified,
+                        contentType: headerView.contentType,
+                    };
+                }
+                if (response.status >= 300 && response.status < 400) {
+                    const location = response.headers.get('location');
+                    if (!location) {
+                        throw new ResolverRedirectMissingLocationError(currentUrl, response.status);
+                    }
+                    let nextUrl;
+                    try {
+                        nextUrl = new URL(location, currentUrl).toString();
+                    }
+                    catch (cause) {
+                        throw new ResolverRedirectMissingLocationError(currentUrl, location, cause);
+                    }
+                    // Cancel the 3xx body so `dispatcher.close()` in `finally` can
+                    // proceed without waiting for body drain.
+                    if (response.body)
+                        await response.body.cancel().catch(() => undefined);
+                    currentUrl = nextUrl;
+                    continue;
+                }
+                if (!response.ok) {
+                    if (response.body)
+                        await response.body.cancel().catch(() => undefined);
+                    throw new ResolverHttpError(currentUrl, response.status);
+                }
+                const body = await readWithLimit(response, maxBytes, currentUrl, totalTimeoutMs);
+                const bodyDigest = await computeDigest(body);
+                const headerView = extractHeaders(response.headers);
+                return {
+                    finalUrl: currentUrl,
+                    status: response.status,
+                    body,
+                    bodyDigest,
+                    etag: headerView.etag,
+                    lastModified: headerView.lastModified,
+                    contentType: headerView.contentType,
+                };
+            }
+            finally {
+                await dispatcher.close().catch(() => undefined);
+            }
+        }
+        throw new ResolverTooManyRedirectsError(url, maxRedirects);
+    }
+    catch (cause) {
+        if (cause instanceof Error && cause.code?.startsWith('resolver.')) {
+            throw cause;
+        }
+        // Re-throw UrlValidationErrors and other StructuredErrors unwrapped.
+        if (cause instanceof Error &&
+            typeof cause.code === 'string' &&
+            (cause.code.startsWith('url.') ||
+                cause.code.startsWith('resolver.'))) {
+            throw cause;
+        }
+        if (isAbortLikeError(cause)) {
+            throw new ResolverTimedOutError(url, totalTimeoutMs, cause);
+        }
+        throw new ResolverNetworkError(url, cause);
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+}
+function isAbortLikeError(error) {
+    return error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError');
+}
+function extractHeaders(headers) {
+    const view = {};
+    const etag = parseEntityTag(headers.get('etag') ?? '');
+    if (etag !== undefined)
+        view.etag = etag;
+    const lastModified = parseImfDate(headers.get('last-modified') ?? '');
+    if (lastModified !== undefined)
+        view.lastModified = lastModified;
+    const contentType = parseMediaType(headers.get('content-type') ?? '');
+    if (contentType !== undefined)
+        view.contentType = contentType;
+    return view;
+}
+async function computeDigest(body) {
+    return MultibaseDigest.fromData(body, {
+        algorithm: RESOLVER_DEFAULTS.digestAlgorithm,
+        base: RESOLVER_DEFAULTS.digestEncoding,
+    });
+}
+async function readWithLimit(response, limit, url, totalTimeoutMs) {
+    if (!response.body)
+        return new Uint8Array(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > limit) {
+                await reader.cancel().catch(() => undefined);
+                throw new ResolverTooLargeError(url, limit);
+            }
+            chunks.push(value);
+        }
+    }
+    catch (error) {
+        // Release the reader so the upstream socket can be recycled.
+        await reader.cancel().catch(() => undefined);
+        if (error instanceof ResolverTooLargeError)
+            throw error;
+        if (isAbortLikeError(error))
+            throw new ResolverTimedOutError(url, totalTimeoutMs, error);
+        throw new ResolverNetworkError(url, error);
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return merged;
+}
+//# sourceMappingURL=resolve-document.js.map

package/build/resolvers/resolve-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-document.js","sourceRoot":"","sources":["../../src/resolvers/resolve-document.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,eAAe,EAA8C,MAAM,8BAA8B,CAAC;AAC3G,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,oCAAoC,EACpC,qBAAqB,EACrB,qBAAqB,EACrB,6BAA6B,GAC9B,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,8EAA8E;IAC9E,gBAAgB,EAAE,SAAS;IAC3B,uFAAuF;IACvF,cAAc,EAAE,MAAM;IACtB,iHAAiH;IACjH,YAAY,EAAE,CAAC;IACf,+DAA+D;IAC/D,eAAe,EAAE,UAAU;IAC3B,yDAAyD;IACzD,cAAc,EAAE,WAAW;CAO5B,CAAC;AAEF;;;;;;;;GAQG;AACH,SAAS,aAAa,CAAC,OAA2C;IAChE,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,YAAY,CAAC,CAAC;IACjG,IAAI,WAAW;QAAE,OAAO,OAAiC,CAAC;IAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC;IAChG,OAAO,EAAE,GAAG,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;AACjD,CAAC;AAmDD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAW,EAAE,OAAgC;IACjF,mEAAmE;IACnE,wEAAwE;IACxE,wEAAwE;IACxE,2DAA2D;IAC3D,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,OAAO,EAAE,gBAAgB,IAAI,iBAAiB,CAAC,gBAAgB,CAAC;IACjF,MAAM,cAAc,GAAG,OAAO,EAAE,cAAc,IAAI,iBAAiB,CAAC,cAAc,CAAC;IACnF,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,iBAAiB,CAAC,YAAY,CAAC;IAE7E,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,aAAa,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,cAAc,CAAC,CAAC;IAE3E,IAAI,CAAC;QACH,IAAI,UAAU,GAAG,GAAG,CAAC;QACrB,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,IAAI,YAAY,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;YAChD,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,iBAAiB,CAAC,UAAU,EAAE;gBAC3F,cAAc,EAAE,OAAO,EAAE,cAAc;aACxC,CAAC,CAAC;YAEH,MAAM,UAAU,GAAG,IAAI,KAAK,CAAC;gBAC3B,OAAO,EAAE;oBACP,iEAAiE;oBACjE,6DAA6D;oBAC7D,8DAA8D;oBAC9D,+DAA+D;oBAC/D,yCAAyC;oBACzC,MAAM,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;iBAC/F;aACF,CAAC,CAAC;YAEH,mEAAmE;YACnE,iEAAiE;YACjE,mEAAmE;YACnE,qEAAqE;YACrE,qEAAqE;YACrE,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,UAAU,EAAE;oBAC7C,MAAM,EAAE,KAAK;oBACb,QAAQ,EAAE,QAAQ;oBAClB,MAAM,EAAE,UAAU,CAAC,MAAM;oBACzB,OAAO,EAAE,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC;oBACxC,UAAU;iBACX,CAAC,CAAC;gBAEH,oEAAoE;gBACpE,gDAAgD;gBAChD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;oBAC5B,MAAM,UAAU,GAAG,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;oBACpD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;oBAChC,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,KAAK,CAAC,CAAC;oBAC9C,OAAO;wBACL,QAAQ,EAAE,UAAU;wBACpB,MAAM,EAAE,GAAG;wBACX,IAAI,EAAE,KAAK;wBACX,UAAU;wBACV,IAAI,EAAE,UAAU,CAAC,IAAI;wBACrB,YAAY,EAAE,UAAU,CAAC,YAAY;wBACrC,WAAW,EAAE,UAAU,CAAC,WAAW;qBACpC,CAAC;gBACJ,CAAC;gBAED,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;oBACpD,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;oBAClD,IAAI,CAAC,QAAQ,EAAE,CAAC;wBACd,MAAM,IAAI,oCAAoC,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;oBAC9E,CAAC;oBACD,IAAI,OAAe,CAAC;oBACpB,IAAI,CAAC;wBACH,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,QAAQ,EAAE,CAAC;oBACrD,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,MAAM,IAAI,oCAAoC,CAAC,UAAU,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;oBAC9E,CAAC;oBACD,+DAA+D;oBAC/D,0CAA0C;oBAC1C,IAAI,QAAQ,CAAC,IAAI;wBAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;oBACvE,UAAU,GAAG,OAAO,CAAC;oBACrB,SAAS;gBACX,CAAC;gBAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;oBACjB,IAAI,QAAQ,CAAC,IAAI;wBAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;oBACvE,MAAM,IAAI,iBAAiB,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;gBAC3D,CAAC;gBAED,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,CAAC,CAAC;gBACjF,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;gBAC7C,MAAM,UAAU,GAAG,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;gBACpD,OAAO;oBACL,QAAQ,EAAE,UAAU;oBACpB,MAAM,EAAE,QAAQ,CAAC,MAAM;oBACvB,IAAI;oBACJ,UAAU;oBACV,IAAI,EAAE,UAAU,CAAC,IAAI;oBACrB,YAAY,EAAE,UAAU,CAAC,YAAY;oBACrC,WAAW,EAAE,UAAU,CAAC,WAAW;iBACpC,CAAC;YACJ,CAAC;oBAAS,CAAC;gBACT,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAClD,CAAC;QACH,CAAC;QAED,MAAM,IAAI,6BAA6B,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,IAAK,KAAmC,CAAC,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACjG,MAAM,KAAK,CAAC;QACd,CAAC;QACD,qEAAqE;QACrE,IACE,KAAK,YAAY,KAAK;YACtB,OAAQ,KAAoC,CAAC,IAAI,KAAK,QAAQ;YAC9D,CAAE,KAAkC,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;gBACzD,KAAkC,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,EACnE,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,qBAAqB,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,IAAI,oBAAoB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,aAAa,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,KAAK,YAAY,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC;AAClG,CAAC;AAQD,SAAS,cAAc,CAAC,OAAgB;IACtC,MAAM,IAAI,GAAe,EAAE,CAAC;IAC5B,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACvD,IAAI,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACzC,MAAM,YAAY,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC;IACtE,IAAI,YAAY,KAAK,SAAS;QAAE,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACjE,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC;IACtE,IAAI,WAAW,KAAK,SAAS;QAAE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IAC9D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,IAAgB;IAC3C,OAAO,eAAe,CAAC,QAAQ,CAAC,IAAI,EAAE;QACpC,SAAS,EAAE,iBAAiB,CAAC,eAAe;QAC5C,IAAI,EAAE,iBAAiB,CAAC,cAAc;KACvC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,QAAqD,EACrD,KAAa,EACb,GAAW,EACX,cAAsB;IAEtB,IAAI,CAAC,QAAQ,CAAC,IAAI;QAAE,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAE7C,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;IACzC,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,IAAI,CAAC;QACH,iDAAiD;QACjD,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,KAAK,IAAI,KAAK,CAAC,UAAU,CAAC;YAC1B,IAAI,KAAK,GAAG,KAAK,EAAE,CAAC;gBAClB,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;gBAC7C,MAAM,IAAI,qBAAqB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC9C,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,6DAA6D;QAC7D,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,KAAK,YAAY,qBAAqB;YAAE,MAAM,KAAK,CAAC;QACxD,IAAI,gBAAgB,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,qBAAqB,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;QACzF,MAAM,IAAI,oBAAoB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC;IAC7B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/build/resolvers/resolve-document.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/resolvers/resolve-document.test.js

@@ -0,0 +1,299 @@
+import { jest } from '@jest/globals';
+import { ReadableStream } from 'node:stream/web';
+import { PrivateAddressError } from '../node/index.js';
+import { ResolverHttpError, ResolverNetworkError, ResolverRedirectMissingLocationError, ResolverTimedOutError, ResolverTooLargeError, ResolverTooManyRedirectsError, } from './errors.js';
+const undiciFetch = jest.fn();
+let lastAgentClose = jest.fn(() => Promise.resolve());
+class FakeAgent {
+    close;
+    constructor() {
+        this.close = jest.fn(() => Promise.resolve());
+        lastAgentClose = this.close;
+    }
+}
+jest.unstable_mockModule('undici', () => ({
+    Agent: FakeAgent,
+    fetch: undiciFetch,
+}));
+const validatePublicUrl = jest.fn();
+jest.unstable_mockModule('../node/index.js', () => ({
+    validatePublicUrl,
+    PrivateAddressError,
+}));
+const { resolveDocument } = await import('./resolve-document.js');
+const { DEFAULT_USER_AGENT, USER_AGENT_ENV_VAR } = await import('../http-headers/index.js');
+function makeResponse(opts) {
+    const status = opts.status ?? 200;
+    const headers = new Headers(opts.headers ?? {});
+    let bodyStream;
+    if (opts.body === null || opts.body === undefined) {
+        bodyStream = null;
+    }
+    else {
+        const bytes = typeof opts.body === 'string' ? new TextEncoder().encode(opts.body) : opts.body;
+        bodyStream = new ReadableStream({
+            start(controller) {
+                controller.enqueue(bytes);
+                controller.close();
+            },
+        });
+    }
+    return {
+        status,
+        ok: opts.ok ?? (status >= 200 && status < 300),
+        headers,
+        body: bodyStream,
+    };
+}
+function resolvedAddress(address = '1.1.1.1', family = 4) {
+    return { address, family };
+}
+describe('resolveDocument', () => {
+    beforeEach(() => {
+        undiciFetch.mockReset();
+        validatePublicUrl.mockReset();
+    });
+    describe('SSRF guard', () => {
+        it('propagates validatePublicUrl errors unwrapped and never calls fetch', async () => {
+            validatePublicUrl.mockRejectedValue(new PrivateAddressError('https://attacker.example/', ['10.0.0.1']));
+            await expect(resolveDocument('https://attacker.example/')).rejects.toBeInstanceOf(PrivateAddressError);
+            expect(undiciFetch).not.toHaveBeenCalled();
+        });
+    });
+    describe('happy path', () => {
+        it('returns a LoadResult with body, digest, and the allowlisted headers', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({
+                body: '{"hello":"world"}',
+                headers: {
+                    'content-type': 'application/json',
+                    etag: '"abc"',
+                    'last-modified': 'Wed, 21 May 2026 12:00:00 GMT',
+                    'set-cookie': 'session=secret', // must NOT appear on the LoadResult
+                    'x-internal-trace': 'noisy', // ditto
+                },
+            }));
+            const result = await resolveDocument('https://example.com/doc.json');
+            expect(result.status).toBe(200);
+            expect(result.finalUrl).toBe('https://example.com/doc.json');
+            expect(result.etag).toBe('"abc"');
+            expect(result.lastModified).toBe('Wed, 21 May 2026 12:00:00 GMT');
+            expect(result.contentType).toBe('application/json');
+            expect(new TextDecoder().decode(result.body)).toBe('{"hello":"world"}');
+            expect(result.bodyDigest.toString()).toMatch(/^z[1-9A-HJ-NP-Za-km-z]+$/); // multibase base58btc
+            // Arbitrary upstream headers must NOT be echoed onto the LoadResult.
+            const valueAsRecord = result;
+            expect(valueAsRecord['set-cookie']).toBeUndefined();
+            expect(valueAsRecord['x-internal-trace']).toBeUndefined();
+        });
+    });
+    describe('HTTP errors', () => {
+        it('throws ResolverHttpError for a 4xx response with status attached', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({ status: 404, ok: false, body: 'not found' }));
+            const error = (await resolveDocument('https://example.com/missing').catch((e) => e));
+            expect(error).toBeInstanceOf(ResolverHttpError);
+            expect(error.status).toBe(404);
+        });
+        it('throws ResolverHttpError for a 5xx response', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({ status: 503, ok: false, body: 'busy' }));
+            const error = (await resolveDocument('https://example.com/busy').catch((e) => e));
+            expect(error).toBeInstanceOf(ResolverHttpError);
+            expect(error.status).toBe(503);
+        });
+    });
+    describe('network errors and timeouts', () => {
+        it('throws ResolverNetworkError on fetch rejection', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockRejectedValue(new Error('ECONNREFUSED'));
+            const error = (await resolveDocument('https://example.com/').catch((e) => e));
+            expect(error).toBeInstanceOf(ResolverNetworkError);
+            expect(error.cause).toBeInstanceOf(Error);
+        });
+        it('throws ResolverTimedOutError when the fetch is aborted', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            const abort = new Error('aborted');
+            abort.name = 'AbortError';
+            undiciFetch.mockRejectedValue(abort);
+            await expect(resolveDocument('https://example.com/')).rejects.toBeInstanceOf(ResolverTimedOutError);
+        });
+        it('throws ResolverNetworkError when the response body stream rejects mid-read', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            const erroringStream = new ReadableStream({
+                pull(controller) {
+                    controller.error(new Error('connection reset by peer'));
+                },
+            });
+            undiciFetch.mockResolvedValue({
+                status: 200,
+                ok: true,
+                headers: new Headers(),
+                body: erroringStream,
+            });
+            await expect(resolveDocument('https://example.com/')).rejects.toBeInstanceOf(ResolverNetworkError);
+        });
+    });
+    describe('size limit', () => {
+        it('throws ResolverTooLargeError with limit attached when the body exceeds maxResponseBytes', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            const big = new Uint8Array(2048);
+            undiciFetch.mockResolvedValue(makeResponse({ body: big }));
+            const error = (await resolveDocument('https://example.com/big', { maxResponseBytes: 1024 }).catch((e) => e));
+            expect(error).toBeInstanceOf(ResolverTooLargeError);
+            expect(error.limit).toBe(1024);
+        });
+    });
+    describe('redirects', () => {
+        it('follows a redirect chain within the cap', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch
+                .mockResolvedValueOnce(makeResponse({ status: 301, headers: { location: 'https://example.com/next' }, body: null }))
+                .mockResolvedValueOnce(makeResponse({ body: 'final' }));
+            const result = await resolveDocument('https://example.com/start');
+            expect(result.finalUrl).toBe('https://example.com/next');
+            expect(new TextDecoder().decode(result.body)).toBe('final');
+            expect(undiciFetch).toHaveBeenCalledTimes(2);
+        });
+        it('re-validates each redirect target through validatePublicUrl', async () => {
+            validatePublicUrl
+                .mockResolvedValueOnce(resolvedAddress('1.1.1.1'))
+                .mockRejectedValueOnce(new PrivateAddressError('https://internal.example/', ['10.0.0.1']));
+            undiciFetch.mockResolvedValueOnce(makeResponse({ status: 301, headers: { location: 'https://internal.example/' }, body: null }));
+            await expect(resolveDocument('https://public.example/')).rejects.toBeInstanceOf(PrivateAddressError);
+            expect(validatePublicUrl).toHaveBeenCalledTimes(2);
+            // Second hop's URL must be the Location target, not the original.
+            expect(validatePublicUrl).toHaveBeenNthCalledWith(2, 'https://internal.example/', expect.anything());
+            expect(undiciFetch).toHaveBeenCalledTimes(1);
+        });
+        it('throws ResolverRedirectMissingLocationError when Location is not a parseable URL', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            const malformed = 'http://[';
+            undiciFetch.mockResolvedValue(makeResponse({ status: 301, headers: { location: malformed }, body: null }));
+            const error = (await resolveDocument('https://example.com/').catch((e) => e));
+            expect(error).toBeInstanceOf(ResolverRedirectMissingLocationError);
+            expect(error.received).toBe(malformed);
+        });
+        it('throws ResolverTooManyRedirectsError with limit attached when the chain exceeds the cap', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({ status: 301, headers: { location: 'https://example.com/loop' }, body: null }));
+            const error = (await resolveDocument('https://example.com/start', { maxRedirects: 1 }).catch((e) => e));
+            expect(error).toBeInstanceOf(ResolverTooManyRedirectsError);
+            expect(error.limit).toBe(1);
+        });
+        it('throws ResolverRedirectMissingLocationError when a 3xx has no Location', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({ status: 302, body: null }));
+            await expect(resolveDocument('https://example.com/')).rejects.toBeInstanceOf(ResolverRedirectMissingLocationError);
+        });
+    });
+    describe('dispatcher lifecycle', () => {
+        it('closes the dispatcher only after the response body has been fully read', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            const bodyPull = jest.fn();
+            const slowStream = new ReadableStream({
+                async pull(controller) {
+                    bodyPull();
+                    controller.enqueue(new TextEncoder().encode('chunk'));
+                    controller.close();
+                },
+            });
+            undiciFetch.mockResolvedValue({
+                status: 200,
+                ok: true,
+                headers: new Headers(),
+                body: slowStream,
+            });
+            await resolveDocument('https://example.com/');
+            expect(bodyPull).toHaveBeenCalled();
+            expect(lastAgentClose).toHaveBeenCalled();
+            const pullOrder = bodyPull.mock.invocationCallOrder[0];
+            const closeOrder = lastAgentClose.mock.invocationCallOrder[0];
+            expect(closeOrder).toBeGreaterThan(pullOrder);
+        });
+    });
+    describe('User-Agent', () => {
+        afterEach(() => {
+            delete process.env[USER_AGENT_ENV_VAR];
+        });
+        function sentHeaders(callIndex = 0) {
+            const init = undiciFetch.mock.calls[callIndex][1];
+            return init.headers ?? {};
+        }
+        it('sends the default User-Agent when the caller supplies none', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({ body: '{}' }));
+            await resolveDocument('https://example.com/doc.json', { headers: { Accept: 'application/json' } });
+            expect(sentHeaders()['User-Agent']).toBe(DEFAULT_USER_AGENT);
+            expect(sentHeaders()['Accept']).toBe('application/json');
+        });
+        it('sends the default User-Agent when no headers are supplied at all', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({ body: '{}' }));
+            await resolveDocument('https://example.com/doc.json');
+            expect(sentHeaders()['User-Agent']).toBe(DEFAULT_USER_AGENT);
+        });
+        it('prefers the RI_HTTP_USER_AGENT environment override to the default', async () => {
+            process.env[USER_AGENT_ENV_VAR] = 'acme-operator/1.0';
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({ body: '{}' }));
+            await resolveDocument('https://example.com/doc.json');
+            expect(sentHeaders()['User-Agent']).toBe('acme-operator/1.0');
+        });
+        it('falls back to the default when the environment override is blank (blank is treated as unset)', async () => {
+            process.env[USER_AGENT_ENV_VAR] = '   ';
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({ body: '{}' }));
+            await resolveDocument('https://example.com/doc.json');
+            expect(sentHeaders()['User-Agent']).toBe(DEFAULT_USER_AGENT);
+        });
+        it('passes a non-blank override through unvalidated (boot-time validation owns rejection)', async () => {
+            process.env[USER_AGENT_ENV_VAR] = 'operator-agent/1.0';
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({ body: '{}' }));
+            await resolveDocument('https://example.com/doc.json');
+            expect(sentHeaders()['User-Agent']).toBe('operator-agent/1.0');
+        });
+        it('passes an invalid override through raw rather than silently substituting the default', async () => {
+            process.env[USER_AGENT_ENV_VAR] = 'evil\r\nX-Injected: 1';
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({ body: '{}' }));
+            await resolveDocument('https://example.com/doc.json');
+            // The load-bearing rule: no request-time fallback. The raw value reaches
+            // the fetch layer, which rejects it loudly in real undici; deployments
+            // that want fail-fast validate at boot instead.
+            expect(sentHeaders()['User-Agent']).toBe('evil\r\nX-Injected: 1');
+        });
+        it.each(['user-agent', 'User-Agent', 'USER-AGENT', 'uSeR-aGeNt'])('never overrides a caller-supplied %s header', async (headerName) => {
+            process.env[USER_AGENT_ENV_VAR] = 'acme-operator/1.0';
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({ body: '{}' }));
+            await resolveDocument('https://example.com/doc.json', { headers: { [headerName]: 'caller/2.0' } });
+            const headers = sentHeaders();
+            expect(headers[headerName]).toBe('caller/2.0');
+            const uaKeys = Object.keys(headers).filter((k) => k.toLowerCase() === 'user-agent');
+            expect(uaKeys).toEqual([headerName]);
+        });
+        it('sends the User-Agent on every redirect hop', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch
+                .mockResolvedValueOnce(makeResponse({ status: 302, headers: { location: 'https://example.com/final' }, body: null }))
+                .mockResolvedValueOnce(makeResponse({ body: '{}' }));
+            await resolveDocument('https://example.com/doc.json');
+            expect(undiciFetch).toHaveBeenCalledTimes(2);
+            expect(sentHeaders(0)['User-Agent']).toBe(DEFAULT_USER_AGENT);
+            expect(sentHeaders(1)['User-Agent']).toBe(DEFAULT_USER_AGENT);
+        });
+    });
+    describe('304 Not Modified', () => {
+        it('returns a LoadResult with status 304 and an empty body', async () => {
+            validatePublicUrl.mockResolvedValue(resolvedAddress());
+            undiciFetch.mockResolvedValue(makeResponse({ status: 304, body: null, headers: { etag: '"abc"' } }));
+            const result = await resolveDocument('https://example.com/');
+            expect(result.status).toBe(304);
+            expect(result.body.byteLength).toBe(0);
+            expect(result.etag).toBe('"abc"');
+        });
+    });
+});
+//# sourceMappingURL=resolve-document.test.js.map