ox 1.0.4 → 1.1.0

package/src/core/internal/bls.ts

@@ -0,0 +1,121 @@
+import { bls12_381 as bls } from '@noble/curves/bls12-381.js'
+import { type Bls, type Complete, overrides } from './engine.js'
+
+/**
+ * Resolvers for the `Bls` 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.
+ */
+
+// Branching on the group rather than selecting a curve into a variable: the
+// two `Point` types are unrelated, so a union of them has no common `add`.
+const aggregateDefault: Complete<Bls>['aggregate'] = (points, group) => {
+  if (group === 'G1') {
+    let point = bls.G1.Point.ZERO
+    for (const value of points) point = point.add(bls.G1.Point.fromBytes(value))
+    return point.toBytes()
+  }
+  let point = bls.G2.Point.ZERO
+  for (const value of points) point = point.add(bls.G2.Point.fromBytes(value))
+  return point.toBytes()
+}
+
+const getPublicKeyDefault: Complete<Bls>['getPublicKey'] = (
+  privateKey,
+  group,
+) => {
+  const curve = group === 'G1' ? bls.G1 : bls.G2
+  return curve.Point.BASE.multiply(
+    curve.Point.Fn.fromBytes(privateKey),
+  ).toBytes()
+}
+
+const randomSecretKeyDefault: Complete<Bls>['randomSecretKey'] = () =>
+  bls.utils.randomSecretKey()
+
+const signDefault: Complete<Bls>['sign'] = (payload, privateKey, options) => {
+  const { dst, group } = options
+  const signatureCurve = group === 'G1' ? bls.G1 : bls.G2
+  // The scalar comes from the group the public key lives in, which is the one
+  // the signature does not.
+  const privateKeyCurve = group === 'G1' ? bls.G2 : bls.G1
+  const payloadPoint = signatureCurve.hashToCurve(
+    payload,
+    dst ? { DST: dst } : undefined,
+  )
+  return payloadPoint
+    .multiply(privateKeyCurve.Point.Fn.fromBytes(privateKey))
+    .toBytes()
+}
+
+const verifyDefault: Complete<Bls>['verify'] = (
+  signature,
+  payload,
+  publicKey,
+  options,
+) => {
+  const { dst, signatureGroup } = options
+  const shortSignature = signatureGroup === 'G1'
+  const curve = shortSignature ? bls.G1 : bls.G2
+  const payloadPoint = curve.hashToCurve(
+    payload,
+    dst ? { DST: dst } : undefined,
+  )
+  const pairing = shortSignature
+    ? bls.pairingBatch([
+        {
+          g1: payloadPoint as InstanceType<typeof bls.G1.Point>,
+          g2: bls.G2.Point.fromBytes(publicKey),
+        },
+        {
+          g1: bls.G1.Point.fromBytes(signature),
+          g2: bls.G2.Point.BASE.negate(),
+        },
+      ])
+    : bls.pairingBatch([
+        {
+          g1: bls.G1.Point.fromBytes(publicKey).negate(),
+          g2: payloadPoint as InstanceType<typeof bls.G2.Point>,
+        },
+        {
+          g1: bls.G1.Point.BASE,
+          g2: bls.G2.Point.fromBytes(signature),
+        },
+      ])
+  return bls.fields.Fp12.eql(pairing, bls.fields.Fp12.ONE)
+}
+
+/** @internal */
+export const aggregate: Complete<Bls>['aggregate'] = (points, group) =>
+  (overrides.Bls?.aggregate ?? aggregateDefault)(points, group)
+
+/** @internal */
+export const getPublicKey: Complete<Bls>['getPublicKey'] = (
+  privateKey,
+  group,
+) => (overrides.Bls?.getPublicKey ?? getPublicKeyDefault)(privateKey, group)
+
+/** @internal */
+export const randomSecretKey: Complete<Bls>['randomSecretKey'] = () =>
+  (overrides.Bls?.randomSecretKey ?? randomSecretKeyDefault)()
+
+/** @internal */
+export const sign: Complete<Bls>['sign'] = (payload, privateKey, options) =>
+  (overrides.Bls?.sign ?? signDefault)(payload, privateKey, options)
+
+/** @internal */
+export const verify: Complete<Bls>['verify'] = (
+  signature,
+  payload,
+  publicKey,
+  options,
+) =>
+  (overrides.Bls?.verify ?? verifyDefault)(
+    signature,
+    payload,
+    publicKey,
+    options,
+  )

package/src/core/internal/codec/_test/base64.conformance.ts

