ox 1.0.5 → 1.1.2

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')
+})

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

@@ -0,0 +1,239 @@
+import * as fs from 'node:fs'
+import { x25519 } from '@noble/curves/ed25519.js'
+import { Hex } from 'ox'
+import { describe, expect, test } from 'vp/test'
+import * as X25519 from '../X25519.js'
+
+type LowOrderVector = {
+  name: string
+  publicKey: string
+}
+
+const alicePrivateKey =
+  '77076d0a7318a57d3c16c17251b26645df4c2f87ebc0992ab177fba51db92c2a'
+const bobPrivateKey =
+  '5dab087e624a8a4b79e17f8b83800ee66f3bb1292618b6fd1c2f8b27ff88e0eb'
+
+const lowOrderPublicKeys = JSON.parse(
+  fs.readFileSync(
+    new URL('../../../test/vectors/x25519/low-order.json', import.meta.url),
+    'utf8',
+  ),
+) as readonly LowOrderVector[]
+
+describe('engine', () => {
+  test('behavior: exposes only the supported primitives', async () => {
+    const engine = await X25519.engine()
+
+    expect(Object.keys(engine).sort()).toMatchInlineSnapshot(`
+      [
+        "getPublicKey",
+        "getSharedSecret",
+      ]
+    `)
+  })
+
+  test('behavior: matches RFC 7748 key-agreement vectors', async () => {
+    const engine = await X25519.engine()
+    const alicePublicKey = engine.getPublicKey(fromHex(alicePrivateKey))
+    const bobPublicKey = engine.getPublicKey(fromHex(bobPrivateKey))
+
+    expect({
+      alicePublicKey: Hex.fromBytes(alicePublicKey),
+      bobPublicKey: Hex.fromBytes(bobPublicKey),
+      sharedSecret: Hex.fromBytes(
+        engine.getSharedSecret(fromHex(alicePrivateKey), bobPublicKey),
+      ),
+    }).toMatchInlineSnapshot(`
+      {
+        "alicePublicKey": "0x8520f0098930a754748b7ddcb43ef75a0dbf3a0d26381af4eba4a98eaa9b4e6a",
+        "bobPublicKey": "0xde9edb7d7b7dc1b4d35b61c2ece435373f8343c85b78674dadfc7e146f882b4f",
+        "sharedSecret": "0x4a5d9d5ba4ce2de1728e3bf480350f25e07e21c947d19e3376f09b3c1e161742",
+      }
+    `)
+  })
+
+  test('behavior: matches RFC 7748 arbitrary-point vectors', async () => {
+    const engine = await X25519.engine()
+    const vectors = [
+      {
+        privateKey:
+          'a546e36bf0527c9d3b16154b82465edd62144c0ac1fc5a18506a2244ba449ac4',
+        publicKey:
+          'e6db6867583030db3594c1a424b15f7c726624ec26b3353b10a903a6d0ab1c4c',
+      },
+      {
+        privateKey:
+          '4b66e9d4d1b4673c5ad22691957d6af5c11b6421e0ea01d42ca4169e7918ba0d',
+        publicKey:
+          'e5210f12786811d3f4b7959d0538ae2c31dbe7106fc03c3efc4cd549c715a493',
+      },
+    ] as const
+
+    expect(
+      vectors.map(({ privateKey, publicKey }) =>
+        Hex.fromBytes(
+          engine.getSharedSecret(fromHex(privateKey), fromHex(publicKey)),
+        ),
+      ),
+    ).toMatchInlineSnapshot(`
+      [
+        "0xc3da55379de9c6908e94ea4df28d084f32eccf03491c71f754b4075577a28552",
+        "0x95cbde9476e8907d7aade45cb4b873f88b595a68799fa152e6f8f7647aac7957",
+      ]
+    `)
+  })
+
+  test('behavior: matches the default across private keys', async () => {
+    const engine = await X25519.engine()
+    const privateKeys = [
+      fromHex(alicePrivateKey),
+      fromHex(bobPrivateKey),
+      new Uint8Array(32),
+      new Uint8Array(32).fill(0xff),
+      Uint8Array.from({ length: 32 }, (_, index) => index),
+    ]
+
+    for (const [index, privateKey] of privateKeys.entries()) {
+      const peerPrivateKey = Uint8Array.from(
+        { length: 32 },
+        (_, offset) => (offset * 17 + index + 1) % 251,
+      )
+      const publicKey = x25519.getPublicKey(peerPrivateKey)
+      expect(engine.getPublicKey(privateKey)).toEqual(
+        x25519.getPublicKey(privateKey),
+      )
+      expect(engine.getSharedSecret(privateKey, publicKey)).toEqual(
+        x25519.getSharedSecret(privateKey, publicKey),
+      )
+    }
+  })
+
+  test('behavior: masks the public u-coordinate high bit', async () => {
+    const engine = await X25519.engine()
+    const privateKey = fromHex(alicePrivateKey)
+    const publicKey = x25519.getPublicKey(fromHex(bobPrivateKey))
+    const highBitPublicKey = publicKey.slice()
+    highBitPublicKey[31]! |= 0x80
+    const expected = x25519.getSharedSecret(privateKey, publicKey)
+
+    expect(x25519.getSharedSecret(privateKey, highBitPublicKey)).toEqual(
+      expected,
+    )
+    expect(engine.getSharedSecret(privateKey, highBitPublicKey)).toEqual(
+      expected,
+    )
+  })
+
+  test('behavior: reduces noncanonical public u-coordinates', async () => {
+    const engine = await X25519.engine()
+    const privateKey = fromHex(alicePrivateKey)
+    // 2^255 - 19 + 9 encodes the base point modulo the field prime.
+    const publicKey = fromHex(`f6${'ff'.repeat(30)}7f`)
+    const expected = x25519.getPublicKey(privateKey)
+
+    expect(x25519.getSharedSecret(privateKey, publicKey)).toEqual(expected)
+    expect(engine.getSharedSecret(privateKey, publicKey)).toEqual(expected)
+  })
+
+  test('behavior: rejects the complete published low-order set', async () => {
+    const engine = await X25519.engine()
+    const privateKey = fromHex(alicePrivateKey)
+
+    expect(lowOrderPublicKeys).toHaveLength(7)
+    for (const vector of lowOrderPublicKeys) {
+      const publicKey = fromHex(vector.publicKey)
+      const highBitPublicKey = publicKey.slice()
+      highBitPublicKey[31]! |= 0x80
+
+      for (const [name, value] of [
+        ['published', publicKey],
+        ['top-bit alias', highBitPublicKey],
+      ] as const) {
+        expect(
+          () => x25519.getSharedSecret(privateKey, value),
+          `${vector.name} (${name})`,
+        ).toThrowError()
+        expect(
+          () => engine.getSharedSecret(privateKey, value),
+          `${vector.name} (${name})`,
+        ).toThrowError()
+      }
+    }
+  })
+
+  test('behavior: respects typed-array offsets without mutating inputs', async () => {
+    const engine = await X25519.engine()
+    const privateKey = offsetView(fromHex(alicePrivateKey))
+    const publicKey = offsetView(x25519.getPublicKey(fromHex(bobPrivateKey)))
+    const privateKeyBefore = privateKey.slice()
+    const publicKeyBefore = publicKey.slice()
+
+    expect(engine.getPublicKey(privateKey)).toEqual(
+      x25519.getPublicKey(privateKey),
+    )
+    expect(engine.getSharedSecret(privateKey, publicKey)).toEqual(
+      x25519.getSharedSecret(privateKey, publicKey),
+    )
+    expect({ privateKey, publicKey }).toEqual({
+      privateKey: privateKeyBefore,
+      publicKey: publicKeyBefore,
+    })
+  })
+
+  test('behavior: rejects malformed key lengths', async () => {
+    const engine = await X25519.engine()
+    const privateKey = fromHex(alicePrivateKey)
+    const publicKey = x25519.getPublicKey(fromHex(bobPrivateKey))
+
+    for (const size of [0, 1, 31, 33, 64]) {
+      expect(() => engine.getPublicKey(new Uint8Array(size))).toThrowError(
+        `X25519 private key must be 32 bytes, got ${size}`,
+      )
+      expect(() =>
+        engine.getSharedSecret(new Uint8Array(size), publicKey),
+      ).toThrowError(`X25519 private key must be 32 bytes, got ${size}`)
+      expect(() =>
+        engine.getSharedSecret(privateKey, new Uint8Array(size)),
+      ).toThrowError(`X25519 public key must be 32 bytes, got ${size}`)
+    }
+  })
+
+  test('behavior: returns owned Uint8Array values', async () => {
+    const engine = await X25519.engine()
+    const privateKey = fromHex(alicePrivateKey)
+    const publicKey = x25519.getPublicKey(fromHex(bobPrivateKey))
+    const outputs = [
+      engine.getPublicKey(privateKey),
+      engine.getSharedSecret(privateKey, publicKey),
+    ]
+
+    expect(outputs.map((output) => output.constructor === Uint8Array))
+      .toMatchInlineSnapshot(`
+      [
+        true,
+        true,
+      ]
+    `)
+    expect(
+      engine.getPublicKey(privateKey) === engine.getPublicKey(privateKey),
+    ).toMatchInlineSnapshot('false')
+  })
+
+  test('behavior: returns a fresh engine', async () => {
+    const first = await X25519.engine()
+    const second = await X25519.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/index.ts

@@ -0,0 +1,132 @@
+/** @entrypointCategory Node */
+
+/**
+ * Node.js implementations of Ox's supported cryptographic primitives, backed
+ * by `node:crypto`.
+ *
+ * Import this entrypoint only in Node.js. Its static `node:crypto` dependency
+ * is intentionally kept outside Ox's runtime-neutral entrypoint.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine, Hash } from 'ox/node'
+ *
+ * await Engine.install()
+ *
+ * Hash.sha256('0xdeadbeef')
+ * ```
+ *
+ * @category Crypto
+ */
+export * as Engine from './Engine.js'
+
+/**
+ * Ox's Ed25519 API and its supported Node.js engine primitives.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Ed25519 } from 'ox/node'
+ *
+ * await Engine.install({ Ed25519: Ed25519.engine() })
+ *
+ * Ed25519.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @category Crypto
+ */
+export * as Ed25519 from './Ed25519.js'
+
+/**
+ * Ox's hash API and its supported Node.js engine primitives.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Hash } from 'ox/node'
+ *
+ * await Engine.install({ Hash: Hash.engine() })
+ *
+ * Hash.sha256('0xdeadbeef')
+ * ```
+ *
+ * @category Crypto
+ */
+export * as Hash from './Hash.js'
+
+/**
+ * Ox's keystore API and its supported Node.js engine primitives.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Keystore } from 'ox/node'
+ *
+ * await Engine.install({ Keystore: Keystore.engine() })
+ *
+ * Keystore.pbkdf2({ password: 'testpassword' })
+ * ```
+ *
+ * @category Crypto
+ */
+export * as Keystore from './Keystore.js'
+
+/**
+ * Ox's mnemonic API and its Node.js BIP-39 seed engine primitive.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Mnemonic } from 'ox/node'
+ *
+ * await Engine.install({ Mnemonic: Mnemonic.engine() })
+ *
+ * Mnemonic.toSeed(
+ *   'test test test test test test test test test test test junk'
+ * )
+ * ```
+ *
+ * @category Crypto
+ */
+export * as Mnemonic from './Mnemonic.js'
+
+/**
+ * Ox's P256 API and its Node.js public-key derivation engine primitive.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { P256 } from 'ox/node'
+ *
+ * await Engine.install({ P256: P256.engine() })
+ *
+ * P256.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @category Crypto
+ */
+export * as P256 from './P256.js'
+
+/**
+ * Ox's X25519 API and its supported Node.js engine primitives.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { X25519 } from 'ox/node'
+ *
+ * await Engine.install({ X25519: X25519.engine() })
+ *
+ * X25519.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @category Crypto
+ */
+export * as X25519 from './X25519.js'