@majikah/majik-key 0.1.1

package/dist/core/majik-contact.js

@@ -0,0 +1,195 @@
+/* -------------------------------
+ * Types
+ * ------------------------------- */
+import { arrayBufferToBase64, base64ToArrayBuffer } from "./utils";
+/* -------------------------------
+ * 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;
+    meta;
+    majikah_registered;
+    constructor(data) {
+        this.assertId(data.id);
+        this.assertPublicKey(data.publicKey);
+        this.assertFingerprint(data.fingerprint);
+        this.id = data.id;
+        this.publicKey = data.publicKey;
+        this.fingerprint = data.fingerprint;
+        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, fingerprint, meta) {
+        return new MajikContact({
+            id,
+            publicKey,
+            fingerprint,
+            meta,
+        });
+    }
+    assertId(id) {
+        if (!id || typeof id !== "string") {
+            throw new MajikContactError("Contact ID 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,
+        };
+    }
+    /**
+     * 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,
+            });
+        }
+        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,
+            };
+            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/types.d.ts

@@ -0,0 +1,19 @@
+export type ISODateString = string;
+export type MajikMessageAccountID = string;
+export type MajikMessagePublicKey = string;
+export type MajikMessageChatID = string;
+export interface MajikKeyJSON {
+    id: string;
+    label: string;
+    publicKey: string;
+    fingerprint: string;
+    encryptedPrivateKey: string;
+    salt: string;
+    backup: string;
+    timestamp: string;
+}
+export interface MnemonicJSON {
+    seed: string[];
+    id: string;
+    phrase?: string;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/utils.d.ts

@@ -0,0 +1,28 @@
+import { MnemonicJSON } from "./types";
+export declare function keyToBase64(key: CryptoKey | {
+    raw: Uint8Array;
+}): Promise<string>;
+export declare function base64ToKey(base64: string): Promise<CryptoKey | {
+    raw: Uint8Array;
+}>;
+export declare function arrayToBase64(data: Uint8Array): string;
+export declare function base64ToUint8Array(base64: string): Uint8Array;
+export declare function arrayBufferToBase64(buffer: ArrayBuffer): string;
+export declare function base64ToArrayBuffer(base64: string): ArrayBuffer;
+export declare function base64ToUtf8(base64: string): string;
+export declare function utf8ToBase64(str: string): string;
+export declare function concatArrayBuffers(a: ArrayBuffer, b: ArrayBuffer): ArrayBuffer;
+export declare function concatUint8Arrays(a: Uint8Array, b: Uint8Array): Uint8Array;
+/**
+ * Converts a space-separated seed phrase string into MnemonicJSON
+ */
+export declare function seedToJSON(seed: string, id: string, phrase?: string): MnemonicJSON;
+/**
+ * Converts MnemonicJSON into a single space-separated string
+ */
+export declare function jsonToSeed(json: MnemonicJSON): string;
+export declare function seedStringToArray(seed: string): string[];
+/**
+ * Convert an array of words to a mnemonic string
+ */
+export declare function seedArrayToString(seed: string[]): string;

package/dist/core/utils.js

@@ -0,0 +1,107 @@
+/* ================================
+ * Utilities
+ * ================================ */
+import { KEY_ALGO } from "./crypto/constants";
+export async function keyToBase64(key) {
+    const anyKey = key;
+    if (anyKey && anyKey.raw instanceof Uint8Array) {
+        return arrayBufferToBase64(anyKey.raw.buffer);
+    }
+    const raw = await crypto.subtle.exportKey("raw", key);
+    return arrayBufferToBase64(raw);
+}
+export async function base64ToKey(base64) {
+    const raw = base64ToArrayBuffer(base64);
+    try {
+        return await crypto.subtle.importKey("raw", raw, KEY_ALGO, true, []);
+    }
+    catch (e) {
+        // WebCrypto may not support X25519; return a raw-key wrapper as fallback
+        const ua = new Uint8Array(raw);
+        const wrapper = { type: "public", raw: ua };
+        return wrapper;
+    }
+}
+// utils/utilities.ts
+export function arrayToBase64(data) {
+    let binary = "";
+    const bytes = data;
+    const len = bytes.byteLength;
+    for (let i = 0; i < len; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+export function base64ToUint8Array(base64) {
+    return new Uint8Array(base64ToArrayBuffer(base64));
+}
+export function arrayBufferToBase64(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = "";
+    const chunkSize = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize));
+    }
+    return btoa(binary);
+}
+export function base64ToArrayBuffer(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+}
+export function base64ToUtf8(base64) {
+    const buf = base64ToArrayBuffer(base64);
+    return new TextDecoder().decode(new Uint8Array(buf));
+}
+export function utf8ToBase64(str) {
+    const bytes = new TextEncoder().encode(str);
+    return arrayBufferToBase64(bytes.buffer);
+}
+export function concatArrayBuffers(a, b) {
+    const tmp = new Uint8Array(a.byteLength + b.byteLength);
+    tmp.set(new Uint8Array(a), 0);
+    tmp.set(new Uint8Array(b), a.byteLength);
+    return tmp.buffer;
+}
+export function concatUint8Arrays(a, b) {
+    const out = new Uint8Array(a.byteLength + b.byteLength);
+    out.set(a, 0);
+    out.set(b, a.byteLength);
+    return out;
+}
+/**
+ * Converts a space-separated seed phrase string into MnemonicJSON
+ */
+export function seedToJSON(seed, id, phrase) {
+    return {
+        seed: seed
+            .trim()
+            .split(/\s+/)
+            .map((w) => w.toLowerCase())
+            .filter(Boolean),
+        id,
+        phrase,
+    };
+}
+/**
+ * Converts MnemonicJSON into a single space-separated string
+ */
+export function jsonToSeed(json) {
+    return seedArrayToString(json.seed);
+}
+export function seedStringToArray(seed) {
+    return seed
+        .trim()
+        .split(/\s+/)
+        .map((w) => w.toLowerCase())
+        .filter(Boolean);
+}
+/**
+ * Convert an array of words to a mnemonic string
+ */
+export function seedArrayToString(seed) {
+    return seed.join(" ");
+}

