@majikah/majik-file 0.0.1

package/dist/core/utils.js

@@ -0,0 +1,413 @@
+/**
+ * utils.ts
+ *
+ * Utility functions for MajikFile:
+ *  - Base64 encode / decode
+ *  - SHA-256 hashing (synchronous via @stablelib/sha256)
+ *  - UUID generation
+ *  - .mjkb binary encode / decode  ← updated format supporting single & group
+ *  - R2 key construction
+ *  - MIME type helpers
+ *  - Human-readable file size formatting
+ *  - Expiry helpers
+ */
+import { hash } from "@stablelib/sha256";
+import { MajikFileError } from "./error";
+import { MJKB_MAGIC, MJKB_VERSION, R2_PREFIX, INLINE_VIEWABLE_MIME_TYPES, EXTENSION_TO_MIME, MAX_RECIPIENTS, INCOMPRESSIBLE_MIME_TYPES, WEBP_CONVERTIBLE_IMAGE_TYPES, } from "./crypto/constants";
+// ─── Base64 ───────────────────────────────────────────────────────────────────
+export function arrayToBase64(data) {
+    let binary = "";
+    const chunkSize = 0x8000;
+    for (let i = 0; i < data.length; i += chunkSize) {
+        binary += String.fromCharCode(...data.subarray(i, i + chunkSize));
+    }
+    return btoa(binary);
+}
+export function arrayBufferToBase64(buffer) {
+    return arrayToBase64(new Uint8Array(buffer));
+}
+export function base64ToUint8Array(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+export function base64ToArrayBuffer(base64) {
+    return base64ToUint8Array(base64).buffer;
+}
+// ─── SHA-256 ──────────────────────────────────────────────────────────────────
+/**
+ * Synchronous SHA-256 digest → lowercase hex string (64 chars).
+ * Always computed over the ORIGINAL raw bytes (before compression/encryption)
+ * so it can be used reliably for duplicate detection.
+ */
+export function sha256Hex(data) {
+    const digest = hash(data);
+    return Array.from(digest)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Synchronous SHA-256 digest → base64 string.
+ * Used for ML-KEM public key fingerprints.
+ */
+export function sha256Base64(data) {
+    return arrayToBase64(hash(data));
+}
+// ─── UUID ─────────────────────────────────────────────────────────────────────
+export function generateUUID() {
+    return crypto.randomUUID();
+}
+// ─── Human-readable Size ──────────────────────────────────────────────────────
+export function formatBytes(bytes) {
+    if (bytes < 0)
+        return "0 B";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 ** 2)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 ** 3)
+        return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+    return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+}
+// ─── R2 Key Construction ──────────────────────────────────────────────────────
+/**
+ * Build an R2 object key for a permanent (user-owned) file.
+ *   files/user/<userId>/<fileHash>.mjkb
+ */
+export function buildPermanentR2Key(userId, fileHash) {
+    return `${R2_PREFIX.PERMANENT}/${userId}/${fileHash}.mjkb`;
+}
+/**
+ * Build an R2 object key for a temporary / public file.
+ * Objects under this prefix are auto-deleted by the bucket lifecycle policy.
+ *   files/public/<userId>_<fileHash>.mjkb
+ */
+export function buildTemporaryR2Key(userId, fileHash) {
+    return `${R2_PREFIX.TEMPORARY}/${userId}_${fileHash}.mjkb`;
+}
+/**
+ * Build an R2 object key for an encrypted WebP chat image.
+ *
+ * Scoped per conversation so all images belonging to a conversation can be
+ * listed or batch-deleted via a single R2 prefix scan.
+ *
+ *   images/chats/<conversationId>/<userId>_<fileHash>.mjkb
+ *
+ * @param conversationId  The chat conversation / channel ID (UUID or slug).
+ * @param userId          The uploading user's auth sub (UUID).
+ * @param fileHash        SHA-256 hex digest of the ORIGINAL image bytes
+ *                        (pre-WebP-conversion, pre-compression) — same value
+ *                        stored in majik_files.file_hash for dedup queries.
+ */
+export function buildChatImageR2Key(conversationId, userId, fileHash) {
+    return `${R2_PREFIX.CHAT_IMAGE}/${conversationId}/${userId}_${fileHash}.mjkb`;
+}
+// ─── MIME Type Helpers ────────────────────────────────────────────────────────
+/**
+ * Returns true if the MIME type can be rendered inline in a browser.
+ */
+export function isMimeTypeInlineViewable(mimeType) {
+    if (!mimeType)
+        return false;
+    return INLINE_VIEWABLE_MIME_TYPES.has(mimeType.toLowerCase().split(";")[0].trim());
+}
+/**
+ * Infer a MIME type from a filename extension.
+ * Returns null if the extension is unknown.
+ *
+ * @example
+ * inferMimeTypeFromFilename("photo.jpg")  // "image/jpeg"
+ * inferMimeTypeFromFilename("archive.rar") // "application/x-rar-compressed"
+ * inferMimeTypeFromFilename("unknown.xyz") // null
+ */
+export function inferMimeTypeFromFilename(filename) {
+    if (!filename)
+        return null;
+    const dot = filename.lastIndexOf(".");
+    if (dot === -1)
+        return null;
+    const ext = filename.slice(dot + 1).toLowerCase();
+    return EXTENSION_TO_MIME[ext] ?? null;
+}
+/**
+ * Derive a safe download filename from the file hash + original extension.
+ * Falls back to "<hash>.mjkb" if originalName is null or has no extension.
+ */
+export function deriveFilename(fileHash, originalName) {
+    if (!originalName)
+        return `${fileHash}.mjkb`;
+    const dot = originalName.lastIndexOf(".");
+    const ext = dot !== -1 ? originalName.slice(dot).toLowerCase() : "";
+    const safeExt = /^\.[a-z0-9]{1,10}$/.test(ext) ? ext : "";
+    return `${fileHash}${safeExt || ".mjkb"}`;
+}
+// ─── Normalise Input to Uint8Array ────────────────────────────────────────────
+export function normaliseToUint8Array(data) {
+    if (data instanceof Uint8Array)
+        return data;
+    return new Uint8Array(data);
+}
+export async function normaliseToUint8ArrayAsync(data) {
+    if (data instanceof Blob)
+        return new Uint8Array(await data.arrayBuffer());
+    return normaliseToUint8Array(data);
+}
+// ─── .mjkb Binary Codec ───────────────────────────────────────────────────────
+//
+//  The format supports both single-recipient and group-recipient files by
+//  embedding a variable-length JSON payload section (instead of a fixed
+//  ML-KEM ciphertext field) after the IV.
+//
+//  ┌───────────────────────────────────────────────────────────────────────────┐
+//  │  4 bytes  │ Magic: ASCII "MJKB"  (0x4D 0x4A 0x4B 0x42)                  │
+//  │  1 byte   │ Version              (currently 0x01)                         │
+//  │ 12 bytes  │ AES-GCM IV                                                    │
+//  │  4 bytes  │ Payload JSON length  (big-endian uint32)                      │
+//  │  N bytes  │ Payload JSON         (UTF-8; MjkbSinglePayload | MjkbGroupPayload) │
+//  │  M bytes  │ AES-GCM ciphertext   (Zstd-compressed plaintext + 16-byte tag)│
+//  └───────────────────────────────────────────────────────────────────────────┘
+//
+//  Single payload JSON:
+//    { "mlKemCipherText": "<base64 1088 bytes>" }
+//
+//  Group payload JSON:
+//    { "keys": [{ "fingerprint": "...", "mlKemCipherText": "...", "encryptedAesKey": "..." }, ...] }
+//
+//  Fixed header size (before payload JSON):  4 + 1 + 12 + 4 = 21 bytes
+const MJKB_FIXED_HEADER = 4 + 1 + 12 + 4; // 21 bytes
+/**
+ * Encode a .mjkb binary from its constituent parts.
+ *
+ * @param iv          12-byte AES-GCM IV.
+ * @param payload     Serialised MjkbSinglePayload or MjkbGroupPayload.
+ * @param ciphertext  AES-GCM ciphertext (Zstd-compressed plaintext + 16-byte auth tag).
+ */
+export function encodeMjkb(iv, payload, ciphertext) {
+    const payloadBytes = new TextEncoder().encode(JSON.stringify(payload));
+    const payloadLen = payloadBytes.length;
+    const total = MJKB_FIXED_HEADER + payloadLen + ciphertext.length;
+    const buf = new Uint8Array(total);
+    let offset = 0;
+    // Magic
+    buf.set(MJKB_MAGIC, offset);
+    offset += 4;
+    // Version
+    buf[offset++] = MJKB_VERSION;
+    // IV (12 bytes)
+    buf.set(iv, offset);
+    offset += 12;
+    // Payload JSON length (big-endian uint32)
+    buf[offset++] = (payloadLen >>> 24) & 0xff;
+    buf[offset++] = (payloadLen >>> 16) & 0xff;
+    buf[offset++] = (payloadLen >>> 8) & 0xff;
+    buf[offset++] = payloadLen & 0xff;
+    // Payload JSON
+    buf.set(payloadBytes, offset);
+    offset += payloadLen;
+    // Ciphertext
+    buf.set(ciphertext, offset);
+    return buf;
+}
+/**
+ * Decode a raw .mjkb buffer into its constituent parts.
+ *
+ * @throws MajikFileError on magic mismatch, unsupported version, truncation,
+ *         or malformed payload JSON.
+ */
+export function decodeMjkb(raw) {
+    // Minimum: fixed header + 1 byte payload JSON + 1 byte ciphertext
+    if (raw.length < MJKB_FIXED_HEADER + 2) {
+        throw MajikFileError.formatError(`.mjkb binary is too short (${raw.length} bytes) — minimum is ${MJKB_FIXED_HEADER + 2} bytes`);
+    }
+    // Magic check
+    for (let i = 0; i < 4; i++) {
+        if (raw[i] !== MJKB_MAGIC[i]) {
+            throw MajikFileError.formatError("Invalid .mjkb magic bytes — this is not a MajikFile binary");
+        }
+    }
+    let offset = 4;
+    const version = raw[offset++];
+    if (version !== MJKB_VERSION) {
+        throw MajikFileError.unsupportedVersion(version, MJKB_VERSION);
+    }
+    // IV (12 bytes)
+    const iv = raw.slice(offset, offset + 12);
+    offset += 12;
+    // Payload JSON length (big-endian uint32)
+    const payloadLen = (raw[offset] << 24) |
+        (raw[offset + 1] << 16) |
+        (raw[offset + 2] << 8) |
+        raw[offset + 3];
+    offset += 4;
+    if (payloadLen <= 0 || raw.length < offset + payloadLen + 1) {
+        throw MajikFileError.formatError(`.mjkb binary is truncated — payload JSON declares ${payloadLen} bytes but insufficient data remains`);
+    }
+    // Payload JSON
+    let payload;
+    try {
+        payload = JSON.parse(new TextDecoder().decode(raw.slice(offset, offset + payloadLen)));
+    }
+    catch {
+        throw MajikFileError.formatError(".mjkb payload JSON is malformed and could not be parsed");
+    }
+    offset += payloadLen;
+    // Ciphertext (remainder)
+    const ciphertext = raw.slice(offset);
+    if (ciphertext.length === 0) {
+        throw MajikFileError.formatError(".mjkb ciphertext section is empty");
+    }
+    return { version, iv, payload, ciphertext };
+}
+// ─── Expiry Helpers ───────────────────────────────────────────────────────────
+/** Returns true if the given ISO-8601 timestamp is in the past. */
+export function isExpired(expiresAt) {
+    if (!expiresAt)
+        return false;
+    return new Date(expiresAt).getTime() < Date.now();
+}
+/**
+ * Build a default expiry ISO string for temporary files.
+ * @param days Days from now. Defaults to 15 (matching the R2 lifecycle policy).
+ */
+export function buildExpiryDate(days = 15) {
+    const d = new Date();
+    d.setDate(d.getDate() + days);
+    return d.toISOString();
+}
+// ─── Module-level helpers ─────────────────────────────────────────────────────
+/**
+ * Deduplicate a recipient list and strip the owner's own key.
+ *
+ * Rules:
+ *  - The owner's fingerprint is never allowed in `recipients` — it is
+ *    always prepended automatically in the group path. If present, it is
+ *    silently removed rather than throwing.
+ *  - Any fingerprint that appears more than once is deduplicated; the first
+ *    occurrence wins.
+ *  - Deduplication is by fingerprint string, not by raw public key bytes.
+ *
+ * Returns the cleaned list. If the result is empty the caller should use
+ * the single-recipient path.
+ */
+export function deduplicateRecipients(recipients, ownerFingerprint) {
+    const seen = new Set([ownerFingerprint]);
+    const result = [];
+    for (const r of recipients) {
+        if (seen.has(r.fingerprint))
+            continue; // owner duplicate or repeated entry
+        seen.add(r.fingerprint);
+        result.push(r);
+    }
+    return result;
+}
+/**
+ * Assert that the recipient count (after deduplication) does not exceed
+ * MAX_RECIPIENTS (100). Throws a MajikFileError if the limit is exceeded.
+ *
+ * Does NOT include the owner in the count — `recipients` here is the
+ * already-deduplicated list of *additional* recipients beyond the owner.
+ *
+ * @throws MajikFileError("INVALID_INPUT") if count > MAX_RECIPIENTS.
+ */
+export function assertRecipientLimit(recipients) {
+    if (recipients.length > MAX_RECIPIENTS) {
+        throw MajikFileError.invalidInput(`Too many recipients: ${recipients.length} (maximum is ${MAX_RECIPIENTS} excluding the owner). ` +
+            `Consider splitting into multiple files or threads.`);
+    }
+}
+/**
+ * Decide whether raw bytes should be Zstd-compressed before encryption.
+ *
+ * Returns false for MIME types that are already compressed at the codec level
+ * (JPEG, WebP, AVIF, all video, lossy audio, archives, zipped Office formats).
+ * Returns true for everything else — text, code, raw images (PNG, BMP),
+ * lossless audio (WAV, FLAC, AIFF), PDFs, JSON, XML, etc.
+ *
+ * @param mimeType  The resolved MIME type of the file, or null if unknown.
+ *                  When null, compression is applied (safer default).
+ */
+export function shouldCompress(mimeType) {
+    if (!mimeType)
+        return true;
+    const normalised = mimeType.toLowerCase().split(";")[0].trim();
+    return !INCOMPRESSIBLE_MIME_TYPES.has(normalised);
+}
+/**
+ * Convert an image Uint8Array to WebP format using the browser's Canvas API.
+ *
+ * Used exclusively in the `chat_attachment` context to normalise all
+ * non-WebP images (PNG, JPEG, GIF, BMP, etc.) to WebP before encryption.
+ * This reduces payload size for PNG and BMP in particular, and ensures a
+ * consistent delivery format to chat clients.
+ *
+ * SVG files are returned unchanged — they are vector and cannot be meaningfully
+ * rasterised without knowing the intended display dimensions.
+ *
+ * HEIC/HEIF/JXL files are returned unchanged — browsers do not support
+ * encoding these via Canvas.
+ *
+ * @param imageBytes  Raw bytes of the source image.
+ * @param mimeType    Resolved MIME type of the source image.
+ * @param quality     WebP encoding quality 0–1. Defaults to 0.88 (a good
+ *                    balance between visual quality and file size).
+ * @returns           WebP bytes, or the original bytes if conversion is not
+ *                    applicable for this MIME type.
+ */
+export async function convertImageToWebP(imageBytes, mimeType, quality = 0.88) {
+    const normalised = mimeType.toLowerCase().split(";")[0].trim();
+    // Already WebP, or not a type we can convert via Canvas
+    if (!WEBP_CONVERTIBLE_IMAGE_TYPES.has(normalised)) {
+        return { bytes: imageBytes, mimeType };
+    }
+    // Canvas API is only available in browser environments
+    if (typeof document === "undefined" ||
+        typeof HTMLCanvasElement === "undefined") {
+        // Server-side / non-browser environment — return as-is
+        return { bytes: imageBytes, mimeType };
+    }
+    return new Promise((resolve) => {
+        const blob = new Blob([imageBytes], { type: mimeType });
+        const url = URL.createObjectURL(blob);
+        const img = new Image();
+        img.onload = () => {
+            URL.revokeObjectURL(url);
+            try {
+                const canvas = document.createElement("canvas");
+                canvas.width = img.naturalWidth;
+                canvas.height = img.naturalHeight;
+                const ctx = canvas.getContext("2d");
+                if (!ctx) {
+                    // Canvas context unavailable — fall back to original
+                    resolve({ bytes: imageBytes, mimeType });
+                    return;
+                }
+                ctx.drawImage(img, 0, 0);
+                canvas.toBlob((webpBlob) => {
+                    if (!webpBlob) {
+                        // Browser declined to encode WebP — fall back to original
+                        resolve({ bytes: imageBytes, mimeType });
+                        return;
+                    }
+                    webpBlob
+                        .arrayBuffer()
+                        .then((buf) => {
+                        resolve({ bytes: new Uint8Array(buf), mimeType: "image/webp" });
+                    })
+                        .catch(() => resolve({ bytes: imageBytes, mimeType }));
+                }, "image/webp", quality);
+            }
+            catch {
+                resolve({ bytes: imageBytes, mimeType });
+            }
+        };
+        img.onerror = () => {
+            URL.revokeObjectURL(url);
+            // Not a renderable image — keep original
+            resolve({ bytes: imageBytes, mimeType });
+        };
+        img.src = url;
+    });
+}

