@btoon/js 0.0.0-stage → 0.1.0

package/dist/esm/node.js

@@ -0,0 +1,70 @@
+/**
+ * BTOON for JavaScript and TypeScript — Node.js entry point (also used by Bun). Same API
+ * as the portable entry; synchronous compression and signing use `node:zlib` (zlib,
+ * Brotli, and Zstandard where Node.js has it) and `node:crypto`.
+ *
+ * @packageDocumentation
+ */
+import { decodeAsyncWith, decodeWith, encodeAsyncWith, encodeWith } from './core.js';
+import { nodePlatform } from './platform-node.js';
+export { SPEC_VERSION, VERSION } from './constants.js';
+export { BtoonError } from './errors.js';
+export { Ext, Timestamp } from './values.js';
+/**
+ * Encodes a value as canonical BTOON (SPEC §4): identical values produce identical bytes
+ * in every conforming implementation.
+ *
+ * Accepted values: `null`/`undefined` (nil), booleans, numbers (safe integers as integers,
+ * everything else — including `-0`, `NaN` and integral values beyond ±2^53 — as float64),
+ * `bigint`, strings (must not contain lone surrogates), `Uint8Array`/`ArrayBuffer`/other
+ * typed arrays and `DataView` (binary), `Float32Array`/`Float64Array` (float vectors),
+ * arrays, plain objects and `Map`s with string keys (maps, keys sorted by UTF-8 bytes),
+ * `Date` and {@link Timestamp} (timestamps), and {@link Ext}. Any other object is encoded
+ * the way `JSON.stringify` sees it: the result of its `toJSON()` method if it has one
+ * (called once), otherwise a map of its own enumerable string-keyed properties; `Number`,
+ * `String`, `Boolean` and `BigInt` wrapper objects are unwrapped. Functions and symbols are
+ * rejected. Arrays of uniform objects use the tabular encoding when it is smaller.
+ *
+ * With `compress` or `hmacKey`, the document is wrapped in a compression and/or signed
+ * envelope, layered as sign(compress(document)).
+ *
+ * @throws {BtoonError} `invalid_argument` for functions, symbols or invalid options, `max_depth`
+ *   for values nested deeper than `maxDepth` (including cycles), `invalid_utf8` for strings
+ *   with lone surrogates, `unsupported_compression` if the algorithm has no synchronous
+ *   implementation here (see `encodeAsync` and `options.codecs`).
+ */
+export function encode(value, options) {
+    return encodeWith(value, options, nodePlatform);
+}
+/**
+ * Decodes one BTOON document, enforcing SPEC §7: bounds-checked reads, a nesting limit,
+ * no allocation beyond what the input justifies, strict UTF-8, unique map keys and no
+ * trailing bytes. Compression envelopes are decompressed (with the output capped at the
+ * declared size and `maxDecompressedSize`); with `hmacKey` the signature is verified before
+ * anything is parsed.
+ *
+ * Maps decode to plain objects. A `"__proto__"` key becomes an own property (as with
+ * `JSON.parse`); it never changes an object's prototype.
+ *
+ * @throws {BtoonError} with the SPEC §7 error code describing the problem.
+ */
+export function decode(data, options) {
+    return decodeWith(data, options, nodePlatform);
+}
+/**
+ * Like {@link encode}, but compresses with `CompressionStream` (when the runtime supports
+ * the algorithm) and signs with WebCrypto, falling back to the synchronous implementations.
+ * Rejects with a {@link BtoonError}.
+ */
+export function encodeAsync(value, options) {
+    return encodeAsyncWith(value, options, nodePlatform);
+}
+/**
+ * Like {@link decode}, but decompresses with `DecompressionStream` (when the runtime
+ * supports the algorithm) and verifies signatures with `crypto.subtle.verify`, falling back
+ * to the synchronous implementations. The input is copied first, so the caller may reuse
+ * its buffer immediately. Rejects with a {@link BtoonError}.
+ */
+export function decodeAsync(data, options) {
+    return decodeAsyncWith(data, options, nodePlatform);
+}

package/dist/esm/options.d.ts

