tiny-essentials 1.28.19 → 1.29.1

package/dist/v1/webTemplates/media/MediaValidator/v1/Browser/index.cjs

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * @template T
+ * @typedef {Object} ValidationResult
+ * @property {string|null} error - The error message if validation failed.
+ * @property {T} [data]
+ */
+
+/**
+ * LAYER 1: Fast Binary Validation (Magic Numbers)
+ * Validates if the file header matches expected media categories.
+ *
+ * @param {Object} options
+ * @param {Buffer|Uint8Array|Blob} options.inputData - The raw file data.
+ * @param {'image' | 'audio' | 'video'} options.expectedType - The expected media category.
+ * @param {(buffer: Uint8Array | ArrayBuffer) => Promise<{ mime: string; } | undefined>} options.fileTypeFromBuffer
+ * @returns {Promise<string>} Resolves with the confirmed MIME type if valid.
+ * @throws {Error} If the file signature does not match the expected type.
+ */
+async function validateMagicNumbers({ inputData, expectedType, fileTypeFromBuffer }) {
+  const arrayBuffer = inputData instanceof Blob ? await inputData.arrayBuffer() : inputData;
+  const bufferData = new Uint8Array(arrayBuffer);
+  const detected = await fileTypeFromBuffer(bufferData);
+
+  if (!detected) {
+    throw new Error('File signature could not be identified (Unknown Magic Numbers).');
+  }
+
+  const mime = detected.mime;
+  const isTypeValid = {
+    image: mime.startsWith('image/'),
+    audio: mime.startsWith('audio/'),
+    video: mime.startsWith('video/') || mime === 'application/x-mpegurl', // Handles some streaming formats
+  };
+
+  if (!isTypeValid[expectedType]) {
+    throw new Error(`Security Alert: File disguised as ${expectedType}. Actual MIME type: ${mime}`);
+  }
+
+  return mime;
+}
+
+/**
+ * @typedef {import('sharp').SharpConstructor} SharpConstructor
+ * @typedef {import('sharp').Sharp} Sharp
+ * @typedef {import('sharp').Metadata} SharpMetadata
+ */
+
+/**
+ * LAYER 2 (IMAGE): Structural and metadata validation for images.
+ * Forces the decoding engine to parse the image structure to detect hidden exploits.
+ *
+ * @param {Object} options
+ * @param {Buffer|Blob} options.inputData - The raw image data.
+ * @returns {Promise<ValidationResult<{ width: number; height: number }>>} The validation outcome.
+ */
+async function validateImage({ inputData }) {
+  try {
+    if (!(inputData instanceof Blob)) throw new TypeError('InputData must be a Blob or File.');
+    const bitmap = await createImageBitmap(inputData);
+    return {
+      error: null,
+      data: { width: bitmap.width, height: bitmap.height },
+    };
+  } catch (err) {
+    console.error(err);
+    return {
+      error: err instanceof Error ? err.message : 'Unknown Error',
+    };
+  }
+}
+
+/**
+ * @typedef {import('music-metadata').IAudioMetadata} IAudioMetadata
+ */
+
+/**
+ * @typedef {Object} ValidationResultExtra
+ * @property {string|null} mimeType - The detected MIME type of the file.
+ */
+
+/**
+ * LAYER 2 (AUDIO/VIDEO): Deep validation for audio/video files.
+ * Validates headers, durations, and container integrity.
+ *
+ * @param {Object} options
+ * @param {Buffer|Blob} options.inputData - The raw media data.
+ * @param {string} options.mimeType - Result from {@link validateMagicNumbers}
+ * @returns {Promise<ValidationResult<{ duration: number }> & ValidationResultExtra>} The validation outcome.
+ */
+async function validateAudioVideo({ inputData, mimeType }) {
+  try {
+    if (!(inputData instanceof Blob)) throw new TypeError('InputData must be a Blob or File.');
+    return new Promise((resolve) => {
+      const isAudio = mimeType.startsWith('audio/');
+      const mediaElement = document.createElement(isAudio ? 'audio' : 'video');
+      const url = URL.createObjectURL(inputData);
+
+      mediaElement.preload = 'metadata';
+
+      mediaElement.onloadedmetadata = () => {
+        URL.revokeObjectURL(url);
+        if (isNaN(mediaElement.duration) || mediaElement.duration === 0) {
+          resolve({
+            mimeType: null,
+            error: 'Media structure corrupted: Missing duration in browser.',
+          });
+        } else {
+          resolve({ mimeType, error: null, data: { duration: mediaElement.duration } });
+        }
+      };
+
+      mediaElement.onerror = () => {
+        URL.revokeObjectURL(url);
+        resolve({
+          mimeType: null,
+          error: 'Native browser decoder failed to parse media container.',
+        });
+      };
+
+      mediaElement.src = url;
+    });
+  } catch (err) {
+    console.error(err);
+    return {
+      mimeType: null,
+      error: err instanceof Error ? err.message : 'Unknown Error',
+    };
+  }
+}
+
+exports.validateAudioVideo = validateAudioVideo;
+exports.validateImage = validateImage;
+exports.validateMagicNumbers = validateMagicNumbers;

