@abraca/dabra 1.3.1 → 1.3.3

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";