@starklabs/forge 1.3.25-cors.0 → 2.0.0

package/dist/upload/CloudinaryStorage.d.ts

@@ -0,0 +1,19 @@
+import type { StoreFile } from "../types/StoreFile.js";
+import type { UploadType } from "../types/upload.js";
+import type { IncomingFile, StorageProvider } from "./StorageProvider.js";
+export interface CloudinaryOptions {
+    apiKey: string;
+    apiSecret: string;
+    cloudName: string;
+    folder: string;
+}
+export declare class CloudinaryStorage implements StorageProvider {
+    private readonly options;
+    readonly name: "cloudinary";
+    constructor(options: CloudinaryOptions);
+    upload(file: IncomingFile, { type }: {
+        type: UploadType;
+    }): Promise<StoreFile>;
+    remove(file: Pick<StoreFile, "storageKey" | "resourceType">): Promise<void>;
+}
+//# sourceMappingURL=CloudinaryStorage.d.ts.map

package/dist/upload/CloudinaryStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudinaryStorage.d.ts","sourceRoot":"","sources":["../../src/upload/CloudinaryStorage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE1E,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,iBAAkB,YAAW,eAAe;IAG3C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IAEtC,YAA6B,OAAO,EAAE,iBAAiB,EAQtD;IAED,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CA4B7E;IAEK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhF;CACF"}

package/dist/upload/CloudinaryStorage.js

@@ -0,0 +1,44 @@
+import { v2 as cloudinary } from "cloudinary";
+import { ErrorCode, ServiceUnavailableError } from "../errors/index.js";
+export class CloudinaryStorage {
+    options;
+    name = "cloudinary";
+    constructor(options) {
+        this.options = options;
+        // Configured once, not on every upload.
+        cloudinary.config({
+            cloud_name: options.cloudName,
+            api_key: options.apiKey,
+            api_secret: options.apiSecret,
+            secure: true,
+        });
+    }
+    upload(file, { type }) {
+        return new Promise((resolve, reject) => {
+            const stream = cloudinary.uploader.upload_stream({ folder: this.options.folder, resource_type: type, use_filename: false, unique_filename: true }, (error, result) => {
+                if (error || !result) {
+                    return reject(new ServiceUnavailableError({
+                        message: "The file could not be uploaded to storage.",
+                        code: ErrorCode.UPLOAD_FAILED,
+                        cause: error,
+                    }));
+                }
+                resolve({
+                    url: result.secure_url,
+                    storageKey: result.public_id,
+                    width: result.width,
+                    height: result.height,
+                    bytes: result.bytes,
+                    format: result.format ?? "",
+                    mimeType: file.mimetype,
+                    resourceType: result.resource_type,
+                });
+            });
+            stream.end(file.buffer);
+        });
+    }
+    async remove(file) {
+        await cloudinary.uploader.destroy(file.storageKey, { resource_type: file.resourceType || "image", invalidate: true });
+    }
+}
+//# sourceMappingURL=CloudinaryStorage.js.map