package/dist/v1/webTemplates/media/MediaValidator/v1/Browser/index.d.mts

@@ -0,0 +1,83 @@
+/**
+ * @template T
+ * @typedef {Object} ValidationResult
+ * @property {string|null} error - The error message if validation failed.
+ * @property {T} [data]
+ */
+export type ValidationResult<T> = {
+    /**
+     * - The error message if validation failed.
+     */
+    error: string | null;
+    data?: T;
+};
+/**
+ * LAYER 1: Fast Binary Validation (Magic Numbers)
+ * Validates if the file header matches expected media categories.
+ *
+ * @param {Object} options
+ * @param {Buffer|Uint8Array|Blob} options.inputData - The raw file data.
+ * @param {'image' | 'audio' | 'video'} options.expectedType - The expected media category.
+ * @param {(buffer: Uint8Array | ArrayBuffer) => Promise<{ mime: string; } | undefined>} options.fileTypeFromBuffer
+ * @returns {Promise<string>} Resolves with the confirmed MIME type if valid.
+ * @throws {Error} If the file signature does not match the expected type.
+ */
+export declare function validateMagicNumbers({ inputData, expectedType, fileTypeFromBuffer }: {
+    inputData: Buffer | Uint8Array | Blob;
+    expectedType: 'image' | 'audio' | 'video';
+    fileTypeFromBuffer: (buffer: Uint8Array | ArrayBuffer) => Promise<{
+        mime: string;
+    } | undefined>;
+}): Promise<string>;
+export type SharpConstructor = import('sharp').SharpConstructor;
+export type Sharp = import('sharp').Sharp;
+export type SharpMetadata = import('sharp').Metadata;
+/**
+ * @typedef {import('sharp').SharpConstructor} SharpConstructor
+ * @typedef {import('sharp').Sharp} Sharp
+ * @typedef {import('sharp').Metadata} SharpMetadata
+ */
+/**
+ * LAYER 2 (IMAGE): Structural and metadata validation for images.
+ * Forces the decoding engine to parse the image structure to detect hidden exploits.
+ *
+ * @param {Object} options
+ * @param {Buffer|Blob} options.inputData - The raw image data.
+ * @returns {Promise<ValidationResult<{ width: number; height: number }>>} The validation outcome.
+ */
+export declare function validateImage({ inputData }: {
+    inputData: Buffer | Blob;
+}): Promise<ValidationResult<{
+    width: number;
+    height: number;
+}>>;
+export type IAudioMetadata = import('music-metadata').IAudioMetadata;
+export type ValidationResultExtra = {
+    /**
+     * - The detected MIME type of the file.
+     */
+    mimeType: string | null;
+};
+/**
+ * @typedef {import('music-metadata').IAudioMetadata} IAudioMetadata
+ */
+/**
+ * @typedef {Object} ValidationResultExtra
+ * @property {string|null} mimeType - The detected MIME type of the file.
+ */
+/**
+ * LAYER 2 (AUDIO/VIDEO): Deep validation for audio/video files.
+ * Validates headers, durations, and container integrity.
+ *
+ * @param {Object} options
+ * @param {Buffer|Blob} options.inputData - The raw media data.
+ * @param {string} options.mimeType - Result from {@link validateMagicNumbers}
+ * @returns {Promise<ValidationResult<{ duration: number }> & ValidationResultExtra>} The validation outcome.
+ */
+export declare function validateAudioVideo({ inputData, mimeType }: {
+    inputData: Buffer | Blob;
+    mimeType: string;
+}): Promise<ValidationResult<{
+    duration: number;
+}> & ValidationResultExtra>;
+//# sourceMappingURL=index.d.mts.map

