ox 1.1.0 → 1.1.2

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

@@ -1,7 +1,8 @@
 /** @entrypointCategory Node */
 
 /**
- * Node.js implementations of Ox's hash primitives, backed by `node:crypto`.
+ * 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.
@@ -9,10 +10,9 @@
  * @example
  * ```ts twoslash
  * // @noErrors
- * import { Hash } from 'ox'
- * import { Engine } from 'ox/node'
+ * import { Engine, Hash } from 'ox/node'
  *
- * await Engine.load()
+ * await Engine.install()
  *
  * Hash.sha256('0xdeadbeef')
  * ```
@@ -22,15 +22,33 @@
 export * as Engine from './Engine.js'
 
 /**
- * Node.js implementations of Ox's supported hash primitives.
+ * Ox's Ed25519 API and its supported Node.js engine primitives.
  *
  * @example
  * ```ts twoslash
  * // @noErrors
- * import { Engine, Hash } from 'ox'
- * import * as NodeHash from 'ox/node/Hash'
+ * import { Engine } from 'ox'
+ * import { Ed25519 } from 'ox/node'
  *
- * Engine.set(await NodeHash.create())
+ * 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')
  * ```
@@ -38,3 +56,77 @@ export * as Engine from './Engine.js'
  * @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'

package/src/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '1.1.0'
+export const version = '1.1.2'

package/src/wasm/Ed25519.ts

@@ -0,0 +1,114 @@
+import type * as Engine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+import * as crypto25519 from './internal/crypto25519.js'
+import * as ed25519 from './internal/ed25519.js'
+import * as internal from './internal/instantiate.js'
+
+export * from '../core/Ed25519.js'
+export { MemoryError } from './internal/instantiate.js'
+
+const keySize = 32
+const signatureSize = 64
+
+/**
+ * Compiles WASM implementations of selected [`Ed25519`](/api/Ed25519)
+ * primitives, without installing them.
+ *
+ * Public-key conversion and random key generation remain on Ox's default
+ * implementation. The public conversion is omitted because Monocypher does not
+ * reproduce Ox's invalid-point validation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Ed25519 } from 'ox/wasm'
+ *
+ * await Engine.install({ Ed25519: Ed25519.engine() })
+ *
+ * Ed25519.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @returns The WASM implementation of part of the `Ed25519` slot.
+ */
+export async function engine(): Promise<engine.ReturnType> {
+  const module = await crypto25519.load()
+
+  return {
+    getPublicKey(privateKey) {
+      assertLength(privateKey, keySize, 'private key')
+      module.reserve(keySize * 2)
+      const privateKeyPtr = module.heapBase
+      const publicKeyPtr = privateKeyPtr + keySize
+      try {
+        module.view().set(privateKey, privateKeyPtr)
+        module.exports.ed25519_get_public_key(privateKeyPtr, publicKeyPtr)
+        return module.view().slice(publicKeyPtr, publicKeyPtr + keySize)
+      } finally {
+        module.exports.zero(privateKeyPtr, keySize * 2)
+      }
+    },
+    sign(payload, privateKey) {
+      assertLength(privateKey, keySize, 'private key')
+      return ed25519.sign(module, payload, privateKey)
+    },
+    toMontgomerySecret(privateKey) {
+      assertLength(privateKey, keySize, 'private key')
+      module.reserve(keySize * 2)
+      const privateKeyPtr = module.heapBase
+      const secretKeyPtr = privateKeyPtr + keySize
+      try {
+        module.view().set(privateKey, privateKeyPtr)
+        module.exports.ed25519_to_montgomery_secret(privateKeyPtr, secretKeyPtr)
+        return module.view().slice(secretKeyPtr, secretKeyPtr + keySize)
+      } finally {
+        module.exports.zero(privateKeyPtr, keySize * 2)
+      }
+    },
+    verify(signature, payload, publicKey) {
+      assertLength(signature, signatureSize, 'signature')
+      assertLength(publicKey, keySize, 'public key')
+      const size = signatureSize + payload.length + keySize
+      module.reserve(size)
+      const signaturePtr = module.heapBase
+      const payloadPtr = signaturePtr + signatureSize
+      const publicKeyPtr = payloadPtr + payload.length
+      try {
+        const memory = module.view()
+        memory.set(signature, signaturePtr)
+        memory.set(payload, payloadPtr)
+        memory.set(publicKey, publicKeyPtr)
+        return (
+          module.exports.ed25519_verify(
+            signaturePtr,
+            payloadPtr,
+            payload.length,
+            publicKeyPtr,
+          ) === 1
+        )
+      } finally {
+        module.exports.zero(signaturePtr, size)
+      }
+    },
+  }
+}
+
+export declare namespace engine {
+  /** Every `Ed25519` primitive this module implements. */
+  type ReturnType = {
+    [key in
+      | 'getPublicKey'
+      | 'sign'
+      | 'toMontgomerySecret'
+      | 'verify']-?: NonNullable<Engine.Eddsa[key]>
+  }
+
+  type ErrorType = internal.MemoryError | Errors.GlobalErrorType
+}
+
+function assertLength(value: Uint8Array, length: number, name: string): void {
+  if (value.length !== length)
+    throw new RangeError(
+      `Ed25519 ${name} must be ${length} bytes, got ${value.length}`,
+    )
+}