package/dist/upload/CloudinaryStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudinaryStorage.js","sourceRoot":"","sources":["../../src/upload/CloudinaryStorage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,IAAI,UAAU,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAYxE,MAAM,OAAO,iBAAiB;IAGC,OAAO;IAF3B,IAAI,GAAG,YAAqB,CAAC;IAEtC,YAA6B,OAA0B;uBAA1B,OAAO;QAClC,wCAAwC;QACxC,UAAU,CAAC,MAAM,CAAC;YAChB,UAAU,EAAE,OAAO,CAAC,SAAS;YAC7B,OAAO,EAAE,OAAO,CAAC,MAAM;YACvB,UAAU,EAAE,OAAO,CAAC,SAAS;YAC7B,MAAM,EAAE,IAAI;SACb,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,IAAkB,EAAE,EAAE,IAAI,EAAwB;QACvD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,aAAa,CAC9C,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,EAChG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;gBAChB,IAAI,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;oBACrB,OAAO,MAAM,CACX,IAAI,uBAAuB,CAAC;wBAC1B,OAAO,EAAE,4CAA4C;wBACrD,IAAI,EAAE,SAAS,CAAC,aAAa;wBAC7B,KAAK,EAAE,KAAK;qBACb,CAAC,CACH,CAAC;gBACJ,CAAC;gBACD,OAAO,CAAC;oBACN,GAAG,EAAE,MAAM,CAAC,UAAU;oBACtB,UAAU,EAAE,MAAM,CAAC,SAAS;oBAC5B,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,MAAM,EAAE,MAAM,CAAC,MAAM;oBACrB,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;oBAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,YAAY,EAAE,MAAM,CAAC,aAAa;iBACnC,CAAC,CAAC;YACL,CAAC,CACF,CAAC;YACF,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAoD;QAC/D,MAAM,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,CAAC,YAAY,IAAI,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IACxH,CAAC;CACF"}

package/dist/upload/FileTypeSniffer.d.ts

@@ -0,0 +1,5 @@
+/** Detects a file's real type from its first bytes, so a spoofed `Content-Type` cannot sneak past. */
+export declare class FileTypeSniffer {
+    sniff(buffer: Buffer): string | undefined;
+}
+//# sourceMappingURL=FileTypeSniffer.d.ts.map

package/dist/upload/FileTypeSniffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileTypeSniffer.d.ts","sourceRoot":"","sources":["../../src/upload/FileTypeSniffer.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,qBAAa,eAAe;IAC1B,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAexC;CACF"}

package/dist/upload/FileTypeSniffer.js

@@ -0,0 +1,27 @@
+/** Detects a file's real type from its first bytes, so a spoofed `Content-Type` cannot sneak past. */
+export class FileTypeSniffer {
+    sniff(buffer) {
+        const b = buffer;
+        if (b.length < 12)
+            return undefined;
+        if (b[0] === 0x89 && b.toString("ascii", 1, 4) === "PNG")
+            return "image/png";
+        if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff)
+            return "image/jpeg";
+        if (b.toString("ascii", 0, 3) === "GIF")
+            return "image/gif";
+        if (b.toString("ascii", 0, 4) === "RIFF" && b.toString("ascii", 8, 12) === "WEBP")
+            return "image/webp";
+        if (b.toString("ascii", 0, 5) === "%PDF-")
+            return "application/pdf";
+        if (b.toString("ascii", 4, 8) === "ftyp") {
+            return b.toString("ascii", 8, 12).startsWith("qt") ? "video/quicktime" : "video/mp4";
+        }
+        if (b[0] === 0x1a && b[1] === 0x45 && b[2] === 0xdf && b[3] === 0xa3)
+            return "video/webm";
+        if (b[0] === 0x50 && b[1] === 0x4b && b[2] === 0x03 && b[3] === 0x04)
+            return "application/zip";
+        return undefined;
+    }
+}
+//# sourceMappingURL=FileTypeSniffer.js.map

package/dist/upload/FileTypeSniffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileTypeSniffer.js","sourceRoot":"","sources":["../../src/upload/FileTypeSniffer.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,MAAM,OAAO,eAAe;IAC1B,KAAK,CAAC,MAAc;QAClB,MAAM,CAAC,GAAG,MAAM,CAAC;QACjB,IAAI,CAAC,CAAC,MAAM,GAAG,EAAE;YAAE,OAAO,SAAS,CAAC;QAEpC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK;YAAE,OAAO,WAAW,CAAC;QAC7E,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;YAAE,OAAO,YAAY,CAAC;QACzE,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK;YAAE,OAAO,WAAW,CAAC;QAC5D,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,MAAM;YAAE,OAAO,YAAY,CAAC;QACvG,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,OAAO;YAAE,OAAO,iBAAiB,CAAC;QACpE,IAAI,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;YACzC,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,WAAW,CAAC;QACvF,CAAC;QACD,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;YAAE,OAAO,YAAY,CAAC;QAC1F,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;YAAE,OAAO,iBAAiB,CAAC;QAC/F,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/upload/StorageProvider.d.ts

