@abraca/dabra 1.3.0 → 1.3.2

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);
+}

package/src/index.ts

@@ -36,3 +36,13 @@ export type {
 	DeviceTier,
 } from "./IdentityDoc.ts";
 export { DeviceRegistrationService } from "./DeviceRegistrationService.ts";
+export {
+	generateMnemonic,
+	validateMnemonic,
+	mnemonicToEd25519Seed,
+	mnemonicToKeyPair,
+	deriveSeedWrappingKey,
+	wrapSeed,
+	unwrapSeed,
+	bip39Wordlist,
+} from "./MnemonicKeyDerivation.ts";

package/src/webrtc/AbracadabraWebRTC.ts

@@ -288,6 +288,9 @@ export class AbracadabraWebRTC extends EventEmitter {
 			this.signaling = null;
 		}
 
+		this._resolvedE2ee = null;
+		this._resolveE2eePromise = null;
+
 		this.removeAllListeners();
 	}
 
@@ -493,55 +496,74 @@ export class AbracadabraWebRTC extends EventEmitter {
 	}
 
 	private attachDataHandlers(peerId: string, pc: PeerConnection): void {
-		// Set up E2EE if configured.
-		if (this.config.e2ee) {
-			// Resolve E2EE identity (may be lazy — e.g. passkey-derived X25519 key).
-			this.resolveE2ee().then((identity) => {
-				if (!identity) {
-					this.startDataSync(peerId, pc);
-					return;
-				}
-				const e2ee = new E2EEChannel(identity, this.config.docId);
-				this.e2eeChannels.set(peerId, e2ee);
-				pc.router.setEncryptor(e2ee);
-
-				// Listen for key-exchange messages on the router.
-				pc.router.on("channelMessage", async ({ name, data }: { name: string; data: any }) => {
-					if (name === KEY_EXCHANGE_CHANNEL) {
-						try {
-							const buf = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
-							await e2ee.handleKeyExchange(buf);
-						} catch (err) {
-							this.emit("e2eeFailed", { peerId, error: err });
-						}
-					}
-				});
+		if (!this.config.e2ee) {
+			this.startDataSync(peerId, pc);
+			return;
+		}
 
-				// When key-exchange channel opens, send our public key.
-				pc.router.on("channelOpen", ({ name, channel }: { name: string; channel: RTCDataChannel }) => {
-					if (name === KEY_EXCHANGE_CHANNEL) {
-						channel.send(e2ee.getKeyExchangeMessage());
-					}
-				});
+		// E2EE identity may resolve asynchronously (e.g. lazy passkey-derived key).
+		// Register handlers synchronously so no messages are lost during resolution.
+		let e2ee: E2EEChannel | null = null;
+		const pendingMessages: Uint8Array[] = [];
+		let pendingKeyExchangeChannel: RTCDataChannel | null = null;
+
+		pc.router.on("channelMessage", async ({ name, data }: { name: string; data: any }) => {
+			if (name !== KEY_EXCHANGE_CHANNEL) return;
+			const buf = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+			if (!e2ee) {
+				pendingMessages.push(buf);
+				return;
+			}
+			try {
+				await e2ee.handleKeyExchange(buf);
+			} catch (err) {
+				this.emit("e2eeFailed", { peerId, error: err });
+			}
+		});
 
-				e2ee.on("established", () => {
-					this.emit("e2eeEstablished", { peerId });
-					// Now that E2EE is ready, start Y.js sync (deferred).
-					this.startDataSync(peerId, pc);
-				});
+		pc.router.on("channelOpen", ({ name, channel }: { name: string; channel: RTCDataChannel }) => {
+			if (name !== KEY_EXCHANGE_CHANNEL) return;
+			if (!e2ee) {
+				pendingKeyExchangeChannel = channel;
+				return;
+			}
+			channel.send(e2ee.getKeyExchangeMessage());
+		});
+
+		this.resolveE2ee().then(async (identity) => {
+			if (!identity) {
+				this.startDataSync(peerId, pc);
+				return;
+			}
+			e2ee = new E2EEChannel(identity, this.config.docId);
+			this.e2eeChannels.set(peerId, e2ee);
+			pc.router.setEncryptor(e2ee);
 
-				e2ee.on("error", (err: Error) => {
+			// Drain buffered key-exchange channel open
+			if (pendingKeyExchangeChannel) {
+				pendingKeyExchangeChannel.send(e2ee.getKeyExchangeMessage());
+			}
+			// Drain buffered messages
+			for (const msg of pendingMessages) {
+				try {
+					await e2ee.handleKeyExchange(msg);
+				} catch (err) {
 					this.emit("e2eeFailed", { peerId, error: err });
-				});
-			}).catch((err) => {
-				this.emit("e2eeFailed", { peerId, error: err });
-				// Fall back to unencrypted sync on E2EE resolution failure.
+				}
+			}
+
+			e2ee.on("established", () => {
+				this.emit("e2eeEstablished", { peerId });
 				this.startDataSync(peerId, pc);
 			});
-		} else {
-			// No E2EE — start data sync immediately.
+
+			e2ee.on("error", (err: Error) => {
+				this.emit("e2eeFailed", { peerId, error: err });
+			});
+		}).catch((err) => {
+			this.emit("e2eeFailed", { peerId, error: err });
 			this.startDataSync(peerId, pc);
-		}
+		});
 	}
 
 	private startDataSync(peerId: string, pc: PeerConnection): void {