ox 1.1.0 → 1.2.0

package/src/wasm/Secp256k1.ts

@@ -0,0 +1,248 @@
+import type * as Engine from '../core/Engine.js'
+import * as Errors from '../core/Errors.js'
+import * as internal from './internal/instantiate.js'
+import * as secp256k1 from './internal/secp256k1.js'
+
+export * from '../core/Secp256k1.js'
+export { MemoryError } from './internal/instantiate.js'
+
+const privateKeySize = 32
+const publicKeySize = 65
+const sharedSecretSize = 33
+const compactSignatureSize = 64
+const recoveredSignatureSize = 65
+const maxRawMessageSize = 8192
+
+/**
+ * Compiles WASM implementations of deterministic
+ * [`Secp256k1`](/api/Secp256k1) primitives, without installing them.
+ *
+ * Random key generation remains on Ox's host-backed default implementation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Secp256k1 } from 'ox/wasm'
+ *
+ * await Engine.install({ Secp256k1: Secp256k1.engine() })
+ *
+ * Secp256k1.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @returns The WASM implementation of the deterministic `Secp256k1` primitives.
+ */
+export async function engine(): Promise<engine.ReturnType> {
+  const module = await secp256k1.load()
+
+  return {
+    getPublicKey(privateKey) {
+      assertLength(privateKey, privateKeySize, 'private key')
+      const size = privateKeySize + publicKeySize
+      module.reserve(size)
+      const privateKeyPtr = module.heapBase
+      const publicKeyPtr = privateKeyPtr + privateKeySize
+      try {
+        module.view().set(privateKey, privateKeyPtr)
+        if (
+          module.exports.secp256k1_get_public_key(
+            privateKeyPtr,
+            publicKeyPtr,
+          ) !== 1
+        )
+          throw new InvalidInputError({ operation: 'getPublicKey' })
+        return module.view().slice(publicKeyPtr, publicKeyPtr + publicKeySize)
+      } finally {
+        module.exports.zero(privateKeyPtr, size)
+      }
+    },
+    getSharedSecret(privateKey, publicKey) {
+      assertLength(privateKey, privateKeySize, 'private key')
+      assertPublicKeyLength(publicKey)
+      const size = privateKeySize + publicKey.length + sharedSecretSize
+      module.reserve(size)
+      const privateKeyPtr = module.heapBase
+      const publicKeyPtr = privateKeyPtr + privateKeySize
+      const sharedSecretPtr = publicKeyPtr + publicKey.length
+      try {
+        const memory = module.view()
+        memory.set(privateKey, privateKeyPtr)
+        memory.set(publicKey, publicKeyPtr)
+        if (
+          module.exports.secp256k1_get_shared_secret(
+            privateKeyPtr,
+            publicKeyPtr,
+            publicKey.length,
+            sharedSecretPtr,
+          ) !== 1
+        )
+          throw new InvalidInputError({ operation: 'getSharedSecret' })
+        return module
+          .view()
+          .slice(sharedSecretPtr, sharedSecretPtr + sharedSecretSize)
+      } finally {
+        module.exports.zero(privateKeyPtr, size)
+      }
+    },
+    recoverPublicKey(signature, payload) {
+      assertLength(signature, recoveredSignatureSize, 'signature')
+      assertRawMessageLength(payload)
+      const size = recoveredSignatureSize + payload.length + publicKeySize
+      module.reserve(size)
+      const signaturePtr = module.heapBase
+      const payloadPtr = signaturePtr + recoveredSignatureSize
+      const publicKeyPtr = payloadPtr + payload.length
+      try {
+        const memory = module.view()
+        memory.set(signature, signaturePtr)
+        memory.set(payload, payloadPtr)
+        if (
+          module.exports.secp256k1_recover_public_key(
+            signaturePtr,
+            payloadPtr,
+            payload.length,
+            publicKeyPtr,
+          ) !== 1
+        )
+          throw new InvalidInputError({ operation: 'recoverPublicKey' })
+        return module.view().slice(publicKeyPtr, publicKeyPtr + publicKeySize)
+      } finally {
+        module.exports.zero(signaturePtr, size)
+      }
+    },
+    sign(payload, privateKey, options) {
+      assertLength(privateKey, privateKeySize, 'private key')
+      if (!options.prehash) assertRawMessageLength(payload)
+      const entropy =
+        options.extraEntropy === true
+          ? crypto.getRandomValues(new Uint8Array(privateKeySize))
+          : options.extraEntropy === false
+            ? undefined
+            : options.extraEntropy
+      const entropySize = entropy?.length ?? 0
+      const size =
+        payload.length + privateKeySize + entropySize + recoveredSignatureSize
+      module.reserve(size)
+      const payloadPtr = module.heapBase
+      const privateKeyPtr = payloadPtr + payload.length
+      const entropyPtr = entropy ? privateKeyPtr + privateKeySize : 0
+      const signaturePtr = privateKeyPtr + privateKeySize + entropySize
+      try {
+        const memory = module.view()
+        memory.set(payload, payloadPtr)
+        memory.set(privateKey, privateKeyPtr)
+        if (entropy) memory.set(entropy, entropyPtr)
+        if (
+          module.exports.secp256k1_sign(
+            payloadPtr,
+            payload.length,
+            privateKeyPtr,
+            entropyPtr,
+            entropySize,
+            Number(options.prehash),
+            signaturePtr,
+          ) !== 1
+        )
+          throw new InvalidInputError({ operation: 'sign' })
+        return module
+          .view()
+          .slice(signaturePtr, signaturePtr + recoveredSignatureSize)
+      } finally {
+        module.exports.zero(payloadPtr, size)
+      }
+    },
+    verify(signature, payload, publicKey, options) {
+      assertLength(signature, compactSignatureSize, 'signature')
+      assertPublicKeyLength(publicKey)
+      if (!options.prehash && payload.length > maxRawMessageSize) return false
+      const size = compactSignatureSize + payload.length + publicKey.length
+      module.reserve(size)
+      const signaturePtr = module.heapBase
+      const payloadPtr = signaturePtr + compactSignatureSize
+      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.secp256k1_verify(
+            signaturePtr,
+            payloadPtr,
+            payload.length,
+            publicKeyPtr,
+            publicKey.length,
+            Number(options.prehash),
+          ) === 1
+        )
+      } finally {
+        module.exports.zero(signaturePtr, size)
+      }
+    },
+  }
+}
+
+export declare namespace engine {
+  /** Every `Secp256k1` primitive this module implements. */
+  type ReturnType = {
+    [key in
+      | 'getPublicKey'
+      | 'getSharedSecret'
+      | 'recoverPublicKey'
+      | 'sign'
+      | 'verify']-?: NonNullable<Engine.Ecdsa[key]>
+  }
+
+  type ErrorType =
+    | InvalidInputError
+    | internal.MemoryError
+    | Errors.GlobalErrorType
+}
+
+function assertLength(value: Uint8Array, length: number, name: string): void {
+  if (value.length !== length)
+    throw new RangeError(
+      `Secp256k1 ${name} must be ${length} bytes, got ${value.length}`,
+    )
+}
+
+function assertPublicKeyLength(publicKey: Uint8Array): void {
+  if (
+    publicKey.length !== sharedSecretSize &&
+    publicKey.length !== publicKeySize
+  )
+    throw new RangeError(
+      `Secp256k1 public key must be 33 or 65 bytes, got ${publicKey.length}`,
+    )
+}
+
+function assertRawMessageLength(payload: Uint8Array): void {
+  if (payload.length > maxRawMessageSize)
+    throw new RangeError(
+      `Secp256k1 unhashed payload must not exceed ${maxRawMessageSize} bytes, got ${payload.length}`,
+    )
+}
+
+/**
+ * Thrown when libsecp256k1 rejects a key or recovered signature.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Secp256k1 } from 'ox/wasm'
+ *
+ * try {
+ *   const engine = await Secp256k1.engine()
+ *   engine.getPublicKey(new Uint8Array(32))
+ * } catch (error) {
+ *   if (error instanceof Secp256k1.InvalidInputError)
+ *     console.error(error.message)
+ * }
+ * ```
+ */
+export class InvalidInputError extends Errors.BaseError {
+  override readonly name = 'Secp256k1.InvalidInputError'
+
+  constructor({ operation }: { operation: string }) {
+    super(`WASM secp256k1 ${operation} received invalid input.`)
+  }
+}

