beatrina 0.8.6

package/host/ai-policy.mjs

@@ -0,0 +1,218 @@
+// ai-policy.mjs — which AI providers an administrator permits, and what the
+// kernel can actually do about it. A transcription of spike/ai-policy.R.
+//
+// ── the honest scope, first, because everything else depends on it ──────────
+//
+// The notebook runs in a browser the user controls, and the AI request for a
+// key-based provider is a `fetch()` from that page. No kernel can prevent a
+// determined user with devtools and their own API key from calling any endpoint
+// they like. Any document promising otherwise would be lying.
+//
+// What an administrator policy DOES buy is three things: a default the user did
+// not choose and cannot casually change, the constraint made VISIBLE rather
+// than discovered by hitting it, and the two doors the supervisor genuinely
+// owns, closed:
+//
+//   · `ai-key` — the provider key is handed out by the supervisor. Under a
+//     policy permitting no key-based provider it stops handing it out AND stops
+//     accepting one. The user can still paste a key into the tab; the kernel
+//     will not keep one for them, and the refusal is audited.
+//   · `agent-chat` — a CLI turn is a process the SUPERVISOR spawns. A policy
+//     that does not permit it means it is never spawned, with no page-side
+//     bypass because there is no page-side spawn. (That door is WP5b's; this
+//     module answers the question for it.)
+//
+// Everything else is disclosure and audit.
+//
+// ── where a policy comes from ──────────────────────────────────────────────
+//
+//   CARMAR_AI_POLICY=/etc/carmar/ai-policy.json   a file the user cannot write
+//   CARMAR_AI_PROVIDERS=anthropic,lmstudio        the quick form
+//   CARMAR_AI_LOCAL_ONLY=1                        only on-machine providers
+//
+// The file wins where both are set, because a file is the form an administrator
+// can own while an environment variable is inherited from whoever started the
+// process — on a shared host, that may be the user.
+
+import fs from "node:fs";
+
+/**
+ * The providers whose text never leaves the machine.
+ *
+ * THIS LIST IS A CROSS-LANGUAGE CONTRACT. It must agree with `staysOnMachine()`
+ * in lib/llm.js, which is the browser's answer to the same question;
+ * test/ai-policy.test.mjs reads both and fails if they diverge. Note what is
+ * NOT here: `claudecode` and `codex` carry `local: true` in lib/llm.js because
+ * they cost no API key, but they hand the prompt to a CLI that sends it to a
+ * vendor. Using `local` to mean "stays here" would quietly ship the user's code
+ * out.
+ */
+export const ON_MACHINE_PROVIDERS = Object.freeze(["chrome", "webgpu", "ollama", "lmstudio", "jan"]);
+/** Providers reached with the user's API key — the ones the `ai-key` door serves. */
+export const KEY_PROVIDERS = Object.freeze(["openai", "anthropic", "google", "groq", "together", "openrouter", "azure", "custom"]);
+/** Providers that are a CLI process the SUPERVISOR spawns. The door it owns. */
+export const CLI_PROVIDERS = Object.freeze(["claudecode", "codex"]);
+export const ALL_PROVIDERS = Object.freeze([...ON_MACHINE_PROVIDERS, ...KEY_PROVIDERS, ...CLI_PROVIDERS]);
+
+const sysEnv = (name, unset = "") => (process.env[name] == null ? unset : String(process.env[name]));
+const asList = (v) => (v == null ? [] : (Array.isArray(v) ? v : [v]));
+
+/**
+ * Normalise a policy file's `models` map into provider → array of ids.
+ * Accepts a single string as a one-element list, because
+ * `"anthropic": "claude-sonnet-4"` is what an administrator will write and
+ * refusing it over a missing pair of brackets would be pedantry with a startup
+ * failure attached.
+ */
+export function normaliseModels(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out = {};
+  for (const key of Object.keys(raw)) {
+    if (!key.length) continue;
+    const ids = [...new Set(asList(raw[key]).flat().map((v) => String(v).trim()))].filter((v) => v.length);
+    if (ids.length) out[key] = ids;
+  }
+  return out;
+}
+
+const HOSTED_RE = /^https:\/\/[^/@?#\s]+(?::[0-9]+)?(?:\/[^?#\s]*)?\/?$/i;
+const LOOPBACK_RE = /^http:\/\/(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]+)?(?:\/[^?#\s]*)?\/?$/i;
+
+/**
+ * Normalise administrator-pinned provider endpoints. These values are returned
+ * to the page, so credentials, query strings and fragments are forbidden.
+ * Hosted gateways must use HTTPS. Loopback HTTP is allowed only for the
+ * providers that genuinely run on this machine.
+ */
+export function normaliseBaseUrls(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { values: {}, errors: [] };
+  const values = {};
+  const errors = [];
+  for (const provider of Object.keys(raw)) {
+    if (!provider.length) continue;
+    const list = asList(raw[provider]).flat().map((v) => String(v));
+    const value = list.length ? list[0].trim() : "";
+    const hosted = HOSTED_RE.test(value);
+    const loopback = ON_MACHINE_PROVIDERS.includes(provider) && LOOPBACK_RE.test(value);
+    if (!value.length || list.length !== 1 || (!hosted && !loopback)) {
+      errors.push(`AI policy base_urls.${provider} must be one credential-free HTTPS URL (or loopback HTTP for an on-machine provider).`);
+    } else values[provider] = value;
+  }
+  return { values, errors };
+}
+
+const policySplit = (value) => String(value || "").split(/[,\s]+/).map((s) => s.trim()).filter((s) => s.length);
+// Control characters are 0x00-0x1f and 0x7f — R's [[:cntrl:]], spelled out.
+// eslint-disable-next-line no-control-regex
+const stripControl = (s) => String(s).replace(/[\u0000-\u001f\u007f]/g, " ");
+
+/**
+ * Read the administrator's AI policy.
+ *
+ * A policy that names NOTHING valid is an ERROR, never an empty allow-list:
+ * silently permitting no provider would look identical to the AI being broken,
+ * and an administrator would have no way to tell which it was. Three states —
+ * named nothing / named something valid / named only junk — and conflating the
+ * last two is the fail-open bug.
+ */
+export function carmarAiPolicy(env = sysEnv) {
+  const file = String(env("CARMAR_AI_POLICY", "")).trim();
+  let named = [];
+  let models = {};
+  let baseUrls = {};
+  let localOnly = env("CARMAR_AI_LOCAL_ONLY", "") === "1";
+  let note = "";
+  let source = "";
+  let errors = [];
+
+  if (file.length) {
+    source = file;
+    if (!fs.existsSync(file)) {
+      errors.push(`CARMAR_AI_POLICY names a file that does not exist: ${file}`);
+    } else {
+      let doc = null;
+      let parseError = "";
+      try { doc = JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) { parseError = e.message; }
+      if (parseError) errors.push(`CARMAR_AI_POLICY is not valid JSON: ${parseError}`);
+      else {
+        named = asList(doc && doc.providers).flat().map((v) => String(v));
+        if (doc && doc.local_only === true) localOnly = true;
+        note = String(asList(doc && doc.note).flat()[0] ?? "").trim();
+        // `models` is FILE-ONLY, deliberately. A provider list flattens to a
+        // comma-separated environment variable without losing anything; a map
+        // of provider to permitted model ids does not, and every syntax that
+        // crams one into a single string is a syntax a typo hides in.
+        models = normaliseModels(doc && doc.models);
+        const endpoints = normaliseBaseUrls(doc && doc.base_urls);
+        baseUrls = endpoints.values;
+        errors = errors.concat(endpoints.errors);
+      }
+    }
+  } else if (String(env("CARMAR_AI_PROVIDERS", "")).length) {
+    source = "env";
+    named = policySplit(env("CARMAR_AI_PROVIDERS", ""));
+  } else if (localOnly) {
+    source = "env";
+  }
+
+  const unknown = named.filter((n) => !ALL_PROVIDERS.includes(n));
+  const asked = named.length > 0;                 // did the policy NAME anything at all?
+  named = named.filter((n) => ALL_PROVIDERS.includes(n));
+
+  let providers = named.length ? named : (asked ? [] : [...ALL_PROVIDERS]);
+  if (localOnly) providers = providers.filter((p) => ON_MACHINE_PROVIDERS.includes(p));
+
+  let set = source.length > 0 && errors.length === 0;
+  if (set && !providers.length) {
+    errors.push(`The AI policy permits no provider at all${
+      unknown.length ? ` (unrecognised: ${unknown.join(", ")})` : ""}${
+      localOnly ? " — local_only was combined with providers that all send text off the machine" : ""
+    }. Name at least one, or remove the policy.`);
+  }
+  if (errors.length) { set = false; providers = [...ALL_PROVIDERS]; }
+
+  // Control characters out: this string is rendered in the notebook and written
+  // to the audit log, and an administrator's file is still a file.
+  note = stripControl(note).slice(0, 400).trim();
+
+  // A models entry for a provider that is not permitted is dead weight, and
+  // leaving it in would make the page render a constraint on a control the user
+  // cannot reach anyway.
+  const keep = (map) => Object.fromEntries(Object.entries(map).filter(([k]) => providers.includes(k)));
+  models = errors.length ? {} : keep(models);
+  baseUrls = errors.length ? {} : keep(baseUrls);
+
+  return { set, source, providers, models, base_urls: baseUrls, local_only: localOnly, note, unknown, errors,
+    // The two doors the supervisor actually owns, precomputed so the call sites
+    // read as the questions they are asking.
+    allows_key: providers.some((p) => KEY_PROVIDERS.includes(p)),
+    allows_cli: providers.filter((p) => CLI_PROVIDERS.includes(p)) };
+}
+
+/** May this provider be used at all? */
+export const aiProviderAllowed = (provider, policy) =>
+  policy.set !== true || (typeof provider === "string" && provider.length > 0 && policy.providers.includes(provider));
+
+/**
+ * May this model be used with this provider? TRUE when no models are pinned for
+ * that provider — pinning is opt-in per provider. DISCLOSURE ONLY: a model id
+ * is a field in a request body the page builds and sends itself, so there is no
+ * door here to close.
+ */
+export const aiModelAllowed = (provider, model, policy) => {
+  if (policy.set !== true) return true;
+  const allowed = policy.models[provider || ""];
+  if (!allowed || !allowed.length) return true;
+  return typeof model === "string" && model.length > 0 && allowed.includes(model);
+};
+
+/**
+ * The sentence the notebook shows when something is refused. Names the
+ * administrator's own note when there is one, because "your administrator has
+ * limited this" without saying who or why is the worst version of a policy
+ * message.
+ */
+export const aiPolicyReason = (policy) => {
+  const base = `This CarmaR is configured to allow only: ${policy.providers.join(", ")}.`;
+  return policy.note.length ? `${base} ${policy.note}` : base;
+};

package/host/deployment.mjs

@@ -0,0 +1,160 @@
+// deployment.mjs — where the host listens, and who is allowed to reach it.
+//
+// A pure port of spike/deployment.R. The posture is computed ONCE from the
+// environment and handed to the gates as a decided answer; every gate reads a
+// field of it rather than re-interpreting an environment variable at each call
+// site. `env` is injected so the whole policy is testable without a server —
+// test/host-deployment.test.mjs runs the same vectors spike/test-deployment.R
+// runs against the R implementation, which is what keeps two implementations of
+// one trust model from drifting.
+//
+// The rule that INVERTS off loopback (and why this file exists at all): a
+// request with no Origin header is allowed on 127.0.0.1 because it proves the
+// client is not a browser and therefore is this same OS user; anywhere the port
+// is reachable by someone else the same header proves nothing, so it is refused.
+
+export const LOOPBACK_HOSTS = ["127.0.0.1", "::1", "[::1]", "localhost"];
+
+/** Split a comma/space-separated environment value into trimmed, non-empty parts. */
+export function splitList(value) {
+  return String(value ?? "").split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * Is this bind address one of the loopback literals?
+ *
+ * Deliberately a literal comparison and not a resolve: a NAME that currently
+ * resolves to 127.0.0.1 is not the same promise as an address that cannot leave
+ * the machine, and the whole point of the flag is that it cannot be talked into
+ * being true.
+ */
+export function isLoopbackBind(bind) {
+  return LOOPBACK_HOSTS.includes(String(bind ?? "").toLowerCase());
+}
+
+/**
+ * Compute the deployment posture from the environment.
+ *
+ * @param {number} port the port the server will listen on
+ * @param {(name: string, unset?: string) => string} [env] a getter with
+ *   `Sys.getenv`'s signature; defaults to `process.env`
+ * @returns {{bind:string, port:number, loopback:boolean, origins:string[],
+ *   hosts:string[], allow_native:boolean, require_origin:boolean,
+ *   trust_proxy:boolean, user_header:string, user_header_key:string,
+ *   proxy_addrs:string[], allow_unauthenticated:boolean, errors:string[]}}
+ *   `errors` is EMPTY when the posture is safe to serve. A non-empty `errors`
+ *   must abort startup; it is never a warning.
+ */
+export function carmarDeployment(port, env = envFromProcess()) {
+  let bind = env("CARMAR_BIND", "127.0.0.1").trim();
+  if (!bind) bind = "127.0.0.1";
+  const loopback = isLoopbackBind(bind);
+
+  // The origin this host serves its own page from is always allowed: that is
+  // the same-origin case. Off loopback the server is behind a proxy, so its own
+  // page arrives with the PROXY's origin — which the operator must name.
+  const selfOrigins = [`http://${bind}:${port}`, `http://127.0.0.1:${port}`, `http://localhost:${port}`];
+  const origins = unique([...selfOrigins, ...splitList(env("CARMAR_ORIGINS", ""))]);
+
+  let hostsEnv = splitList(env("CARMAR_HOSTS", ""));
+  const defaultHosts = [`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`];
+  // A configured host may or may not carry a port. Accept both spellings so an
+  // operator writing `stats.example.edu` is not silently refused behind a proxy
+  // that forwards the default 80/443 and therefore sends no port at all.
+  hostsEnv = unique([...hostsEnv, ...hostsEnv.map((h) => (h.includes(":") ? h : `${h}:${port}`))]);
+  const hosts = unique([...defaultHosts, ...hostsEnv].map((h) => h.toLowerCase()));
+
+  // "Anyone who reaches this port is this same OS user" is the premise behind
+  // allowing an Origin-less client. Binding off loopback breaks it, but so does
+  // a shared multi-user host or a container whose 127.0.0.1 is forwarded out,
+  // so the posture is declarable in its own right.
+  const requireOrigin = env("CARMAR_REQUIRE_ORIGIN", "") === "1" || !loopback;
+
+  const trustProxy = env("CARMAR_TRUST_PROXY", "") === "1";
+  const userHeader = env("CARMAR_USER_HEADER", "X-Forwarded-User").trim();
+  const proxyAddrs = splitList(env("CARMAR_TRUSTED_PROXY", "127.0.0.1 ::1"));
+  const allowOpen = env("CARMAR_ALLOW_UNAUTHENTICATED", "") === "1";
+
+  const errors = [];
+  if (!loopback) {
+    if (!hostsEnv.length) {
+      errors.push(`CARMAR_BIND is ${bind} but CARMAR_HOSTS is unset. Off loopback the `
+        + "Host allow-list is the only defence against DNS rebinding, so it must "
+        + "name the hostname readers will use (e.g. CARMAR_HOSTS=stats.example.edu).");
+    }
+    if (!trustProxy && !allowOpen) {
+      errors.push(`CARMAR_BIND is ${bind} with no authentication in front of it. Put `
+        + "Beatrina behind a reverse proxy that authenticates and set "
+        + "CARMAR_TRUST_PROXY=1, or set CARMAR_ALLOW_UNAUTHENTICATED=1 to serve code "
+        + "execution to everyone who can reach this port. See docs/server.md.");
+    }
+    if (trustProxy && !userHeader) {
+      errors.push("CARMAR_TRUST_PROXY=1 requires a non-empty CARMAR_USER_HEADER.");
+    }
+    if (trustProxy && !proxyAddrs.length) {
+      errors.push("CARMAR_TRUST_PROXY=1 requires CARMAR_TRUSTED_PROXY to name the proxy's address.");
+    }
+  }
+
+  return {
+    bind,
+    port,
+    loopback,
+    origins,
+    hosts,
+    // THE INVERSION. On a private loopback an absent Origin is a same-user
+    // native client and is allowed; anywhere the port is reachable by someone
+    // else it is an unauthenticated stranger and is not.
+    allow_native: !requireOrigin,
+    require_origin: requireOrigin,
+    trust_proxy: trustProxy && requireOrigin,
+    user_header: userHeader,
+    // The Rook spelling R's gates read: `HTTP_` + uppercase, `-` → `_`. Kept
+    // so the vectors stay word-for-word comparable across the two hosts.
+    user_header_key: `HTTP_${userHeader.toUpperCase().replace(/-/g, "_")}`,
+    proxy_addrs: proxyAddrs,
+    allow_unauthenticated: allowOpen,
+    errors,
+  };
+}
+
+/**
+ * Who is this request, according to the proxy in front of us?
+ *
+ * Returns "" unless the posture trusts a proxy AND the request actually came
+ * from one of the named proxy addresses. That second half is what stops the
+ * header being a self-service login.
+ *
+ * @param {{REMOTE_ADDR?: string} & Record<string, string>} req a Rook-shaped
+ *   request: `REMOTE_ADDR` plus `HTTP_*` header keys
+ * @param {ReturnType<typeof carmarDeployment>} deployment
+ * @returns {string}
+ */
+export function proxyUser(req, deployment) {
+  if (!deployment.trust_proxy) return "";
+  const peer = String(req.REMOTE_ADDR ?? "").toLowerCase();
+  if (!peer || !deployment.proxy_addrs.map((a) => a.toLowerCase()).includes(peer)) return "";
+  let name = String(req[deployment.user_header_key] ?? "");
+  // One line, printable, bounded — it reaches the audit log and the page title.
+  // eslint-disable-next-line no-control-regex
+  name = name.replace(/[\x00-\x1f\x7f]/g, "");
+  return name.slice(0, 128).trim();
+}
+
+/** Node's request headers, spelled the way `proxyUser` reads them. */
+export function rookOf(req) {
+  const out = { REMOTE_ADDR: req.socket?.remoteAddress ?? "" };
+  for (const [k, v] of Object.entries(req.headers || {})) {
+    out[`HTTP_${k.toUpperCase().replace(/-/g, "_")}`] = Array.isArray(v) ? v.join(", ") : String(v);
+  }
+  return out;
+}
+
+/** A getter with `Sys.getenv`'s signature over `process.env`. */
+export function envFromProcess(source = process.env) {
+  return (name, unset = "") => (source[name] == null ? unset : String(source[name]));
+}
+
+function unique(list) {
+  return [...new Set(list)];
+}

package/host/engine-js.mjs

@@ -0,0 +1,98 @@
+// engine-js.mjs — the JavaScript engine's adapter (docs/beatrix-alternative-plan.md Stage 5).
+//
+// The process behind it is `engines/js/worker.mjs`, run by a Node the host
+// can name. It speaks the wire worker.R and worker.py speak, so everything but
+// three answers is StdioEngine's:
+//
+//   · WHICH NODE. The host's own `process.execPath` when the host is a plain
+//     `node host/main.mjs` — the Node the R launcher already found and
+//     version-checked. A packaged single-executable host (node:sea) cannot run
+//     a script, so there the engine needs `BEATRIX_NODE` / `CARMAR_NODE`, and
+//     says so on the ready frame rather than appearing and failing.
+//   · A CONSOLE LINE MEANS NOTHING. The worker reads commands only; there is
+//     no prompt, so canInput and canDebug are false and the plane refuses
+//     input_reply and debug_cmd for this engine by those capabilities.
+//   · STOP is the same group SIGINT: the worker leads its own process group and
+//     runs every chunk with vm's `breakOnSigint`, so a tight loop is interrupted
+//     with the session's variables kept.
+
+import fs from "node:fs";
+import { StdioEngine } from "./engine-stdio.mjs";
+import { findInterruptTool } from "./windows-runtime.mjs";
+
+export const JS_MIN_NODE = 22;
+
+/**
+ * Find a Node for the JavaScript engine, and SAY WHAT WAS DECIDED.
+ * @returns {{available: boolean, path: string, version: string, detail: string}}
+ */
+export function detectNode({ env = process.env, packaged = false, execPath = process.execPath, versions = process.versions } = {}) {
+  const explicit = env.BEATRIX_NODE || env.CARMAR_NODE || "";
+  if (explicit) {
+    if (!fs.existsSync(explicit)) return { available: false, path: "", version: "", detail: `BEATRIX_NODE points at ${explicit}, which does not exist.` };
+    return { available: true, path: explicit, version: "", detail: `Node at ${explicit} (BEATRIX_NODE)` };
+  }
+  if (packaged) {
+    // A single executable IS a Node: it runs the worker bundled inside it when
+    // started with BEATRIX_ENGINE_ROLE=js (the retired executable build; kept for any old binary).
+    return { available: true, path: execPath, version: versions.node, detail: `Node ${versions.node} (inside this executable)`, selfHosted: true };
+  }
+  const major = Number(String(versions.node || "").split(".")[0]);
+  if (!(major >= JS_MIN_NODE)) return { available: false, path: "", version: versions.node || "", detail: `JavaScript chunks need Node ${JS_MIN_NODE} or newer; this host runs on ${versions.node}.` };
+  return { available: true, path: execPath, version: versions.node, detail: `Node ${versions.node}` };
+}
+
+/** One `engines/js/worker.mjs` process. */
+export class JsEngine extends StdioEngine {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.workerPath  engines/js/worker.mjs
+   * @param {string} opts.node        the Node detectNode chose
+   * @param {Record<string,string>} [opts.env]
+   * @param {string} [opts.cwd]
+   */
+  constructor({ workerPath, node, env = {}, cwd, platform = process.platform, selfHosted = false } = {}) {
+    super({ language: "js", workerPath, env, cwd, platform });
+    this.selfHosted = selfHosted;
+    if (!selfHosted && (!workerPath || !fs.existsSync(workerPath))) throw new Error(`JsEngine: no worker at ${workerPath}`);
+    if (!node) throw new Error("JsEngine: no Node found (set BEATRIX_NODE)");
+    this.node = node;
+    if (platform === "win32") this.interruptTool = findInterruptTool({ env: process.env });
+  }
+
+  get label() { return "JavaScript"; }
+  get canInput() { return false; }
+  get canDebug() { return false; }
+
+  spawnPlan() {
+    // The worker's dynamic import() goes through vm's main-context loader,
+    // which Node still labels experimental and announces on stderr — into the
+    // first chunk that imports anything. The label is Node's; the output is not
+    // the user's, so it is not printed.
+    if (this.selfHosted) return { bin: this.node, args: [], env: { CARMAR_WORKER_MODE: "batch", BEATRIX_ENGINE_ROLE: "js" } };
+    return { bin: this.node, args: ["--disable-warning=ExperimentalWarning", this.workerPath], env: { CARMAR_WORKER_MODE: "batch" } };
+  }
+
+  /**
+   * ONE SIGINT, to the worker's process group — never the pair the base class sends.
+   *
+   * The second signal of that pair exists for R's system() (engine-stdio.mjs). A Node worker does
+   * not need it: vm's `breakOnSigint` watchdog catches the group signal even while a blocking call
+   * such as execSync runs, and the child that call started gets the same group signal. And the
+   * second signal is harmful: it lands while `breakOnSigint` is tearing its watchdog down, when no
+   * handler is installed, and the default action ends the process — the session's variables with
+   * it. Measured 2026-09-16 with the pair sent exactly as the base class sends it: Linux (Node
+   * 22.23.2) 19/20 workers died; macOS (Node 25.5.0) 1/20. test/js-interrupt.test.mjs pins it.
+   */
+  interrupt(stillWanted = () => true) {
+    if (this.platform === "win32") return super.interrupt(stillWanted);
+    if (!this.alive || !this.pid) return false;
+    try { this.killImpl(-this.pid, "SIGINT"); } catch {
+      try { this.killImpl(this.pid, "SIGINT"); } catch { return false; }   // not a group leader after all
+    }
+    return true;
+  }
+
+  /** There is no prompt behind this worker: a console line is refused, not typed. */
+  console() { throw new Error("The JavaScript engine has no console prompt."); }
+}