@@ -0,0 +1,156 @@
+/**
+ * Base64 codec conformance, written once and run by every runtime.
+ *
+ * Declares the tiers this runtime can actually execute, pins them to published
+ * vectors, and compares them against each other. Coverage widens on its own
+ * where more tiers exist -- Node runs the loop, a browser the loop and
+ * its native method -- without this file changing or naming a runtime.
+ *
+ * Collected by both the `core` and `browser` projects, via their
+ * `*.conformance.ts` globs.
+ *
+ * @internal
+ */
+
+import { describe, expect, test } from 'vp/test'
+import {
+  corrupted,
+  expectTiersAgree,
+  expectTiersMatch,
+  expectTiersReject,
+  sampleBytes,
+  type Tier,
+} from '../../../../../test/conformance.js'
+import * as base64 from '../base64.js'
+
+/**
+ * Published vectors, transcribed verbatim rather than regenerated, so a change
+ * to ox cannot quietly move the expected values.
+ *
+ * - RFC 4648 section 10 specifies Base64 and gives the `""` through `"foobar"`
+ *   progression. https://www.rfc-editor.org/rfc/rfc4648#section-10
+ * - test262 pins which characters the native codec must reject.
+ *   https://github.com/tc39/test262/tree/main/test/built-ins/Uint8Array/fromBase64
+ */
+
+/** Bytes and their Base64, from RFC 4648 section 10. */
+const roundTrip = ['', 'f', 'fo', 'foo', 'foob', 'fooba', 'foobar'].map(
+  (value, i) => ({
+    bytes: Uint8Array.from(value, (c) => c.charCodeAt(0)),
+    encoded: ['', 'Zg==', 'Zm8=', 'Zm9v', 'Zm9vYg==', 'Zm9vYmE=', 'Zm9vYmFy'][
+      i
+    ]!,
+  }),
+)
+
+/**
+ * Strings a decoder must reject, from test262
+ * `fromBase64/illegal-characters.js`.
+ *
+ * U+2212 and U+FF0B are the interesting ones: they are homoglyphs for `-` and
+ * `+`, both of which *are* Base64 alphabet characters, and U+FF0B sits above
+ * the Latin-1 table. Before the guard it decoded silently as `A` rather than
+ * being refused.
+ */
+const illegal = [
+  'Zm.9v',
+  'Zm9v^',
+  'Zg==&',
+  'Z\u2212==', // minus sign, homoglyph for '-'
+  'Z\uff0b==', // fullwidth plus sign, homoglyph for '+'
+  'Zg\u00a0==', // no-break space
+  'Zg\u2009==', // thin space
+  'Zg\u2028==', // line separator
+]
+
+describe('base64', () => {
+  const options = [
+    { pad: true, url: false },
+    { pad: false, url: false },
+    { pad: true, url: true },
+    { pad: false, url: true },
+  ] as const
+
+  type EncodeInput = { bytes: Uint8Array; options: base64.Options }
+  const encodeTiers: Tier<EncodeInput, string>[] = [
+    {
+      name: 'loop',
+      run: ({ bytes, options }) => base64.fromBytesLoop(bytes, options),
+    },
+    ...(base64.fromBytesNative
+      ? [
+          {
+            name: 'native',
+            run: ({ bytes, options }: EncodeInput) =>
+              base64.fromBytesNative!(bytes, options),
+          },
+        ]
+      : []),
+  ]
+
+  // `toBytes` strips padding before handing the body to a tier, so the suite
+  // has to do the same to compare them.
+  const bodyEnd = (value: string) => {
+    let end = value.length
+    while (end > 0 && value.charCodeAt(end - 1) === 61) end--
+    return end
+  }
+  // Only one decode tier: `Uint8Array.fromBase64` cannot match ox's
+  // alphabet-agnostic decoding, so the loop is all there is. The suite still
+  // pins it to the published
+  const decodeTiers: Tier<string, Uint8Array>[] = [
+    { name: 'loop', run: (v) => base64.toBytesLoop(v, bodyEnd(v)) },
+  ]
+
+  test(`behavior: exercises ${encodeTiers.length} encode / ${decodeTiers.length} decode tiers`, () => {
+    expect(encodeTiers.length).toBeGreaterThan(0)
+    expect(decodeTiers.length).toBe(1)
+  })
+
+  test('vectors: RFC 4648', () => {
+    expectTiersMatch(
+      encodeTiers,
+      roundTrip.map(({ bytes, encoded }) => ({
+        input: { bytes, options: { pad: true, url: false } },
+        output: encoded,
+      })),
+      { describe: ({ bytes }) => `${bytes.length} bytes` },
+    )
+    expectTiersMatch(
+      decodeTiers,
+      roundTrip.map(({ bytes, encoded }) => ({
+        input: encoded,
+        output: bytes,
+      })),
+    )
+  })
+
+  test('vectors: illegal characters are rejected by every tier', () => {
+    expectTiersReject(decodeTiers, illegal)
+  })
+
+  test('differential: tiers agree on valid input', () => {
+    for (const option of options)
+      expectTiersAgree(
+        encodeTiers,
+        [...sampleBytes(200)].map((bytes) => ({ bytes, options: option })),
+        {
+          describe: ({ bytes }) =>
+            `${bytes.length} bytes, ${JSON.stringify(option)}`,
+        },
+      )
+    expectTiersAgree(
+      decodeTiers,
+      [...sampleBytes(400)].map((b) => base64.fromBytesLoop(b)),
+      { describe: (v) => `${v.slice(0, 20)}… (${v.length})` },
+    )
+  })
+
+  test('differential: tiers agree on corrupted input', () => {
+    expectTiersAgree(
+      decodeTiers,
+      [...corrupted((b) => base64.fromBytesLoop(b), 400)],
+      { describe: (v) => JSON.stringify(v.slice(0, 24)) },
+    )
+  })
+})

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