package/dist/core/validator.d.ts

@@ -0,0 +1,10 @@
+import { MajikKeyJSON } from "./types";
+export declare class MajikKeyValidator {
+    static validateMnemonic(mnemonic: string): void;
+    static validatePassphrase(passphrase: string, fieldName?: string): void;
+    static validateLabel(label: string | undefined): void;
+    static validateId(id: string): void;
+    static validateJSON(json: unknown): MajikKeyJSON;
+    static assert(condition: unknown, message: string): asserts condition;
+    static assertString(value: unknown, field: string): asserts value is string;
+}

package/dist/core/validator.js

@@ -0,0 +1,80 @@
+import { validateMnemonic } from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english";
+/* -------------------------------
+ * Validators
+ * ------------------------------- */
+import { MajikKeyError } from "./error";
+export class MajikKeyValidator {
+    static validateMnemonic(mnemonic) {
+        if (!mnemonic || typeof mnemonic !== "string") {
+            throw new MajikKeyError("Mnemonic must be a non-empty string");
+        }
+        const trimmed = mnemonic.trim();
+        if (!trimmed) {
+            throw new MajikKeyError("Mnemonic cannot be empty or whitespace");
+        }
+        if (!validateMnemonic(trimmed, wordlist)) {
+            throw new MajikKeyError("Invalid BIP39 mnemonic phrase");
+        }
+    }
+    static validatePassphrase(passphrase, fieldName = "Passphrase") {
+        if (!passphrase || typeof passphrase !== "string") {
+            throw new MajikKeyError(`${fieldName} must be a non-empty string`);
+        }
+        if (!passphrase.trim()) {
+            throw new MajikKeyError(`${fieldName} cannot be empty or whitespace`);
+        }
+    }
+    static validateLabel(label) {
+        if (label !== undefined && typeof label !== "string") {
+            throw new MajikKeyError("Label must be a string if provided");
+        }
+    }
+    static validateId(id) {
+        if (!id || typeof id !== "string") {
+            throw new MajikKeyError("ID must be a non-empty string");
+        }
+        if (!id.trim()) {
+            throw new MajikKeyError("ID cannot be empty or whitespace");
+        }
+    }
+    static validateJSON(json) {
+        if (!json || typeof json !== "object") {
+            throw new MajikKeyError("Invalid JSON: must be an object");
+        }
+        const obj = json;
+        if (!obj.id || typeof obj.id !== "string") {
+            throw new MajikKeyError("Invalid JSON: missing or invalid 'id' field");
+        }
+        if (!obj.publicKey || typeof obj.publicKey !== "string") {
+            throw new MajikKeyError("Invalid JSON: missing or invalid 'publicKey' field");
+        }
+        if (!obj.fingerprint || typeof obj.fingerprint !== "string") {
+            throw new MajikKeyError("Invalid JSON: missing or invalid 'fingerprint' field");
+        }
+        if (!obj.encryptedPrivateKey ||
+            typeof obj.encryptedPrivateKey !== "string") {
+            throw new MajikKeyError("Invalid JSON: missing or invalid 'encryptedPrivateKey' field");
+        }
+        if (!obj.salt || typeof obj.salt !== "string") {
+            throw new MajikKeyError("Invalid JSON: missing or invalid 'salt' field");
+        }
+        if (!obj.backup || typeof obj.backup !== "string") {
+            throw new MajikKeyError("Invalid JSON: missing or invalid 'backup' field");
+        }
+        if (!obj.timestamp || typeof obj.timestamp !== "string") {
+            throw new MajikKeyError("Invalid JSON: missing or invalid 'timestamp' field");
+        }
+        if (obj.label !== undefined && typeof obj.label !== "string") {
+            throw new MajikKeyError("Invalid JSON: 'label' must be a string if provided");
+        }
+        return obj;
+    }
+    static assert(condition, message) {
+        if (!condition)
+            throw new Error(message);
+    }
+    static assertString(value, field) {
+        this.assert(typeof value === "string" && value.trim().length > 0, `${field} must be a non-empty string`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./majik-key";
+export type * from "./core/types";
+export * from "./core/error";
+export * from "./core/validator";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./majik-key";
+export * from "./core/error";
+export * from "./core/validator";