ox 1.0.4 → 1.1.0

package/src/core/internal/hash.ts

@@ -0,0 +1,48 @@
+import { blake3 as noble_blake3 } from '@noble/hashes/blake3.js'
+import { hmac } from '@noble/hashes/hmac.js'
+import { ripemd160 as noble_ripemd160 } from '@noble/hashes/legacy.js'
+import { sha256 as noble_sha256 } from '@noble/hashes/sha2.js'
+import { keccak_256 as noble_keccak256 } from '@noble/hashes/sha3.js'
+import { type Complete, type Hash, overrides } from './engine.js'
+
+/**
+ * Resolvers for the `Hash` slot, and ox's defaults for it, backed by
+ * `@noble/hashes`.
+ *
+ * Declaring the defaults against the slot contract is what keeps them honest: a
+ * default that goes missing, or whose signature drifts, fails to compile rather
+ * than failing at the call site.
+ */
+
+const blake3Default: Complete<Hash>['blake3'] = (input) => noble_blake3(input)
+
+const hmacSha256Default: Complete<Hash>['hmacSha256'] = (key, message) =>
+  hmac(noble_sha256, key, message)
+
+const keccak256Default: Complete<Hash>['keccak256'] = (input) =>
+  noble_keccak256(input)
+
+const ripemd160Default: Complete<Hash>['ripemd160'] = (input) =>
+  noble_ripemd160(input)
+
+const sha256Default: Complete<Hash>['sha256'] = (input) => noble_sha256(input)
+
+/** @internal */
+export const blake3: Complete<Hash>['blake3'] = (input) =>
+  (overrides.Hash?.blake3 ?? blake3Default)(input)
+
+/** @internal */
+export const hmacSha256: Complete<Hash>['hmacSha256'] = (key, message) =>
+  (overrides.Hash?.hmacSha256 ?? hmacSha256Default)(key, message)
+
+/** @internal */
+export const keccak256: Complete<Hash>['keccak256'] = (input) =>
+  (overrides.Hash?.keccak256 ?? keccak256Default)(input)
+
+/** @internal */
+export const ripemd160: Complete<Hash>['ripemd160'] = (input) =>
+  (overrides.Hash?.ripemd160 ?? ripemd160Default)(input)
+
+/** @internal */
+export const sha256: Complete<Hash>['sha256'] = (input) =>
+  (overrides.Hash?.sha256 ?? sha256Default)(input)

package/src/core/internal/keystore.ts

