@majikah/majik-key-client

v0.3.0

Published

2 days ago

The base parent client class for Majikah applications, centralizing post-quantum cryptographic account management, keystores, and client state.

0High
0Medium
0Low

thezelijah

majikah majik-key-client majik-key account-management keystore cryptographic-client base-client post-quantum post-quantum-cryptography hybrid-cryptography client-state data-integrity typescript

Majik Key Client

GitHub Sponsors

npm npm downloads

Majik Key Client is the foundational root class that powers all Majikah application clients. It acts as the central orchestration layer for @majikah/majik-key, handling everything from multi-account lifecycle management to client state persistence, so downstream apps (like Majik Signature or Majik Buwiz) get unified, battle-tested cryptographic management out of the box.

Why Majik Key Client?

When building products on top of Majik Key (which turns a BIP-39 mnemonic into a hybrid post-quantum identity), applications consistently need the same infrastructure:

Account Management: Creating, importing, updating, and removing cryptographic identities.
State Persistence: Safely storing locked MajikKey instances in a keystore, tracking which account is active, and persisting user preferences.
Session Security: Providing unified lock/unlock flows, passphrase verification, and lifecycle events.

Instead of duplicating this logic in every app, @majikah/majik-key-client provides it all in a single abstract class: MajikKeyClient.

By extending this class, a child client gets robust, event-driven key management for free, leaving the child class responsible only for its specific domain logic (e.g., managing a contact directory or signing files).

Features

Centralized Keystore Management: Uses MajikKeyManager to seamlessly read and write MajikKey data to any storage adapter (in-memory by default, extensible to SQLite, IndexedDB, etc.).
Client State Synchronization: Manages the ordering of loaded accounts and tracks the currently active identity via MajikKeyClientStateManager.
Event-Driven Architecture: Exposes typed event hooks (new-account, unlock, active-account-change, error, etc.) making it easy to wire up reactive UIs.
Account Hydration & Recovery: Built-in methods to hydrate keys from storage on boot, and robust flows to import or replace accounts from Mnemonic backups.
Agnostic Domain Logic: Deliberately abstracts away the contact directory shape via hooks (_buildOwnAccountContact, _onAccountRegistered, _onAccountRemoved). Subclasses define what a "Contact" looks like in their ecosystem.

Architecture Overview

flowchart TD
    A[12/24-word BIP-39 Seed Phrase] --> B[Majik Key]

    %% Signing branch
    B --> S[Signing]
    S --> S1[Ed25519]
    S --> S2[ML-DSA-87]

    %% Encryption branch
    B --> E[Encryption]
    E --> E1[ML-KEM-768]
    E --> E2[AES-256-GCM]

    %% Identity branch
    B --> I[Identity]
    I --> I1[BIP-39]
    I --> I2[X25519]

    %% Experimental Web3 branch
    B -.-> W[Web3 - Experimental]
    W -.-> W1[Bitcoin - BIP-32/84]
    W -.-> W2[Solana - Ed25519-derived]

    %% Products (fan-in)
    S1 --> P1[Majik Signature]
    S2 --> P1

    S1 --> P2[Majik Buwiz]
    S2 --> P2
    E1 --> P2
    E2 --> P2
    I1 --> P2
    I2 --> P2
    

    E1 --> P3[Majik Message]
    E2 --> P3

    I1 --> P4[Majik Universal ID]
    I2 --> P4

    P4 --> P5[Majik SLink]