@venizia/ignis-helpers 0.2.0-9 → 0.2.0

package/dist/cjs/modules/network/utilities/url-safety/common/constants.d.ts

@@ -0,0 +1,18 @@
+import { TConstValue } from '../../../../../common/types';
+/** The only schemes a guarded fetch will speak. `file:` and `gopher:` are the classic SSRF pivots. */
+export declare class UrlSchemes {
+    static readonly HTTP = "http:";
+    static readonly HTTPS = "https:";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(value: string): boolean;
+}
+export type TUrlScheme = TConstValue<typeof UrlSchemes>;
+/** Safe by default: https only, no private address, three hops, ten seconds. */
+export declare class UrlSafetyDefaults {
+    static readonly ALLOWED_SCHEMES: string[];
+    static readonly ALLOW_PRIVATE_ADDRESS = false;
+    static readonly MAX_REDIRECTS = 3;
+    static readonly TIMEOUT_MILLISECONDS = 10000;
+    static readonly MAX_BYTES: number;
+}
+//# sourceMappingURL=constants.d.ts.map

package/dist/cjs/modules/network/utilities/url-safety/common/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,sGAAsG;AACtG,qBAAa,UAAU;IACrB,MAAM,CAAC,QAAQ,CAAC,IAAI,WAAW;IAC/B,MAAM,CAAC,QAAQ,CAAC,KAAK,YAAY;IAEjC,MAAM,CAAC,QAAQ,CAAC,UAAU,cAA4C;IAEtE,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAGvC;AACD,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,UAAU,CAAC,CAAC;AAExD,gFAAgF;AAChF,qBAAa,iBAAiB;IAC5B,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,CAAsB;IAC/D,MAAM,CAAC,QAAQ,CAAC,qBAAqB,SAAS;IAC9C,MAAM,CAAC,QAAQ,CAAC,aAAa,KAAK;IAClC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,SAAU;IAC9C,MAAM,CAAC,QAAQ,CAAC,SAAS,SAAoB;CAC9C"}