@@ -0,0 +1,107 @@
+import { ctr } from '@noble/ciphers/aes.js'
+import {
+  pbkdf2 as pbkdf2_noble,
+  pbkdf2Async as pbkdf2Async_noble,
+} from '@noble/hashes/pbkdf2.js'
+import {
+  scrypt as scrypt_noble,
+  scryptAsync as scryptAsync_noble,
+} from '@noble/hashes/scrypt.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { type Complete, type Keystore, overrides } from './engine.js'
+
+/**
+ * Resolvers for the `Keystore` slot, and ox's defaults for it, backed by
+ * `@noble/ciphers` and `@noble/hashes`.
+ *
+ * Declaring the defaults against the slot contract is what keeps them honest: a
+ * default that goes missing, or whose signature drifts, fails to compile rather
+ * than failing at the call site.
+ */
+
+const aesCtrDecryptDefault: Complete<Keystore>['aesCtrDecrypt'] = (
+  key,
+  iv,
+  data,
+) => ctr(key, iv).decrypt(data)
+
+const aesCtrEncryptDefault: Complete<Keystore>['aesCtrEncrypt'] = (
+  key,
+  iv,
+  data,
+) => ctr(key, iv).encrypt(data)
+
+const pbkdf2Sha256Default: Complete<Keystore>['pbkdf2Sha256'] = (
+  password,
+  salt,
+  options,
+) => pbkdf2_noble(sha256, password, salt, options)
+
+const pbkdf2Sha256AsyncDefault: Complete<Keystore>['pbkdf2Sha256Async'] = (
+  password,
+  salt,
+  options,
+) => pbkdf2Async_noble(sha256, password, salt, options)
+
+const scryptDefault: Complete<Keystore>['scrypt'] = (password, salt, options) =>
+  scrypt_noble(password, salt, options)
+
+const scryptAsyncDefault: Complete<Keystore>['scryptAsync'] = (
+  password,
+  salt,
+  options,
+) => scryptAsync_noble(password, salt, options)
+
+/** @internal */
+export const aesCtrDecrypt: Complete<Keystore>['aesCtrDecrypt'] = (
+  key,
+  iv,
+  data,
+) => (overrides.Keystore?.aesCtrDecrypt ?? aesCtrDecryptDefault)(key, iv, data)
+
+/** @internal */
+export const aesCtrEncrypt: Complete<Keystore>['aesCtrEncrypt'] = (
+  key,
+  iv,
+  data,
+) => (overrides.Keystore?.aesCtrEncrypt ?? aesCtrEncryptDefault)(key, iv, data)
+
+/** @internal */
+export const pbkdf2Sha256: Complete<Keystore>['pbkdf2Sha256'] = (
+  password,
+  salt,
+  options,
+) =>
+  (overrides.Keystore?.pbkdf2Sha256 ?? pbkdf2Sha256Default)(
+    password,
+    salt,
+    options,
+  )
+
+/** @internal */
+export const pbkdf2Sha256Async: Complete<Keystore>['pbkdf2Sha256Async'] = (
+  password,
+  salt,
+  options,
+) =>
+  (overrides.Keystore?.pbkdf2Sha256Async ?? pbkdf2Sha256AsyncDefault)(
+    password,
+    salt,
+    options,
+  )
+
+/** @internal */
+export const scrypt: Complete<Keystore>['scrypt'] = (password, salt, options) =>
+  (overrides.Keystore?.scrypt ?? scryptDefault)(password, salt, options)
+
+/** @internal */
+export const scryptAsync: Complete<Keystore>['scryptAsync'] = (
+  password,
+  salt,
+  options,
+) =>
+  (overrides.Keystore?.scryptAsync ?? scryptAsyncDefault)(
+    password,
+    salt,
+    options,
+  )

package/src/core/internal/mnemonic.ts

@@ -0,0 +1,18 @@
+import { mnemonicToSeedSync } from '@scure/bip39'
+import { type Complete, type Mnemonic, overrides } from './engine.js'
+
+/**
+ * Resolvers for the `Mnemonic` slot, and ox's defaults for it, backed by
+ * `@scure/bip39`.
+ *
+ * Declaring the defaults against the slot contract is what keeps them honest: a
+ * default that goes missing, or whose signature drifts, fails to compile rather
+ * than failing at the call site.
+ */
+
+const toSeedDefault: Complete<Mnemonic>['toSeed'] = (mnemonic, passphrase) =>
+  mnemonicToSeedSync(mnemonic, passphrase)
+
+/** @internal */
+export const toSeed: Complete<Mnemonic>['toSeed'] = (mnemonic, passphrase) =>
+  (overrides.Mnemonic?.toSeed ?? toSeedDefault)(mnemonic, passphrase)

package/src/core/internal/p256.ts

