@tinvar/renderer 0.0.0-stage → 0.4.1

package/src/server.js

@@ -0,0 +1,466 @@
+// The renderer: a private Unix socket server next to PHP.
+//
+// Hardening the spec requires of this process:
+//   - no secrets: it starts with a scrubbed environment and holds no credentials
+//   - private socket, mode 0600, owned by the app user -- or, run as a user
+//     of its own, 0660 in a group of that user and PHP's (ADR 0028)
+//   - frames capped at a configured size
+//   - it never decodes client payloads, which is the class of bug behind
+//     React's CVE-2025-55182
+//   - per-render isolation: each render has its own context and nothing is
+//     cached across requests
+
+import net from 'node:net';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { FrameReader, DEFAULT_MAX_FRAME_BYTES, createCodec, encodeFrame, msgpackCodec } from './codec.js';
+import { logLine, requestIdOf } from './log.js';
+import { FRAME, assertFromPhp } from './protocol.js';
+import { RenderSession } from './render-session.js';
+
+/**
+ * Credentials must never reach this process. Refuse to start if they have.
+ *
+ * By shape as well as by name. A fixed list missed the names applications
+ * actually use -- TINVAR_APP_KEY, TINVAR_DB_PASSWORD, TINVAR_DSN -- and a
+ * renderer started from a shell that exported them started without a word.
+ * Anything whose last segment names a key, password, secret or connection
+ * string counts, under any prefix.
+ *
+ * The live hub's keys too (ADR 0048). PHP signs the hub's access and
+ * publisher tokens with them -- TINVAR_LIVE_SUBSCRIBER_KEY and
+ * TINVAR_LIVE_PUBLISHER_KEY, or Mercure's own MERCURE_*_JWT_KEY -- and a
+ * renderer holding the publisher key could tell every open page anything.
+ * Their names end in neither APP_KEY nor PRIVATE_KEY, and passed.
+ *
+ * And the probes' and the trace exporter's (ADR 0041): TINVAR_PROBE_TOKEN
+ * opens /_metrics and /_ready to whoever holds it, and
+ * OTEL_EXPORTER_OTLP_HEADERS -- or its per-signal form -- is where a
+ * collector's API key or bearer token is written. Neither name ends in a
+ * key, a password or a secret, and both passed.
+ *
+ * And where a private key's file is (ADR 0116): TINVAR_MAIL_DKIM_PRIVATE_KEY
+ * ends in PRIVATE_KEY, and its _FILE form names a file this process might
+ * read.
+ *
+ * And then every name the list did not reach: STRIPE_SECRET_KEY,
+ * OPENAI_API_KEY, GITHUB_TOKEN, AWS_SESSION_TOKEN, TINVAR_SESSION_KEY,
+ * TINVAR_SMTP_PASS. Any name with a segment that says key, token, pass,
+ * secret, credential or private, anywhere in it -- so a _FILE form, which
+ * names where one is, too. None of the names the renderer is told anything
+ * by (TINVAR_RENDERER_*, TINVAR_APP_*, NODE_*) has one.
+ */
+const FORBIDDEN_ENV =
+  /(^|_)(KEYS?|APIKEY|TOKENS?|AUTHTOKEN|PASS|PASSWORD|PASSWD|PASSPHRASE|SECRETS?|CREDENTIALS?|PRIVATE|DSN|DATABASE_URL|DB_USERNAME|DB_USER|OTLP_HEADERS|OTLP_(TRACES|METRICS|LOGS)_HEADERS)(_|$)/i;
+
+/**
+ * A URL with credentials in it -- `redis://:password@cache` -- anywhere in
+ * a value: a connection string carries its password whatever its variable
+ * is called. An `@` in the URL's authority, before any path, query or
+ * fragment.
+ */
+const URL_WITH_USERINFO = /[a-z][a-z0-9+.-]*:\/\/[^/?#\s]*@/i;
+
+/**
+ * @param {Record<string, string | undefined>} [env]
+ * @throws {Error} naming each variable that holds a credential, never its value
+ */
+export function assertScrubbedEnvironment(env = process.env) {
+  const present = Object.keys(env).filter((key) => {
+    const value = env[key];
+    if (typeof value !== 'string' || value === '') return false;
+    return FORBIDDEN_ENV.test(key) || URL_WITH_USERINFO.test(value);
+  });
+  if (present.length > 0) {
+    throw new Error(
+      `The renderer must start with a scrubbed environment; found ${present.join(', ')}. ` +
+        'It never needs credentials, and holding them widens what a compromised dependency reaches.',
+    );
+  }
+}
+
+/**
+ * How long a renderer told to stop goes on serving the renders it has:
+ * PHP's overall cap on one render, the 15 s deadline four times over, which
+ * counts a slow client too. Past it PHP has stopped waiting for the render,
+ * so there is nothing left to finish it for.
+ */
+export const DEFAULT_DRAIN_MS = 60_000;
+
+/** How long a draining renderer goes on accepting once its socket's path is gone; see drain(). */
+const BACKLOG_GRACE_MS = 100;
+
+/**
+ * Has the app load what its renders will, before the socket says it is
+ * ready: an entry's `warm()`, where it exports one -- every client
+ * component's module, so the first page's head preloads what every later
+ * one's does (@tinvar/renderer/warm). What does not load is reported, and
+ * left for the render that needs it to fail as it would have.
+ *
+ * @param {Record<string, unknown>} app the app's rsc entry
+ */
+export async function warmApp(app) {
+  if (typeof app.warm !== 'function') return;
+  try {
+    const warmed = await app.warm();
+    const failed = Array.isArray(warmed?.failed) ? warmed.failed : [];
+    if (failed.length > 0) {
+      console.error(`[tinvar:renderer] could not load ahead of the first render: ${failed.join(', ')}`);
+    }
+  } catch (error) {
+    console.error(
+      '[tinvar:renderer] could not warm the app:',
+      error instanceof Error ? error.message : error,
+    );
+  }
+}
+
+/**
+ * @param {{socketPath: string, appEntry: string, maxFrameBytes?: number, checkEnvironment?: boolean, codec?: 'msgpack' | 'json-lines', socketGroup?: number | null}} options
+ *        `socketGroup` shares the socket with that group (0660), for PHP
+ *        running as another user in it; 0600 without one. `codec` is the
+ *        frames' encoding, msgpack unless set to json-lines to match PHP
+ */
+export async function createRenderer(options) {
+  const {
+    socketPath,
+    appEntry,
+    maxFrameBytes = DEFAULT_MAX_FRAME_BYTES,
+    checkEnvironment = true,
+    codec: codecName = 'msgpack',
+    socketGroup = null,
+  } = options;
+
+  const codec = typeof codecName === 'string' ? createCodec(codecName) : (codecName ?? msgpackCodec);
+
+  if (checkEnvironment) assertScrubbedEnvironment();
+
+  const app = await import(appEntry);
+  if (typeof app.renderHtml !== 'function') {
+    throw new Error(`${appEntry} does not export renderHtml(frame, client).`);
+  }
+  await warmApp(app);
+
+  await fs.rm(socketPath, { force: true });
+
+  // The directory is locked down first, so the socket is never reachable even
+  // for the instant before its own mode is set.
+  // Under the sandbox the launcher made it, and the renderer may neither look
+  // into it nor write there beyond its own socket.
+  if (typeof process.permission?.has !== 'function') {
+    const made = await fs.mkdir(path.dirname(socketPath), { recursive: true, mode: 0o700 });
+    if (made !== undefined && socketGroup !== null) {
+      await shareDirectory(path.dirname(socketPath), socketGroup);
+    }
+  }
+
+  // What a health check reports, and what a drain waits for.
+  const state = { inFlight: 0, served: 0 };
+  const connections = new Set();
+
+  const server = net.createServer((socket) => {
+    connections.add(socket);
+    socket.on('close', () => connections.delete(socket));
+    socket.on('error', (error) => logLine('warning', 'socket error', {}, error));
+    handleConnection(socket, app, maxFrameBytes, codec, state);
+  });
+
+  // listen() creates the socket with 0666 & ~umask. chmod afterwards leaves a
+  // window in which any local user can connect, so the mode is set by umask
+  // before the socket exists rather than corrected after.
+  const previousUmask = process.umask(0o177);
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(socketPath, resolve);
+    });
+  } finally {
+    process.umask(previousUmask);
+  }
+
+  // Belt and braces on platforms that ignore umask for sockets, then verify:
+  // the spec requires mode 0600, so starting wider is a failure, not a warning.
+  await fs.chmod(socketPath, 0o600);
+
+  // Shared with PHP's user through a group of the two, as a renderer run as
+  // a user of its own must be: given to the group while still 0600, and only
+  // then opened to it, so it is never open to a group it was not meant for
+  // -- Linux makes it in this process's group, macOS in its directory's.
+  if (socketGroup !== null) {
+    await fs.chown(socketPath, -1, socketGroup);
+    await fs.chmod(socketPath, 0o660);
+  }
+
+  const listening = await fs.stat(socketPath);
+  const mode = listening.mode & 0o777;
+  const wanted = socketGroup === null ? 0o600 : 0o660;
+  if (mode !== wanted || (socketGroup !== null && listening.gid !== socketGroup)) {
+    await new Promise((resolve) => server.close(resolve));
+    throw new Error(
+      socketGroup === null
+        ? `Renderer socket is mode ${mode.toString(8)}; it must be 600.`
+        : `Renderer socket is mode ${mode.toString(8)} in group ${listening.gid}; it must be 660 in group ${socketGroup}.`,
+    );
+  }
+
+  let draining = null;
+
+  /**
+   * Stops taking renders and finishes the ones it has: the graceful stop.
+   * Renders still open after `timeoutMs` are cut off, and PHP reports each
+   * as an incomplete render, the error it gives any renderer that goes away
+   * mid-render.
+   */
+  const drain = (timeoutMs = DEFAULT_DRAIN_MS) => {
+    draining ??= (async () => {
+      // The path goes first, so that PHP finds no renderer here at once and
+      // picks another, rather than connecting to a socket nobody accepts on.
+      // A pool gives each renderer a path of its own and never reuses one,
+      // so this can never remove a successor's.
+      await fs.rm(socketPath, { force: true });
+
+      // Then the listener stays open a moment longer. A connect that found
+      // the path just before it went is waiting in the kernel's backlog --
+      // connected, as far as PHP knows, with its render frame sent -- and
+      // closing the listener under it reset it: a render dropped by a
+      // rolling restart. With the path gone no more can arrive; the wait,
+      // then one more pass through the loop's poll phase (setImmediate runs
+      // after it, where a timer runs before), accepts every one still there.
+      await new Promise((resolve) => setTimeout(resolve, BACKLOG_GRACE_MS));
+      await new Promise((resolve) => setImmediate(resolve));
+
+      // The server reports itself closed once it has counted its last
+      // connection out, which is before that connection's own 'close' --
+      // its handle closes a loop turn later -- so the connections are
+      // waited for too, or a drain could end with a render's last bytes
+      // still unwritten.
+      const finished = new Promise((resolve) => server.close(() => resolve())).then(() =>
+        Promise.all(
+          [...connections].map((socket) => new Promise((resolve) => socket.once('close', resolve))),
+        ),
+      );
+
+      let timer;
+      const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('late'), timeoutMs);
+      });
+      if ((await Promise.race([finished, late])) === 'late') {
+        for (const socket of connections) socket.destroy();
+        await finished;
+      }
+      clearTimeout(timer);
+    })();
+
+    return draining;
+  };
+
+  return {
+    server,
+    socketPath,
+    codec: codec.name,
+    mode: process.env.NODE_ENV ?? 'development',
+    drain,
+    close: () => drain(),
+    /** Renders open now, and renders finished since it started. */
+    stats: () => ({ ...state }),
+  };
+}
+
+/**
+ * Opens a socket's directory, made 0700, to the group its socket is shared
+ * with: 0750, so PHP's user can find the socket and no one else can look.
+ * Given to the group first, then opened to it.
+ */
+export async function shareDirectory(directory, socketGroup) {
+  await fs.chown(directory, -1, socketGroup);
+  await fs.chmod(directory, 0o750);
+}
+
+function handleConnection(socket, app, maxFrameBytes, codec, state) {
+  const reader = new FrameReader(maxFrameBytes, codec);
+  // write() says when the socket's buffer is full, and drained() when it has
+  // room again, so the session reads the render no faster than PHP takes it.
+  const write = (bytes) => (socket.destroyed ? true : socket.write(bytes));
+  const drained = () =>
+    new Promise((resolve) => {
+      if (socket.destroyed || !socket.writableNeedDrain) {
+        resolve();
+        return;
+      }
+      const done = () => {
+        socket.off('drain', done);
+        socket.off('close', done);
+        resolve();
+      };
+      socket.on('drain', done);
+      socket.on('close', done);
+    });
+
+  // One session per connection: PHP opens a socket per request, so there is no
+  // state to carry between renders.
+  const session = new RenderSession(write, app, { codec, maxFrameBytes, drained });
+  let rendering = null;
+  let checked = false;
+  let greeted = false;
+
+  // Counted from the render frame until the connection closes, which is
+  // when PHP has everything: a drain that waited only for the render to
+  // settle could exit with its last chunks still in the socket's buffer.
+  let counted = false;
+  socket.on('close', () => {
+    if (counted) state.inFlight--;
+  });
+
+  socket.on('data', (chunk) => {
+    let frames;
+    try {
+      frames = reader.push(new Uint8Array(chunk));
+    } catch (error) {
+      logLine('warning', 'framing error', {}, error);
+      socket.destroy();
+      return;
+    }
+
+    for (const frame of frames) {
+      let type;
+      try {
+        type = assertFromPhp(frame);
+      } catch (error) {
+        logLine('warning', 'protocol violation', {}, error);
+        socket.destroy();
+        return;
+      }
+
+      if (type === FRAME.HELLO) {
+        // First on its connection, and once: PHP asks before it sends
+        // anything, and reads who answered from the kernel's credentials
+        // on the reply. Later, it would be a reply to nothing PHP waits on.
+        if (greeted || rendering || checked) {
+          logLine('warning', 'a hello frame arrived on a connection already in use');
+          socket.destroy();
+          return;
+        }
+        greeted = true;
+        write(encodeFrame({ t: FRAME.READY }, maxFrameBytes, codec));
+        continue;
+      }
+
+      if (type === FRAME.HEALTH) {
+        // Alone on its connection: a health check that rode along with a
+        // render could report on a render it was itself part of.
+        if (rendering || checked) {
+          logLine('warning', 'a health frame arrived on a connection already in use');
+          socket.destroy();
+          return;
+        }
+        checked = true;
+        write(
+          encodeFrame(
+            { t: FRAME.HEALTHY, pid: process.pid, inFlight: state.inFlight, served: state.served },
+            maxFrameBytes,
+            codec,
+          ),
+        );
+        socket.end();
+        return;
+      }
+
+      if (type === FRAME.RENDER || type === FRAME.FRAGMENT || type === FRAME.MAIL) {
+        if (rendering || checked) {
+          logLine('warning', 'a second render frame arrived on one connection');
+          socket.destroy();
+          return;
+        }
+        counted = true;
+        state.inFlight++;
+        rendering = (type === FRAME.MAIL ? session.mail(frame) : session.render(frame)).then(
+          () => {
+            // Served only where PHP was there to take it: a render
+            // abandoned when its socket closed settles too.
+            if (!socket.destroyed) state.served++;
+            socket.end();
+          },
+          (error) => {
+            logLine('error', 'unhandled render failure', { request_id: requestIdOf(frame) }, error);
+            socket.destroy();
+          },
+        );
+        continue;
+      }
+
+      if (type === FRAME.RESULT) {
+        try {
+          session.settle(normalizeResults(frame.r));
+        } catch (error) {
+          // As for minted below: thrown here, it is outside any try and
+          // takes the process -- every render on it -- down with this one.
+          logLine('warning', 'malformed result frame', {}, error);
+          socket.destroy();
+          return;
+        }
+        continue;
+      }
+
+      if (type === FRAME.MINTED) {
+        // Not a reply at all, so it settles no batch: each minted frame is
+        // taken as the answer to the oldest mint frame still waiting, and
+        // boundaries it leaves out are refused.
+        if (!Array.isArray(frame.m)) continue;
+        try {
+          session.settleMints(normalizeMints(frame.m));
+        } catch (error) {
+          // Thrown inside socket.on('data'), which is outside any try the
+          // caller has, so an unchecked destructure here takes the process
+          // down. PHP validates its side; this is the symmetric half.
+          logLine('warning', 'malformed minted frame', {}, error);
+          socket.destroy();
+          return;
+        }
+      }
+    }
+  });
+
+  // BOTH clients. The mint client was left out, and RenderSession's own
+  // finally cannot cover it: that finally runs when the render settles, and
+  // the render is awaiting the mint promise -- so a refused mint left the
+  // session, the React tree and the promise alive for the life of the
+  // process, once per request to a deferred page.
+  //
+  // And the render itself: the pump read on into a destroyed socket and
+  // React rendered the page to its end for no one. abort() cancels the
+  // app's stream and fires the signal its entries hand React.
+  socket.on('close', () => {
+    session.abort('socket_closed');
+    session.client?.close('socket_closed');
+    session.mints?.close('socket_closed');
+  });
+}
+
+/**
+ * MessagePack gives back BigInt for int64 and Uint8Array for bin. Query results
+ * are handed to React, so they are normalized to ordinary JS values first.
+ */
+/** @param {unknown} tokens */
+function normalizeMints(tokens) {
+  if (!Array.isArray(tokens)) return [];
+
+  return tokens.map((entry) => {
+    if (entry === null || typeof entry !== 'object') {
+      throw new TypeError('A minted entry must be an object.');
+    }
+
+    return { id: Number(entry.id), token: entry.token };
+  });
+}
+
+function normalizeResults(results) {
+  if (!Array.isArray(results)) return [];
+
+  return results.map((result) => {
+    if (result === null || typeof result !== 'object') {
+      throw new TypeError('A result entry must be an object.');
+    }
+
+    return { ...result, id: Number(result.id) };
+  });
+}

