ox 1.6.2 → 1.7.0

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/tempo/KeyAuthorization.test-d.ts

@@ -23,6 +23,12 @@ const multisig = {
   type: 'multisig',
 } as const satisfies SignatureEnvelope.Multisig
 
+const keychain = {
+  inner: signature,
+  type: 'keychain',
+  userAddress: authorization.address,
+} as const satisfies SignatureEnvelope.Keychain
+
 test('accepts primitive signatures', () => {
   const signed = KeyAuthorization.from(authorization, { signature })
 
@@ -31,11 +37,12 @@ test('accepts primitive signatures', () => {
   >()
 })
 
-test('rejects multisig signatures', () => {
-  KeyAuthorization.from(authorization, {
-    // @ts-expect-error Key authorizations accept only primitive signatures.
-    signature: multisig,
-  })
+test('accepts multisig signatures', () => {
+  const signed = KeyAuthorization.from(authorization, { signature: multisig })
+
+  expectTypeOf(signed.signature).toMatchTypeOf<
+    KeyAuthorization.Signed['signature']
+  >()
 
   const multisigRpc = {
     account: multisig.account,
@@ -54,9 +61,37 @@ test('rejects multisig signatures', () => {
     expiry: null,
     keyId: authorization.address,
     keyType: authorization.type,
-    // @ts-expect-error Key authorizations accept only primitive RPC signatures.
     signature: multisigRpc,
   }
 
   expectTypeOf(rpc).toEqualTypeOf<KeyAuthorization.Rpc>()
 })
+
+test('rejects keychain signatures', () => {
+  KeyAuthorization.from(authorization, {
+    // @ts-expect-error Key authorizations do not accept keychain signatures.
+    signature: keychain,
+  })
+
+  const keychainRpc = {
+    signature: {
+      r: '0x01',
+      s: '0x02',
+      type: 'secp256k1',
+      yParity: '0x0',
+    },
+    type: 'keychain',
+    userAddress: authorization.address,
+  } as const satisfies SignatureEnvelope.KeychainRpc
+
+  const rpc: KeyAuthorization.Rpc = {
+    chainId: '0x1',
+    expiry: null,
+    keyId: authorization.address,
+    keyType: authorization.type,
+    // @ts-expect-error Key authorizations do not accept keychain RPC signatures.
+    signature: keychainRpc,
+  }
+
+  expectTypeOf(rpc).toEqualTypeOf<KeyAuthorization.Rpc>()
+})

package/src/tempo/KeyAuthorization.test.ts

@@ -53,11 +53,17 @@ const signature_webauthn = SignatureEnvelope.from({
   },
 })
 
-const signature_multisig = SignatureEnvelope.from({
+const signature_multisig = {
   account: address,
   signatures: [SignatureEnvelope.from(signature_secp256k1)],
   type: 'multisig',
-})
+} as const satisfies SignatureEnvelope.Multisig
+
+const signature_keychain = {
+  inner: SignatureEnvelope.from(signature_secp256k1),
+  type: 'keychain',
+  userAddress: address,
+} as const satisfies SignatureEnvelope.Keychain
 
 describe('from', () => {
   test('default', () => {
@@ -423,7 +429,34 @@ describe('from', () => {
     `)
   })
 
-  test('rejects a multisig signature', () => {
+  test('with signature (multisig)', () => {
+    const authorization = KeyAuthorization.from({
+      address,
+      chainId: 1n,
+      type: 'secp256k1',
+    })
+
+    const signed = KeyAuthorization.from(authorization, {
+      signature: signature_multisig,
+    })
+    expect(signed.signature).toEqual(signature_multisig)
+    expect(
+      KeyAuthorization.from(authorization, {
+        signature: SignatureEnvelope.serialize(signature_multisig),
+      }).signature,
+    ).toEqual(signature_multisig)
+    expect(
+      KeyAuthorization.from({
+        ...authorization,
+        signature: signature_multisig,
+      }).signature,
+    ).toEqual(signature_multisig)
+    expect(
+      KeyAuthorization.deserialize(KeyAuthorization.serialize(signed)),
+    ).toEqual(signed)
+  })
+
+  test('rejects a keychain signature', () => {
     const authorization = KeyAuthorization.from({
       address,
       chainId: 1n,
@@ -432,43 +465,55 @@ describe('from', () => {
 
     expect(() =>
       KeyAuthorization.from(authorization, {
-        signature: signature_multisig as never,
+        signature: signature_keychain as never,
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[KeyAuthorization.InvalidSignatureTypeError: Signature type \`multisig\` is invalid for key authorizations; expected \`secp256k1\`, \`p256\`, or \`webAuthn\`.]`,
+      `[KeyAuthorization.InvalidSignatureTypeError: Signature type \`keychain\` is invalid for key authorizations; expected \`secp256k1\`, \`p256\`, \`webAuthn\`, or \`multisig\`.]`,
     )
 
     expect(() =>
       KeyAuthorization.from(authorization, {
-        signature: SignatureEnvelope.serialize(signature_multisig),
+        signature: SignatureEnvelope.serialize(signature_keychain),
       }),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[KeyAuthorization.InvalidSignatureTypeError: Signature type \`multisig\` is invalid for key authorizations; expected \`secp256k1\`, \`p256\`, or \`webAuthn\`.]`,
+      `[KeyAuthorization.InvalidSignatureTypeError: Signature type \`keychain\` is invalid for key authorizations; expected \`secp256k1\`, \`p256\`, \`webAuthn\`, or \`multisig\`.]`,
     )
 
     expect(() =>
       KeyAuthorization.from({
         ...authorization,
-        signature: signature_multisig,
+        signature: signature_keychain,
       } as never),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[KeyAuthorization.InvalidSignatureTypeError: Signature type \`multisig\` is invalid for key authorizations; expected \`secp256k1\`, \`p256\`, or \`webAuthn\`.]`,
+      `[KeyAuthorization.InvalidSignatureTypeError: Signature type \`keychain\` is invalid for key authorizations; expected \`secp256k1\`, \`p256\`, \`webAuthn\`, or \`multisig\`.]`,
     )
   })
 })
 
 describe('fromRpc', () => {
-  test('rejects a multisig signature', () => {
+  test('multisig', () => {
+    const authorization = KeyAuthorization.fromRpc({
+      chainId: '0x1',
+      expiry: null,
+      keyId: address,
+      keyType: 'secp256k1',
+      signature: SignatureEnvelope.toRpc(signature_multisig),
+    })
+
+    expect(authorization.signature).toEqual(signature_multisig)
+  })
+
+  test('rejects a keychain signature', () => {
     expect(() =>
       KeyAuthorization.fromRpc({
         chainId: '0x1',
         expiry: null,
         keyId: address,
         keyType: 'secp256k1',
-        signature: SignatureEnvelope.toRpc(signature_multisig),
+        signature: SignatureEnvelope.toRpc(signature_keychain),
       } as never),
     ).toThrowErrorMatchingInlineSnapshot(
-      `[KeyAuthorization.InvalidSignatureTypeError: Signature type \`multisig\` is invalid for key authorizations; expected \`secp256k1\`, \`p256\`, or \`webAuthn\`.]`,
+      `[KeyAuthorization.InvalidSignatureTypeError: Signature type \`keychain\` is invalid for key authorizations; expected \`secp256k1\`, \`p256\`, \`webAuthn\`, or \`multisig\`.]`,
     )
   })
 
@@ -2401,12 +2446,12 @@ describe('admin keys (TIP-1049)', () => {
     expect(restored.account).toBeUndefined()
   })
 
-  test('fromTuple: drops orphan account without isAdmin', () => {
+  test('fromTuple: preserves a non-admin account binding', () => {
     const restored = KeyAuthorization.fromTuple([
       ['0x01', '0x', address, '0x', [], [], '0x', '0x', account],
     ])
-    expect(restored.isAdmin).toBeUndefined()
-    expect(restored.account).toBeUndefined()
+    expect(restored.isAdmin).toBe(false)
+    expect(restored.account).toBe(account)
   })
 
   test('fromTuple: extracts isAdmin + account together', () => {
@@ -2441,6 +2486,20 @@ describe('admin keys (TIP-1049)', () => {
     expect(restored.account).toBe(account)
   })
 
+  test('serialize/deserialize: roundtrip with non-admin account binding', () => {
+    const authorization = KeyAuthorization.from({
+      address,
+      account,
+      chainId: 1n,
+      isAdmin: false,
+      type: 'secp256k1',
+    })
+    const serialized = KeyAuthorization.serialize(authorization)
+    const restored = KeyAuthorization.deserialize(serialized)
+    expect(restored.isAdmin).toBe(false)
+    expect(restored.account).toBe(account)
+  })
+
   test('toRpc/fromRpc: roundtrip with isAdmin + account', () => {
     const authorization = KeyAuthorization.from(
       {
@@ -2471,15 +2530,15 @@ describe('admin keys (TIP-1049)', () => {
     expect(restored.account).toBeUndefined()
   })
 
-  test('fromRpc: drops orphan account without isAdmin', () => {
+  test('fromRpc: preserves a non-admin account binding', () => {
     const authorization = KeyAuthorization.from(
       { address, chainId: 1n, type: 'secp256k1' },
       { signature: SignatureEnvelope.from(signature_secp256k1) },
     )
     const rpc = KeyAuthorization.toRpc(authorization)
     const restored = KeyAuthorization.fromRpc({ ...rpc, account })
-    expect(restored.isAdmin).toBeUndefined()
-    expect(restored.account).toBeUndefined()
+    expect(restored.isAdmin).toBe(false)
+    expect(restored.account).toBe(account)
   })
 
   test('hash: changes when admin pair is added', () => {