package/src/wasm/X25519.ts

@@ -0,0 +1,70 @@
+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 internal from './internal/instantiate.js'
+import * as x25519 from './internal/x25519.js'
+
+export * from '../core/X25519.js'
+export { MemoryError } from './internal/instantiate.js'
+
+const keySize = 32
+
+/**
+ * Compiles WASM implementations of selected [`X25519`](/api/X25519)
+ * primitives, without installing them.
+ *
+ * Random key generation remains on Ox's default implementation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { X25519 } from 'ox/wasm'
+ *
+ * await Engine.install({ X25519: X25519.engine() })
+ *
+ * X25519.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @returns The WASM implementation of part of the `X25519` slot.
+ */
+export async function engine(): Promise<engine.ReturnType> {
+  const module = await crypto25519.load()
+
+  return {
+    getPublicKey(privateKey) {
+      assertLength(privateKey, 'private')
+      module.reserve(keySize * 2)
+      const privateKeyPtr = module.heapBase
+      const publicKeyPtr = privateKeyPtr + keySize
+      try {
+        module.view().set(privateKey, privateKeyPtr)
+        module.exports.x25519_get_public_key(privateKeyPtr, publicKeyPtr)
+        return module.view().slice(publicKeyPtr, publicKeyPtr + keySize)
+      } finally {
+        module.exports.zero(privateKeyPtr, keySize * 2)
+      }
+    },
+    getSharedSecret(privateKey, publicKey) {
+      assertLength(privateKey, 'private')
+      assertLength(publicKey, 'public')
+      return x25519.getSharedSecret(module, privateKey, publicKey)
+    },
+  }
+}
+
+export declare namespace engine {
+  /** Every `X25519` primitive this module implements. */
+  type ReturnType = {
+    [key in 'getPublicKey' | 'getSharedSecret']-?: NonNullable<Engine.Ecdh[key]>
+  }
+
+  type ErrorType = internal.MemoryError | Errors.GlobalErrorType
+}
+
+function assertLength(key: Uint8Array, type: 'private' | 'public'): void {
+  if (key.length !== keySize)
+    throw new RangeError(
+      `X25519 ${type} key must be ${keySize} bytes, got ${key.length}`,
+    )
+}

