feat(keys): derive ML-DSA-65 keys from BIP-39 seed phrases (#224)

Adopts the SLIP-0010 ML-DSA extension from satoshilabs/slips#1968 (also
QIP-0002 and the Lattice HD Wallets construction): master node
HMAC-SHA512(key = "ML-DSA-65 seed", data = BIP-39 seed), standard
hardened-only child steps, and the 32-byte node secret used as the
FIPS 204 seed xi.

parseSeedPhrase now takes an options object ({ path, keyType }) in
addition to the existing path-string form. The SLIP-0010 code moves to
utils/hd.ts, parametrized by curve salt, and is verified against the
official ed25519 vectors and the slips#1968 ML-DSA-65 vectors (which are
validated against the NIST ACVP ML-DSA-keyGen-FIPS204 KATs).

Path parsing now accepts bare "m" (master node) and rejects indexes
>= 2^31, which previously wrapped silently.

Author: r-near

.changeset/ml-dsa-seed-phrase-derivation.md

@@ -0,0 +1,5 @@
+---
+"near-kit": minor
+---
+
+Add ML-DSA-65 key derivation from BIP-39 seed phrases. `parseSeedPhrase` now accepts an options object with a `keyType` of `"ed25519"` (default) or `"ml-dsa-65"`, deriving post-quantum keys via the SLIP-0010 construction from satoshilabs/slips#1968 (master node `HMAC-SHA512(key = "ML-DSA-65 seed", data = BIP-39 seed)`, hardened-only children, node secret used as the FIPS 204 seed ξ). Validated against the slips#1968 test vectors.

docs/in-depth/key-management.mdx

@@ -168,6 +168,22 @@ await pqNear.transaction("alice.near").transfer("bob.near", "1 NEAR").send()
 
 For a key generated by `MlDsa65KeyPair`, the serialized secret key is the 32-byte seed (`ml-dsa-65:<base58 seed>`). `parseKey` also accepts the 4032-byte raw expanded secret key that nearcore / near-cli write to credential files (`ml-dsa-65:<base58 raw key>`), so existing credentials load too. Either form round-trips. The public key is 1952 bytes and signatures are 3309 bytes.
 