@@ -0,0 +1,95 @@
+/** Compression algorithms of the envelope (SPEC §6). Only `zlib` is mandatory. */
+export type CompressionAlgorithm = 'zlib' | 'lz4' | 'zstd' | 'brotli' | 'snappy';
+/**
+ * A user-supplied compression codec (see {@link CodecRegistry}). Either function may be
+ * synchronous or return a Promise; synchronous `encode`/`decode` accept only synchronous
+ * results.
+ */
+export interface Codec {
+    /**
+     * Compress a whole document. The output must be the payload format SPEC §6 requires for
+     * the algorithm: an RFC 1950 zlib stream, an LZ4 *block* (no frame), a Zstandard frame,
+     * a Brotli stream, or raw Snappy.
+     */
+    compress?(data: Uint8Array): Uint8Array | Promise<Uint8Array>;
+    /**
+     * Decompress a payload. `uncompressedSize` is the size declared by the envelope, already
+     * checked against `maxDecompressedSize`; implementations must not produce more than that
+     * (LZ4 block decoders need it as the output size). The result must be exactly that long.
+     */
+    decompress?(data: Uint8Array, uncompressedSize: number): Uint8Array | Promise<Uint8Array>;
+}
+/**
+ * Compression codecs supplied by the caller, keyed by algorithm. A codec here takes
+ * precedence over the built-in implementations, so this is how to add LZ4 or Snappy, or
+ * synchronous zlib compression in browsers (for example with `fflate`).
+ */
+export type CodecRegistry = {
+    readonly [A in CompressionAlgorithm]?: Codec;
+};
+/** Options of `encode` / `encodeAsync`. */
+export interface EncodeOptions {
+    /** Wrap the document in a compression envelope (SPEC §6). Default `false`. */
+    compress?: boolean;
+    /** Algorithm used when `compress` is true. Default `'zlib'`. Has no effect unless `compress` is true. */
+    compression?: CompressionAlgorithm;
+    /** Use the tabular (columnar) encoding where SPEC §5.6.2's size rule says so. Default `true`. */
+    autoTabular?: boolean;
+    /** Maximum container nesting; deeper or cyclic values throw `max_depth`. Default `128`. */
+    maxDepth?: number;
+    /** Sign the output with HMAC-SHA256 (SPEC §8). A string is used as its UTF-8 bytes. Must not be empty. */
+    hmacKey?: Uint8Array | string;
+    /** Caller-supplied compression codecs. */
+    codecs?: CodecRegistry;
+}
+/** Options of `decode` / `decodeAsync`. */
+export interface DecodeOptions {
+    /**
+     * SPEC §7 strict mode. Default `true`. Non-strict mode allows trailing bytes and
+     * duplicate keys (last wins) and replaces invalid UTF-8 with U+FFFD; bounds, depth and
+     * allocation checks are never relaxed.
+     */
+    strict?: boolean;
+    /** Maximum container nesting; deeper input throws `max_depth`. Default `128`. */
+    maxDepth?: number;
+    /** Largest accepted `uncompressed_size` of a compression envelope, in bytes. Default 256 MiB. */
+    maxDecompressedSize?: number;
+    /** Accept compression envelopes. Default `true`; when `false` they throw `invalid_envelope`. */
+    autoDecompress?: boolean;
+    /** Require a signed envelope and verify it (SPEC §8) before parsing. Must not be empty. */
+    hmacKey?: Uint8Array | string;
+    /**
+     * How timestamp (-1), date (-2) and datetime (-3) values decode. `'date'` (default):
+     * `Date` (millisecond precision, offset dropped; instants outside the range of `Date`
+     * become `Timestamp`). `'object'`: always {@link Timestamp}, with full precision.
+     */
+    timestamps?: 'date' | 'object';
+    /**
+     * `'auto'` (default): integers decode to `number` when they are safe integers and to
+     * `bigint` otherwise. `'always'`: integers written with a 64-bit marker (uint64/int64)
+     * or as a bigint extension always decode to `bigint`.
+     */
+    bigint?: 'auto' | 'always';
+    /** Caller-supplied compression codecs. */
+    codecs?: CodecRegistry;
+}
+export interface EncodeConfig {
+    compress: boolean;
+    algorithm: CompressionAlgorithm;
+    autoTabular: boolean;
+    maxDepth: number;
+    hmacKey: Uint8Array | undefined;
+    codecs: CodecRegistry | undefined;
+}
+export interface DecodeConfig {
+    strict: boolean;
+    maxDepth: number;
+    maxDecompressedSize: number;
+    autoDecompress: boolean;
+    hmacKey: Uint8Array | undefined;
+    timestampObjects: boolean;
+    bigintAlways: boolean;
+    codecs: CodecRegistry | undefined;
+}
+export declare function encodeConfig(options: EncodeOptions | undefined): EncodeConfig;
+export declare function decodeConfig(options: DecodeOptions | undefined): DecodeConfig;

