@uncefact/untp-utils 0.1.0 → 0.3.0

package/build/node/is-private-ip.js.map

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

package/build/node/is-private-ip.test.d.ts

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

package/build/node/is-private-ip.test.js

@@ -0,0 +1,124 @@
+import { isPrivateHostname, isPrivateIpv4, isPrivateIpv6 } from './is-private-ip.js';
+describe('isPrivateIpv4', () => {
+    it.each([['1.1.1.1'], ['8.8.8.8'], ['151.101.0.1']])('returns false for the unmistakeably public address %s', (addr) => {
+        expect(isPrivateIpv4(addr)).toBe(false);
+    });
+    it.each([
+        ['0.0.0.0'], // unspecified
+        ['10.0.0.1'], // RFC 1918
+        ['10.255.255.255'],
+        ['100.64.0.1'], // CGNAT
+        ['127.0.0.1'], // loopback
+        ['127.255.255.255'],
+        ['169.254.0.1'], // link-local
+        ['169.254.169.254'], // cloud metadata (AWS/GCP/Azure)
+        ['172.16.0.1'], // RFC 1918
+        ['172.31.255.255'],
+        ['192.168.0.1'], // RFC 1918
+        ['192.168.255.255'],
+        ['224.0.0.1'], // multicast
+        ['255.255.255.255'], // broadcast
+        ['198.18.0.1'], // benchmarking
+        ['203.0.113.1'], // TEST-NET-3 (reserved)
+        ['100.100.100.200'], // Alibaba Cloud metadata (publicly routable, but explicitly blocked)
+    ])('returns true for the private/reserved/metadata address %s', (addr) => {
+        expect(isPrivateIpv4(addr)).toBe(true);
+    });
+    it('returns false for non-IPv4 input', () => {
+        expect(isPrivateIpv4('not an ip')).toBe(false);
+        expect(isPrivateIpv4('::1')).toBe(false);
+        expect(isPrivateIpv4('')).toBe(false);
+    });
+});
+describe('isPrivateIpv6', () => {
+    it.each([
+        ['2606:4700:4700::1111'], // Cloudflare public DNS
+        ['2001:4860:4860::8888'], // Google public DNS
+    ])('returns false for the unmistakeably public address %s', (addr) => {
+        expect(isPrivateIpv6(addr)).toBe(false);
+    });
+    it.each([
+        ['::'], // unspecified
+        ['::1'], // loopback
+        ['fe80::1'], // link-local
+        ['fc00::1'], // unique local
+        ['fd00::1'], // unique local
+        ['ff02::1'], // multicast
+        ['2001:db8::1'], // documentation / reserved
+        ['2002::1'], // 6to4
+    ])('returns true for the non-public address %s', (addr) => {
+        expect(isPrivateIpv6(addr)).toBe(true);
+    });
+    it('treats IPv4-mapped IPv6 addresses by their embedded IPv4 status', () => {
+        expect(isPrivateIpv6('::ffff:127.0.0.1')).toBe(true);
+        expect(isPrivateIpv6('::ffff:169.254.169.254')).toBe(true);
+        expect(isPrivateIpv6('::ffff:1.1.1.1')).toBe(false);
+    });
+    it.each([
+        ['::7f00:1'], // IPv4-compatible wrapping 127.0.0.1
+        ['::a9fe:a9fe'], // IPv4-compatible wrapping 169.254.169.254
+        ['::5db8:d822'], // IPv4-compatible wrapping a public address: still deprecated, non-routing space
+        ['::127.0.0.1'], // dotted spelling of the compatible form (ipaddr.js rewrites it to mapped)
+        ['::93.184.216.34'], // dotted compatible wrapping a public address
+        ['::1.1.1.1%lo0'], // zone-indexed dotted compatible (ipaddr.js rewrites this spelling too)
+        ['::93.184.216.34%eth0'], // zone-indexed dotted compatible wrapping a public address
+    ])('rejects the deprecated IPv4-compatible form %s regardless of the embedded address', (addr) => {
+        expect(isPrivateIpv6(addr)).toBe(true);
+    });
+    it('treats the hex-group mapped form the same as the dotted mapped form', () => {
+        // `URL.hostname` canonicalises `[::ffff:127.0.0.1]` to `[::ffff:7f00:1]`,
+        // so the hex-group encoding is the one URL-derived callers present.
+        expect(isPrivateIpv6('::ffff:7f00:1')).toBe(true);
+        expect(isPrivateIpv6('::ffff:101:101')).toBe(false); // 1.1.1.1
+        // Control: the zone-suffix handling must not start denying mapped-public.
+        expect(isPrivateIpv6('::ffff:1.1.1.1')).toBe(false);
+    });
+    it.each([
+        ['4000::1'], // unallocated, outside 2000::/3
+        ['fe00::1'], // reserved, outside 2000::/3
+        ['101::1'], // unallocated, outside 2000::/3
+        ['100:0:0:1::1'], // discard-only 100::/64 sibling space
+        ['3ffe::1'], // decommissioned 6bone block inside 2000::/3
+    ])('rejects the reserved or unallocated address %s that ipaddr.js has no named range for', (addr) => {
+        expect(isPrivateIpv6(addr)).toBe(true);
+    });
+    it('returns false for non-IPv6 input', () => {
+        expect(isPrivateIpv6('not an ip')).toBe(false);
+        expect(isPrivateIpv6('10.0.0.1')).toBe(false);
+        expect(isPrivateIpv6('')).toBe(false);
+    });
+});
+describe('isPrivateHostname', () => {
+    it.each([
+        [''],
+        ['localhost'],
+        ['LOCALHOST'],
+        ['foo.localhost'],
+        ['bar.local'],
+        ['printer.local.'], // trailing dot is stripped
+        ['db.internal'],
+        ['svc.intranet'],
+        ['file-server.lan'],
+        ['router.home'],
+        ['app.corp'],
+        ['vault.private'],
+    ])('returns true for the private hostname %s', (host) => {
+        expect(isPrivateHostname(host)).toBe(true);
+    });
+    it.each([['example.com'], ['api.cloudflare.com'], ['google.com.']])('returns false for the public hostname %s', (host) => {
+        expect(isPrivateHostname(host)).toBe(false);
+    });
+    it('defers to IP predicates when the hostname is an IP literal', () => {
+        expect(isPrivateHostname('127.0.0.1')).toBe(true);
+        expect(isPrivateHostname('169.254.169.254')).toBe(true);
+        expect(isPrivateHostname('::1')).toBe(true);
+        expect(isPrivateHostname('1.1.1.1')).toBe(false);
+        expect(isPrivateHostname('2606:4700:4700::1111')).toBe(false);
+    });
+    it('handles IPv6 literals wrapped in brackets (as URL.hostname returns)', () => {
+        expect(isPrivateHostname('[::1]')).toBe(true);
+        expect(isPrivateHostname('[fc00::1]')).toBe(true);
+        expect(isPrivateHostname('[2606:4700:4700::1111]')).toBe(false);
+    });
+});
+//# sourceMappingURL=is-private-ip.test.js.map

