@uncefact/untp-utils 0.1.0 → 0.3.0

package/build/node/validate-public-url.test.js

@@ -0,0 +1,324 @@
+import { jest } from '@jest/globals';
+import { InvalidUrlError, PrivateAddressError, PrivateHostnameError, ResolutionEmptyError, ResolutionFailedError, UrlValidationError, } from './errors.js';
+const lookup = jest.fn();
+jest.unstable_mockModule('node:dns/promises', () => ({
+    default: { lookup },
+    lookup,
+}));
+const { validatePublicUrl } = await import('./validate-public-url.js');
+/**
+ * The shape `validatePublicUrl` returns for a single validated address:
+ * `address` / `family` repeat the first entry of `addresses`.
+ */
+function validated(address, family) {
+    return { address, family, addresses: [{ address, family }] };
+}
+describe('validatePublicUrl', () => {
+    beforeEach(() => {
+        lookup.mockReset();
+    });
+    describe('URL parsing', () => {
+        it('throws InvalidUrlError when the string is not a parseable URL', async () => {
+            await expect(validatePublicUrl('not a url')).rejects.toBeInstanceOf(InvalidUrlError);
+            await expect(validatePublicUrl('not a url')).rejects.toMatchObject({
+                code: 'url.invalid',
+                received: 'not a url',
+            });
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it('retains parse rejection when private addresses are allowed', async () => {
+            await expect(validatePublicUrl('not a url', { allowPrivateAddresses: true })).rejects.toBeInstanceOf(InvalidUrlError);
+            expect(lookup).not.toHaveBeenCalled();
+        });
+    });
+    describe('scheme', () => {
+        it('throws UnsupportedSchemeError for an unallowed scheme', async () => {
+            await expect(validatePublicUrl('ftp://example.com/path')).rejects.toMatchObject({
+                name: 'UnsupportedSchemeError',
+                code: 'url.unsupported-scheme',
+                received: 'ftp',
+            });
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it('accepts a caller-supplied allowedSchemes list', async () => {
+            lookup.mockResolvedValue([{ address: '1.1.1.1', family: 4 }]);
+            await expect(validatePublicUrl('wss://example.com/ws', { allowedSchemes: ['wss', 'ws'] })).resolves.toEqual(validated('1.1.1.1', 4));
+        });
+        it('retains scheme rejection when private addresses are allowed', async () => {
+            await expect(validatePublicUrl('ftp://example.com/path', { allowPrivateAddresses: true })).rejects.toMatchObject({
+                name: 'UnsupportedSchemeError',
+            });
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it('reports canonical scheme details on the error', async () => {
+            await expect(validatePublicUrl('ftp://example.com/')).rejects.toMatchObject({
+                received: 'ftp',
+                expected: ['http', 'https'],
+                remediation: 'Use one of: http, https.',
+            });
+        });
+        it('compares schemes case-insensitively', async () => {
+            lookup.mockResolvedValue([{ address: '1.1.1.1', family: 4 }]);
+            await expect(validatePublicUrl('HTTPS://example.com/')).resolves.toEqual(validated('1.1.1.1', 4));
+        });
+    });
+    describe('hostname', () => {
+        it('rejects localhost without DNS lookup', async () => {
+            await expect(validatePublicUrl('http://localhost/path')).rejects.toBeInstanceOf(PrivateHostnameError);
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it('rejects .internal suffix without DNS lookup', async () => {
+            await expect(validatePublicUrl('http://db.internal/')).rejects.toBeInstanceOf(PrivateHostnameError);
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it('rejects a literal private IPv4 in the URL without DNS lookup', async () => {
+            await expect(validatePublicUrl('http://10.0.0.1/')).rejects.toBeInstanceOf(PrivateHostnameError);
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it('rejects a literal IPv6 loopback in the URL without DNS lookup', async () => {
+            await expect(validatePublicUrl('http://[::1]/')).rejects.toBeInstanceOf(PrivateHostnameError);
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it('returns the literal IP for a public IPv4 host without calling DNS', async () => {
+            await expect(validatePublicUrl('http://1.1.1.1/')).resolves.toEqual(validated('1.1.1.1', 4));
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it('returns the literal IP for a public IPv6 host without calling DNS', async () => {
+            await expect(validatePublicUrl('http://[2606:4700:4700::1111]/')).resolves.toEqual(validated('2606:4700:4700::1111', 6));
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it('rejects a literal 0.0.0.0 host without DNS lookup', async () => {
+            await expect(validatePublicUrl('http://0.0.0.0/')).rejects.toBeInstanceOf(PrivateHostnameError);
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it('rejects userinfo@host smuggling where the host is private', async () => {
+            // `URL` discards the `evil.com@` userinfo; pin the regression.
+            await expect(validatePublicUrl('http://evil.com@127.0.0.1/')).rejects.toMatchObject({
+                name: 'PrivateHostnameError',
+                received: '127.0.0.1',
+            });
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it.each([undefined, false, 'true'])('keeps private literals strict when allowPrivateAddresses is %p', async (option) => {
+            await expect(validatePublicUrl('http://10.0.0.1/', { allowPrivateAddresses: option })).rejects.toBeInstanceOf(PrivateHostnameError);
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it('rejects an empty hostname as malformed input even when private addresses are allowed', async () => {
+            await expect(validatePublicUrl('file:///', { allowedSchemes: ['file'], allowPrivateAddresses: true })).rejects.toBeInstanceOf(InvalidUrlError);
+            expect(lookup).not.toHaveBeenCalled();
+        });
+        it.each(['localhost', 'db.internal'])('resolves local names when private addresses are allowed', async (hostname) => {
+            lookup.mockResolvedValue([{ address: '10.0.0.5', family: 4 }]);
+            await expect(validatePublicUrl(`http://${hostname}/`, { allowPrivateAddresses: true })).resolves.toEqual(validated('10.0.0.5', 4));
+            expect(lookup).toHaveBeenCalledWith(hostname, { family: 0, all: true });
+        });
+        it.each([
+            ['127.0.0.1', 'http://127.0.0.1/'],
+            ['169.254.169.254', 'http://169.254.169.254/'],
+            ['224.0.0.1', 'http://224.0.0.1/'],
+            ['0.0.0.0', 'http://0.0.0.0/'],
+            ['::1', 'http://[::1]/'],
+            ['fc00::1', 'http://[fc00::1]/'],
+            ['::ffff:10.0.0.1', 'http://[::ffff:10.0.0.1]/'],
+        ])('allows the non-public literal %s without DNS when opted in', async (_address, url) => {
+            const hostname = new URL(url).hostname.replace(/^\[|\]$/g, '');
+            await expect(validatePublicUrl(url, { allowPrivateAddresses: true })).resolves.toEqual(validated(hostname, url.includes('[') ? 6 : 4));
+            expect(lookup).not.toHaveBeenCalled();
+        });
+    });
+    describe('DNS resolution', () => {
+        it('uses a supplied lookup callback while still validating its addresses', async () => {
+            const suppliedLookup = jest.fn().mockResolvedValue([{ address: '10.0.0.5', family: 4 }]);
+            await expect(validatePublicUrl('https://example.com/', { lookup: suppliedLookup })).rejects.toBeInstanceOf(PrivateAddressError);
+            expect(suppliedLookup).toHaveBeenCalledWith('example.com', { family: 0, all: true });
+        });
+        it('throws ResolutionFailedError when dns.lookup rejects', async () => {
+            lookup.mockRejectedValue(new Error('ENOTFOUND example.com'));
+            await expect(validatePublicUrl('https://example.com/')).rejects.toMatchObject({
+                name: 'ResolutionFailedError',
+                code: 'url.resolution-failed',
+                received: 'ENOTFOUND example.com',
+            });
+        });
+        it('throws ResolutionEmptyError when the resolver returns no records', async () => {
+            lookup.mockResolvedValue([]);
+            await expect(validatePublicUrl('https://example.com/')).rejects.toBeInstanceOf(ResolutionEmptyError);
+        });
+        it('rejects a record whose address does not parse as an IP', async () => {
+            lookup.mockResolvedValue([{ address: 'not-an-ip-address', family: 4 }]);
+            await expect(validatePublicUrl('https://example.com/')).rejects.toThrow(ResolutionFailedError);
+        });
+        it('rejects a record whose claimed family contradicts its address', async () => {
+            lookup.mockResolvedValue([{ address: '10.0.0.1', family: 6 }]);
+            await expect(validatePublicUrl('https://example.com/')).rejects.toThrow(ResolutionFailedError);
+        });
+        it('requires family agreement even when the address itself is public', async () => {
+            lookup.mockResolvedValue([{ address: '93.184.216.34', family: 0 }]);
+            await expect(validatePublicUrl('https://example.com/')).rejects.toThrow(ResolutionFailedError);
+        });
+        it('passes the family option through to dns.lookup with all: true', async () => {
+            lookup.mockResolvedValue([{ address: '1.1.1.1', family: 4 }]);
+            await validatePublicUrl('https://example.com/', { family: 4 });
+            expect(lookup).toHaveBeenCalledWith('example.com', { family: 4, all: true });
+        });
+        it('defaults the family option to 0 (any)', async () => {
+            lookup.mockResolvedValue([{ address: '1.1.1.1', family: 4 }]);
+            await validatePublicUrl('https://example.com/');
+            expect(lookup).toHaveBeenCalledWith('example.com', { family: 0, all: true });
+        });
+        it('throws ResolutionFailedError when dns returns an unsupported family', async () => {
+            lookup.mockResolvedValue([{ address: 'whatever', family: 7 }]);
+            await expect(validatePublicUrl('https://example.com/')).rejects.toBeInstanceOf(ResolutionFailedError);
+        });
+        it('retains DNS rejection when private addresses are allowed', async () => {
+            const dnsError = new Error('EAI_AGAIN');
+            lookup.mockRejectedValue(dnsError);
+            await expect(validatePublicUrl('https://example.com/', { allowPrivateAddresses: true })).rejects.toMatchObject({
+                name: 'ResolutionFailedError',
+                cause: dnsError,
+            });
+        });
+        it('retains empty resolution when private addresses are allowed', async () => {
+            lookup.mockResolvedValue([]);
+            await expect(validatePublicUrl('https://example.com/', { allowPrivateAddresses: true })).rejects.toBeInstanceOf(ResolutionEmptyError);
+        });
+    });
+    describe('rebind defence', () => {
+        it('rejects a hostname that resolves to AWS metadata', async () => {
+            lookup.mockResolvedValue([{ address: '169.254.169.254', family: 4 }]);
+            await expect(validatePublicUrl('https://metadata.attacker.example/')).rejects.toMatchObject({
+                name: 'PrivateAddressError',
+                code: 'url.private-address',
+                resolvedAddresses: ['169.254.169.254'],
+            });
+        });
+        it('rejects a hostname that resolves to an RFC 1918 address', async () => {
+            lookup.mockResolvedValue([{ address: '10.0.0.1', family: 4 }]);
+            await expect(validatePublicUrl('https://internal.attacker.example/')).rejects.toMatchObject({
+                name: 'PrivateAddressError',
+                resolvedAddresses: ['10.0.0.1'],
+            });
+        });
+        it('rejects a hostname that resolves to an IPv6 loopback', async () => {
+            lookup.mockResolvedValue([{ address: '::1', family: 6 }]);
+            await expect(validatePublicUrl('https://example.com/')).rejects.toBeInstanceOf(PrivateAddressError);
+        });
+        it('rejects a hostname that resolves to an IPv6 unique-local address', async () => {
+            lookup.mockResolvedValue([{ address: 'fc00::1', family: 6 }]);
+            await expect(validatePublicUrl('https://example.com/')).rejects.toBeInstanceOf(PrivateAddressError);
+        });
+        it('rejects a hostname that resolves to an IPv4-mapped private IPv6 address', async () => {
+            lookup.mockResolvedValue([{ address: '::ffff:10.0.0.1', family: 6 }]);
+            await expect(validatePublicUrl('https://example.com/')).rejects.toBeInstanceOf(PrivateAddressError);
+        });
+        it('rejects when any A or AAAA record is private even if others are public', async () => {
+            lookup.mockResolvedValue([
+                { address: '1.1.1.1', family: 4 },
+                { address: '169.254.169.254', family: 4 },
+            ]);
+            await expect(validatePublicUrl('https://mixed.attacker.example/')).rejects.toMatchObject({
+                name: 'PrivateAddressError',
+                resolvedAddresses: ['169.254.169.254'],
+            });
+        });
+        it('returns every validated public record so callers can use them all as connect targets', async () => {
+            lookup.mockResolvedValue([
+                { address: '1.1.1.1', family: 4 },
+                { address: '8.8.8.8', family: 4 },
+            ]);
+            await expect(validatePublicUrl('https://example.com/')).resolves.toEqual({
+                address: '1.1.1.1',
+                family: 4,
+                addresses: [
+                    { address: '1.1.1.1', family: 4 },
+                    { address: '8.8.8.8', family: 4 },
+                ],
+            });
+        });
+        it('allows private and public records and returns them all when opted in', async () => {
+            lookup.mockResolvedValue([
+                { address: '10.0.0.1', family: 4 },
+                { address: '1.1.1.1', family: 4 },
+            ]);
+            await expect(validatePublicUrl('https://mixed.example/', { allowPrivateAddresses: true })).resolves.toEqual({
+                address: '10.0.0.1',
+                family: 4,
+                addresses: [
+                    { address: '10.0.0.1', family: 4 },
+                    { address: '1.1.1.1', family: 4 },
+                ],
+            });
+        });
+        // The dual-stack `localhost` case that CI hit: only one of the two
+        // addresses has a listener, so the caller needs both to reach it.
+        it('returns both records for a dual-stack loopback name when opted in', async () => {
+            lookup.mockResolvedValue([
+                { address: '::1', family: 6 },
+                { address: '127.0.0.1', family: 4 },
+            ]);
+            await expect(validatePublicUrl('http://localhost/', { allowPrivateAddresses: true })).resolves.toEqual({
+                address: '::1',
+                family: 6,
+                addresses: [
+                    { address: '::1', family: 6 },
+                    { address: '127.0.0.1', family: 4 },
+                ],
+            });
+        });
+        it('returns every public record in strict mode', async () => {
+            lookup.mockResolvedValue([
+                { address: '1.1.1.1', family: 4 },
+                { address: '2606:4700:4700::1111', family: 6 },
+            ]);
+            await expect(validatePublicUrl('https://example.com/')).resolves.toEqual({
+                address: '1.1.1.1',
+                family: 4,
+                addresses: [
+                    { address: '1.1.1.1', family: 4 },
+                    { address: '2606:4700:4700::1111', family: 6 },
+                ],
+            });
+        });
+        it('still throws when a later record is private in strict mode', async () => {
+            lookup.mockResolvedValue([
+                { address: '1.1.1.1', family: 4 },
+                { address: '10.0.0.1', family: 4 },
+            ]);
+            await expect(validatePublicUrl('https://example.com/')).rejects.toBeInstanceOf(PrivateAddressError);
+        });
+        it('leads with a public first record rather than preferring a later private record when opted in', async () => {
+            lookup.mockResolvedValue([
+                { address: '1.1.1.1', family: 4 },
+                { address: '10.0.0.1', family: 4 },
+            ]);
+            await expect(validatePublicUrl('https://mixed.example/', { allowPrivateAddresses: true })).resolves.toEqual({
+                address: '1.1.1.1',
+                family: 4,
+                addresses: [
+                    { address: '1.1.1.1', family: 4 },
+                    { address: '10.0.0.1', family: 4 },
+                ],
+            });
+        });
+        it('checks every record for contradictory metadata in relaxed mode', async () => {
+            lookup.mockResolvedValue([
+                { address: '10.0.0.1', family: 4 },
+                { address: 'not-an-ip', family: 4 },
+            ]);
+            await expect(validatePublicUrl('https://mixed.example/', { allowPrivateAddresses: true })).rejects.toBeInstanceOf(ResolutionFailedError);
+        });
+        it('retains family validation and lookup hints in relaxed mode', async () => {
+            lookup.mockResolvedValue([{ address: '10.0.0.1', family: 6 }]);
+            await expect(validatePublicUrl('https://mixed.example/', { allowPrivateAddresses: true, family: 6 })).rejects.toBeInstanceOf(ResolutionFailedError);
+            expect(lookup).toHaveBeenCalledWith('mixed.example', { family: 6, all: true });
+        });
+    });
+    describe('hierarchy', () => {
+        it('every concrete error extends UrlValidationError', async () => {
+            await expect(validatePublicUrl('not a url')).rejects.toBeInstanceOf(UrlValidationError);
+            lookup.mockResolvedValue([{ address: '10.0.0.1', family: 4 }]);
+            await expect(validatePublicUrl('https://example.com/')).rejects.toBeInstanceOf(UrlValidationError);
+        });
+    });
+});
+//# sourceMappingURL=validate-public-url.test.js.map

package/build/node/validate-public-url.test.js.map

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

package/build/resolvers/errors.d.ts

@@ -0,0 +1,73 @@
+import { StructuredError } from '../structured-error.js';
+/**
+ * Base for every diagnostic from `@uncefact/untp-utils/resolvers`.
+ * Catch to handle any resolver failure generically; catch a concrete
+ * subclass for specific handling. URL-shape failures (invalid URL,
+ * unsupported scheme, private hostname, resolution failure, private
+ * address) surface as `UrlValidationError` subclasses from the
+ * underlying `validatePublicUrl` call rather than being re-wrapped here.
+ */
+export declare class ResolverError extends StructuredError {
+}
+/**
+ * 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 declare class ResolverNetworkError extends ResolverError {
+    constructor(url: string, cause: unknown);
+}
+/**
+ * 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 declare class ResolverHttpError extends ResolverError {
+    readonly status: number;
+    readonly url: string;
+    constructor(url: string, status: number);
+}
+/** The response body exceeded the configured size cap. */
+export declare class ResolverTooLargeError extends ResolverError {
+    readonly limit: number;
+    constructor(url: string, limit: number);
+}
+/**
+ * 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 declare class ResolverTooManyRedirectsError extends ResolverError {
+    readonly limit: number;
+    readonly lastHopUrl?: string;
+    constructor(startUrl: string, limit: number, lastHopUrl?: string);
+}
+/**
+ * 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 declare class ResolverTimedOutError extends ResolverError {
+    readonly timeoutMs: number;
+    constructor(url: string, timeoutMs: number, cause?: unknown);
+}
+/** A 3xx response was received without a parseable `Location` header. */
+export declare class ResolverRedirectMissingLocationError extends ResolverError {
+    constructor(url: string, received: string | number, cause?: unknown);
+}
+/**
+ * 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 declare class ResolverInvalidJsonError extends ResolverError {
+    readonly url: string;
+    constructor(url: string, cause: unknown);
+}

package/build/resolvers/errors.js

@@ -0,0 +1,133 @@
+import { StructuredError } from '../structured-error.js';
+/**
+ * Base for every diagnostic from `@uncefact/untp-utils/resolvers`.
+ * Catch to handle any resolver failure generically; catch a concrete
+ * subclass for specific handling. URL-shape failures (invalid URL,
+ * unsupported scheme, private hostname, resolution failure, private
+ * address) surface as `UrlValidationError` subclasses from the
+ * underlying `validatePublicUrl` call rather than being re-wrapped here.
+ */
+export class ResolverError extends StructuredError {
+}
+/**
+ * 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({
+            code: 'resolver.network-error',
+            message: `Network error fetching ${url}.`,
+            received: cause instanceof Error ? cause.message : String(cause),
+            cause,
+        });
+    }
+}
+/**
+ * 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',
+            message: `${url} returned status ${status}.`,
+            received: status,
+            expected: '2xx',
+        });
+        this.status = status;
+        this.url = url;
+    }
+}
+/** The response body exceeded the configured size cap. */
+export class ResolverTooLargeError extends ResolverError {
+    limit;
+    constructor(url, limit) {
+        super({
+            code: 'resolver.too-large',
+            message: `Response body for ${url} exceeds ${limit}-byte limit.`,
+            received: `> ${limit} bytes`,
+            expected: `<= ${limit} bytes`,
+        });
+        this.limit = limit;
+    }
+}
+/**
+ * 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;
+    lastHopUrl;
+    constructor(startUrl, limit, lastHopUrl) {
+        super({
+            code: 'resolver.too-many-redirects',
+            message: `Exceeded ${limit} redirect hops starting from ${startUrl}.`,
+            received: `> ${limit} hops`,
+            expected: `<= ${limit} hops`,
+        });
+        this.limit = limit;
+        if (lastHopUrl !== undefined)
+            this.lastHopUrl = lastHopUrl;
+    }
+}
+/**
+ * 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) {
+        super({
+            code: 'resolver.timed-out',
+            message: `Request to ${url} timed out after ${timeoutMs}ms.`,
+            received: `> ${timeoutMs}ms`,
+            expected: `<= ${timeoutMs}ms`,
+            cause,
+        });
+        this.timeoutMs = timeoutMs;
+    }
+}
+/** A 3xx response was received without a parseable `Location` header. */
+export class ResolverRedirectMissingLocationError extends ResolverError {
+    constructor(url, received, cause) {
+        super({
+            code: 'resolver.redirect-missing-location',
+            message: `Redirect from ${url} had no parseable Location header.`,
+            received,
+            cause,
+        });
+    }
+}
+/**
+ * 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',
+            message: `Response body for ${url} is not valid JSON.`,
+            received: cause instanceof Error ? cause.message : String(cause),
+            expected: 'a JSON document',
+            cause,
+        });
+        this.url = url;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/build/resolvers/errors.js.map

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

package/build/resolvers/index.d.ts

@@ -0,0 +1,5 @@
+export { ResolverError, ResolverNetworkError, ResolverHttpError, ResolverTooLargeError, ResolverTooManyRedirectsError, ResolverTimedOutError, ResolverRedirectMissingLocationError, ResolverInvalidJsonError, } from './errors.js';
+export { resolveDocument, RESOLVER_DEFAULTS, type LoadResult, type ResolveDocumentOptions, } from './resolve-document.js';
+export { DEFAULT_USER_AGENT, USER_AGENT_ENV_VAR, isValidHttpUserAgent } from '../http-headers/index.js';
+export { resolveJsonDocument, type ResolveJsonDocumentOptions, type ResolvedJsonDocument, } from './resolve-json-document.js';
+export { resolveDocumentIfChanged, type CachedResource, type ResolveDocumentIfChangedValue, } from './resolve-document-if-changed.js';

package/build/resolvers/index.js

@@ -0,0 +1,6 @@
+export { ResolverError, ResolverNetworkError, ResolverHttpError, ResolverTooLargeError, ResolverTooManyRedirectsError, ResolverTimedOutError, ResolverRedirectMissingLocationError, ResolverInvalidJsonError, } from './errors.js';
+export { resolveDocument, RESOLVER_DEFAULTS, } from './resolve-document.js';
+export { DEFAULT_USER_AGENT, USER_AGENT_ENV_VAR, isValidHttpUserAgent } from '../http-headers/index.js';
+export { resolveJsonDocument, } from './resolve-json-document.js';
+export { resolveDocumentIfChanged, } from './resolve-document-if-changed.js';
+//# sourceMappingURL=index.js.map

package/build/resolvers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resolvers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,6BAA6B,EAC7B,qBAAqB,EACrB,oCAAoC,EACpC,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,iBAAiB,GAGlB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACxG,OAAO,EACL,mBAAmB,GAGpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,wBAAwB,GAGzB,MAAM,kCAAkC,CAAC"}

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

@@ -0,0 +1,48 @@
+import type { MultibaseDigest } from '../multibase-digest/index.js';
+import { type LoadResult, type ResolveDocumentOptions } from './resolve-document.js';
+/**
+ * Description of a previously-cached resource, used by
+ * {@link resolveDocumentIfChanged} to drive the conditional-fetch skip
+ * chain (`If-None-Match`, `If-Modified-Since`, body-digest comparison).
+ */
+export interface CachedResource {
+    /** The `ETag` previously observed for this URL, if any. */
+    etag?: string;
+    /** The `Last-Modified` header previously observed, if any. */
+    lastModifiedHeader?: string;
+    /** The body digest of the previously cached response. */
+    bodyDigest?: MultibaseDigest;
+}
+/**
+ * Discriminated return from {@link resolveDocumentIfChanged}.
+ *
+ * - `{ kind: 'unchanged' }`: the upstream confirmed the cache is fresh
+ *   (either via a `304 Not Modified` or via a `200` whose body digest
+ *   matched `cached.bodyDigest`).
+ * - `{ kind: 'loaded'; result }`: the upstream returned fresh content;
+ *   `result` is the new {@link LoadResult} the caller should store.
+ */
+export type ResolveDocumentIfChangedValue = {
+    kind: 'unchanged';
+} | {
+    kind: 'loaded';
+    result: LoadResult;
+};
+/**
+ * Conditional-fetch wrapper around {@link resolveDocument} that implements
+ * the skip chain from ADR-033 §1.
+ *
+ * Three short-circuits, in order:
+ *
+ *  1. **`304 Not Modified`** from the upstream (driven by `If-None-Match`
+ *     and `If-Modified-Since` headers built from `cached.etag` and
+ *     `cached.lastModifiedHeader`).
+ *  2. **Body-digest match** after a `200 OK` (the upstream ignored the
+ *     conditional headers but returned the same content; compared against
+ *     `cached.bodyDigest`).
+ *  3. Otherwise, the fresh {@link LoadResult} is returned under the
+ *     `loaded` discriminator.
+ *
+ * Errors from the underlying {@link resolveDocument} propagate unchanged.
+ */
+export declare function resolveDocumentIfChanged(url: string, cached: CachedResource, options?: ResolveDocumentOptions): Promise<ResolveDocumentIfChangedValue>;