@majikah/majik-key 0.5.2 → 0.7.0

package/dist/core/backup/error.d.ts

@@ -0,0 +1,28 @@
+/**
+ * All errors this module throws. Typed so callers can branch on
+ * `instanceof` instead of string-matching `.message` — and so every
+ * failure is loud and specific rather than a generic Error/undefined.
+ */
+export declare class MajikKeyBackupError extends Error {
+    constructor(message: string);
+}
+/** An optional peer dependency (jszip, @majikah/majik-bytes) wasn't resolvable at runtime. */
+export declare class MissingOptionalDependencyError extends MajikKeyBackupError {
+    constructor(pkg: string, feature: string);
+}
+/** A JSON payload (bare, or decoded from a PNG/zip) failed shape validation. */
+export declare class InvalidBackupJSONError extends MajikKeyBackupError {
+    constructor(reason: string);
+}
+/** A PNG file wasn't a valid MajikByte, or its decoded payload wasn't a valid backup. */
+export declare class InvalidBackupPNGError extends MajikKeyBackupError {
+    constructor(reason: string);
+}
+/** A .zip archive contained no valid backup.png or backup.json anywhere inside it. */
+export declare class InvalidBackupZipError extends MajikKeyBackupError {
+    constructor(reason: string);
+}
+/** A zip contained both a valid PNG backup and a valid JSON backup, but they describe different accounts. */
+export declare class BackupIntegrityMismatchError extends MajikKeyBackupError {
+    constructor(details: string);
+}

package/dist/core/backup/error.js

@@ -0,0 +1,41 @@
+/**
+ * All errors this module throws. Typed so callers can branch on
+ * `instanceof` instead of string-matching `.message` — and so every
+ * failure is loud and specific rather than a generic Error/undefined.
+ */
+export class MajikKeyBackupError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+/** An optional peer dependency (jszip, @majikah/majik-bytes) wasn't resolvable at runtime. */
+export class MissingOptionalDependencyError extends MajikKeyBackupError {
+    constructor(pkg, feature) {
+        super(`"${pkg}" is required to ${feature}. Install it with \`npm install ${pkg}\`.`);
+    }
+}
+/** A JSON payload (bare, or decoded from a PNG/zip) failed shape validation. */
+export class InvalidBackupJSONError extends MajikKeyBackupError {
+    constructor(reason) {
+        super(`Invalid backup JSON: ${reason}`);
+    }
+}
+/** A PNG file wasn't a valid MajikByte, or its decoded payload wasn't a valid backup. */
+export class InvalidBackupPNGError extends MajikKeyBackupError {
+    constructor(reason) {
+        super(`Invalid backup PNG: ${reason}`);
+    }
+}
+/** A .zip archive contained no valid backup.png or backup.json anywhere inside it. */
+export class InvalidBackupZipError extends MajikKeyBackupError {
+    constructor(reason) {
+        super(`Invalid backup archive: ${reason}`);
+    }
+}
+/** A zip contained both a valid PNG backup and a valid JSON backup, but they describe different accounts. */
+export class BackupIntegrityMismatchError extends MajikKeyBackupError {
+    constructor(details) {
+        super(`Backup archive contains conflicting payloads: ${details}`);
+    }
+}

package/dist/core/backup/index.d.ts

@@ -0,0 +1,4 @@
+export { MajikKeyBackup } from "./majik-key-backup";
+export type { BackupSource, CreateBackupParams, ToZipOptions } from "./types";
+export { BACKUP_FORMAT_VERSION } from "./types";
+export { MajikKeyBackupError, MissingOptionalDependencyError, InvalidBackupJSONError, InvalidBackupPNGError, InvalidBackupZipError, BackupIntegrityMismatchError, } from "./error";

package/dist/core/backup/index.js

@@ -0,0 +1,3 @@
+export { MajikKeyBackup } from "./majik-key-backup";
+export { BACKUP_FORMAT_VERSION } from "./types";
+export { MajikKeyBackupError, MissingOptionalDependencyError, InvalidBackupJSONError, InvalidBackupPNGError, InvalidBackupZipError, BackupIntegrityMismatchError, } from "./error";