package/dist/esm/options.js

@@ -0,0 +1,124 @@
+import { ALGORITHM_NAMES, DEFAULT_MAX_DECOMPRESSED_SIZE, DEFAULT_MAX_DEPTH } from './constants.js';
+import { fail } from './errors.js';
+import { isWellFormed } from './utf8.js';
+import { isUint8Array } from './values.js';
+const DEFAULT_ENCODE = Object.freeze({
+    compress: false,
+    algorithm: 'zlib',
+    autoTabular: true,
+    maxDepth: DEFAULT_MAX_DEPTH,
+    hmacKey: undefined,
+    codecs: undefined,
+});
+const DEFAULT_DECODE = Object.freeze({
+    strict: true,
+    maxDepth: DEFAULT_MAX_DEPTH,
+    maxDecompressedSize: DEFAULT_MAX_DECOMPRESSED_SIZE,
+    autoDecompress: true,
+    hmacKey: undefined,
+    timestampObjects: false,
+    bigintAlways: false,
+    codecs: undefined,
+});
+function optionsObject(options, what) {
+    if (options === undefined || options === null)
+        return undefined;
+    if (typeof options !== 'object')
+        throw fail('invalid_argument', `${what} options must be an object`);
+    return options;
+}
+function bool(o, name, dflt) {
+    const v = o[name];
+    if (v === undefined)
+        return dflt;
+    if (typeof v !== 'boolean')
+        throw fail('invalid_argument', `option ${name} must be a boolean`);
+    return v;
+}
+function count(o, name, dflt) {
+    const v = o[name];
+    if (v === undefined)
+        return dflt;
+    if (typeof v !== 'number' || !Number.isSafeInteger(v) || v < 0) {
+        throw fail('invalid_argument', `option ${name} must be a non-negative integer`);
+    }
+    return v;
+}
+function oneOf(o, name, allowed, dflt) {
+    const v = o[name];
+    if (v === undefined)
+        return dflt;
+    if (typeof v !== 'string' || !allowed.includes(v)) {
+        throw fail('invalid_argument', `option ${name} must be one of ${allowed.map((a) => `'${a}'`).join(', ')}`);
+    }
+    return v;
+}
+function hmacKey(o) {
+    const v = o.hmacKey;
+    if (v === undefined)
+        return undefined;
+    let key;
+    if (typeof v === 'string') {
+        if (!isWellFormed(v))
+            throw fail('invalid_argument', 'hmacKey string contains a lone surrogate');
+        key = new TextEncoder().encode(v);
+    }
+    else if (isUint8Array(v)) {
+        key = Uint8Array.prototype.slice.call(v); // private copy: immune to later mutation
+    }
+    else {
+        throw fail('invalid_argument', 'option hmacKey must be a Uint8Array or a string');
+    }
+    if (key.length === 0)
+        throw fail('invalid_argument', 'option hmacKey must not be empty');
+    return key;
+}
+function codecs(o) {
+    const v = o.codecs;
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== 'object' || v === null)
+        throw fail('invalid_argument', 'option codecs must be an object');
+    for (const name of ALGORITHM_NAMES) {
+        const c = v[name];
+        if (c === undefined)
+            continue;
+        if (typeof c !== 'object' || c === null)
+            throw fail('invalid_argument', `codecs.${name} must be an object`);
+        for (const fn of ['compress', 'decompress']) {
+            const f = c[fn];
+            if (f !== undefined && typeof f !== 'function') {
+                throw fail('invalid_argument', `codecs.${name}.${fn} must be a function`);
+            }
+        }
+    }
+    return v;
+}
+export function encodeConfig(options) {
+    const o = optionsObject(options, 'encode');
+    if (o === undefined)
+        return DEFAULT_ENCODE;
+    return {
+        compress: bool(o, 'compress', false),
+        algorithm: oneOf(o, 'compression', ALGORITHM_NAMES, 'zlib'),
+        autoTabular: bool(o, 'autoTabular', true),
+        maxDepth: count(o, 'maxDepth', DEFAULT_MAX_DEPTH),
+        hmacKey: hmacKey(o),
+        codecs: codecs(o),
+    };
+}
+export function decodeConfig(options) {
+    const o = optionsObject(options, 'decode');
+    if (o === undefined)
+        return DEFAULT_DECODE;
+    return {
+        strict: bool(o, 'strict', true),
+        maxDepth: count(o, 'maxDepth', DEFAULT_MAX_DEPTH),
+        maxDecompressedSize: count(o, 'maxDecompressedSize', DEFAULT_MAX_DECOMPRESSED_SIZE),
+        autoDecompress: bool(o, 'autoDecompress', true),
+        hmacKey: hmacKey(o),
+        timestampObjects: oneOf(o, 'timestamps', ['date', 'object'], 'date') === 'object',
+        bigintAlways: oneOf(o, 'bigint', ['auto', 'always'], 'auto') === 'always',
+        codecs: codecs(o),
+    };
+}