package/dist/cjs/modules/network/utilities/url-safety/common/constants.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UrlSafetyDefaults = exports.UrlSchemes = void 0;
+/** The only schemes a guarded fetch will speak. `file:` and `gopher:` are the classic SSRF pivots. */
+class UrlSchemes {
+    static { this.HTTP = 'http:'; }
+    static { this.HTTPS = 'https:'; }
+    static { this.SCHEME_SET = new Set([this.HTTP, this.HTTPS]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
+}
+exports.UrlSchemes = UrlSchemes;
+/** Safe by default: https only, no private address, three hops, ten seconds. */
+class UrlSafetyDefaults {
+    static { this.ALLOWED_SCHEMES = [UrlSchemes.HTTPS]; }
+    static { this.ALLOW_PRIVATE_ADDRESS = false; }
+    static { this.MAX_REDIRECTS = 3; }
+    static { this.TIMEOUT_MILLISECONDS = 10_000; }
+    static { this.MAX_BYTES = 10 * 1024 * 1024; }
+}
+exports.UrlSafetyDefaults = UrlSafetyDefaults;
+//# sourceMappingURL=constants.js.map

package/dist/cjs/modules/network/utilities/url-safety/common/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/constants.ts"],"names":[],"mappings":";;;AAEA,sGAAsG;AACtG,MAAa,UAAU;aACL,SAAI,GAAG,OAAO,CAAC;aACf,UAAK,GAAG,QAAQ,CAAC;aAEjB,eAAU,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAEtE,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AARH,gCASC;AAGD,gFAAgF;AAChF,MAAa,iBAAiB;aACZ,oBAAe,GAAa,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;aAC/C,0BAAqB,GAAG,KAAK,CAAC;aAC9B,kBAAa,GAAG,CAAC,CAAC;aAClB,yBAAoB,GAAG,MAAM,CAAC;aAC9B,cAAS,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;;AAL/C,8CAMC"}

package/dist/cjs/modules/network/utilities/url-safety/common/errors.d.ts

@@ -0,0 +1,31 @@
+import type { TRegisterErrors } from '@venizia/ignis-inversion';
+/**
+ * A url the policy refuses is refused forever - the same url will never be allowed. A caller that
+ * retries on failure has to tell that apart from a host that timed out, or it retries a rejection
+ * and turns the guard into a repeat scanner.
+ */
+export declare const UrlSafetyErrors: {
+    readonly URL_REFUSED: {
+        readonly message: {
+            readonly text: "Url refused by the safety policy";
+            readonly code: "core.url_safety.url_refused";
+        };
+        readonly statusCode: 400;
+        readonly category: "business";
+    };
+};
+declare module '@venizia/ignis-inversion' {
+    interface IErrorKeyRegistry extends TRegisterErrors<typeof UrlSafetyErrors> {
+    }
+}
+/**
+ * True when the url will never be allowed, whatever happens next: a bad scheme, a non-public
+ * address, a host outside the allow-list, a malformed url, or too many hops. Retrying any of those
+ * repeats the same rejection - drop the work instead.
+ *
+ * A timeout, a DNS failure or a 5xx answers `false`: those are worth another attempt.
+ */
+export declare const isUrlRefusedError: (opts: {
+    error: unknown;
+}) => boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/modules/network/utilities/url-safety/common/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/errors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAoB,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAGlF;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;;;;;CAMyB,CAAC;AAEtD,OAAO,QAAQ,0BAA0B,CAAC;IACxC,UAAU,iBAAkB,SAAQ,eAAe,CAAC,OAAO,eAAe,CAAC;KAAG;CAC/E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,KAAG,OAG5D,CAAC"}

package/dist/cjs/modules/network/utilities/url-safety/common/errors.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isUrlRefusedError = exports.UrlSafetyErrors = void 0;
+const constants_1 = require("../../../../../common/constants");
+const ignis_inversion_1 = require("@venizia/ignis-inversion");
+/**
+ * A url the policy refuses is refused forever - the same url will never be allowed. A caller that
+ * retries on failure has to tell that apart from a host that timed out, or it retries a rejection
+ * and turns the guard into a repeat scanner.
+ */
+exports.UrlSafetyErrors = {
+    URL_REFUSED: {
+        message: { text: 'Url refused by the safety policy', code: 'core.url_safety.url_refused' },
+        statusCode: constants_1.HTTP.ResultCodes.RS_4.BadRequest,
+        category: ignis_inversion_1.ErrorScopes.BUSINESS,
+    },
+};
+/**
+ * True when the url will never be allowed, whatever happens next: a bad scheme, a non-public
+ * address, a host outside the allow-list, a malformed url, or too many hops. Retrying any of those
+ * repeats the same rejection - drop the work instead.
+ *
+ * A timeout, a DNS failure or a 5xx answers `false`: those are worth another attempt.
+ */
+const isUrlRefusedError = (opts) => {
+    const source = opts.error;
+    return source?.normalized?.code === exports.UrlSafetyErrors.URL_REFUSED.message.code;
+};
+exports.isUrlRefusedError = isUrlRefusedError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/modules/network/utilities/url-safety/common/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/errors.ts"],"names":[],"mappings":";;;AAAA,kDAA0C;AAE1C,8DAAuD;AAEvD;;;;GAIG;AACU,QAAA,eAAe,GAAG;IAC7B,WAAW,EAAE;QACX,OAAO,EAAE,EAAE,IAAI,EAAE,kCAAkC,EAAE,IAAI,EAAE,6BAA6B,EAAE;QAC1F,UAAU,EAAE,gBAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU;QAC5C,QAAQ,EAAE,6BAAW,CAAC,QAAQ;KAC/B;CACkD,CAAC;AAMtD;;;;;;GAMG;AACI,MAAM,iBAAiB,GAAG,CAAC,IAAwB,EAAW,EAAE;IACrE,MAAM,MAAM,GAAG,IAAI,CAAC,KAA2C,CAAC;IAChE,OAAO,MAAM,EAAE,UAAU,EAAE,IAAI,KAAK,uBAAe,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC;AAC/E,CAAC,CAAC;AAHW,QAAA,iBAAiB,qBAG5B"}

package/dist/cjs/modules/network/utilities/url-safety/common/index.d.ts

@@ -0,0 +1,4 @@
+export * from './constants';
+export * from './errors';
+export * from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/modules/network/utilities/url-safety/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}

package/dist/cjs/modules/network/utilities/url-safety/common/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./constants"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./types"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/modules/network/utilities/url-safety/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,2CAAyB;AACzB,0CAAwB"}

package/dist/cjs/modules/network/utilities/url-safety/common/types.d.ts

@@ -0,0 +1,24 @@
+import type { IDuration } from '../../../../../common/constants/duration';
+/**
+ * What a caller will accept from an untrusted url. Every field is per call: an app that must reach
+ * plain `http` says so at the call site rather than weakening a build-time constant for everyone.
+ */
+export interface IUrlSafetyPolicy {
+    /** Defaults to `['https:']`. */
+    allowedSchemes?: string[];
+    /**
+     * Defaults to `false`. Turning it on in a path that takes urls from user input re-opens the
+     * server-side request forgery this guard exists to close - a request can then be steered at
+     * `169.254.169.254` and the cloud credentials behind it.
+     */
+    allowPrivateAddress?: boolean;
+    /** When set, nothing outside the list passes, whatever it resolves to. */
+    allowedHosts?: string[];
+    /** Defaults to 3. Each hop is re-checked, so a public host cannot bounce into a private one. */
+    maxRedirects?: number;
+    /** Defaults to 10 seconds. A slow host holds a worker slot for exactly this long. */
+    timeout?: IDuration;
+    /** Defaults to 10 MB. The read stops and cancels the moment the body crosses it. */
+    maxBytes?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/modules/network/utilities/url-safety/common/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,qFAAqF;IACrF,OAAO,CAAC,EAAE,SAAS,CAAC;IAEpB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/cjs/modules/network/utilities/url-safety/common/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/modules/network/utilities/url-safety/common/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../../src/modules/network/utilities/url-safety/common/types.ts"],"names":[],"mappings":""}

package/dist/cjs/modules/network/utilities/url-safety/index.d.ts

@@ -0,0 +1,4 @@
+export * from './common';
+export * from './policy';
+export * from './ingest';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/modules/network/utilities/url-safety/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/network/utilities/url-safety/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}

package/dist/cjs/modules/network/utilities/url-safety/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./common"), exports);
+__exportStar(require("./policy"), exports);
+__exportStar(require("./ingest"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/modules/network/utilities/url-safety/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/modules/network/utilities/url-safety/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,2CAAyB;AACzB,2CAAyB"}

package/dist/cjs/modules/network/utilities/url-safety/ingest.d.ts

@@ -0,0 +1,52 @@
+import type { IUrlSafetyPolicy } from './common/types';
+/** Fetching an untrusted url without letting it reach inside the network. */
+export declare class UrlIngest {
+    /**
+     * Rejects when ANY resolved address is non-public. Checking only the first walks straight into a
+     * host that publishes one public A record beside an internal one.
+     *
+     * A rebinding window remains: the address can change between this check and the connect. Closing
+     * it means connecting to the resolved address and setting `Host` by hand, which no fetch API
+     * exposes.
+     */
+    static assertPublicHost(opts: {
+        hostname: string;
+        policy?: IUrlSafetyPolicy;
+    }): Promise<void>;
+    /** Both halves, in the order they must run: shape first, then the network. */
+    static assertReachableUrl(opts: {
+        url: string;
+        policy?: IUrlSafetyPolicy;
+    }): Promise<URL>;
+    private static readTimeoutMilliseconds;
+    /**
+     * A GET that an untrusted url cannot steer inside the network. Redirects are followed by hand so
+     * every hop is re-checked - `redirect: 'follow'` would land on an internal host with no second
+     * look.
+     *
+     * The body is returned unread: the caller decides whether to stream it onward or cap it with
+     * {@link UrlIngest.readCappedBody}. Nothing is buffered here.
+     */
+    static fetchGuarded(opts: {
+        url: string;
+        policy?: IUrlSafetyPolicy;
+        headers?: Record<string, string>;
+    }): Promise<Response>;
+    /**
+     * Enforces `maxBytes` on a stream nothing reads into this process - the shape a caller wants when
+     * the body is piped onward rather than held. Without it a `maxBytes` policy is inert on that path.
+     */
+    static capStream(opts: {
+        source: ReadableStream<Uint8Array>;
+        policy?: IUrlSafetyPolicy;
+    }): ReadableStream<Uint8Array>;
+    /**
+     * Reads a body that must not exceed `maxBytes`, cancelling the moment it does. `content-length` is
+     * checked first because it is free, and counted anyway because it may be absent or lie.
+     */
+    static readCappedBody(opts: {
+        response: Response;
+        policy?: IUrlSafetyPolicy;
+    }): Promise<Buffer>;
+}
+//# sourceMappingURL=ingest.d.ts.map

package/dist/cjs/modules/network/utilities/url-safety/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/network/utilities/url-safety/ingest.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvD,6EAA6E;AAC7E,qBAAa,SAAS;IACpB;;;;;;;OAOG;WACU,gBAAgB,CAAC,IAAI,EAAE;QAClC,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,gBAAgB,CAAC;KAC3B,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BjB,8EAA8E;WACjE,kBAAkB,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC;IAM/F,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAMtC;;;;;;;OAOG;WACU,YAAY,CAAC,IAAI,EAAE;QAC9B,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,CAAC,EAAE,gBAAgB,CAAC;QAC1B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,QAAQ,CAAC;IAgDrB;;;OAGG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE;QACrB,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;QACnC,MAAM,CAAC,EAAE,gBAAgB,CAAC;KAC3B,GAAG,cAAc,CAAC,UAAU,CAAC;IA0B9B;;;OAGG;WACU,cAAc,CAAC,IAAI,EAAE;QAChC,QAAQ,EAAE,QAAQ,CAAC;QACnB,MAAM,CAAC,EAAE,gBAAgB,CAAC;KAC3B,GAAG,OAAO,CAAC,MAAM,CAAC;CA2CpB"}

package/dist/cjs/modules/network/utilities/url-safety/ingest.js

@@ -0,0 +1,167 @@
+"use strict";
+// The half `policy.ts` cannot do: resolving a hostname needs `node:dns`, so nothing here may be
+// re-exported from the `./core` subpath.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UrlIngest = void 0;
+const duration_1 = require("../../../../common/constants/duration");
+const error_1 = require("../../../error");
+const promises_1 = require("node:dns/promises");
+const constants_1 = require("./common/constants");
+const errors_1 = require("./common/errors");
+const policy_1 = require("./policy");
+/** Fetching an untrusted url without letting it reach inside the network. */
+class UrlIngest {
+    /**
+     * Rejects when ANY resolved address is non-public. Checking only the first walks straight into a
+     * host that publishes one public A record beside an internal one.
+     *
+     * A rebinding window remains: the address can change between this check and the connect. Closing
+     * it means connecting to the resolved address and setting `Host` by hand, which no fetch API
+     * exposes.
+     */
+    static async assertPublicHost(opts) {
+        const { hostname, policy } = opts;
+        if (policy?.allowPrivateAddress ?? constants_1.UrlSafetyDefaults.ALLOW_PRIVATE_ADDRESS) {
+            return;
+        }
+        // `URL.hostname` keeps the brackets on an IPv6 literal; `lookup` does not accept them, and the
+        // ENOTFOUND that follows reads as a transient DNS failure rather than the refusal it should be.
+        const address = policy_1.UrlPolicy.readHostAddress({ hostname });
+        const addresses = await (0, promises_1.lookup)(address, { all: true });
+        if (!addresses.length) {
+            throw (0, error_1.getError)({
+                error: errors_1.UrlSafetyErrors.URL_REFUSED,
+                message: `[assertPublicHost] Host resolves to nothing | host: ${hostname}`,
+            });
+        }
+        const offender = addresses.find(entry => policy_1.UrlPolicy.isNonPublicAddress({ address: entry.address }));
+        if (offender) {
+            throw (0, error_1.getError)({
+                error: errors_1.UrlSafetyErrors.URL_REFUSED,
+                message: `[assertPublicHost] Host resolves to a non-public address | host: ${hostname} | address: ${offender.address}`,
+            });
+        }
+    }
+    /** Both halves, in the order they must run: shape first, then the network. */
+    static async assertReachableUrl(opts) {
+        const parsed = policy_1.UrlPolicy.assertSafeUrl(opts);
+        await UrlIngest.assertPublicHost({ hostname: parsed.hostname, policy: opts.policy });
+        return parsed;
+    }
+    static readTimeoutMilliseconds(opts) {
+        const { timeout } = opts.policy ?? {};
+        const milliseconds = timeout ? duration_1.DurationMultipliers.toMilliseconds(timeout) : null;
+        return milliseconds ?? constants_1.UrlSafetyDefaults.TIMEOUT_MILLISECONDS;
+    }
+    /**
+     * A GET that an untrusted url cannot steer inside the network. Redirects are followed by hand so
+     * every hop is re-checked - `redirect: 'follow'` would land on an internal host with no second
+     * look.
+     *
+     * The body is returned unread: the caller decides whether to stream it onward or cap it with
+     * {@link UrlIngest.readCappedBody}. Nothing is buffered here.
+     */
+    static async fetchGuarded(opts) {
+        const { url, policy, headers } = opts;
+        const maxRedirects = policy?.maxRedirects ?? constants_1.UrlSafetyDefaults.MAX_REDIRECTS;
+        const timeoutMilliseconds = UrlIngest.readTimeoutMilliseconds({ policy });
+        let target = await UrlIngest.assertReachableUrl({ url, policy });
+        for (let hop = 0; hop <= maxRedirects; hop += 1) {
+            const response = await fetch(target, {
+                redirect: 'manual',
+                signal: AbortSignal.timeout(timeoutMilliseconds),
+                ...(headers ? { headers } : {}),
+            });
+            if (response.status < 300 || response.status > 399) {
+                if (!response.ok) {
+                    // Cancelled, or the socket stays open on every 4xx and 5xx.
+                    await response.body?.cancel();
+                    throw (0, error_1.getError)({
+                        message: `[fetchGuarded] Request failed | status: ${response.status} | url: ${url}`,
+                    });
+                }
+                return response;
+            }
+            const location = response.headers.get('location');
+            await response.body?.cancel();
+            if (!location) {
+                throw (0, error_1.getError)({
+                    error: errors_1.UrlSafetyErrors.URL_REFUSED,
+                    message: `[fetchGuarded] Redirect carried no location | url: ${url}`,
+                });
+            }
+            target = await UrlIngest.assertReachableUrl({
+                url: new URL(location, target).toString(),
+                policy,
+            });
+        }
+        throw (0, error_1.getError)({
+            error: errors_1.UrlSafetyErrors.URL_REFUSED,
+            message: `[fetchGuarded] Too many redirects | max: ${maxRedirects} | url: ${url}`,
+        });
+    }
+    /**
+     * Enforces `maxBytes` on a stream nothing reads into this process - the shape a caller wants when
+     * the body is piped onward rather than held. Without it a `maxBytes` policy is inert on that path.
+     */
+    static capStream(opts) {
+        const { source } = opts;
+        const maxBytes = opts.policy?.maxBytes ?? constants_1.UrlSafetyDefaults.MAX_BYTES;
+        let received = 0;
+        return source.pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                received += chunk.byteLength;
+                if (received > maxBytes) {
+                    controller.error((0, error_1.getError)({
+                        error: errors_1.UrlSafetyErrors.URL_REFUSED,
+                        message: `[capStream] Body exceeds the cap | received: ${received} | max: ${maxBytes}`,
+                    }));
+                    return;
+                }
+                controller.enqueue(chunk);
+            },
+        }));
+    }
+    /**
+     * Reads a body that must not exceed `maxBytes`, cancelling the moment it does. `content-length` is
+     * checked first because it is free, and counted anyway because it may be absent or lie.
+     */
+    static async readCappedBody(opts) {
+        const { response, policy } = opts;
+        const maxBytes = policy?.maxBytes ?? constants_1.UrlSafetyDefaults.MAX_BYTES;
+        const declaredLength = Number(response.headers.get('content-length') ?? 0);
+        if (declaredLength > maxBytes) {
+            await response.body?.cancel();
+            // The same fact as the streaming branch below, so the same verdict: a caller must not retry an
+            // oversized body when the server sends `content-length` and drop it when the server omits one.
+            throw (0, error_1.getError)({
+                error: errors_1.UrlSafetyErrors.URL_REFUSED,
+                message: `[readCappedBody] Body exceeds the cap | declared: ${declaredLength} | max: ${maxBytes}`,
+            });
+        }
+        const reader = response.body?.getReader();
+        if (!reader) {
+            throw (0, error_1.getError)({ message: '[readCappedBody] Response carried no body' });
+        }
+        const chunks = [];
+        let received = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            received += value.length;
+            if (received > maxBytes) {
+                await reader.cancel();
+                throw (0, error_1.getError)({
+                    error: errors_1.UrlSafetyErrors.URL_REFUSED,
+                    message: `[readCappedBody] Body exceeds the cap | received: ${received} | max: ${maxBytes}`,
+                });
+            }
+            chunks.push(value);
+        }
+        return Buffer.concat(chunks);
+    }
+}
+exports.UrlIngest = UrlIngest;
+//# sourceMappingURL=ingest.js.map

