@venizia/ignis-helpers 0.2.0-16 → 0.2.0-18

package/README.md

@@ -80,7 +80,6 @@ backends you imported by name.
 | `/bullmq` | `BullMQHelper` | `bullmq` |
 | `/mqtt` | `MQTTClientHelper` | `mqtt` |
 | `/kafka` | `KafkaProducerHelper`, `KafkaConsumerHelper`, `KafkaAdminHelper`, ... | `@platformatic/kafka` |
-| `/minio` | `MinioHelper` | `minio` |
 | `/bun-s3` | `BunS3Helper` | none - Bun's native S3 client |
 | `/socket-io` | `SocketIOServerHelper`, `SocketIOClientHelper` | `socket.io`, `socket.io-client` (+ `@socket.io/redis-adapter`, `@socket.io/redis-emitter` for multi-node) |
 | `/axios` | `AxiosFetcher`, `AxiosNetworkRequest` | `axios` |
@@ -89,8 +88,8 @@ backends you imported by name.
 | `/dotenv-vault` | `DotenvVaultHelper` | `@dotenvx/dotenvx` |
 
 ```bash
-# example: pino logging + BullMQ jobs + MinIO storage
-bun add pino bullmq minio
+# example: pino logging + BullMQ jobs
+bun add pino bullmq
 ```
 
 Everything else - Redis (`ioredis` is a real dependency), disk and in-memory storage, crypto,
