@majikah/majik-file 0.0.8 → 0.0.10

package/dist/core/types.d.ts

@@ -53,6 +53,8 @@ export interface MjkbSinglePayload {
     n: string | null;
     /** Original MIME type (e.g. "image/png"). Short key keeps the binary compact. */
     m: string | null;
+    /** Usage context — determines downstream UX and access control. */
+    c: FileContext | null;
 }
 /**
  * JSON payload embedded in a group .mjkb binary.
@@ -66,6 +68,8 @@ export interface MjkbGroupPayload {
     n: string | null;
     /** Original MIME type (e.g. "image/png"). Short key keeps the binary compact. */
     m: string | null;
+    /** Usage context — determines downstream UX and access control. */
+    c: FileContext | null;
 }
 export type MjkbPayload = MjkbSinglePayload | MjkbGroupPayload;
 export declare function isMjkbGroupPayload(p: MjkbPayload): p is MjkbGroupPayload;

package/dist/majik-file.d.ts

@@ -50,21 +50,21 @@ import type { MajikFileJSON, CreateOptions, MajikFileIdentity, MajikFileStats, F
 export declare class MajikFile {
     private readonly _id;
     private readonly _userId;
-    private readonly _r2Key;
+    private _r2Key;
     private readonly _originalName;
     private readonly _mimeType;
     private readonly _sizeOriginal;
     private readonly _sizeStored;
     private readonly _fileHash;
     private readonly _encryptionIv;
-    private readonly _storageType;
+    private _storageType;
     private _isShared;
     private _shareToken;
     private readonly _context;
     private readonly _chatMessageId;
     private readonly _threadMessageId;
     private readonly _conversationId;
-    private readonly _expiresAt;
+    private _expiresAt;
     private readonly _timestamp;
     private _lastUpdate;
     private readonly _isGroup;
@@ -171,6 +171,27 @@ export declare class MajikFile {
      * @throws MajikFileError if _binary is not loaded or decryption fails.
      */
     decryptBinary(identity: Pick<MajikFileIdentity, "fingerprint" | "mlKemSecretKey">): Promise<Uint8Array>;
+    /**
+     * Mutate the storage type in-place and rebuild the R2 key to match.
+     *
+     * This is intentionally a low-level escape hatch. Prefer the convenience
+     * wrappers `setPermanent()` and `setTemporary(days?)` which enforce the
+     * required invariants automatically.
+     *
+     * @throws MajikFileError when switching to temporary without an expiresAt,
+     *         or if the instance has no userId / fileHash yet.
+     */
+    setStorageType(type: StorageType, expiresAt: string | null): void;
+    /**
+     * Switch to permanent storage. Clears any expiry date and updates the R2 key.
+     */
+    setPermanent(): void;
+    /**
+     * Switch to temporary storage with an optional TTL.
+     *
+     * @param days  Days until expiry. Defaults to 15 to match R2 lifecycle policy.
+     */
+    setTemporary(days?: number): void;
     /**
      * Serialise metadata to a plain object matching the `majik_files` Supabase table.
      * The encrypted binary (_binary) is intentionally excluded.

package/dist/majik-file.js

@@ -214,7 +214,7 @@ export class MajikFile {
      * @throws MajikFileError on validation or crypto failure
      */
     static async create(options) {
-        const { data, identity, context, recipients = [], originalName = null, mimeType: rawMimeType = null, isTemporary = false, isShared = false, id = generateUUID(), bypassSizeLimit = false, expiresAt = null, chatMessageId = null, threadMessageId = null, conversationId = null, userId } = options;
+        const { data, identity, context, recipients = [], originalName = null, mimeType: rawMimeType = null, isTemporary = false, isShared = false, id = generateUUID(), bypassSizeLimit = false, expiresAt = null, chatMessageId = null, threadMessageId = null, conversationId = null, userId, } = options;
         // ── Input validation ─────────────────────────────────────────────────
         if (!data)
             throw MajikFileError.invalidInput("data is required");
@@ -292,7 +292,9 @@ export class MajikFile {
             // WebP and therefore skipped here — WebP is already codec-compressed.
             // For user_upload and thread_attachment, compressible images (PNG, BMP,
             // TIFF, SVG, etc.) are Zstd-compressed at level 22.
-            const compressible = shouldCompress(resolvedMimeType);
+            const compressible = context === "user_upload" || context === "thread_attachment"
+                ? true
+                : shouldCompress(resolvedMimeType);
             const compressed = compressible
                 ? await MajikCompressor.compress(processedBytes)
                 : processedBytes;
@@ -317,6 +319,7 @@ export class MajikFile {
                     mlKemCipherText: arrayToBase64(mlKemCT),
                     n: originalName ?? null,
                     m: resolvedMimeType ?? null,
+                    c: context ?? null,
                 };
             }
             else {
@@ -349,6 +352,7 @@ export class MajikFile {
                     keys,
                     n: originalName ?? null,
                     m: resolvedMimeType ?? null,
+                    c: context ?? null,
                 };
             }
             // ── 6. Encode .mjkb ───────────────────────────────────────────────
@@ -451,11 +455,17 @@ export class MajikFile {
             else {
                 throw MajikFileError.formatError(".mjkb payload JSON is neither a single nor group payload");
             }
-            const compressed = aesGcmDecrypt(aesKey, iv, ciphertext);
-            if (!compressed) {
+            const decrypted = aesGcmDecrypt(aesKey, iv, ciphertext);
+            if (!decrypted) {
                 throw MajikFileError.decryptionFailed("Decryption failed — wrong key or corrupted .mjkb file");
             }
-            return await MajikCompressor.decompress(compressed);
+            const compressible = payload.c === "user_upload" || payload.c === "thread_attachment"
+                ? true
+                : shouldCompress(payload.m);
+            const returnData = compressible
+                ? await MajikCompressor.decompress(decrypted)
+                : decrypted;
+            return returnData;
         }
         catch (err) {
             if (err instanceof MajikFileError)
@@ -509,11 +519,16 @@ export class MajikFile {
             else {
                 throw MajikFileError.formatError(".mjkb payload JSON is neither a single nor group payload");
             }
-            const compressed = aesGcmDecrypt(aesKey, iv, ciphertext);
-            if (!compressed) {
+            const decrypted = aesGcmDecrypt(aesKey, iv, ciphertext);
+            if (!decrypted) {
                 throw MajikFileError.decryptionFailed("Decryption failed — wrong key or corrupted .mjkb file");
             }
-            const bytes = await MajikCompressor.decompress(compressed);
+            const compressible = payload.c === "user_upload" || payload.c === "thread_attachment"
+                ? true
+                : shouldCompress(payload.m);
+            const bytes = compressible
+                ? await MajikCompressor.decompress(decrypted)
+                : decrypted;
             // 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
@@ -539,6 +554,52 @@ export class MajikFile {
             throw MajikFileError.missingBinary();
         return MajikFile.decrypt(this._binary, identity);
     }
+    // ── STORAGE TYPE MUTATION ─────────────────────────────────────────────────
+    /**
+     * Mutate the storage type in-place and rebuild the R2 key to match.
+     *
+     * This is intentionally a low-level escape hatch. Prefer the convenience
+     * wrappers `setPermanent()` and `setTemporary(days?)` which enforce the
+     * required invariants automatically.
+     *
+     * @throws MajikFileError when switching to temporary without an expiresAt,
+     *         or if the instance has no userId / fileHash yet.
+     */
+    setStorageType(type, expiresAt) {
+        if (!["permanent", "temporary"].includes(type)) {
+            throw MajikFileError.invalidInput(`setStorageType: type must be "permanent" or "temporary" (got "${type}")`);
+        }
+        if (type === "temporary" && !expiresAt) {
+            throw MajikFileError.invalidInput("setStorageType: expiresAt is required when switching to temporary. " +
+                "Use setTemporary(days?) instead.");
+        }
+        // Rebuild R2 key — context is preserved, only the storage tier changes.
+        // chat_image files are context-scoped and must never be rekeyed here.
+        if (this._context === "chat_image") {
+            throw MajikFileError.invalidInput("setStorageType: chat_image files are conversation-scoped and cannot change storage type.");
+        }
+        const newR2Key = type === "temporary"
+            ? buildTemporaryR2Key(this._userId, this._fileHash)
+            : buildPermanentR2Key(this._userId, this._fileHash);
+        this._storageType = type;
+        this._expiresAt = type === "temporary" ? expiresAt : null;
+        this._r2Key = newR2Key;
+        this._lastUpdate = new Date().toISOString();
+    }
+    /**
+     * Switch to permanent storage. Clears any expiry date and updates the R2 key.
+     */
+    setPermanent() {
+        this.setStorageType("permanent", null);
+    }
+    /**
+     * Switch to temporary storage with an optional TTL.
+     *
+     * @param days  Days until expiry. Defaults to 15 to match R2 lifecycle policy.
+     */
+    setTemporary(days = 15) {
+        this.setStorageType("temporary", MajikFile.buildExpiryDate(days));
+    }
     // ── SERIALISATION ─────────────────────────────────────────────────────────
     /**
      * Serialise metadata to a plain object matching the `majik_files` Supabase table.

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.8",
+  "version": "0.0.10",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",