ox 1.1.2 → 1.3.0

package/src/core/Hash.ts

@@ -1,8 +1,246 @@
 import * as Bytes from './Bytes.js'
-import type * as Errors from './Errors.js'
+import * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
+import type { HashState } from './internal/engine.js'
 import * as engine from './internal/hash.js'
 
+/**
+ * Incremental hash state.
+ *
+ * A hasher accepts any number of chunks. Calling `digest` or `digestInto`
+ * consumes the state. Call `clone` before finalizing to branch from the same
+ * prefix.
+ */
+export type Hasher = {
+  /** Creates an independent copy of the current state. */
+  clone(): Hasher
+  /** Destroys the state. Calling `destroy` more than once has no effect. */
+  destroy(): void
+  /** Finalizes the digest and consumes the state. */
+  digest<as extends 'Hex' | 'Bytes' = 'Hex'>(
+    options?: Hasher.DigestOptions<as>,
+  ): Hasher.DigestReturnType<as>
+  /**
+   * Finalizes into the start of `output` and consumes the state.
+   *
+   * `output` may be larger than the digest. Bytes after the digest are left
+   * unchanged.
+   */
+  digestInto(output: Bytes.Bytes): void
+  /** Absorbs a message chunk. */
+  update(value: Hex.Hex | Bytes.Bytes): Hasher
+}
+
+export declare namespace Hasher {
+  /** Options for `Hasher.digest`. */
+  type DigestOptions<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /** The return type. @default 'Hex' */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  /** Return type for `Hasher.digest`. */
+  type DigestReturnType<as extends 'Hex' | 'Bytes' = 'Hex'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  /** Errors thrown by an incremental hash state. */
+  type ErrorType =
+    | HasherDestroyedError
+    | InvalidDigestSizeError
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Creates an incremental BLAKE3 hasher.
+ *
+ * The installed Engine provider is captured when this function is called.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * const hash = Hash.createBlake3()
+ * hash.update('0xdead')
+ * hash.update('0xbeef')
+ * hash.digest()
+ * // @log: '0x53147f3ce49ed4f60dfa5b9654c36ba6103c11f5737df3dabd4cbd296c4161bd'
+ * ```
+ *
+ * @returns An incremental BLAKE3 hasher.
+ */
+export function createBlake3(): Hasher {
+  return fromState(engine.createBlake3(), 32)
+}
+
+export declare namespace createBlake3 {
+  type ErrorType = Hasher.ErrorType
+}
+
+/**
+ * Creates an incremental HMAC-SHA256 hasher.
+ *
+ * The installed Engine provider is captured when this function is called.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash, Hex } from 'ox'
+ *
+ * const hash = Hash.createHmac256(Hex.fromString('key'))
+ * hash.update('0xdead')
+ * hash.update('0xbeef')
+ * hash.digest()
+ * ```
+ *
+ * @param key - HMAC key.
+ * @returns An incremental HMAC-SHA256 hasher.
+ */
+export function createHmac256(key: Hex.Hex | Bytes.Bytes): Hasher {
+  return fromState(engine.createHmacSha256(Bytes.from(key)), 32)
+}
+
+export declare namespace createHmac256 {
+  type ErrorType = Hasher.ErrorType
+}
+
+/**
+ * Creates an incremental Keccak256 hasher.
+ *
+ * The installed Engine provider is captured when this function is called.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * const hash = Hash.createKeccak256()
+ * hash.update('0xdead')
+ * hash.update('0xbeef')
+ * hash.digest()
+ * // @log: '0xd4fd4e189132273036449fc9e11198c739161b4c0116a9a2dccdfa1c492006f1'
+ * ```
+ *
+ * @returns An incremental Keccak256 hasher.
+ */
+export function createKeccak256(): Hasher {
+  return fromState(engine.createKeccak256(), 32)
+}
+
+export declare namespace createKeccak256 {
+  type ErrorType = Hasher.ErrorType
+}
+
+/**
+ * Creates an incremental RIPEMD-160 hasher.
+ *
+ * The installed Engine provider is captured when this function is called.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * const hash = Hash.createRipemd160()
+ * hash.update('0xdead')
+ * hash.update('0xbeef')
+ * hash.digest()
+ * // @log: '0x226821c2f5423e11fe9af68bd285c249db2e4b5a'
+ * ```
+ *
+ * @returns An incremental RIPEMD-160 hasher.
+ */
+export function createRipemd160(): Hasher {
+  return fromState(engine.createRipemd160(), 20)
+}
+
+export declare namespace createRipemd160 {
+  type ErrorType = Hasher.ErrorType
+}
+
+/**
+ * Creates an incremental SHA-256 hasher.
+ *
+ * The installed Engine provider is captured when this function is called.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * const hash = Hash.createSha256()
+ * hash.update('0xdead')
+ * hash.update('0xbeef')
+ * hash.digest()
+ * // @log: '0x5f78c33274e43fa9de5659265c1d917e25c03722dcb0b8d27db8d5feaa813953'
+ * ```
+ *
+ * @returns An incremental SHA-256 hasher.
+ */
+export function createSha256(): Hasher {
+  return fromState(engine.createSha256(), 32)
+}
+
+export declare namespace createSha256 {
+  type ErrorType = Hasher.ErrorType
+}
+
+/**
+ * Calculates the [BLAKE3](https://github.com/BLAKE3-team/BLAKE3) hash of a {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
+ *
+ * Backed by `blake3` from [`@noble/hashes`](https://github.com/paulmillr/noble-hashes), an audited & minimal JS hashing library, unless another implementation is installed with {@link ox#Engine.set}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * Hash.blake3('0xdeadbeef')
+ * // @log: '0x53147f3ce49ed4f60dfa5b9654c36ba6103c11f5737df3dabd4cbd296c4161bd'
+ * ```
+ *
+ * @example
+ * ### Configure Return Type
+ *
+ * ```ts twoslash
+ * import { Hash } from 'ox'
+ *
+ * Hash.blake3('0xdeadbeef', { as: 'Bytes' })
+ * // @log: Uint8Array [...]
+ * ```
+ *
+ * @param value - {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
+ * @param options - Options.
+ * @returns BLAKE3 hash.
+ */
+export function blake3<
+  value extends Hex.Hex | Bytes.Bytes,
+  as extends 'Hex' | 'Bytes' =
+    | (value extends Hex.Hex ? 'Hex' : never)
+    | (value extends Bytes.Bytes ? 'Bytes' : never),
+>(
+  value: value | Hex.Hex | Bytes.Bytes,
+  options: blake3.Options<as> = {},
+): blake3.ReturnType<as> {
+  const isBytes = value instanceof Uint8Array
+  const { as = isBytes ? 'Bytes' : 'Hex' } = options
+  const bytes = engine.blake3(isBytes ? value : Bytes.from(value))
+  if (as === 'Bytes') return bytes as never
+  return Hex.fromBytes(bytes) as never
+}
+
+export declare namespace blake3 {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> = {
+    /** The return type. Defaults to the input format. */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
 /**
  * Calculates the [Keccak256](https://en.wikipedia.org/wiki/SHA-3) hash of a {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value.
  *
@@ -264,3 +502,85 @@ export declare namespace validate {
     | Hex.size.ErrorType
     | Errors.GlobalErrorType
 }
+
+/** Thrown when an incremental hash state has been consumed or destroyed. */
+export class HasherDestroyedError extends Errors.BaseError {
+  override readonly name = 'Hash.HasherDestroyedError'
+
+  constructor() {
+    super('Hasher has been destroyed.')
+  }
+}
+
+/** Thrown when a digest output buffer is too small. */
+export class InvalidDigestSizeError extends Errors.BaseError {
+  override readonly name = 'Hash.InvalidDigestSizeError'
+
+  constructor(options: InvalidDigestSizeError.Options) {
+    const { minimum, size } = options
+    super(
+      `Digest output is too small. Expected at least ${minimum} bytes. Received ${size} bytes.`,
+    )
+  }
+}
+
+export declare namespace InvalidDigestSizeError {
+  type Options = {
+    /** Minimum output size. */
+    minimum: number
+    /** Received output size. */
+    size: number
+  }
+}
+
+function fromState(state: HashState, digestSize: number): Hasher {
+  let active = true
+
+  const assertActive = () => {
+    if (!active) throw new HasherDestroyedError()
+  }
+
+  const consume = <returnType>(fn: () => returnType): returnType => {
+    assertActive()
+    active = false
+    try {
+      return fn()
+    } finally {
+      state.destroy()
+    }
+  }
+
+  const hasher: Hasher = {
+    clone() {
+      assertActive()
+      return fromState(state.clone(), digestSize)
+    },
+    destroy() {
+      if (!active) return
+      active = false
+      state.destroy()
+    },
+    digest(options = {}) {
+      const value = new Uint8Array(digestSize)
+      consume(() => state.digestInto(value))
+      if (options.as === 'Bytes') return value as never
+      return Hex.fromBytes(value) as never
+    },
+    digestInto(output) {
+      assertActive()
+      if (output.length < digestSize)
+        throw new InvalidDigestSizeError({
+          minimum: digestSize,
+          size: output.length,
+        })
+      consume(() => state.digestInto(output))
+    },
+    update(value) {
+      assertActive()
+      state.update(Bytes.from(value))
+      return hasher
+    },
+  }
+
+  return hasher
+}

package/src/core/Hex.ts

@@ -74,10 +74,7 @@ export function concat(...values: readonly Hex[]): Hex {
   if (values.length === 1) return values[0]!
   if (values.length === 2)
     return `0x${(values[0] as string).slice(2)}${(values[1] as string).slice(2)}` as Hex
-  const parts = Array.from<string>({ length: values.length })
-  for (let i = 0; i < values.length; i++)
-    parts[i] = (values[i] as string).slice(2)
-  return `0x${parts.join('')}` as Hex
+  return `0x${values.reduce((hex, value) => hex + value.replace('0x', ''), '')}`
 }
 
 export declare namespace concat {

package/src/core/Rlp.ts

@@ -192,6 +192,48 @@ export declare namespace readList {
     | Errors.GlobalErrorType
 }
 
+/**
+ * Encodes a value as Recursive-Length Prefix (RLP) and writes the encoded bytes
+ * through a synchronous callback without allocating the complete encoding.
+ *
+ * Ox validates the complete input before the first write. If the callback
+ * throws, the error propagates and earlier callback side effects remain.
+ *
+ * Ox does not mutate a chunk after the callback returns. A chunk may alias a
+ * byte-array leaf from the encoded value. The callback must not mutate the
+ * chunk before `encodeTo` returns.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Bytes, Rlp } from 'ox'
+ *
+ * const chunks: Uint8Array[] = []
+ * Rlp.encodeTo(['0x01', '0x0203'], (chunk) => {
+ *   chunks.push(chunk)
+ * })
+ *
+ * const encoded = Bytes.concat(...chunks)
+ * // @log: Uint8Array([196, 1, 130, 2, 3])
+ * ```
+ *
+ * @param value - The bytes or Hex value, or nested list of values, to encode.
+ * @param write - The synchronous callback for encoded chunks.
+ * @returns Nothing.
+ */
+export function encodeTo(
+  value: RecursiveArray<Bytes.Bytes> | RecursiveArray<Hex.Hex>,
+  write: (chunk: Bytes.Bytes) => undefined,
+): void {
+  const snapshot = snapshotValue(value)
+  const ctx: EncodeCtx = { lengths: [], cursor: 0 }
+  measure(snapshot, ctx)
+  writeEncodedTo(write, snapshot, { lengths: ctx.lengths, cursor: 0 })
+}
+
+export declare namespace encodeTo {
+  type ErrorType = Errors.BaseError | Errors.GlobalErrorType
+}
+
 /**
  * Encodes a {@link ox#Bytes.Bytes} or {@link ox#Hex.Hex} value into a Recursive-Length Prefix (RLP) value.
  *
@@ -368,7 +410,29 @@ function getSizeOfLength(length: number) {
  *
  * @internal
  */
-type EncodeCtx = { lengths: number[]; cursor: number }
+type EncodeCtx = {
+  cursor: number
+  lengths: number[]
+}
+
+type Encodable = RecursiveArray<Bytes.Bytes | Hex.Hex>
+
+/**
+ * Validates Hex leaves and copies list structure before the callback can mutate
+ * the input during encoding. Byte leaves remain zero-copy.
+ *
+ * @internal
+ */
+function snapshotValue(value: Encodable): Encodable {
+  if (Array.isArray(value)) {
+    const snapshot: Encodable[] = []
+    for (let i = 0; i < value.length; i++)
+      snapshot.push(snapshotValue(value[i]!))
+    return snapshot
+  }
+  if (typeof value === 'string') validateHexLeaf(value)
+  return value
+}
 
 /**
  * Walks `value` once, caches each list's `bodyLength` into `ctx.lengths`,
@@ -377,10 +441,7 @@ type EncodeCtx = { lengths: number[]; cursor: number }
  *
  * @internal
  */
-function measure(
-  value: RecursiveArray<Bytes.Bytes> | RecursiveArray<Hex.Hex>,
-  ctx: EncodeCtx,
-): number {
+function measure(value: Encodable, ctx: EncodeCtx): number {
   if (Array.isArray(value)) {
     // Reserve this list's slot before descending so children's slots come
     // after ours; `writeEncoded` walks in the same order and reads slot N
@@ -458,6 +519,112 @@ function writeEncoded(
   return writeBytesLeaf(bytes, offset, value as Bytes.Bytes)
 }
 
+const writeChunkSize = 16_384
+
+type Write = (chunk: Bytes.Bytes) => undefined
+
+/**
+ * Writes an RLP value using list lengths cached by `measure`.
+ *
+ * @internal
+ */
+function writeEncodedTo(write: Write, value: Encodable, ctx: EncodeCtx): void {
+  if (Array.isArray(value)) {
+    write(encodePrefix(ctx.lengths[ctx.cursor++]!, 0xc0))
+    for (let i = 0; i < value.length; i++) writeEncodedTo(write, value[i]!, ctx)
+    return
+  }
+
+  if (typeof value === 'string') {
+    writeHexLeafTo(write, value)
+    return
+  }
+
+  writeBytesLeafTo(write, value as Bytes.Bytes)
+}
+
+/**
+ * Writes a Hex leaf in bounded chunks. `snapshotValue` validated every nibble
+ * before this function can run.
+ *
+ * @internal
+ */
+function writeHexLeafTo(write: Write, hex: Hex.Hex): void {
+  const byteLength = (hex.length - 1) >> 1
+  if (byteLength === 1 && readHexByte(hex, 0) < 0x80) {
+    write(Uint8Array.of(readHexByte(hex, 0)))
+    return
+  }
+
+  write(encodePrefix(byteLength, 0x80))
+  for (let offset = 0; offset < byteLength; offset += writeChunkSize) {
+    const length = Math.min(writeChunkSize, byteLength - offset)
+    const chunk = new Uint8Array(length)
+    for (let i = 0; i < length; i++) chunk[i] = readHexByte(hex, offset + i)
+    write(chunk)
+  }
+}
+
+/**
+ * Writes a byte leaf without copying its body.
+ *
+ * @internal
+ */
+function writeBytesLeafTo(write: Write, leaf: Bytes.Bytes): void {
+  const length = leaf.length
+  if (length === 1 && leaf[0]! < 0x80) {
+    write(leaf)
+    return
+  }
+
+  write(encodePrefix(length, 0x80))
+  if (length > 0) write(leaf)
+}
+
+/**
+ * Encodes a string or list length prefix.
+ *
+ * @internal
+ */
+function encodePrefix(length: number, offset: 0x80 | 0xc0): Uint8Array {
+  if (length <= 55) return Uint8Array.of(offset + length)
+
+  const size = getSizeOfLength(length)
+  const prefix = new Uint8Array(size + 1)
+  prefix[0] = offset + 55 + size
+  writeBigEndian(prefix, 1, length, size)
+  return prefix
+}
+
+/**
+ * Reads one byte from an odd- or even-nibble Hex value.
+ *
+ * @internal
+ */
+function readHexByte(hex: Hex.Hex, index: number): number {
+  const odd = (hex.length & 1) === 1
+  if (odd && index === 0)
+    return internal_bytes.charCodeToBase16(hex.charCodeAt(2))!
+
+  const nibble = odd ? index * 2 - 1 : index * 2
+  const high = internal_bytes.charCodeToBase16(hex.charCodeAt(2 + nibble))!
+  const low = internal_bytes.charCodeToBase16(hex.charCodeAt(3 + nibble))!
+  return (high << 4) | low
+}
+
+/**
+ * Validates a Hex leaf while preserving RLP's odd-nibble left-padding.
+ *
+ * @internal
+ */
+function validateHexLeaf(hex: string): asserts hex is Hex.Hex {
+  if (hex.length < 2 || hex.charCodeAt(0) !== 48 || hex.charCodeAt(1) !== 120)
+    throw invalidNibble(hex as Hex.Hex)
+  for (let i = 2; i < hex.length; i++)
+    if (internal_bytes.charCodeToBase16(hex.charCodeAt(i)) === undefined)
+      throw invalidNibble(hex as Hex.Hex)
+}
+
 /**
  * Hex-leaf fast path: writes the RLP encoding of a hex string directly into
  * `bytes` by nibble-decoding the source hex chars into the destination

package/src/core/Secp256k1.ts

@@ -1,7 +1,8 @@
 import { secp256k1 } from '@noble/curves/secp256k1.js'
 import * as Address from './Address.js'
 import * as Bytes from './Bytes.js'
-import type * as Errors from './Errors.js'
+import * as Errors from './Errors.js'
+import * as Hash from './Hash.js'
 import * as Hex from './Hex.js'
 import {
   formatPublicKey,
@@ -71,6 +72,75 @@ export declare namespace createKeyPair {
     | Errors.GlobalErrorType
 }
 
+/**
+ * Derives a valid secp256k1 private key from a 32-byte WebAuthn PRF output.
+ *
+ * The permanent derivation contract uses the PRF output as the HMAC-SHA256
+ * key. Its message is the UTF-8 bytes of `ox.secp256k1.fromPrf.v1` followed by
+ * a 32-bit big-endian counter starting at zero. Invalid scalars are skipped.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Secp256k1 } from 'ox'
+ *
+ * const privateKey = Secp256k1.fromPrf(
+ *   '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+ * )
+ * ```
+ *
+ * @param value - A 32-byte WebAuthn PRF output.
+ * @param options - Options.
+ * @returns A valid secp256k1 private key.
+ */
+export function fromPrf<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  value: Hex.Hex | Bytes.Bytes,
+  options: fromPrf.Options<as> = {},
+): fromPrf.ReturnType<as> {
+  const { as = 'Hex' } = options
+  const bytes = Bytes.from(value)
+  if (bytes.length !== 32) throw new InvalidPrfSizeError({ size: bytes.length })
+
+  for (let counter = 0; ; counter++) {
+    const candidate = Hash.hmac256(
+      bytes,
+      Bytes.concat(fromPrfLabel, Bytes.fromNumber(counter, { size: 4 })),
+      { as: 'Bytes' },
+    )
+    if (noble.utils.isValidSecretKey(candidate)) {
+      if (as === 'Hex') {
+        const value = Hex.fromBytes(candidate)
+        candidate.fill(0)
+        return value as never
+      }
+      return candidate as never
+    }
+    candidate.fill(0)
+  }
+}
+
+export declare namespace fromPrf {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned private key.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.concat.ErrorType
+    | Bytes.from.ErrorType
+    | Bytes.fromNumber.ErrorType
+    | Hash.hmac256.ErrorType
+    | Hex.fromBytes.ErrorType
+    | InvalidPrfSizeError
+    | Errors.GlobalErrorType
+}
+
 /**
  * Computes the secp256k1 ECDSA public key from a provided private key.
  *
@@ -503,3 +573,24 @@ export declare namespace verify {
 
   type ErrorType = Errors.GlobalErrorType
 }
+
+/** Thrown when a WebAuthn PRF output is not 32 bytes. */
+export class InvalidPrfSizeError extends Errors.BaseError {
+  override readonly name = 'Secp256k1.InvalidPrfSizeError'
+
+  constructor(options: InvalidPrfSizeError.Options) {
+    super(
+      `PRF output must be exactly 32 bytes. Received ${options.size} bytes.`,
+    )
+  }
+}
+
+export declare namespace InvalidPrfSizeError {
+  /** Options for {@link ox#Secp256k1.InvalidPrfSizeError}. */
+  type Options = {
+    /** Received PRF output size. */
+    size: number
+  }
+}
+
+const fromPrfLabel = Bytes.fromString('ox.secp256k1.fromPrf.v1')