@majikah/majik-file 0.0.2 → 0.0.4

package/dist/core/compressor/majik-compressor.d.ts

@@ -8,12 +8,13 @@
  * lifetime of the module. Subsequent calls are synchronous after the first
  * await.
  */
-/**
- * Ensure the Zstd WASM module is initialised.
- * Safe to call concurrently — the second caller will await the same promise.
- */
-export declare function ensureZstd(): Promise<void>;
 export declare class MajikCompressor {
+    private static initialized;
+    /**
+     * Ensure the Zstd WASM module is initialised.
+     * Safe to call concurrently — the second caller will await the same promise.
+     */
+    private static ensureInit;
     /**
      * Compress raw bytes using Zstd at the specified level.
      *

package/dist/core/compressor/majik-compressor.js

@@ -11,20 +11,19 @@
 import { init, compress as zstdCompress, decompress as zstdDecompress, } from "@bokuweb/zstd-wasm";
 import { MajikFileError } from "../error";
 import { ZSTD_MAX_LEVEL } from "../crypto/constants";
-// ─── Init Guard ───────────────────────────────────────────────────────────────
-let zstdReady = false;
-/**
- * Ensure the Zstd WASM module is initialised.
- * Safe to call concurrently — the second caller will await the same promise.
- */
-export async function ensureZstd() {
-    if (!zstdReady) {
-        await init();
-        zstdReady = true;
-    }
-}
 // ─── MajikCompressor ──────────────────────────────────────────────────────────
 export class MajikCompressor {
+    static initialized = false;
+    /**
+     * Ensure the Zstd WASM module is initialised.
+     * Safe to call concurrently — the second caller will await the same promise.
+     */
+    static async ensureInit() {
+        if (!this.initialized) {
+            await init(); // only init Zstd for binary mode
+            this.initialized = true;
+        }
+    }
     /**
      * Compress raw bytes using Zstd at the specified level.
      *
@@ -41,7 +40,7 @@ export class MajikCompressor {
             throw MajikFileError.invalidInput(`MajikCompressor.compress: level must be an integer between 1 and 22 (got ${level})`);
         }
         try {
-            await ensureZstd();
+            await this.ensureInit();
             return zstdCompress(data, level);
         }
         catch (err) {
@@ -60,7 +59,7 @@ export class MajikCompressor {
             throw MajikFileError.invalidInput("MajikCompressor.decompress: data must be a non-empty Uint8Array");
         }
         try {
-            await ensureZstd();
+            await this.ensureInit();
             return zstdDecompress(data);
         }
         catch (err) {

package/dist/core/types.d.ts

@@ -49,6 +49,10 @@ export interface MajikFileGroupKey {
 export interface MjkbSinglePayload {
     /** Base64-encoded ML-KEM-768 ciphertext (1088 bytes). */
     mlKemCipherText: string;
+    /** Original filename (e.g. "photo.png"). Short key keeps the binary compact. */
+    n?: string | null;
+    /** Original MIME type (e.g. "image/png"). Short key keeps the binary compact. */
+    m?: string | null;
 }
 /**
  * JSON payload embedded in a group .mjkb binary.
@@ -58,6 +62,10 @@ export interface MjkbSinglePayload {
 export interface MjkbGroupPayload {
     /** Per-recipient key entries. */
     keys: MajikFileGroupKey[];
+    /** Original filename (e.g. "photo.png"). Short key keeps the binary compact. */
+    n?: string | null;
+    /** Original MIME type (e.g. "image/png"). Short key keeps the binary compact. */
+    m?: string | null;
 }
 export type MjkbPayload = MjkbSinglePayload | MjkbGroupPayload;
 export declare function isMjkbGroupPayload(p: MjkbPayload): p is MjkbGroupPayload;

package/dist/majik-file.d.ts

