ox 1.1.0 → 1.2.0

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

@@ -0,0 +1,198 @@
+import { ctr } from '@noble/ciphers/aes.js'
+import { pbkdf2 } from '@noble/hashes/pbkdf2.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { Hex } from 'ox'
+import { describe, expect, test } from 'vp/test'
+import * as vectors from '../../../test/vectors/pbkdf2/index.js'
+import * as Keystore from '../Keystore.js'
+
+describe('engine', () => {
+  test('behavior: matches NIST SP 800-38A AES-CTR vectors', async () => {
+    const { aesCtrDecrypt, aesCtrEncrypt } = await Keystore.engine()
+    const iv = Hex.toBytes('0xf0f1f2f3f4f5f6f7f8f9fafbfcfdfeff')
+    const plaintext = Hex.toBytes('0x6bc1bee22e409f96e93d7e117393172a')
+    const vectors = [
+      {
+        ciphertext: '0x874d6191b620e3261bef6864990db6ce',
+        key: '0x2b7e151628aed2a6abf7158809cf4f3c',
+      },
+      {
+        ciphertext: '0x1abc932417521ca24f2b0459fe7e6e0b',
+        key: '0x8e73b0f7da0e6452c810f32b809079e562f8ead2522c6b7b',
+      },
+      {
+        ciphertext: '0x601ec313775789a5b7a7f504bbf3d228',
+        key: '0x603deb1015ca71be2b73aef0857d77811f352c073b6108d72d9810a30914dff4',
+      },
+    ] as const
+
+    expect(
+      vectors.map(({ ciphertext, key }) => {
+        const encrypted = aesCtrEncrypt(Hex.toBytes(key), iv, plaintext)
+        const decrypted = aesCtrDecrypt(
+          Hex.toBytes(key),
+          iv,
+          Hex.toBytes(ciphertext),
+        )
+        return {
+          decrypted: Hex.fromBytes(decrypted),
+          encrypted: Hex.fromBytes(encrypted),
+        }
+      }),
+    ).toMatchInlineSnapshot(`
+      [
+        {
+          "decrypted": "0x6bc1bee22e409f96e93d7e117393172a",
+          "encrypted": "0x874d6191b620e3261bef6864990db6ce",
+        },
+        {
+          "decrypted": "0x6bc1bee22e409f96e93d7e117393172a",
+          "encrypted": "0x1abc932417521ca24f2b0459fe7e6e0b",
+        },
+        {
+          "decrypted": "0x6bc1bee22e409f96e93d7e117393172a",
+          "encrypted": "0x601ec313775789a5b7a7f504bbf3d228",
+        },
+      ]
+    `)
+  })
+
+  test('behavior: matches RFC 7914 PBKDF2-HMAC-SHA256 vectors', async () => {
+    const { pbkdf2Sha256 } = await Keystore.engine()
+
+    for (const { iterations, key, password, salt } of vectors.vectors)
+      expect(
+        pbkdf2Sha256(password, salt, {
+          c: iterations,
+          dkLen: key.length,
+        }),
+      ).toEqual(key)
+  })
+
+  test('behavior: agrees with the defaults across boundary sizes', async () => {
+    const node = await Keystore.engine()
+    const iv = Uint8Array.from(
+      { length: 20 },
+      (_, index) => (index * 13) % 251,
+    ).subarray(2, 18)
+
+    for (const keySize of [16, 24, 32]) {
+      const key = Uint8Array.from(
+        { length: keySize + 4 },
+        (_, index) => (index * 17) % 251,
+      ).subarray(2, keySize + 2)
+
+      for (const size of [0, 1, 15, 16, 17, 31, 32, 33]) {
+        const data = Uint8Array.from(
+          { length: size + 6 },
+          (_, index) => (index * 29) % 251,
+        ).subarray(3, size + 3)
+        const encrypted = node.aesCtrEncrypt(key, iv, data)
+
+        expect(encrypted).toEqual(ctr(key, iv).encrypt(data))
+        expect(node.aesCtrDecrypt(key, iv, encrypted)).toEqual(data)
+      }
+    }
+
+    const password = Uint8Array.from(
+      { length: 37 },
+      (_, index) => (index * 31) % 251,
+    ).subarray(3, 34)
+    const salt = Uint8Array.from(
+      { length: 41 },
+      (_, index) => (index * 37) % 251,
+    ).subarray(5, 37)
+
+    for (const options of [
+      { c: 1, dkLen: 1 },
+      { c: 2, dkLen: 31 },
+      { c: 3, dkLen: 32 },
+      { c: 4, dkLen: 33 },
+      { c: 16, dkLen: 64 },
+    ]) {
+      const expected = pbkdf2(sha256, password, salt, options)
+      expect(node.pbkdf2Sha256(password, salt, options)).toEqual(expected)
+      expect(await node.pbkdf2Sha256Async(password, salt, options)).toEqual(
+        expected,
+      )
+    }
+  })
+
+  test('behavior: does not mutate inputs and returns owned arrays', async () => {
+    const node = await Keystore.engine()
+    const data = Uint8Array.of(1, 2, 3, 4, 5)
+    const iv = new Uint8Array(16).fill(2)
+    const key = new Uint8Array(16).fill(3)
+    const password = Uint8Array.of(4, 5, 6)
+    const salt = Uint8Array.of(7, 8, 9)
+    const inputs = [data, iv, key, password, salt]
+    const before = inputs.map((input) => input.slice())
+
+    const outputs = [
+      node.aesCtrEncrypt(key, iv, data),
+      node.aesCtrDecrypt(key, iv, data),
+      node.pbkdf2Sha256(password, salt, { c: 1, dkLen: 32 }),
+      await node.pbkdf2Sha256Async(password, salt, { c: 1, dkLen: 32 }),
+    ]
+
+    expect(inputs).toEqual(before)
+    expect(outputs.map((output) => output.constructor === Uint8Array))
+      .toMatchInlineSnapshot(`
+        [
+          true,
+          true,
+          true,
+          true,
+        ]
+      `)
+    expect(
+      node.aesCtrEncrypt(key, iv, data) === node.aesCtrEncrypt(key, iv, data),
+    ).toMatchInlineSnapshot('false')
+  })
+
+  test('behavior: rejects malformed AES and PBKDF2 parameters', async () => {
+    const node = await Keystore.engine()
+    const data = new Uint8Array()
+    const iv = new Uint8Array(16)
+    const key = new Uint8Array(16)
+
+    for (const keyLength of [0, 15, 17, 23, 25, 31, 33]) {
+      expect(() => ctr(new Uint8Array(keyLength), iv).encrypt(data)).toThrow()
+      expect(() =>
+        node.aesCtrEncrypt(new Uint8Array(keyLength), iv, data),
+      ).toThrow()
+      expect(() =>
+        node.aesCtrDecrypt(new Uint8Array(keyLength), iv, data),
+      ).toThrow()
+    }
+    for (const ivLength of [0, 15, 17]) {
+      expect(() => ctr(key, new Uint8Array(ivLength)).encrypt(data)).toThrow()
+      expect(() =>
+        node.aesCtrEncrypt(key, new Uint8Array(ivLength), data),
+      ).toThrow()
+      expect(() =>
+        node.aesCtrDecrypt(key, new Uint8Array(ivLength), data),
+      ).toThrow()
+    }
+
+    for (const options of [
+      { c: 0, dkLen: 32 },
+      { c: 1.5, dkLen: 32 },
+      { c: 1, dkLen: 0 },
+      { c: 1, dkLen: 1.5 },
+    ]) {
+      expect(() => pbkdf2(sha256, data, data, options)).toThrow()
+      expect(() => node.pbkdf2Sha256(data, data, options)).toThrow()
+      await expect(
+        node.pbkdf2Sha256Async(data, data, options),
+      ).rejects.toThrow()
+    }
+  })
+
+  test('behavior: returns a fresh engine', async () => {
+    const first = await Keystore.engine()
+    const second = await Keystore.engine()
+
+    expect(first === second).toMatchInlineSnapshot('false')
+  })
+})

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