package/build/node/is-private-ip.test.js.map

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

package/build/node/validate-public-url.d.ts

@@ -0,0 +1,81 @@
+import type { LookupAddress, LookupAllOptions } from 'node:dns';
+/**
+ * Options for {@link validatePublicUrl}.
+ */
+export interface ValidatePublicUrlOptions {
+    /**
+     * URL schemes that are allowed (e.g. `['http', 'https']`). Compared
+     * case-insensitively. Defaults to `['http', 'https']`.
+     */
+    allowedSchemes?: readonly string[];
+    /**
+     * IP family hint passed to `dns.lookup`. `0` (default) returns whichever
+     * family the resolver prefers, `4` forces IPv4-only, `6` forces IPv6-only.
+     */
+    family?: 0 | 4 | 6;
+    /** Permit private, loopback and reserved hostnames and addresses. Defaults to strict rejection. */
+    allowPrivateAddresses?: boolean;
+    /**
+     * Lookup implementation used for hostname resolution. This is a test and
+     * diagnostics seam, not a policy switch: every returned address still goes
+     * through the hostname and address guard below. Omitted uses Node's default
+     * `node:dns/promises` lookup.
+     */
+    lookup?: PublicUrlLookup;
+}
+/** Node lookup result shape used when validating all addresses for a hostname. */
+export type PublicUrlLookup = (hostname: string, options: LookupAllOptions) => Promise<LookupAddress[]>;
+/**
+ * The resolved address that callers must use as the connect target so the
+ * connection lands on the IP that validation checked. Connecting via the
+ * hostname instead opens a DNS rebinding window.
+ */
+export interface ResolvedAddress {
+    address: string;
+    family: 4 | 6;
+}
+/**
+ * The validated address set for one hostname, in resolver order. Callers must
+ * connect only to these addresses, so the connection lands on IPs that
+ * validation checked.
+ *
+ * `address` and `family` repeat the first entry of `addresses`, so a caller
+ * that can use only one connect target keeps working unchanged. A caller that
+ * can offer several targets to its connector should hand it the whole of
+ * `addresses`: a name such as `localhost` resolves to both `::1` and
+ * `127.0.0.1`, and only one of them may have a listener, so pinning the first
+ * alone refuses a connection an unpinned request would have made.
+ */
+export interface ValidatedAddresses extends ResolvedAddress {
+    addresses: readonly ResolvedAddress[];
+}
+/**
+ * Validates that `url` is a parseable HTTP(S) URL whose hostname resolves
+ * to publicly routable IP addresses, and returns the validated address set,
+ * pinned by the resolver, for the caller to use as its connect targets. When
+ * `allowPrivateAddresses` is exactly `true`, private and reserved destinations
+ * are permitted while the other validation and pinning rules remain active.
+ *
+ * DNS resolution is performed with `all: true`; in strict mode the URL is
+ * rejected if any resolved address is in a private / loopback / link-local /
+ * cloud-metadata range, so a mixed public/private DNS response cannot sneak a
+ * private record through. `addresses` therefore holds every structurally valid
+ * record, in resolver order: in strict mode all of them are public, because a
+ * private one has already thrown, and in relaxed mode all of them. `address`
+ * and `family` repeat the first entry.
+ *
+ * Per ADR-035, this function throws subclasses of {@link UrlValidationError}
+ * on failure. The structured payload (`code`, `message`, `received`,
+ * `expected`, `remediation`, `pointer`, `cause`) is available on the thrown
+ * instance.
+ *
+ * @see https://owasp.org/www-community/attacks/Server_Side_Request_Forgery
+ * @see ../../../docs/adrs/035-utils-throws-structured-errors.md
+ * @throws {InvalidUrlError} `url` is not a parseable URL, or has no hostname.
+ * @throws {UnsupportedSchemeError} the URL's scheme is not allowed.
+ * @throws {PrivateHostnameError} the hostname names a private resource in strict mode.
+ * @throws {ResolutionFailedError} DNS resolution rejected, or the resolver returned an unparseable or family-contradictory record.
+ * @throws {ResolutionEmptyError} DNS resolution returned no records.
+ * @throws {PrivateAddressError} any resolved record is private in strict mode.
+ */
+export declare function validatePublicUrl(url: string, options?: ValidatePublicUrlOptions): Promise<ValidatedAddresses>;

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