@@ -0,0 +1,17 @@
+import type { StoreFile } from "../types/StoreFile.js";
+import type { UploadProvider, UploadType } from "../types/upload.js";
+export interface IncomingFile {
+    buffer: Buffer;
+    originalname: string;
+    mimetype: string;
+    size: number;
+}
+/** A place files are kept (Cloudinary, S3, disk...). */
+export interface StorageProvider {
+    readonly name: UploadProvider;
+    upload(file: IncomingFile, options: {
+        type: UploadType;
+    }): Promise<StoreFile>;
+    remove(file: Pick<StoreFile, "storageKey" | "resourceType">): Promise<void>;
+}
+//# sourceMappingURL=StorageProvider.d.ts.map

package/dist/upload/StorageProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageProvider.d.ts","sourceRoot":"","sources":["../../src/upload/StorageProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9E,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,cAAc,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7E"}

package/dist/upload/StorageProvider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=StorageProvider.js.map

package/dist/upload/StorageProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageProvider.js","sourceRoot":"","sources":["../../src/upload/StorageProvider.ts"],"names":[],"mappings":""}

package/dist/upload/UploadService.d.ts

@@ -0,0 +1,40 @@
+import type { Request, RequestHandler } from "express";
+import type { ForgeConfig } from "../config/ForgeConfig.js";
+import type { StoreFile } from "../types/StoreFile.js";
+import type { Upload, UploadProvider } from "../types/upload.js";
+import type { Logger } from "../utils/Logger.js";
+import { FileTypeSniffer } from "./FileTypeSniffer.js";
+import type { IncomingFile, StorageProvider } from "./StorageProvider.js";
+/** A stored file as persisted in a document: metadata plus its own id. */
+export type StoredFile = StoreFile & {
+    _id: string;
+};
+/** Result of storing the files of one request: schema field -> files (file fields are always arrays). */
+export type StoredFiles = Record<string, StoredFile[]>;
+/** Receives, verifies and stores uploaded files. */
+export declare class UploadService {
+    private readonly config;
+    private readonly logger;
+    private readonly sniffer;
+    private readonly providers;
+    constructor(config: ForgeConfig, logger: Logger, providers?: StorageProvider[], sniffer?: FileTypeSniffer);
+    register(provider: StorageProvider): void;
+    provider(name?: UploadProvider): StorageProvider;
+    allowedMimeTypes(upload: Upload): readonly string[];
+    /** Multer middleware that parses the multipart fields declared by a route (memory storage, size limited). */
+    parser(uploads: Upload[]): RequestHandler;
+    /** Files multer put on the request, grouped by field. */
+    filesOf(req: Request): Record<string, IncomingFile[]>;
+    /** Verifies the bytes of every file, uploads them, and returns their metadata. Nothing is stored if any file is bad. */
+    store(req: Request, uploads: Upload[], options?: {
+        requireAll?: boolean;
+    }): Promise<StoredFiles>;
+    /** Best-effort removal of stored files. Never throws: used for cleanup paths. */
+    discard(items: Array<{
+        file: Pick<StoreFile, "storageKey" | "resourceType">;
+        provider?: UploadProvider | undefined;
+    }>): Promise<void>;
+    flatten(stored: StoredFiles): StoredFile[];
+    private verifyContent;
+}
+//# sourceMappingURL=UploadService.d.ts.map