package/dist/core/backup/majik-key-backup.d.ts

@@ -0,0 +1,49 @@
+import type { MnemonicLanguage } from "../crypto/wordlist";
+import { MnemonicJSON } from "../types";
+import { CreateBackupParams, ToZipOptions } from "./types";
+/**
+ * A validated Majik Key backup payload, and the single place that knows
+ * how to read/write it as JSON, a MajikByte PNG, or a .zip archive
+ * containing both plus a README.
+ *
+ * Every construction path (create, fromJSON, fromPNG, fromZIP) funnels
+ * through the same shape validator, so there is exactly one definition
+ * of "valid backup" anywhere in the app.
+ */
+export declare class MajikKeyBackup {
+    private readonly data;
+    private constructor();
+    /** Builds a fresh backup from a newly generated seed. Pure — no I/O. */
+    static create(params: CreateBackupParams): MajikKeyBackup;
+    /** Validates and wraps an already-parsed JSON payload (e.g. a bare .json file the user dropped, no zip/PNG involved). */
+    static fromJSON(input: unknown): MajikKeyBackup;
+    /** Decodes a MajikByte PNG backup and validates the embedded payload. */
+    static fromPNG(file: File | Blob): Promise<MajikKeyBackup>;
+    /**
+     * Parses a `.zip` backup archive. Walks every file entry — JSZip
+     * already flattens nested folders into full relative paths in
+     * `archive.files`, so no manual recursion is needed even for a zip
+     * re-created one folder level deeper than expected.
+     *
+     * Classification is by magic bytes, not filename/extension, so a
+     * renamed or oddly-cased file is still found.
+     *
+     * PNG wins when both a valid PNG and a valid JSON backup are present
+     * (harder to tamper with — carries the MajikByte integrity check).
+     * Falls back to JSON only if no valid PNG is found anywhere in the
+     * archive. If both are present but describe different accounts,
+     * that's a real integrity problem and is surfaced as one, not
+     * silently resolved by picking a winner.
+     */
+    static fromZIP(file: File | Blob | Uint8Array): Promise<MajikKeyBackup>;
+    toJSON(): MnemonicJSON;
+    get id(): string;
+    get seed(): string[];
+    get seedPhrase(): string;
+    get language(): MnemonicLanguage | undefined;
+    get formatVersion(): number | undefined;
+    toPNG(): Promise<Blob>;
+    toZIP(_opts?: ToZipOptions): Promise<Blob>;
+    /** Convenience for callers building a native `save()` dialog default path. */
+    suggestedFileName(label?: string): string;
+}

package/dist/core/backup/majik-key-backup.js

