@majikah/majik-key 0.1.1

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

@@ -0,0 +1,6 @@
+export declare const KEY_ALGO: {
+    readonly name: "ECDH";
+    readonly namedCurve: "X25519";
+};
+export declare const MAJIK_SALT = "MajikMessageSalt";
+export declare const MAJIK_MNEMONIC_SALT = "MajikMessageMnemonicSalt";

package/dist/core/crypto/constants.js

@@ -0,0 +1,3 @@
+export const KEY_ALGO = { name: "ECDH", namedCurve: "X25519" };
+export const MAJIK_SALT = "MajikMessageSalt";
+export const MAJIK_MNEMONIC_SALT = "MajikMessageMnemonicSalt";

package/dist/core/crypto/crypto-provider.d.ts

@@ -0,0 +1,21 @@
+export declare const IV_LENGTH = 12;
+export declare function generateRandomBytes(len: number): Uint8Array;
+export declare function generateEd25519Keypair(): {
+    edPublic: Uint8Array;
+    edSecret: Uint8Array;
+    xPublic: Uint8Array | null;
+    xSecret: Uint8Array | null;
+};
+export declare function deriveEd25519FromSeed(seed32: Uint8Array): {
+    edPublic: Uint8Array;
+    edSecret: Uint8Array;
+    xPublic: Uint8Array | null;
+    xSecret: Uint8Array | null;
+};
+export declare function fingerprintFromPublicRaw(rawPublic: Uint8Array): string;
+export declare function aesGcmEncrypt(keyBytes: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Uint8Array;
+export declare function aesGcmDecrypt(keyBytes: Uint8Array, iv: Uint8Array, ciphertext: Uint8Array): Uint8Array | null;
+export declare function deriveKeyFromPassphrase(passphrase: string, salt: Uint8Array, iterations?: number, keyLen?: number): Uint8Array;
+export declare function deriveKeyFromMnemonic(mnemonic: string, salt: Uint8Array, iterations?: number, keyLen?: number): Uint8Array;
+export declare function x25519SharedSecret(privRaw: Uint8Array, pubRaw: Uint8Array): Uint8Array;
+export declare function sha256(input: string): string;

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

@@ -0,0 +1,74 @@
+import * as ed25519 from "@stablelib/ed25519";
+import ed2curve from "ed2curve";
+import { AES } from "@stablelib/aes";
+import { GCM } from "@stablelib/gcm";
+import { deriveKey } from "@stablelib/pbkdf2";
+import { hash, SHA256 } from "@stablelib/sha256";
+import * as x25519 from "@stablelib/x25519";
+import { arrayToBase64 } from "../utils";
+export const IV_LENGTH = 12;
+export function generateRandomBytes(len) {
+    const b = new Uint8Array(len);
+    crypto.getRandomValues(b);
+    return b;
+}
+export function generateEd25519Keypair() {
+    const ed = ed25519.generateKeyPair();
+    const pkCurve = ed2curve.convertPublicKey(ed.publicKey);
+    const skCurve = ed2curve.convertSecretKey(ed.secretKey);
+    return {
+        edPublic: ed.publicKey,
+        edSecret: ed.secretKey,
+        xPublic: pkCurve ? new Uint8Array(pkCurve) : null,
+        xSecret: skCurve ? new Uint8Array(skCurve) : null,
+    };
+}
+export function deriveEd25519FromSeed(seed32) {
+    const ed = ed25519.generateKeyPairFromSeed(seed32);
+    const pkCurve = ed2curve.convertPublicKey(ed.publicKey);
+    const skCurve = ed2curve.convertSecretKey(ed.secretKey);
+    return {
+        edPublic: ed.publicKey,
+        edSecret: ed.secretKey,
+        xPublic: pkCurve ? new Uint8Array(pkCurve) : null,
+        xSecret: skCurve ? new Uint8Array(skCurve) : null,
+    };
+}
+export function fingerprintFromPublicRaw(rawPublic) {
+    const digest = hash(rawPublic);
+    return arrayToBase64(digest);
+}
+export function aesGcmEncrypt(keyBytes, iv, plaintext) {
+    const aes = new AES(keyBytes);
+    const gcm = new GCM(aes);
+    return gcm.seal(iv, plaintext);
+}
+export function aesGcmDecrypt(keyBytes, iv, ciphertext) {
+    const aes = new AES(keyBytes);
+    const gcm = new GCM(aes);
+    return gcm.open(iv, ciphertext);
+}
+export function deriveKeyFromPassphrase(passphrase, salt, iterations = 250000, keyLen = 32) {
+    const pw = new TextEncoder().encode(passphrase);
+    return deriveKey(SHA256, pw, salt, iterations, keyLen);
+}
+export function deriveKeyFromMnemonic(mnemonic, salt, iterations = 200000, keyLen = 32) {
+    const m = new TextEncoder().encode(mnemonic);
+    return deriveKey(SHA256, m, salt, iterations, keyLen);
+}
+export function x25519SharedSecret(privRaw, pubRaw) {
+    // Use @stablelib/x25519 for scalar multiplication / shared secret
+    const priv = new Uint8Array(privRaw);
+    const pub = new Uint8Array(pubRaw);
+    if (x25519.scalarMult) {
+        return x25519.scalarMult(priv, pub);
+    }
+    if (x25519.sharedKey) {
+        return x25519.sharedKey(priv, pub);
+    }
+    throw new Error("@stablelib/x25519: compatible API not found");
+}
+export function sha256(input) {
+    const hashed = hash(new TextEncoder().encode(input));
+    return arrayToBase64(hashed);
+}

package/dist/core/crypto/encryption-engine.d.ts

@@ -0,0 +1,36 @@
+export interface EncryptionIdentity {
+    publicKey: CryptoKey | {
+        raw: Uint8Array;
+    };
+    privateKey: CryptoKey | {
+        raw: Uint8Array;
+    };
+    fingerprint: string;
+}
+/**
+ * EncryptionEngine
+ * ----------------
+ * Core cryptographic engine.
+ */
+export declare class EncryptionEngine {
+    /**
+     * Generates a long-term X25519 identity keypair.
+     */
+    static generateIdentity(): Promise<EncryptionIdentity>;
+    /**
+     * Derive an identity deterministically from a BIP39 mnemonic.
+     * Uses Stablelib Ed25519 to derive a keypair from seed and converts to X25519.
+     */
+    static deriveIdentityFromMnemonic(mnemonic: string): Promise<EncryptionIdentity>;
+    /**
+     * Generates a SHA-256 fingerprint from a public key.
+     */
+    static fingerprintFromPublicKey(publicKey: CryptoKey | {
+        raw: Uint8Array;
+    }): Promise<string>;
+    private static assertPublicKey;
+}
+export declare class CryptoError extends Error {
+    cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}

package/dist/core/crypto/encryption-engine.js

@@ -0,0 +1,114 @@
+import { mnemonicToSeedSync } from "@scure/bip39";
+import * as ed25519 from "@stablelib/ed25519";
+import ed2curve from "ed2curve";
+import { fingerprintFromPublicRaw, } from "./crypto-provider";
+/**
+ * EncryptionEngine
+ * ----------------
+ * Core cryptographic engine.
+ */
+export class EncryptionEngine {
+    /* ================================
+     * Identity
+     * ================================ */
+    /**
+     * Generates a long-term X25519 identity keypair.
+     */
+    static async generateIdentity() {
+        try {
+            // Generate an Ed25519 keypair (stablelib) and convert to Curve25519
+            const ed = ed25519.generateKeyPair();
+            const skCurve = ed2curve.convertSecretKey(ed.secretKey);
+            const pkCurve = ed2curve.convertPublicKey(ed.publicKey);
+            if (!skCurve || !pkCurve) {
+                throw new CryptoError("Failed to convert Ed25519 keys to Curve25519");
+            }
+            const pkBytes = new Uint8Array(pkCurve);
+            const skBytes = new Uint8Array(skCurve);
+            // Use raw key wrappers (Stablelib-backed) to avoid WebCrypto import variability
+            const publicKey = { type: "public", raw: pkBytes };
+            const privateKey = { type: "private", raw: skBytes };
+            const fingerprint = fingerprintFromPublicRaw(pkBytes);
+            return { publicKey, privateKey, fingerprint };
+        }
+        catch (err) {
+            throw new CryptoError("Failed to generate identity", err);
+        }
+    }
+    /**
+     * Derive an identity deterministically from a BIP39 mnemonic.
+     * Uses Stablelib Ed25519 to derive a keypair from seed and converts to X25519.
+     */
+    static async deriveIdentityFromMnemonic(mnemonic) {
+        try {
+            if (typeof mnemonic !== "string" || mnemonic.trim().length === 0) {
+                throw new CryptoError("Mnemonic must be a non-empty string");
+            }
+            // Convert mnemonic to seed (64 bytes) then reduce to 32 bytes
+            const seed = mnemonicToSeedSync(mnemonic); // Buffer
+            const seed32 = new Uint8Array(seed.slice(0, 32));
+            // Derive Ed25519 keypair from seed (stablelib)
+            const ed = ed25519.generateKeyPairFromSeed(seed32);
+            // Convert Ed25519 keys to X25519 (curve25519)
+            const skCurve = ed2curve.convertSecretKey(ed.secretKey);
+            const pkCurve = ed2curve.convertPublicKey(ed.publicKey);
+            if (!skCurve || !pkCurve) {
+                throw new CryptoError("Failed to convert derived Ed25519 keys to Curve25519");
+            }
+            // Ensure plain Uint8Array
+            const pkCurveBytes = new Uint8Array(pkCurve);
+            const skCurveBytes = new Uint8Array(skCurve);
+            const publicKey = { type: "public", raw: pkCurveBytes };
+            const privateKey = { type: "private", raw: skCurveBytes };
+            const fingerprint = fingerprintFromPublicRaw(pkCurveBytes);
+            return { publicKey, privateKey, fingerprint };
+        }
+        catch (err) {
+            throw new CryptoError("Failed to derive identity from mnemonic", err);
+        }
+    }
+    /* ================================
+     * Fingerprinting
+     * ================================ */
+    /**
+     * Generates a SHA-256 fingerprint from a public key.
+     */
+    static async fingerprintFromPublicKey(publicKey) {
+        // Accept both CryptoKey and raw wrappers; use stablelib sha256 via provider
+        const anyKey = publicKey;
+        let rawBytes;
+        if (anyKey && anyKey.raw instanceof Uint8Array) {
+            rawBytes = anyKey.raw;
+        }
+        else {
+            this.assertPublicKey(publicKey);
+            const exported = await crypto.subtle.exportKey("raw", publicKey);
+            rawBytes = new Uint8Array(exported);
+        }
+        return fingerprintFromPublicRaw(rawBytes);
+    }
+    /* ================================
+     * Validation Helpers
+     * ================================ */
+    static assertPublicKey(key) {
+        const anyKey = key;
+        if (!key)
+            throw new CryptoError("Invalid public key");
+        if (anyKey.raw instanceof Uint8Array)
+            return; // raw wrapper
+        if (key.type !== "public") {
+            throw new CryptoError("Invalid public key");
+        }
+    }
+}
+/* ================================
+ * Errors
+ * ================================ */
+export class CryptoError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "CryptoError";
+        this.cause = cause;
+    }
+}

