ox 1.1.2 → 1.3.0

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

@@ -1,4 +1,4 @@
-import { Bytes, Ed25519, Hex, X25519 } from 'ox'
+import { Bytes, Ed25519, Engine, Hex, X25519 } from 'ox'
 import { describe, expect, test } from 'vp/test'
 
 describe('createKeyPair', () => {
@@ -44,6 +44,108 @@ describe('createKeyPair', () => {
   })
 })
 
+describe('fromPrf', () => {
+  test.each([
+    {
+      privateKey:
+        '0x2c513679b40b7572cbfaf5aee41680258ab23de9ec68d6eaf243470c28e7cea3',
+      prf: '0x0000000000000000000000000000000000000000000000000000000000000000',
+    },
+    {
+      privateKey:
+        '0x7ad5cfcdff4bd56cf35bd854b794c9e18f9bcc3e6e12f9ecc0ef44bb23c6d920',
+      prf: '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f',
+    },
+  ] as const)('vector: $prf', ({ privateKey, prf }) => {
+    expect(Ed25519.fromPrf(prf)).toBe(privateKey)
+  })
+
+  test('value: Bytes', () => {
+    const prf = Bytes.fromHex(
+      '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f',
+    )
+    expect(Ed25519.fromPrf(prf)).toMatchInlineSnapshot(
+      `"0x7ad5cfcdff4bd56cf35bd854b794c9e18f9bcc3e6e12f9ecc0ef44bb23c6d920"`,
+    )
+  })
+
+  test('options: as', () => {
+    const privateKey = Ed25519.fromPrf(
+      '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f',
+      { as: 'Bytes' },
+    )
+    expect(privateKey).toEqual(
+      Bytes.fromHex(
+        '0x7ad5cfcdff4bd56cf35bd854b794c9e18f9bcc3e6e12f9ecc0ef44bb23c6d920',
+      ),
+    )
+  })
+
+  test('behavior: output signs and verifies', () => {
+    const privateKey = Ed25519.fromPrf(Bytes.random(32))
+    const publicKey = Ed25519.getPublicKey({ privateKey })
+    const payload = '0xdeadbeef'
+    const signature = Ed25519.sign({ payload, privateKey })
+
+    expect(Ed25519.verify({ payload, publicKey, signature })).toBe(true)
+  })
+
+  test('behavior: uses versioned label and zero counter', () => {
+    const messages: Hex.Hex[] = []
+    Engine.with(
+      {
+        Hash: {
+          hmacSha256: (_key, message) => {
+            messages.push(Hex.fromBytes(message))
+            return new Uint8Array(32)
+          },
+        },
+      },
+      () =>
+        Ed25519.fromPrf(
+          '0x0000000000000000000000000000000000000000000000000000000000000000',
+        ),
+    )
+
+    expect(messages).toMatchInlineSnapshot(`
+      [
+        "0x6f782e656432353531392e66726f6d5072662e763100000000",
+      ]
+    `)
+  })
+
+  test('behavior: zeroes intermediate key for Hex output', () => {
+    const candidate = new Uint8Array(32).fill(1)
+    Engine.with(
+      {
+        Hash: {
+          hmacSha256: () => candidate,
+        },
+      },
+      () =>
+        Ed25519.fromPrf(
+          '0x0000000000000000000000000000000000000000000000000000000000000000',
+        ),
+    )
+
+    expect(candidate).toEqual(new Uint8Array(32))
+  })
+
+  test('error: PRF output is too short', () => {
+    expect(() => Ed25519.fromPrf(new Uint8Array(31)))
+      .toThrowErrorMatchingInlineSnapshot(`
+        [Ed25519.InvalidPrfSizeError: PRF output must be exactly 32 bytes. Received 31 bytes.]
+      `)
+  })
+
+  test('error: PRF output is too long', () => {
+    expect(() => Ed25519.fromPrf(new Uint8Array(33)))
+      .toThrowErrorMatchingInlineSnapshot(`
+        [Ed25519.InvalidPrfSizeError: PRF output must be exactly 32 bytes. Received 33 bytes.]
+      `)
+  })
+})
+
 describe('getPublicKey', () => {
   const privateKey =
     '0x9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60'
@@ -436,3 +538,20 @@ describe('noble export', () => {
     expect(Ed25519.noble.getPublicKey).toBeDefined()
   })
 })