package/dist/v1/webTemplates/media/MediaValidator/v1/Browser/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../../../../../src/v1/webTemplates/media/MediaValidator/v1/Browser/index.mjs"],"names":[],"mappings":"AAAA;;;;;GAKG;AAHA,YAAkB,gBAAgB,CADxB,CAAC,IAEX;;;;IAAwB,KAAK,EAAlB,MAAM,GAAC,IAAI,CACtB;IAAe,IAAI,AAAnB,CAAoB,EAAT,CAAC,CAAQ;CAAA,CAAA;AAGvB;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CAAC,EAAE,SAAS,EAAE,YAAY,EAAE,kBAAkB,EAAE,EANvF;IAAwC,SAAS,EAAzC,MAAM,GAAC,UAAU,GAAC,IAAI,CAC9B;IAA6C,YAAY,EAAjD,OAAO,GAAG,OAAO,GAAG,OAAO,CACnC;IAA8F,kBAAkB,EAAxG,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;KAAE,GAAG,SAAS,CAAC,CACpF;CAGuF,GAH7E,OAAO,CAAC,MAAM,CAAC,CAwB3B;AAGE,YAA4C,gBAAgB,GAAlD,OAAO,OAAO,EAAE,gBAAgB,CAAkB;AAC5D,YAAiC,KAAK,GAA5B,OAAO,OAAO,EAAE,KAAK,CAAO;AACtC,YAAoC,aAAa,GAAvC,OAAO,OAAO,EAAE,QAAQ,CAAe;AAHpD;;;;GAIG;AAEH;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,EAAE,SAAS,EAAE,EAH9C;IAA6B,SAAS,EAA9B,MAAM,GAAC,IAAI,CACnB;CAE8C,GAFpC,OAAO,CAAC,gBAAgB,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAgBxE;AAGE,YAAmD,cAAc,GAAvD,OAAO,gBAAgB,EAAE,cAAc,CAAgB;AAIjE,YAAkB,qBAAqB,GACvC;;;;IAAwB,QAAQ,EAArB,MAAM,GAAC,IAAI,CACxB;CAAA,CAAA;AAPD;;GAEG;AAEH;;;GAGG;AAEH;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,EAJ7D;IAA6B,SAAS,EAA9B,MAAM,GAAC,IAAI,CACnB;IAAwB,QAAQ,EAAxB,MAAM,CACd;CAE6D,GAFnD,OAAO,CAAC,gBAAgB,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,qBAAqB,CAAC,CAyCnF"}

package/dist/v1/webTemplates/media/MediaValidator/v1/Browser/index.mjs

