beatrina 0.8.6

package/host/plugin-store.mjs

@@ -0,0 +1,838 @@
+// plugin-store.mjs — the plugin store, ported from spike/plugins.R.
+//
+// A PLUGIN IS DATA A KNOWN CONSUMER READS. IT IS NEVER CODE. That sentence is
+// the whole trust model and it is why the table of kinds is CLOSED: `csl` is
+// XML pandoc parses, `theme` is a palette the stylesheet applies, `latex` is a
+// preamble SOMEONE ELSE'S TeX engine runs (the one row with a deny-list, and it
+// says so rather than inheriting the other two rows' sentence by proximity).
+// "js" is not a row and cannot become one from a manifest.
+//
+// Three layers, searched in order, exactly as .libPaths() is:
+//
+//   user     R_user_dir("carmar","data")/plugins/<kind>/<id>/   the ONLY layer written
+//   system   $CARMAR_PLUGIN_DIR/<kind>/<id>/                     an administrator's, read-only
+//   shipped  <kernel>/plugins/<kind>/<id>/                       the bundle's, read-only
+//
+// The first OK copy of an id wins. A BROKEN copy never wins: integrity is
+// recomputed on EVERY listing, and a payload that no longer matches its
+// manifest is listed with the reason and used by nothing.
+//
+// Everything here is a function of its arguments and the file system — no
+// socket, no frame — so host/planes/plugins.mjs owns who may ask and this file
+// owns what the answer is. test/host-plugins.test.mjs is spike/test-plugins.R's
+// twin, case for case.
+//
+// Divergence from the R, stated rather than hidden: `csl_info()` and
+// `csl_looks_like_style()` live in spike/cite.R there and here, because the
+// kinds table needs them at module scope and JavaScript has no `source()`.
+// host/planes/cite.mjs re-exports them, so cite still owns "what a CSL file is"
+// at the seam a reader looks for it.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { appId } from "./user-dirs.mjs";
+
+export const PLUGIN_ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+export const PLUGIN_FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export const PLUGIN_MANIFEST = "plugin.json";
+export const PLUGIN_MANIFEST_MAX_BYTES = 65536;
+export const PLUGIN_FETCH_TIMEOUT_S = 20;
+export const PLUGIN_POLICY_DEFAULT_FILE = "/etc/carmar/plugin-policy.json";
+export const PLUGIN_SYSTEM_DEFAULT_DIR = "/etc/carmar/plugins";
+
+/** A CROSS-LANGUAGE CONTRACT with `EDITOR_TOKENS` in lib/editor-themes.js. */
+export const THEME_TOKENS = Object.freeze([
+  "--ed-bg", "--ed-fg", "--ed-gutter", "--ed-gutter-bg", "--ed-line", "--ed-sel",
+  "--ed-caret", "--ed-border", "--ed-bar", "--ed-brmatch",
+  "--rtok-com", "--rtok-doc", "--rtok-section", "--rtok-tag", "--rtok-str", "--rtok-num",
+  "--rtok-kw", "--rtok-const", "--rtok-fn", "--rtok-ns", "--rtok-arg", "--rtok-op",
+  "--rtok-infix", "--rtok-paren"]);
+export const THEME_WASH_TOKENS = Object.freeze(["--ed-line", "--ed-sel", "--ed-brmatch"]);
+
+/** The SECOND cross-language contract, with lib/latex-templates.js. */
+export const LATEX_TEMPLATE_KEYS = Object.freeze(["label", "documentclass", "classOptions",
+  "citeStyle", "citePackage", "topLevel", "preamble", "description", "version"]);
+export const LATEX_CITE_STYLES = Object.freeze(["natbib", "biblatex", "plain"]);
+export const LATEX_TOP_LEVELS = Object.freeze(["section", "chapter"]);
+const LATEX_CLASS_RE = /^[A-Za-z][A-Za-z0-9._-]{0,39}$/;
+const LATEX_OPTION_RE = /^[A-Za-z0-9][A-Za-z0-9 =.,%*-]{0,79}$/;
+const LATEX_CITE_PACKAGE_RE = /^\\usepackage(\[[^\]]{0,120}\])?\{[A-Za-z0-9,._-]{1,60}\}$/;
+export const LATEX_PREAMBLE_MAX_LINES = 200;
+export const LATEX_PREAMBLE_MAX_CHARS = 400;
+
+// WHY THIS ROW HAS A DENY-LIST AND THE OTHER TWO DO NOT: a preamble is code
+// the AUTHOR'S TeX engine runs. The boundary is `(?![A-Za-z])`, never `\b` — a
+// TeX control word ends at the first NON-letter, so `\bopenout\b` misses
+// `\openout1`, which is how anyone writes it. It must cut both ways:
+// `\inputencoding` and `\includegraphics` are ordinary and must pass.
+export const LATEX_FORBIDDEN = Object.freeze([
+  { re: /\\write[\s]*18/, why: "runs a shell command" },
+  { re: /\\(ShellEscape|directlua|luadirect|pdfprimitive|javascript)(?![A-Za-z])/, why: "runs code outside TeX" },
+  { re: /\\(openout|openin|read|write)[a-z]*(?![A-Za-z])/, why: "reads or writes files" },
+  { re: /\\(input|include|includeonly|subfile|subimport|import)(?![A-Za-z])/, why: "pulls in another file" },
+  { re: /shellesc|\bshell-?escape/, why: "asks for shell escape" },
+  { re: /\\documentclass|\\begin[\s]*\{document\}/, why: "is the document's, not the preamble's" },
+]);
+
+/** The first forbidden construct in any of `texts`, as a sentence, or "". */
+export function latexForbiddenReason(texts) {
+  const all = (Array.isArray(texts) ? texts : [texts]).filter((t) => typeof t === "string");
+  for (const rule of LATEX_FORBIDDEN) {
+    if (all.some((t) => rule.re.test(t))) return rule.why;
+  }
+  return "";
+}
+
+const isScalarString = (x) => typeof x === "string";
+const readHead = (file, lines) => {
+  let text;
+  try { text = fs.readFileSync(file, "utf8"); } catch { return ""; }
+  return text.split("\n").slice(0, lines).join("\n");
+};
+
+export const CSL_NS = "http://purl.org/net/xbiblio/csl";
+/** The repository's own name alphabet (measured over all 10,861 entries). */
+export const CSL_NAME_RE = /^[a-z0-9][a-z0-9.-]{0,118}$/;
+
+/**
+ * A style's own <title>, and the parent a DEPENDENT style names.
+ *
+ * Read as text from the head of the file — a full XML parse of Chicago
+ * (164 KB) for two lines is not worth a dependency.
+ */
+export function cslInfo(file) {
+  const head = readHead(file, 60);
+  let title = "";
+  const m = head.match(/<title>[^<]+<\/title>/);
+  if (m) title = m[0].replace(/^<title>/, "").replace(/<\/title>$/, "").trim();
+  // The five XML entities, decoded, in the R's order: a title is shown as text,
+  // and "Taylor &amp; Francis" is not a name.
+  for (const [from, to] of [["&lt;", "<"], ["&gt;", ">"], ["&quot;", '"'], ["&apos;", "'"], ["&amp;", "&"]]) {
+    title = title.split(from).join(to);
+  }
+  let parentName = "";
+  const link = head.match(/<link[^>]*rel="independent-parent"[^>]*\/?>/);
+  if (link) {
+    const href = link[0].match(/href="[^"]+"/);
+    if (href) parentName = path.basename(href[0].replace(/^href="/, "").replace(/"$/, ""));
+  }
+  parentName = parentName.replace(/\.csl$/, "");
+  return { title, parent: parentName ? `${parentName}.csl` : "" };
+}
+
+/** Is this file a CSL style? The root element, the namespace, a title. */
+export function cslLooksLikeStyle(file) {
+  const head = readHead(file, 40);
+  return /<style[ >]/.test(head) && head.includes(CSL_NS)
+    && !/<!DOCTYPE|<!ENTITY/.test(head) && Boolean(cslInfo(file).title);
+}
+
+/** The registry a `csl` install fetches by name from. Env-driven, as in R. */
+export const cslIndexUrl = (env) => env("CARMAR_CSL_INDEX_URL", "https://www.zotero.org/styles-files/styles.json");
+export const cslStyleBase = (env) => env("CARMAR_CSL_STYLE_BASE", "https://www.zotero.org/styles/");
+
+/* ── the kinds table ──────────────────────────────────────────────────────
+ *
+ * Closed, by design. A row is: what the payload is, who reads it, how big it
+ * may be, how it is checked, and — for a kind with a public registry — where it
+ * is fetched by name. `validate(dir, file)` returns {ok, error, name, version,
+ * requires}; `requires` names OTHER plugins of the same kind this one renders
+ * through (a dependent CSL style's parent), which an install completes.
+ */
+export function pluginKinds(env) {
+  return {
+    csl: {
+      label: "Citation styles",
+      consumer: "pandoc renders citations and the reference list with it; it is placed beside a saved document.",
+      extension: "csl",
+      max_bytes: 2000000,
+      license: "CC BY-SA 3.0",
+      registry: () => ({ base: cslStyleBase(env), index: cslIndexUrl(env) }),
+      validate(dir, file) {
+        const p = path.join(dir, file);
+        if (!cslLooksLikeStyle(p)) return { ok: false, error: "did not arrive as a CSL style" };
+        const info = cslInfo(p);
+        const parent = info.parent.replace(/\.csl$/, "");
+        if (parent && !PLUGIN_ID_RE.test(parent)) {
+          return { ok: false, error: "names a parent style this kernel will not fetch" };
+        }
+        const head = readHead(p, 80);
+        const updated = head.match(/<updated>[^<]+<\/updated>/);
+        const version = updated ? updated[0].replace(/<\/?updated>/g, "").slice(0, 10) : "";
+        return { ok: true, name: info.title, version, requires: parent ? [parent] : [] };
+      },
+    },
+    theme: {
+      label: "Editor themes",
+      consumer: "the editor: chunks, console, script editor and R code in prose.",
+      extension: "json",
+      max_bytes: 65536,
+      license: "",
+      registry: null,
+      validate(dir, file) {
+        let doc;
+        try { doc = JSON.parse(fs.readFileSync(path.join(dir, file), "utf8")); }
+        catch (e) { return { ok: false, error: `is not valid JSON: ${e.message}` }; }
+        const label = doc && doc.label;
+        if (!isScalarString(label) || !label.trim() || label.length > 60) {
+          return { ok: false, error: "needs a `label` of up to 60 characters" };
+        }
+        if (typeof doc.dark !== "boolean") return { ok: false, error: "needs `dark`: true or false" };
+        const vars = doc.vars;
+        if (!vars || typeof vars !== "object" || Array.isArray(vars) || !Object.keys(vars).length) {
+          return { ok: false, error: "needs a `vars` object of editor tokens" };
+        }
+        const unknown = Object.keys(vars).filter((k) => !THEME_TOKENS.includes(k));
+        if (unknown.length) {
+          return { ok: false, error: `sets tokens the editor does not have: ${unknown.slice(0, 3).join(", ")}` };
+        }
+        if (!["--ed-bg", "--ed-fg"].every((k) => k in vars)) {
+          return { ok: false, error: "must set at least --ed-bg and --ed-fg" };
+        }
+        const bad = Object.keys(vars).find((k) => {
+          const v = vars[k];
+          if (!isScalarString(v)) return true;
+          const hex = /^#[0-9a-fA-F]{6}$/.test(v);
+          const wash = THEME_WASH_TOKENS.includes(k)
+            && /^rgba\(\s*[0-9]{1,3}\s*,\s*[0-9]{1,3}\s*,\s*[0-9]{1,3}\s*,\s*(0|1|0?\.[0-9]{1,4})\s*\)$/.test(v);
+          return !(hex || wash);
+        });
+        if (bad) return { ok: false, error: `colour for ${bad} must be #rrggbb (a wash may be rgba())` };
+        const version = isScalarString(doc.version) ? doc.version.slice(0, 40) : "";
+        return { ok: true, name: label.trim(), version, requires: [] };
+      },
+    },
+    latex: {
+      label: "LaTeX templates",
+      consumer: "the LaTeX export: it sets the document class, its options and the preamble of the .tex that is written.",
+      extension: "json",
+      max_bytes: 65536,
+      license: "",
+      registry: null,
+      validate(dir, file) {
+        let doc;
+        try { doc = JSON.parse(fs.readFileSync(path.join(dir, file), "utf8")); }
+        catch (e) { return { ok: false, error: `is not valid JSON: ${e.message}` }; }
+        if (!doc || typeof doc !== "object" || Array.isArray(doc) || !Object.keys(doc).length) {
+          return { ok: false, error: "is not a template object" };
+        }
+        const unknown = Object.keys(doc).filter((k) => !LATEX_TEMPLATE_KEYS.includes(k));
+        if (unknown.length) {
+          return { ok: false, error: `sets keys a template does not have: ${unknown.slice(0, 3).join(", ")}` };
+        }
+        const one = (v, max) => isScalarString(v) && v.trim() !== "" && v.length <= max;
+        // null → "not given"; a string → one; an array of strings → itself;
+        // anything else → null, which the caller reads as "not a list of strings".
+        const strings = (v) => {
+          if (v == null) return [];
+          if (typeof v === "string") return [v];
+          if (!Array.isArray(v)) return null;
+          if (!v.length) return [];
+          if (!v.every(isScalarString)) return null;
+          return v;
+        };
+
+        if (!one(doc.label, 60)) return { ok: false, error: "needs a `label` of up to 60 characters" };
+        if (!one(doc.documentclass, 40) || !LATEX_CLASS_RE.test(doc.documentclass)) {
+          return { ok: false, error: "needs a `documentclass` that is a plain class name (letters, digits, . _ -)" };
+        }
+        const opts = strings(doc.classOptions);
+        if (opts === null) return { ok: false, error: "`classOptions` must be a list of strings" };
+        if (opts.length > 12) return { ok: false, error: "names more class options than a class takes" };
+        const badOpt = opts.find((o) => !LATEX_OPTION_RE.test(o));
+        if (badOpt) return { ok: false, error: `has a class option that is not a plain option: ${badOpt}` };
+
+        const pre = strings(doc.preamble);
+        if (pre === null) return { ok: false, error: "`preamble` must be a list of lines" };
+        if (pre.length > LATEX_PREAMBLE_MAX_LINES) {
+          return { ok: false, error: `has a preamble longer than ${LATEX_PREAMBLE_MAX_LINES} lines` };
+        }
+        if (pre.some((l) => l.length > LATEX_PREAMBLE_MAX_CHARS)) {
+          return { ok: false, error: `has a preamble line longer than ${LATEX_PREAMBLE_MAX_CHARS} characters` };
+        }
+        const why = latexForbiddenReason([doc.documentclass, ...opts, ...pre, String(doc.citePackage ?? "")]);
+        if (why) return { ok: false, error: `contains LaTeX that ${why}, which a template may not do` };
+
+        if (doc.citeStyle != null && !(one(doc.citeStyle, 20) && LATEX_CITE_STYLES.includes(doc.citeStyle))) {
+          return { ok: false, error: `\`citeStyle\` must be one of ${LATEX_CITE_STYLES.join(", ")}` };
+        }
+        if (doc.citePackage != null && !(one(doc.citePackage, 200) && LATEX_CITE_PACKAGE_RE.test(doc.citePackage))) {
+          return { ok: false, error: "`citePackage` must be a single \\usepackage line" };
+        }
+        if (doc.topLevel != null && !(one(doc.topLevel, 20) && LATEX_TOP_LEVELS.includes(doc.topLevel))) {
+          return { ok: false, error: `\`topLevel\` must be one of ${LATEX_TOP_LEVELS.join(", ")}` };
+        }
+        if (doc.description != null && !one(doc.description, 200)) {
+          return { ok: false, error: "`description` must be a sentence of up to 200 characters" };
+        }
+        const version = isScalarString(doc.version) ? doc.version.slice(0, 40) : "";
+        return { ok: true, name: doc.label.trim(), version, requires: [] };
+      },
+    },
+  };
+}
+
+export const pluginKindOk = (kinds, kind) => isScalarString(kind) && Object.hasOwn(kinds, kind);
+export const pluginIdOk = (id) => isScalarString(id) && PLUGIN_ID_RE.test(id);
+export const pluginFileOk = (file) => isScalarString(file) && PLUGIN_FILE_RE.test(file) && !file.includes("..");
+
+/** Split a policy value the way spike/settings.R's policy_split does. */
+export const policySplit = (value) => String(value ?? "").split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
+
+/** The host of a URL, lower-cased, or "" when it has none. */
+export function urlHost(url) {
+  const m = String(url ?? "").match(/^https?:\/\/[^/?#]+/);
+  if (!m) return "";
+  return m[0].replace(/^https?:\/\//, "").replace(/:[0-9]+$/, "").toLowerCase();
+}
+
+/**
+ * `tools::R_user_dir(pkg, which)`, in JavaScript.
+ *
+ * The whole plugin store, the CSL index cache and every test that relocates
+ * them turn on this function agreeing with R's, so it is a transcription of
+ * R 4.5's source rather than a guess: the env var, then XDG, then the
+ * platform's own place, then `R/<package>` under it.
+ */
+export function rUserDir(pkg, which, env) {
+  const home = os.homedir();
+  const win = process.platform === "win32";
+  const mac = process.platform === "darwin";
+  let p = "";
+  if (which === "data") {
+    p = env("R_USER_DATA_DIR") || env("XDG_DATA_HOME")
+      || (win ? path.join(env("APPDATA"), "R", "data")
+        : mac ? path.join(home, "Library", "Application Support", "org.R-project.R")
+          : path.join(home, ".local", "share"));
+  } else if (which === "cache") {
+    p = env("R_USER_CACHE_DIR") || env("XDG_CACHE_HOME")
+      || (win ? path.join(env("LOCALAPPDATA"), "R", "cache")
+        : mac ? path.join(home, "Library", "Caches", "org.R-project.R")
+          : path.join(home, ".cache"));
+  } else {
+    p = env("R_USER_CONFIG_DIR") || env("XDG_CONFIG_HOME")
+      || (win ? path.join(env("APPDATA"), "R", "config")
+        : mac ? path.join(home, "Library", "Preferences", "org.R-project.R")
+          : path.join(home, ".config"));
+  }
+  return path.join(p, "R", pkg);
+}
+
+/* ── the administrator's policy ──────────────────────────────────────────── */
+
+/**
+ * Read the administrator's plugin policy.
+ *
+ * Three states, as in ai-policy.R: names nothing → everything; names something
+ * valid → exactly that; names ONLY junk → an error, because an empty allow-list
+ * that fails open is the bug the AI policy suite caught.
+ *
+ * @returns {{set:boolean, source:string, install:string, sources:string[],
+ *   network:boolean, kinds:string[], unknown:string[], note:string,
+ *   system_dir:string, errors:string[]}}
+ */
+export function carmarPluginPolicy(env, {
+  defaultFile = PLUGIN_POLICY_DEFAULT_FILE, defaultDir = PLUGIN_SYSTEM_DEFAULT_DIR,
+} = {}) {
+  const kinds_table = pluginKinds(env);
+  const allKinds = Object.keys(kinds_table);
+  const errors = [];
+  let source = "";
+  let install = "";
+  let sourcesRaw = null;
+  let kindsRaw = null;
+  let note = "";
+  let systemDir = env("CARMAR_PLUGIN_DIR", "").trim();
+  if (!systemDir && defaultDir && dirExists(defaultDir)) systemDir = defaultDir;
+
+  let file = env("CARMAR_PLUGIN_POLICY", "").trim();
+  if (!file && defaultFile && fileExists(defaultFile)) file = defaultFile;
+  if (file) {
+    source = file;
+    if (!fileExists(file)) {
+      errors.push(`CARMAR_PLUGIN_POLICY names a file that does not exist: ${file}`);
+    } else {
+      let doc = null;
+      try { doc = JSON.parse(fs.readFileSync(file, "utf8")); }
+      catch (e) { errors.push(`CARMAR_PLUGIN_POLICY is not valid JSON: ${e.message}`); }
+      if (doc && typeof doc === "object") {
+        install = String(doc.install ?? "").trim();
+        if (doc.sources != null) sourcesRaw = [].concat(doc.sources).map(String);
+        if (doc.kinds != null) kindsRaw = [].concat(doc.kinds).map(String);
+        note = String(doc.note ?? "").trim();
+        const d = String(doc.system_dir ?? "").trim();
+        if (d) systemDir = d;
+      }
+    }
+  } else {
+    if (env("CARMAR_PLUGIN_INSTALL", "")) { source = "env"; install = env("CARMAR_PLUGIN_INSTALL", "").trim(); }
+    if (env("CARMAR_PLUGIN_SOURCES", "")) { source = "env"; sourcesRaw = policySplit(env("CARMAR_PLUGIN_SOURCES", "")); }
+    if (env("CARMAR_PLUGIN_KINDS", "")) { source = "env"; kindsRaw = policySplit(env("CARMAR_PLUGIN_KINDS", "")); }
+  }
+
+  if (!install) install = "user";
+  if (!["user", "none"].includes(install)) {
+    errors.push(`The plugin policy's \`install\` must be "user" or "none", not "${install}".`);
+    install = "user";
+  }
+
+  // Kinds: three states.
+  const kindsNamed = [...new Set((kindsRaw || []).map((k) => k.trim()).filter(Boolean))];
+  const unknown = kindsNamed.filter((k) => !allKinds.includes(k));
+  let kinds = kindsNamed.length ? kindsNamed.filter((k) => allKinds.includes(k)) : allKinds.slice();
+  if (kindsNamed.length && !kinds.length) {
+    errors.push(`The plugin policy permits no plugin kind at all (unrecognised: ${unknown.join(", ")}). `
+      + `Name at least one of ${allKinds.join(", ")}, or remove the policy.`);
+  }
+
+  // Sources: absent → the kinds' own registries; "none" → no network at all;
+  // else an exact host list. https is required of every fetch regardless.
+  let network = true;
+  let sources = [];
+  if (sourcesRaw == null) {
+    sources = pluginDefaultHosts(env);
+  } else {
+    const named = [...new Set(sourcesRaw.map((s) => s.trim().toLowerCase()).filter(Boolean))];
+    if ((named.length === 1 && named[0] === "none") || !named.length) {
+      network = false;
+    } else {
+      const bad = named.filter((h) => !/^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/.test(h));
+      if (bad.length) errors.push(`The plugin policy's \`sources\` must be bare host names: ${bad.join(", ")}`);
+      sources = named.filter((h) => !bad.includes(h));
+      if (!sources.length) network = false;
+    }
+  }
+
+  let set = Boolean(source) && !errors.length;
+  if (errors.length) { install = "user"; kinds = allKinds.slice(); sources = pluginDefaultHosts(env); network = true; set = false; }
+  // eslint-disable-next-line no-control-regex
+  note = note.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 400).trim();
+
+  return { set, source, install, sources, network, kinds, unknown, note, system_dir: systemDir, errors };
+}
+
+/**
+ * The hosts an install may fetch from when no policy names any: the registries
+ * of the kinds themselves. Computed, not written down, so a test pointing the
+ * CSL registry at 127.0.0.1 permits 127.0.0.1 without a second override.
+ */
+export function pluginDefaultHosts(env) {
+  const table = pluginKinds(env);
+  const hosts = [];
+  for (const k of Object.values(table)) {
+    if (!k.registry) continue;
+    const r = k.registry();
+    hosts.push(urlHost(r.base), urlHost(r.index));
+  }
+  return [...new Set(hosts.filter(Boolean))];
+}
+
+/** The sentence shown when the policy refuses something. */
+export function pluginPolicyReason(policy, what = "install") {
+  const base = {
+    install: "This CarmaR is configured so that plugins are not installed by users; the set is fixed by the deployment.",
+    network: "This CarmaR is configured to fetch no plugins from the network; a plugin arrives as a file.",
+    host: `This CarmaR is configured to fetch plugins only from: ${policy.sources.join(", ")}.`,
+    kind: "This CarmaR is configured without that plugin kind.",
+  }[what] || "This CarmaR's plugin policy refuses that.";
+  return policy.note ? `${base} ${policy.note}` : base;
+}
+
+/* ── layers and paths ────────────────────────────────────────────────────── */
+
+const dirExists = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+const fileExists = (p) => { try { return fs.statSync(p).isFile(); } catch { return false; } };
+
+export const pluginUserDir = (env) => path.join(rUserDir(appId(env), "data", env), "plugins");
+
+/**
+ * The layers, in precedence order. The user layer is ABSENT under
+ * `install: none` — not read-only, absent, because "the set is fixed by the
+ * deployment" and a person's earlier imports quietly outranking it would make
+ * that sentence false.
+ */
+export function pluginLayers(here, policy, env) {
+  const layers = [];
+  if (policy.install === "user") layers.push({ name: "user", dir: pluginUserDir(env), writable: true });
+  if (policy.system_dir) layers.push({ name: "system", dir: policy.system_dir, writable: false });
+  layers.push({ name: "shipped", dir: path.join(here, "plugins"), writable: false });
+  return layers;
+}
+
+/**
+ * A path INSIDE `base`, or null. The regexes on id and file already forbid a
+ * separator and `..`; this is the SECOND lock — resolved paths, compared — so a
+ * symlink or an encoding trick a regex did not foresee still cannot reach out
+ * of the layer.
+ */
+export function pluginContained(base, ...parts) {
+  if (!dirExists(base)) return null;
+  let root;
+  try { root = fs.realpathSync(base); } catch { return null; }
+  if (!parts.length) return null;
+  if (!parts.every((x) => isScalarString(x) && !/[/\\]/.test(x) && !/^\.\.?$/.test(x))) return null;
+  let p = path.join(root, parts.join("/"));
+  // An existing target is resolved through any symlink before the check; one
+  // that does not exist yet is a plain child of the resolved root by
+  // construction (no separator, no dot segment — refused above).
+  if (fs.existsSync(p)) { try { p = fs.realpathSync(p); } catch { return null; } }
+  if (p !== root && !p.startsWith(`${root}${path.sep}`)) return null;
+  return p;
+}
+
+export function pluginDigest(file) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(file));
+  return { algo: "sha256", value: hash.digest("hex") };
+}
+
+/* ── the manifest ────────────────────────────────────────────────────────── */
+
+/** Build the manifest for a validated payload sitting in `dir`. */
+export function pluginManifestFor(dir, kind, id, files, info, source, license = "") {
+  const list = [].concat(files);
+  const sha256 = {};
+  for (const f of list) sha256[f] = pluginDigest(path.join(dir, f)).value;
+  return {
+    id, kind,
+    name: String(info.name ?? id).slice(0, 200),
+    version: info.version ?? "",
+    file: list[0],
+    files: list,
+    requires: [].concat(info.requires ?? []).map(String),
+    license: license ?? "",
+    source,
+    digest: "sha256",
+    sha256,
+    bytes: list.reduce((n, f) => n + fs.statSync(path.join(dir, f)).size, 0),
+    installed: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+  };
+}
+
+export function pluginManifestWrite(dir, manifest) {
+  fs.writeFileSync(path.join(dir, PLUGIN_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+/**
+ * Read and CHECK one plugin folder.
+ *
+ * Returns a row with `status` "ok" or "broken" and a `reason`; a folder is
+ * never trusted for what its manifest claims.
+ */
+export function pluginInspect(layer, kind, id, kindsTable) {
+  const dir = pluginContained(path.join(layer.dir, kind), id);
+  const row = {
+    kind, id, name: id, version: "", layer: layer.name, dir: dir || "",
+    file: "", files: [], requires: [], source: "", license: "",
+    installed: "", bytes: 0, status: "broken", reason: "", verified: false,
+  };
+  if (!dir || !dirExists(dir)) { row.reason = "the folder is outside its layer"; return row; }
+  const mpath = path.join(dir, PLUGIN_MANIFEST);
+  if (!fileExists(mpath)) { row.reason = "no plugin.json"; return row; }
+  if (fs.statSync(mpath).size > PLUGIN_MANIFEST_MAX_BYTES) { row.reason = "plugin.json is too large to be one"; return row; }
+  let m;
+  try { m = JSON.parse(fs.readFileSync(mpath, "utf8")); }
+  catch (e) { row.reason = `plugin.json is not valid JSON: ${e.message}`; return row; }
+  if (m.id !== id) { row.reason = "plugin.json names a different id than its folder"; return row; }
+  if (m.kind !== kind) { row.reason = "plugin.json names a different kind than its folder"; return row; }
+  const files = [].concat(m.files ?? m.file ?? []).map((f) => (typeof f === "string" ? f : ""));
+  if (!files.length || !files.every(pluginFileOk)) { row.reason = "plugin.json lists no valid file"; return row; }
+  const spec = kindsTable[kind];
+  if (!files[0].endsWith(`.${spec.extension}`)) { row.reason = `the payload is not a .${spec.extension} file`; return row; }
+  row.name = String(m.name ?? id).slice(0, 200);
+  row.version = String(m.version ?? "");
+  row.file = files[0];
+  row.files = files;
+  row.requires = [].concat(m.requires ?? []).map(String);
+  row.source = String(m.source ?? "");
+  row.license = String(m.license ?? "");
+  row.installed = String(m.installed ?? "");
+  for (const f of files) {
+    const p = pluginContained(dir, f);
+    if (!p || !fs.existsSync(p)) { row.reason = `${f} is missing`; return row; }
+    const size = fs.statSync(p).size;
+    if (size > spec.max_bytes) { row.reason = `${f} is larger than this kind allows`; return row; }
+    row.bytes += size;
+  }
+  // Integrity: the recorded digest, recomputed.
+  const algo = String(m.digest ?? (m.sha256 ? "sha256" : m.md5 ? "md5" : ""));
+  const recorded = algo === "sha256" ? m.sha256 : algo === "md5" ? m.md5 : null;
+  const can = algo === "sha256";       // node has no md5 manifest to answer for
+  if (algo && recorded && can) {
+    for (const f of files) {
+      const want = String(recorded[f] ?? "");
+      const have = pluginDigest(path.join(dir, f)).value;
+      if (!want || want.toLowerCase() !== have.toLowerCase()) {
+        row.reason = `${f} has changed since it was installed (${algo} differs)`;
+        return row;
+      }
+    }
+    row.verified = true;
+  }
+  row.status = "ok";
+  return row;
+}
+
+/**
+ * Every plugin in every layer, checked, one row each.
+ *
+ * `active` marks the copy consumers use: the FIRST ok copy of an id in layer
+ * order. Kinds the policy does not permit are not listed at all.
+ */
+export function pluginRows(here, policy, env, kind = null) {
+  const table = pluginKinds(env);
+  const kinds = kind == null ? policy.kinds : [].concat(kind).filter((k) => policy.kinds.includes(k));
+  const rows = [];
+  for (const layer of pluginLayers(here, policy, env)) {
+    for (const k of kinds) {
+      const kdir = path.join(layer.dir, k);
+      if (!dirExists(kdir)) continue;
+      let ids;
+      try { ids = fs.readdirSync(kdir).sort(); } catch { continue; }
+      ids = ids.filter((id) => !id.startsWith(".") && dirExists(path.join(kdir, id)) && PLUGIN_ID_RE.test(id));
+      for (const id of ids) rows.push(pluginInspect(layer, k, id, table));
+    }
+  }
+  const claimed = new Set();
+  for (const r of rows) {
+    const key = `${r.kind} ${r.id}`;
+    r.active = r.status === "ok" && !claimed.has(key);
+    if (r.active) claimed.add(key);
+  }
+  return rows;
+}
+
+/** The active copy of one plugin, or null. */
+export function pluginActive(here, policy, env, kind, id) {
+  const table = pluginKinds(env);
+  if (!pluginKindOk(table, kind) || !pluginIdOk(id)) return null;
+  return pluginRows(here, policy, env, kind).find((r) => r.id === id && r.active) || null;
+}
+
+/** The text of one manifest-listed file of an active plugin. */
+export function pluginRead(here, policy, env, kind, id, file = null) {
+  const row = pluginActive(here, policy, env, kind, id);
+  if (!row) return { ok: false, error: "No such plugin." };
+  const want = file ?? row.file;
+  if (!pluginFileOk(want) || !row.files.includes(want)) return { ok: false, error: "That file is not part of the plugin." };
+  const p = pluginContained(row.dir, want);
+  if (!p) return { ok: false, error: "That file is not inside the plugin." };
+  let text;
+  try { text = fs.readFileSync(p, "utf8").replace(/\n$/, ""); } catch { return { ok: false, error: "The file could not be read." }; }
+  return { ok: true, kind, id, file: want, name: row.name, text };
+}
+
+/* ── fetching ────────────────────────────────────────────────────────────── */
+
+/**
+ * Fetch one URL into `dest`, bounded, from a permitted host only.
+ * https everywhere but loopback (the test registry); the host must be on the
+ * policy's list. Resolves to "" or the reason.
+ */
+export async function pluginFetch(policy, url, dest, maxBytes) {
+  if (policy.network !== true) return pluginPolicyReason(policy, "network");
+  if (!isScalarString(url)) return "not a URL";
+  const host = urlHost(url);
+  const loopback = ["127.0.0.1", "localhost"].includes(host);
+  if (!url.startsWith("https://") && !(loopback && url.startsWith("http://"))) return "only https is fetched";
+  if (!host || !policy.sources.includes(host)) return pluginPolicyReason(policy, "host");
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), PLUGIN_FETCH_TIMEOUT_S * 1000);
+  try {
+    const res = await fetch(url, { signal: controller.signal, redirect: "follow" });
+    if (!res.ok) return `cannot open URL '${url}': HTTP status was ${res.status}`;
+    const body = Buffer.from(await res.arrayBuffer());
+    if (body.length > maxBytes) {
+      return `the file is larger than this kind allows (${Math.trunc(maxBytes / 1000)} KB)`;
+    }
+    fs.writeFileSync(dest, body);
+    return "";
+  } catch (e) {
+    try { fs.unlinkSync(dest); } catch { /* never written */ }
+    return e.name === "AbortError" ? "the download timed out" : e.message;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/* ── install and remove ──────────────────────────────────────────────────── */
+
+function pluginStageDir(userDir) {
+  const staging = path.join(userDir, ".staging");
+  fs.mkdirSync(staging, { recursive: true, mode: 0o700 });
+  const d = fs.mkdtempSync(path.join(staging, "plugin-"));
+  fs.chmodSync(d, 0o700);
+  return d;
+}
+
+/**
+ * Install one plugin into the user layer.
+ *
+ * @param {object} from one of {registry} · {url} · {text, filename}
+ * @param {boolean} complete install the plugins this one `requires` from the
+ *   registry (a dependent CSL style's parent). One level: a parent is
+ *   independent.
+ */
+export async function pluginInstall(here, policy, env, kind, from, complete = true) {
+  const table = pluginKinds(env);
+  if (!pluginKindOk(table, kind)) return { ok: false, error: "That is not a plugin kind this kernel has." };
+  if (!policy.kinds.includes(kind)) return { ok: false, error: pluginPolicyReason(policy, "kind") };
+  if (policy.install !== "user") return { ok: false, error: pluginPolicyReason(policy, "install") };
+  if (!from || typeof from !== "object" || Array.isArray(from)) return { ok: false, error: "`from` must say where the plugin comes from." };
+  const spec = table[kind];
+  const ext = `.${spec.extension}`;
+
+  let id;
+  let source;
+  let door;
+  if (isScalarString(from.registry)) {
+    if (!spec.registry) return { ok: false, error: "That plugin kind has no registry to fetch by name from." };
+    id = from.registry;
+    if (!pluginIdOk(id)) return { ok: false, error: "That is not a name from the registry." };
+    source = `${spec.registry().base}${id}`;
+    door = "registry";
+  } else if (isScalarString(from.url)) {
+    source = from.url;
+    id = path.basename(source.replace(/[?#].*$/, "")).replace(new RegExp(`\\${ext}$`), "");
+    if (!pluginIdOk(id)) return { ok: false, error: "The URL does not end in a name a plugin can have (lower-case letters, digits, . _ -)." };
+    door = "url";
+  } else if (isScalarString(from.text) && isScalarString(from.filename)) {
+    const fname = from.filename;   // a picked file's own name: a path in it is not a name
+    if (!pluginFileOk(fname) || !new RegExp(`\\${ext}$`, "i").test(fname)) {
+      return { ok: false, error: `The file must be a ${ext} file with a plain name.` };
+    }
+    id = fname.replace(new RegExp(`\\${ext}$`, "i"), "").toLowerCase();
+    if (!pluginIdOk(id)) return { ok: false, error: "The file's name is not one a plugin can have (lower-case letters, digits, . _ -)." };
+    if (Buffer.byteLength(from.text, "utf8") > spec.max_bytes) return { ok: false, error: "The file is larger than this kind allows." };
+    source = `file:${fname}`;
+    door = "text";
+  } else {
+    return { ok: false, error: "`from` must be a registry name, a URL, or a file's text." };
+  }
+
+  // A shipped or system copy of that id IS the plugin: nothing to write, and
+  // the answer says so. (A user copy is replaced — that is how a style updates.)
+  const have = pluginRows(here, policy, env, kind).find((r) => r.id === id && r.active && r.layer !== "user");
+  if (have) {
+    return { ok: true, kind, id, name: have.name, version: have.version, file: have.file,
+      requires: have.requires, layer: have.layer, already: true };
+  }
+
+  const userDir = pluginUserDir(env);
+  fs.mkdirSync(path.join(userDir, kind), { recursive: true, mode: 0o700 });
+  const stage = pluginStageDir(userDir);
+  let landed = false;
+  try {
+    const file = `${id}${ext}`;
+    const targetTmp = path.join(stage, file);
+    if (door === "text") {
+      try { fs.writeFileSync(targetTmp, from.text); } catch { return { ok: false, error: "Could not write the file." }; }
+    } else {
+      const err = await pluginFetch(policy, source, targetTmp, spec.max_bytes);
+      if (err) return { ok: false, error: `Could not fetch ${id}: ${err}` };
+    }
+    fs.chmodSync(targetTmp, 0o600);
+    const v = spec.validate(stage, file);
+    if (v.ok !== true) return { ok: false, error: `${id} ${v.error}.` };
+
+    // What it renders through, completed from the registry — once, BEFORE this
+    // one lands, so a plugin never sits installed with a missing parent.
+    const requires = [].concat(v.requires ?? []).map(String);
+    for (const req of requires) {
+      if (pluginActive(here, policy, env, kind, req)) continue;
+      if (complete !== true || !spec.registry) {
+        return { ok: false, error: `${id} renders through ${req}, which is not on this machine.` };
+      }
+      // eslint-disable-next-line no-await-in-loop
+      const r = await pluginInstall(here, policy, env, kind, { registry: req }, false);
+      if (r.ok !== true) return { ok: false, error: `Could not complete ${id}: ${r.error}` };
+      if (r.requires && r.requires.length) {
+        pluginRemove(here, policy, env, kind, req);
+        return { ok: false, error: `${req} is not an independent plugin; ${id} was not installed.` };
+      }
+    }
+
+    const manifest = pluginManifestFor(stage, kind, id, file, v, source, spec.license);
+    pluginManifestWrite(stage, manifest);
+    fs.chmodSync(path.join(stage, PLUGIN_MANIFEST), 0o600);
+
+    // Into place, atomically: the staged folder is renamed onto the id. An
+    // existing user copy is moved aside first and removed after, so at no
+    // instant is there half a plugin at that path.
+    const dest = pluginContained(path.join(userDir, kind), id);
+    if (!dest) return { ok: false, error: "The plugin's folder would fall outside the user layer." };
+    let old = null;
+    if (dirExists(dest)) {
+      old = path.join(userDir, ".staging", `plugin-old-${crypto.randomBytes(6).toString("hex")}`);
+      try { fs.renameSync(dest, old); } catch { return { ok: false, error: "Could not replace the existing copy." }; }
+    }
+    try { fs.renameSync(stage, dest); }
+    catch {
+      if (old) { try { fs.renameSync(old, dest); } catch { /* the copy is lost either way */ } }
+      return { ok: false, error: "Could not move the plugin into place." };
+    }
+    landed = true;
+    if (old) fs.rmSync(old, { recursive: true, force: true });
+    return { ok: true, kind, id, name: manifest.name, version: manifest.version,
+      file, requires, layer: "user", already: false };
+  } finally {
+    if (!landed) fs.rmSync(stage, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Remove one plugin from the user layer. A shipped or system plugin is not the
+ * person's to remove; a plugin another user plugin renders through stays until
+ * that one goes.
+ */
+export function pluginRemove(here, policy, env, kind, id) {
+  const table = pluginKinds(env);
+  if (!pluginKindOk(table, kind) || !pluginIdOk(id)) return { ok: false, error: "That is not a plugin." };
+  if (policy.install !== "user") return { ok: false, error: pluginPolicyReason(policy, "install") };
+  const rows = pluginRows(here, policy, env, kind);
+  const mine = rows.find((r) => r.id === id && r.layer === "user");
+  if (!mine) {
+    if (rows.some((r) => r.id === id)) return { ok: false, error: "That plugin is part of this deployment; it cannot be removed here." };
+    return { ok: false, error: "No such plugin." };
+  }
+  const needs = rows.find((r) => r.layer === "user" && r.id !== id && r.requires.includes(id));
+  if (needs) return { ok: false, error: `${needs.name} renders through it; remove that one first.` };
+  const dest = pluginContained(path.join(pluginUserDir(env), kind), id);
+  if (!dest) return { ok: false, error: "That plugin's folder is outside the user layer." };
+  fs.rmSync(dest, { recursive: true, force: true });
+  return { ok: true, kind, id };
+}
+
+/** What the policy and the layers are, for the page: disclosure, never hidden. */
+export function pluginPolicyDisclosure(here, policy, env) {
+  const table = pluginKinds(env);
+  const layers = pluginLayers(here, policy, env);
+  const kindInfo = {};
+  for (const k of policy.kinds) {
+    kindInfo[k] = {
+      kind: k, label: table[k].label, consumer: table[k].consumer,
+      extension: table[k].extension, max_bytes: table[k].max_bytes,
+      registry: Boolean(table[k].registry),
+    };
+  }
+  return {
+    set: policy.set === true,
+    source: policy.source === "env" ? "environment" : policy.source ? "file" : "",
+    install: policy.install,
+    network: policy.network === true,
+    sources: policy.sources.slice(),
+    kinds: policy.kinds.slice(),
+    note: policy.note,
+    layers: layers.map((l) => ({ name: l.name, dir: l.dir, writable: l.writable === true, exists: dirExists(l.dir) })),
+    kind_info: kindInfo,
+  };
+}
+
+/** ONE policy per host process, as serve.R has ONE `plugin_policy`. */
+let cachedPolicy = null;
+export function pluginPolicyOnce(env, opts) {
+  if (!cachedPolicy) cachedPolicy = carmarPluginPolicy(env, opts);
+  return cachedPolicy;
+}