ox 1.6.2 → 1.7.0

package/src/core/Secp256k1.ts

@@ -10,6 +10,7 @@ import {
   normalizePublicKey,
   normalizeSignature,
 } from './internal/cryptoIo.js'
+import * as keyDerivation from './internal/keyDerivation.js'
 import * as engine from './internal/secp256k1.js'
 import * as Entropy from './internal/entropy.js'
 import {
@@ -18,6 +19,7 @@ import {
   toRecoveredBytes,
 } from './internal/signature.js'
 import type { OneOf } from './internal/types.js'
+import * as Mnemonic from './Mnemonic.js'
 import * as PublicKey from './PublicKey.js'
 import type * as Signature from './Signature.js'
 
@@ -76,7 +78,7 @@ export declare namespace createKeyPair {
  * Derives a valid secp256k1 private key from a 32-byte WebAuthn PRF output.
  *
  * The permanent derivation contract uses the PRF output as the HMAC-SHA256
- * key. Its message is the UTF-8 bytes of `ox.secp256k1.fromPrf.v1` followed by
+ * key. The HMAC message uses the `ox.secp256k1.fromPrf.v1` domain followed by
  * a 32-bit big-endian counter starting at zero. Invalid scalars are skipped.
  *
  * @example
@@ -103,7 +105,7 @@ export function fromPrf<as extends 'Hex' | 'Bytes' = 'Hex'>(
   for (let counter = 0; ; counter++) {
     const candidate = Hash.hmac256(
       bytes,
-      Bytes.concat(fromPrfLabel, Bytes.fromNumber(counter, { size: 4 })),
+      Bytes.concat(fromPrfDomain, Bytes.fromNumber(counter, { size: 4 })),
       { as: 'Bytes' },
     )
     if (noble.utils.isValidSecretKey(candidate)) {
@@ -141,6 +143,115 @@ export declare namespace fromPrf {
     | Errors.GlobalErrorType
 }
 
+/**
+ * Derives a valid secp256k1 private key from a BIP-39 mnemonic.
+ *
+ * This is equivalent to {@link ox#Mnemonic.toPrivateKey}, and derives the
+ * private key at `m/44'/60'/0'/0/0` by default.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Secp256k1 } from 'ox'
+ *
+ * const privateKey = Secp256k1.fromMnemonic(
+ *   'test test test test test test test test test test test junk'
+ * )
+ * ```
+ *
+ * @param mnemonic - BIP-39 mnemonic phrase.
+ * @param options - Options.
+ * @returns A valid secp256k1 private key.
+ */
+export function fromMnemonic<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  mnemonic: string,
+  options: fromMnemonic.Options<as> = {},
+): fromMnemonic.ReturnType<as> {
+  const { as = 'Hex', passphrase, path } = options
+  return Mnemonic.toPrivateKey(mnemonic, { as, passphrase, path }) as never
+}
+
+export declare namespace fromMnemonic {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned private key.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+    /** Derivation path. @default `m/44'/60'/0'/0/0` */
+    path?: string | undefined
+    /** Optional BIP-39 passphrase. */
+    passphrase?: string | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    Mnemonic.toPrivateKey.ReturnType<as>
+
+  type ErrorType = Mnemonic.toPrivateKey.ErrorType
+}
+
+/**
+ * Derives a valid secp256k1 private key from a seed.
+ *
+ * The seed must contain at least 32 bytes of cryptographically strong key
+ * material. Do not pass a password directly; use a password KDF first.
+ *
+ * The permanent derivation contract uses the seed as the HMAC-SHA256
+ * key. The HMAC message uses the `ox.secp256k1.fromSeed.v1` domain followed by
+ * a 32-bit big-endian counter starting at zero. Invalid scalars are skipped.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Secp256k1 } from 'ox'
+ *
+ * const privateKey = Secp256k1.fromSeed(
+ *   '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+ * )
+ * ```
+ *
+ * @param seed - Seed containing at least 32 bytes of cryptographically strong key material.
+ * @param options - Options.
+ * @returns A valid secp256k1 private key.
+ */
+export function fromSeed<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  seed: Hex.Hex | Bytes.Bytes,
+  options: fromSeed.Options<as> = {},
+): fromSeed.ReturnType<as> {
+  const { as = 'Hex' } = options
+  const bytes = Bytes.from(seed)
+  if (bytes.length < 32) throw new InvalidSeedSizeError({ size: bytes.length })
+
+  const privateKey = keyDerivation.derive(bytes, fromSeedDomain, {
+    validate: noble.utils.isValidSecretKey,
+  })
+  if (as === 'Hex') {
+    const value = Hex.fromBytes(privateKey)
+    privateKey.fill(0)
+    return value as never
+  }
+  return privateKey as never
+}
+
+export declare namespace fromSeed {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned private key.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | keyDerivation.derive.ErrorType
+    | InvalidSeedSizeError
+    | Errors.GlobalErrorType
+}
+
 /**
  * Computes the secp256k1 ECDSA public key from a provided private key.
  *
@@ -593,4 +704,24 @@ export declare namespace InvalidPrfSizeError {
   }
 }
 
-const fromPrfLabel = Bytes.fromString('ox.secp256k1.fromPrf.v1')
+/** Thrown when a seed contains fewer than 32 bytes. */
+export class InvalidSeedSizeError extends Errors.BaseError {
+  override readonly name = 'Secp256k1.InvalidSeedSizeError'
+
+  constructor(options: InvalidSeedSizeError.Options) {
+    super(
+      `Seed must contain at least 32 bytes. Received ${options.size} bytes.`,
+    )
+  }
+}
+
+export declare namespace InvalidSeedSizeError {
+  /** Options for {@link ox#Secp256k1.InvalidSeedSizeError}. */
+  type Options = {
+    /** Received seed size. */
+    size: number
+  }
+}
+
+const fromPrfDomain = Bytes.fromString('ox.secp256k1.fromPrf.v1')
+const fromSeedDomain = Bytes.fromString('ox.secp256k1.fromSeed.v1')

package/src/core/_test/AesGcm.test-d.ts

@@ -0,0 +1,19 @@
+import { AesGcm } from 'ox'
+import { expectTypeOf, test } from 'vp/test'
+
+test('fromMnemonic', () => {
+  const mnemonic = 'test test test test test test test test test test test junk'
+
+  expectTypeOf(AesGcm.fromMnemonic(mnemonic)).toEqualTypeOf<
+    Promise<CryptoKey>
+  >()
+  expectTypeOf(
+    AesGcm.fromMnemonic(mnemonic, { passphrase: 'qwerty' }),
+  ).toEqualTypeOf<Promise<CryptoKey>>()
+})
+
+test('fromSeed', () => {
+  expectTypeOf(AesGcm.fromSeed(new Uint8Array(32))).toEqualTypeOf<
+    Promise<CryptoKey>
+  >()
+})

package/src/core/_test/AesGcm.test.ts

@@ -1,4 +1,4 @@
-import { AesGcm, Bytes, Hex } from 'ox'
+import { AesGcm, Bytes, Hex, Mnemonic } from 'ox'
 import { describe, expect, test } from 'vp/test'
 
 describe('decrypt', () => {
@@ -159,6 +159,92 @@ describe('fromPrf', () => {
   })
 })
 
+describe('fromMnemonic', () => {
+  const mnemonic = 'test test test test test test test test test test test junk'
+
+  test('default', async () => {
+    const key = await AesGcm.fromMnemonic(mnemonic)
+    const expectedKey = await AesGcm.fromSeed(Mnemonic.toSeed(mnemonic))
+    const value = Bytes.fromString('i am a secret message')
+    const encrypted = await AesGcm.encrypt(value, key)
+
+    await expect(AesGcm.decrypt(encrypted, expectedKey)).resolves.toEqual(value)
+  })
+
+  test('options: passphrase', async () => {
+    const key = await AesGcm.fromMnemonic(mnemonic, {
+      passphrase: 'qwerty',
+    })
+    const defaultKey = await AesGcm.fromMnemonic(mnemonic)
+    const encrypted = await AesGcm.encrypt('0xdeadbeef', key)
+
+    await expect(AesGcm.decrypt(encrypted, defaultKey)).rejects.toThrowError()
+  })
+})
+
+describe('fromSeed', () => {
+  const seed =
+    '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+
+  test('vector', async () => {
+    const key = await AesGcm.fromSeed(seed)
+    const expectedKey = await globalThis.crypto.subtle.importKey(
+      'raw',
+      Bytes.fromHex(
+        '0xd42ffe5cb894ce61e9f448e8083f53b2ab90d2acad0929e80b0abb85e915cb3a',
+      ),
+      { name: 'AES-GCM' },
+      false,
+      ['decrypt'],
+    )
+    const value = Bytes.fromString('i am a secret message')
+    const encrypted = await AesGcm.encrypt(value, key)
+
+    await expect(AesGcm.decrypt(encrypted, expectedKey)).resolves.toEqual(value)
+  })
+
+  test('value: Bytes', async () => {
+    const key = await AesGcm.fromSeed(Bytes.fromHex(seed))
+    const value = Bytes.fromString('i am a secret message')
+
+    await expect(
+      AesGcm.decrypt(await AesGcm.encrypt(value, key), key),
+    ).resolves.toEqual(value)
+  })
+
+  test('behavior: accepts seeds longer than 32 bytes', async () => {
+    const key = await AesGcm.fromSeed(new Uint8Array(64))
+
+    expect({
+      algorithm: key.algorithm,
+      extractable: key.extractable,
+      type: key.type,
+      usages: key.usages,
+    }).toMatchInlineSnapshot(`
+      {
+        "algorithm": {
+          "length": 256,
+          "name": "AES-GCM",
+        },
+        "extractable": false,
+        "type": "secret",
+        "usages": [
+          "encrypt",
+          "decrypt",
+        ],
+      }
+    `)
+  })
+
+  test('error: seed is too short', async () => {
+    await expect(
+      AesGcm.fromSeed(new Uint8Array(31)),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[AesGcm.InvalidSeedSizeError: Seed must contain at least 32 bytes. Received 31 bytes.]`,
+    )
+  })
+})
+
 describe('getKey', () => {
   test('default', async () => {
     const key = await AesGcm.getKey({ password: 'qwerty' })
@@ -180,9 +266,12 @@ test('exports', () => {
       "decrypt",
       "encrypt",
       "fromPrf",
+      "fromMnemonic",
+      "fromSeed",
       "getKey",
       "randomSalt",
       "InvalidPrfSizeError",
+      "InvalidSeedSizeError",
     ]
   `)
 })

package/src/core/_test/Ed25519.test-d.ts

@@ -40,6 +40,30 @@ test('fromPrf', () => {
   ).toEqualTypeOf<Bytes.Bytes>()
 })
 
+test('fromMnemonic', () => {
+  const mnemonic = 'test test test test test test test test test test test junk'
+
+  expectTypeOf(Ed25519.fromMnemonic(mnemonic)).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    Ed25519.fromMnemonic(mnemonic, { passphrase: 'qwerty' }),
+  ).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    Ed25519.fromMnemonic(mnemonic, { as: 'Bytes' }),
+  ).toEqualTypeOf<Bytes.Bytes>()
+})
+
+test('fromSeed', () => {
+  const seed =
+    '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+
+  expectTypeOf(Ed25519.fromSeed(seed)).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(Ed25519.fromSeed(new Uint8Array(32))).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(Ed25519.fromSeed(seed, { as: 'Hex' })).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    Ed25519.fromSeed(seed, { as: 'Bytes' }),
+  ).toEqualTypeOf<Bytes.Bytes>()
+})
+
 test('getPublicKey', () => {
   // Default behavior (Hex)
   {

package/src/core/_test/Ed25519.test.ts

@@ -1,4 +1,4 @@
-import { Bytes, Ed25519, Engine, Hex, X25519 } from 'ox'
+import { Bytes, Ed25519, Engine, Hex, Mnemonic, X25519 } from 'ox'
 import { describe, expect, test } from 'vp/test'
 
 describe('createKeyPair', () => {
@@ -146,6 +146,89 @@ describe('fromPrf', () => {
   })
 })
 
+describe('fromMnemonic', () => {
+  const mnemonic = 'test test test test test test test test test test test junk'
+
+  test('default', () => {
+    const privateKey = Ed25519.fromMnemonic(mnemonic)
+
+    expect(privateKey).toBe(Ed25519.fromSeed(Mnemonic.toSeed(mnemonic)))
+    expect(privateKey).toMatchInlineSnapshot(
+      `"0x23fb07a427d2bc36141d1e6c7e56c72679739eff374a8e8def282f1048674567"`,
+    )
+  })
+
+  test('options: passphrase', () => {
+    expect(
+      Ed25519.fromMnemonic(mnemonic, { passphrase: 'qwerty' }),
+    ).toMatchInlineSnapshot(
+      `"0xe888791c9d783e772d92b0bf2aa326b1cda8214a03c3c07933615b1a98fc8651"`,
+    )
+  })
+
+  test('options: as', () => {
+    const privateKey = Ed25519.fromMnemonic(mnemonic, { as: 'Bytes' })
+
+    expect(privateKey).toBeInstanceOf(Uint8Array)
+    expect(privateKey).toHaveLength(32)
+  })
+})
+
+describe('fromSeed', () => {
+  const seed =
+    '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+
+  test('vector', () => {
+    expect(Ed25519.fromSeed(seed)).toMatchInlineSnapshot(
+      `"0xfd09c7b2acda46034df7e428377fdc37200094c9b51690fa1b733ee3c16a2d07"`,
+    )
+  })
+
+  test('value: Bytes', () => {
+    expect(Ed25519.fromSeed(Bytes.fromHex(seed))).toMatchInlineSnapshot(
+      `"0xfd09c7b2acda46034df7e428377fdc37200094c9b51690fa1b733ee3c16a2d07"`,
+    )
+  })
+
+  test('options: as', () => {
+    expect(Ed25519.fromSeed(seed, { as: 'Bytes' })).toEqual(
+      Bytes.fromHex(
+        '0xfd09c7b2acda46034df7e428377fdc37200094c9b51690fa1b733ee3c16a2d07',
+      ),
+    )
+  })
+
+  test('behavior: output signs and verifies', () => {
+    const privateKey = Ed25519.fromSeed(new Uint8Array(64))
+    const publicKey = Ed25519.getPublicKey({ privateKey })
+    const payload = '0xdeadbeef'
+    const signature = Ed25519.sign({ payload, privateKey })
+
+    expect(Ed25519.verify({ payload, publicKey, signature })).toBe(true)
+  })
+
+  test('behavior: zeroes intermediate key for Hex output', () => {
+    const candidate = new Uint8Array(32).fill(1)
+    Engine.with(
+      {
+        Hash: {
+          hmacSha256: () => candidate,
+        },
+      },
+      () => Ed25519.fromSeed(new Uint8Array(32)),
+    )
+
+    expect(candidate).toEqual(new Uint8Array(32))
+  })
+
+  test('error: seed is too short', () => {
+    expect(() => Ed25519.fromSeed(new Uint8Array(31)))
+      .toThrowErrorMatchingInlineSnapshot(`
+        [Ed25519.InvalidSeedSizeError: Seed must contain at least 32 bytes. Received 31 bytes.]
+      `)
+  })
+})
+
 describe('getPublicKey', () => {
   const privateKey =
     '0x9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60'
@@ -545,6 +628,8 @@ test('exports', () => {
       "noble",
       "createKeyPair",
       "fromPrf",
+      "fromMnemonic",
+      "fromSeed",
       "getPublicKey",
       "randomPrivateKey",
       "sign",
@@ -552,6 +637,7 @@ test('exports', () => {
       "toX25519PublicKey",
       "toX25519PrivateKey",
       "InvalidPrfSizeError",
+      "InvalidSeedSizeError",
     ]
   `)
 })

package/src/core/_test/MlDsa44.test-d.ts

@@ -24,6 +24,30 @@ test('fromPrf', () => {
   ).toEqualTypeOf<Bytes.Bytes>()
 })
 
+test('fromMnemonic', () => {
+  const mnemonic = 'test test test test test test test test test test test junk'
+
+  expectTypeOf(MlDsa44.fromMnemonic(mnemonic)).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    MlDsa44.fromMnemonic(mnemonic, { passphrase: 'qwerty' }),
+  ).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    MlDsa44.fromMnemonic(mnemonic, { as: 'Bytes' }),
+  ).toEqualTypeOf<Bytes.Bytes>()
+})
+
+test('fromSeed', () => {
+  const seed =
+    '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+
+  expectTypeOf(MlDsa44.fromSeed(seed)).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(MlDsa44.fromSeed(new Uint8Array(32))).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(MlDsa44.fromSeed(seed, { as: 'Hex' })).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    MlDsa44.fromSeed(seed, { as: 'Bytes' }),
+  ).toEqualTypeOf<Bytes.Bytes>()
+})
+
 test('getPublicKey', () => {
   expectTypeOf(
     MlDsa44.getPublicKey({ privateKey: '0x' }),

package/src/core/_test/MlDsa44.test.ts

@@ -1,4 +1,4 @@
-import { Bytes, Engine, Hash, Hex, MlDsa44 } from 'ox'
+import { Bytes, Engine, Hash, Hex, MlDsa44, Mnemonic } from 'ox'
 import { describe, expect, test } from 'vp/test'
 
 const privateKey = Hex.fromBytes(new Uint8Array(32).fill(7))
@@ -139,6 +139,74 @@ describe('fromPrf', () => {
   })
 })
 
+describe('fromMnemonic', () => {
+  const mnemonic = 'test test test test test test test test test test test junk'
+
+  test('default', () => {
+    const privateKey = MlDsa44.fromMnemonic(mnemonic)
+
+    expect(privateKey).toBe(MlDsa44.fromSeed(Mnemonic.toSeed(mnemonic)))
+    expect(privateKey).toMatchInlineSnapshot(
+      `"0x787f747b571a3511deac4d045a7876ae2349f45b9f9f4e3a6ee40342313a963f"`,
+    )
+  })
+
+  test('options: passphrase', () => {
+    expect(
+      MlDsa44.fromMnemonic(mnemonic, { passphrase: 'qwerty' }),
+    ).toMatchInlineSnapshot(
+      `"0x51202c4aaf8b4090f94c43ae43234b133a2646642fbc4ca39d8883a0b39d2b44"`,
+    )
+  })
+
+  test('options: as', () => {
+    const privateKey = MlDsa44.fromMnemonic(mnemonic, { as: 'Bytes' })
+
+    expect(privateKey).toBeInstanceOf(Uint8Array)
+    expect(privateKey).toHaveLength(32)
+  })
+})
+
+describe('fromSeed', () => {
+  const seed =
+    '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+
+  test('vector', () => {
+    expect(MlDsa44.fromSeed(seed)).toMatchInlineSnapshot(
+      `"0xbee74160aef452ec0e90a4c347bbb0ac37e93fb94855f7a98dfe9afabebbdad6"`,
+    )
+  })
+
+  test('value: Bytes', () => {
+    expect(MlDsa44.fromSeed(Bytes.fromHex(seed))).toMatchInlineSnapshot(
+      `"0xbee74160aef452ec0e90a4c347bbb0ac37e93fb94855f7a98dfe9afabebbdad6"`,
+    )
+  })
+
+  test('options: as', () => {
+    expect(MlDsa44.fromSeed(seed, { as: 'Bytes' })).toEqual(
+      Bytes.fromHex(
+        '0xbee74160aef452ec0e90a4c347bbb0ac37e93fb94855f7a98dfe9afabebbdad6',
+      ),
+    )
+  })
+
+  test('behavior: output signs and verifies', () => {
+    const privateKey = MlDsa44.fromSeed(new Uint8Array(64))
+    const publicKey = MlDsa44.getPublicKey({ privateKey })
+    const signature = MlDsa44.sign({ payload, privateKey })
+
+    expect(MlDsa44.verify({ payload, publicKey, signature })).toBe(true)
+  })
+
+  test('error: seed is too short', () => {
+    expect(() => MlDsa44.fromSeed(new Uint8Array(31)))
+      .toThrowErrorMatchingInlineSnapshot(`
+        [MlDsa44.InvalidSeedSizeError: Seed must contain at least 32 bytes. Received 31 bytes.]
+      `)
+  })
+})
+
 describe('getPublicKey', () => {
   test('default', () => {
     const publicKey = MlDsa44.getPublicKey({ privateKey })

package/src/core/_test/P256.test-d.ts

@@ -0,0 +1,26 @@
+import { type Bytes, type Hex, P256 } from 'ox'
+import { expectTypeOf, test } from 'vp/test'
+
+test('fromMnemonic', () => {
+  const mnemonic = 'test test test test test test test test test test test junk'
+
+  expectTypeOf(P256.fromMnemonic(mnemonic)).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    P256.fromMnemonic(mnemonic, { passphrase: 'qwerty' }),
+  ).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    P256.fromMnemonic(mnemonic, { as: 'Bytes' }),
+  ).toEqualTypeOf<Bytes.Bytes>()
+})
+
+test('fromSeed', () => {
+  const seed =
+    '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+
+  expectTypeOf(P256.fromSeed(seed)).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(P256.fromSeed(new Uint8Array(32))).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(P256.fromSeed(seed, { as: 'Hex' })).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    P256.fromSeed(seed, { as: 'Bytes' }),
+  ).toEqualTypeOf<Bytes.Bytes>()
+})