@venizia/ignis-helpers 0.2.0-2 → 0.2.0-21

package/dist/esm/modules/network/index.d.ts

@@ -1,4 +1,5 @@
 export * from './http-request/index.js';
 export * from './tcp-socket/index.js';
 export * from './udp-socket/index.js';
+export * from './url-safety/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/modules/network/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/modules/network/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/modules/network/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/esm/modules/network/index.js

@@ -1,4 +1,5 @@
 export * from './http-request/index.js';
 export * from './tcp-socket/index.js';
 export * from './udp-socket/index.js';
+export * from './url-safety/index.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/modules/network/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/network/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/network/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/esm/modules/network/tcp-socket/base-tcp-client.helper.d.ts

@@ -1,4 +1,4 @@
-import { BaseHelper } from '../../../modules/base.js';
+import { BaseHelper } from '../../base.js';
 import { ValueOrPromise } from '../../../common/index.js';
 import { TcpSocketConnectOpts as PlainConnectionOptions, Socket as PlainSocketClient } from 'node:net';
 import { ConnectionOptions as TlsConnectionOptions, TLSSocket as TlsSocketClient } from 'node:tls';

package/dist/esm/modules/network/tcp-socket/base-tcp-client.helper.js

@@ -1,5 +1,5 @@
 import { redactSecrets } from '../../../common/redact.js';
-import { BaseHelper } from '../../../modules/base.js';
+import { BaseHelper } from '../../base.js';
 import isEmpty from 'lodash/isEmpty';
 const DEFAULT_MAX_RETRY = 5;
 export class BaseNetworkTcpClient extends BaseHelper {

package/dist/esm/modules/network/tcp-socket/base-tcp-server.helper.d.ts

@@ -1,5 +1,5 @@
-import { ValueOrPromise } from '../../../common/types.js';
-import { BaseHelper } from '../../../modules/base.js';
+import { ValueOrPromise } from '../../../common/types/index.js';
+import { BaseHelper } from '../../base.js';
 import { dayjs } from '../../../utilities/date.utility.js';
 import { ListenOptions, ServerOpts, Socket as SocketClient, Server as SocketServer } from 'node:net';
 export interface ITcpSocketClient<SocketClientType> {

package/dist/esm/modules/network/tcp-socket/base-tcp-server.helper.js

@@ -1,5 +1,5 @@
-import { BaseHelper } from '../../../modules/base.js';
-import { getError } from '../../../modules/error/index.js';
+import { BaseHelper } from '../../base.js';
+import { getError } from '../../error/index.js';
 import { dayjs } from '../../../utilities/date.utility.js';
 import { getUID } from '../../../utilities/parse.utility.js';
 import { voidExecution } from '../../../utilities/promise.utility.js';

package/dist/esm/modules/network/udp-socket/network-udp-client.helper.d.ts

@@ -1,5 +1,5 @@
 import { ValueOrPromise } from '../../../common/index.js';
-import { BaseHelper } from '../../../modules/base.js';
+import { BaseHelper } from '../../base.js';
 import dgram from 'node:dgram';
 interface INetworkUdpClientProps {
     identifier: string;

package/dist/esm/modules/network/udp-socket/network-udp-client.helper.js

@@ -1,4 +1,4 @@
-import { BaseHelper } from '../../../modules/base.js';
+import { BaseHelper } from '../../base.js';
 import { voidExecution } from '../../../utilities/promise.utility.js';
 import dgram from 'node:dgram';
 export class NetworkUdpClient extends BaseHelper {

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

@@ -0,0 +1,18 @@
+import { TConstValue } from '../../../../common/types/index.js';
+/** 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/esm/modules/network/url-safety/common/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/network/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/esm/modules/network/url-safety/common/constants.js

@@ -0,0 +1,18 @@
+/** The only schemes a guarded fetch will speak. `file:` and `gopher:` are the classic SSRF pivots. */
+export 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);
+    }
+}
+/** Safe by default: https only, no private address, three hops, ten seconds. */
+export 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; }
+}
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../../src/modules/network/url-safety/common/constants.ts"],"names":[],"mappings":"AAEA,sGAAsG;AACtG,MAAM,OAAO,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;;AAIH,gFAAgF;AAChF,MAAM,OAAO,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"}

