@uncefact/untp-utils 0.0.1 → 0.2.0

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

@@ -0,0 +1,177 @@
+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');
+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();
+        });
+    });
+    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({
+                address: '1.1.1.1',
+                family: 4,
+            });
+        });
+        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({
+                address: '1.1.1.1',
+                family: 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({ address: '1.1.1.1', family: 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({
+                address: '2606:4700:4700::1111',
+                family: 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();
+        });
+    });
+    describe('DNS resolution', () => {
+        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('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);
+        });
+    });
+    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 the first resolved IP so callers can use it as the connect target', 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 });
+        });
+    });
+    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,43 @@
+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.). */
+export declare class ResolverNetworkError extends ResolverError {
+    constructor(url: string, cause: unknown);
+}
+/** The remote returned a non-success HTTP status. */
+export declare class ResolverHttpError extends ResolverError {
+    readonly status: number;
+    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. */
+export declare class ResolverTooManyRedirectsError extends ResolverError {
+    readonly limit: number;
+    constructor(url: string, limit: number);
+}
+/** The fetch was aborted by the timeout signal. */
+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. */
+export declare class ResolverInvalidJsonError extends ResolverError {
+    constructor(url: string, cause: unknown);
+}

package/build/resolvers/errors.js

@@ -0,0 +1,99 @@
+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.). */
+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. */
+export class ResolverHttpError extends ResolverError {
+    status;
+    constructor(url, status) {
+        super({
+            code: 'resolver.http-error',
+            message: `${url} returned status ${status}.`,
+            received: status,
+            expected: '2xx',
+        });
+        this.status = status;
+    }
+}
+/** 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. */
+export class ResolverTooManyRedirectsError extends ResolverError {
+    limit;
+    constructor(url, limit) {
+        super({
+            code: 'resolver.too-many-redirects',
+            message: `Exceeded ${limit} redirect hops starting from ${url}.`,
+            received: `> ${limit} hops`,
+            expected: `<= ${limit} hops`,
+        });
+        this.limit = limit;
+    }
+}
+/** The fetch was aborted by the timeout signal. */
+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. */
+export class ResolverInvalidJsonError extends ResolverError {
+    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,
+        });
+    }
+}
+//# 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":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,OAAO,aAAc,SAAQ,eAAe;CAAG;AAErD,2FAA2F;AAC3F,MAAM,OAAO,oBAAqB,SAAQ,aAAa;IACrD,YAAY,GAAW,EAAE,KAAc;QACrC,KAAK,CAAC;YACJ,IAAI,EAAE,wBAAwB;YAC9B,OAAO,EAAE,0BAA0B,GAAG,GAAG;YACzC,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;YAChE,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AAED,qDAAqD;AACrD,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IACzC,MAAM,CAAS;IACxB,YAAY,GAAW,EAAE,MAAc;QACrC,KAAK,CAAC;YACJ,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,GAAG,GAAG,oBAAoB,MAAM,GAAG;YAC5C,QAAQ,EAAE,MAAM;YAChB,QAAQ,EAAE,KAAK;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,0DAA0D;AAC1D,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IAC7C,KAAK,CAAS;IACvB,YAAY,GAAW,EAAE,KAAa;QACpC,KAAK,CAAC;YACJ,IAAI,EAAE,oBAAoB;YAC1B,OAAO,EAAE,qBAAqB,GAAG,YAAY,KAAK,cAAc;YAChE,QAAQ,EAAE,KAAK,KAAK,QAAQ;YAC5B,QAAQ,EAAE,MAAM,KAAK,QAAQ;SAC9B,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,kEAAkE;AAClE,MAAM,OAAO,6BAA8B,SAAQ,aAAa;IACrD,KAAK,CAAS;IACvB,YAAY,GAAW,EAAE,KAAa;QACpC,KAAK,CAAC;YACJ,IAAI,EAAE,6BAA6B;YACnC,OAAO,EAAE,YAAY,KAAK,gCAAgC,GAAG,GAAG;YAChE,QAAQ,EAAE,KAAK,KAAK,OAAO;YAC3B,QAAQ,EAAE,MAAM,KAAK,OAAO;SAC7B,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,mDAAmD;AACnD,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IAC7C,SAAS,CAAS;IAC3B,YAAY,GAAW,EAAE,SAAiB,EAAE,KAAe;QACzD,KAAK,CAAC;YACJ,IAAI,EAAE,oBAAoB;YAC1B,OAAO,EAAE,cAAc,GAAG,oBAAoB,SAAS,KAAK;YAC5D,QAAQ,EAAE,KAAK,SAAS,IAAI;YAC5B,QAAQ,EAAE,MAAM,SAAS,IAAI;YAC7B,KAAK;SACN,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED,yEAAyE;AACzE,MAAM,OAAO,oCAAqC,SAAQ,aAAa;IACrE,YAAY,GAAW,EAAE,QAAyB,EAAE,KAAe;QACjE,KAAK,CAAC;YACJ,IAAI,EAAE,oCAAoC;YAC1C,OAAO,EAAE,iBAAiB,GAAG,oCAAoC;YACjE,QAAQ;YACR,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AAED,qEAAqE;AACrE,MAAM,OAAO,wBAAyB,SAAQ,aAAa;IACzD,YAAY,GAAW,EAAE,KAAc;QACrC,KAAK,CAAC;YACJ,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,qBAAqB,GAAG,qBAAqB;YACtD,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;YAChE,QAAQ,EAAE,iBAAiB;YAC3B,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF"}

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>;

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