package/dist/cjs/modules/network/utilities/url-safety/ingest.js.map

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

package/dist/cjs/modules/network/utilities/url-safety/policy.d.ts

@@ -0,0 +1,29 @@
+import { UrlSafetyDefaults, UrlSchemes } from './common/constants';
+import type { IUrlSafetyPolicy } from './common/types';
+/** Everything about a url that can be decided without touching the network. */
+export declare class UrlPolicy {
+    /** A dotted-quad that is not routable on the public internet. An unparseable input counts as non-public. */
+    private static isNonPublicIPv4;
+    /**
+     * An address that must never be reached with an untrusted url. Anything unrecognised answers
+     * `true`: a guard that fails open on a string it cannot parse is not a guard.
+     */
+    static isNonPublicAddress(opts: {
+        address: string;
+    }): boolean;
+    /** A bracketed IPv6 literal arrives as `[::1]`; the brackets are not part of the address. */
+    static readHostAddress(opts: {
+        hostname: string;
+    }): string;
+    /**
+     * A hostname that RESOLVES to a private address passes here on purpose - `UrlIngest` catches that,
+     * and this half runs where `node:dns` does not exist.
+     */
+    static assertSafeUrl(opts: {
+        url: string;
+        policy?: IUrlSafetyPolicy;
+    }): URL;
+}
+export { UrlSafetyDefaults, UrlSchemes };
+export type { IUrlSafetyPolicy };
+//# sourceMappingURL=policy.d.ts.map

