ox 1.1.0 → 1.1.2

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

@@ -0,0 +1,113 @@
+import { fc, test } from '@fast-check/vitest'
+import { pbkdf2 as pbkdf2_noble } from '@noble/hashes/pbkdf2.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { beforeAll, describe, expect } from 'vp/test'
+import { numRuns } from '../../../test/fuzz/numRuns.js'
+import * as WasmHash from '../Hash.js'
+import * as WasmKeystore from '../Keystore.js'
+
+let hash: WasmHash.engine.ReturnType
+let keystore: WasmKeystore.engine.ReturnType
+
+beforeAll(async () => {
+  ;[hash, keystore] = await Promise.all([
+    WasmHash.engine(),
+    WasmKeystore.engine(),
+  ])
+})
+
+const arbitraryPassword = fc.oneof(
+  {
+    arbitrary: fc
+      .constantFrom(0, 1, 32, 63, 64, 65, 128, 129)
+      .chain((size) => fc.uint8Array({ maxLength: size, minLength: size })),
+    weight: 3,
+  },
+  { arbitrary: fc.uint8Array({ maxLength: 200 }), weight: 2 },
+)
+
+const arbitrarySalt = fc.oneof(
+  {
+    arbitrary: fc
+      .constantFrom(0, 1, 31, 32, 51, 52, 55, 56, 63, 64, 65, 136)
+      .chain((size) => fc.uint8Array({ maxLength: size, minLength: size })),
+    weight: 3,
+  },
+  { arbitrary: fc.uint8Array({ maxLength: 200 }), weight: 2 },
+)
+
+const arbitraryDkLen = fc.oneof(
+  {
+    arbitrary: fc.constantFrom(1, 2, 31, 32, 33, 63, 64, 65, 96, 97),
+    weight: 3,
+  },
+  { arbitrary: fc.integer({ max: 256, min: 1 }), weight: 2 },
+)
+
+function asSubview(input: Uint8Array) {
+  const backing = new Uint8Array(input.length + 11).fill(0xa5)
+  backing.set(input, 7)
+  return { backing, view: backing.subarray(7, 7 + input.length) }
+}
+
+describe('pbkdf2Sha256', () => {
+  test.prop(
+    {
+      c: fc.integer({ max: 20, min: 1 }),
+      dkLen: arbitraryDkLen,
+      password: arbitraryPassword,
+      salt: arbitrarySalt,
+    },
+    { numRuns },
+  )(
+    'matches @noble/hashes for arbitrary inputs and output lengths',
+    ({ c, dkLen, password, salt }) => {
+      expect(keystore.pbkdf2Sha256(password, salt, { c, dkLen })).toEqual(
+        pbkdf2_noble(sha256, password, salt, { c, dkLen }),
+      )
+    },
+  )
+
+  test.prop(
+    {
+      c: fc.integer({ max: 10, min: 1 }),
+      dkLen: arbitraryDkLen,
+      password: arbitraryPassword,
+      salt: arbitrarySalt,
+    },
+    { numRuns },
+  )(
+    'handles subviews without mutating either backing buffer',
+    ({ c, dkLen, password, salt }) => {
+      const password_ = asSubview(password)
+      const salt_ = asSubview(salt)
+      const passwordSnapshot = password_.backing.slice()
+      const saltSnapshot = salt_.backing.slice()
+
+      expect(
+        keystore.pbkdf2Sha256(password_.view, salt_.view, {
+          c,
+          dkLen,
+        }),
+      ).toEqual(pbkdf2_noble(sha256, password_.view, salt_.view, { c, dkLen }))
+      expect(password_.backing).toEqual(passwordSnapshot)
+      expect(salt_.backing).toEqual(saltSnapshot)
+    },
+  )
+
+  test.prop(
+    {
+      dkLen: arbitraryDkLen,
+      input: fc.uint8Array({ maxLength: 256 }),
+    },
+    { numRuns },
+  )('shares memory safely with hash calls', ({ dkLen, input }) => {
+    const derived = keystore.pbkdf2Sha256(input, input, {
+      c: 2,
+      dkLen,
+    })
+    const snapshot = derived.slice()
+    expect(hash.sha256(input)).toEqual(sha256(input))
+    expect(derived).toEqual(snapshot)
+  })
+})

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