package/dist/upload/UploadService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UploadService.d.ts","sourceRoot":"","sources":["../../src/upload/UploadService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAc,MAAM,oBAAoB,CAAC;AAC7E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAQ1E,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD,yGAAyG;AACzG,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;AAEvD,oDAAoD;AACpD,qBAAa,aAAa;IAItB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8C;IAExE,YACmB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EAC/B,SAAS,GAAE,eAAe,EAAO,EAChB,OAAO,kBAAwB,EAGjD;IAED,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAExC;IAED,QAAQ,CAAC,IAAI,GAAE,cAA6B,GAAG,eAAe,CAS7D;IAED,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAElD;IAED,6GAA6G;IAC7G,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,cAAc,CAqBxC;IAED,yDAAyD;IACzD,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAIpD;IAED,wHAAwH;IAClH,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAoCzG;IAED,iFAAiF;IAC3E,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,cAAc,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAU1I;IAED,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,EAAE,CAEzC;IAED,OAAO,CAAC,aAAa;CAsBtB"}

package/dist/upload/UploadService.js

@@ -0,0 +1,143 @@
+import multer from "multer";
+import { BadRequestError, ConfigurationError, ErrorCode, UnsupportedMediaTypeError } from "../errors/index.js";
+import { newObjectId } from "../utils/ids.js";
+import { FileTypeSniffer } from "./FileTypeSniffer.js";
+const DEFAULT_ALLOWED = {
+    image: ["image/jpeg", "image/png", "image/gif", "image/webp"],
+    video: ["video/mp4", "video/webm", "video/quicktime"],
+    raw: ["application/pdf"],
+};
+/** Receives, verifies and stores uploaded files. */
+export class UploadService {
+    config;
+    logger;
+    sniffer;
+    providers = new Map();
+    constructor(config, logger, providers = [], sniffer = new FileTypeSniffer()) {
+        this.config = config;
+        this.logger = logger;
+        this.sniffer = sniffer;
+        for (const provider of providers)
+            this.providers.set(provider.name, provider);
+    }
+    register(provider) {
+        this.providers.set(provider.name, provider);
+    }
+    provider(name = "cloudinary") {
+        const provider = this.providers.get(name);
+        if (!provider) {
+            throw new ConfigurationError({
+                message: `The '${name}' storage provider is not available.`,
+                hint: name === "cloudinary" ? "Set the cloudinary* options." : "Only 'cloudinary' ships with Forge; register your own StorageProvider.",
+            });
+        }
+        return provider;
+    }
+    allowedMimeTypes(upload) {
+        return upload.allowedMimeTypes ?? DEFAULT_ALLOWED[upload.type ?? "image"];
+    }
+    /** Multer middleware that parses the multipart fields declared by a route (memory storage, size limited). */
+    parser(uploads) {
+        const byField = new Map(uploads.map((u) => [u.paramField, u]));
+        const middleware = multer({
+            storage: multer.memoryStorage(),
+            limits: { fileSize: this.config.upload.maxFileSize, files: this.config.upload.maxFiles, fields: 50, parts: 100 },
+            fileFilter: (_req, file, cb) => {
+                const upload = byField.get(file.fieldname);
+                if (!upload)
+                    return cb(new multer.MulterError("LIMIT_UNEXPECTED_FILE", file.fieldname));
+                if (!this.allowedMimeTypes(upload).includes(file.mimetype)) {
+                    return cb(new UnsupportedMediaTypeError({
+                        message: `'${file.mimetype}' files are not allowed for '${file.fieldname}'.`,
+                        code: ErrorCode.UPLOAD_INVALID_TYPE,
+                        hint: `Allowed: ${this.allowedMimeTypes(upload).join(", ")}.`,
+                    }));
+                }
+                cb(null, true);
+            },
+        }).fields(uploads.map((u) => ({ name: u.paramField, maxCount: u.multiple ? this.config.upload.maxFiles : 1 })));
+        return middleware;
+    }
+    /** Files multer put on the request, grouped by field. */
+    filesOf(req) {
+        const files = req.files;
+        if (!files || Array.isArray(files))
+            return {};
+        return files;
+    }
+    /** Verifies the bytes of every file, uploads them, and returns their metadata. Nothing is stored if any file is bad. */
+    async store(req, uploads, options = {}) {
+        const incoming = this.filesOf(req);
+        // Validate everything first so we never store a partial request.
+        for (const upload of uploads) {
+            const files = incoming[upload.paramField] ?? [];
+            if (files.length === 0 && options.requireAll) {
+                throw new BadRequestError({
+                    message: `A file is required in the '${upload.paramField}' field.`,
+                    code: ErrorCode.UPLOAD_REQUIRED,
+                    hint: "Send the request as multipart/form-data.",
+                });
+            }
+            for (const file of files)
+                this.verifyContent(file, upload);
+        }
+        const stored = {};
+        const done = [];
+        try {
+            for (const upload of uploads) {
+                const files = incoming[upload.paramField] ?? [];
+                if (files.length === 0)
+                    continue;
+                const storage = this.provider(upload.provider);
+                const results = [];
+                for (const file of files) {
+                    const result = { _id: newObjectId(), ...(await storage.upload(file, { type: upload.type ?? "image" })) };
+                    done.push({ upload, file: result });
+                    results.push(result);
+                }
+                stored[upload.schemaField] = [...(stored[upload.schemaField] ?? []), ...results];
+            }
+        }
+        catch (error) {
+            await this.discard(done.map((d) => ({ file: d.file, provider: d.upload.provider })));
+            throw error;
+        }
+        return stored;
+    }
+    /** Best-effort removal of stored files. Never throws: used for cleanup paths. */
+    async discard(items) {
+        await Promise.all(items.map(async ({ file, provider }) => {
+            try {
+                await this.provider(provider).remove(file);
+            }
+            catch (error) {
+                this.logger.warn("Could not remove a stored file.", { storageKey: file.storageKey, error: String(error) });
+            }
+        }));
+    }
+    flatten(stored) {
+        return Object.values(stored).flat();
+    }
+    verifyContent(file, upload) {
+        const allowed = this.allowedMimeTypes(upload);
+        const type = upload.type ?? "image";
+        const real = this.sniffer.sniff(file.buffer);
+        if (real) {
+            if (!allowed.includes(real)) {
+                throw new UnsupportedMediaTypeError({
+                    message: `The content of '${file.originalname}' does not match an allowed file type.`,
+                    code: ErrorCode.UPLOAD_INVALID_TYPE,
+                });
+            }
+            return;
+        }
+        // Images and videos must always be recognisable; only "raw" text-like files may go unsniffed.
+        if (type !== "raw") {
+            throw new UnsupportedMediaTypeError({
+                message: `'${file.originalname}' is not a valid ${type} file.`,
+                code: ErrorCode.UPLOAD_INVALID_TYPE,
+            });
+        }
+    }
+}
+//# sourceMappingURL=UploadService.js.map

