@abraca/dabra 1.3.1 → 1.3.2

package/dist/index.d.ts

@@ -553,18 +553,20 @@ declare class AbracadabraClient {
 /**
  * CryptoIdentityKeystore
  *
- * Per-user Ed25519 keypair derived deterministically from a synced WebAuthn
- * passkey's PRF extension output. The same passkey on any device produces the
- * same identity — no private key storage needed.
+ * Ed25519 identity management with two derivation modes:
  *
- * Derivation chain:
- *   Synced Passkey → PRF(constant salt) → HKDF-SHA256 → Ed25519 seed → keypair
+ * 1. **Passkey-only (legacy)**: PRF output → HKDF → Ed25519 seed.
+ *    The passkey IS the identity source.
  *
- * IndexedDB is used only as a lightweight cache for the public key and
- * credential ID. Loss of IndexedDB is non-catastrophic — a passkey assertion
- * re-derives everything.
+ * 2. **Mnemonic-rooted**: BIP-39 mnemonic → Ed25519 seed, encrypted by
+ *    passkey PRF for day-to-day convenience. The mnemonic IS the identity
+ *    source; the passkey is a convenience wrapper. Recovery via mnemonic
+ *    re-derives the exact same key.
  *
- * Dependencies: @noble/ed25519, @noble/hashes (for HKDF), @noble/curves (for X25519)
+ * Both modes coexist. IndexedDB records with `encryptedSeed` use mode 2;
+ * records without it use mode 1 (backward compatible).
+ *
+ * Dependencies: @noble/ed25519, @noble/hashes, @noble/curves, @scure/bip39
  */
 declare class CryptoIdentityKeystore {
   /**
@@ -647,6 +649,47 @@ declare class CryptoIdentityKeystore {
     publicKey: string;
     username: string;
   }[]>;
+  /**
+   * Register a new identity rooted in a BIP-39 mnemonic. Optionally wraps the
+   * derived seed with a passkey for biometric day-to-day access.
+   *
+   * @param username - Display name for the identity.
+   * @param mnemonic - Valid BIP-39 mnemonic (12 or 24 words).
+   * @param passphrase - Optional BIP-39 passphrase ("25th word").
+   * @param rpId - WebAuthn relying party ID (omit to skip passkey wrapping).
+   * @param rpName - WebAuthn relying party display name.
+   * @returns Public keys and optional credential ID.
+   */
+  registerWithMnemonic(username: string, mnemonic: string, passphrase?: string, rpId?: string, rpName?: string): Promise<{
+    publicKey: string;
+    x25519PublicKey: string;
+    credentialId?: string;
+  }>;
+  /**
+   * Wrap an existing mnemonic-derived seed with a new passkey. Use this when
+   * a user logged in via mnemonic and wants to add biometric convenience.
+   *
+   * @param mnemonic - The user's BIP-39 mnemonic.
+   * @param passphrase - Optional BIP-39 passphrase.
+   * @param rpId - WebAuthn relying party ID.
+   * @param rpName - WebAuthn relying party display name.
+   * @returns The new credential ID.
+   */
+  wrapSeedWithPasskey(mnemonic: string, passphrase: string | undefined, rpId: string, rpName: string): Promise<{
+    credentialId: string;
+  }>;
+  /**
+   * Sign a challenge directly with a provided seed. No WebAuthn prompt.
+   * For ephemeral mnemonic sessions where the seed is held in memory.
+   *
+   * The caller manages the seed lifecycle (wiping on session end).
+   */
+  static signWithSeed(challengeB64: string, seed: Uint8Array): Promise<string>;
+  /**
+   * Stateless mnemonic sign: derive seed, sign, wipe. No IndexedDB, no WebAuthn.
+   * Useful for CLI or one-shot operations.
+   */
+  static signWithMnemonic(mnemonic: string, challengeB64: string, passphrase?: string): Promise<string>;
   /**
    * Perform a WebAuthn assertion with PRF, derive the Ed25519 seed, and
    * update the IndexedDB cache. Returns the seed (caller MUST wipe it).
@@ -2706,4 +2749,71 @@ declare class DeviceRegistrationService {
   }): Promise<void>;
 }
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceTier, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedYMap, EncryptedYText, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, InviteRow, KEY_EXCHANGE_CHANNEL, ManualSignaling, type ManualSignalingBlob, MessageTooBig, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, decryptField, deriveIdentityDocId, encryptField, makeEncryptedYMap, makeEncryptedYText, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };
+//#region node_modules/@scure/bip39/esm/wordlists/english.d.ts
+declare const wordlist: string[];
+//#endregion
+//#region packages/provider/src/MnemonicKeyDerivation.d.ts
+/**
+ * Generate a new BIP-39 mnemonic phrase.
+ * @param strength 128 for 12 words (default), 256 for 24 words.
+ */
+declare function generateMnemonic(strength?: 128 | 256): string;
+/**
+ * Validate a BIP-39 mnemonic (wordlist + checksum).
+ */
+declare function validateMnemonic(mnemonic: string): boolean;
+/**
+ * Derive a 32-byte Ed25519 seed from a BIP-39 mnemonic.
+ *
+ * Chain: mnemonic → PBKDF2-HMAC-SHA512 (2048 rounds) → first 32 bytes →
+ *        HKDF-SHA256(salt, info) → 32-byte seed.
+ *
+ * @param mnemonic  Valid BIP-39 mnemonic (12 or 24 words).
+ * @param passphrase  Optional BIP-39 passphrase ("25th word").
+ * @returns 32-byte Ed25519 seed. Caller MUST wipe after use: `seed.fill(0)`.
+ */
+declare function mnemonicToEd25519Seed(mnemonic: string, passphrase?: string): Uint8Array;
+/**
+ * Derive the full Ed25519 + X25519 keypair from a BIP-39 mnemonic.
+ *
+ * @param mnemonic  Valid BIP-39 mnemonic.
+ * @param passphrase  Optional BIP-39 passphrase.
+ * @returns Keys and seed. Caller MUST wipe `seed` after use.
+ */
+declare function mnemonicToKeyPair(mnemonic: string, passphrase?: string): Promise<{
+  seed: Uint8Array;
+  publicKey: Uint8Array;
+  publicKeyB64: string;
+  x25519PublicKey: Uint8Array;
+  x25519PublicKeyB64: string;
+}>;
+/**
+ * Derive a 32-byte AES-256-GCM key from WebAuthn PRF output for seed wrapping.
+ *
+ * @param prfOutput  Raw PRF output from WebAuthn assertion (32 bytes typical).
+ * @param wrapSalt   Random 32-byte salt, stored alongside the ciphertext.
+ */
+declare function deriveSeedWrappingKey(prfOutput: ArrayBuffer, wrapSalt: Uint8Array): Uint8Array;
+/**
+ * Encrypt an Ed25519 seed with AES-256-GCM.
+ *
+ * @param seed  32-byte Ed25519 seed to protect.
+ * @param wrappingKeyBytes  32-byte AES key from `deriveSeedWrappingKey`.
+ * @returns Ciphertext (48 bytes: 32 plaintext + 16 auth tag) and 12-byte IV.
+ */
+declare function wrapSeed(seed: Uint8Array, wrappingKeyBytes: Uint8Array): Promise<{
+  ciphertext: ArrayBuffer;
+  iv: Uint8Array;
+}>;
+/**
+ * Decrypt an Ed25519 seed from AES-256-GCM ciphertext.
+ *
+ * @param ciphertext  Encrypted seed (48 bytes).
+ * @param iv  12-byte GCM nonce.
+ * @param wrappingKeyBytes  32-byte AES key from `deriveSeedWrappingKey`.
+ * @returns 32-byte Ed25519 seed. Caller MUST wipe after use.
+ * @throws If the auth tag is invalid (wrong key or tampered data).
+ */
+declare function unwrapSeed(ciphertext: ArrayBuffer, iv: Uint8Array, wrappingKeyBytes: Uint8Array): Promise<Uint8Array>;
+//#endregion
+export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceTier, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedYMap, EncryptedYText, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, InviteRow, KEY_EXCHANGE_CHANNEL, ManualSignaling, type ManualSignalingBlob, MessageTooBig, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptField, generateMnemonic, makeEncryptedYMap, makeEncryptedYText, mnemonicToEd25519Seed, mnemonicToKeyPair, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, unwrapSeed, validateMnemonic, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",
@@ -32,6 +32,7 @@
     "@noble/curves": "^2.0.1",
     "@noble/ed25519": "^2.3.0",
     "@noble/hashes": "^1.8.0",
+    "@scure/bip39": "^1.5.0",
     "lib0": "^0.2.117",
     "ws": "^8.19.0"
   },

package/src/CryptoIdentityKeystore.ts

@@ -1,24 +1,33 @@
 /**
  * CryptoIdentityKeystore
  *
- * Per-user Ed25519 keypair derived deterministically from a synced WebAuthn
- * passkey's PRF extension output. The same passkey on any device produces the
- * same identity — no private key storage needed.
+ * Ed25519 identity management with two derivation modes:
  *
- * Derivation chain:
- *   Synced Passkey → PRF(constant salt) → HKDF-SHA256 → Ed25519 seed → keypair
+ * 1. **Passkey-only (legacy)**: PRF output → HKDF → Ed25519 seed.
+ *    The passkey IS the identity source.
  *
- * IndexedDB is used only as a lightweight cache for the public key and
- * credential ID. Loss of IndexedDB is non-catastrophic — a passkey assertion
- * re-derives everything.
+ * 2. **Mnemonic-rooted**: BIP-39 mnemonic → Ed25519 seed, encrypted by
+ *    passkey PRF for day-to-day convenience. The mnemonic IS the identity
+ *    source; the passkey is a convenience wrapper. Recovery via mnemonic
+ *    re-derives the exact same key.
  *
- * Dependencies: @noble/ed25519, @noble/hashes (for HKDF), @noble/curves (for X25519)
+ * Both modes coexist. IndexedDB records with `encryptedSeed` use mode 2;
+ * records without it use mode 1 (backward compatible).
+ *
+ * Dependencies: @noble/ed25519, @noble/hashes, @noble/curves, @scure/bip39
  */
 
 import * as ed from "@noble/ed25519";
 import { hkdf } from "@noble/hashes/hkdf";
 import { sha256 } from "@noble/hashes/sha256";
 import { ed25519 as nobleEd25519Curves } from "@noble/curves/ed25519.js";
+import {
+	mnemonicToKeyPair,
+	mnemonicToEd25519Seed,
+	deriveSeedWrappingKey,
+	wrapSeed,
+	unwrapSeed,
+} from "./MnemonicKeyDerivation.ts";
 
 // ── Constants ───────────────────────────────────────────────────────────────
 
@@ -39,13 +48,22 @@ const HKDF_INFO = new TextEncoder().encode("abracadabra-identity-v1");
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
-/** Lightweight cache record — no private key material. */
+/** Lightweight cache record — no private key material stored in plaintext. */
 interface StoredIdentity {
 	username: string;
 	/** base64url-encoded Ed25519 public key (32 bytes). */
 	publicKey: string;
 	/** WebAuthn credential ID for allowCredentials hint. */
 	credentialId: ArrayBuffer;
+	// ── Mnemonic-rooted fields (absent = legacy passkey-only mode) ──
+	/** AES-256-GCM ciphertext of the 32-byte Ed25519 seed (48 bytes with tag). */
+	encryptedSeed?: ArrayBuffer;
+	/** 12-byte AES-GCM nonce used for seed encryption. */
+	seedIv?: Uint8Array;
+	/** 32-byte random salt for HKDF(PRF → wrapping key). Per-credential. */
+	wrapSalt?: Uint8Array;
+	/** How the identity was created. Absent = legacy passkey-only. */
+	authMethod?: "passkey" | "mnemonic";
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -71,10 +89,12 @@ const STORE_NAME = "identity";
 
 function openDb(): Promise<IDBDatabase> {
 	return new Promise((resolve, reject) => {
-		const req = indexedDB.open(DB_NAME, 2);
+		const req = indexedDB.open(DB_NAME, 3);
 		req.onupgradeneeded = () => {
 			const db = req.result;
-			// v1 had a plain object store; v2 uses credentialId-keyed records
+			// v1: plain object store; v2: credentialId-keyed records
+			// v3: optional encryptedSeed/seedIv/wrapSalt/authMethod fields on values
+			//     (no structural changes — same store, new optional value fields)
 			if (!db.objectStoreNames.contains(STORE_NAME)) {
 				db.createObjectStore(STORE_NAME);
 			}
@@ -425,6 +445,208 @@ export class CryptoIdentityKeystore {
 		}
 	}
 
+	// ── Mnemonic-based methods ───────────────────────────────────────────────
+
+	/**
+	 * Register a new identity rooted in a BIP-39 mnemonic. Optionally wraps the
+	 * derived seed with a passkey for biometric day-to-day access.
+	 *
+	 * @param username - Display name for the identity.
+	 * @param mnemonic - Valid BIP-39 mnemonic (12 or 24 words).
+	 * @param passphrase - Optional BIP-39 passphrase ("25th word").
+	 * @param rpId - WebAuthn relying party ID (omit to skip passkey wrapping).
+	 * @param rpName - WebAuthn relying party display name.
+	 * @returns Public keys and optional credential ID.
+	 */
+	async registerWithMnemonic(
+		username: string,
+		mnemonic: string,
+		passphrase?: string,
+		rpId?: string,
+		rpName?: string,
+	): Promise<{ publicKey: string; x25519PublicKey: string; credentialId?: string }> {
+		const kp = await mnemonicToKeyPair(mnemonic, passphrase);
+
+		try {
+			if (rpId && rpName) {
+				// Create a passkey to wrap the mnemonic-derived seed
+				const credential = await navigator.credentials.create({
+					publicKey: {
+						challenge: crypto.getRandomValues(new Uint8Array(32)),
+						rp: { id: rpId, name: rpName },
+						user: {
+							id: new TextEncoder().encode(username),
+							name: username,
+							displayName: username,
+						},
+						pubKeyCredParams: [
+							{ alg: -7, type: "public-key" },
+							{ alg: -257, type: "public-key" },
+						],
+						authenticatorSelection: {
+							residentKey: "required",
+							requireResidentKey: true,
+							userVerification: "required",
+						},
+						extensions: {
+							prf: { eval: { first: PRF_SALT.buffer } },
+						} as AuthenticationExtensionsClientInputs,
+					},
+				}) as PublicKeyCredential | null;
+
+				if (!credential) {
+					throw new Error("WebAuthn credential creation cancelled");
+				}
+
+				const prfOutput = extractPrfOutput(credential);
+				const wrapSalt = crypto.getRandomValues(new Uint8Array(32));
+				const wrapKey = deriveSeedWrappingKey(prfOutput, wrapSalt);
+				const { ciphertext, iv } = await wrapSeed(kp.seed, wrapKey);
+				wrapKey.fill(0);
+
+				const credentialIdB64 = toBase64url(new Uint8Array(credential.rawId));
+				const db = await openDb();
+				await dbPut(db, credentialIdB64, {
+					username,
+					publicKey: kp.publicKeyB64,
+					credentialId: credential.rawId,
+					encryptedSeed: ciphertext,
+					seedIv: iv,
+					wrapSalt,
+					authMethod: "mnemonic",
+				});
+				db.close();
+
+				return {
+					publicKey: kp.publicKeyB64,
+					x25519PublicKey: kp.x25519PublicKeyB64,
+					credentialId: credentialIdB64,
+				};
+			}
+
+			// No passkey wrapping — ephemeral or mnemonic-only mode
+			return {
+				publicKey: kp.publicKeyB64,
+				x25519PublicKey: kp.x25519PublicKeyB64,
+			};
+		} finally {
+			kp.seed.fill(0);
+		}
+	}
+
+	/**
+	 * Wrap an existing mnemonic-derived seed with a new passkey. Use this when
+	 * a user logged in via mnemonic and wants to add biometric convenience.
+	 *
+	 * @param mnemonic - The user's BIP-39 mnemonic.
+	 * @param passphrase - Optional BIP-39 passphrase.
+	 * @param rpId - WebAuthn relying party ID.
+	 * @param rpName - WebAuthn relying party display name.
+	 * @returns The new credential ID.
+	 */
+	async wrapSeedWithPasskey(
+		mnemonic: string,
+		passphrase: string | undefined,
+		rpId: string,
+		rpName: string,
+	): Promise<{ credentialId: string }> {
+		const kp = await mnemonicToKeyPair(mnemonic, passphrase);
+		try {
+			const credential = await navigator.credentials.create({
+				publicKey: {
+					challenge: crypto.getRandomValues(new Uint8Array(32)),
+					rp: { id: rpId, name: rpName },
+					user: {
+						id: fromBase64url(kp.publicKeyB64),
+						name: kp.publicKeyB64.slice(0, 16),
+						displayName: kp.publicKeyB64.slice(0, 16),
+					},
+					pubKeyCredParams: [
+						{ alg: -7, type: "public-key" },
+						{ alg: -257, type: "public-key" },
+					],
+					authenticatorSelection: {
+						residentKey: "required",
+						requireResidentKey: true,
+						userVerification: "required",
+					},
+					extensions: {
+						prf: { eval: { first: PRF_SALT.buffer } },
+					} as AuthenticationExtensionsClientInputs,
+				},
+			}) as PublicKeyCredential | null;
+
+			if (!credential) {
+				throw new Error("WebAuthn credential creation cancelled");
+			}
+
+			const prfOutput = extractPrfOutput(credential);
+			const wrapSalt = crypto.getRandomValues(new Uint8Array(32));
+			const wrapKey = deriveSeedWrappingKey(prfOutput, wrapSalt);
+			const { ciphertext, iv } = await wrapSeed(kp.seed, wrapKey);
+			wrapKey.fill(0);
+
+			const credentialIdB64 = toBase64url(new Uint8Array(credential.rawId));
+
+			// Try to preserve username from an existing record with the same pubkey
+			let username = "";
+			try {
+				const db = await openDb();
+				const all = await dbGetAll(db);
+				const existing = all.find(e => e.value.publicKey === kp.publicKeyB64);
+				if (existing) username = existing.value.username;
+				db.close();
+			} catch { /* non-fatal */ }
+
+			const db = await openDb();
+			await dbPut(db, credentialIdB64, {
+				username,
+				publicKey: kp.publicKeyB64,
+				credentialId: credential.rawId,
+				encryptedSeed: ciphertext,
+				seedIv: iv,
+				wrapSalt,
+				authMethod: "mnemonic",
+			});
+			db.close();
+
+			return { credentialId: credentialIdB64 };
+		} finally {
+			kp.seed.fill(0);
+		}
+	}
+
+	/**
+	 * Sign a challenge directly with a provided seed. No WebAuthn prompt.
+	 * For ephemeral mnemonic sessions where the seed is held in memory.
+	 *
+	 * The caller manages the seed lifecycle (wiping on session end).
+	 */
+	static async signWithSeed(challengeB64: string, seed: Uint8Array): Promise<string> {
+		const challengeBytes = fromBase64url(challengeB64);
+		const signature = await ed.signAsync(challengeBytes, seed);
+		return toBase64url(signature);
+	}
+
+	/**
+	 * Stateless mnemonic sign: derive seed, sign, wipe. No IndexedDB, no WebAuthn.
+	 * Useful for CLI or one-shot operations.
+	 */
+	static async signWithMnemonic(
+		mnemonic: string,
+		challengeB64: string,
+		passphrase?: string,
+	): Promise<string> {
+		const seed = mnemonicToEd25519Seed(mnemonic, passphrase);
+		try {
+			const challengeBytes = fromBase64url(challengeB64);
+			const signature = await ed.signAsync(challengeBytes, seed);
+			return toBase64url(signature);
+		} finally {
+			seed.fill(0);
+		}
+	}
+
 	// ── Internal ─────────────────────────────────────────────────────────────
 
 	/**
@@ -477,12 +699,33 @@ export class CryptoIdentityKeystore {
 		}
 
 		const prfOutput = extractPrfOutput(assertion);
-		const seed = deriveEd25519Seed(prfOutput);
+		const credentialIdB64 = toBase64url(new Uint8Array(assertion.rawId));
+
+		// Check if this credential has a wrapped mnemonic seed
+		let stored: StoredIdentity | undefined;
+		try {
+			const db = await openDb();
+			stored = await dbGet(db, credentialIdB64);
+			db.close();
+		} catch {
+			// IndexedDB unavailable — fall through to legacy derivation
+		}
+
+		let seed: Uint8Array;
+		if (stored?.encryptedSeed && stored.seedIv && stored.wrapSalt) {
+			// Mnemonic-rooted: decrypt the stored seed using PRF-derived wrap key
+			const wrapKey = deriveSeedWrappingKey(prfOutput, stored.wrapSalt);
+			seed = await unwrapSeed(stored.encryptedSeed, stored.seedIv, wrapKey);
+			wrapKey.fill(0);
+		} else {
+			// Legacy passkey-only: derive seed directly from PRF via HKDF
+			seed = deriveEd25519Seed(prfOutput);
+		}
+
 		const publicKey = await ed.getPublicKeyAsync(seed);
 		const publicKeyB64 = toBase64url(publicKey);
-		const credentialIdB64 = toBase64url(new Uint8Array(assertion.rawId));
 
-		// Update cache
+		// Update cache (preserve mnemonic-rooted fields if present)
 		try {
 			const db = await openDb();
 			const existing = await dbGet(db, credentialIdB64);
@@ -490,6 +733,11 @@ export class CryptoIdentityKeystore {
 				username: existing?.username ?? "",
 				publicKey: publicKeyB64,
 				credentialId: assertion.rawId,
+				// Preserve wrapped seed fields from existing record
+				encryptedSeed: existing?.encryptedSeed,
+				seedIv: existing?.seedIv,
+				wrapSalt: existing?.wrapSalt,
+				authMethod: existing?.authMethod,
 			});
 			db.close();
 		} catch {

package/src/MnemonicKeyDerivation.ts

@@ -0,0 +1,167 @@
+/**
+ * MnemonicKeyDerivation
+ *
+ * Pure, stateless functions for BIP-39 mnemonic-based Ed25519 identity
+ * derivation and AES-256-GCM seed wrapping. No IndexedDB, no WebAuthn,
+ * no DOM access — fully unit-testable.
+ *
+ * Derivation chain:
+ *   BIP-39 Mnemonic (+optional passphrase)
+ *     → PBKDF2-HMAC-SHA512 (2048 rounds, per BIP-39 spec)
+ *     → first 32 bytes as IKM
+ *     → HKDF-SHA256(salt="abracadabra-mnemonic-v1", info="abracadabra-identity-v1")
+ *     → Ed25519 seed (32 bytes)
+ *     → Ed25519 keypair + X25519 (Montgomery conversion)
+ *
+ * The HKDF salt differs from the passkey PRF path (which uses PRF_SALT),
+ * providing domain separation: identical raw input bytes can never produce
+ * the same Ed25519 seed across the two derivation methods.
+ *
+ * Dependencies: @scure/bip39, @noble/ed25519, @noble/hashes, @noble/curves
+ */
+
+import * as ed from "@noble/ed25519";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha256";
+import { ed25519 as nobleEd25519Curves } from "@noble/curves/ed25519.js";
+import { generateMnemonic as _generateMnemonic, validateMnemonic as _validateMnemonic, mnemonicToSeedSync } from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english";
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+/** HKDF salt for mnemonic → Ed25519 seed derivation. */
+const MNEMONIC_HKDF_SALT = /* @__PURE__ */ new TextEncoder().encode("abracadabra-mnemonic-v1");
+
+/** HKDF info string — intentionally matches the passkey path's HKDF_INFO. */
+const MNEMONIC_HKDF_INFO = /* @__PURE__ */ new TextEncoder().encode("abracadabra-identity-v1");
+
+/** HKDF info string for deriving the AES-GCM seed-wrapping key from PRF output. */
+export const SEED_WRAP_INFO = /* @__PURE__ */ new TextEncoder().encode("abracadabra-seed-wrap-v1");
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function toBase64url(bytes: Uint8Array): string {
+	return btoa(String.fromCharCode(...bytes))
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=/g, "");
+}
+
+// ── Mnemonic generation & validation ────────────────────────────────────────
+
+/**
+ * Generate a new BIP-39 mnemonic phrase.
+ * @param strength 128 for 12 words (default), 256 for 24 words.
+ */
+export function generateMnemonic(strength: 128 | 256 = 128): string {
+	return _generateMnemonic(wordlist, strength);
+}
+
+/**
+ * Validate a BIP-39 mnemonic (wordlist + checksum).
+ */
+export function validateMnemonic(mnemonic: string): boolean {
+	return _validateMnemonic(mnemonic, wordlist);
+}
+
+/**
+ * Re-export the English wordlist for UI auto-complete.
+ */
+export { wordlist as bip39Wordlist };
+
+// ── Key derivation ──────────────────────────────────────────────────────────
+
+/**
+ * Derive a 32-byte Ed25519 seed from a BIP-39 mnemonic.
+ *
+ * Chain: mnemonic → PBKDF2-HMAC-SHA512 (2048 rounds) → first 32 bytes →
+ *        HKDF-SHA256(salt, info) → 32-byte seed.
+ *
+ * @param mnemonic  Valid BIP-39 mnemonic (12 or 24 words).
+ * @param passphrase  Optional BIP-39 passphrase ("25th word").
+ * @returns 32-byte Ed25519 seed. Caller MUST wipe after use: `seed.fill(0)`.
+ */
+export function mnemonicToEd25519Seed(mnemonic: string, passphrase?: string): Uint8Array {
+	// BIP-39: PBKDF2-HMAC-SHA512(mnemonic, "mnemonic" + passphrase, 2048) → 64 bytes
+	const bip39Seed = mnemonicToSeedSync(mnemonic, passphrase ?? "");
+	// Take first 32 bytes as input key material
+	const ikm = bip39Seed.subarray(0, 32);
+	// HKDF-SHA256 with our domain-specific salt
+	const seed = hkdf(sha256, ikm, MNEMONIC_HKDF_SALT, MNEMONIC_HKDF_INFO, 32);
+	// Wipe intermediate material
+	bip39Seed.fill(0);
+	return seed;
+}
+
+/**
+ * Derive the full Ed25519 + X25519 keypair from a BIP-39 mnemonic.
+ *
+ * @param mnemonic  Valid BIP-39 mnemonic.
+ * @param passphrase  Optional BIP-39 passphrase.
+ * @returns Keys and seed. Caller MUST wipe `seed` after use.
+ */
+export async function mnemonicToKeyPair(
+	mnemonic: string,
+	passphrase?: string,
+): Promise<{
+	seed: Uint8Array;
+	publicKey: Uint8Array;
+	publicKeyB64: string;
+	x25519PublicKey: Uint8Array;
+	x25519PublicKeyB64: string;
+}> {
+	const seed = mnemonicToEd25519Seed(mnemonic, passphrase);
+	const publicKey = await ed.getPublicKeyAsync(seed);
+	const publicKeyB64 = toBase64url(publicKey);
+	const x25519PublicKey = nobleEd25519Curves.utils.toMontgomery(publicKey);
+	const x25519PublicKeyB64 = toBase64url(x25519PublicKey);
+	return { seed, publicKey, publicKeyB64, x25519PublicKey, x25519PublicKeyB64 };
+}
+
+// ── Seed wrapping (AES-256-GCM via WebCrypto) ──────────────────────────────
+
+/**
+ * Derive a 32-byte AES-256-GCM key from WebAuthn PRF output for seed wrapping.
+ *
+ * @param prfOutput  Raw PRF output from WebAuthn assertion (32 bytes typical).
+ * @param wrapSalt   Random 32-byte salt, stored alongside the ciphertext.
+ */
+export function deriveSeedWrappingKey(prfOutput: ArrayBuffer, wrapSalt: Uint8Array): Uint8Array {
+	return hkdf(sha256, new Uint8Array(prfOutput), wrapSalt, SEED_WRAP_INFO, 32);
+}
+
+/**
+ * Encrypt an Ed25519 seed with AES-256-GCM.
+ *
+ * @param seed  32-byte Ed25519 seed to protect.
+ * @param wrappingKeyBytes  32-byte AES key from `deriveSeedWrappingKey`.
+ * @returns Ciphertext (48 bytes: 32 plaintext + 16 auth tag) and 12-byte IV.
+ */
+export async function wrapSeed(
+	seed: Uint8Array,
+	wrappingKeyBytes: Uint8Array,
+): Promise<{ ciphertext: ArrayBuffer; iv: Uint8Array }> {
+	const iv = crypto.getRandomValues(new Uint8Array(12));
+	const key = await crypto.subtle.importKey("raw", wrappingKeyBytes, "AES-GCM", false, ["encrypt"]);
+	const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, seed);
+	return { ciphertext, iv };
+}
+
+/**
+ * Decrypt an Ed25519 seed from AES-256-GCM ciphertext.
+ *
+ * @param ciphertext  Encrypted seed (48 bytes).
+ * @param iv  12-byte GCM nonce.
+ * @param wrappingKeyBytes  32-byte AES key from `deriveSeedWrappingKey`.
+ * @returns 32-byte Ed25519 seed. Caller MUST wipe after use.
+ * @throws If the auth tag is invalid (wrong key or tampered data).
+ */
+export async function unwrapSeed(
+	ciphertext: ArrayBuffer,
+	iv: Uint8Array,
+	wrappingKeyBytes: Uint8Array,
+): Promise<Uint8Array> {
+	const key = await crypto.subtle.importKey("raw", wrappingKeyBytes, "AES-GCM", false, ["decrypt"]);
+	const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, ciphertext);
+	return new Uint8Array(plaintext);
+}