package/dist/esm/platform-node.d.ts

@@ -0,0 +1,3 @@
+import type { Platform } from './core.js';
+/** Node.js (and Bun): node:zlib for zlib, Brotli and Zstandard; node:crypto for HMAC. */
+export declare const nodePlatform: Platform;

package/dist/esm/platform-node.js

@@ -0,0 +1,96 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import * as zlib from 'node:zlib';
+import { fail } from './errors.js';
+import { adler32 } from './inflate.js';
+function nodeFn(name) {
+    const f = zlib[name];
+    return typeof f === 'function' ? f : undefined;
+}
+function plain(b) {
+    return new Uint8Array(b.buffer, b.byteOffset, b.byteLength);
+}
+/**
+ * Wraps a node:zlib `*Sync` decompressor: output is capped at the declared size
+ * (`maxOutputLength`), and input left over after the end of the stream is rejected.
+ */
+function decompressor(alg, fn, extra) {
+    if (fn === undefined)
+        return undefined;
+    return (data, size) => {
+        let r;
+        try {
+            r = fn(data, { ...extra?.(size), info: true, maxOutputLength: Math.max(1, size) });
+        }
+        catch (e) {
+            if (e.code === 'ERR_BUFFER_TOO_LARGE') {
+                throw fail('invalid_envelope', `${alg} payload decompresses to more than the declared size`, e);
+            }
+            throw fail('invalid_envelope', `${alg} payload is corrupt: ${e.message}`, e);
+        }
+        let out;
+        let consumed;
+        if (r instanceof Uint8Array) {
+            out = r;
+        }
+        else {
+            const info = r;
+            out = info.buffer;
+            consumed = info.engine?.bytesWritten;
+        }
+        if (typeof consumed === 'number') {
+            if (consumed !== data.length)
+                throw fail('invalid_envelope', `${alg} payload has trailing bytes`);
+        }
+        else if (alg === 'zlib') {
+            // A runtime that doesn't report consumed input: the stream must end in its Adler-32.
+            const n = data.length;
+            const trailer = n >= 4 ? ((data[n - 4] << 24) | (data[n - 3] << 16) | (data[n - 2] << 8) | data[n - 1]) >>> 0 : -1;
+            if (trailer !== adler32(out))
+                throw fail('invalid_envelope', 'zlib payload has trailing bytes');
+        }
+        return plain(out);
+    };
+}
+function compressor(fn, options) {
+    if (fn === undefined)
+        return undefined;
+    return (data) => plain(fn(data, options));
+}
+const decompress = {};
+const compress = {};
+decompress.zlib = decompressor('zlib', nodeFn('inflateSync'));
+compress.zlib = compressor(nodeFn('deflateSync'), { level: 6 });
+const brotliQuality = zlib.constants?.BROTLI_PARAM_QUALITY;
+if (brotliQuality !== undefined) {
+    decompress.brotli = decompressor('brotli', nodeFn('brotliDecompressSync'));
+    compress.brotli = compressor(nodeFn('brotliCompressSync'), { params: { [brotliQuality]: 6 } });
+}
+// node:zlib has Zstandard from Node.js 22.15 / 23.8. SPEC §6: bound the decoder's memory
+// by rejecting frames whose window exceeds max(8 MiB, min(uncompressed_size, 128 MiB)).
+const zstdWindowLogMax = zlib.constants?.ZSTD_d_windowLogMax;
+decompress.zstd = decompressor('zstd', nodeFn('zstdDecompressSync'), (size) => zstdWindowLogMax === undefined
+    ? {}
+    : { params: { [zstdWindowLogMax]: Math.ceil(Math.log2(Math.max(8 << 20, Math.min(size, 128 << 20)))) } });
+compress.zstd = compressor(nodeFn('zstdCompressSync'), {});
+for (const alg of Object.keys(decompress)) {
+    if (decompress[alg] === undefined)
+        delete decompress[alg];
+}
+for (const alg of Object.keys(compress)) {
+    if (compress[alg] === undefined)
+        delete compress[alg];
+}
+/** Node.js (and Bun): node:zlib for zlib, Brotli and Zstandard; node:crypto for HMAC. */
+export const nodePlatform = {
+    decompress,
+    compress,
+    hmac(key, parts) {
+        const h = createHmac('sha256', key);
+        for (const p of parts)
+            h.update(p);
+        return plain(h.digest());
+    },
+    equal(a, b) {
+        return a.length === b.length && timingSafeEqual(a, b);
+    },
+};