package/dist/upload/UploadService.js.map

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

package/dist/upload/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./StorageProvider.js";
+export * from "./CloudinaryStorage.js";
+export * from "./FileTypeSniffer.js";
+export * from "./UploadService.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/upload/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/upload/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC"}

package/dist/upload/index.js

@@ -0,0 +1,5 @@
+export * from "./StorageProvider.js";
+export * from "./CloudinaryStorage.js";
+export * from "./FileTypeSniffer.js";
+export * from "./UploadService.js";
+//# sourceMappingURL=index.js.map

package/dist/upload/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/upload/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC"}

package/dist/utils/Logger.d.ts

@@ -0,0 +1,22 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+/** Where log lines go. Swap it to ship logs to pino, winston, a file... */
+export interface LogSink {
+    write(level: Exclude<LogLevel, "silent">, message: string, meta?: Record<string, unknown>): void;
+}
+export declare class ConsoleSink implements LogSink {
+    write(level: Exclude<LogLevel, "silent">, message: string, meta?: Record<string, unknown>): void;
+}
+/** Minimal levelled logger. Never logs secrets: callers pass only safe metadata. */
+export declare class Logger {
+    private readonly level;
+    private readonly sink;
+    constructor(level?: LogLevel, sink?: LogSink);
+    static silent(): Logger;
+    child(): Logger;
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    private log;
+}
+//# sourceMappingURL=Logger.d.ts.map

