@majikah/majik-universal-id-client 0.0.1

package/dist/core/contacts/majik-contact-directory.d.ts

@@ -0,0 +1,37 @@
+import { MAJIK_API_RESPONSE } from "../types";
+import { MajikContact, MajikContactData, SerializedMajikContact } from "./majik-contact";
+export interface MajikContactDirectoryData {
+    contacts: SerializedMajikContact[];
+}
+export declare class MajikContactDirectoryError extends Error {
+    cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare class MajikContactDirectory {
+    private contacts;
+    private fingerprintMap;
+    constructor(initialContacts?: MajikContact[]);
+    addContact(contact: MajikContact): this;
+    addContacts(contacts: MajikContact[]): this;
+    removeContact(id: string): MAJIK_API_RESPONSE;
+    updateContactMeta(id: string, meta: Partial<MajikContactData["meta"]>): MajikContact;
+    getContact(id: string): MajikContact | undefined;
+    getContactByFingerprint(fingerprint: string): MajikContact | undefined;
+    /**
+     * Get contact by public key (base64)
+     * Uses MajikContact.getPublicKeyBase64() for canonical comparison
+     */
+    getContactByPublicKeyBase64(publicKeyBase64: string): Promise<MajikContact | undefined>;
+    hasFingerprint(fingerprint: string): boolean;
+    listContacts(sortedByLabel?: boolean, majikahOnly?: boolean): MajikContact[];
+    blockContact(id: string): MajikContact;
+    unblockContact(id: string): MajikContact;
+    hasContact(id: string): boolean;
+    clear(): this;
+    setMajikahStatus(id: string, status: boolean): MajikContact;
+    isMajikahIdentityChecked(id: string): boolean;
+    isMajikahRegistered(id: string): boolean;
+    toJSON(): Promise<MajikContactDirectoryData>;
+    fromJSON(data: MajikContactDirectoryData): Promise<this>;
+    private assertId;
+}

package/dist/core/contacts/majik-contact-directory.js

@@ -0,0 +1,191 @@
+import { KEY_ALGO } from "../crypto/constants";
+import { base64ToArrayBuffer } from "../utils/utilities";
+import { MajikContact, } from "./majik-contact";
+/* -------------------------------
+ * Errors
+ * ------------------------------- */
+export class MajikContactDirectoryError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "MajikContactDirectoryError";
+        this.cause = cause;
+    }
+}
+/* -------------------------------
+ * MajikContactDirectory Class
+ * ------------------------------- */
+export class MajikContactDirectory {
+    contacts = new Map();
+    fingerprintMap = new Map(); // fingerprint → contact id
+    constructor(initialContacts) {
+        if (initialContacts?.length) {
+            initialContacts.forEach((c) => this.addContact(c));
+        }
+    }
+    /* ================================
+     * Contact Management
+     * ================================ */
+    addContact(contact) {
+        if (!(contact instanceof MajikContact)) {
+            throw new MajikContactDirectoryError("Invalid contact instance");
+        }
+        if (this.contacts.has(contact.id)) {
+            throw new MajikContactDirectoryError(`Contact with id "${contact.id}" already exists`);
+        }
+        this.contacts.set(contact.id, contact);
+        this.fingerprintMap.set(contact.fingerprint, contact.id);
+        return this;
+    }
+    addContacts(contacts) {
+        contacts.forEach((c) => this.addContact(c));
+        return this;
+    }
+    removeContact(id) {
+        this.assertId(id);
+        const contact = this.contacts.get(id);
+        if (contact) {
+            this.fingerprintMap.delete(contact.fingerprint);
+            this.contacts.delete(id);
+            return {
+                message: "Contact removed successfully",
+                success: true,
+            };
+        }
+        else {
+            return {
+                message: "Contact not found",
+                success: false,
+            };
+        }
+    }
+    updateContactMeta(id, meta) {
+        const contact = this.getContact(id);
+        if (!contact)
+            throw new MajikContactDirectoryError("Contact not found");
+        if (meta) {
+            meta.label && contact.updateLabel(meta.label);
+            meta.notes && contact.updateNotes(meta.notes);
+            meta.blocked !== undefined && contact.setBlocked(meta.blocked);
+        }
+        return contact;
+    }
+    getContact(id) {
+        this.assertId(id);
+        return this.contacts.get(id);
+    }
+    getContactByFingerprint(fingerprint) {
+        if (!fingerprint) {
+            throw new MajikContactDirectoryError("Fingerprint must be a non-empty string");
+        }
+        const contactId = this.fingerprintMap.get(fingerprint);
+        return contactId ? this.contacts.get(contactId) : undefined;
+    }
+    /**
+     * Get contact by public key (base64)
+     * Uses MajikContact.getPublicKeyBase64() for canonical comparison
+     */
+    async getContactByPublicKeyBase64(publicKeyBase64) {
+        if (!publicKeyBase64 || typeof publicKeyBase64 !== "string") {
+            throw new MajikContactDirectoryError("Public key must be a non-empty base64 string");
+        }
+        for (const contact of this.contacts.values()) {
+            const contactKey = await contact.getPublicKeyBase64();
+            if (contactKey === publicKeyBase64) {
+                return contact;
+            }
+        }
+        return undefined;
+    }
+    hasFingerprint(fingerprint) {
+        return this.fingerprintMap.has(fingerprint);
+    }
+    listContacts(sortedByLabel = false, majikahOnly = false) {
+        let contacts = [...this.contacts.values()];
+        if (majikahOnly) {
+            contacts = contacts.filter((c) => c.isMajikahRegistered());
+        }
+        if (sortedByLabel) {
+            contacts.sort((a, b) => (a.meta.label || "").localeCompare(b.meta.label || ""));
+        }
+        return contacts;
+    }
+    blockContact(id) {
+        const contact = this.getContact(id);
+        if (!contact)
+            throw new MajikContactDirectoryError(`Contact with id "${id}" not found for block`);
+        return contact.block();
+    }
+    unblockContact(id) {
+        const contact = this.getContact(id);
+        if (!contact)
+            throw new MajikContactDirectoryError(`Contact with id "${id}" not found for unblock`);
+        return contact.unblock();
+    }
+    hasContact(id) {
+        return this.contacts.has(id);
+    }
+    clear() {
+        this.contacts.clear();
+        this.fingerprintMap.clear();
+        return this;
+    }
+    setMajikahStatus(id, status) {
+        const contact = this.getContact(id);
+        if (!contact)
+            throw new MajikContactDirectoryError("Contact not found");
+        contact.setMajikahStatus(status);
+        return contact;
+    }
+    isMajikahIdentityChecked(id) {
+        const contact = this.getContact(id);
+        if (!contact)
+            throw new MajikContactDirectoryError("Contact not found");
+        return contact.isMajikahIdentityChecked();
+    }
+    isMajikahRegistered(id) {
+        const contact = this.getContact(id);
+        if (!contact)
+            throw new MajikContactDirectoryError("Contact not found");
+        return contact.isMajikahRegistered();
+    }
+    /* ================================
+     * Serialization / Persistence
+     * ================================ */
+    async toJSON() {
+        const contactsData = [];
+        for (const contact of this.contacts.values()) {
+            contactsData.push(await contact.toJSON());
+        }
+        return { contacts: contactsData };
+    }
+    async fromJSON(data) {
+        if (!data?.contacts) {
+            throw new MajikContactDirectoryError("Invalid serialized data");
+        }
+        this.clear();
+        for (const item of data.contacts) {
+            const raw = base64ToArrayBuffer(item.publicKeyBase64);
+            let publicKey;
+            try {
+                publicKey = await crypto.subtle.importKey("raw", raw, KEY_ALGO, true, []);
+            }
+            catch (e) {
+                // Fallback: create a raw-key wrapper when the browser does not support the namedCurve
+                publicKey = { raw: new Uint8Array(raw) };
+            }
+            const contact = MajikContact.create(item.id, publicKey, item.mlKey, item.fingerprint, item.meta);
+            this.contacts.set(contact.id, contact);
+            this.fingerprintMap.set(contact.fingerprint, contact.id);
+        }
+        return this;
+    }
+    /* ================================
+     * Validation Helpers
+     * ================================ */
+    assertId(id) {
+        if (!id || typeof id !== "string") {
+            throw new MajikContactDirectoryError("Contact ID must be a non-empty string");
+        }
+    }
+}