@@ -0,0 +1,204 @@
+/**
+ * Hex codec conformance, written once and run by every runtime.
+ *
+ * Declares the tiers this runtime can actually execute, pins them to published
+ * vectors, and compares them against each other. Coverage widens on its own
+ * where more tiers exist -- Node runs the loop and `Buffer`, a browser the loop and
+ * its native method -- without this file changing or naming a runtime.
+ *
+ * Collected by both the `core` and `browser` projects, via their
+ * `*.conformance.ts` globs.
+ *
+ * @internal
+ */
+
+import { describe, expect, test } from 'vp/test'
+import {
+  corrupted,
+  expectTiersAgree,
+  expectTiersMatch,
+  expectTiersReject,
+  sampleBytes,
+  type Tier,
+} from '../../../../../test/conformance.js'
+import * as hex from '../hex.js'
+
+/**
+ * Published vectors, transcribed verbatim rather than regenerated, so a change
+ * to ox cannot quietly move the expected values.
+ *
+ * - RFC 4648 section 10 specifies Base16 and gives the `""` through `"foobar"`
+ *   progression. Section 8 defines it as case-insensitive on decode; ox emits
+ *   lowercase. https://www.rfc-editor.org/rfc/rfc4648#section-10
+ * - test262 pins the native codec ox delegates to, including which characters
+ *   it must reject.
+ *   https://github.com/tc39/test262/tree/main/test/built-ins/Uint8Array/fromHex
+ */
+
+/** The RFC 4648 section 10 inputs, as bytes. */
+const foobar = ['', 'f', 'fo', 'foo', 'foob', 'fooba', 'foobar'].map((value) =>
+  Uint8Array.from(value, (c) => c.charCodeAt(0)),
+)
+
+/**
+ * Bytes and their lowercase hex, from RFC 4648 section 10 and test262
+ * `fromHex/results.js` / `toHex/results.js`. The two agree except on case: the
+ * RFC writes uppercase, the ECMAScript methods emit lowercase.
+ */
+const roundTrip = foobar.map((bytes, i) => ({
+  bytes,
+  encoded: [
+    '',
+    '66',
+    '666f',
+    '666f6f',
+    '666f6f62',
+    '666f6f6261',
+    '666f6f626172',
+  ][i]!,
+}))
+
+/**
+ * Uppercase and mixed-case bodies that must decode to the same bytes as their
+ * lowercase form, from test262 `fromHex/results.js` and the uppercase spellings
+ * RFC 4648 section 10 uses.
+ */
+const decodeCaseInsensitive = [
+  { bytes: Uint8Array.of(102, 111), encoded: '666F' },
+  { bytes: Uint8Array.of(102, 111, 111), encoded: '666F6f' },
+  { bytes: foobar[6]!, encoded: '666F6F626172' },
+]
+
+/**
+ * Characters a decoder must reject, from test262
+ * `fromHex/illegal-characters.js`: punctuation, every flavor of ASCII
+ * whitespace, and three non-ASCII spaces.
+ *
+ * The last two sit above the Latin-1 lookup table ox decodes through, so a
+ * table read for them yields `undefined` rather than the invalid sentinel --
+ * the exact shape of the bug this suite exists to catch.
+ */
+const illegalCharacters = [
+  '.',
+  '^',
+  ' ',
+  '\t',
+  '\u000a', // line feed
+  '\u000c', // form feed
+  '\u000d', // carriage return
+  '\u00a0', // no-break space -- inside the Latin-1 table
+  '\u2009', // thin space -- above it
+  '\u2028', // line separator -- above it
+]
+
+/**
+ * Bodies that Node's `Buffer` hex decoder accepted, wrongly, before ox guarded
+ * against it: it 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 the
+ * surrogate pair for U+1D330 masks to `40`.
+ */
+const maskedNonAscii = [
+  { body: '\uc2300', note: 'U+C230 masks to the digit 0' },
+  { body: '\u{1d330}', note: 'surrogate pair masks to 4 and 0' },
+]
+
+describe('hex', () => {
+  const encodeTiers: Tier<Uint8Array, string>[] = [
+    { name: 'loop', run: hex.bytesToHexLoop },
+    ...(hex.bytesToHexNative
+      ? [{ name: 'native', run: hex.bytesToHexNative }]
+      : []),
+    ...(hex.bytesToHexBuffer
+      ? [{ name: 'buffer', run: hex.bytesToHexBuffer }]
+      : []),
+  ]
+
+  const byteLength = (value: string) => (value.length - 2) >> 1
+  // No native decode tier: `Uint8Array.fromHex` cannot be trusted to reject
+  // non-ASCII across the browser versions ox supports.
+  const decodeTiers: Tier<string, Uint8Array>[] = [
+    { name: 'loop', run: (v) => hex.hexToBytesLoop(v, byteLength(v)) },
+    ...(hex.hexToBytesBuffer
+      ? [
+          {
+            name: 'buffer',
+            run: (v: string) => hex.hexToBytesBuffer!(v, byteLength(v)),
+          },
+        ]
+      : []),
+  ]
+
+  test(`behavior: exercises ${encodeTiers.length} encode / ${decodeTiers.length} decode tiers`, () => {
+    // Named so the report says which tiers a runtime actually covered, and so
+    // a tier silently disappearing is visible rather than quietly shrinking
+    // coverage. Encoding has one more tier than decoding: the native method is
+    // trusted to encode but not to validate.
+    expect(encodeTiers.length).toBeGreaterThan(0)
+    expect(decodeTiers.length).toBeGreaterThan(0)
+  })
+
+  test('vectors: RFC 4648 and test262', () => {
+    expectTiersMatch(
+      encodeTiers,
+      roundTrip.map(({ bytes, encoded }) => ({
+        input: bytes,
+        output: `0x${encoded}`,
+      })),
+    )
+    expectTiersMatch(
+      decodeTiers,
+      roundTrip.map(({ bytes, encoded }) => ({
+        input: `0x${encoded}`,
+        output: bytes,
+      })),
+    )
+    expectTiersMatch(
+      decodeTiers,
+      decodeCaseInsensitive.map(({ bytes, encoded }) => ({
+        input: `0x${encoded}`,
+        output: bytes,
+      })),
+    )
+  })
+
+  test('vectors: illegal characters are rejected by every tier', () => {
+    const pad = 'ab'.repeat(96)
+    expectTiersReject(
+      decodeTiers,
+      illegalCharacters.flatMap((char) => [
+        `0xaa${char}a`,
+        `0x${pad}aa${char}a`,
+      ]),
+    )
+  })
+
+  test('vectors: characters Buffer would mask into a digit are rejected', () => {
+    const pad = 'ab'.repeat(96)
+    expectTiersReject(
+      decodeTiers,
+      maskedNonAscii.flatMap(({ body }) => [`0x${body}`, `0x${pad}${body}`]),
+    )
+  })
+
+  test('differential: tiers agree on valid input', () => {
+    expectTiersAgree(encodeTiers, sampleBytes(400), {
+      describe: (b) => `${b.length} bytes`,
+    })
+    expectTiersAgree(
+      decodeTiers,
+      [...sampleBytes(400)].map((b) => hex.bytesToHexLoop(b)),
+      { describe: (v) => `${v.slice(0, 20)}… (${v.length})` },
+    )
+  })
+
+  test('differential: tiers agree on corrupted input', () => {
+    expectTiersAgree(
+      decodeTiers,
+      [...corrupted((b) => hex.bytesToHexLoop(b), 400)].filter(
+        // Odd bodies never reach a tier; the dispatcher rejects them first.
+        (v) => (v.length - 2) % 2 === 0,
+      ),
+      { describe: (v) => JSON.stringify(v.slice(0, 24)) },
+    )
+  })
+})