package/dist/majik-file.d.ts

@@ -0,0 +1,280 @@
+import type { MajikFileJSON, CreateOptions, MajikFileIdentity, MajikFileStats, FileContext, StorageType } from "./core/types";
+/**
+ * MajikFile
+ * ----------------
+ * Post-quantum binary file encryption for Majik Message.
+ *
+ * Mirrors MajikEnvelope's single/group encryption model, but operates on raw
+ * binary blobs rather than plaintext strings.
+ *
+ * Single-recipient ────────────────────────────────────────────────────────
+ * ----------------
+ *   ML-KEM encapsulate → 32-byte sharedSecret used directly as AES-256-GCM key.
+ *   Payload JSON: { mlKemCipherText }
+ *
+ * Group (2+ recipients) ───────────────────────────────────────────────────
+ * ----------------
+ *   Generate random 32-byte AES key → encrypt file once.
+ *   Per recipient: ML-KEM encapsulate → encryptedAesKey = aesKey XOR sharedSecret.
+ *   Payload JSON: { keys: [{ fingerprint, mlKemCipherText, encryptedAesKey }] }
+ *
+ * The owner is always included as the first recipient automatically.
+ * Duplicate recipients are silently removed; if the deduplicated list is empty
+ * after stripping the owner's own key, single-recipient mode is used.
+ *
+ * ─── Immutability ────────────────────────────────────────────────────────────
+ *   MajikFile binaries are write-once. A file cannot be patched or replaced
+ *   in place — callers must delete the existing record + R2 object and call
+ *   create() again. This is enforced by the absence of any update/patch method
+ *   on the encrypted fields.
+ *
+ * ─── Encrypt pipeline ────────────────────────────────────────────────────────
+ *   raw bytes
+ *     → SHA-256 hash       (for dedup, computed pre-compression)
+ *     → image/webp convert (chat_image always; chat_attachment for images only)
+ *     → Zstd compress      (compressible formats only; skipped for already-
+ *                           compressed images JPEG/WebP/AVIF and video/audio/archives)
+ *     → [single] ML-KEM encapsulate → sharedSecret = AES key
+ *       [group]  random AES key; per recipient: ML-KEM encapsulate → XOR wrap
+ *     → AES-256-GCM encrypt
+ *     → .mjkb binary       (stored in R2)
+ *
+ * ─── .mjkb binary format ─────────────────────────────────────────────────────
+ *   [4   magic "MJKB"]
+ *   [1   version]
+ *   [12  AES-GCM IV]
+ *   [4   payload JSON length (big-endian uint32)]
+ *   [N   payload JSON — MjkbSinglePayload | MjkbGroupPayload]
+ *   [M   AES-GCM ciphertext (Zstd-compressed file + 16-byte auth tag)]
+ */
+export declare class MajikFile {
+    private readonly _id;
+    private readonly _userId;
+    private readonly _r2Key;
+    private readonly _originalName;
+    private readonly _mimeType;
+    private readonly _sizeOriginal;
+    private readonly _sizeStored;
+    private readonly _fileHash;
+    private readonly _encryptionIv;
+    private readonly _storageType;
+    private _isShared;
+    private _shareToken;
+    private readonly _context;
+    private readonly _chatMessageId;
+    private readonly _threadMessageId;
+    private readonly _conversationId;
+    private readonly _expiresAt;
+    private readonly _timestamp;
+    private _lastUpdate;
+    private readonly _isGroup;
+    /**
+     * Encrypted .mjkb binary.
+     * NOT serialised to JSON / Supabase — lives in R2 storage only.
+     */
+    private _binary;
+    private constructor();
+    get id(): string;
+    get userId(): string;
+    get r2Key(): string;
+    get originalName(): string | null;
+    get mimeType(): string | null;
+    get sizeOriginal(): number;
+    get sizeStored(): number;
+    get fileHash(): string;
+    /** Original file size in kilobytes (3 decimal places). */
+    get sizeKB(): number;
+    /** Original file size in megabytes (3 decimal places). */
+    get sizeMB(): number;
+    /** Original file size in gigabytes (3 decimal places). */
+    get sizeGB(): number;
+    /** Original file size in terabytes (3 decimal places). */
+    get sizeTB(): number;
+    get encryptionIv(): string;
+    get storageType(): StorageType;
+    get isShared(): boolean;
+    get shareToken(): string | null;
+    get context(): FileContext | null;
+    get chatMessageId(): string | null;
+    get threadMessageId(): string | null;
+    /** Conversation ID — only populated for chat_image context files. */
+    get conversationId(): string | null;
+    get expiresAt(): string | null;
+    get timestamp(): string | null;
+    get lastUpdate(): string | null;
+    /** True if the encrypted .mjkb binary is loaded in memory. */
+    get hasBinary(): boolean;
+    /** True if this file was encrypted for multiple recipients. */
+    get isGroup(): boolean;
+    /** True if this file was encrypted for a single recipient (the owner). */
+    get isSingle(): boolean;
+    /**
+     * Encrypt a raw binary file and produce a MajikFile instance.
+     *
+     * Single-recipient (no `recipients` supplied or empty array):
+     *   ML-KEM encapsulate → sharedSecret → AES-256-GCM key.
+     *
+     * Group (one or more entries in `recipients`):
+     *   Random 32-byte AES key encrypts the file once.
+     *   The owner + every recipient each get their own ML-KEM key entry.
+     *   encryptedAesKey = aesKey XOR sharedSecret  (safe one-time-pad).
+     *
+     * Steps:
+     *  1. Validate inputs and enforce size limit
+     *  2. Infer MIME type from filename if not provided
+     *  3. Compute SHA-256 file_hash (original bytes, pre-compression)
+     *  4. Zstd compress at level 22
+     *  5. Encrypt (single or group path)
+     *  6. Encode to .mjkb binary → store in _binary
+     *  7. Build metadata + validate
+     *
+     * @throws MajikFileError on validation or crypto failure
+     */
+    static create(options: CreateOptions): Promise<MajikFile>;
+    /**
+     * Decrypt a .mjkb Blob, Uint8Array, or ArrayBuffer.
+     *
+     * Single:
+     *   Decapsulate → sharedSecret → AES-256-GCM key → decompress → raw bytes.
+     *
+     * Group:
+     *   Find key entry by `identity.fingerprint` → decapsulate → XOR to recover
+     *   group AES key → AES-256-GCM decrypt → decompress → raw bytes.
+     *
+     * Note: ML-KEM decapsulation NEVER throws on a wrong key — it returns a garbage
+     * shared secret. AES-GCM authentication catches this silently (returns null).
+     *
+     * @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 the .mjkb binary already loaded on this instance.
+     * Convenience wrapper around MajikFile.decrypt() — avoids re-fetching from R2.
+     *
+     * @throws MajikFileError if _binary is not loaded or decryption fails.
+     */
+    decryptBinary(identity: Pick<MajikFileIdentity, "fingerprint" | "mlKemSecretKey">): Promise<Uint8Array>;
+    /**
+     * Serialise metadata to a plain object matching the `majik_files` Supabase table.
+     * The encrypted binary (_binary) is intentionally excluded.
+     */
+    toJSON(): MajikFileJSON;
+    /**
+     * Restore a MajikFile from its serialised JSON representation.
+     *
+     * The R2 prefix check is intentionally NOT performed here — rows restored
+     * from Supabase may have been written by earlier code or migrations and
+     * should not be rejected at read time.
+     *
+     * @param json   MajikFileJSON — typically a Supabase row.
+     * @param binary Optional encrypted .mjkb bytes. When provided the instance is
+     *               immediately ready for toMJKB() / decryptBinary().
+     */
+    static fromJSON(json: MajikFileJSON, binary?: Uint8Array | ArrayBuffer | null): MajikFile;
+    /**
+     * Async variant of fromJSON that accepts a Blob for the binary parameter.
+     */
+    static fromJSONWithBlob(json: MajikFileJSON, binary: Blob): Promise<MajikFile>;
+    /**
+     * Export the encrypted binary as a .mjkb Blob for upload to R2.
+     * @throws MajikFileError if _binary is not loaded.
+     */
+    toMJKB(): Blob;
+    /**
+     * Export the encrypted binary as a raw Uint8Array.
+     * @throws MajikFileError if _binary is not loaded.
+     */
+    toBinaryBytes(): Uint8Array;
+    /**
+     * Validate all required properties against business invariants.
+     * Collects ALL errors before throwing so the full list is visible at once.
+     *
+     * NOTE: R2 prefix structure is only checked during create(), not here.
+     * This keeps fromJSON() tolerant of rows written by other services.
+     *
+     * @throws MajikFileError
+     */
+    validate(): void;
+    /**
+     * Stricter validation used only during create() — includes R2 prefix checks.
+     */
+    private _validateCreate;
+    /** Returns true if the given userId matches the file's owner. */
+    userIsOwner(userId: string): boolean;
+    /**
+     * Attach (or replace) the encrypted .mjkb binary on this instance.
+     * Also updates the isGroup flag by peeking at the payload type.
+     */
+    attachBinary(binary: Uint8Array | ArrayBuffer): void;
+    /**
+     * Clear the in-memory binary to free memory after an upload completes.
+     */
+    clearBinary(): void;
+    /** Returns true if this file has an active share token. */
+    get hasShareToken(): boolean;
+    /**
+     * Toggle the shareable state of this file.
+     *
+     * - If currently NOT shared → sets isShared = true, assigns token (auto-generated if omitted).
+     * - If currently shared     → sets isShared = false, clears token.
+     *
+     * Updates last_update automatically. Call toJSON() to persist the change.
+     *
+     * @param token  Optional explicit token. Ignored when toggling OFF.
+     * @returns      The active share token, or null if sharing was disabled.
+     */
+    toggleSharing(token?: string): string | null;
+    /** Returns true if this file has passed its expiry date. */
+    get isExpired(): boolean;
+    /** Returns true if this file uses temporary storage. */
+    get isTemporary(): boolean;
+    /** Returns true if the MIME type can be rendered inline in a browser. */
+    get isInlineViewable(): boolean;
+    /** Safe download filename derived from the hash + original extension. */
+    get safeFilename(): string;
+    /**
+     * Returns true if the original file size exceeds the given limit.
+     * @param limitMB  Limit in megabytes (must be positive and finite).
+     * @throws MajikFileError on invalid input.
+     */
+    exceedsSize(limitMB: number): boolean;
+    /**
+     * Lightweight fingerprint check — returns true if the given public key
+     * hashes (SHA-256 base64) to the supplied ownerFingerprint.
+     *
+     * This does NOT attempt decryption. For cryptographic proof use decrypt().
+     *
+     * @param publicKey         ML-KEM-768 public key (1184 bytes).
+     * @param ownerFingerprint  Base64 SHA-256 fingerprint of the authorised key.
+     */
+    static hasPublicKeyAccess(publicKey: Uint8Array, ownerFingerprint: string): boolean;
+    /** Return a human-readable stats snapshot for display in a file manager UI. */
+    getStats(): MajikFileStats;
+    /**
+     * Returns true if this file has the same plaintext content as another
+     * MajikFile (comparison by SHA-256 file_hash of original bytes).
+     */
+    isDuplicateOf(other: MajikFile): boolean;
+    /**
+     * Synchronous check — returns true if raw bytes would produce a duplicate.
+     * Use this to short-circuit the encrypt + upload flow.
+     */
+    static wouldBeDuplicate(rawBytes: Uint8Array, existingHash: string): boolean;
+    /**
+     * Quick magic-byte check. Does NOT fully parse — use before attempting decryption.
+     */
+    static isMjkbCandidate(data: Uint8Array | ArrayBuffer): boolean;
+    /**
+     * Build a default ISO-8601 expiry date for temporary files.
+     * @param days Days from now. Defaults to 15 (R2 lifecycle policy).
+     */
+    static buildExpiryDate(days?: number): string;
+    /** Format bytes as a human-readable string (e.g. "4.2 MB"). */
+    static formatBytes(bytes: number): string;
+    /**
+     * Infer a MIME type from a filename extension.
+     * Exposed here for convenience — delegates to core/utils.
+     */
+    static inferMimeType(filename: string): string | null;
+    toString(): string;
+}