tiny-essentials 1.28.18 → 1.29.0

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',
+        };
+    }
+}

package/dist/v1/webTemplates/multiformats/14.0/IPFSHasher/index.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+var cid = require('../../../../../node_modules/multiformats/dist/src/cid.cjs');
+var sha2 = require('../../../../../node_modules/multiformats/dist/src/hashes/sha2.cjs');
+
+/**
+ * Multicodec code for the dag-pb format.
+ * @type {number}
+ */
+const CODEC_DAG_PB = 0x70;
+
+/**
+ * Multicodec code for raw binary data.
+ * @type {number}
+ */
+const CODEC_RAW = 0x55;
+
+/**
+ * @typedef {Object} CIDGenerationResult
+ * @property {string} cidString - The string representation of the CID.
+ * @property {'v0' | 'v1'} version - The CID version that was generated.
+ * @property {'sha256'} hashAlgorithm - The algorithm used for hashing.
+ * @property {number} codec - The multicodec code of the content.
+ */
+
+/**
+ * A utility class to generate IPFS Content Identifiers (CIDs) locally.
+ */
+class IPFSHasher {
+  /** @type {'v0' | 'v1'} */
+  #version;
+
+  /**
+   * @param {'v0' | 'v1'} [version='v1'] - The CID version to generate.
+   * @throws {TypeError} If the version is not 'v0' or 'v1'.
+   */
+  constructor(version = 'v1') {
+    if (version !== 'v0' && version !== 'v1') {
+      throw new TypeError('Invalid CID version. Use "v0" or "v1".');
+    }
+    this.#version = version;
+  }
+
+  /**
+   * Generates a CID from the provided data.
+   *
+   * @param {Uint8Array} data - The raw data to be hashed.
+   * @returns {Promise<CIDGenerationResult>} A promise resolving to the CID result.
+   * @throws {TypeError} If the input data is not a Uint8Array.
+   */
+  async generate(data) {
+    if (!(data instanceof Uint8Array)) {
+      throw new TypeError(`Expected Uint8Array, but received ${typeof data}.`);
+    }
+
+    // sha256.digest is asynchronous and must be awaited.
+    const hash = await sha2.sha256.digest(data);
+
+    /** @type {CID} */
+    let cid$1;
+    /** @type {number} */
+    let codec;
+
+    if (this.#version === 'v0') {
+      // CIDv0 is locked to dag-pb + sha256. The codec is implicit.
+      codec = CODEC_DAG_PB;
+      cid$1 = cid.CID.createV0(hash);
+    } else {
+      // CIDv1 is explicit: we choose the raw codec for file bytes.
+      codec = CODEC_RAW;
+      cid$1 = cid.CID.create(1, codec, hash);
+    }
+
+    return {
+      cidString: cid$1.toString(),
+      version: this.#version,
+      hashAlgorithm: 'sha256',
+      codec,
+    };
+  }
+}
+
+module.exports = IPFSHasher;

package/dist/v1/webTemplates/multiformats/14.0/IPFSHasher/index.d.mts

@@ -0,0 +1,46 @@
+export type CIDGenerationResult = {
+    /**
+     * - The string representation of the CID.
+     */
+    cidString: string;
+    /**
+     * - The CID version that was generated.
+     */
+    version: 'v0' | 'v1';
+    /**
+     * - The algorithm used for hashing.
+     */
+    hashAlgorithm: 'sha256';
+    /**
+     * - The multicodec code of the content.
+     */
+    codec: number;
+};
+/**
+ * @typedef {Object} CIDGenerationResult
+ * @property {string} cidString - The string representation of the CID.
+ * @property {'v0' | 'v1'} version - The CID version that was generated.
+ * @property {'sha256'} hashAlgorithm - The algorithm used for hashing.
+ * @property {number} codec - The multicodec code of the content.
+ */
+/**
+ * A utility class to generate IPFS Content Identifiers (CIDs) locally.
+ */
+declare class IPFSHasher {
+    #private;
+    /**
+     * @param {'v0' | 'v1'} [version='v1'] - The CID version to generate.
+     * @throws {TypeError} If the version is not 'v0' or 'v1'.
+     */
+    constructor(version?: 'v0' | 'v1');
+    /**
+     * Generates a CID from the provided data.
+     *
+     * @param {Uint8Array} data - The raw data to be hashed.
+     * @returns {Promise<CIDGenerationResult>} A promise resolving to the CID result.
+     * @throws {TypeError} If the input data is not a Uint8Array.
+     */
+    generate(data: Uint8Array): Promise<CIDGenerationResult>;
+}
+export default IPFSHasher;
+//# sourceMappingURL=index.d.mts.map