@@ -0,0 +1,120 @@
+/**
+ * @template T
+ * @typedef {Object} ValidationResult
+ * @property {string|null} error - The error message if validation failed.
+ * @property {T} [data]
+ */
+/**
+ * LAYER 1: Fast Binary Validation (Magic Numbers)
+ * Validates if the file header matches expected media categories.
+ *
+ * @param {Object} options
+ * @param {Buffer|Uint8Array|Blob} options.inputData - The raw file data.
+ * @param {'image' | 'audio' | 'video'} options.expectedType - The expected media category.
+ * @param {(buffer: Uint8Array | ArrayBuffer) => Promise<{ mime: string; } | undefined>} options.fileTypeFromBuffer
+ * @returns {Promise<string>} Resolves with the confirmed MIME type if valid.
+ * @throws {Error} If the file signature does not match the expected type.
+ */
+export async function validateMagicNumbers({ inputData, expectedType, fileTypeFromBuffer }) {
+    const arrayBuffer = inputData instanceof Blob ? await inputData.arrayBuffer() : inputData;
+    const bufferData = new Uint8Array(arrayBuffer);
+    const detected = await fileTypeFromBuffer(bufferData);
+    if (!detected) {
+        throw new Error('File signature could not be identified (Unknown Magic Numbers).');
+    }
+    const mime = detected.mime;
+    const isTypeValid = {
+        image: mime.startsWith('image/'),
+        audio: mime.startsWith('audio/'),
+        video: mime.startsWith('video/') || mime === 'application/x-mpegurl', // Handles some streaming formats
+    };
+    if (!isTypeValid[expectedType]) {
+        throw new Error(`Security Alert: File disguised as ${expectedType}. Actual MIME type: ${mime}`);
+    }
+    return mime;
+}
+/**
+ * @typedef {import('sharp').SharpConstructor} SharpConstructor
+ * @typedef {import('sharp').Sharp} Sharp
+ * @typedef {import('sharp').Metadata} SharpMetadata
+ */
+/**
+ * LAYER 2 (IMAGE): Structural and metadata validation for images.
+ * Forces the decoding engine to parse the image structure to detect hidden exploits.
+ *
+ * @param {Object} options
+ * @param {Buffer|Blob} options.inputData - The raw image data.
+ * @returns {Promise<ValidationResult<{ width: number; height: number }>>} The validation outcome.
+ */
+export async function validateImage({ inputData }) {
+    try {
+        if (!(inputData instanceof Blob))
+            throw new TypeError('InputData must be a Blob or File.');
+        const bitmap = await createImageBitmap(inputData);
+        return {
+            error: null,
+            data: { width: bitmap.width, height: bitmap.height },
+        };
+    }
+    catch (err) {
+        console.error(err);
+        return {
+            error: err instanceof Error ? err.message : 'Unknown Error',
+        };
+    }
+}
+/**
+ * @typedef {import('music-metadata').IAudioMetadata} IAudioMetadata
+ */
+/**
+ * @typedef {Object} ValidationResultExtra
+ * @property {string|null} mimeType - The detected MIME type of the file.
+ */
+/**
+ * LAYER 2 (AUDIO/VIDEO): Deep validation for audio/video files.
+ * Validates headers, durations, and container integrity.
+ *
+ * @param {Object} options
+ * @param {Buffer|Blob} options.inputData - The raw media data.
+ * @param {string} options.mimeType - Result from {@link validateMagicNumbers}
+ * @returns {Promise<ValidationResult<{ duration: number }> & ValidationResultExtra>} The validation outcome.
+ */
+export async function validateAudioVideo({ inputData, mimeType }) {
+    try {
+        if (!(inputData instanceof Blob))
+            throw new TypeError('InputData must be a Blob or File.');
+        return new Promise((resolve) => {
+            const isAudio = mimeType.startsWith('audio/');
+            const mediaElement = document.createElement(isAudio ? 'audio' : 'video');
+            const url = URL.createObjectURL(inputData);
+            mediaElement.preload = 'metadata';
+            mediaElement.onloadedmetadata = () => {
+                URL.revokeObjectURL(url);
+                if (isNaN(mediaElement.duration) || mediaElement.duration === 0) {
+                    resolve({
+                        mimeType: null,
+                        error: 'Media structure corrupted: Missing duration in browser.',
+                    });
+                }
+                else {
+                    resolve({ mimeType, error: null, data: { duration: mediaElement.duration } });
+                }
+            };
+            mediaElement.onerror = () => {
+                URL.revokeObjectURL(url);
+                resolve({
+                    mimeType: null,
+                    error: 'Native browser decoder failed to parse media container.',
+                });
+            };
+            mediaElement.src = url;
+        });
+    }
+    catch (err) {
+        console.error(err);
+        return {
+            mimeType: null,
+            error: err instanceof Error ? err.message : 'Unknown Error',
+        };
+    }
+}

package/dist/v1/webTemplates/media/MediaValidator/v1/Node/index.cjs

