@uncefact/untp-utils 0.2.0 → 0.4.0

package/build/resolvers/errors.js

@@ -9,7 +9,14 @@ import { StructuredError } from '../structured-error.js';
  */
 export class ResolverError extends StructuredError {
 }
-/** The fetch call rejected before producing a response (TCP/TLS error, DNS race, etc.). */
+/**
+ * The fetch call rejected before producing a response (TCP/TLS error, DNS
+ * race, etc.), or the body read rejected after the headers arrived. Rejections
+ * that the resolver classifies as this request's timeout are reported as
+ * {@link ResolverTimedOutError} instead; every other rejection caught at those
+ * two awaits, including a non-abort-shaped one that arrives after the deadline
+ * has passed, arrives here.
+ */
 export class ResolverNetworkError extends ResolverError {
     constructor(url, cause) {
         super({
@@ -20,9 +27,14 @@ export class ResolverNetworkError extends ResolverError {
         });
     }
 }
-/** The remote returned a non-success HTTP status. */
+/**
+ * The remote returned a non-success HTTP status. `url` is the URL of the hop
+ * that produced the status (the end of the redirect chain), exposed so
+ * callers can still report on the final URL of a failed resolution.
+ */
 export class ResolverHttpError extends ResolverError {
     status;
+    url;
     constructor(url, status) {
         super({
             code: 'resolver.http-error',
@@ -31,6 +43,7 @@ export class ResolverHttpError extends ResolverError {
             expected: '2xx',
         });
         this.status = status;
+        this.url = url;
     }
 }
 /** The response body exceeded the configured size cap. */
@@ -46,20 +59,35 @@ export class ResolverTooLargeError extends ResolverError {
         this.limit = limit;
     }
 }
-/** A redirect chain exceeded the configured maximum hop count. */
+/**
+ * A redirect chain exceeded the configured maximum hop count. `.lastHopUrl` is
+ * optional. The resolver supplies it as the hop that answered the exhausting
+ * redirect whenever a chain exhausts a finite non-negative integer
+ * `maxRedirects`, which is the supported input. It is absent otherwise: for a
+ * negative or non-integer limit, where the loop names no responder, and for a
+ * direct two-argument construction, which this constructor permits.
+ */
 export class ResolverTooManyRedirectsError extends ResolverError {
     limit;
-    constructor(url, limit) {
+    lastHopUrl;
+    constructor(startUrl, limit, lastHopUrl) {
         super({
             code: 'resolver.too-many-redirects',
-            message: `Exceeded ${limit} redirect hops starting from ${url}.`,
+            message: `Exceeded ${limit} redirect hops starting from ${startUrl}.`,
             received: `> ${limit} hops`,
             expected: `<= ${limit} hops`,
         });
         this.limit = limit;
+        if (lastHopUrl !== undefined)
+            this.lastHopUrl = lastHopUrl;
     }
 }
-/** The fetch was aborted by the timeout signal. */
+/**
+ * The request's total deadline expired. That covers expiry while the guard was
+ * still waiting on DNS, before any fetch began, as well as a fetch or body read
+ * that rejected with an abort-shaped error once this request's signal had
+ * fired.
+ */
 export class ResolverTimedOutError extends ResolverError {
     timeoutMs;
     constructor(url, timeoutMs, cause) {
@@ -84,8 +112,13 @@ export class ResolverRedirectMissingLocationError extends ResolverError {
         });
     }
 }
-/** The response body was fetched but could not be parsed as JSON. */
+/**
+ * The response body was fetched but could not be parsed as JSON. `url` is
+ * the final URL the body was fetched from (after redirect chasing), exposed
+ * so callers can still report on the final URL of a failed resolution.
+ */
 export class ResolverInvalidJsonError extends ResolverError {
+    url;
     constructor(url, cause) {
         super({
             code: 'resolver.invalid-json',
@@ -94,6 +127,7 @@ export class ResolverInvalidJsonError extends ResolverError {
             expected: 'a JSON document',
             cause,
         });
+        this.url = url;
     }
 }
 //# sourceMappingURL=errors.js.map

package/build/resolvers/errors.js.map

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

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

@@ -43,6 +43,13 @@ describe('resolveDocumentIfChanged', () => {
             expect(passedOptions.headers['accept']).toBe('application/json');
             expect(passedOptions.headers['if-none-match']).toBe('"abc"');
         });
+        it('forwards private permission alongside conditional headers', async () => {
+            resolveDocument.mockResolvedValue(loadResult({ status: 304, bodyDigest: await digestOf('') }));
+            await resolveDocumentIfChanged('https://example.com/', { etag: '"abc"' }, { allowPrivateAddresses: true });
+            const passedOptions = resolveDocument.mock.calls[0][1];
+            expect(passedOptions.allowPrivateAddresses).toBe(true);
+            expect(passedOptions.headers['if-none-match']).toBe('"abc"');
+        });
         it('does not emit duplicate conditional headers when the caller supplies a differently-cased variant', async () => {
             resolveDocument.mockResolvedValue(loadResult({ status: 304, bodyDigest: await digestOf('') }));
             await resolveDocumentIfChanged('https://example.com/', { etag: '"new"' }, 

package/build/resolvers/resolve-document-if-changed.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-document-if-changed.test.js","sourceRoot":"","sources":["../../src/resolvers/resolve-document-if-changed.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,eAAe,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC;AAElC,IAAI,CAAC,mBAAmB,CAAC,uBAAuB,EAAE,GAAG,EAAE,CAAC,CAAC;IACvD,eAAe;CAChB,CAAC,CAAC,CAAC;AAEJ,MAAM,EAAE,wBAAwB,EAAE,GAAG,MAAM,MAAM,CAAC,kCAAkC,CAAC,CAAC;AAEtF,KAAK,UAAU,QAAQ,CAAC,IAAY;IAClC,OAAO,eAAe,CAAC,QAAQ,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;AAChH,CAAC;AAED,SAAS,UAAU,CACjB,SAAuG;IAEvG,OAAO;QACL,MAAM,EAAE,GAAG;QACX,IAAI,EAAE,IAAI,UAAU,CAAC,CAAC,CAAC;QACvB,QAAQ,EAAE,EAAE;QACZ,UAAU,EAAE,SAAS,CAAC,UAAU;QAChC,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACxC,UAAU,CAAC,GAAG,EAAE;QACd,eAAe,CAAC,SAAS,EAAE,CAAC;IAC9B,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;QACnC,EAAE,CAAC,kDAAkD,EAAE,KAAK,IAAI,EAAE;YAChE,eAAe,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAU,CAAC,CAAC;YAExG,MAAM,wBAAwB,CAAC,sBAAsB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YAE1E,MAAM,aAAa,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAwC,CAAC;YAC9F,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,oEAAoE,EAAE,KAAK,IAAI,EAAE;YAClF,MAAM,EAAE,GAAG,+BAA+B,CAAC;YAC3C,eAAe,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAU,CAAC,CAAC;YAExG,MAAM,wBAAwB,CAAC,sBAAsB,EAAE,EAAE,kBAAkB,EAAE,EAAE,EAAE,CAAC,CAAC;YAEnF,MAAM,aAAa,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAwC,CAAC;YAC9F,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,8DAA8D,EAAE,KAAK,IAAI,EAAE;YAC5E,eAAe,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAU,CAAC,CAAC;YAExG,MAAM,wBAAwB,CAC5B,sBAAsB,EACtB,EAAE,IAAI,EAAE,OAAO,EAAE,EACjB,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,EAAE,CAC5C,CAAC;YAEF,MAAM,aAAa,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAwC,CAAC;YAC9F,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACjE,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,kGAAkG,EAAE,KAAK,IAAI,EAAE;YAChH,eAAe,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAU,CAAC,CAAC;YAExG,MAAM,wBAAwB,CAC5B,sBAAsB,EACtB,EAAE,IAAI,EAAE,OAAO,EAAE;YACjB,+DAA+D;YAC/D,6EAA6E;YAC7E,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,SAAS,EAAE,EAAE,CAC5C,CAAC;YAEF,MAAM,aAAa,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAwC,CAAC;YAC9F,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;YAChD,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,eAAe,CAAC,CAAC;YAChF,MAAM,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;YACnD,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/D,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;QAC1B,EAAE,CAAC,iDAAiD,EAAE,KAAK,IAAI,EAAE;YAC/D,eAAe,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAU,CAAC,CAAC;YAExG,MAAM,MAAM,CAAC,wBAAwB,CAAC,sBAAsB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;gBACjG,IAAI,EAAE,WAAW;aAClB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,0FAA0F,EAAE,KAAK,IAAI,EAAE;YACxG,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,CAAC;YAC9C,eAAe,CAAC,iBAAiB,CAC/B,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAU,CACzG,CAAC;YAEF,MAAM,MAAM,CAAC,wBAAwB,CAAC,sBAAsB,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;gBACtG,IAAI,EAAE,WAAW;aAClB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,mFAAmF,EAAE,KAAK,IAAI,EAAE;YACjG,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,CAAC;YAChD,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,CAAC;YAChD,MAAM,MAAM,GAAG,UAAU,CAAC;gBACxB,MAAM,EAAE,GAAG;gBACX,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC;gBAC7C,QAAQ,EAAE,sBAAsB;gBAChC,UAAU,EAAE,SAAS;aACtB,CAAC,CAAC;YACH,eAAe,CAAC,iBAAiB,CAAC,MAAe,CAAC,CAAC;YAEnD,MAAM,MAAM,CAAC,wBAAwB,CAAC,sBAAsB,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;gBACzG,IAAI,EAAE,QAAQ;gBACd,MAAM;aACP,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,6FAA6F,EAAE,KAAK,IAAI,EAAE;YAC3G,MAAM,MAAM,GAAG,UAAU,CAAC;gBACxB,MAAM,EAAE,GAAG;gBACX,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC;gBACvC,QAAQ,EAAE,sBAAsB;gBAChC,UAAU,EAAE,MAAM,QAAQ,CAAC,OAAO,CAAC;aACpC,CAAC,CAAC;YACH,eAAe,CAAC,iBAAiB,CAAC,MAAe,CAAC,CAAC;YAEnD,MAAM,MAAM,CAAC,wBAAwB,CAAC,sBAAsB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;gBACjG,IAAI,EAAE,QAAQ;gBACd,MAAM;aACP,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;QACjC,EAAE,CAAC,iEAAiE,EAAE,KAAK,IAAI,EAAE;YAC/E,eAAe,CAAC,iBAAiB,CAAC,IAAI,oBAAoB,CAAC,sBAAsB,EAAE,IAAI,KAAK,CAAC,MAAM,CAAC,CAAU,CAAC,CAAC;YAEhH,MAAM,MAAM,CAAC,wBAAwB,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC;QAClH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"resolve-document-if-changed.test.js","sourceRoot":"","sources":["../../src/resolvers/resolve-document-if-changed.test.ts"],"names":[],"mappings":"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"}

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

@@ -1,4 +1,5 @@
 import { MultibaseDigest } from '../multibase-digest/index.js';
+import { type PublicUrlLookup } from '../node/index.js';
 /**
  * Defaults applied by {@link resolveDocument} (and, via composition,
  * by {@link import('./resolve-document-if-changed.js').resolveDocumentIfChanged})
@@ -7,7 +8,7 @@ import { MultibaseDigest } from '../multibase-digest/index.js';
 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). */
+    /** Total wait for asynchronous DNS and fetch work in milliseconds. Synchronous work cannot be interrupted, and DNS itself is not cancelled. */
     readonly totalTimeoutMs: 10000;
     /** Maximum additional hops after the initial request; exceeding throws {@link ResolverTooManyRedirectsError}. */
     readonly maxRedirects: 3;
@@ -62,23 +63,42 @@ export interface ResolveDocumentOptions {
     headers?: Record<string, string>;
     /** Allowed URL schemes (forwarded to {@link import('../node/index.js').validatePublicUrl}). */
     allowedSchemes?: readonly string[];
+    /** Permit private and reserved destinations while retaining every other guard. */
+    allowPrivateAddresses?: boolean;
+    /**
+     * Optional hostname lookup for tests and diagnostics. This is not a policy
+     * switch: its answers still pass through `validatePublicUrl`'s hostname and
+     * address guard before they reach the pinned connector. When omitted, the
+     * existing `node:dns/promises` lookup is used.
+     */
+    lookup?: PublicUrlLookup;
 }
 /**
  * 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.
+ * {@link import('../node/index.js').validatePublicUrl}, and the connection to
+ * each hop is pinned to the set of addresses its validation resolved, so an
+ * upstream cannot rebind its hostname between check and connect. Node's
+ * address selection tries those addresses within the request budget, so a
+ * `localhost` that resolves to both `::1` and `127.0.0.1` reaches whichever
+ * listens. Private and reserved destinations remain rejected unless
+ * `allowPrivateAddresses` is exactly true.
  *
- * @throws {UrlValidationError} for URL / scheme / hostname / DNS / private-address rejections from `validatePublicUrl`.
- * @throws {ResolverNetworkError} when fetch rejects before producing a response.
+ * Only two awaits convert a foreign rejection into a resolver error: the undici
+ * fetch and the body read. Every other throw inside this function, whether a
+ * guard error or a defect in this module, propagates exactly as thrown. That
+ * is the contract #995 settled, and it is why `verify-did-web.ts:104` now
+ * surfaces a resolver defect to its caller instead of reporting it as a
+ * retryable network fault.
+ *
+ * @throws {UrlValidationError} for URL / scheme / hostname / DNS / private-address rejections from `validatePublicUrl`, propagated unwrapped.
+ * @throws {ResolverNetworkError} when the fetch rejects before producing a response, or when a mid-body read rejects, and the rejection was not classified as this request's timeout; a non-abort-shaped rejection arriving after the deadline is also reported here.
  * @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 {ResolverTooManyRedirectsError} when the redirect chain exceeds the hop cap (with `.limit`, and `.lastHopUrl` for the hop that answered the exhausting redirect).
+ * @throws {ResolverTimedOutError} before a hop or while the guard was waiting on DNS, once the deadline has passed; in flight or mid-body, when this request's abort is what the failing call observed (with `.timeoutMs`).
  * @throws {ResolverRedirectMissingLocationError} for a 3xx with no / unparseable Location header.
  *
  * @see https://owasp.org/www-community/attacks/Server_Side_Request_Forgery

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

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

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

@@ -0,0 +1,108 @@
+import { createServer } from 'node:http';
+import { resolveJsonDocument } from './resolve-json-document.js';
+const listeners = [];
+async function startListener(host, port, handler) {
+    const requests = [];
+    const server = createServer((request, response) => {
+        requests.push(request.url ?? '');
+        handler(request, response);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error(`Listener did not expose an address for ${host}`);
+    }
+    const { port: boundPort } = address;
+    const listener = {
+        host,
+        port: boundPort,
+        requests,
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+        }),
+    };
+    listeners.push(listener);
+    return listener;
+}
+function jsonResponse(response, value) {
+    response.writeHead(200, { 'content-type': 'application/json' });
+    response.end(JSON.stringify(value));
+}
+function address(host) {
+    return { address: host, family: host.includes(':') ? 6 : 4 };
+}
+function controlledLookup(answers, calls) {
+    return async (hostname, _options) => {
+        calls.push(hostname);
+        const answer = answers.shift();
+        if (!answer)
+            throw new Error(`Unexpected lookup for ${hostname}`);
+        return answer;
+    };
+}
+afterEach(async () => {
+    await Promise.all(listeners.splice(0).map((listener) => listener.close()));
+});
+describe('resolveJsonDocument real socket pinning', () => {
+    // Both listeners use loopback addresses. The explicit private-address
+    // allowance is only for this local fixture; the callback's answers still
+    // pass through the resolver's hostname and address guard.
+    it('connects to the address validated first even when the next lookup answer changes', async () => {
+        const listenerA = await startListener('127.0.0.1', 0, (_request, response) => {
+            jsonResponse(response, { listener: 'A' });
+        });
+        const listenerB = await startListener('::1', listenerA.port, (_request, response) => {
+            jsonResponse(response, { listener: 'B' });
+        });
+        const lookupCalls = [];
+        const lookup = controlledLookup([[address(listenerA.host)], [address(listenerB.host)]], lookupCalls);
+        const result = await resolveJsonDocument(`http://accepted.test:${listenerA.port}/document`, {
+            allowPrivateAddresses: true,
+            lookup,
+        });
+        expect(result.json).toEqual({ listener: 'A' });
+        expect(listenerA.requests).toEqual(['/document']);
+        expect(listenerB.requests).toEqual([]);
+        expect(lookupCalls).toEqual(['accepted.test']);
+    });
+    it('re-validates and re-pins a redirect hop to the second listener', async () => {
+        let redirectLocation = '';
+        const listenerA = await startListener('127.0.0.1', 0, (_request, response) => {
+            response.writeHead(302, { location: redirectLocation });
+            response.end();
+        });
+        const listenerB = await startListener('::1', listenerA.port, (_request, response) => {
+            jsonResponse(response, { listener: 'B' });
+        });
+        redirectLocation = `http://redirect-target.test:${listenerA.port}/final`;
+        const lookupCalls = [];
+        const lookup = controlledLookup([[address(listenerA.host)], [address(listenerB.host)]], lookupCalls);
+        const result = await resolveJsonDocument(`http://redirect-source.test:${listenerA.port}/start`, {
+            allowPrivateAddresses: true,
+            lookup,
+        });
+        expect(result.json).toEqual({ listener: 'B' });
+        expect(listenerA.requests).toEqual(['/start']);
+        expect(listenerB.requests).toEqual(['/final']);
+        expect(lookupCalls).toEqual(['redirect-source.test', 'redirect-target.test']);
+    });
+    it('tries the second validated address when the first address refuses the connection', async () => {
+        const listenerB = await startListener('127.0.0.1', 0, (_request, response) => {
+            jsonResponse(response, { listener: 'B' });
+        });
+        const refusedAddress = '::1';
+        const lookupCalls = [];
+        const lookup = controlledLookup([[address(refusedAddress), address(listenerB.host)]], lookupCalls);
+        const result = await resolveJsonDocument(`http://failover.test:${listenerB.port}/document`, {
+            allowPrivateAddresses: true,
+            lookup,
+        });
+        expect(result.json).toEqual({ listener: 'B' });
+        expect(listenerB.requests).toEqual(['/document']);
+        expect(lookupCalls).toEqual(['failover.test']);
+    });
+});
+//# sourceMappingURL=resolve-document.integration.test.js.map

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

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

package/build/resolvers/resolve-document.js

@@ -10,7 +10,7 @@ import { ResolverHttpError, ResolverNetworkError, ResolverRedirectMissingLocatio
 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). */
+    /** Total wait for asynchronous DNS and fetch work in milliseconds. Synchronous work cannot be interrupted, and DNS itself is not cancelled. */
     totalTimeoutMs: 10_000,
     /** Maximum additional hops after the initial request; exceeding throws {@link ResolverTooManyRedirectsError}. */
     maxRedirects: 3,
@@ -22,7 +22,9 @@ export const RESOLVER_DEFAULTS = {
 /**
  * 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
+ * override (blank treated as unset), then the default. Both branches copy the
+ * caller's headers before request conversion, so a throwing getter remains a
+ * caller defect rather than becoming a transport failure. 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
@@ -31,7 +33,7 @@ export const RESOLVER_DEFAULTS = {
 function withUserAgent(headers) {
     const hasExplicit = Object.keys(headers ?? {}).some((key) => key.toLowerCase() === 'user-agent');
     if (hasExplicit)
-        return headers;
+        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 };
@@ -41,17 +43,27 @@ function withUserAgent(headers) {
  * 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.
+ * {@link import('../node/index.js').validatePublicUrl}, and the connection to
+ * each hop is pinned to the set of addresses its validation resolved, so an
+ * upstream cannot rebind its hostname between check and connect. Node's
+ * address selection tries those addresses within the request budget, so a
+ * `localhost` that resolves to both `::1` and `127.0.0.1` reaches whichever
+ * listens. Private and reserved destinations remain rejected unless
+ * `allowPrivateAddresses` is exactly true.
  *
- * @throws {UrlValidationError} for URL / scheme / hostname / DNS / private-address rejections from `validatePublicUrl`.
- * @throws {ResolverNetworkError} when fetch rejects before producing a response.
+ * Only two awaits convert a foreign rejection into a resolver error: the undici
+ * fetch and the body read. Every other throw inside this function, whether a
+ * guard error or a defect in this module, propagates exactly as thrown. That
+ * is the contract #995 settled, and it is why `verify-did-web.ts:104` now
+ * surfaces a resolver defect to its caller instead of reporting it as a
+ * retryable network fault.
+ *
+ * @throws {UrlValidationError} for URL / scheme / hostname / DNS / private-address rejections from `validatePublicUrl`, propagated unwrapped.
+ * @throws {ResolverNetworkError} when the fetch rejects before producing a response, or when a mid-body read rejects, and the rejection was not classified as this request's timeout; a non-abort-shaped rejection arriving after the deadline is also reported here.
  * @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 {ResolverTooManyRedirectsError} when the redirect chain exceeds the hop cap (with `.limit`, and `.lastHopUrl` for the hop that answered the exhausting redirect).
+ * @throws {ResolverTimedOutError} before a hop or while the guard was waiting on DNS, once the deadline has passed; in flight or mid-body, when this request's abort is what the failing call observed (with `.timeoutMs`).
  * @throws {ResolverRedirectMissingLocationError} for a 3xx with no / unparseable Location header.
  *
  * @see https://owasp.org/www-community/attacks/Server_Side_Request_Forgery
@@ -65,22 +77,59 @@ export async function resolveDocument(url, options) {
     const maxBytes = options?.maxResponseBytes ?? RESOLVER_DEFAULTS.maxResponseBytes;
     const totalTimeoutMs = options?.totalTimeoutMs ?? RESOLVER_DEFAULTS.totalTimeoutMs;
     const maxRedirects = options?.maxRedirects ?? RESOLVER_DEFAULTS.maxRedirects;
+    // The deadline protocol. `currentUrl` is hoisted above the abort promise so
+    // the promise, created once per request rather than once per hop, rejects
+    // with whichever hop was in flight when the timer fired: a timeout during
+    // DNS then names the host it was waiting on. Racing the guard against that
+    // promise bounds the wait without cancelling the lookup, because
+    // `dns.lookup` takes no signal. The bare promises are raced so that a
+    // rejection from whichever settles first still reaches the caller; the two
+    // `void ... .catch(...)` side channels exist only to keep the loser's
+    // rejection from surfacing as an unhandled rejection, and must not be moved
+    // into the race, where they would resolve the race with `undefined` and
+    // swallow a DNS failure. `signal.aborted` is checked before the guard is
+    // invoked, so a hop whose predecessor's cleanup consumed the budget makes no
+    // further guard call, and again after the race, so nothing is dispatched
+    // once the budget is spent. No `await` may be inserted between that second
+    // check and `new Agent`: any suspension there reopens the window in which
+    // the timer fires and an Agent is still constructed. Tests enforce all of
+    // this (no second-hop guard call, no Agent, fetch never called), not types.
+    let currentUrl = url;
     const controller = new AbortController();
+    let removeAbortListener = () => undefined;
+    const abortPromise = new Promise((_resolve, reject) => {
+        const onAbort = () => reject(new ResolverTimedOutError(currentUrl, totalTimeoutMs));
+        controller.signal.addEventListener('abort', onAbort, { once: true });
+        removeAbortListener = () => controller.signal.removeEventListener('abort', onAbort);
+    });
+    void abortPromise.catch(() => undefined);
     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, {
+            if (controller.signal.aborted)
+                throw new ResolverTimedOutError(currentUrl, totalTimeoutMs);
+            const guard = validatePublicUrl(currentUrl, {
                 allowedSchemes: options?.allowedSchemes,
+                allowPrivateAddresses: options?.allowPrivateAddresses,
+                ...(options?.lookup ? { lookup: options.lookup } : {}),
             });
+            void guard.catch(() => undefined);
+            const { addresses: pinnedAddresses } = await Promise.race([guard, abortPromise]);
+            if (controller.signal.aborted)
+                throw new ResolverTimedOutError(currentUrl, totalTimeoutMs);
             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 }]),
+                    // undici spreads this `lookup` option into `net.connect` and
+                    // `tls.connect` and performs no lookup of its own. Under Node's
+                    // default family autoselection it calls the callback with
+                    // `all: true` and walks the returned list, so return every address
+                    // `validatePublicUrl` validated (`addresses` is already in resolver
+                    // order) and each address Node may try is one the SSRF check passed.
+                    // Handing it only the first would refuse a name whose other
+                    // addresses hold the listener: `localhost` resolves to both `::1`
+                    // and `127.0.0.1`, and the walk is what reaches the second when the
+                    // first is refused.
+                    lookup: (_hostname, _opts, cb) => cb(null, pinnedAddresses.map(({ address, family }) => ({ address, family }))),
                 },
             });
             // The entire request lifecycle (fetch + status-check + body read +
@@ -89,13 +138,28 @@ export async function resolveDocument(url, options) {
             // 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, {
+                const headers = withUserAgent(options?.headers);
+                const requestOptions = {
                     method: 'GET',
                     redirect: 'manual',
                     signal: controller.signal,
-                    headers: withUserAgent(options?.headers),
+                    headers,
                     dispatcher,
-                });
+                };
+                let response;
+                try {
+                    response = await undiciFetch(currentUrl, requestOptions);
+                }
+                catch (cause) {
+                    // This catch also sees undici's Request-construction rejections, so a
+                    // redirect hop carrying userinfo or a malformed header value is
+                    // wrapped as a network error rather than propagating as a defect.
+                    // That is the recorded exception to #995's wording.
+                    if (isOurTimeout(cause, controller.signal)) {
+                        throw new ResolverTimedOutError(currentUrl, totalTimeoutMs, cause);
+                    }
+                    throw new ResolverNetworkError(currentUrl, cause);
+                }
                 // 304 Not Modified: body is intentionally empty; the caller maps it
                 // to `unchanged` in `resolveDocumentIfChanged`.
                 if (response.status === 304) {
@@ -128,6 +192,9 @@ export async function resolveDocument(url, options) {
                     // proceed without waiting for body drain.
                     if (response.body)
                         await response.body.cancel().catch(() => undefined);
+                    if (hop === maxRedirects) {
+                        throw new ResolverTooManyRedirectsError(url, maxRedirects, currentUrl);
+                    }
                     currentUrl = nextUrl;
                     continue;
                 }
@@ -136,7 +203,7 @@ export async function resolveDocument(url, options) {
                         await response.body.cancel().catch(() => undefined);
                     throw new ResolverHttpError(currentUrl, response.status);
                 }
-                const body = await readWithLimit(response, maxBytes, currentUrl, totalTimeoutMs);
+                const body = await readWithLimit(response, maxBytes, currentUrl, totalTimeoutMs, controller.signal);
                 const bodyDigest = await computeDigest(body);
                 const headerView = extractHeaders(response.headers);
                 return {
@@ -155,28 +222,32 @@ export async function resolveDocument(url, options) {
         }
         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);
+        removeAbortListener();
     }
 }
+/**
+ * The classification policy at the two transport catches: a rejection counts as
+ * this request's timeout only when this request's signal has fired and the
+ * error is named `AbortError` or `TimeoutError`. Everything else caught there
+ * becomes a {@link ResolverNetworkError}.
+ *
+ * The signal gate stops an abort-shaped rejection counting as this request's
+ * timeout while its signal is quiet, which would tell the operator "timed out
+ * after 10000ms" when 300 ms elapsed. The name gate keeps a non-abort-shaped
+ * rejection arriving after the deadline classified as a network fault. Neither
+ * gate proves the rejection was caused by this signal; this is the chosen
+ * policy, not a proof of cause.
+ */
+function isOurTimeout(error, signal) {
+    return signal.aborted && isAbortLikeError(error);
+}
 function isAbortLikeError(error) {
-    return error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError');
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const name = error.name;
+    return name === 'AbortError' || name === 'TimeoutError';
 }
 function extractHeaders(headers) {
     const view = {};
@@ -197,7 +268,7 @@ async function computeDigest(body) {
         base: RESOLVER_DEFAULTS.digestEncoding,
     });
 }
-async function readWithLimit(response, limit, url, totalTimeoutMs) {
+async function readWithLimit(response, limit, url, totalTimeoutMs, signal) {
     if (!response.body)
         return new Uint8Array(0);
     const reader = response.body.getReader();
@@ -206,27 +277,36 @@ async function readWithLimit(response, limit, url, totalTimeoutMs) {
     try {
         // eslint-disable-next-line no-constant-condition
         while (true) {
-            const { value, done } = await reader.read();
+            let readResult;
+            try {
+                readResult = await reader.read();
+            }
+            catch (error) {
+                if (isOurTimeout(error, signal))
+                    throw new ResolverTimedOutError(url, totalTimeoutMs, error);
+                throw new ResolverNetworkError(url, error);
+            }
+            const { value, done } = readResult;
             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.
+        // Cleanup only: release the reader so the upstream socket can be
+        // recycled, then rethrow the original value unchanged. Classification
+        // happens at the read await above, and the over-cap error is raised
+        // without cancelling inline precisely so cancellation stays here. A
+        // future edit that classified or replaced the error here would relabel
+        // both a defect and an already-classified resolver error.
         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);
+        throw error;
     }
     const merged = new Uint8Array(total);
     let offset = 0;