ox 1.4.0 → 1.6.0

package/src/tempo/index.ts

@@ -529,6 +529,30 @@ export * as VirtualAddress from './VirtualAddress.js'
  */
 export * as VirtualMaster from './VirtualMaster.js'
 
+/**
+ * Utilities for deriving the sender tag that correlates a Zone withdrawal with
+ * its indexed parent-chain `WithdrawalProcessed` event.
+ *
+ * The sender tag commits to the withdrawal sender and the Zone transaction hash
+ * containing the `ZoneOutbox.requestWithdrawal` call.
+ *
+ * [Authenticated Withdrawals Specification](https://github.com/tempoxyz/zones/blob/main/specs/spec.md#authenticated-withdrawals)
+ *
+ * @example
+ * ```ts twoslash
+ * import { WithdrawalSenderTag } from 'ox/tempo'
+ *
+ * const senderTag = WithdrawalSenderTag.from({
+ *   sender: '0x1234567890abcdef1234567890abcdef12345678',
+ *   transactionHash:
+ *     '0xabababababababababababababababababababababababababababababababab'
+ * })
+ * ```
+ *
+ * @category Reference
+ */
+export * as WithdrawalSenderTag from './WithdrawalSenderTag.js'
+
 /**
  * Zone ID utilities for converting between zone IDs and zone chain IDs.
  *

package/src/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '1.4.0'
+export const version = '1.6.0'

package/src/wasm/Engine.ts

@@ -3,7 +3,9 @@ import type * as Errors from '../core/Errors.js'
 import * as Ed25519 from './Ed25519.js'
 import * as Hash from './Hash.js'
 import * as keystore from './internal/keystore.js'
+import * as MlDsa44 from './MlDsa44.js'
 import * as Mnemonic from './Mnemonic.js'
+import * as Secp256k1 from './Secp256k1.js'
 import * as X25519 from './X25519.js'
 import type * as internal from './internal/instantiate.js'
 
@@ -26,6 +28,7 @@ export type {
   Hash,
   HashState,
   Keystore,
+  MlDsa,
   Mnemonic,
 } from '../core/Engine.js'
 
@@ -56,7 +59,9 @@ export async function install(): Promise<install.ReturnType> {
     Ed25519: Ed25519.engine(),
     Hash: Hash.engine(),
     Keystore: keystore.engine(),
+    MlDsa44: MlDsa44.engine(),
     Mnemonic: Mnemonic.engine(),
+    Secp256k1: Secp256k1.engine(),
     X25519: X25519.engine(),
   })
 }
@@ -92,18 +97,23 @@ export declare namespace install {
  * @returns An engine, ready to install.
  */
 export async function engine(): Promise<engine.ReturnType> {
-  const [ed25519, hash, keystoreEngine, mnemonic, x25519] = await Promise.all([
-    Ed25519.engine(),
-    Hash.engine(),
-    keystore.engine(),
-    Mnemonic.engine(),
-    X25519.engine(),
-  ])
+  const [ed25519, hash, keystoreEngine, mlDsa44, mnemonic, secp256k1, x25519] =
+    await Promise.all([
+      Ed25519.engine(),
+      Hash.engine(),
+      keystore.engine(),
+      MlDsa44.engine(),
+      Mnemonic.engine(),
+      Secp256k1.engine(),
+      X25519.engine(),
+    ])
   return {
     Ed25519: ed25519,
     Hash: hash,
     Keystore: keystoreEngine,
+    MlDsa44: mlDsa44,
     Mnemonic: mnemonic,
+    Secp256k1: secp256k1,
     X25519: x25519,
   }
 }
@@ -116,7 +126,9 @@ export declare namespace engine {
     Keystore: {
       pbkdf2Sha256: NonNullable<CoreEngine.Keystore['pbkdf2Sha256']>
     }
+    MlDsa44: MlDsa44.engine.ReturnType
     Mnemonic: Mnemonic.engine.ReturnType
+    Secp256k1: Secp256k1.engine.ReturnType
     X25519: X25519.engine.ReturnType
   }
 