package/dist/core/contacts/majik-contact.d.ts

@@ -0,0 +1,89 @@
+import { ISODateString } from "../../core/types";
+import { MajikMessageIdentityJSON } from "../identity";
+export type SerializedMajikContact = {
+    id: string;
+    fingerprint: string;
+    meta?: MajikContactMeta;
+    publicKeyBase64: string;
+    mlKey: string;
+    majikah_registered?: boolean;
+    edPublicKeyBase64?: string;
+    mlDsaPublicKeyBase64?: string;
+};
+export interface MajikContactMeta {
+    label?: string;
+    notes?: string;
+    blocked?: boolean;
+    createdAt?: ISODateString;
+    updatedAt?: ISODateString;
+}
+export interface MajikContactData {
+    id: string;
+    publicKey: CryptoKey | {
+        raw: Uint8Array;
+    };
+    fingerprint: string;
+    mlKey: string;
+    meta?: MajikContactMeta;
+    majikah_registered?: boolean;
+    edPublicKeyBase64?: string;
+    mlDsaPublicKeyBase64?: string;
+}
+export interface MajikContactCard {
+    id: string;
+    publicKey: string;
+    fingerprint: string;
+    label: string;
+    mlKey: string;
+    edPublicKeyBase64?: string;
+    mlDsaPublicKeyBase64?: string;
+}
+export declare class MajikContactError extends Error {
+    cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare class MajikContact {
+    readonly id: string;
+    readonly publicKey: CryptoKey | {
+        raw: Uint8Array;
+    };
+    readonly fingerprint: string;
+    readonly mlKey: string;
+    readonly edPublicKeyBase64: string;
+    readonly mlDsaPublicKeyBase64: string;
+    meta: MajikContactMeta;
+    private majikah_registered?;
+    constructor(data: MajikContactData);
+    static create(id: string, publicKey: CryptoKey | {
+        raw: Uint8Array;
+    }, mlKey: string, fingerprint: string, meta?: Partial<MajikContactMeta>): MajikContact;
+    private assertId;
+    private assertMLKey;
+    private assertPublicKey;
+    private assertFingerprint;
+    private updateTimestamp;
+    updateLabel(label: string): this;
+    updateNotes(notes: string): this;
+    isBlocked(): boolean;
+    setBlocked(blocked: boolean): this;
+    block(): this;
+    unblock(): this;
+    isMajikahIdentityChecked(): boolean;
+    isMajikahRegistered(): boolean;
+    setMajikahStatus(status: boolean): this;
+    getDisplayName(): Promise<string>;
+    /**
+     * Support both CryptoKey and raw-key wrappers (fallbacks when WebCrypto X25519 unsupported)
+     */
+    getPublicKeyBase64(): Promise<string>;
+    toJSON(): Promise<SerializedMajikContact>;
+    /**
+     * Reconstruct a MajikContact from its serialized form
+     */
+    static fromJSON(serialized: SerializedMajikContact): MajikContact;
+    /**
+     * Create a new MajikContact from a MajikMessageIdentityJSON
+     */
+    static fromIdentityJSON(identityJSON: MajikMessageIdentityJSON): Promise<MajikContact>;
+    static isBlocked(contact: MajikContact): boolean;
+}

package/dist/core/contacts/majik-contact.js

@@ -0,0 +1,212 @@
+import { arrayBufferToBase64, base64ToArrayBuffer } from "../utils/utilities";
+/* -------------------------------
+ * Errors
+ * ------------------------------- */
+export class MajikContactError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "MajikContactError";
+        this.cause = cause;
+    }
+}
+/* -------------------------------
+ * MajikContact Class
+ * ------------------------------- */
+export class MajikContact {
+    id;
+    publicKey;
+    fingerprint;
+    mlKey;
+    edPublicKeyBase64;
+    mlDsaPublicKeyBase64;
+    meta;
+    majikah_registered;
+    constructor(data) {
+        this.assertId(data.id);
+        this.assertPublicKey(data.publicKey);
+        this.assertMLKey(data.mlKey);
+        this.assertFingerprint(data.fingerprint);
+        this.id = data.id;
+        this.publicKey = data.publicKey;
+        this.fingerprint = data.fingerprint;
+        this.mlKey = data.mlKey;
+        this.edPublicKeyBase64 = data.edPublicKeyBase64 || "";
+        this.mlDsaPublicKeyBase64 = data.mlDsaPublicKeyBase64 || "";
+        this.meta = {
+            label: data.meta?.label || "",
+            notes: data.meta?.notes || "",
+            blocked: data.meta?.blocked || false,
+            createdAt: data.meta?.createdAt || new Date().toISOString(),
+            updatedAt: data.meta?.updatedAt || new Date().toISOString(),
+        };
+    }
+    static create(id, publicKey, mlKey, fingerprint, meta) {
+        return new MajikContact({
+            id,
+            publicKey,
+            fingerprint,
+            meta,
+            mlKey,
+        });
+    }
+    assertId(id) {
+        if (!id || typeof id !== "string") {
+            throw new MajikContactError("Contact ID must be a non-empty string");
+        }
+    }
+    assertMLKey(key) {
+        if (!key || typeof key !== "string") {
+            throw new MajikContactError("ML Key must be a non-empty string");
+        }
+    }
+    assertPublicKey(key) {
+        // Accept either a WebCrypto CryptoKey (with .type === 'public')
+        // or a raw-key wrapper object that contains a Uint8Array `raw` field.
+        if (!key)
+            throw new MajikContactError("Invalid public key");
+        const anyKey = key;
+        if (anyKey && typeof anyKey === "object") {
+            if (anyKey.type === "public")
+                return;
+            if (anyKey.raw instanceof Uint8Array)
+                return;
+        }
+        throw new MajikContactError("Invalid public key");
+    }
+    assertFingerprint(fingerprint) {
+        if (!fingerprint || typeof fingerprint !== "string") {
+            throw new MajikContactError("Fingerprint must be a non-empty string");
+        }
+    }
+    updateTimestamp() {
+        this.meta.updatedAt = new Date().toISOString();
+    }
+    updateLabel(label) {
+        if (typeof label !== "string")
+            throw new MajikContactError("Label must be a string");
+        this.meta.label = label;
+        this.updateTimestamp();
+        return this;
+    }
+    updateNotes(notes) {
+        if (typeof notes !== "string")
+            throw new MajikContactError("Notes must be a string");
+        this.meta.notes = notes;
+        this.updateTimestamp();
+        return this;
+    }
+    isBlocked() {
+        return this.meta.blocked || false;
+    }
+    setBlocked(blocked) {
+        if (typeof blocked !== "boolean")
+            throw new MajikContactError("Blocked must be boolean");
+        this.meta.blocked = blocked;
+        this.updateTimestamp();
+        return this;
+    }
+    // Idempotent block/unblock for safe scanning
+    block() {
+        if (!this.isBlocked())
+            this.setBlocked(true);
+        return this;
+    }
+    unblock() {
+        if (this.isBlocked())
+            this.setBlocked(false);
+        return this;
+    }
+    isMajikahIdentityChecked() {
+        return this.majikah_registered !== undefined;
+    }
+    isMajikahRegistered() {
+        return this.majikah_registered || false;
+    }
+    setMajikahStatus(status) {
+        this.majikah_registered = status;
+        return this;
+    }
+    async getDisplayName() {
+        return this.meta.label || (await this.getPublicKeyBase64());
+    }
+    /**
+     * Support both CryptoKey and raw-key wrappers (fallbacks when WebCrypto X25519 unsupported)
+     */
+    async getPublicKeyBase64() {
+        try {
+            // If it's a CryptoKey, export with SubtleCrypto
+            const raw = await crypto.subtle.exportKey("raw", this.publicKey);
+            return arrayBufferToBase64(raw);
+        }
+        catch (e) {
+            // Fallback: publicKey may be a wrapper with `raw` Uint8Array
+            const maybe = this.publicKey;
+            if (maybe && maybe.raw instanceof Uint8Array) {
+                return arrayBufferToBase64(maybe.raw.buffer);
+            }
+            throw e;
+        }
+    }
+    async toJSON() {
+        return {
+            id: this.id,
+            fingerprint: this.fingerprint,
+            meta: { ...this.meta },
+            publicKeyBase64: await this.getPublicKeyBase64(),
+            majikah_registered: this.majikah_registered,
+            mlKey: this.mlKey,
+            edPublicKeyBase64: this.edPublicKeyBase64,
+            mlDsaPublicKeyBase64: this.mlDsaPublicKeyBase64,
+        };
+    }
+    /**
+     * Reconstruct a MajikContact from its serialized form
+     */
+    static fromJSON(serialized) {
+        try {
+            const publicKeyRaw = new Uint8Array(base64ToArrayBuffer(serialized.publicKeyBase64));
+            return new MajikContact({
+                id: serialized.id,
+                fingerprint: serialized.fingerprint,
+                meta: serialized.meta,
+                publicKey: { raw: publicKeyRaw },
+                majikah_registered: serialized.majikah_registered,
+                mlKey: serialized.mlKey,
+                edPublicKeyBase64: serialized.edPublicKeyBase64,
+                mlDsaPublicKeyBase64: serialized.mlDsaPublicKeyBase64,
+            });
+        }
+        catch (err) {
+            throw new MajikContactError("Failed to deserialize MajikContact", err);
+        }
+    }
+    /**
+     * Create a new MajikContact from a MajikMessageIdentityJSON
+     */
+    static async fromIdentityJSON(identityJSON) {
+        try {
+            const publicKeyRaw = new Uint8Array(base64ToArrayBuffer(identityJSON.public_key));
+            const contactData = {
+                id: identityJSON.id,
+                publicKey: { raw: publicKeyRaw },
+                fingerprint: identityJSON.id,
+                meta: {
+                    label: identityJSON.label,
+                    createdAt: identityJSON.timestamp,
+                    updatedAt: identityJSON.timestamp,
+                    blocked: identityJSON.restricted,
+                },
+                majikah_registered: true,
+                mlKey: identityJSON.ml_key,
+            };
+            return new MajikContact(contactData);
+        }
+        catch (err) {
+            throw new MajikContactError("Failed to create MajikContact from MajikMessageIdentityJSON", err);
+        }
+    }
+    static isBlocked(contact) {
+        return !!contact.meta.blocked;
+    }
+}

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

