@majikah/majik-key 0.3.1 → 0.3.3

package/README.md

@@ -1,7 +1,10 @@
 # Majik Key
 
+
+
 [![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)
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21339132.svg)](https://doi.org/10.5281/zenodo.21339132) ![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.
 
@@ -157,10 +160,10 @@ Majik Key can derive **Bitcoin** and **Solana** key material directly from the s
 - **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:**
 
-| Chain | Peer dependency | Needed for |
-| :--- | :--- | :--- |
+| 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 |
+| Solana  | `@solana/kit`       | Real `KeyPairSigner` instances, kit-native `Address` type  |
 
 ```bash
 npm install @scure/btc-signer   # for Bitcoin addresses
@@ -234,38 +237,38 @@ localStorage.setItem('myKey', key.toString());
 
 ### Static Methods (Lifecycle & Generation)
 
-| 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. |
+| 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.                                |
 
 ### Instance Methods (State & Management)
 
-| 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. |
+| 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.                                                                                                                    |
 
 ### Export & Integration Methods
 
-| 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`. |
+| 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`.                                                                                               |
 
 ### Instance Getters
 
@@ -279,14 +282,14 @@ localStorage.setItem('myKey', key.toString());
 
 ### Web3 (Experimental)
 
-| 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. |
+| 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.                                                                           |
 
 ---
 
@@ -391,9 +394,13 @@ Developed by **Josef Elijah Fabian (Zelijah)** | [Majikah Solutions OPC](https:/
 
 
 **Developer**: [Josef Elijah Fabian](https://github.com/jedlsf)
+
 **GitHub**: [https://github.com/Majikah](https://github.com/Majikah)
+
 **Project Repository**: [https://github.com/Majikah/majik-signature](https://github.com/Majikah/majik-signature)
 
+**Technical Whitepaper**: [https://zenodo.org/records/21339132](https://zenodo.org/records/21339132)
+
 ---
 
 ## Contact

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

@@ -11,10 +11,12 @@ import { argon2id as nobleArgon2id } from "@noble/hashes/argon2.js";
 import { ARGON2_PARAMS } from "./constants";
 import { ml_kem768 } from "@noble/post-quantum/ml-kem.js";
 import { argon2id as hashWasmArgon2id } from "hash-wasm";
+const secureGetRandomValues = crypto.getRandomValues.bind(crypto);
+const secureFill = Uint8Array.prototype.fill;
 export const IV_LENGTH = 12;
 export function generateRandomBytes(len) {
     const b = new Uint8Array(len);
-    crypto.getRandomValues(b);
+    secureGetRandomValues(b);
     return b;
 }
 export function generateEd25519Keypair() {
@@ -133,8 +135,13 @@ async function _argon2id(input, salt, params) {
  */
 export async function deriveKeyFromPassphraseArgon2(passphrase, salt) {
     const pw = new TextEncoder().encode(passphrase);
-    const result = await _argon2id(pw, salt, ARGON2_PARAMS.PASSPHRASE);
-    return result.slice(); // ← force a copy out of WASM memory
+    try {
+        const result = await _argon2id(pw, salt, ARGON2_PARAMS.PASSPHRASE);
+        return result.slice();
+    }
+    finally {
+        secureFill.call(pw, 0);
+    }
 }
 /**
  * Derive a 32-byte AES key from a BIP-39 mnemonic using Argon2id.
@@ -146,8 +153,13 @@ export async function deriveKeyFromPassphraseArgon2(passphrase, salt) {
  */
 export async function deriveKeyFromMnemonicArgon2(mnemonic, salt) {
     const m = new TextEncoder().encode(mnemonic);
-    const result = await _argon2id(m, salt, ARGON2_PARAMS.MNEMONIC);
-    return result.slice(); // ← force a copy out of WASM memory
+    try {
+        const result = await _argon2id(m, salt, ARGON2_PARAMS.MNEMONIC);
+        return result.slice(); // ← force a copy out of WASM memory
+    }
+    finally {
+        secureFill.call(m, 0);
+    }
 }
 // ─── KDF v1: PBKDF2-SHA256 (legacy — do not use for new operations) ───────────
 /**

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

@@ -1,8 +1,8 @@
 export interface EncryptionIdentity {
-    publicKey: CryptoKey | {
+    publicKey: {
         raw: Uint8Array;
     };
-    privateKey: CryptoKey | {
+    privateKey: {
         raw: Uint8Array;
     };
     fingerprint: string;

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

@@ -7,6 +7,7 @@ import { deriveMlKemKeypairFromSeed, fingerprintFromPublicRaw, } from "./crypto-
 import { concatUint8Arrays } from "../utils";
 import { hash } from "@stablelib/sha256";
 import { MAJIK_SIGNATURE_SEED } from "./constants";
+const secureFill = Uint8Array.prototype.fill;
 /**
  * EncryptionEngine
  * ----------------
@@ -35,15 +36,22 @@ export class EncryptionEngine {
      * seed[32..64] for the implicit rejection parameter `z`.
      */
     static async deriveIdentityFromMnemonic(mnemonic) {
+        if (typeof mnemonic !== "string" || mnemonic.trim().length === 0) {
+            throw new CryptoError("Mnemonic must be a non-empty string");
+        }
+        // Step 1: BIP-39 seed → 64 bytes
+        const seed = mnemonicToSeedSync(mnemonic); // returns Buffer (Node) or Uint8Array
+        const seed64 = new Uint8Array(seed); // normalize to Uint8Array
+        // Step 3: ML-KEM-768 keypair from FULL 64-byte seed (new)
+        // ml_kem768.keygen() accepts a 64-byte seed directly.
+        // seed[0..32] → lattice key matrix expansion (K-PKE keygen)
+        // seed[32..64] → implicit rejection parameter z (stored in secretKey)
+        const mlKemKeypair = deriveMlKemKeypairFromSeed(seed64);
+        const mlDsaSeedInput = concatUint8Arrays(seed64, new TextEncoder().encode(MAJIK_SIGNATURE_SEED));
+        const mlDsaSeed = hash(mlDsaSeedInput);
+        // Step 2: X25519 identity from first 32 bytes (existing path)
+        const seed32 = seed64.subarray(0, 32);
         try {
-            if (typeof mnemonic !== "string" || mnemonic.trim().length === 0) {
-                throw new CryptoError("Mnemonic must be a non-empty string");
-            }
-            // Step 1: BIP-39 seed → 64 bytes
-            const seed = mnemonicToSeedSync(mnemonic); // returns Buffer (Node) or Uint8Array
-            const seed64 = new Uint8Array(seed); // normalize to Uint8Array
-            // Step 2: X25519 identity from first 32 bytes (existing path)
-            const seed32 = seed64.subarray(0, 32);
             const ed = ed25519.generateKeyPairFromSeed(seed32);
             const skCurve = ed2curve.convertSecretKey(ed.secretKey);
             const pkCurve = ed2curve.convertPublicKey(ed.publicKey);
@@ -55,12 +63,6 @@ export class EncryptionEngine {
             const publicKey = { type: "public", raw: pkCurveBytes };
             const privateKey = { type: "private", raw: skCurveBytes };
             const fingerprint = fingerprintFromPublicRaw(pkCurveBytes);
-            // Step 3: ML-KEM-768 keypair from FULL 64-byte seed (new)
-            // ml_kem768.keygen() accepts a 64-byte seed directly.
-            // seed[0..32] → lattice key matrix expansion (K-PKE keygen)
-            // seed[32..64] → implicit rejection parameter z (stored in secretKey)
-            const mlKemKeypair = deriveMlKemKeypairFromSeed(seed64);
-            const mlDsaSeed = hash(concatUint8Arrays(seed64, new TextEncoder().encode(MAJIK_SIGNATURE_SEED))); // 32 bytes, deterministic, domain-separated
             const mlDsaKeypair = ml_dsa87.keygen(mlDsaSeed);
             return {
                 publicKey,
@@ -77,6 +79,14 @@ export class EncryptionEngine {
         catch (err) {
             throw new CryptoError("Failed to derive identity from mnemonic", err);
         }
+        finally {
+            secureFill.call(seed64, 0);
+            secureFill.call(seed32, 0);
+            secureFill.call(mlDsaSeedInput, 0);
+            secureFill.call(mlDsaSeed, 0);
+            if (seed instanceof Uint8Array)
+                secureFill.call(seed, 0);
+        }
     }
     /* ================================
      * Fingerprinting
@@ -123,3 +133,5 @@ export class CryptoError extends Error {
         this.cause = cause;
     }
 }
+Object.freeze(EncryptionEngine);
+Object.freeze(EncryptionEngine.prototype);

package/dist/core/validator.js

@@ -73,3 +73,5 @@ export class MajikKeyValidator {
         this.assert(typeof value === "string" && value.trim().length > 0, `${field} must be a non-empty string`);
     }
 }
+Object.freeze(MajikKeyValidator);
+Object.freeze(MajikKeyValidator.prototype);

package/dist/majik-key.d.ts

@@ -26,13 +26,13 @@ export interface MajikKeyIdentity {
     /** Account identifier. Equal to `fingerprint` for accounts created by this library. */
     id: string;
     /** X25519 public key — native `CryptoKey` where WebCrypto supports it, otherwise a raw-bytes wrapper. */
-    publicKey: CryptoKey | {
+    publicKey: {
         raw: Uint8Array;
     };
     /** SHA-256 fingerprint of `publicKey`. */
     fingerprint: MajikKeyFingerprint;
     /** X25519 private key, decrypted into memory. ⚠️ Live key material — do not log or serialize directly. */
-    privateKey: CryptoKey | {
+    privateKey: {
         raw: Uint8Array;
     };
     /** AES-256-GCM-encrypted X25519 private key (IV + ciphertext), as stored at rest. */
@@ -106,7 +106,7 @@ export interface SerializedIdentity {
  */
 export interface MajikKeyConstructorOptions {
     id: string;
-    publicKey: CryptoKey | {
+    publicKey: {
         raw: Uint8Array;
     };
     publicKeyBase64: MajikKeyAddress;
@@ -126,11 +126,9 @@ export interface MajikKeyConstructorOptions {
     encryptedMlKemSecretKey?: ArrayBuffer;
     encryptedMlKemSecretKeyBase64?: string;
     /** Present only when constructing an already-unlocked instance. ⚠️ Live key material. */
-    privateKey?: CryptoKey | {
+    privateKey?: {
         raw: Uint8Array;
     };
-    /** Present only when constructing an already-unlocked instance. ⚠️ Live key material. */
-    privateKeyBase64?: string;
     edPublicKey?: Uint8Array;
     encryptedEdSecretKey?: ArrayBuffer;
     encryptedEdSecretKeyBase64?: string;
@@ -192,7 +190,6 @@ export declare class MajikKey {
     private _encryptedMlKemSecretKey?;
     private _encryptedMlKemSecretKeyBase64?;
     private _privateKey?;
-    private _privateKeyBase64?;
     private _edPublicKey?;
     private _edSecretKey?;
     private _encryptedEdSecretKey?;

package/dist/majik-key.js

@@ -8,12 +8,13 @@ import { aesGcmDecrypt, aesGcmEncrypt, deriveKeyFromPassphraseArgon2, deriveKeyF
 import { EncryptionEngine } from "./core/crypto/encryption-engine";
 import { MajikContact } from "@majikah/majik-contact";
 import { arrayBufferToBase64, arrayToBase64, base64ToArrayBuffer, concatUint8Arrays, utf8ToBase64, base64ToUtf8, seedStringToArray, seedArrayToString, base64ToUint8Array, } from "./core/utils";
-import { KDF_VERSION, KEY_ALGO, MAJIK_MNEMONIC_SALT, } from "./core/crypto/constants";
+import { KDF_VERSION, MAJIK_MNEMONIC_SALT, } from "./core/crypto/constants";
 import { MajikKeyValidator } from "./core/validator";
 import { MajikKeyError } from "./core/error";
 import { MajikMessageIdentity } from "./core/database/system/identity";
 import { WORDLISTS } from "./core/crypto/wordlist";
 import { deriveBitcoinKeypairFromSeed, signWithBitcoinMaterial, toBitcoinAddress, toWIF, deriveSolanaKeypairFromEdSecretKey, signWithSolanaMaterial, solanaAddressFromPublicKey, solanaMaterialFromEd25519SecretKey, toSolanaAddress, toSolanaKeyPairSigner, } from "./core/web3";
+const secureFill = Uint8Array.prototype.fill;
 const SALT_SIZE = 32;
 /**
  * MajikKey
@@ -56,7 +57,6 @@ export class MajikKey {
     _encryptedMlKemSecretKey;
     _encryptedMlKemSecretKeyBase64;
     _privateKey;
-    _privateKeyBase64;
     _edPublicKey;
     _edSecretKey;
     _encryptedEdSecretKey;
@@ -102,7 +102,6 @@ export class MajikKey {
         this._encryptedMlKemSecretKey = options.encryptedMlKemSecretKey;
         this._encryptedMlKemSecretKeyBase64 = options.encryptedMlKemSecretKeyBase64;
         this._privateKey = options.privateKey;
-        this._privateKeyBase64 = options.privateKeyBase64;
         this._edPublicKey = options.edPublicKey;
         this._encryptedEdSecretKey = options.encryptedEdSecretKey;
         this._encryptedEdSecretKeyBase64 = options.encryptedEdSecretKeyBase64;
@@ -284,7 +283,6 @@ export class MajikKey {
                 encryptedMlKemSecretKey: identity.encryptedMlKemSecretKey,
                 encryptedMlKemSecretKeyBase64: arrayBufferToBase64(identity.encryptedMlKemSecretKey),
                 privateKey: identity.privateKey,
-                privateKeyBase64,
                 edPublicKey: identity.edPublicKey,
                 encryptedEdSecretKey: identity.encryptedEdSecretKey,
                 encryptedEdSecretKeyBase64: arrayBufferToBase64(identity.encryptedEdSecretKey),
@@ -396,11 +394,11 @@ export class MajikKey {
         if (!this._edSecretKey ||
             !this._mlDsaSecretKey ||
             !this._mlKemSecretKey ||
-            !this._privateKeyBase64)
+            !this._privateKey)
             throw new MajikKeyError("MajikKey is missing secret keys — re-import via importFromMnemonicBackup() first.");
         return {
             ...this.toJSON(),
-            privateKeyBase64: this._privateKeyBase64,
+            privateKeyBase64: arrayToBase64(this._privateKey.raw),
             mlKemSecretKeyBase64: arrayToBase64(this._mlKemSecretKey),
             edSecretKeyBase64: arrayToBase64(this._edSecretKey),
             mlDsaSecretKeyBase64: arrayToBase64(this._mlDsaSecretKey),
@@ -448,7 +446,6 @@ export class MajikKey {
                 publicKey: { raw: base64ToUint8Array(parsed.publicKey) },
                 publicKeyBase64: parsed.publicKey,
                 privateKey: { raw: privateKeyBytes },
-                privateKeyBase64: parsed.privateKeyBase64,
                 encryptedPrivateKey: new ArrayBuffer(0),
                 encryptedPrivateKeyBase64: parsed.encryptedPrivateKey,
                 salt: parsed.salt,
@@ -510,11 +507,13 @@ export class MajikKey {
         return this;
     }
     async updatePassphrase(currentPassphrase, newPassphrase) {
+        if (this.isLocked)
+            throw new MajikKeyError("MajikKey must be unlocked to update passphrase");
+        MajikKeyValidator.validatePassphrase(currentPassphrase, "Current passphrase");
+        MajikKeyValidator.validatePassphrase(newPassphrase, "New passphrase");
+        const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
+        const privateKeyBuffer = await MajikKey._decryptPrivateKey(this._encryptedPrivateKey, currentPassphrase, salt, this._kdfVersion);
         try {
-            MajikKeyValidator.validatePassphrase(currentPassphrase, "Current passphrase");
-            MajikKeyValidator.validatePassphrase(newPassphrase, "New passphrase");
-            const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
-            const privateKeyBuffer = await MajikKey._decryptPrivateKey(this._encryptedPrivateKey, currentPassphrase, salt, this._kdfVersion);
             let mlKemSecretKeyBytes;
             if (this._encryptedMlKemSecretKey) {
                 mlKemSecretKeyBytes = await MajikKey._decryptMlKemSecretKey(this._encryptedMlKemSecretKey, currentPassphrase, salt);
@@ -529,6 +528,8 @@ export class MajikKey {
                 const encMlKem = await MajikKey._encryptMlKemSecretKey(mlKemSecretKeyBytes, newPassphrase, newSalt);
                 this._encryptedMlKemSecretKey = encMlKem;
                 this._encryptedMlKemSecretKeyBase64 = arrayBufferToBase64(encMlKem);
+                if (this._mlKemSecretKey)
+                    secureFill.call(this._mlKemSecretKey, 0);
                 this._mlKemSecretKey = mlKemSecretKeyBytes;
             }
             if (this._encryptedEdSecretKey) {
@@ -536,6 +537,8 @@ export class MajikKey {
                 const encEd = await MajikKey._encryptSigningKey(edSecretKeyBytes, newPassphrase, newSalt);
                 this._encryptedEdSecretKey = encEd;
                 this._encryptedEdSecretKeyBase64 = arrayBufferToBase64(encEd);
+                if (this._edSecretKey)
+                    secureFill.call(this._edSecretKey, 0);
                 this._edSecretKey = edSecretKeyBytes;
             }
             if (this._encryptedMlDsaSecretKey) {
@@ -543,6 +546,8 @@ export class MajikKey {
                 const encDsa = await MajikKey._encryptSigningKey(mlDsaSecretKeyBytes, newPassphrase, newSalt);
                 this._encryptedMlDsaSecretKey = encDsa;
                 this._encryptedMlDsaSecretKeyBase64 = arrayBufferToBase64(encDsa);
+                if (this._mlDsaSecretKey)
+                    secureFill.call(this._mlDsaSecretKey, 0);
                 this._mlDsaSecretKey = mlDsaSecretKeyBytes;
             }
             if (this._encryptedBtcSecretKey) {
@@ -550,6 +555,8 @@ export class MajikKey {
                 const encBtc = await MajikKey._encryptSigningKey(btcSecretKeyBytes, newPassphrase, newSalt);
                 this._encryptedBtcSecretKey = encBtc;
                 this._encryptedBtcSecretKeyBase64 = arrayBufferToBase64(encBtc);
+                if (this._btcSecretKey)
+                    secureFill.call(this._btcSecretKey, 0);
                 this._btcSecretKey = btcSecretKeyBytes;
             }
             return this;
@@ -559,18 +566,24 @@ export class MajikKey {
                 throw err;
             throw new MajikKeyError("Failed to update passphrase", err);
         }
+        finally {
+            // Clear the temporary unencrypted buffer
+            secureFill.call(new Uint8Array(privateKeyBuffer), 0);
+            secureFill.call(salt, 0);
+        }
     }
     /**
      * Migrate KDF from PBKDF2 to Argon2id without changing passphrase.
      * NOTE: Does not add ML-KEM keys — use importFromMnemonicBackup() for full upgrade.
      */
     async migrate(passphrase) {
+        MajikKeyValidator.validatePassphrase(passphrase);
+        if (this._kdfVersion === KDF_VERSION.ARGON2ID)
+            return this;
+        const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
+        let privateKeyBuffer;
         try {
-            MajikKeyValidator.validatePassphrase(passphrase);
-            if (this._kdfVersion === KDF_VERSION.ARGON2ID)
-                return this;
-            const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
-            const privateKeyBuffer = await MajikKey._decryptPrivateKey(this._encryptedPrivateKey, passphrase, salt, KDF_VERSION.PBKDF2);
+            privateKeyBuffer = await MajikKey._decryptPrivateKey(this._encryptedPrivateKey, passphrase, salt, KDF_VERSION.PBKDF2);
             const newSalt = generateRandomBytes(SALT_SIZE);
             const { blob } = await MajikKey._encryptPrivateKey(privateKeyBuffer, passphrase, newSalt);
             this._encryptedPrivateKey = blob;
@@ -584,12 +597,34 @@ export class MajikKey {
                 throw err;
             throw new MajikKeyError("Failed to migrate MajikKey to Argon2id", err);
         }
+        finally {
+            if (privateKeyBuffer)
+                secureFill.call(new Uint8Array(privateKeyBuffer), 0);
+            secureFill.call(salt, 0);
+        }
     }
     // ── LOCK / UNLOCK ────────────────────────────────────────────────────────────
     // required
     lock() {
+        // 1. Zeroize raw bytes of all active keys
+        // Apply the secure fill using .call(targetArray, value)
+        if (this._privateKey &&
+            "raw" in this._privateKey &&
+            this._privateKey.raw instanceof Uint8Array) {
+            secureFill.call(this._privateKey.raw, 0);
+        }
+        if (this._mlKemSecretKey)
+            secureFill.call(this._mlKemSecretKey, 0);
+        if (this._edSecretKey)
+            secureFill.call(this._edSecretKey, 0);
+        if (this._mlDsaSecretKey)
+            secureFill.call(this._mlDsaSecretKey, 0);
+        if (this._btcSecretKey)
+            secureFill.call(this._btcSecretKey, 0);
+        if (this._solanaKeypairMaterial) {
+            secureFill.call(this._solanaKeypairMaterial.secretKey, 0);
+        }
         this._privateKey = undefined;
-        this._privateKeyBase64 = undefined;
         this._mlKemSecretKey = undefined;
         this._edSecretKey = undefined;
         this._mlDsaSecretKey = undefined;
@@ -604,18 +639,11 @@ export class MajikKey {
             MajikKeyValidator.validatePassphrase(passphrase);
             const salt = new Uint8Array(base64ToArrayBuffer(this._salt));
             const privateKeyBuffer = await MajikKey._decryptPrivateKey(this._encryptedPrivateKey, passphrase, salt, this._kdfVersion);
-            let privateKey;
-            try {
-                privateKey = await crypto.subtle.importKey("raw", privateKeyBuffer, KEY_ALGO, true, ["sign"]);
-            }
-            catch {
-                privateKey = {
-                    type: "private",
-                    raw: new Uint8Array(privateKeyBuffer),
-                };
-            }
+            const privateKey = {
+                type: "private",
+                raw: new Uint8Array(privateKeyBuffer),
+            };
             this._privateKey = privateKey;
-            this._privateKeyBase64 = arrayBufferToBase64(privateKeyBuffer);
             if (this._encryptedMlKemSecretKey) {
                 this._mlKemSecretKey = await MajikKey._decryptMlKemSecretKey(this._encryptedMlKemSecretKey, passphrase, salt);
             }
@@ -654,7 +682,7 @@ export class MajikKey {
     getPrivateKeyBase64() {
         if (this.isLocked)
             throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
-        return this._privateKeyBase64;
+        return arrayToBase64(this._privateKey.raw);
     }
     getMlKemSecretKey() {
         if (this.isLocked)
@@ -849,7 +877,6 @@ export class MajikKey {
                 encryptedMlKemSecretKey: identity.encryptedMlKemSecretKey,
                 encryptedMlKemSecretKeyBase64: arrayBufferToBase64(identity.encryptedMlKemSecretKey),
                 privateKey: identity.privateKey,
-                privateKeyBase64,
                 edPublicKey: identity.edPublicKey,
                 encryptedEdSecretKey: identity.encryptedEdSecretKey,
                 encryptedEdSecretKeyBase64: arrayBufferToBase64(identity.encryptedEdSecretKey),
@@ -886,19 +913,8 @@ export class MajikKey {
     static async _deriveAndEncryptFromMnemonic(mnemonic, passphrase, options) {
         const deriveBitcoin = options?.deriveBitcoin ?? true;
         const encIdentity = await EncryptionEngine.deriveIdentityFromMnemonic(mnemonic);
-        let exportedXPrivate;
-        try {
-            exportedXPrivate = await crypto.subtle.exportKey("raw", encIdentity.privateKey);
-        }
-        catch {
-            const anyPriv = encIdentity.privateKey;
-            if (anyPriv?.raw instanceof Uint8Array) {
-                exportedXPrivate = anyPriv.raw.buffer.slice(anyPriv.raw.byteOffset, anyPriv.raw.byteOffset + anyPriv.raw.byteLength);
-            }
-            else {
-                throw new MajikKeyError("Cannot export private key: unsupported format");
-            }
-        }
+        const anyPriv = encIdentity.privateKey;
+        const exportedXPrivate = anyPriv.raw.buffer.slice(anyPriv.raw.byteOffset, anyPriv.raw.byteOffset + anyPriv.raw.byteLength);
         // Single salt — one Argon2id derivation unlocks every key below
         const salt = generateRandomBytes(SALT_SIZE);
         const { blob: encryptedPrivateKey } = await MajikKey._encryptPrivateKey(exportedXPrivate, passphrase, salt);
@@ -997,13 +1013,18 @@ export class MajikKey {
     }
     static async _decryptSigningKey(buffer, passphrase, salt) {
         const keyBytes = await deriveKeyFromPassphraseArgon2(passphrase, salt);
-        const full = new Uint8Array(buffer);
-        const iv = full.slice(0, IV_LENGTH);
-        const ciphertext = full.slice(IV_LENGTH);
-        const plain = aesGcmDecrypt(keyBytes, iv, ciphertext);
-        if (!plain)
-            throw new MajikKeyError("Failed to decrypt signing key");
-        return plain;
+        try {
+            const full = new Uint8Array(buffer);
+            const iv = full.slice(0, IV_LENGTH);
+            const ciphertext = full.slice(IV_LENGTH);
+            const plain = aesGcmDecrypt(keyBytes, iv, ciphertext);
+            if (!plain)
+                throw new MajikKeyError("Failed to decrypt signing key");
+            return plain;
+        }
+        finally {
+            secureFill.call(keyBytes, 0);
+        }
     }
     // ── PRIVATE: Backup ──────────────────────────────────────────────────────────
     static async _verifyBackupDecryption(ivBase64, ciphertextBase64, mnemonic, backupKdfVersion) {
@@ -1029,26 +1050,10 @@ export class MajikKey {
     static async _exportMnemonicBackup(identity, mnemonic) {
         if (!identity?.privateKey)
             throw new MajikKeyError("Identity must have privateKey to export backup");
-        let privRawBuf;
-        let pubRawBuf;
-        try {
-            privRawBuf = await crypto.subtle.exportKey("raw", identity.privateKey);
-            pubRawBuf = await crypto.subtle.exportKey("raw", identity.publicKey);
-        }
-        catch {
-            const anyPriv = identity.privateKey;
-            const anyPub = identity.publicKey;
-            if (anyPriv?.raw instanceof Uint8Array) {
-                privRawBuf = anyPriv.raw.buffer.slice(anyPriv.raw.byteOffset, anyPriv.raw.byteOffset + anyPriv.raw.byteLength);
-            }
-            else
-                throw new MajikKeyError("Cannot export private key");
-            if (anyPub?.raw instanceof Uint8Array) {
-                pubRawBuf = anyPub.raw.buffer.slice(anyPub.raw.byteOffset, anyPub.raw.byteOffset + anyPub.raw.byteLength);
-            }
-            else
-                throw new MajikKeyError("Cannot export public key");
-        }
+        const anyPriv = identity.privateKey;
+        const anyPub = identity.publicKey;
+        const privRawBuf = anyPriv.raw.buffer.slice(anyPriv.raw.byteOffset, anyPriv.raw.byteOffset + anyPriv.raw.byteLength);
+        const pubRawBuf = anyPub.raw.buffer.slice(anyPub.raw.byteOffset, anyPub.raw.byteOffset + anyPub.raw.byteLength);
         const mnemonicSalt = new TextEncoder().encode(MAJIK_MNEMONIC_SALT);
         const keyBytes = await deriveKeyFromMnemonicArgon2(mnemonic, mnemonicSalt);
         const iv = generateRandomBytes(IV_LENGTH);
@@ -1210,3 +1215,7 @@ export class MajikKey {
         return solanaAddressFromPublicKey(this.getSolanaKeypairMaterial(options).publicKey);
     }
 }
+// Freeze static methods (e.g., MajikKey.create, MajikKey.fromJSON)
+Object.freeze(MajikKey);
+// Freeze instance methods (e.g., this.lock, this.unlock)
+Object.freeze(MajikKey.prototype);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@majikah/majik-key",
   "type": "module",
   "description": "A post-quantum ready seed phrase account library for the Majikah ecosystem. Manages deterministic X25519 and ML-KEM-768 identities with Argon2id protection and seamless legacy account migration.",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",
@@ -48,6 +48,7 @@
     "package": "npm run build && npm version patch && git push && git push --tags",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:compat": "npx vitest test/majik-key-cross-compat.test.ts",
     "test:web3:bitcoin": "npx vitest test/majik-key-bitcoin.test.ts",
     "test:web3:solana": "npx vitest test/majik-key-solana.test.ts",
     "test:web3": "npx vitest test/majik-key-bitcoin.test.ts test/majik-key-solana.test.ts",
@@ -74,9 +75,9 @@
     "@scure/btc-signer": "^2.2.0",
     "@solana/kit": "^7.0.0",
     "@types/ed2curve": "^0.2.4",
-    "@types/node": "^26.1.0",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.9"
+    "@types/node": "^26.1.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "@scure/btc-signer": "^2.2.0",