@majikah/majik-key 0.2.12 → 0.2.14

package/README.md

@@ -1,936 +1,392 @@
 # Majik Key
 
-[![Developed by Zelijah](https://img.shields.io/badge/Developed%20by-Zelijah-red?logo=github&logoColor=white)](https://thezelijah.world) ![GitHub Sponsors](https://img.shields.io/github/sponsors/jedlsf?style=plastic&label=Sponsors&link=https%3A%2F%2Fgithub.com%2Fsponsors%2Fjedlsf)
-
-**Majik Key** is a next-generation seed phrase account library for creating and managing mnemonic-based identities. It provides a post-quantum ready, high-security bridge between BIP39 mnemonics and the Majikah ecosystem.
-
-![npm](https://img.shields.io/npm/v/@majikah/majik-key) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-key) ![npm bundle size](https://img.shields.io/bundlephobia/min/%40majikah%2Fmajik-key) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
-
+[![Developed by Zelijah](https://img.shields.io/badge/Developed%20by-Zelijah-red?logo=github&logoColor=white)](https://www.thezelijah.world) ![GitHub Sponsors](https://img.shields.io/github/sponsors/jedlsf?style=plastic&label=Sponsors&link=https%3A%2F%2Fgithub.com%2Fsponsors%2Fjedlsf)
+![npm](https://img.shields.io/npm/v/@majikah/majik-key) ![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-key) ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
+**Majik Key** turns a single BIP-39 mnemonic into a complete cryptographic identity — encryption, classical + post-quantum signing, and (experimentally) Bitcoin and Solana keys — encrypted at rest and ready to plug into the rest of the Majikah ecosystem.
 
 ---
-- [Majik Key](#majik-key)
-  - [Next-Gen Security Architecture](#next-gen-security-architecture)
-    - [1. Post-Quantum Ready (ML-KEM)](#1-post-quantum-ready-ml-kem)
-    - [2. Argon2id Key Derivation](#2-argon2id-key-derivation)
-    - [3. Seamless Auto-Migration](#3-seamless-auto-migration)
-  - [Overview](#overview)
-    - [What is a Majik Key?](#what-is-a-majik-key)
-    - [Use Cases](#use-cases)
-  - [Features](#features)
-    - [Security \& Post-Quantum Readiness](#security--post-quantum-readiness)
-    - [BIP39 Compliance \& Key Derivation](#bip39-compliance--key-derivation)
-    - [Developer Experience](#developer-experience)
-    - [Import / Export \& Storage](#import--export--storage)
-    - [Interoperability](#interoperability)
-  - [Installation](#installation)
-  - [Quick Start](#quick-start)
-  - [API Reference](#api-reference)
-    - [Static Methods](#static-methods)
-      - [`MajikKey.create(mnemonic, passphrase, label?)`](#majikkeycreatemnemonic-passphrase-label)
-      - [`MajikKey.fromJSON(json)`](#majikkeyfromjsonjson)
-      - [`MajikKey.fromMnemonicJSON(mnemonicJson, passphrase, label?)`](#majikkeyfrommnemonicjsonmnemonicjson-passphrase-label)
-      - [`MajikKey.importFromMnemonicBackup(backup, mnemonic, passphrase, label?)`](#majikkeyimportfrommnemonicbackupbackup-mnemonic-passphrase-label)
-      - [`MajikKey.generateMnemonic(strength?)`](#majikkeygeneratemnemonicstrength)
-      - [`MajikKey.validateMnemonic(mnemonic)`](#majikkeyvalidatemnemonicmnemonic)
-    - [Instance Methods](#instance-methods)
-      - [`unlock(passphrase)`](#unlockpassphrase)
-      - [`lock()`](#lock)
-      - [`verify(passphrase)`](#verifypassphrase)
-      - [`updateLabel(newLabel)`](#updatelabelnewlabel)
-      - [`updatePassphrase(currentPassphrase, newPassphrase)`](#updatepassphrasecurrentpassphrase-newpassphrase)
-      - [`getPrivateKey()`](#getprivatekey)
-      - [`getPrivateKeyBase64()`](#getprivatekeybase64)
-      - [`toJSON()`](#tojson)
-      - [`toString(pretty?)`](#tostringpretty)
-      - [`toMnemonicJSON(mnemonic, passphrase?)`](#tomnemonicjsonmnemonic-passphrase)
-      - [`exportMnemonicBackup(mnemonic)`](#exportmnemonicbackupmnemonic)
-      - [`toContact()`](#tocontact)
-      - [`toMajikMessageIdentity(user, options?)`](#tomajikmessageidentityuser-options)
-    - [Getters](#getters)
-      - [`id: string`](#id-string)
-      - [`fingerprint: string`](#fingerprint-string)
-      - [`publicKey: CryptoKey | { raw: Uint8Array }`](#publickey-cryptokey---raw-uint8array-)
-      - [`publicKeyBase64: string`](#publickeybase64-string)
-      - [`label: string`](#label-string)
-      - [`backup: string`](#backup-string)
-      - [`timestamp: Date`](#timestamp-date)
-      - [`isLocked: boolean`](#islocked-boolean)
-      - [`isUnlocked: boolean`](#isunlocked-boolean)
-      - [`metadata: MajikKeyMetadata`](#metadata-majikkeymetadata)
-  - [Usage Examples](#usage-examples)
-    - [Example 1: Create and Manage a Key](#example-1-create-and-manage-a-key)
-    - [Example 2: Lock/Unlock Pattern](#example-2-lockunlock-pattern)
-    - [Example 3: Backup and Recovery](#example-3-backup-and-recovery)
-    - [Example 4: Update Passphrase](#example-4-update-passphrase)
-    - [Example 5: Verify Passphrase](#example-5-verify-passphrase)
-  - [Integration with Majik Message](#integration-with-majik-message)
-    - [Importing to Majik Message](#importing-to-majik-message)
-    - [Converting to Majik Message Identity](#converting-to-majik-message-identity)
-  - [Security Considerations](#security-considerations)
-    - [Best Practices](#best-practices)
-    - [What NOT to Do](#what-not-to-do)
-    - [What TO Do](#what-to-do)
-    - [Tips \& Reminders](#tips--reminders)
-      - [For Developers](#for-developers)
-      - [For Users](#for-users)
-  - [Related Projects](#related-projects)
-    - [Majik Message](#majik-message)
-  - [Contributing](#contributing)
-  - [License](#license)
-  - [Author](#author)
-  - [About the Developer](#about-the-developer)
-  - [Contact](#contact)
-
 
+## Why Majik Key
 
+- **One seed, one identity, five key pairs.** A 12- or 24-word mnemonic deterministically derives X25519, ML-KEM-768, Ed25519, ML-DSA-87, and (by default) a domain-separated Bitcoin key — all reproducible from the mnemonic alone.
+- **Post-quantum from day one.** Every account gets an ML-KEM-768 (FIPS-203) encryption keypair and an ML-DSA-87 signing keypair alongside their classical counterparts (X25519, Ed25519) — no separate migration project required later.
+- **Encrypted at rest, always.** Private key material is never persisted in plaintext. Everything is AES-256-GCM encrypted using a key derived with Argon2id.
+- **Local-first.** Key generation and derivation run entirely offline — no network request is made in the process, verifiable directly in source.
+- **Built for the Majikah ecosystem**, but usable standalone in any TypeScript/JavaScript project.
 
 ---
 
-## Next-Gen Security Architecture
+## Security Architecture
 
-Majik Key has been upgraded to meet modern and future cryptographic standards.
+- **Encrypted at rest, not "hashed."** Private keys are **AES-256-GCM encrypted**, using a 256-bit key **derived via Argon2id** from your passphrase. (Argon2id is a key-derivation function, not applied to the private key directly — the private key itself is encrypted, not hashed.)
+- **Argon2id KDF (v2), memory-hard by design.** Passphrase-based encryption uses Argon2id at **64 MB memory / 3 iterations / 4 parallel lanes**, tuned to resist GPU/ASIC brute-force attacks. A WASM implementation (`hash-wasm`) is used when available in the runtime, with an automatic, transparent fallback to a pure-JS implementation (`@noble/hashes`) — output is bit-identical either way, so switching implementations never breaks decryption.
+- **Post-quantum ready.** ML-KEM-768 (FIPS-203) is derived from the full 64-byte BIP-39 seed for encryption/key-encapsulation, and ML-DSA-87 is derived from a domain-separated hash of that same seed for signing — both deterministic and fully recoverable from the mnemonic.
+- **Legacy KDF read support.** Older accounts encrypted with KDF v1 (PBKDF2-SHA256, 200k–250k iterations) can still be unlocked. New accounts, and any account whose passphrase is changed via `updatePassphrase()`, always land on Argon2id (v2).
+- **Full migration path.** `importFromMnemonicBackup()` re-derives a complete identity straight from the mnemonic — X25519, ML-KEM-768, Ed25519, ML-DSA-87, and Bitcoin — and re-encrypts everything with Argon2id in one step, so an old account becomes fully post-quantum capable automatically. A lighter `migrate()` method is also available if you only want to upgrade the KDF version without re-deriving the newer key types.
+- **Isomorphic by design.** Uses native WebCrypto (ECDH/X25519) where the runtime supports it, and transparently falls back to a raw keypair representation where it doesn't (e.g. Node environments without X25519 in WebCrypto) — the public API is identical either way.
+- **Multi-language mnemonics.** BIP-39 wordlists for English, French, Spanish, Italian, Japanese, Korean, Czech, Portuguese, Simplified Chinese, and Traditional Chinese are supported, lazy-loaded per language so you only pay for the ones you use.
 
-### 1. Post-Quantum Ready (ML-KEM)
-Every identity now generates a dual-key system derived deterministically from a 64-byte BIP39 seed:
-* **X25519 (Curve25519):** Derived from the first 32 bytes of the seed. Used for fingerprints, contact identity, and legacy compatibility.
-* **ML-KEM-768 (FIPS-203):** Derived from the full 64-byte seed. Provides post-quantum key encapsulation for "v3" secure envelopes.
-
-### 2. Argon2id Key Derivation
-We have transitioned to **Argon2id** (KDF v2) for encrypting private keys at rest.
-* **Memory-Hard:** Configured with 64 MB of memory, 3 iterations, and 4 parallelism factors.
-* **Brute-Force Resistant:** Engineered to defeat GPU and ASIC-based cracking attempts that easily bypass older PBKDF2 implementations.
-
-### 3. Seamless Auto-Migration
-The library handles "Security Debt" automatically during standard workflows:
-* **On Import:** `importFromMnemonicBackup()` detects v1 (PBKDF2) accounts and performs a full upgrade to v2. 
-* **Deterministic Recovery:** If ML-KEM keys are missing from an old backup, they are re-derived from the mnemonic during the upgrade process.
-* **Password Updates:** Changing a passphrase via `updatePassphrase()` automatically migrates the account to the latest Argon2id standard.
 ---
 
+## Architecture
 
+```mermaid
+flowchart TD
+    A[12/24-word BIP-39 Seed Phrase] --> B[Majik Key]
 
-## Overview
+    %% Signing branch
+    B --> S[Signing]
+    S --> S1[Ed25519]
+    S --> S2[ML-DSA-87]
 
-**Majik Key** is a comprehensive library for managing seed phrase-based cryptographic accounts. It provides a secure, intuitive way to create, store, and manage mnemonic-based identities with built-in encryption, backup, and recovery features.
+    %% Encryption branch
+    B --> E[Encryption]
+    E --> E1[ML-KEM-768]
+    E --> E2[AES-256-GCM]
 
-### What is a Majik Key?
+    %% Identity branch
+    B --> I[Identity]
+    I --> I1[BIP-39]
+    I --> I2[X25519]
 
-A Majik Key is a seed phrase account that:
-- Derives cryptographic key pairs from BIP39 mnemonic phrases
-- Encrypts private keys at rest with a user-defined passphrase
-- Supports secure backup and recovery via mnemonic encryption
-- Provides locked/unlocked state management for enhanced security
-- Is fully compatible with **Majik Message** and other Majikah products
+    %% Experimental Web3 branch
+    B -.-> W[Web3 - Experimental]
+    W -.-> W1[Bitcoin - BIP-32/84]
+    W -.-> W2[Solana - Ed25519-derived]
 
-### Use Cases
+    %% Products (fan-in)
+    S1 --> P1[Majik Signature]
+    S2 --> P1
 
-- **Majik Message Integration**: Create seed phrase accounts that can be imported directly into Majik Message
-- **Cryptographic Identity Management**: Manage multiple identities with deterministic key derivation
-- **Secure Messaging**: Generate signing keys for end-to-end encrypted communication
-- **Blockchain Applications**: Create wallet-like accounts from mnemonic phrases
-- **Majikah Ecosystem**: Use across all Majikah products and services
+    S1 --> P2[Majik Buwiz]
+    S2 --> P2
+    E1 --> P2
+    E2 --> P2
+    I1 --> P2
+    I2 --> P2
+    
 
----
+    E1 --> P3[Majik Message]
+    E2 --> P3
 
-## Features
-
-### Security & Post-Quantum Readiness
-- **Post-Quantum Ready**: Implements **ML-KEM-768 (FIPS-203)** for key encapsulation, ensuring identities are secure against future quantum computing threats.
-- **Argon2id Key Derivation**: Uses memory-hard **Argon2id** (KDF v2) for passphrase encryption (64 MB / 3 iterations / 4 parallelism), providing industry-leading resistance to GPU/ASIC brute-force attacks.
-- **Seamless Auto-Migration**: Automatically detects and upgrades legacy v1 (PBKDF2) accounts to v2 (Argon2id) during import, re-deriving missing ML-KEM keys deterministically from the seed.
-- **AES-GCM Authenticated Encryption**: Industry-standard encryption for private keys at rest with unique, per-identity salts and random IVs.
-- **Locked/Unlocked States**: Private keys are only decrypted into memory when explicitly unlocked and are purged immediately upon calling `.lock()`.
-
-### BIP39 Compliance & Key Derivation
-- **Standard Mnemonic Generation**: Generate high-entropy 12 or 24-word seed phrases (128/256-bit strength).
-- **Deterministic Multi-Key Derivation**: 
-    - **X25519 (Curve25519)**: Derived from the first 32 bytes of the seed for legacy compatibility and fingerprints.
-    - **ML-KEM-768**: Derived from the full 64-byte seed for post-quantum security.
-- **Built-in Validation**: Full BIP39 mnemonic validation and error handling.
-
-### Developer Experience
-- **First-Class TypeScript Support**: Full type definitions included for all interfaces and classes.
-- **Fluent API**: Intuitive method chaining for common operations (e.g., `key.unlock(p).updateLabel(l)`).
-- **Comprehensive Error Handling**: Specialized `MajikKeyError` and `CryptoError` classes for precise debugging.
-- **Isomorphic Support**: Works across Node.js and modern browser environments.
-
-### Import / Export & Storage
-- **Security-Minded JSON Serialization**: Export accounts to JSON format for storage without ever exposing raw private keys or seed phrases.
-- **MnemonicJSON Format**: A secure, portable format for seed phrase storage and recovery.
-- **Mnemonic-Encrypted Backups**: Export and import specialized backup strings that utilize the mnemonic as a secondary encryption layer.
-
-### Interoperability
-- **Majik Message Integration**: Native support for exporting identities compatible with **Majik Message v3** envelopes.
-- **Contact Portability**: Convert Majik Keys directly into contact formats for easy sharing of public identities.
-- **Ecosystem Ready**: Designed as the core identity provider for all current and future Majikah products.
----
-
-## Installation
-
-```bash
-# Using npm
-npm install @majikah/majik-key
+    I1 --> P4[Majik Universal ID]
+    I2 --> P4
 
+    P4 --> P5[Majik SLink]
 ```
 
----
-
-## Quick Start
-
-```ts
-import { MajikKey } from '@majikah/majik-key';
-
-// Generate a new mnemonic
-const mnemonic = MajikKey.generateMnemonic(); // 12 words
-console.log('Save this mnemonic:', mnemonic);
-
-// Create a new Majik Key (unlocked state)
-const key = await MajikKey.create(mnemonic, 'secure-passphrase', 'My PQ Account');
-
-// 2. Access your keys (requires unlock)
-console.log('Fingerprint:', key.fingerprint);
-console.log('PQ Ready:', key.metadata.kdfVersion); // 'argon2id'
-console.log('Key ID:', key.id);
-console.log('Is Unlocked:', key.isUnlocked); // true
-
-// Lock the key (clear private keys from memory)
-key.lock();
-console.log('Is Locked:', key.isLocked); // true
-
-// Unlock when needed
-await key.unlock('my-secure-passphrase');
-console.log('Is Unlocked:', key.isUnlocked); // true
-
-// Access private key (only when unlocked)
-const privateKey = key.getPrivateKey();
-const privateKeyBase64 = key.getPrivateKeyBase64();
-
-// Save to storage (private keys never included)
-const json = key.toJSON();
-localStorage.setItem('myKey', JSON.stringify(json));
-
-// Load from storage (locked state)
-const loadedKey = MajikKey.fromJSON(json);
-await loadedKey.unlock('my-secure-passphrase');
-```
+Your Majik Key is generated entirely offline. No network request is made during key creation — verifiable in source code.
 
 ---
 
-## API Reference
-
-### Static Methods
+## Powering the Majikah Ecosystem
 
-#### `MajikKey.create(mnemonic, passphrase, label?)`
-Create a new Majik Key from a mnemonic phrase. Generates a new Argon2id-protected account.
+Majik Key is the shared identity layer underneath every Majikah product. Here's what each one draws from it.
 
-**Parameters:**
-- `mnemonic: string` - BIP39 mnemonic phrase (12-24 words)
-- `passphrase: string` - Passphrase to encrypt the private key at rest
-- `label?: string` - Optional label for the key
+### [Majik Signature](https://majikah.solutions/products/majik-signature) — Flagship
 
-**Returns:** `Promise<MajikKey>` - A new unlocked MajikKey instance
+**Post-quantum cryptographic file signing and verification.**
 
-**Example:**
-```ts
-const mnemonic = 'witch collapse practice feed shame open despair creek road again ice least';
-const key = await MajikKey.create(mnemonic, 'my-password', 'Personal Account');
+[![npm](https://img.shields.io/npm/v/@majikah/majik-signature)](https://www.npmjs.com/package/@majikah/majik-signature) [![npm downloads](https://img.shields.io/npm/dm/@majikah/majik-signature)](https://www.npmjs.com/package/@majikah/majik-signature) [![npm bundle size](https://img.shields.io/bundlephobia/min/%40majikah%2Fmajik-signature)](https://bundlephobia.com/package/@majikah/majik-signature) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-```
+[![Majik Signature Hero](https://github.com/user-attachments/assets/781bb778-9535-4b1f-bbc5-820550ecc864)](https://signature.majikah.solutions)
 
----
+Majik Signature consumes a Majik Key's **Ed25519** and **ML-DSA-87** signing keypairs to require *both* a classical and a post-quantum signature before a file verifies — hybrid security with forward secrecy against future quantum attacks on either scheme alone.
 
-#### `MajikKey.fromJSON(json)`
-Load a Majik Key from JSON (locked state).
+```typescript
+import { MajikKey } from '@majikah/majik-key';
+import { MajikSignature } from '@majikah/majik-signature';
 
-**Parameters:**
-- `json: MajikKeyJSON | string` - JSON object or string
+// 1. Sign a file and embed the signature (requires an unlocked key with signing keys)
+const { blob, signature } = await MajikSignature.signFile(myFileBlob, myUnlockedKey, {
+  // Optional: restrict future signers
+  expectedSigners: [ MajikSignature.expectedSignerFromKey(myUnlockedKey) ]
+});
 
-**Returns:** `MajikKey` - A locked MajikKey instance
+// 2. Verify a signed file's embedded signatures
+const results = await MajikSignature.verifyFile(blob, myUnlockedKey);
+results.forEach(res => {
+  console.log(`Signer ${res.signerId} valid?`, res.valid);
+});
 
-**Example:**
-```ts
-const json = localStorage.getItem('myKey');
-const key = MajikKey.fromJSON(json);
-await key.unlock('my-password');
+// 3. Seal a multi-sig file to prevent further signatures
+const { sealInfo } = await MajikSignature.seal(blob, myUnlockedKey);
+console.log("File sealed at:", sealInfo.sealTimestamp);
 ```
 
----
+### Majik Message
 
-#### `MajikKey.fromMnemonicJSON(mnemonicJson, passphrase, label?)`
-Create a Majik Key from MnemonicJSON format. Auto-migrates legacy PBKDF2 accounts to Argon2id + ML-KEM.
+**Post-quantum secure messaging envelopes.**
 
-**Parameters:**
-- `mnemonicJson: MnemonicJSON | string` - MnemonicJSON object or string
-- `passphrase: string` - Passphrase to encrypt the key at rest
-- `label?: string` - Optional label for the key
+Majik Key derives an ML-KEM-768 keypair specifically so it can be used for Majik Message's v3 secure envelopes — the ML-KEM-768 keypair handles post-quantum key encapsulation, and AES-256-GCM handles the actual payload encryption once a shared secret is established.
 
-**Returns:** `Promise<MajikKey>` - A new unlocked MajikKey instance
+Majik Key ships a direct integration point for this: `toMajikMessageIdentity()` converts an unlocked key into a `MajikMessageIdentity`, ready to hand to Majik Message.
 
-**Example:**
-```ts
-const mnemonicData = {
-  id: 'backup-id',
-  seed: ['word1', 'word2', ...],
-  phrase: 'optional-encryption-phrase'
-};
-
-const key = await MajikKey.fromMnemonicJSON(mnemonicData, 'my-password');
-```
-
----
+```typescript
+import { MajikKey } from '@majikah/majik-key';
 
-#### `MajikKey.importFromMnemonicBackup(backup, mnemonic, passphrase, label?)`
-Import a Majik Key from a mnemonic-encrypted backup. Auto-migrates legacy PBKDF2 accounts to Argon2id + ML-KEM.
-
-**Parameters:**
-- `backup: string` - Base64-encoded backup string
-- `mnemonic: string` - The mnemonic phrase used to encrypt the backup
-- `passphrase: string` - Passphrase to encrypt the imported key
-- `label?: string` - Optional label for the key
-
-**Returns:** `Promise<MajikKey>` - A new unlocked MajikKey instance
-
-**Example:**
-```ts
-const backupString = 'eT8xY2F...'; // From exportMnemonicBackup()
-const key = await MajikKey.importFromMnemonicBackup(
-  backupString,
-  mnemonic,
-  'new-password',
-  'Restored Account'
-);
+// user: an existing MajikUser instance (from @thezelijah/majik-user)
+const identity = await key.toMajikMessageIdentity(user, {
+  label: 'My Device',
+  restricted: false,
+});
 ```
 
----
-
-#### `MajikKey.generateMnemonic(strength?)`
-Generate a new BIP39 mnemonic phrase.
-
-**Parameters:**
-- `strength?: 128 | 256` - Entropy strength (128 = 12 words, 256 = 24 words). Default: 128
-
-**Returns:** `string` - A new mnemonic phrase
-
-**Example:**
-```ts
-const mnemonic12 = MajikKey.generateMnemonic();      // 12 words
-const mnemonic24 = MajikKey.generateMnemonic(256);   // 24 words
-```
+### Majik Buwiz
 
----
+**Multi-key custody built on the full Majik Key stack.**
 
-#### `MajikKey.validateMnemonic(mnemonic)`
-Validate a BIP39 mnemonic phrase.
+Majik Buwiz is built on Majik Key's complete key set: Ed25519/ML-DSA-87 for signing, ML-KEM-768/AES-256-GCM for encryption, and X25519/BIP-39 for identity — plus the experimental Bitcoin and Solana keys described below for multi-chain support. Everything a Buwiz account needs is derivable from, and recoverable with, the same mnemonic.
 
-**Parameters:**
-- `mnemonic: string` - Mnemonic phrase to validate
+### Majik Universal ID & Majik SLink
 
-**Returns:** `boolean` - true if valid, false otherwise
+**A portable identity primitive, and shareable links built on top of it.**
 
-**Example:**
-```ts
-const isValid = MajikKey.validateMnemonic('witch collapse practice...');
-```
+Majik Universal ID is built on the Identity branch of Majik Key — the BIP-39-derived X25519 keypair, public key, and fingerprint, exportable via `toContact()` as a `MajikContact` for use across apps. Majik SLink extends that identity layer downstream, per the architecture above. Both are separate Majikah packages; consult [majikah.solutions](https://majikah.solutions) for the latest on their APIs.
 
 ---
 
-### Instance Methods
-
-#### `unlock(passphrase)`
-Unlock the Majik Key by decrypting the private key. Decrypts X25519 and ML-KEM private keys into memory.
-
-**Parameters:**
-- `passphrase: string` - Passphrase to decrypt the private key
+## Experimental Web3 Support
 
-**Returns:** `Promise<this>` - This instance for chaining
-
-**Throws:** `MajikKeyError` if passphrase is incorrect or key is already unlocked
-
-**Example:**
-```ts
-await key.unlock('my-password');
-```
+Majik Key can derive **Bitcoin** and **Solana** key material directly from the same mnemonic. This is marked experimental — the shape of the `web3` namespace may change without a major version bump.
 
----
+### What's built in vs. what needs an extra install
 
-#### `lock()`
-Lock the Majik Key by clearing private keys from memory.
+- **Bitcoin key derivation is automatic.** Every account created via `create()` or `importFromMnemonicBackup()` also derives and encrypts a Bitcoin keypair (real BIP-32 HD derivation off the raw 64-byte seed, using a Majik-specific domain-separated path by default). This works out of the box — no extra install needed for the private key, public key, or WIF export.
+- **Solana key derivation is on-demand.** Rather than storing a separate Solana keypair, Majik Key derives it deterministically from your Ed25519 signing key each time you access `key.web3.solana` (and caches it in memory for as long as the key stays unlocked). The base58 Solana address also works with no extra install.
+- **The optional peer dependencies are only needed for chain-native address/transaction objects:**
 
-**Returns:** `this` - This instance for chaining
+| Chain | Peer dependency | Needed for |
+| :--- | :--- | :--- |
+| Bitcoin | `@scure/btc-signer` | Native SegWit (bech32) address encoding, PSBT construction |
+| Solana | `@solana/kit` | Real `KeyPairSigner` instances, kit-native `Address` type |
 
-**Example:**
-```ts
-key.lock();
+```bash
+npm install @scure/btc-signer   # for Bitcoin addresses
+npm install @solana/kit         # for Solana signer/address objects
 ```
 
----
+Everything else — raw key bytes, WIF export, message signing (ECDSA/Schnorr for Bitcoin, Ed25519 for Solana), and base58 Solana addresses — works with zero extra dependencies.
 
-#### `verify(passphrase)`
-Verify that a passphrase can decrypt the private key.
+### Two Bitcoin paths, on purpose
 
-**Parameters:**
-- `passphrase: string` - Passphrase to verify
+By default, Bitcoin keys use `MAJIK_BITCOIN_DOMAIN_PATH` — a real, standard BIP-32 derivation, but not the path a generic wallet would derive by default, so it stays effectively private to Majik. Pass `{ standard: true }` to derive the actual BIP-84 mainnet path instead — the address any standard wallet would show for the same mnemonic:
 
-**Returns:** `Promise<boolean>` - true if valid, false otherwise
+```typescript
+// Majik's default (domain-separated, stored on the key)
+const wif = key.getBitcoinWIF();
 
-**Example:**
-```ts
-const isValid = await key.verify('my-password');
+// The real BIP-84 mainnet key — recoverable in any standard wallet
+const standardBtc = await MajikKey.deriveStandardBitcoinFromMnemonic(mnemonic);
 ```
 
----
-
-#### `updateLabel(newLabel)`
-Update the label of the Majik Key.
+### Two Solana paths, on purpose
 
-**Parameters:**
-- `newLabel: string` - New label value
+By default (`deriveSolanaKeypairFromEdSecretKey`), the Solana keypair is domain-separated from your Ed25519 message-signing key via `SHA256(edSeed || "MajikMessageSolanaSeed")`, so the same private key never secures two different protocols. You can opt into reusing your Ed25519 message-signing key directly instead:
 
-**Returns:** `this` - This instance for chaining
+```typescript
+// Recommended: domain-separated Solana key
+const solanaAddress = key.getSolanaAddress();
 
-**Example:**
-```ts
-key.updateLabel('Work Account');
+// Opt-in: reuse the Ed25519 message-signing key as-is (not recommended)
+const reusedAddress = key.getSolanaAddress({ reuseMessageKey: true });
 ```
 
 ---
 
-#### `updatePassphrase(currentPassphrase, newPassphrase)`
-Change the passphrase used to encrypt the private key. Re-encrypts keys and triggers an auto-migration to KDF v2.
-
-**Parameters:**
-- `currentPassphrase: string` - Current passphrase
-- `newPassphrase: string` - New passphrase
-
-**Returns:** `Promise<this>` - This instance for chaining
-
-**Throws:** `MajikKeyError` if current passphrase is incorrect
+## Installation
 
-**Example:**
-```ts
-await key.updatePassphrase('old-password', 'new-password');
+```bash
+npm install @majikah/majik-key
 ```
 
 ---
 
-#### `getPrivateKey()`
-Get the private key (only when unlocked).
-
-**Returns:** `CryptoKey | { raw: Uint8Array }` - The private key
-
-**Throws:** `MajikKeyError` if the key is locked
-
-**Example:**
-```ts
-const privateKey = key.getPrivateKey();
-```
+## Quick Start (Core Identity)
 
----
+```typescript
+import { MajikKey } from '@majikah/majik-key';
 
-#### `getPrivateKeyBase64()`
-Get the private key as base64 (only when unlocked).
+// 1. Generate & Create
+const mnemonic = await MajikKey.generateMnemonic(); // 12 words (128-bit)
+const key = await MajikKey.create(mnemonic, 'super-secure-passphrase', 'My PQ Account');
 
-**Returns:** `string` - The private key in base64 format
+// 2. Access Identity
+console.log('Fingerprint:', key.fingerprint);
+console.log('Key ID:', key.id);
+console.log('Unlocked?', key.isUnlocked); // true — create() returns an already-unlocked key
 
-**Throws:** `MajikKeyError` if the key is locked
+// 3. Lock to purge private key material from memory
+key.lock();
 
-**Example:**
-```ts
+// 4. Unlock again when cryptographic operations are needed
+await key.unlock('super-secure-passphrase');
 const privateKeyBase64 = key.getPrivateKeyBase64();
-```
 
----
-
-#### `toJSON()`
-Export to JSON format (safe for storage).
-
-**Returns:** `MajikKeyJSON` - JSON representation (private keys never included)
-
-**Example:**
-```ts
-const json = key.toJSON();
-localStorage.setItem('myKey', JSON.stringify(json));
+// 5. Safe storage — toJSON()/toString() never include raw private keys
+localStorage.setItem('myKey', key.toString());
 ```
 
 ---
 
-#### `toString(pretty?)`
-Export to JSON string.
-
-**Parameters:**
-- `pretty?: boolean` - Whether to pretty-print. Default: false
-
-**Returns:** `string` - JSON string representation
-
-**Example:**
-```ts
-const jsonString = key.toString(true);
-```
-
----
-
-#### `toMnemonicJSON(mnemonic, passphrase?)`
-Export to MnemonicJSON format.
-
-**Parameters:**
-- `mnemonic: string` - The BIP39 mnemonic phrase
-- `passphrase?: string` - Optional passphrase
-
-**Returns:** `MnemonicJSON` - MnemonicJSON object
-
-**Throws:** `MajikKeyError` if the key is locked
-
-**Example:**
-```ts
-const mnemonicData = key.toMnemonicJSON(mnemonic, 'encryption-phrase');
-```
-
----
-
-#### `exportMnemonicBackup(mnemonic)`
-Export a mnemonic-encrypted backup.
-
-**Parameters:**
-- `mnemonic: string` - The original mnemonic phrase
-
-**Returns:** `Promise<string>` - Base64-encoded backup string
-
-**Throws:** `MajikKeyError` if the key is locked
-
-**Example:**
-```ts
-const backup = await key.exportMnemonicBackup(mnemonic);
-```
-
----
-
-#### `toContact()`
-Create a MajikContact from this Majik Key.
-
-**Returns:** `MajikContact` - A MajikContact instance
-
-**Example:**
-```ts
-const contact = key.toContact();
-```
-
----
-
-#### `toMajikMessageIdentity(user, options?)`
-Convert to MajikMessageIdentity for use in Majik Message.
-
-**Parameters:**
-- `user: MajikUser` - MajikUser instance
-- `options?: { label?: string, restricted?: boolean }` - Optional configuration
-
-**Returns:** `Promise<MajikMessageIdentity>` - MajikMessageIdentity instance
-
-**Example:**
-```ts
-const identity = await key.toMajikMessageIdentity(user, {
-  label: 'My Account',
-  restricted: false
-});
-```
+## API Reference
 
----
+### Static Methods (Lifecycle & Generation)
 
-### Getters
+| Method | Parameters | Returns | Description |
+| :--- | :--- | :--- | :--- |
+| `create()` | `mnemonic`, `passphrase`, `label?`, `mnemonicLanguage?` | `Promise<MajikKey>` | Creates a new Argon2id-protected, fully post-quantum-capable account. |
+| `fromJSON()` | `json` | `MajikKey` | Loads a locked key from safe JSON storage. |
+| `fromMnemonicJSON()` | `mnemonicJson`, `passphrase`, `label?` | `Promise<MajikKey>` | Rebuilds a key straight from a portable seed export. |
+| `importFromMnemonicBackup()` | `backup`, `mnemonic`, `passphrase`, `label?`, `mnemonicLanguage?` | `Promise<MajikKey>` | Full migration path — verifies the mnemonic, then re-derives and re-encrypts the complete identity with Argon2id. |
+| `fromDangerousJSON()` | `json` | `MajikKey` | Reconstructs an already-unlocked key from a dangerous export. Server-side only — see warning below. |
+| `generateMnemonic()` | `strength?` *(128 \| 256)*, `language?` | `Promise<string>` | Generates a 12- or 24-word BIP-39 phrase. |
+| `validateMnemonic()` | `mnemonic` | `boolean` | Validates a BIP-39 mnemonic phrase. |
+| `deriveStandardBitcoinFromMnemonic()` *(experimental)* | `mnemonic`, `mnemonicLanguage?` | `Promise<BitcoinKeypairMaterial>` | Derives the real BIP-84 mainnet Bitcoin key without needing a `MajikKey` instance. |
 
-#### `id: string`
-The unique identifier (fingerprint).
+### Instance Methods (State & Management)
 
-#### `fingerprint: string`
-The cryptographic fingerprint.
+| Method | Parameters | Returns | Description |
+| :--- | :--- | :--- | :--- |
+| `unlock()` | `passphrase` | `Promise<this>` | Decrypts keys into memory. Chainable. |
+| `lock()` | None | `this` | Purges all private key material (including cached Web3 keys) from memory. Chainable. |
+| `verify()` | `passphrase` | `Promise<boolean>` | Tests a passphrase without keeping keys in memory or requiring an unlock. |
+| `updatePassphrase()` | `currentPass`, `newPass` | `Promise<this>` | Re-encrypts every stored key under a new passphrase and migrates to KDF v2 if needed. |
+| `migrate()` | `passphrase` | `Promise<this>` | Upgrades the X25519 key's KDF from v1 to v2 only — does **not** add ML-KEM/Ed25519/ML-DSA/Bitcoin keys. Use `importFromMnemonicBackup()` for a full upgrade. |
+| `updateLabel()` | `newLabel` | `this` | Updates the human-readable account label. |
 
-#### `publicKey: CryptoKey | { raw: Uint8Array }`
-The public key.
+### Export & Integration Methods
 
-#### `publicKeyBase64: string`
-The public key in base64 format.
+| Method | Returns | Description |
+| :--- | :--- | :--- |
+| `toJSON()` / `toString()` | `MajikKeyJSON` / `string` | Safe export for DB/LocalStorage. No raw keys. |
+| `toDangerousJSON()` | `MajikKeyDangerousJSON` | ⚠️ Contains every raw private key. Server-side secret injection only — see warning below. |
+| `toMnemonicJSON()` | `MnemonicJSON` | ⚠️ Contains the raw mnemonic words (and passphrase, if you pass one) in plaintext — a transport format, not an at-rest storage format. Requires the key to be unlocked. |
+| `exportMnemonicBackup()` | `Promise<string>` | Encrypted backup string, decryptable only with the original mnemonic — used to verify a mnemonic before `importFromMnemonicBackup()` re-derives the identity. |
+| `toContact()` | `MajikContact` | Extracts public identity data for sharing (the basis for Majik Universal ID). |
+| `toMajikMessageIdentity()` | `Promise<MajikMessageIdentity>` | Formats the key for direct use in Majik Message. Requires a `MajikUser`. |
 
-#### `label: string`
-The user-defined label.
+### Instance Getters
 
-#### `backup: string`
-The mnemonic backup identifier.
+*Public — available at any time, regardless of lock state:*
 
-#### `timestamp: Date`
-The creation timestamp.
+`id`, `fingerprint`, `publicKey`, `publicKeyBase64`, `label`, `backup`, `timestamp`, `mnemonicLanguage`, `kdfVersion`, `isArgon2id`, `isLocked`, `isUnlocked`, `isFullyUpgraded`, `mlKemPublicKey`, `hasMlKem`, `edPublicKey`, `mlDsaPublicKey`, `hasSigningKeys`, `btcPublicKey`, `hasBitcoin`, `hasSolanaKeypair`, `hasBitcoinKeypair`, `metadata`.
 
-#### `isLocked: boolean`
-Whether the key is currently locked.
+*Restricted — throws `MajikKeyError` if locked (or if that key type isn't present, e.g. on an account not yet fully migrated):*
 
-#### `isUnlocked: boolean`
-Whether the key is currently unlocked.
+`getPrivateKey()`, `getPrivateKeyBase64()`, `getMlKemSecretKey()`, `getEdSecretKey()`, `getMlDsaSecretKey()`, `getBtcSecretKey()`.
 
-#### `metadata: MajikKeyMetadata`
-Safe metadata object (no sensitive data).
+### Web3 (Experimental)
 
-**Example:**
-```ts
-console.log(key.metadata);
-// {
-//   id: 'fingerprint-id',
-//   fingerprint: 'fingerprint-id',
-//   label: 'My Key',
-//   timestamp: Date,
-//   isLocked: false
-// }
-```
+| Member | Returns | Notes |
+| :--- | :--- | :--- |
+| `web3` *(getter)* | `{ solana, bitcoin? } \| undefined` | `undefined` if locked or has no Ed25519 signing key. `bitcoin` is present only if the account has stored Bitcoin key material. |
+| `getBitcoinKeypairMaterial()` | `BitcoinKeypairMaterial` | Raw Bitcoin keypair bytes. |
+| `getBitcoinWIF()` | `string` | Wallet Import Format string, pastes into any standard Bitcoin wallet. |
+| `getSolanaKeypairMaterial()` | `SolanaKeypairMaterial` | Raw Solana keypair bytes. |
+| `getSolanaKeypair()` | `Promise<any>` | Real `@solana/kit` `KeyPairSigner`. Requires `@solana/kit`. |
+| `getSolanaAddress()` | `string` | Base58 Solana address. No extra dependency required. |
 
 ---
 
 ## Usage Examples
 
-### Example 1: Create and Manage a Key
+### 1. Secure Backup & Recovery Workflow
 
-```ts
+```typescript
 import { MajikKey } from '@majikah/majik-key';
 
-async function createKey() {
-  // Generate mnemonic
-  const mnemonic = MajikKey.generateMnemonic();
-  console.log('🔑 Save this mnemonic safely:', mnemonic);
-
-  // Create key
-  const key = await MajikKey.create(
-    mnemonic,
-    'secure-passphrase',
-    'Personal Account'
-  );
-
-  console.log('✅ Key created!');
-  console.log('ID:', key.id);
-  console.log('Fingerprint:', key.fingerprint);
-  console.log('Label:', key.label);
-
-  // Save to storage
-  const json = key.toJSON();
-  localStorage.setItem('myKey', JSON.stringify(json));
-
-  return { key, mnemonic };
-}
-
-createKey();
+// -- EXPORTING --
+// ⚠️ jsonData contains the raw mnemonic (and passphrase, if provided) in
+// plaintext. Treat this exactly like the mnemonic itself — encrypt the
+// file yourself, or keep it offline. This is a transport format, not a
+// safe-storage format.
+const jsonData = key.toMnemonicJSON(mnemonic, 'password123');
+const blob = new Blob([JSON.stringify(jsonData)], { type: "application/json" });
+// Save blob to a secure location...
+
+// -- RECOVERING --
+const recoveredData = JSON.parse(await blob.text());
+const recoveredKey = await MajikKey.importFromMnemonicBackup(
+  recoveredData.id,
+  recoveredData.seed.join(" "),
+  recoveredData.phrase,
+  'Recovered Key',
+);
 ```
 
----
-
-### Example 2: Lock/Unlock Pattern
-
-```ts
-import { MajikKey } from '@majikah/majik-key';
-
-async function secureLockPattern() {
-  const json = localStorage.getItem('myKey');
-  const key = MajikKey.fromJSON(json);
-
-  // Key is locked by default when loaded from JSON
-  console.log('Locked:', key.isLocked); // true
-
-  try {
-    // This will throw an error
-    const privateKey = key.getPrivateKey();
-  } catch (error) {
-    console.log('❌ Cannot access private key when locked');
-  }
+### 2. Password Verification Before Action
 
-  // Unlock to use private key
-  await key.unlock('secure-passphrase');
-  console.log('Unlocked:', key.isUnlocked); // true
+```typescript
+const key = MajikKey.fromJSON(storedJson);
 
-  // Now we can access private keys
-  const privateKey = key.getPrivateKey();
-  const privateKeyBase64 = key.getPrivateKeyBase64();
-
-  // Use the key for cryptographic operations
-  // ...
-
-  // Lock again when done
-  key.lock();
-  console.log('🔒 Key locked again');
+if (await key.verify('user-input-password')) {
+  await key.unlock('user-input-password');
+  // ... proceed with signing/encryption
+  key.lock(); // Always clean up!
+} else {
+  throw new Error("Invalid passphrase");
 }
-
-secureLockPattern();
 ```
 
----
-
-### Example 3: Backup and Recovery
-
-```ts
-import { MajikKey } from '@majikah/majik-key';
-
-async function backupAndRecover() {
-  const mnemonic = MajikKey.generateMnemonic();
-  const key = await MajikKey.create(mnemonic, 'password123', 'Original Key');
-
-  //Download as Blob JSON File
-
-  const jsonData = await key.toMnemonicJSON(mnemonic, 'password123');
-  const jsonString = JSON.stringify(jsonData);
-  const blob = new Blob([jsonString], {
-    type: "application/json;charset=utf-8",
-  });
-  downloadBlob(
-    blob,
-    "json",
-    `${label} | ${key.id} | SEED KEY`,
-  );
-
+### 3. Server-Side Secret Injection (Dangerous JSON)
 
+`toDangerousJSON()` / `fromDangerousJSON()` skip encryption entirely — no KDF, no AES-GCM, instant reconstruction. This exists for one narrow case: injecting a pre-unlocked signing key into a server process, not for anything that touches a database, log, or the network.
 
-  // Later... recover from backup
+```typescript
+// At deploy time, generated once and stored in your secrets manager:
+const dangerousJson = unlockedKey.toDangerousJSON();
 
-  //Parse the downloaded JSON into this object
-  const jsonData: MnemonicJSON = {
-    id: "abc123",
-    seed: ["word1", "word2", ...],
-    phrase: 'password123',
-  };
-
-  const recoveredKey = await MajikKey.importFromMnemonicBackup(
-    jsonData.id,
-    seedArrayToString(jsonData.seed),
-    jsonData.phrase,
-    'Recovered Key'
-  );
-
-  console.log('✅ Key recovered!');
-  console.log('Same fingerprint:', key.fingerprint === recoveredKey.fingerprint);
-}
-
-backupAndRecover();
+// At server boot:
+const serverKey = MajikKey.fromDangerousJSON(process.env.MAJIK_SIGNING_KEY!);
+// serverKey is already unlocked — no passphrase needed, no KDF cost.
 ```
 
+### 4. Experimental Web3 Usage
 
----
-
-### Example 4: Update Passphrase
-
-```ts
-import { MajikKey } from '@majikah/majik-key';
+```typescript
+// Bitcoin — key material is already derived and stored on any account
+console.log('Bitcoin WIF:', key.getBitcoinWIF());
+console.log('Bitcoin address:', await key.web3?.bitcoin?.getBitcoinAddress()); // needs @scure/btc-signer
 
-async function changePassphrase() {
-  const json = localStorage.getItem('myKey');
-  const key = MajikKey.fromJSON(json);
-
-  // Must unlock first
-  await key.unlock('old-password');
-
-  // Change passphrase
-  await key.updatePassphrase('old-password', 'new-secure-password');
-  console.log('✅ Passphrase updated!');
-
-  // Save updated key
-  localStorage.setItem('myKey', JSON.stringify(key.toJSON()));
-
-  // Verify new passphrase works
-  key.lock();
-  await key.unlock('new-secure-password');
-  console.log('✅ New passphrase verified!');
-}
-
-changePassphrase();
+// Solana — derived on demand from your Ed25519 signing key
+console.log('Solana address:', key.getSolanaAddress()); // no extra dependency
+const solanaSigner = await key.getSolanaKeypair(); // needs @solana/kit
 ```
 
 ---
 
-### Example 5: Verify Passphrase
+## Security Best Practices
 
-```ts
-import { MajikKey } from '@majikah/majik-key';
+✅ **DO:**
+- Call `.lock()` immediately after signing or decrypting payloads to free key material from memory.
+- Use `mlKemPublicKey` for all new communication protocols to stay post-quantum ready.
+- Keep `@scure/bip39` and the underlying crypto dependencies up to date.
+- Treat any `toMnemonicJSON()` export, and the mnemonic itself, as the master secret — it recovers everything.
 
-async function verifyPassphrase() {
-  const json = localStorage.getItem('myKey');
-  const key = MajikKey.fromJSON(json);
-
-  // Verify without unlocking
-  const isValid = await key.verify('user-entered-password');
-
-  if (isValid) {
-    console.log('✅ Passphrase is correct');
-    await key.unlock('user-entered-password');
-    // Proceed with operations...
-  } else {
-    console.log('❌ Invalid passphrase');
-    // Show error to user
-  }
-}
-
-verifyPassphrase();
-```
+❌ **DON'T:**
+- Log `mnemonic` phrases, `privateKeyBase64`, or any `*SecretKeyBase64` value in production.
+- Use `toDangerousJSON()` / `fromDangerousJSON()` outside of controlled, server-side secret injection.
+- Store the output of `toMnemonicJSON()` unencrypted — it is not the same as `toJSON()`/`toString()`.
 
 ---
 
-## Integration with Majik Message
-
-Majik Key is fully compatible with **Majik Message** as its seed phrase account implementation. Keys created with Majik Key can be directly imported into Majik Message.
-
-### Importing to Majik Message
-
-```ts
-import { MajikKey } from '@majikah/majik-key';
-
-async function importToMajikMessage() {
-  // Create or load a Majik Key
-  const mnemonic = MajikKey.generateMnemonic();
-  const key = await MajikKey.create(mnemonic, 'password', 'Message Account');
-
-  // Export to MnemonicJSON format for Majik Message
-  const mnemonicData = key.toMnemonicJSON(mnemonic, 'password');
-  const jsonString = JSON.stringify(mnemonicData);
+## Ecosystem
 
-  // Download this blob as a JSON locally
-  const blob = new Blob([jsonString], {
-    type: "application/json;charset=utf-8",
-  });
-
-  // This mnemonicData can be imported directly into Majik Message
-  // as a seed phrase account
-  console.log('Import the saved JSON to Majik Message:', mnemonicData);
-}
-```
-
-### Converting to Majik Message Identity
-
-```ts
-import { MajikKey } from '@majikah/majik-key';
-import { MajikUser } from '@thezelijah/majik-user';
-
-async function createMessageIdentity() {
-  const mnemonic = MajikKey.generateMnemonic();
-  const key = await MajikKey.create(mnemonic, 'password', 'Message Identity');
-
-  // Create/parse a MajikUser instance
-  const user = new MajikUser({
-    username: 'myusername',
-    // ... other user properties
-  });
-
-  // Convert to Majik Message Identity
-  const identity = await key.toMajikMessageIdentity(user, {
-    label: 'My Message Account',
-    restricted: false
-  });
-
-  console.log('Majik Message Identity created:', identity);
-}
-```
-
----
-
-## Security Considerations
-
-### Best Practices
-
-1. **Never expose mnemonics**: Treat mnemonic phrases like root passwords. Never log or store them unencrypted.
-
-2. **Lock when not in use**: Always call .lock() when private key access is no longer required to purge the heap.
-
-3. **PQ Readiness**: For all new communication protocols, ensure you are utilizing the mlKemPublicKey.
-
-Security Summary
-- **Primary KDF**: Argon2id (64 / 3t / 4p).
-
-- **Legacy KDF**: PBKDF2-SHA256 (250,000 iterations).
-
-- **Encryption**: AES-256-GCM with unique salts and IVs.
-
-- **Post-Quantum**: ML-KEM-768 (Lattice-based cryptography).
-
-### What NOT to Do
-
-❌ **DON'T** store mnemonics in code or version control  
-❌ **DON'T** transmit mnemonics over insecure channels  
-❌ **DON'T** use weak passphrases like "password123"  
-❌ **DON'T** share mnemonics or passphrases with anyone  
-❌ **DON'T** screenshot or photograph mnemonics  
-
-### What TO Do
-
-✅ **DO** use password managers for mnemonic storage  
-✅ **DO** write mnemonics on paper and store securely  
-✅ **DO** use hardware security modules when possible  
-✅ **DO** test recovery procedures before relying on them  
-✅ **DO** keep multiple encrypted backups in different locations  
-
----
-
-### Tips & Reminders
-
-#### For Developers
-
-- **Remember**: Always validate user input before creating or unlocking keys.
-
-- **Security**: Never log sensitive data (mnemonics, private keys, passphrases) in production.
-
-- **Performance**: Lock keys when not in use to free memory and reduce attack surface.
-
-- **Testing**: Test backup/recovery procedures in development before deploying to production.
-
-- **Dependencies**: Keep `@scure/bip39` and other crypto dependencies up to date.
-
-#### For Users
-
-- **Backup**: Always keep multiple backups of your mnemonic phrase in secure locations.
-
-- **Passphrase**: Use a strong, unique passphrase for each Majik Key.
-
-- **Recovery**: Test your ability to recover keys from backups before you need to.
-
-- **Organization**: Use meaningful labels to identify different keys.
-- **Loss Prevention**: Losing your mnemonic phrase means permanent loss of access to your key.
+- [Majik Signature Web App](https://signature.majikah.solutions)
+- [Majik Signature on Microsoft Store](https://apps.microsoft.com/detail/9pl9g3xzvd1x)
+- [Majik Signature Official Repository](https://github.com/Majikah/majik-signature)
+- [Majikah Solutions](https://majikah.solutions)
 
 ---
 
-## Related Projects
-
-### [Majik Message](https://message.majikah.solutions)
-Secure messaging platform using Majik Keys
-
-[Read more about Majik Message here](https://majikah.solutions/products/majik-message)
-
-[![Majik Message Thumbnail](https://github.com/user-attachments/assets/6355cbd3-63e4-4a95-a370-64ba27cbb4a7)](https://message.majikah.solutions)
-
-> Click the image to try Majik Message live.
-
-[Read Docs](https://majikah.solutions/products/majik-message/docs)
-
-
-Also available on [Microsoft Store](https://apps.microsoft.com/detail/9pmjgvzzjspn) for free.
-
-[Official Repository](https://github.com/Majikah/majik-message)
-[SDK Library](https://www.npmjs.com/package/@majikah/majik-message)
+## License & Author
 
----
-
-## Contributing
-
-If you want to contribute or help extend support to more platforms, reach out via email. All contributions are welcome!  
-
----
-
-## License
-
-[Apache-2.0](LICENSE) — free for personal and commercial use.
-
----
-## Author
-
-Made with 💙 by [@thezelijah](https://github.com/jedlsf)
-
-## About the Developer
-
-- **Developer**: Josef Elijah Fabian
-- **GitHub**: [https://github.com/jedlsf](https://github.com/jedlsf)
-- **Project Repository**: [https://github.com/Majikah/majik-key](https://github.com/Majikah/majik-key)
-
----
+**License:** [Apache-2.0](LICENSE) — free for personal and commercial use.
 
-## Contact
+Developed by **Josef Elijah Fabian (Zelijah)** | [Majikah Solutions OPC](https://majikah.solutions/about)
 
-- **Business Email**: [business@thezelijah.world](mailto:business@thezelijah.world)
-- **Official Website**: [https://www.thezelijah.world](https://www.thezelijah.world)
+- **GitHub:** [@jedlsf](https://github.com/jedlsf)
+- **Website:** [https://www.thezelijah.world](https://www.thezelijah.world)
+- **Email:** [business@thezelijah.world](mailto:business@thezelijah.world)