ox 1.1.0 → 1.1.2

package/src/core/_test/Engine.test-d.ts

@@ -17,6 +17,62 @@ type Unlisted = {
   >
 }[keyof Engine.Engine]
 
+describe('install', () => {
+  test('accepts raw and promised slots and preserves their resolved shape', () => {
+    const keccak256 = (input: Uint8Array) => input
+    const toSeed = (_mnemonic: string) => new Uint8Array(64)
+
+    expectTypeOf(
+      Engine.install({
+        Hash: Promise.resolve({ keccak256 }),
+        Mnemonic: { toSeed },
+      }),
+    ).toEqualTypeOf<
+      Promise<{
+        Hash: { keccak256: typeof keccak256 }
+        Mnemonic: { toSeed: typeof toSeed }
+      }>
+    >()
+  })
+
+  test('rejects an unknown slot', () => {
+    // @ts-expect-error
+    void Engine.install({ Keccak: Promise.resolve({}) })
+  })
+
+  test('rejects an unknown slot alongside a valid slot', () => {
+    void Engine.install({
+      Hash: { keccak256: (input) => input },
+      // @ts-expect-error
+      Keccak: {},
+    })
+  })
+
+  test('rejects a misspelled function', () => {
+    void Engine.install({
+      // @ts-expect-error
+      Hash: Promise.resolve({ keccak_256: (input: Uint8Array) => input }),
+    })
+  })
+
+  test('rejects a misspelled function alongside a valid function', () => {
+    void Engine.install({
+      // @ts-expect-error
+      Hash: {
+        keccak256: (input: Uint8Array) => input,
+        keccak_256: (input: Uint8Array) => input,
+      },
+    })
+  })
+
+  test('rejects a mistyped promised function', () => {
+    void Engine.install({
+      // @ts-expect-error
+      Hash: Promise.resolve({ keccak256: (input: string) => input }),
+    })
+  })
+})
+
 describe('set', () => {
   test('accepts a partial engine', () => {
     expectTypeOf(Engine.set).parameter(0).toEqualTypeOf<Engine.Engine>()

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

@@ -38,6 +38,101 @@ function merkelize() {
   return BinaryStateTree.merkelize(tree)
 }
 
+describe('install', () => {
+  test('behavior: resolves slots in parallel and installs them atomically', async () => {
+    const keccak256 = () => new Uint8Array(32).fill(1)
+    const sign = () => new Uint8Array(65).fill(3)
+    const toSeed = () => new Uint8Array(64).fill(2)
+    let releaseHash: (() => void) | undefined
+
+    Engine.set({ Secp256k1: { sign } })
+
+    const hash = {
+      // oxlint-disable-next-line unicorn/no-thenable -- Distinguishes parallel resolution from sequential awaits.
+      then(
+        resolve: (value: Engine.Hash) => void,
+        reject: (reason: unknown) => void,
+      ) {
+        const timeout = setTimeout(
+          () => reject(new Error('slots resolved serially')),
+          0,
+        )
+        releaseHash = () => {
+          clearTimeout(timeout)
+          resolve({ keccak256 })
+        }
+      },
+    } as unknown as PromiseLike<Engine.Hash>
+    const mnemonic = {
+      // oxlint-disable-next-line unicorn/no-thenable -- Distinguishes parallel resolution from sequential awaits.
+      then(resolve: (value: Engine.Mnemonic) => void) {
+        resolve({ toSeed })
+        releaseHash?.()
+      },
+    } as unknown as PromiseLike<Engine.Mnemonic>
+
+    const installed = await Engine.install({ Hash: hash, Mnemonic: mnemonic })
+
+    expect(installed).toEqual({
+      Hash: { keccak256 },
+      Mnemonic: { toSeed },
+    })
+    expect(Engine.get()).toEqual({
+      ...installed,
+      Secp256k1: { sign },
+    })
+  })
+
+  test('behavior: a rejected slot leaves the previous engine installed', async () => {
+    const keccak256 = () => new Uint8Array(32).fill(1)
+    Engine.set({ Hash: { keccak256 } })
+
+    await expect(
+      Engine.install({
+        Hash: Promise.resolve({
+          sha256: () => new Uint8Array(32).fill(2),
+        }),
+        Mnemonic: Promise.reject(new Error('could not load engine')),
+      }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: could not load engine]`,
+    )
+    expect(Engine.get()).toEqual({ Hash: { keccak256 } })
+  })
+
+  test('behavior: an invalid resolved engine leaves the previous engine installed', async () => {
+    const keccak256 = () => new Uint8Array(32).fill(1)
+    Engine.set({ Hash: { keccak256 } })
+
+    await expect(
+      Engine.install({
+        Hash: Promise.resolve({
+          sha256: () => new Uint8Array(32).fill(2),
+        }),
+        Mnemonic: Promise.resolve({
+          to_seed: () => new Uint8Array(64),
+        }),
+      } as never),
+    ).rejects.toThrowError(Engine.UnknownPrimitiveError)
+    expect(Engine.get()).toEqual({ Hash: { keccak256 } })
+  })
+
+  test('behavior: a null resolved slot leaves the previous engine installed', async () => {
+    const keccak256 = () => new Uint8Array(32).fill(1)
+    Engine.set({ Hash: { keccak256 } })
+
+    await expect(
+      Engine.install({
+        Hash: Promise.resolve({
+          sha256: () => new Uint8Array(32).fill(2),
+        }),
+        Mnemonic: Promise.resolve(null),
+      } as never),
+    ).rejects.toThrowError(Engine.InvalidSlotValueError)
+    expect(Engine.get()).toEqual({ Hash: { keccak256 } })
+  })
+})
+
 describe('set', () => {
   test('behavior: empty engine is a no-op', () => {
     const before = Hash.keccak256(payload)

package/src/core/_test/Hash.vectors.test.ts

@@ -1,6 +1,7 @@
 import { Hash } from 'ox'
 import { describe, expect, test } from 'vp/test'
 import * as vectors from '../../../test/vectors/hashes/index.js'
+import * as hash from '../internal/hash.js'
 
 /**
  * Published vectors against ox's default (`@noble/hashes`) implementations.
@@ -11,6 +12,13 @@ import * as vectors from '../../../test/vectors/hashes/index.js'
  * See `test/vectors/hashes/README.md`.
  */
 
+describe('blake3', () => {
+  test(`matches ${vectors.blake3.length} official BLAKE3 vectors`, () => {
+    for (const { digest, message } of vectors.blake3)
+      expect(hash.blake3(message)).toEqual(digest)
+  })
+})
+
 describe('sha256', () => {
   test(`matches ${vectors.sha256.length} NIST CAVP vectors`, () => {
     for (const { digest, message } of vectors.sha256)

package/src/core/internal/engine.ts

@@ -263,21 +263,21 @@ export type Bls = {
  * @internal
  */
 export type Engine = {
-  /** Implementation for {@link ox#Bls}. */
+  /** Implementation for [`Bls`](/api/Bls). */
   Bls?: Bls | undefined
-  /** Implementation for {@link ox#Ed25519}. */
+  /** Implementation for [`Ed25519`](/api/Ed25519). */
   Ed25519?: Eddsa | undefined
-  /** Implementation for {@link ox#Hash}. */
+  /** Implementation for [`Hash`](/api/Hash). */
   Hash?: Hash | undefined
-  /** Implementation for {@link ox#Keystore}. */
+  /** Implementation for [`Keystore`](/api/Keystore). */
   Keystore?: Keystore | undefined
-  /** Implementation for {@link ox#Mnemonic}. */
+  /** Implementation for [`Mnemonic`](/api/Mnemonic). */
   Mnemonic?: Mnemonic | undefined
-  /** Implementation for {@link ox#P256}. */
+  /** Implementation for [`P256`](/api/P256). */
   P256?: Ecdsa | undefined
-  /** Implementation for {@link ox#Secp256k1}. */
+  /** Implementation for [`Secp256k1`](/api/Secp256k1). */
   Secp256k1?: Ecdsa | undefined
-  /** Implementation for {@link ox#X25519}. */
+  /** Implementation for [`X25519`](/api/X25519). */
   X25519?: Ecdh | undefined
 }
 

package/src/index.ts

@@ -1536,9 +1536,12 @@ export * as Ed25519 from './core/Ed25519.js'
  *
  * ```ts twoslash
  * // @noErrors
- * import { Engine } from 'ox/wasm'
+ * import { Engine } from 'ox'
+ * import { Hash } from 'ox/wasm'
  *
- * await Engine.load()
+ * await Engine.install({
+ *   Hash: Hash.engine()
+ * })
  * ```
  *
  * @example

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

@@ -1,40 +1,67 @@
 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'
 
 /**
- * Creates and installs every Node.js implementation this entrypoint provides.
+ * 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.
+ * Slots initialize in parallel and are installed atomically. Call this once
+ * during startup, before any cryptographic operation.
  *
  * @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')
  * ```
  *
  * @returns The engine that was installed.
  */
-export async function load(): Promise<load.ReturnType> {
-  const engine = await create()
-  CoreEngine.set(engine)
-  return engine
+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 load {
-  type ReturnType = create.ReturnType
+export declare namespace install {
+  /** Every slot this entrypoint installs, each with its primitives present. */
+  type ReturnType = engine.ReturnType
 
-  type ErrorType =
-    | create.ErrorType
-    | CoreEngine.set.ErrorType
-    | Errors.GlobalErrorType
+  type ErrorType = engine.ErrorType | CoreEngine.install.ErrorType
 }
 
 /**
@@ -50,20 +77,49 @@ export declare namespace load {
  * import { Engine, Hash } from 'ox'
  * import { Engine as NodeEngine } from 'ox/node'
  *
- * const node = await NodeEngine.create()
+ * const node = await NodeEngine.engine()
  *
  * Engine.with(node, () => Hash.sha256('0xdeadbeef'))
  * ```
  *
  * @returns An engine, ready to install.
  */
-export async function create(): Promise<create.ReturnType> {
-  return { ...(await Hash.create()) }
+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 create {
+export declare namespace engine {
   /** Every slot this entrypoint supplies, each with its primitives present. */
-  type ReturnType = Hash.create.ReturnType
+  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 = Hash.create.ErrorType | Errors.GlobalErrorType
+  type ErrorType =
+    | Ed25519.engine.ErrorType
+    | Hash.engine.ErrorType
+    | Keystore.engine.ErrorType
+    | Mnemonic.engine.ErrorType
+    | P256.engine.ErrorType
+    | X25519.engine.ErrorType
+    | Errors.GlobalErrorType
 }

package/src/node/Hash.ts

@@ -2,14 +2,15 @@ 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/Hash.js'
+
 /**
- * Creates Node.js implementations of the [`Hash`](/api/Hash) primitives, without
- * installing them.
+ * Creates a Node.js implementation of the [`Hash`](/api/Hash) engine slot,
+ * without installing it.
  *
- * 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.
+ * Most callers want [`Engine.install`](/node/crypto/Engine/install) instead,
+ * which installs every implementation this entrypoint provides. Reach for this
+ * to install or hold the `Hash` slot on its own.
  *
  * Node's `sha3-256` is not Ethereum Keccak256, so this engine deliberately
  * omits `keccak256`. Any earlier override remains installed; otherwise Ox uses
@@ -18,38 +19,32 @@ import type * as Errors from '../core/Errors.js'
  * @example
  * ```ts twoslash
  * // @noErrors
- * import { Engine, Hash } from 'ox'
- * import * as NodeHash from 'ox/node/Hash'
+ * import { Engine } from 'ox'
+ * import { Hash } from 'ox/node'
  *
- * Engine.set(await NodeHash.create())
+ * await Engine.install({ Hash: Hash.engine() })
  *
  * Hash.sha256('0xdeadbeef')
  * ```
  *
- * @returns An engine supplying the `Hash` slot.
+ * @returns The raw `Hash` engine slot.
  */
-export function create(): Promise<create.ReturnType> {
+export function engine(): Promise<engine.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')),
-    },
+    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. */
+export declare namespace engine {
+  /** Every `Hash` primitive this module implements. */
   type ReturnType = {
-    Hash: {
-      [key in 'hmacSha256' | 'ripemd160' | 'sha256']-?: NonNullable<
-        Engine.Hash[key]
-      >
-    }
+    [key in 'hmacSha256' | 'ripemd160' | 'sha256']-?: NonNullable<
+      Engine.Hash[key]
+    >
   }
 
   type ErrorType = Errors.GlobalErrorType

package/src/node/Keystore.ts

@@ -0,0 +1,103 @@
+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/Keystore.js'
+
+/**
+ * Creates a Node.js implementation of the [`Keystore`](/api/Keystore) engine
+ * slot, without installing it.
+ *
+ * Most callers want [`Engine.install`](/node/crypto/Engine/install) instead,
+ * which installs every implementation this entrypoint provides. Reach for this
+ * to install or hold the `Keystore` slot on its own.
+ *
+ * This engine deliberately omits scrypt. OpenSSL rejects Ox's default scrypt
+ * parameter shape, so installing it would make valid existing calls fail.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Keystore } from 'ox/node'
+ *
+ * await Engine.install({ Keystore: Keystore.engine() })
+ *
+ * Keystore.pbkdf2({ password: 'testpassword' })
+ * ```
+ *
+ * @returns The raw `Keystore` engine slot.
+ */
+export function engine(): Promise<engine.ReturnType> {
+  return Promise.resolve({
+    aesCtrDecrypt: (key, iv, data) => {
+      const cipher = crypto.createDecipheriv(
+        `aes-${key.length * 8}-ctr`,
+        key,
+        iv,
+      )
+      return cipherData(cipher, data)
+    },
+    aesCtrEncrypt: (key, iv, data) => {
+      const cipher = crypto.createCipheriv(`aes-${key.length * 8}-ctr`, key, iv)
+      return cipherData(cipher, data)
+    },
+    pbkdf2Sha256: (password, salt, options) =>
+      copyAndClear(
+        crypto.pbkdf2Sync(password, salt, options.c, options.dkLen, 'sha256'),
+      ),
+    pbkdf2Sha256Async: (password, salt, options) =>
+      new Promise((resolve, reject) => {
+        crypto.pbkdf2(
+          password,
+          salt,
+          options.c,
+          options.dkLen,
+          'sha256',
+          (error, key) => {
+            if (error) return reject(error)
+            try {
+              resolve(copyAndClear(key))
+            } catch (error) {
+              reject(error)
+            }
+          },
+        )
+      }),
+  })
+}
+
+export declare namespace engine {
+  /** Every `Keystore` primitive this module implements. */
+  type ReturnType = {
+    [key in
+      | 'aesCtrDecrypt'
+      | 'aesCtrEncrypt'
+      | 'pbkdf2Sha256'
+      | 'pbkdf2Sha256Async']-?: NonNullable<Engine.Keystore[key]>
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+function cipherData(
+  cipher: crypto.Cipheriv | crypto.Decipheriv,
+  data: Uint8Array,
+): Uint8Array {
+  const chunks: Buffer[] = []
+  try {
+    chunks.push(cipher.update(data))
+    chunks.push(cipher.final())
+    return copyAndClear(Buffer.concat(chunks))
+  } finally {
+    for (const chunk of chunks) chunk.fill(0)
+  }
+}
+
+function copyAndClear(value: Buffer): Uint8Array {
+  try {
+    return Uint8Array.from(value)
+  } finally {
+    value.fill(0)
+  }
+}