+#### Deriving from a seed phrase
+
+`parseSeedPhrase` can derive an ML-DSA-65 key from a BIP-39 mnemonic, so a post-quantum key is recoverable from the same phrase a wallet already backs up:
+
+```typescript
+import { parseSeedPhrase } from "near-kit"
+
+const pqKey = parseSeedPhrase("word1 word2 ... word12", {
+  keyType: "ml-dsa-65",
+  path: "m/44'/397'/0'", // default; bump the index for more keys
+})
+console.log(pqKey.publicKey.toString()) // ml-dsa-65:...
+```
+
+Derivation follows the SLIP-0010 extension proposed in [satoshilabs/slips#1968](https://github.com/satoshilabs/slips/pull/1968): the master node is `HMAC-SHA512(key = "ML-DSA-65 seed", data = BIP-39 seed)`, children use the standard SLIP-0010 hardened-only step, and the derived 32-byte node secret is the FIPS 204 seed ξ fed to ML-DSA key generation. Because the master salt differs from ed25519's, the ML-DSA-65 key derived from a phrase is unrelated to the ed25519 key derived from that same phrase.
+
 <Note title="On-chain key handles">
 On-chain, an ML-DSA-65 access key is stored as a 32-byte hash, so `view_access_key_list` returns it as `ml-dsa-65-hash:...`, **not** the full key. Parse that form with `parseMlDsa65Handle()` for display and comparison — it is a read-only handle and cannot be used to sign or as an `addKey` public key (the full key is not recoverable from it).
 </Note>

packages/near-kit/src/index.ts

@@ -117,6 +117,7 @@ export {
   isValidPublicKey,
   MlDsa65KeyPair,
   type MlDsa65PublicKeyHandle,
+  type ParseSeedPhraseOptions,
   type PrivateKey,
   parseAmount,
   parseGas,

packages/near-kit/src/utils/hd.ts

@@ -0,0 +1,103 @@
+/**
+ * SLIP-0010 hardened-only hierarchical key derivation.
+ *
+ * Implements the HMAC-SHA512 derivation chain from
+ * {@link https://github.com/satoshilabs/slips/blob/master/slip-0010.md | SLIP-0010}
+ * for curves without public-key derivation: every path segment must be
+ * hardened, and the derived 32-byte node secret is used directly as key
+ * material (an ed25519 private key, or an ML-DSA-65 FIPS 204 seed ξ).
+ *
+ * The ML-DSA-65 variant uses the `"ML-DSA-65 seed"` master salt from
+ * {@link https://github.com/satoshilabs/slips/pull/1968 | satoshilabs/slips#1968},
+ * the same construction adopted by Quantus (QIP-0002) and proven secure in the
+ * Lattice HD Wallets paper (https://eprint.iacr.org/2026/380).
+ */
+
+import { hmac } from "@noble/hashes/hmac.js"
+import { sha512 } from "@noble/hashes/sha2.js"
+import { InvalidKeyError } from "../errors/index.js"
+
+/** SLIP-0010 master-node HMAC key for the ed25519 curve. */
+export const ED25519_CURVE_SALT = "ed25519 seed"
+/** Master-node HMAC key for ML-DSA-65, per satoshilabs/slips#1968. */
+export const ML_DSA_65_CURVE_SALT = "ML-DSA-65 seed"
+
+const HARDENED_OFFSET = 0x80000000
+
+/** A SLIP-0010 node: 32-byte secret (I_L) and 32-byte chain code (I_R). */
+export interface Slip10Node {
+  key: Uint8Array
+  chainCode: Uint8Array
+}
+
+/**
+ * SLIP-0010 master node: `I = HMAC-SHA512(key = salt, data = seed)`.
+ * @internal
+ */
+function masterNodeFromSeed(salt: string, seed: Uint8Array): Slip10Node {
+  const I = hmac(sha512, new TextEncoder().encode(salt), seed)
+  return {
+    key: I.slice(0, 32),
+    chainCode: I.slice(32),
+  }
+}
+
+/**
+ * SLIP-0010 hardened child step:
+ * `I = HMAC-SHA512(key = c_par, data = 0x00 || k_par || ser32(index))`.
+ * @internal
+ */
+function deriveChild(parent: Slip10Node, index: number): Slip10Node {
+  const data = new Uint8Array(37)
+  data[0] = 0
+  data.set(parent.key, 1)
+  const view = new DataView(data.buffer)
+  view.setUint32(33, index, false) // big-endian
+
+  const I = hmac(sha512, parent.chainCode, data)
+  return {
+    key: I.slice(0, 32),
+    chainCode: I.slice(32),
+  }
+}
+
+/**
+ * Derive a SLIP-0010 node from a BIP-39 seed along a hardened BIP-32 path.
+ *
+ * @param salt - Master-node HMAC key selecting the scheme
+ * ({@link ED25519_CURVE_SALT} or {@link ML_DSA_65_CURVE_SALT}).
+ * @param seed - BIP-39 seed (typically 64 bytes from `mnemonicToSeedSync`).
+ * @param path - Path like `"m/44'/397'/0'"`. Every segment must be hardened
+ * (`'` suffix); `"m"` alone derives the master node.
+ * @returns The derived node; `key` is the 32-byte secret (ed25519 private key
+ * or ML-DSA-65 seed ξ).
+ */
+export function slip10DerivePath(
+  salt: string,
+  seed: Uint8Array,
+  path: string,
+): Slip10Node {
+  if (!/^m(\/\d+')*$/.test(path)) {
+    throw new InvalidKeyError(
+      `Invalid derivation path: ${path}. Must be hardened (e.g., m/44'/397'/0')`,
+    )
+  }
+
+  let node = masterNodeFromSeed(salt, seed)
+
+  const segments = path
+    .split("/")
+    .slice(1) // Remove 'm'
+    .map((s) => Number.parseInt(s.replace("'", ""), 10))
+
+  for (const segment of segments) {
+    if (segment >= HARDENED_OFFSET) {
+      throw new InvalidKeyError(
+        `Invalid derivation path: ${path}. Index ${segment} out of range`,
+      )
+    }
+    node = deriveChild(node, segment + HARDENED_OFFSET)
+  }
+
+  return node
+}

packages/near-kit/src/utils/key.ts

@@ -1,7 +1,5 @@
 import { ed25519 } from "@noble/curves/ed25519.js"
 import { secp256k1 } from "@noble/curves/secp256k1.js"
-import { hmac } from "@noble/hashes/hmac.js"
-import { sha512 } from "@noble/hashes/sha2.js"
 import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js"
 import { base58, base64 } from "@scure/base"
 import * as bip39 from "@scure/bip39"
@@ -26,6 +24,11 @@ import {
   type SignMessageParams,
 } from "../core/types.js"
 import { InvalidKeyError } from "../errors/index.js"
+import {
+  ED25519_CURVE_SALT,
+  ML_DSA_65_CURVE_SALT,
+  slip10DerivePath,
+} from "./hd.js"
 import { serializeNep413Message } from "./nep413.js"
 
 /**
@@ -484,98 +487,58 @@ export function generateSeedPhrase(
 }
 
 /**
- * SLIP-0010 master key derivation for ed25519
- * Uses 'ed25519 seed' as the HMAC key per SLIP-0010 specification
- * @internal
- */
-function getMasterKeyFromSeed(seed: Uint8Array): {
-  key: Uint8Array
-  chainCode: Uint8Array
-} {
-  const ED25519_SEED = new TextEncoder().encode("ed25519 seed")
-  const I = hmac(sha512, ED25519_SEED, seed)
-  return {
-    key: I.slice(0, 32),
-    chainCode: I.slice(32),
-  }
-}
-
-/**
- * SLIP-0010 child key derivation for ed25519
- * Only supports hardened derivation (index >= 0x80000000)
- * @internal
- */
-function deriveChild(
-  parentKey: Uint8Array,
-  parentChainCode: Uint8Array,
-  index: number,
-): { key: Uint8Array; chainCode: Uint8Array } {
-  // Build data: 0x00 || parent_key || index (big-endian)
-  const data = new Uint8Array(37)
-  data[0] = 0
-  data.set(parentKey, 1)
-  const view = new DataView(data.buffer)
-  view.setUint32(33, index, false) // big-endian
-
-  const I = hmac(sha512, parentChainCode, data)
-  return {
-    key: I.slice(0, 32),
-    chainCode: I.slice(32),
-  }
-}
-
-/**
- * Parse derivation path and derive key using SLIP-0010 for ed25519
- * @internal
+ * Options for {@link parseSeedPhrase}.
  */
-function derivePath(path: string, seed: Uint8Array): Uint8Array {
-  const HARDENED_OFFSET = 0x80000000
-
-  // Validate path format
-  if (!/^m(\/\d+')+$/.test(path)) {
-    throw new InvalidKeyError(
-      `Invalid derivation path: ${path}. Must be hardened (e.g., m/44'/397'/0')`,
-    )
-  }
-
-  // Get master key
-  let { key, chainCode } = getMasterKeyFromSeed(seed)
-
-  // Parse and apply each path segment
-  const segments = path
-    .split("/")
-    .slice(1) // Remove 'm'
-    .map((s) => Number.parseInt(s.replace("'", ""), 10))
-
-  for (const segment of segments) {
-    const result = deriveChild(key, chainCode, segment + HARDENED_OFFSET)
-    key = result.key
-    chainCode = result.chainCode
-  }
-
-  return key
+export interface ParseSeedPhraseOptions {
+  /**
+   * BIP-32 derivation path. Every segment must be hardened.
+   * Defaults to `"m/44'/397'/0'"` (NEAR's coin type).
+   */
+  path?: string
+  /**
+   * Signature scheme of the derived key. Defaults to `"ed25519"`.
+   *
+   * `"ml-dsa-65"` derives a post-quantum ML-DSA-65 (FIPS 204) key using the
+   * SLIP-0010 construction from satoshilabs/slips#1968: the master node is
+   * `HMAC-SHA512(key = "ML-DSA-65 seed", data = BIP-39 seed)` and the derived
+   * 32-byte node secret is the FIPS 204 seed ξ fed to ML-DSA key generation.
+   */
+  keyType?: "ed25519" | "ml-dsa-65"
 }
 
 /**
- * Parse a BIP39 seed phrase to derive a key pair using SLIP-0010 for ed25519.
+ * Parse a BIP39 seed phrase to derive a key pair using SLIP-0010.
  *
- * This uses the correct 'ed25519 seed' HMAC key per SLIP-0010 specification,
- * which is compatible with NEAR CLI and wallet-generated seed phrases.
+ * For ed25519 this uses the 'ed25519 seed' HMAC key per SLIP-0010
+ * specification, which is compatible with NEAR CLI and wallet-generated seed
+ * phrases. For ML-DSA-65 it uses the 'ML-DSA-65 seed' HMAC key per
+ * satoshilabs/slips#1968, and the derived 32-byte node secret is the FIPS 204
+ * seed ξ. The same phrase yields unrelated ed25519 and ML-DSA-65 keys.
  *
  * @param phrase - BIP39 seed phrase (12-24 words)
- * @param path - Derivation path (defaults to "m/44'/397'/0'" for NEAR)
+ * @param pathOrOptions - Derivation path string (defaults to "m/44'/397'/0'"
+ * for NEAR), or a {@link ParseSeedPhraseOptions} object to also pick the key
+ * type
  * @returns KeyPair instance
  *
  * @example
  * ```typescript
  * const keyPair = parseSeedPhrase("word1 word2 ... word12")
  * console.log(keyPair.publicKey.toString()) // ed25519:...
+ *
+ * const pqKeyPair = parseSeedPhrase("word1 word2 ... word12", {
+ *   keyType: "ml-dsa-65",
+ * })
+ * console.log(pqKeyPair.publicKey.toString()) // ml-dsa-65:...
  * ```
  */
 export function parseSeedPhrase(
   phrase: string,
-  path: string = "m/44'/397'/0'",
+  pathOrOptions: string | ParseSeedPhraseOptions = {},
 ): KeyPair {
+  const { path = "m/44'/397'/0'", keyType = "ed25519" } =
+    typeof pathOrOptions === "string" ? { path: pathOrOptions } : pathOrOptions
+
   // Normalize the seed phrase (trim, lowercase, single spaces)
   const normalizedPhrase = phrase
     .trim()
@@ -591,8 +554,17 @@ export function parseSeedPhrase(
   // Convert mnemonic to seed (64 bytes)
   const seed = bip39.mnemonicToSeedSync(normalizedPhrase)
 
-  // Derive key using SLIP-0010 for ed25519
-  const privateKey = derivePath(path, seed)
+  if (keyType === "ml-dsa-65") {
+    // The derived node secret is the FIPS 204 seed ξ; MlDsa65KeyPair expands
+    // it via ML-DSA.KeyGen.
+    const { key } = slip10DerivePath(ML_DSA_65_CURVE_SALT, seed, path)
+    return new MlDsa65KeyPair(key)
+  }
+  if (keyType !== "ed25519") {
+    throw new InvalidKeyError(`Unsupported key type: ${keyType}`)
+  }
+
+  const { key: privateKey } = slip10DerivePath(ED25519_CURVE_SALT, seed, path)
 
   // Get the ed25519 public key from private key
   const publicKey = ed25519.getPublicKey(privateKey)