@@ -0,0 +1,56 @@
+export declare const KEY_ALGO: {
+    readonly name: "ECDH";
+    readonly namedCurve: "X25519";
+};
+export declare const MAJIK_SALT = "MajikMessageSalt";
+export declare const MAJIK_MNEMONIC_SALT = "MajikMessageMnemonicSalt";
+/**
+ * KDF version identifiers.
+ * Stored alongside every encrypted private key blob so the correct
+ * derivation function is always used on decryption.
+ */
+export declare const KDF_VERSION: {
+    readonly PBKDF2: 1;
+    readonly ARGON2ID: 2;
+};
+export type KDF_VERSION = (typeof KDF_VERSION)[keyof typeof KDF_VERSION];
+/**
+ * Argon2id parameters.
+ *
+ * PASSPHRASE (protecting the private key at rest):
+ *   m=131072 (128 MB) — double OWASP "high security" tier (64 MB)
+ *   t=4               — 4 passes
+ *   p=4               — 4 parallel lanes
+ *
+ * Benchmark targets (approximate):
+ *   Modern laptop (2020+):          ~600–900ms  ✓
+ *   Mid-range desktop (2018):       ~800–1200ms ✓
+ *   Low-end / older machine:        ~1500–2500ms — acceptable for a one-time unlock
+ *   RTX 4090 brute-force attack:    ~1–3 guesses/sec vs ~400,000/sec for PBKDF2
+ *   Improvement over current PBKDF2: ~100,000–400,000×
+ *
+ * MNEMONIC BACKUP (protecting exported backup files):
+ *   m=65536 (64 MB) — lower because the mnemonic itself is 128-bit entropy;
+ *                     the KDF is a domain separator, not a weak-password defense.
+ *   t=3
+ *   p=2
+ *
+ * If benchmarks on your lowest-spec target device exceed 3s for the passphrase
+ * parameters, reduce m to 65536 (64 MB) and t to 3. That is still ~50,000×
+ * harder than the current PBKDF2 setup.
+ */
+export declare const ARGON2_PARAMS: {
+    readonly PASSPHRASE: {
+        readonly m: 131072;
+        readonly t: 4;
+        readonly p: 4;
+        readonly dkLen: 32;
+    };
+    readonly MNEMONIC: {
+        readonly m: 65536;
+        readonly t: 3;
+        readonly p: 2;
+        readonly dkLen: 32;
+    };
+};
+export type ARGON2_PARAMS = (typeof ARGON2_PARAMS)[keyof typeof ARGON2_PARAMS];