@@ -0,0 +1,127 @@
+'use strict';
+
+/**
+ * @template T
+ * @typedef {Object} ValidationResult
+ * @property {string|null} error - The error message if validation failed.
+ * @property {T} [data]
+ */
+
+/**
+ * @typedef {import('stream').Readable} Readable
+ * @typedef {typeof import('stream').Readable} ConstructorReadable
+ */
+
+/**
+ * @typedef {import('file-type').FileTypeResult} FileTypeResult
+ */
+
+/**
+ * LAYER 1: Fast Binary Validation (Magic Numbers)
+ * Validates if the file header matches expected media categories.
+ *
+ * `file-type@22.0.2` npm package.
+ *
+ * @param {Object} options
+ * @param {Buffer} options.buffer - The raw file buffer from the upload.
+ * @param {'image' | 'audio' | 'video'} options.expectedType - The expected media category.
+ * @param {(buffer: Uint8Array | ArrayBuffer) => Promise<FileTypeResult | undefined>} options.fileTypeFromBuffer
+ * @returns {Promise<string>} Resolves with the confirmed MIME type if valid.
+ * @throws {Error} If the file signature does not match the expected type.
+ */
+async function validateMagicNumbers({ buffer, expectedType, fileTypeFromBuffer }) {
+  const detected = await fileTypeFromBuffer(buffer);
+
+  if (!detected) {
+    throw new Error('File signature could not be identified (Unknown Magic Numbers).');
+  }
+
+  const mime = detected.mime;
+  const isTypeValid = {
+    image: mime.startsWith('image/'),
+    audio: mime.startsWith('audio/'),
+    video: mime.startsWith('video/') || mime === 'application/x-mpegurl', // Handles some streaming formats
+  };
+
+  if (!isTypeValid[expectedType]) {
+    throw new Error(`Security Alert: File disguised as ${expectedType}. Actual MIME type: ${mime}`);
+  }
+
+  return mime;
+}
+
+/**
+ * @typedef {import('sharp').SharpConstructor} SharpConstructor
+ * @typedef {import('sharp').Sharp} Sharp
+ * @typedef {import('sharp').Metadata} SharpMetadata
+ */
+
+/**
+ * LAYER 2 (IMAGE): Structural and metadata validation for images.
+ * Forces the decoding engine to parse the image structure to detect hidden exploits.
+ *
+ * `sharp@0.35.4` npm package.
+ *
+ * @param {Object} options
+ * @param {Buffer} options.buffer - The raw image buffer.
+ * @param {SharpConstructor} options.Sharp
+ * @returns {Promise<ValidationResult<{ data: Sharp; metadata: SharpMetadata }>>} The validation outcome.
+ */
+async function validateImage({ buffer, Sharp }) {
+  try {
+    // Deep structural parsing (Checks for corrupted structures or embedded malicious scripts)
+    // sharp().metadata() forces the libvips C++ library to completely parse the image header/payload.
+    const data = Sharp(buffer);
+    const metadata = await data.metadata();
+
+    return { error: null, data: { data, metadata } };
+  } catch (err) {
+    console.error(err);
+    return {
+      error: err instanceof Error ? err.message : 'Unknown Error',
+    };
+  }
+}
+
+/**
+ * @typedef {import('music-metadata').IAudioMetadata} IAudioMetadata
+ * @typedef {import('music-metadata').IFileInfo} IFileInfo
+ * @typedef {import('music-metadata').IOptions} IOptions
+ */
+
+/**
+ * LAYER 2 (AUDIO/VIDEO): Deep validation for audio files using native JS metadata parsing.
+ * Validates audio headers, durations, and container integrity without external tools.
+ *
+ * `music-metadata@11.15.0` npm package.
+ *
+ * @param {Object} options
+ * @param {Buffer} options.buffer - The raw media buffer.
+ * @param {(stream: Readable, fileInfo?: IFileInfo | string, options?: IOptions) => Promise<IAudioMetadata>} [options.parseStream]
+ * @param {(uint8Array: Uint8Array<ArrayBufferLike>, fileInfo?: IFileInfo | string, options?: IOptions) => Promise<IAudioMetadata>} [options.parseBuffer]
+ * @param {ConstructorReadable} [options.Readable]
+ * @returns {Promise<ValidationResult<IAudioMetadata>>} The validation outcome.
+ */
+async function validateAudioVideo({ buffer, parseBuffer }) {
+  try {
+    // Deep metadata structural parsing
+    // music-metadata parses the container (ID3 tags, RIFF headers, FLAC blocks).
+    // If the file is a disguised script, the parser will fail to find valid audio frames.
+    const metadata = await (parseBuffer ? parseBuffer(buffer) : null);
+
+    if (!metadata || !metadata.format || typeof metadata.format.duration !== 'number') {
+      throw new Error('Audio file structure is corrupted or missing explicit audio streams.');
+    }
+
+    return { error: null, data: metadata };
+  } catch (err) {
+    console.error(err);
+    return {
+      error: err instanceof Error ? err.message : 'Unknown Error',
+    };
+  }
+}
+
+exports.validateAudioVideo = validateAudioVideo;
+exports.validateImage = validateImage;
+exports.validateMagicNumbers = validateMagicNumbers;

package/dist/v1/webTemplates/media/MediaValidator/v1/Node/index.d.mts

