@thezelijah/majik-message 1.0.0

package/dist/majik-message.js

@@ -0,0 +1,940 @@
+// MajikMessage.ts
+import { MajikContact, } from "./core/contacts/majik-contact";
+import { KEY_ALGO } from "./core/crypto/constants";
+import { ScannerEngine } from "./core/scanner/scanner-engine";
+import { MessageEnvelope } from "./core/messages/message-envelope";
+import { EnvelopeCache, } from "./core/messages/envelope-cache";
+import { EncryptionEngine } from "./core/crypto/encryption-engine";
+import { KeyStore } from "./core/crypto/keystore";
+import { MajikContactDirectory, } from "./core/contacts/majik-contact-directory";
+import { arrayBufferToBase64, arrayToBase64, base64ToArrayBuffer, base64ToUtf8, utf8ToBase64, } from "./core/utils/utilities";
+import { autoSaveMajikFileData, loadSavedMajikFileData, } from "./core/utils/majik-file-utils";
+import { randomBytes } from "@stablelib/random";
+import { idbLoadBlob, idbSaveBlob } from "./core/utils/idb-majik-system";
+export class MajikMessage {
+    // Optional PIN protection (hashed). If set, UI should prompt for PIN to unlock.
+    pinHash = null;
+    id;
+    contactDirectory;
+    envelopeCache;
+    scanner;
+    listeners = new Map();
+    ownAccounts = new Map();
+    ownAccountsOrder = []; // keeps the order of IDs, first is active
+    autosaveTimer = null;
+    autosaveIntervalMs = 15000; // periodic backup interval
+    autosaveDebounceMs = 500; // debounce for rapid changes
+    constructor(config, id) {
+        this.id = id || arrayToBase64(randomBytes(32));
+        this.contactDirectory =
+            config.contactDirectory || new MajikContactDirectory();
+        this.envelopeCache = config.envelopeCache || new EnvelopeCache();
+        // Initialize scanner
+        this.scanner = new ScannerEngine({
+            contactDirectory: this.contactDirectory,
+            onEnvelopeFound: (env) => this.handleEnvelope(env),
+            onUntrusted: (raw) => this.emit("untrusted", raw),
+            onError: (err, ctx) => this.emit("error", err, ctx),
+        });
+        // Prepare listeners map
+        ["message", "envelope", "untrusted", "error"].forEach((e) => this.listeners.set(e, []));
+        // Attach autosave handlers so state is persisted automatically
+        this.attachAutosaveHandlers();
+    }
+    /* ================================
+     * Account Management
+     * ================================ */
+    /**
+     * Create a new account (generates identity via KeyStore) and add it as an own account.
+     * Returns the created identity id and a backup blob (base64) that the user should store.
+     */
+    async createAccount(passphrase, label) {
+        const identity = await KeyStore.createIdentity(passphrase);
+        // Import public key into a MajikContact
+        const contact = new MajikContact({
+            id: identity.id,
+            publicKey: identity.publicKey,
+            fingerprint: identity.fingerprint,
+            meta: { label: label || "" },
+        });
+        this.addOwnAccount(contact);
+        const backup = await KeyStore.exportIdentityBackup(identity.id);
+        return { id: identity.id, fingerprint: identity.fingerprint, backup };
+    }
+    /**
+     * Import an account from a backup blob (created with `exportIdentityBackup`) and unlock it.
+     */
+    async importAccountFromBackup(backupBase64, passphrase, label) {
+        await KeyStore.importIdentityBackup(backupBase64);
+        // Unlock the imported identity
+        const decoded = JSON.parse(base64ToUtf8(backupBase64));
+        const id = decoded.id;
+        const identity = await KeyStore.unlockIdentity(id, passphrase);
+        const contact = new MajikContact({
+            id: identity.id,
+            publicKey: identity.publicKey,
+            fingerprint: identity.fingerprint,
+            meta: { label: label || "" },
+        });
+        if (!!this.getOwnAccountById(identity.id)) {
+            throw new Error("Account with the same ID already exists");
+        }
+        this.addOwnAccount(contact);
+        return { id: identity.id, fingerprint: identity.fingerprint };
+    }
+    /**
+     * Generate a BIP39 mnemonic for backup (12 words by default).
+     */
+    generateMnemonic() {
+        return KeyStore.generateMnemonic();
+    }
+    /**
+     * Export a mnemonic-encrypted backup for an unlocked identity.
+     */
+    async exportAccountMnemonicBackup(id, mnemonic) {
+        return KeyStore.exportIdentityMnemonicBackup(id, mnemonic);
+    }
+    /**
+     * Import an account from a mnemonic-encrypted backup blob and store it using `passphrase`.
+     */
+    async importAccountFromMnemonicBackup(backupBase64, mnemonic, passphrase, label) {
+        const identity = await KeyStore.importIdentityFromMnemonicBackup(backupBase64, mnemonic, passphrase);
+        const contact = new MajikContact({
+            id: identity.id,
+            publicKey: identity.publicKey,
+            fingerprint: identity.fingerprint,
+            meta: { label: label || "" },
+        });
+        if (!!this.getOwnAccountById(identity.id)) {
+            throw new Error("Account with the same ID already exists");
+        }
+        this.addOwnAccount(contact);
+        return { id: identity.id, fingerprint: identity.fingerprint };
+    }
+    /**
+     * Create a new account deterministically from `mnemonic` and store it encrypted with `passphrase`.
+     * Returns the created identity id (which equals fingerprint) and fingerprint.
+     */
+    async createAccountFromMnemonic(mnemonic, passphrase, label) {
+        const identity = await KeyStore.createIdentityFromMnemonic(mnemonic, passphrase);
+        const contact = new MajikContact({
+            id: identity.id,
+            publicKey: identity.publicKey,
+            fingerprint: identity.fingerprint,
+            meta: { label: label || "" },
+        });
+        const backup = await KeyStore.exportIdentityMnemonicBackup(identity.id, mnemonic);
+        this.addOwnAccount(contact);
+        return {
+            id: identity.id,
+            fingerprint: identity.fingerprint,
+            backup: backup,
+        };
+    }
+    addOwnAccount(account) {
+        if (!this.ownAccounts.has(account.id)) {
+            this.ownAccounts.set(account.id, account);
+            this.ownAccountsOrder.push(account.id);
+        }
+        try {
+            if (!this.contactDirectory.hasContact(account.id)) {
+                this.contactDirectory.addContact(account);
+            }
+        }
+        catch (e) {
+            // ignore if contact can't be added
+        }
+        this.scheduleAutosave();
+    }
+    listOwnAccounts() {
+        const userAccounts = this.ownAccountsOrder
+            .map((id) => this.ownAccounts.get(id))
+            .filter((c) => !!c);
+        return userAccounts;
+    }
+    getOwnAccountById(id) {
+        return this.ownAccounts.get(id);
+    }
+    /**
+     * Set an active account (moves it to index 0)
+     */
+    setActiveAccount(id) {
+        if (!this.ownAccounts.has(id))
+            return false;
+        // Remove ID from current position
+        const index = this.ownAccountsOrder.indexOf(id);
+        if (index > -1)
+            this.ownAccountsOrder.splice(index, 1);
+        // Add to the front
+        this.ownAccountsOrder.unshift(id);
+        this.scheduleAutosave();
+        return true;
+    }
+    getActiveAccount() {
+        if (this.ownAccountsOrder.length === 0)
+            return null;
+        return this.ownAccounts.get(this.ownAccountsOrder[0]) || null;
+    }
+    isAccountActive(id) {
+        if (!this.ownAccounts.has(id))
+            return false;
+        if (this.ownAccountsOrder.length === 0)
+            return false;
+        return this.ownAccountsOrder[0] === id;
+    }
+    /**
+     * Remove an own account from the in-memory registry.
+     */
+    removeOwnAccount(id) {
+        if (!this.ownAccounts.has(id))
+            return false;
+        this.ownAccounts.delete(id);
+        const idx = this.ownAccountsOrder.indexOf(id);
+        if (idx > -1)
+            this.ownAccountsOrder.splice(idx, 1);
+        this.removeContact(id);
+        // remove cached envelopes addressed to this identity
+        this.envelopeCache.deleteByFingerprint(id).catch((error) => {
+            console.warn("Account not found in cache: ", error);
+        });
+        this.scheduleAutosave();
+        return true;
+    }
+    /**
+     * Retrieve a contact from the directory by ID.
+     * Validates that the input is a non-empty string.
+     * Returns the MajikContact instance or null if not found.
+     */
+    getContactByID(id) {
+        if (typeof id !== "string" || !id.trim()) {
+            throw new Error("Invalid contact ID: must be a non-empty string");
+        }
+        if (!this.contactDirectory.hasContact(id)) {
+            return null; // Not found
+        }
+        return this.contactDirectory.getContact(id) ?? null;
+    }
+    /**
+     * Returns a JSON string representation of a contact
+     * suitable for sharing.
+     */
+    async exportContactAsJSON(contactId) {
+        const contact = this.contactDirectory.getContact(contactId);
+        if (!contact)
+            return null;
+        // Support raw-key wrappers produced by the Stablelib provider
+        let publicKeyBase64;
+        const anyPub = contact.publicKey;
+        if (anyPub && anyPub.raw instanceof Uint8Array) {
+            publicKeyBase64 = arrayBufferToBase64(anyPub.raw.buffer);
+        }
+        else {
+            const raw = await crypto.subtle.exportKey("raw", contact.publicKey);
+            publicKeyBase64 = arrayBufferToBase64(raw);
+        }
+        const payload = {
+            id: contact.id,
+            label: contact.meta?.label || "",
+            publicKey: publicKeyBase64,
+            fingerprint: contact.fingerprint,
+        };
+        return JSON.stringify(payload, null, 2); // pretty-print for easier copy-paste
+    }
+    /**
+     * Returns a compact base64 string for sharing a contact.
+     * Encodes JSON payload into base64.
+     */
+    async exportContactAsString(contactId) {
+        const json = await this.exportContactAsJSON(contactId);
+        if (!json)
+            return null;
+        return utf8ToBase64(json);
+    }
+    /* ================================
+     * Contact Management
+     * ================================ */
+    async importContactFromJSON(jsonStr) {
+        try {
+            const data = JSON.parse(jsonStr);
+            if (!data.id || !data.publicKey || !data.fingerprint)
+                return {
+                    success: false,
+                    message: "Invalid contact JSON",
+                };
+            // If publicKey is a base64 string, import it
+            let publicKeyPromise;
+            if (typeof data.publicKey === "string") {
+                try {
+                    const rawBuffer = base64ToArrayBuffer(data.publicKey);
+                    try {
+                        publicKeyPromise = await crypto.subtle.importKey("raw", rawBuffer, KEY_ALGO, true, []);
+                    }
+                    catch (e) {
+                        // Fallback: create a raw-key wrapper when the browser does not support the namedCurve
+                        publicKeyPromise = { raw: new Uint8Array(rawBuffer) };
+                    }
+                }
+                catch (e) {
+                    console.error("Failed to parse publicKey base64", e);
+                    return {
+                        success: false,
+                        message: "Failed to parse publicKey base64",
+                    };
+                }
+            }
+            else {
+                // assume already a CryptoKey
+                publicKeyPromise = await Promise.resolve(data.publicKey);
+            }
+            const contact = new MajikContact({
+                id: data.id,
+                publicKey: publicKeyPromise,
+                fingerprint: data.fingerprint,
+                meta: { label: data.label },
+            });
+            this.addContact(contact);
+            return {
+                success: true,
+                message: "Contact imported successfully",
+            };
+        }
+        catch (err) {
+            console.error("Failed to import contact from JSON:", err);
+            return {
+                success: false,
+                message: err instanceof Error ? err.message : "Unknown error",
+            };
+        }
+    }
+    /**
+     * List cached envelopes stored in the local cache (most recent first).
+     * Returns objects: { id, envelope, timestamp, source }
+     */
+    async listCachedEnvelopes(offset = 0, limit = 50) {
+        return await this.envelopeCache.listRecent(offset, limit);
+    }
+    /**
+     * Clear cached envelopes stored in the local cache.
+     */
+    async clearCachedEnvelopes() {
+        const response = await this.envelopeCache.clear();
+        if (!response?.success) {
+            throw new Error(response.message);
+        }
+        this.scheduleAutosave();
+        return response.success;
+    }
+    async hasOwnIdentity(fingerprint) {
+        return await KeyStore.hasIdentity(fingerprint);
+    }
+    /**
+     * Attempt to decrypt a given envelope and return the plaintext string.
+     * Will prompt to unlock identity if necessary.
+     */
+    async decryptEnvelope(envelope, bypassIdentity = false) {
+        const fingerprint = envelope.extractFingerprint();
+        const authorizedAccount = this.listContacts(true).find((a) => a.fingerprint === fingerprint);
+        if (!authorizedAccount) {
+            throw new Error("No matching own account to decrypt this envelope");
+        }
+        let privateKey;
+        if (bypassIdentity) {
+            const activeAccount = this.getActiveAccount();
+            if (!activeAccount) {
+                throw new Error("No active account available to bypass identity check");
+            }
+            privateKey = await KeyStore.getPrivateKey(activeAccount.id);
+        }
+        else {
+            privateKey = await this.ensureIdentityUnlocked(authorizedAccount.id);
+        }
+        if (!privateKey) {
+            throw new Error("No private key found for this fingerprint.");
+        }
+        let decrypted;
+        if (envelope.isGroup()) {
+            const recipientKey = envelope.getRecipientKey(fingerprint);
+            if (!recipientKey) {
+                throw new Error("No recipient key found for this fingerprint");
+            }
+            decrypted = await EncryptionEngine.decryptGroupMessage(envelope.extractEncryptedPayload(), privateKey, fingerprint);
+        }
+        else {
+            decrypted = await EncryptionEngine.decryptSoloMessage(envelope.extractEncryptedPayload(), privateKey);
+        }
+        await this.envelopeCache.set(envelope, typeof window !== "undefined" && window.location
+            ? window.location.hostname
+            : "extension");
+        return decrypted;
+    }
+    async importContactFromString(base64Str) {
+        const jsonStr = base64ToUtf8(base64Str);
+        const isImportSuccess = await this.importContactFromJSON(jsonStr);
+        if (!isImportSuccess.success)
+            throw new Error(isImportSuccess.message);
+    }
+    addContact(contact) {
+        this.contactDirectory.addContact(contact);
+        this.scheduleAutosave();
+    }
+    removeContact(id) {
+        const removalStatus = this.contactDirectory.removeContact(id);
+        if (!removalStatus.success) {
+            throw new Error(removalStatus.message);
+        }
+        this.scheduleAutosave();
+    }
+    updateContactMeta(id, meta) {
+        this.contactDirectory.updateContactMeta(id, meta);
+        this.scheduleAutosave();
+    }
+    blockContact(id) {
+        this.contactDirectory.blockContact(id);
+        this.scheduleAutosave();
+    }
+    unblockContact(id) {
+        this.contactDirectory.unblockContact(id);
+        this.scheduleAutosave();
+    }
+    listContacts(all = true) {
+        const contacts = this.contactDirectory.listContacts(true);
+        if (all) {
+            return contacts;
+        }
+        const userAccounts = this.listOwnAccounts();
+        const userAccountIds = new Set(userAccounts.map((a) => a.id));
+        return contacts.filter((contact) => !userAccountIds.has(contact.id));
+    }
+    /**
+     * Update the passphrase for an identity.
+     * - `id` defaults to the current active account if not provided.
+     * - Throws if no active account exists or passphrase is invalid.
+     */
+    async updatePassphrase(currentPassphrase, newPassphrase, id) {
+        // Determine target account
+        const targetAccount = id
+            ? this.getOwnAccountById(id)
+            : this.getActiveAccount();
+        if (!targetAccount) {
+            throw new Error("No target account specified and no active account available");
+        }
+        // Delegate to KeyStore
+        await KeyStore.updatePassphrase(targetAccount.id, currentPassphrase, newPassphrase);
+        // Optionally emit an event or autosave
+        this.scheduleAutosave();
+    }
+    /* ================================
+     * Encryption / Decryption
+     * ================================ */
+    /**
+     * Encrypts a plaintext message for a single recipient (solo message)
+     * Returns a MessageEnvelope instance and caches it automatically.
+     */
+    async encryptSoloMessage(toId, plaintext, cache = true) {
+        const contact = this.contactDirectory.getContact(toId);
+        if (!contact)
+            throw new Error(`No contact with id "${toId}"`);
+        const payload = await EncryptionEngine.encryptSoloMessage(plaintext, contact.publicKey);
+        const payloadJSON = JSON.stringify(payload);
+        const encoder = new TextEncoder();
+        const payloadBytes = encoder.encode(payloadJSON);
+        // Envelope: [version byte][fingerprint][payload]
+        const versionByte = new Uint8Array([1]);
+        const fingerprintBytes = new Uint8Array(base64ToArrayBuffer(contact.fingerprint));
+        const blob = new Uint8Array(versionByte.length + fingerprintBytes.length + payloadBytes.length);
+        blob.set(versionByte, 0);
+        blob.set(fingerprintBytes, versionByte.length);
+        blob.set(payloadBytes, versionByte.length + fingerprintBytes.length);
+        const envelope = new MessageEnvelope(blob.buffer);
+        if (!!cache) {
+            // Cache envelope
+            await this.envelopeCache.set(envelope, typeof window !== "undefined" && window.location
+                ? window.location.hostname
+                : "extension");
+        }
+        this.scheduleAutosave();
+        this.emit("envelope", envelope);
+        return envelope;
+    }
+    /**
+     * Encrypts a plaintext message for a group of recipients.
+     * Returns a unified group MessageEnvelope instance.
+     */
+    async encryptGroupMessage(recipientIds, plaintext, cache = true) {
+        if (!recipientIds.length) {
+            throw new Error("No recipients provided");
+        }
+        // Resolve recipients and their keys
+        const recipients = recipientIds.map((id) => {
+            const contact = this.contactDirectory.getContact(id);
+            if (!contact)
+                throw new Error(`No contact with id "${id}"`);
+            return {
+                id: contact.id,
+                publicKey: contact.publicKey,
+                fingerprint: contact.fingerprint,
+            };
+        });
+        // 🔐 Encrypt once for all recipients
+        const payload = await EncryptionEngine.encryptGroupMessage(plaintext, recipients);
+        // Serialize payload
+        const payloadBytes = new TextEncoder().encode(JSON.stringify(payload));
+        // Envelope structure: [version byte][sender fingerprint][payload bytes]
+        const versionByte = new Uint8Array([2]);
+        // Use sender fingerprint for group envelope
+        const activeAccount = this.getActiveAccount();
+        if (!activeAccount)
+            throw new Error("No active account to send from");
+        const fingerprintBytes = new Uint8Array(base64ToArrayBuffer(activeAccount.fingerprint));
+        // Combine all parts into a single Uint8Array
+        const blob = new Uint8Array(versionByte.length + fingerprintBytes.length + payloadBytes.length);
+        blob.set(versionByte, 0);
+        blob.set(fingerprintBytes, versionByte.length);
+        blob.set(payloadBytes, versionByte.length + fingerprintBytes.length);
+        // Wrap as MessageEnvelope
+        const envelope = new MessageEnvelope(blob.buffer);
+        if (!!cache) {
+            // Cache envelope
+            await this.envelopeCache.set(envelope, typeof window !== "undefined" && window.location
+                ? window.location.hostname
+                : "extension");
+        }
+        this.scheduleAutosave();
+        this.emit("envelope", envelope);
+        return envelope;
+    }
+    async sendMessage(recipients, plaintext) {
+        if (recipients.length === 0 || !recipients) {
+            throw new Error("No recipients provided. At least one recipient is required.");
+        }
+        if (recipients.length === 1) {
+            return await this.encryptSoloMessage(recipients[0], plaintext);
+        }
+        else {
+            return await this.encryptGroupMessage(recipients, plaintext);
+        }
+    }
+    /* ================================
+     * High-Level DOM Wrapper
+     * ================================ */
+    /**
+     * Encrypts currently selected text in the browser DOM for given recipients.
+     * If `recipients` is empty, defaults to the first own account.
+     * Returns the fully serialized base64 envelope string for the scanner.
+     */
+    async encryptSelectedTextForScanner(recipients = []) {
+        // Delegate to textarea-agnostic implementation
+        const plaintext = window.getSelection()?.toString().trim() ?? "";
+        return await this.encryptTextForScanner(plaintext, recipients);
+    }
+    /**
+     * Encrypt a provided plaintext string and return a serialized MajikMessage envelope string.
+     * Supports single or multiple recipients. Safe to call from background contexts.
+     */
+    async encryptTextForScanner(plaintext, recipients = [], cache = true) {
+        if (!plaintext?.trim()) {
+            console.warn("No text provided to encrypt.");
+            return null;
+        }
+        try {
+            // Determine recipients: default to first own account if none provided
+            if (recipients.length === 0) {
+                const firstOwn = this.listOwnAccounts()[0];
+                if (!firstOwn)
+                    throw new Error("No own account available for encryption.");
+                recipients = [firstOwn.id];
+            }
+            let envelope;
+            if (recipients.length === 1) {
+                // Single recipient → solo message
+                envelope = await this.encryptSoloMessage(recipients[0], plaintext, cache);
+            }
+            else {
+                // Multiple recipients → unified group message
+                envelope = await this.encryptGroupMessage(recipients, plaintext, cache);
+            }
+            // Convert envelope to base64 for scanner
+            const envelopeBase64 = arrayBufferToBase64(envelope.raw);
+            return `${MessageEnvelope.PREFIX}:${envelopeBase64}`;
+        }
+        catch (err) {
+            this.emit("error", err, { context: "encryptTextForScanner" });
+            return null;
+        }
+    }
+    /**
+     * Encrypt text for a given target (label or ID).
+     * - If target is self or not found, just encrypt normally.
+     * - If target is another contact, always make a group message including self + target.
+     */
+    async encryptForTarget(target, // can be label or id
+    plaintext) {
+        const activeAccount = this.getActiveAccount();
+        if (!activeAccount)
+            throw new Error("No active account available");
+        // Try to find contact by ID first
+        let contact = this.listContacts(false).find((c) => c.id === target);
+        // If not found by ID, try by label
+        if (!contact) {
+            contact = this.listContacts(false).find((c) => c.meta?.label === target);
+        }
+        // If still not found or it's self → solo encryption
+        if (!contact || contact.id === activeAccount.id) {
+            return this.encryptTextForScanner(plaintext, [activeAccount.id]);
+        }
+        // Otherwise → group with self + target contact
+        return this.encryptTextForScanner(plaintext, [
+            activeAccount.id,
+            contact.id,
+        ]);
+    }
+    /* ================================
+     * DOM Scanning
+     * ================================ */
+    scanDOM(rootNode) {
+        this.scanner.scanDOM(rootNode);
+    }
+    startDOMObserver(rootNode) {
+        this.scanner.startDOMObserver(rootNode);
+    }
+    stopDOMObserver() {
+        this.scanner.stopDOMObserver();
+    }
+    /* ================================
+     * Event Handling
+     * ================================ */
+    on(event, callback) {
+        this.listeners.get(event)?.push(callback);
+    }
+    emit(event, ...args) {
+        this.listeners.get(event)?.forEach((cb) => cb(...args));
+    }
+    /* ================================
+     * Envelope Handling
+     * ================================ */
+    async handleEnvelope(envelope) {
+        // Skip if already cached
+        const cached = await this.envelopeCache.get(envelope);
+        if (cached)
+            return;
+        const fingerprint = envelope.extractFingerprint();
+        // contact is the directory entry (useful for metadata); ownAccount
+        // must match fingerprint for this device to be able to decrypt.
+        const contact = this.contactDirectory.getContactByFingerprint(fingerprint);
+        const ownAccount = this.listOwnAccounts().find((a) => a.fingerprint === fingerprint);
+        // If this envelope isn't addressed to one of our own accounts, mark as untrusted
+        if (!ownAccount) {
+            this.emit("untrusted", envelope);
+            return;
+        }
+        try {
+            // Ensure identity unlocked; try interactive prompt if needed
+            const privateKey = await this.ensureIdentityUnlocked(ownAccount.id);
+            let decrypted;
+            if (envelope.isGroup()) {
+                const recipientKey = envelope.getRecipientKey(fingerprint);
+                if (!recipientKey) {
+                    throw new Error("No recipient key found for this fingerprint");
+                }
+                decrypted = await EncryptionEngine.decryptGroupMessage(envelope.extractEncryptedPayload(), privateKey, fingerprint);
+            }
+            else {
+                decrypted = await EncryptionEngine.decryptSoloMessage(envelope.extractEncryptedPayload(), privateKey);
+            }
+            // Cache envelope (record source as current hostname when available)
+            await this.envelopeCache.set(envelope, typeof window !== "undefined" && window.location
+                ? window.location.hostname
+                : "extension");
+            this.scheduleAutosave();
+            this.emit("message", decrypted, envelope, contact);
+        }
+        catch (err) {
+            this.emit("error", err, { envelope });
+        }
+    }
+    /**
+     * Ensure an identity is unlocked. If locked, prompt the user for a passphrase.
+     * `promptFn` can be provided to show a custom UI: either synchronous returning string
+     * or async Promise<string>. If omitted, falls back to `window.prompt`.
+     */
+    async ensureIdentityUnlocked(id, promptFn) {
+        try {
+            return await KeyStore.getPrivateKey(id);
+        }
+        catch (err) {
+            // If KeyStore indicates unlocking is required, prompt the user
+            const needsUnlock = err instanceof Error &&
+                /must be unlocked|unlockIdentity/.test(err.message);
+            if (!needsUnlock)
+                throw err;
+            // Ask for passphrase
+            let passphrase = null;
+            if (promptFn) {
+                const res = promptFn(id);
+                passphrase = typeof res === "string" ? res : await res;
+            }
+            else if (KeyStore.onUnlockRequested) {
+                const res = KeyStore.onUnlockRequested(id);
+                passphrase = typeof res === "string" ? res : await res;
+            }
+            else if (typeof window !== "undefined" && window.prompt) {
+                passphrase = window.prompt("Enter passphrase to unlock identity:", "");
+            }
+            if (!passphrase)
+                throw new Error("Unlock cancelled");
+            // Attempt to unlock
+            await KeyStore.unlockIdentity(id, passphrase);
+            return await KeyStore.getPrivateKey(id);
+        }
+    }
+    async isPassphraseValid(passphrase, id) {
+        const target = id ? this.getOwnAccountById(id) : this.getActiveAccount();
+        if (!target)
+            return false;
+        return KeyStore.isPassphraseValid(target.id, passphrase);
+    }
+    async toJSON() {
+        const finalJSON = {
+            id: this.id,
+            contacts: await this.contactDirectory.toJSON(),
+            envelopeCache: this.envelopeCache.toJSON(),
+        };
+        // Serialize own accounts (preserve order)
+        try {
+            const ownAccountsArr = [];
+            for (const id of this.ownAccountsOrder) {
+                const acct = this.ownAccounts.get(id);
+                if (!acct)
+                    continue;
+                ownAccountsArr.push(await acct.toJSON());
+            }
+            finalJSON.ownAccounts = {
+                accounts: ownAccountsArr,
+                order: [...this.ownAccountsOrder],
+            };
+        }
+        catch (e) {
+            // ignore serialization errors for own accounts
+            console.warn("Failed to serialize ownAccounts:", e);
+        }
+        // include optional PIN hash
+        finalJSON.pinHash = this.pinHash || null;
+        return finalJSON;
+    }
+    static async fromJSON(json) {
+        const newDirectory = new MajikContactDirectory();
+        const parsedContacts = await newDirectory.fromJSON(json.contacts);
+        const parsedEnvelopeCache = EnvelopeCache.fromJSON(json.envelopeCache);
+        const parsedInstance = new MajikMessage({
+            contactDirectory: parsedContacts,
+            envelopeCache: parsedEnvelopeCache,
+            keyStore: KeyStore,
+        }, json.id);
+        // Restore ownAccounts if present
+        try {
+            if (json.ownAccounts && Array.isArray(json.ownAccounts.accounts)) {
+                for (const acct of json.ownAccounts.accounts) {
+                    try {
+                        const raw = base64ToArrayBuffer(acct.publicKeyBase64);
+                        const publicKey = await crypto.subtle.importKey("raw", raw, KEY_ALGO, true, []);
+                        const contact = MajikContact.create(acct.id, publicKey, acct.fingerprint, acct.meta);
+                        parsedInstance.ownAccounts.set(contact.id, contact);
+                    }
+                    catch (e) {
+                        // SubtleCrypto may not support importing X25519 keys in some environments.
+                        // This is non-fatal: we fall back to raw-key wrappers elsewhere.
+                        console.info("Fallback restoring own account (using raw-key wrapper)", acct.id, e);
+                    }
+                }
+                if (Array.isArray(json.ownAccounts.order)) {
+                    parsedInstance.ownAccountsOrder = [...json.ownAccounts.order];
+                }
+                // Fallback: if accounts array was empty but order exists, try to populate
+                // ownAccounts from the restored contactDirectory entries
+                try {
+                    if (Array.isArray(json.ownAccounts.order) &&
+                        parsedInstance.ownAccounts.size === 0) {
+                        for (const id of json.ownAccounts.order) {
+                            try {
+                                const c = parsedInstance.contactDirectory.getContact(id);
+                                if (c)
+                                    parsedInstance.ownAccounts.set(id, c);
+                            }
+                            catch (e) {
+                                // ignore missing contacts
+                            }
+                        }
+                    }
+                }
+                catch (e) {
+                    // ignore
+                }
+                // Also add own accounts into contact directory for discoverability
+                try {
+                    parsedInstance.ownAccountsOrder.forEach((id) => {
+                        const c = parsedInstance.ownAccounts.get(id);
+                        if (c && !parsedInstance.contactDirectory.hasContact(c.id)) {
+                            parsedInstance.contactDirectory.addContact(c);
+                        }
+                    });
+                }
+                catch (e) {
+                    // ignore
+                }
+            }
+        }
+        catch (e) {
+            console.warn("Error restoring ownAccounts:", e);
+        }
+        // restore pin hash if present
+        try {
+            const anyJson = json;
+            if (anyJson.pinHash)
+                parsedInstance.pinHash = anyJson.pinHash;
+        }
+        catch (e) {
+            // ignore
+        }
+        return parsedInstance;
+    }
+    /**
+     * Set a PIN (stores hash). Passphrase is any string; we store SHA-256(base64) of it.
+     */
+    async setPIN(pin) {
+        if (!pin)
+            throw new Error("PIN must be a non-empty string");
+        const hash = await MajikMessage.hashPIN(pin);
+        this.pinHash = hash;
+        this.scheduleAutosave();
+    }
+    async clearPIN() {
+        this.pinHash = null;
+        this.scheduleAutosave();
+    }
+    async isValidPIN(pin) {
+        if (!this.pinHash)
+            return true; // no PIN set => always valid
+        const hash = await MajikMessage.hashPIN(pin);
+        return hash === this.pinHash;
+    }
+    getPinHash() {
+        return this.pinHash || null;
+    }
+    static async hashPIN(pin) {
+        const data = new TextEncoder().encode(pin);
+        const digest = await crypto.subtle.digest("SHA-256", data);
+        // base64 encode
+        const b64 = arrayBufferToBase64(digest);
+        return b64;
+    }
+    /* ================================
+     * Persistence
+     * ================================ */
+    autosaveIntervalId = null;
+    attachAutosaveHandlers() {
+        if (typeof window !== "undefined") {
+            // Save before unload (best-effort)
+            try {
+                window.addEventListener("beforeunload", () => {
+                    void this.saveState();
+                });
+            }
+            catch (e) {
+                // ignore
+            }
+            // Start periodic backups
+            this.startAutosave();
+        }
+    }
+    startAutosave() {
+        if (this.autosaveIntervalId)
+            return;
+        if (typeof window === "undefined")
+            return;
+        this.autosaveIntervalId = window.setInterval(() => {
+            void this.saveState();
+        }, this.autosaveIntervalMs);
+    }
+    stopAutosave() {
+        if (!this.autosaveIntervalId)
+            return;
+        if (typeof window !== "undefined") {
+            window.clearInterval(this.autosaveIntervalId);
+        }
+        this.autosaveIntervalId = null;
+    }
+    scheduleAutosave() {
+        try {
+            if (this.autosaveTimer) {
+                if (typeof window !== "undefined")
+                    window.clearTimeout(this.autosaveTimer);
+                this.autosaveTimer = null;
+            }
+            if (typeof window !== "undefined") {
+                this.autosaveTimer = window.setTimeout(() => {
+                    void this.saveState();
+                    this.autosaveTimer = null;
+                }, this.autosaveDebounceMs);
+            }
+        }
+        catch (e) {
+            // ignore scheduling errors
+        }
+    }
+    /** Save current state into IndexedDB (autosave). */
+    async saveState() {
+        try {
+            const jsonDocument = await this.toJSON();
+            const autosaveBlob = autoSaveMajikFileData(jsonDocument);
+            await idbSaveBlob("majik-message-state", autosaveBlob);
+        }
+        catch (err) {
+            console.error("Failed to save MajikMessage state:", err);
+        }
+    }
+    /** Load state from IndexedDB and apply to this instance. */
+    async loadState() {
+        try {
+            const autosaveData = await idbLoadBlob("majik-message-state");
+            if (!autosaveData?.data)
+                return;
+            const blobFile = autosaveData.data;
+            const loadedData = await loadSavedMajikFileData(blobFile);
+            const parsedJSON = loadedData.j;
+            // Use fromJSON to ensure ownAccounts and other fields are restored consistently
+            const restored = await MajikMessage.fromJSON(parsedJSON);
+            this.id = restored.id;
+            this.contactDirectory = restored.contactDirectory;
+            this.envelopeCache = restored.envelopeCache;
+            this.ownAccounts = restored.ownAccounts;
+            this.ownAccountsOrder = [...restored.ownAccountsOrder];
+        }
+        catch (err) {
+            console.error("Failed to load MajikMessage state:", err);
+        }
+    }
+    /**
+     * Try to load an existing state from IDB; if none exists, create a fresh instance and save it.
+     */
+    static async loadOrCreate(config) {
+        try {
+            const saved = await idbLoadBlob("majik-message-state");
+            if (saved?.data) {
+                const loaded = await loadSavedMajikFileData(saved.data);
+                const parsedJSON = loaded.j;
+                const instance = await MajikMessage.fromJSON(parsedJSON);
+                console.log("Account Loaded Successfully");
+                instance.attachAutosaveHandlers();
+                return instance;
+            }
+        }
+        catch (err) {
+            console.warn("Error trying to load saved MajikMessage state:", err);
+        }
+        // No saved state; create new and persist initial state
+        const created = new MajikMessage(config);
+        await created.saveState();
+        created.attachAutosaveHandlers();
+        return created;
+    }
+}