package/dist/core/database/system/identity.d.ts

@@ -0,0 +1,61 @@
+import { MajikUser } from "@thezelijah/majik-user";
+import { SerializedMajikContact } from "../../majik-contact";
+export interface MajikMessageIdentityJSON {
+    id: string;
+    user_id: string;
+    public_key: string;
+    phash: string;
+    label: string;
+    timestamp: string;
+    restricted: boolean;
+}
+/**
+ * MajikMessageIdentity
+ * Immutable identity container with integrity verification
+ */
+export declare class MajikMessageIdentity {
+    private readonly _id;
+    private readonly _userId;
+    private readonly _publicKey;
+    private readonly _phash;
+    private _label;
+    private readonly _timestamp;
+    private readonly _restricted;
+    /**
+     * Constructor is private to enforce controlled creation
+     */
+    private constructor();
+    /**
+     * Create a new immutable identity from MajikUser
+     */
+    static create(user: MajikUser, account: SerializedMajikContact, options?: {
+        label?: string;
+        restricted?: boolean;
+    }): MajikMessageIdentity;
+    get id(): string;
+    get userID(): string;
+    get publicKey(): string;
+    get phash(): string;
+    get label(): string;
+    get timestamp(): string;
+    get restricted(): boolean;
+    /**
+     * Only mutable field
+     */
+    set label(label: string);
+    /**
+     * Returns true if identity is restricted
+     */
+    isRestricted(): boolean;
+    /**
+     * Verify identity integrity
+     * Detects tampering of id/public_key
+     */
+    validateIntegrity(): boolean;
+    /**
+     * Explicit verification helper
+     */
+    matches(userId: string, publicKey: string): boolean;
+    toJSON(): MajikMessageIdentityJSON;
+    static fromJSON(json: string | MajikMessageIdentityJSON): MajikMessageIdentity;
+}