@@ -0,0 +1,95 @@
+/**
+ * @template T
+ * @typedef {Object} ValidationResult
+ * @property {string|null} error - The error message if validation failed.
+ * @property {T} [data]
+ */
+export type ValidationResult<T> = {
+    /**
+     * - The error message if validation failed.
+     */
+    error: string | null;
+    data?: T;
+};
+export type Readable = import('stream').Readable;
+export type ConstructorReadable = typeof import('stream').Readable;
+export type FileTypeResult = import('file-type').FileTypeResult;
+/**
+ * @typedef {import('stream').Readable} Readable
+ * @typedef {typeof import('stream').Readable} ConstructorReadable
+ */
+/**
+ * @typedef {import('file-type').FileTypeResult} FileTypeResult
+ */
+/**
+ * LAYER 1: Fast Binary Validation (Magic Numbers)
+ * Validates if the file header matches expected media categories.
+ *
+ * `file-type@22.0.2` npm package.
+ *
+ * @param {Object} options
+ * @param {Buffer} options.buffer - The raw file buffer from the upload.
+ * @param {'image' | 'audio' | 'video'} options.expectedType - The expected media category.
+ * @param {(buffer: Uint8Array | ArrayBuffer) => Promise<FileTypeResult | undefined>} options.fileTypeFromBuffer
+ * @returns {Promise<string>} Resolves with the confirmed MIME type if valid.
+ * @throws {Error} If the file signature does not match the expected type.
+ */
+export declare function validateMagicNumbers({ buffer, expectedType, fileTypeFromBuffer }: {
+    buffer: Buffer;
+    expectedType: 'image' | 'audio' | 'video';
+    fileTypeFromBuffer: (buffer: Uint8Array | ArrayBuffer) => Promise<FileTypeResult | undefined>;
+}): Promise<string>;
+export type SharpConstructor = import('sharp').SharpConstructor;
+export type Sharp = import('sharp').Sharp;
+export type SharpMetadata = import('sharp').Metadata;
+/**
+ * @typedef {import('sharp').SharpConstructor} SharpConstructor
+ * @typedef {import('sharp').Sharp} Sharp
+ * @typedef {import('sharp').Metadata} SharpMetadata
+ */
+/**
+ * LAYER 2 (IMAGE): Structural and metadata validation for images.
+ * Forces the decoding engine to parse the image structure to detect hidden exploits.
+ *
+ * `sharp@0.35.4` npm package.
+ *
+ * @param {Object} options
+ * @param {Buffer} options.buffer - The raw image buffer.
+ * @param {SharpConstructor} options.Sharp
+ * @returns {Promise<ValidationResult<{ data: Sharp; metadata: SharpMetadata }>>} The validation outcome.
+ */
+export declare function validateImage({ buffer, Sharp }: {
+    buffer: Buffer;
+    Sharp: SharpConstructor;
+}): Promise<ValidationResult<{
+    data: Sharp;
+    metadata: SharpMetadata;
+}>>;
+export type IAudioMetadata = import('music-metadata').IAudioMetadata;
+export type IFileInfo = import('music-metadata').IFileInfo;
+export type IOptions = import('music-metadata').IOptions;
+/**
+ * @typedef {import('music-metadata').IAudioMetadata} IAudioMetadata
+ * @typedef {import('music-metadata').IFileInfo} IFileInfo
+ * @typedef {import('music-metadata').IOptions} IOptions
+ */
+/**
+ * LAYER 2 (AUDIO/VIDEO): Deep validation for audio files using native JS metadata parsing.
+ * Validates audio headers, durations, and container integrity without external tools.
+ *
+ * `music-metadata@11.15.0` npm package.
+ *
+ * @param {Object} options
+ * @param {Buffer} options.buffer - The raw media buffer.
+ * @param {(stream: Readable, fileInfo?: IFileInfo | string, options?: IOptions) => Promise<IAudioMetadata>} [options.parseStream]
+ * @param {(uint8Array: Uint8Array<ArrayBufferLike>, fileInfo?: IFileInfo | string, options?: IOptions) => Promise<IAudioMetadata>} [options.parseBuffer]
+ * @param {ConstructorReadable} [options.Readable]
+ * @returns {Promise<ValidationResult<IAudioMetadata>>} The validation outcome.
+ */
+export declare function validateAudioVideo({ buffer, parseBuffer }: {
+    buffer: Buffer;
+    parseStream?: (stream: Readable, fileInfo?: IFileInfo | string, options?: IOptions) => Promise<IAudioMetadata>;
+    parseBuffer?: (uint8Array: Uint8Array<ArrayBufferLike>, fileInfo?: IFileInfo | string, options?: IOptions) => Promise<IAudioMetadata>;
+    Readable?: ConstructorReadable;
+}): Promise<ValidationResult<IAudioMetadata>>;
+//# sourceMappingURL=index.d.mts.map

