ox 1.1.0 → 1.2.0

package/src/node/_test/X25519.test.ts

@@ -0,0 +1,239 @@
+import * as fs from 'node:fs'
+import { x25519 } from '@noble/curves/ed25519.js'
+import { Hex } from 'ox'
+import { describe, expect, test } from 'vp/test'
+import * as X25519 from '../X25519.js'
+
+type LowOrderVector = {
+  name: string
+  publicKey: string
+}
+
+const alicePrivateKey =
+  '77076d0a7318a57d3c16c17251b26645df4c2f87ebc0992ab177fba51db92c2a'
+const bobPrivateKey =
+  '5dab087e624a8a4b79e17f8b83800ee66f3bb1292618b6fd1c2f8b27ff88e0eb'
+
+const lowOrderPublicKeys = JSON.parse(
+  fs.readFileSync(
+    new URL('../../../test/vectors/x25519/low-order.json', import.meta.url),
+    'utf8',
+  ),
+) as readonly LowOrderVector[]
+
+describe('engine', () => {
+  test('behavior: exposes only the supported primitives', async () => {
+    const engine = await X25519.engine()
+
+    expect(Object.keys(engine).sort()).toMatchInlineSnapshot(`
+      [
+        "getPublicKey",
+        "getSharedSecret",
+      ]
+    `)
+  })
+
+  test('behavior: matches RFC 7748 key-agreement vectors', async () => {
+    const engine = await X25519.engine()
+    const alicePublicKey = engine.getPublicKey(fromHex(alicePrivateKey))
+    const bobPublicKey = engine.getPublicKey(fromHex(bobPrivateKey))
+
+    expect({
+      alicePublicKey: Hex.fromBytes(alicePublicKey),
+      bobPublicKey: Hex.fromBytes(bobPublicKey),
+      sharedSecret: Hex.fromBytes(
+        engine.getSharedSecret(fromHex(alicePrivateKey), bobPublicKey),
+      ),
+    }).toMatchInlineSnapshot(`
+      {
+        "alicePublicKey": "0x8520f0098930a754748b7ddcb43ef75a0dbf3a0d26381af4eba4a98eaa9b4e6a",
+        "bobPublicKey": "0xde9edb7d7b7dc1b4d35b61c2ece435373f8343c85b78674dadfc7e146f882b4f",
+        "sharedSecret": "0x4a5d9d5ba4ce2de1728e3bf480350f25e07e21c947d19e3376f09b3c1e161742",
+      }
+    `)
+  })
+
+  test('behavior: matches RFC 7748 arbitrary-point vectors', async () => {
+    const engine = await X25519.engine()
+    const vectors = [
+      {
+        privateKey:
+          'a546e36bf0527c9d3b16154b82465edd62144c0ac1fc5a18506a2244ba449ac4',
+        publicKey:
+          'e6db6867583030db3594c1a424b15f7c726624ec26b3353b10a903a6d0ab1c4c',
+      },
+      {
+        privateKey:
+          '4b66e9d4d1b4673c5ad22691957d6af5c11b6421e0ea01d42ca4169e7918ba0d',
+        publicKey:
+          'e5210f12786811d3f4b7959d0538ae2c31dbe7106fc03c3efc4cd549c715a493',
+      },
+    ] as const
+
+    expect(
+      vectors.map(({ privateKey, publicKey }) =>
+        Hex.fromBytes(
+          engine.getSharedSecret(fromHex(privateKey), fromHex(publicKey)),
+        ),
+      ),
+    ).toMatchInlineSnapshot(`
+      [
+        "0xc3da55379de9c6908e94ea4df28d084f32eccf03491c71f754b4075577a28552",
+        "0x95cbde9476e8907d7aade45cb4b873f88b595a68799fa152e6f8f7647aac7957",
+      ]
+    `)
+  })
+
+  test('behavior: matches the default across private keys', async () => {
+    const engine = await X25519.engine()
+    const privateKeys = [
+      fromHex(alicePrivateKey),
+      fromHex(bobPrivateKey),
+      new Uint8Array(32),
+      new Uint8Array(32).fill(0xff),
+      Uint8Array.from({ length: 32 }, (_, index) => index),
+    ]
+
+    for (const [index, privateKey] of privateKeys.entries()) {
+      const peerPrivateKey = Uint8Array.from(
+        { length: 32 },
+        (_, offset) => (offset * 17 + index + 1) % 251,
+      )
+      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: masks the public u-coordinate high bit', async () => {
+    const engine = await X25519.engine()
+    const privateKey = fromHex(alicePrivateKey)
+    const publicKey = x25519.getPublicKey(fromHex(bobPrivateKey))
+    const highBitPublicKey = publicKey.slice()
+    highBitPublicKey[31]! |= 0x80
+    const expected = x25519.getSharedSecret(privateKey, publicKey)
+
+    expect(x25519.getSharedSecret(privateKey, highBitPublicKey)).toEqual(
+      expected,
+    )
+    expect(engine.getSharedSecret(privateKey, highBitPublicKey)).toEqual(
+      expected,
+    )
+  })
+
+  test('behavior: reduces noncanonical public u-coordinates', async () => {
+    const engine = await X25519.engine()
+    const privateKey = fromHex(alicePrivateKey)
+    // 2^255 - 19 + 9 encodes the base point modulo the field prime.
+    const publicKey = fromHex(`f6${'ff'.repeat(30)}7f`)
+    const expected = x25519.getPublicKey(privateKey)
+
+    expect(x25519.getSharedSecret(privateKey, publicKey)).toEqual(expected)
+    expect(engine.getSharedSecret(privateKey, publicKey)).toEqual(expected)
+  })
+
+  test('behavior: rejects the complete published low-order set', async () => {
+    const engine = await X25519.engine()
+    const privateKey = fromHex(alicePrivateKey)
+
+    expect(lowOrderPublicKeys).toHaveLength(7)
+    for (const vector of lowOrderPublicKeys) {
+      const publicKey = fromHex(vector.publicKey)
+      const highBitPublicKey = publicKey.slice()
+      highBitPublicKey[31]! |= 0x80
+
+      for (const [name, value] of [
+        ['published', publicKey],
+        ['top-bit alias', highBitPublicKey],
+      ] as const) {
+        expect(
+          () => x25519.getSharedSecret(privateKey, value),
+          `${vector.name} (${name})`,
+        ).toThrowError()
+        expect(
+          () => engine.getSharedSecret(privateKey, value),
+          `${vector.name} (${name})`,
+        ).toThrowError()
+      }
+    }
+  })
+
+  test('behavior: respects typed-array offsets without mutating inputs', async () => {
+    const engine = await X25519.engine()
+    const privateKey = offsetView(fromHex(alicePrivateKey))
+    const publicKey = offsetView(x25519.getPublicKey(fromHex(bobPrivateKey)))
+    const privateKeyBefore = privateKey.slice()
+    const publicKeyBefore = publicKey.slice()
+
+    expect(engine.getPublicKey(privateKey)).toEqual(
+      x25519.getPublicKey(privateKey),
+    )
+    expect(engine.getSharedSecret(privateKey, publicKey)).toEqual(
+      x25519.getSharedSecret(privateKey, publicKey),
+    )
+    expect({ privateKey, publicKey }).toEqual({
+      privateKey: privateKeyBefore,
+      publicKey: publicKeyBefore,
+    })
+  })
+
+  test('behavior: rejects malformed key lengths', async () => {
+    const engine = await X25519.engine()
+    const privateKey = fromHex(alicePrivateKey)
+    const publicKey = x25519.getPublicKey(fromHex(bobPrivateKey))
+
+    for (const size of [0, 1, 31, 33, 64]) {
+      expect(() => engine.getPublicKey(new Uint8Array(size))).toThrowError(
+        `X25519 private key must be 32 bytes, got ${size}`,
+      )
+      expect(() =>
+        engine.getSharedSecret(new Uint8Array(size), publicKey),
+      ).toThrowError(`X25519 private key must be 32 bytes, got ${size}`)
+      expect(() =>
+        engine.getSharedSecret(privateKey, new Uint8Array(size)),
+      ).toThrowError(`X25519 public key must be 32 bytes, got ${size}`)
+    }
+  })
+
+  test('behavior: returns owned Uint8Array values', async () => {
+    const engine = await X25519.engine()
+    const privateKey = fromHex(alicePrivateKey)
+    const publicKey = x25519.getPublicKey(fromHex(bobPrivateKey))
+    const outputs = [
+      engine.getPublicKey(privateKey),
+      engine.getSharedSecret(privateKey, publicKey),
+    ]
+
+    expect(outputs.map((output) => output.constructor === Uint8Array))
+      .toMatchInlineSnapshot(`
+      [
+        true,
+        true,
+      ]
+    `)
+    expect(
+      engine.getPublicKey(privateKey) === engine.getPublicKey(privateKey),
+    ).toMatchInlineSnapshot('false')
+  })
+
+  test('behavior: returns a fresh engine', async () => {
+    const first = await X25519.engine()
+    const second = await X25519.engine()
+
+    expect(first === second).toMatchInlineSnapshot('false')
+  })
+})
+
+function fromHex(value: string): Uint8Array {
+  return Hex.toBytes(`0x${value}`)
+}
+
+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/index.ts

@@ -1,7 +1,8 @@
 /** @entrypointCategory Node */
 
 /**
- * Node.js implementations of Ox's hash primitives, backed by `node:crypto`.
+ * Node.js implementations of Ox's supported cryptographic primitives, backed
+ * by `node:crypto`.
  *
  * Import this entrypoint only in Node.js. Its static `node:crypto` dependency
  * is intentionally kept outside Ox's runtime-neutral entrypoint.
@@ -9,10 +10,9 @@
  * @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')
  * ```
@@ -22,15 +22,33 @@
 export * as Engine from './Engine.js'
 
 /**
- * Node.js implementations of Ox's supported hash primitives.
+ * Ox's Ed25519 API and its supported Node.js engine primitives.
  *
  * @example
  * ```ts twoslash
  * // @noErrors
- * import { Engine, Hash } from 'ox'
- * import * as NodeHash from 'ox/node/Hash'
+ * import { Engine } from 'ox'
+ * import { Ed25519 } from 'ox/node'
  *
- * Engine.set(await NodeHash.create())
+ * await Engine.install({ Ed25519: Ed25519.engine() })
+ *
+ * Ed25519.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @category Crypto
+ */
+export * as Ed25519 from './Ed25519.js'
+
+/**
+ * Ox's hash API and its supported Node.js engine primitives.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Hash } from 'ox/node'
+ *
+ * await Engine.install({ Hash: Hash.engine() })
  *
  * Hash.sha256('0xdeadbeef')
  * ```
@@ -38,3 +56,77 @@ export * as Engine from './Engine.js'
  * @category Crypto
  */
 export * as Hash from './Hash.js'
+
+/**
+ * Ox's keystore API and its supported Node.js engine primitives.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { Keystore } from 'ox/node'
+ *
+ * await Engine.install({ Keystore: Keystore.engine() })
+ *
+ * Keystore.pbkdf2({ password: 'testpassword' })
+ * ```
+ *
+ * @category Crypto
+ */
+export * as Keystore from './Keystore.js'
+
+/**
+ * Ox's mnemonic API and its Node.js BIP-39 seed engine primitive.
+ *
+ * @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'
+ * )
+ * ```
+ *
+ * @category Crypto
+ */
+export * as Mnemonic from './Mnemonic.js'
+
+/**
+ * Ox's P256 API and its Node.js public-key derivation engine primitive.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { P256 } from 'ox/node'
+ *
+ * await Engine.install({ P256: P256.engine() })
+ *
+ * P256.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @category Crypto
+ */
+export * as P256 from './P256.js'
+
+/**
+ * Ox's X25519 API and its supported Node.js engine primitives.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Engine } from 'ox'
+ * import { X25519 } from 'ox/node'
+ *
+ * await Engine.install({ X25519: X25519.engine() })
+ *
+ * X25519.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @category Crypto
+ */
+export * as X25519 from './X25519.js'

package/src/trusted-setups/Paths.ts

@@ -1,3 +1,4 @@
 import { path } from './internal/paths.js'
 
+/** File-system path to the Ethereum mainnet trusted setup. */
 export const mainnet = path('mainnet')

package/src/trusted-setups/README.md

@@ -0,0 +1,39 @@
+# Trusted setup maintenance
+
+Ox bundles the finalized Ethereum KZG ceremony output. This setup is not a
+rolling network parameter, so a new `c-kzg-4844` release does not normally
+change its points.
+
+The committed `mainnet.source.json` records the reviewed `c-kzg-4844` release
+tag, source path, source SHA-256, and generated JSON SHA-256.
+
+## Refresh from c-kzg
+
+1. Review the latest official
+   [`c-kzg-4844` release](https://github.com/ethereum/c-kzg-4844/releases/latest)
+   and its `src/trusted_setup.txt` changes. Do not update from a moving branch.
+2. Pass the selected release tag explicitly:
+
+   ```bash
+   pnpm trusted-setups:update v2.1.8
+   ```
+
+   The command downloads that tagged file, requires 4,096 G1 Lagrange points,
+   4,096 G1 monomial points, and 65 G2 monomial points, then regenerates the
+   canonical JSON, source metadata, and packed TypeScript artifact.
+
+3. Inspect the setup and metadata diff. Treat any point change as
+   security-sensitive. An implementation-only `c-kzg-4844` release should
+   change only the recorded tag when the source bytes are identical.
+4. Verify the generated artifacts and KZG conformance:
+
+   ```bash
+   pnpm trusted-setups:check
+   SKIP_GLOBAL_SETUP=1 pnpm test --project core --bail=1 \
+     src/trusted-setups src/wasm/_test/Kzg.test.ts
+   pnpm check:types
+   ```
+
+`mainnet.json` remains available for file-based consumers through
+`Paths.mainnet`. `mainnet.ts` is the independently tree-shakeable packed
+artifact behind `Setups.mainnet`.

package/src/trusted-setups/Setups.ts

@@ -0,0 +1,46 @@
+import * as Base64 from '../core/Base64.js'
+import type * as Bytes from '../core/Bytes.js'
+import {
+  g1Lagrange,
+  g1Monomial,
+  g2Monomial,
+} from './internal/setups/mainnet.js'
+
+/**
+ * Trusted setup points for EIP-4844 and EIP-7594 KZG operations.
+ */
+export type TrustedSetup = {
+  /** G1 points in Lagrange form. */
+  readonly g1_lagrange: Bytes.Bytes
+  /** G1 points in monomial form. */
+  readonly g1_monomial: Bytes.Bytes
+  /** G2 points in monomial form. */
+  readonly g2_monomial: Bytes.Bytes
+}
+
+/**
+ * Ethereum mainnet trusted setup for EIP-4844 and EIP-7594.
+ *
+ * The setup stores packed points and is safe to reuse across `Kzg.create`
+ * calls. `Kzg.create` copies every field before asynchronous initialization.
+ *
+ * Treat the exported byte arrays as read-only.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Setups } from 'ox/trusted-setups'
+ * import { Kzg } from 'ox/wasm'
+ *
+ * const kzg = await Kzg.create({
+ *   trustedSetup: Setups.mainnet
+ * })
+ *
+ * kzg.dispose()
+ * ```
+ */
+export const mainnet: TrustedSetup = /* @__PURE__ */ Object.freeze({
+  g1_lagrange: /* @__PURE__ */ Base64.toBytes(g1Lagrange),
+  g1_monomial: /* @__PURE__ */ Base64.toBytes(g1Monomial),
+  g2_monomial: /* @__PURE__ */ Base64.toBytes(g2Monomial),
+})

package/src/trusted-setups/_test/Paths.test.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from 'node:fs'
 import { expect, test } from 'vp/test'
 import * as Module from '../Paths.js'
 
@@ -8,3 +9,18 @@ test('exports', () => {
     ]
   `)
 })
+
+test('mainnet resolves to the packaged trusted setup', () => {
+  const setup = JSON.parse(readFileSync(Module.mainnet, 'utf8'))
+  expect({
+    g1Lagrange: setup.g1_lagrange.length,
+    g1Monomial: setup.g1_monomial.length,
+    g2Monomial: setup.g2_monomial.length,
+  }).toMatchInlineSnapshot(`
+    {
+      "g1Lagrange": 4096,
+      "g1Monomial": 4096,
+      "g2Monomial": 65,
+    }
+  `)
+})

package/src/trusted-setups/_test/Setups.test-d.ts

@@ -0,0 +1,7 @@
+import { expectTypeOf, test } from 'vp/test'
+import type * as WasmKzg from '../../wasm/Kzg.js'
+import * as Setups from '../Setups.js'
+
+test('mainnet satisfies the WASM KZG trusted setup', () => {
+  expectTypeOf(Setups.mainnet).toMatchTypeOf<WasmKzg.TrustedSetup>()
+})

package/src/trusted-setups/_test/Setups.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from 'vp/test'
+import * as Hex from '../../core/Hex.js'
+import * as Setups from '../Setups.js'
+
+describe('mainnet', () => {
+  test('exports the canonical PeerDAS setup as packed points', () => {
+    expect({
+      g1Lagrange: {
+        bytes: Setups.mainnet.g1_lagrange.length,
+        first: Hex.fromBytes(Setups.mainnet.g1_lagrange.slice(0, 48)),
+        last: Hex.fromBytes(Setups.mainnet.g1_lagrange.slice(-48)),
+      },
+      g1Monomial: {
+        bytes: Setups.mainnet.g1_monomial.length,
+        first: Hex.fromBytes(Setups.mainnet.g1_monomial.slice(0, 48)),
+        last: Hex.fromBytes(Setups.mainnet.g1_monomial.slice(-48)),
+      },
+      g2Monomial: {
+        bytes: Setups.mainnet.g2_monomial.length,
+        first: Hex.fromBytes(Setups.mainnet.g2_monomial.slice(0, 96)),
+        last: Hex.fromBytes(Setups.mainnet.g2_monomial.slice(-96)),
+      },
+    }).toMatchInlineSnapshot(`
+      {
+        "g1Lagrange": {
+          "bytes": 196608,
+          "first": "0xa0413c0dcafec6dbc9f47d66785cf1e8c981044f7d13cfe3e4fcbb71b5408dfde6312493cb3c1d30516cb3ca88c03654",
+          "last": "0x825a6f586726c68d45f00ad0f5a4436523317939a47713f78fd4fe81cd74236fdac1b04ecd97c2d0267d6f4981d7beb1",
+        },
+        "g1Monomial": {
+          "bytes": 196608,
+          "first": "0x97f1d3a73197d7942695638c4fa9ac0fc3688c4f9774b905a14e3a3f171bac586c55e83ff97a1aeffb3af00adb22c6bb",
+          "last": "0xb0bfaf56a5aa59b48960aa7c1617e832e65c823523fb2a5cd44ba606800501cf873e8db1d0dda64065285743dc40786e",
+        },
+        "g2Monomial": {
+          "bytes": 6240,
+          "first": "0x93e02b6052719f607dacd3a088274f65596bd0d09920b61ab5da61bbdc7f5049334cf11213945d57e5ac7d055d042b7e024aa2b2f08f0a91260805272dc51051c6e47ad4fa403b02b4510b647ae3d1770bac0326a805bbefd48056c8c121bdb8",
+          "last": "0x92dcc5a1c8c3e1b28b1524e3dd6dbecd63017c9201da9dbe077f1b82adc08c50169f56fc7b5a3b28ec6b89254de3e2fd12838a761053437883c3e01ba616670cea843754548ef84bcc397de2369adcca2ab54cd73c55dc68d87aec3fc2fe4f10",
+        },
+      }
+    `)
+  })
+})

package/src/trusted-setups/_test/index.test.ts

@@ -5,6 +5,7 @@ test('exports', () => {
   expect(Object.keys(Module)).toMatchInlineSnapshot(`
     [
       "Paths",
+      "Setups",
     ]
   `)
 })

package/src/trusted-setups/index.ts

@@ -1 +1,22 @@
+/**
+ * File-system paths for trusted setup files bundled with Ox.
+ */
 export * as Paths from './Paths.js'
+
+/**
+ * Trusted setup data bundled with Ox.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Setups } from 'ox/trusted-setups'
+ * import { Kzg } from 'ox/wasm'
+ *
+ * const kzg = await Kzg.create({
+ *   trustedSetup: Setups.mainnet
+ * })
+ *
+ * kzg.dispose()
+ * ```
+ */
+export * as Setups from './Setups.js'

package/src/trusted-setups/internal/paths.ts

@@ -10,5 +10,8 @@ export function path(name: string) {
     import.meta.url,
   )
   const __dirname = dirname(__filename)
-  return resolve(__dirname, `./setups/${name}.json`)
+  return resolve(
+    __dirname,
+    `../../../src/trusted-setups/internal/setups/${name}.json`,
+  )
 }

package/src/trusted-setups/internal/setups/mainnet.source.json

@@ -0,0 +1,7 @@
+{
+  "path": "src/trusted_setup.txt",
+  "repository": "https://github.com/ethereum/c-kzg-4844",
+  "setupSha256": "c4732d98dd1452318e1f1943e240fa4c202a8973a44c24e68c937f86b00f9cb2",
+  "sourceSha256": "d39b9f2d047cc9dca2de58f264b6a09448ccd34db967881a6713eacacf0f26b7",
+  "tag": "v2.1.8"
+}