ox 1.0.5 → 1.1.0

package/src/core/internal/codec/hex.ts

@@ -19,40 +19,92 @@ const nibbleTable = /*#__PURE__*/ (() => {
   return table
 })()
 
-// Phase 2 native fast-path detection: `Uint8Array.prototype.toHex` lands in
-// Node 22+, Safari 18+, Firefox 133+. Falls back to `Buffer` on Node, then to
-// the JS loop.
+// Native fast-path detection. `Uint8Array.prototype.toHex` ships in Chromium
+// 145, Safari 18.2+ and Firefox 133+, but not in Node 24, which reaches
+// `Buffer` instead.
+//
+// Only *encoding* delegates to it. Encoding is total, so a native method has
+// nothing to get wrong; decoding has to reject, and the native decoders do not
+// do so reliably -- Chromium 145 reads U+C230 as the digit `0`, masking the
+// code unit to 8 bits exactly as `Buffer` does, and only rejects it from 149
+// on. test262 misses this because none of its illegal characters mask onto the
+// hex alphabet. Guarding `fromHex` costs an ASCII scan that leaves it only
+// 10-25% ahead of the loop, so it is not used at all.
 const _Buffer: typeof globalThis.Buffer | undefined = (
   globalThis as typeof globalThis & { Buffer?: typeof globalThis.Buffer }
 ).Buffer
 const nativeToHex: ((this: Uint8Array) => string) | undefined = (
   Uint8Array.prototype as Uint8Array & { toHex?: () => string }
 ).toHex
-const nativeFromHex: ((value: string) => Uint8Array) | undefined = (
-  Uint8Array as typeof Uint8Array & { fromHex?: (value: string) => Uint8Array }
-).fromHex
+
+/**
+ * Byte count below which {@link hexToBytesLoop} beats `Buffer.from(…, 'hex')`,
+ * whose fixed per-call cost short inputs cannot amortize. Measured on Node 24
+ * (V8 13.6): the crossover sits between 32 and 48 bytes, and 32 covers the
+ * sizes Ethereum work is made of -- 20-byte addresses and 32-byte words.
+ *
+ * `Buffer` is the only tier this applies to; where it is absent the loop
+ * decodes at every size. Re-measure before moving it.
+ *
+ * @internal
+ */
+const loopDecodeMaxBytes = 32
 
 /**
  * Encodes a `Uint8Array` into a `0x`-prefixed lowercase hex string. Uses the
- * native `Uint8Array.prototype.toHex` (Node 22+, Safari 18+, Firefox 133+) or
- * Node's `Buffer` when available; otherwise a tight JS loop.
+ * native `Uint8Array.prototype.toHex` or Node's `Buffer` when available;
+ * otherwise a tight JS loop.
  *
  * @internal
  */
 export function bytesToHex(value: Uint8Array): Hex {
-  if (nativeToHex) return `0x${nativeToHex.call(value)}` as Hex
-  if (_Buffer)
-    return `0x${_Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString('hex')}` as Hex
+  if (bytesToHexNative) return bytesToHexNative(value)
+  if (bytesToHexBuffer) return bytesToHexBuffer(value)
+  return bytesToHexLoop(value)
+}
+
+/**
+ * Encodes via `Uint8Array.prototype.toHex`, where the runtime has it.
+ * `undefined` otherwise, so callers and the conformance suite can both ask
+ * whether this tier exists rather than inferring it.
+ *
+ * @internal
+ */
+export const bytesToHexNative: ((value: Uint8Array) => Hex) | undefined =
+  nativeToHex && ((value) => `0x${nativeToHex.call(value)}` as Hex)
+
+/**
+ * Encodes via Node's `Buffer`, where the runtime has it.
+ *
+ * @internal
+ */
+export const bytesToHexBuffer: ((value: Uint8Array) => Hex) | undefined =
+  _Buffer &&
+  ((value) =>
+    `0x${_Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString('hex')}` as Hex)
+
+/**
+ * Encodes in plain JavaScript, for runtimes with neither the native method nor
+ * `Buffer`: browsers predating `Uint8Array.prototype.toHex`, which is recent
+ * enough that a meaningful share of installed browsers still land here.
+ *
+ * Appending to a string beats collecting substrings and joining them: V8 builds
+ * a rope and flattens it once, where `join` over an `Array.from({ length })`
+ * pays for a holey array as well as the concatenation. Measured at ~6.5x on a
+ * 32-byte input, counting the flatten.
+ *
+ * @internal
+ */
+export function bytesToHexLoop(value: Uint8Array): Hex {
   const length = value.length
-  const parts = Array.from<string>({ length })
-  for (let i = 0; i < length; i++) parts[i] = hexes[value[i]!]!
-  return `0x${parts.join('')}` as Hex
+  let hex = '0x'
+  for (let i = 0; i < length; i++) hex += hexes[value[i]!]
+  return hex as Hex
 }
 
 /**
  * Strictly decodes a `0x`-prefixed even-length hex string into a `Uint8Array`.
- * Uses the native `Uint8Array.fromHex` (Node 22+, Safari 18+, Firefox 133+) or
- * Node's `Buffer` when available; otherwise a tight JS loop.
+ * Uses a JS loop for short inputs and Node's `Buffer` for longer ones.
  *
  * @internal
  */