@@ -0,0 +1,31 @@
+import { mnemonicToSeedSync } from '@scure/bip39'
+import { fc, test } from '@fast-check/vitest'
+import { expect } from 'vp/test'
+import { numRuns } from '../../../test/fuzz/numRuns.js'
+import * as Mnemonic from '../Mnemonic.js'
+
+const arbitraryWord = fc.oneof(
+  fc
+    .string({ maxLength: 16, minLength: 1 })
+    .filter((value) => !value.normalize('NFKD').includes(' ')),
+  fc.constantFrom('café', 'cafe\u0301', 'あおぞら', '㍍ガバヴァ'),
+)
+
+test.prop(
+  {
+    mnemonic: fc
+      .array(arbitraryWord, { maxLength: 12, minLength: 12 })
+      .map((words) => words.join(' ')),
+    passphrase: fc.string({ maxLength: 32 }),
+  },
+  { numRuns },
+)(
+  'Node BIP-39 seed derivation agrees with the default',
+  async ({ mnemonic, passphrase }) => {
+    const { toSeed } = await Mnemonic.engine()
+
+    expect(toSeed(mnemonic, passphrase)).toEqual(
+      mnemonicToSeedSync(mnemonic, passphrase),
+    )
+  },
+)

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

@@ -0,0 +1,21 @@
+import { expectTypeOf, test } from 'vp/test'
+import type * as Engine from '../../core/Engine.js'
+import * as core_Mnemonic from '../../core/Mnemonic.js'
+import * as NodeMnemonic from '../Mnemonic.js'
+
+type Slot = Awaited<ReturnType<typeof NodeMnemonic.engine>>
+
+test('every implemented primitive is present', () => {
+  expectTypeOf<Slot['toSeed']>().toEqualTypeOf<
+    (mnemonic: string, passphrase?: string) => Uint8Array
+  >()
+})
+
+test('the result is the raw slot', () => {
+  expectTypeOf<{ Mnemonic: Slot }>().toExtend<Engine.Engine>()
+})
+
+test('the Node namespace exposes the public Mnemonic API', () => {
+  expectTypeOf(NodeMnemonic.toSeed).toEqualTypeOf(core_Mnemonic.toSeed)
+  expectTypeOf<typeof NodeMnemonic>().not.toHaveProperty('create')
+})

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