@@ -0,0 +1,193 @@
+import { validateMnemonicJSONShape } from "./validator";
+import { InvalidBackupPNGError, InvalidBackupZipError, BackupIntegrityMismatchError, } from "./error";
+import { getJSZip, getMajikBytes, looksLikePNG, toSafeFileName, buildReadmeText, } from "./utils";
+import { BACKUP_FORMAT_VERSION, } from "./types";
+import { base64ToUtf8, utf8ToBase64 } from "../utils";
+const BACKUP_JSON_FILENAME = "backup.json";
+const BACKUP_PNG_FILENAME = "backup.png";
+const README_FILENAME = "IMPORTANT README.txt";
+/**
+ * A validated Majik Key backup payload, and the single place that knows
+ * how to read/write it as JSON, a MajikByte PNG, or a .zip archive
+ * containing both plus a README.
+ *
+ * Every construction path (create, fromJSON, fromPNG, fromZIP) funnels
+ * through the same shape validator, so there is exactly one definition
+ * of "valid backup" anywhere in the app.
+ */
+export class MajikKeyBackup {
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+    // ────────────────────────────────────────────────────────────────
+    // Static constructors
+    // ────────────────────────────────────────────────────────────────
+    /** Builds a fresh backup from a newly generated seed. Pure — no I/O. */
+    static create(params) {
+        const seedArray = Array.isArray(params.seed)
+            ? params.seed
+            : params.seed.trim().split(/\s+/);
+        const json = {
+            id: params.id,
+            seed: seedArray,
+            language: params.language,
+            phrase: params.phrase,
+            version: BACKUP_FORMAT_VERSION,
+        };
+        validateMnemonicJSONShape(json);
+        return new MajikKeyBackup(json);
+    }
+    /** Validates and wraps an already-parsed JSON payload (e.g. a bare .json file the user dropped, no zip/PNG involved). */
+    static fromJSON(input) {
+        validateMnemonicJSONShape(input);
+        return new MajikKeyBackup(input);
+    }
+    /** Decodes a MajikByte PNG backup and validates the embedded payload. */
+    static async fromPNG(file) {
+        const { MajikBytes } = await getMajikBytes();
+        const check = await MajikBytes.isValidPNG(file);
+        if (!check?.isValid) {
+            throw new InvalidBackupPNGError("not a recognized MajikByte PNG");
+        }
+        let decoded;
+        try {
+            const mbyte = await MajikBytes.fromPNG(file);
+            const base64 = mbyte.toStringValue();
+            decoded = JSON.parse(base64ToUtf8(base64));
+        }
+        catch (err) {
+            throw new InvalidBackupPNGError(`could not decode embedded payload (${err?.message ?? err})`);
+        }
+        validateMnemonicJSONShape(decoded);
+        return new MajikKeyBackup(decoded);
+    }
+    /**
+     * Parses a `.zip` backup archive. Walks every file entry — JSZip
+     * already flattens nested folders into full relative paths in
+     * `archive.files`, so no manual recursion is needed even for a zip
+     * re-created one folder level deeper than expected.
+     *
+     * Classification is by magic bytes, not filename/extension, so a
+     * renamed or oddly-cased file is still found.
+     *
+     * PNG wins when both a valid PNG and a valid JSON backup are present
+     * (harder to tamper with — carries the MajikByte integrity check).
+     * Falls back to JSON only if no valid PNG is found anywhere in the
+     * archive. If both are present but describe different accounts,
+     * that's a real integrity problem and is surfaced as one, not
+     * silently resolved by picking a winner.
+     */
+    static async fromZIP(file) {
+        const JSZip = await getJSZip();
+        let archive;
+        try {
+            archive = await JSZip.loadAsync(file);
+        }
+        catch (err) {
+            throw new InvalidBackupZipError(`could not open archive (${err?.message ?? err})`);
+        }
+        let pngResult = null;
+        let pngError = null;
+        let jsonResult = null;
+        for (const relativePath of Object.keys(archive.files)) {
+            const entry = archive.files[relativePath];
+            if (entry.dir)
+                continue;
+            const bytes = await entry.async("uint8array");
+            if (!pngResult && looksLikePNG(bytes)) {
+                try {
+                    const blob = new Blob([bytes], { type: "image/png" });
+                    pngResult = await MajikKeyBackup.fromPNG(blob);
+                }
+                catch (err) {
+                    // Keep the first PNG-shaped-but-invalid error for the final
+                    // message, but keep scanning — a later entry might still be
+                    // a valid JSON backup.
+                    pngError = pngError ?? err;
+                }
+                continue;
+            }
+            if (!jsonResult) {
+                try {
+                    const text = new TextDecoder("utf-8").decode(bytes);
+                    const parsed = JSON.parse(text);
+                    jsonResult = MajikKeyBackup.fromJSON(parsed);
+                }
+                catch {
+                    // Not every non-PNG entry is the backup JSON (e.g. the
+                    // README) — skip silently, we only error if *nothing* valid
+                    // turns up anywhere in the archive.
+                }
+            }
+        }
+        if (pngResult && jsonResult) {
+            const idsMatch = pngResult.data.id === jsonResult.data.id;
+            const seedsMatch = pngResult.data.seed.join(" ") === jsonResult.data.seed.join(" ");
+            if (!idsMatch || !seedsMatch) {
+                throw new BackupIntegrityMismatchError("the PNG and JSON backups inside this archive do not describe the same account");
+            }
+        }
+        if (pngResult)
+            return pngResult;
+        if (jsonResult)
+            return jsonResult;
+        const reason = pngError
+            ? `a PNG-shaped file was found but is invalid (${pngError?.message ?? pngError})`
+            : "no valid backup.png or backup.json found inside the archive";
+        throw new InvalidBackupZipError(reason);
+    }
+    // ────────────────────────────────────────────────────────────────
+    // Instance accessors
+    // ────────────────────────────────────────────────────────────────
+    toJSON() {
+        return { ...this.data };
+    }
+    get id() {
+        return this.data.id;
+    }
+    get seed() {
+        return [...this.data.seed];
+    }
+    get seedPhrase() {
+        return this.data.seed.join(" ");
+    }
+    get language() {
+        return this.data.language;
+    }
+    get formatVersion() {
+        return this.data.version;
+    }
+    // ────────────────────────────────────────────────────────────────
+    // Instance serializers
+    // ────────────────────────────────────────────────────────────────
+    async toPNG() {
+        const { MajikBytes } = await getMajikBytes();
+        const base64 = utf8ToBase64(JSON.stringify(this.toJSON()));
+        const mbyte = await MajikBytes.create(base64);
+        return mbyte.toPNG();
+    }
+    async toZIP(_opts = {}) {
+        const JSZip = await getJSZip();
+        const json = this.toJSON();
+        const pngBlob = await this.toPNG();
+        const pngBuffer = await pngBlob.arrayBuffer();
+        const zip = new JSZip();
+        zip.file(BACKUP_JSON_FILENAME, JSON.stringify(json));
+        zip.file(BACKUP_PNG_FILENAME, pngBuffer, { binary: true });
+        zip.file(README_FILENAME, buildReadmeText(new Date()));
+        return zip.generateAsync({
+            type: "blob",
+            compression: "DEFLATE",
+            compressionOptions: { level: 9 },
+        });
+    }
+    /** Convenience for callers building a native `save()` dialog default path. */
+    suggestedFileName(label) {
+        return toSafeFileName(`${label ?? "Majik Key"} - ${this.data.id} - SEED KEY - ${new Date().toISOString()}`);
+    }
+}
+// Freeze static methods (e.g., MajikKey.create, MajikKey.fromJSON)
+Object.freeze(MajikKeyBackup);
+// Freeze instance methods (e.g., this.lock, this.unlock)
+Object.freeze(MajikKeyBackup.prototype);

