ox 1.0.4 → 1.1.0

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

@@ -0,0 +1,234 @@
+import { fc, test } from '@fast-check/vitest'
+import { describe, expect } from 'vp/test'
+import {
+  bytesToHex,
+  bytesToHexLoop,
+  hexToBytes,
+  hexToBytesLoop,
+} from '../hex.js'
+import { numRuns } from '../../../../../test/fuzz/numRuns.js'
+
+// The implementations as they stood before the tiering change, vendored so the
+// suite has an oracle independent of the code under test. Any disagreement is
+// either a regression or a deliberate behavior change that should be argued for
+// in review -- not something to discover in the wild.
+
+const referenceHexes = Array.from({ length: 256 }, (_v, i) =>
+  i.toString(16).padStart(2, '0'),
+)
+
+function referenceEncode(value: Uint8Array): string {
+  const length = value.length
+  const parts = Array.from<string>({ length })
+  for (let i = 0; i < length; i++) parts[i] = referenceHexes[value[i]!]!
+  return `0x${parts.join('')}`
+}
+
+/**
+ * Whether the previous decoder can be reconstructed here at all. It was built
+ * on `Buffer`, so on a runtime without one there is nothing to compare against
+ * -- and nothing to regress, since such a runtime always used the JS loop.
+ */
+const hasReference = typeof globalThis.Buffer !== 'undefined'
+
+/**
+ * The previous decoder: `Buffer` at every size, with the JS loop reachable only
+ * where `Buffer` was absent. Throws a bare `Error` rather than ox's error
+ * classes, so properties compare *whether* it threw, not what it threw.
+ */
+function referenceDecode(value: string): Uint8Array {
+  if (
+    typeof value !== 'string' ||
+    value.length < 2 ||
+    value.charCodeAt(0) !== 48 ||
+    value.charCodeAt(1) !== 120
+  )
+    throw new Error('invalid')
+  const body = value.length === 2 ? '' : value.slice(2)
+  if ((body.length & 1) !== 0) throw new Error('odd')
+  if (body.length > 0) {
+    const expected = body.length >> 1
+    const buf = Buffer.from(body, 'hex')
+    if (buf.length !== expected) throw new Error('invalid')
+    const out = new Uint8Array(buf.byteLength)
+    out.set(buf)
+    return out
+  }
+  return new Uint8Array(0)
+}
+
+/** Runs `fn`, reporting either its value or the fact that it threw. */
+function outcome<value>(
+  fn: () => value,
+): { ok: true; value: value } | { ok: false } {
+  try {
+    return { ok: true, value: fn() }
+  } catch {
+    return { ok: false }
+  }
+}
+
+// Sizes cluster at the tier boundary (`loopDecodeMaxBytes` is 32 or 64
+// depending on the runtime), where an off-by-one is likeliest to hide.
+const arbitraryBoundaryBytes = fc.oneof(
+  fc.uint8Array({ minLength: 0, maxLength: 4 }),
+  fc.uint8Array({ minLength: 30, maxLength: 34 }),
+  fc.uint8Array({ minLength: 62, maxLength: 66 }),
+  fc.uint8Array({ minLength: 0, maxLength: 300 }),
+)
+
+/**
+ * A single character: the troublemakers test262 enumerates, plus any code point
+ * at all -- including lone surrogates and astral characters, which sit far
+ * above the Latin-1 lookup table the decoder reads through.
+ */
+const arbitraryChar = fc.oneof(
+  fc.constantFrom(
+    '.',
+    '^',
+    ' ',
+    '\t',
+    '\n',
+    '\r',
+    '\u00a0',
+    '\u2009',
+    '\u2028',
+    '\u0000',
+    '\u00ff',
+    '\u0100',
+    '\ud800',
+    '\u{1f600}',
+    'g',
+    'G',
+    'z',
+    'Z',
+    '+',
+    '-',
+    '/',
+  ),
+  fc.integer({ min: 0, max: 0x10ffff }).map((c) => String.fromCodePoint(c)),
+)
+
+/** Valid hex with exactly one character swapped for an arbitrary one. */
+const arbitraryCorruptedHex = fc
+  .tuple(
+    fc.uint8Array({ minLength: 1, maxLength: 80 }),
+    fc.nat(),
+    arbitraryChar,
+  )
+  .map(([bytes, index, char]) => {
+    const body = referenceEncode(bytes).slice(2)
+    const at = index % body.length
+    return `0x${body.slice(0, at)}${char}${body.slice(at + 1)}`
+  })
+
+describe.runIf(hasReference)('encode: new vs previous implementation', () => {
+  test.prop({ bytes: arbitraryBoundaryBytes }, { numRuns })(
+    'bytesToHexLoop agrees with the previous loop',
+    ({ bytes }) => {
+      expect(bytesToHexLoop(bytes)).toBe(referenceEncode(bytes))
+    },
+  )
+
+  test.prop({ bytes: arbitraryBoundaryBytes }, { numRuns })(
+    'the dispatched encoder agrees with the previous loop',
+    ({ bytes }) => {
+      expect(bytesToHex(bytes)).toBe(referenceEncode(bytes))
+    },
+  )
+})
+
+describe.runIf(hasReference)('decode: new vs previous implementation', () => {
+  // The previous decoder had a bug: `Buffer.from(…, 'hex')` masks UTF-16 code
+  // units to 8 bits, so a character above U+00FF could alias a hex digit and
+  // decode instead of being refused. That is now rejected, which is the one
+  // intended difference between the two. For pure-ASCII input -- everything a
+  // caller could legitimately pass -- they must still agree exactly.
+  const isAscii = (value: string) => {
+    for (let i = 0; i < value.length; i++)
+      if (value.charCodeAt(i) > 0x7f) return false
+    return true
+  }
+
+  test.prop({ bytes: arbitraryBoundaryBytes }, { numRuns })(
+    'valid input decodes identically',
+    ({ bytes }) => {
+      const hex = referenceEncode(bytes)
+      expect(hexToBytes(hex)).toEqual(referenceDecode(hex))
+      expect(hexToBytesLoop(hex, bytes.length)).toEqual(referenceDecode(hex))
+    },
+  )
+
+  test.prop({ hex: arbitraryCorruptedHex }, { numRuns })(
+    'pure-ASCII corruption is accepted or rejected identically',
+    ({ hex }) => {
+      fc.pre(isAscii(hex))
+      expect(outcome(() => hexToBytes(hex))).toEqual(
+        outcome(() => referenceDecode(hex)),
+      )
+    },
+  )
+
+  test.prop({ value: fc.string({ unit: 'grapheme' }) }, { numRuns })(
+    'pure-ASCII strings are accepted or rejected identically',
+    ({ value }) => {
+      fc.pre(isAscii(value))
+      const hex = `0x${value}`
+      expect(outcome(() => hexToBytes(hex))).toEqual(
+        outcome(() => referenceDecode(hex)),
+      )
+    },
+  )
+
+  test.prop({ hex: arbitraryCorruptedHex }, { numRuns })(
+    'non-ASCII input is always rejected',
+    ({ hex }) => {
+      fc.pre(!isAscii(hex))
+      expect(() => hexToBytes(hex)).toThrow()
+      const length = (hex.length - 2) >> 1
+      if ((hex.length - 2) % 2 === 0)
+        expect(() => hexToBytesLoop(hex, length)).toThrow()
+    },
+  )
+})
+
+describe('decode: tiers agree with each other', () => {
+  // Prefixing with valid hex pushes the same body across the size threshold and
+  // through a different tier. The prefix cannot change whether the body is
+  // valid, so the two must agree on outcome, and on value up to the prefix.
+  const prefix = 'ab'.repeat(96)
+  const prefixBytes = hexToBytes(`0x${prefix}`)
+
+  test.prop({ hex: arbitraryCorruptedHex }, { numRuns })(
+    'the tier chosen by size does not change the verdict',
+    ({ hex }) => {
+      const body = hex.slice(2)
+      const short = outcome(() => hexToBytes(`0x${body}`))
+      const long = outcome(() => hexToBytes(`0x${prefix}${body}`))
+      expect(long.ok).toBe(short.ok)
+      if (short.ok && long.ok)
+        expect(long.value).toEqual(
+          Uint8Array.from([...prefixBytes, ...short.value]),
+        )
+    },
+  )
+
+  test.prop({ bytes: arbitraryBoundaryBytes }, { numRuns })(
+    'the loop agrees with whichever tier size selects',
+    ({ bytes }) => {
+      const hex = referenceEncode(bytes)
+      expect(hexToBytesLoop(hex, bytes.length)).toEqual(hexToBytes(hex))
+    },
+  )
+})
+
+describe('round-trip', () => {
+  test.prop({ bytes: arbitraryBoundaryBytes }, { numRuns })(
+    'decode(encode(b)) is b, through every tier',
+    ({ bytes }) => {
+      expect(hexToBytes(bytesToHex(bytes))).toEqual(bytes)
+      expect(hexToBytes(bytesToHexLoop(bytes))).toEqual(bytes)
+      expect(hexToBytesLoop(bytesToHexLoop(bytes), bytes.length)).toEqual(bytes)
+    },
+  )
+})

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