package/dist/esm/platform-portable.d.ts

@@ -0,0 +1,7 @@
+import type { Platform } from './core.js';
+/**
+ * Environments without Node.js built-ins (browsers, Deno, workers): synchronous zlib
+ * decompression and HMAC-SHA256 in pure JavaScript. Synchronous compression needs a
+ * caller-supplied codec; encodeAsync uses CompressionStream instead.
+ */
+export declare const portablePlatform: Platform;

package/dist/esm/platform-portable.js

@@ -0,0 +1,13 @@
+import { inflateZlib } from './inflate.js';
+import { hmacSha256, timingSafeEqual } from './sha256.js';
+/**
+ * Environments without Node.js built-ins (browsers, Deno, workers): synchronous zlib
+ * decompression and HMAC-SHA256 in pure JavaScript. Synchronous compression needs a
+ * caller-supplied codec; encodeAsync uses CompressionStream instead.
+ */
+export const portablePlatform = {
+    decompress: { zlib: inflateZlib },
+    compress: {},
+    hmac: hmacSha256,
+    equal: timingSafeEqual,
+};

package/dist/esm/sha256.d.ts

@@ -0,0 +1,5 @@
+export declare function sha256(data: Uint8Array): Uint8Array;
+/** HMAC-SHA256 over the concatenation of `parts` (no copy of the parts is made). */
+export declare function hmacSha256(key: Uint8Array, parts: readonly Uint8Array[]): Uint8Array;
+/** Compares two byte strings in time that depends only on their length. */
+export declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;

package/dist/esm/sha256.js

