@majikah/majik-key 0.2.11 → 0.2.12

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

@@ -0,0 +1 @@
+export declare const MAJIK_SOLANA_SEED = "MajikKeySolanaSeed";

package/dist/core/web3/constants.js

@@ -0,0 +1 @@
+export const MAJIK_SOLANA_SEED = "MajikKeySolanaSeed";

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

@@ -0,0 +1,74 @@
+/**
+ * solana.ts
+ *
+ * ⚠️ EXPERIMENTAL — Solana keypair utilities for MajikKey.
+ * This module's API may change or be removed without notice in a minor version.
+ *
+ * Design:
+ *   - Solana accounts are plain Ed25519 keypairs — no new key material or
+ *     wallet standard is needed, just bytes in the right shape.
+ *   - `secretKey` is always the 64-byte nacl/tweetnacl-compatible format
+ *     (32-byte seed || 32-byte public key) — exactly what
+ *     `@solana/web3.js`'s `Keypair.fromSecretKey()` expects, and exactly
+ *     what `@stablelib/ed25519` already produces.
+ *   - `@solana/web3.js` is NOT a dependency of this package. It is lazily
+ *     `import()`-ed only when a caller needs an actual `Keypair`/`PublicKey`
+ *     instance (e.g. to build a transaction). If it isn't installed, we
+ *     throw a clear, actionable MajikKeyError instead of failing module
+ *     load. Base58 address derivation does NOT require the library at all.
+ *
+ * Two ways to obtain a Solana identity from a MajikKey:
+ *   1. deriveSolanaKeypairFromEdSecretKey() — RECOMMENDED. Domain-separates
+ *      a brand-new Ed25519 keypair from the MajikKey's message-signing
+ *      Ed25519 secret key, so the Solana key is never reused elsewhere.
+ *   2. solanaMaterialFromEd25519SecretKey() — reuses the MajikKey's message
+ *      signing Ed25519 keypair AS-IS. Simpler, but means the same private
+ *      key secures two different protocols. Opt-in only.
+ */
+export interface SolanaKeypairMaterial {
+    /** 32-byte Ed25519 / Solana public key. */
+    publicKey: Uint8Array;
+    /** 64-byte nacl-format secret key (32-byte seed || 32-byte public key). */
+    secretKey: Uint8Array;
+}
+/**
+ * Derive a Solana keypair domain-separated from the MajikKey's
+ * message-signing Ed25519 key, but fully deterministic from it (and
+ * therefore ultimately from the mnemonic).
+ *
+ *   seed' = SHA256(edSecretKey[0..32] || "MajikMessageSolanaSeed")
+ */
+export declare function deriveSolanaKeypairFromEdSecretKey(edSecretKey: Uint8Array): SolanaKeypairMaterial;
+/**
+ * Reuse the MajikKey's existing message-signing Ed25519 keypair directly
+ * as a Solana keypair (no re-derivation).
+ *
+ * ⚠️ Not recommended: the same private key would secure both Majik message
+ * signing AND any Solana transactions. Prefer
+ * `deriveSolanaKeypairFromEdSecretKey()` unless you specifically want the
+ * identical key on both.
+ */
+export declare function solanaMaterialFromEd25519SecretKey(edSecretKey: Uint8Array): SolanaKeypairMaterial;
+export declare function base58Encode(bytes: Uint8Array): string;
+/**
+ * Solana address for a given Solana/Ed25519 public key — just its base58
+ * encoding. Does NOT require @solana/web3.js.
+ */
+export declare function solanaAddressFromPublicKey(publicKey: Uint8Array): string;
+type SolanaKitModule = typeof import("@solana/kit");
+export declare function loadSolanaKit(): Promise<SolanaKitModule>;
+/**
+ * Real @solana/kit KeyPairSigner backed by a genuine CryptoKeyPair.
+ * Requires @solana/kit — see loadSolanaKit().
+ */
+export declare function toSolanaKeyPairSigner(material: SolanaKeypairMaterial): Promise<Awaited<ReturnType<SolanaKitModule["createKeyPairSignerFromBytes"]>>>;
+/**
+ * Real @solana/kit Address (branded string) for this material's public key.
+ */
+export declare function toSolanaAddress(material: SolanaKeypairMaterial): Promise<Awaited<ReturnType<SolanaKitModule["getAddressFromPublicKey"]>>>;
+/**
+ * Sign an arbitrary message with a Solana keypair's Ed25519 secret key.
+ * Uses @stablelib/ed25519 directly — does NOT require @solana/web3.js.
+ */
+export declare function signWithSolanaMaterial(material: SolanaKeypairMaterial, message: Uint8Array): Uint8Array;
+export {};