package/dist/utils/Logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/utils/Logger.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAItE,2EAA2E;AAC3E,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAClG;AAED,qBAAa,WAAY,YAAW,OAAO;IACzC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAK/F;CACF;AAED,oFAAoF;AACpF,qBAAa,MAAM;IAEf,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFvB,YACmB,KAAK,GAAE,QAAiB,EACxB,IAAI,GAAE,OAA2B,EAChD;IAEJ,MAAM,CAAC,MAAM,IAAI,MAAM,CAEtB;IAED,KAAK,IAAI,MAAM,CAEd;IAED,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE3D;IACD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE1D;IACD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE1D;IACD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE3D;IAED,OAAO,CAAC,GAAG;CAIZ"}

package/dist/utils/Logger.js

@@ -0,0 +1,44 @@
+const ORDER = { debug: 10, info: 20, warn: 30, error: 40, silent: 100 };
+export class ConsoleSink {
+    write(level, message, meta) {
+        const line = `[${new Date().toISOString()}] ${level.toUpperCase()} ${message}`;
+        const out = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
+        if (meta && Object.keys(meta).length > 0)
+            out(line, meta);
+        else
+            out(line);
+    }
+}
+/** Minimal levelled logger. Never logs secrets: callers pass only safe metadata. */
+export class Logger {
+    level;
+    sink;
+    constructor(level = "info", sink = new ConsoleSink()) {
+        this.level = level;
+        this.sink = sink;
+    }
+    static silent() {
+        return new Logger("silent");
+    }
+    child() {
+        return this;
+    }
+    debug(message, meta) {
+        this.log("debug", message, meta);
+    }
+    info(message, meta) {
+        this.log("info", message, meta);
+    }
+    warn(message, meta) {
+        this.log("warn", message, meta);
+    }
+    error(message, meta) {
+        this.log("error", message, meta);
+    }
+    log(level, message, meta) {
+        if (ORDER[level] < ORDER[this.level])
+            return;
+        this.sink.write(level, message, meta);
+    }
+}
+//# sourceMappingURL=Logger.js.map

package/dist/utils/Logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.js","sourceRoot":"","sources":["../../src/utils/Logger.ts"],"names":[],"mappings":"AAEA,MAAM,KAAK,GAA6B,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AAOlG,MAAM,OAAO,WAAW;IACtB,KAAK,CAAC,KAAkC,EAAE,OAAe,EAAE,IAA8B;QACvF,MAAM,IAAI,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,WAAW,EAAE,IAAI,OAAO,EAAE,CAAC;QAC/E,MAAM,GAAG,GAAG,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;QAC9F,IAAI,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;;YACrD,GAAG,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;CACF;AAED,oFAAoF;AACpF,MAAM,OAAO,MAAM;IAEE,KAAK;IACL,IAAI;IAFvB,YACmB,KAAK,GAAa,MAAM,EACxB,IAAI,GAAY,IAAI,WAAW,EAAE;qBADjC,KAAK;oBACL,IAAI;IACpB,CAAC;IAEJ,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAA8B;QACnD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,CAAC,OAAe,EAAE,IAA8B;QAClD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,OAAe,EAAE,IAA8B;QAClD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IACD,KAAK,CAAC,OAAe,EAAE,IAA8B;QACnD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAEO,GAAG,CAAC,KAAkC,EAAE,OAAe,EAAE,IAA8B;QAC7F,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO;QAC7C,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC;CACF"}

package/dist/utils/html.d.ts