@@ -0,0 +1,91 @@
+import { p256 } from '@noble/curves/nist.js'
+import { type Complete, type Ecdsa, overrides } from './engine.js'
+
+/**
+ * Resolvers for the `P256` slot, and ox's defaults for it, backed by
+ * `@noble/curves`.
+ *
+ * Declaring the defaults against the slot contract is what keeps them honest: a
+ * default that goes missing, or whose signature drifts, fails to compile rather
+ * than failing at the call site. `lowS` and the recovered signature format are
+ * pinned here rather than in the contract, so an engine cannot opt out of them.
+ */
+
+const getPublicKeyDefault: Complete<Ecdsa>['getPublicKey'] = (privateKey) =>
+  p256.getPublicKey(privateKey, false)
+
+const getSharedSecretDefault: Complete<Ecdsa>['getSharedSecret'] = (
+  privateKey,
+  publicKey,
+) => p256.getSharedSecret(privateKey, publicKey, true)
+
+const randomSecretKeyDefault: Complete<Ecdsa>['randomSecretKey'] = () =>
+  p256.utils.randomSecretKey()
+
+const recoverPublicKeyDefault: Complete<Ecdsa>['recoverPublicKey'] = (
+  signature,
+  payload,
+) =>
+  p256.Signature.fromBytes(signature, 'recovered')
+    .recoverPublicKey(payload)
+    .toBytes(false)
+
+const signDefault: Complete<Ecdsa>['sign'] = (payload, privateKey, options) =>
+  p256.sign(payload, privateKey, {
+    ...options,
+    format: 'recovered',
+    lowS: true,
+  })
+
+const verifyDefault: Complete<Ecdsa>['verify'] = (
+  signature,
+  payload,
+  publicKey,
+  options,
+) => p256.verify(signature, payload, publicKey, { ...options, lowS: true })
+
+/** @internal */
+export const getPublicKey: Complete<Ecdsa>['getPublicKey'] = (privateKey) =>
+  (overrides.P256?.getPublicKey ?? getPublicKeyDefault)(privateKey)
+
+/** @internal */
+export const getSharedSecret: Complete<Ecdsa>['getSharedSecret'] = (
+  privateKey,
+  publicKey,
+) =>
+  (overrides.P256?.getSharedSecret ?? getSharedSecretDefault)(
+    privateKey,
+    publicKey,
+  )
+
+/** @internal */
+export const randomSecretKey: Complete<Ecdsa>['randomSecretKey'] = () =>
+  (overrides.P256?.randomSecretKey ?? randomSecretKeyDefault)()
+
+/** @internal */
+export const recoverPublicKey: Complete<Ecdsa>['recoverPublicKey'] = (
+  signature,
+  payload,
+) =>
+  (overrides.P256?.recoverPublicKey ?? recoverPublicKeyDefault)(
+    signature,
+    payload,
+  )
+
+/** @internal */
+export const sign: Complete<Ecdsa>['sign'] = (payload, privateKey, options) =>
+  (overrides.P256?.sign ?? signDefault)(payload, privateKey, options)
+
+/** @internal */
+export const verify: Complete<Ecdsa>['verify'] = (
+  signature,
+  payload,
+  publicKey,
+  options,
+) =>
+  (overrides.P256?.verify ?? verifyDefault)(
+    signature,
+    payload,
+    publicKey,
+    options,
+  )

package/src/core/internal/secp256k1.ts