package/dist/esm/modules/network/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/esm/modules/network/url-safety/common/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/network/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/esm/modules/network/url-safety/common/errors.js

@@ -0,0 +1,26 @@
+import { HTTP } from '../../../../common/constants/index.js';
+import { ErrorScopes } 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 const UrlSafetyErrors = {
+    URL_REFUSED: {
+        message: { text: 'Url refused by the safety policy', code: 'core.url_safety.url_refused' },
+        statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+        category: 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.
+ */
+export const isUrlRefusedError = (opts) => {
+    const source = opts.error;
+    return source?.normalized?.code === UrlSafetyErrors.URL_REFUSED.message.code;
+};
+//# sourceMappingURL=errors.js.map

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,24 @@
+import type { IDuration } from '../../../../common/constants/duration.js';
+/**
+ * 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/esm/modules/network/url-safety/common/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/network/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/esm/modules/network/url-safety/common/types.js.map

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

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

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

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

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

package/dist/esm/modules/network/url-safety/index.js

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

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

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

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

@@ -0,0 +1,52 @@
+import type { IUrlSafetyPolicy } from './common/types.js';
+/** 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/esm/modules/network/url-safety/ingest.d.ts.map

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

@@ -0,0 +1,163 @@
+// The half `policy.ts` cannot do: resolving a hostname needs `node:dns`, so nothing here may be
+// re-exported from the `./core` subpath.
+import { DurationMultipliers } from '../../../common/constants/duration.js';
+import { getError } from '../../error/index.js';
+import { lookup } from 'node:dns/promises';
+import { UrlSafetyDefaults } from './common/constants.js';
+import { UrlSafetyErrors } from './common/errors.js';
+import { UrlPolicy } from './policy.js';
+/** Fetching an untrusted url without letting it reach inside the network. */
+export 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 ?? 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 = UrlPolicy.readHostAddress({ hostname });
+        const addresses = await lookup(address, { all: true });
+        if (!addresses.length) {
+            throw getError({
+                error: UrlSafetyErrors.URL_REFUSED,
+                message: `[assertPublicHost] Host resolves to nothing | host: ${hostname}`,
+            });
+        }
+        const offender = addresses.find(entry => UrlPolicy.isNonPublicAddress({ address: entry.address }));
+        if (offender) {
+            throw getError({
+                error: 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 = UrlPolicy.assertSafeUrl(opts);
+        await UrlIngest.assertPublicHost({ hostname: parsed.hostname, policy: opts.policy });
+        return parsed;
+    }
+    static readTimeoutMilliseconds(opts) {
+        const { timeout } = opts.policy ?? {};
+        const milliseconds = timeout ? DurationMultipliers.toMilliseconds(timeout) : null;
+        return milliseconds ?? 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 ?? 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 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 getError({
+                    error: UrlSafetyErrors.URL_REFUSED,
+                    message: `[fetchGuarded] Redirect carried no location | url: ${url}`,
+                });
+            }
+            target = await UrlIngest.assertReachableUrl({
+                url: new URL(location, target).toString(),
+                policy,
+            });
+        }
+        throw getError({
+            error: 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 ?? UrlSafetyDefaults.MAX_BYTES;
+        let received = 0;
+        return source.pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                received += chunk.byteLength;
+                if (received > maxBytes) {
+                    controller.error(getError({
+                        error: 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 ?? 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 getError({
+                error: UrlSafetyErrors.URL_REFUSED,
+                message: `[readCappedBody] Body exceeds the cap | declared: ${declaredLength} | max: ${maxBytes}`,
+            });
+        }
+        const reader = response.body?.getReader();
+        if (!reader) {
+            throw 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 getError({
+                    error: UrlSafetyErrors.URL_REFUSED,
+                    message: `[readCappedBody] Body exceeds the cap | received: ${received} | max: ${maxBytes}`,
+                });
+            }
+            chunks.push(value);
+        }
+        return Buffer.concat(chunks);
+    }
+}
+//# sourceMappingURL=ingest.js.map

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

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

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

@@ -0,0 +1,29 @@
+import { UrlSafetyDefaults, UrlSchemes } from './common/constants.js';
+import type { IUrlSafetyPolicy } from './common/types.js';
+/** 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/esm/modules/network/url-safety/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../../../src/modules/network/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"}