@majikah/majik-file 0.0.1

package/LICENSE

@@ -0,0 +1,67 @@
+Copyright (c) 2025 Josef Elijah Delos Santos Fabian
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+---
+
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,310 @@
+# Majik File
+
+[![Developed by Zelijah](https://img.shields.io/badge/Developed%20by-Zelijah-red?logo=github&logoColor=white)](https://thezelijah.world) ![GitHub Sponsors](https://img.shields.io/github/sponsors/jedlsf?style=plastic&label=Sponsors&link=https%3A%2F%2Fgithub.com%2Fsponsors%2Fjedlsf)
+
+**Majik File** is the core cryptographic engine for secure file handling in the [Majik Message](https://github.com/Majikah/majik-message) ecosystem. It provides a **post-quantum secure "MJKB" format** designed for file encryption, multi-recipient key encapsulation, and transparent compression using NIST-standardized algorithms.
+
+![npm](https://img.shields.io/npm/v/@majikah/majik-file) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-file) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40majikah%2Fmajik-file) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+
+
+---
+- [Majik File](#majik-file)
+  - [Overview](#overview)
+    - [Key Features](#key-features)
+  - [Installation](#installation)
+  - [Usage Guide](#usage-guide)
+    - [Creating a MajikFile](#creating-a-majikfile)
+    - [Accessing metadata](#accessing-metadata)
+    - [Encrypting and exporting](#encrypting-and-exporting)
+    - [Decrypting a MajikFile](#decrypting-a-majikfile)
+    - [Sharing](#sharing)
+    - [Duplicate Detection](#duplicate-detection)
+    - [Stats](#stats)
+    - [Static Helpers](#static-helpers)
+  - [Notes](#notes)
+  - [Related Projects](#related-projects)
+    - [Majik Message](#majik-message)
+    - [Majik Key](#majik-key)
+    - [Majik Envelope](#majik-envelope)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Author](#author)
+  - [About the Developer](#about-the-developer)
+  - [Contact](#contact)
+
+
+---
+
+## Overview
+
+**Majik File** implements a **File Envelope Format**, which uses **ML-KEM-768 (FIPS-203)** for **post-quantum secure key encapsulation**.  
+
+It abstracts the complexity of:  
+
+- Managing shared secrets  
+- AES-GCM initialization vectors  
+- Multi-recipient key wrapping  
+- File compression/decompression  
+
+This allows developers to **securely encrypt and share files with minimal cryptographic overhead**.
+
+---
+
+### Key Features
+
+- **Single-recipient encryption**: ML-KEM encapsulation → AES-256-GCM key → encrypted `.mjkb`.
+- **Group encryption (2+ recipients)**:
+  - Random AES-256 key encrypts file once
+  - Per recipient: ML-KEM encapsulate → AES key XOR sharedSecret
+- **Write-once immutability**: `.mjkb` binaries are never patched in-place.
+- **Automatic deduplication**: Files are checked by SHA-256 hash before encryption.
+- **Context-aware storage**:
+  - `user_upload`, `chat_attachment`, `chat_image`, `thread_attachment`
+- **Optional image conversion**: Chat images/attachments converted to WebP for efficiency.
+- **Compression**: Zstd at level 22 for compressible formats.
+- **Expiry and sharing**:
+  - Temporary files with expiry date
+  - Shareable links with auto-generated tokens
+- **Inline viewable MIME detection** and safe download filename derivation.
+
+---
+
+## Installation
+
+```bash
+npm install @majikah/majik-file
+
+```
+
+---
+
+## Usage Guide
+
+### Creating a MajikFile
+
+The library automatically chooses between "Single" and "Group" logic based on the number of recipients.
+
+```ts
+import { MajikFile } from "@majikah/majik-file";
+
+const file = await MajikFile.create({
+  data: myFileBlob,           // Blob, ArrayBuffer, or Uint8Array
+  identity: {
+    userId: "user_123",
+    fingerprint: "BASE64_FINGERPRINT",
+    mlKemPublicKey: publicKey // Uint8Array of length 1184 bytes
+  },
+  context: "user_upload",     // or "chat_attachment", "chat_image", "thread_attachment"
+  originalName: "photo.png",
+  recipients: [               // Optional: for group encryption
+    {
+      fingerprint: "recipient_fingerprint",
+      mlKemPublicKey: recipientPublicKey
+    }
+  ],
+  isTemporary: true,          // Optional
+  expiresAt: MajikFile.buildExpiryDate(15)
+});
+
+
+```
+
+### Accessing metadata
+
+For group messages, a senderFingerprint is required for metadata.
+
+```ts
+console.log(file.id);
+console.log(file.originalName);
+console.log(file.sizeMB);
+console.log(file.isGroup);
+console.log(file.isExpired);
+console.log(file.safeFilename);
+
+
+```
+
+
+### Encrypting and exporting
+
+
+```ts
+// Export .mjkb binary for R2 upload
+const mjkbBlob = file.toMJKB();
+
+// Export raw Uint8Array
+const rawBytes = file.toBinaryBytes();
+
+
+
+```
+
+### Decrypting a MajikFile
+
+To decrypt, you simply provide the recipient's identity (their private ML-KEM key and fingerprint).
+
+```ts
+import { MajikFile } from "@majikah/majik-file";
+
+const decrypted = await MajikFile.decrypt(
+  mjkbBlob,
+  {
+    fingerprint: "BASE64_FINGERPRINT",
+    mlKemSecretKey: secretKey // Uint8Array of length 2400 bytes
+  }
+);
+
+// If you already loaded the binary into memory
+await file.decryptBinary({
+  fingerprint: "BASE64_FINGERPRINT",
+  mlKemSecretKey: secretKey
+});
+
+```
+
+### Sharing
+
+Enable sharing (auto-generates token if not provided)
+
+```ts
+
+const token = file.toggleSharing();
+
+// Disable sharing
+file.toggleSharing();
+
+```
+
+### Duplicate Detection
+
+```ts
+
+if (file.isDuplicateOf(otherFile)) {
+  console.log("Duplicate file detected");
+}
+
+if (MajikFile.wouldBeDuplicate(newRawBytes, existingHash)) {
+  console.log("New data is a duplicate");
+}
+
+
+```
+
+### Stats
+
+```ts
+
+console.log(file.getStats());
+
+
+```
+
+
+### Static Helpers
+
+```ts
+import { MajikFile } from "@majikah/majik-file";
+
+MajikFile.buildExpiryDate(15);   // ISO expiry date string
+MajikFile.formatBytes(1024);     // "1 KB"
+MajikFile.inferMimeType("file.png"); // "image/png"
+MajikFile.isMjkbCandidate(someBytes); // true/false
+MajikFile.hasPublicKeyAccess(pubKey, ownerFingerprint); // true/false
+
+```
+
+
+---
+## Notes
+
+.mjkb 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)]
+
+```
+
+- Owner is always first recipient in group encryption.
+- Files cannot be updated in place — delete + re-create for modifications.
+- Chat images always use conversation-scoped R2 prefix.
+
+---
+
+## Related Projects
+
+### [Majik Message](https://message.majikah.solutions)
+Secure messaging platform using Majik Keys
+
+![npm](https://img.shields.io/npm/v/@majikah/majik-message) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-message) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40majikah%2Fmajik-message) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+
+[Read more about Majik Message here](https://majikah.solutions/products/majik-message)
+
+[![Majik Message Thumbnail](https://github.com/user-attachments/assets/d433c6b8-1841-4fa1-a6da-b348029d1dbe)](https://message.majikah.solutions)
+
+> Click the image to try Majik Message live.
+
+[Read Docs](https://majikah.solutions/products/majik-message/docs)
+
+
+Also available on [Microsoft Store](https://apps.microsoft.com/detail/9pmjgvzzjspn) for free.
+
+[Official Repository](https://github.com/Majikah/majik-message)
+[SDK Library](https://www.npmjs.com/package/@majikah/majik-message)
+
+---
+
+### [Majik Key](https://majikah.solutions/sdk/majik-key)
+**Majik Key** is a seed phrase account library for creating, managing, and parsing mnemonic-based cryptographic accounts (Majik Keys). Generate deterministic key pairs from BIP39 seed phrases with simple, developer-friendly APIs. Now supports ML-KEM-768 post-quantum key derivation alongside X25519.
+
+![npm](https://img.shields.io/npm/v/@majikah/majik-key) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-key) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40majikah%2Fmajik-key) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+
+[Read Docs](https://majikah.solutions/sdk/majik-key/docs)
+[Official Repository](https://github.com/Majikah/majik-key)
+[SDK Library](https://www.npmjs.com/package/@majikah/majik-key)
+
+---
+
+
+### [Majik Envelope](https://majikah.solutions/sdk/majik-envelope)
+**Majik Envelope** is the core cryptographic engine of the [Majik Message](https://github.com/Majikah/majik-message) platform. It provides a post-quantum secure "envelope" format that handles message encryption, multi-recipient key encapsulation, and transparent compression using NIST-standardized algorithms.
+
+![npm](https://img.shields.io/npm/v/@majikah/majik-envelope) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-envelope) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40majikah%2Fmajik-envelope) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+
+[Read Docs](https://majikah.solutions/sdk/majik-envelope/docs)
+[Official Repository](https://github.com/Majikah/majik-envelope)
+[SDK Library](https://www.npmjs.com/package/@majikah/majik-envelope)
+
+---
+
+## Contributing
+
+If you want to contribute or help extend support to more platforms, reach out via email. All contributions are welcome!  
+
+---
+
+## License
+
+[Apache-2.0](LICENSE) — free for personal and commercial use.
+
+---
+## Author
+
+Made with 💙 by [@thezelijah](https://github.com/jedlsf)
+
+## About the Developer
+
+- **Developer**: Josef Elijah Fabian
+- **GitHub**: [https://github.com/jedlsf](https://github.com/jedlsf)
+- **Project Repository**: [https://github.com/Majikah/majik-file](https://github.com/Majikah/majik-file)
+
+---
+
+## Contact
+
+- **Business Email**: [business@thezelijah.world](mailto:business@thezelijah.world)
+- **Official Website**: [https://www.thezelijah.world](https://www.thezelijah.world)

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

@@ -0,0 +1,43 @@
+/**
+ * majik-compressor.ts
+ *
+ * Zstd (WASM) compression provider for MajikFile.
+ * Uses @bokuweb/zstd-wasm exclusively — no gzip fallback.
+ *
+ * The WASM module is initialised lazily on first use and cached for the
+ * 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 {
+    /**
+     * Compress raw bytes using Zstd at the specified level.
+     *
+     * @param data   Raw bytes to compress.
+     * @param level  Compression level 1–22. Defaults to ZSTD_MAX_LEVEL (22).
+     * @returns      Compressed bytes.
+     * @throws       MajikFileError on failure.
+     */
+    static compress(data: Uint8Array, level?: number): Promise<Uint8Array>;
+    /**
+     * Decompress Zstd-compressed bytes.
+     *
+     * @param data  Zstd-compressed bytes.
+     * @returns     Decompressed bytes.
+     * @throws      MajikFileError on failure or corrupt data.
+     */
+    static decompress(data: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Returns the compression ratio as a percentage size reduction.
+     * e.g. 100 bytes → 30 bytes = 70.0% reduction.
+     *
+     * @param originalSize   Size before compression (bytes).
+     * @param compressedSize Size after compression (bytes).
+     * @returns              Reduction percentage (0–100), rounded to one decimal.
+     */
+    static compressionRatioPct(originalSize: number, compressedSize: number): number;
+}

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

@@ -0,0 +1,84 @@
+/**
+ * majik-compressor.ts
+ *
+ * Zstd (WASM) compression provider for MajikFile.
+ * Uses @bokuweb/zstd-wasm exclusively — no gzip fallback.
+ *
+ * The WASM module is initialised lazily on first use and cached for the
+ * lifetime of the module. Subsequent calls are synchronous after the first
+ * await.
+ */
+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 {
+    /**
+     * Compress raw bytes using Zstd at the specified level.
+     *
+     * @param data   Raw bytes to compress.
+     * @param level  Compression level 1–22. Defaults to ZSTD_MAX_LEVEL (22).
+     * @returns      Compressed bytes.
+     * @throws       MajikFileError on failure.
+     */
+    static async compress(data, level = ZSTD_MAX_LEVEL) {
+        if (!(data instanceof Uint8Array) || data.length === 0) {
+            throw MajikFileError.invalidInput("MajikCompressor.compress: data must be a non-empty Uint8Array");
+        }
+        if (!Number.isInteger(level) || level < 1 || level > 22) {
+            throw MajikFileError.invalidInput(`MajikCompressor.compress: level must be an integer between 1 and 22 (got ${level})`);
+        }
+        try {
+            await ensureZstd();
+            return zstdCompress(data, level);
+        }
+        catch (err) {
+            throw MajikFileError.compressionFailed(err);
+        }
+    }
+    /**
+     * Decompress Zstd-compressed bytes.
+     *
+     * @param data  Zstd-compressed bytes.
+     * @returns     Decompressed bytes.
+     * @throws      MajikFileError on failure or corrupt data.
+     */
+    static async decompress(data) {
+        if (!(data instanceof Uint8Array) || data.length === 0) {
+            throw MajikFileError.invalidInput("MajikCompressor.decompress: data must be a non-empty Uint8Array");
+        }
+        try {
+            await ensureZstd();
+            return zstdDecompress(data);
+        }
+        catch (err) {
+            throw MajikFileError.decompressionFailed(err);
+        }
+    }
+    /**
+     * Returns the compression ratio as a percentage size reduction.
+     * e.g. 100 bytes → 30 bytes = 70.0% reduction.
+     *
+     * @param originalSize   Size before compression (bytes).
+     * @param compressedSize Size after compression (bytes).
+     * @returns              Reduction percentage (0–100), rounded to one decimal.
+     */
+    static compressionRatioPct(originalSize, compressedSize) {
+        if (originalSize <= 0)
+            return 0;
+        const reduction = ((originalSize - compressedSize) / originalSize) * 100;
+        return Math.max(0, Math.round(reduction * 10) / 10);
+    }
+}

package/dist/core/crypto/constants.d.ts

@@ -0,0 +1,93 @@
+/** Current .mjkb binary format version. */
+export declare const MJKB_VERSION: 1;
+/**
+ * .mjkb magic bytes: ASCII "MJKB" (0x4D 0x4A 0x4B 0x42).
+ * Present at the very start of every .mjkb file for format identification.
+ */
+export declare const MJKB_MAGIC: Uint8Array;
+/**
+ * Fixed header size before the variable-length payload JSON section:
+ *   4    magic "MJKB"
+ *   1    version
+ *   12   AES-GCM IV
+ *   4    payload JSON length (big-endian uint32)
+ * = 21 bytes
+ *
+ * @deprecated Use MJKB_FIXED_HEADER in utils.ts — this constant is kept only
+ * for backwards-compatibility with any external code that referenced it.
+ */
+export declare const MJKB_HEADER_SIZE: number;
+/** ML-KEM-768 public key length in bytes. */
+export declare const ML_KEM_PK_LEN = 1184;
+/** ML-KEM-768 secret key length in bytes. */
+export declare const ML_KEM_SK_LEN = 2400;
+/** ML-KEM-768 ciphertext length in bytes. */
+export declare const ML_KEM_CT_LEN = 1088;
+/** AES-256-GCM key length in bytes. */
+export declare const AES_KEY_LEN = 32;
+/** AES-GCM IV length in bytes. */
+export declare const IV_LENGTH = 12;
+/** Maximum Zstd compression level (highest ratio, slowest). */
+export declare const ZSTD_MAX_LEVEL = 22;
+/** Default maximum file size: 100 MB in bytes. Bypassable via CreateOptions. */
+export declare const MAX_FILE_SIZE_BYTES: number;
+/**
+ * R2 bucket key prefixes.
+ *
+ * PERMANENT  →  files/user/<userId>/<fileHash>.mjkb
+ *   Retained indefinitely. Scoped to the user's sub-directory.
+ *
+ * TEMPORARY  →  files/public/<userId>_<fileHash>.mjkb
+ *   Auto-deleted after ~15 days by the bucket lifecycle policy
+ *   targeting all objects under the `files/public/` prefix.
+ */
+export declare const R2_PREFIX: {
+    readonly PERMANENT: "files/user";
+    readonly TEMPORARY: "files/public";
+    /**
+     * Encrypted WebP chat images.
+     * Structure: images/chats/<conversationId>/<userId>_<fileHash>.mjkb
+     *
+     * Scoped per conversation so all images in a conversation can be
+     * batch-deleted (e.g. when a conversation is removed).
+     * These files use temporary storage by default with the standard
+     * 15-day R2 lifecycle policy, but can be made permanent if needed.
+     */
+    readonly CHAT_IMAGE: "images/chats";
+};
+export type R2Prefix = (typeof R2_PREFIX)[keyof typeof R2_PREFIX];
+/**
+ * MIME types that can be rendered inline in a modern browser without
+ * requiring a download. Used by MajikFile.isInlineViewable.
+ */
+export declare const INLINE_VIEWABLE_MIME_TYPES: Set<string>;
+/**
+ * Comprehensive MIME type registry for popular file formats.
+ * Used for validation, labelling, and icon selection in the UI.
+ * Organised by category.
+ */
+export declare const KNOWN_MIME_TYPES: Set<string>;
+/**
+ * Map from common file extension → canonical MIME type.
+ * Use this when a file is uploaded without a MIME type and you need to infer
+ * one from the filename extension.
+ */
+export declare const EXTENSION_TO_MIME: Readonly<Record<string, string>>;
+/**
+ * Maximum number of recipients for a group-encrypted file.
+ * Prevents pathological payload sizes (each recipient adds ~1.5 KB to the
+ * .mjkb binary: 1088-byte ML-KEM CT + 32-byte encrypted AES key in base64).
+ */
+export declare const MAX_RECIPIENTS = 100;
+/**
+ * MIME type prefixes and exact types that are already compressed at the
+ * codec level. Applying Zstd to these yields negligible savings and
+ * measurable CPU/memory overhead — especially on mobile.
+ */
+export declare const INCOMPRESSIBLE_MIME_TYPES: Set<string>;
+/**
+ * Image MIME types that can be re-encoded to WebP in the browser.
+ * Used by the chat attachment path to normalise all images to WebP before
+ * encryption, reducing payload size for non-WebP sources.
+ */
+export declare const WEBP_CONVERTIBLE_IMAGE_TYPES: Set<string>;