@tinvar/renderer 0.0.0-stage → 0.4.0

package/src/sandbox.js

@@ -0,0 +1,710 @@
+// Runs the renderer under Node's permission model.
+//
+// "The renderer gets no database credentials or secrets." Keeping them out
+// of its environment is not enough: it runs as the same OS user as PHP, so
+// any dependency it loads could simply read a key file, a .env, or the
+// user's SSH keys from disk -- or spawn `cat` to do it. Under --permission
+// it can read only what rendering needs, write only its socket directory,
+// and cannot start processes or workers at all.
+//
+// What rendering needs:
+//   - the renderer's own package;
+//   - the app's built output (the directory above the entry, so the rsc
+//     entry can load the ssr build beside it);
+//   - each package in every node_modules directory above either of them
+//     that is there for real; and by its real path each package the app or
+//     the renderer depends on, directly or through another, found where
+//     Node finds it -- a workspace link, or a package in pnpm's store --
+//     unless it leads into the app's own source tree;
+//   - its socket, read and write -- and nothing else in that directory.
+//
+// One limit to know: the model checks the path as requested, not as
+// resolved, and treats an allowed directory as covering everything beneath
+// it -- so a symlink inside an allowed directory reaches wherever it points.
+// That is why node_modules is allowed package by package rather than whole.
+// Secrets still belong outside the project tree -- the generated app key is
+// kept in the user's state directory -- and the sandbox is the second line,
+// not the only one.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+
+/**
+ * @param {{ rendererRoot: string, appEntry: string, socketPath: string, extraRead?: string[] }} options
+ * @returns {string[]} the node flags
+ */
+export function sandboxFlags({ rendererRoot, appEntry, socketPath, extraRead = [], appRoot: givenAppRoot }) {
+  // Real paths: Node resolves a module to its real path before reading it,
+  // so an allowlist written through a symlink -- macOS's /var is one --
+  // would not cover the file actually read.
+  linksBeneath.clear();
+  const renderer = real(rendererRoot);
+  const appRoot = givenAppRoot ? real(givenAppRoot) : path.dirname(path.dirname(real(appEntry)));
+  assertBuildDirectory(appRoot, renderer);
+
+  /** @type {Set<string>} directories, granted with everything beneath them */
+  const trees = new Set([appRoot, ...extraRead.filter(Boolean).map((p) => checkedExtra(p, renderer))]);
+  /** @type {Set<string>} single files */
+  const files = new Set();
+  /** @type {Set<string>} links to packages in pnpm's store, granted at the path Node finds them by */
+  const linked = new Set();
+
+  // The renderer's own package entry by entry: a blanket grant would also
+  // cover any node_modules inside it, and with it every symlink there.
+  grantEntries(renderer, trees, files);
+
+  // Packages only, never a node_modules directory itself: Node treats an
+  // allowed directory as covering everything beneath it, symlinks included.
+  // A package there for real is granted; a link -- a workspace package, or
+  // under pnpm nearly every package -- only once rendering is found to
+  // depend on it, below.
+  for (const modules of new Set([...nodeModulesAbove(renderer), ...nodeModulesAbove(appRoot)])) {
+    for (const entry of packagesIn(modules)) {
+      if (!fs.lstatSync(entry).isSymbolicLink()) trees.add(entry);
+    }
+  }
+
+  // The packages rendering may load: what the app or the renderer depends
+  // on, and in turn what each of those depends on, each found where Node
+  // would find it -- the first node_modules above the package asking that
+  // holds the name -- and granted by its real path, which is what Node
+  // reads. Under pnpm that is the package's own directory in the store
+  // (node_modules/.pnpm/<name>@<version>/node_modules/<name>), and its
+  // dependencies are the links beside it there, so the store is granted
+  // package by package, never whole: whole, it held every package pnpm
+  // installed, and every link pnpm hoists into .pnpm/node_modules, which
+  // leads anywhere -- a workspace package nothing rendering loads, another
+  // app of the workspace and its database. A link is never granted for
+  // being there: granted by its presence alone, another app of the same
+  // workspace was granted whole, and so was every package of a checkout
+  // above this one. Not when it leads into the app's own source tree -- the
+  // renderer reaches the build directly -- nor to the disk's root or the
+  // home directory; a package in the store whole, being its own files; and
+  // any other only its package, not its node_modules or its
+  // dot-directories.
+  const pending = [
+    ...dependenciesOf(packageAbove(appRoot), { development: true }).map((name) => ({ name, from: appRoot })),
+    ...dependenciesOf(path.join(renderer, 'package.json'), { development: true }).map((name) => ({
+      name,
+      from: renderer,
+    })),
+  ];
+  const reached = new Set();
+  const home = process.env.HOME ? real(process.env.HOME) : null;
+  while (pending.length > 0) {
+    const { name, from } = /** @type {{ name: string, from: string }} */ (pending.pop());
+    const entry = resolvePackage(name, from);
+    if (entry === null) continue;
+    const target = real(entry);
+    if (appRoot === target || appRoot.startsWith(target + path.sep)) continue;
+    if (target === path.parse(target).root || target === home || renderer.startsWith(target + path.sep))
+      continue;
+    // Node reads a package at the path it found it by, a link's included,
+    // and the model checks that path as requested -- so a package found
+    // through a link loads only if the link is granted, and a granted link
+    // covers everything beneath its target. That is the package and no
+    // more for a package in pnpm's store, which holds its own files and
+    // puts its dependencies beside it, never a node_modules or a link of
+    // its own; so its link is granted, unless something beneath it is a
+    // link after all. A workspace package's directory holds its
+    // node_modules, its links and its dot-files, so its link is not: it is
+    // granted by its real path alone, and loaded through its link at run
+    // time it is refused -- the app's build bundles it.
+    const whole = inStore(target) && fs.statSync(target).isDirectory() && !linkBeneath(target);
+    if (entry !== target && whole) linked.add(entry);
+    if (reached.has(target)) continue;
+    reached.add(target);
+    if (!fs.statSync(target).isDirectory()) {
+      files.add(target);
+      continue;
+    }
+    // A package in the store whole, as its link already reaches it: one
+    // flag, not one per file, so a pnpm app's allowlist stays well inside
+    // a command line.
+    if (whole) trees.add(target);
+    else grantEntries(target, trees, files);
+    pending.push(
+      ...dependenciesOf(path.join(target, 'package.json'), { development: false }).map((dependency) => ({
+        name: dependency,
+        from: target,
+      })),
+    );
+  }
+
+  // The socket and nothing else beside it -- not even a read of its
+  // directory, which Node would extend to everything in it. The launcher
+  // creates the directory before the sandbox starts, so a shared one like
+  // /tmp stays out of reach.
+  const socket = real(socketPath);
+
+  const covered = (p) => [...trees].some((t) => t !== p && p.startsWith(t + path.sep));
+  const granted = (p) => trees.has(p) || files.has(p) || linked.has(p) || covered(p);
+  const everything = [...trees, ...files, ...linked];
+  // Node's model refuses a directory it was granted exactly when another
+  // grant runs on from it as text -- react beside react-dom, as pnpm puts
+  // them -- so such a link is granted as a prefix, `react*`, when every
+  // entry beside it that the prefix also names is granted anyway; when one
+  // is not, exactly, and the package fails to load rather than the grant
+  // widen.
+  const linkFlag = (link) => {
+    if (!everything.some((other) => other !== link && other.startsWith(link))) return link;
+    const base = path.basename(link);
+    const beside = fs
+      .readdirSync(path.dirname(link))
+      .filter((name) => name !== base && name.startsWith(base))
+      .map((name) => path.join(path.dirname(link), name));
+    return beside.every(granted) ? `${link}*` : link;
+  };
+
+  const links = [...linked].filter((l) => !covered(l)).map(linkFlag);
+  // What a prefix grant already covers is not granted again: Node's model
+  // also loses a prefix granted after a path that runs on from it.
+  const prefixes = links.filter((l) => l.endsWith('*')).map((l) => l.slice(0, -1));
+  const unprefixed = (p) => !prefixes.some((prefix) => p.startsWith(prefix));
+
+  return [
+    permissionFlag(),
+    ...links.map((l) => `--allow-fs-read=${l}`),
+    // Without the ones a broader grant already covers: a package reached by
+    // its dependencies that is also in a node_modules granted for real.
+    ...[...trees]
+      .filter((t) => !covered(t) && unprefixed(t))
+      .map((t) => `--allow-fs-read=${path.join(t, '*')}`),
+    ...[...files].filter((f) => !covered(f) && unprefixed(f)).map((f) => `--allow-fs-read=${f}`),
+    `--allow-fs-read=${socket}`,
+    `--allow-fs-write=${socket}`,
+  ];
+}
+
+/**
+ * The flag's name: `--permission` from Node 22.13, `--experimental-permission`
+ * before it. Asked of the running Node rather than assumed, so an older 22
+ * is sandboxed too instead of failing to start with "bad option".
+ */
+export function permissionFlag() {
+  return process.allowedNodeEnvironmentFlags.has('--permission')
+    ? '--permission'
+    : '--experimental-permission';
+}
+
+/**
+ * The app's build directory is granted whole, so it must be a build
+ * directory. Derived from the entry as its grandparent (dist/rsc/index.js
+ * -> dist), an entry anywhere else made it the project's parent, or the
+ * root: every sibling project and its .env, or the whole disk.
+ */
+function assertBuildDirectory(appRoot, renderer) {
+  const home = process.env.HOME ? real(process.env.HOME) : null;
+  if (appRoot === path.parse(appRoot).root || appRoot === home || renderer.startsWith(appRoot + path.sep)) {
+    throw new Error(
+      `[tinvar:renderer] Refusing to sandbox with ${appRoot} as the app's build directory: it would grant far ` +
+        'more than the build. Set TINVAR_APP_ROOT to the build directory (the one holding rsc/ and ssr/).',
+    );
+  }
+}
+
+/**
+ * An extra read path from TINVAR_RENDERER_READ: absolute, and no wider than
+ * a build directory may be. `.` or `/` there granted the project or the
+ * whole disk.
+ */
+function checkedExtra(p, renderer) {
+  if (!path.isAbsolute(p)) {
+    throw new Error(`[tinvar:renderer] TINVAR_RENDERER_READ entries must be absolute; got ${p}.`);
+  }
+  const resolved = real(p);
+  assertBuildDirectory(resolved, renderer);
+  return resolved;
+}
+
+/** Grants each entry of a package directory except node_modules and dot-entries. */
+function grantEntries(dir, trees, files) {
+  for (const name of fs.readdirSync(dir)) {
+    if (name === 'node_modules' || name.startsWith('.')) continue;
+    const entry = path.join(dir, name);
+    const stat = fs.lstatSync(entry);
+    if (stat.isSymbolicLink()) continue;
+    if (stat.isDirectory()) trees.add(entry);
+    else files.add(entry);
+  }
+}
+
+/**
+ * Each package in a node_modules directory. Dot-entries are caches and
+ * tooling (.vite, .vitest, .cache) and pnpm's store (.pnpm), and are left
+ * out: what rendering loads from the store is granted package by package,
+ * as its dependencies reach it.
+ *
+ * @param {string} modules
+ * @returns {string[]}
+ */
+function packagesIn(modules) {
+  const found = [];
+  const visit = (dir, scoped) => {
+    for (const name of fs.readdirSync(dir)) {
+      if (name.startsWith('.')) continue;
+      const entry = path.join(dir, name);
+      if (!scoped && name.startsWith('@') && fs.lstatSync(entry).isDirectory()) {
+        visit(entry, true);
+        continue;
+      }
+      found.push(entry);
+    }
+  };
+  visit(modules, false);
+  return found;
+}
+
+/**
+ * The real path of `p`, or -- for a path that does not exist yet, like a
+ * socket -- the real path of its nearest existing ancestor with the rest
+ * appended.
+ */
+export function real(p) {
+  const absolute = path.resolve(p);
+  try {
+    return fs.realpathSync(absolute);
+  } catch {
+    const parent = path.dirname(absolute);
+    return parent === absolute ? absolute : path.join(real(parent), path.basename(absolute));
+  }
+}
+
+/**
+ * The package.json nearest above `start`: the app's, for its build
+ * directory. Null when there is none up to the root.
+ *
+ * @param {string} start
+ * @returns {string | null}
+ */
+function packageAbove(start) {
+  for (let dir = path.resolve(start); ; dir = path.dirname(dir)) {
+    const candidate = path.join(dir, 'package.json');
+    if (fs.existsSync(candidate)) return candidate;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+/**
+ * The names a package.json depends on: what its package needs to run, and
+ * with `development`, what it builds with too -- for the app and the
+ * renderer, whose builds may leave any of them to be loaded at run time.
+ * None for a manifest that is missing or does not parse.
+ *
+ * @param {string | null} manifest
+ * @param {{ development: boolean }} options
+ * @returns {string[]}
+ */
+function dependenciesOf(manifest, { development }) {
+  let parsed;
+  try {
+    parsed = manifest === null ? null : JSON.parse(fs.readFileSync(manifest, 'utf8'));
+  } catch {
+    return [];
+  }
+  const fields = ['dependencies', 'optionalDependencies', 'peerDependencies'];
+  if (development) fields.push('devDependencies');
+  return fields.flatMap((field) => {
+    const named = parsed?.[field];
+    return named !== null && typeof named === 'object' && !Array.isArray(named) ? Object.keys(named) : [];
+  });
+}
+
+/** Every existing node_modules directory from `start` up to the root. */
+function nodeModulesAbove(start) {
+  const found = [];
+  let dir = path.resolve(start);
+  for (;;) {
+    const candidate = path.join(dir, 'node_modules');
+    if (fs.existsSync(candidate)) found.push(candidate);
+    const parent = path.dirname(dir);
+    if (parent === dir) return found;
+    dir = parent;
+  }
+}
+
+/**
+ * Where Node finds the package `name` from `from`: the first node_modules
+ * above it holding the name, as the path there -- a link, or the package.
+ * Null for one it would not find, and for a name that is not a package's:
+ * the names come from manifests, and one like `../../secrets` must not
+ * lead out of a node_modules.
+ *
+ * @param {string} name
+ * @param {string} from
+ * @returns {string | null}
+ */
+function resolvePackage(name, from) {
+  if (!PACKAGE_NAME.test(name)) return null;
+  for (const modules of nodeModulesAbove(from)) {
+    const candidate = path.join(modules, ...name.split('/'));
+    try {
+      fs.lstatSync(candidate);
+      return candidate;
+    } catch {
+      // Not here: the next node_modules up.
+    }
+  }
+  return null;
+}
+
+/**
+ * Whether `dir` is a package in pnpm's store, where pnpm's isolated linker
+ * puts every package it installs:
+ * node_modules/.pnpm/<name>@<version>/node_modules/<name>.
+ *
+ * @param {string} dir a real path
+ */
+function inStore(dir) {
+  const parts = dir.split(path.sep);
+  const at = parts.lastIndexOf('.pnpm');
+  if (at < 1 || parts[at - 1] !== 'node_modules' || parts[at + 2] !== 'node_modules') return false;
+  const rest = parts.slice(at + 3);
+  return rest.length === 1 || (rest.length === 2 && rest[0].startsWith('@'));
+}
+
+/**
+ * Whether anything beneath `dir` is a link: a link granted to a package
+ * would reach wherever such a one points.
+ *
+ * @param {string} dir
+ */
+function linkBeneath(dir) {
+  let found = linksBeneath.get(dir);
+  if (found === undefined) {
+    found = fs
+      .readdirSync(dir, { withFileTypes: true })
+      .some(
+        (entry) => entry.isSymbolicLink() || (entry.isDirectory() && linkBeneath(path.join(dir, entry.name))),
+      );
+    linksBeneath.set(dir, found);
+  }
+  return found;
+}
+
+/** @type {Map<string, boolean>} what linkBeneath() found, by directory, for the one walk of a start */
+const linksBeneath = new Map();
+
+/** A package's name: an optional scope, then a name, neither starting with a dot or holding a path. */
+const PACKAGE_NAME = /^(@[a-z0-9~-][a-z0-9._~-]*\/)?[a-z0-9~-][a-z0-9._~-]*$/i;
+
+/**
+ * The variables rendering needs, and no others.
+ *
+ * The permission model does not restrict the network or Unix sockets, so
+ * what the child can reach is decided by what it is told about: with
+ * SSH_AUTH_SOCK it could have the user's ssh-agent sign with their keys,
+ * and any other socket or token in the launching shell was one variable
+ * away. The child gets an allowlist instead of process.env.
+ */
+const CHILD_ENV = ['PATH', 'NODE_ENV', 'TZ', 'LANG', 'LC_ALL', 'TINVAR_RENDERER_CODEC'];
+
+/**
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {Record<string, string>}
+ */
+export function childEnvironment(env = process.env) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const name of CHILD_ENV) {
+    if (typeof env[name] === 'string') out[name] = env[name];
+  }
+  return out;
+}
+
+/**
+ * Cuts this process's own environment down to childEnvironment()'s
+ * allowlist, and `keep`, in place: for a renderer that runs where it was
+ * started rather than in a child -- the dev renderer, and the renderer with
+ * the sandbox turned off -- so the app and its dependencies see what a
+ * sandboxed child would, and nothing a shell happened to export.
+ *
+ * @param {string[]} [keep] names beyond the allowlist this renderer reads
+ * @param {Record<string, string | undefined>} [env]
+ */
+export function scrubEnvironment(keep = [], env = process.env) {
+  const allowed = new Set([...CHILD_ENV, ...keep]);
+  for (const name of Object.keys(env)) {
+    if (!allowed.has(name)) delete env[name];
+  }
+}
+
+/** Whether this process is already running under the permission model. */
+export function isSandboxed() {
+  return typeof process.permission?.has === 'function';
+}
+
+/**
+ * Starts `script` under the permission model and returns the child.
+ *
+ * Its standard input is its tether: a pipe of its own, whose other end this
+ * process holds and never writes to or reads. Killed outright, a parent can
+ * forward nothing, and the child would keep serving its socket as an
+ * orphan; but however the parent dies, its end closes, and the child stops
+ * at the end of its input (watchTether). Nothing of this process's is
+ * passed on -- an inherited descriptor is readable without any permission
+ * check, so its own standard input, a terminal or tinvar serve's tether,
+ * stays out of reach.
+ *
+ * Not an IPC channel, which the tether once was. Node reads a channel for
+ * as long as it is open and keeps what it reads until a message ends, so a
+ * compromised renderer writing to it without end had the supervisor hold
+ * all of it: 400 MB written grew the supervisor by 478 MB. The pipe is a
+ * socket pair, as Node makes them, so the child can write to its end too --
+ * and what it writes waits in the kernel's buffer for this end, which is
+ * never read: a few kilobytes, and then the child's writes wait.
+ *
+ * Some failures throw from spawn() itself rather than arriving as an
+ * 'error' event -- E2BIG, an allowlist too long for the command line, is
+ * one -- so a caller handles both.
+ *
+ * @param {string} script
+ * @param {string[]} args
+ * @param {string[]} flags from sandboxFlags()
+ * @param {{ detached?: boolean }} [options] `detached` gives the child a
+ *        process group of its own, so a terminal's Ctrl-C reaches only the
+ *        parent, which then decides what each child is told
+ * @returns {import('node:child_process').ChildProcess}
+ */
+export function spawnSandboxed(script, args, flags, { detached = false } = {}) {
+  closeInheritedDescriptors();
+  const child = spawn(process.execPath, [...flags, script, ...args], {
+    stdio: ['pipe', 'inherit', 'inherit'],
+    env: childEnvironment(),
+    detached,
+  });
+  // Never written, so it has no EPIPE to report; but an 'error' with no
+  // listener would take the supervisor down, and every renderer with it.
+  child.stdin?.on('error', () => {});
+
+  return child;
+}
+
+/** O_CLOEXEC, as /proc/self/fdinfo writes a descriptor's flags: in octal. */
+const O_CLOEXEC = 0o2000000;
+
+/**
+ * Closes every descriptor above 2 this process inherited, so the sandboxed
+ * child it is about to start inherits none of them in turn. Linux only, and
+ * returns what it closed.
+ *
+ * PHP opens nothing close-on-exec, so tinvar serve, renderer:start and the
+ * test pool hand this process the database, the log, the key it read and
+ * each other's pipes, each under its own number -- pcntl_exec keeps every
+ * one. Node marks what it inherited close-on-exec as it starts, but only up
+ * to the first gap past descriptor 15 (uv_disable_stdio_inheritance()), and
+ * a PHP worker holding many is past one: libuv on Linux closes nothing
+ * above 2 in a child it spawns, and the permission model checks paths,
+ * never a descriptor already open, so the sandboxed renderer could read
+ * each one left. (On macOS libuv spawns with POSIX_SPAWN_CLOEXEC_DEFAULT,
+ * and the child gets only its stdio.)
+ *
+ * What would be handed on is told apart by its flags: everything Node and
+ * libuv open is close-on-exec, as is what Node's start marked, and
+ * nothing else is. The IPC channel, the one
+ * descriptor Node takes on inherited, is left; the renderer is started
+ * with none. No /proc to read is refused: what would be handed on cannot
+ * be known.
+ *
+ * @param {{ platform?: string, root?: string }} [options] for the tests
+ * @returns {number[]}
+ */
+export function closeInheritedDescriptors({ platform = process.platform, root = '/proc/self' } = {}) {
+  if (platform !== 'linux') return [];
+
+  let names;
+  try {
+    names = fs.readdirSync(`${root}/fd`);
+  } catch (error) {
+    throw new Error(
+      `Cannot list this process's descriptors to keep them from the sandboxed renderer (${error.code ?? error.message}).`,
+    );
+  }
+  const channel = /** @type {{ fd?: unknown } | undefined} */ (process.channel)?.fd;
+  const closed = [];
+  for (const name of names) {
+    const fd = Number(name);
+    if (!Number.isInteger(fd) || fd <= 2 || fd === channel) continue;
+    let info;
+    try {
+      info = fs.readFileSync(`${root}/fdinfo/${fd}`, 'utf8');
+    } catch {
+      // Gone since the listing: the listing's own.
+      continue;
+    }
+    const flags = /^flags:\s*([0-7]+)$/m.exec(info);
+    if (flags !== null && (parseInt(flags[1], 8) & O_CLOEXEC) !== 0) continue;
+    try {
+      fs.closeSync(fd);
+      closed.push(fd);
+    } catch {
+      // Closed since it was read.
+    }
+  }
+  return closed;
+}
+
+/**
+ * Calls `gone` when the parent that started this process is gone, read off
+ * the tether spawnSandboxed() gives it: the end of its standard input. For
+ * the sandboxed child.
+ *
+ * Only a pipe or a socket is a tether. Started some other way, with a
+ * terminal or /dev/null for standard input -- which ends at once -- the
+ * process has nothing to watch, and serves until it is told to stop.
+ *
+ * @param {() => void} gone
+ * @returns {boolean} whether there was a tether to watch
+ */
+export function watchTether(gone) {
+  let stat;
+  try {
+    stat = fs.fstatSync(0);
+  } catch {
+    return false;
+  }
+  if (!stat.isFIFO() && !stat.isSocket()) return false;
+
+  // Read for its end alone: nothing is written to it. An error counts as
+  // the end -- a peer that closes with what the child wrote still unread is
+  // a reset, not an end of input, to Linux.
+  process.stdin.once('end', gone);
+  process.stdin.on('error', gone);
+  process.stdin.resume();
+
+  return true;
+}
+
+/**
+ * Starts `script` again under the permission model, passing signals
+ * through, and resolves with its exit code.
+ *
+ * @param {string} script
+ * @param {string[]} args
+ * @param {string[]} flags from sandboxFlags()
+ */
+export function relaunchSandboxed(script, args, flags) {
+  const failed = (error) => {
+    console.error(`[tinvar:renderer] could not start the sandboxed renderer: ${error.message}`);
+    return 1;
+  };
+
+  let child;
+  try {
+    child = spawnSandboxed(script, args, flags);
+  } catch (error) {
+    return Promise.resolve(failed(error));
+  }
+
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(signal, () => child.kill(signal));
+  }
+
+  return new Promise((resolve) => {
+    child.on('error', (error) => resolve(failed(error)));
+    child.on('exit', (code, signal) => resolve(exitCode(code, signal)));
+  });
+}
+
+/** A child's exit as a shell reports it: its code, or 128 + its signal's number. */
+export function exitCode(code, signal) {
+  return code ?? (signal ? 128 + (os.constants.signals[signal] ?? 0) : 0);
+}
+
+/**
+ * What each networking module may still be called for, because it opens
+ * nothing: a server for the renderer's own socket (held to it below), the
+ * classes and checks that make or read no connection, and the settings
+ * that change none. Every other function the module exports is refused --
+ * by default, so an export a Node release adds is refused until it is
+ * named here. Each underscore export the default now catches made a raw
+ * handle: `dgram._createSocketHandle()` one that sent a datagram out of
+ * the sandbox, `net._createServerHandle()` a TCP server on any port.
+ */
+export const OPENS_NOTHING = Object.freeze({
+  net: Object.freeze([
+    'createServer',
+    'Server',
+    'Socket',
+    'Stream',
+    'BlockList',
+    'SocketAddress',
+    'isIP',
+    'isIPv4',
+    'isIPv6',
+    'getDefaultAutoSelectFamily',
+    'setDefaultAutoSelectFamily',
+    'getDefaultAutoSelectFamilyAttemptTimeout',
+    'setDefaultAutoSelectFamilyAttemptTimeout',
+  ]),
+  dgram: Object.freeze([]),
+  dns: Object.freeze(['getServers', 'getDefaultResultOrder', 'setDefaultResultOrder']),
+});
+
+/**
+ * Closes outbound networking from inside the sandboxed child.
+ *
+ * Node 22's permission model has no network flag, so a dependency could
+ * open a socket to the database, or to anywhere, and send what it read. This
+ * replaces every function node:net, node:dgram and node:dns export but the
+ * few that open nothing (OPENS_NOTHING) -- TCP and Unix-socket connects
+ * (which fetch, http, https, http2 and tls all go through), UDP, and DNS,
+ * itself a way to send data out -- with one that throws, and pins the
+ * replacements so code loaded later cannot put the originals back. The
+ * internal bindings these sit on are refused by the permission model itself
+ * (process.binding throws under --permission).
+ *
+ * The classes it leaves are held where they would open something: a
+ * socket's connect(), and a server's listen. Listening is closed but for the
+ * renderer's own socket: a server anyone who can reach the host could
+ * connect to -- a port, a descriptor, another socket file -- is a way out
+ * turned around, collecting what the renderer draws for every user. Every
+ * listen goes through the server's `_listen2`, so that is where it is held,
+ * not listen() alone. Defence in depth, not a network boundary --
+ * production should still run the renderer as its own user with no route
+ * out (see the spec's trust boundaries).
+ *
+ * @param {{ net: typeof import('node:net'), dgram: typeof import('node:dgram'), dns: typeof import('node:dns'), listenOn?: string }} modules
+ *        `listenOn` the socket path the renderer serves, the one thing it
+ *        may listen on; without one it may listen on nothing
+ */
+export function lockNetwork({ net, dgram, dns, listenOn }) {
+  const refuse = (what) =>
+    function refused() {
+      const error = new Error(
+        `[tinvar:renderer] ${what} is not allowed: the renderer has no network access.`,
+      );
+      error.code = 'ERR_ACCESS_DENIED';
+      throw error;
+    };
+  const pin = (target, name, value) =>
+    Object.defineProperty(target, name, { value, writable: false, configurable: false, enumerable: true });
+
+  // Data properties only: a getter -- dns.promises is one -- is not called
+  // to find out what it holds.
+  const lock = (module, label, allowed) => {
+    for (const name of Object.getOwnPropertyNames(module)) {
+      const value = Object.getOwnPropertyDescriptor(module, name)?.value;
+      if (typeof value === 'function' && !allowed.includes(name))
+        pin(module, name, refuse(`${label}.${name}()`));
+    }
+  };
+  lock(net, 'net', OPENS_NOTHING.net);
+  lock(dgram, 'dgram', OPENS_NOTHING.dgram);
+  lock(dns, 'dns', OPENS_NOTHING.dns);
+  lock(dns.promises, 'dns.promises', OPENS_NOTHING.dns);
+
+  pin(net.Socket.prototype, 'connect', refuse('Opening a connection'));
+
+  // Every listen -- a port, a path, a handle, a descriptor -- reaches the
+  // server's handle through `_listen2(address, port, ...)`, with the path
+  // as the address for a socket file and null for a handle or descriptor.
+  const listen = net.Server.prototype._listen2;
+  const refuseListen = refuse('Listening anywhere but the renderer socket');
+  pin(net.Server.prototype, '_listen2', function listenOnOwnSocket(address, port, ...rest) {
+    if (typeof listenOn !== 'string' || address !== listenOn || port !== -1) refuseListen();
+    return listen.call(this, address, port, ...rest);
+  });
+}