@btoon/js 0.0.0-stage → 0.1.1

package/dist/cjs/core.js

@@ -0,0 +1,275 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeWith = encodeWith;
+exports.decodeWith = decodeWith;
+exports.encodeAsyncWith = encodeAsyncWith;
+exports.decodeAsyncWith = decodeAsyncWith;
+// encode/decode with the compression (SPEC §6) and signed (SPEC §8) envelopes, layered as
+// sign(compress(encode(value))). The entry points bind these to a Platform: the set of
+// synchronous codecs available in that environment.
+const constants_js_1 = require("./constants.js");
+const decode_js_1 = require("./decode.js");
+const encode_js_1 = require("./encode.js");
+const errors_js_1 = require("./errors.js");
+const options_js_1 = require("./options.js");
+const values_js_1 = require("./values.js");
+const web_js_1 = require("./web.js");
+const COMPRESSED_MAGIC = [0x42, 0x54, 0x4f, 0x4e]; // "BTON"
+const SIGNED_MAGIC = [0x42, 0x54, 0x53, 0x47]; // "BTSG"
+const SIGNED_HEADER = new Uint8Array([0x42, 0x54, 0x53, 0x47, 1, 1, 0, 0]);
+const objectToString = Object.prototype.toString;
+function hasMagic(b, magic) {
+    return b.length >= 4 && b[0] === magic[0] && b[1] === magic[1] && b[2] === magic[2] && b[3] === magic[3];
+}
+function inputBytes(data) {
+    if (ArrayBuffer.isView(data))
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    const tag = objectToString.call(data);
+    if (tag === '[object ArrayBuffer]' || tag === '[object SharedArrayBuffer]')
+        return new Uint8Array(data);
+    throw (0, errors_js_1.fail)('invalid_argument', 'decode() expects a Uint8Array, ArrayBuffer or other ArrayBufferView');
+}
+function isShared(b) {
+    return typeof SharedArrayBuffer !== 'undefined' && b.buffer instanceof SharedArrayBuffer;
+}
+function isThenable(v) {
+    return (typeof v === 'object' || typeof v === 'function') && v !== null && typeof v.then === 'function';
+}
+function messageOf(e) {
+    return e instanceof Error ? e.message || e.name : String(e);
+}
+// --- compression envelope -----------------------------------------------------------------
+function envelopeIfSmaller(raw, payload, alg) {
+    // SPEC §6: only when it saves at least 5%, i.e. 20 × envelope_size ≤ 19 × input_size.
+    if (20 * (constants_js_1.COMPRESSION_HEADER_SIZE + payload.length) > 19 * raw.length)
+        return raw;
+    const out = new Uint8Array(constants_js_1.COMPRESSION_HEADER_SIZE + payload.length);
+    out.set(COMPRESSED_MAGIC, 0);
+    out[4] = 1;
+    out[5] = constants_js_1.ALGORITHM_IDS[alg];
+    const view = new DataView(out.buffer);
+    view.setUint32(8, payload.length);
+    view.setUint32(12, raw.length);
+    out.set(payload, constants_js_1.COMPRESSION_HEADER_SIZE);
+    return out;
+}
+/** Checks the header of a compression envelope (before any decompression), or returns null. */
+function compressionEnvelope(b, cfg) {
+    if (b.length < constants_js_1.COMPRESSION_HEADER_SIZE || !hasMagic(b, COMPRESSED_MAGIC))
+        return null;
+    if (!cfg.autoDecompress)
+        throw (0, errors_js_1.fail)('invalid_envelope', 'input is compressed but autoDecompress is disabled');
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    if (b[4] !== 1)
+        throw (0, errors_js_1.fail)('invalid_envelope', `unsupported compression envelope version ${b[4]}`);
+    if (view.getUint16(6) !== 0)
+        throw (0, errors_js_1.fail)('invalid_envelope', 'compression envelope reserved bytes must be zero');
+    if (view.getUint32(8) !== b.length - constants_js_1.COMPRESSION_HEADER_SIZE) {
+        throw (0, errors_js_1.fail)('invalid_envelope', 'compressed size does not match the envelope length');
+    }
+    const size = view.getUint32(12);
+    if (size > cfg.maxDecompressedSize) {
+        throw (0, errors_js_1.fail)('size_limit', `declared uncompressed size ${size} exceeds maxDecompressedSize (${cfg.maxDecompressedSize})`);
+    }
+    const alg = constants_js_1.ALGORITHM_NAMES[b[5]];
+    if (alg === undefined)
+        throw (0, errors_js_1.fail)('unsupported_compression', `unknown compression algorithm id ${b[5]}`);
+    return { alg, payload: b.subarray(constants_js_1.COMPRESSION_HEADER_SIZE), size };
+}
+function checkSize(out, size, alg) {
+    if (out.length !== size)
+        throw (0, errors_js_1.fail)('invalid_envelope', `${alg} payload decompressed size does not match the header`);
+    return out;
+}
+function unavailable(alg, op, asyncWorks) {
+    const fn = op === 'compression' ? 'encodeAsync()' : 'decodeAsync()';
+    return (0, errors_js_1.fail)('unsupported_compression', asyncWorks
+        ? `${alg} ${op} is not available synchronously in this environment; use ${fn} or pass options.codecs.${alg}`
+        : `${alg} ${op} is not available in this environment; pass options.codecs.${alg}`);
+}
+function codecResult(r, alg, fn) {
+    if (!(0, values_js_1.isUint8Array)(r))
+        throw (0, errors_js_1.fail)('invalid_argument', `codecs.${alg}.${fn} must return a Uint8Array`);
+    return (0, decode_js_1.plainBytes)(r);
+}
+function codecError(e, alg, fn) {
+    if (e instanceof errors_js_1.BtoonError)
+        return e;
+    return (0, errors_js_1.fail)(fn === 'decompress' ? 'invalid_envelope' : 'invalid_argument', `codecs.${alg}.${fn} failed: ${messageOf(e)}`, e);
+}
+function callCodecSync(codecs, alg, fn, args) {
+    const codec = codecs?.[alg];
+    const f = codec?.[fn];
+    if (f === undefined)
+        return undefined;
+    let r;
+    try {
+        r = f.apply(codec, args);
+    }
+    catch (e) {
+        throw codecError(e, alg, fn);
+    }
+    if (isThenable(r)) {
+        Promise.resolve(r).catch(() => undefined);
+        throw (0, errors_js_1.fail)('invalid_argument', `codecs.${alg}.${fn} returned a Promise; use the async API (encodeAsync/decodeAsync)`);
+    }
+    return codecResult(r, alg, fn);
+}
+async function callCodecAsync(codecs, alg, fn, args) {
+    const codec = codecs?.[alg];
+    const f = codec?.[fn];
+    if (f === undefined)
+        return undefined;
+    let r;
+    try {
+        r = await f.apply(codec, args);
+    }
+    catch (e) {
+        throw codecError(e, alg, fn);
+    }
+    return codecResult(r, alg, fn);
+}
+function hasCodec(codecs, alg, fn) {
+    return typeof codecs?.[alg]?.[fn] === 'function';
+}
+function signedEnvelope(b) {
+    if (!hasMagic(b, SIGNED_MAGIC))
+        throw (0, errors_js_1.fail)('authentication_failed', 'input is not a signed envelope');
+    if (b.length < constants_js_1.SIGNED_HEADER_SIZE)
+        throw (0, errors_js_1.fail)('invalid_envelope', 'signed envelope is truncated');
+    if (b[4] !== 1 || b[5] !== 1 || b[6] !== 0 || b[7] !== 0) {
+        throw (0, errors_js_1.fail)('invalid_envelope', 'unsupported signed envelope version or algorithm');
+    }
+    return { header: b.subarray(0, 8), mac: b.subarray(8, constants_js_1.SIGNED_HEADER_SIZE), payload: b.subarray(constants_js_1.SIGNED_HEADER_SIZE) };
+}
+function rejectUnexpectedSignature(b) {
+    if (b.length >= constants_js_1.SIGNED_HEADER_SIZE && hasMagic(b, SIGNED_MAGIC)) {
+        throw (0, errors_js_1.fail)('authentication_failed', 'input is signed but no hmacKey was provided');
+    }
+}
+function assembleSigned(mac, payload) {
+    const out = new Uint8Array(constants_js_1.SIGNED_HEADER_SIZE + payload.length);
+    out.set(SIGNED_HEADER, 0);
+    out.set(mac, 8);
+    out.set(payload, constants_js_1.SIGNED_HEADER_SIZE);
+    return out;
+}
+function concat2(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+// --- synchronous API ------------------------------------------------------------------------
+function encodeWith(value, options, platform) {
+    const cfg = (0, options_js_1.encodeConfig)(options);
+    let out = (0, encode_js_1.encodeDocument)(value, cfg.maxDepth, cfg.autoTabular);
+    if (cfg.compress) {
+        const alg = cfg.algorithm;
+        const builtin = platform.compress[alg];
+        // Fail fast, even for documents too small to compress, so a missing codec shows up in testing.
+        if (!hasCodec(cfg.codecs, alg, 'compress') && builtin === undefined) {
+            throw unavailable(alg, 'compression', (0, web_js_1.webFormat)(alg, 'CompressionStream') !== undefined);
+        }
+        if (out.length >= constants_js_1.MIN_COMPRESSION_SIZE) {
+            if (out.length > 0xffffffff)
+                throw (0, errors_js_1.fail)('size_limit', 'document too large to compress');
+            const payload = callCodecSync(cfg.codecs, alg, 'compress', [out]) ?? builtin(out);
+            out = envelopeIfSmaller(out, payload, alg);
+        }
+    }
+    if (cfg.hmacKey !== undefined)
+        out = assembleSigned(platform.hmac(cfg.hmacKey, [SIGNED_HEADER, out]), out);
+    return out;
+}
+function decodeWith(data, options, platform) {
+    const cfg = (0, options_js_1.decodeConfig)(options);
+    let bytes = inputBytes(data);
+    if (cfg.hmacKey !== undefined) {
+        if (isShared(bytes))
+            bytes = bytes.slice(); // verify and parse the same bytes
+        const env = signedEnvelope(bytes);
+        const expected = platform.hmac(cfg.hmacKey, [env.header, env.payload]);
+        if (!platform.equal(expected, env.mac))
+            throw (0, errors_js_1.fail)('authentication_failed', 'HMAC verification failed');
+        bytes = env.payload;
+    }
+    else {
+        rejectUnexpectedSignature(bytes);
+    }
+    const env = compressionEnvelope(bytes, cfg);
+    if (env !== null) {
+        const { alg, payload, size } = env;
+        let out = callCodecSync(cfg.codecs, alg, 'decompress', [payload, size]);
+        if (out === undefined) {
+            const builtin = platform.decompress[alg];
+            if (builtin === undefined)
+                throw unavailable(alg, 'decompression', (0, web_js_1.webFormat)(alg, 'DecompressionStream') !== undefined);
+            out = builtin(payload, size);
+        }
+        bytes = checkSize(out, size, alg);
+    }
+    return (0, decode_js_1.decodeDocument)(bytes, cfg);
+}
+// --- asynchronous API -------------------------------------------------------------------------
+async function encodeAsyncWith(value, options, platform) {
+    const cfg = (0, options_js_1.encodeConfig)(options);
+    let out = (0, encode_js_1.encodeDocument)(value, cfg.maxDepth, cfg.autoTabular);
+    if (cfg.compress) {
+        const alg = cfg.algorithm;
+        const builtin = platform.compress[alg];
+        const format = (0, web_js_1.webFormat)(alg, 'CompressionStream');
+        if (!hasCodec(cfg.codecs, alg, 'compress') && format === undefined && builtin === undefined) {
+            throw unavailable(alg, 'compression', false);
+        }
+        if (out.length >= constants_js_1.MIN_COMPRESSION_SIZE) {
+            if (out.length > 0xffffffff)
+                throw (0, errors_js_1.fail)('size_limit', 'document too large to compress');
+            let payload = await callCodecAsync(cfg.codecs, alg, 'compress', [out]);
+            if (payload === undefined)
+                payload = format !== undefined ? await (0, web_js_1.webCompress)(format, out) : builtin(out);
+            out = envelopeIfSmaller(out, payload, alg);
+        }
+    }
+    if (cfg.hmacKey !== undefined) {
+        const s = (0, web_js_1.subtle)();
+        const mac = s !== undefined ? await (0, web_js_1.webHmacSign)(s, cfg.hmacKey, concat2(SIGNED_HEADER, out)) : platform.hmac(cfg.hmacKey, [SIGNED_HEADER, out]);
+        out = assembleSigned(mac, out);
+    }
+    return out;
+}
+async function decodeAsyncWith(data, options, platform) {
+    const cfg = (0, options_js_1.decodeConfig)(options);
+    // A private copy: the caller may reuse its buffer while we wait.
+    let bytes = inputBytes(data).slice();
+    if (cfg.hmacKey !== undefined) {
+        const env = signedEnvelope(bytes);
+        const s = (0, web_js_1.subtle)();
+        const ok = s !== undefined
+            ? await (0, web_js_1.webHmacVerify)(s, cfg.hmacKey, env.mac, concat2(env.header, env.payload))
+            : platform.equal(platform.hmac(cfg.hmacKey, [env.header, env.payload]), env.mac);
+        if (!ok)
+            throw (0, errors_js_1.fail)('authentication_failed', 'HMAC verification failed');
+        bytes = env.payload;
+    }
+    else {
+        rejectUnexpectedSignature(bytes);
+    }
+    const env = compressionEnvelope(bytes, cfg);
+    if (env !== null) {
+        const { alg, payload, size } = env;
+        let out = await callCodecAsync(cfg.codecs, alg, 'decompress', [payload, size]);
+        if (out === undefined) {
+            const format = (0, web_js_1.webFormat)(alg, 'DecompressionStream');
+            const builtin = platform.decompress[alg];
+            if (format !== undefined)
+                out = await (0, web_js_1.webDecompress)(alg, format, payload, size);
+            else if (builtin !== undefined)
+                out = builtin(payload, size);
+            else
+                throw unavailable(alg, 'decompression', false);
+        }
+        bytes = checkSize(out, size, alg);
+    }
+    return (0, decode_js_1.decodeDocument)(bytes, cfg);
+}

package/dist/cjs/decode.d.ts

@@ -0,0 +1,10 @@
+import type { DecodeConfig } from './options.js';
+/** A plain Uint8Array view of the same bytes (Buffer.prototype.slice does not copy). */
+export declare function plainBytes(b: Uint8Array): Uint8Array;
+/** Decodes one bare BTOON document (no envelopes). */
+export declare function decodeDocument(bytes: Uint8Array, cfg: DecodeConfig): unknown;
+/**
+ * Used by the encoder: an `Ext` that carries a BTOON-defined id must hold a payload a
+ * strict decoder accepts, so the encoder never emits a document decoders reject.
+ */
+export declare function validateBtoonExt(type: number, data: Uint8Array, depth: number, maxDepth?: number): void;