ox 1.0.5 → 1.1.2

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,45 @@ 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'
+ * import { Hash } from 'ox/wasm'
+ *
+ * await Engine.install({
+ *   Hash: Hash.engine()
+ * })
+ * ```
+ *
+ * @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/Ed25519.ts

@@ -0,0 +1,87 @@
+import * as crypto from 'node:crypto'
+import type * as Engine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+
+export * from '../core/Ed25519.js'
+
+const privateKeyPrefix = Buffer.from('302e020100300506032b657004220420', 'hex')
+
+/**
+ * Creates a Node.js implementation of the [`Ed25519`](/api/Ed25519) engine
+ * slot, without installing it.
+ *
+ * Node's verifier does not implement Ox's ZIP-215 verification semantics, so
+ * this engine deliberately omits `verify`. Public-key conversion and random
+ * key generation also remain on Ox's default implementation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Ed25519 } from 'ox/node'
+ *
+ * await Engine.install({ Ed25519: Ed25519.engine() })
+ *
+ * Ed25519.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @returns The raw `Ed25519` engine slot.
+ */
+export function engine(): Promise<engine.ReturnType> {
+  return Promise.resolve({
+    getPublicKey: (privateKey) =>
+      rawPublicKey(crypto.createPublicKey(toPrivateKey(privateKey))),
+    sign: (payload, privateKey) =>
+      new Uint8Array(crypto.sign(null, payload, toPrivateKey(privateKey))),
+    toMontgomerySecret: (privateKey) => {
+      assertLength(privateKey)
+      const digest = crypto.hash('sha512', privateKey, 'buffer')
+      try {
+        const secretKey = Uint8Array.from(digest.subarray(0, 32))
+        secretKey[0]! &= 248
+        secretKey[31]! &= 127
+        secretKey[31]! |= 64
+        return secretKey
+      } finally {
+        digest.fill(0)
+      }
+    },
+  })
+}
+
+export declare namespace engine {
+  /** Every `Ed25519` primitive this module implements. */
+  type ReturnType = {
+    [key in 'getPublicKey' | 'sign' | 'toMontgomerySecret']-?: NonNullable<
+      Engine.Eddsa[key]
+    >
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+function assertLength(key: Uint8Array): void {
+  if (key.length !== 32)
+    throw new RangeError(
+      `Ed25519 private key must be 32 bytes, got ${key.length}`,
+    )
+}
+
+function rawPublicKey(publicKey: crypto.KeyObject): Uint8Array {
+  const der = publicKey.export({ format: 'der', type: 'spki' })
+  return Uint8Array.from(der.subarray(-32))
+}
+
+function toPrivateKey(privateKey: Uint8Array): crypto.KeyObject {
+  assertLength(privateKey)
+  const der = Buffer.concat([privateKeyPrefix, privateKey])
+  try {
+    return crypto.createPrivateKey({
+      format: 'der',
+      key: der,
+      type: 'pkcs8',
+    })
+  } finally {
+    der.fill(0)
+  }
+}

package/src/node/Engine.ts

@@ -0,0 +1,125 @@
+import * as CoreEngine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+import * as Ed25519 from './Ed25519.js'
+import * as Hash from './Hash.js'
+import * as Keystore from './Keystore.js'
+import * as Mnemonic from './Mnemonic.js'
+import * as P256 from './P256.js'
+import * as X25519 from './X25519.js'
+
+export {
+  AsyncScopeError,
+  get,
+  InvalidSlotValueError,
+  reset,
+  set,
+  UnknownPrimitiveError,
+  UnknownSlotError,
+  with,
+} from '../core/Engine.js'
+export type {
+  Bls,
+  Ecdh,
+  Ecdsa,
+  Eddsa,
+  Engine,
+  Hash,
+  Keystore,
+  Mnemonic,
+} from '../core/Engine.js'
+
+/**
+ * Installs every Node.js implementation this entrypoint provides.
+ *
+ * Slots initialize in parallel and are installed atomically. Call this once
+ * during startup, before any cryptographic operation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine, Hash } from 'ox/node'
+ *
+ * await Engine.install()
+ *
+ * Hash.sha256('0xdeadbeef')
+ * ```
+ *
+ * @returns The engine that was installed.
+ */
+export function install(): Promise<install.ReturnType> {
+  return CoreEngine.install({
+    Ed25519: Ed25519.engine(),
+    Hash: Hash.engine(),
+    Keystore: Keystore.engine(),
+    Mnemonic: Mnemonic.engine(),
+    P256: P256.engine(),
+    X25519: X25519.engine(),
+  })
+}
+
+export declare namespace install {
+  /** Every slot this entrypoint installs, each with its primitives present. */
+  type ReturnType = engine.ReturnType
+
+  type ErrorType = engine.ErrorType | CoreEngine.install.ErrorType
+}
+
+/**
+ * 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.engine()
+ *
+ * Engine.with(node, () => Hash.sha256('0xdeadbeef'))
+ * ```
+ *
+ * @returns An engine, ready to install.
+ */
+export async function engine(): Promise<engine.ReturnType> {
+  const [ed25519, hash, keystore, mnemonic, p256, x25519] = await Promise.all([
+    Ed25519.engine(),
+    Hash.engine(),
+    Keystore.engine(),
+    Mnemonic.engine(),
+    P256.engine(),
+    X25519.engine(),
+  ])
+  return {
+    Ed25519: ed25519,
+    Hash: hash,
+    Keystore: keystore,
+    Mnemonic: mnemonic,
+    P256: p256,
+    X25519: x25519,
+  }
+}
+
+export declare namespace engine {
+  /** Every slot this entrypoint supplies, each with its primitives present. */
+  type ReturnType = {
+    Ed25519: Ed25519.engine.ReturnType
+    Hash: Hash.engine.ReturnType
+    Keystore: Keystore.engine.ReturnType
+    Mnemonic: Mnemonic.engine.ReturnType
+    P256: P256.engine.ReturnType
+    X25519: X25519.engine.ReturnType
+  }
+
+  type ErrorType =
+    | Ed25519.engine.ErrorType
+    | Hash.engine.ErrorType
+    | Keystore.engine.ErrorType
+    | Mnemonic.engine.ErrorType
+    | P256.engine.ErrorType
+    | X25519.engine.ErrorType
+    | Errors.GlobalErrorType
+}