@thezelijah/majik-message 1.0.0

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

@@ -0,0 +1,135 @@
+import { arrayBufferToBase64 } 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;
+    meta;
+    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;
+    }
+    async toJSON() {
+        // Support both CryptoKey and raw-key wrappers (fallbacks when WebCrypto X25519 unsupported)
+        try {
+            // If it's a CryptoKey, export with SubtleCrypto
+            const raw = await crypto.subtle.exportKey("raw", this.publicKey);
+            return {
+                id: this.id,
+                fingerprint: this.fingerprint,
+                meta: { ...this.meta },
+                publicKeyBase64: arrayBufferToBase64(raw),
+            };
+        }
+        catch (e) {
+            // Fallback: publicKey may be a wrapper with `raw` Uint8Array
+            const maybe = this.publicKey;
+            if (maybe && maybe.raw instanceof Uint8Array) {
+                return {
+                    id: this.id,
+                    fingerprint: this.fingerprint,
+                    meta: { ...this.meta },
+                    publicKeyBase64: arrayBufferToBase64(maybe.raw.buffer),
+                };
+            }
+            throw e;
+        }
+    }
+    static isBlocked(contact) {
+        return !!contact.meta.blocked;
+    }
+}

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

@@ -0,0 +1,7 @@
+import { MAJIK_API_RESPONSE } from "../types";
+export declare const KEY_ALGO: {
+    readonly name: "ECDH";
+    readonly namedCurve: "X25519";
+};
+export declare const MAJIK_SALT = "MajikMessageSalt";
+export declare const API_DEFAULT_FAIL: MAJIK_API_RESPONSE;

package/dist/core/crypto/constants.js

@@ -0,0 +1,6 @@
+export const KEY_ALGO = { name: "ECDH", namedCurve: "X25519" };
+export const MAJIK_SALT = "MajikMessageSalt";
+export const API_DEFAULT_FAIL = {
+    message: "Something went wrong",
+    success: false,
+};

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

@@ -0,0 +1,20 @@
+export declare const IV_LENGTH = 12;
+export declare function generateRandomBytes(len: number): Uint8Array;
+export declare function generateEd25519Keypair(): {
+    edPublic: Uint8Array<ArrayBufferLike>;
+    edSecret: Uint8Array<ArrayBufferLike>;
+    xPublic: Uint8Array<ArrayBuffer> | null;
+    xSecret: Uint8Array<ArrayBuffer> | null;
+};
+export declare function deriveEd25519FromSeed(seed32: Uint8Array): {
+    edPublic: Uint8Array<ArrayBufferLike>;
+    edSecret: Uint8Array<ArrayBufferLike>;
+    xPublic: Uint8Array<ArrayBuffer> | null;
+    xSecret: Uint8Array<ArrayBuffer> | 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;

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

@@ -0,0 +1,70 @@
+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/utilities";
+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");
+}

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

@@ -0,0 +1,59 @@
+import type { MultiRecipientPayload, SingleRecipientPayload } from "../types";
+export interface EncryptionIdentity {
+    publicKey: CryptoKey | {
+        raw: Uint8Array;
+    };
+    privateKey: CryptoKey | {
+        raw: Uint8Array;
+    };
+    fingerprint: string;
+}
+/**
+ * EncryptionEngine
+ * ----------------
+ * Core cryptographic engine for MajikMessage.
+ *
+ * ⚠️ Background-only. Never import this into content scripts.
+ */
+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>;
+    static encryptSoloMessage(plaintext: string, recipientPublicKey: CryptoKey | {
+        raw: Uint8Array;
+    }): Promise<SingleRecipientPayload>;
+    static decryptSoloMessage(payload: SingleRecipientPayload, recipientPrivateKey: CryptoKey | {
+        raw: Uint8Array;
+    }): Promise<string>;
+    static encryptGroupMessage(plaintext: string, recipients: Array<{
+        id: string;
+        publicKey: CryptoKey | {
+            raw: Uint8Array;
+        };
+    }>): Promise<MultiRecipientPayload>;
+    static decryptGroupMessage(payload: MultiRecipientPayload, recipient: CryptoKey | {
+        raw: Uint8Array;
+    }, fingerprint: string): Promise<string>;
+    /**
+     * Generates a SHA-256 fingerprint from a public key.
+     */
+    static fingerprintFromPublicKey(publicKey: CryptoKey | {
+        raw: Uint8Array;
+    }): Promise<string>;
+    private static _extractPublicRaw;
+    private static _extractPrivateRaw;
+    private static assertNonEmptyString;
+    private static assertPublicKey;
+    private static assertPrivateKey;
+    private static assertPayload;
+}
+export declare class CryptoError extends Error {
+    cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}

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