@@ -0,0 +1,98 @@
+import { mnemonicToSeedSync } from '@scure/bip39'
+import { Hex } from 'ox'
+import { describe, expect, test } from 'vp/test'
+import * as bip39 from '../../../test/vectors/bip39/index.js'
+import * as Mnemonic from '../Mnemonic.js'
+
+describe('engine', () => {
+  test('behavior: matches the BIP-39 English vector', async () => {
+    const { toSeed } = await Mnemonic.engine()
+    const { mnemonic, passphrase, seed } = bip39.vectors.english
+
+    expect(Hex.fromBytes(toSeed(mnemonic, passphrase))).toBe(`0x${seed}`)
+  })
+
+  test('behavior: matches the BIP-39 Japanese Unicode vector', async () => {
+    const { toSeed } = await Mnemonic.engine()
+    const { mnemonic, passphrase, seed } = bip39.vectors.japanese
+
+    expect(Hex.fromBytes(toSeed(mnemonic, passphrase))).toBe(`0x${seed}`)
+  })
+
+  test('behavior: applies BIP-39 NFKD normalization', async () => {
+    const { toSeed } = await Mnemonic.engine()
+    const composed = Array.from({ length: 12 }, () => 'café').join(' ')
+    const decomposed = Array.from({ length: 12 }, () => '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: accepts every supported phrase length', async () => {
+    const { toSeed } = await Mnemonic.engine()
+
+    expect(
+      [12, 15, 18, 21, 24].map(
+        (length) =>
+          toSeed(Array.from({ length }, () => 'word').join(' ')).length,
+      ),
+    ).toMatchInlineSnapshot(`
+      [
+        64,
+        64,
+        64,
+        64,
+        64,
+      ]
+    `)
+  })
+
+  test('behavior: rejects unsupported phrase lengths', async () => {
+    const { toSeed } = await Mnemonic.engine()
+
+    for (const length of [0, 1, 11, 13, 23, 25])
+      expect(() =>
+        toSeed(Array.from({ length }, () => 'word').join(' ')),
+      ).toThrowErrorMatchingInlineSnapshot(`[Error: Invalid mnemonic]`)
+  })
+
+  test('behavior: agrees with the default for localized input', async () => {
+    const { toSeed } = await Mnemonic.engine()
+    const mnemonic = Array.from({ length: 12 }, () => 'あおぞら').join('　')
+    const passphrase = '㍍ガバヴァぱばぐゞちぢ十人十色'
+
+    expect(toSeed(mnemonic, passphrase)).toEqual(
+      mnemonicToSeedSync(mnemonic, passphrase),
+    )
+  })
+
+  test('behavior: rejects non-string mnemonics like the default', async () => {
+    const { toSeed } = await Mnemonic.engine()
+
+    expect(() => toSeed(1 as never)).toThrowErrorMatchingInlineSnapshot(
+      `[TypeError: invalid mnemonic type: number]`,
+    )
+  })
+
+  test('behavior: returns owned Uint8Array values', async () => {
+    const { toSeed } = await Mnemonic.engine()
+    const mnemonic = Array.from({ length: 12 }, () => 'word').join(' ')
+    const first = toSeed(mnemonic)
+    const second = toSeed(mnemonic)
+
+    expect(first.constructor === Uint8Array).toMatchInlineSnapshot('true')
+    expect(first === second).toMatchInlineSnapshot('false')
+    expect(first).toEqual(second)
+  })
+
+  test('behavior: returns a fresh engine', async () => {
+    const first = await Mnemonic.engine()
+    const second = await Mnemonic.engine()
+
+    expect(first === second).toMatchInlineSnapshot('false')
+  })
+})

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

@@ -0,0 +1,29 @@
+import { expectTypeOf, test } from 'vp/test'
+import type * as Engine from '../../core/Engine.js'
+import * as core_P256 from '../../core/P256.js'
+import * as NodeP256 from '../P256.js'
+
+type Slot = Awaited<ReturnType<typeof NodeP256.engine>>
+
+test('public-key derivation is present', () => {
+  expectTypeOf<Slot['getPublicKey']>().toEqualTypeOf<
+    (privateKey: Uint8Array) => Uint8Array
+  >()
+})
+
+test('unsupported primitives are absent', () => {
+  expectTypeOf<Slot>().not.toHaveProperty('getSharedSecret')
+  expectTypeOf<Slot>().not.toHaveProperty('randomSecretKey')
+  expectTypeOf<Slot>().not.toHaveProperty('recoverPublicKey')
+  expectTypeOf<Slot>().not.toHaveProperty('sign')
+  expectTypeOf<Slot>().not.toHaveProperty('verify')
+})
+
+test('the result is the raw slot', () => {
+  expectTypeOf<{ P256: Slot }>().toExtend<Engine.Engine>()
+})
+
+test('the Node namespace exposes the public P256 API', () => {
+  expectTypeOf(NodeP256.getPublicKey).toEqualTypeOf(core_P256.getPublicKey)
+  expectTypeOf<typeof NodeP256>().not.toHaveProperty('create')
+})

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

@@ -0,0 +1,102 @@
+import { p256 } from '@noble/curves/nist.js'
+import { Hex } from 'ox'
+import { describe, expect, test } from 'vp/test'
+import * as P256 from '../P256.js'
+
+const order = 'ffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551'
+
+describe('engine', () => {
+  test('behavior: exposes only public-key derivation', async () => {
+    const engine = await P256.engine()
+
+    expect(Object.keys(engine)).toMatchInlineSnapshot(`
+      [
+        "getPublicKey",
+      ]
+    `)
+  })
+
+  test('behavior: matches the SEC 2 generator vector', async () => {
+    const engine = await P256.engine()
+    const privateKey = new Uint8Array(32)
+    privateKey[31] = 1
+
+    expect(
+      Hex.fromBytes(engine.getPublicKey(privateKey)),
+    ).toMatchInlineSnapshot(
+      `"0x046b17d1f2e12c4247f8bce6e563a440f277037d812deb33a0f4a13945d898c2964fe342e2fe1a7f9b8ee7eb4a7c0f9e162bce33576b315ececbb6406837bf51f5"`,
+    )
+  })
+
+  test('behavior: matches the default across valid scalars', async () => {
+    const engine = await P256.engine()
+    const privateKeys = [
+      `${'00'.repeat(31)}01`,
+      `${'00'.repeat(31)}02`,
+      '7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff',
+      'dde57ae9b9ed6f76fa5358c24d5ca2057ebc1ece18b7273121450a29c96ec8e5',
+      'ffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632550',
+    ]
+
+    for (const privateKey of privateKeys) {
+      const bytes = fromHex(privateKey)
+      expect(engine.getPublicKey(bytes)).toEqual(
+        p256.getPublicKey(bytes, false),
+      )
+    }
+  })
+
+  test('behavior: respects typed-array offsets without mutating inputs', async () => {
+    const engine = await P256.engine()
+    const privateKey = offsetView(
+      fromHex(
+        'dde57ae9b9ed6f76fa5358c24d5ca2057ebc1ece18b7273121450a29c96ec8e5',
+      ),
+    )
+    const before = privateKey.slice()
+
+    expect(engine.getPublicKey(privateKey)).toEqual(
+      p256.getPublicKey(privateKey, false),
+    )
+    expect(privateKey).toEqual(before)
+  })
+
+  test('behavior: rejects malformed and out-of-range private keys', async () => {
+    const engine = await P256.engine()
+
+    for (const size of [0, 1, 31, 33, 64])
+      expect(() => engine.getPublicKey(new Uint8Array(size))).toThrowError(
+        `P256 private key must be 32 bytes, got ${size}`,
+      )
+
+    expect(() => engine.getPublicKey(new Uint8Array(32))).toThrowError()
+    expect(() => engine.getPublicKey(fromHex(order))).toThrowError()
+  })
+
+  test('behavior: returns owned Uint8Array values', async () => {
+    const engine = await P256.engine()
+    const privateKey = fromHex(`${'00'.repeat(31)}01`)
+    const first = engine.getPublicKey(privateKey)
+    const second = engine.getPublicKey(privateKey)
+
+    expect(first.constructor === Uint8Array).toMatchInlineSnapshot('true')
+    expect(first === second).toMatchInlineSnapshot('false')
+  })
+
+  test('behavior: returns a fresh engine', async () => {
+    const first = await P256.engine()
+    const second = await P256.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)
+}

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

@@ -0,0 +1,28 @@
+import { expectTypeOf, test } from 'vp/test'
+import type * as Engine from '../../core/Engine.js'
+import * as core_X25519 from '../../core/X25519.js'
+import * as NodeX25519 from '../X25519.js'
+
+type Slot = Awaited<ReturnType<typeof NodeX25519.engine>>
+
+test('every implemented primitive is present', () => {
+  expectTypeOf<Slot['getPublicKey']>().toEqualTypeOf<
+    (privateKey: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Slot['getSharedSecret']>().toEqualTypeOf<
+    (privateKey: Uint8Array, publicKey: Uint8Array) => Uint8Array
+  >()
+})
+
+test('unsupported primitives are absent', () => {
+  expectTypeOf<Slot>().not.toHaveProperty('randomSecretKey')
+})
+
+test('the result is the raw slot', () => {
+  expectTypeOf<{ X25519: Slot }>().toExtend<Engine.Engine>()
+})
+
+test('the Node namespace exposes the public X25519 API', () => {
+  expectTypeOf(NodeX25519.getPublicKey).toEqualTypeOf(core_X25519.getPublicKey)
+  expectTypeOf<typeof NodeX25519>().not.toHaveProperty('create')
+})