ox 1.1.0 → 1.2.0

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

@@ -0,0 +1,220 @@
+import * as crypto from 'node:crypto'
+import * as fs from 'node:fs'
+import { ed25519 } from '@noble/curves/ed25519.js'
+import { Hex } from 'ox'
+import { describe, expect, test } from 'vp/test'
+import * as Ed25519 from '../Ed25519.js'
+
+type Zip215Vector = {
+  sig_bytes: string
+  valid_legacy: boolean
+  valid_zip215: boolean
+  vk_bytes: string
+}
+
+const publicKeyPrefix = Buffer.from('302a300506032b6570032100', 'hex')
+const zip215Text = fs.readFileSync(
+  new URL('../../../test/vectors/ed25519/zip215.json', import.meta.url),
+  'utf8',
+)
+const zip215 = JSON.parse(zip215Text) as readonly Zip215Vector[]
+
+const vectors = [
+  {
+    payload: '',
+    privateKey:
+      '9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60',
+  },
+  {
+    payload: '72',
+    privateKey:
+      '4ccd089b28ff96da9db6c346ec114e0f5b8a319f35aba624da8cf6ed4fb8a6fb',
+  },
+] as const
+
+describe('engine', () => {
+  test('behavior: exposes only primitives compatible with Ox semantics', async () => {
+    const engine = await Ed25519.engine()
+
+    // Node verification is deliberately absent because it does not implement
+    // the ZIP-215 rules used by Ox's default verifier.
+    expect(Object.keys(engine).sort()).toMatchInlineSnapshot(`
+      [
+        "getPublicKey",
+        "sign",
+        "toMontgomerySecret",
+      ]
+    `)
+  })
+
+  test('behavior: matches RFC 8032 test vectors', async () => {
+    const engine = await Ed25519.engine()
+
+    expect(
+      vectors.map(({ payload, privateKey }) => ({
+        publicKey: Hex.fromBytes(engine.getPublicKey(fromHex(privateKey))),
+        signature: Hex.fromBytes(
+          engine.sign(fromHex(payload), fromHex(privateKey)),
+        ),
+      })),
+    ).toMatchInlineSnapshot(`
+      [
+        {
+          "publicKey": "0xd75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a",
+          "signature": "0xe5564300c360ac729086e2cc806e828a84877f1eb8e5d974d873e065224901555fb8821590a33bacc61e39701cf9b46bd25bf5f0595bbe24655141438e7a100b",
+        },
+        {
+          "publicKey": "0x3d4017c3e843895a92b70aa74d1b7ebc9c982ccf2ec4968cc0cd55f12af4660c",
+          "signature": "0x92a009a9f0d4cab8720e820b5f642540a2b27b5416503f8fb3762223ebdb69da085ac1e43e15996e458f3613d0f11d8c387b2eaeb4302aeeb00d291612bb0c00",
+        },
+      ]
+    `)
+  })
+
+  test('behavior: omits verification that disagrees with ZIP-215', async () => {
+    const engine = await Ed25519.engine()
+    const digest = crypto
+      .createHash('sha256')
+      .update(JSON.stringify(zip215))
+      .digest('hex')
+    const message = new TextEncoder().encode('Zcash')
+    let defaultAccepted = 0
+    let nodeAccepted = 0
+
+    for (const vector of zip215) {
+      const publicKey = fromHex(vector.vk_bytes)
+      const signature = fromHex(vector.sig_bytes)
+      if (ed25519.verify(signature, message, publicKey)) defaultAccepted++
+      if (nodeVerify(vector, message)) nodeAccepted++
+    }
+
+    expect({
+      defaultAccepted,
+      digest,
+      legacyAccepted: zip215.filter((vector) => vector.valid_legacy).length,
+      nodeDisagrees: nodeAccepted < defaultAccepted,
+      vectors: zip215.length,
+    }).toMatchInlineSnapshot(`
+      {
+        "defaultAccepted": 196,
+        "digest": "e99ef30c602df87b8d5970dea07f35bcd5993b003e5682ca2c8dc4dab9de4335",
+        "legacyAccepted": 3,
+        "nodeDisagrees": true,
+        "vectors": 196,
+      }
+    `)
+    expect('verify' in engine).toMatchInlineSnapshot('false')
+  })
+
+  test('behavior: matches the default across messages and private keys', async () => {
+    const engine = await Ed25519.engine()
+
+    for (const [index, { privateKey }] of vectors.entries()) {
+      const key = fromHex(privateKey)
+      for (const size of [0, 1, 31, 32, 63, 64, 65, 255]) {
+        const payload = Uint8Array.from(
+          { length: size },
+          (_, offset) => (offset * 29 + index) % 251,
+        )
+        expect(engine.sign(payload, key)).toEqual(ed25519.sign(payload, key))
+      }
+      expect(engine.getPublicKey(key)).toEqual(ed25519.getPublicKey(key))
+      expect(engine.toMontgomerySecret(key)).toEqual(
+        ed25519.utils.toMontgomerySecret(key),
+      )
+    }
+  })
+
+  test('behavior: respects typed-array offsets without mutating inputs', async () => {
+    const engine = await Ed25519.engine()
+    const privateKey = offsetView(fromHex(vectors[0].privateKey))
+    const payload = offsetView(
+      Uint8Array.from({ length: 65 }, (_, index) => (index * 17) % 251),
+    )
+    const privateKeyBefore = privateKey.slice()
+    const payloadBefore = payload.slice()
+
+    expect(engine.getPublicKey(privateKey)).toEqual(
+      ed25519.getPublicKey(privateKey),
+    )
+    expect(engine.sign(payload, privateKey)).toEqual(
+      ed25519.sign(payload, privateKey),
+    )
+    expect(engine.toMontgomerySecret(privateKey)).toEqual(
+      ed25519.utils.toMontgomerySecret(privateKey),
+    )
+    expect({ payload, privateKey }).toEqual({
+      payload: payloadBefore,
+      privateKey: privateKeyBefore,
+    })
+  })
+
+  test('behavior: rejects malformed private-key lengths', async () => {
+    const engine = await Ed25519.engine()
+
+    for (const size of [0, 1, 31, 33, 64]) {
+      const privateKey = new Uint8Array(size)
+      expect(() => engine.getPublicKey(privateKey)).toThrowError(
+        `Ed25519 private key must be 32 bytes, got ${size}`,
+      )
+      expect(() => engine.sign(new Uint8Array(), privateKey)).toThrowError(
+        `Ed25519 private key must be 32 bytes, got ${size}`,
+      )
+      expect(() => engine.toMontgomerySecret(privateKey)).toThrowError(
+        `Ed25519 private key must be 32 bytes, got ${size}`,
+      )
+    }
+  })
+
+  test('behavior: returns owned Uint8Array values', async () => {
+    const engine = await Ed25519.engine()
+    const privateKey = fromHex(vectors[0].privateKey)
+    const outputs = [
+      engine.getPublicKey(privateKey),
+      engine.sign(new Uint8Array(), privateKey),
+      engine.toMontgomerySecret(privateKey),
+    ]
+
+    expect(outputs.map((output) => output.constructor === Uint8Array))
+      .toMatchInlineSnapshot(`
+      [
+        true,
+        true,
+        true,
+      ]
+    `)
+    expect(
+      engine.getPublicKey(privateKey) === engine.getPublicKey(privateKey),
+    ).toMatchInlineSnapshot('false')
+  })
+
+  test('behavior: returns a fresh engine', async () => {
+    const first = await Ed25519.engine()
+    const second = await Ed25519.engine()
+
+    expect(first === second).toMatchInlineSnapshot('false')
+  })
+})
+
+function fromHex(value: string): Uint8Array {
+  return Hex.toBytes(`0x${value}`)
+}
+
+function offsetView(value: Uint8Array): Uint8Array {
+  const bytes = new Uint8Array(value.length + 4).fill(0xff)
+  bytes.set(value, 2)
+  return bytes.subarray(2, -2)
+}
+
+function nodeVerify(vector: Zip215Vector, message: Uint8Array): boolean {
+  try {
+    const publicKey = crypto.createPublicKey({
+      format: 'der',
+      key: Buffer.concat([publicKeyPrefix, fromHex(vector.vk_bytes)]),
+      type: 'spki',
+    })
+    return crypto.verify(null, message, publicKey, fromHex(vector.sig_bytes))
+  } catch {
+    return false
+  }
+}

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

