{"id":51054485,"url":"https://github.com/majikah/majik-key","last_synced_at":"2026-06-22T20:01:09.899Z","repository":{"id":337240140,"uuid":"1150539304","full_name":"Majikah/majik-key","owner":"Majikah","description":"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.","archived":false,"fork":false,"pushed_at":"2026-04-13T10:31:46.000Z","size":216,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T12:28:47.544Z","etag":null,"topics":["bip39","crypto","cryptography","key","keypairs","majik-message","mnemonic","security","seed-phrase"],"latest_commit_sha":null,"homepage":"https://majikah.solutions/products/majik-message","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Majikah.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":"FUNDING.yaml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["jedlsf"]}},"created_at":"2026-02-05T11:57:14.000Z","updated_at":"2026-04-13T10:31:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Majikah/majik-key","commit_stats":null,"previous_names":["majikah/majik-key"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Majikah/majik-key","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Majikah%2Fmajik-key","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Majikah%2Fmajik-key/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Majikah%2Fmajik-key/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Majikah%2Fmajik-key/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Majikah","download_url":"https://codeload.github.com/Majikah/majik-key/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Majikah%2Fmajik-key/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34663524,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bip39","crypto","cryptography","key","keypairs","majik-message","mnemonic","security","seed-phrase"],"created_at":"2026-06-22T20:01:08.690Z","updated_at":"2026-06-22T20:01:09.893Z","avatar_url":"https://github.com/Majikah.png","language":"TypeScript","funding_links":["https://github.com/sponsors/jedlsf"],"categories":[],"sub_categories":[],"readme":"# Majik Key\n\n[![Developed by Zelijah](https://img.shields.io/badge/Developed%20by-Zelijah-red?logo=github\u0026logoColor=white)](https://thezelijah.world) ![GitHub Sponsors](https://img.shields.io/github/sponsors/jedlsf?style=plastic\u0026label=Sponsors\u0026link=https%3A%2F%2Fgithub.com%2Fsponsors%2Fjedlsf)\n\n**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.\n\n![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)\n\n\n\n---\n- [Majik Key](#majik-key)\n  - [Next-Gen Security Architecture](#next-gen-security-architecture)\n    - [1. Post-Quantum Ready (ML-KEM)](#1-post-quantum-ready-ml-kem)\n    - [2. Argon2id Key Derivation](#2-argon2id-key-derivation)\n    - [3. Seamless Auto-Migration](#3-seamless-auto-migration)\n  - [Overview](#overview)\n    - [What is a Majik Key?](#what-is-a-majik-key)\n    - [Use Cases](#use-cases)\n  - [Features](#features)\n    - [Security \\\u0026 Post-Quantum Readiness](#security--post-quantum-readiness)\n    - [BIP39 Compliance \\\u0026 Key Derivation](#bip39-compliance--key-derivation)\n    - [Developer Experience](#developer-experience)\n    - [Import / Export \\\u0026 Storage](#import--export--storage)\n    - [Interoperability](#interoperability)\n  - [Installation](#installation)\n  - [Quick Start](#quick-start)\n  - [API Reference](#api-reference)\n    - [Static Methods](#static-methods)\n      - [`MajikKey.create(mnemonic, passphrase, label?)`](#majikkeycreatemnemonic-passphrase-label)\n      - [`MajikKey.fromJSON(json)`](#majikkeyfromjsonjson)\n      - [`MajikKey.fromMnemonicJSON(mnemonicJson, passphrase, label?)`](#majikkeyfrommnemonicjsonmnemonicjson-passphrase-label)\n      - [`MajikKey.importFromMnemonicBackup(backup, mnemonic, passphrase, label?)`](#majikkeyimportfrommnemonicbackupbackup-mnemonic-passphrase-label)\n      - [`MajikKey.generateMnemonic(strength?)`](#majikkeygeneratemnemonicstrength)\n      - [`MajikKey.validateMnemonic(mnemonic)`](#majikkeyvalidatemnemonicmnemonic)\n    - [Instance Methods](#instance-methods)\n      - [`unlock(passphrase)`](#unlockpassphrase)\n      - [`lock()`](#lock)\n      - [`verify(passphrase)`](#verifypassphrase)\n      - [`updateLabel(newLabel)`](#updatelabelnewlabel)\n      - [`updatePassphrase(currentPassphrase, newPassphrase)`](#updatepassphrasecurrentpassphrase-newpassphrase)\n      - [`getPrivateKey()`](#getprivatekey)\n      - [`getPrivateKeyBase64()`](#getprivatekeybase64)\n      - [`toJSON()`](#tojson)\n      - [`toString(pretty?)`](#tostringpretty)\n      - [`toMnemonicJSON(mnemonic, passphrase?)`](#tomnemonicjsonmnemonic-passphrase)\n      - [`exportMnemonicBackup(mnemonic)`](#exportmnemonicbackupmnemonic)\n      - [`toContact()`](#tocontact)\n      - [`toMajikMessageIdentity(user, options?)`](#tomajikmessageidentityuser-options)\n    - [Getters](#getters)\n      - [`id: string`](#id-string)\n      - [`fingerprint: string`](#fingerprint-string)\n      - [`publicKey: CryptoKey | { raw: Uint8Array }`](#publickey-cryptokey---raw-uint8array-)\n      - [`publicKeyBase64: string`](#publickeybase64-string)\n      - [`label: string`](#label-string)\n      - [`backup: string`](#backup-string)\n      - [`timestamp: Date`](#timestamp-date)\n      - [`isLocked: boolean`](#islocked-boolean)\n      - [`isUnlocked: boolean`](#isunlocked-boolean)\n      - [`metadata: MajikKeyMetadata`](#metadata-majikkeymetadata)\n  - [Usage Examples](#usage-examples)\n    - [Example 1: Create and Manage a Key](#example-1-create-and-manage-a-key)\n    - [Example 2: Lock/Unlock Pattern](#example-2-lockunlock-pattern)\n    - [Example 3: Backup and Recovery](#example-3-backup-and-recovery)\n    - [Example 4: Update Passphrase](#example-4-update-passphrase)\n    - [Example 5: Verify Passphrase](#example-5-verify-passphrase)\n  - [Integration with Majik Message](#integration-with-majik-message)\n    - [Importing to Majik Message](#importing-to-majik-message)\n    - [Converting to Majik Message Identity](#converting-to-majik-message-identity)\n  - [Security Considerations](#security-considerations)\n    - [Best Practices](#best-practices)\n    - [What NOT to Do](#what-not-to-do)\n    - [What TO Do](#what-to-do)\n    - [Tips \\\u0026 Reminders](#tips--reminders)\n      - [For Developers](#for-developers)\n      - [For Users](#for-users)\n  - [Related Projects](#related-projects)\n    - [Majik Message](#majik-message)\n  - [Contributing](#contributing)\n  - [License](#license)\n  - [Author](#author)\n  - [About the Developer](#about-the-developer)\n  - [Contact](#contact)\n\n\n\n\n---\n\n## Next-Gen Security Architecture\n\nMajik Key has been upgraded to meet modern and future cryptographic standards.\n\n### 1. Post-Quantum Ready (ML-KEM)\nEvery identity now generates a dual-key system derived deterministically from a 64-byte BIP39 seed:\n* **X25519 (Curve25519):** Derived from the first 32 bytes of the seed. Used for fingerprints, contact identity, and legacy compatibility.\n* **ML-KEM-768 (FIPS-203):** Derived from the full 64-byte seed. Provides post-quantum key encapsulation for \"v3\" secure envelopes.\n\n### 2. Argon2id Key Derivation\nWe have transitioned to **Argon2id** (KDF v2) for encrypting private keys at rest.\n* **Memory-Hard:** Configured with 64 MB of memory, 3 iterations, and 4 parallelism factors.\n* **Brute-Force Resistant:** Engineered to defeat GPU and ASIC-based cracking attempts that easily bypass older PBKDF2 implementations.\n\n### 3. Seamless Auto-Migration\nThe library handles \"Security Debt\" automatically during standard workflows:\n* **On Import:** `importFromMnemonicBackup()` detects v1 (PBKDF2) accounts and performs a full upgrade to v2. \n* **Deterministic Recovery:** If ML-KEM keys are missing from an old backup, they are re-derived from the mnemonic during the upgrade process.\n* **Password Updates:** Changing a passphrase via `updatePassphrase()` automatically migrates the account to the latest Argon2id standard.\n---\n\n\n\n## Overview\n\n**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.\n\n### What is a Majik Key?\n\nA Majik Key is a seed phrase account that:\n- Derives cryptographic key pairs from BIP39 mnemonic phrases\n- Encrypts private keys at rest with a user-defined passphrase\n- Supports secure backup and recovery via mnemonic encryption\n- Provides locked/unlocked state management for enhanced security\n- Is fully compatible with **Majik Message** and other Majikah products\n\n### Use Cases\n\n- **Majik Message Integration**: Create seed phrase accounts that can be imported directly into Majik Message\n- **Cryptographic Identity Management**: Manage multiple identities with deterministic key derivation\n- **Secure Messaging**: Generate signing keys for end-to-end encrypted communication\n- **Blockchain Applications**: Create wallet-like accounts from mnemonic phrases\n- **Majikah Ecosystem**: Use across all Majikah products and services\n\n---\n\n## Features\n\n### Security \u0026 Post-Quantum Readiness\n- **Post-Quantum Ready**: Implements **ML-KEM-768 (FIPS-203)** for key encapsulation, ensuring identities are secure against future quantum computing threats.\n- **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.\n- **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.\n- **AES-GCM Authenticated Encryption**: Industry-standard encryption for private keys at rest with unique, per-identity salts and random IVs.\n- **Locked/Unlocked States**: Private keys are only decrypted into memory when explicitly unlocked and are purged immediately upon calling `.lock()`.\n\n### BIP39 Compliance \u0026 Key Derivation\n- **Standard Mnemonic Generation**: Generate high-entropy 12 or 24-word seed phrases (128/256-bit strength).\n- **Deterministic Multi-Key Derivation**: \n    - **X25519 (Curve25519)**: Derived from the first 32 bytes of the seed for legacy compatibility and fingerprints.\n    - **ML-KEM-768**: Derived from the full 64-byte seed for post-quantum security.\n- **Built-in Validation**: Full BIP39 mnemonic validation and error handling.\n\n### Developer Experience\n- **First-Class TypeScript Support**: Full type definitions included for all interfaces and classes.\n- **Fluent API**: Intuitive method chaining for common operations (e.g., `key.unlock(p).updateLabel(l)`).\n- **Comprehensive Error Handling**: Specialized `MajikKeyError` and `CryptoError` classes for precise debugging.\n- **Isomorphic Support**: Works across Node.js and modern browser environments.\n\n### Import / Export \u0026 Storage\n- **Security-Minded JSON Serialization**: Export accounts to JSON format for storage without ever exposing raw private keys or seed phrases.\n- **MnemonicJSON Format**: A secure, portable format for seed phrase storage and recovery.\n- **Mnemonic-Encrypted Backups**: Export and import specialized backup strings that utilize the mnemonic as a secondary encryption layer.\n\n### Interoperability\n- **Majik Message Integration**: Native support for exporting identities compatible with **Majik Message v3** envelopes.\n- **Contact Portability**: Convert Majik Keys directly into contact formats for easy sharing of public identities.\n- **Ecosystem Ready**: Designed as the core identity provider for all current and future Majikah products.\n---\n\n## Installation\n\n```bash\n# Using npm\nnpm install @majikah/majik-key\n\n```\n\n---\n\n## Quick Start\n\n```ts\nimport { MajikKey } from '@majikah/majik-key';\n\n// Generate a new mnemonic\nconst mnemonic = MajikKey.generateMnemonic(); // 12 words\nconsole.log('Save this mnemonic:', mnemonic);\n\n// Create a new Majik Key (unlocked state)\nconst key = await MajikKey.create(mnemonic, 'secure-passphrase', 'My PQ Account');\n\n// 2. Access your keys (requires unlock)\nconsole.log('Fingerprint:', key.fingerprint);\nconsole.log('PQ Ready:', key.metadata.kdfVersion); // 'argon2id'\nconsole.log('Key ID:', key.id);\nconsole.log('Is Unlocked:', key.isUnlocked); // true\n\n// Lock the key (clear private keys from memory)\nkey.lock();\nconsole.log('Is Locked:', key.isLocked); // true\n\n// Unlock when needed\nawait key.unlock('my-secure-passphrase');\nconsole.log('Is Unlocked:', key.isUnlocked); // true\n\n// Access private key (only when unlocked)\nconst privateKey = key.getPrivateKey();\nconst privateKeyBase64 = key.getPrivateKeyBase64();\n\n// Save to storage (private keys never included)\nconst json = key.toJSON();\nlocalStorage.setItem('myKey', JSON.stringify(json));\n\n// Load from storage (locked state)\nconst loadedKey = MajikKey.fromJSON(json);\nawait loadedKey.unlock('my-secure-passphrase');\n```\n\n---\n\n## API Reference\n\n### Static Methods\n\n#### `MajikKey.create(mnemonic, passphrase, label?)`\nCreate a new Majik Key from a mnemonic phrase. Generates a new Argon2id-protected account.\n\n**Parameters:**\n- `mnemonic: string` - BIP39 mnemonic phrase (12-24 words)\n- `passphrase: string` - Passphrase to encrypt the private key at rest\n- `label?: string` - Optional label for the key\n\n**Returns:** `Promise\u003cMajikKey\u003e` - A new unlocked MajikKey instance\n\n**Example:**\n```ts\nconst mnemonic = 'witch collapse practice feed shame open despair creek road again ice least';\nconst key = await MajikKey.create(mnemonic, 'my-password', 'Personal Account');\n\n```\n\n---\n\n#### `MajikKey.fromJSON(json)`\nLoad a Majik Key from JSON (locked state).\n\n**Parameters:**\n- `json: MajikKeyJSON | string` - JSON object or string\n\n**Returns:** `MajikKey` - A locked MajikKey instance\n\n**Example:**\n```ts\nconst json = localStorage.getItem('myKey');\nconst key = MajikKey.fromJSON(json);\nawait key.unlock('my-password');\n```\n\n---\n\n#### `MajikKey.fromMnemonicJSON(mnemonicJson, passphrase, label?)`\nCreate a Majik Key from MnemonicJSON format. Auto-migrates legacy PBKDF2 accounts to Argon2id + ML-KEM.\n\n**Parameters:**\n- `mnemonicJson: MnemonicJSON | string` - MnemonicJSON object or string\n- `passphrase: string` - Passphrase to encrypt the key at rest\n- `label?: string` - Optional label for the key\n\n**Returns:** `Promise\u003cMajikKey\u003e` - A new unlocked MajikKey instance\n\n**Example:**\n```ts\nconst mnemonicData = {\n  id: 'backup-id',\n  seed: ['word1', 'word2', ...],\n  phrase: 'optional-encryption-phrase'\n};\n\nconst key = await MajikKey.fromMnemonicJSON(mnemonicData, 'my-password');\n```\n\n---\n\n#### `MajikKey.importFromMnemonicBackup(backup, mnemonic, passphrase, label?)`\nImport a Majik Key from a mnemonic-encrypted backup. Auto-migrates legacy PBKDF2 accounts to Argon2id + ML-KEM.\n\n**Parameters:**\n- `backup: string` - Base64-encoded backup string\n- `mnemonic: string` - The mnemonic phrase used to encrypt the backup\n- `passphrase: string` - Passphrase to encrypt the imported key\n- `label?: string` - Optional label for the key\n\n**Returns:** `Promise\u003cMajikKey\u003e` - A new unlocked MajikKey instance\n\n**Example:**\n```ts\nconst backupString = 'eT8xY2F...'; // From exportMnemonicBackup()\nconst key = await MajikKey.importFromMnemonicBackup(\n  backupString,\n  mnemonic,\n  'new-password',\n  'Restored Account'\n);\n```\n\n---\n\n#### `MajikKey.generateMnemonic(strength?)`\nGenerate a new BIP39 mnemonic phrase.\n\n**Parameters:**\n- `strength?: 128 | 256` - Entropy strength (128 = 12 words, 256 = 24 words). Default: 128\n\n**Returns:** `string` - A new mnemonic phrase\n\n**Example:**\n```ts\nconst mnemonic12 = MajikKey.generateMnemonic();      // 12 words\nconst mnemonic24 = MajikKey.generateMnemonic(256);   // 24 words\n```\n\n---\n\n#### `MajikKey.validateMnemonic(mnemonic)`\nValidate a BIP39 mnemonic phrase.\n\n**Parameters:**\n- `mnemonic: string` - Mnemonic phrase to validate\n\n**Returns:** `boolean` - true if valid, false otherwise\n\n**Example:**\n```ts\nconst isValid = MajikKey.validateMnemonic('witch collapse practice...');\n```\n\n---\n\n### Instance Methods\n\n#### `unlock(passphrase)`\nUnlock the Majik Key by decrypting the private key. Decrypts X25519 and ML-KEM private keys into memory.\n\n**Parameters:**\n- `passphrase: string` - Passphrase to decrypt the private key\n\n**Returns:** `Promise\u003cthis\u003e` - This instance for chaining\n\n**Throws:** `MajikKeyError` if passphrase is incorrect or key is already unlocked\n\n**Example:**\n```ts\nawait key.unlock('my-password');\n```\n\n---\n\n#### `lock()`\nLock the Majik Key by clearing private keys from memory.\n\n**Returns:** `this` - This instance for chaining\n\n**Example:**\n```ts\nkey.lock();\n```\n\n---\n\n#### `verify(passphrase)`\nVerify that a passphrase can decrypt the private key.\n\n**Parameters:**\n- `passphrase: string` - Passphrase to verify\n\n**Returns:** `Promise\u003cboolean\u003e` - true if valid, false otherwise\n\n**Example:**\n```ts\nconst isValid = await key.verify('my-password');\n```\n\n---\n\n#### `updateLabel(newLabel)`\nUpdate the label of the Majik Key.\n\n**Parameters:**\n- `newLabel: string` - New label value\n\n**Returns:** `this` - This instance for chaining\n\n**Example:**\n```ts\nkey.updateLabel('Work Account');\n```\n\n---\n\n#### `updatePassphrase(currentPassphrase, newPassphrase)`\nChange the passphrase used to encrypt the private key. Re-encrypts keys and triggers an auto-migration to KDF v2.\n\n**Parameters:**\n- `currentPassphrase: string` - Current passphrase\n- `newPassphrase: string` - New passphrase\n\n**Returns:** `Promise\u003cthis\u003e` - This instance for chaining\n\n**Throws:** `MajikKeyError` if current passphrase is incorrect\n\n**Example:**\n```ts\nawait key.updatePassphrase('old-password', 'new-password');\n```\n\n---\n\n#### `getPrivateKey()`\nGet the private key (only when unlocked).\n\n**Returns:** `CryptoKey | { raw: Uint8Array }` - The private key\n\n**Throws:** `MajikKeyError` if the key is locked\n\n**Example:**\n```ts\nconst privateKey = key.getPrivateKey();\n```\n\n---\n\n#### `getPrivateKeyBase64()`\nGet the private key as base64 (only when unlocked).\n\n**Returns:** `string` - The private key in base64 format\n\n**Throws:** `MajikKeyError` if the key is locked\n\n**Example:**\n```ts\nconst privateKeyBase64 = key.getPrivateKeyBase64();\n```\n\n---\n\n#### `toJSON()`\nExport to JSON format (safe for storage).\n\n**Returns:** `MajikKeyJSON` - JSON representation (private keys never included)\n\n**Example:**\n```ts\nconst json = key.toJSON();\nlocalStorage.setItem('myKey', JSON.stringify(json));\n```\n\n---\n\n#### `toString(pretty?)`\nExport to JSON string.\n\n**Parameters:**\n- `pretty?: boolean` - Whether to pretty-print. Default: false\n\n**Returns:** `string` - JSON string representation\n\n**Example:**\n```ts\nconst jsonString = key.toString(true);\n```\n\n---\n\n#### `toMnemonicJSON(mnemonic, passphrase?)`\nExport to MnemonicJSON format.\n\n**Parameters:**\n- `mnemonic: string` - The BIP39 mnemonic phrase\n- `passphrase?: string` - Optional passphrase\n\n**Returns:** `MnemonicJSON` - MnemonicJSON object\n\n**Throws:** `MajikKeyError` if the key is locked\n\n**Example:**\n```ts\nconst mnemonicData = key.toMnemonicJSON(mnemonic, 'encryption-phrase');\n```\n\n---\n\n#### `exportMnemonicBackup(mnemonic)`\nExport a mnemonic-encrypted backup.\n\n**Parameters:**\n- `mnemonic: string` - The original mnemonic phrase\n\n**Returns:** `Promise\u003cstring\u003e` - Base64-encoded backup string\n\n**Throws:** `MajikKeyError` if the key is locked\n\n**Example:**\n```ts\nconst backup = await key.exportMnemonicBackup(mnemonic);\n```\n\n---\n\n#### `toContact()`\nCreate a MajikContact from this Majik Key.\n\n**Returns:** `MajikContact` - A MajikContact instance\n\n**Example:**\n```ts\nconst contact = key.toContact();\n```\n\n---\n\n#### `toMajikMessageIdentity(user, options?)`\nConvert to MajikMessageIdentity for use in Majik Message.\n\n**Parameters:**\n- `user: MajikUser` - MajikUser instance\n- `options?: { label?: string, restricted?: boolean }` - Optional configuration\n\n**Returns:** `Promise\u003cMajikMessageIdentity\u003e` - MajikMessageIdentity instance\n\n**Example:**\n```ts\nconst identity = await key.toMajikMessageIdentity(user, {\n  label: 'My Account',\n  restricted: false\n});\n```\n\n---\n\n### Getters\n\n#### `id: string`\nThe unique identifier (fingerprint).\n\n#### `fingerprint: string`\nThe cryptographic fingerprint.\n\n#### `publicKey: CryptoKey | { raw: Uint8Array }`\nThe public key.\n\n#### `publicKeyBase64: string`\nThe public key in base64 format.\n\n#### `label: string`\nThe user-defined label.\n\n#### `backup: string`\nThe mnemonic backup identifier.\n\n#### `timestamp: Date`\nThe creation timestamp.\n\n#### `isLocked: boolean`\nWhether the key is currently locked.\n\n#### `isUnlocked: boolean`\nWhether the key is currently unlocked.\n\n#### `metadata: MajikKeyMetadata`\nSafe metadata object (no sensitive data).\n\n**Example:**\n```ts\nconsole.log(key.metadata);\n// {\n//   id: 'fingerprint-id',\n//   fingerprint: 'fingerprint-id',\n//   label: 'My Key',\n//   timestamp: Date,\n//   isLocked: false\n// }\n```\n\n---\n\n## Usage Examples\n\n### Example 1: Create and Manage a Key\n\n```ts\nimport { MajikKey } from '@majikah/majik-key';\n\nasync function createKey() {\n  // Generate mnemonic\n  const mnemonic = MajikKey.generateMnemonic();\n  console.log('🔑 Save this mnemonic safely:', mnemonic);\n\n  // Create key\n  const key = await MajikKey.create(\n    mnemonic,\n    'secure-passphrase',\n    'Personal Account'\n  );\n\n  console.log('✅ Key created!');\n  console.log('ID:', key.id);\n  console.log('Fingerprint:', key.fingerprint);\n  console.log('Label:', key.label);\n\n  // Save to storage\n  const json = key.toJSON();\n  localStorage.setItem('myKey', JSON.stringify(json));\n\n  return { key, mnemonic };\n}\n\ncreateKey();\n```\n\n---\n\n### Example 2: Lock/Unlock Pattern\n\n```ts\nimport { MajikKey } from '@majikah/majik-key';\n\nasync function secureLockPattern() {\n  const json = localStorage.getItem('myKey');\n  const key = MajikKey.fromJSON(json);\n\n  // Key is locked by default when loaded from JSON\n  console.log('Locked:', key.isLocked); // true\n\n  try {\n    // This will throw an error\n    const privateKey = key.getPrivateKey();\n  } catch (error) {\n    console.log('❌ Cannot access private key when locked');\n  }\n\n  // Unlock to use private key\n  await key.unlock('secure-passphrase');\n  console.log('Unlocked:', key.isUnlocked); // true\n\n  // Now we can access private keys\n  const privateKey = key.getPrivateKey();\n  const privateKeyBase64 = key.getPrivateKeyBase64();\n\n  // Use the key for cryptographic operations\n  // ...\n\n  // Lock again when done\n  key.lock();\n  console.log('🔒 Key locked again');\n}\n\nsecureLockPattern();\n```\n\n---\n\n### Example 3: Backup and Recovery\n\n```ts\nimport { MajikKey } from '@majikah/majik-key';\n\nasync function backupAndRecover() {\n  const mnemonic = MajikKey.generateMnemonic();\n  const key = await MajikKey.create(mnemonic, 'password123', 'Original Key');\n\n  //Download as Blob JSON File\n\n  const jsonData = await key.toMnemonicJSON(mnemonic, 'password123');\n  const jsonString = JSON.stringify(jsonData);\n  const blob = new Blob([jsonString], {\n    type: \"application/json;charset=utf-8\",\n  });\n  downloadBlob(\n    blob,\n    \"json\",\n    `${label} | ${key.id} | SEED KEY`,\n  );\n\n\n\n  // Later... recover from backup\n\n  //Parse the downloaded JSON into this object\n  const jsonData: MnemonicJSON = {\n    id: \"abc123\",\n    seed: [\"word1\", \"word2\", ...],\n    phrase: 'password123',\n  };\n\n  const recoveredKey = await MajikKey.importFromMnemonicBackup(\n    jsonData.id,\n    seedArrayToString(jsonData.seed),\n    jsonData.phrase,\n    'Recovered Key'\n  );\n\n  console.log('✅ Key recovered!');\n  console.log('Same fingerprint:', key.fingerprint === recoveredKey.fingerprint);\n}\n\nbackupAndRecover();\n```\n\n\n---\n\n### Example 4: Update Passphrase\n\n```ts\nimport { MajikKey } from '@majikah/majik-key';\n\nasync function changePassphrase() {\n  const json = localStorage.getItem('myKey');\n  const key = MajikKey.fromJSON(json);\n\n  // Must unlock first\n  await key.unlock('old-password');\n\n  // Change passphrase\n  await key.updatePassphrase('old-password', 'new-secure-password');\n  console.log('✅ Passphrase updated!');\n\n  // Save updated key\n  localStorage.setItem('myKey', JSON.stringify(key.toJSON()));\n\n  // Verify new passphrase works\n  key.lock();\n  await key.unlock('new-secure-password');\n  console.log('✅ New passphrase verified!');\n}\n\nchangePassphrase();\n```\n\n---\n\n### Example 5: Verify Passphrase\n\n```ts\nimport { MajikKey } from '@majikah/majik-key';\n\nasync function verifyPassphrase() {\n  const json = localStorage.getItem('myKey');\n  const key = MajikKey.fromJSON(json);\n\n  // Verify without unlocking\n  const isValid = await key.verify('user-entered-password');\n\n  if (isValid) {\n    console.log('✅ Passphrase is correct');\n    await key.unlock('user-entered-password');\n    // Proceed with operations...\n  } else {\n    console.log('❌ Invalid passphrase');\n    // Show error to user\n  }\n}\n\nverifyPassphrase();\n```\n\n---\n\n## Integration with Majik Message\n\nMajik 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.\n\n### Importing to Majik Message\n\n```ts\nimport { MajikKey } from '@majikah/majik-key';\n\nasync function importToMajikMessage() {\n  // Create or load a Majik Key\n  const mnemonic = MajikKey.generateMnemonic();\n  const key = await MajikKey.create(mnemonic, 'password', 'Message Account');\n\n  // Export to MnemonicJSON format for Majik Message\n  const mnemonicData = key.toMnemonicJSON(mnemonic, 'password');\n  const jsonString = JSON.stringify(mnemonicData);\n\n  // Download this blob as a JSON locally\n  const blob = new Blob([jsonString], {\n    type: \"application/json;charset=utf-8\",\n  });\n\n  // This mnemonicData can be imported directly into Majik Message\n  // as a seed phrase account\n  console.log('Import the saved JSON to Majik Message:', mnemonicData);\n}\n```\n\n### Converting to Majik Message Identity\n\n```ts\nimport { MajikKey } from '@majikah/majik-key';\nimport { MajikUser } from '@thezelijah/majik-user';\n\nasync function createMessageIdentity() {\n  const mnemonic = MajikKey.generateMnemonic();\n  const key = await MajikKey.create(mnemonic, 'password', 'Message Identity');\n\n  // Create/parse a MajikUser instance\n  const user = new MajikUser({\n    username: 'myusername',\n    // ... other user properties\n  });\n\n  // Convert to Majik Message Identity\n  const identity = await key.toMajikMessageIdentity(user, {\n    label: 'My Message Account',\n    restricted: false\n  });\n\n  console.log('Majik Message Identity created:', identity);\n}\n```\n\n---\n\n## Security Considerations\n\n### Best Practices\n\n1. **Never expose mnemonics**: Treat mnemonic phrases like root passwords. Never log or store them unencrypted.\n\n2. **Lock when not in use**: Always call .lock() when private key access is no longer required to purge the heap.\n\n3. **PQ Readiness**: For all new communication protocols, ensure you are utilizing the mlKemPublicKey.\n\nSecurity Summary\n- **Primary KDF**: Argon2id (64 / 3t / 4p).\n\n- **Legacy KDF**: PBKDF2-SHA256 (250,000 iterations).\n\n- **Encryption**: AES-256-GCM with unique salts and IVs.\n\n- **Post-Quantum**: ML-KEM-768 (Lattice-based cryptography).\n\n### What NOT to Do\n\n❌ **DON'T** store mnemonics in code or version control  \n❌ **DON'T** transmit mnemonics over insecure channels  \n❌ **DON'T** use weak passphrases like \"password123\"  \n❌ **DON'T** share mnemonics or passphrases with anyone  \n❌ **DON'T** screenshot or photograph mnemonics  \n\n### What TO Do\n\n✅ **DO** use password managers for mnemonic storage  \n✅ **DO** write mnemonics on paper and store securely  \n✅ **DO** use hardware security modules when possible  \n✅ **DO** test recovery procedures before relying on them  \n✅ **DO** keep multiple encrypted backups in different locations  \n\n---\n\n### Tips \u0026 Reminders\n\n#### For Developers\n\n- **Remember**: Always validate user input before creating or unlocking keys.\n\n- **Security**: Never log sensitive data (mnemonics, private keys, passphrases) in production.\n\n- **Performance**: Lock keys when not in use to free memory and reduce attack surface.\n\n- **Testing**: Test backup/recovery procedures in development before deploying to production.\n\n- **Dependencies**: Keep `@scure/bip39` and other crypto dependencies up to date.\n\n#### For Users\n\n- **Backup**: Always keep multiple backups of your mnemonic phrase in secure locations.\n\n- **Passphrase**: Use a strong, unique passphrase for each Majik Key.\n\n- **Recovery**: Test your ability to recover keys from backups before you need to.\n\n- **Organization**: Use meaningful labels to identify different keys.\n- **Loss Prevention**: Losing your mnemonic phrase means permanent loss of access to your key.\n\n---\n\n## Related Projects\n\n### [Majik Message](https://message.majikah.solutions)\nSecure messaging platform using Majik Keys\n\n[Read more about Majik Message here](https://majikah.solutions/products/majik-message)\n\n[![Majik Message Thumbnail](https://github.com/user-attachments/assets/6355cbd3-63e4-4a95-a370-64ba27cbb4a7)](https://message.majikah.solutions)\n\n\u003e Click the image to try Majik Message live.\n\n[Read Docs](https://majikah.solutions/products/majik-message/docs)\n\n\nAlso available on [Microsoft Store](https://apps.microsoft.com/detail/9pmjgvzzjspn) for free.\n\n[Official Repository](https://github.com/Majikah/majik-message)\n[SDK Library](https://www.npmjs.com/package/@majikah/majik-message)\n\n---\n\n## Contributing\n\nIf you want to contribute or help extend support to more platforms, reach out via email. All contributions are welcome!  \n\n---\n\n## License\n\n[Apache-2.0](LICENSE) — free for personal and commercial use.\n\n---\n## Author\n\nMade with 💙 by [@thezelijah](https://github.com/jedlsf)\n\n## About the Developer\n\n- **Developer**: Josef Elijah Fabian\n- **GitHub**: [https://github.com/jedlsf](https://github.com/jedlsf)\n- **Project Repository**: [https://github.com/Majikah/majik-key](https://github.com/Majikah/majik-key)\n\n---\n\n## Contact\n\n- **Business Email**: [business@thezelijah.world](mailto:business@thezelijah.world)\n- **Official Website**: [https://www.thezelijah.world](https://www.thezelijah.world)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmajikah%2Fmajik-key","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmajikah%2Fmajik-key","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmajikah%2Fmajik-key/lists"}