package/dist/core/web3/solana.js

@@ -0,0 +1,146 @@
+/**
+ * solana.ts
+ *
+ * ⚠️ EXPERIMENTAL — Solana keypair utilities for MajikKey.
+ * This module's API may change or be removed without notice in a minor version.
+ *
+ * Design:
+ *   - Solana accounts are plain Ed25519 keypairs — no new key material or
+ *     wallet standard is needed, just bytes in the right shape.
+ *   - `secretKey` is always the 64-byte nacl/tweetnacl-compatible format
+ *     (32-byte seed || 32-byte public key) — exactly what
+ *     `@solana/web3.js`'s `Keypair.fromSecretKey()` expects, and exactly
+ *     what `@stablelib/ed25519` already produces.
+ *   - `@solana/web3.js` is NOT a dependency of this package. It is lazily
+ *     `import()`-ed only when a caller needs an actual `Keypair`/`PublicKey`
+ *     instance (e.g. to build a transaction). If it isn't installed, we
+ *     throw a clear, actionable MajikKeyError instead of failing module
+ *     load. Base58 address derivation does NOT require the library at all.
+ *
+ * Two ways to obtain a Solana identity from a MajikKey:
+ *   1. deriveSolanaKeypairFromEdSecretKey() — RECOMMENDED. Domain-separates
+ *      a brand-new Ed25519 keypair from the MajikKey's message-signing
+ *      Ed25519 secret key, so the Solana key is never reused elsewhere.
+ *   2. solanaMaterialFromEd25519SecretKey() — reuses the MajikKey's message
+ *      signing Ed25519 keypair AS-IS. Simpler, but means the same private
+ *      key secures two different protocols. Opt-in only.
+ */
+import * as ed25519 from "@stablelib/ed25519";
+import { hash } from "@stablelib/sha256";
+import { MAJIK_SOLANA_SEED } from "./constants";
+import { MajikKeyError } from "../error";
+const ED25519_SECRET_KEY_LENGTH = 64;
+const ED25519_SEED_LENGTH = 32;
+// ─── Derivation ─────────────────────────────────────────────────────────────
+/**
+ * Derive a Solana keypair domain-separated from the MajikKey's
+ * message-signing Ed25519 key, but fully deterministic from it (and
+ * therefore ultimately from the mnemonic).
+ *
+ *   seed' = SHA256(edSecretKey[0..32] || "MajikMessageSolanaSeed")
+ */
+export function deriveSolanaKeypairFromEdSecretKey(edSecretKey) {
+    if (edSecretKey.length !== ED25519_SECRET_KEY_LENGTH) {
+        throw new MajikKeyError(`Expected a 64-byte Ed25519 secret key, got ${edSecretKey.length} bytes`);
+    }
+    const edSeed = edSecretKey.slice(0, ED25519_SEED_LENGTH);
+    const domain = new TextEncoder().encode(MAJIK_SOLANA_SEED);
+    const combined = new Uint8Array(edSeed.length + domain.length);
+    combined.set(edSeed, 0);
+    combined.set(domain, edSeed.length);
+    const solanaSeed = hash(combined); // 32 bytes
+    const kp = ed25519.generateKeyPairFromSeed(solanaSeed);
+    return { publicKey: kp.publicKey, secretKey: kp.secretKey };
+}
+/**
+ * Reuse the MajikKey's existing message-signing Ed25519 keypair directly
+ * as a Solana keypair (no re-derivation).
+ *
+ * ⚠️ Not recommended: the same private key would secure both Majik message
+ * signing AND any Solana transactions. Prefer
+ * `deriveSolanaKeypairFromEdSecretKey()` unless you specifically want the
+ * identical key on both.
+ */
+export function solanaMaterialFromEd25519SecretKey(edSecretKey) {
+    if (edSecretKey.length !== ED25519_SECRET_KEY_LENGTH) {
+        throw new MajikKeyError(`Expected a 64-byte Ed25519 secret key, got ${edSecretKey.length} bytes`);
+    }
+    return {
+        publicKey: edSecretKey.slice(ED25519_SEED_LENGTH),
+        secretKey: edSecretKey.slice(),
+    };
+}
+// ─── Base58 (Solana address encoding) — no external dependency ─────────────
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+export function base58Encode(bytes) {
+    if (bytes.length === 0)
+        return "";
+    const digits = [0];
+    for (let i = 0; i < bytes.length; i++) {
+        let carry = bytes[i];
+        for (let j = 0; j < digits.length; j++) {
+            carry += digits[j] << 8;
+            digits[j] = carry % 58;
+            carry = (carry / 58) | 0;
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = (carry / 58) | 0;
+        }
+    }
+    let leadingZeros = 0;
+    for (let i = 0; i < bytes.length && bytes[i] === 0; i++)
+        leadingZeros++;
+    let result = "1".repeat(leadingZeros);
+    for (let i = digits.length - 1; i >= 0; i--) {
+        result += BASE58_ALPHABET[digits[i]];
+    }
+    return result;
+}
+/**
+ * Solana address for a given Solana/Ed25519 public key — just its base58
+ * encoding. Does NOT require @solana/web3.js.
+ */
+export function solanaAddressFromPublicKey(publicKey) {
+    return base58Encode(publicKey);
+}
+let _kitModule = null;
+export async function loadSolanaKit() {
+    if (_kitModule)
+        return _kitModule;
+    try {
+        _kitModule = (await import(
+        /* webpackIgnore: true */
+        /* @vite-ignore */
+        "@solana/kit"));
+        return _kitModule;
+    }
+    catch (err) {
+        throw new MajikKeyError("@solana/kit is required for this operation but is not installed. " +
+            "Install it in your project with `npm install @solana/kit` " +
+            "(or the yarn/pnpm equivalent) and try again.", err);
+    }
+}
+/**
+ * Real @solana/kit KeyPairSigner backed by a genuine CryptoKeyPair.
+ * Requires @solana/kit — see loadSolanaKit().
+ */
+export async function toSolanaKeyPairSigner(material) {
+    const kit = await loadSolanaKit();
+    return kit.createKeyPairSignerFromBytes(material.secretKey);
+}
+/**
+ * Real @solana/kit Address (branded string) for this material's public key.
+ */
+export async function toSolanaAddress(material) {
+    const kit = await loadSolanaKit();
+    const signer = await toSolanaKeyPairSigner(material);
+    return signer.address;
+}
+/**
+ * Sign an arbitrary message with a Solana keypair's Ed25519 secret key.
+ * Uses @stablelib/ed25519 directly — does NOT require @solana/web3.js.
+ */
+export function signWithSolanaMaterial(material, message) {
+    return ed25519.sign(material.secretKey, message);
+}

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