@@ -0,0 +1,136 @@
+// SHA-256 (FIPS 180-4) and HMAC-SHA256 (RFC 2104) for runtimes without a synchronous
+// native implementation. Used only for the signed envelope (SPEC §8).
+const K = new Int32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98,
+    0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+    0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8,
+    0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819,
+    0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+    0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
+    0xc67178f2,
+]);
+const IV = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
+class Sha256 {
+    constructor() {
+        this.h = new Int32Array(IV);
+        this.w = new Int32Array(64);
+        this.block = new Uint8Array(64);
+        this.blockLen = 0;
+        this.total = 0;
+    }
+    update(data) {
+        let i = 0;
+        const n = data.length;
+        this.total += n;
+        if (this.blockLen > 0) {
+            const take = Math.min(64 - this.blockLen, n);
+            this.block.set(data.subarray(0, take), this.blockLen);
+            this.blockLen += take;
+            i = take;
+            if (this.blockLen < 64)
+                return this;
+            this.compress(this.block, 0);
+            this.blockLen = 0;
+        }
+        for (; i + 64 <= n; i += 64)
+            this.compress(data, i);
+        if (i < n) {
+            this.block.set(data.subarray(i), 0);
+            this.blockLen = n - i;
+        }
+        return this;
+    }
+    digest() {
+        const bits = this.total * 8;
+        const block = this.block;
+        block[this.blockLen++] = 0x80;
+        if (this.blockLen > 56) {
+            block.fill(0, this.blockLen);
+            this.compress(block, 0);
+            this.blockLen = 0;
+        }
+        block.fill(0, this.blockLen, 56);
+        const view = new DataView(block.buffer);
+        view.setUint32(56, Math.floor(bits / 4294967296));
+        view.setUint32(60, bits >>> 0);
+        this.compress(block, 0);
+        const out = new Uint8Array(32);
+        const ov = new DataView(out.buffer);
+        for (let j = 0; j < 8; j++)
+            ov.setInt32(j * 4, this.h[j]);
+        return out;
+    }
+    compress(d, p) {
+        const w = this.w;
+        for (let j = 0; j < 16; j++, p += 4)
+            w[j] = (d[p] << 24) | (d[p + 1] << 16) | (d[p + 2] << 8) | d[p + 3];
+        for (let j = 16; j < 64; j++) {
+            const a = w[j - 15];
+            const b = w[j - 2];
+            const s0 = ((a >>> 7) | (a << 25)) ^ ((a >>> 18) | (a << 14)) ^ (a >>> 3);
+            const s1 = ((b >>> 17) | (b << 15)) ^ ((b >>> 19) | (b << 13)) ^ (b >>> 10);
+            w[j] = (w[j - 16] + s0 + w[j - 7] + s1) | 0;
+        }
+        const h = this.h;
+        let a = h[0];
+        let b = h[1];
+        let c = h[2];
+        let e = h[4];
+        let f = h[5];
+        let g = h[6];
+        let d0 = h[3];
+        let hh = h[7];
+        for (let j = 0; j < 64; j++) {
+            const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (hh + S1 + ch + K[j] + w[j]) | 0;
+            const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (S0 + maj) | 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d0 + t1) | 0;
+            d0 = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+        h[0] = (h[0] + a) | 0;
+        h[1] = (h[1] + b) | 0;
+        h[2] = (h[2] + c) | 0;
+        h[3] = (h[3] + d0) | 0;
+        h[4] = (h[4] + e) | 0;
+        h[5] = (h[5] + f) | 0;
+        h[6] = (h[6] + g) | 0;
+        h[7] = (h[7] + hh) | 0;
+    }
+}
+export function sha256(data) {
+    return new Sha256().update(data).digest();
+}
+/** HMAC-SHA256 over the concatenation of `parts` (no copy of the parts is made). */
+export function hmacSha256(key, parts) {
+    const k = key.length > 64 ? sha256(key) : key;
+    const ipad = new Uint8Array(64);
+    const opad = new Uint8Array(64);
+    for (let i = 0; i < 64; i++) {
+        const b = i < k.length ? k[i] : 0;
+        ipad[i] = b ^ 0x36;
+        opad[i] = b ^ 0x5c;
+    }
+    const inner = new Sha256().update(ipad);
+    for (const p of parts)
+        inner.update(p);
+    return new Sha256().update(opad).update(inner.digest()).digest();
+}
+/** Compares two byte strings in time that depends only on their length. */
+export function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}

package/dist/esm/utf8.d.ts

@@ -0,0 +1,19 @@
+export declare const textEncoder: TextEncoder;
+/** True if `s` has no lone surrogates, i.e. it can be encoded as UTF-8 losslessly. */
+export declare function isWellFormed(s: string): boolean;
+export declare function loneSurrogateError(): Error;
+/** Exact UTF-8 byte length of `s`; throws `invalid_utf8` for a lone surrogate. */
+export declare function utf8Length(s: string): number;
+/**
+ * Orders strings by their UTF-8 bytes (SPEC §4.4), which equals code point order. Plain
+ * `<` compares UTF-16 code units, which puts astral characters (surrogate pairs,
+ * U+D800–U+DFFF) before U+E000–U+FFFF; this corrects exactly that case.
+ */
+export declare function compareUtf8(a: string, b: string): number;
+/**
+ * Decodes `length` bytes at `start`. Strict mode rejects ill-formed UTF-8 (RFC 3629:
+ * overlongs, surrogates, > U+10FFFF, truncated sequences) via TextDecoder's fatal mode;
+ * non-strict mode substitutes U+FFFD. Returns `undefined` for invalid input so the caller
+ * can report the position.
+ */
+export declare function decodeUtf8(bytes: Uint8Array, start: number, length: number, strict: boolean): string | undefined;