package/src/wasm/_test/Crypto25519.conformance.ts

@@ -0,0 +1,57 @@
+import { ed25519, x25519 } from '@noble/curves/ed25519.js'
+import { mnemonicToSeedSync } from '@scure/bip39'
+import { describe, expect, test } from 'vp/test'
+import { vectors } from '../../../test/vectors/bip39/index.js'
+import * as Ed25519 from '../Ed25519.js'
+import * as Mnemonic from '../Mnemonic.js'
+import * as X25519 from '../X25519.js'
+
+describe('crypto25519 WASM', () => {
+  test('behavior: Ed25519 works in this runtime', async () => {
+    const engine = await Ed25519.engine()
+    const privateKey = fromHex(
+      '9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60',
+    )
+    const payload = new TextEncoder().encode('browser conformance')
+    const publicKey = engine.getPublicKey(privateKey)
+    const signature = engine.sign(payload, privateKey)
+
+    expect(publicKey).toEqual(ed25519.getPublicKey(privateKey))
+    expect(signature).toEqual(ed25519.sign(payload, privateKey))
+    expect(engine.verify(signature, payload, publicKey)).toBe(true)
+  })
+
+  test('behavior: X25519 works in this runtime', async () => {
+    const engine = await X25519.engine()
+    const privateKey = fromHex(
+      '77076d0a7318a57d3c16c17251b26645df4c2f87ebc0992ab177fba51db92c2a',
+    )
+    const peerPrivateKey = fromHex(
+      '5dab087e624a8a4b79e17f8b83800ee66f3bb1292618b6fd1c2f8b27ff88e0eb',
+    )
+    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: Unicode BIP-39 works in this runtime', async () => {
+    const engine = await Mnemonic.engine()
+    const vector = vectors.japanese
+
+    expect(engine.toSeed(vector.mnemonic, vector.passphrase)).toEqual(
+      mnemonicToSeedSync(vector.mnemonic, vector.passphrase),
+    )
+  })
+})
+
+function fromHex(value: string): Uint8Array {
+  const bytes = new Uint8Array(value.length / 2)
+  for (let index = 0; index < bytes.length; index++)
+    bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16)
+  return bytes
+}

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