@@ -0,0 +1,28 @@
+import { Engine } from 'ox/node'
+import { expectTypeOf, test } from 'vp/test'
+import * as CoreEngine from '../../core/Engine.js'
+
+type Installed = Awaited<ReturnType<typeof Engine.install>>
+type Uninstalled = Awaited<ReturnType<typeof Engine.engine>>
+
+test('install and engine expose the same precise engine', () => {
+  expectTypeOf<Installed>().toEqualTypeOf<Uninstalled>()
+  expectTypeOf<Installed['Hash']['sha256']>().toEqualTypeOf<
+    (input: Uint8Array) => Uint8Array
+  >()
+})
+
+test('the Node Engine namespace exposes synchronous core operations', () => {
+  expectTypeOf(Engine.get).toEqualTypeOf(CoreEngine.get)
+  expectTypeOf(Engine.InvalidSlotValueError).toEqualTypeOf(
+    CoreEngine.InvalidSlotValueError,
+  )
+  expectTypeOf(Engine.reset).toEqualTypeOf(CoreEngine.reset)
+  expectTypeOf(Engine.set).toEqualTypeOf(CoreEngine.set)
+  expectTypeOf(Engine.with).toEqualTypeOf(CoreEngine.with)
+})
+
+test('the replaced aliases are absent', () => {
+  expectTypeOf<typeof Engine>().not.toHaveProperty('create')
+  expectTypeOf<typeof Engine>().not.toHaveProperty('load')
+})

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