package/dist/esm/utf8.js

@@ -0,0 +1,99 @@
+import { fail } from './errors.js';
+export const textEncoder = new TextEncoder();
+// ignoreBOM: true keeps a leading U+FEFF instead of silently stripping it.
+const fatalDecoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+const lenientDecoder = new TextDecoder('utf-8', { ignoreBOM: true });
+const LONE_SURROGATE = /(?:^|[^\uD800-\uDBFF])[\uDC00-\uDFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])/;
+const HAS_SURROGATE = /[\uD800-\uDFFF]/;
+const nativeIsWellFormed = typeof String.prototype.isWellFormed === 'function';
+/** True if `s` has no lone surrogates, i.e. it can be encoded as UTF-8 losslessly. */
+export function isWellFormed(s) {
+    if (nativeIsWellFormed)
+        return s.isWellFormed();
+    return !HAS_SURROGATE.test(s) || !LONE_SURROGATE.test(s);
+}
+export function loneSurrogateError() {
+    return fail('invalid_utf8', 'string contains a lone surrogate and cannot be encoded as UTF-8');
+}
+/** Exact UTF-8 byte length of `s`; throws `invalid_utf8` for a lone surrogate. */
+export function utf8Length(s) {
+    const n = s.length;
+    let bytes = n;
+    for (let i = 0; i < n; i++) {
+        const c = s.charCodeAt(i);
+        if (c < 0x80)
+            continue;
+        if (c < 0x800) {
+            bytes += 1;
+        }
+        else if (c < 0xd800 || c > 0xdfff) {
+            bytes += 2;
+        }
+        else {
+            const d = c <= 0xdbff && i + 1 < n ? s.charCodeAt(i + 1) : 0;
+            if (d < 0xdc00 || d > 0xdfff)
+                throw loneSurrogateError();
+            i++;
+            bytes += 2; // 4 bytes for 2 code units
+        }
+    }
+    return bytes;
+}
+/**
+ * Orders strings by their UTF-8 bytes (SPEC §4.4), which equals code point order. Plain
+ * `<` compares UTF-16 code units, which puts astral characters (surrogate pairs,
+ * U+D800–U+DFFF) before U+E000–U+FFFF; this corrects exactly that case.
+ */
+export function compareUtf8(a, b) {
+    if (a === b)
+        return 0;
+    const n = a.length < b.length ? a.length : b.length;
+    for (let i = 0; i < n; i++) {
+        const x = a.charCodeAt(i);
+        const y = b.charCodeAt(i);
+        if (x !== y) {
+            if (x >= 0xd800 && y >= 0xd800) {
+                const xs = x <= 0xdfff;
+                const ys = y <= 0xdfff;
+                if (xs !== ys)
+                    return xs ? 1 : -1;
+            }
+            return x - y;
+        }
+    }
+    return a.length - b.length;
+}
+const fromCharCode = String.fromCharCode;
+/**
+ * Decodes `length` bytes at `start`. Strict mode rejects ill-formed UTF-8 (RFC 3629:
+ * overlongs, surrogates, > U+10FFFF, truncated sequences) via TextDecoder's fatal mode;
+ * non-strict mode substitutes U+FFFD. Returns `undefined` for invalid input so the caller
+ * can report the position.
+ */
+export function decodeUtf8(bytes, start, length, strict) {
+    if (length <= 32) {
+        // Short ASCII: one pass, no TextDecoder call.
+        let s = '';
+        let i = start;
+        const end = start + length;
+        for (; i < end; i++) {
+            const b = bytes[i];
+            if (b >= 0x80)
+                break;
+            s += fromCharCode(b);
+        }
+        if (i === end)
+            return s;
+    }
+    const view = bytes.subarray(start, start + length);
+    try {
+        return (strict ? fatalDecoder : lenientDecoder).decode(view);
+    }
+    catch (e) {
+        // The fatal decoder reports ill-formed input as a TypeError; anything else is the
+        // engine refusing to build a string that large.
+        if (strict && e instanceof TypeError)
+            return undefined;
+        throw fail('size_limit', 'string is too long for this JavaScript engine', e);
+    }
+}