+
+test('exports', () => {
+  expect(Object.keys(Ed25519)).toMatchInlineSnapshot(`
+    [
+      "noble",
+      "createKeyPair",
+      "fromPrf",
+      "getPublicKey",
+      "randomPrivateKey",
+      "sign",
+      "verify",
+      "toX25519PublicKey",
+      "toX25519PrivateKey",
+      "InvalidPrfSizeError",
+    ]
+  `)
+})

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

@@ -136,5 +136,14 @@ describe('Engine', () => {
     expectTypeOf<NonNullable<Engine.Hash['keccak256']>>().toEqualTypeOf<
       (input: Uint8Array) => Uint8Array
     >()
+    expectTypeOf<NonNullable<Engine.Hash['createKeccak256']>>().toEqualTypeOf<
+      () => Engine.HashState
+    >()
+    expectTypeOf<Engine.HashState>().toEqualTypeOf<{
+      clone(): Engine.HashState
+      destroy(): void
+      digestInto(output: Uint8Array): void
+      update(input: Uint8Array): void
+    }>()
   })
 })

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

@@ -266,7 +266,7 @@ describe('set', () => {
     ).toThrowErrorMatchingInlineSnapshot(`
       [Engine.UnknownPrimitiveError: \`keccak_256\` is not a valid primitive for the \`Hash\` slot.
 
-      Valid primitives: blake3, hmacSha256, keccak256, ripemd160, sha256]
+      Valid primitives: blake3, createBlake3, createHmacSha256, createKeccak256, createRipemd160, createSha256, hmacSha256, keccak256, ripemd160, sha256]
     `)
   })
 

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

@@ -0,0 +1,41 @@
+import { type Bytes, Hash, type Hex } from 'ox'
+import { describe, expectTypeOf, test } from 'vp/test'
+
+describe('blake3', () => {
+  test('default', () => {
+    expectTypeOf(Hash.blake3('0x')).toEqualTypeOf<Hex.Hex>()
+    expectTypeOf(Hash.blake3(new Uint8Array())).toEqualTypeOf<Bytes.Bytes>()
+  })
+
+  test('as', () => {
+    expectTypeOf(
+      Hash.blake3('0x', { as: 'Bytes' }),
+    ).toEqualTypeOf<Bytes.Bytes>()
+    expectTypeOf(
+      Hash.blake3(new Uint8Array(), { as: 'Hex' }),
+    ).toEqualTypeOf<Hex.Hex>()
+  })
+})
+
+describe('incremental', () => {
+  test('factories', () => {
+    expectTypeOf(Hash.createBlake3()).toEqualTypeOf<Hash.Hasher>()
+    expectTypeOf(Hash.createHmac256('0x')).toEqualTypeOf<Hash.Hasher>()
+    expectTypeOf(Hash.createKeccak256()).toEqualTypeOf<Hash.Hasher>()
+    expectTypeOf(Hash.createRipemd160()).toEqualTypeOf<Hash.Hasher>()
+    expectTypeOf(Hash.createSha256()).toEqualTypeOf<Hash.Hasher>()
+  })
+
+  test('Hasher', () => {
+    const hash = Hash.createSha256()
+
+    expectTypeOf(hash.update('0x')).toEqualTypeOf<Hash.Hasher>()
+    expectTypeOf(hash.update(new Uint8Array())).toEqualTypeOf<Hash.Hasher>()
+    expectTypeOf(hash.clone()).toEqualTypeOf<Hash.Hasher>()
+    expectTypeOf(hash.digest()).toEqualTypeOf<Hex.Hex>()
+    expectTypeOf(hash.digest({ as: 'Hex' })).toEqualTypeOf<Hex.Hex>()
+    expectTypeOf(hash.digest({ as: 'Bytes' })).toEqualTypeOf<Bytes.Bytes>()
+    expectTypeOf(hash.digestInto(new Uint8Array())).toEqualTypeOf<void>()
+    expectTypeOf(hash.destroy()).toEqualTypeOf<void>()
+  })
+})

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