package/src/wasm/MlDsa44.ts

@@ -0,0 +1,190 @@
+import type * as Engine from '../core/Engine.js'
+import * as Errors from '../core/Errors.js'
+import * as internal from './internal/instantiate.js'
+import * as mldsa44 from './internal/mldsa44.js'
+
+export * from '../core/MlDsa44.js'
+export { MemoryError } from './internal/instantiate.js'
+
+const privateKeySize = 32
+const publicKeySize = 1312
+const signatureSize = 2420
+const randomSize = 32
+const maxContextSize = 255
+
+/**
+ * Compiles WASM implementations of selected [`MlDsa44`](/api/MlDsa44)
+ * primitives, without installing them.
+ *
+ * Random key generation remains on Ox's host-backed default implementation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { MlDsa44 } from 'ox/wasm'
+ *
+ * await Engine.install({ MlDsa44: MlDsa44.engine() })
+ *
+ * MlDsa44.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @returns The WASM implementation of part of the `MlDsa44` slot.
+ */
+export async function engine(): Promise<engine.ReturnType> {
+  const module = await mldsa44.load()
+
+  return {
+    getPublicKey(privateKey) {
+      assertLength(privateKey, privateKeySize, 'private key')
+      const size = privateKeySize + publicKeySize
+      module.reserve(size)
+      const privateKeyPtr = module.heapBase
+      const publicKeyPtr = privateKeyPtr + privateKeySize
+      try {
+        module.view().set(privateKey, privateKeyPtr)
+        if (
+          module.exports.mldsa44_get_public_key(privateKeyPtr, publicKeyPtr) !==
+          1
+        )
+          throw new InvalidInputError({ operation: 'getPublicKey' })
+        return module.view().slice(publicKeyPtr, publicKeyPtr + publicKeySize)
+      } finally {
+        module.exports.zero(privateKeyPtr, size)
+      }
+    },
+    sign(payload, privateKey, options) {
+      assertLength(privateKey, privateKeySize, 'private key')
+      const context = options.context ?? new Uint8Array(0)
+      assertContextLength(context)
+      // FIPS 204 hedged signing draws 32 bytes of randomness; the
+      // deterministic variant pins them to zero.
+      const random =
+        options.extraEntropy === true
+          ? crypto.getRandomValues(new Uint8Array(randomSize))
+          : options.extraEntropy === false
+            ? new Uint8Array(randomSize)
+            : options.extraEntropy
+      assertLength(random, randomSize, 'extra entropy')
+      const size =
+        privateKeySize +
+        randomSize +
+        context.length +
+        payload.length +
+        signatureSize
+      module.reserve(size)
+      const privateKeyPtr = module.heapBase
+      const randomPtr = privateKeyPtr + privateKeySize
+      const contextPtr = randomPtr + randomSize
+      const payloadPtr = contextPtr + context.length
+      const signaturePtr = payloadPtr + payload.length
+      try {
+        const memory = module.view()
+        memory.set(privateKey, privateKeyPtr)
+        memory.set(random, randomPtr)
+        memory.set(context, contextPtr)
+        memory.set(payload, payloadPtr)
+        if (
+          module.exports.mldsa44_sign(
+            privateKeyPtr,
+            payloadPtr,
+            payload.length,
+            contextPtr,
+            context.length,
+            randomPtr,
+            signaturePtr,
+          ) !== 1
+        )
+          throw new InvalidInputError({ operation: 'sign' })
+        return module.view().slice(signaturePtr, signaturePtr + signatureSize)
+      } finally {
+        module.exports.zero(privateKeyPtr, size)
+      }
+    },
+    verify(signature, payload, publicKey, options) {
+      assertLength(publicKey, publicKeySize, 'public key')
+      const context = options.context ?? new Uint8Array(0)
+      assertContextLength(context)
+      // A malformed signature is a verification failure, not an error.
+      if (signature.length !== signatureSize) return false
+      const size =
+        signatureSize + context.length + payload.length + publicKeySize
+      module.reserve(size)
+      const signaturePtr = module.heapBase
+      const contextPtr = signaturePtr + signatureSize
+      const payloadPtr = contextPtr + context.length
+      const publicKeyPtr = payloadPtr + payload.length
+      try {
+        const memory = module.view()
+        memory.set(signature, signaturePtr)
+        memory.set(context, contextPtr)
+        memory.set(payload, payloadPtr)
+        memory.set(publicKey, publicKeyPtr)
+        return (
+          module.exports.mldsa44_verify(
+            signaturePtr,
+            payloadPtr,
+            payload.length,
+            contextPtr,
+            context.length,
+            publicKeyPtr,
+          ) === 1
+        )
+      } finally {
+        module.exports.zero(signaturePtr, size)
+      }
+    },
+  }
+}
+
+export declare namespace engine {
+  /** Every `MlDsa44` primitive this module implements. */
+  type ReturnType = {
+    [key in 'getPublicKey' | 'sign' | 'verify']-?: NonNullable<
+      Engine.MlDsa[key]
+    >
+  }
+
+  type ErrorType =
+    | InvalidInputError
+    | internal.MemoryError
+    | Errors.GlobalErrorType
+}
+
+function assertLength(value: Uint8Array, length: number, name: string): void {
+  if (value.length !== length)
+    throw new RangeError(
+      `ML-DSA-44 ${name} must be ${length} bytes, got ${value.length}`,
+    )
+}
+
+function assertContextLength(context: Uint8Array): void {
+  if (context.length > maxContextSize)
+    throw new RangeError(
+      `ML-DSA-44 context must be at most ${maxContextSize} bytes, got ${context.length}`,
+    )
+}
+
+/**
+ * Thrown when mldsa-native rejects an input or fails to produce a signature.
+ *
+ * @example
+ * ```ts twoslash
+ * import { MlDsa44 } from 'ox/wasm'
+ *
+ * try {
+ *   const engine = await MlDsa44.engine()
+ *   engine.getPublicKey(new Uint8Array(32))
+ * } catch (error) {
+ *   if (error instanceof MlDsa44.InvalidInputError)
+ *     console.error(error.message)
+ * }
+ * ```
+ */
+export class InvalidInputError extends Errors.BaseError {
+  override readonly name = 'MlDsa44.InvalidInputError'
+
+  constructor({ operation }: { operation: string }) {
+    super(`WASM ML-DSA-44 ${operation} received invalid input.`)
+  }
+}

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