package/dist/v1/webTemplates/media/MediaValidator/v1/Node/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../../../../../src/v1/webTemplates/media/MediaValidator/v1/Node/index.mjs"],"names":[],"mappings":"AAAA;;;;;GAKG;AAHA,YAAkB,gBAAgB,CADxB,CAAC,IAEX;;;;IAAwB,KAAK,EAAlB,MAAM,GAAC,IAAI,CACtB;IAAe,IAAI,AAAnB,CAAoB,EAAT,CAAC,CAAQ;CAAA,CAAA;AAIpB,YAAqC,QAAQ,GAAnC,OAAO,QAAQ,EAAE,QAAQ,CAAU;AAC7C,YAA4C,mBAAmB,GAArD,cAAc,QAAQ,EAAE,QAAQ,CAAqB;AAI/D,YAA8C,cAAc,GAAlD,OAAO,WAAW,EAAE,cAAc,CAAgB;AAN/D;;;GAGG;AAEH;;GAEG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,kBAAkB,EAAE,EANpF;IAAwB,MAAM,EAAtB,MAAM,CACd;IAA6C,YAAY,EAAjD,OAAO,GAAG,OAAO,GAAG,OAAO,CACnC;IAA2F,kBAAkB,EAArG,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CACjF;CAGoF,GAH1E,OAAO,CAAC,MAAM,CAAC,CAsB3B;AAGE,YAA4C,gBAAgB,GAAlD,OAAO,OAAO,EAAE,gBAAgB,CAAkB;AAC5D,YAAiC,KAAK,GAA5B,OAAO,OAAO,EAAE,KAAK,CAAO;AACtC,YAAoC,aAAa,GAAvC,OAAO,OAAO,EAAE,QAAQ,CAAe;AAHpD;;;;GAIG;AAEH;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAJlD;IAAwB,MAAM,EAAtB,MAAM,CACd;IAAkC,KAAK,EAA/B,gBAAgB,CACxB;CAEkD,GAFxC,OAAO,CAAC,gBAAgB,CAAC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAA;CAAE,CAAC,CAAC,CAgB/E;AAGE,YAAmD,cAAc,GAAvD,OAAO,gBAAgB,EAAE,cAAc,CAAgB;AACjE,YAA8C,SAAS,GAA7C,OAAO,gBAAgB,EAAE,SAAS,CAAW;AACvD,YAA6C,QAAQ,GAA3C,OAAO,gBAAgB,EAAE,QAAQ,CAAU;AAHxD;;;;GAIG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAN7D;IAAwB,MAAM,EAAtB,MAAM,CACd;IAAmH,WAAW,AAA9H,CACA,EADQ,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,cAAc,CAAC,CACxG;IAA0I,WAAW,AAArJ,CACA,EADQ,CAAC,UAAU,EAAE,UAAU,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,KAAK,OAAO,CAAC,cAAc,CAAC,CAC/H;IAAsC,QAAQ,AAA9C,CACA,EADQ,mBAAmB,CAC3B;CAE6D,GAFnD,OAAO,CAAC,gBAAgB,CAAC,cAAc,CAAC,CAAC,CAoBrD"}

package/dist/v1/webTemplates/media/MediaValidator/v1/Node/index.mjs