@@ -0,0 +1,42 @@
+import { resolveDocument } from './resolve-document.js';
+/**
+ * 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 async function resolveDocumentIfChanged(url, cached, options) {
+    // HTTP header names are case-insensitive on the wire, but a plain
+    // `Record<string, string>` is not: a caller-supplied `'if-none-match'`
+    // and our `'If-None-Match'` would survive as two distinct keys and
+    // undici would emit both. Normalise every key to lower-case so the
+    // cached validator wins cleanly.
+    const conditionalHeaders = {};
+    for (const [key, value] of Object.entries(options?.headers ?? {})) {
+        conditionalHeaders[key.toLowerCase()] = value;
+    }
+    if (cached.etag)
+        conditionalHeaders['if-none-match'] = cached.etag;
+    if (cached.lastModifiedHeader)
+        conditionalHeaders['if-modified-since'] = cached.lastModifiedHeader;
+    const result = await resolveDocument(url, { ...options, headers: conditionalHeaders });
+    if (result.status === 304) {
+        return { kind: 'unchanged' };
+    }
+    if (cached.bodyDigest && result.bodyDigest.toString() === cached.bodyDigest.toString()) {
+        return { kind: 'unchanged' };
+    }
+    return { kind: 'loaded', result };
+}
+//# sourceMappingURL=resolve-document-if-changed.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-document-if-changed.js","sourceRoot":"","sources":["../../src/resolvers/resolve-document-if-changed.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAgD,MAAM,uBAAuB,CAAC;AA2BtG;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,GAAW,EACX,MAAsB,EACtB,OAAgC;IAEhC,kEAAkE;IAClE,uEAAuE;IACvE,mEAAmE;IACnE,mEAAmE;IACnE,iCAAiC;IACjC,MAAM,kBAAkB,GAA2B,EAAE,CAAC;IACtD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;QAClE,kBAAkB,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,GAAG,KAAK,CAAC;IAChD,CAAC;IACD,IAAI,MAAM,CAAC,IAAI;QAAE,kBAAkB,CAAC,eAAe,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;IACnE,IAAI,MAAM,CAAC,kBAAkB;QAAE,kBAAkB,CAAC,mBAAmB,CAAC,GAAG,MAAM,CAAC,kBAAkB,CAAC;IAEnG,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAEvF,IAAI,MAAM,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC/B,CAAC;IAED,IAAI,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,KAAK,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,EAAE,CAAC;QACvF,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC/B,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AACpC,CAAC"}

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

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

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

@@ -0,0 +1,109 @@
+import { jest } from '@jest/globals';
+import { MultibaseDigest } from '../multibase-digest/index.js';
+import { ResolverNetworkError } from './errors.js';
+const resolveDocument = jest.fn();
+jest.unstable_mockModule('./resolve-document.js', () => ({
+    resolveDocument,
+}));
+const { resolveDocumentIfChanged } = await import('./resolve-document-if-changed.js');
+async function digestOf(text) {
+    return MultibaseDigest.fromData(new TextEncoder().encode(text), { algorithm: 'sha2-256', base: 'base58btc' });
+}
+function loadResult(overrides) {
+    return {
+        status: 200,
+        body: new Uint8Array(0),
+        finalUrl: '',
+        bodyDigest: overrides.bodyDigest,
+        ...overrides,
+    };
+}
+describe('resolveDocumentIfChanged', () => {
+    beforeEach(() => {
+        resolveDocument.mockReset();
+    });
+    describe('conditional headers', () => {
+        it('sends If-None-Match when cached.etag is supplied', async () => {
+            resolveDocument.mockResolvedValue(loadResult({ status: 304, bodyDigest: await digestOf('') }));
+            await resolveDocumentIfChanged('https://example.com/', { etag: '"abc"' });
+            const passedOptions = resolveDocument.mock.calls[0][1];
+            expect(passedOptions.headers['if-none-match']).toBe('"abc"');
+        });
+        it('sends If-Modified-Since when cached.lastModifiedHeader is supplied', async () => {
+            const ts = 'Wed, 21 May 2026 12:00:00 GMT';
+            resolveDocument.mockResolvedValue(loadResult({ status: 304, bodyDigest: await digestOf('') }));
+            await resolveDocumentIfChanged('https://example.com/', { lastModifiedHeader: ts });
+            const passedOptions = resolveDocument.mock.calls[0][1];
+            expect(passedOptions.headers['if-modified-since']).toBe(ts);
+        });
+        it('preserves caller-supplied headers alongside conditional ones', async () => {
+            resolveDocument.mockResolvedValue(loadResult({ status: 304, bodyDigest: await digestOf('') }));
+            await resolveDocumentIfChanged('https://example.com/', { etag: '"abc"' }, { headers: { Accept: 'application/json' } });
+            const passedOptions = resolveDocument.mock.calls[0][1];
+            expect(passedOptions.headers['accept']).toBe('application/json');
+            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"' }, 
+            // Caller passes a stale variant under a differently-cased key.
+            // The cached etag must win and only one normalised header lands on the wire.
+            { headers: { 'IF-NONE-MATCH': '"stale"' } });
+            const passedOptions = resolveDocument.mock.calls[0][1];
+            const keys = Object.keys(passedOptions.headers);
+            const ifNoneMatchKeys = keys.filter((k) => k.toLowerCase() === 'if-none-match');
+            expect(ifNoneMatchKeys).toEqual(['if-none-match']);
+            expect(passedOptions.headers['if-none-match']).toBe('"new"');
+        });
+    });
+    describe('skip chain', () => {
+        it('returns { kind: "unchanged" } on a 304 response', async () => {
+            resolveDocument.mockResolvedValue(loadResult({ status: 304, bodyDigest: await digestOf('') }));
+            await expect(resolveDocumentIfChanged('https://example.com/', { etag: '"abc"' })).resolves.toEqual({
+                kind: 'unchanged',
+            });
+        });
+        it('returns { kind: "unchanged" } on a 200 response whose body digest matches the cached one', async () => {
+            const digest = await digestOf('same content');
+            resolveDocument.mockResolvedValue(loadResult({ status: 200, body: new TextEncoder().encode('same content'), bodyDigest: digest }));
+            await expect(resolveDocumentIfChanged('https://example.com/', { bodyDigest: digest })).resolves.toEqual({
+                kind: 'unchanged',
+            });
+        });
+        it('returns { kind: "loaded", result } on a 200 response with a different body digest', async () => {
+            const oldDigest = await digestOf('old content');
+            const newDigest = await digestOf('new content');
+            const result = loadResult({
+                status: 200,
+                body: new TextEncoder().encode('new content'),
+                finalUrl: 'https://example.com/',
+                bodyDigest: newDigest,
+            });
+            resolveDocument.mockResolvedValue(result);
+            await expect(resolveDocumentIfChanged('https://example.com/', { bodyDigest: oldDigest })).resolves.toEqual({
+                kind: 'loaded',
+                result,
+            });
+        });
+        it('returns { kind: "loaded", result } on a 200 response when no cached body digest is supplied', async () => {
+            const result = loadResult({
+                status: 200,
+                body: new TextEncoder().encode('fresh'),
+                finalUrl: 'https://example.com/',
+                bodyDigest: await digestOf('fresh'),
+            });
+            resolveDocument.mockResolvedValue(result);
+            await expect(resolveDocumentIfChanged('https://example.com/', { etag: '"abc"' })).resolves.toEqual({
+                kind: 'loaded',
+                result,
+            });
+        });
+    });
+    describe('error propagation', () => {
+        it('propagates errors thrown by the underlying resolveDocument call', async () => {
+            resolveDocument.mockRejectedValue(new ResolverNetworkError('https://example.com/', new Error('boom')));
+            await expect(resolveDocumentIfChanged('https://example.com/', {})).rejects.toBeInstanceOf(ResolverNetworkError);
+        });
+    });
+});
+//# sourceMappingURL=resolve-document-if-changed.test.js.map

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

@@ -0,0 +1 @@
+{"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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"}