@@ -0,0 +1,128 @@
+import { isIP } from 'node:net';
+import { lookup as dnsLookup } from 'node:dns/promises';
+import { isPrivateHostname, isPrivateIpv4, isPrivateIpv6 } from './is-private-ip.js';
+import { InvalidUrlError, PrivateAddressError, PrivateHostnameError, ResolutionEmptyError, ResolutionFailedError, UnsupportedSchemeError, } from './errors.js';
+const DEFAULT_ALLOWED_SCHEMES = ['http', 'https'];
+/**
+ * Validates that `url` is a parseable HTTP(S) URL whose hostname resolves
+ * to publicly routable IP addresses, and returns the validated address set,
+ * pinned by the resolver, for the caller to use as its connect targets. When
+ * `allowPrivateAddresses` is exactly `true`, private and reserved destinations
+ * are permitted while the other validation and pinning rules remain active.
+ *
+ * DNS resolution is performed with `all: true`; in strict mode the URL is
+ * rejected if any resolved address is in a private / loopback / link-local /
+ * cloud-metadata range, so a mixed public/private DNS response cannot sneak a
+ * private record through. `addresses` therefore holds every structurally valid
+ * record, in resolver order: in strict mode all of them are public, because a
+ * private one has already thrown, and in relaxed mode all of them. `address`
+ * and `family` repeat the first entry.
+ *
+ * Per ADR-035, this function throws subclasses of {@link UrlValidationError}
+ * on failure. The structured payload (`code`, `message`, `received`,
+ * `expected`, `remediation`, `pointer`, `cause`) is available on the thrown
+ * instance.
+ *
+ * @see https://owasp.org/www-community/attacks/Server_Side_Request_Forgery
+ * @see ../../../docs/adrs/035-utils-throws-structured-errors.md
+ * @throws {InvalidUrlError} `url` is not a parseable URL, or has no hostname.
+ * @throws {UnsupportedSchemeError} the URL's scheme is not allowed.
+ * @throws {PrivateHostnameError} the hostname names a private resource in strict mode.
+ * @throws {ResolutionFailedError} DNS resolution rejected, or the resolver returned an unparseable or family-contradictory record.
+ * @throws {ResolutionEmptyError} DNS resolution returned no records.
+ * @throws {PrivateAddressError} any resolved record is private in strict mode.
+ */
+export async function validatePublicUrl(url, options) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch (cause) {
+        throw new InvalidUrlError(url, cause);
+    }
+    const allowedSchemes = options?.allowedSchemes ?? DEFAULT_ALLOWED_SCHEMES;
+    const allowPrivateAddresses = options?.allowPrivateAddresses === true;
+    const scheme = parsed.protocol.toLowerCase().replace(/:$/, '');
+    if (!allowedSchemes.some((s) => s.toLowerCase() === scheme)) {
+        throw new UnsupportedSchemeError(scheme, allowedSchemes);
+    }
+    // URL.hostname wraps IPv6 literals in brackets (e.g. `[::1]`); strip them
+    // so the hostname can be passed to predicates and DNS resolution. Note
+    // that `URL` already discards any `userinfo@` prefix from the hostname, so
+    // a smuggling attempt like `http://evil.com@127.0.0.1/` is checked and
+    // connected as `127.0.0.1`, never as `evil.com`. In strict mode
+    // `isPrivateHostname` below then refuses it; in relaxed mode the private
+    // test does not run, and the destination is permitted as any other private
+    // destination is. Refusing the userinfo itself is not this function's job in
+    // either mode: for user-submitted URLs the RI's request schema rejects one
+    // that carries userinfo, and undici does not send credentials it was not
+    // asked for. URLs this function is given from elsewhere (did:web resolution,
+    // for instance) pass through no such schema, so that first clause covers the
+    // caller-supplied case only.
+    const hostname = parsed.hostname.replace(/^\[|\]$/g, '');
+    // A URL with no authority is malformed input, not a private destination, so
+    // it is reported as an invalid URL in both modes. Refusing it here keeps the
+    // function total: with no hostname there is nothing to resolve and nothing to
+    // pin, so returning normally would hand the caller an unpinned fetch.
+    if (!hostname) {
+        throw new InvalidUrlError(url, new Error('URL has no hostname.'));
+    }
+    if (!allowPrivateAddresses && isPrivateHostname(hostname)) {
+        throw new PrivateHostnameError(hostname);
+    }
+    // If the hostname is already an IP literal, skip DNS resolution: the
+    // literal itself is the resolved address, so there is nothing to look up.
+    // In strict mode `isPrivateHostname` above has already refused a private
+    // literal. In relaxed mode that test did not run, which is the point of the
+    // mode: the literal is returned and pinned without a private-range check.
+    const literalFamily = isIP(hostname);
+    if (literalFamily === 4 || literalFamily === 6) {
+        return { address: hostname, family: literalFamily, addresses: [{ address: hostname, family: literalFamily }] };
+    }
+    let records;
+    try {
+        const lookup = options?.lookup ?? dnsLookup;
+        records = await lookup(hostname, { family: options?.family ?? 0, all: true });
+    }
+    catch (cause) {
+        throw new ResolutionFailedError(hostname, cause);
+    }
+    if (records.length === 0) {
+        throw new ResolutionEmptyError(hostname);
+    }
+    const privateRecords = [];
+    const validRecords = [];
+    for (const record of records) {
+        // Derive the record's family from the address string itself rather than
+        // trusting `record.family` (typed as a bare `number`, and DNS resolvers
+        // have shipped bugs that misreport it). A record whose address does not
+        // parse as an IP at all, or whose derived family disagrees with the
+        // resolver's claim, is contradictory metadata and is rejected outright
+        // rather than silently reconciled.
+        const derivedFamily = isIP(record.address);
+        if ((derivedFamily !== 4 && derivedFamily !== 6) || derivedFamily !== record.family) {
+            throw new ResolutionFailedError(hostname, new Error(`resolver returned a contradictory or unparseable record: ${record.address} (family ${record.family})`));
+        }
+        const isPrivate = derivedFamily === 4 ? isPrivateIpv4(record.address) : isPrivateIpv6(record.address);
+        validRecords.push({ address: record.address, family: derivedFamily });
+        if (isPrivate && !allowPrivateAddresses) {
+            privateRecords.push(record.address);
+        }
+    }
+    if (!allowPrivateAddresses && privateRecords.length > 0) {
+        throw new PrivateAddressError(hostname, privateRecords);
+    }
+    // Defensive: every record either throws above or is collected, so
+    // `records.length > 0` implies `validRecords` is non-empty. That reasoning
+    // holds in both modes; the pre-relaxation version reasoned from a public
+    // record existing, which is no longer what the loop collects. Throwing
+    // rather than `!`-asserting keeps the invariant explicit at the boundary. It
+    // throws a plain Error rather than a resolution failure so a defect in this
+    // loop can never be classified as a retryable DNS fault by a caller.
+    const [first] = validRecords;
+    if (!first) {
+        throw new Error('validatePublicUrl invariant: no record selected');
+    }
+    return { address: first.address, family: first.family, addresses: validRecords };
+}
+//# sourceMappingURL=validate-public-url.js.map

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

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

package/build/node/validate-public-url.test.d.ts

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