@@ -0,0 +1,109 @@
+/**
+ * @template T
+ * @typedef {Object} ValidationResult
+ * @property {string|null} error - The error message if validation failed.
+ * @property {T} [data]
+ */
+/**
+ * @typedef {import('stream').Readable} Readable
+ * @typedef {typeof import('stream').Readable} ConstructorReadable
+ */
+/**
+ * @typedef {import('file-type').FileTypeResult} FileTypeResult
+ */
+/**
+ * LAYER 1: Fast Binary Validation (Magic Numbers)
+ * Validates if the file header matches expected media categories.
+ *
+ * `file-type@22.0.2` npm package.
+ *
+ * @param {Object} options
+ * @param {Buffer} options.buffer - The raw file buffer from the upload.
+ * @param {'image' | 'audio' | 'video'} options.expectedType - The expected media category.
+ * @param {(buffer: Uint8Array | ArrayBuffer) => Promise<FileTypeResult | undefined>} options.fileTypeFromBuffer
+ * @returns {Promise<string>} Resolves with the confirmed MIME type if valid.
+ * @throws {Error} If the file signature does not match the expected type.
+ */
+export async function validateMagicNumbers({ buffer, expectedType, fileTypeFromBuffer }) {
+    const detected = await fileTypeFromBuffer(buffer);
+    if (!detected) {
+        throw new Error('File signature could not be identified (Unknown Magic Numbers).');
+    }
+    const mime = detected.mime;
+    const isTypeValid = {
+        image: mime.startsWith('image/'),
+        audio: mime.startsWith('audio/'),
+        video: mime.startsWith('video/') || mime === 'application/x-mpegurl', // Handles some streaming formats
+    };
+    if (!isTypeValid[expectedType]) {
+        throw new Error(`Security Alert: File disguised as ${expectedType}. Actual MIME type: ${mime}`);
+    }
+    return mime;
+}
+/**
+ * @typedef {import('sharp').SharpConstructor} SharpConstructor
+ * @typedef {import('sharp').Sharp} Sharp
+ * @typedef {import('sharp').Metadata} SharpMetadata
+ */
+/**
+ * LAYER 2 (IMAGE): Structural and metadata validation for images.
+ * Forces the decoding engine to parse the image structure to detect hidden exploits.
+ *
+ * `sharp@0.35.4` npm package.
+ *
+ * @param {Object} options
+ * @param {Buffer} options.buffer - The raw image buffer.
+ * @param {SharpConstructor} options.Sharp
+ * @returns {Promise<ValidationResult<{ data: Sharp; metadata: SharpMetadata }>>} The validation outcome.
+ */
+export async function validateImage({ buffer, Sharp }) {
+    try {
+        // Deep structural parsing (Checks for corrupted structures or embedded malicious scripts)
+        // sharp().metadata() forces the libvips C++ library to completely parse the image header/payload.
+        const data = Sharp(buffer);
+        const metadata = await data.metadata();
+        return { error: null, data: { data, metadata } };
+    }
+    catch (err) {
+        console.error(err);
+        return {
+            error: err instanceof Error ? err.message : 'Unknown Error',
+        };
+    }
+}
+/**
+ * @typedef {import('music-metadata').IAudioMetadata} IAudioMetadata
+ * @typedef {import('music-metadata').IFileInfo} IFileInfo
+ * @typedef {import('music-metadata').IOptions} IOptions
+ */
+/**
+ * LAYER 2 (AUDIO/VIDEO): Deep validation for audio files using native JS metadata parsing.
+ * Validates audio headers, durations, and container integrity without external tools.
+ *
+ * `music-metadata@11.15.0` npm package.
+ *
+ * @param {Object} options
+ * @param {Buffer} options.buffer - The raw media buffer.
+ * @param {(stream: Readable, fileInfo?: IFileInfo | string, options?: IOptions) => Promise<IAudioMetadata>} [options.parseStream]
+ * @param {(uint8Array: Uint8Array<ArrayBufferLike>, fileInfo?: IFileInfo | string, options?: IOptions) => Promise<IAudioMetadata>} [options.parseBuffer]
+ * @param {ConstructorReadable} [options.Readable]
+ * @returns {Promise<ValidationResult<IAudioMetadata>>} The validation outcome.
+ */
+export async function validateAudioVideo({ buffer, parseBuffer }) {
+    try {
+        // Deep metadata structural parsing
+        // music-metadata parses the container (ID3 tags, RIFF headers, FLAC blocks).
+        // If the file is a disguised script, the parser will fail to find valid audio frames.
+        const metadata = await (parseBuffer ? parseBuffer(buffer) : null);
+        if (!metadata || !metadata.format || typeof metadata.format.duration !== 'number') {
+            throw new Error('Audio file structure is corrupted or missing explicit audio streams.');
+        }
+        return { error: null, data: metadata };
+    }
+    catch (err) {
+        console.error(err);
+        return {
+            error: err instanceof Error ? err.message : 'Unknown Error',
+        };
+    }
+}