@@ -103,7 +102,7 @@ network, UID, env, pool, worker threads - comes straight off the root barrel.
 | [logger](https://ignis.venizia.ai/extensions/helpers/logger/) | Scoped `ILogger` over a pluggable winston or pino backend, plus `HfLogger` for hot paths |
 | [redis](https://ignis.venizia.ai/extensions/helpers/redis/) | Single, cluster, and sentinel clients over `ioredis`: key-value, hash, RedisJSON, pub/sub |
 | [queue](https://ignis.venizia.ai/extensions/helpers/queue/) | BullMQ jobs, MQTT topics, [Kafka](https://ignis.venizia.ai/extensions/helpers/kafka/) producers and consumers, plus an in-process `SequentialQueueHelper` |
-| [storage](https://ignis.venizia.ai/extensions/helpers/storage/) | One `IStorageHelper` interface over MinIO/S3, Bun S3, local disk, and memory |
+| [storage](https://ignis.venizia.ai/extensions/helpers/storage/) | One `IStorageHelper` interface over any S3-compatible provider, local disk, and memory |
 | [crypto](https://ignis.venizia.ai/extensions/helpers/crypto/) | `AES`, `RSA`, `ECDH` - encryption, signing, and key exchange |
 | [cron](https://ignis.venizia.ai/extensions/helpers/cron/) | `CronHelper`: declarative schedules with lifecycle hooks |
 | [socket](https://ignis.venizia.ai/extensions/helpers/socket-io/) | Socket.IO server and client, plus a [Bun-native WebSocket](https://ignis.venizia.ai/extensions/helpers/websocket/) server |

package/dist/cjs/common/constants/mime.d.ts

@@ -4,6 +4,73 @@ export declare class MimeTypes {
     static readonly IMAGE = "image";
     static readonly VIDEO = "video";
     static readonly TEXT = "text";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(value: string): boolean;
 }
 export type TMimeTypes = TConstValue<typeof MimeTypes>;
+/** The leading dot is part of the value: `path.extname` returns one. */
+export declare class FileExtensions {
+    static readonly PNG = ".png";
+    static readonly JPG = ".jpg";
+    static readonly JPEG = ".jpeg";
+    static readonly GIF = ".gif";
+    static readonly WEBP = ".webp";
+    static readonly SVG = ".svg";
+    static readonly PDF = ".pdf";
+    static readonly JSON = ".json";
+    static readonly TXT = ".txt";
+    static readonly HTML = ".html";
+    static readonly CSS = ".css";
+    static readonly JS = ".js";
+    static readonly MP4 = ".mp4";
+    static readonly WEBM = ".webm";
+    static readonly MP3 = ".mp3";
+    static readonly WAV = ".wav";
+    static readonly ZIP = ".zip";
+    static readonly CSV = ".csv";
+    static readonly XML = ".xml";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(value: string): boolean;
+}
+export type TFileExtension = TConstValue<typeof FileExtensions>;
+/** Full content types, as they go on the wire. `MimeTypes` holds only the top-level part. */
+export declare class ContentTypes {
+    static readonly OCTET_STREAM = "application/octet-stream";
+    static readonly PNG = "image/png";
+    static readonly JPEG = "image/jpeg";
+    static readonly GIF = "image/gif";
+    static readonly WEBP = "image/webp";
+    static readonly SVG = "image/svg+xml";
+    static readonly PDF = "application/pdf";
+    static readonly JSON = "application/json";
+    static readonly PLAIN_TEXT = "text/plain";
+    static readonly HTML = "text/html";
+    static readonly CSS = "text/css";
+    static readonly JAVASCRIPT = "text/javascript";
+    static readonly MP4 = "video/mp4";
+    static readonly WEBM = "video/webm";
+    static readonly MPEG_AUDIO = "audio/mpeg";
+    static readonly WAV = "audio/wav";
+    static readonly ZIP = "application/zip";
+    static readonly CSV = "text/csv";
+    static readonly XML = "application/xml";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(value: string): boolean;
+}
+export type TContentType = TConstValue<typeof ContentTypes>;
+/** The extension table and the lookup that reads it, together - the `DurationMultipliers` shape. */
+export declare class ContentTypeTable {
+    /** `satisfies` makes the table total; the declared `string` key keeps a lookup cast-free. */
+    static readonly BY_EXTENSION: Readonly<Partial<Record<string, TContentType>>>;
+    /**
+     * The content type an object name implies. `node:path` is deliberately not used: this file is
+     * reachable from the browser-pure `./common` subpath, and an extension is the tail after the last
+     * dot either way.
+     */
+    static resolve(opts: {
+        filename: string;
+    }): TContentType;
+}
+/** Published before the table moved onto the class; kept as the one-line delegate it now is. */
+export declare const CONTENT_TYPE_BY_EXTENSION: Readonly<Partial<Record<string, TContentType>>>;
 //# sourceMappingURL=mime.d.ts.map

package/dist/cjs/common/constants/mime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mime.d.ts","sourceRoot":"","sources":["../../../../src/common/constants/mime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,qBAAa,SAAS;IACpB,MAAM,CAAC,QAAQ,CAAC,OAAO,aAAa;IACpC,MAAM,CAAC,QAAQ,CAAC,KAAK,WAAW;IAChC,MAAM,CAAC,QAAQ,CAAC,KAAK,WAAW;IAChC,MAAM,CAAC,QAAQ,CAAC,IAAI,UAAU;CAC/B;AACD,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,SAAS,CAAC,CAAC"}
+{"version":3,"file":"mime.d.ts","sourceRoot":"","sources":["../../../../src/common/constants/mime.ts"],"names":[],"mappings":"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"}

package/dist/cjs/common/constants/mime.js

@@ -1,11 +1,148 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MimeTypes = void 0;
+exports.CONTENT_TYPE_BY_EXTENSION = exports.ContentTypeTable = exports.ContentTypes = exports.FileExtensions = exports.MimeTypes = void 0;
 class MimeTypes {
     static { this.UNKNOWN = 'unknown'; }
     static { this.IMAGE = 'image'; }
     static { this.VIDEO = 'video'; }
     static { this.TEXT = 'text'; }
+    static { this.SCHEME_SET = new Set([this.UNKNOWN, this.IMAGE, this.VIDEO, this.TEXT]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
 }
 exports.MimeTypes = MimeTypes;
+/** The leading dot is part of the value: `path.extname` returns one. */
+class FileExtensions {
+    static { this.PNG = '.png'; }
+    static { this.JPG = '.jpg'; }
+    static { this.JPEG = '.jpeg'; }
+    static { this.GIF = '.gif'; }
+    static { this.WEBP = '.webp'; }
+    static { this.SVG = '.svg'; }
+    static { this.PDF = '.pdf'; }
+    static { this.JSON = '.json'; }
+    static { this.TXT = '.txt'; }
+    static { this.HTML = '.html'; }
+    static { this.CSS = '.css'; }
+    static { this.JS = '.js'; }
+    static { this.MP4 = '.mp4'; }
+    static { this.WEBM = '.webm'; }
+    static { this.MP3 = '.mp3'; }
+    static { this.WAV = '.wav'; }
+    static { this.ZIP = '.zip'; }
+    static { this.CSV = '.csv'; }
+    static { this.XML = '.xml'; }
+    static { this.SCHEME_SET = new Set([
+        this.PNG,
+        this.JPG,
+        this.JPEG,
+        this.GIF,
+        this.WEBP,
+        this.SVG,
+        this.PDF,
+        this.JSON,
+        this.TXT,
+        this.HTML,
+        this.CSS,
+        this.JS,
+        this.MP4,
+        this.WEBM,
+        this.MP3,
+        this.WAV,
+        this.ZIP,
+        this.CSV,
+        this.XML,
+    ]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
+}
+exports.FileExtensions = FileExtensions;
+/** Full content types, as they go on the wire. `MimeTypes` holds only the top-level part. */
+class ContentTypes {
+    static { this.OCTET_STREAM = 'application/octet-stream'; }
+    static { this.PNG = 'image/png'; }
+    static { this.JPEG = 'image/jpeg'; }
+    static { this.GIF = 'image/gif'; }
+    static { this.WEBP = 'image/webp'; }
+    static { this.SVG = 'image/svg+xml'; }
+    static { this.PDF = 'application/pdf'; }
+    static { this.JSON = 'application/json'; }
+    static { this.PLAIN_TEXT = 'text/plain'; }
+    static { this.HTML = 'text/html'; }
+    static { this.CSS = 'text/css'; }
+    static { this.JAVASCRIPT = 'text/javascript'; }
+    static { this.MP4 = 'video/mp4'; }
+    static { this.WEBM = 'video/webm'; }
+    static { this.MPEG_AUDIO = 'audio/mpeg'; }
+    static { this.WAV = 'audio/wav'; }
+    static { this.ZIP = 'application/zip'; }
+    static { this.CSV = 'text/csv'; }
+    static { this.XML = 'application/xml'; }
+    static { this.SCHEME_SET = new Set([
+        this.OCTET_STREAM,
+        this.PNG,
+        this.JPEG,
+        this.GIF,
+        this.WEBP,
+        this.SVG,
+        this.PDF,
+        this.JSON,
+        this.PLAIN_TEXT,
+        this.HTML,
+        this.CSS,
+        this.JAVASCRIPT,
+        this.MP4,
+        this.WEBM,
+        this.MPEG_AUDIO,
+        this.WAV,
+        this.ZIP,
+        this.CSV,
+        this.XML,
+    ]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
+}
+exports.ContentTypes = ContentTypes;
+/** The extension table and the lookup that reads it, together - the `DurationMultipliers` shape. */
+class ContentTypeTable {
+    /** `satisfies` makes the table total; the declared `string` key keeps a lookup cast-free. */
+    static { this.BY_EXTENSION = {
+        [FileExtensions.PNG]: ContentTypes.PNG,
+        [FileExtensions.JPG]: ContentTypes.JPEG,
+        [FileExtensions.JPEG]: ContentTypes.JPEG,
+        [FileExtensions.GIF]: ContentTypes.GIF,
+        [FileExtensions.WEBP]: ContentTypes.WEBP,
+        [FileExtensions.SVG]: ContentTypes.SVG,
+        [FileExtensions.PDF]: ContentTypes.PDF,
+        [FileExtensions.JSON]: ContentTypes.JSON,
+        [FileExtensions.TXT]: ContentTypes.PLAIN_TEXT,
+        [FileExtensions.HTML]: ContentTypes.HTML,
+        [FileExtensions.CSS]: ContentTypes.CSS,
+        [FileExtensions.JS]: ContentTypes.JAVASCRIPT,
+        [FileExtensions.MP4]: ContentTypes.MP4,
+        [FileExtensions.WEBM]: ContentTypes.WEBM,
+        [FileExtensions.MP3]: ContentTypes.MPEG_AUDIO,
+        [FileExtensions.WAV]: ContentTypes.WAV,
+        [FileExtensions.ZIP]: ContentTypes.ZIP,
+        [FileExtensions.CSV]: ContentTypes.CSV,
+        [FileExtensions.XML]: ContentTypes.XML,
+    }; }
+    /**
+     * The content type an object name implies. `node:path` is deliberately not used: this file is
+     * reachable from the browser-pure `./common` subpath, and an extension is the tail after the last
+     * dot either way.
+     */
+    static resolve(opts) {
+        const { filename } = opts;
+        const lastDot = filename.lastIndexOf('.');
+        const extension = lastDot === -1 ? '' : filename.slice(lastDot).toLowerCase();
+        return this.BY_EXTENSION[extension] ?? ContentTypes.OCTET_STREAM;
+    }
+}
+exports.ContentTypeTable = ContentTypeTable;
+/** Published before the table moved onto the class; kept as the one-line delegate it now is. */
+exports.CONTENT_TYPE_BY_EXTENSION = ContentTypeTable.BY_EXTENSION;
 //# sourceMappingURL=mime.js.map

package/dist/cjs/common/constants/mime.js.map

@@ -1 +1 @@
-{"version":3,"file":"mime.js","sourceRoot":"","sources":["../../../../src/common/constants/mime.ts"],"names":[],"mappings":";;;AAEA,MAAa,SAAS;aACJ,YAAO,GAAG,SAAS,CAAC;aACpB,UAAK,GAAG,OAAO,CAAC;aAChB,UAAK,GAAG,OAAO,CAAC;aAChB,SAAI,GAAG,MAAM,CAAC;;AAJhC,8BAKC"}
+{"version":3,"file":"mime.js","sourceRoot":"","sources":["../../../../src/common/constants/mime.ts"],"names":[],"mappings":";;;AAEA,MAAa,SAAS;aACJ,YAAO,GAAG,SAAS,CAAC;aACpB,UAAK,GAAG,OAAO,CAAC;aAChB,UAAK,GAAG,OAAO,CAAC;aAChB,SAAI,GAAG,MAAM,CAAC;aAEd,eAAU,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAEhG,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AAVH,8BAWC;AAGD,wEAAwE;AACxE,MAAa,cAAc;aACT,QAAG,GAAG,MAAM,CAAC;aACb,QAAG,GAAG,MAAM,CAAC;aACb,SAAI,GAAG,OAAO,CAAC;aACf,QAAG,GAAG,MAAM,CAAC;aACb,SAAI,GAAG,OAAO,CAAC;aACf,QAAG,GAAG,MAAM,CAAC;aACb,QAAG,GAAG,MAAM,CAAC;aACb,SAAI,GAAG,OAAO,CAAC;aACf,QAAG,GAAG,MAAM,CAAC;aACb,SAAI,GAAG,OAAO,CAAC;aACf,QAAG,GAAG,MAAM,CAAC;aACb,OAAE,GAAG,KAAK,CAAC;aACX,QAAG,GAAG,MAAM,CAAC;aACb,SAAI,GAAG,OAAO,CAAC;aACf,QAAG,GAAG,MAAM,CAAC;aACb,QAAG,GAAG,MAAM,CAAC;aACb,QAAG,GAAG,MAAM,CAAC;aACb,QAAG,GAAG,MAAM,CAAC;aACb,QAAG,GAAG,MAAM,CAAC;aAEb,eAAU,GAAG,IAAI,GAAG,CAAS;QAC3C,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,EAAE;QACP,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;KACT,CAAC,CAAC;IAEH,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AA7CH,wCA8CC;AAGD,6FAA6F;AAC7F,MAAa,YAAY;aACP,iBAAY,GAAG,0BAA0B,CAAC;aAC1C,QAAG,GAAG,WAAW,CAAC;aAClB,SAAI,GAAG,YAAY,CAAC;aACpB,QAAG,GAAG,WAAW,CAAC;aAClB,SAAI,GAAG,YAAY,CAAC;aACpB,QAAG,GAAG,eAAe,CAAC;aACtB,QAAG,GAAG,iBAAiB,CAAC;aACxB,SAAI,GAAG,kBAAkB,CAAC;aAC1B,eAAU,GAAG,YAAY,CAAC;aAC1B,SAAI,GAAG,WAAW,CAAC;aACnB,QAAG,GAAG,UAAU,CAAC;aACjB,eAAU,GAAG,iBAAiB,CAAC;aAC/B,QAAG,GAAG,WAAW,CAAC;aAClB,SAAI,GAAG,YAAY,CAAC;aACpB,eAAU,GAAG,YAAY,CAAC;aAC1B,QAAG,GAAG,WAAW,CAAC;aAClB,QAAG,GAAG,iBAAiB,CAAC;aACxB,QAAG,GAAG,UAAU,CAAC;aACjB,QAAG,GAAG,iBAAiB,CAAC;aAExB,eAAU,GAAG,IAAI,GAAG,CAAS;QAC3C,IAAI,CAAC,YAAY;QACjB,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,UAAU;QACf,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,UAAU;QACf,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,IAAI;QACT,IAAI,CAAC,UAAU;QACf,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;QACR,IAAI,CAAC,GAAG;KACT,CAAC,CAAC;IAEH,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AA7CH,oCA8CC;AAGD,oGAAoG;AACpG,MAAa,gBAAgB;IAC3B,6FAA6F;aAC7E,iBAAY,GAAoD;QAC9E,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,IAAI;QACvC,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI;QACxC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI;QACxC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI;QACxC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,UAAU;QAC7C,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI;QACxC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,YAAY,CAAC,UAAU;QAC5C,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI;QACxC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,UAAU;QAC7C,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;QACtC,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG;KACkB,CAAC;IAE3D;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,IAA0B;QACvC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;QAC1B,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1C,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;QAE9E,OAAO,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,IAAI,YAAY,CAAC,YAAY,CAAC;IACnE,CAAC;;AAnCH,4CAoCC;AAED,gGAAgG;AACnF,QAAA,yBAAyB,GAAG,gBAAgB,CAAC,YAAY,CAAC"}

package/dist/cjs/core.d.ts

@@ -7,6 +7,9 @@ export * from './modules/queue/internal/hf';
 export type { ILogger, ILoggerProvider, TLogLevel } from './modules/logger/common/types';
 export { LogLevels } from './modules/logger/common/types';
 export * from './modules/network/http-request/fetcher/base-fetcher';
+export * from './modules/network/url-safety/policy';
+export * from './modules/network/url-safety/common/constants';
+export type { IUrlSafetyPolicy } from './modules/network/url-safety/common/types';
 export { RetryHelper } from './modules/retry/helper';
 export { RetryBackoffStrategies, RetryJitterModes } from './modules/retry/common/constants';
 export type { TRetryBackoffStrategy, TRetryJitterMode } from './modules/retry/common/constants';

package/dist/cjs/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAG5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AACzF,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC1D,cAAc,qDAAqD,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAC5F,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAChG,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AACxF,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,YAAY,EACV,SAAS,EACT,aAAa,EACb,cAAc,EACd,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,aAAa,GACd,MAAM,6BAA6B,CAAC;AAMrC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAKvE,YAAY,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAClF,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,YAAY,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAG5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AACzF,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC1D,cAAc,qDAAqD,CAAC;AAGpE,cAAc,qCAAqC,CAAC;AACpD,cAAc,+CAA+C,CAAC;AAC9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAC5F,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAChG,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AACxF,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,YAAY,EACV,SAAS,EACT,aAAa,EACb,cAAc,EACd,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,aAAa,GACd,MAAM,6BAA6B,CAAC;AAMrC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAKvE,YAAY,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAClF,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,YAAY,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/cjs/core.js

@@ -28,6 +28,10 @@ __exportStar(require("./modules/queue/internal/hf"), exports);
 var types_1 = require("./modules/logger/common/types");
 Object.defineProperty(exports, "LogLevels", { enumerable: true, get: function () { return types_1.LogLevels; } });
 __exportStar(require("./modules/network/http-request/fetcher/base-fetcher"), exports);
+// The url guard, pure half only: `UrlPolicy` decides a url and a literal address with string and
+// number work. Its sibling `UrlIngest` reaches `node:dns` and stays out of this subpath.
+__exportStar(require("./modules/network/url-safety/policy"), exports);
+__exportStar(require("./modules/network/url-safety/common/constants"), exports);
 var helper_1 = require("./modules/retry/helper");
 Object.defineProperty(exports, "RetryHelper", { enumerable: true, get: function () { return helper_1.RetryHelper; } });
 var constants_1 = require("./modules/retry/common/constants");

package/dist/cjs/core.js.map

@@ -1 +1 @@
-{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uCAA4C;AAAnC,kGAAA,UAAU,OAAA;AACnB,6FAA6F;AAC7F,8DAA8D;AAC9D,6CAAuD;AAA9C,yGAAA,gBAAgB,OAAA;AACzB,kDAAgC;AAChC,gDAA8B;AAC9B,iDAA+B;AAC/B,8DAA4C;AAE5C,uDAA0D;AAAjD,kGAAA,SAAS,OAAA;AAClB,sFAAoE;AACpE,iDAAqD;AAA5C,qGAAA,WAAW,OAAA;AACpB,8DAA4F;AAAnF,mHAAA,sBAAsB,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAGjD,gDAAmD;AAA1C,oGAAA,UAAU,OAAA;AACnB,4CAAiD;AAAxC,kGAAA,UAAU,OAAA;AACnB,kDAAqD;AAA5C,sGAAA,WAAW,OAAA;AAepB,gGAAgG;AAChG,6FAA6F;AAC7F,iGAAiG;AACjG,0DAA0D;AAC1D,2DAAiF;AAAxE,0GAAA,SAAS,OAAA;AAAE,oGAAA,GAAG,OAAA;AAAE,wGAAA,OAAO,OAAA;AAAE,4GAAA,WAAW,OAAA;AAC7C,uEAAgF;AAAvE,oIAAA,6BAA6B,OAAA;AACtC,yEAAuE;AAA9D,2HAAA,mBAAmB,OAAA"}
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uCAA4C;AAAnC,kGAAA,UAAU,OAAA;AACnB,6FAA6F;AAC7F,8DAA8D;AAC9D,6CAAuD;AAA9C,yGAAA,gBAAgB,OAAA;AACzB,kDAAgC;AAChC,gDAA8B;AAC9B,iDAA+B;AAC/B,8DAA4C;AAE5C,uDAA0D;AAAjD,kGAAA,SAAS,OAAA;AAClB,sFAAoE;AACpE,iGAAiG;AACjG,yFAAyF;AACzF,sEAAoD;AACpD,gFAA8D;AAE9D,iDAAqD;AAA5C,qGAAA,WAAW,OAAA;AACpB,8DAA4F;AAAnF,mHAAA,sBAAsB,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAGjD,gDAAmD;AAA1C,oGAAA,UAAU,OAAA;AACnB,4CAAiD;AAAxC,kGAAA,UAAU,OAAA;AACnB,kDAAqD;AAA5C,sGAAA,WAAW,OAAA;AAepB,gGAAgG;AAChG,6FAA6F;AAC7F,iGAAiG;AACjG,0DAA0D;AAC1D,2DAAiF;AAAxE,0GAAA,SAAS,OAAA;AAAE,oGAAA,GAAG,OAAA;AAAE,wGAAA,OAAO,OAAA;AAAE,4GAAA,WAAW,OAAA;AAC7C,uEAAgF;AAAvE,oIAAA,6BAA6B,OAAA;AACtC,yEAAuE;AAA9D,2HAAA,mBAAmB,OAAA"}

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

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

package/dist/cjs/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/cjs/modules/network/index.js

@@ -17,4 +17,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./http-request"), exports);
 __exportStar(require("./tcp-socket"), exports);
 __exportStar(require("./udp-socket"), exports);
+__exportStar(require("./url-safety"), exports);
 //# sourceMappingURL=index.js.map

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

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

package/dist/cjs/modules/network/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/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/cjs/modules/network/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/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,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/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/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/cjs/modules/network/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/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,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/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/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/cjs/modules/network/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/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,8CAA4B;AAC5B,2CAAyB;AACzB,0CAAwB"}

package/dist/cjs/modules/network/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/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/cjs/modules/network/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/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/cjs/modules/network/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/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/cjs/modules/network/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/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,2CAAyB;AACzB,2CAAyB;AACzB,2CAAyB"}

package/dist/cjs/modules/network/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/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"}