@@ -0,0 +1,187 @@
+import { fc, test } from '@fast-check/vitest'
+import { ed25519, x25519 } from '@noble/curves/ed25519.js'
+import { mnemonicToSeedSync } from '@scure/bip39'
+import { beforeAll, describe, expect } from 'vp/test'
+import { numRuns } from '../../../test/fuzz/numRuns.js'
+import * as Ed25519 from '../Ed25519.js'
+import * as Mnemonic from '../Mnemonic.js'
+import * as X25519 from '../X25519.js'
+import { x25519LowOrder } from './fixtures.js'
+
+let ed25519Engine: Ed25519.engine.ReturnType
+let mnemonicEngine: Mnemonic.engine.ReturnType
+let x25519Engine: X25519.engine.ReturnType
+
+beforeAll(async () => {
+  ed25519Engine = await Ed25519.engine()
+  mnemonicEngine = await Mnemonic.engine()
+  x25519Engine = await X25519.engine()
+})
+
+const arbitraryKey = fc.uint8Array({ maxLength: 32, minLength: 32 })
+const arbitraryPayload = fc.oneof(
+  fc.uint8Array({ maxLength: 512 }),
+  fc
+    .constantFrom(0, 1, 31, 32, 63, 64, 65, 127, 128, 129, 1024, 4096)
+    .chain((size) => fc.uint8Array({ maxLength: size, minLength: size })),
+)
+const arbitraryWord = fc.oneof(
+  fc
+    .string({ maxLength: 16, minLength: 1 })
+    .filter((value) => !value.normalize('NFKD').includes(' ')),
+  fc.constantFrom('café', 'cafe\u0301', 'あおぞら', '㍍ガバヴァ'),
+)
+const arbitraryMnemonic = fc
+  .tuple(
+    fc.constantFrom(12, 15, 18, 21, 24),
+    fc.array(arbitraryWord, { maxLength: 24, minLength: 24 }),
+  )
+  .map(([count, words]) => words.slice(0, count).join(' '))
+
+describe('Ed25519', () => {
+  test.prop(
+    { payload: arbitraryPayload, privateKey: arbitraryKey },
+    { numRuns },
+  )('matches the default for arbitrary subviews', (options) => {
+    const payload = offsetView(options.payload)
+    const privateKey = offsetView(options.privateKey)
+    const publicKey = ed25519Engine.getPublicKey(privateKey)
+    const signature = ed25519Engine.sign(payload, privateKey)
+
+    expect(publicKey).toEqual(ed25519.getPublicKey(privateKey))
+    expect(signature).toEqual(ed25519.sign(payload, privateKey))
+    expect(ed25519Engine.verify(signature, payload, publicKey)).toBe(true)
+    expect(
+      ed25519Engine.verify(signature, Uint8Array.of(...payload, 1), publicKey),
+    ).toBe(false)
+    expect(ed25519Engine.toMontgomerySecret(privateKey)).toEqual(
+      ed25519.utils.toMontgomerySecret(privateKey),
+    )
+  })
+
+  test.prop(
+    {
+      payload: arbitraryPayload,
+      publicKey: arbitraryKey,
+      signature: fc.uint8Array({ maxLength: 64, minLength: 64 }),
+    },
+    { numRuns },
+  )('verification matches ZIP-215 for arbitrary encodings', (options) => {
+    expect(
+      ed25519Engine.verify(
+        options.signature,
+        options.payload,
+        options.publicKey,
+      ),
+    ).toBe(
+      ed25519.verify(options.signature, options.payload, options.publicKey),
+    )
+  })
+})
+
+describe('X25519', () => {
+  test.prop(
+    { privateKey: arbitraryKey, publicKeySeed: arbitraryKey },
+    { numRuns },
+  )('matches the default for arbitrary subviews', (options) => {
+    const privateKey = offsetView(options.privateKey)
+    const publicKey = offsetView(x25519.getPublicKey(options.publicKeySeed))
+
+    expect(x25519Engine.getPublicKey(privateKey)).toEqual(
+      x25519.getPublicKey(privateKey),
+    )
+    expect(x25519Engine.getSharedSecret(privateKey, publicKey)).toEqual(
+      x25519.getSharedSecret(privateKey, publicKey),
+    )
+  })
+
+  test.prop(
+    {
+      highBit: fc.boolean(),
+      privateKey: arbitraryKey,
+      vector: fc.constantFrom(...x25519LowOrder),
+    },
+    { numRuns },
+  )(
+    'rejects arbitrary private keys paired with low-order points',
+    (options) => {
+      const publicKey = fromHex(options.vector.publicKey)
+      if (options.highBit) publicKey[31]! |= 0x80
+      expect(() =>
+        x25519Engine.getSharedSecret(options.privateKey, publicKey),
+      ).toThrow()
+    },
+  )
+})
+
+describe('Mnemonic', () => {
+  test.prop(
+    {
+      mnemonic: arbitraryMnemonic,
+      passphrase: fc.string({ maxLength: 64 }),
+    },
+    { numRuns },
+  )('matches the default for arbitrary normalized text', (options) => {
+    expect(mnemonicEngine.toSeed(options.mnemonic, options.passphrase)).toEqual(
+      mnemonicToSeedSync(options.mnemonic, options.passphrase),
+    )
+  })
+})
+
+describe('memory', () => {
+  test.prop(
+    {
+      operations: fc.array(
+        fc.record({
+          payload: arbitraryPayload,
+          privateKey: arbitraryKey,
+          publicKeySeed: arbitraryKey,
+        }),
+        { maxLength: 8, minLength: 2 },
+      ),
+    },
+    { numRuns },
+  )(
+    'interleaved providers remain isolated and outputs stay owned',
+    (options) => {
+      const held: Uint8Array[] = []
+      const snapshots: Uint8Array[] = []
+
+      for (const operation of options.operations) {
+        const edPublicKey = ed25519Engine.getPublicKey(operation.privateKey)
+        const signature = ed25519Engine.sign(
+          operation.payload,
+          operation.privateKey,
+        )
+        const xPublicKey = x25519.getPublicKey(operation.publicKeySeed)
+        const sharedSecret = x25519Engine.getSharedSecret(
+          operation.privateKey,
+          xPublicKey,
+        )
+        expect(
+          ed25519Engine.verify(signature, operation.payload, edPublicKey),
+        ).toBe(true)
+        expect(sharedSecret).toEqual(
+          x25519.getSharedSecret(operation.privateKey, xPublicKey),
+        )
+        held.push(signature, sharedSecret)
+        snapshots.push(signature.slice(), sharedSecret.slice())
+      }
+
+      expect(held).toEqual(snapshots)
+    },
+  )
+})
+
+function offsetView(value: Uint8Array): Uint8Array {
+  const bytes = new Uint8Array(value.length + 4).fill(0xff)
+  bytes.set(value, 2)
+  return bytes.subarray(2, -2)
+}
+
+function fromHex(value: string): Uint8Array {
+  const bytes = new Uint8Array(value.length / 2)
+  for (let index = 0; index < bytes.length; index++)
+    bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16)
+  return bytes
+}

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