package/dist/v1/webTemplates/multiformats/14.0/IPFSHasher/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../../../../src/v1/webTemplates/multiformats/14.0/IPFSHasher/index.mjs"],"names":[],"mappings":"AAgBG,YAAkB,mBAAmB,GACrC;;;;IAAmB,SAAS,EAAjB,MAAM,CACjB;;;;IAAwB,OAAO,EAApB,IAAI,GAAG,IAAI,CACtB;;;;IAAqB,aAAa,EAAvB,QAAQ,CACnB;;;;IAAmB,KAAK,EAAb,MAAM,CACnB;CAAA,CAAA;AAND;;;;;;GAMG;AAEH;;GAEG;AACH,cAAM,UAAU;;IAId;;;OAGG;IACH,YAAY,OAAO,AAHhB,CACA,EADQ,IAAI,GAAG,IAGQ,EAKzB;IAED;;;;;;OAMG;IACG,QAAQ,CAAC,IAAI,EAJR,UAIQ,GAHN,OAAO,CAAC,mBAAmB,CAAC,CAgCxC;CACF;eAEc,UAAU"}

package/dist/v1/webTemplates/multiformats/14.0/IPFSHasher/index.mjs

@@ -0,0 +1,71 @@
+import { CID } from 'multiformats/cid';
+import { sha256 } from 'multiformats/hashes/sha2';
+/**
+ * Multicodec code for the dag-pb format.
+ * @type {number}
+ */
+const CODEC_DAG_PB = 0x70;
+/**
+ * Multicodec code for raw binary data.
+ * @type {number}
+ */
+const CODEC_RAW = 0x55;
+/**
+ * @typedef {Object} CIDGenerationResult
+ * @property {string} cidString - The string representation of the CID.
+ * @property {'v0' | 'v1'} version - The CID version that was generated.
+ * @property {'sha256'} hashAlgorithm - The algorithm used for hashing.
+ * @property {number} codec - The multicodec code of the content.
+ */
+/**
+ * A utility class to generate IPFS Content Identifiers (CIDs) locally.
+ */
+class IPFSHasher {
+    /** @type {'v0' | 'v1'} */
+    #version;
+    /**
+     * @param {'v0' | 'v1'} [version='v1'] - The CID version to generate.
+     * @throws {TypeError} If the version is not 'v0' or 'v1'.
+     */
+    constructor(version = 'v1') {
+        if (version !== 'v0' && version !== 'v1') {
+            throw new TypeError('Invalid CID version. Use "v0" or "v1".');
+        }
+        this.#version = version;
+    }
+    /**
+     * Generates a CID from the provided data.
+     *
+     * @param {Uint8Array} data - The raw data to be hashed.
+     * @returns {Promise<CIDGenerationResult>} A promise resolving to the CID result.
+     * @throws {TypeError} If the input data is not a Uint8Array.
+     */
+    async generate(data) {
+        if (!(data instanceof Uint8Array)) {
+            throw new TypeError(`Expected Uint8Array, but received ${typeof data}.`);
+        }
+        // sha256.digest is asynchronous and must be awaited.
+        const hash = await sha256.digest(data);
+        /** @type {CID} */
+        let cid;
+        /** @type {number} */
+        let codec;
+        if (this.#version === 'v0') {
+            // CIDv0 is locked to dag-pb + sha256. The codec is implicit.
+            codec = CODEC_DAG_PB;
+            cid = CID.createV0(hash);
+        }
+        else {
+            // CIDv1 is explicit: we choose the raw codec for file bytes.
+            codec = CODEC_RAW;
+            cid = CID.create(1, codec, hash);
+        }
+        return {
+            cidString: cid.toString(),
+            version: this.#version,
+            hashAlgorithm: 'sha256',
+            codec,
+        };
+    }
+}
+export default IPFSHasher;