@@ -0,0 +1,33 @@
+import type { Engine } from 'ox'
+import { expectTypeOf, test } from 'vp/test'
+import * as core_Keystore from '../../core/Keystore.js'
+import * as WasmKeystore from '../Keystore.js'
+
+type Slot = Awaited<ReturnType<typeof WasmKeystore.engine>>
+
+test('synchronous PBKDF2 is present', () => {
+  expectTypeOf<Slot['pbkdf2Sha256']>().toEqualTypeOf<
+    (
+      password: Uint8Array,
+      salt: Uint8Array,
+      options: { c: number; dkLen: number },
+    ) => Uint8Array
+  >()
+})
+
+test('unsupported primitives are absent', () => {
+  expectTypeOf<Slot>().not.toHaveProperty('aesCtrDecrypt')
+  expectTypeOf<Slot>().not.toHaveProperty('aesCtrEncrypt')
+  expectTypeOf<Slot>().not.toHaveProperty('pbkdf2Sha256Async')
+  expectTypeOf<Slot>().not.toHaveProperty('scrypt')
+  expectTypeOf<Slot>().not.toHaveProperty('scryptAsync')
+})
+
+test('the result is the raw slot', () => {
+  expectTypeOf<{ Keystore: Slot }>().toExtend<Engine.Engine>()
+})
+
+test('the WASM namespace exposes the public Keystore API', () => {
+  expectTypeOf(WasmKeystore.pbkdf2).toEqualTypeOf(core_Keystore.pbkdf2)
+  expectTypeOf<typeof WasmKeystore>().not.toHaveProperty('create')
+})

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