@@ -0,0 +1,7 @@
+/** Escapes text for safe use in HTML content and attribute values. */
+export declare const escapeHtml: (value: string) => string;
+/** Allows only http(s) and mailto links; anything else (e.g. `javascript:`) becomes `#`. */
+export declare const safeUrl: (value: string) => string;
+/** Removes CR/LF so a value can never inject extra e-mail headers. */
+export declare const stripNewlines: (value: string) => string;
+//# sourceMappingURL=html.d.ts.map

package/dist/utils/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/utils/html.ts"],"names":[],"mappings":"AASA,sEAAsE;AACtE,eAAO,MAAM,UAAU,UAAW,MAAM,KAAG,MAA6D,CAAC;AAEzG,4FAA4F;AAC5F,eAAO,MAAM,OAAO,UAAW,MAAM,KAAG,MAQvC,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,aAAa,UAAW,MAAM,KAAG,MAA+C,CAAC"}

package/dist/utils/html.js

@@ -0,0 +1,24 @@
+const ENTITIES = {
+    "&": "&",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+    "`": "&#96;",
+};
+/** Escapes text for safe use in HTML content and attribute values. */
+export const escapeHtml = (value) => value.replace(/[&<>"'`]/g, (c) => ENTITIES[c] ?? c);
+/** Allows only http(s) and mailto links; anything else (e.g. `javascript:`) becomes `#`. */
+export const safeUrl = (value) => {
+    const trimmed = value.trim();
+    try {
+        const url = new URL(trimmed);
+        return ["http:", "https:", "mailto:"].includes(url.protocol) ? trimmed : "#";
+    }
+    catch {
+        return "#";
+    }
+};
+/** Removes CR/LF so a value can never inject extra e-mail headers. */
+export const stripNewlines = (value) => value.replace(/[\r\n]+/g, " ").trim();
+//# sourceMappingURL=html.js.map

package/dist/utils/html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.js","sourceRoot":"","sources":["../../src/utils/html.ts"],"names":[],"mappings":"AAAA,MAAM,QAAQ,GAA2B;IACvC,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,OAAO;CACb,CAAC;AAEF,sEAAsE;AACtE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAEzG,4FAA4F;AAC5F,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAU,EAAE;IAC/C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QAC7B,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC,CAAC;AAEF,sEAAsE;AACtE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC"}

package/dist/utils/ids.d.ts

@@ -0,0 +1,7 @@
+/** True for a 24-character hex string (the only form Forge accepts as a document id). */
+export declare const isObjectId: (value: unknown) => value is string;
+/** Generates a MongoDB-compatible ObjectId string without needing a driver. */
+export declare const newObjectId: () => string;
+/** Normalises an id-ish value (string, ObjectId, `{ _id }`) to a string. */
+export declare const idToString: (value: unknown) => string | undefined;
+//# sourceMappingURL=ids.d.ts.map

package/dist/utils/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/utils/ids.ts"],"names":[],"mappings":"AAIA,yFAAyF;AACzF,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,KAAK,IAAI,MACD,CAAC;AAErD,+EAA+E;AAC/E,eAAO,MAAM,WAAW,QAAO,MAG9B,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,MAAM,GAAG,SASpD,CAAC"}

package/dist/utils/ids.js

@@ -0,0 +1,25 @@
+import { randomBytes } from "node:crypto";
+const OBJECT_ID = /^[0-9a-fA-F]{24}$/;
+/** True for a 24-character hex string (the only form Forge accepts as a document id). */
+export const isObjectId = (value) => typeof value === "string" && OBJECT_ID.test(value);
+/** Generates a MongoDB-compatible ObjectId string without needing a driver. */
+export const newObjectId = () => {
+    const time = Math.floor(Date.now() / 1000).toString(16).padStart(8, "0");
+    return time + randomBytes(8).toString("hex");
+};
+/** Normalises an id-ish value (string, ObjectId, `{ _id }`) to a string. */
+export const idToString = (value) => {
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "object") {
+        const v = value;
+        if (typeof v.toHexString === "function")
+            return v.toHexString();
+        if (v._id !== undefined && v._id !== value)
+            return idToString(v._id);
+    }
+    return String(value);
+};
+//# sourceMappingURL=ids.js.map

package/dist/utils/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/utils/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAEtC,yFAAyF;AACzF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAc,EAAmB,EAAE,CAC5D,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAErD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,WAAW,GAAG,GAAW,EAAE;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACzE,OAAO,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/C,CAAC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAc,EAAsB,EAAE;IAC/D,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,KAAsD,CAAC;QACjE,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,UAAU;YAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;QAChE,IAAI,CAAC,CAAC,GAAG,KAAK,SAAS,IAAI,CAAC,CAAC,GAAG,KAAK,KAAK;YAAE,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./Logger.js";
+export * from "./ids.js";
+export * from "./html.js";
+export * from "./sanitizeInput.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,5 @@
+export * from "./Logger.js";
+export * from "./ids.js";
+export * from "./html.js";
+export * from "./sanitizeInput.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC"}