package/dist/core/backup/types.d.ts

@@ -0,0 +1,22 @@
+import type { MnemonicLanguage } from "../crypto/wordlist";
+/**
+ * Bump this whenever the *shape* of MnemonicJSON or the zip layout
+ * changes in a way that could break parsing of older backups. Written
+ * into every backup created by `MajikKeyBackup.create()`; read back
+ * (but not currently enforced) by `fromJSON`/`fromPNG`/`fromZIP`, so
+ * future versions can branch on it if the shape ever diverges.
+ */
+export declare const BACKUP_FORMAT_VERSION = 1;
+/** Which artifact inside a parsed backup archive supplied the winning payload. */
+export type BackupSource = "png" | "json";
+export interface CreateBackupParams {
+    /** Either the full mnemonic string ("word1 word2 ...") or a pre-split word array. */
+    seed: string | string[];
+    id: string;
+    language: MnemonicLanguage;
+    phrase?: string;
+}
+export interface ToZipOptions {
+    /** Used only to build the human-facing filename hint (suggestedFileName); purely cosmetic. */
+    label?: string;
+}

package/dist/core/backup/types.js

@@ -0,0 +1,8 @@
+/**
+ * Bump this whenever the *shape* of MnemonicJSON or the zip layout
+ * changes in a way that could break parsing of older backups. Written
+ * into every backup created by `MajikKeyBackup.create()`; read back
+ * (but not currently enforced) by `fromJSON`/`fromPNG`/`fromZIP`, so
+ * future versions can branch on it if the shape ever diverges.
+ */
+export const BACKUP_FORMAT_VERSION = 1;

package/dist/core/backup/utils.d.ts