package/dist/core/database/system/identity.js

@@ -0,0 +1,171 @@
+import { hash } from "@stablelib/sha256";
+import { arrayToBase64 } from "../../utils";
+/**
+ * Utility assertions
+ */
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+function assertString(value, field) {
+    assert(typeof value === "string" && value.trim().length > 0, `${field} must be a non-empty string`);
+}
+function assertISODate(value, field) {
+    const date = new Date(value);
+    assert(!isNaN(date.getTime()), `${field} must be a valid ISO timestamp`);
+}
+function sha256(input) {
+    const hashed = hash(new TextEncoder().encode(input));
+    return arrayToBase64(hashed);
+}
+/**
+ * MajikMessageIdentity
+ * Immutable identity container with integrity verification
+ */
+export class MajikMessageIdentity {
+    // 🔒 Private backing fields
+    _id;
+    _userId;
+    _publicKey;
+    _phash;
+    _label;
+    _timestamp;
+    _restricted;
+    /**
+     * Constructor is private to enforce controlled creation
+     */
+    constructor(params) {
+        assertString(params.id, "id");
+        assertString(params.userId, "user_id");
+        assertString(params.publicKey, "public_key");
+        assertString(params.phash, "phash");
+        assertString(params.label, "label");
+        assertISODate(params.timestamp, "timestamp");
+        assert(typeof params.restricted === "boolean", "restricted must be boolean");
+        this._id = params.id;
+        this._userId = params.userId;
+        this._publicKey = params.publicKey;
+        this._phash = params.phash;
+        this._label = params.label;
+        this._timestamp = params.timestamp;
+        this._restricted = params.restricted;
+        // Final integrity check at construction
+        assert(this.validateIntegrity(), "Identity integrity validation failed");
+    }
+    // ─────────────────────────────
+    // Static factory
+    // ─────────────────────────────
+    /**
+     * Create a new immutable identity from MajikUser
+     */
+    static create(user, account, options) {
+        assert(user, "MajikUser is required");
+        const userValidResult = user.validate();
+        if (!userValidResult.isValid) {
+            throw new Error(`Invalid MajikUser: ${userValidResult.errors.join(", ")}`);
+        }
+        const label = options?.label || account?.meta?.label || user.displayName;
+        assertString(label, "label");
+        const timestamp = new Date().toISOString();
+        const publicKey = account.publicKeyBase64;
+        const phash = sha256(`${user.id}:${publicKey}:${account.id}`);
+        return new MajikMessageIdentity({
+            id: account.id,
+            userId: user.id,
+            publicKey: publicKey,
+            phash,
+            label,
+            timestamp,
+            restricted: options?.restricted ?? false,
+        });
+    }
+    // ─────────────────────────────
+    // Getters (safe, read-only)
+    // ─────────────────────────────
+    get id() {
+        return this._id;
+    }
+    get userID() {
+        return this._userId;
+    }
+    get publicKey() {
+        return this._publicKey;
+    }
+    get phash() {
+        return this._phash;
+    }
+    get label() {
+        return this._label;
+    }
+    get timestamp() {
+        return this._timestamp;
+    }
+    get restricted() {
+        return this._restricted;
+    }
+    // ─────────────────────────────
+    // Mutators (restricted)
+    // ─────────────────────────────
+    /**
+     * Only mutable field
+     */
+    set label(label) {
+        assertString(label, "label");
+        this._label = label;
+    }
+    // ─────────────────────────────
+    // Identity checks
+    // ─────────────────────────────
+    /**
+     * Returns true if identity is restricted
+     */
+    isRestricted() {
+        return this._restricted === true;
+    }
+    /**
+     * Verify identity integrity
+     * Detects tampering of id/public_key
+     */
+    validateIntegrity() {
+        const expected = sha256(`${this._userId}:${this._publicKey}:${this._id}`);
+        return expected === this._phash;
+    }
+    /**
+     * Explicit verification helper
+     */
+    matches(userId, publicKey) {
+        assertString(userId, "userId");
+        assertString(publicKey, "publicKey");
+        const hash = sha256(`${userId}:${publicKey}:${this._id}`);
+        return hash === this._phash;
+    }
+    // ─────────────────────────────
+    // Serialization
+    // ─────────────────────────────
+    toJSON() {
+        return {
+            id: this._id,
+            user_id: this._userId,
+            public_key: this._publicKey,
+            phash: this._phash,
+            label: this._label,
+            timestamp: this._timestamp,
+            restricted: this._restricted,
+        };
+    }
+    static fromJSON(json) {
+        const obj = typeof json === "string" ? JSON.parse(json) : json;
+        assert(typeof obj === "object" && obj !== null, "Invalid JSON object");
+        const identity = new MajikMessageIdentity({
+            id: obj.id,
+            userId: obj.user_id,
+            publicKey: obj.public_key,
+            phash: obj.phash,
+            label: obj.label,
+            timestamp: obj.timestamp,
+            restricted: obj.restricted,
+        });
+        assert(identity.validateIntegrity(), "Invalid phash in JSON");
+        return identity;
+    }
+}

package/dist/core/error.d.ts

@@ -0,0 +1,4 @@
+export declare class MajikKeyError extends Error {
+    cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}

package/dist/core/error.js

@@ -0,0 +1,11 @@
+/* -------------------------------
+ * Errors
+ * ------------------------------- */
+export class MajikKeyError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "MajikKeyError";
+        this.cause = cause;
+    }
+}

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

@@ -0,0 +1,72 @@
+import { MajikMessageIdentityJSON } from "./database/system/identity";
+import { ISODateString } from "./types";
+export type SerializedMajikContact = Omit<MajikContactData, "publicKey"> & {
+    publicKeyBase64: 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;
+    meta?: MajikContactMeta;
+    majikah_registered?: boolean;
+}
+export interface MajikContactCard {
+    id: string;
+    publicKey: string;
+    fingerprint: string;
+    label: 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;
+    meta: MajikContactMeta;
+    private majikah_registered?;
+    constructor(data: MajikContactData);
+    static create(id: string, publicKey: CryptoKey | {
+        raw: Uint8Array;
+    }, fingerprint: string, meta?: Partial<MajikContactMeta>): MajikContact;
+    private assertId;
+    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;
+}