@@ -0,0 +1,192 @@
+import { pbkdf2 as pbkdf2_noble } from '@noble/hashes/pbkdf2.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { beforeAll, 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'
+import * as hashes from '../internal/hashes.js'
+import { wasmBase64 } from '../internal/hashes.wasm.js'
+import * as internal from '../internal/instantiate.js'
+import * as pbkdf2 from '../internal/pbkdf2.js'
+
+let engine: WasmKeystore.engine.ReturnType
+
+beforeAll(async () => {
+  engine = await WasmKeystore.engine()
+})
+
+function input(size: number) {
+  return new Uint8Array(size).map((_, index) => (index * 37 + 11) & 0xff)
+}
+
+describe('engine', () => {
+  test('default', async () => {
+    expect(Object.keys(await WasmKeystore.engine())).toMatchInlineSnapshot(`
+      [
+        "pbkdf2Sha256",
+      ]
+    `)
+  })
+
+  test('behavior: shares the compiled hashes instance', async () => {
+    const [a, b] = await Promise.all([hashes.load(), hashes.load()])
+    expect(a).toBe(b)
+  })
+
+  test('behavior: hands every caller its own engine', async () => {
+    const [a, b] = await Promise.all([
+      WasmKeystore.engine(),
+      WasmKeystore.engine(),
+    ])
+    expect(a).not.toBe(b)
+
+    a.pbkdf2Sha256 = () => new Uint8Array([9])
+    const c = await WasmKeystore.engine()
+    expect(c.pbkdf2Sha256(input(8), input(16), { c: 2, dkLen: 33 })).toEqual(
+      b.pbkdf2Sha256(input(8), input(16), { c: 2, dkLen: 33 }),
+    )
+  })
+})
+
+const cases = [
+  { c: 1, dkLen: 1, password: 0, salt: 0 },
+  { c: 2, dkLen: 31, password: 1, salt: 51 },
+  { c: 3, dkLen: 32, password: 63, salt: 52 },
+  { c: 4, dkLen: 33, password: 64, salt: 55 },
+  { c: 7, dkLen: 64, password: 65, salt: 64 },
+  { c: 2, dkLen: 65, password: 129, salt: 137 },
+] as const
+
+describe('pbkdf2Sha256', () => {
+  test.each(cases)(
+    'matches the default for password=$password salt=$salt c=$c dkLen=$dkLen',
+    ({ c, dkLen, password: passwordLength, salt: saltLength }) => {
+      const password = input(passwordLength)
+      const salt = input(saltLength)
+      expect(engine.pbkdf2Sha256(password, salt, { c, dkLen })).toEqual(
+        pbkdf2_noble(sha256, password, salt, { c, dkLen }),
+      )
+    },
+  )
+
+  test('behavior: reads non-zero-offset views without mutating their backing buffers', () => {
+    const passwordBacking = new Uint8Array(80).fill(0xa5)
+    const saltBacking = new Uint8Array(90).fill(0x5a)
+    const password = passwordBacking.subarray(7, 72)
+    const salt = saltBacking.subarray(11, 63)
+    password.set(input(password.length))
+    salt.set(input(salt.length))
+    const passwordSnapshot = passwordBacking.slice()
+    const saltSnapshot = saltBacking.slice()
+
+    expect(engine.pbkdf2Sha256(password, salt, { c: 3, dkLen: 65 })).toEqual(
+      pbkdf2_noble(sha256, password, salt, { c: 3, dkLen: 65 }),
+    )
+    expect(passwordBacking).toEqual(passwordSnapshot)
+    expect(saltBacking).toEqual(saltSnapshot)
+  })
+
+  test('behavior: results are fresh and never alias WASM memory', () => {
+    const password = input(65)
+    const salt = input(52)
+    const first = engine.pbkdf2Sha256(password, salt, {
+      c: 2,
+      dkLen: 65,
+    })
+    const snapshot = first.slice()
+    const second = engine.pbkdf2Sha256(input(5), input(9), {
+      c: 3,
+      dkLen: 97,
+    })
+
+    expect(first).not.toBe(second)
+    expect(first).toEqual(snapshot)
+  })
+
+  test('behavior: clears passwords, salts, outputs, and scratch', async () => {
+    const module = await internal.instantiate<hashes.Exports>(wasmBase64)
+    const password = input(65)
+    const salt = input(52)
+    const stack = module.view().slice(0, module.heapBase)
+
+    expect(
+      pbkdf2.pbkdf2Sha256(module, password, salt, { c: 3, dkLen: 65 }),
+    ).toEqual(pbkdf2_noble(sha256, password, salt, { c: 3, dkLen: 65 }))
+    expect(module.view().slice(0, module.heapBase)).toEqual(stack)
+    expect(module.view().slice(module.heapBase)).toEqual(
+      new Uint8Array(module.view().length - module.heapBase),
+    )
+  })
+
+  test('behavior: clears the complete region after a late trap', async () => {
+    const module = await internal.instantiate<hashes.Exports>(wasmBase64)
+    const password = input(65)
+    const salt = input(52)
+    const exports: pbkdf2.Exports = {
+      pbkdf2_sha256(...parameters) {
+        module.exports.pbkdf2_sha256(...parameters)
+        throw new WebAssembly.RuntimeError('forced late trap')
+      },
+      zero: (ptr, length) => module.exports.zero(ptr, length),
+    }
+
+    expect(() =>
+      pbkdf2.pbkdf2Sha256({ ...module, exports }, password, salt, {
+        c: 3,
+        dkLen: 65,
+      }),
+    ).toThrow(WebAssembly.RuntimeError)
+    expect(module.view().slice(module.heapBase)).toEqual(
+      new Uint8Array(module.view().length - module.heapBase),
+    )
+  })
+
+  test('behavior: rejects a workspace that overflows wasm32 before growing memory', async () => {
+    const module = await internal.instantiate<hashes.Exports>(wasmBase64)
+    const memory = module.view().length
+
+    expect(() =>
+      pbkdf2.pbkdf2Sha256(module, new Uint8Array(), new Uint8Array(), {
+        c: 1,
+        dkLen: 0xffff_ffff,
+      }),
+    ).toThrow(internal.MemoryError)
+    expect(module.view()).toHaveLength(memory)
+  })
+
+  test.each([
+    { name: 'c', options: { c: 0, dkLen: 32 } },
+    { name: 'c', options: { c: 1.5, dkLen: 32 } },
+    { name: 'c', options: { c: 0x1_0000_0000, dkLen: 32 } },
+    { name: 'dkLen', options: { c: 1, dkLen: 0 } },
+    { name: 'dkLen', options: { c: 1, dkLen: 1.5 } },
+    { name: 'dkLen', options: { c: 1, dkLen: 0x1_0000_0000 } },
+  ])('behavior: rejects invalid $name before entering WASM', ({ options }) => {
+    expect(() => engine.pbkdf2Sha256(input(8), input(16), options)).toThrow()
+  })
+})
+
+describe('Engine.install', () => {
+  test('behavior: ox uses synchronous WASM PBKDF2 once installed', async () => {
+    await Engine.install({ Keystore: engine })
+    try {
+      const salt = input(32)
+      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()
+    }
+  })
+})

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