@@ -11,6 +11,8 @@ test('install and engine expose the same precise engine', () => {
     (input: Uint8Array) => Uint8Array
   >()
   expectTypeOf<Installed['Keystore']>().not.toHaveProperty('scrypt')
+  expectTypeOf<Installed['MlDsa44']>().not.toHaveProperty('randomSecretKey')
+  expectTypeOf<Installed['Secp256k1']>().not.toHaveProperty('randomSecretKey')
 })
 
 test('the WASM Engine namespace exposes synchronous core operations', () => {

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

@@ -10,7 +10,9 @@ describe('engine', () => {
         "Ed25519",
         "Hash",
         "Keystore",
+        "MlDsa44",
         "Mnemonic",
+        "Secp256k1",
         "X25519",
       ]
     `)
@@ -39,7 +41,9 @@ describe('install', () => {
         "Ed25519",
         "Hash",
         "Keystore",
+        "MlDsa44",
         "Mnemonic",
+        "Secp256k1",
         "X25519",
       ]
     `)
@@ -88,9 +92,21 @@ describe('install', () => {
           "Keystore": [
             "pbkdf2Sha256",
           ],
+          "MlDsa44": [
+            "getPublicKey",
+            "sign",
+            "verify",
+          ],
           "Mnemonic": [
             "toSeed",
           ],
+          "Secp256k1": [
+            "getPublicKey",
+            "getSharedSecret",
+            "recoverPublicKey",
+            "sign",
+            "verify",
+          ],
           "X25519": [
             "getPublicKey",
             "getSharedSecret",

package/src/wasm/_test/MlDsa44.test-d.ts

@@ -0,0 +1,28 @@
+import { expectTypeOf, test } from 'vp/test'
+import type * as Engine from '../../core/Engine.js'
+import * as core_MlDsa44 from '../../core/MlDsa44.js'
+import * as MlDsa44 from '../MlDsa44.js'
+
+type Slot = Awaited<ReturnType<typeof MlDsa44.engine>>
+
+test('return type exposes only deterministic MlDsa44 primitives', () => {
+  expectTypeOf<Slot['getPublicKey']>().toEqualTypeOf<
+    NonNullable<Engine.MlDsa['getPublicKey']>
+  >()
+  expectTypeOf<Slot['sign']>().toEqualTypeOf<
+    NonNullable<Engine.MlDsa['sign']>
+  >()
+  expectTypeOf<Slot['verify']>().toEqualTypeOf<
+    NonNullable<Engine.MlDsa['verify']>
+  >()
+  expectTypeOf<Slot>().not.toHaveProperty('randomSecretKey')
+})
+
+test('the WASM namespace exposes the public MlDsa44 API', () => {
+  expectTypeOf(MlDsa44.getPublicKey).toEqualTypeOf(core_MlDsa44.getPublicKey)
+  expectTypeOf(MlDsa44.randomPrivateKey).toEqualTypeOf(
+    core_MlDsa44.randomPrivateKey,
+  )
+  expectTypeOf(MlDsa44.sign).toEqualTypeOf(core_MlDsa44.sign)
+  expectTypeOf(MlDsa44.verify).toEqualTypeOf(core_MlDsa44.verify)
+})

package/src/wasm/_test/MlDsa44.test.ts

@@ -0,0 +1,192 @@
+import { ml_dsa44 } from '@noble/post-quantum/ml-dsa.js'
+import { Engine } from 'ox'
+import { describe, expect, test } from 'vp/test'
+import * as MlDsa44 from '../MlDsa44.js'
+
+const seed = new Uint8Array(32).fill(7)
+const keys = ml_dsa44.keygen(seed)
+const payload = Uint8Array.of(0xde, 0xad, 0xbe, 0xef)
+
+function nobleSign(
+  payload: Uint8Array,
+  options: { context?: Uint8Array; extraEntropy?: Uint8Array | false } = {},
+) {
+  return ml_dsa44.sign(payload, keys.secretKey, {
+    extraEntropy: false,
+    ...options,
+  })
+}
+
+describe('engine', () => {
+  test('behavior: exposes only deterministic primitives', async () => {
+    const engine = await MlDsa44.engine()
+
+    expect(Object.keys(engine).sort()).toMatchInlineSnapshot(`
+      [
+        "getPublicKey",
+        "sign",
+        "verify",
+      ]
+    `)
+  })
+
+  test('behavior: matches noble public keys', async () => {
+    const engine = await MlDsa44.engine()
+
+    expect(engine.getPublicKey(seed)).toEqual(keys.publicKey)
+  })
+
+  test('behavior: matches noble signing across payload boundaries', async () => {
+    const engine = await MlDsa44.engine()
+
+    for (const size of [0, 1, 31, 32, 33, 64, 1024, 100_000]) {
+      const payload = new Uint8Array(size).fill(size % 256)
+      const signature = engine.sign(payload, seed, { extraEntropy: false })
+
+      expect(signature).toEqual(nobleSign(payload))
+      expect(engine.verify(signature, payload, keys.publicKey, {})).toBe(true)
+      expect(ml_dsa44.verify(signature, payload, keys.publicKey)).toBe(true)
+    }
+  })
+
+  test('behavior: matches noble signing with context and entropy', async () => {
+    const engine = await MlDsa44.engine()
+    const context = Uint8Array.of(1, 2, 3)
+    const entropy = new Uint8Array(32).fill(9)
+
+    for (const options of [
+      { context },
+      { extraEntropy: entropy },
+      { context, extraEntropy: entropy },
+      { context: new Uint8Array(255).fill(5) },
+    ] as const) {
+      const signature = engine.sign(payload, seed, {
+        extraEntropy: false,
+        ...options,
+      })
+
+      expect(signature).toEqual(nobleSign(payload, options))
+      expect(
+        engine.verify(signature, payload, keys.publicKey, {
+          context: options.context,
+        }),
+      ).toBe(true)
+    }
+  })
+
+  test('behavior: context binds verification', async () => {
+    const engine = await MlDsa44.engine()
+    const context = Uint8Array.of(1)
+    const signature = engine.sign(payload, seed, {
+      context,
+      extraEntropy: false,
+    })
+
+    expect(engine.verify(signature, payload, keys.publicKey, { context })).toBe(
+      true,
+    )
+    expect(engine.verify(signature, payload, keys.publicKey, {})).toBe(false)
+    expect(
+      engine.verify(signature, payload, keys.publicKey, {
+        context: Uint8Array.of(2),
+      }),
+    ).toBe(false)
+  })
+
+  test('behavior: generates host entropy for hedged signing', async () => {
+    const engine = await MlDsa44.engine()
+    const signatureA = engine.sign(payload, seed, { extraEntropy: true })
+    const signatureB = engine.sign(payload, seed, { extraEntropy: true })
+
+    expect(signatureA).not.toEqual(signatureB)
+    expect(engine.verify(signatureA, payload, keys.publicKey, {})).toBe(true)
+    expect(engine.verify(signatureB, payload, keys.publicKey, {})).toBe(true)
+    expect(ml_dsa44.verify(signatureA, payload, keys.publicKey)).toBe(true)
+  })
+
+  test('behavior: rejects corrupted and truncated signatures', async () => {
+    const engine = await MlDsa44.engine()
+    const signature = engine.sign(payload, seed, { extraEntropy: false })
+
+    for (const corrupt of [0, 1, 100, 2419]) {
+      const bad = signature.slice()
+      bad[corrupt]! ^= 1
+      expect(engine.verify(bad, payload, keys.publicKey, {})).toBe(false)
+    }
+    expect(engine.verify(signature.slice(1), payload, keys.publicKey, {})).toBe(
+      false,
+    )
+    expect(engine.verify(new Uint8Array(0), payload, keys.publicKey, {})).toBe(
+      false,
+    )
+    expect(engine.verify(signature, payload.slice(1), keys.publicKey, {})).toBe(
+      false,
+    )
+  })
+
+  test('behavior: rejects noble signatures made with other keys', async () => {
+    const engine = await MlDsa44.engine()
+    const other = ml_dsa44.keygen(new Uint8Array(32).fill(8))
+    const signature = engine.sign(payload, seed, { extraEntropy: false })
+
+    expect(engine.verify(signature, payload, other.publicKey, {})).toBe(false)
+  })
+
+  test('behavior: installs into the Engine registry', async () => {
+    await Engine.install({ MlDsa44: MlDsa44.engine() })
+    try {
+      expect(Engine.get().MlDsa44).toBeDefined()
+
+      const signature = MlDsa44.sign({
+        payload: '0xdeadbeef',
+        privateKey: seed,
+        as: 'Bytes',
+      })
+      expect(signature).toEqual(nobleSign(payload))
+      expect(
+        MlDsa44.verify({
+          payload: '0xdeadbeef',
+          publicKey: keys.publicKey,
+          signature,
+        }),
+      ).toBe(true)
+    } finally {
+      Engine.reset('MlDsa44')
+    }
+  })
+
+  test('error: rejects malformed inputs', async () => {
+    const engine = await MlDsa44.engine()
+
+    for (const size of [0, 31, 33, 2560]) {
+      expect(() => engine.getPublicKey(new Uint8Array(size))).toThrowError(
+        `ML-DSA-44 private key must be 32 bytes, got ${size}`,
+      )
+      expect(() =>
+        engine.sign(payload, new Uint8Array(size), { extraEntropy: false }),
+      ).toThrowError(`ML-DSA-44 private key must be 32 bytes, got ${size}`)
+    }
+    expect(() =>
+      engine.sign(payload, seed, { extraEntropy: new Uint8Array(31) }),
+    ).toThrowError('ML-DSA-44 extra entropy must be 32 bytes, got 31')
+    expect(() =>
+      engine.sign(payload, seed, {
+        context: new Uint8Array(256),
+        extraEntropy: false,
+      }),
+    ).toThrowError('ML-DSA-44 context must be at most 255 bytes, got 256')
+    expect(() =>
+      engine.verify(
+        new Uint8Array(2420),
+        payload,
+        keys.publicKey.slice(0, 100),
+        {},
+      ),
+    ).toThrowError('ML-DSA-44 public key must be 1312 bytes, got 100')
+    expect(() =>
+      engine.verify(new Uint8Array(2420), payload, keys.publicKey, {
+        context: new Uint8Array(256),
+      }),
+    ).toThrowError('ML-DSA-44 context must be at most 255 bytes, got 256')
+  })
+})

package/src/wasm/index.ts

@@ -105,6 +105,28 @@ export * as Keystore from './Keystore.js'
  */
 export * as Kzg from './Kzg.js'
 
+/**
+ * WASM implementations of Ox's supported ML-DSA-44 primitives, backed by
+ * [mldsa-native](https://github.com/pq-code-package/mldsa-native).
+ *
+ * This provider is installed by [`Engine.install`](/api/Engine/install), or
+ * can be installed individually.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { MlDsa44 } from 'ox/wasm'
+ *
+ * await Engine.install({ MlDsa44: MlDsa44.engine() })
+ *
+ * MlDsa44.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @category Post Quantum
+ */
+export * as MlDsa44 from './MlDsa44.js'
+
 /**
  * WASM implementation of Ox's BIP-39 seed derivation.
  *
@@ -128,8 +150,8 @@ export * as Mnemonic from './Mnemonic.js'
 /**
  * WASM implementations of deterministic Secp256k1 primitives.
  *
- * This provider is opt-in because its embedded libsecp256k1 artifact is larger
- * than the modules installed by [`Engine.install`](/api/Engine/install).
+ * This provider is installed by [`Engine.install`](/api/Engine/install), or
+ * can be installed individually.
  *
  * @example
  * ```ts twoslash

package/src/wasm/internal/mldsa44.ts

@@ -0,0 +1,34 @@
+import {
+  instantiate,
+  memoize,
+  type Module as WasmModule,
+} from './instantiate.js'
+import { wasmBase64 } from './mldsa44.wasm.js'
+
+export type Exports = {
+  mldsa44_get_public_key(seed: number, publicKey: number): number
+  mldsa44_sign(
+    seed: number,
+    message: number,
+    messageSize: number,
+    context: number,
+    contextSize: number,
+    random: number,
+    signature: number,
+  ): number
+  mldsa44_verify(
+    signature: number,
+    message: number,
+    messageSize: number,
+    context: number,
+    contextSize: number,
+    publicKey: number,
+  ): number
+  zero(pointer: number, length: number): void
+}
+
+/** Instantiated ML-DSA-44 module. */
+export type Module = WasmModule<Exports>
+
+/** Instantiates the ML-DSA-44 module once. */
+export const load = memoize(() => instantiate<Exports>(wasmBase64))