@majikah/majik-key 0.3.3 → 0.4.0

package/README.md

@@ -1,13 +1,16 @@
 # Majik Key
 
+[![ZENODO](https://img.shields.io/badge/Read_the_Technical_Whitepaper_Here-1682D4?style=for-the-badge&logo=zenodo&logoColor=white)](https://doi.org/10.5281/zenodo.21339132)
 
 
 [![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)
 
-[![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.
 
+[![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)
+
 ---
 
 ## Why Majik Key

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

@@ -1,16 +1,13 @@
+import type { ED25519RawPublicKey, MajikKeyFingerprint, MLDSA87RawPublicKey, MLKEM768RawPublicKey, X25519RawKey } from "../types";
 export interface EncryptionIdentity {
-    publicKey: {
-        raw: Uint8Array;
-    };
-    privateKey: {
-        raw: Uint8Array;
-    };
-    fingerprint: string;
-    mlKemPublicKey: Uint8Array;
+    publicKey: X25519RawKey;
+    privateKey: X25519RawKey;
+    fingerprint: MajikKeyFingerprint;
+    mlKemPublicKey: MLKEM768RawPublicKey;
     mlKemSecretKey?: Uint8Array;
-    edPublicKey: Uint8Array;
+    edPublicKey: ED25519RawPublicKey;
     edSecretKey: Uint8Array;
-    mlDsaPublicKey: Uint8Array;
+    mlDsaPublicKey: MLDSA87RawPublicKey;
     mlDsaSecretKey: Uint8Array;
 }
 /**
@@ -41,9 +38,7 @@ export declare class EncryptionEngine {
     /**
      * Generates a SHA-256 fingerprint from a public key.
      */
-    static fingerprintFromPublicKey(publicKey: CryptoKey | {
-        raw: Uint8Array;
-    }): Promise<string>;
+    static fingerprintFromPublicKey(publicKey: CryptoKey | X25519RawKey): Promise<string>;
     private static assertPublicKey;
 }
 export declare class CryptoError extends Error {

package/dist/core/types.d.ts

@@ -1,13 +1,21 @@
 import { MnemonicLanguage } from "./crypto/wordlist";
 /** ISO 8601 timestamp string, e.g. `"2026-07-11T00:00:00.000Z"`. */
 export type ISODateString = string;
-export type MajikMessageAccountID = string;
-export type MajikMessagePublicKey = string;
-export type MajikMessageChatID = string;
 /** Base64-encoded public key material. Safe to store, log, or transmit. */
 export type MajikKeyAddress = string;
 /** Base64-encoded SHA-256 digest of a MajikKey's X25519 public key. Doubles as the account `id`. */
 export type MajikKeyFingerprint = string;
+export type ED25519PublicKey = string;
+export type MLKEM768PublicKey = string;
+export type MLDSA87PublicKey = string;
+export type BitcoinPublicKey = string;
+export type ED25519RawPublicKey = Uint8Array;
+export type MLKEM768RawPublicKey = Uint8Array;
+export type MLDSA87RawPublicKey = Uint8Array;
+export type BitcoinRawPublicKey = Uint8Array;
+export interface X25519RawKey {
+    raw: Uint8Array;
+}
 /**
  * Safe, serializable snapshot of a MajikKey — what `toJSON()` / `toString()` produce.
  *
@@ -21,7 +29,7 @@ export type MajikKeyFingerprint = string;
  */
 export interface MajikKeyJSON {
     /** Account identifier. Equal to `fingerprint` for accounts created by this library. */
-    id: string;
+    id: MajikKeyFingerprint;
     /** Human-readable, user-editable account name. */
     label: string;
     /** X25519 public key, base64. */
@@ -40,23 +48,23 @@ export interface MajikKeyJSON {
      */
     backup: string;
     /** Account creation time, ISO 8601. */
-    timestamp: string;
+    timestamp: ISODateString;
     /** KDF used for every `encrypted*` field on this account: `1` = legacy PBKDF2 (read-only), `2` = Argon2id (current). Defaults to `1` if omitted. */
     kdfVersion?: number;
     /** ML-KEM-768 (FIPS-203) public key, base64. Post-quantum key encapsulation. */
-    mlKemPublicKey?: string;
+    mlKemPublicKey?: MLKEM768PublicKey;
     /** AES-256-GCM-encrypted ML-KEM-768 secret key, base64. */
     encryptedMlKemSecretKey?: string;
     /** Ed25519 public key, base64. Classical signing — same keypair the X25519 identity key is converted from. */
-    edPublicKey?: string;
+    edPublicKey?: ED25519PublicKey;
     /** AES-256-GCM-encrypted Ed25519 secret key, base64. */
     encryptedEdSecretKey?: string;
     /** ML-DSA-87 (FIPS-204) public key, base64. Post-quantum signing. */
-    mlDsaPublicKey?: string;
+    mlDsaPublicKey?: MLDSA87PublicKey;
     /** AES-256-GCM-encrypted ML-DSA-87 secret key, base64. */
     encryptedMlDsaSecretKey?: string;
     /** @experimental secp256k1 Bitcoin public key, base64. Domain-separated BIP-32/84 derivation by default — see `MajikKeyBitcoinNamespace`. */
-    btcPublicKey?: string;
+    btcPublicKey?: BitcoinPublicKey;
     /** @experimental AES-256-GCM-encrypted Bitcoin private key, base64. */
     encryptedBtcSecretKey?: string;
     /** BIP-39 wordlist language the original mnemonic was generated/validated against. Defaults to `"en"`. */
@@ -132,4 +140,5 @@ export interface MnemonicJSON {
     id: string;
     /** Optional passphrase, carried in plaintext for convenience during export/import. ⚠️ Not encrypted. */
     phrase?: string;
+    language?: MnemonicLanguage;
 }

package/dist/core/web3/bitcoin/bitcoin.d.ts

@@ -23,11 +23,12 @@
  *     installed, we throw a clear, actionable MajikKeyError instead of
  *     failing module load.
  */
+import { BitcoinRawPublicKey } from "../../types";
 export interface BitcoinKeypairMaterial {
     /** 32-byte secp256k1 private key. */
     privateKey: Uint8Array;
     /** 33-byte compressed secp256k1 public key. */
-    publicKey: Uint8Array;
+    publicKey: BitcoinRawPublicKey;
 }
 export interface BitcoinDerivationOptions {
     /**

package/dist/core/web3/bitcoin/types.d.ts

@@ -1,3 +1,4 @@
+import { BitcoinRawPublicKey } from "../../types";
 /**
  * @experimental By default this is Majik's DOMAIN-SEPARATED Bitcoin key
  * (derived via `MAJIK_BITCOIN_DOMAIN_PATH`) — deterministic and fully
@@ -9,7 +10,7 @@
  */
 export interface MajikKeyBitcoinNamespace {
     /** 33-byte compressed secp256k1 public key. */
-    readonly publicKey: Uint8Array;
+    readonly publicKey: BitcoinRawPublicKey;
     /** 32-byte secp256k1 private key. Handle with the same care as any private key. */
     readonly privateKey: Uint8Array;
     /** Native SegWit (bech32) address. Lazily loads @scure/btc-signer — throws if not installed. */

package/dist/core/web3/solana/solana.d.ts

@@ -25,9 +25,10 @@
  *      signing Ed25519 keypair AS-IS. Simpler, but means the same private
  *      key secures two different protocols. Opt-in only.
  */
+import { ED25519RawPublicKey } from "../../types";
 export interface SolanaKeypairMaterial {
     /** 32-byte Ed25519 / Solana public key. */
-    publicKey: Uint8Array;
+    publicKey: ED25519RawPublicKey;
     /** 64-byte nacl-format secret key (32-byte seed || 32-byte public key). */
     secretKey: Uint8Array;
 }

package/dist/core/web3/solana/types.d.ts

@@ -1,10 +1,11 @@
+import { ED25519RawPublicKey } from "../../types";
 /**
  * @experimental Web3 / blockchain integrations are experimental. This
  * namespace's shape may change without a major version bump.
  */
 export interface MajikKeySolanaNamespace {
     /** 32-byte Solana/Ed25519 public key. */
-    readonly publicKey: Uint8Array;
+    readonly publicKey: ED25519RawPublicKey;
     /** 64-byte nacl-format secret key. Handle with the same care as any private key. */
     readonly secretKey: Uint8Array;
     /** Base58 Solana address — does not require @solana/kit. */

package/dist/majik-key.d.ts

@@ -5,7 +5,7 @@
  */
 import { MajikContact, MajikContactMeta } from "@majikah/majik-contact";
 import { KDF_VERSION } from "./core/crypto/constants";
-import type { MajikKeyAddress, MajikKeyDangerousJSON, MajikKeyFingerprint, MajikKeyJSON, MajikKeyMetadata, MnemonicJSON } from "./core/types";
+import type { BitcoinRawPublicKey, ED25519RawPublicKey, MajikKeyAddress, MajikKeyDangerousJSON, MajikKeyFingerprint, MajikKeyJSON, MajikKeyMetadata, MLDSA87RawPublicKey, MLKEM768RawPublicKey, MnemonicJSON, X25519RawKey } from "./core/types";
 import { MajikMessageIdentity } from "./core/database/system/identity";
 import { MajikUser } from "@thezelijah/majik-user";
 import { MnemonicLanguage } from "./core/crypto/wordlist";
@@ -24,17 +24,13 @@ import { MajikKeyWeb3Namespace, BitcoinDerivationOptions, BitcoinKeypairMaterial
  */
 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: {
-        raw: Uint8Array;
-    };
+    id: MajikKeyFingerprint;
+    /** X25519 public key */
+    publicKey: X25519RawKey;
     /** SHA-256 fingerprint of `publicKey`. */
     fingerprint: MajikKeyFingerprint;
     /** X25519 private key, decrypted into memory. ⚠️ Live key material — do not log or serialize directly. */
-    privateKey: {
-        raw: Uint8Array;
-    };
+    privateKey: X25519RawKey;
     /** AES-256-GCM-encrypted X25519 private key (IV + ciphertext), as stored at rest. */
     encryptedPrivateKey: ArrayBuffer;
     /** Random salt used to derive the passphrase-based encryption key. Base64. */
@@ -106,9 +102,7 @@ export interface SerializedIdentity {
  */
 export interface MajikKeyConstructorOptions {
     id: string;
-    publicKey: {
-        raw: Uint8Array;
-    };
+    publicKey: X25519RawKey;
     publicKeyBase64: MajikKeyAddress;
     fingerprint: MajikKeyFingerprint;
     encryptedPrivateKey: ArrayBuffer;
@@ -120,19 +114,17 @@ export interface MajikKeyConstructorOptions {
     timestamp?: Date;
     /** Defaults to legacy PBKDF2 (`KDF_VERSION.PBKDF2`) if omitted — see the private constructor. */
     kdfVersion?: KDF_VERSION;
-    mlKemPublicKey: Uint8Array;
+    mlKemPublicKey: MLKEM768RawPublicKey;
     /** Present only when constructing an already-unlocked instance. ⚠️ Live key material. */
     mlKemSecretKey?: Uint8Array;
     encryptedMlKemSecretKey?: ArrayBuffer;
     encryptedMlKemSecretKeyBase64?: string;
     /** Present only when constructing an already-unlocked instance. ⚠️ Live key material. */
-    privateKey?: {
-        raw: Uint8Array;
-    };
-    edPublicKey?: Uint8Array;
+    privateKey?: X25519RawKey;
+    edPublicKey?: ED25519RawPublicKey;
     encryptedEdSecretKey?: ArrayBuffer;
     encryptedEdSecretKeyBase64?: string;
-    mlDsaPublicKey?: Uint8Array;
+    mlDsaPublicKey?: MLDSA87RawPublicKey;
     encryptedMlDsaSecretKey?: ArrayBuffer;
     encryptedMlDsaSecretKeyBase64?: string;
     /** Present only when constructing an already-unlocked instance. ⚠️ Live key material. */
@@ -140,7 +132,7 @@ export interface MajikKeyConstructorOptions {
     /** Present only when constructing an already-unlocked instance. ⚠️ Live key material. */
     mlDsaSecretKey?: Uint8Array;
     /** @experimental secp256k1 Bitcoin public key. */
-    btcPublicKey?: Uint8Array;
+    btcPublicKey?: BitcoinRawPublicKey;
     /** @experimental AES-256-GCM-encrypted Bitcoin private key. */
     encryptedBtcSecretKey?: ArrayBuffer;
     /** @experimental Base64 form of `encryptedBtcSecretKey`. */
@@ -220,13 +212,11 @@ export declare class MajikKey {
     private _encryptedBtcSecretKeyBase64?;
     private constructor();
     /** Account identifier. Equal to `fingerprint` for accounts created by this library. */
-    get id(): string;
+    get id(): MajikKeyFingerprint;
     /** SHA-256 fingerprint of the X25519 public key. Stable identity anchor for the account. */
     get fingerprint(): MajikKeyFingerprint;
-    /** X25519 public key — native `CryptoKey` where WebCrypto supports it, otherwise a raw-bytes wrapper. Always available, even when locked. */
-    get publicKey(): CryptoKey | {
-        raw: Uint8Array;
-    };
+    /** X25519 public key. Always available, even when locked. */
+    get publicKey(): X25519RawKey;
     /** X25519 public key, base64-encoded. Always available, even when locked. */
     get publicKeyBase64(): MajikKeyAddress;
     /** Human-readable, user-editable account name. Update via `updateLabel()`. */
@@ -251,7 +241,7 @@ export declare class MajikKey {
     /** `true` if private key material is currently decrypted in memory. The inverse of `isLocked`. */
     get isUnlocked(): boolean;
     /** ML-KEM-768 (FIPS-203) public key. Post-quantum key encapsulation. Always available, even when locked. */
-    get mlKemPublicKey(): Uint8Array;
+    get mlKemPublicKey(): MLKEM768RawPublicKey;
     /** ML-KEM-768 secret key. `undefined` unless the account is unlocked. ⚠️ Live key material — prefer `getMlKemSecretKey()` if you want a thrown error instead of `undefined` on locked accounts. */
     get mlKemSecretKey(): Uint8Array | undefined;
     /** `true` if this account has ML-KEM-768 keys (i.e. is post-quantum-encryption capable). `false` means it's a legacy account pending migration. */
@@ -263,7 +253,7 @@ export declare class MajikKey {
      * has no stored Bitcoin key material (e.g. it predates Web3 support and
      * hasn't been re-imported via `importFromMnemonicBackup()`).
      */
-    get btcPublicKey(): Uint8Array | undefined;
+    get btcPublicKey(): BitcoinRawPublicKey | undefined;
     /** @experimental `true` if this account has a stored Bitcoin keypair. */
     get hasBitcoin(): boolean;
     /**
@@ -273,9 +263,9 @@ export declare class MajikKey {
      */
     get metadata(): MajikKeyMetadata;
     /** Ed25519 public key. Classical signing — same keypair the X25519 identity key is converted from. Always available, even when locked. */
-    get edPublicKey(): Uint8Array | undefined;
+    get edPublicKey(): ED25519RawPublicKey | undefined;
     /** ML-DSA-87 (FIPS-204) public key. Post-quantum signing. Always available, even when locked. */
-    get mlDsaPublicKey(): Uint8Array | undefined;
+    get mlDsaPublicKey(): MLDSA87RawPublicKey | undefined;
     /** `true` if this account has both Ed25519 and ML-DSA-87 signing keys. `false` means it's a legacy account pending migration. */
     get hasSigningKeys(): boolean;
     /**
@@ -331,9 +321,7 @@ export declare class MajikKey {
     lock(): this;
     unlock(passphrase: string): Promise<this>;
     verify(passphrase: string): Promise<boolean>;
-    getPrivateKey(): CryptoKey | {
-        raw: Uint8Array;
-    };
+    getPrivateKey(): X25519RawKey;
     getPrivateKeyBase64(): string;
     getMlKemSecretKey(): Uint8Array;
     getEdSecretKey(): Uint8Array;

package/dist/majik-key.js

@@ -125,7 +125,7 @@ export class MajikKey {
     get fingerprint() {
         return this._fingerprint;
     }
-    /** X25519 public key — native `CryptoKey` where WebCrypto supports it, otherwise a raw-bytes wrapper. Always available, even when locked. */
+    /** X25519 public key. Always available, even when locked. */
     get publicKey() {
         return this._publicKey;
     }
@@ -478,6 +478,7 @@ export class MajikKey {
             id: this._backup,
             seed: seedStringToArray(mnemonic.trim()),
             phrase: passphrase?.trim() || undefined,
+            language: this._mnemonicLanguage,
         };
     }
     static async fromMnemonicJSON(mnemonicJson, passphrase, label, options = {

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.3",
+  "version": "0.4.0",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",
@@ -56,11 +56,11 @@
   },
   "dependencies": {
     "@majikah/majik-contact": "^0.0.6",
-    "@noble/curves": "^2.2.0",
-    "@noble/hashes": "^2.2.0",
-    "@noble/post-quantum": "^0.6.1",
-    "@scure/bip32": "^2.2.0",
-    "@scure/bip39": "^2.2.0",
+    "@noble/curves": "^2.3.0",
+    "@noble/hashes": "^2.3.0",
+    "@noble/post-quantum": "^0.7.0",
+    "@scure/bip32": "^2.3.0",
+    "@scure/bip39": "^2.3.0",
     "@stablelib/aes": "^2.0.1",
     "@stablelib/ed25519": "^2.1.0",
     "@stablelib/gcm": "^2.0.1",
@@ -72,10 +72,10 @@
     "hash-wasm": "^4.12.0"
   },
   "devDependencies": {
-    "@scure/btc-signer": "^2.2.0",
-    "@solana/kit": "^7.0.0",
+    "@scure/btc-signer": "^2.3.0",
+    "@solana/kit": "^7.1.0",
     "@types/ed2curve": "^0.2.4",
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.2.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   },