@@ -0,0 +1,14 @@
+export declare function getJSZip(): Promise<any>;
+export declare function getMajikBytes(): Promise<any>;
+export declare function looksLikePNG(bytes: Uint8Array): boolean;
+/** Zip local-file-header signature ("PK\x03\x04"), also covers empty-archive/spanned variants starting "PK". */
+export declare function looksLikeZip(bytes: Uint8Array): boolean;
+export declare function toSafeFileName(value: string): string;
+/**
+ * Static body of the backup README. Update this whenever the copy
+ * needs to change — every zip generated by toZIP() picks it up
+ * automatically, nothing else needs to change.
+ */
+export declare const README_TEXT = "Majik Key Backup\n\nIMPORTANT: Keep this file secure and private at all times. If lost or compromised, your account access may be permanently at risk.\n\nOverview\nThis backup ZIP file contains your raw JSON data and a Backup PNG. These files are essential for recovering your account.\n\nUsage Instructions\n- Storage: You may delete the JSON file and keep only the PNG file if preferred.\n- Customization: You can rename the PNG file for added discretion.\n- Recovery: This PNG allows you to securely re-import your account without exposing raw JSON data.\n\nCritical Handling Requirements\nTo prevent data corruption and ensure the backup remains functional, please follow these rules:\n\n- No Modifications: Do not edit, crop, or apply filters to the PNG image.\n- No Processing: Avoid running the image through compression tools or \"optimization\" software.\n- Storage Only: Store the image as is. Do not upload it to social media, messaging apps, or cloud platforms that automatically compress or manipulate images, as this will destroy the embedded data.\n\nIMPORTANT: Keep this file secure and private at all times. If lost or compromised, your account access may be permanently at risk.";
+/** README_TEXT plus a creation timestamp line — the only per-backup variable part. */
+export declare function buildReadmeText(createdAt?: Date): string;

package/dist/core/backup/utils.js

