ox 1.1.0 → 1.2.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,54 +2,49 @@ 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
- * its default implementation.
+ * Node does not provide BLAKE3, and its `sha3-256` is not Ethereum Keccak256, so
+ * this engine deliberately omits `blake3` and `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'
+ * 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)
+  }
+}

package/src/node/Mnemonic.ts

@@ -0,0 +1,68 @@
+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/Mnemonic.js'
+
+/**
+ * Creates a Node.js implementation of the [`Mnemonic`](/api/Mnemonic) 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 `Mnemonic` slot on its own.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Mnemonic } from 'ox/node'
+ *
+ * await Engine.install({ Mnemonic: Mnemonic.engine() })
+ *
+ * Mnemonic.toSeed(
+ *   'test test test test test test test test test test test junk'
+ * )
+ * ```
+ *
+ * @returns The raw `Mnemonic` engine slot.
+ */
+export function engine(): Promise<engine.ReturnType> {
+  return Promise.resolve({
+    toSeed: (mnemonic, passphrase = '') => {
+      if (typeof mnemonic !== 'string')
+        throw new TypeError(`invalid mnemonic type: ${typeof mnemonic}`)
+
+      const normalized = mnemonic.normalize('NFKD')
+      if (![12, 15, 18, 21, 24].includes(normalized.split(' ').length))
+        throw new Error('Invalid mnemonic')
+
+      return copyAndClear(
+        crypto.pbkdf2Sync(
+          normalized,
+          `mnemonic${passphrase}`.normalize('NFKD'),
+          2048,
+          64,
+          'sha512',
+        ),
+      )
+    },
+  })
+}
+
+export declare namespace engine {
+  /** Every `Mnemonic` primitive this module implements. */
+  type ReturnType = {
+    [key in 'toSeed']-?: NonNullable<Engine.Mnemonic[key]>
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+function copyAndClear(value: Buffer): Uint8Array {
+  try {
+    return Uint8Array.from(value)
+  } finally {
+    value.fill(0)
+  }
+}

package/src/node/P256.ts

@@ -0,0 +1,48 @@
+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/P256.js'
+
+/**
+ * Creates a Node.js implementation of the [`P256`](/api/P256) engine slot,
+ * without installing it.
+ *
+ * Node's other P256 operations do not reproduce Ox's recovered-signature and
+ * compressed-shared-point contracts, so they remain on Ox's defaults.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { P256 } from 'ox/node'
+ *
+ * await Engine.install({ P256: P256.engine() })
+ *
+ * P256.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @returns The raw `P256` engine slot.
+ */
+export function engine(): Promise<engine.ReturnType> {
+  return Promise.resolve({
+    getPublicKey: (privateKey) => {
+      if (privateKey.length !== 32)
+        throw new RangeError(
+          `P256 private key must be 32 bytes, got ${privateKey.length}`,
+        )
+      const ecdh = crypto.createECDH('prime256v1')
+      ecdh.setPrivateKey(privateKey)
+      return new Uint8Array(ecdh.getPublicKey(undefined, 'uncompressed'))
+    },
+  })
+}
+
+export declare namespace engine {
+  /** Every `P256` primitive this module implements. */
+  type ReturnType = {
+    getPublicKey: NonNullable<Engine.Ecdsa['getPublicKey']>
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}

package/src/node/X25519.ts

@@ -0,0 +1,93 @@
+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/X25519.js'
+
+const privateKeyPrefix = Buffer.from('302e020100300506032b656e04220420', 'hex')
+const publicKeyPrefix = Buffer.from('302a300506032b656e032100', 'hex')
+
+/**
+ * Creates a Node.js implementation of the [`X25519`](/api/X25519) engine slot,
+ * without installing it.
+ *
+ * Random key generation remains on Ox's default implementation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { X25519 } from 'ox/node'
+ *
+ * await Engine.install({ X25519: X25519.engine() })
+ *
+ * X25519.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @returns The raw `X25519` engine slot.
+ */
+export function engine(): Promise<engine.ReturnType> {
+  return Promise.resolve({
+    getPublicKey: (privateKey) =>
+      rawPublicKey(crypto.createPublicKey(toPrivateKey(privateKey))),
+    getSharedSecret: (privateKey, publicKey) =>
+      copyAndClear(
+        crypto.diffieHellman({
+          privateKey: toPrivateKey(privateKey),
+          publicKey: toPublicKey(publicKey),
+        }),
+      ),
+  })
+}
+
+export declare namespace engine {
+  /** Every `X25519` primitive this module implements. */
+  type ReturnType = {
+    [key in 'getPublicKey' | 'getSharedSecret']-?: NonNullable<Engine.Ecdh[key]>
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+function copyAndClear(value: Buffer): Uint8Array {
+  try {
+    return Uint8Array.from(value)
+  } finally {
+    value.fill(0)
+  }
+}
+
+function assertLength(key: Uint8Array, type: 'private' | 'public'): void {
+  if (key.length !== 32)
+    throw new RangeError(
+      `X25519 ${type} 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, 'private')
+  const der = Buffer.concat([privateKeyPrefix, privateKey])
+  try {
+    return crypto.createPrivateKey({
+      format: 'der',
+      key: der,
+      type: 'pkcs8',
+    })
+  } finally {
+    der.fill(0)
+  }
+}
+
+function toPublicKey(publicKey: Uint8Array): crypto.KeyObject {
+  assertLength(publicKey, 'public')
+  return crypto.createPublicKey({
+    format: 'der',
+    key: Buffer.concat([publicKeyPrefix, publicKey]),
+    type: 'spki',
+  })
+}

package/src/node/_test/Curves.fuzz.ts

@@ -0,0 +1,76 @@
+import { fc, test } from '@fast-check/vitest'
+import { ed25519, x25519 } from '@noble/curves/ed25519.js'
+import { p256 } from '@noble/curves/nist.js'
+import { describe, expect } from 'vp/test'
+import { numRuns } from '../../../test/fuzz/numRuns.js'
+import * as Ed25519 from '../Ed25519.js'
+import * as P256 from '../P256.js'
+import * as X25519 from '../X25519.js'
+
+const arbitraryBytes = fc.uint8Array({ maxLength: 512 })
+const arbitraryKey = fc.uint8Array({ maxLength: 32, minLength: 32 })
+const arbitraryP256PrivateKey = fc
+  .tuple(
+    fc.integer({ max: 0xfe, min: 1 }),
+    fc.uint8Array({ maxLength: 31, minLength: 31 }),
+  )
+  .map(([first, rest]) => Uint8Array.of(first, ...rest))
+
+describe('Ed25519', () => {
+  test.prop({ payload: arbitraryBytes, privateKey: arbitraryKey }, { numRuns })(
+    'matches the default for arbitrary offset views',
+    async (options) => {
+      const engine = await Ed25519.engine()
+      const payload = offsetView(options.payload)
+      const privateKey = offsetView(options.privateKey)
+
+      expect(engine.getPublicKey(privateKey)).toEqual(
+        ed25519.getPublicKey(privateKey),
+      )
+      expect(engine.sign(payload, privateKey)).toEqual(
+        ed25519.sign(payload, privateKey),
+      )
+      expect(engine.toMontgomerySecret(privateKey)).toEqual(
+        ed25519.utils.toMontgomerySecret(privateKey),
+      )
+    },
+  )
+})
+
+describe('X25519', () => {
+  test.prop(
+    { privateKey: arbitraryKey, publicKeySeed: arbitraryKey },
+    { numRuns },
+  )('matches the default for arbitrary offset views', async (options) => {
+    const engine = await X25519.engine()
+    const privateKey = offsetView(options.privateKey)
+    const publicKey = offsetView(x25519.getPublicKey(options.publicKeySeed))
+
+    expect(engine.getPublicKey(privateKey)).toEqual(
+      x25519.getPublicKey(privateKey),
+    )
+    expect(engine.getSharedSecret(privateKey, publicKey)).toEqual(
+      x25519.getSharedSecret(privateKey, publicKey),
+    )
+  })
+})
+
+describe('P256', () => {
+  test.prop({ privateKey: arbitraryP256PrivateKey }, { numRuns })(
+    'matches the default for arbitrary offset views',
+    async (options) => {
+      const engine = await P256.engine()
+      const privateKey = offsetView(options.privateKey)
+
+      expect(engine.getPublicKey(privateKey)).toEqual(
+        p256.getPublicKey(privateKey, false),
+      )
+    },
+  )
+})
+
+function offsetView(value: Uint8Array): Uint8Array {
+  const bytes = new Uint8Array(value.length + 4).fill(0xff)
+  bytes.set(value, 2)
+  return bytes.subarray(2, -2)
+}

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

@@ -0,0 +1,35 @@
+import { expectTypeOf, test } from 'vp/test'
+import type * as Engine from '../../core/Engine.js'
+import * as core_Ed25519 from '../../core/Ed25519.js'
+import * as NodeEd25519 from '../Ed25519.js'
+
+type Slot = Awaited<ReturnType<typeof NodeEd25519.engine>>
+
+test('every implemented primitive is present', () => {
+  expectTypeOf<Slot['getPublicKey']>().toEqualTypeOf<
+    (privateKey: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Slot['sign']>().toEqualTypeOf<
+    (payload: Uint8Array, privateKey: Uint8Array) => Uint8Array
+  >()
+  expectTypeOf<Slot['toMontgomerySecret']>().toEqualTypeOf<
+    (privateKey: Uint8Array) => Uint8Array
+  >()
+})
+
+test('unsupported primitives are absent', () => {
+  expectTypeOf<Slot>().not.toHaveProperty('randomSecretKey')
+  expectTypeOf<Slot>().not.toHaveProperty('toMontgomery')
+  expectTypeOf<Slot>().not.toHaveProperty('verify')
+})
+
+test('the result is the raw slot', () => {
+  expectTypeOf<{ Ed25519: Slot }>().toExtend<Engine.Engine>()
+})
+
+test('the Node namespace exposes the public Ed25519 API', () => {
+  expectTypeOf(NodeEd25519.getPublicKey).toEqualTypeOf(
+    core_Ed25519.getPublicKey,
+  )
+  expectTypeOf<typeof NodeEd25519>().not.toHaveProperty('create')
+})