@@ -64,43 +116,72 @@ export function hexToBytes(value: string): Uint8Array {
     value.charCodeAt(1) !== 120 /* 'x' */
   )
     throw new InvalidHexValueError(value)
-  const body = value.length === 2 ? '' : (value as string).slice(2)
-  if ((body.length & 1) !== 0) throw new InvalidLengthError(value as Hex)
+  const nibbles = value.length - 2
+  if ((nibbles & 1) !== 0) throw new InvalidLengthError(value as Hex)
+  const length = nibbles >> 1
 
-  if (nativeFromHex) {
-    try {
-      return nativeFromHex(body)
-    } catch {
+  if (length <= loopDecodeMaxBytes) return hexToBytesLoop(value, length)
+  if (hexToBytesBuffer) return hexToBytesBuffer(value, length)
+  return hexToBytesLoop(value, length)
+}
+
+/**
+ * Decodes via Node's `Buffer`, where the runtime has it.
+ *
+ * @internal
+ */
+export const hexToBytesBuffer:
+  | ((value: string, length: number) => Uint8Array)
+  | undefined =
+  _Buffer &&
+  ((value, length) => {
+    const body = value.slice(2)
+    // `Buffer.from(…, 'hex')` masks each UTF-16 code unit to 8 bits, so a
+    // character above U+00FF can alias a hex digit: U+C230 masks to 0x30, the
+    // digit `0`, and `'0x숰0'` decodes to `0x00` instead of being rejected.
+    // Masking cannot fabricate a digit from pure ASCII, and a string is pure
+    // ASCII exactly when its UTF-8 length matches its code-unit count.
+    if (_Buffer.byteLength(body, 'utf8') !== body.length)
       throw new InvalidHexValueError(value)
-    }
-  }
-  if (_Buffer && body.length > 0) {
     // Buffer.from with 'hex' silently truncates on invalid chars; verify
     // byteLength matches expectations to detect malformed input.
-    const expected = body.length >> 1
     const buf = _Buffer.from(body, 'hex')
-    if (buf.length !== expected) throw new InvalidHexValueError(value)
+    if (buf.length !== length) throw new InvalidHexValueError(value)
     // Copy out of Buffer pool: callers may rely on `.buffer` being a
     // standalone ArrayBuffer (e.g. WebAuthn attestationObject round-trips).
     const out = new Uint8Array(buf.byteLength)
     out.set(buf)
     return out
-  }
+  })
 