@@ -0,0 +1,91 @@
+import { secp256k1 } from '@noble/curves/secp256k1.js'
+import { type Complete, type Ecdsa, overrides } from './engine.js'
+
+/**
+ * Resolvers for the `Secp256k1` slot, and ox's defaults for it, backed by
+ * `@noble/curves`.
+ *
+ * Declaring the defaults against the slot contract is what keeps them honest: a
+ * default that goes missing, or whose signature drifts, fails to compile rather
+ * than failing at the call site. `lowS` and the recovered signature format are
+ * pinned here rather than in the contract, so an engine cannot opt out of them.
+ */
+
+const getPublicKeyDefault: Complete<Ecdsa>['getPublicKey'] = (privateKey) =>
+  secp256k1.getPublicKey(privateKey, false)
+
+const getSharedSecretDefault: Complete<Ecdsa>['getSharedSecret'] = (
+  privateKey,
+  publicKey,
+) => secp256k1.getSharedSecret(privateKey, publicKey, true)
+
+const randomSecretKeyDefault: Complete<Ecdsa>['randomSecretKey'] = () =>
+  secp256k1.utils.randomSecretKey()
+
+const recoverPublicKeyDefault: Complete<Ecdsa>['recoverPublicKey'] = (
+  signature,
+  payload,
+) =>
+  secp256k1.Signature.fromBytes(signature, 'recovered')
+    .recoverPublicKey(payload)
+    .toBytes(false)
+
+const signDefault: Complete<Ecdsa>['sign'] = (payload, privateKey, options) =>
+  secp256k1.sign(payload, privateKey, {
+    ...options,
+    format: 'recovered',
+    lowS: true,
+  })
+
+const verifyDefault: Complete<Ecdsa>['verify'] = (
+  signature,
+  payload,
+  publicKey,
+  options,
+) => secp256k1.verify(signature, payload, publicKey, { ...options, lowS: true })
+
+/** @internal */
+export const getPublicKey: Complete<Ecdsa>['getPublicKey'] = (privateKey) =>
+  (overrides.Secp256k1?.getPublicKey ?? getPublicKeyDefault)(privateKey)
+
+/** @internal */
+export const getSharedSecret: Complete<Ecdsa>['getSharedSecret'] = (
+  privateKey,
+  publicKey,
+) =>
+  (overrides.Secp256k1?.getSharedSecret ?? getSharedSecretDefault)(
+    privateKey,
+    publicKey,
+  )
+
+/** @internal */
+export const randomSecretKey: Complete<Ecdsa>['randomSecretKey'] = () =>
+  (overrides.Secp256k1?.randomSecretKey ?? randomSecretKeyDefault)()
+
+/** @internal */
+export const recoverPublicKey: Complete<Ecdsa>['recoverPublicKey'] = (
+  signature,
+  payload,
+) =>
+  (overrides.Secp256k1?.recoverPublicKey ?? recoverPublicKeyDefault)(
+    signature,
+    payload,
+  )
+
+/** @internal */
+export const sign: Complete<Ecdsa>['sign'] = (payload, privateKey, options) =>
+  (overrides.Secp256k1?.sign ?? signDefault)(payload, privateKey, options)
+
+/** @internal */
+export const verify: Complete<Ecdsa>['verify'] = (
+  signature,
+  payload,
+  publicKey,
+  options,
+) =>
+  (overrides.Secp256k1?.verify ?? verifyDefault)(
+    signature,
+    payload,
+    publicKey,
+    options,
+  )

package/src/core/internal/x25519.ts

@@ -0,0 +1,40 @@
+import { x25519 } from '@noble/curves/ed25519.js'
+import { type Complete, type Ecdh, overrides } from './engine.js'
+
+/**
+ * Resolvers for the `X25519` slot, and ox's defaults for it, backed by
+ * `@noble/curves`.
+ *
+ * Declaring the defaults against the slot contract is what keeps them honest: a
+ * default that goes missing, or whose signature drifts, fails to compile rather
+ * than failing at the call site.
+ */
+
+const getPublicKeyDefault: Complete<Ecdh>['getPublicKey'] = (privateKey) =>
+  x25519.getPublicKey(privateKey)
+
+const getSharedSecretDefault: Complete<Ecdh>['getSharedSecret'] = (
+  privateKey,
+  publicKey,
+) => x25519.getSharedSecret(privateKey, publicKey)
+
+const randomSecretKeyDefault: Complete<Ecdh>['randomSecretKey'] = () =>
+  x25519.utils.randomSecretKey()
+
+/** @internal */
+export const getPublicKey: Complete<Ecdh>['getPublicKey'] = (privateKey) =>
+  (overrides.X25519?.getPublicKey ?? getPublicKeyDefault)(privateKey)
+
+/** @internal */
+export const getSharedSecret: Complete<Ecdh>['getSharedSecret'] = (
+  privateKey,
+  publicKey,
+) =>
+  (overrides.X25519?.getSharedSecret ?? getSharedSecretDefault)(
+    privateKey,
+    publicKey,
+  )
+
+/** @internal */
+export const randomSecretKey: Complete<Ecdh>['randomSecretKey'] = () =>
+  (overrides.X25519?.randomSecretKey ?? randomSecretKeyDefault)()

package/src/index.docs.ts

@@ -7,6 +7,8 @@ export * from './erc6492/index.js'
 export * from './erc7821/index.js'
 export * from './erc8010/index.js'
 export * from './erc8021/index.js'
+export * from './node/index.js'
 export * from './webauthn/index.js'
 export * from './tempo/index.js'
