ox 1.1.0 → 1.1.2

package/src/wasm/_test/Hash.fuzz.ts

@@ -1,4 +1,5 @@
 import { fc, test } from '@fast-check/vitest'
+import { blake3 } from '@noble/hashes/blake3.js'
 import { hmac } from '@noble/hashes/hmac.js'
 import { ripemd160 } from '@noble/hashes/legacy.js'
 import { sha256 } from '@noble/hashes/sha2.js'
@@ -7,10 +8,10 @@ import { Hash as WasmHash } from 'ox/wasm'
 import { beforeAll, describe, expect } from 'vp/test'
 import { numRuns } from '../../../test/fuzz/numRuns.js'
 
-let engine: WasmHash.create.ReturnType
+let engine: WasmHash.engine.ReturnType
 
 beforeAll(async () => {
-  engine = await WasmHash.create()
+  engine = await WasmHash.engine()
 })
 
 /**
@@ -21,14 +22,33 @@ beforeAll(async () => {
  *
  * The distribution is weighted toward the sizes where padding and block-boundary
  * bugs hide -- empty input, exact multiples of the keccak256 rate (136) and the
- * SHA-2 block (64), and the 56-byte threshold at which the length counter no
- * longer fits in the final block.
+ * SHA-2 block (64), BLAKE3 chunk (1024), and the 56-byte threshold at which
+ * the SHA-2 length counter no longer fits in the final block.
  */
 const arbitraryInput = fc.oneof(
   { arbitrary: fc.uint8Array({ maxLength: 300, minLength: 0 }), weight: 6 },
   {
     arbitrary: fc
-      .constantFrom(0, 1, 55, 56, 63, 64, 65, 111, 112, 135, 136, 137, 272)
+      .constantFrom(
+        0,
+        1,
+        55,
+        56,
+        63,
+        64,
+        65,
+        111,
+        112,
+        135,
+        136,
+        137,
+        272,
+        1023,
+        1024,
+        1025,
+        2048,
+        2049,
+      )
       .chain((size) => fc.uint8Array({ maxLength: size, minLength: size })),
     weight: 3,
   },
@@ -54,55 +74,63 @@ const arbitraryKey = fc.oneof(
 )
 
 const primitives = {
+  blake3: {
+    reference: (input: Uint8Array) => blake3(input),
+    wasm: (input: Uint8Array) => engine.blake3(input),
+  },
   hmacSha256: {
     reference: (input: Uint8Array, key: Uint8Array) => hmac(sha256, key, input),
-    wasm: (input: Uint8Array, key: Uint8Array) =>
-      engine.Hash.hmacSha256(key, input),
+    wasm: (input: Uint8Array, key: Uint8Array) => engine.hmacSha256(key, input),
   },
   keccak256: {
     reference: (input: Uint8Array) => keccak_256(input),
-    wasm: (input: Uint8Array) => engine.Hash.keccak256(input),
+    wasm: (input: Uint8Array) => engine.keccak256(input),
   },
   ripemd160: {
     reference: (input: Uint8Array) => ripemd160(input),
-    wasm: (input: Uint8Array) => engine.Hash.ripemd160(input),
+    wasm: (input: Uint8Array) => engine.ripemd160(input),
   },
   sha256: {
     reference: (input: Uint8Array) => sha256(input),
-    wasm: (input: Uint8Array) => engine.Hash.sha256(input),
+    wasm: (input: Uint8Array) => engine.sha256(input),
   },
 } as const
 
 type Name = keyof typeof primitives
 
 describe('Hash', () => {
+  test.prop({ input: arbitraryInput }, { numRuns })(
+    'blake3 ≡ @noble/hashes',
+    ({ input }) => {
+      expect(engine.blake3(input)).toEqual(blake3(input))
+    },
+  )
+
   test.prop({ input: arbitraryInput }, { numRuns })(
     'keccak256 ≡ @noble/hashes',
     ({ input }) => {
-      expect(engine.Hash.keccak256(input)).toEqual(keccak_256(input))
+      expect(engine.keccak256(input)).toEqual(keccak_256(input))
     },
   )
 
   test.prop({ input: arbitraryInput }, { numRuns })(
     'sha256 ≡ @noble/hashes',
     ({ input }) => {
-      expect(engine.Hash.sha256(input)).toEqual(sha256(input))
+      expect(engine.sha256(input)).toEqual(sha256(input))
     },
   )
 
   test.prop({ input: arbitraryInput }, { numRuns })(
     'ripemd160 ≡ @noble/hashes',
     ({ input }) => {
-      expect(engine.Hash.ripemd160(input)).toEqual(ripemd160(input))
+      expect(engine.ripemd160(input)).toEqual(ripemd160(input))
     },
   )
 
   test.prop({ input: arbitraryInput, key: arbitraryKey }, { numRuns })(
     'hmacSha256 ≡ @noble/hashes',
     ({ input, key }) => {
-      expect(engine.Hash.hmacSha256(key, input)).toEqual(
-        hmac(sha256, key, input),
-      )
+      expect(engine.hmacSha256(key, input)).toEqual(hmac(sha256, key, input))
     },
   )
 })
@@ -115,6 +143,7 @@ describe('memory', () => {
           input: arbitraryInput,
           key: arbitraryKey,
           name: fc.constantFrom<Name>(
+            'blake3',
             'hmacSha256',
             'keccak256',
             'ripemd160',
@@ -156,7 +185,7 @@ describe('memory', () => {
     // as zeroes rather than throwing.
     for (const pages of sizes) {
       const input = new Uint8Array(pages * 65_536).fill(pages & 0xff)
-      expect(engine.Hash.keccak256(input), `${pages} pages`).toEqual(
+      expect(engine.keccak256(input), `${pages} pages`).toEqual(
         keccak_256(input),
       )
     }
@@ -167,10 +196,15 @@ describe('memory', () => {
     ({ input }) => {
       // A digest returned as a view over linear memory would be silently
       // rewritten by the next call. Hold one across a larger call and check it.
-      const digest = engine.Hash.keccak256(input)
+      const digest = engine.keccak256(input)
       const snapshot = digest.slice()
-      engine.Hash.keccak256(new Uint8Array(input.length + 1024).fill(0xaa))
+      engine.keccak256(new Uint8Array(input.length + 1024).fill(0xaa))
       expect(digest).toEqual(snapshot)
+
+      const blake3Digest = engine.blake3(input)
+      const blake3Snapshot = blake3Digest.slice()
+      engine.blake3(new Uint8Array(input.length + 1024).fill(0xaa))
+      expect(blake3Digest).toEqual(blake3Snapshot)
     },
   )
 
@@ -178,10 +212,11 @@ describe('memory', () => {
     'inputs are not mutated',
     ({ input }) => {
       const snapshot = input.slice()
-      engine.Hash.keccak256(input)
-      engine.Hash.sha256(input)
-      engine.Hash.ripemd160(input)
-      engine.Hash.hmacSha256(input, input)
+      engine.blake3(input)
+      engine.keccak256(input)
+      engine.sha256(input)
+      engine.ripemd160(input)
+      engine.hmacSha256(input, input)
       expect(input).toEqual(snapshot)
     },
   )

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

@@ -1,28 +1,33 @@
-import type { Engine } from 'ox'
 import { Hash as WasmHash } from 'ox/wasm'
 import { expectTypeOf, test } from 'vp/test'
+import type * as CoreEngine from '../../core/Engine.js'
+import * as CoreHash from '../../core/Hash.js'
 
-type Created = Awaited<ReturnType<typeof WasmHash.create>>
+type Slot = Awaited<ReturnType<typeof WasmHash.engine>>
 
 test('every primitive is present, so callers need no assertion', () => {
-  expectTypeOf<Created['Hash']['keccak256']>().toEqualTypeOf<
+  expectTypeOf<Slot['blake3']>().toEqualTypeOf<
     (input: Uint8Array) => Uint8Array
   >()
-  expectTypeOf<Created['Hash']['sha256']>().toEqualTypeOf<
+  expectTypeOf<Slot['keccak256']>().toEqualTypeOf<
     (input: Uint8Array) => Uint8Array
   >()
-  expectTypeOf<Created['Hash']['ripemd160']>().toEqualTypeOf<
+  expectTypeOf<Slot['sha256']>().toEqualTypeOf<
     (input: Uint8Array) => Uint8Array
   >()
-  expectTypeOf<Created['Hash']['hmacSha256']>().toEqualTypeOf<
+  expectTypeOf<Slot['ripemd160']>().toEqualTypeOf<
+    (input: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Slot['hmacSha256']>().toEqualTypeOf<
     (key: Uint8Array, message: Uint8Array) => Uint8Array
   >()
 })
 
-test('blake3 is absent, because the WASM module does not implement it', () => {
-  expectTypeOf<Created['Hash']>().not.toHaveProperty('blake3')
+test('the result is the raw slot, so `Engine.install` accepts it', () => {
+  expectTypeOf<{ Hash: Slot }>().toExtend<CoreEngine.Engine>()
 })
 
-test('the result is still an engine, so `Engine.set` accepts it', () => {
-  expectTypeOf<Created>().toExtend<Engine.Engine>()
+test('the WASM namespace exposes the public Hash API', () => {
+  expectTypeOf(WasmHash.sha256).toEqualTypeOf(CoreHash.sha256)
+  expectTypeOf<typeof WasmHash>().not.toHaveProperty('create')
 })

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

@@ -1,3 +1,4 @@
+import { blake3 } from '@noble/hashes/blake3.js'
 import { hmac } from '@noble/hashes/hmac.js'
 import { ripemd160 } from '@noble/hashes/legacy.js'
 import { sha256 } from '@noble/hashes/sha2.js'
@@ -5,25 +6,23 @@ import { keccak_256 } from '@noble/hashes/sha3.js'
 import { Bytes, Engine, Hash } from 'ox'
 import { Hash as WasmHash } from 'ox/wasm'
 import { beforeAll, describe, expect, test } from 'vp/test'
+import { wasmBase64 as blake3WasmBase64 } from '../internal/blake3.wasm.js'
+import * as blake3_internal from '../internal/blake3.js'
 import { hmacSha256ScratchSize, wasmBase64 } from '../internal/hashes.wasm.js'
 import * as hash from '../internal/hash.js'
 import * as internal from '../internal/instantiate.js'
 
-let engine: WasmHash.create.ReturnType
+let engine: WasmHash.engine.ReturnType
 
 beforeAll(async () => {
-  engine = await WasmHash.create()
+  engine = await WasmHash.engine()
 })
 
-describe('create', () => {
+describe('engine', () => {
   test('default', async () => {
-    expect(Object.keys(await WasmHash.create())).toMatchInlineSnapshot(`
-      [
-        "Hash",
-      ]
-    `)
-    expect(Object.keys((await WasmHash.create()).Hash)).toMatchInlineSnapshot(`
+    expect(Object.keys(await WasmHash.engine())).toMatchInlineSnapshot(`
       [
+        "blake3",
         "hmacSha256",
         "keccak256",
         "ripemd160",
@@ -33,28 +32,26 @@ describe('create', () => {
   })
 
   test('behavior: hands every caller its own engine', async () => {
-    const [a, b] = await Promise.all([WasmHash.create(), WasmHash.create()])
+    const [a, b] = await Promise.all([WasmHash.engine(), WasmHash.engine()])
 
-    // Deliberately not the same object. A shared slot lets one caller's
-    // customisation for composition leak into what a later `create` -- or
-    // `Engine.load` -- installs.
+    // Deliberately not the same object. Sharing the slot object would let one
+    // caller's customisation leak into a later `engine` or `Engine.install`.
     expect(a).not.toBe(b)
-    expect(a.Hash).not.toBe(b.Hash)
 
-    a.Hash.keccak256 = () => new Uint8Array(32).fill(9)
-    const c = await WasmHash.create()
-    expect(c.Hash.keccak256(Bytes.from('0xdeadbeef'))).toEqual(
-      b.Hash.keccak256(Bytes.from('0xdeadbeef')),
+    a.keccak256 = () => new Uint8Array(32).fill(9)
+    const c = await WasmHash.engine()
+    expect(c.keccak256(Bytes.from('0xdeadbeef'))).toEqual(
+      b.keccak256(Bytes.from('0xdeadbeef')),
     )
   })
 })
 
 // Sizes chosen around the block boundaries where padding bugs live: keccak256's
 // rate is 136 bytes, sha256 and ripemd160 use 64-byte blocks and need a second
-// block once the remainder reaches 56.
+// block once the remainder reaches 56, and BLAKE3 uses 1024-byte chunks.
 const sizes = [
   0, 1, 2, 31, 32, 55, 56, 63, 64, 65, 71, 72, 111, 135, 136, 137, 199, 200,
-  271, 272, 1000,
+  271, 272, 1000, 1023, 1024, 1025, 2048, 2049,
 ]
 
 function input(size: number) {
@@ -62,16 +59,20 @@ function input(size: number) {
 }
 
 describe('Hash', () => {
+  test.each(sizes)('blake3 matches the default at %i bytes', (size) => {
+    expect(engine.blake3(input(size))).toEqual(blake3(input(size)))
+  })
+
   test.each(sizes)('keccak256 matches the default at %i bytes', (size) => {
-    expect(engine.Hash.keccak256(input(size))).toEqual(keccak_256(input(size)))
+    expect(engine.keccak256(input(size))).toEqual(keccak_256(input(size)))
   })
 
   test.each(sizes)('sha256 matches the default at %i bytes', (size) => {
-    expect(engine.Hash.sha256(input(size))).toEqual(sha256(input(size)))
+    expect(engine.sha256(input(size))).toEqual(sha256(input(size)))
   })
 
   test.each(sizes)('ripemd160 matches the default at %i bytes', (size) => {
-    expect(engine.Hash.ripemd160(input(size))).toEqual(ripemd160(input(size)))
+    expect(engine.ripemd160(input(size))).toEqual(ripemd160(input(size)))
   })
 
   test.each([0, 1, 32, 63, 64, 65, 200])(
@@ -79,33 +80,117 @@ describe('Hash', () => {
     (size) => {
       const key = new Uint8Array(size).fill(0xa5)
       const message = input(100)
-      expect(engine.Hash.hmacSha256(key, message)).toEqual(
+      expect(engine.hmacSha256(key, message)).toEqual(
         hmac(sha256, key, message),
       )
     },
   )
 
   test('behavior: known vectors', () => {
-    expect(Bytes.toHex(engine.Hash.keccak256(new Uint8Array(0)))).toBe(
+    expect(Bytes.toHex(engine.blake3(new Uint8Array(0)))).toBe(
+      '0xaf1349b9f5f9a1a6a0404dea36dcc9499bcb25c9adc112b7cc9a93cae41f3262',
+    )
+    expect(Bytes.toHex(engine.keccak256(new Uint8Array(0)))).toBe(
       '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470',
     )
-    expect(Bytes.toHex(engine.Hash.sha256(new Uint8Array(0)))).toBe(
+    expect(Bytes.toHex(engine.sha256(new Uint8Array(0)))).toBe(
       '0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
     )
-    expect(Bytes.toHex(engine.Hash.ripemd160(new Uint8Array(0)))).toBe(
+    expect(Bytes.toHex(engine.ripemd160(new Uint8Array(0)))).toBe(
       '0x9c1185a5c5e9fc54612808977ee8f548b2258d31',
     )
   })
 
   test('behavior: grows memory past 64 MiB, then still hashes small inputs', () => {
     // The input itself is exactly 64 MiB, so the heap base and digest force
-    // memory past that boundary. Growing detaches the previous `ArrayBuffer`; a
-    // retained view would silently read zero bytes in the assertion below.
+    // memory past that boundary. Growing detaches the previous `ArrayBuffer`;
+    // a retained view would silently read zero bytes in the assertion below.
     const large = new Uint8Array(64 * 1024 * 1024).fill(7)
-    expect(engine.Hash.sha256(large)).toEqual(sha256(large))
+    expect(engine.sha256(large)).toEqual(sha256(large))
+    expect(engine.blake3(large)).toEqual(blake3(large))
 
     const small = input(32)
-    expect(engine.Hash.sha256(small)).toEqual(sha256(small))
+    expect(engine.sha256(small)).toEqual(sha256(small))
+    expect(engine.blake3(small)).toEqual(blake3(small))
+  }, 60_000)
+
+  test('behavior: accepts Uint8Array subviews without mutation', () => {
+    const backing = input(1027)
+    const subview = backing.subarray(1, 1026)
+    const snapshot = backing.slice()
+    expect(engine.blake3(subview)).toEqual(blake3(subview))
+    expect(backing).toEqual(snapshot)
+  })
+
+  test('behavior: blake3 clears its complete memory region', async () => {
+    const module =
+      await internal.instantiate<blake3_internal.Exports>(blake3WasmBase64)
+    const message = input(1025)
+    const end = module.heapBase + message.length + 32
+
+    expect(blake3_internal.hash(module, message)).toEqual(blake3(message))
+    expect(module.view().slice(module.heapBase, end)).toEqual(
+      new Uint8Array(end - module.heapBase),
+    )
+  })
+
+  test('behavior: blake3 clears its complete region after a late trap', async () => {
+    const module =
+      await internal.instantiate<blake3_internal.Exports>(blake3WasmBase64)
+    const message = input(1025)
+    const end = module.heapBase + message.length + 32
+    const exports = {
+      blake3_hash(inputPtr: number, length: number, outPtr: number) {
+        module.exports.blake3_hash(inputPtr, length, outPtr)
+        throw new WebAssembly.RuntimeError('forced late trap')
+      },
+      zero: (ptr: number, length: number) => module.exports.zero(ptr, length),
+    }
+
+    expect(() =>
+      blake3_internal.hash({ ...module, exports }, message),
+    ).toThrowError('forced late trap')
+    expect(module.view().slice(module.heapBase, end)).toEqual(
+      new Uint8Array(end - module.heapBase),
+    )
+  })
+
+  test('behavior: rejects wasm32 pointer overflow before reserving', () => {
+    let reserved = false
+    const module: internal.Module<blake3_internal.Exports> = {
+      exports: {
+        blake3_hash() {},
+        zero() {},
+      },
+      heapBase: 0xffff_fff0,
+      reserve() {
+        reserved = true
+      },
+      view: () => new Uint8Array(0),
+    }
+
+    expect(() => blake3_internal.hash(module, input(1))).toThrow(
+      internal.MemoryError,
+    )
+    expect(reserved).toBe(false)
+  })
+
+  test('behavior: accepts a workspace ending exactly at the wasm32 boundary', () => {
+    const marker = new Error('reserve reached')
+    const module: internal.Module<blake3_internal.Exports> = {
+      exports: {
+        blake3_hash() {},
+        zero() {},
+      },
+      heapBase: 0x1_0000_0000 - 33,
+      reserve(bytes) {
+        expect(bytes).toBe(33)
+        throw marker
+      },
+      view: () => new Uint8Array(0),
+    }
+
+    expect(() => blake3_internal.hash(module, input(1))).toThrow(marker)
   })
 
   test('behavior: hmacSha256 clears its complete memory region', async () => {
@@ -182,30 +267,45 @@ describe('Hash', () => {
   test('behavior: consecutive calls do not corrupt each other', () => {
     const a = input(200)
     const b = input(7)
-    expect(engine.Hash.keccak256(a)).toEqual(keccak_256(a))
-    expect(engine.Hash.keccak256(b)).toEqual(keccak_256(b))
-    expect(engine.Hash.keccak256(a)).toEqual(keccak_256(a))
+    expect(engine.keccak256(a)).toEqual(keccak_256(a))
+    expect(engine.blake3(a)).toEqual(blake3(a))
+    expect(engine.blake3(b)).toEqual(blake3(b))
+    expect(engine.blake3(a)).toEqual(blake3(a))
+    expect(engine.keccak256(b)).toEqual(keccak_256(b))
+    expect(engine.keccak256(a)).toEqual(keccak_256(a))
   })
 
   test('behavior: results do not alias WASM memory', () => {
-    const first = engine.Hash.keccak256(input(32))
+    const first = engine.keccak256(input(32))
     const snapshot = first.slice()
-    engine.Hash.keccak256(input(64))
+    engine.keccak256(input(64))
     expect(first).toEqual(snapshot)
+
+    const blake3First = engine.blake3(input(32))
+    const blake3Snapshot = blake3First.slice()
+    engine.blake3(input(64))
+    expect(blake3First).toEqual(blake3Snapshot)
   })
 })
 
-describe('Engine.set', () => {
-  test('behavior: ox uses the WASM implementation once installed', () => {
-    Engine.set(engine)
-    expect(Hash.keccak256('0xdeadbeef')).toBe(
-      '0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1',
-    )
-    expect(Hash.sha256('0xdeadbeef')).toBe(
-      '0x5f78c33274e43fa9de5659265c1d917e25c03722dcb0b8d27db8d5feaa813953',
-    )
-    expect(Hash.ripemd160('0xdeadbeef')).toBe(
-      '0x226821c2f5423e11fe9af68bd285c249db2e4b5a',
-    )
+describe('Engine.install', () => {
+  test('behavior: ox uses the WASM implementation once installed', async () => {
+    await Engine.install({ Hash: engine })
+    try {
+      expect(Engine.get().Hash?.blake3?.(Bytes.from('0xdeadbeef'))).toEqual(
+        blake3(Bytes.from('0xdeadbeef')),
+      )
+      expect(Hash.keccak256('0xdeadbeef')).toBe(
+        '0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1',
+      )
+      expect(Hash.sha256('0xdeadbeef')).toBe(
+        '0x5f78c33274e43fa9de5659265c1d917e25c03722dcb0b8d27db8d5feaa813953',
+      )
+      expect(Hash.ripemd160('0xdeadbeef')).toBe(
+        '0x226821c2f5423e11fe9af68bd285c249db2e4b5a',
+      )
+    } finally {
+      Engine.reset()
+    }
   })
 })

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

@@ -13,16 +13,23 @@ import { instantiate } from '../internal/instantiate.js'
  * See `test/vectors/hashes/README.md`.
  */
 
-let engine: WasmHash.create.ReturnType
+let engine: WasmHash.engine.ReturnType
 
 beforeAll(async () => {
-  engine = await WasmHash.create()
+  engine = await WasmHash.engine()
+})
+
+describe('blake3', () => {
+  test(`matches ${vectors.blake3.length} official BLAKE3 vectors`, () => {
+    for (const { digest, message } of vectors.blake3)
+      expect(engine.blake3(message)).toEqual(digest)
+  })
 })
 
 describe('sha256', () => {
   test(`matches ${vectors.sha256.length} NIST CAVP vectors`, () => {
     for (const { digest, message } of vectors.sha256)
-      expect(engine.Hash.sha256(message)).toEqual(digest)
+      expect(engine.sha256(message)).toEqual(digest)
   })
 })
 
@@ -31,26 +38,26 @@ describe('hmacSha256', () => {
     // Two of these use 131-byte keys, which is the only coverage of the
     // longer-than-a-block path where the key is hashed before padding.
     for (const { digest, key, message } of vectors.hmacSha256)
-      expect(engine.Hash.hmacSha256(key, message)).toEqual(digest)
+      expect(engine.hmacSha256(key, message)).toEqual(digest)
   })
 })
 
 describe('ripemd160', () => {
   test(`matches ${vectors.ripemd160.length} reference vectors`, () => {
     for (const { digest, message } of vectors.ripemd160)
-      expect(engine.Hash.ripemd160(message)).toEqual(digest)
+      expect(engine.ripemd160(message)).toEqual(digest)
   })
 
   test('matches the million-`a` reference vector', () => {
     const { digest, message } = vectors.ripemd160MillionA
-    expect(engine.Hash.ripemd160(message)).toEqual(digest)
+    expect(engine.ripemd160(message)).toEqual(digest)
   })
 })
 
 describe('keccak256', () => {
   test(`matches ${vectors.keccak256.length} OpenSSL vectors`, () => {
     for (const { digest, message } of vectors.keccak256)
-      expect(engine.Hash.keccak256(message)).toEqual(digest)
+      expect(engine.keccak256(message)).toEqual(digest)
   })
 })
 
@@ -60,7 +67,7 @@ describe('keccak_f1600', () => {
   /** Writes 25 lanes as little-endian 64-bit words, permutes, and reads back. */
   async function permute(lanes: readonly bigint[]) {
     // A separate instance, because this export is not part of the engine and so
-    // is deliberately not reachable through `WasmHash.load`.
+    // is deliberately not reachable through `WasmHash.engine`.
     const module = await instantiate<Exports>(wasmBase64)
     module.reserve(200)
     const view = module.view()

package/src/wasm/_test/Keystore.browser.test.ts

@@ -0,0 +1,42 @@
+import { pbkdf2 as pbkdf2_noble } from '@noble/hashes/pbkdf2.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { describe, expect, test } from 'vp/test'
+import * as Bytes from '../../core/Bytes.js'
+import * as Engine from '../../core/Engine.js'
+import * as Keystore from '../../core/Keystore.js'
+import * as WasmKeystore from '../Keystore.js'
+
+describe('engine', () => {
+  test('behavior: derives arbitrary-length keys in a real browser', async () => {
+    const engine = await WasmKeystore.engine()
+    const password = Bytes.fromString('testpassword')
+    const salt = new Uint8Array(52).fill(0xa5)
+
+    expect(engine.pbkdf2Sha256(password, salt, { c: 3, dkLen: 65 })).toEqual(
+      pbkdf2_noble(sha256, password, salt, { c: 3, dkLen: 65 }),
+    )
+  })
+
+  test('behavior: ox uses synchronous WASM PBKDF2 once installed', async () => {
+    const engine = await WasmKeystore.engine()
+    await Engine.install({ Keystore: engine })
+    try {
+      const salt = new Uint8Array(32).fill(7)
+      const [key] = Keystore.pbkdf2({
+        iterations: 1_000,
+        password: 'testpassword',
+        salt,
+      })
+      expect(key()).toBe(
+        Bytes.toHex(
+          pbkdf2_noble(sha256, Bytes.fromString('testpassword'), salt, {
+            c: 1_000,
+            dkLen: 32,
+          }),
+        ),
+      )
+    } finally {
+      Engine.reset()
+    }
+  })
+})