@@ -0,0 +1,21 @@
+import { beforeAll, describe, expect, test } from 'vp/test'
+import * as vectors from '../../../test/vectors/pbkdf2/index.js'
+import * as WasmKeystore from '../Keystore.js'
+
+let engine: WasmKeystore.engine.ReturnType
+
+beforeAll(async () => {
+  engine = await WasmKeystore.engine()
+})
+
+describe('pbkdf2Sha256', () => {
+  test(`matches ${vectors.vectors.length} RFC 7914 vectors`, () => {
+    for (const { iterations, key, password, salt } of vectors.vectors)
+      expect(
+        engine.pbkdf2Sha256(password, salt, {
+          c: iterations,
+          dkLen: key.length,
+        }),
+      ).toEqual(key)
+  })
+})

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

@@ -0,0 +1,17 @@
+import { expectTypeOf, test } from 'vp/test'
+import type * as Engine from '../../core/Engine.js'
+import * as core_Mnemonic from '../../core/Mnemonic.js'
+import * as Mnemonic from '../Mnemonic.js'
+
+type Slot = Awaited<ReturnType<typeof Mnemonic.engine>>
+
+test('return type exposes Mnemonic.toSeed', () => {
+  expectTypeOf<Slot['toSeed']>().toEqualTypeOf<
+    NonNullable<Engine.Mnemonic['toSeed']>
+  >()
+})
+
+test('the WASM namespace exposes the public Mnemonic API', () => {
+  expectTypeOf(Mnemonic.toSeed).toEqualTypeOf(core_Mnemonic.toSeed)
+  expectTypeOf<typeof Mnemonic>().not.toHaveProperty('create')
+})

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