@@ -0,0 +1,124 @@
+import { Bytes, Hex } from 'ox'
+import { describe, expect, test } from 'vp/test'
+import {
+  bytesToHex,
+  bytesToHexLoop,
+  hexToBytes,
+  hexToBytesLoop,
+} from '../hex.js'
+
+// The dispatched `bytesToHex` / `hexToBytes` pick a native method or `Buffer`
+// when the runtime offers one, so the JS loops underneath them are unreachable
+// on Node. They back every browser without `Uint8Array.prototype.toHex`, so
+// they are exercised directly here rather than left to whichever tier the test
+// runtime happens to take.
+
+const sizes = [0, 1, 2, 19, 20, 31, 32, 33, 48, 64, 127, 128, 1024]
+
+describe('bytesToHexLoop', () => {
+  test('agrees with the dispatched encoder at every size', () => {
+    for (const size of sizes) {
+      const value = Bytes.random(size)
+      expect(bytesToHexLoop(value)).toBe(bytesToHex(value))
+    }
+  })
+
+  test('behavior: empty input', () => {
+    expect(bytesToHexLoop(new Uint8Array(0))).toMatchInlineSnapshot(`"0x"`)
+  })
+
+  test('behavior: pads each byte to two nibbles', () => {
+    expect(
+      bytesToHexLoop(Uint8Array.of(0, 1, 15, 16, 255)),
+    ).toMatchInlineSnapshot(`"0x00010f10ff"`)
+  })
+
+  test('behavior: reads through a subarray offset', () => {
+    const backing = Uint8Array.of(0xde, 0xad, 0xbe, 0xef)
+    expect(bytesToHexLoop(backing.subarray(1, 3))).toMatchInlineSnapshot(
+      `"0xadbe"`,
+    )
+  })
+})
+
+describe('hexToBytesLoop', () => {
+  test('agrees with the dispatched decoder at every size', () => {
+    for (const size of sizes) {
+      const hex = Hex.fromBytes(Bytes.random(size))
+      expect(hexToBytesLoop(hex, size)).toEqual(hexToBytes(hex))
+    }
+  })
+
+  test('behavior: empty input', () => {
+    expect(hexToBytesLoop('0x', 0)).toMatchInlineSnapshot(`Uint8Array []`)
+  })
+
+  test('behavior: accepts uppercase nibbles', () => {
+    expect(hexToBytesLoop('0xDEADBEEF', 4)).toEqual(hexToBytes('0xdeadbeef'))
+  })
+
+  test('error: invalid character in the high nibble', () => {
+    expect(() => hexToBytesLoop('0xzz', 1)).toThrowErrorMatchingInlineSnapshot(
+      `
+      [Hex.InvalidHexValueError: Value \`0xzz\` is an invalid hex value.
+
+      Hex values must start with \`"0x"\` and contain only hexadecimal characters (0-9, a-f, A-F).]
+    `,
+    )
+  })
+
+  test('error: invalid character in the low nibble', () => {
+    expect(() => hexToBytesLoop('0x0g', 1)).toThrowError(
+      Hex.InvalidHexValueError,
+    )
+  })
+
+  test('error: invalid character in a trailing byte', () => {
+    // The sentinel is accumulated across the loop, so a late bad nibble must
+    // still be caught rather than masked by the valid ones before it.
+    expect(() => hexToBytesLoop('0xdeadbe$f', 4)).toThrowError(
+      Hex.InvalidHexValueError,
+    )
+  })
+
+  test('error: characters beyond Latin-1', () => {
+    // These index past `nibbleTable`, so they read `undefined` rather than the
+    // sentinel; unmapped, they would OR in as zero and decode to `0x00`.
+    for (const value of ['0x€€', '0xĀĀ', '0xǰ0'])
+      expect(() => hexToBytesLoop(value, 1)).toThrowError(
+        Hex.InvalidHexValueError,
+      )
+  })
+})
+
+describe('hexToBytes', () => {
+  // `loopDecodeMaxBytes` is 32; both sides of it must behave identically.
+  test('behavior: matches across the loop/Buffer threshold', () => {
+    for (const size of [31, 32, 33, 34]) {
+      const bytes = Bytes.random(size)
+      expect(hexToBytes(Hex.fromBytes(bytes))).toEqual(bytes)
+    }
+  })
+
+  test('error: invalid character above the threshold', () => {
+    const hex = `0x${'ab'.repeat(40)}zz` as const
+    expect(() => hexToBytes(hex)).toThrowError(Hex.InvalidHexValueError)
+  })
+
+  test('error: odd length', () => {
+    expect(() => hexToBytes('0xabc')).toThrowError(Hex.InvalidLengthError)
+  })
+
+  test('error: characters beyond Latin-1, both sides of the threshold', () => {
+    for (const value of ['0x€€', `0x${'ab'.repeat(40)}€€`])
+      expect(() => hexToBytes(value)).toThrowError(Hex.InvalidHexValueError)
+  })
+
+  test('behavior: result does not alias a pooled buffer', () => {
+    // Above the threshold the decoder goes through `Buffer`, which allocates
+    // from a shared pool; the returned bytes must own their backing store.
+    const bytes = hexToBytes(Hex.fromBytes(Bytes.random(64)))
+    expect(bytes.byteOffset).toBe(0)
+    expect(bytes.buffer.byteLength).toBe(64)
+  })
+})

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

