@majikah/majik-key 0.1.1

package/dist/majik-key.d.ts

@@ -0,0 +1,269 @@
+import { MajikContact } from "./core/majik-contact";
+import { MajikKeyJSON, MnemonicJSON } from "./core/types";
+import { MajikMessageIdentity } from "./core/database/system/identity";
+import { MajikUser } from "@thezelijah/majik-user";
+export interface MajikKeyIdentity {
+    id: string;
+    publicKey: CryptoKey | {
+        raw: Uint8Array;
+    };
+    fingerprint: string;
+    privateKey: CryptoKey | {
+        raw: Uint8Array;
+    };
+    encryptedPrivateKey: ArrayBuffer;
+    salt: string;
+}
+export interface SerializedIdentity {
+    id: string;
+    publicKey: string;
+    fingerprint: string;
+    encryptedPrivateKey?: string;
+    salt?: string;
+}
+export interface MajikKeyConstructorOptions {
+    id: string;
+    publicKey: CryptoKey | {
+        raw: Uint8Array;
+    };
+    publicKeyBase64: string;
+    fingerprint: string;
+    encryptedPrivateKey: ArrayBuffer;
+    encryptedPrivateKeyBase64: string;
+    salt: string;
+    backup: string;
+    label?: string;
+    timestamp?: Date;
+    privateKey?: CryptoKey | {
+        raw: Uint8Array;
+    };
+    privateKeyBase64?: string;
+}
+export interface MajikKeyMetadata {
+    id: string;
+    fingerprint: string;
+    label: string;
+    timestamp: Date;
+    isLocked: boolean;
+}
+/**
+ * MajikKey
+ * ----------------
+ * A seed phrase account library for creating, managing, and parsing mnemonic-based cryptographic accounts (Majik Keys).
+ * Generate deterministic key pairs from BIP39 seed phrases with simple, developer-friendly APIs.
+ */
+export declare class MajikKey {
+    private readonly _id;
+    private readonly _publicKey;
+    private readonly _publicKeyBase64;
+    private readonly _fingerprint;
+    private readonly _backup;
+    private readonly _timestamp;
+    private _encryptedPrivateKey;
+    private _encryptedPrivateKeyBase64;
+    private _salt;
+    private _label;
+    private _privateKey?;
+    private _privateKeyBase64?;
+    private constructor();
+    get id(): string;
+    get fingerprint(): string;
+    get publicKey(): CryptoKey | {
+        raw: Uint8Array;
+    };
+    get publicKeyBase64(): string;
+    get label(): string;
+    get backup(): string;
+    get timestamp(): Date;
+    get isLocked(): boolean;
+    get isUnlocked(): boolean;
+    /**
+     * Get safe metadata (no sensitive data)
+     */
+    get metadata(): MajikKeyMetadata;
+    /**
+     * CREATE: Generate a new MajikKey from a mnemonic phrase.
+     * The key is created in an unlocked state with private keys available.
+     *
+     * @param mnemonic - BIP39 mnemonic phrase (12-24 words)
+     * @param passphrase - Passphrase to encrypt the private key at rest
+     * @param label - Optional label for the key
+     * @returns A new unlocked MajikKey instance
+     */
+    static create(mnemonic: string, passphrase: string, label?: string): Promise<MajikKey>;
+    /**
+     * Export this MajikKey to MnemonicJSON format.
+     * This format is useful for storing mnemonic data with an optional passphrase.
+     *
+     * @param mnemonic - The BIP39 mnemonic phrase
+     * @param passphrase - Optional passphrase (encryption password, not BIP39 passphrase)
+     * @returns MnemonicJSON object
+     */
+    toMnemonicJSON(mnemonic: string, passphrase?: string): MnemonicJSON;
+    /**
+     * Create a MajikKey from MnemonicJSON format.
+     *
+     * @param mnemonicJson - MnemonicJSON object or string
+     * @param passphrase - Passphrase to encrypt the key at rest
+     * @param label - Optional label for the key
+     * @returns A new unlocked MajikKey instance
+     */
+    static fromMnemonicJSON(mnemonicJson: MnemonicJSON | string, passphrase: string, label?: string): Promise<MajikKey>;
+    /**
+     * READ: Load a MajikKey from JSON (locked state).
+     * The key must be unlocked with the unlock() method before accessing private keys.
+     *
+     * @param json - JSON string or object
+     * @returns A locked MajikKey instance
+     */
+    static fromJSON(json: MajikKeyJSON | string): MajikKey;
+    /**
+     * UPDATE: Change the label of this MajikKey.
+     *
+     * @param newLabel - New label value
+     * @returns This instance for chaining
+     */
+    updateLabel(newLabel: string): this;
+    /**
+     * UPDATE: Change the passphrase used to encrypt the private key.
+     * Requires the current passphrase for verification.
+     *
+     * @param currentPassphrase - Current passphrase
+     * @param newPassphrase - New passphrase
+     * @returns This instance for chaining
+     */
+    updatePassphrase(currentPassphrase: string, newPassphrase: string): Promise<this>;
+    /**
+     * DELETE: Securely lock this MajikKey by clearing private keys from memory.
+     * The encrypted private key remains stored for future unlocking.
+     *
+     * @returns This instance for chaining
+     */
+    lock(): this;
+    /**
+     * Unlock this MajikKey by decrypting the private key with the passphrase.
+     * Sets the private key in memory for cryptographic operations.
+     *
+     * @param passphrase - Passphrase to decrypt the private key
+     * @returns This instance for chaining
+     * @throws MajikKeyError if passphrase is incorrect or key is already unlocked
+     */
+    unlock(passphrase: string): Promise<this>;
+    /**
+     * Verify that the encrypted private key can be decrypted with passphrase
+     */
+    verify(passphrase: string): Promise<boolean>;
+    /**
+     * Get the private key (only available when unlocked).
+     *
+     * @returns The private key
+     * @throws MajikKeyError if the key is locked
+     */
+    getPrivateKey(): CryptoKey | {
+        raw: Uint8Array;
+    };
+    /**
+     * Get the private key as base64 (only available when unlocked).
+     *
+     * @returns The private key in base64 format
+     * @throws MajikKeyError if the key is locked
+     */
+    getPrivateKeyBase64(): string;
+    /**
+     * Export this MajikKey to JSON format (safe for storage).
+     * Private keys are never included in the JSON output.
+     *
+     * @returns JSON representation of this MajikKey
+     */
+    toJSON(): MajikKeyJSON;
+    /**
+     * Export this MajikKey to a JSON string.
+     *
+     * @param pretty - Whether to pretty-print the JSON
+     * @returns JSON string representation
+     */
+    toString(pretty?: boolean): string;
+    /**
+     * Generate a new BIP39 mnemonic phrase.
+     *
+     * @param strength - Entropy strength in bits (128 = 12 words, 256 = 24 words)
+     * @returns A new mnemonic phrase
+     */
+    static generateMnemonic(strength?: 128 | 256): string;
+    /**
+     * Validate a BIP39 mnemonic phrase.
+     *
+     * @param mnemonic - Mnemonic phrase to validate
+     * @returns true if valid, false otherwise
+     */
+    static validateMnemonic(mnemonic: string): boolean;
+    /**
+     * Create a MajikContact from this MajikKey.
+     *
+     * @returns A MajikContact instance
+     */
+    toContact(): MajikContact;
+    /**
+     * Convert to internal MajikKeyIdentity format (for backward compatibility).
+     * Note: Only includes privateKey if unlocked.
+     *
+     * @returns MajikKeyIdentity object
+     */
+    toKeyIdentity(): MajikKeyIdentity;
+    /**
+     * Convert to internal SerializedIdentity format (for Majik Message).
+     *
+     * @returns SerializedIdentity object
+     */
+    toSerializedIdentity(): SerializedIdentity;
+    toMajikMessageIdentity(user: MajikUser, options?: {
+        label?: string;
+        restricted?: boolean;
+    }): Promise<MajikMessageIdentity>;
+    /**
+     * Export a mnemonic-encrypted backup for this MajikKey.
+     * Requires the key to be unlocked.
+     *
+     * @param mnemonic - The original mnemonic phrase
+     * @returns Base64-encoded backup string
+     */
+    exportMnemonicBackup(mnemonic: string): Promise<string>;
+    /**
+     * Import a MajikKey from a mnemonic-encrypted backup.
+     *
+     * @param backup - Base64-encoded backup string
+     * @param mnemonic - The mnemonic phrase used to encrypt the backup
+     * @param passphrase - Passphrase to encrypt the imported key
+     * @param label - Optional label for the imported key
+     * @returns A new unlocked MajikKey instance
+     */
+    static importFromMnemonicBackup(backup: string, mnemonic: string, passphrase: string, label?: string): Promise<MajikKey>;
+    /**
+     * Create a deterministic identity from a mnemonic and encrypt it with passphrase.
+     * The identity `id` is set to the fingerprint for stable referencing.
+     */
+    private static createIdentityFromMnemonic;
+    /**
+     * Export an identity encrypted with a mnemonic-derived key.
+     * Returns a base64 string containing iv+ciphertext and publicKey/fingerprint in JSON.
+     */
+    private static exportIdentityMnemonicBackup;
+    /**
+     * Encrypt a private key with a passphrase.
+     */
+    private static encryptPrivateKey;
+    /**
+     * Decrypt a private key with a passphrase.
+     */
+    private static decryptPrivateKey;
+    private static deriveKeyFromMnemonic;
+    /**
+     * Validate whether a passphrase can decrypt the stored private key.
+     * Does NOT unlock or mutate any in-memory state.
+     */
+    private static isPassphraseValid;
+    /**
+     * Export a CryptoKey to base64 string.
+     */
+    private static exportKeyToBase64;
+}