@uncefact/untp-utils 0.1.0 → 0.3.0

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,116 @@
+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('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"' }, 
+            // 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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"}

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

@@ -0,0 +1,106 @@
+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})
+ * when the caller does not supply a value.
+ */
+export declare const RESOLVER_DEFAULTS: {
+    /** Body-size cap in bytes; exceeding throws {@link ResolverTooLargeError}. */
+    readonly maxResponseBytes: 1048576;
+    /** Total 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;
+    /** Multibase digest algorithm used to hash response bodies. */
+    readonly digestAlgorithm: "sha2-256";
+    /** Multibase encoding used for response body digests. */
+    readonly digestEncoding: "base58btc";
+};
+/**
+ * Result of a fetch that produced a final response (any non-redirect status,
+ * including `304 Not Modified`).
+ *
+ * Only an allowlisted subset of response headers is exposed (the ones
+ * downstream consumers need: `etag` and `last-modified` for the conditional-
+ * fetch skip chain, `content-type` for body-type checks).
+ *
+ * All fields are `readonly`: a `LoadResult` is a frozen snapshot of one
+ * fetch and must not be mutated by consumers.
+ */
+export interface LoadResult {
+    /** Final URL after redirect chasing (matches `url` when there were no redirects). */
+    readonly finalUrl: string;
+    /** HTTP status code of the final response (the redirect chain terminator, or `304`). */
+    readonly status: number;
+    /** Raw response body bytes. */
+    readonly body: Uint8Array;
+    /** Multibase digest of {@link body} (algorithm/encoding per {@link RESOLVER_DEFAULTS}). */
+    readonly bodyDigest: MultibaseDigest;
+    /** The response's `ETag` header if present. */
+    readonly etag?: string;
+    /** The response's `Last-Modified` header if present. */
+    readonly lastModified?: string;
+    /** The response's `Content-Type` header if present. */
+    readonly contentType?: string;
+}
+/**
+ * Options accepted by {@link resolveDocument} and
+ * {@link import('./resolve-document-if-changed.js').resolveDocumentIfChanged}.
+ *
+ * Header keys are case-insensitive on the wire; `resolveDocumentIfChanged`
+ * lowercases all keys before merging and reserves `if-none-match` /
+ * `if-modified-since` for its conditional-fetch wiring.
+ */
+export interface ResolveDocumentOptions {
+    /** Override {@link RESOLVER_DEFAULTS.maxResponseBytes}. */
+    maxResponseBytes?: number;
+    /** Override {@link RESOLVER_DEFAULTS.totalTimeoutMs}. */
+    totalTimeoutMs?: number;
+    /** Override {@link RESOLVER_DEFAULTS.maxRedirects}. */
+    maxRedirects?: number;
+    /** Additional headers to send with the request (e.g. `Accept`). */
+    headers?: Record<string, string>;
+    /** Allowed URL schemes (forwarded to {@link import('../node/index.js').validatePublicUrl}). */
+    allowedSchemes?: readonly string[];
+    /** 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 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.
+ *
+ * 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`, 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
+ */
+export declare function resolveDocument(url: string, options?: ResolveDocumentOptions): Promise<LoadResult>;

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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"}