@beechcms/core 0.7.0 → 0.8.1

package/dist/media/file-types.d.ts

@@ -1,13 +1,107 @@
+/**
+ * File acceptance filter categories used by branch schemas and forms.
+ */
 export type FileAccept = 'image' | 'document' | 'any';
-export declare const IMAGE_EXTENSIONS: Set<string>;
-export declare const BLOCKED_IMAGE_EXTENSIONS: Set<string>;
-export declare const DOCUMENT_EXTENSIONS: Set<string>;
-export declare const ARCHIVE_EXTENSIONS: Set<string>;
-export declare const IMAGE_MIME_TYPES: readonly ["image/jpeg", "image/png", "image/gif", "image/webp", "image/avif", "image/bmp", "image/x-icon", "image/vnd.microsoft.icon"];
-export declare const BLOCKED_IMAGE_MIME_TYPES: readonly ["image/svg+xml", "image/svg"];
-export declare const DOCUMENT_MIME_TYPES: readonly ["application/pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-powerpoint", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "text/plain", "text/csv", "text/markdown"];
-export declare const ARCHIVE_MIME_TYPES: readonly ["application/zip", "application/x-zip-compressed", "application/x-7z-compressed", "application/x-tar", "application/gzip", "application/json"];
+/**
+ * High-level categorization of supported file types.
+ */
+export type FileCategory = 'image' | 'document' | 'archive';
+/**
+ * Definition of a supported file format in BeechCMS, including MIME types,
+ * binary classification, and binary signature verification rules.
+ */
+export interface FileTypeDefinition {
+    /** File extension without leading dot (e.g. 'jpg', 'png', 'pdf'). */
+    readonly extension: string;
+    /** Canonical primary MIME type (e.g. 'image/jpeg'). */
+    readonly primaryMime: string;
+    /** All valid MIME types associated with this format. */
+    readonly mimeTypes: readonly string[];
+    /** High-level file category. */
+    readonly category: FileCategory;
+    /** Whether the file is a binary format requiring magic byte signature validation. */
+    readonly isBinary: boolean;
+    /** Expected magic bytes prefix if the format uses a static prefix. */
+    readonly magicBytes?: readonly number[];
+    /** Custom signature matching function for formats with complex, variable, or offset headers. */
+    readonly matchSignature?: (bytes: Uint8Array) => boolean;
+}
+/**
+ * Checks whether a byte buffer starts with a specified byte prefix.
+ *
+ * @param bytes - The byte buffer to inspect.
+ * @param prefix - The sequence of bytes to match against.
+ * @returns True if the buffer starts with the given prefix, false otherwise.
+ */
+export declare function matchBytePrefix(bytes: Uint8Array, prefix: readonly number[]): boolean;
+/**
+ * Evaluates whether the given byte buffer matches the binary signature of a file definition.
+ *
+ * @param def - The file type definition to check against.
+ * @param bytes - The raw byte buffer to inspect.
+ * @returns True if the bytes match the definition's signature rules, false otherwise.
+ */
+export declare function matchesFileSignature(def: FileTypeDefinition, bytes: Uint8Array): boolean;
+/**
+ * Single source of truth registry for all supported file types in BeechCMS.
+ */
+export declare const SUPPORTED_FILE_TYPES: Record<string, FileTypeDefinition>;
+/**
+ * SVG is intentionally blocked from general file upload as it can embed executable scripts
+ * creating a stored XSS vulnerability when served directly to browsers.
+ */
+export declare const BLOCKED_IMAGE_EXTENSIONS: ReadonlySet<string>;
+/**
+ * Blocked MIME types associated with unsafe image formats.
+ */
+export declare const BLOCKED_IMAGE_MIME_TYPES: readonly string[];
+/** Set of supported image file extensions. */
+export declare const IMAGE_EXTENSIONS: ReadonlySet<string>;
+/** Set of supported document file extensions. */
+export declare const DOCUMENT_EXTENSIONS: ReadonlySet<string>;
+/** Set of supported archive file extensions. */
+export declare const ARCHIVE_EXTENSIONS: ReadonlySet<string>;
+/** List of supported image MIME types. */
+export declare const IMAGE_MIME_TYPES: readonly string[];
+/** List of supported document MIME types. */
+export declare const DOCUMENT_MIME_TYPES: readonly string[];
+/** List of supported archive MIME types. */
+export declare const ARCHIVE_MIME_TYPES: readonly string[];
+/**
+ * Look up a supported file type definition by its extension.
+ *
+ * @param ext - The extension string with or without leading dot.
+ * @returns The matching FileTypeDefinition, or undefined if unsupported.
+ */
+export declare function getFileTypeByExtension(ext: string | null | undefined): FileTypeDefinition | undefined;
+/**
+ * Look up a supported file type definition by its declared MIME type.
+ *
+ * @param mime - The MIME string (e.g. 'image/png' or 'image/jpeg; charset=utf-8').
+ * @returns The matching FileTypeDefinition, or undefined if unsupported.
+ */
+export declare function getFileTypeByMime(mime: string | null | undefined): FileTypeDefinition | undefined;
+/**
+ * Extracts a lowercase file extension from a URL string or query parameters.
+ *
+ * @param url - The URL string to parse.
+ * @returns The extracted extension, or null if none was found.
+ */
 export declare function extensionFromUrl(url: string): string | null;
