beatrina 0.8.7 → 0.9.43

package/host/zip.mjs

@@ -0,0 +1,237 @@
+// zip.mjs — write and read standard ZIP archives, with Node's zlib and nothing else.
+//
+// The container under `.btrn` (docs/results-plan.md R2). A .btrn must open in
+// every unzip there is — macOS Archive Utility, `unzip`, R's utils::unzip() —
+// so this writes the plain, universal subset of the format and nothing clever:
+// one local header + data per entry, a central directory, the end record.
+// Method 0 (stored) or 8 (deflated); UTF-8 names (flag bit 11); no ZIP64 (a
+// .btrn holds ≤ 100 MB of data by design — past that the data lives beside
+// it), no encryption, no data descriptors. zlib.crc32 is Node ≥ 22.2.
+//
+// READING IS READING SOMETHING FROM ELSEWHERE, so the reader refuses before it
+// trusts:
+//   · a name that is absolute, has a `..` segment, a drive letter, a
+//     backslash, a NUL, or is empty — the zip-slip family, refused by name;
+//   · the same name twice;
+//   · an encrypted entry, or a method other than 0/8;
+//   · more than `maxTotal` bytes uncompressed in all — the zip-bomb family,
+//     refused with its numbers BEFORE inflating (a per-entry ratio is
+//     optional: deflate tops out near 1032×, so it guards nothing by default);
+//   · an entry that inflates to more than it declared (zlib's
+//     maxOutputLength enforces the declared size), or whose CRC-32 differs.
+// Every refusal is a thrown Error with `code` set, so callers can say which.
+
+import zlib from "node:zlib";
+
+const SIG_LOCAL = 0x04034b50;
+const SIG_CENTRAL = 0x02014b50;
+const SIG_END = 0x06054b50;
+const FLAG_UTF8 = 0x0800;
+const U32 = 0xffffffff;
+
+/** Date → the two 16-bit MS-DOS fields (2-second resolution, 1980..2107). */
+function dosTime(date) {
+  const d = date instanceof Date && !Number.isNaN(date.getTime()) ? date : new Date(1980, 0, 1);
+  const year = Math.min(2107, Math.max(1980, d.getFullYear()));
+  return {
+    time: (d.getHours() << 11) | (d.getMinutes() << 5) | Math.floor(d.getSeconds() / 2),
+    date: ((year - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate(),
+  };
+}
+
+const fail = (code, message) => Object.assign(new Error(message), { code });
+
+/** The Info-ZIP Unicode Path extra field: version 1, CRC-32 of the header name, the UTF-8 name. */
+function unicodePathExtra(nameBytes) {
+  const field = Buffer.alloc(4 + 5 + nameBytes.length);
+  field.writeUInt16LE(0x7075, 0);
+  field.writeUInt16LE(5 + nameBytes.length, 2);
+  field.writeUInt8(1, 4);
+  field.writeUInt32LE(zlib.crc32(nameBytes) >>> 0, 5);
+  nameBytes.copy(field, 9);
+  return field;
+}
+
+/**
+ * Is this an entry name a reader may use? Relative, forward slashes, no
+ * `..`/`.` segment, no drive, no NUL, not empty. A directory entry ends in `/`.
+ */
+export function safeEntryName(name) {
+  const n = String(name ?? "");
+  if (!n || n.length > 1024 || /[\u0000\\]/.test(n)) return false;
+  if (n.startsWith("/") || /^[A-Za-z]:/.test(n)) return false;
+  const parts = n.replace(/\/$/, "").split("/");
+  return parts.every((p) => p !== "" && p !== "." && p !== "..");
+}
+
+/**
+ * Build a ZIP in memory.
+ *
+ * @param {Array<{name:string, data:Buffer|Uint8Array|string, compress?:boolean, date?:Date}>} entries
+ *   `compress` false stores the bytes (right for PNG/JPEG, already compressed);
+ *   the default deflates, and keeps the stored form when deflate does not help.
+ * @returns {Buffer}
+ */
+export function writeZip(entries, { date = new Date() } = {}) {
+  if (!Array.isArray(entries)) throw fail("zip_input", "writeZip needs a list of entries");
+  if (entries.length > 0xfffe) throw fail("zip_too_many", `${entries.length} entries is more than a plain ZIP holds`);
+  const seen = new Set();
+  const locals = [];
+  const centrals = [];
+  let offset = 0;
+  for (const entry of entries) {
+    const name = String(entry.name ?? "");
+    if (!safeEntryName(name)) throw fail("zip_bad_name", `unsafe entry name: ${JSON.stringify(name)}`);
+    if (seen.has(name)) throw fail("zip_duplicate", `the entry ${name} appears twice`);
+    seen.add(name);
+    const raw = Buffer.isBuffer(entry.data) ? entry.data
+      : typeof entry.data === "string" ? Buffer.from(entry.data, "utf8") : Buffer.from(entry.data ?? []);
+    if (raw.length >= U32) throw fail("zip_too_large", `${name} is over 4 GB; a plain ZIP cannot hold it`);
+    const crc = zlib.crc32(raw) >>> 0;
+    let method = 0;
+    let body = raw;
+    if (entry.compress !== false && raw.length) {
+      const deflated = zlib.deflateRawSync(raw, { level: 6 });
+      if (deflated.length < raw.length) { method = 8; body = deflated; }
+    }
+    const nameBytes = Buffer.from(name, "utf8");
+    // A non-ASCII name also travels in the Info-ZIP Unicode Path field
+    // (0x7075): macOS's bundled unzip ignores the UTF-8 flag and mangles
+    // "ünïcode.csv" without it; readers that honour the flag ignore this.
+    const extra = /[^\x00-\x7f]/.test(name) ? unicodePathExtra(nameBytes) : Buffer.alloc(0);
+    const { time, date: dd } = dosTime(entry.date || date);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(SIG_LOCAL, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(FLAG_UTF8, 6);
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(dd, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(raw.length, 22);
+    local.writeUInt16LE(nameBytes.length, 26);
+    local.writeUInt16LE(extra.length, 28);
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(SIG_CENTRAL, 0);
+    // Made by UNIX (3), spec 2.0: a reader then takes the name's bytes as they
+    // are. Marked MS-DOS (0), macOS's bundled unzip (6.00, no Unicode support)
+    // translated every non-ASCII name from code page 437 and wrote garbage.
+    central.writeUInt16LE((3 << 8) | 20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(FLAG_UTF8, 8);
+    central.writeUInt16LE(method, 10);
+    central.writeUInt16LE(time, 12);
+    central.writeUInt16LE(dd, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(body.length, 20);
+    central.writeUInt32LE(raw.length, 24);
+    central.writeUInt16LE(nameBytes.length, 28);
+    central.writeUInt16LE(extra.length, 30);
+    central.writeUInt32LE(((name.endsWith("/") ? 0o40755 : 0o100644) << 16) >>> 0, 38);   // rw-r--r-- (a dir rwxr-xr-x)
+    central.writeUInt32LE(offset, 42);       // comment, disk, internal attrs: 0
+    locals.push(local, nameBytes, extra, body);
+    centrals.push(central, nameBytes, extra);
+    offset += local.length + nameBytes.length + extra.length + body.length;
+    if (offset >= U32) throw fail("zip_too_large", "the archive would pass 4 GB; a plain ZIP cannot hold it");
+  }
+  const cd = Buffer.concat(centrals);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(SIG_END, 0);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(cd.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, cd, end]);
+}
+
+/**
+ * The central directory: every entry's name, sizes, method and where its
+ * bytes are — nothing inflated. What `bundle_list` shows, and what readZip
+ * checks the caps against before touching any data.
+ *
+ * @param {Buffer} buf
+ * @returns {Array<{name:string, method:number, crc:number, csize:number, usize:number, offset:number, dir:boolean}>}
+ */
+export function listZip(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 22) throw fail("zip_not_zip", "not a ZIP archive (too short)");
+  let end = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 0xffff); i -= 1) {
+    if (buf.readUInt32LE(i) === SIG_END) { end = i; break; }
+  }
+  if (end < 0) throw fail("zip_not_zip", "not a ZIP archive (no end record)");
+  const count = buf.readUInt16LE(end + 10);
+  const cdSize = buf.readUInt32LE(end + 12);
+  const cdOffset = buf.readUInt32LE(end + 16);
+  if (count === 0xffff || cdOffset === U32) throw fail("zip_zip64", "a ZIP64 archive — not a .btrn this version wrote");
+  if (cdOffset + cdSize > end) throw fail("zip_corrupt", "the central directory runs past the end record");
+  const out = [];
+  const names = new Set();
+  let p = cdOffset;
+  for (let k = 0; k < count; k += 1) {
+    if (p + 46 > end || buf.readUInt32LE(p) !== SIG_CENTRAL) throw fail("zip_corrupt", `central directory entry ${k + 1} is damaged`);
+    const flags = buf.readUInt16LE(p + 8);
+    const method = buf.readUInt16LE(p + 10);
+    const crc = buf.readUInt32LE(p + 16) >>> 0;
+    const csize = buf.readUInt32LE(p + 20);
+    const usize = buf.readUInt32LE(p + 24);
+    const nlen = buf.readUInt16LE(p + 28);
+    const xlen = buf.readUInt16LE(p + 30);
+    const clen = buf.readUInt16LE(p + 32);
+    const offset = buf.readUInt32LE(p + 42);
+    const name = buf.subarray(p + 46, p + 46 + nlen).toString((flags & FLAG_UTF8) ? "utf8" : "latin1");
+    if (!safeEntryName(name)) throw fail("zip_bad_name", `unsafe entry name in the archive: ${JSON.stringify(name)}`);
+    if (names.has(name)) throw fail("zip_duplicate", `the entry ${name} appears twice`);
+    names.add(name);
+    if (flags & 0x0001) throw fail("zip_encrypted", `${name} is encrypted`);
+    if (method !== 0 && method !== 8) throw fail("zip_method", `${name} uses compression method ${method}; only stored and deflated are read`);
+    out.push({ name, method, crc, csize, usize, offset, dir: name.endsWith("/") });
+    p += 46 + nlen + xlen + clen;
+  }
+  return out;
+}
+
+/**
+ * Read a ZIP: every file entry's bytes, verified.
+ *
+ * @param {Buffer} buf
+ * @param {{maxTotal?:number, maxRatio?:number, only?:(name:string)=>boolean}} [opts]
+ *   the cap on the whole archive's uncompressed bytes (default 2 GB); an
+ *   optional per-entry expansion cap (none by default: one layer of deflate
+ *   cannot pass ~1032×, and an honest file of zeros reaches 1026×, so a ratio
+ *   refuses real data while the total cap and the declared-size inflate are
+ *   what actually stop a bomb); `only` reads a subset
+ * @returns {Map<string, Buffer>}
+ */
+export function readZip(buf, { maxTotal = 2 * 1024 ** 3, maxRatio = Infinity, only = null } = {}) {
+  const entries = listZip(buf).filter((e) => !e.dir && (!only || only(e.name)));
+  const total = entries.reduce((a, e) => a + e.usize, 0);
+  if (total > maxTotal) throw fail("zip_bomb", `the archive expands to ${total} bytes, over the ${maxTotal}-byte cap`);
+  for (const e of entries) {
+    if (e.method === 8 && e.usize > Math.max(1024, e.csize * maxRatio)) {
+      throw fail("zip_bomb", `${e.name} claims to expand ${e.csize} → ${e.usize} bytes, over ${maxRatio}×`);
+    }
+  }
+  const files = new Map();
+  for (const e of entries) {
+    const p = e.offset;
+    if (p + 30 > buf.length || buf.readUInt32LE(p) !== SIG_LOCAL) throw fail("zip_corrupt", `${e.name}: its local header is damaged`);
+    const start = p + 30 + buf.readUInt16LE(p + 26) + buf.readUInt16LE(p + 28);
+    if (start + e.csize > buf.length) throw fail("zip_corrupt", `${e.name}: its data runs past the end`);
+    const body = buf.subarray(start, start + e.csize);
+    let data;
+    if (e.method === 0) {
+      if (e.csize !== e.usize) throw fail("zip_corrupt", `${e.name}: stored entry with two different sizes`);
+      data = Buffer.from(body);
+    } else {
+      try { data = zlib.inflateRawSync(body, { maxOutputLength: Math.max(1, e.usize) }); }
+      catch (err) { throw fail("zip_corrupt", `${e.name}: ${err.code === "ERR_BUFFER_TOO_LARGE" ? "inflates past its declared size" : "does not inflate"}`); }
+      if (data.length !== e.usize) throw fail("zip_corrupt", `${e.name}: inflated to ${data.length} bytes, declared ${e.usize}`);
+    }
+    if ((zlib.crc32(data) >>> 0) !== e.crc) throw fail("zip_crc", `${e.name}: CRC-32 does not match — the archive is damaged`);
+    files.set(e.name, data);
+  }
+  return files;
+}
+
+export default { writeZip, readZip, listZip, safeEntryName };

package/kernel/analyze.R

@@ -44,7 +44,7 @@ suppressPackageStartupMessages(stopifnot(requireNamespace("jsonlite", quietly =
 # raise it knowingly. Clamped to [0, 60] so a typo cannot remove the bound —
 # and 0 is a real setting, meaning "scan nothing and report it truncated".
 ANALYZE_BUDGET <- local({
-  v <- suppressWarnings(as.numeric(Sys.getenv("CARMAR_ANALYZE_BUDGET", "3")))
+  v <- suppressWarnings(as.numeric(Sys.getenv("BEATRINA_ANALYZE_BUDGET", "3")))
   if (!is.finite(v)) v <- 3
   max(0, min(v, 60))
 })

package/{check → kernel/check}/acceptance.mjs

@@ -14,7 +14,7 @@
 //
 // Usage
 //   node tools/beatrina/acceptance.mjs                         # this checkout's host
-//   node tools/beatrina/acceptance.mjs --installed             # the installed carmar package's host
+//   node tools/beatrina/acceptance.mjs --installed             # the installed beatrina package's host
 //   node tools/beatrina/acceptance.mjs --host=C:\path\to\host\main.mjs
 //   node tools/beatrina/acceptance.mjs --supervisor=serve-r    # the retired R supervisor, for comparison
 //   options: --port=28900 --repeat=5 --json=out.json --junit=out.xml --only=stop,readline --log=host.log