@@ -147,6 +147,23 @@ export declare class MajikFile {
      * @throws MajikFileError on wrong key, missing key entry, corrupt data, or format errors.
      */
     static decrypt(source: Blob | Uint8Array | ArrayBuffer, identity: Pick<MajikFileIdentity, "fingerprint" | "mlKemSecretKey">): Promise<Uint8Array>;
+    /**
+     * Decrypt a .mjkb binary and return the raw bytes together with the
+     * original filename and MIME type that were embedded in the payload at
+     * encryption time.
+     *
+     * This is the preferred method for the File Vault UI because it avoids a
+     * second parse of the binary — everything comes from the single decodeMjkb
+     * call that decryption already performs.
+     *
+     * @returns `{ bytes, originalName, mimeType }` where `originalName` and
+     *          `mimeType` may be null if the file was encrypted without metadata.
+     */
+    static decryptWithMetadata(source: Blob | Uint8Array | ArrayBuffer, identity: Pick<MajikFileIdentity, "fingerprint" | "mlKemSecretKey">): Promise<{
+        bytes: Uint8Array;
+        originalName: string | null;
+        mimeType: string | null;
+    }>;
     /**
      * Decrypt the .mjkb binary already loaded on this instance.
      * Convenience wrapper around MajikFile.decrypt() — avoids re-fetching from R2.

package/dist/majik-file.js

@@ -315,6 +315,8 @@ export class MajikFile {
                 ciphertext = aesGcmEncrypt(sharedSecret, iv, compressed);
                 payload = {
                     mlKemCipherText: arrayToBase64(mlKemCT),
+                    n: originalName ?? null,
+                    m: resolvedMimeType ?? null,
                 };
             }
             else {
@@ -343,7 +345,11 @@ export class MajikFile {
                         encryptedAesKey: arrayToBase64(encryptedAesKey),
                     };
                 });
-                payload = { keys };
+                payload = {
+                    keys,
+                    n: originalName ?? null,
+                    m: resolvedMimeType ?? null,
+                };
             }
             // ── 6. Encode .mjkb ───────────────────────────────────────────────
             const mjkbBytes = encodeMjkb(iv, payload, ciphertext);
@@ -457,6 +463,71 @@ export class MajikFile {
             throw MajikFileError.decryptionFailed("File decryption failed", err);
         }
     }
+    /**
+     * Decrypt a .mjkb binary and return the raw bytes together with the
+     * original filename and MIME type that were embedded in the payload at
+     * encryption time.
+     *
+     * This is the preferred method for the File Vault UI because it avoids a
+     * second parse of the binary — everything comes from the single decodeMjkb
+     * call that decryption already performs.
+     *
+     * @returns `{ bytes, originalName, mimeType }` where `originalName` and
+     *          `mimeType` may be null if the file was encrypted without metadata.
+     */
+    static async decryptWithMetadata(source, identity) {
+        if (!identity)
+            throw MajikFileError.invalidInput("identity is required for decryption");
+        if (!(identity.mlKemSecretKey instanceof Uint8Array) ||
+            identity.mlKemSecretKey.length !== ML_KEM_SK_LEN) {
+            throw MajikFileError.invalidInput(`identity.mlKemSecretKey must be ${ML_KEM_SK_LEN} bytes (got ${identity.mlKemSecretKey?.length ?? "undefined"})`);
+        }
+        try {
+            const raw = await normaliseToUint8ArrayAsync(source);
+            const { iv, payload, ciphertext } = decodeMjkb(raw);
+            let aesKey;
+            if (isMjkbSinglePayload(payload)) {
+                const mlKemCT = base64ToUint8Array(payload.mlKemCipherText);
+                aesKey = mlKemDecapsulate(mlKemCT, identity.mlKemSecretKey);
+            }
+            else if (isMjkbGroupPayload(payload)) {
+                if (!identity.fingerprint?.trim()) {
+                    throw MajikFileError.invalidInput("identity.fingerprint is required to decrypt group files");
+                }
+                const entry = payload.keys.find((k) => k.fingerprint === identity.fingerprint);
+                if (!entry) {
+                    throw MajikFileError.decryptionFailed(`No key entry found for fingerprint "${identity.fingerprint}"`);
+                }
+                const mlKemCT = base64ToUint8Array(entry.mlKemCipherText);
+                const sharedSecret = mlKemDecapsulate(mlKemCT, identity.mlKemSecretKey);
+                const encAesKey = base64ToUint8Array(entry.encryptedAesKey);
+                aesKey = new Uint8Array(AES_KEY_LEN);
+                for (let i = 0; i < AES_KEY_LEN; i++) {
+                    aesKey[i] = encAesKey[i] ^ sharedSecret[i];
+                }
+            }
+            else {
+                throw MajikFileError.formatError(".mjkb payload JSON is neither a single nor group payload");
+            }
+            const compressed = aesGcmDecrypt(aesKey, iv, ciphertext);
+            if (!compressed) {
+                throw MajikFileError.decryptionFailed("Decryption failed — wrong key or corrupted .mjkb file");
+            }
+            const bytes = await MajikCompressor.decompress(compressed);
+            // Extract original filename and MIME type from the payload.
+            // Written at encryption time as short keys n/m to keep the binary compact.
+            // Older .mjkb files without these fields return null — callers should fall
+            // back to stripping ".mjkb" from the filename and using "application/octet-stream".
+            const originalName = payload.n ?? null;
+            const mimeType = payload.m ?? null;
+            return { bytes, originalName, mimeType };
+        }
+        catch (err) {
+            if (err instanceof MajikFileError)
+                throw err;
+            throw MajikFileError.decryptionFailed("File decryption failed", err);
+        }
+    }
     /**
      * Decrypt the .mjkb binary already loaded on this instance.
      * Convenience wrapper around MajikFile.decrypt() — avoids re-fetching from R2.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@majikah/majik-file",
   "type": "module",
   "description": "Majik File is the core cryptographic engine for secure file handling in the Majikah ecosystem. It provides a post-quantum secure \"MJKB\" format designed for file encryption, multi-recipient key encapsulation, and transparent compression using NIST-standardized algorithms.",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",