package/dist/cjs/modules/network/utilities/url-safety/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/network/utilities/url-safety/policy.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,+EAA+E;AAC/E,qBAAa,SAAS;IACpB,4GAA4G;IAC5G,OAAO,CAAC,MAAM,CAAC,eAAe;IA0B9B;;;OAGG;IACH,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO;IAoC7D,6FAA6F;IAC7F,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;IAK1D;;;OAGG;IACH,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;KAAE,GAAG,GAAG;CA0C5E;AAED,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/cjs/modules/network/utilities/url-safety/policy.js

@@ -0,0 +1,114 @@
+"use strict";
+// The browser-pure half of the guard: a url and a literal address are decided with string and
+// number work alone. Resolving a hostname needs `node:dns` and lives in `ingest.ts`, which this
+// file must never import - `policy.ts` is re-exported from the `./core` subpath and is gated by
+// `make purity`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UrlSchemes = exports.UrlSafetyDefaults = exports.UrlPolicy = void 0;
+const error_1 = require("../../../error");
+const constants_1 = require("./common/constants");
+Object.defineProperty(exports, "UrlSafetyDefaults", { enumerable: true, get: function () { return constants_1.UrlSafetyDefaults; } });
+Object.defineProperty(exports, "UrlSchemes", { enumerable: true, get: function () { return constants_1.UrlSchemes; } });
+const errors_1 = require("./common/errors");
+/** Everything about a url that can be decided without touching the network. */
+class UrlPolicy {
+    /** A dotted-quad that is not routable on the public internet. An unparseable input counts as non-public. */
+    static isNonPublicIPv4(opts) {
+        const parts = opts.address.split('.').map(Number);
+        if (parts.length !== 4 ||
+            parts.some(part => !Number.isInteger(part) || part < 0 || part > 255)) {
+            return true;
+        }
+        const [first, second] = parts;
+        return (first === 0 || // this host
+            first === 10 || // private
+            first === 127 || // loopback
+            (first === 100 && second >= 64 && second <= 127) || // carrier-grade NAT
+            (first === 169 && second === 254) || // link-local, and the cloud metadata address
+            (first === 172 && second >= 16 && second <= 31) || // private
+            (first === 192 && second === 0) || // IETF protocol assignments
+            (first === 192 && second === 168) || // private
+            (first === 198 && (second === 18 || second === 19)) || // benchmarking
+            first >= 224 // multicast and reserved
+        );
+    }
+    /**
+     * An address that must never be reached with an untrusted url. Anything unrecognised answers
+     * `true`: a guard that fails open on a string it cannot parse is not a guard.
+     */
+    static isNonPublicAddress(opts) {
+        const normalized = opts.address.toLowerCase().split('%')[0];
+        if (!normalized.includes(':')) {
+            return UrlPolicy.isNonPublicIPv4({ address: normalized });
+        }
+        // An IPv4 address wearing an IPv6 coat walks past every naive v6 check. Both spellings must be
+        // unwrapped: `new URL` rewrites `::ffff:169.254.169.254` into the hex form `::ffff:a9fe:a9fe`,
+        // so a dotted-quad-only check is green on a value the parser never actually produces.
+        const dottedMapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(normalized)?.[1];
+        if (dottedMapped) {
+            return UrlPolicy.isNonPublicIPv4({ address: dottedMapped });
+        }
+        const hexMapped = /^::ffff:([\da-f]{1,4}):([\da-f]{1,4})$/.exec(normalized);
+        if (hexMapped) {
+            const high = Number.parseInt(hexMapped[1], 16);
+            const low = Number.parseInt(hexMapped[2], 16);
+            const dotted = [high >> 8, high & 0xff, low >> 8, low & 0xff].join('.');
+            return UrlPolicy.isNonPublicIPv4({ address: dotted });
+        }
+        return (normalized === '::' ||
+            normalized === '::1' ||
+            normalized.startsWith('fc') || // unique local
+            normalized.startsWith('fd') ||
+            normalized.startsWith('fe8') || // link-local
+            normalized.startsWith('fe9') ||
+            normalized.startsWith('fea') ||
+            normalized.startsWith('feb'));
+    }
+    /** A bracketed IPv6 literal arrives as `[::1]`; the brackets are not part of the address. */
+    static readHostAddress(opts) {
+        const { hostname } = opts;
+        return hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+    }
+    /**
+     * A hostname that RESOLVES to a private address passes here on purpose - `UrlIngest` catches that,
+     * and this half runs where `node:dns` does not exist.
+     */
+    static assertSafeUrl(opts) {
+        const { url, policy } = opts;
+        const allowedSchemes = policy?.allowedSchemes ?? constants_1.UrlSafetyDefaults.ALLOWED_SCHEMES;
+        const allowPrivateAddress = policy?.allowPrivateAddress ?? constants_1.UrlSafetyDefaults.ALLOW_PRIVATE_ADDRESS;
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw (0, error_1.getError)({
+                error: errors_1.UrlSafetyErrors.URL_REFUSED,
+                message: `[assertSafeUrl] Malformed url | url: ${url}`,
+            });
+        }
+        if (!allowedSchemes.includes(parsed.protocol)) {
+            throw (0, error_1.getError)({
+                error: errors_1.UrlSafetyErrors.URL_REFUSED,
+                message: `[assertSafeUrl] Disallowed scheme | scheme: ${parsed.protocol} | allowed: ${allowedSchemes.join(', ')}`,
+            });
+        }
+        if (policy?.allowedHosts && !policy.allowedHosts.includes(parsed.hostname)) {
+            throw (0, error_1.getError)({
+                error: errors_1.UrlSafetyErrors.URL_REFUSED,
+                message: `[assertSafeUrl] Host is not in the allow-list | host: ${parsed.hostname}`,
+            });
+        }
+        const address = UrlPolicy.readHostAddress({ hostname: parsed.hostname });
+        const isLiteralAddress = /^[\d.]+$/.test(address) || address.includes(':');
+        if (!allowPrivateAddress && isLiteralAddress && UrlPolicy.isNonPublicAddress({ address })) {
+            throw (0, error_1.getError)({
+                error: errors_1.UrlSafetyErrors.URL_REFUSED,
+                message: `[assertSafeUrl] Url points at a non-public address | address: ${address}`,
+            });
+        }
+        return parsed;
+    }
+}
+exports.UrlPolicy = UrlPolicy;
+//# sourceMappingURL=policy.js.map

package/dist/cjs/modules/network/utilities/url-safety/policy.js.map

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