@@ -1,22 +1,27 @@
-import { Engine as CoreEngine, Hash } from 'ox'
-import { Engine } from 'ox/node'
+import { Engine as CoreEngine } from 'ox'
+import { Engine, Hash } from 'ox/node'
 import { describe, expect, test } from 'vp/test'
 
-describe('create', () => {
+describe('engine', () => {
   test('behavior: does not install', async () => {
-    const engine = await Engine.create()
+    const engine = await Engine.engine()
 
     expect(Object.keys(engine)).toMatchInlineSnapshot(`
       [
+        "Ed25519",
         "Hash",
+        "Keystore",
+        "Mnemonic",
+        "P256",
+        "X25519",
       ]
     `)
-    expect(CoreEngine.get()).toMatchInlineSnapshot('{}')
+    expect(Engine.get()).toMatchInlineSnapshot('{}')
   })
 
   test('behavior: installs for the duration of a call', async () => {
-    const node = await Engine.create()
-    const digest = CoreEngine.with(node, () => Hash.sha256('0xdeadbeef'))
+    const node = await Engine.engine()
+    const digest = Engine.with(node, () => Hash.sha256('0xdeadbeef'))
 
     expect(digest).toMatchInlineSnapshot(
       `"0x5f78c33274e43fa9de5659265c1d917e25c03722dcb0b8d27db8d5feaa813953"`,
@@ -25,23 +30,53 @@ describe('create', () => {
   })
 })
 
-describe('load', () => {
+describe('install', () => {
   test('behavior: installs and returns what it installed', async () => {
-    const engine = await Engine.load()
+    const engine = await Engine.install()
 
-    expect(Object.keys(CoreEngine.get())).toEqual(Object.keys(engine))
-    expect(Object.keys(CoreEngine.get().Hash ?? {}).sort())
-      .toMatchInlineSnapshot(`
-      [
-        "hmacSha256",
-        "ripemd160",
-        "sha256",
-      ]
-    `)
+    expect(Engine.get()).toEqual(CoreEngine.get())
+    expect(Object.keys(Engine.get())).toEqual(Object.keys(engine))
+    expect(
+      Object.fromEntries(
+        Object.entries(Engine.get()).map(([slot, value]) => [
+          slot,
+          Object.keys(value ?? {}).sort(),
+        ]),
+      ),
+    ).toMatchInlineSnapshot(`
+        {
+          "Ed25519": [
+            "getPublicKey",
+            "sign",
+            "toMontgomerySecret",
+          ],
+          "Hash": [
+            "hmacSha256",
+            "ripemd160",
+            "sha256",
+          ],
+          "Keystore": [
+            "aesCtrDecrypt",
+            "aesCtrEncrypt",
+            "pbkdf2Sha256",
+            "pbkdf2Sha256Async",
+          ],
+          "Mnemonic": [
+            "toSeed",
+          ],
+          "P256": [
+            "getPublicKey",
+          ],
+          "X25519": [
+            "getPublicKey",
+            "getSharedSecret",
+          ],
+        }
+      `)
   })
 
   test('behavior: leaves unsupported primitives on the default', async () => {
-    await Engine.load()
+    await Engine.install()
 
     expect(Hash.keccak256('0xdeadbeef')).toMatchInlineSnapshot(
       `"0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1"`,
@@ -49,13 +84,18 @@ describe('load', () => {
   })
 
   test('behavior: merges with later engines', async () => {
-    await Engine.load()
-    CoreEngine.set({ Mnemonic: { toSeed: () => new Uint8Array(64) } })
+    await Engine.install()
+    Engine.set({ Bls: { randomSecretKey: () => new Uint8Array(32) } })
 
-    expect(Object.keys(CoreEngine.get()).sort()).toMatchInlineSnapshot(`
+    expect(Object.keys(Engine.get()).sort()).toMatchInlineSnapshot(`
       [
+        "Bls",
+        "Ed25519",
         "Hash",
+        "Keystore",
         "Mnemonic",
+        "P256",
+        "X25519",
       ]
     `)
   })

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

@@ -1,26 +1,33 @@
-import type { Engine } from 'ox'
 import { Hash as NodeHash } from 'ox/node'
 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 NodeHash.create>>
+type Slot = Awaited<ReturnType<typeof NodeHash.engine>>
 
 test('every implemented primitive is present', () => {
-  expectTypeOf<Created['Hash']['hmacSha256']>().toEqualTypeOf<
+  expectTypeOf<Slot['hmacSha256']>().toEqualTypeOf<
     (key: Uint8Array, message: Uint8Array) => Uint8Array
   >()
-  expectTypeOf<Created['Hash']['ripemd160']>().toEqualTypeOf<
+  expectTypeOf<Slot['ripemd160']>().toEqualTypeOf<
     (input: Uint8Array) => Uint8Array
   >()
-  expectTypeOf<Created['Hash']['sha256']>().toEqualTypeOf<
+  expectTypeOf<Slot['sha256']>().toEqualTypeOf<
     (input: Uint8Array) => Uint8Array
   >()
 })
 
 test('unsupported primitives are absent', () => {
-  expectTypeOf<Created['Hash']>().not.toHaveProperty('blake3')
-  expectTypeOf<Created['Hash']>().not.toHaveProperty('keccak256')
+  expectTypeOf<Slot>().not.toHaveProperty('blake3')
+  expectTypeOf<Slot>().not.toHaveProperty('keccak256')
 })
 
-test('the result is still an engine', () => {
-  expectTypeOf<Created>().toExtend<Engine.Engine>()
+test('the result is the raw slot, so `Engine.install` accepts it', () => {
+  expectTypeOf<{ Hash: Slot }>().toExtend<CoreEngine.Engine>()
+})
+
+test('the Node namespace exposes the public Hash API', () => {
+  expectTypeOf(NodeHash.blake3).toEqualTypeOf(CoreHash.blake3)
+  expectTypeOf(NodeHash.sha256).toEqualTypeOf(CoreHash.sha256)
+  expectTypeOf<typeof NodeHash>().not.toHaveProperty('create')
 })

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

@@ -2,11 +2,11 @@ import { Hash as CoreHash, Hex } from 'ox'
 import { Hash } from 'ox/node'
 import { describe, expect, test } from 'vp/test'
 
-describe('create', () => {
+describe('engine', () => {
   test('behavior: exposes the supported primitives', async () => {
-    const engine = await Hash.create()
+    const engine = await Hash.engine()
 
-    expect(Object.keys(engine.Hash).sort()).toMatchInlineSnapshot(`
+    expect(Object.keys(engine).sort()).toMatchInlineSnapshot(`
       [
         "hmacSha256",
         "ripemd160",
@@ -16,7 +16,7 @@ describe('create', () => {
   })
 
   test('behavior: matches published empty-input vectors', async () => {
-    const { hmacSha256, ripemd160, sha256 } = (await Hash.create()).Hash
+    const { hmacSha256, ripemd160, sha256 } = await Hash.engine()
     const empty = new Uint8Array()
 
     expect(Hex.fromBytes(sha256(empty))).toMatchInlineSnapshot(
@@ -31,7 +31,7 @@ describe('create', () => {
   })
 
   test('behavior: agrees with the default across block boundaries', async () => {
-    const node = (await Hash.create()).Hash
+    const node = await Hash.engine()
 
     for (const size of [0, 1, 55, 56, 63, 64, 65, 127, 128, 129]) {
       const input = Uint8Array.from({ length: size }, (_, index) => index % 251)
@@ -45,7 +45,7 @@ describe('create', () => {
   })
 
   test('behavior: agrees with the default across HMAC key sizes', async () => {
-    const { hmacSha256 } = (await Hash.create()).Hash
+    const { hmacSha256 } = await Hash.engine()
     const message = Uint8Array.from({ length: 65 }, (_, index) => index % 251)
 
     for (const size of [0, 1, 32, 63, 64, 65, 200]) {
@@ -57,7 +57,7 @@ describe('create', () => {
   })
 
   test('behavior: respects typed-array offsets', async () => {
-    const node = (await Hash.create()).Hash
+    const node = await Hash.engine()
     const input = Uint8Array.from(
       { length: 80 },
       (_, index) => (index * 17) % 251,
@@ -77,15 +77,14 @@ describe('create', () => {
   })
 
   test('behavior: returns a fresh engine', async () => {
-    const first = await Hash.create()
-    const second = await Hash.create()
+    const first = await Hash.engine()
+    const second = await Hash.engine()
 
     expect(first === second).toMatchInlineSnapshot('false')
-    expect(first.Hash === second.Hash).toMatchInlineSnapshot('false')
   })
 
   test('behavior: returns owned Uint8Array values', async () => {
-    const { hmacSha256, ripemd160, sha256 } = (await Hash.create()).Hash
+    const { hmacSha256, ripemd160, sha256 } = await Hash.engine()
     const input = Uint8Array.of(1, 2, 3)
     const outputs = [hmacSha256(input, input), ripemd160(input), sha256(input)]
 

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

@@ -0,0 +1,58 @@
+import { ctr } from '@noble/ciphers/aes.js'
+import { pbkdf2 } from '@noble/hashes/pbkdf2.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { fc, test } from '@fast-check/vitest'
+import { expect } from 'vp/test'
+import { numRuns } from '../../../test/fuzz/numRuns.js'
+import * as Keystore from '../Keystore.js'
+
+const subview = (bytes: Uint8Array) => {
+  const value = new Uint8Array(bytes.length + 4)
+  value.set(bytes, 2)
+  return value.subarray(2, bytes.length + 2)
+}
+
+const arbitraryKey = fc
+  .oneof(
+    fc.uint8Array({ maxLength: 16, minLength: 16 }),
+    fc.uint8Array({ maxLength: 24, minLength: 24 }),
+    fc.uint8Array({ maxLength: 32, minLength: 32 }),
+  )
+  .map(subview)
+
+test.prop(
+  {
+    data: fc.uint8Array({ maxLength: 256 }).map(subview),
+    iv: fc.uint8Array({ maxLength: 16, minLength: 16 }).map(subview),
+    key: arbitraryKey,
+  },
+  { numRuns },
+)('Node AES-CTR agrees with the default', async ({ data, iv, key }) => {
+  const { aesCtrDecrypt, aesCtrEncrypt } = await Keystore.engine()
+  const expected = ctr(key, iv).encrypt(data)
+  const encrypted = aesCtrEncrypt(key, iv, data)
+
+  expect(encrypted).toEqual(expected)
+  expect(aesCtrDecrypt(key, iv, encrypted)).toEqual(data)
+})
+
+test.prop(
+  {
+    c: fc.integer({ max: 32, min: 1 }),
+    dkLen: fc.integer({ max: 96, min: 1 }),
+    password: fc.uint8Array({ maxLength: 96 }).map(subview),
+    salt: fc.uint8Array({ maxLength: 96 }).map(subview),
+  },
+  { numRuns },
+)(
+  'Node PBKDF2-HMAC-SHA256 agrees with the default',
+  async ({ c, dkLen, password, salt }) => {
+    const { pbkdf2Sha256, pbkdf2Sha256Async } = await Keystore.engine()
+    const expected = pbkdf2(sha256, password, salt, { c, dkLen })
+
+    expect(pbkdf2Sha256(password, salt, { c, dkLen })).toEqual(expected)
+    expect(await pbkdf2Sha256Async(password, salt, { c, dkLen })).toEqual(
+      expected,
+    )
+  },
+)

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

@@ -0,0 +1,43 @@
+import type { Engine } from 'ox'
+import { expectTypeOf, test } from 'vp/test'
+import * as core_Keystore from '../../core/Keystore.js'
+import * as NodeKeystore from '../Keystore.js'
+
+type Slot = Awaited<ReturnType<typeof NodeKeystore.engine>>
+
+test('every implemented primitive is present', () => {
+  expectTypeOf<Slot['aesCtrDecrypt']>().toEqualTypeOf<
+    (key: Uint8Array, iv: Uint8Array, data: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Slot['aesCtrEncrypt']>().toEqualTypeOf<
+    (key: Uint8Array, iv: Uint8Array, data: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Slot['pbkdf2Sha256']>().toEqualTypeOf<
+    (
+      password: Uint8Array,
+      salt: Uint8Array,
+      options: { c: number; dkLen: number },
+    ) => Uint8Array
+  >()
+  expectTypeOf<Slot['pbkdf2Sha256Async']>().toEqualTypeOf<
+    (
+      password: Uint8Array,
+      salt: Uint8Array,
+      options: { c: number; dkLen: number },
+    ) => Promise<Uint8Array>
+  >()
+})
+
+test('unsupported primitives are absent', () => {
+  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 Node namespace exposes the public Keystore API', () => {
+  expectTypeOf(NodeKeystore.pbkdf2).toEqualTypeOf(core_Keystore.pbkdf2)
+  expectTypeOf<typeof NodeKeystore>().not.toHaveProperty('create')
+})