@@ -0,0 +1,92 @@
+import { MissingOptionalDependencyError } from "./error";
+// ────────────────────────────────────────────────────────────────
+// Lazy-loaded optional dependencies
+// ────────────────────────────────────────────────────────────────
+// jszip is only needed by toZIP()/fromZIP() — every other method on
+// MajikKeyBackup (create, fromJSON, fromPNG, toJSON) never touches it,
+// so no consumer pays for it unless they actually use the zip feature.
+// Note: in bundled contexts (Vite/webpack/etc.) `import("jszip")` still
+// needs jszip resolvable at build time — this buys code-splitting
+// (its own lazy-fetched chunk), not "works with zero jszip installed".
+// In plain-Node consumers (CLI, MCP server) it genuinely defers
+// resolution to runtime, and throws the typed error below if absent.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _jszip = null;
+export async function getJSZip() {
+    if (_jszip)
+        return _jszip;
+    try {
+        const mod = await import("jszip");
+        _jszip = mod.default ?? mod;
+    }
+    catch {
+        throw new MissingOptionalDependencyError("jszip", "read or write .zip backups");
+    }
+    return _jszip;
+}
+// @majikah/majik-bytes is a hard dependency of this library (Josef
+// controls it), so this loader exists purely to keep the import
+// pattern consistent with getJSZip() — not for optionality.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _majikBytes = null;
+export async function getMajikBytes() {
+    if (_majikBytes)
+        return _majikBytes;
+    _majikBytes = await import("@majikah/majik-bytes");
+    return _majikBytes;
+}
+// ────────────────────────────────────────────────────────────────
+// Binary sniffing — classify by magic bytes, never by file extension
+// ────────────────────────────────────────────────────────────────
+const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+export function looksLikePNG(bytes) {
+    if (bytes.length < PNG_MAGIC.length)
+        return false;
+    return PNG_MAGIC.every((byte, i) => bytes[i] === byte);
+}
+/** Zip local-file-header signature ("PK\x03\x04"), also covers empty-archive/spanned variants starting "PK". */
+export function looksLikeZip(bytes) {
+    return bytes.length > 2 && bytes[0] === 0x50 && bytes[1] === 0x4b;
+}
+// ────────────────────────────────────────────────────────────────
+// Encoding helpers
+// ────────────────────────────────────────────────────────────────
+export function toSafeFileName(value) {
+    return value
+        .replace(/[<>:"/\\|?*\x00-\x1F]/g, "-")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/[. ]+$/, "");
+}
+// ────────────────────────────────────────────────────────────────
+// README — centralized so copy updates happen in exactly one place
+// ────────────────────────────────────────────────────────────────
+/**
+ * Static body of the backup README. Update this whenever the copy
+ * needs to change — every zip generated by toZIP() picks it up
+ * automatically, nothing else needs to change.
+ */
+export const README_TEXT = `Majik Key Backup
+
+IMPORTANT: Keep this file secure and private at all times. If lost or compromised, your account access may be permanently at risk.
+
+Overview
+This backup ZIP file contains your raw JSON data and a Backup PNG. These files are essential for recovering your account.
+
+Usage Instructions
+- Storage: You may delete the JSON file and keep only the PNG file if preferred.
+- Customization: You can rename the PNG file for added discretion.
+- Recovery: This PNG allows you to securely re-import your account without exposing raw JSON data.
+
+Critical Handling Requirements
+To prevent data corruption and ensure the backup remains functional, please follow these rules:
+
+- No Modifications: Do not edit, crop, or apply filters to the PNG image.
+- No Processing: Avoid running the image through compression tools or "optimization" software.
+- Storage Only: Store the image as is. Do not upload it to social media, messaging apps, or cloud platforms that automatically compress or manipulate images, as this will destroy the embedded data.
+
+IMPORTANT: Keep this file secure and private at all times. If lost or compromised, your account access may be permanently at risk.`;
+/** README_TEXT plus a creation timestamp line — the only per-backup variable part. */
+export function buildReadmeText(createdAt = new Date()) {
+    return `${README_TEXT}\n\nBackup created on: ${createdAt.toLocaleString()}\n`;
+}

package/dist/core/backup/validator.d.ts

@@ -0,0 +1,11 @@
+import { MnemonicJSON } from "../types";
+/**
+ * Single source of truth for "is this a structurally valid
+ * MnemonicJSON". Called by `create`, `fromJSON`, `fromPNG` (post-decode),
+ * and `fromZIP` — never reimplemented at any entry point (DRY validation:
+ * one validator, many callers).
+ *
+ * Throws InvalidBackupJSONError with a specific reason on failure;
+ * narrows `input` to MnemonicJSON on success.
+ */
+export declare function validateMnemonicJSONShape(input: unknown): asserts input is MnemonicJSON;

package/dist/core/backup/validator.js

@@ -0,0 +1,36 @@
+import { InvalidBackupJSONError } from "./error";
+/**
+ * Single source of truth for "is this a structurally valid
+ * MnemonicJSON". Called by `create`, `fromJSON`, `fromPNG` (post-decode),
+ * and `fromZIP` — never reimplemented at any entry point (DRY validation:
+ * one validator, many callers).
+ *
+ * Throws InvalidBackupJSONError with a specific reason on failure;
+ * narrows `input` to MnemonicJSON on success.
+ */
+export function validateMnemonicJSONShape(input) {
+    if (typeof input !== "object" || input === null) {
+        throw new InvalidBackupJSONError("payload is not an object");
+    }
+    const candidate = input;
+    if (typeof candidate.id !== "string" || !candidate.id.trim()) {
+        throw new InvalidBackupJSONError("missing or empty `id`");
+    }
+    if (!Array.isArray(candidate.seed) || candidate.seed.length === 0) {
+        throw new InvalidBackupJSONError("missing or empty `seed`");
+    }
+    if (!candidate.seed.every((word) => typeof word === "string" && word.trim().length > 0)) {
+        throw new InvalidBackupJSONError("`seed` must be an array of non-empty words");
+    }
+    if (candidate.phrase !== undefined && typeof candidate.phrase !== "string") {
+        throw new InvalidBackupJSONError("`phrase` must be a string when present");
+    }
+    if (candidate.language !== undefined &&
+        typeof candidate.language !== "string") {
+        throw new InvalidBackupJSONError("`language` must be a string when present");
+    }
+    if (candidate.version !== undefined &&
+        typeof candidate.version !== "number") {
+        throw new InvalidBackupJSONError("`version` must be a number when present");
+    }
+}

package/dist/core/crypto/crypto-provider.js

@@ -108,7 +108,7 @@ async function _argon2id(input, salt, params) {
     if (_wasmAvailable === null) {
         _wasmAvailable = await _probeWasm();
         if (!_wasmAvailable) {
-            console.warn("[majikah/crypto] hash-wasm unavailable, using @noble/hashes argon2id fallback");
+            console.warn("[@majikah/majik-key/crypto] hash-wasm unavailable, using @noble/hashes argon2id fallback");
         }
     }
     if (_wasmAvailable) {
@@ -119,7 +119,7 @@ async function _argon2id(input, salt, params) {
             // WASM loaded but failed at runtime (e.g. OOM, corrupted module)
             // Flip flag so we stop trying for the rest of this session
             _wasmAvailable = false;
-            console.warn("[majikah/majik-key/crypto] hash-wasm runtime failure, falling back to @noble/hashes", err);
+            console.warn("[@majikah/majik-key/crypto] hash-wasm runtime failure, falling back to @noble/hashes", err);
         }
     }
     return _argon2idNoble(input, salt, params);

package/dist/core/types.d.ts

@@ -141,4 +141,6 @@ export interface MnemonicJSON {
     /** Optional passphrase, carried in plaintext for convenience during export/import. ⚠️ Not encrypted. */
     phrase?: string;
     language?: MnemonicLanguage;
+    /** Backup format version this payload was written with. See BACKUP_FORMAT_VERSION. */
+    version?: number;
 }

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export type * from "./core/types";
 export * from "./core/error";
 export * from "./core/validator";
 export * from "./core/web3";
+export * from "./core/backup";

package/dist/index.js

@@ -2,3 +2,4 @@ export * from "./majik-key";
 export * from "./core/error";
 export * from "./core/validator";
 export * from "./core/web3";
+export * from "./core/backup";

package/dist/majik-key.d.ts

@@ -3,7 +3,7 @@
  * Seed phrase account library for the Majikah ecosystem.
  *
  */
-import { MajikContact, MajikContactMeta } from "@majikah/majik-contact";
+import { MajikContact, MajikContactData, MajikContactMeta } from "@majikah/majik-contact";
 import { KDF_VERSION } from "./core/crypto/constants";
 import type { BitcoinRawPublicKey, ED25519RawPublicKey, MajikKeyAddress, MajikKeyDangerousJSON, MajikKeyFingerprint, MajikKeyJSON, MajikKeyMetadata, MLDSA87RawPublicKey, MLKEM768RawPublicKey, MnemonicJSON, X25519RawKey } from "./core/types";
 import { MajikMessageIdentity } from "./core/database/system/identity";
@@ -361,6 +361,8 @@ export declare class MajikKey {
      * You can pass a custom metadata type if needed, e.g., toContact<MyMeta>()
      */
     toContact<TMeta extends MajikContactMeta = MajikContactMeta>(initialMeta?: Partial<TMeta>): MajikContact<TMeta>;
+    /** Build any MajikContact subclass by passing its constructor. */
+    toContact<TMeta extends MajikContactMeta, TContact extends MajikContact<TMeta>>(ContactClass: new (data: MajikContactData<TMeta>) => TContact, initialMeta?: Partial<TMeta>): TContact;
     toKeyIdentity(): MajikKeyIdentity;
     toSerializedIdentity(): SerializedIdentity;
     toMajikMessageIdentity(user: MajikUser, options?: {

package/dist/majik-key.js

@@ -6,7 +6,7 @@
 import { generateMnemonic as bip39GenerateMnemonic, mnemonicToSeed, validateMnemonic, } from "@scure/bip39";
 import { aesGcmDecrypt, aesGcmEncrypt, deriveKeyFromPassphraseArgon2, deriveKeyFromMnemonicArgon2, deriveKeyFromPassphrase, generateRandomBytes, IV_LENGTH, } from "./core/crypto/crypto-provider";
 import { EncryptionEngine } from "./core/crypto/encryption-engine";
-import { MajikContact } from "@majikah/majik-contact";
+import { MajikContact, } from "@majikah/majik-contact";
 import { arrayBufferToBase64, arrayToBase64, base64ToArrayBuffer, concatUint8Arrays, utf8ToBase64, base64ToUtf8, seedStringToArray, seedArrayToString, base64ToUint8Array, } from "./core/utils";
 import { KDF_VERSION, MAJIK_MNEMONIC_SALT } from "./core/crypto/constants";
 import { MajikKeyValidator } from "./core/validator";
@@ -801,23 +801,15 @@ export class MajikKey {
             return false;
         }
     }
-    /**
-     * Converts the MajikKey to a MajikContact.
-     * You can pass a custom metadata type if needed, e.g., toContact<MyMeta>()
-     */
-    toContact(initialMeta) {
-        const mlKeyBase64 = arrayToBase64(this.mlKemPublicKey);
-        // We construct the base metadata and merge with any provided initialMeta
-        const meta = {
-            label: this._label,
-            ...initialMeta,
-        };
-        return new MajikContact({
+    toContact(arg1, arg2) {
+        const ContactClass = (typeof arg1 === "function" ? arg1 : MajikContact);
+        const initialMeta = (typeof arg1 === "function" ? arg2 : arg1);
+        return new ContactClass({
             id: this._id,
             publicKey: this._publicKey,
             fingerprint: this._fingerprint,
-            meta: meta,
-            mlKey: mlKeyBase64,
+            meta: { label: this._label, ...initialMeta },
+            mlKey: arrayToBase64(this.mlKemPublicKey),
             edPublicKeyBase64: this._edPublicKey
                 ? arrayToBase64(this._edPublicKey)
                 : undefined,

package/package.json

@@ -2,7 +2,7 @@
   "name": "@majikah/majik-key",
   "type": "module",
   "description": "A post-quantum ready seed phrase account library for the Majikah ecosystem. Manages deterministic X25519 and ML-KEM-768 identities with Argon2id protection and seamless legacy account migration.",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",
@@ -48,14 +48,15 @@
     "package": "npm run build && npm version patch && git push && git push --tags",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:compat": "npx vitest test/majik-key-cross-compat.test.ts",
-    "test:web3:bitcoin": "npx vitest test/majik-key-bitcoin.test.ts",
-    "test:web3:solana": "npx vitest test/majik-key-solana.test.ts",
-    "test:web3": "npx vitest test/majik-key-bitcoin.test.ts test/majik-key-solana.test.ts",
-    "test:core": "npx vitest test/majik-key.test.ts"
+    "test:compat": "vitest run test/majik-key-cross-compat.test.ts",
+    "test:web3:bitcoin": "vitest run test/majik-key-bitcoin.test.ts",
+    "test:web3:solana": "vitest run test/majik-key-solana.test.ts",
+    "test:web3": "vitest run test/majik-key-bitcoin.test.ts test/majik-key-solana.test.ts",
+    "test:core": "vitest run test/majik-key.test.ts",
+    "test:backup": "vitest run test/backup/majik-key-backup.test.ts"
   },
   "dependencies": {
-    "@majikah/majik-contact": "^0.0.6",
+    "@majikah/majik-contact": "^0.1.1",
     "@noble/curves": "^2.4.0",
     "@noble/hashes": "^2.4.0",
     "@noble/post-quantum": "^0.7.1",
@@ -72,16 +73,20 @@
     "hash-wasm": "^4.12.0"
   },
   "devDependencies": {
+    "@majikah/majik-bytes": "^1.0.0",
     "@scure/btc-signer": "^2.4.1",
     "@solana/kit": "^8.3.0",
     "@types/ed2curve": "^0.2.4",
     "@types/node": "^26.6.2",
+    "jszip": "^3.10.2",
     "typescript": "^7.0.2",
     "vitest": "^5.0.1"
   },
   "peerDependencies": {
-    "@scure/btc-signer": "^2.4.1",
-    "@solana/kit": "^8.3.0"
+    "@majikah/majik-bytes": ">=1.0.0",
+    "@scure/btc-signer": ">=2.4.1",
+    "@solana/kit": ">=8.3.0",
+    "jszip": ">=3.10.2"
   },
   "peerDependenciesMeta": {
     "@solana/kit": {
@@ -89,6 +94,12 @@
     },
     "@scure/btc-signer": {
       "optional": true
+    },
+    "jszip": {
+      "optional": true
+    },
+    "@majikah/majik-bytes": {
+      "optional": true
     }
   }
 }