package/dist/core/crypto/constants.js

@@ -0,0 +1,51 @@
+export const KEY_ALGO = { name: "ECDH", namedCurve: "X25519" };
+export const MAJIK_SALT = "MajikMessageSalt";
+export const MAJIK_MNEMONIC_SALT = "MajikMessageMnemonicSalt";
+/**
+ * KDF version identifiers.
+ * Stored alongside every encrypted private key blob so the correct
+ * derivation function is always used on decryption.
+ */
+export const KDF_VERSION = {
+    PBKDF2: 1, // legacy — read-only support for existing accounts
+    ARGON2ID: 2, // current — all new accounts and re-encryptions
+};
+/**
+ * Argon2id parameters.
+ *
+ * PASSPHRASE (protecting the private key at rest):
+ *   m=131072 (128 MB) — double OWASP "high security" tier (64 MB)
+ *   t=4               — 4 passes
+ *   p=4               — 4 parallel lanes
+ *
+ * Benchmark targets (approximate):
+ *   Modern laptop (2020+):          ~600–900ms  ✓
+ *   Mid-range desktop (2018):       ~800–1200ms ✓
+ *   Low-end / older machine:        ~1500–2500ms — acceptable for a one-time unlock
+ *   RTX 4090 brute-force attack:    ~1–3 guesses/sec vs ~400,000/sec for PBKDF2
+ *   Improvement over current PBKDF2: ~100,000–400,000×
+ *
+ * MNEMONIC BACKUP (protecting exported backup files):
+ *   m=65536 (64 MB) — lower because the mnemonic itself is 128-bit entropy;
+ *                     the KDF is a domain separator, not a weak-password defense.
+ *   t=3
+ *   p=2
+ *
+ * If benchmarks on your lowest-spec target device exceed 3s for the passphrase
+ * parameters, reduce m to 65536 (64 MB) and t to 3. That is still ~50,000×
+ * harder than the current PBKDF2 setup.
+ */
+export const ARGON2_PARAMS = {
+    PASSPHRASE: {
+        m: 131072, // memory in KB (128 MB)
+        t: 4, // time cost (passes)
+        p: 4, // parallelism (lanes)
+        dkLen: 32, // output length in bytes (256-bit AES key)
+    },
+    MNEMONIC: {
+        m: 65536, // 64 MB
+        t: 3,
+        p: 2,
+        dkLen: 32,
+    },
+};