@@ -0,0 +1,28 @@
+import { expectTypeOf, test } from 'vp/test'
+import type * as Engine from '../../core/Engine.js'
+import * as core_Ed25519 from '../../core/Ed25519.js'
+import * as Ed25519 from '../Ed25519.js'
+
+type Slot = Awaited<ReturnType<typeof Ed25519.engine>>
+
+test('return type exposes only implemented Ed25519 primitives', () => {
+  expectTypeOf<Slot['getPublicKey']>().toEqualTypeOf<
+    NonNullable<Engine.Eddsa['getPublicKey']>
+  >()
+  expectTypeOf<Slot['sign']>().toEqualTypeOf<
+    NonNullable<Engine.Eddsa['sign']>
+  >()
+  expectTypeOf<Slot['toMontgomerySecret']>().toEqualTypeOf<
+    NonNullable<Engine.Eddsa['toMontgomerySecret']>
+  >()
+  expectTypeOf<Slot['verify']>().toEqualTypeOf<
+    NonNullable<Engine.Eddsa['verify']>
+  >()
+  expectTypeOf<Slot>().not.toHaveProperty('randomSecretKey')
+  expectTypeOf<Slot>().not.toHaveProperty('toMontgomery')
+})
+
+test('the WASM namespace exposes the public Ed25519 API', () => {
+  expectTypeOf(Ed25519.getPublicKey).toEqualTypeOf(core_Ed25519.getPublicKey)
+  expectTypeOf<typeof Ed25519>().not.toHaveProperty('create')
+})