beatrina 0.8.7 → 0.9.43

package/host/planes/bundle.mjs

@@ -0,0 +1,344 @@
+// bundle.mjs (plane) — the supervisor's side of `.btrn` (docs/results-plan.md R2).
+//
+// The format is host/bundle.mjs; this is its file system and its doors:
+//
+//   bundle_cap     {path, mode: read|write}  → a one-use capability for GET/PUT /bundle
+//   PUT /bundle    the page's parts (source, results record + figures, which
+//                  files, with their kinds) → the supervisor reads the files from disk
+//                  ITSELF, builds the zip, writes it atomically (temp + rename),
+//                  and writes beside-mode data to <bundle>-data/
+//   GET /bundle    → every part, verified, plus what opening would do to each
+//                  data file (absent / same / differs beside the document)
+//   bundle_extract {path, write:[rel], replace:[rel]} → data unpacked next to the
+//                  bundle; `replace` only for files the person agreed to replace
+//   bundle_probe   {dir, paths:[rel]} → which of the paths the code names are
+//                  files, with sizes (the Save dialog's list)
+//   bundle_adopt   {dir, from, to, replace?} → copy a file from outside the
+//                  document's folder into it (the packaging dialog's "Copy in")
+//   bundle_list    {path} → the manifest, read-only
+//
+// Why the supervisor and not the page: data can be 100 MB, and it is already
+// on this machine's disk; the page sends only what it holds. Why not the
+// worker: packing is not evaluation, and a Save must not queue behind a run.
+//
+// Page-only in BOTH senses (role and class) and agent-refused, all but
+// bundle_list: these read and write files at paths, and an agent works on the
+// notebook through its chunks. Every path is absolute, inside BEATRINA_ROOT,
+// and data paths are confined to the bundle's own folder.
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { secureToken, PAGE_ONLY_CLASSES } from "../server.mjs";
+import { makeRoot } from "./files.mjs";
+import { buildBundle, readBundle, dataPlan, dataFolderFor, safeDataPath, sha256, BUNDLE_EXT } from "../bundle.mjs";
+
+const PAGE_REFUSAL = "Only the local notebook page may ask this.";
+const isBundle = (p) => typeof p === "string" && p.toLowerCase().endsWith(BUNDLE_EXT);
+
+/** `rel` under `dir`, or null when it would leave it (a symlink included). */
+export function confined(dir, rel) {
+  if (!safeDataPath(rel)) return null;
+  const base = path.resolve(dir);
+  const target = path.resolve(base, rel);
+  if (target !== base && !target.startsWith(base + path.sep)) return null;
+  let real = target;
+  try { real = fs.realpathSync(target); } catch { return target; }       // absent: the lexical check stands
+  let realBase = base;
+  try { realBase = fs.realpathSync(base); } catch { /* keep */ }
+  return real === realBase || real.startsWith(realBase + path.sep) ? target : null;
+}
+
+/** A path the code names, made absolute against the document's folder: `~/…` is the home folder. */
+export function resolveFrom(dir, raw) {
+  const p = String(raw || "").replace(/\\/g, "/");
+  if (!p || p.length > 4096 || p.includes("\u0000")) return null;
+  if (p === "~" || p.startsWith("~/")) return path.join(os.homedir(), p.slice(1));
+  return path.resolve(dir, p);
+}
+
+const FOLDER_LIST_MAX = 200;
+
+/**
+ * What one path the code names is, on this disk: a file inside the document's
+ * folder (packable as it is), a file OUTSIDE it (absolute, ~, ../ — packable
+ * only by copying it in), a folder (with its files, non-recursive, capped), or
+ * nothing. Sizes only; no bytes are read.
+ */
+export function probeOne(dir, raw) {
+  const written = String(raw).replace(/\\/g, "/").replace(/^\.\//, "");
+  const abs = resolveFrom(dir, written);
+  // Inside means: it resolves under the document's folder ("../me/x.csv" can).
+  const relative = abs ? path.relative(path.resolve(dir), abs).split(path.sep).join("/") : "";
+  const inside = abs && relative && !relative.startsWith("../") && !path.isAbsolute(relative) ? confined(dir, relative) : (abs && !relative ? path.resolve(dir) : null);
+  let st = null;
+  try { st = abs ? fs.statSync(abs) : null; } catch { st = null; }
+  const rel = inside ? (relative || ".") : written;
+  const out = { path: written, rel, exists: !!(st && st.isFile()), size: st && st.isFile() ? st.size : 0, outside: !inside, abs: abs || null };
+  if (st && st.isDirectory()) {
+    out.isDir = true;
+    let names = [];
+    try { names = fs.readdirSync(abs, { withFileTypes: true }).filter((e) => e.isFile() && !e.name.startsWith(".")).map((e) => e.name).sort(); } catch { names = []; }
+    out.truncated = names.length > FOLDER_LIST_MAX;
+    out.files = names.slice(0, FOLDER_LIST_MAX).map((n) => {
+      let size = 0;
+      try { size = fs.statSync(path.join(abs, n)).size; } catch { size = 0; }
+      return { path: rel === "." ? n : `${rel.replace(/\/$/, "")}/${n}`, size };
+    });
+  }
+  return out;
+}
+
+/** Write bytes atomically: a temp file beside the target, then rename. */
+function writeAtomic(target, bytes) {
+  const tmp = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${Date.now()}.tmp`);
+  fs.writeFileSync(tmp, bytes, { mode: 0o644 });
+  try { fs.renameSync(tmp, target); } catch (e) { try { fs.unlinkSync(tmp); } catch { /* gone */ } throw e; }
+}
+
+export function createPlane({ env, audit }) {
+  const root = makeRoot(env("BEATRINA_ROOT"));
+  const bodyMax = Math.min(2e9, Math.max(1e6, Number(env("BEATRINA_UPLOAD_MAX")) || 64 * 1024 * 1024));
+  const insideMax = Number(env("BEATRINA_BUNDLE_INSIDE_MAX")) > 0 ? Number(env("BEATRINA_BUNDLE_INSIDE_MAX")) : undefined;
+  const app = env("BEATRINA_BUILD") || "";
+  const caps = new Map();
+  const mint = (p, mode) => {
+    const now = Date.now();
+    for (const [k, g] of caps) if (g.expires < now) caps.delete(k);
+    const token = secureToken(32);
+    caps.set(token, { path: p, mode, expires: now + 60000 });
+    return token;
+  };
+  const take = (token, mode) => {
+    if (typeof token !== "string" || !/^[A-Za-z0-9]{32}$/.test(token)) return null;
+    const g = caps.get(token);
+    caps.delete(token);
+    return g && g.mode === mode && g.expires >= Date.now() ? g : null;
+  };
+  const pageOnly = (rec) => rec.role === "page" && PAGE_ONLY_CLASSES.includes(rec.class);
+  const checkPath = (p) => {
+    if (typeof p !== "string" || !path.isAbsolute(p)) return "an absolute path is required";
+    if (!isBundle(p)) return `a Beatrina document ends in ${BUNDLE_EXT}`;
+    if (!root.within(p)) return root.outsideMsg();
+    return null;
+  };
+
+  /** Read the bundle at p and say what opening it would do to its data. */
+  const openParts = (p) => {
+    const buf = fs.readFileSync(p);
+    const parts = readBundle(buf);
+    const dir = path.dirname(p);
+    const plan = dataPlan(parts.manifest, (rel) => {
+      const t = confined(dir, rel);
+      try { return t && fs.statSync(t).isFile() ? fs.readFileSync(t) : null; } catch { return null; }
+    });
+    // Beside-mode data: does the carrier folder hold what the manifest says?
+    if (parts.manifest.data?.mode === "beside") {
+      const folder = dataFolderFor(p);
+      plan.forEach((f) => {
+        const t = confined(folder, f.path);
+        let bytes = null;
+        try { bytes = t && fs.statSync(t).isFile() ? fs.readFileSync(t) : null; } catch { bytes = null; }
+        const want = parts.manifest.data.files.find((x) => x.path === f.path);
+        f.carrier = !bytes ? "missing" : sha256(bytes) === want.sha256 ? "ok" : "changed";
+      });
+    }
+    return { parts, plan, digest: sha256(buf), bytes: buf.length };
+  };
+
+  const readBody = (req, max) => new Promise((resolve) => {
+    const chunks = [];
+    let total = 0;
+    let over = false;
+    req.on("data", (d) => { total += d.length; if (total > max) { over = true; chunks.length = 0; return; } chunks.push(d); });
+    req.on("end", () => resolve({ over, body: over ? Buffer.alloc(0) : Buffer.concat(chunks) }));
+    req.on("error", () => resolve({ over, body: Buffer.alloc(0), broken: true }));
+  });
+
+  return {
+    name: "bundle",
+    ops: ["bundle_cap", "bundle_extract", "bundle_probe", "bundle_adopt", "bundle_list"],
+    agentRefused: ["bundle_cap", "bundle_extract", "bundle_probe", "bundle_adopt"],
+    agentRefusalFor: () => PAGE_REFUSAL,
+    commands: ["bundle_cap", "bundle_extract", "bundle_probe", "bundle_adopt", "bundle_list"],
+    capabilities: ["bundle-v1"],
+
+    handle(cmd, rec, ctx) {
+      if (typeof cmd.id !== "string" || !cmd.id.length) return undefined;
+      const reply = (fields) => rec.ws.send(ctx.enc({ type: cmd.type, id: cmd.id, ...fields }));
+      if (cmd.type !== "bundle_list" && !pageOnly(rec)) {
+        audit("bundle-refused", { class: rec.class || "unknown", detail: cmd.type });
+        return reply({ error: PAGE_REFUSAL });
+      }
+      try {
+        if (cmd.type === "bundle_cap") {
+          const bad = checkPath(cmd.path);
+          if (bad) return reply({ error: bad });
+          const mode = cmd.mode === "write" ? "write" : "read";
+          if (mode === "read" && !(fs.existsSync(cmd.path) && fs.statSync(cmd.path).isFile())) return reply({ error: "no such file" });
+          if (mode === "write" && !fs.existsSync(path.dirname(cmd.path))) return reply({ error: `no such folder: ${path.dirname(cmd.path)}` });
+          audit("bundle-cap", { detail: mode });
+          return reply({ cap: mint(cmd.path, mode), mode, max: bodyMax });
+        }
+        if (cmd.type === "bundle_list") {
+          const bad = checkPath(cmd.path);
+          if (bad) return reply({ error: bad });
+          const { parts, plan, digest, bytes } = openParts(cmd.path);
+          return reply({ manifest: parts.manifest, data: plan, digest, bytes });
+        }
+        if (cmd.type === "bundle_probe") {
+          const dir = String(cmd.dir || "");
+          if (!path.isAbsolute(dir) || !root.within(dir)) return reply({ error: "an absolute folder inside the session's root is required" });
+          const paths = Array.isArray(cmd.paths) ? cmd.paths.slice(0, 500).map(String) : [];
+          return reply({ files: paths.map((raw) => probeOne(dir, raw)) });
+        }
+        if (cmd.type === "bundle_adopt") {
+          // Copy a file the document reads from OUTSIDE its folder into it
+          // (`from` absolute, or ~ / ../ relative to dir), under `to`. Never
+          // replaces a different file without `replace: true`; an identical
+          // one is simply reused.
+          const dir = String(cmd.dir || "");
+          if (!path.isAbsolute(dir) || !root.within(dir)) return reply({ error: "an absolute folder inside the session's root is required" });
+          const from = resolveFrom(dir, String(cmd.from || ""));
+          const to = String(cmd.to || "").replace(/\\/g, "/").replace(/^\.\//, "");
+          const target = confined(dir, to);
+          if (!target) return reply({ error: `${to} would leave the document's folder` });
+          if (!from || !root.within(from)) return reply({ error: root.outsideMsg() });
+          let st = null;
+          try { st = fs.statSync(from); } catch { st = null; }
+          if (!st || !st.isFile()) return reply({ error: `${cmd.from} is not a file` });
+          const bytes = fs.readFileSync(from);
+          let there = null;
+          try { there = fs.statSync(target).isFile() ? fs.readFileSync(target) : null; } catch { there = null; }
+          if (there && sha256(there) === sha256(bytes)) return reply({ ok: true, path: to, same: true, size: bytes.length });
+          if (there && cmd.replace !== true) return reply({ exists: true, differs: true, path: to, size: there.length });
+          fs.mkdirSync(path.dirname(target), { recursive: true });
+          writeAtomic(target, bytes);
+          audit("bundle-adopt", { detail: to });
+          return reply({ ok: true, path: to, size: bytes.length, replaced: !!there });
+        }
+        if (cmd.type === "bundle_extract") {
+          const bad = checkPath(cmd.path);
+          if (bad) return reply({ error: bad });
+          const { parts, plan } = openParts(cmd.path);
+          const dir = path.dirname(cmd.path);
+          const want = new Set(Array.isArray(cmd.write) ? cmd.write.map(String) : []);
+          const replace = new Set(Array.isArray(cmd.replace) ? cmd.replace.map(String) : []);
+          const written = []; const skipped = []; const failed = [];
+          for (const f of plan) {
+            const asked = f.state === "absent" ? want.has(f.path) : f.state === "differs" ? replace.has(f.path) : false;
+            if (!asked) { skipped.push({ path: f.path, state: f.state }); continue; }
+            const t = confined(dir, f.path);
+            if (!t) { failed.push({ path: f.path, error: "outside the document's folder" }); continue; }
+            let bytes = parts.data.get(f.path) || null;
+            if (!bytes && parts.manifest.data?.mode === "beside") {
+              const s = confined(dataFolderFor(cmd.path), f.path);
+              try { bytes = s ? fs.readFileSync(s) : null; } catch { bytes = null; }
+            }
+            const entry = parts.manifest.data.files.find((x) => x.path === f.path);
+            if (!bytes || sha256(bytes) !== entry.sha256) { failed.push({ path: f.path, error: "the bundle's copy is missing or changed" }); continue; }
+            try { fs.mkdirSync(path.dirname(t), { recursive: true }); writeAtomic(t, bytes); written.push(f.path); }
+            catch (e) { failed.push({ path: f.path, error: e.message }); }
+          }
+          audit("bundle-extract", { detail: `${written.length} written` });
+          return reply({ written, skipped, failed });
+        }
+      } catch (e) {
+        return reply({ error: e.message, code: e.code || null });
+      }
+      return undefined;
+    },
+
+    http(req, res, pathname, ctx) {
+      if (pathname !== "/bundle") return false;
+      const blocked = ctx.controlRejection(req, { allowFile: true, allowApproved: true });
+      if (blocked) { ctx.reject(res, blocked.reason, blocked.detail); return true; }
+      const origin = req.headers.origin || "";
+      const cors = origin ? { "Access-Control-Allow-Origin": origin, Vary: "Origin" } : {};
+      const json = (status, obj) => ctx.respond(res, status, "application/json", JSON.stringify(obj), { ...cors, "Cache-Control": "no-store" });
+      const method = String(req.method || "GET").toUpperCase();
+      if (method === "OPTIONS") {
+        ctx.respond(res, 204, "text/plain", "", { ...cors, "Access-Control-Allow-Methods": "GET, PUT, OPTIONS",
+          "Access-Control-Allow-Headers": "X-Beatrina-Cap, Content-Type", "Access-Control-Max-Age": "60" });
+        return true;
+      }
+      if (method === "GET") {
+        const url = new URL(req.url, "http://x");
+        const grant = take(url.searchParams.get("cap"), "read");
+        if (!grant) { json(403, { error: "no valid capability" }); return true; }
+        try {
+          const { parts, plan, digest, bytes } = openParts(grant.path);
+          const figures = {};
+          for (const [name, buf] of parts.figures) figures[name] = buf.toString("base64");
+          json(200, { path: grant.path, manifest: parts.manifest, source: parts.source, sourceName: parts.sourceName,
+            results: parts.results, figures, data: plan, digest, bytes });
+        } catch (e) {
+          json(422, { error: e.message, code: e.code || null });
+        }
+        return true;
+      }
+      if (method === "PUT") {
+        const grant = take(req.headers["x-beatrina-cap"], "write");
+        if (!grant) { req.resume(); json(403, { error: "no valid capability" }); return true; }
+        readBody(req, bodyMax).then(({ over, body, broken }) => {
+          if (broken) return json(400, { error: "the upload broke off" });
+          if (over) return json(413, { error: `over the ${Math.round(bodyMax / 1048576)} MB upload limit` });
+          let msg;
+          try { msg = JSON.parse(body.toString("utf8")); } catch { return json(400, { error: "not JSON" }); }
+          const p = grant.path;
+          const dir = path.dirname(p);
+          try {
+            // The file the page read is the file being replaced — or it changed underneath.
+            if (typeof msg.expectedDigest === "string" && msg.expectedDigest && fs.existsSync(p)) {
+              if (sha256(fs.readFileSync(p)) !== msg.expectedDigest) {
+                return json(409, { error: "changed on disk since it was opened", conflict: true });
+              }
+            }
+            const data = [];
+            for (const item of Array.isArray(msg.data) ? msg.data : []) {
+              // A path, or {path, kind} — kind is what the manifest says the file is FOR.
+              const rel = typeof item === "string" ? item : String(item?.path || "");
+              const kind = typeof item === "object" && item && /^[a-z]{1,16}$/.test(String(item.kind || "")) ? item.kind : "data";
+              const t = confined(dir, String(rel));
+              if (!t) return json(400, { error: `${rel} is outside the document's folder`, code: "bundle_bad_path" });
+              let st = null;
+              try { st = fs.statSync(t); } catch { st = null; }
+              if (!st || !st.isFile()) return json(400, { error: `${rel} is not a file next to the document`, code: "bundle_no_data" });
+              data.push({ path: String(rel).replace(/\\/g, "/"), bytes: fs.readFileSync(t), kind });
+            }
+            const figures = (Array.isArray(msg.figures) ? msg.figures : [])
+              .map((f) => ({ name: String(f.name), data: Buffer.from(String(f.data || ""), "base64") }));
+            const built = buildBundle({
+              source: String(msg.source ?? ""), sourceName: String(msg.sourceName || ""), title: String(msg.title || ""),
+              results: msg.results == null ? null : String(msg.results), figures,
+              data, app, bundleName: path.basename(p),
+              ...(insideMax ? { insideMax } : {}),
+            });
+            if (built.beside.length) {
+              const folder = dataFolderFor(p);
+              for (const d of built.beside) {
+                const t = confined(folder, d.path);
+                if (!t) return json(400, { error: `${d.path} would leave the data folder` });
+                let same = false;
+                try { same = sha256(fs.readFileSync(t)) === sha256(d.bytes); } catch { same = false; }
+                if (!same) { fs.mkdirSync(path.dirname(t), { recursive: true }); writeAtomic(t, d.bytes); }
+              }
+            }
+            writeAtomic(p, built.zip);
+            audit("bundle-write", { detail: `${built.zip.length} bytes, data ${built.manifest.data.mode}` });
+            return json(200, { ok: true, path: p, bytes: built.zip.length, digest: sha256(built.zip),
+              dataMode: built.manifest.data.mode, data: built.manifest.data.files.map((f) => ({ path: f.path, size: f.size, kind: f.kind })),
+              folder: built.beside.length ? dataFolderFor(p) : null });
+          } catch (e) {
+            return json(e.code && /^bundle_|^zip_/.test(e.code) ? 400 : 500, { error: e.message, code: e.code || null });
+          }
+        });
+        return true;
+      }
+      json(405, { error: "GET, PUT or OPTIONS" });
+      return true;
+    },
+  };
+}
+
+export default { createPlane, confined };