package/dist/utils/sanitizeInput.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Removes keys that enable NoSQL operator injection (`$ne`, `$gt`...), dotted
+ * path injection (`a.b`), and prototype pollution - in place, recursively.
+ * Works on `req.body`, `req.query` and `req.params`.
+ */
+export declare const stripDangerousKeys: (value: unknown, depth?: number) => void;
+/** Copies `source` without the listed keys (non-mutating). */
+export declare const omitKeys: <T extends Record<string, unknown>>(source: T, keys: readonly string[]) => Partial<T>;
+//# sourceMappingURL=sanitizeInput.d.ts.map

package/dist/utils/sanitizeInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizeInput.d.ts","sourceRoot":"","sources":["../../src/utils/sanitizeInput.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,UAAW,OAAO,qBAAc,IAgB9D,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,QAAQ,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,CAAC,CAIzG,CAAC"}

package/dist/utils/sanitizeInput.js

@@ -0,0 +1,32 @@
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Removes keys that enable NoSQL operator injection (`$ne`, `$gt`...), dotted
+ * path injection (`a.b`), and prototype pollution - in place, recursively.
+ * Works on `req.body`, `req.query` and `req.params`.
+ */
+export const stripDangerousKeys = (value, depth = 0) => {
+    if (depth > 20 || value === null || typeof value !== "object")
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            stripDangerousKeys(item, depth + 1);
+        return;
+    }
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (key.startsWith("$") || key.includes(".") || FORBIDDEN_KEYS.has(key)) {
+            delete record[key];
+        }
+        else {
+            stripDangerousKeys(record[key], depth + 1);
+        }
+    }
+};
+/** Copies `source` without the listed keys (non-mutating). */
+export const omitKeys = (source, keys) => {
+    const copy = { ...source };
+    for (const key of keys)
+        delete copy[key];
+    return copy;
+};
+//# sourceMappingURL=sanitizeInput.js.map

package/dist/utils/sanitizeInput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizeInput.js","sourceRoot":"","sources":["../../src/utils/sanitizeInput.ts"],"names":[],"mappings":"AAAA,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC;AAE1E;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAc,EAAE,KAAK,GAAG,CAAC,EAAQ,EAAE;IACpE,IAAI,KAAK,GAAG,EAAE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO;IAEtE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,kBAAkB,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAC9D,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACxE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;aAAM,CAAC;YACN,kBAAkB,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAoC,MAAS,EAAE,IAAuB,EAAc,EAAE;IAC5G,MAAM,IAAI,GAA4B,EAAE,GAAG,MAAM,EAAE,CAAC;IACpD,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;IACzC,OAAO,IAAkB,CAAC;AAC5B,CAAC,CAAC"}