ox 1.1.0 → 1.1.2

package/src/wasm/Engine.ts

@@ -1,55 +1,81 @@
 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 X25519 from './X25519.js'
 import type * as internal from './internal/instantiate.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'
+
 /**
- * Compiles every implementation this entrypoint provides and installs it.
+ * Compiles and installs every WASM implementation this entrypoint provides.
  *
- * WASM must be compiled asynchronously, so this is where the `await` lives.
- * Everything afterwards, including the hashing itself, is synchronous.
+ * Slot compilation starts concurrently. Nothing is installed until every slot
+ * resolves successfully.
  *
- * Call it once, during startup, before any crypto call. ox resolves the engine
- * at call time, so values computed beforehand used whatever was installed then.
+ * Call this once, during startup, before any crypto call. Ox resolves the
+ * engine at call time, so values computed beforehand used whatever was
+ * installed then.
  *
  * @example
  * ```ts twoslash
  * // @noErrors
- * import { Hash } from 'ox'
- * import { Engine } from 'ox/wasm'
+ * import { Engine, Hash } from 'ox/wasm'
  *
- * await Engine.load()
+ * await Engine.install()
  *
- * Hash.keccak256('0xdeadbeef')
+ * 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 async function install(): Promise<install.ReturnType> {
+  return CoreEngine.install({
+    Ed25519: Ed25519.engine(),
+    Hash: Hash.engine(),
+    Keystore: Keystore.engine(),
+    Mnemonic: Mnemonic.engine(),
+    X25519: X25519.engine(),
+  })
 }
 
-export declare namespace load {
-  type ReturnType = create.ReturnType
+export declare namespace install {
+  type ReturnType = engine.ReturnType
 
   type ErrorType =
-    | create.ErrorType
-    | CoreEngine.set.ErrorType
+    | engine.ErrorType
+    | CoreEngine.install.ErrorType
     | Errors.GlobalErrorType
 }
 
 /**
- * Compiles every implementation this entrypoint provides, without installing
- * it.
+ * Compiles every WASM implementation this entrypoint provides, without
+ * installing it.
  *
- * Reach for this where an engine has to exist as a value: measuring one
- * implementation against another, or installing through
- * [`Engine.with`](/api/Engine/with) for the duration of a call. Combining
- * engines does not need it, because
- * [`Engine.set`](/api/Engine/set) merges -- `await load()` followed by
- * `Engine.set({ Secp256k1 })` leaves both in place.
+ * Reach for this where an engine has to exist as a value, such as a benchmark
+ * or an [`Engine.with`](/api/Engine/with) scope. Use the individual module's
+ * `engine` function to select only some slots.
  *
  * @example
  * ```ts twoslash
@@ -57,20 +83,39 @@ export declare namespace load {
  * import { Engine, Hash } from 'ox'
  * import { Engine as Wasm } from 'ox/wasm'
  *
- * const wasm = await Wasm.create()
+ * const wasm = await Wasm.engine()
  *
- * Engine.with(wasm, () => Hash.keccak256('0xdeadbeef'))
+ * Engine.with(wasm, () => 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, x25519] = await Promise.all([
+    Ed25519.engine(),
+    Hash.engine(),
+    Keystore.engine(),
+    Mnemonic.engine(),
+    X25519.engine(),
+  ])
+  return {
+    Ed25519: ed25519,
+    Hash: hash,
+    Keystore: keystore,
+    Mnemonic: mnemonic,
+    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
+    X25519: X25519.engine.ReturnType
+  }
 
   type ErrorType = internal.MemoryError | Errors.GlobalErrorType
 }

package/src/wasm/Hash.bench.ts

@@ -3,7 +3,7 @@ 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 { bench, describe } from 'vp/test'
-import { create as createWasm } from './Hash.js'
+import { engine as wasmEngine } from './Hash.js'
 
 // Sizes expose fixed boundary overhead and sustained throughput. Crossovers
 // vary by primitive, runtime, and processor.
@@ -12,7 +12,7 @@ import { create as createWasm } from './Hash.js'
 // run Rust, and this portable benchmark must remain browser-compatible.
 const sizes = [32, 64, 256, 1024, 4096, 65_536, 1_048_576] as const
 
-const wasm = (await createWasm()).Hash
+const wasm = await wasmEngine()
 const key = Uint8Array.from({ length: 32 }, (_, index) => index % 97)
 
 for (const size of sizes) {

package/src/wasm/Hash.ts

@@ -1,38 +1,22 @@
 import type * as Engine from '../core/Engine.js'
 import type * as Errors from '../core/Errors.js'
+import * as blake3 from './internal/blake3.js'
 import * as hash from './internal/hash.js'
-import { wasmBase64 } from './internal/hashes.wasm.js'
+import * as hashes from './internal/hashes.js'
 import * as internal from './internal/instantiate.js'
 
+export * from '../core/Hash.js'
 export { MemoryError } from './internal/instantiate.js'
 
-type Exports = hash.Exports & {
-  keccak256(input: number, length: number, out: number): void
-  ripemd160(input: number, length: number, out: number): void
-  sha256(input: number, length: number, out: number): void
-}
-
 /** Digest sizes, in bytes. */
 const digestSize = { keccak256: 32, ripemd160: 20, sha256: 32 }
 
 /**
- * Compilation is memoized; the engine object deliberately is not.
- *
- * Handing every caller the same object means one of them customising a slot
- * for composition silently changes what a later `create` -- or `Engine.load`
- * -- installs.
- *
- * @internal
- */
-const instantiate = /*#__PURE__*/ internal.memoize(() =>
-  internal.instantiate<Exports>(wasmBase64),
-)
-
-/**
- * Compiles the WASM implementation of the [`Hash`](/api/Hash) primitives, without
- * installing it.
+ * Compiles the WASM implementation of the [`Hash`](/api/Hash) primitives,
+ * without installing it.
  *
- * Most callers want {@link ox#Engine.load} instead, which compiles every
+ * Most callers want
+ * [`Engine.install`](/wasm/crypto/Engine/install) instead, which compiles every
  * implementation this entrypoint provides and installs them in one call. Reach
  * for this to take the `Hash` slot on its own, or to hold the implementation
  * without touching the installed engine.
@@ -46,19 +30,22 @@ const instantiate = /*#__PURE__*/ internal.memoize(() =>
  * @example
  * ```ts twoslash
  * // @noErrors
- * import { Engine, Hash } from 'ox'
- * import * as WasmHash from 'ox/wasm/Hash'
+ * import { Engine } from 'ox'
+ * import { Hash } from 'ox/wasm'
  *
- * Engine.set(await WasmHash.create())
+ * await Engine.install({ Hash: Hash.engine() })
  *
  * Hash.keccak256('0xdeadbeef')
  * ```
  *
- * @returns An engine supplying the `Hash` slot.
+ * @returns The WASM implementation of the `Hash` slot.
  */
-export async function create(): Promise<create.ReturnType> {
+export async function engine(): Promise<engine.ReturnType> {
   {
-    const module = await instantiate()
+    const [blake3Module, module] = await Promise.all([
+      blake3.load(),
+      hashes.load(),
+    ])
 
     // Copies `input` in, runs `hash`, and copies the digest back out.
     function call(
@@ -77,32 +64,24 @@ export async function create(): Promise<create.ReturnType> {
     }
 
     return {
-      Hash: {
-        hmacSha256: (key, message) => hash.hmacSha256(module, key, message),
-        keccak256: (input) => call('keccak256', input),
-        ripemd160: (input) => call('ripemd160', input),
-        sha256: (input) => call('sha256', input),
-      },
+      blake3: (input) => blake3.hash(blake3Module, input),
+      hmacSha256: (key, message) => hash.hmacSha256(module, key, message),
+      keccak256: (input) => call('keccak256', input),
+      ripemd160: (input) => call('ripemd160', input),
+      sha256: (input) => call('sha256', input),
     }
   }
 }
 
-export declare namespace create {
-  /**
-   * The `Hash` slot, carrying every primitive this module implements.
-   *
-   * {@link ox#Engine.Engine} is optional all the way down so that an engine can
-   * fill in as little as it likes. This one always fills the same four, and
-   * saying so is what spares callers a non-null assertion per primitive.
-   */
+export declare namespace engine {
+  /** Every `Hash` primitive this module implements. */
   type ReturnType = {
-    Hash: {
-      [key in
-        | 'hmacSha256'
-        | 'keccak256'
-        | 'ripemd160'
-        | 'sha256']-?: NonNullable<Engine.Hash[key]>
-    }
+    [key in
+      | 'blake3'
+      | 'hmacSha256'
+      | 'keccak256'
+      | 'ripemd160'
+      | 'sha256']-?: NonNullable<Engine.Hash[key]>
   }
 
   type ErrorType = internal.MemoryError | Errors.GlobalErrorType

package/src/wasm/Keystore.ts

@@ -0,0 +1,48 @@
+import type * as Engine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+import * as hashes from './internal/hashes.js'
+import * as internal from './internal/instantiate.js'
+import * as pbkdf2 from './internal/pbkdf2.js'
+
+export * from '../core/Keystore.js'
+export { MemoryError } from './internal/instantiate.js'
+
+/**
+ * Compiles the WASM implementation of the [`Keystore`](/api/Keystore) PBKDF2
+ * primitive, without installing it.
+ *
+ * Most callers want
+ * [`Engine.install`](/wasm/crypto/Engine/install) instead, which compiles every
+ * implementation this entrypoint provides and installs them in one call. This
+ * provider deliberately stays synchronous and leaves AES, asynchronous PBKDF2,
+ * and scrypt on Ox's default implementation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Keystore } from 'ox/wasm'
+ *
+ * await Engine.install({ Keystore: Keystore.engine() })
+ *
+ * Keystore.pbkdf2({ password: 'testpassword' })
+ * ```
+ *
+ * @returns The WASM implementation of synchronous PBKDF2-HMAC-SHA256.
+ */
+export async function engine(): Promise<engine.ReturnType> {
+  const module = await hashes.load()
+  return {
+    pbkdf2Sha256: (password, salt, options) =>
+      pbkdf2.pbkdf2Sha256(module, password, salt, options),
+  }
+}
+
+export declare namespace engine {
+  /** The WASM `Keystore` primitives this module implements. */
+  type ReturnType = {
+    pbkdf2Sha256: NonNullable<Engine.Keystore['pbkdf2Sha256']>
+  }
+
+  type ErrorType = internal.MemoryError | Errors.GlobalErrorType
+}

package/src/wasm/Mnemonic.ts

@@ -0,0 +1,44 @@
+import type * as Engine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+import * as crypto25519 from './internal/crypto25519.js'
+import * as internal from './internal/instantiate.js'
+import * as mnemonic from './internal/mnemonic.js'
+
+export * from '../core/Mnemonic.js'
+export { MemoryError } from './internal/instantiate.js'
+
+/**
+ * Compiles the WASM implementation of [`Mnemonic.toSeed`](/api/Mnemonic/toSeed),
+ * without installing it.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Mnemonic } from 'ox/wasm'
+ *
+ * await Engine.install({ Mnemonic: Mnemonic.engine() })
+ *
+ * Mnemonic.toSeed(
+ *   'test test test test test test test test test test test junk'
+ * )
+ * ```
+ *
+ * @returns The WASM implementation of the `Mnemonic` slot.
+ */
+export async function engine(): Promise<engine.ReturnType> {
+  const module = await crypto25519.load()
+
+  return {
+    toSeed: (value, passphrase) => mnemonic.toSeed(module, value, passphrase),
+  }
+}
+
+export declare namespace engine {
+  /** Every `Mnemonic` primitive this module implements. */
+  type ReturnType = {
+    toSeed: NonNullable<Engine.Mnemonic['toSeed']>
+  }
+
+  type ErrorType = internal.MemoryError | Errors.GlobalErrorType
+}

package/src/wasm/X25519.ts

@@ -0,0 +1,70 @@
+import type * as Engine from '../core/Engine.js'
+import type * as Errors from '../core/Errors.js'
+import * as crypto25519 from './internal/crypto25519.js'
+import * as internal from './internal/instantiate.js'
+import * as x25519 from './internal/x25519.js'
+
+export * from '../core/X25519.js'
+export { MemoryError } from './internal/instantiate.js'
+
+const keySize = 32
+
+/**
+ * Compiles WASM implementations of selected [`X25519`](/api/X25519)
+ * primitives, without installing them.
+ *
+ * Random key generation remains on Ox's default implementation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { X25519 } from 'ox/wasm'
+ *
+ * await Engine.install({ X25519: X25519.engine() })
+ *
+ * X25519.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @returns The WASM implementation of part of the `X25519` slot.
+ */
+export async function engine(): Promise<engine.ReturnType> {
+  const module = await crypto25519.load()
+
+  return {
+    getPublicKey(privateKey) {
+      assertLength(privateKey, 'private')
+      module.reserve(keySize * 2)
+      const privateKeyPtr = module.heapBase
+      const publicKeyPtr = privateKeyPtr + keySize
+      try {
+        module.view().set(privateKey, privateKeyPtr)
+        module.exports.x25519_get_public_key(privateKeyPtr, publicKeyPtr)
+        return module.view().slice(publicKeyPtr, publicKeyPtr + keySize)
+      } finally {
+        module.exports.zero(privateKeyPtr, keySize * 2)
+      }
+    },
+    getSharedSecret(privateKey, publicKey) {
+      assertLength(privateKey, 'private')
+      assertLength(publicKey, 'public')
+      return x25519.getSharedSecret(module, privateKey, publicKey)
+    },
+  }
+}
+
+export declare namespace engine {
+  /** Every `X25519` primitive this module implements. */
+  type ReturnType = {
+    [key in 'getPublicKey' | 'getSharedSecret']-?: NonNullable<Engine.Ecdh[key]>
+  }
+
+  type ErrorType = internal.MemoryError | Errors.GlobalErrorType
+}
+
+function assertLength(key: Uint8Array, type: 'private' | 'public'): void {
+  if (key.length !== keySize)
+    throw new RangeError(
+      `X25519 ${type} key must be ${keySize} bytes, got ${key.length}`,
+    )
+}

package/src/wasm/_test/Crypto25519.conformance.ts

@@ -0,0 +1,57 @@
+import { ed25519, x25519 } from '@noble/curves/ed25519.js'
+import { mnemonicToSeedSync } from '@scure/bip39'
+import { describe, expect, test } from 'vp/test'
+import { vectors } from '../../../test/vectors/bip39/index.js'
+import * as Ed25519 from '../Ed25519.js'
+import * as Mnemonic from '../Mnemonic.js'
+import * as X25519 from '../X25519.js'
+
+describe('crypto25519 WASM', () => {
+  test('behavior: Ed25519 works in this runtime', async () => {
+    const engine = await Ed25519.engine()
+    const privateKey = fromHex(
+      '9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60',
+    )
+    const payload = new TextEncoder().encode('browser conformance')
+    const publicKey = engine.getPublicKey(privateKey)
+    const signature = engine.sign(payload, privateKey)
+
+    expect(publicKey).toEqual(ed25519.getPublicKey(privateKey))
+    expect(signature).toEqual(ed25519.sign(payload, privateKey))
+    expect(engine.verify(signature, payload, publicKey)).toBe(true)
+  })
+
+  test('behavior: X25519 works in this runtime', async () => {
+    const engine = await X25519.engine()
+    const privateKey = fromHex(
+      '77076d0a7318a57d3c16c17251b26645df4c2f87ebc0992ab177fba51db92c2a',
+    )
+    const peerPrivateKey = fromHex(
+      '5dab087e624a8a4b79e17f8b83800ee66f3bb1292618b6fd1c2f8b27ff88e0eb',
+    )
+    const publicKey = x25519.getPublicKey(peerPrivateKey)
+
+    expect(engine.getPublicKey(privateKey)).toEqual(
+      x25519.getPublicKey(privateKey),
+    )
+    expect(engine.getSharedSecret(privateKey, publicKey)).toEqual(
+      x25519.getSharedSecret(privateKey, publicKey),
+    )
+  })
+
+  test('behavior: Unicode BIP-39 works in this runtime', async () => {
+    const engine = await Mnemonic.engine()
+    const vector = vectors.japanese
+
+    expect(engine.toSeed(vector.mnemonic, vector.passphrase)).toEqual(
+      mnemonicToSeedSync(vector.mnemonic, vector.passphrase),
+    )
+  })
+})
+
+function fromHex(value: string): Uint8Array {
+  const bytes = new Uint8Array(value.length / 2)
+  for (let index = 0; index < bytes.length; index++)
+    bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16)
+  return bytes
+}