-export declare function isExtensionAccepted(ext: string | null, accept: FileAccept): boolean;
+/**
+ * Checks whether a given file extension satisfies an acceptance policy ('image' | 'document' | 'any').
+ *
+ * @param ext - The file extension.
+ * @param accept - The acceptance mode.
+ * @returns True if accepted, false otherwise.
+ */
+export declare function isExtensionAccepted(ext: string | null | undefined, accept: FileAccept): boolean;
+/**
+ * Checks whether a given MIME type satisfies an acceptance policy ('image' | 'document' | 'any').
+ *
+ * @param mime - The declared MIME string.
+ * @param accept - The acceptance mode.
+ * @returns True if accepted, false otherwise.
+ */
 export declare function isMimeAccepted(mime: string, accept: FileAccept): boolean;
 //# sourceMappingURL=file-types.d.ts.map

package/dist/media/file-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-types.d.ts","sourceRoot":"","sources":["../../src/media/file-types.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,KAAK,CAAA;AAKrD,eAAO,MAAM,gBAAgB,aAAuE,CAAA;AACpG,eAAO,MAAM,wBAAwB,aAA2B,CAAA;AAChE,eAAO,MAAM,mBAAmB,aAAoF,CAAA;AACpH,eAAO,MAAM,kBAAkB,aAA8C,CAAA;AAI7E,eAAO,MAAM,gBAAgB,wIASnB,CAAA;AAGV,eAAO,MAAM,wBAAwB,yCAA0C,CAAA;AAC/E,eAAO,MAAM,mBAAmB,yXAWtB,CAAA;AACV,eAAO,MAAM,kBAAkB,0JAOrB,CAAA;AAEV,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgB3D;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAOnF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAcxE"}
+{"version":3,"file":"file-types.d.ts","sourceRoot":"","sources":["../../src/media/file-types.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,KAAK,CAAA;AAErD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAA;AAE3D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC,gGAAgG;IAChG,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAA;CACzD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAMrF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,kBAAkB,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAKxF;AA6CD;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAgMnE,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAA4B,CAAA;AAErF;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAAmC,CAAA;AAIzF,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAEhD,CAAA;AAED,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAEnD,CAAA;AAED,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAElD,CAAA;AAED,0CAA0C;AAC1C,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAE7C,CAAA;AAED,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAEhD,CAAA;AAED,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAE/C,CAAA;AAMD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAIrG;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAMjG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgB3D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAO/F;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CASxE"}

package/dist/media/file-types.js

@@ -1,47 +1,322 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2024–2026 Flavio De Musso
-// SVG is intentionally excluded: SVG can embed <script> tags and is rendered
-// inline by browsers when served as image/svg+xml on a same-origin route,
-// creating a stored XSS vector (see security audit finding #4).
-export const IMAGE_EXTENSIONS = new Set(['jpg', 'jpeg', 'png', 'gif', 'webp', 'avif', 'bmp', 'ico']);
+/**
+ * Checks whether a byte buffer starts with a specified byte prefix.
+ *
+ * @param bytes - The byte buffer to inspect.
+ * @param prefix - The sequence of bytes to match against.
+ * @returns True if the buffer starts with the given prefix, false otherwise.
+ */
+export function matchBytePrefix(bytes, prefix) {
+    if (bytes.length < prefix.length)
+        return false;
+    for (let i = 0; i < prefix.length; i++) {
+        if (bytes[i] !== prefix[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Evaluates whether the given byte buffer matches the binary signature of a file definition.
+ *
+ * @param def - The file type definition to check against.
+ * @param bytes - The raw byte buffer to inspect.
+ * @returns True if the bytes match the definition's signature rules, false otherwise.
+ */
+export function matchesFileSignature(def, bytes) {
+    if (!def.isBinary)
+        return true;
+    if (def.matchSignature)
+        return def.matchSignature(bytes);
+    if (def.magicBytes)
+        return matchBytePrefix(bytes, def.magicBytes);
+    return false;
+}
+/** OLE Compound File Binary Format (CFBF) header used by legacy MS Office files (.doc, .xls, .ppt). */
+const OLE_MAGIC = [0xD0, 0xCF, 0x11, 0xE0, 0xA1, 0xB1, 0x1A, 0xE1];
+/** Matcher for OLE CFBF binary files. */
+function matchOleSignature(bytes) {
+    return matchBytePrefix(bytes, OLE_MAGIC);
+}
+/** Standard ZIP header matcher used by .zip and Office OpenXML (.docx, .xlsx, .pptx). */
+function matchZipSignature(bytes) {
+    if (bytes.length < 4)
+        return false;
+    return ((bytes[0] === 0x50 && bytes[1] === 0x4B && bytes[2] === 0x03 && bytes[3] === 0x04) || // standard zip
+        (bytes[0] === 0x50 && bytes[1] === 0x4B && bytes[2] === 0x05 && bytes[3] === 0x06) || // empty zip
+        (bytes[0] === 0x50 && bytes[1] === 0x4B && bytes[2] === 0x07 && bytes[3] === 0x08) // spanned zip
+    );
+}
+/** Common shared definition for JPEG files. */
+const JPEG_DEFINITION = {
+    primaryMime: 'image/jpeg',
+    mimeTypes: ['image/jpeg', 'image/jpg'],
+    category: 'image',
+    isBinary: true,
+    magicBytes: [0xFF, 0xD8, 0xFF],
+};
+/** Common shared definition for legacy MS Office files. */
+const OLE_DOCUMENT_DEFINITION = {
+    category: 'document',
+    isBinary: true,
+    magicBytes: [...OLE_MAGIC],
+    matchSignature: matchOleSignature,
+};
+/** Common shared definition for OpenXML Office files. */
+const OPENXML_DOCUMENT_DEFINITION = {
+    category: 'document',
+    isBinary: true,
+    magicBytes: [0x50, 0x4B, 0x03, 0x04],
+    matchSignature: matchZipSignature,
+};
+/**
+ * Single source of truth registry for all supported file types in BeechCMS.
+ */
+export const SUPPORTED_FILE_TYPES = {
+    // --- IMAGES ---
+    jpg: {
+        extension: 'jpg',
+        ...JPEG_DEFINITION,
+    },
+    jpeg: {
+        extension: 'jpeg',
+        ...JPEG_DEFINITION,
+    },
+    png: {
+        extension: 'png',
+        primaryMime: 'image/png',
+        mimeTypes: ['image/png'],
+        category: 'image',
+        isBinary: true,
+        magicBytes: [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A],
+    },
+    gif: {
+        extension: 'gif',
+        primaryMime: 'image/gif',
+        mimeTypes: ['image/gif'],
+        category: 'image',
+        isBinary: true,
+        magicBytes: [0x47, 0x49, 0x46, 0x38],
+        matchSignature: (bytes) => bytes.length >= 6 &&
+            bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x38 &&
+            (bytes[4] === 0x37 || bytes[4] === 0x39) && bytes[5] === 0x61,
+    },
+    webp: {
+        extension: 'webp',
+        primaryMime: 'image/webp',
+        mimeTypes: ['image/webp'],
+        category: 'image',
+        isBinary: true,
+        magicBytes: [0x52, 0x49, 0x46, 0x46],
+        matchSignature: (bytes) => bytes.length >= 12 &&
+            bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46 &&
+            bytes[8] === 0x57 && bytes[9] === 0x45 && bytes[10] === 0x42 && bytes[11] === 0x50,
+    },
+    avif: {
+        extension: 'avif',
+        primaryMime: 'image/avif',
+        mimeTypes: ['image/avif'],
+        category: 'image',
+        isBinary: true,
+        magicBytes: [0x66, 0x74, 0x79, 0x70],
+        matchSignature: (bytes) => {
+            if (bytes.length < 12)
+                return false;
+            // Check for 'ftyp' at offset 4
+            const isFtyp = bytes[4] === 0x66 && bytes[5] === 0x74 && bytes[6] === 0x79 && bytes[7] === 0x70;
+            if (!isFtyp)
+                return false;
+            // Brand check: 'avif', 'avis', 'mif1', 'msf1'
+            const brand = String.fromCharCode(bytes[8], bytes[9], bytes[10], bytes[11]);
+            return brand === 'avif' || brand === 'avis' || brand === 'mif1' || brand === 'msf1';
+        },
+    },
+    bmp: {
+        extension: 'bmp',
+        primaryMime: 'image/bmp',
+        mimeTypes: ['image/bmp'],
+        category: 'image',
+        isBinary: true,
+        magicBytes: [0x42, 0x4D],
+    },
+    ico: {
+        extension: 'ico',
+        primaryMime: 'image/x-icon',
+        mimeTypes: ['image/x-icon', 'image/vnd.microsoft.icon'],
+        category: 'image',
+        isBinary: true,
+        magicBytes: [0x00, 0x00, 0x01, 0x00],
+    },
+    // --- DOCUMENTS ---
+    pdf: {
+        extension: 'pdf',
+        primaryMime: 'application/pdf',
+        mimeTypes: ['application/pdf'],
+        category: 'document',
+        isBinary: true,
+        magicBytes: [0x25, 0x50, 0x44, 0x46],
+    },
+    docx: {
+        extension: 'docx',
+        primaryMime: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        mimeTypes: ['application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
+        ...OPENXML_DOCUMENT_DEFINITION,
+    },
+    doc: {
+        extension: 'doc',
+        primaryMime: 'application/msword',
+        mimeTypes: ['application/msword'],
+        ...OLE_DOCUMENT_DEFINITION,
+    },
+    xlsx: {
+        extension: 'xlsx',
+        primaryMime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        mimeTypes: ['application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
+        ...OPENXML_DOCUMENT_DEFINITION,
+    },
+    xls: {
+        extension: 'xls',
+        primaryMime: 'application/vnd.ms-excel',
+        mimeTypes: ['application/vnd.ms-excel'],
+        ...OLE_DOCUMENT_DEFINITION,
+    },
+    pptx: {
+        extension: 'pptx',
+        primaryMime: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+        mimeTypes: ['application/vnd.openxmlformats-officedocument.presentationml.presentation'],
+        ...OPENXML_DOCUMENT_DEFINITION,
+    },
+    ppt: {
+        extension: 'ppt',
+        primaryMime: 'application/vnd.ms-powerpoint',
+        mimeTypes: ['application/vnd.ms-powerpoint'],
+        ...OLE_DOCUMENT_DEFINITION,
+    },
+    txt: {
+        extension: 'txt',
+        primaryMime: 'text/plain',
+        mimeTypes: ['text/plain'],
+        category: 'document',
+        isBinary: false,
+    },
+    csv: {
+        extension: 'csv',
+        primaryMime: 'text/csv',
+        mimeTypes: ['text/csv'],
+        category: 'document',
+        isBinary: false,
+    },
+    md: {
+        extension: 'md',
+        primaryMime: 'text/markdown',
+        mimeTypes: ['text/markdown'],
+        category: 'document',
+        isBinary: false,
+    },
+    // --- ARCHIVES & DATA ---
+    zip: {
+        extension: 'zip',
+        primaryMime: 'application/zip',
+        mimeTypes: ['application/zip', 'application/x-zip-compressed'],
+        category: 'archive',
+        isBinary: true,
+        magicBytes: [0x50, 0x4B, 0x03, 0x04],
+        matchSignature: matchZipSignature,
+    },
+    '7z': {
+        extension: '7z',
+        primaryMime: 'application/x-7z-compressed',
+        mimeTypes: ['application/x-7z-compressed'],
+        category: 'archive',
+        isBinary: true,
+        magicBytes: [0x37, 0x7A, 0xBC, 0xAF, 0x27, 0x1C],
+    },
+    tar: {
+        extension: 'tar',
+        primaryMime: 'application/x-tar',
+        mimeTypes: ['application/x-tar'],
+        category: 'archive',
+        isBinary: true,
+        magicBytes: [0x75, 0x73, 0x74, 0x61, 0x72], // 'ustar'
+        matchSignature: (bytes) => {
+            if (bytes.length < 512)
+                return false;
+            // Check for POSIX 'ustar' at offset 257
+            return (bytes[257] === 0x75 && bytes[258] === 0x73 && bytes[259] === 0x74 &&
+                bytes[260] === 0x61 && bytes[261] === 0x72);
+        },
+    },
+    gz: {
+        extension: 'gz',
+        primaryMime: 'application/gzip',
+        mimeTypes: ['application/gzip'],
+        category: 'archive',
+        isBinary: true,
+        magicBytes: [0x1F, 0x8B],
+    },
+    json: {
+        extension: 'json',
+        primaryMime: 'application/json',
+        mimeTypes: ['application/json'],
+        category: 'archive',
+        isBinary: false,
+    },
+};
+/**
+ * SVG is intentionally blocked from general file upload as it can embed executable scripts
+ * creating a stored XSS vulnerability when served directly to browsers.
+ */
 export const BLOCKED_IMAGE_EXTENSIONS = new Set(['svg', 'svgz']);
-export const DOCUMENT_EXTENSIONS = new Set(['pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'txt', 'csv', 'md']);
-export const ARCHIVE_EXTENSIONS = new Set(['zip', '7z', 'tar', 'gz', 'json']);
-// Explicitly enumerate safe image MIME types instead of using the wildcard
-// `image/*` prefix, which would permit `image/svg+xml` and other XSS vectors.
-export const IMAGE_MIME_TYPES = [
-    'image/jpeg',
-    'image/png',
-    'image/gif',
-    'image/webp',
-    'image/avif',
-    'image/bmp',
-    'image/x-icon',
-    'image/vnd.microsoft.icon',
-];
-// Blocked image MIME types — listed explicitly so upload code can reject them
-// with a clear error rather than a generic "file type not allowed".
+/**
+ * Blocked MIME types associated with unsafe image formats.
+ */
 export const BLOCKED_IMAGE_MIME_TYPES = ['image/svg+xml', 'image/svg'];
-export const DOCUMENT_MIME_TYPES = [
-    'application/pdf',
-    'application/msword',
-    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-    'application/vnd.ms-excel',
-    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-    'application/vnd.ms-powerpoint',
-    'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-    'text/plain',
-    'text/csv',
-    'text/markdown',
-];
-export const ARCHIVE_MIME_TYPES = [
-    'application/zip',
-    'application/x-zip-compressed',
-    'application/x-7z-compressed',
-    'application/x-tar',
-    'application/gzip',
-    'application/json',
-];
+const BLOCKED_IMAGE_MIME_SET = new Set(BLOCKED_IMAGE_MIME_TYPES);
+/** Set of supported image file extensions. */
+export const IMAGE_EXTENSIONS = new Set(Object.values(SUPPORTED_FILE_TYPES).filter((def) => def.category === 'image').map((def) => def.extension));
+/** Set of supported document file extensions. */
+export const DOCUMENT_EXTENSIONS = new Set(Object.values(SUPPORTED_FILE_TYPES).filter((def) => def.category === 'document').map((def) => def.extension));
+/** Set of supported archive file extensions. */
+export const ARCHIVE_EXTENSIONS = new Set(Object.values(SUPPORTED_FILE_TYPES).filter((def) => def.category === 'archive').map((def) => def.extension));
+/** List of supported image MIME types. */
+export const IMAGE_MIME_TYPES = Array.from(new Set(Object.values(SUPPORTED_FILE_TYPES).filter((def) => def.category === 'image').flatMap((def) => def.mimeTypes)));
+/** List of supported document MIME types. */
+export const DOCUMENT_MIME_TYPES = Array.from(new Set(Object.values(SUPPORTED_FILE_TYPES).filter((def) => def.category === 'document').flatMap((def) => def.mimeTypes)));
+/** List of supported archive MIME types. */
+export const ARCHIVE_MIME_TYPES = Array.from(new Set(Object.values(SUPPORTED_FILE_TYPES).filter((def) => def.category === 'archive').flatMap((def) => def.mimeTypes)));
+const IMAGE_MIME_SET = new Set(IMAGE_MIME_TYPES);
+const DOCUMENT_MIME_SET = new Set(DOCUMENT_MIME_TYPES);
+const ARCHIVE_MIME_SET = new Set(ARCHIVE_MIME_TYPES);
+/**
+ * Look up a supported file type definition by its extension.
+ *
+ * @param ext - The extension string with or without leading dot.
+ * @returns The matching FileTypeDefinition, or undefined if unsupported.
+ */
+export function getFileTypeByExtension(ext) {
+    if (!ext)
+        return undefined;
+    const normalised = ext.replace(/^\./, '').toLowerCase().trim();
+    return SUPPORTED_FILE_TYPES[normalised];
+}
+/**
+ * Look up a supported file type definition by its declared MIME type.
+ *
+ * @param mime - The MIME string (e.g. 'image/png' or 'image/jpeg; charset=utf-8').
+ * @returns The matching FileTypeDefinition, or undefined if unsupported.
+ */
+export function getFileTypeByMime(mime) {
+    if (!mime)
+        return undefined;
+    const normalised = mime.split(';')[0].trim().toLowerCase();
+    return Object.values(SUPPORTED_FILE_TYPES).find((def) => def.mimeTypes.some((m) => m.toLowerCase() === normalised));
+}
+/**
+ * Extracts a lowercase file extension from a URL string or query parameters.
+ *
+ * @param url - The URL string to parse.
+ * @returns The extracted extension, or null if none was found.
+ */
 export function extensionFromUrl(url) {
     try {
         const parsed = new URL(url);
@@ -50,9 +325,9 @@ export function extensionFromUrl(url) {
         if (dot >= 0 && dot < path.length - 1) {
             return path.slice(dot + 1).toLowerCase();
         }
-        const fm = parsed.searchParams.get('fm') || parsed.searchParams.get('format') || parsed.searchParams.get('ext');
-        if (fm && /^[a-z0-9]+$/i.test(fm)) {
-            return fm.toLowerCase();
+        const param = parsed.searchParams.get('fm') || parsed.searchParams.get('format') || parsed.searchParams.get('ext');
+        if (param && /^[a-z0-9]+$/i.test(param)) {
+            return param.toLowerCase();
         }
         return null;
     }
@@ -60,6 +335,13 @@ export function extensionFromUrl(url) {
         return null;
     }
 }
+/**
+ * Checks whether a given file extension satisfies an acceptance policy ('image' | 'document' | 'any').
+ *
+ * @param ext - The file extension.
+ * @param accept - The acceptance mode.
+ * @returns True if accepted, false otherwise.
+ */
 export function isExtensionAccepted(ext, accept) {
     if (accept === 'any')
         return true;
@@ -73,21 +355,23 @@ export function isExtensionAccepted(ext, accept) {
         return DOCUMENT_EXTENSIONS.has(ext);
     return false;
 }
+/**
+ * Checks whether a given MIME type satisfies an acceptance policy ('image' | 'document' | 'any').
+ *
+ * @param mime - The declared MIME string.
+ * @param accept - The acceptance mode.
+ * @returns True if accepted, false otherwise.
+ */
 export function isMimeAccepted(mime, accept) {
-    // Normalise: strip parameters (e.g. "image/jpeg; charset=utf-8" → "image/jpeg")
     const normalised = mime.split(';')[0].trim().toLowerCase();
-    // Unconditionally reject SVG regardless of accept mode — SVG can carry
-    // embedded scripts and is rendered by browsers when served inline.
-    if (BLOCKED_IMAGE_MIME_TYPES.includes(normalised))
+    if (BLOCKED_IMAGE_MIME_SET.has(normalised))
         return false;
     if (accept === 'any') {
-        return IMAGE_MIME_TYPES.includes(normalised)
-            || DOCUMENT_MIME_TYPES.includes(normalised)
-            || ARCHIVE_MIME_TYPES.includes(normalised);
+        return IMAGE_MIME_SET.has(normalised) || DOCUMENT_MIME_SET.has(normalised) || ARCHIVE_MIME_SET.has(normalised);
     }
     if (accept === 'image')
-        return IMAGE_MIME_TYPES.includes(normalised);
+        return IMAGE_MIME_SET.has(normalised);
     if (accept === 'document')
-        return DOCUMENT_MIME_TYPES.includes(normalised);
+        return DOCUMENT_MIME_SET.has(normalised);
     return false;
 }

package/dist/media/image-transformer.d.ts

@@ -0,0 +1,34 @@
+/** Pixel dimensions of an image. */
+export interface MediaDimensions {
+    readonly width: number;
+    readonly height: number;
+}
+/** Output MIME types the transform path may emit. AVIF is deliberately absent (v1). */
+export type ImageOutputMime = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+/**
+ * A fully resolved transformation. Every number here comes from a pre-registered preset or from
+ * MEDIA_QUALITY_VALUES — never from the request.
+ */
+export interface ImageTransformSpec {
+    readonly width: number;
+    /** Present for crop presets only; scale presets derive height from the source aspect ratio. */
+    readonly height?: number;
+    readonly fit: 'cover' | 'scale-down';
+    readonly outputMime: ImageOutputMime;
+    readonly quality: number;
+}
+export interface TransformedImage {
+    readonly body: ReadableStream<Uint8Array>;
+    readonly contentType: string;
+}
+/**
+ * Port for edge image transformation. The API injects a Cloudflare Images adapter when the
+ * `IMAGES` binding exists and `null` otherwise; handlers never see the binding itself.
+ */
+export interface IImageTransformer {
+    /** Reads the source's pixel dimensions. Rejects when the stream is not a raster image. */
+    probe(source: ReadableStream<Uint8Array>): Promise<MediaDimensions>;
+    /** Applies the spec and returns the encoded variant. */
+    transform(source: ReadableStream<Uint8Array>, spec: ImageTransformSpec): Promise<TransformedImage>;
+}
+//# sourceMappingURL=image-transformer.d.ts.map

package/dist/media/image-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-transformer.d.ts","sourceRoot":"","sources":["../../src/media/image-transformer.ts"],"names":[],"mappings":"AAGA,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,uFAAuF;AACvF,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,YAAY,CAAA;AAErF;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAA;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IACnE,wDAAwD;IACxD,SAAS,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;CACnG"}

package/dist/media/image-transformer.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/media/magic-bytes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Result of a file magic bytes signature validation.
+ */
+export interface MagicBytesValidationResult {
+    /** Whether the byte buffer matches the declared format signature. */
+    valid: boolean;
+    /** Detected canonical primary MIME type if valid or identified. */
+    detectedMime?: string;
+    /** Human-readable error description when validation fails. */
+    error?: string;
+}
+/**
+ * Validates that an uploaded file's binary content matches its declared MIME type,
+ * protecting against MIME-spoofing, disguised executables, and blocked formats (e.g. SVG).
+ *
+ * @param buffer - The raw binary buffer (ArrayBuffer or Uint8Array).
+ * @param declaredMime - The client-declared MIME type string.
+ * @returns A MagicBytesValidationResult indicating validity and details.
+ */
+export declare function verifyMagicBytes(buffer: ArrayBuffer | Uint8Array, declaredMime: string): MagicBytesValidationResult;
+//# sourceMappingURL=magic-bytes.d.ts.map

package/dist/media/magic-bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic-bytes.d.ts","sourceRoot":"","sources":["../../src/media/magic-bytes.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAA;IACd,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAiBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,GAAG,UAAU,EAChC,YAAY,EAAE,MAAM,GACnB,0BAA0B,CAgD5B"}