@@ -0,0 +1,222 @@
+/**
+ * Base64 codec tiers, and the tables they share.
+ *
+ * Split out of the public `Base64` module for the same reason the hex codec is:
+ * a runtime selects one tier at import, so the others are unreachable from a
+ * test unless they can be called directly. Keeping them here lets the
+ * conformance suite compare every tier a runtime can execute, without widening
+ * `Base64`'s public surface.
+ *
+ * @internal
+ */
+
+import * as Errors from '../../Errors.js'
+import type * as Bytes from '../../Bytes.js'
+import { decoder } from './utf8.js'
+
+/** @internal */
+export type Options = {
+  /** Whether to pad the encoded string. */
+  pad?: boolean | undefined
+  /** Whether to use the URL-safe alphabet. */
+  url?: boolean | undefined
+}
+
+// Standard Base64 alphabet (RFC 4648 section 4) and URL-safe alphabet (section 5).
+const stdAlphabet =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+
+// Char-code -> 6-bit integer lookup. Sentinel `0xff` = invalid character.
+// Standard alphabet plus URL-safe `-`/`_` (decoders are alphabet-agnostic).
+const characterToInteger = /*#__PURE__*/ (() => {
+  const table = new Uint8Array(256).fill(0xff)
+  for (let i = 0; i < stdAlphabet.length; i++)
+    table[stdAlphabet.charCodeAt(i)] = i
+  // URL-safe alternates: `-` for `+` (62), `_` for `/` (63).
+  table[45 /* '-' */] = 62
+  table[95 /* '_' */] = 63
+  return table
+})()
+
+// Integer -> char-code table for the standard alphabet, indexed by 6-bit value.
+const integerToCharacter = /*#__PURE__*/ (() => {
+  const table = new Uint8Array(64)
+  for (let i = 0; i < stdAlphabet.length; i++)
+    table[i] = stdAlphabet.charCodeAt(i)
+  return table
+})()
+
+// Native fast-path detection. `Uint8Array.prototype.toBase64` ships in
+// Chromium 145, Safari 18.2+, Firefox 133+ and Bun, but not in Node 24.
+//
+// Only encoding delegates to it; see `toBytes` for why decoding cannot.
+const nativeToBase64:
+  | ((
+      this: Uint8Array,
+      options?: { alphabet?: 'base64' | 'base64url'; omitPadding?: boolean },
+    ) => string)
+  | undefined = (
+  Uint8Array.prototype as Uint8Array & {
+    toBase64?: (options?: {
+      alphabet?: 'base64' | 'base64url'
+      omitPadding?: boolean
+    }) => string
+  }
+).toBase64
+
+/**
+ * Encodes via `Uint8Array.prototype.toBase64`, where the runtime has it.
+ * `undefined` otherwise, so the conformance suite can ask whether this tier
+ * exists rather than inferring it from the runtime.
+ *
+ * @internal
+ */
+export const fromBytesNative:
+  | ((value: Bytes.Bytes, options?: Options) => string)
+  | undefined =
+  nativeToBase64 &&
+  ((value, options = {}) => {
+    const { pad = true, url = false } = options
+    // `omitPadding` governs both alphabets, so `base64url` is padded here too
+    // when asked. Appending padding on top of that double-pads it.
+    return nativeToBase64.call(value, {
+      alphabet: url ? 'base64url' : 'base64',
+      omitPadding: !pad,
+    })
+  })
+
+/**
+ * Encodes in plain JavaScript, for runtimes without the native method.
+ *
+ * @internal
+ */
+export function fromBytesLoop(
+  value: Bytes.Bytes,
+  options: Options = {},
+): string {
+  const { pad = true, url = false } = options
+
+  const encoded = new Uint8Array(Math.ceil(value.length / 3) * 4)
+
+  for (let i = 0, j = 0; j < value.length; i += 4, j += 3) {
+    const y = (value[j]! << 16) + (value[j + 1]! << 8) + (value[j + 2]! | 0)
+    encoded[i] = integerToCharacter[y >> 18]!
+    encoded[i + 1] = integerToCharacter[(y >> 12) & 0x3f]!
+    encoded[i + 2] = integerToCharacter[(y >> 6) & 0x3f]!
+    encoded[i + 3] = integerToCharacter[y & 0x3f]!
+  }
+
+  const k = value.length % 3
+  const end = Math.floor(value.length / 3) * 4 + (k && k + 1)
+  let base64 = decoder.decode(new Uint8Array(encoded.buffer, 0, end))
+  if (pad && k === 1) base64 += '=='
+  if (pad && k === 2) base64 += '='
+  if (url) base64 = base64.replaceAll('+', '-').replaceAll('/', '_')
+  return base64
+}
+
+/**
+ * Encodes with whichever tier this runtime provides.
+ *
+ * @internal
+ */
+export function fromBytes(value: Bytes.Bytes, options: Options = {}): string {
+  if (fromBytesNative) return fromBytesNative(value, options)
+  return fromBytesLoop(value, options)
+}
+
+/**
+ * `Uint8Array.fromBase64` is deliberately unused.
+ *
+ * Its `alphabet` option is strict and mutually exclusive -- `base64` refuses
+ * `-`/`_`, `base64url` refuses `+`/`/` -- while ox decodes either alphabet
+ * transparently. There is no single native call with that behavior, so matching
+ * it would mean normalizing the string first or trying both alphabets and
+ * throwing on one. Both cost more than they would save, and neither has been
+ * measured; the loop is the only decode tier until one is.
+ */
+
+/**
+ * Decodes in plain JavaScript, for runtimes without the native method.
+ *
+ * @internal
+ */
+export function toBytesLoop(value: string, bodyEnd: number): Bytes.Bytes {
+  const size = bodyEnd
+
+  // Validate characters: every char must be in the standard or URL-safe
+  // alphabet, and '=' may not appear in the body (only stripped trailing
+  // padding).
+  const decoded = new Uint8Array(
+    (size >> 2) * 3 + (size % 4 ? (size % 4) - 1 : 0),
+  )
+  let acc = 0
+  let bits = 0
+  let n = 0
+  for (let i = 0; i < size; i++) {
+    const code = value.charCodeAt(i)
+    if (code === 61 /* '=' */)
+      throw new InvalidCharacterError({ character: '=' })
+    // `characterToInteger` only spans Latin-1, so a code unit above it reads
+    // `undefined` and has to be mapped to the sentinel. Without that, `undefined`
+    // fails the `=== 0xff` test, then coerces to zero in the shift below, and a
+    // non-ASCII character silently decodes as `A`.
+    const v = characterToInteger[code] ?? 0xff
+    if (v === 0xff) throw new InvalidCharacterError({ character: value[i]! })
+    acc = (acc << 6) | v
+    bits += 6
+    if (bits >= 8) {
+      bits -= 8
+      decoded[n++] = (acc >>> bits) & 0xff
+    }
+  }
+  return decoded
+}
+
+/**
+ * Decodes with whichever tier this runtime provides.
+ *
+ * @internal
+ */
+export function toBytes(value: string): Bytes.Bytes {
+  // Strip trailing '=' padding (only at the very end).
+  let bodyEnd = value.length
+  let pad = 0
+  while (bodyEnd > 0 && value.charCodeAt(bodyEnd - 1) === 61 /* '=' */) {
+    bodyEnd--
+    pad++
+  }
+
+  // Reject impossible lengths and excessive padding.
+  if (bodyEnd % 4 === 1) throw new InvalidLengthError({ length: value.length })
+  if (pad > 2) throw new InvalidPaddingError({ padding: pad })
+
+  return toBytesLoop(value, bodyEnd)
+}
+
+/** Thrown when a Base64 string contains an invalid character. */
+export class InvalidCharacterError extends Errors.BaseError {
+  override readonly name = 'Base64.InvalidCharacterError'
+
+  constructor({ character }: { character: string }) {
+    super(`Invalid Base64 character: "${character}".`)
+  }
+}
+
+/** Thrown when a Base64 string has an impossible length. */
+export class InvalidLengthError extends Errors.BaseError {
+  override readonly name = 'Base64.InvalidLengthError'
+
+  constructor({ length }: { length: number }) {
+    super(`Invalid Base64 input length \`${length}\`.`)
+  }
+}
+
+/** Thrown when a Base64 string contains too many trailing `=` padding characters. */
+export class InvalidPaddingError extends Errors.BaseError {
+  override readonly name = 'Base64.InvalidPaddingError'
+
+  constructor({ padding }: { padding: number }) {
+    super(`Invalid Base64 padding length \`${padding}\` (must be 0, 1, or 2).`)
+  }
+}