@btoon/js 0.1.1 → 0.1.2

package/dist/esm/web.d.ts

@@ -1,12 +1,19 @@
 import type { CompressionAlgorithm } from './options.js';
 /** The Compression Streams format name for `alg`, if this runtime supports it. */
 export declare function webFormat(alg: CompressionAlgorithm, kind: 'CompressionStream' | 'DecompressionStream'): string | undefined;
+/**
+ * The DecompressionStream format that decodeAsync may use for `alg` when no other
+ * decompressor is available, or undefined: never for zstd, and only once the runtime has
+ * shown that it rejects trailing bytes.
+ */
+export declare function trustedDecompressionFormat(alg: CompressionAlgorithm): Promise<string | undefined>;
+/** Whether decodeAsync might decompress `alg` with a DecompressionStream here (for error messages). */
+export declare function mayDecompressAsync(alg: CompressionAlgorithm): boolean;
 export declare function webCompress(format: string, data: Uint8Array): Promise<Uint8Array>;
 /**
- * Decompresses with a DecompressionStream, stopping as soon as the output exceeds
- * `limit` (the declared size). For zlib it also checks that the payload ends with the
- * Adler-32 of the output: older runtimes silently ignore bytes after the end of the
- * stream, which a strict decoder must reject.
+ * Decompresses with a DecompressionStream, stopping as soon as the output exceeds `limit`
+ * (the declared size). Only for a format that trustedDecompressionFormat() returned, which
+ * rejects bytes after the end of the stream.
  */
 export declare function webDecompress(alg: CompressionAlgorithm, format: string, data: Uint8Array, limit: number): Promise<Uint8Array>;
 type Subtle = {

package/dist/esm/web.js

@@ -1,8 +1,10 @@
 // Asynchronous implementations on top of web platform APIs: Compression Streams and
 // WebCrypto. Used by encodeAsync/decodeAsync wherever the runtime provides them.
 import { BtoonError, fail } from './errors.js';
-import { adler32 } from './inflate.js';
 const FORMATS = { zlib: 'deflate', brotli: 'brotli', zstd: 'zstd' };
+// DecompressionStream has no way to bound a Zstandard window (SPEC §6), so it is never used
+// for zstd.
+const DECOMPRESSION_FORMATS = { zlib: 'deflate', brotli: 'brotli' };
 const CHUNK = 64 * 1024;
 const supported = new Map();
 function streamCtor(kind) {
@@ -40,6 +42,76 @@ function concat(chunks, total) {
     }
     return out;
 }
+function fromHex(h) {
+    const out = new Uint8Array(h.length / 2);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(h.slice(2 * i, 2 * i + 2), 16);
+    return out;
+}
+// Streams of the five bytes "BTOON" (zlib level 9, Brotli quality 11) for the trust probe.
+const PROBE_TEXT = 'BTOON';
+const PROBE_STREAMS = { deflate: '78da730af1f7f7030004780183', brotli: '0b028042544f4f4e03' };
+const trust = new Map();
+/**
+ * Whether this runtime's DecompressionStream can be trusted with `format`: it must decode a
+ * valid stream and reject one followed by a byte (in the same write or in the next), or by a
+ * second stream. Node.js 18 to 23 (some later 22.x releases excepted) ignore bytes after a
+ * zlib stream, and Node.js 22 and 24 after a Brotli stream, while SPEC §6 requires
+ * `invalid_envelope`. Checked once per format.
+ */
+function trusted(format) {
+    let p = trust.get(format);
+    if (p === undefined) {
+        p = probe(format);
+        trust.set(format, p);
+    }
+    return p;
+}
+async function probe(format) {
+    const hex = PROBE_STREAMS[format];
+    if (hex === undefined)
+        return false;
+    const valid = fromHex(hex);
+    const next = (extra) => {
+        const out = new Uint8Array(valid.length + extra.length);
+        out.set(valid);
+        out.set(extra, valid.length);
+        return out;
+    };
+    try {
+        const out = await decompressChunks(format, [valid], 64, format);
+        if (String.fromCharCode(...out) !== PROBE_TEXT)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    for (const chunks of [[next(Uint8Array.of(0))], [valid, Uint8Array.of(0)], [next(valid)]]) {
+        try {
+            await decompressChunks(format, chunks, 64, format);
+            return false; // trailing bytes accepted
+        }
+        catch {
+            // rejected, as it should be
+        }
+    }
+    return true;
+}
+/**
+ * The DecompressionStream format that decodeAsync may use for `alg` when no other
+ * decompressor is available, or undefined: never for zstd, and only once the runtime has
+ * shown that it rejects trailing bytes.
+ */
+export async function trustedDecompressionFormat(alg) {
+    const format = DECOMPRESSION_FORMATS[alg];
+    if (format === undefined || webFormat(alg, 'DecompressionStream') === undefined)
+        return undefined;
+    return (await trusted(format)) ? format : undefined;
+}
+/** Whether decodeAsync might decompress `alg` with a DecompressionStream here (for error messages). */
+export function mayDecompressAsync(alg) {
+    return DECOMPRESSION_FORMATS[alg] !== undefined && webFormat(alg, 'DecompressionStream') !== undefined;
+}
 async function readAll(reader, limit, alg) {
     const chunks = [];
     let total = 0;
@@ -56,11 +128,18 @@ async function readAll(reader, limit, alg) {
     }
     return concat(chunks, total);
 }
-/** Feeds `data` in chunks, honouring backpressure, then closes the writer. */
-async function pump(writer, data) {
-    for (let i = 0; i < data.length; i += CHUNK) {
+/** Splits `data` into the chunks written to a stream. */
+function chunked(data) {
+    const chunks = [];
+    for (let i = 0; i < data.length; i += CHUNK)
+        chunks.push(data.subarray(i, Math.min(i + CHUNK, data.length)));
+    return chunks;
+}
+/** Writes `chunks`, honouring backpressure, then closes the writer. */
+async function pump(writer, chunks) {
+    for (const chunk of chunks) {
         await writer.ready;
-        await writer.write(data.subarray(i, Math.min(i + CHUNK, data.length)));
+        await writer.write(chunk);
     }
     await writer.close();
 }
@@ -70,41 +149,45 @@ function messageOf(e) {
 export async function webCompress(format, data) {
     const stream = new (streamCtor('CompressionStream'))(format);
     const writer = stream.writable.getWriter();
-    const writing = pump(writer, data);
+    const writing = pump(writer, chunked(data));
     writing.catch(() => undefined);
     const out = await readAll(stream.readable.getReader(), Infinity, format);
     await writing;
     return out;
 }
 /**
- * Decompresses with a DecompressionStream, stopping as soon as the output exceeds
- * `limit` (the declared size). For zlib it also checks that the payload ends with the
- * Adler-32 of the output: older runtimes silently ignore bytes after the end of the
- * stream, which a strict decoder must reject.
+ * Runs `chunks` through a DecompressionStream. Output beyond `limit` bytes fails with
+ * `invalid_envelope` ("<label> payload decompresses to more than the declared size").
  */
-export async function webDecompress(alg, format, data, limit) {
+async function decompressChunks(format, chunks, limit, label) {
     const stream = new (streamCtor('DecompressionStream'))(format);
     const writer = stream.writable.getWriter();
-    const writing = pump(writer, data);
+    const writing = pump(writer, chunks);
     writing.catch(() => undefined);
-    let out;
     try {
-        out = await readAll(stream.readable.getReader(), limit, alg);
+        const out = await readAll(stream.readable.getReader(), limit, label);
         await writing;
+        return out;
     }
     catch (e) {
         writer.abort(e).catch(() => undefined);
+        throw e;
+    }
+}
+/**
+ * Decompresses with a DecompressionStream, stopping as soon as the output exceeds `limit`
+ * (the declared size). Only for a format that trustedDecompressionFormat() returned, which
+ * rejects bytes after the end of the stream.
+ */
+export async function webDecompress(alg, format, data, limit) {
+    try {
+        return await decompressChunks(format, chunked(data), limit, alg);
+    }
+    catch (e) {
         if (e instanceof BtoonError)
             throw e;
         throw fail('invalid_envelope', `${alg} payload is corrupt: ${messageOf(e)}`, e);
     }
-    if (alg === 'zlib') {
-        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 out;
 }
 /** WebCrypto's SubtleCrypto, if available (absent in Node 18 and on insecure origins). */
 export function subtle() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btoon/js",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "BTOON (Binary TOON) for JavaScript and TypeScript: canonical, hardened MessagePack with a columnar encoding for tables. Pure TypeScript, zero dependencies; runs in browsers, Node.js, Deno, Bun and edge runtimes.",
   "keywords": [
     "btoon",