ox 1.6.3 → 1.7.0

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

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

@@ -1,4 +1,4 @@
-import { Bytes, Hex, P256 } from 'ox'
+import { Bytes, Engine, Hex, Mnemonic, P256 } from 'ox'
 import { describe, expect, test } from 'vp/test'
 import { accounts } from '../../../test/constants/accounts.js'
 
@@ -145,6 +145,100 @@ describe('createKeyPair', () => {
   })
 })
 
+describe('fromMnemonic', () => {
+  const mnemonic = 'test test test test test test test test test test test junk'
+
+  test('default', () => {
+    const privateKey = P256.fromMnemonic(mnemonic)
+
+    expect(privateKey).toBe(P256.fromSeed(Mnemonic.toSeed(mnemonic)))
+    expect(privateKey).toMatchInlineSnapshot(
+      `"0x882f5b02a84c96bceeebf9c868bec73041d51b041ae05380e66a41508648ebc3"`,
+    )
+  })
+
+  test('options: passphrase', () => {
+    expect(
+      P256.fromMnemonic(mnemonic, { passphrase: 'qwerty' }),
+    ).toMatchInlineSnapshot(
+      `"0x364ff539f37ce477d49a35476c9ad32a2a3fed1d1237eaee7abdfd07655ad9f5"`,
+    )
+  })
+
+  test('options: as', () => {
+    const privateKey = P256.fromMnemonic(mnemonic, { as: 'Bytes' })
+
+    expect(privateKey).toBeInstanceOf(Uint8Array)
+    expect(privateKey).toHaveLength(32)
+  })
+})
+
+describe('fromSeed', () => {
+  const seed =
+    '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+
+  test('vector', () => {
+    expect(P256.fromSeed(seed)).toMatchInlineSnapshot(
+      `"0x724009e76eb27e34eb77b93db354b9015ecd4296deb57561f5214bab68b94a6f"`,
+    )
+  })
+
+  test('value: Bytes', () => {
+    expect(P256.fromSeed(Bytes.fromHex(seed))).toMatchInlineSnapshot(
+      `"0x724009e76eb27e34eb77b93db354b9015ecd4296deb57561f5214bab68b94a6f"`,
+    )
+  })
+
+  test('options: as', () => {
+    expect(P256.fromSeed(seed, { as: 'Bytes' })).toEqual(
+      Bytes.fromHex(
+        '0x724009e76eb27e34eb77b93db354b9015ecd4296deb57561f5214bab68b94a6f',
+      ),
+    )
+  })
+
+  test('behavior: output is a valid P256 private key', () => {
+    const privateKey = P256.fromSeed(new Uint8Array(64), { as: 'Bytes' })
+
+    expect(P256.noble.utils.isValidSecretKey(privateKey)).toBe(true)
+  })
+
+  test('behavior: skips invalid scalar candidates', () => {
+    const messages: Hex.Hex[] = []
+    const privateKey = Engine.with(
+      {
+        Hash: {
+          hmacSha256: (_key, message) => {
+            messages.push(Hex.fromBytes(message))
+            if (messages.length === 1) return new Uint8Array(32)
+            return Bytes.fromHex(
+              '0xef3f982137910a4c362017e69ba173fbb342325802ec827767aa6942027af35b',
+            )
+          },
+        },
+      },
+      () => P256.fromSeed(new Uint8Array(32)),
+    )
+
+    expect(privateKey).toBe(
+      '0xef3f982137910a4c362017e69ba173fbb342325802ec827767aa6942027af35b',
+    )
+    expect(messages).toMatchInlineSnapshot(`
+      [
+        "0x6f782e703235362e66726f6d536565642e763100000000",
+        "0x6f782e703235362e66726f6d536565642e763100000001",
+      ]
+    `)
+  })
+
+  test('error: seed is too short', () => {
+    expect(() => P256.fromSeed(new Uint8Array(31)))
+      .toThrowErrorMatchingInlineSnapshot(`
+        [P256.InvalidSeedSizeError: Seed must contain at least 32 bytes. Received 31 bytes.]
+      `)
+  })
+})
+
 describe('getSharedSecret', () => {
   test('default', () => {
     const { privateKey: privateKeyA, publicKey: publicKeyA } =
@@ -546,12 +640,15 @@ test('exports', () => {
     [
       "noble",
       "createKeyPair",
+      "fromMnemonic",
+      "fromSeed",
       "getPublicKey",
       "getSharedSecret",
       "randomPrivateKey",
       "recoverPublicKey",
       "sign",
       "verify",
+      "InvalidSeedSizeError",
     ]
   `)
 })

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

@@ -12,3 +12,30 @@ test('fromPrf', () => {
     Secp256k1.fromPrf(prf, { as: 'Bytes' }),
   ).toEqualTypeOf<Bytes.Bytes>()
 })
+
+test('fromMnemonic', () => {
+  const mnemonic = 'test test test test test test test test test test test junk'
+
+  expectTypeOf(Secp256k1.fromMnemonic(mnemonic)).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    Secp256k1.fromMnemonic(mnemonic, { passphrase: 'qwerty' }),
+  ).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    Secp256k1.fromMnemonic(mnemonic, { as: 'Bytes' }),
+  ).toEqualTypeOf<Bytes.Bytes>()
+  expectTypeOf(
+    Secp256k1.fromMnemonic(mnemonic, { path: "m/44'/60'/0'/0/1" }),
+  ).toEqualTypeOf<Hex.Hex>()
+})
+
+test('fromSeed', () => {
+  const seed =
+    '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+
+  expectTypeOf(Secp256k1.fromSeed(seed)).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(Secp256k1.fromSeed(new Uint8Array(32))).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(Secp256k1.fromSeed(seed, { as: 'Hex' })).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    Secp256k1.fromSeed(seed, { as: 'Bytes' }),
+  ).toEqualTypeOf<Bytes.Bytes>()
+})

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

@@ -1,4 +1,4 @@
-import { Address, Bytes, Engine, Hex, PublicKey, Secp256k1 } from 'ox'
+import { Address, Bytes, Engine, Hex, Mnemonic, PublicKey, Secp256k1 } from 'ox'
 import { describe, expect, test } from 'vp/test'
 import { accounts } from '../../../test/constants/accounts.js'
 
@@ -211,6 +211,114 @@ describe('fromPrf', () => {
   })
 })
 
+describe('fromMnemonic', () => {
+  const mnemonic = 'test test test test test test test test test test test junk'
+
+  test('default', () => {
+    const privateKey = Secp256k1.fromMnemonic(mnemonic)
+
+    expect(privateKey).toBe(Mnemonic.toPrivateKey(mnemonic, { as: 'Hex' }))
+    expect(privateKey).toMatchInlineSnapshot(
+      `"0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"`,
+    )
+  })
+
+  test('options: passphrase', () => {
+    expect(
+      Secp256k1.fromMnemonic(mnemonic, { passphrase: 'qwerty' }),
+    ).toMatchInlineSnapshot(
+      `"0x0bef893b1cc27e9ce726d5f12f75d61a07d4df87c02106083463cd712ac5c478"`,
+    )
+  })
+
+  test('options: as', () => {
+    const privateKey = Secp256k1.fromMnemonic(mnemonic, { as: 'Bytes' })
+
+    expect(privateKey).toBeInstanceOf(Uint8Array)
+    expect(privateKey).toHaveLength(32)
+  })
+
+  test('options: path', () => {
+    const path = "m/44'/60'/0'/0/1"
+
+    expect(Secp256k1.fromMnemonic(mnemonic, { path })).toBe(
+      Mnemonic.toPrivateKey(mnemonic, { as: 'Hex', path }),
+    )
+  })
+})
+
+describe('fromSeed', () => {
+  const seed =
+    '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+
+  test('vector', () => {
+    expect(Secp256k1.fromSeed(seed)).toMatchInlineSnapshot(
+      `"0x5f7dcbba41adaafa378861d78b144f7b2827e79fa994a341628f5470d5bfbdd4"`,
+    )
+  })
+
+  test('value: Bytes', () => {
+    expect(Secp256k1.fromSeed(Bytes.fromHex(seed))).toMatchInlineSnapshot(
+      `"0x5f7dcbba41adaafa378861d78b144f7b2827e79fa994a341628f5470d5bfbdd4"`,
+    )
+  })
+
+  test('options: as', () => {
+    expect(Secp256k1.fromSeed(seed, { as: 'Bytes' })).toEqual(
+      Bytes.fromHex(
+        '0x5f7dcbba41adaafa378861d78b144f7b2827e79fa994a341628f5470d5bfbdd4',
+      ),
+    )
+  })
+
+  test('behavior: accepts seeds longer than 32 bytes', () => {
+    const privateKey = Secp256k1.fromSeed(new Uint8Array(64), { as: 'Bytes' })
+
+    expect(Secp256k1.noble.utils.isValidSecretKey(privateKey)).toBe(true)
+  })
+
+  test('behavior: domain is distinct from fromPrf', () => {
+    expect(Secp256k1.fromSeed(seed)).not.toBe(Secp256k1.fromPrf(seed))
+  })
+
+  test('behavior: skips invalid scalar candidates', () => {
+    const invalid = new Uint8Array(32).fill(0xff)
+    const messages: Hex.Hex[] = []
+    const privateKey = Engine.with(
+      {
+        Hash: {
+          hmacSha256: (_key, message) => {
+            messages.push(Hex.fromBytes(message))
+            if (messages.length === 1) return invalid
+            return Bytes.fromHex(
+              '0xef3f982137910a4c362017e69ba173fbb342325802ec827767aa6942027af35b',
+            )
+          },
+        },
+      },
+      () => Secp256k1.fromSeed(new Uint8Array(32)),
+    )
+
+    expect(privateKey).toBe(
+      '0xef3f982137910a4c362017e69ba173fbb342325802ec827767aa6942027af35b',
+    )
+    expect(invalid).toEqual(new Uint8Array(32))
+    expect(messages).toMatchInlineSnapshot(`
+      [
+        "0x6f782e736563703235366b312e66726f6d536565642e763100000000",
+        "0x6f782e736563703235366b312e66726f6d536565642e763100000001",
+      ]
+    `)
+  })
+
+  test('error: seed is too short', () => {
+    expect(() => Secp256k1.fromSeed(new Uint8Array(31)))
+      .toThrowErrorMatchingInlineSnapshot(`
+        [Secp256k1.InvalidSeedSizeError: Seed must contain at least 32 bytes. Received 31 bytes.]
+      `)
+  })
+})
+
 describe('getSharedSecret', () => {
   test('default', () => {
     const privateKeyA = accounts[0].privateKey
@@ -572,6 +680,8 @@ test('exports', () => {
       "noble",
       "createKeyPair",
       "fromPrf",
+      "fromMnemonic",
+      "fromSeed",
       "getPublicKey",
       "getSharedSecret",
       "randomPrivateKey",
@@ -580,6 +690,7 @@ test('exports', () => {
       "sign",
       "verify",
       "InvalidPrfSizeError",
+      "InvalidSeedSizeError",
     ]
   `)
 })

package/src/core/internal/keyDerivation.ts

@@ -0,0 +1,34 @@
+import * as Bytes from '../Bytes.js'
+import type * as Errors from '../Errors.js'
+import * as Hash from '../Hash.js'
+
+/** @internal */
+export function derive(
+  seed: Bytes.Bytes,
+  domain: Bytes.Bytes,
+  options: derive.Options = {},
+): Bytes.Bytes {
+  const { validate } = options
+  for (let counter = 0; ; counter++) {
+    const key = Hash.hmac256(
+      seed,
+      Bytes.concat(domain, Bytes.fromNumber(counter, { size: 4 })),
+      { as: 'Bytes' },
+    )
+    if (!validate || validate(key)) return key
+    key.fill(0)
+  }
+}
+
+/** @internal */
+export declare namespace derive {
+  type Options = {
+    validate?: ((key: Bytes.Bytes) => boolean) | undefined
+  }
+
+  type ErrorType =
+    | Bytes.concat.ErrorType
+    | Bytes.fromNumber.ErrorType
+    | Hash.hmac256.ErrorType
+    | Errors.GlobalErrorType
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '1.6.3'
+export const version = '1.7.0'