+export * from './wasm/index.js'
 export * from './zod/index.js'

package/src/index.ts

@@ -1520,6 +1520,42 @@ export * as CoseKey from './core/CoseKey.js'
  */
 export * as Ed25519 from './core/Ed25519.js'
 
+/**
+ * Functions for delegating ox's cryptography to a different implementation.
+ *
+ * Ox uses [`@noble`](https://github.com/paulmillr/noble-hashes) and
+ * [`@scure`](https://github.com/paulmillr/scure-bip32) by default. An engine
+ * replaces those implementations with your own — for example a WASM build of an
+ * audited C library.
+ *
+ * @example
+ * ### Installing an Engine
+ *
+ * Engine slots are named after ox modules, and everything is optional: any slot
+ * or function you leave out keeps using ox's default implementation.
+ *
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox/wasm'
+ *
+ * await Engine.load()
+ * ```
+ *
+ * @example
+ * ### Overriding a Single Primitive
+ *
+ * ```ts twoslash
+ * import { Engine } from 'ox'
+ *
+ * Engine.set({
+ *   Hash: { keccak256: () => new Uint8Array(32) }
+ * })
+ * ```
+ *
+ * @category Crypto
+ */
+export * as Engine from './core/Engine.js'
+
 /**
  * Utility functions for working with ENS names.
  *

package/src/node/Engine.ts

@@ -0,0 +1,69 @@
+import * as CoreEngine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+import * as Hash from './Hash.js'
+
+/**
+ * Creates and installs every Node.js implementation this entrypoint provides.
+ *
+ * The function is asynchronous to match the `ox/wasm` entrypoint, even though
+ * Node's built-in cryptography needs no compilation. Call it once during
+ * startup, before any cryptographic operation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Hash } from 'ox'
+ * import { Engine } from 'ox/node'
+ *
+ * await Engine.load()
+ *
+ * Hash.sha256('0xdeadbeef')
+ * ```
+ *
+ * @returns The engine that was installed.
+ */
+export async function load(): Promise<load.ReturnType> {
+  const engine = await create()
+  CoreEngine.set(engine)
+  return engine
+}
+
+export declare namespace load {
+  type ReturnType = create.ReturnType
+
+  type ErrorType =
+    | create.ErrorType
+    | CoreEngine.set.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Creates every Node.js implementation this entrypoint provides, without
+ * installing it.
+ *
+ * Reach for this where an engine has to exist as a value, such as a benchmark
+ * or an [`Engine.with`](/api/Engine/with) scope.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine, Hash } from 'ox'
+ * import { Engine as NodeEngine } from 'ox/node'
+ *
+ * const node = await NodeEngine.create()
+ *
+ * Engine.with(node, () => Hash.sha256('0xdeadbeef'))
+ * ```
+ *
+ * @returns An engine, ready to install.
+ */
+export async function create(): Promise<create.ReturnType> {
+  return { ...(await Hash.create()) }
+}
+
+export declare namespace create {
+  /** Every slot this entrypoint supplies, each with its primitives present. */
+  type ReturnType = Hash.create.ReturnType
+
+  type ErrorType = Hash.create.ErrorType | Errors.GlobalErrorType
+}

package/src/node/Hash.ts

@@ -0,0 +1,56 @@
+import * as crypto from 'node:crypto'
+import type * as Engine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+
+/**
+ * Creates Node.js implementations of the [`Hash`](/api/Hash) primitives, without
+ * installing them.
+ *
+ * Most callers want {@link ox#Engine.load} instead, which installs every
+ * implementation this entrypoint provides. Reach for this to take the `Hash`
+ * slot on its own, or to hold the implementation without touching the
+ * installed engine.
+ *
+ * Node's `sha3-256` is not Ethereum Keccak256, so this engine deliberately
+ * omits `keccak256`. Any earlier override remains installed; otherwise Ox uses
+ * its default implementation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine, Hash } from 'ox'
+ * import * as NodeHash from 'ox/node/Hash'
+ *
+ * Engine.set(await NodeHash.create())
+ *
+ * Hash.sha256('0xdeadbeef')
+ * ```
+ *
+ * @returns An engine supplying the `Hash` slot.
+ */
+export function create(): Promise<create.ReturnType> {
+  return Promise.resolve({
+    Hash: {
+      hmacSha256: (key, message) =>
+        new Uint8Array(
+          crypto.createHmac('sha256', key).update(message).digest(),
+        ),
+      ripemd160: (input) =>
+        new Uint8Array(crypto.hash('ripemd160', input, 'buffer')),
+      sha256: (input) => new Uint8Array(crypto.hash('sha256', input, 'buffer')),
+    },
+  })
+}
+
+export declare namespace create {
+  /** The `Hash` slot, carrying every primitive this module implements. */
+  type ReturnType = {
+    Hash: {
+      [key in 'hmacSha256' | 'ripemd160' | 'sha256']-?: NonNullable<
+        Engine.Hash[key]
+      >
+    }
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}

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

@@ -0,0 +1,62 @@
+import { Engine as CoreEngine, Hash } from 'ox'
+import { Engine } from 'ox/node'
+import { describe, expect, test } from 'vp/test'
+
+describe('create', () => {
+  test('behavior: does not install', async () => {
+    const engine = await Engine.create()
+
+    expect(Object.keys(engine)).toMatchInlineSnapshot(`
+      [
+        "Hash",
+      ]
+    `)
+    expect(CoreEngine.get()).toMatchInlineSnapshot('{}')
+  })
+
+  test('behavior: installs for the duration of a call', async () => {
+    const node = await Engine.create()
+    const digest = CoreEngine.with(node, () => Hash.sha256('0xdeadbeef'))
+
+    expect(digest).toMatchInlineSnapshot(
+      `"0x5f78c33274e43fa9de5659265c1d917e25c03722dcb0b8d27db8d5feaa813953"`,
+    )
+    expect(CoreEngine.get()).toMatchInlineSnapshot('{}')
+  })
+})
+
+describe('load', () => {
+  test('behavior: installs and returns what it installed', async () => {
+    const engine = await Engine.load()
+
+    expect(Object.keys(CoreEngine.get())).toEqual(Object.keys(engine))
+    expect(Object.keys(CoreEngine.get().Hash ?? {}).sort())
+      .toMatchInlineSnapshot(`
+      [
+        "hmacSha256",
+        "ripemd160",
+        "sha256",
+      ]
+    `)
+  })
+
+  test('behavior: leaves unsupported primitives on the default', async () => {
+    await Engine.load()
+
+    expect(Hash.keccak256('0xdeadbeef')).toMatchInlineSnapshot(
+      `"0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1"`,
+    )
+  })
+
+  test('behavior: merges with later engines', async () => {
+    await Engine.load()
+    CoreEngine.set({ Mnemonic: { toSeed: () => new Uint8Array(64) } })
+
+    expect(Object.keys(CoreEngine.get()).sort()).toMatchInlineSnapshot(`
+      [
+        "Hash",
+        "Mnemonic",
+      ]
+    `)
+  })
+})

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

@@ -0,0 +1,26 @@
+import type { Engine } from 'ox'
+import { Hash as NodeHash } from 'ox/node'
+import { expectTypeOf, test } from 'vp/test'
+
+type Created = Awaited<ReturnType<typeof NodeHash.create>>
+
+test('every implemented primitive is present', () => {
+  expectTypeOf<Created['Hash']['hmacSha256']>().toEqualTypeOf<
+    (key: Uint8Array, message: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Created['Hash']['ripemd160']>().toEqualTypeOf<
+    (input: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Created['Hash']['sha256']>().toEqualTypeOf<
+    (input: Uint8Array) => Uint8Array
+  >()
+})
+
+test('unsupported primitives are absent', () => {
+  expectTypeOf<Created['Hash']>().not.toHaveProperty('blake3')
+  expectTypeOf<Created['Hash']>().not.toHaveProperty('keccak256')
+})
+
+test('the result is still an engine', () => {
+  expectTypeOf<Created>().toExtend<Engine.Engine>()
+})