@@ -0,0 +1,26 @@
+/**
+ * @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;
+    /** 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. */
+    readonly address: string;
+    /** Real @solana/kit Keypair. Lazily loads @solana/kit — throws if not installed. */
+    getSolanaKeypair(): Promise<any>;
+    /** Real @solana/kit PublicKey. Lazily loads @solana/kit — throws if not installed. */
+    getSolanaAddress(): Promise<any>;
+    /** Sign a message with this Solana keypair's Ed25519 key. No web3.js needed. */
+    sign(message: Uint8Array): Uint8Array;
+}
+/** @experimental */
+export interface MajikKeyWeb3Namespace {
+    readonly solana: MajikKeySolanaNamespace;
+}
+/** @experimental */
+export interface MajikKeyWeb3Namespace {
+    readonly solana: MajikKeySolanaNamespace;
+}

package/dist/core/web3/types.js

@@ -0,0 +1 @@
+export {};

package/dist/majik-key.d.ts

@@ -27,6 +27,8 @@ import type { MajikKeyDangerousJSON, MajikKeyJSON, MajikKeyMetadata, MnemonicJSO
 import { MajikMessageIdentity } from "./core/database/system/identity";
 import { MajikUser } from "@thezelijah/majik-user";
 import { MnemonicLanguage } from "./core/crypto/wordlist";
+import { SolanaKeypairMaterial } from "./core/web3/solana";
+import { MajikKeyWeb3Namespace } from "./core/web3/types";
 export interface MajikKeyIdentity {
     id: string;
     publicKey: CryptoKey | {
@@ -117,6 +119,7 @@ export declare class MajikKey {
     private _mlDsaSecretKey?;
     private _encryptedMlDsaSecretKey?;
     private _encryptedMlDsaSecretKeyBase64?;
+    private _solanaKeypairMaterial?;
     private constructor();
     get id(): string;
     get fingerprint(): string;
@@ -221,4 +224,43 @@ export declare class MajikKey {
     private static _exportMnemonicBackup;
     private static _deriveLegacyMnemonicKey;
     private static _exportKeyToBase64;
+    /**
+     * @experimental Blockchain/web3 integrations are experimental — this API
+     * may change without notice. `undefined` when the MajikKey is locked or
+     * has no Ed25519 signing key to derive from.
+     *
+     * By default `web3.solana` is DOMAIN-SEPARATED from the MajikKey's message
+     * signing key (see deriveSolanaKeypairFromEdSecretKey). Use
+     * `getSolanaKeypairMaterial({ reuseMessageKey: true })` if you specifically
+     * want the identical key reused for Solana instead.
+     */
+    get web3(): MajikKeyWeb3Namespace | undefined;
+    /**
+     * @experimental True if this MajikKey can currently produce a Solana
+     * keypair (i.e. it's unlocked and has an Ed25519 signing key).
+     */
+    get hasSolanaKeypair(): boolean;
+    private _getOrDeriveSolanaMaterial;
+    /**
+     * @experimental Raw Solana keypair material (public/secret key bytes).
+     * Pass `{ reuseMessageKey: true }` to reuse the MajikKey's message signing
+     * Ed25519 key directly instead of the domain-separated derivation.
+     */
+    getSolanaKeypairMaterial(options?: {
+        reuseMessageKey?: boolean;
+    }): SolanaKeypairMaterial;
+    /**
+     * @experimental Real @solana/kit Keypair instance. Lazily loads
+     * @solana/kit — throws a MajikKeyError with install instructions if
+     * it isn't present in the consuming project.
+     */
+    getSolanaKeypair(options?: {
+        reuseMessageKey?: boolean;
+    }): Promise<any>;
+    /**
+     * @experimental Base58 Solana address. Does NOT require @solana/kit.
+     */
+    getSolanaAddress(options?: {
+        reuseMessageKey?: boolean;
+    }): string;
 }

package/dist/majik-key.js

@@ -31,6 +31,7 @@ import { MajikKeyValidator } from "./core/validator";
 import { MajikKeyError } from "./core/error";
 import { MajikMessageIdentity } from "./core/database/system/identity";
 import { WORDLISTS } from "./core/crypto/wordlist";
+import { deriveSolanaKeypairFromEdSecretKey, signWithSolanaMaterial, solanaAddressFromPublicKey, solanaMaterialFromEd25519SecretKey, toSolanaAddress, toSolanaKeyPairSigner, } from "./core/web3/solana";
 const SALT_SIZE = 32;
 // ─── MajikKey ─────────────────────────────────────────────────────────────────
 export class MajikKey {
@@ -60,6 +61,8 @@ export class MajikKey {
     _mlDsaSecretKey;
     _encryptedMlDsaSecretKey;
     _encryptedMlDsaSecretKeyBase64;
+    //Experimental
+    _solanaKeypairMaterial;
     constructor(options) {
         this._id = options.id;
         this._publicKey = options.publicKey;
@@ -457,8 +460,9 @@ export class MajikKey {
         this._privateKey = undefined;
         this._privateKeyBase64 = undefined;
         this._mlKemSecretKey = undefined;
-        this._edSecretKey = undefined; // ADD
-        this._mlDsaSecretKey = undefined; // ADD
+        this._edSecretKey = undefined;
+        this._mlDsaSecretKey = undefined;
+        this._solanaKeypairMaterial = undefined;
         return this;
     }
     async unlock(passphrase) {
@@ -906,4 +910,74 @@ export class MajikKey {
         const raw = await crypto.subtle.exportKey("raw", key);
         return arrayBufferToBase64(raw);
     }
+    // ── WEB3 (EXPERIMENTAL) ─────────────────────────────────────────────────────
+    /**
+     * @experimental Blockchain/web3 integrations are experimental — this API
+     * may change without notice. `undefined` when the MajikKey is locked or
+     * has no Ed25519 signing key to derive from.
+     *
+     * By default `web3.solana` is DOMAIN-SEPARATED from the MajikKey's message
+     * signing key (see deriveSolanaKeypairFromEdSecretKey). Use
+     * `getSolanaKeypairMaterial({ reuseMessageKey: true })` if you specifically
+     * want the identical key reused for Solana instead.
+     */
+    get web3() {
+        if (!this.hasSolanaKeypair)
+            return undefined;
+        const material = this._getOrDeriveSolanaMaterial();
+        return {
+            solana: {
+                publicKey: material.publicKey,
+                secretKey: material.secretKey,
+                address: solanaAddressFromPublicKey(material.publicKey),
+                getSolanaKeypair: () => toSolanaKeyPairSigner(material),
+                getSolanaAddress: () => toSolanaAddress(material),
+                sign: (message) => signWithSolanaMaterial(material, message),
+            },
+        };
+    }
+    /**
+     * @experimental True if this MajikKey can currently produce a Solana
+     * keypair (i.e. it's unlocked and has an Ed25519 signing key).
+     */
+    get hasSolanaKeypair() {
+        return this.isUnlocked && this._edSecretKey !== undefined;
+    }
+    _getOrDeriveSolanaMaterial() {
+        if (!this._edSecretKey)
+            throw new MajikKeyError("No Ed25519 secret key — MajikKey must be unlocked and have signing keys.");
+        if (!this._solanaKeypairMaterial) {
+            this._solanaKeypairMaterial = deriveSolanaKeypairFromEdSecretKey(this._edSecretKey);
+        }
+        return this._solanaKeypairMaterial;
+    }
+    /**
+     * @experimental Raw Solana keypair material (public/secret key bytes).
+     * Pass `{ reuseMessageKey: true }` to reuse the MajikKey's message signing
+     * Ed25519 key directly instead of the domain-separated derivation.
+     */
+    getSolanaKeypairMaterial(options) {
+        if (this.isLocked)
+            throw new MajikKeyError("MajikKey is locked. Call unlock() first.");
+        if (!this._edSecretKey)
+            throw new MajikKeyError("No Ed25519 secret key — re-import via importFromMnemonicBackup() first.");
+        if (options?.reuseMessageKey) {
+            return solanaMaterialFromEd25519SecretKey(this._edSecretKey);
+        }
+        return this._getOrDeriveSolanaMaterial();
+    }
+    /**
+     * @experimental Real @solana/kit Keypair instance. Lazily loads
+     * @solana/kit — throws a MajikKeyError with install instructions if
+     * it isn't present in the consuming project.
+     */
+    async getSolanaKeypair(options) {
+        return toSolanaKeyPairSigner(this.getSolanaKeypairMaterial(options));
+    }
+    /**
+     * @experimental Base58 Solana address. Does NOT require @solana/kit.
+     */
+    getSolanaAddress(options) {
+        return solanaAddressFromPublicKey(this.getSolanaKeypairMaterial(options).publicKey);
+    }
 }

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.2.11",
+  "version": "0.2.12",
   "license": "Apache-2.0",
   "author": "Zelijah",
   "main": "./dist/index.js",
@@ -60,14 +60,23 @@
     "@stablelib/pbkdf2": "^2.0.1",
     "@stablelib/sha256": "^2.0.1",
     "@stablelib/x25519": "^2.0.1",
-    "@thezelijah/majik-user": "^1.0.6",
+    "@thezelijah/majik-user": "^1.0.9",
     "ed2curve": "^0.3.0",
     "hash-wasm": "^4.12.0"
   },
   "devDependencies": {
+    "@solana/kit": "^7.0.0",
     "@types/ed2curve": "^0.2.4",
-    "@types/node": "^26.0.0",
+    "@types/node": "^26.1.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
+  },
+  "peerDependencies": {
+    "@solana/kit": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@solana/kit": {
+      "optional": true
+    }
   }
 }