Majik File Client

Post-quantum file encryption client for Majik File (.mjkb). Client-side ML-KEM-768 and AES-256-GCM file processing, streaming, zero-knowledge security, and storage metadata routing.

Overview

@majikah/majik-file-client is a high-level wrapper and client orchestrator for the Majik ecosystem. It brings together identity management, post-quantum file encryption (.mjkb), cryptographic signing, contact directories, and zero-knowledge file vault storage into a single, cohesive TypeScript interface.

This library is designed for seamless integration into web apps, desktop wrappers (Electron/Tauri), and local-first browser environments.

Features

• Post-Quantum Cryptography: Encrypt and decrypt files using ML-KEM-768 and AES-256-GCM.
• Zero-Knowledge File Storage: Manage local file vaults (MajikFileVaultManager) and client state seamlessly.
• Integrated Identity & Keystore: Built on top of @majikah/majik-key-client for seamless account creation, unlocking, and active-account tracking.
• Contact Directory: Built-in MajikContactManager for managing trusted identities, groups, favorites, and blocked contacts.
• Advanced File Signatures: Detached, embedded, multi-sig, and timestamped (TSA) file signing.
• Audit Logging: Built-in HistoryLogManager and UserActivityLogManager to keep an immutable, localized trail of cryptographic operations and user actions.
• Compression: Integrated zstd compression via fflate.

Installation

npm install @majikah/majik-file-client

Architecture

The core of this package is the MajikFileClient (which extends MajikKeyClient). It serves as the primary entry point to coordinate the following domains:

• MajikContactManager: Directory for user contacts.
• MajikFileVaultItemVaultManager: Local storage interface for encrypted items.
• ClientStateManager: User app preferences and runtime states.
• HistoryLogManager / UserActivityLogManager: Action auditing.

Quick Start & Usage

1. Initialization and Hydration

import { MajikFileClient, InMemoryFileVaultAdapter } from "@majikah/majik-file-client";

// Initialize the client with storage adapters (defaults to in-memory if omitted)
const client = new MajikFileClient({
  adapters: {
    vault: new InMemoryFileVaultAdapter(),
    // add indexedDB adapters for contacts, history, etc.
  }
});

// Hydrate state, keys, and contacts from storage on startup
await client.hydrate();

2. Encrypting a File

Encrypt a binary file to the .mjkb format. You can optionally sign it during encryption.

const fileData = new Uint8Array([...]);

const result = await client.encryptFile({
  data: fileData,
  originalName: "confidential_report.pdf",
  mimeType: "application/pdf",
  sign: true, // Automatically signs with the active account's keys
  recipients: ["recipient_public_key_address"]
});

// result.binary contains the encrypted .mjkb bytes
// result.metadata contains routing/decryption metadata

3. Decrypting a File

Decrypt a .mjkb binary. The client automatically cycles through your unlocked owned accounts to find the correct decryption key.

const mjkbBytes = new Uint8Array([...]);
const metadata = { /* fetched from server/storage */ };

const { bytes, originalName, mimeType, signature } = await client.decryptFile({
  source: mjkbBytes,
  metadata
});

console.log(`Decrypted ${originalName} (${mimeType})`);
if (signature) {
  console.log("File contains a signature from:", signature.signerId);
}

4. Cryptographic Signing & Verification

Sign a File:

const pdfBlob = new Blob([pdfBytes], { type: "application/pdf" });

// Creates a signed file with an embedded signature envelope
const { blob, signature } = await client.signFile(pdfBlob, {
  mimeType: "application/pdf"
});

Verify a File:

// Verifies embedded signatures against the active contact directory or self-reported keys
const verifyResult = await client.verifyFile(signedBlob);

if (verifyResult.valid) {
  console.log(`Signature is valid. Signed by: ${verifyResult.signerLabel || verifyResult.signerId}`);
}

5. Multi-sig and File Sealing

The client fully supports restricting multi-sig files and "sealing" them to prevent further signatures.

// Seal a file to finalize the signature envelope
const { blob, sealInfo } = await client.seal(multiSignedBlob);
console.log("File sealed at:", sealInfo.sealTimestamp);

// Check seal status
const isSealed = await client.isSealed(blob);

6. Managing the Local Vault (In-app Storage)

The Vault securely stores local files, keeping them encrypted at rest using the active account's identity.

// Add a file to the vault
const vaultItem = await client.addVaultFile(secretImageBytes, "secret_image.png", {
  mimeType: "image/png"
});

// Retrieve and decrypt
const decryptedBytes = await client.decryptStampContent(vaultItem.id);

Event Listening

The client extends an EventEmitter, allowing you to react to lifecycle events.

client.on("new-contact", (contact) => {
  console.log("A new contact was added:", contact.id);
});

client.on("sign", (result) => {
  console.log("Content signed successfully. Hash:", result.contentHash);
});

client.on("error", (err, context) => {
  console.error("Client Error in", context, err);
});

License

Apache-2.0 — free for personal and commercial use.

Author

Made with 💙 by @thezelijah

About the Developer

• Developer: Josef Elijah Fabian
• GitHub: https://github.com/jedlsf
• Project Repository: https://github.com/Majikah/majik-file-client

Contact

• Business Email: [email protected]
• Official Website: https://www.thezelijah.world