ox 1.1.2 → 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/_test/Engine.test-d.ts

@@ -10,6 +10,7 @@ test('install and engine expose the same precise engine', () => {
   expectTypeOf<Installed['Hash']['sha256']>().toEqualTypeOf<
     (input: Uint8Array) => Uint8Array
   >()
+  expectTypeOf<Installed['Keystore']>().not.toHaveProperty('scrypt')
 })
 
 test('the WASM Engine namespace exposes synchronous core operations', () => {

package/src/wasm/_test/Hash.browser.test.ts

@@ -44,6 +44,9 @@ describe('engine', () => {
   test('behavior: ox uses the WASM implementation once installed', async () => {
     await Engine.install({ Hash: WasmHash.engine() })
     try {
+      expect(Hash.blake3('0xdeadbeef')).toBe(
+        '0x53147f3ce49ed4f60dfa5b9654c36ba6103c11f5737df3dabd4cbd296c4161bd',
+      )
       expect(Hash.keccak256('0xdeadbeef')).toBe(
         '0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1',
       )

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

@@ -28,6 +28,7 @@ test('the result is the raw slot, so `Engine.install` accepts it', () => {
 })
 
 test('the WASM namespace exposes the public Hash API', () => {
+  expectTypeOf(WasmHash.blake3).toEqualTypeOf(CoreHash.blake3)
   expectTypeOf(WasmHash.sha256).toEqualTypeOf(CoreHash.sha256)
   expectTypeOf<typeof WasmHash>().not.toHaveProperty('create')
 })

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

@@ -292,8 +292,8 @@ describe('Engine.install', () => {
   test('behavior: ox uses the WASM implementation once installed', async () => {
     await Engine.install({ Hash: engine })
     try {
-      expect(Engine.get().Hash?.blake3?.(Bytes.from('0xdeadbeef'))).toEqual(
-        blake3(Bytes.from('0xdeadbeef')),
+      expect(Hash.blake3('0xdeadbeef')).toBe(
+        '0x53147f3ce49ed4f60dfa5b9654c36ba6103c11f5737df3dabd4cbd296c4161bd',
       )
       expect(Hash.keccak256('0xdeadbeef')).toBe(
         '0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1',

package/src/wasm/_test/Keystore.browser.test.ts

@@ -1,4 +1,5 @@
 import { pbkdf2 as pbkdf2_noble } from '@noble/hashes/pbkdf2.js'
+import { scrypt as scrypt_noble } from '@noble/hashes/scrypt.js'
 import { sha256 } from '@noble/hashes/sha2.js'
 import { describe, expect, test } from 'vp/test'
 import * as Bytes from '../../core/Bytes.js'
@@ -15,6 +16,9 @@ describe('engine', () => {
     expect(engine.pbkdf2Sha256(password, salt, { c: 3, dkLen: 65 })).toEqual(
       pbkdf2_noble(sha256, password, salt, { c: 3, dkLen: 65 }),
     )
+    expect(
+      engine.scrypt(password, salt, { N: 1024, dkLen: 65, p: 2, r: 1 }),
+    ).toEqual(scrypt_noble(password, salt, { N: 1024, dkLen: 65, p: 2, r: 1 }))
   })
 
   test('behavior: ox uses synchronous WASM PBKDF2 once installed', async () => {
@@ -39,4 +43,31 @@ describe('engine', () => {
       Engine.reset()
     }
   })
+
+  test('behavior: ox uses synchronous WASM scrypt once installed', async () => {
+    const engine = await WasmKeystore.engine()
+    await Engine.install({ Keystore: engine })
+    try {
+      const salt = new Uint8Array(32).fill(7)
+      const [key] = Keystore.scrypt({
+        n: 1024,
+        p: 2,
+        password: 'testpassword',
+        r: 1,
+        salt,
+      })
+      expect(key()).toBe(
+        Bytes.toHex(
+          scrypt_noble(Bytes.fromString('testpassword'), salt, {
+            N: 1024,
+            dkLen: 32,
+            p: 2,
+            r: 1,
+          }),
+        ),
+      )
+    } finally {
+      Engine.reset()
+    }
+  })
 })

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

@@ -1,5 +1,6 @@
 import { fc, test } from '@fast-check/vitest'
 import { pbkdf2 as pbkdf2_noble } from '@noble/hashes/pbkdf2.js'
+import { scrypt as scrypt_noble } from '@noble/hashes/scrypt.js'
 import { sha256 } from '@noble/hashes/sha2.js'
 import { beforeAll, describe, expect } from 'vp/test'
 import { numRuns } from '../../../test/fuzz/numRuns.js'
@@ -111,3 +112,52 @@ describe('pbkdf2Sha256', () => {
     expect(derived).toEqual(snapshot)
   })
 })
+
+describe('scrypt', () => {
+  test.prop(
+    {
+      dkLen: arbitraryDkLen,
+      logN: fc.integer({ max: 7, min: 1 }),
+      p: fc.integer({ max: 3, min: 1 }),
+      password: arbitraryPassword,
+      r: fc.integer({ max: 4, min: 1 }),
+      salt: arbitrarySalt,
+    },
+    { numRuns },
+  )(
+    'matches @noble/hashes for arbitrary parameters and inputs',
+    ({ dkLen, logN, p, password, r, salt }) => {
+      const options = { N: 2 ** logN, dkLen, p, r }
+      expect(keystore.scrypt(password, salt, options)).toEqual(
+        scrypt_noble(password, salt, options),
+      )
+    },
+  )
+
+  test.prop(
+    {
+      dkLen: arbitraryDkLen,
+      logN: fc.integer({ max: 7, min: 1 }),
+      p: fc.integer({ max: 3, min: 1 }),
+      password: arbitraryPassword,
+      r: fc.integer({ max: 4, min: 1 }),
+      salt: arbitrarySalt,
+    },
+    { numRuns },
+  )(
+    'handles subviews without mutating either backing buffer',
+    ({ dkLen, logN, p, password, r, salt }) => {
+      const password_ = asSubview(password)
+      const salt_ = asSubview(salt)
+      const passwordSnapshot = password_.backing.slice()
+      const saltSnapshot = salt_.backing.slice()
+      const options = { N: 2 ** logN, dkLen, p, r }
+
+      expect(keystore.scrypt(password_.view, salt_.view, options)).toEqual(
+        scrypt_noble(password_.view, salt_.view, options),
+      )
+      expect(password_.backing).toEqual(passwordSnapshot)
+      expect(salt_.backing).toEqual(saltSnapshot)
+    },
+  )
+})

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

@@ -15,11 +15,20 @@ test('synchronous PBKDF2 is present', () => {
   >()
 })
 
+test('synchronous scrypt is present', () => {
+  expectTypeOf<Slot['scrypt']>().toEqualTypeOf<
+    (
+      password: Uint8Array,
+      salt: Uint8Array,
+      options: { N: number; dkLen: number; p: number; r: number },
+    ) => Uint8Array
+  >()
+})
+
 test('unsupported primitives are absent', () => {
   expectTypeOf<Slot>().not.toHaveProperty('aesCtrDecrypt')
   expectTypeOf<Slot>().not.toHaveProperty('aesCtrEncrypt')
   expectTypeOf<Slot>().not.toHaveProperty('pbkdf2Sha256Async')
-  expectTypeOf<Slot>().not.toHaveProperty('scrypt')
   expectTypeOf<Slot>().not.toHaveProperty('scryptAsync')
 })