@h3l1os/mp4vault 2.0.0

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@h3l1os/mp4vault",
+  "version": "2.0.0",
+  "description": "Hide and extract files within MP4 video containers with AES-256-GCM encryption",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/*.map",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mp4",
+    "vault",
+    "secure",
+    "embed",
+    "extract",
+    "encryption",
+    "aes-256-gcm",
+    "video",
+    "container"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/h3l1os-sol/mp4vault.git"
+  },
+  "homepage": "https://github.com/h3l1os-sol/mp4vault",
+  "bugs": {
+    "url": "https://github.com/h3l1os-sol/mp4vault/issues"
+  },
+  "dependencies": {
+    "debug": "^4.3.1",
+    "tmp": "^0.2.1"
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.12",
+    "@types/node": "^25.4.0",
+    "@types/tmp": "^0.2.6",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "author": "h3l1os-sol",
+  "license": "AGPL-3.0"
+}

package/src/AES.ts

@@ -0,0 +1,134 @@
+import crypto from 'crypto';
+
+const IV_BYTE_LENGTH = 12;
+const SALT_BYTE_LENGTH = 16;
+const AUTH_TAG_BYTE_LENGTH = 16;
+const KEY_BYTE_LENGTH = 32; // AES-256
+const PBKDF2_ITERATIONS = 600000;
+const PBKDF2_DIGEST = 'sha512';
+
+export interface AESParams {
+	key?: Buffer | Uint8Array;
+	password?: string;
+	iv?: Buffer;
+	salt?: Buffer;
+	authTag?: Buffer;
+}
+
+export class AES {
+	static readonly ivByteLength = IV_BYTE_LENGTH;
+	static readonly saltByteLength = SALT_BYTE_LENGTH;
+	static readonly authTagByteLength = AUTH_TAG_BYTE_LENGTH;
+
+	private _key: Buffer;
+	private _iv: Buffer;
+	private _salt: Buffer | null;
+	private _authTag: Buffer | null;
+	private _cipher: crypto.CipherGCM | null = null;
+	private _decipher: crypto.DecipherGCM | null = null;
+
+	constructor(params: AESParams) {
+		this._iv = params.iv || crypto.randomBytes(IV_BYTE_LENGTH);
+		this._salt = params.salt || null;
+		this._authTag = params.authTag || null;
+
+		if (params.password) {
+			if (!this._salt) {
+				this._salt = crypto.randomBytes(SALT_BYTE_LENGTH);
+			}
+			this._key = AES.deriveKey(params.password, this._salt);
+		} else if (params.key) {
+			this._key = AES._normalizeKey(params.key);
+		} else {
+			throw new Error('Either key or password is required');
+		}
+	}
+
+	private static _normalizeKey(key: Buffer | Uint8Array): Buffer {
+		if (Buffer.isBuffer(key)) {
+			if (key.length !== 16 && key.length !== 24 && key.length !== 32) {
+				throw new Error('Key must be 16, 24, or 32 bytes. Got ' + key.length);
+			}
+			return key;
+		}
+		if (key instanceof Uint8Array) {
+			if (key.length !== 16 && key.length !== 24 && key.length !== 32) {
+				throw new Error('Key must be 16, 24, or 32 bytes. Got ' + key.length);
+			}
+			return Buffer.from(key);
+		}
+		throw new Error('Key must be a Buffer or Uint8Array');
+	}
+
+	private static _algorithmForKey(key: Buffer): string {
+		switch (key.length) {
+			case 16: return 'aes-128-gcm';
+			case 24: return 'aes-192-gcm';
+			case 32: return 'aes-256-gcm';
+			default: throw new Error('Key must be 16, 24, or 32 bytes. Got ' + key.length);
+		}
+	}
+
+	static deriveKey(password: string, salt: Buffer): Buffer {
+		return crypto.pbkdf2Sync(password, salt, PBKDF2_ITERATIONS, KEY_BYTE_LENGTH, PBKDF2_DIGEST);
+	}
+
+	encrypt(chunk: Buffer | null, finalize = false): Buffer {
+		if (!this._cipher) {
+			const algo = AES._algorithmForKey(this._key);
+			this._cipher = crypto.createCipheriv(algo, this._key, this._iv) as crypto.CipherGCM;
+		}
+
+		if (finalize) {
+			if (chunk && chunk.length > 0) {
+				const processed = this._cipher.update(chunk);
+				const final = this._cipher.final();
+				this._authTag = this._cipher.getAuthTag();
+				return Buffer.concat([processed, final]);
+			} else {
+				const final = this._cipher.final();
+				this._authTag = this._cipher.getAuthTag();
+				return final;
+			}
+		} else {
+			return this._cipher.update(chunk!);
+		}
+	}
+
+	decrypt(chunk: Buffer | null, finalize = false): Buffer {
+		if (!this._decipher) {
+			const algo = AES._algorithmForKey(this._key);
+			this._decipher = crypto.createDecipheriv(algo, this._key, this._iv) as crypto.DecipherGCM;
+			if (this._authTag) {
+				this._decipher.setAuthTag(this._authTag);
+			}
+		}
+
+		if (finalize) {
+			if (chunk && chunk.length > 0) {
+				const processed = this._decipher.update(chunk);
+				const final = this._decipher.final();
+				return Buffer.concat([processed, final]);
+			} else {
+				return this._decipher.final();
+			}
+		} else {
+			return this._decipher.update(chunk!);
+		}
+	}
+
+	getAuthTag(): Buffer {
+		if (!this._authTag) {
+			throw new Error('Auth tag not available. Call encrypt with finalize=true first');
+		}
+		return this._authTag;
+	}
+
+	getIV(): Buffer {
+		return this._iv;
+	}
+
+	getSalt(): Buffer | null {
+		return this._salt;
+	}
+}

package/src/Atom.ts

@@ -0,0 +1,148 @@
+import { Pack } from './Pack.js';
+import { BUFFER_SIZE, MAX_INT32 } from './constants.js';
+import type { IReadable, IWritable } from './types.js';
+
+export class Atom {
+	readable: IReadable | null;
+	name: string;
+	start: number;
+	size: number;
+	header_size: number;
+	mother: Atom | null;
+	children: Atom[];
+	contents: number[] | null;
+
+	constructor(params: {
+		readable?: IReadable;
+		name: string;
+		start: number;
+		size: number;
+		header_size: number;
+		mother?: Atom | null;
+	}) {
+		this.readable = params.readable || null;
+		this.name = params.name;
+		this.start = params.start;
+		this.size = params.size;
+		this.header_size = params.header_size;
+		this.mother = params.mother || null;
+		this.children = [];
+		this.contents = null;
+	}
+
+	findAtoms(atoms: Atom[] | null, name: string): Atom[] {
+		atoms = atoms || this.children;
+
+		let ret: Atom[] = [];
+		for (const a of atoms) {
+			if (a.name === name) {
+				ret.push(a);
+			}
+			if (a.children.length) {
+				ret = ret.concat(this.findAtoms(a.children, name));
+			}
+		}
+
+		return ret;
+	}
+
+	async unpackFromOffset(offset: number, length: number, fmt: string): Promise<number[]> {
+		try {
+			const data = await this.readable!.getSlice(this.start + offset, length);
+			return Pack.unpack(fmt, data);
+		} catch {
+			return [];
+		}
+	}
+
+	isVideo(): boolean {
+		const vmhdAtoms = this.findAtoms(null, 'vmhd');
+		return !!(vmhdAtoms && vmhdAtoms.length);
+	}
+
+	isAudio(): boolean {
+		const smhdAtoms = this.findAtoms(null, 'smhd');
+		return !!(smhdAtoms && smhdAtoms.length);
+	}
+
+	async getChunkOffsets(): Promise<number[]> {
+		let sampleOffsets: number[] = [];
+		if (this.name !== 'stco' && this.name !== 'co64') {
+			const sampleAtoms = this.findAtoms(null, 'stco').concat(this.findAtoms(null, 'co64'));
+			for (const atom of sampleAtoms) {
+				sampleOffsets = sampleOffsets.concat(await atom.getChunkOffsets());
+			}
+			return sampleOffsets;
+		}
+
+		const data = await this.readable!.getSlice(this.start + this.header_size, 8);
+		const unpacked = Pack.unpack('>II', data);
+		const count = unpacked[1];
+
+		if (this.name === 'stco') {
+			for (let i = 0; i < count; i += 1024) {
+				const cToRead = Math.min(1024, count - i);
+				const readOffsets = Pack.unpack(
+					'>' + 'I'.repeat(cToRead),
+					await this.readable!.getSlice(this.start + this.header_size + 8 + i * 4, cToRead * 4),
+				);
+				sampleOffsets.push(...readOffsets);
+			}
+		} else if (this.name === 'co64') {
+			for (let i = 0; i < count; i += 1024) {
+				const cToRead = Math.min(1024, count - i);
+				const readOffsets = Pack.unpack(
+					'>' + 'Q'.repeat(cToRead),
+					await this.readable!.getSlice(this.start + this.header_size + 8 + i * 8, cToRead * 8),
+				);
+				sampleOffsets.push(...readOffsets);
+			}
+		}
+
+		return sampleOffsets;
+	}
+
+	async writeHeader(writable: IWritable): Promise<void> {
+		if (this.size > MAX_INT32 && this.header_size === 8) {
+			throw new Error('Size too large for compact header');
+		}
+
+		if (this.size < MAX_INT32) {
+			await writable.write(Pack.pack('>I4s', [this.size, this.name]));
+		} else {
+			await writable.write(Pack.pack('>I4sQ', [1, this.name, this.size]));
+		}
+	}
+
+	async writePayload(writable: IWritable): Promise<void> {
+		if (this.children.length) {
+			for (const a of this.children) {
+				await a.write(writable);
+			}
+		} else {
+			const bodySize = this.size - this.header_size;
+			if (this.readable) {
+				for (let i = 0; i < bodySize; i += BUFFER_SIZE) {
+					const copySize = Math.min(BUFFER_SIZE, bodySize - i);
+					const chunk = await this.readable.getSlice(this.start + this.header_size + i, copySize);
+					await writable.write(chunk);
+				}
+			} else if (this.contents) {
+				if (this.contents.length === bodySize) {
+					await writable.write(this.contents);
+				} else {
+					throw new Error('Invalid bodySize for contents chunk');
+				}
+			} else {
+				if (bodySize > 0) {
+					await writable.write(new Uint8Array([0]));
+				}
+			}
+		}
+	}
+
+	async write(writable: IWritable): Promise<void> {
+		await this.writeHeader(writable);
+		await this.writePayload(writable);
+	}
+}

package/src/Convert.ts

@@ -0,0 +1,28 @@
+import crypto from 'crypto';
+
+export class Convert {
+	static randomByteIn(maxOptions: number, option: number): number {
+		const maxMultiple = Math.floor(256 / maxOptions);
+		const randomValue = crypto.randomInt(maxMultiple);
+		return randomValue * maxOptions + option;
+	}
+
+	static isByteIn(byte: number, maxOptions: number, option: number): boolean {
+		return (byte % maxOptions === option);
+	}
+
+	static objectToBuffer(object: unknown): Buffer {
+		return Buffer.from(JSON.stringify(object), 'utf-8');
+	}
+
+	static bufferToObject(buffer: Buffer | Uint8Array): unknown {
+		return JSON.parse(Buffer.from(buffer).toString('utf-8'));
+	}
+
+	static hexStringToBuffer(str: string): Buffer {
+		if (typeof str !== 'string' || !/^[0-9a-fA-F]*$/.test(str) || str.length % 2 !== 0) {
+			throw new Error('Invalid hex string');
+		}
+		return Buffer.from(str, 'hex');
+	}
+}

package/src/Embed.ts

@@ -0,0 +1,243 @@
+import { EmbedObject } from './EmbedObject.js';
+import { EmbedBinary } from './EmbedBinary.js';
+import type { IReadable, IWritable, FileRecord } from './types.js';
+
+interface FileEntity {
+	filename: string | null;
+	embedBinary: EmbedBinary;
+	isEncrypted: boolean;
+	meta?: Record<string, unknown>;
+}
+
+export class Embed {
+	private _files: FileEntity[] = [];
+	private _headerEmbed: EmbedObject | null = null;
+	_publicHeaderEmbed: EmbedObject | null = null;
+
+	hasEncryptedFiles = false;
+	hasPublicFiles = false;
+
+	private _key: Buffer | null;
+	private _password: string | null;
+
+	constructor(params: {
+		mp4?: unknown;
+		key?: Buffer | null;
+		password?: string | null;
+	} = {}) {
+		this._key = params.key || null;
+		this._password = params.password || null;
+	}
+
+	private basename(path: string): string {
+		return ('' + path).split(/[\\/]/).pop() || '';
+	}
+
+	async addFile(params: {
+		file?: { name?: string };
+		filename?: string | null;
+		meta?: Record<string, unknown>;
+		key?: Buffer | null;
+		password?: string | null;
+	}): Promise<void> {
+		const file = params.file || null;
+		let filename = params.filename || null;
+		const meta = params.meta || null;
+
+		// Per-file encryption opt-out: setting params.key or params.password to null
+		// explicitly disables encryption for this file, even if the Embed instance has a key/password.
+		// This enables mixing public and encrypted files in the same container.
+		let isEncrypted = false;
+		if ((this._key || this._password) && params.key !== null && params.password !== null) {
+			isEncrypted = true;
+		}
+
+		let embedBinary: EmbedBinary;
+		if (isEncrypted) {
+			embedBinary = new EmbedBinary({
+				filename: filename || undefined,
+				file: file || undefined,
+				key: this._key,
+				password: this._password,
+			});
+		} else {
+			embedBinary = new EmbedBinary({
+				filename: filename || undefined,
+				file: file || undefined,
+			});
+		}
+
+		if (!filename && file) {
+			filename = file.name || null;
+		}
+
+		const fileEntity: FileEntity = {
+			filename: filename,
+			embedBinary: embedBinary,
+			isEncrypted: isEncrypted,
+		};
+
+		if (meta) {
+			fileEntity.meta = meta;
+		}
+
+		this._files.push(fileEntity);
+	}
+
+	async composeHeader(): Promise<boolean> {
+		const headerObject: { files: FileRecord[] } = { files: [] };
+		const publicHeaderObject: { files: FileRecord[] } = { files: [] };
+
+		for (const fileEntity of this._files) {
+			const size = await fileEntity.embedBinary.getExpectedSize();
+			const fileRecord: FileRecord = {
+				filename: this.basename(fileEntity.filename || ''),
+				size: size,
+			};
+			if (fileEntity.meta) {
+				fileRecord.meta = fileEntity.meta;
+			}
+
+			if (fileEntity.isEncrypted) {
+				headerObject.files.push(fileRecord);
+				this.hasEncryptedFiles = true;
+			} else {
+				publicHeaderObject.files.push(fileRecord);
+				this.hasPublicFiles = true;
+			}
+		}
+
+		this._publicHeaderEmbed = new EmbedObject({ object: publicHeaderObject });
+		this._headerEmbed = new EmbedObject({
+			object: headerObject,
+			key: this._key,
+			password: this._password,
+		});
+
+		return true;
+	}
+
+	async getExpectedSize(): Promise<number> {
+		await this.composeHeader();
+		let size = 0;
+		if (this.hasEncryptedFiles) {
+			size += await this._headerEmbed!.getExpectedSize();
+		}
+		if (this.hasPublicFiles) {
+			size += await this._publicHeaderEmbed!.getExpectedSize();
+		}
+
+		const encFiles = (this._headerEmbed!.object as { files: FileRecord[] }).files;
+		for (const file of encFiles) {
+			size += file.size;
+		}
+		const pubFiles = (this._publicHeaderEmbed!.object as { files: FileRecord[] }).files;
+		for (const file of pubFiles) {
+			size += file.size;
+		}
+
+		return size;
+	}
+
+	async writeTo(writable: IWritable): Promise<void> {
+		await this.composeHeader();
+		if (this.hasPublicFiles) {
+			await this._publicHeaderEmbed!.writeTo(writable);
+		}
+		if (this.hasEncryptedFiles) {
+			await this._headerEmbed!.writeTo(writable);
+		}
+		for (const file of this._files) {
+			await file.embedBinary.writeTo(writable);
+		}
+	}
+
+	async restoreFromReadable(
+		readable: IReadable,
+		params: { key?: Buffer; password?: string | null } = {},
+		offset = 0,
+	): Promise<void> {
+		const publicParams: { password?: string | null; key?: Buffer } = {};
+		Object.assign(publicParams, params);
+		Object.assign(publicParams, { password: null, key: undefined });
+
+		let encryptedHeaderOffset = 0;
+		try {
+			this._publicHeaderEmbed = await EmbedObject.restoreFromReadable(
+				readable,
+				publicParams as Parameters<typeof EmbedObject.restoreFromReadable>[1],
+				offset,
+			);
+			encryptedHeaderOffset = this._publicHeaderEmbed.readBytes;
+		} catch {
+			this._publicHeaderEmbed = new EmbedObject({ object: { files: [] } });
+		}
+
+		const pubObj = this._publicHeaderEmbed._object as { files?: unknown[] } | null;
+		this.hasPublicFiles = !!(pubObj && pubObj.files && pubObj.files.length);
+
+		try {
+			this._headerEmbed = await EmbedObject.restoreFromReadable(
+				readable,
+				params as Parameters<typeof EmbedObject.restoreFromReadable>[1],
+				offset + encryptedHeaderOffset,
+			);
+		} catch {
+			this._headerEmbed = new EmbedObject({
+				object: { files: [] },
+				key: this._key,
+				password: this._password,
+			});
+		}
+
+		const encObj = this._headerEmbed._object as { files?: unknown[] } | null;
+		this.hasEncryptedFiles = !!(encObj && encObj.files && encObj.files.length);
+	}
+
+	getFilesToExtract(): FileRecord[] {
+		const filesToExtract: FileRecord[] = [];
+		let offset = 0;
+		offset += this._publicHeaderEmbed!.readBytes;
+		offset += this._headerEmbed!.readBytes;
+
+		const pubFiles = (this._publicHeaderEmbed!._object as { files: FileRecord[] }).files;
+		for (const fileRecord of pubFiles) {
+			filesToExtract.push({ ...fileRecord, isEncrypted: false, offset: offset });
+			offset += fileRecord.size;
+		}
+		const encFiles = (this._headerEmbed!._object as { files: FileRecord[] }).files;
+		for (const fileRecord of encFiles) {
+			filesToExtract.push({ ...fileRecord, isEncrypted: true, offset: offset });
+			offset += fileRecord.size;
+		}
+
+		return filesToExtract;
+	}
+
+	async restoreBinary(
+		readable: IReadable,
+		params: { key?: Buffer; password?: string | undefined },
+		n: number,
+		offset: number,
+		writable: IWritable | null = null,
+	): Promise<IWritable> {
+		if (!this._headerEmbed && !this._publicHeaderEmbed) {
+			await this.restoreFromReadable(readable, params, offset);
+		}
+
+		const filesToExtract = this.getFilesToExtract();
+		if (!filesToExtract[n]) {
+			throw new Error('There is no file ' + n + ' found in this container');
+		}
+
+		const fileSize = filesToExtract[n].size;
+		const fileOffset = offset + filesToExtract[n].offset!;
+
+		if (filesToExtract[n].isEncrypted) {
+			return await EmbedBinary.restoreFromReadable(readable, params, fileOffset, fileSize, writable);
+		} else {
+			const publicParams = { ...params, password: undefined, key: undefined };
+			return await EmbedBinary.restoreFromReadable(readable, publicParams, fileOffset, fileSize, writable);
+		}
+	}
+}