@majikah/majik-message 0.2.20 → 0.3.0

package/dist/majik-message.js

@@ -1,11 +1,9 @@
 // MajikMessage.ts
 import { MajikContact, } from "@majikah/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 { MajikKeyStore } from "./core/crypto/keystore";
-import { MajikContactDirectory, } from "./core/contacts/majik-contact-directory";
 import { arrayBufferToBase64, arrayToBase64, base64ToArrayBuffer, base64ToUint8Array, } from "./core/utils/utilities";
 import { autoSaveMajikFileData, loadSavedMajikFileData, } from "./core/utils/majik-file-utils";
 import { randomBytes } from "@stablelib/random";
@@ -16,14 +14,14 @@ import { MajikEnvelope, } from "@majikah/majik-envelope";
 import { MajikFile, MajikFileError, } from "@majikah/majik-file";
 import { MajikSignature, } from "@majikah/majik-signature";
 import { gzipSync, gunzipSync } from "fflate";
+import { MajikContactManager } from "./core/contacts/majik-contact-manager";
+import { migrateMajikMessageJSON } from "./core/contacts/majik-contact-migration";
 // ─── MajikMessage ─────────────────────────────────────────────────────────────
 export class MajikMessage {
     userProfile = "default";
-    pinHash = null;
     id;
-    contactDirectory;
+    contacts;
     envelopeCache;
-    scanner;
     listeners = new Map();
     ownAccounts = new Map();
     ownAccountsOrder = [];
@@ -34,16 +32,9 @@ export class MajikMessage {
     constructor(config, id, userProfile = "default") {
         this.userProfile = userProfile || "default";
         this.id = id || arrayToBase64(randomBytes(32));
-        this.contactDirectory =
-            config.contactDirectory || new MajikContactDirectory();
+        this.contacts = config.contactManager ?? new MajikContactManager();
         this.envelopeCache =
             config.envelopeCache || new EnvelopeCache(undefined, userProfile);
-        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),
-        });
         const events = [
             "message",
             "envelope",
@@ -58,38 +49,13 @@ export class MajikMessage {
         events.forEach((e) => this.listeners.set(e, []));
         this.attachAutosaveHandlers();
     }
-    // ── Private: Envelope helpers ────────────────────────────────────────────
-    // /**
-    //  * Resolve a list of account/contact IDs into MajikRecipient objects.
-    //  * Each recipient needs their ML-KEM public key from MajikKeyStore.
-    //  */
-    // private async _resolveRecipients(ids: string[]): Promise<MajikRecipient[]> {
-    //   return Promise.all(
-    //     ids.map(async (id) => {
-    //       const contact = this.contactDirectory.getContact(id);
-    //       if (!contact) throw new Error(`No contact found for id "${id}"`);
-    //       // const key = await MajikKeyStore.load(id);
-    //       const mlPubKey = base64ToUint8Array(contact.mlKey);
-    //       if (!mlPubKey) {
-    //         throw new Error(
-    //           `Contact "${id}" has no ML-KEM public key. ` +
-    //             `They may need to upgrade their account via importFromMnemonicBackup().`,
-    //         );
-    //       }
-    //       return {
-    //         fingerprint: contact.fingerprint,
-    //         mlKemPublicKey: mlPubKey,
-    //       } satisfies MajikRecipient;
-    //     }),
-    //   );
-    // }
     /**
      * Resolve a list of account/contact IDs into MajikRecipient objects.
      * Each recipient needs their ML-KEM public key from MajikKeyStore.
      */
     async _resolveRecipientsByPublicKey(publicKeys) {
         return Promise.all(publicKeys.map(async (pkey) => {
-            const contact = await this.contactDirectory.getContactByPublicKeyBase64(pkey);
+            const contact = await this.contacts.getContactByPublicKeyBase64(pkey);
             if (!contact)
                 throw new Error(`No contact found for public key "${pkey}"`);
             const mlPubKey = base64ToUint8Array(contact.mlKey);
@@ -159,7 +125,7 @@ export class MajikMessage {
      */
     async _resolveFileRecipientsByPublicKey(publicKeys) {
         return Promise.all(publicKeys.map(async (pkey) => {
-            const contact = await this.contactDirectory.getContactByPublicKeyBase64(pkey);
+            const contact = await this.contacts.getContactByPublicKeyBase64(pkey);
             if (!contact)
                 throw new Error(`No contact found for public key "${pkey}"`);
             const mlPubKey = base64ToUint8Array(contact.mlKey);
@@ -216,8 +182,8 @@ export class MajikMessage {
             this.ownAccountsOrder.push(account.id);
         }
         try {
-            if (!this.contactDirectory.hasContact(account.id)) {
-                this.contactDirectory.addContact(account);
+            if (!this.contacts.hasContact(account.id)) {
+                this.contacts.addContact(account);
             }
             if (!this.getActiveAccount()) {
                 this.setActiveAccount(account.id);
@@ -298,20 +264,25 @@ export class MajikMessage {
     getContactByID(id) {
         if (!id?.trim())
             throw new Error("Invalid contact ID");
-        return this.contactDirectory.getContact(id) ?? null;
+        return this.contacts.getContact(id) ?? null;
     }
     hasContact(id) {
         if (!id?.trim())
             throw new Error("Invalid contact ID");
-        return this.contactDirectory.hasContact(id);
+        return this.contacts.hasContact(id);
+    }
+    async hasContactByPublicKeyBase64(publicKey) {
+        if (!publicKey?.trim())
+            throw new Error("Invalid contact public key");
+        return await this.contacts.hasContactByPublicKeyBase64(publicKey);
     }
     async getContactByPublicKey(publicKeyBase64) {
         if (!publicKeyBase64?.trim())
             throw new Error("Invalid public key");
-        return ((await this.contactDirectory.getContactByPublicKeyBase64(publicKeyBase64)) ?? null);
+        return ((await this.contacts.getContactByPublicKeyBase64(publicKeyBase64)) ?? null);
     }
-    async exportContactAsJSON(contactId) {
-        const contact = this.contactDirectory.getContact(contactId);
+    async exportContactAsJSON(contactID) {
+        const contact = this.contacts.getContact(contactID);
         if (!contact)
             return null;
         let publicKeyBase64;
@@ -333,8 +304,8 @@ export class MajikMessage {
             mlDsaPublicKeyBase64: contact.mlDsaPublicKeyBase64,
         }, null, 2);
     }
-    async exportContactAsString(contactId) {
-        const contact = this.contactDirectory.getContact(contactId);
+    async exportContactAsString(contactID) {
+        const contact = this.contacts.getContact(contactID);
         if (!contact)
             return null;
         const compressedString = this.exportContactCompressed(contact);
@@ -445,45 +416,276 @@ export class MajikMessage {
             !contact?.mlKey) {
             throw new Error("Invalid contact JSON");
         }
-        this.contactDirectory.addContact(contact);
+        this.contacts.addContact(contact);
         this.emit("new-contact", contact);
         this.scheduleAutosave();
     }
     removeContact(id) {
-        const result = this.contactDirectory.removeContact(id);
+        const result = this.contacts.removeContact(id);
         if (!result.success)
             throw new Error(result.message);
         this.emit("removed-contact", id);
         this.scheduleAutosave();
     }
     updateContactMeta(id, meta) {
-        this.contactDirectory.updateContactMeta(id, meta);
+        this.contacts.updateContactMeta(id, meta);
         this.scheduleAutosave();
     }
     blockContact(id) {
-        this.contactDirectory.blockContact(id);
+        this.contacts.blockContact(id);
         this.scheduleAutosave();
     }
     unblockContact(id) {
-        this.contactDirectory.unblockContact(id);
+        this.contacts.unblockContact(id);
         this.scheduleAutosave();
     }
     listContacts(all = true, majikahOnly = false) {
-        const contacts = this.contactDirectory.listContacts(true, majikahOnly);
+        const contacts = this.contacts.listContacts(true, majikahOnly);
         if (all)
             return contacts;
         const ownIds = new Set(this.listOwnAccounts(majikahOnly).map((a) => a.id));
         return contacts.filter((c) => !ownIds.has(c.id));
     }
     isContactMajikahRegistered(id) {
-        return this.contactDirectory.isMajikahRegistered(id);
+        return this.contacts.isMajikahRegistered(id);
     }
     isContactMajikahIdentityChecked(id) {
-        return this.contactDirectory.isMajikahIdentityChecked(id);
+        return this.contacts.isMajikahIdentityChecked(id);
     }
     setContactMajikahStatus(id, status) {
-        this.contactDirectory.setMajikahStatus(id, status);
+        this.contacts.setMajikahStatus(id, status);
+        this.scheduleAutosave();
+    }
+    /* ================================
+     * Group CRUD Pass-throughs
+     * ================================ */
+    /**
+     * Creates and registers a new user-defined group.
+     * Throws if a group with the same ID already exists.
+     */
+    createGroup(id, name, meta, initialMemberIds) {
+        const newGroup = this.contacts.createGroup(id, name, meta, initialMemberIds);
+        this.emit("new-contact-group", newGroup);
+        this.scheduleAutosave();
+        return this;
+    }
+    /**
+     * Registers an already-constructed MajikContactGroup instance.
+     * Throws if a group with the same ID already exists.
+     */
+    addGroup(group) {
+        this.contacts.addGroup(group);
+        this.emit("new-contact-group", group);
+        this.scheduleAutosave();
+        return this;
+    }
+    /**
+     * Removes a user group by ID.
+     * System groups (Favorites, Blocked) cannot be deleted.
+     */
+    removeGroup(id) {
+        const response = this.contacts.removeGroup(id);
+        this.emit("removed-contact-group", response.data);
+        this.scheduleAutosave();
+        return response;
+    }
+    /**
+     * Returns a group by ID, or undefined if not found.
+     */
+    getContactGroup(id) {
+        return this.contacts.getGroup(id);
+    }
+    /**
+     * Returns a group by ID. Throws if not found.
+     */
+    getGroupOrThrow(id) {
+        return this.contacts.getGroupOrThrow(id);
+    }
+    /**
+     * Returns true if a group with the given ID exists.
+     */
+    hasGroup(id) {
+        return this.contacts.hasGroup(id);
+    }
+    /**
+     * Returns all groups.
+     *
+     * @param includeSystem  Include system groups (Favorites, Blocked). Default: true.
+     * @param sortedByName   Sort results alphabetically by group name. Default: false.
+     */
+    listContactGroups(includeSystem = true, sortedByName = false) {
+        return this.contacts.listGroups(includeSystem, sortedByName);
+    }
+    /**
+     * Returns only user-created groups (excludes Favorites and Blocked).
+     * Sorted alphabetically by name.
+     */
+    listUserGroups(sortedByName = true) {
+        return this.contacts.listGroups(false, sortedByName);
+    }
+    /**
+     * Returns only system groups (Favorites and Blocked).
+     */
+    listSystemGroups() {
+        return this.contacts.listGroups(true).filter((g) => g.isSystem);
+    }
+    /**
+     * Updates mutable metadata on a group (name, description).
+     * Name is locked on system groups — will throw if attempted.
+     */
+    updateGroupMeta(id, meta) {
+        const updatedGroup = this.contacts.updateGroupMeta(id, meta);
+        this.emit("contact-group-change", updatedGroup);
+        this.scheduleAutosave();
+        return this;
+    }
+    /* ================================
+     * Group Membership Pass-throughs
+     * ================================ */
+    /**
+     * Adds a contact to a group.
+     * Validates the contact exists in the directory.
+     * If the group is the system Blocked group, also calls contact.block().
+     * Throws if the contact is already a member — use addContactToGroupIfAbsent for idempotent.
+     */
+    addContactToGroup(groupID, contactID) {
+        const updatedGroup = this.contacts.addContactToGroup(groupID, contactID);
+        this.emit("contact-group-change", updatedGroup);
+        this.scheduleAutosave();
+        return this;
+    }
+    /**
+     * Adds multiple contacts to a group in one call (all-or-nothing).
+     */
+    addContactsToGroup(groupID, contactIds) {
+        const updatedGroup = this.contacts.addContactsToGroup(groupID, contactIds);
+        this.emit("contact-group-change", updatedGroup);
+        this.scheduleAutosave();
+        return this;
+    }
+    /**
+     * Removes a contact from a group.
+     * If the group is the system Blocked group, also calls contact.unblock().
+     * Throws if the contact is not a member — use removeContactFromGroupIfPresent for idempotent.
+     */
+    removeContactFromGroup(groupID, contactID) {
+        const updatedGroup = this.contacts.removeContactFromGroup(groupID, contactID);
+        this.emit("contact-group-change", updatedGroup);
+        this.scheduleAutosave();
+        return this;
+    }
+    /**
+     * Moves a contact from one group to another atomically.
+     * Throws if the contact is not a member of the source group.
+     */
+    moveContactBetweenGroups(contactID, fromGroupId, toGroupId) {
+        const updatedGroup = this.contacts.moveContactBetweenGroups(contactID, fromGroupId, toGroupId);
+        this.emit("contact-group-change", updatedGroup);
+        this.scheduleAutosave();
+        return this;
+    }
+    /* ================================
+     * Group Query Pass-throughs
+     * ================================ */
+    /**
+     * Returns all hydrated MajikContact instances in the given group.
+     * Contacts removed from the directory since last save are silently skipped.
+     */
+    getContactsInGroup(groupID) {
+        return this.contacts.getContactsInGroup(groupID);
+    }
+    /**
+     * Returns hydrated contacts in the group, sorted by label (or ID if no label).
+     */
+    getContactsInGroupSorted(groupID) {
+        return this.contacts.getContactsInGroupSorted(groupID);
+    }
+    /**
+     * Returns true if the contact is a member of the given group.
+     */
+    isContactInGroup(groupID, contactID) {
+        return this.contacts.isContactInGroup(groupID, contactID);
+    }
+    /**
+     * Returns all groups the contact belongs to.
+     */
+    getGroupsForContact(contactID) {
+        return this.contacts.getGroupsForContact(contactID);
+    }
+    /**
+     * Returns all group IDs the contact belongs to.
+     */
+    getGroupIdsForContact(contactID) {
+        return this.contacts.getGroupIdsForContact(contactID);
+    }
+    /* ================================
+     * System Group Convenience Pass-throughs
+     * ================================ */
+    /**
+     * Adds the contact to the Favorites group (idempotent).
+     */
+    addContactToFavorites(contactID) {
+        const updatedGroup = this.contacts.addToFavorites(contactID);
+        this.emit("contact-group-change", updatedGroup);
+        this.scheduleAutosave();
+        return this;
+    }
+    /**
+     * Removes the contact from the Favorites group (idempotent).
+     */
+    removeContactFromFavorites(contactID) {
+        const updatedGroup = this.contacts.removeFromFavorites(contactID);
+        this.emit("contact-group-change", updatedGroup);
+        this.scheduleAutosave();
+        return this;
+    }
+    /**
+     * Returns true if the contact is in the Favorites group.
+     */
+    isContactFavorite(contactID) {
+        return this.contacts.isFavorite(contactID);
+    }
+    /**
+     * Returns true if the contact is in the Blocked group.
+     */
+    isContactBlocked(contactID) {
+        return this.contacts.isContactBlocked(contactID);
+    }
+    /**
+     * Returns the Favorites system group instance.
+     */
+    getFavoritesGroup() {
+        return this.contacts.getFavoritesGroup();
+    }
+    /**
+     * Returns the Blocked system group instance.
+     */
+    getBlockedGroup() {
+        return this.contacts.getBlockedGroup();
+    }
+    /**
+     * Returns all contacts in the Favorites group as hydrated MajikContact instances.
+     */
+    getFavoriteContacts() {
+        return this.contacts.getContactsInGroup(this.contacts.getFavoritesGroup().id);
+    }
+    /**
+     * Returns all contacts in the Blocked group as hydrated MajikContact instances.
+     */
+    getBlockedContacts() {
+        return this.contacts.getContactsInGroup(this.contacts.getBlockedGroup().id);
+    }
+    /* ================================
+     * Directory Clear
+     * ================================ */
+    /**
+     * Clears both the directory and all group memberships.
+     * System groups are preserved (re-bootstrapped by the group manager).
+     */
+    clearDirectory() {
+        this.contacts.clear();
         this.scheduleAutosave();
+        return this;
     }
     // ── Encryption / Decryption ───────────────────────────────────────────────
     /**
@@ -759,7 +961,7 @@ export class MajikMessage {
      *   metadata: row,
      * });
      * if (signature) {
-     *   const result = await majik.verifyMajikFile(file, { contactId: row.user_id });
+     *   const result = await majik.verifyMajikFile(file, { contactID: row.user_id });
      * }
      * ```
      */
@@ -852,7 +1054,7 @@ export class MajikMessage {
      * if the instance was restored from a metadata-only Supabase row.
      *
      * Signer resolution:
-     *   - contactId: looked up in the contact directory (own accounts included)
+     *   - contactID: looked up in the contact directory (own accounts included)
      *   - publicKeyBase64: looked up via contact directory
      *   - key: used directly (skips directory lookup)
      *   - none provided: falls back to public keys embedded in the signature
@@ -863,7 +1065,7 @@ export class MajikMessage {
      * @example — verify against the file's owner contact
      *   file.attachBinary(await r2.get(row.r2_key).arrayBuffer());
      *   const result = await majik.verifyMajikFile(file, {
-     *     contactId: ownerContactId,
+     *     contactID: ownerContactId,
      *   });
      *   if (result?.valid) console.log("Verified, signed by", result.signerId);
      */
@@ -903,7 +1105,7 @@ export class MajikMessage {
      *
      * @example
      *   const result = await majik.verifyMajikFileBinary(file, {
-     *     contactId: "contact_abc",
+     *     contactID: "contact_abc",
      *   });
      *   if (result.valid) console.log("Plaintext verified");
      */
@@ -1113,7 +1315,7 @@ export class MajikMessage {
      *
      * @example
      *   const result = await majik.verifyText("Hello world", sig, {
-     *     contactId: "contact_abc",
+     *     contactID: "contact_abc",
      *   });
      *   if (result.valid) console.log("Authentic");
      */
@@ -1139,7 +1341,7 @@ export class MajikMessage {
      * @example
      *   const row = await db.findOne({ doc_id });
      *   const result = await majik.verifyDetached(docBytes, row.signature, {
-     *     contactId: row.signer_contact_id,
+     *     contactID: row.signer_contact_id,
      *   });
      *   if (result.valid) console.log("Signed by", result.signerId);
      */
@@ -1273,16 +1475,6 @@ export class MajikMessage {
             return false;
         return MajikKeyStore.isPassphraseValid(target.id, passphrase);
     }
-    // ── DOM Scanning ──────────────────────────────────────────────────────────
-    scanDOM(rootNode) {
-        this.scanner.scanDOM(rootNode);
-    }
-    startDOMObserver(rootNode) {
-        this.scanner.startDOMObserver(rootNode);
-    }
-    stopDOMObserver() {
-        this.scanner.stopDOMObserver();
-    }
     // ── Events ────────────────────────────────────────────────────────────────
     on(event, callback) {
         this.listeners.get(event)?.push(callback);
@@ -1504,7 +1696,7 @@ export class MajikMessage {
      * > against a known contact fingerprint before trusting the result.
      *
      * @example — verify against a known contact
-     *   const result = await majik.verifyContent(docBytes, sig, { contactId: "contact_abc" });
+     *   const result = await majik.verifyContent(docBytes, sig, { contactID: "contact_abc" });
      *   if (result.valid) console.log("Authentic, signed by:", result.signerId);
      *
      * @example — verify using embedded keys (self-reported)
@@ -1540,12 +1732,12 @@ export class MajikMessage {
      * envelope are used (self-reported — see security note on verifyContent).
      *
      * @example — verify a signed PDF against a known contact
-     *   const result = await majik.verifyFile(signedPdf, { contactId: "contact_abc" });
+     *   const result = await majik.verifyFile(signedPdf, { contactID: "contact_abc" });
      *   if (result.valid) console.log("Verified:", result.signerId, result.timestamp);
      *
      * @example — check own signed file using active account
      *   const result = await majik.verifyFile(signedWav, {
-     *     contactId: majik.getActiveAccount()?.id,
+     *     contactID: majik.getActiveAccount()?.id,
      *   });
      */
     async verifyFile(file, options) {
@@ -1559,7 +1751,7 @@ export class MajikMessage {
                 return results[0];
             }
             // No signer provided — extract and use self-reported keys from first signature.
-            // For full multi-sig verification, pass a contactId or publicKeyBase64.
+            // For full multi-sig verification, pass a contactID or publicKeyBase64.
             const extracted = await MajikSignature.extractFrom(file, {
                 mimeType: options?.mimeType,
             });
@@ -1594,7 +1786,7 @@ export class MajikMessage {
      * @example
      *   const results = await majik.batchVerifyFiles(
      *     [pdfBlob, wavBlob, mp4Blob],
-     *     { contactId: "contact_abc" },
+     *     { contactID: "contact_abc" },
      *   );
      *   const allValid = results.every(r => r.valid);
      */
@@ -1706,7 +1898,7 @@ export class MajikMessage {
      *
      * @example
      *   if (await majik.isFileSigned(file)) {
-     *     const result = await majik.verifyFile(file, { contactId });
+     *     const result = await majik.verifyFile(file, { contactID });
      *   }
      */
     async isFileSigned(file, options) {
@@ -2050,22 +2242,22 @@ export class MajikMessage {
             return MajikSignature.publicKeysFromMajikKey(options.key);
         }
         // Option B: contact ID looked up from the contact directory
-        if (options.contactId) {
-            const contact = this.contactDirectory.getContact(options.contactId);
+        if (options.contactID) {
+            const contact = this.contacts.getContact(options.contactID);
             if (!contact) {
-                throw new Error(`No contact found for id "${options.contactId}"`);
+                throw new Error(`No contact found for id "${options.contactID}"`);
             }
             // Own accounts are in the keystore — get their signing keys directly
-            const ownAccount = this.getOwnAccountById(options.contactId);
+            const ownAccount = this.getOwnAccountById(options.contactID);
             if (ownAccount) {
-                const key = MajikKeyStore.get(options.contactId);
+                const key = MajikKeyStore.get(options.contactID);
                 if (key?.hasSigningKeys) {
                     return MajikSignature.publicKeysFromMajikKey(key);
                 }
             }
             // External contact — resolve from their contact card fields
             if (!contact.edPublicKeyBase64 || !contact.mlDsaPublicKeyBase64) {
-                throw new Error(`Contact "${options.contactId}" has no signing public keys. ` +
+                throw new Error(`Contact "${options.contactID}" has no signing public keys. ` +
                     `They may need to share an updated contact card.`);
             }
             return {
@@ -2076,7 +2268,7 @@ export class MajikMessage {
         }
         // Option C: raw base64 public key — look up via contact directory
         if (options.publicKeyBase64) {
-            const contact = await this.contactDirectory.getContactByPublicKeyBase64(options.publicKeyBase64);
+            const contact = await this.contacts.getContactByPublicKeyBase64(options.publicKeyBase64);
             if (!contact) {
                 throw new Error(`No contact found for public key "${options.publicKeyBase64}"`);
             }
@@ -2091,34 +2283,11 @@ export class MajikMessage {
         }
         return null;
     }
-    // ── PIN ───────────────────────────────────────────────────────────────────
-    async setPIN(pin) {
-        if (!pin)
-            throw new Error("PIN must be a non-empty string");
-        this.pinHash = await MajikMessage._hashPIN(pin);
-        this.scheduleAutosave();
-    }
-    async clearPIN() {
-        this.pinHash = null;
-        this.scheduleAutosave();
-    }
-    async isValidPIN(pin) {
-        if (!this.pinHash)
-            return true;
-        return (await MajikMessage._hashPIN(pin)) === this.pinHash;
-    }
-    getPinHash() {
-        return this.pinHash ?? null;
-    }
-    static async _hashPIN(pin) {
-        const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(pin));
-        return arrayBufferToBase64(digest);
-    }
     // ── Serialization ─────────────────────────────────────────────────────────
     async toJSON() {
         const json = {
             id: this.id,
-            contacts: await this.contactDirectory.toJSON(),
+            contacts: await this.contacts.toJSON(),
             envelopeCache: this.envelopeCache.toJSON(),
         };
         try {
@@ -2133,14 +2302,14 @@ export class MajikMessage {
         catch (e) {
             console.warn("Failed to serialize ownAccounts:", e);
         }
-        json.pinHash = this.pinHash ?? null;
         return json;
     }
     static async fromJSON(json) {
-        const directory = new MajikContactDirectory();
-        const contacts = await directory.fromJSON(json.contacts);
-        const envelopeCache = EnvelopeCache.fromJSON(json.envelopeCache);
-        const instance = new this({ contactDirectory: contacts, envelopeCache }, json.id);
+        const migratedJSON = migrateMajikMessageJSON(json);
+        // ── Step 2: restore MajikContactManager (directory + groups together) ─
+        const contactManager = await MajikContactManager.fromJSON(migratedJSON.contacts, KEY_ALGO);
+        const envelopeCache = EnvelopeCache.fromJSON(migratedJSON.envelopeCache);
+        const instance = new this({ contactManager, envelopeCache }, migratedJSON.id);
         try {
             if (json.ownAccounts && Array.isArray(json.ownAccounts.accounts)) {
                 for (const acct of json.ownAccounts.accounts) {
@@ -2157,19 +2326,19 @@ export class MajikMessage {
                 if (Array.isArray(json.ownAccounts.order)) {
                     instance.ownAccountsOrder = [...json.ownAccounts.order];
                 }
-                // Fallback: populate from contactDirectory if accounts array failed
+                // Fallback: populate from contacts if accounts array failed
                 if (instance.ownAccounts.size === 0) {
                     for (const id of instance.ownAccountsOrder) {
-                        const c = instance.contactDirectory.getContact(id);
+                        const c = instance.contacts.getContact(id);
                         if (c)
                             instance.ownAccounts.set(id, c);
                     }
                 }
-                // Ensure own accounts are in contactDirectory
+                // Ensure own accounts are in contacts
                 instance.ownAccountsOrder.forEach((id) => {
                     const c = instance.ownAccounts.get(id);
-                    if (c && !instance.contactDirectory.hasContact(c.id)) {
-                        instance.contactDirectory.addContact(c);
+                    if (c && !instance.contacts.hasContact(c.id)) {
+                        instance.contacts.addContact(c);
                     }
                 });
             }
@@ -2177,9 +2346,6 @@ export class MajikMessage {
         catch (e) {
             console.warn("Error restoring ownAccounts:", e);
         }
-        const anyJson = json;
-        if (anyJson.pinHash)
-            instance.pinHash = anyJson.pinHash;
         return instance;
     }
     // ── Persistence ───────────────────────────────────────────────────────────
@@ -2232,7 +2398,7 @@ export class MajikMessage {
             const loaded = await loadSavedMajikFileData(saved.data);
             const restored = await MajikMessage.fromJSON(loaded.j);
             this.id = restored.id;
-            this.contactDirectory = restored.contactDirectory;
+            this.contacts = restored.contacts;
             this.envelopeCache = restored.envelopeCache;
             this.ownAccounts = restored.ownAccounts;
             this.ownAccountsOrder = [...restored.ownAccountsOrder];
@@ -2268,7 +2434,7 @@ export class MajikMessage {
             this.ownAccounts.clear();
             this.ownAccountsOrder = [];
             try {
-                this.contactDirectory.clear();
+                this.contacts.clear();
             }
             catch {
                 /* ignore */
@@ -2279,7 +2445,6 @@ export class MajikMessage {
             catch {
                 /* ignore */
             }
-            this.pinHash = null;
             this.id = arrayToBase64(randomBytes(32));
             try {
                 await clearAllBlobs(userProfile);