@@ -0,0 +1,257 @@
+import { arrayToBase64, base64ToArrayBuffer } from "../utils/utilities";
+import { mnemonicToSeedSync } from "@scure/bip39";
+import * as ed25519 from "@stablelib/ed25519";
+import ed2curve from "ed2curve";
+import nacl from "tweetnacl";
+import { hash } from "@stablelib/sha256";
+import { x25519SharedSecret, generateRandomBytes, aesGcmEncrypt, aesGcmDecrypt, fingerprintFromPublicRaw, IV_LENGTH, } from "./crypto-provider";
+/**
+ * EncryptionEngine
+ * ----------------
+ * Core cryptographic engine for MajikMessage.
+ *
+ * ⚠️ Background-only. Never import this into content scripts.
+ */
+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);
+        }
+    }
+    /* ================================
+     * Solo Encryption (existing original logic)
+     * ================================ */
+    static async encryptSoloMessage(plaintext, recipientPublicKey) {
+        this.assertNonEmptyString(plaintext);
+        this.assertPublicKey(recipientPublicKey);
+        const recipientRaw = await this._extractPublicRaw(recipientPublicKey);
+        // Ephemeral X25519 keypair
+        const ephPrivate = generateRandomBytes(32);
+        const ephPublic = nacl.scalarMult.base(ephPrivate);
+        // Shared secret -> AES key
+        const shared = x25519SharedSecret(ephPrivate, recipientRaw);
+        const aesKey = hash(shared);
+        const iv = generateRandomBytes(IV_LENGTH);
+        const encoded = new TextEncoder().encode(plaintext);
+        const ciphertext = aesGcmEncrypt(aesKey, iv, encoded);
+        return {
+            iv: arrayToBase64(iv),
+            ciphertext: arrayToBase64(ciphertext),
+            ephemeralPublicKey: arrayToBase64(ephPublic),
+        };
+    }
+    static async decryptSoloMessage(payload, recipientPrivateKey) {
+        this.assertPrivateKey(recipientPrivateKey);
+        this.assertPayload(payload);
+        const privRaw = this._extractPrivateRaw(recipientPrivateKey);
+        const ephRaw = new Uint8Array(base64ToArrayBuffer(payload.ephemeralPublicKey));
+        const shared = x25519SharedSecret(privRaw, ephRaw);
+        const aesKey = hash(shared);
+        const iv = new Uint8Array(base64ToArrayBuffer(payload.iv));
+        const ciphertext = new Uint8Array(base64ToArrayBuffer(payload.ciphertext));
+        const plain = aesGcmDecrypt(aesKey, iv, ciphertext);
+        if (!plain)
+            throw new CryptoError("Decryption failed (auth failed)");
+        return new TextDecoder().decode(plain);
+    }
+    /* ================================
+     * Group Encryption
+     * ================================ */
+    static async encryptGroupMessage(plaintext, recipients) {
+        this.assertNonEmptyString(plaintext);
+        if (!recipients || recipients.length === 0) {
+            throw new CryptoError("No recipients provided");
+        }
+        // Generate ephemeral AES key for the message
+        const aesKey = generateRandomBytes(32);
+        const iv = generateRandomBytes(IV_LENGTH);
+        const encoded = new TextEncoder().encode(plaintext);
+        const ciphertext = aesGcmEncrypt(aesKey, iv, encoded);
+        // Ephemeral X25519 keypair for encrypting AES key
+        const ephPrivate = generateRandomBytes(32);
+        const ephPublic = nacl.scalarMult.base(ephPrivate);
+        const keys = await Promise.all(recipients.map(async (r) => {
+            const recipientRaw = await this._extractPublicRaw(r.publicKey);
+            const shared = x25519SharedSecret(ephPrivate, recipientRaw);
+            const nonce = generateRandomBytes(24); // random per recipient
+            const ephemeralEncryptedKey = nacl.secretbox(aesKey, nonce, shared);
+            return {
+                fingerprint: fingerprintFromPublicRaw(recipientRaw),
+                ephemeralEncryptedKey: arrayToBase64(ephemeralEncryptedKey),
+                nonce: arrayToBase64(nonce),
+            };
+        }));
+        return {
+            iv: arrayToBase64(iv),
+            ciphertext: arrayToBase64(ciphertext),
+            keys,
+            ephemeralPublicKey: arrayToBase64(ephPublic), // needed for decryption
+        };
+    }
+    static async decryptGroupMessage(payload, recipient, fingerprint) {
+        this.assertPrivateKey(recipient);
+        this.assertPayload(payload);
+        const keyEntry = payload.keys.find((k) => k.fingerprint === fingerprint);
+        if (!keyEntry)
+            throw new CryptoError("No encrypted key for this recipient");
+        const privRaw = this._extractPrivateRaw(recipient);
+        const ephPublic = new Uint8Array(base64ToArrayBuffer(payload.ephemeralPublicKey));
+        const shared = x25519SharedSecret(privRaw, ephPublic);
+        const nonce = new Uint8Array(base64ToArrayBuffer(keyEntry.nonce));
+        const encryptedKey = new Uint8Array(base64ToArrayBuffer(keyEntry.ephemeralEncryptedKey));
+        const aesKey = nacl.secretbox.open(encryptedKey, nonce, shared);
+        if (!aesKey)
+            throw new CryptoError("Failed to decrypt AES key for group message");
+        const iv = new Uint8Array(base64ToArrayBuffer(payload.iv));
+        const ciphertext = new Uint8Array(base64ToArrayBuffer(payload.ciphertext));
+        const plain = aesGcmDecrypt(aesKey, iv, ciphertext);
+        if (!plain)
+            throw new CryptoError("Failed to decrypt group message");
+        return new TextDecoder().decode(plain);
+    }
+    /* ================================
+     * 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);
+    }
+    /* ================================
+     * Helpers
+     * ================================ */
+    static async _extractPublicRaw(key) {
+        // Unified stablelib-backed path: export recipient raw public key then do X25519 scalar-mult
+        const recipientAny = key;
+        let recipientRaw;
+        if (recipientAny && recipientAny.raw instanceof Uint8Array) {
+            return (recipientRaw = recipientAny.raw);
+        }
+        else {
+            try {
+                const exported = await crypto.subtle.exportKey("raw", key);
+                recipientRaw = new Uint8Array(exported);
+                return recipientRaw;
+            }
+            catch (e) {
+                throw new CryptoError("Failed to export recipient public key", e);
+            }
+        }
+    }
+    static _extractPrivateRaw(key) {
+        const anyKey = key;
+        if (anyKey.raw instanceof Uint8Array)
+            return anyKey.raw;
+        throw new CryptoError("Cannot extract raw private key");
+    }
+    /* ================================
+     * Validation Helpers
+     * ================================ */
+    static assertNonEmptyString(value) {
+        if (!value || typeof value !== "string") {
+            throw new CryptoError("Plaintext must be a non-empty string");
+        }
+    }
+    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");
+        }
+    }
+    static assertPrivateKey(key) {
+        const anyKey = key;
+        if (!key)
+            throw new CryptoError("Invalid private key");
+        if (anyKey.raw instanceof Uint8Array)
+            return; // raw wrapper
+        if (key.type !== "private") {
+            throw new CryptoError("Invalid private key");
+        }
+    }
+    static assertPayload(payload) {
+        if (!payload?.iv || !payload?.ciphertext) {
+            throw new CryptoError("Malformed encrypted payload");
+        }
+    }
+}
+/* ================================
+ * Errors
+ * ================================ */
+export class CryptoError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "CryptoError";
+        this.cause = cause;
+    }
+}

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