@@ -0,0 +1,110 @@
+import { mnemonicToSeedSync } from '@scure/bip39'
+import { describe, expect, test } from 'vp/test'
+import { vectors } from '../../../test/vectors/bip39/index.js'
+import * as Mnemonic from '../Mnemonic.js'
+import * as crypto25519 from '../internal/crypto25519.js'
+import { wasmBase64 } from '../internal/crypto25519.wasm.js'
+import * as internal from '../internal/instantiate.js'
+import * as mnemonic_internal from '../internal/mnemonic.js'
+
+describe('engine', () => {
+  test('vectors: matches the official English BIP-39 vector', async () => {
+    const { toSeed } = await Mnemonic.engine()
+
+    expect(
+      toHex(toSeed(vectors.english.mnemonic, vectors.english.passphrase)),
+    ).toBe(vectors.english.seed)
+  })
+
+  test('vectors: matches the official Japanese Unicode BIP-39 vector', async () => {
+    const { toSeed } = await Mnemonic.engine()
+
+    expect(
+      toHex(toSeed(vectors.japanese.mnemonic, vectors.japanese.passphrase)),
+    ).toBe(vectors.japanese.seed)
+  })
+
+  test('behavior: matches NFKD and every supported word count', async () => {
+    const { toSeed } = await Mnemonic.engine()
+
+    for (const count of [12, 15, 18, 21, 24]) {
+      const composed = Array.from({ length: count }, () => 'café').join(' ')
+      const decomposed = Array.from({ length: count }, () => 'cafe\u0301').join(
+        ' ',
+      )
+      expect(toSeed(composed, 'pássphrase')).toEqual(
+        toSeed(decomposed, 'pa\u0301ssphrase'),
+      )
+      expect(toSeed(composed, 'pássphrase')).toEqual(
+        mnemonicToSeedSync(composed, 'pássphrase'),
+      )
+    }
+  })
+
+  test('behavior: rejects the same malformed phrase shapes', async () => {
+    const { toSeed } = await Mnemonic.engine()
+
+    for (const count of [0, 1, 11, 13, 23, 25])
+      expect(() =>
+        toSeed(Array.from({ length: count }, () => 'word').join(' ')),
+      ).toThrowError('Invalid mnemonic')
+    expect(() => toSeed(1 as never)).toThrowError(
+      'invalid mnemonic type: number',
+    )
+  })
+
+  test('behavior: outputs remain owned and staging memory is cleared', async () => {
+    const { toSeed } = await Mnemonic.engine()
+    const seed = toSeed(vectors.english.mnemonic, vectors.japanese.passphrase)
+    const snapshot = seed.slice()
+    toSeed(Array.from({ length: 24 }, () => 'word').join(' '), 'other')
+    expect(seed).toEqual(snapshot)
+
+    const passwordSize = new TextEncoder().encode(
+      vectors.english.mnemonic.normalize('NFKD'),
+    ).length
+    const saltSize = new TextEncoder().encode(
+      `mnemonic${vectors.japanese.passphrase}`.normalize('NFKD'),
+    ).length
+    const module = await crypto25519.load()
+    expect(
+      module
+        .view()
+        .subarray(
+          module.heapBase,
+          module.heapBase + passwordSize + saltSize + 64,
+        )
+        .every((byte) => byte === 0),
+    ).toBe(true)
+  })
+
+  test('behavior: clears password, salt, and output after a late trap', async () => {
+    const module = await internal.instantiate<crypto25519.Exports>(wasmBase64)
+    const vector = vectors.japanese
+    const exports: crypto25519.Exports = {
+      ...module.exports,
+      mnemonic_to_seed(...parameters) {
+        module.exports.mnemonic_to_seed(...parameters)
+        throw new WebAssembly.RuntimeError('forced late trap')
+      },
+    }
+
+    expect(() =>
+      mnemonic_internal.toSeed(
+        { ...module, exports },
+        vector.mnemonic,
+        vector.passphrase,
+      ),
+    ).toThrow(WebAssembly.RuntimeError)
+    expect(
+      module
+        .view()
+        .subarray(module.heapBase)
+        .every((byte) => byte === 0),
+    ).toBe(true)
+  })
+})
+
+function toHex(value: Uint8Array): string {
+  return Buffer.from(value).toString('hex')
+}

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

@@ -0,0 +1,21 @@
+import { expectTypeOf, test } from 'vp/test'
+import type * as Engine from '../../core/Engine.js'
+import * as core_X25519 from '../../core/X25519.js'
+import * as X25519 from '../X25519.js'
+
+type Slot = Awaited<ReturnType<typeof X25519.engine>>
+
+test('return type exposes only implemented X25519 primitives', () => {
+  expectTypeOf<Slot['getPublicKey']>().toEqualTypeOf<
+    NonNullable<Engine.Ecdh['getPublicKey']>
+  >()
+  expectTypeOf<Slot['getSharedSecret']>().toEqualTypeOf<
+    NonNullable<Engine.Ecdh['getSharedSecret']>
+  >()
+  expectTypeOf<Slot>().not.toHaveProperty('randomSecretKey')
+})
+
+test('the WASM namespace exposes the public X25519 API', () => {
+  expectTypeOf(X25519.getPublicKey).toEqualTypeOf(core_X25519.getPublicKey)
+  expectTypeOf<typeof X25519>().not.toHaveProperty('create')
+})