-  const length = body.length >> 1
+/**
+ * Decodes in plain JavaScript, reading nibbles straight out of `value` from
+ * index 2 so no substring is materialized.
+ *
+ * Invalidity is accumulated rather than branched on per nibble: a valid nibble
+ * is at most `0x0f`, so only the `0xff` sentinel can set bit 7, and one check
+ * after the loop covers every character. `nibbleTable` only spans Latin-1, so a
+ * code unit above it reads `undefined` and has to be mapped to the sentinel --
+ * without that, a non-ASCII character would OR in as zero and decode silently.
+ *
+ * @internal
+ */
+export function hexToBytesLoop(value: string, length: number): Uint8Array {
   const out = new Uint8Array(length)
-  for (let i = 0, j = 0; i < length; i++) {
-    const hi = nibbleTable[body.charCodeAt(j++)]!
-    const lo = nibbleTable[body.charCodeAt(j++)]!
-    if (hi === 0xff || lo === 0xff) throw new InvalidHexValueError(value)
+  let invalid = 0
+  for (let i = 0, j = 2; i < length; i++) {
+    const hi = nibbleTable[value.charCodeAt(j++)] ?? 0xff
+    const lo = nibbleTable[value.charCodeAt(j++)] ?? 0xff
+    invalid |= hi | lo
     out[i] = (hi << 4) | lo
   }
+  if (invalid & 0x80) throw new InvalidHexValueError(value)
   return out
 }
 
 /** @internal */
 export function charCodeToBase16(char: number): number | undefined {
-  const v = nibbleTable[char]!
+  const v = nibbleTable[char] ?? 0xff
   return v === 0xff ? undefined : v
 }
 

package/src/core/internal/curves.ts

@@ -0,0 +1,18 @@
+/**
+ * Curve constants, inlined so that modules needing nothing but an order do not
+ * pull a curve implementation into the bundle.
+ *
+ * These are fixed by the curve specifications and are asserted against
+ * `@noble/curves` in `src/core/_test/curves.test.ts`.
+ *
+ * @internal
+ */
+
+/**
+ * Order of the secp256r1 (P-256) curve.
+ *
+ * @see https://www.secg.org/sec2-v2.pdf
+ * @internal
+ */
+export const p256N =
+  0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n

package/src/core/internal/ed25519.ts

@@ -0,0 +1,64 @@
+import { ed25519 } from '@noble/curves/ed25519.js'
+import { type Complete, type Eddsa, overrides } from './engine.js'
+
+/**
+ * Resolvers for the `Ed25519` 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<Eddsa>['getPublicKey'] = (privateKey) =>
+  ed25519.getPublicKey(privateKey)
+
+const randomSecretKeyDefault: Complete<Eddsa>['randomSecretKey'] = () =>
+  ed25519.utils.randomSecretKey()
+
+const signDefault: Complete<Eddsa>['sign'] = (payload, privateKey) =>
+  ed25519.sign(payload, privateKey)
+
+const toMontgomeryDefault: Complete<Eddsa>['toMontgomery'] = (publicKey) =>
+  ed25519.utils.toMontgomery(publicKey)
+
+const toMontgomerySecretDefault: Complete<Eddsa>['toMontgomerySecret'] = (
+  privateKey,
+) => ed25519.utils.toMontgomerySecret(privateKey)
+
+const verifyDefault: Complete<Eddsa>['verify'] = (
+  signature,
+  payload,
+  publicKey,
+) => ed25519.verify(signature, payload, publicKey)
+
+/** @internal */
+export const getPublicKey: Complete<Eddsa>['getPublicKey'] = (privateKey) =>
+  (overrides.Ed25519?.getPublicKey ?? getPublicKeyDefault)(privateKey)
+
+/** @internal */
+export const randomSecretKey: Complete<Eddsa>['randomSecretKey'] = () =>
+  (overrides.Ed25519?.randomSecretKey ?? randomSecretKeyDefault)()
+
+/** @internal */
+export const sign: Complete<Eddsa>['sign'] = (payload, privateKey) =>
+  (overrides.Ed25519?.sign ?? signDefault)(payload, privateKey)
+
+/** @internal */
+export const toMontgomery: Complete<Eddsa>['toMontgomery'] = (publicKey) =>
+  (overrides.Ed25519?.toMontgomery ?? toMontgomeryDefault)(publicKey)
+
+/** @internal */
+export const toMontgomerySecret: Complete<Eddsa>['toMontgomerySecret'] = (
+  privateKey,
+) =>
+  (overrides.Ed25519?.toMontgomerySecret ?? toMontgomerySecretDefault)(
+    privateKey,
+  )
+
+/** @internal */
+export const verify: Complete<Eddsa>['verify'] = (
+  signature,
+  payload,
+  publicKey,
+) => (overrides.Ed25519?.verify ?? verifyDefault)(signature, payload, publicKey)

package/src/core/internal/engine.ts

@@ -0,0 +1,410 @@
+/**
+ * Engine slot contracts and the override registry.
+ *
+ * This module intentionally has **no imports**. It is pulled into the module
+ * graph of every crypto module in ox, so it must not drag any dependency along
+ * with it. That constraint is also why the contracts speak raw `Uint8Array`
+ * rather than `Bytes.Bytes`/`Hex.Hex` -- coercion stays in the public module,
+ * and the engine boundary is plain bytes in, plain bytes out.
+ *
+ * The registry holds **overrides only**. Defaults are never registered here,
+ * because a registered default has to live on a complete slot object, and a
+ * slot object is a single reachable value: esbuild cannot drop the properties
+ * of one, so every default's `@noble/*` import survives into every bundle that
+ * touches the slot. Measured on a keccak256-only bundle, that costs 5 kB gzip.
+ * Instead each slot has a resolver module under `internal/` holding one binding
+ * per primitive, and the fallback is chosen there, per primitive.
+ *
+ * @internal
+ */
+
+/**
+ * Hash primitives. One-shot, synchronous, bytes in / bytes out.
+ *
+ * @internal
+ */
+export type Hash = {
+  /** BLAKE3, 32-byte digest. */
+  blake3?: ((input: Uint8Array) => Uint8Array) | undefined
+  /** HMAC-SHA256. */
+  hmacSha256?:
+    | ((key: Uint8Array, message: Uint8Array) => Uint8Array)
+    | undefined
+  /** Keccak256 (not FIPS-202 SHA3-256). */
+  keccak256?: ((input: Uint8Array) => Uint8Array) | undefined
+  /** RIPEMD-160. */
+  ripemd160?: ((input: Uint8Array) => Uint8Array) | undefined
+  /** SHA-256. */
+  sha256?: ((input: Uint8Array) => Uint8Array) | undefined
+}
+
+/**
+ * Short-Weierstrass ECDSA. Shared by the `Secp256k1` and `P256` slots.
+ *
+ * Signatures are always low-S normalized and always returned in 65-byte
+ * recovered form -- the contract mandates it, so an engine cannot silently opt
+ * out.
+ *
+ * @internal
+ */
+export type Ecdsa = {
+  /** Derives an uncompressed (65-byte) public key. */
+  getPublicKey?: ((privateKey: Uint8Array) => Uint8Array) | undefined
+  /**
+   * Computes a compressed (33-byte) ECDH shared secret.
+   *
+   * `publicKey` arrives in whichever SEC1 form the caller supplied, so an
+   * implementation has to accept both the compressed 33-byte and uncompressed
+   * 65-byte encodings.
+   */
+  getSharedSecret?:
+    | ((privateKey: Uint8Array, publicKey: Uint8Array) => Uint8Array)
+    | undefined
+  /**
+   * Recovers an uncompressed public key from a 65-byte `yParity || r || s`
+   * signature, the same layout {@link Ecdsa.sign} returns.
+   */
+  recoverPublicKey?:
+    | ((signature: Uint8Array, payload: Uint8Array) => Uint8Array)
+    | undefined
+  /** Generates a random private key. */
+  randomSecretKey?: (() => Uint8Array) | undefined
+  /** Signs a payload, returning 65 bytes of `yParity || r || s`. */
+  sign?:
+    | ((
+        payload: Uint8Array,
+        privateKey: Uint8Array,
+        options: {
+          /** Extra entropy for hedged signing, or `true` for random. */
+          extraEntropy: boolean | Uint8Array
+          /** Whether to hash the payload before signing. */
+          prehash: boolean
+        },
+      ) => Uint8Array)
+    | undefined
+  /** Verifies a 64-byte compact (`r || s`) signature. */
+  verify?:
+    | ((
+        signature: Uint8Array,
+        payload: Uint8Array,
+        publicKey: Uint8Array,
+        options: {
+          /** Whether to hash the payload before verifying. */
+          prehash: boolean
+        },
+      ) => boolean)
+    | undefined
+}
+
+/**
+ * Edwards-curve signatures (Ed25519).
+ *
+ * @internal
+ */
+export type Eddsa = {
+  /** Derives a 32-byte public key. */
+  getPublicKey?: ((privateKey: Uint8Array) => Uint8Array) | undefined
+  /** Generates a random private key. */
+  randomSecretKey?: (() => Uint8Array) | undefined
+  /** Signs a payload, returning a 64-byte signature. */
+  sign?:
+    | ((payload: Uint8Array, privateKey: Uint8Array) => Uint8Array)
+    | undefined
+  /** Converts an Ed25519 public key to its X25519 (Montgomery) form. */
+  toMontgomery?: ((publicKey: Uint8Array) => Uint8Array) | undefined
+  /** Converts an Ed25519 private key to its X25519 (Montgomery) form. */
+  toMontgomerySecret?: ((privateKey: Uint8Array) => Uint8Array) | undefined
+  /** Verifies a 64-byte signature. */
+  verify?:
+    | ((
+        signature: Uint8Array,
+        payload: Uint8Array,
+        publicKey: Uint8Array,
+      ) => boolean)
+    | undefined
+}
+
+/**
+ * Montgomery-curve key agreement (X25519).
+ *
+ * @internal
+ */
+export type Ecdh = {
+  /** Derives a 32-byte public key. */
+  getPublicKey?: ((privateKey: Uint8Array) => Uint8Array) | undefined
+  /** Computes a 32-byte shared secret. */
+  getSharedSecret?:
+    | ((privateKey: Uint8Array, publicKey: Uint8Array) => Uint8Array)
+    | undefined
+  /** Generates a random private key. */
+  randomSecretKey?: (() => Uint8Array) | undefined
+}
+
+/**
+ * Key derivation and symmetric primitives used by keystores.
+ *
+ * The `*Async` functions resolve independently of their synchronous twins --
+ * an engine that supplies only `scrypt` leaves `scryptAsync` on the default
+ * implementation, because wrapping a long synchronous call in a promise is
+ * worse than a genuinely yielding one.
+ *
+ * @internal
+ */
+export type Keystore = {
+  /** AES-CTR decryption (key length selects AES-128/192/256). */
+  aesCtrDecrypt?:
+    | ((key: Uint8Array, iv: Uint8Array, data: Uint8Array) => Uint8Array)
+    | undefined
+  /** AES-CTR encryption (key length selects AES-128/192/256). */
+  aesCtrEncrypt?:
+    | ((key: Uint8Array, iv: Uint8Array, data: Uint8Array) => Uint8Array)
+    | undefined
+  /** PBKDF2-HMAC-SHA256. */
+  pbkdf2Sha256?:
+    | ((
+        password: Uint8Array,
+        salt: Uint8Array,
+        options: { c: number; dkLen: number },
+      ) => Uint8Array)
+    | undefined
+  /** Asynchronous PBKDF2-HMAC-SHA256. */
+  pbkdf2Sha256Async?:
+    | ((
+        password: Uint8Array,
+        salt: Uint8Array,
+        options: { c: number; dkLen: number },
+      ) => Promise<Uint8Array>)
+    | undefined
+  /** scrypt. */
+  scrypt?:
+    | ((
+        password: Uint8Array,
+        salt: Uint8Array,
+        options: { N: number; dkLen: number; p: number; r: number },
+      ) => Uint8Array)
+    | undefined
+  /** Asynchronous scrypt. */
+  scryptAsync?:
+    | ((
+        password: Uint8Array,
+        salt: Uint8Array,
+        options: { N: number; dkLen: number; p: number; r: number },
+      ) => Promise<Uint8Array>)
+    | undefined
+}
+
+/**
+ * BIP-39 seed derivation (PBKDF2-HMAC-SHA512, 2048 iterations).
+ *
+ * Mnemonic generation, validation, and the wordlists themselves are plain data
+ * and string handling, so they are not part of the engine boundary.
+ *
+ * @internal
+ */
+export type Mnemonic = {
+  /** Derives a 64-byte seed from a mnemonic phrase and optional passphrase. */
+  toSeed?: ((mnemonic: string, passphrase?: string) => Uint8Array) | undefined
+}
+
+/**
+ * BLS12-381 operations.
+ *
+ * Points cross this boundary in their compressed serialized form (48 bytes for
+ * G1, 96 for G2), never as projective coordinate triples -- an engine backed by
+ * a native library cannot be expected to reproduce another library's internal
+ * point representation.
+ *
+ * @internal
+ */
+export type Bls = {
+  /** Aggregates compressed points of the same group. */
+  aggregate?:
+    | ((points: readonly Uint8Array[], group: 'G1' | 'G2') => Uint8Array)
+    | undefined
+  /** Derives a compressed public key in the given group. */
+  getPublicKey?:
+    | ((privateKey: Uint8Array, group: 'G1' | 'G2') => Uint8Array)
+    | undefined
+  /** Generates a random private key. */
+  randomSecretKey?: (() => Uint8Array) | undefined
+  /** Signs a payload, returning a compressed point in the opposite group. */
+  sign?:
+    | ((
+        payload: Uint8Array,
+        privateKey: Uint8Array,
+        options: {
+          /** Domain separation tag for hash-to-curve. */
+          dst?: Uint8Array | undefined
+          /** Group of the signature. */
+          group: 'G1' | 'G2'
+        },
+      ) => Uint8Array)
+    | undefined
+  /** Verifies a compressed signature against a compressed public key. */
+  verify?:
+    | ((
+        signature: Uint8Array,
+        payload: Uint8Array,
+        publicKey: Uint8Array,
+        options: {
+          /** Domain separation tag for hash-to-curve. */
+          dst?: Uint8Array | undefined
+          /** Group of the signature. */
+          signatureGroup: 'G1' | 'G2'
+        },
+      ) => boolean)
+    | undefined
+}
+
+/**
+ * Root engine type. Slots and functions are optional; omissions preserve
+ * earlier overrides, or use Ox's default when none exists.
+ *
+ * @internal
+ */
+export type Engine = {
+  /** Implementation for {@link ox#Bls}. */
+  Bls?: Bls | undefined
+  /** Implementation for {@link ox#Ed25519}. */
+  Ed25519?: Eddsa | undefined
+  /** Implementation for {@link ox#Hash}. */
+  Hash?: Hash | undefined
+  /** Implementation for {@link ox#Keystore}. */
+  Keystore?: Keystore | undefined
+  /** Implementation for {@link ox#Mnemonic}. */
+  Mnemonic?: Mnemonic | undefined
+  /** Implementation for {@link ox#P256}. */
+  P256?: Ecdsa | undefined
+  /** Implementation for {@link ox#Secp256k1}. */
+  Secp256k1?: Ecdsa | undefined
+  /** Implementation for {@link ox#X25519}. */
+  X25519?: Ecdh | undefined
+}
+
+/**
+ * A slot with every function present.
+ *
+ * Slots are optional all the way down so that an engine can fill in as little
+ * as it likes. ox's own default implementations are held to the opposite
+ * standard: they back every function ox routes, so they are declared against
+ * this instead, and a default that goes missing or drifts from the contract
+ * fails to compile.
+ *
+ * @internal
+ */
+export type Complete<slot> = { [key in keyof slot]-?: NonNullable<slot[key]> }
+
+/**
+ * Recognized slot names, in the order they appear on {@link Engine}.
+ *
+ * @internal
+ */
+export const slots = [
+  'Bls',
+  'Ed25519',
+  'Hash',
+  'Keystore',
+  'Mnemonic',
+  'P256',
+  'Secp256k1',
+  'X25519',
+] as const satisfies readonly (keyof Engine)[]
+
+/**
+ * Recognized primitive names, per slot.
+ *
+ * An override stored under a name no resolver reads is invisible: the default
+ * keeps running and nothing is reported, so a typo looks exactly like success.
+ * That is worst for the callers who can least afford it -- someone installing a
+ * policy-constrained or hardware-backed implementation silently gets ox's
+ * default instead. {@link Engine.set} checks against this to make it loud.
+ *
+ * @internal
+ */
+export const primitives = {
+  Bls: ['aggregate', 'getPublicKey', 'randomSecretKey', 'sign', 'verify'],
+  Ed25519: [
+    'getPublicKey',
+    'randomSecretKey',
+    'sign',
+    'toMontgomery',
+    'toMontgomerySecret',
+    'verify',
+  ],
+  Hash: ['blake3', 'hmacSha256', 'keccak256', 'ripemd160', 'sha256'],
+  Keystore: [
+    'aesCtrDecrypt',
+    'aesCtrEncrypt',
+    'pbkdf2Sha256',
+    'pbkdf2Sha256Async',
+    'scrypt',
+    'scryptAsync',
+  ],
+  Mnemonic: ['toSeed'],
+  P256: [
+    'getPublicKey',
+    'getSharedSecret',
+    'recoverPublicKey',
+    'randomSecretKey',
+    'sign',
+    'verify',
+  ],
+  Secp256k1: [
+    'getPublicKey',
+    'getSharedSecret',
+    'recoverPublicKey',
+    'randomSecretKey',
+    'sign',
+    'verify',
+  ],
+  X25519: ['getPublicKey', 'getSharedSecret', 'randomSecretKey'],
+} as const satisfies {
+  [key in keyof Engine]-?: readonly (keyof Complete<NonNullable<Engine[key]>>)[]
+}
+
+/**
+ * The installed overrides. Empty by default -- a bare object literal, so
+ * bundlers treat it as side-effect free.
+ *
+ * @internal
+ */
+export const overrides: Engine = {}
+
+/**
+ * Merges overrides into the registry, one level deep. A slot set to `undefined`
+ * is removed.
+ *
+ * @internal
+ */
+export function merge(value: Engine) {
+  for (const key of Object.keys(value) as (keyof Engine)[]) {
+    const slot = value[key]
+    if (slot === undefined) {
+      delete overrides[key]
+      continue
+    }
+    // A member set to `undefined` clears that primitive. Spreading would keep
+    // it as an own property: calls still fall through to the default, but
+    // `get` would report an override that is not there.
+    const merged: Record<string, unknown> = { ...overrides[key] }
+    for (const [name, fn] of Object.entries(slot)) {
+      if (fn === undefined) delete merged[name]
+      else merged[name] = fn
+    }
+    // An empty slot stays: `set({ Hash: {} })` is a no-op a caller wrote
+    // deliberately, and `get` has always reported it.
+    overrides[key] = merged as never
+  }
+}
+
+/**
+ * Removes one slot, or every slot when `slot` is omitted.
+ *
+ * @internal
+ */
+export function reset(slot?: keyof Engine) {
+  if (slot) delete overrides[slot]
+  else
+    for (const key of Object.keys(overrides) as (keyof Engine)[])
+      delete overrides[key]
+}