@@ -0,0 +1,126 @@
+export interface KeyStoreIdentity {
+    id: string;
+    publicKey: CryptoKey | {
+        raw: Uint8Array;
+    };
+    fingerprint: string;
+    privateKey?: CryptoKey | {
+        raw: Uint8Array;
+    };
+    encryptedPrivateKey?: ArrayBuffer;
+    unlocked?: boolean;
+}
+export interface SerializedIdentity {
+    id: string;
+    publicKey: string;
+    fingerprint: string;
+    encryptedPrivateKey?: string;
+    salt?: string;
+}
+export declare class KeyStoreError extends Error {
+    cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * KeyStore
+ * ----------------
+ * Secure storage for MajikMessage identities.
+ * Stores public keys and fingerprints in plaintext,
+ * encrypts private keys with a passphrase.
+ *
+ * ⚠️ Background-only. Never expose private keys to content scripts.
+ */
+export declare class KeyStore {
+    private static DB_NAME;
+    private static STORE_NAME;
+    private static DB_VERSION;
+    private static dbPromise;
+    private static unlockedIdentities;
+    static onUnlockRequested?: (id: string) => string | Promise<string>;
+    private static computeChecksum;
+    private static getDB;
+    private static putSerializedIdentity;
+    private static getSerializedIdentity;
+    /**
+     * Validates whether a passphrase can decrypt the stored private key.
+     * Does NOT unlock or mutate any in-memory state.
+     */
+    static isPassphraseValid(id: string, passphrase: string): Promise<boolean>;
+    static updatePassphrase(id: string, currentPassphrase: string, newPassphrase: string): Promise<void>;
+    /**
+     * Check if an identity exists in memory or in storage
+     */
+    static hasIdentity(fingerprint: string): Promise<boolean>;
+    /**
+     * Creates a new identity and stores it securely.
+     */
+    static createIdentity(passphrase: string): Promise<KeyStoreIdentity>;
+    /**
+     * Create a deterministic identity from a mnemonic and store it encrypted with passphrase.
+     * The identity `id` is set to the fingerprint for stable referencing.
+     */
+    static createIdentityFromMnemonic(mnemonic: string, passphrase: string): Promise<KeyStoreIdentity>;
+    /**
+     * Unlocks a stored identity with the passphrase.
+     */
+    static unlockIdentity(id: string, passphrase: string): Promise<KeyStoreIdentity>;
+    /**
+     * Get the private key of an unlocked identity by ID or fingerprint.
+     * Throws if the identity is not found or not unlocked.
+     */
+    static getPrivateKey(idOrFingerprint: string): Promise<CryptoKey | {
+        raw: Uint8Array;
+    }>;
+    /**
+     * Locks a stored identity (removes private key from memory).
+     */
+    static lockIdentity(identity: KeyStoreIdentity): Promise<KeyStoreIdentity>;
+    /**
+     * Gets a stored identity's public key.
+     */
+    static getPublicKey(id: string): Promise<CryptoKey | {
+        raw: Uint8Array;
+    }>;
+    /**
+     * Gets a stored identity's fingerprint.
+     */
+    static getFingerprint(id: string): Promise<string>;
+    private static encryptPrivateKey;
+    private static decryptPrivateKey;
+    private static exportPublicKeyBase64;
+    private static importPublicKeyBase64;
+    /**
+     * Export a stored identity as a compact base64 backup blob (JSON -> base64).
+     * The exported blob contains the encrypted private key (already encrypted with user's passphrase)
+     * so the caller must preserve it securely. This is not a human-readable mnemonic.
+     */
+    static exportIdentityBackup(id: string): Promise<string>;
+    /**
+     * Import an identity backup previously exported via `exportIdentityBackup`.
+     * This stores the serialized identity in IndexedDB. Caller can then call `unlockIdentity`.
+     */
+    static importIdentityBackup(backupBase64: string): Promise<void>;
+    /**
+     * List all serialized identities stored in IndexedDB.
+     */
+    static listStoredIdentities(): Promise<SerializedIdentity[]>;
+    /**
+     * Delete an identity by id from storage and in-memory caches.
+     */
+    static deleteIdentity(id: string): Promise<void>;
+    /**
+     * Generate a BIP39 mnemonic (default 12 words / 128 bits entropy).
+     */
+    static generateMnemonic(strength?: 128): string;
+    /**
+     * Export an identity encrypted with a mnemonic-derived key.
+     * Requires the identity to be unlocked in memory (privateKey available).
+     * Returns a base64 string containing iv+ciphertext and publicKey/fingerprint in JSON.
+     */
+    static exportIdentityMnemonicBackup(id: string, mnemonic: string): Promise<string>;
+    /**
+     * Import an identity from a mnemonic-encrypted backup blob and store it encrypted with `passphrase`.
+     */
+    static importIdentityFromMnemonicBackup(backupBase64: string, mnemonic: string, passphrase: string): Promise<KeyStoreIdentity>;
+    private static deriveKeyFromMnemonic;
+}