ox 1.2.0 → 1.3.0

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')