@@ -1,6 +1,249 @@
-import { Hash } from 'ox'
+import { type Bytes, Engine, Hash, type Hex } from 'ox'
 import { describe, expect, test } from 'vp/test'
 
+type Factory = {
+  create(): Hash.Hasher
+  digest(value: Hex.Hex | Bytes.Bytes): Bytes.Bytes
+  digestSize: number
+  name: string
+}
+
+const factories = [
+  {
+    create: () => Hash.createBlake3(),
+    digest: (value) => Hash.blake3(value, { as: 'Bytes' }),
+    digestSize: 32,
+    name: 'createBlake3',
+  },
+  {
+    create: () => Hash.createHmac256('0x6b6579'),
+    digest: (value) => Hash.hmac256('0x6b6579', value, { as: 'Bytes' }),
+    digestSize: 32,
+    name: 'createHmac256',
+  },
+  {
+    create: () => Hash.createKeccak256(),
+    digest: (value) => Hash.keccak256(value, { as: 'Bytes' }),
+    digestSize: 32,
+    name: 'createKeccak256',
+  },
+  {
+    create: () => Hash.createRipemd160(),
+    digest: (value) => Hash.ripemd160(value, { as: 'Bytes' }),
+    digestSize: 20,
+    name: 'createRipemd160',
+  },
+  {
+    create: () => Hash.createSha256(),
+    digest: (value) => Hash.sha256(value, { as: 'Bytes' }),
+    digestSize: 32,
+    name: 'createSha256',
+  },
+] as const satisfies readonly Factory[]
+
+describe('incremental', () => {
+  test.each(factories)(
+    '$name: chunked input matches the one-shot function',
+    ({ create, digest }) => {
+      const hash = create()
+      hash.update('0xdead').update(Uint8Array.of(0xbe, 0xef))
+      expect(hash.digest({ as: 'Bytes' })).toEqual(digest('0xdeadbeef'))
+    },
+  )
+
+  test.each(factories)(
+    '$name: empty input matches the one-shot function',
+    ({ create, digest }) => {
+      expect(create().digest({ as: 'Bytes' })).toEqual(digest('0x'))
+    },
+  )
+
+  test.each(factories)(
+    '$name: clone branches from the same prefix',
+    ({ create, digest }) => {
+      const first = create().update('0xdead')
+      const second = first.clone()
+
+      first.update('0xbeef')
+      second.update('0xcafe')
+
+      expect(first.digest({ as: 'Bytes' })).toEqual(digest('0xdeadbeef'))
+      expect(second.digest({ as: 'Bytes' })).toEqual(digest('0xdeadcafe'))
+    },
+  )
+
+  test.each(factories)(
+    '$name: digestInto validates bounds without consuming the state',
+    ({ create, digest, digestSize }) => {
+      const hash = create().update('0xdeadbeef')
+
+      expect(() =>
+        hash.digestInto(new Uint8Array(digestSize - 1)),
+      ).toThrowError(Hash.InvalidDigestSizeError)
+
+      const output = new Uint8Array(digestSize + 2).fill(0xff)
+      hash.digestInto(output)
+
+      expect(output.slice(0, digestSize)).toEqual(digest('0xdeadbeef'))
+      expect(output.slice(digestSize)).toEqual(Uint8Array.of(0xff, 0xff))
+      expect(() => hash.update('0x')).toThrowError(Hash.HasherDestroyedError)
+    },
+  )
+
+  test.each(factories)(
+    '$name: digest consumes the state and destroy is idempotent',
+    ({ create }) => {
+      const hash = create()
+      hash.digest()
+
+      expect(() => hash.clone()).toThrowError(Hash.HasherDestroyedError)
+      expect(() => hash.digest()).toThrowError(Hash.HasherDestroyedError)
+      expect(() => hash.digestInto(new Uint8Array(32))).toThrowError(
+        Hash.HasherDestroyedError,
+      )
+      expect(() => hash.update('0x')).toThrowError(Hash.HasherDestroyedError)
+      expect(() => {
+        hash.destroy()
+        hash.destroy()
+      }).not.toThrow()
+    },
+  )
+
+  test.each(factories)(
+    '$name: destroy consumes the state and is idempotent',
+    ({ create }) => {
+      const hash = create()
+      hash.destroy()
+      hash.destroy()
+
+      expect(() => hash.clone()).toThrowError(Hash.HasherDestroyedError)
+      expect(() => hash.digest()).toThrowError(Hash.HasherDestroyedError)
+      expect(() => hash.update('0x')).toThrowError(Hash.HasherDestroyedError)
+    },
+  )
+
+  test('behavior: independent states can be interleaved', () => {
+    const first = Hash.createSha256().update('0xaa')
+    const second = Hash.createSha256().update('0xbb')
+
+    first.update('0xcc')
+    second.update('0xdd')
+
+    expect(first.digest()).toEqual(Hash.sha256('0xaacc'))
+    expect(second.digest()).toEqual(Hash.sha256('0xbbdd'))
+  })
+
+  test('behavior: a state keeps the provider captured at creation', () => {
+    Engine.set({ Hash: { createSha256: () => sentinelState(1) } })
+    const first = Hash.createSha256()
+
+    Engine.set({ Hash: { createSha256: () => sentinelState(2) } })
+
+    expect(first.digest({ as: 'Bytes' })[0]).toMatchInlineSnapshot('1')
+    expect(
+      Hash.createSha256().digest({ as: 'Bytes' })[0],
+    ).toMatchInlineSnapshot('2')
+  })
+})
+
+describe('blake3', () => {
+  test('default', () => {
+    expect(Hash.blake3('0x')).toMatchInlineSnapshot(
+      `"0xaf1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262"`,
+    )
+
+    expect(Hash.blake3(new Uint8Array())).toMatchInlineSnapshot(`
+      Uint8Array [
+        175,
+        19,
+        73,
+        185,
+        245,
+        249,
+        161,
+        166,
+        160,
+        64,
+        77,
+        234,
+        54,
+        220,
+        201,
+        73,
+        155,
+        203,
+        37,
+        201,
+        173,
+        193,
+        18,
+        183,
+        204,
+        154,
+        147,
+        202,
+        228,
+        31,
+        50,
+        98,
+      ]
+    `)
+  })
+
+  test('as: Hex', () => {
+    expect(Hash.blake3(new Uint8Array(), { as: 'Hex' })).toMatchInlineSnapshot(
+      `"0xaf1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262"`,
+    )
+  })
+
+  test('as: Bytes', () => {
+    expect(Hash.blake3('0x', { as: 'Bytes' })).toMatchInlineSnapshot(`
+      Uint8Array [
+        175,
+        19,
+        73,
+        185,
+        245,
+        249,
+        161,
+        166,
+        160,
+        64,
+        77,
+        234,
+        54,
+        220,
+        201,
+        73,
+        155,
+        203,
+        37,
+        201,
+        173,
+        193,
+        18,
+        183,
+        204,
+        154,
+        147,
+        202,
+        228,
+        31,
+        50,
+        98,
+      ]
+    `)
+  })
+
+  test('behavior: routes through the installed engine', () => {
+    Engine.set({ Hash: { blake3: () => new Uint8Array(32).fill(1) } })
+
+    expect(Hash.blake3('0x')).toMatchInlineSnapshot(
+      `"0x0101010101010101010101010101010101010101010101010101010101010101"`,
+    )
+  })
+})
+
 describe('hmac256', () => {
   test('default', () => {
     expect(
@@ -527,14 +770,48 @@ describe('validate', () => {
   })
 })
 
+function sentinelState(byte: number): Engine.HashState {
+  let active = true
+
+  const assertActive = () => {
+    if (!active) throw new Error('destroyed')
+  }
+
+  return {
+    clone: () => {
+      assertActive()
+      return sentinelState(byte)
+    },
+    destroy: () => {
+      active = false
+    },
+    digestInto: (output) => {
+      assertActive()
+      active = false
+      output.fill(byte, 0, 32)
+    },
+    update: () => {
+      assertActive()
+    },
+  }
+}
+
 test('exports', () => {
   expect(Object.keys(Hash)).toMatchInlineSnapshot(`
     [
+      "createBlake3",
+      "createHmac256",
+      "createKeccak256",
+      "createRipemd160",
+      "createSha256",
+      "blake3",
       "keccak256",
       "hmac256",
       "ripemd160",
       "sha256",
       "validate",
+      "HasherDestroyedError",
+      "InvalidDigestSizeError",
     ]
   `)
 })

package/src/core/_test/Hash.vectors.test.ts

@@ -1,7 +1,6 @@
 import { Hash } from 'ox'
 import { describe, expect, test } from 'vp/test'
 import * as vectors from '../../../test/vectors/hashes/index.js'
-import * as hash from '../internal/hash.js'
 
 /**
  * Published vectors against ox's default (`@noble/hashes`) implementations.
@@ -15,7 +14,7 @@ import * as hash from '../internal/hash.js'
 describe('blake3', () => {
   test(`matches ${vectors.blake3.length} official BLAKE3 vectors`, () => {
     for (const { digest, message } of vectors.blake3)
-      expect(hash.blake3(message)).toEqual(digest)
+      expect(Hash.blake3(message, { as: 'Bytes' })).toEqual(digest)
   })
 })
 

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

@@ -30,6 +30,8 @@ describe('assert', () => {
 
 describe('concat', () => {
   test('default', () => {
+    expect(Hex.concat()).toMatchInlineSnapshot(`"0x"`)
+    expect(Hex.concat('0x1234')).toMatchInlineSnapshot(`"0x1234"`)
     expect(Hex.concat('0x0', '0x1')).toBe('0x01')
     expect(Hex.concat('0x1', '0x69', '0x420')).toBe('0x169420')
     expect(Hex.concat('0x00000001', '0x00000069', '0x00000420')).toBe(

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

@@ -2,6 +2,24 @@ import { Bytes, type Hex, Rlp } from 'ox'
 import { describe, expectTypeOf, test } from 'vp/test'
 import type { RecursiveArray } from '../internal/types.js'
 
+describe('Rlp.encodeTo', () => {
+  test('write', () => {
+    expectTypeOf(
+      Rlp.encodeTo('0x', (value) => {
+        expectTypeOf(value).toEqualTypeOf<Bytes.Bytes>()
+      }),
+    ).toEqualTypeOf<void>()
+  })
+
+  test('rejects asynchronous callbacks', () => {
+    Rlp.encodeTo(
+      '0x',
+      // @ts-expect-error RLP write callbacks are synchronous.
+      async () => {},
+    )
+  })
+})
+
 describe('Rlp.to', () => {
   test('default', () => {
     expectTypeOf(Rlp.toHex('0x')).toEqualTypeOf<RecursiveArray<Hex.Hex>>()

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

@@ -10,6 +10,7 @@ test('exports', () => {
       "decodeRlpCursor",
       "readLength",
       "readList",
+      "encodeTo",
       "from",
       "fromBytes",
       "fromHex",
@@ -32,6 +33,114 @@ const generateList = (length: number) => {
   return bytes
 }
 
+function encodeToBytes(value: Parameters<typeof Rlp.encodeTo>[0]) {
+  const chunks: Uint8Array[] = []
+  Rlp.encodeTo(value, (chunk) => {
+    chunks.push(chunk)
+  })
+  return Bytes.concat(...chunks)
+}
+
+describe('Rlp.encodeTo', () => {
+  test('matches `from` for nested Hex values', () => {
+    const values = [
+      '0x',
+      '0x00',
+      '0x7f',
+      '0x80',
+      '0x1',
+      '0xabc',
+      ['0x', '0x80', ['0x1', `0x${'ab'.repeat(56)}`], `0x${'cd'.repeat(256)}`],
+    ] as const
+
+    for (const value of values)
+      expect(encodeToBytes(value)).toEqual(Rlp.from(value, { as: 'Bytes' }))
+  })
+
+  test('matches `from` for nested byte values', () => {
+    const values = [
+      new Uint8Array(),
+      Uint8Array.of(0),
+      Uint8Array.of(0x7f),
+      Uint8Array.of(0x80),
+      [
+        new Uint8Array(),
+        Uint8Array.of(0x80),
+        [generateBytes(56), generateBytes(256)],
+      ],
+    ] as const
+
+    for (const value of values)
+      expect(encodeToBytes(value)).toEqual(Rlp.from(value, { as: 'Bytes' }))
+  })
+
+  test('does not mutate emitted chunks', () => {
+    const chunks: Uint8Array[] = []
+    const values: Hex.Hex[] = []
+
+    Rlp.encodeTo(['0x01', `0x${'ab'.repeat(16_386)}`, '0x80'], (chunk) => {
+      chunks.push(chunk)
+      values.push(Hex.fromBytes(chunk))
+    })
+
+    expect(chunks.map((chunk) => Hex.fromBytes(chunk))).toEqual(values)
+  })
+
+  test('passes byte leaves without copying', () => {
+    const leaf = generateBytes(64)
+    let found = false
+
+    Rlp.encodeTo(leaf, (chunk) => {
+      if (chunk === leaf) found = true
+    })
+
+    expect(found).toMatchInlineSnapshot(`true`)
+  })
+
+  test('validates every Hex leaf before writing', () => {
+    let writes = 0
+
+    expect(() =>
+      Rlp.encodeTo(['0x01', ['0x02', '0xzz' as Hex.Hex]], () => {
+        writes++
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[BaseError: Invalid hex string \`0xzz\`.]`,
+    )
+    expect(writes).toMatchInlineSnapshot(`0`)
+  })
+
+  test('propagates callback errors after partial output', () => {
+    const chunks: Uint8Array[] = []
+
+    expect(() =>
+      Rlp.encodeTo([Uint8Array.of(1), Uint8Array.of(2)], (chunk) => {
+        chunks.push(chunk)
+        if (chunks.length === 2) throw new Error('write failed')
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(`[Error: write failed]`)
+    expect(chunks.map((chunk) => Hex.fromBytes(chunk))).toMatchInlineSnapshot(`
+      [
+        "0xc2",
+        "0x01",
+      ]
+    `)
+  })
+
+  test('snapshots list structure before writing', () => {
+    const value: Hex.Hex[] = ['0x01']
+    const expected = Rlp.from(value, { as: 'Bytes' })
+    const chunks: Uint8Array[] = []
+
+    Rlp.encodeTo(value, (chunk) => {
+      chunks.push(chunk)
+      if (chunks.length === 1) value.push('0x02')
+    })
+
+    expect(Bytes.concat(...chunks)).toEqual(expected)
+  })
+})
+
 describe('Rlp.to', () => {
   test('no bytes', () => {
     const rlpHex = '0x'

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

@@ -0,0 +1,14 @@
+import { type Bytes, type Hex, Secp256k1 } from 'ox'
+import { expectTypeOf, test } from 'vp/test'
+
+test('fromPrf', () => {
+  const prf =
+    '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+
+  expectTypeOf(Secp256k1.fromPrf(prf)).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(Secp256k1.fromPrf(new Uint8Array(32))).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(Secp256k1.fromPrf(prf, { as: 'Hex' })).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    Secp256k1.fromPrf(prf, { as: 'Bytes' }),
+  ).toEqualTypeOf<Bytes.Bytes>()
+})