package/src/socket-group.js

@@ -0,0 +1,72 @@
+// The group a renderer run as a user of its own shares its socket with
+// (ADR 0028).
+//
+// A renderer's socket is 0600: only its own user may connect, which is PHP
+// when both run as one user. Run as a user of its own -- the stronger
+// boundary -- the renderer must let PHP connect, and no one else: its
+// socket is made 0660 in a group of exactly the two, and its directory
+// 0750 in the same group. Which group is the deployment's to say, and to
+// keep to those two members; the renderer checks only that it is in it,
+// since it cannot give a socket to a group it is not in.
+
+import fs from 'node:fs';
+
+/**
+ * The gid `given` names: a number, or a group's name looked up in
+ * /etc/group -- where Linux keeps the groups a deployment makes, and where
+ * a group only a directory service knows of is not, so its number is
+ * asked for instead.
+ *
+ * @param {string} given
+ * @param {{ groupFile?: string, gids?: number[] }} [options] `gids` are the
+ *        groups this process is in: its own by default
+ * @returns {number}
+ */
+export function resolveSocketGroup(given, { groupFile = '/etc/group', gids = processGroups() } = {}) {
+  let gid;
+  if (/^[0-9]{1,10}$/.test(given)) {
+    gid = Number(given);
+  } else if (/^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/.test(given)) {
+    gid = groupNamed(given, groupFile);
+    if (gid === null) {
+      throw new Error(
+        `--socket-group names '${given}', and ${groupFile} has no such group; give the group's number instead.`,
+      );
+    }
+  } else {
+    throw new Error(`--socket-group must be a group's name or number; got '${given}'.`);
+  }
+
+  if (gid === 0) {
+    throw new Error("--socket-group names root's group; the socket is shared with a group of its own.");
+  }
+  if (!gids.includes(gid)) {
+    throw new Error(
+      `--socket-group names group ${gid}, and this process is not in it, so it cannot give its socket to it. ` +
+        'Start the renderer in that group (systemd Group=, sudo -g).',
+    );
+  }
+
+  return gid;
+}
+
+/** Every group this process is in: its effective one and the rest. */
+function processGroups() {
+  if (typeof process.getegid !== 'function') return [];
+  return [process.getegid(), ...(process.getgroups?.() ?? [])];
+}
+
+/** The gid of the group named `name` in `groupFile`, or null. */
+function groupNamed(name, groupFile) {
+  let text;
+  try {
+    text = fs.readFileSync(groupFile, 'utf8');
+  } catch {
+    return null;
+  }
+  for (const line of text.split('\n')) {
+    const [entry, , gid] = line.split(':');
+    if (entry === name && /^[0-9]{1,10}$/.test(gid ?? '')) return Number(gid);
+  }
+  return null;
+}