create-pmos 0.134.0 → 0.135.0

package/workspace/lib/vendor/workspace/lib/sink.js

@@ -1,321 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-/* sink.js — the ONE place the append-only ledger discipline lives.
- *
- * ── WHY THIS FILE EXISTS ────────────────────────────────────────────────────────────────────────
- * `record-eval.js` was PMOS's first validated writer. Three independent passes found four defects in
- * it, and all four were fixed IN THAT FILE:
- *
- *   1. the sink was a caller-supplied allowlist   -> a caller could name its own destination
- *   2. the file was opened before validation      -> N refused writes leaked N descriptors to EMFILE
- *   3. a refused write still created the sink     -> refusing to write left the file behind
- *   4. the symlink check was a path-level stat    -> a hardlink walked straight through it
- *
- * Two writers built afterwards inherited the fixes BY HAND, and each inheritance read as evidence
- * that the pattern was holding. It was not holding — it was propagating FORWARD ONLY. The two
- * writers that already existed when the defects were found were never revisited, because the process
- * asks "does the new thing follow the rule?" and never "where else does this rule already live?"
- *
- * Measured by attempted write on 2026-08-04:
- *
- *   scripts/work-item.js     -> wrote 198 bytes through a symlink into a decoy
- *   scripts/verify-queue.js  -> the same, AND wrote 202 bytes into a fresh tmpdir, because its
- *                               allowlist compared `path.basename` alone. A basename is not a
- *                               location; every directory on disk has one.
- *
- * Both are merged, PM-accepted, and load-bearing for D65 steps 1 and 2. So the discipline moves here
- * and the writers call it. One wrong place that every assertion points at beats five where three
- * happen to be right.
- *
- * ── THE RULE, STATED ONCE ───────────────────────────────────────────────────────────────────────
- *   Resolve before allowing.  Validate before opening.  Write to the descriptor that was vetted.
- *
- * The third clause is the one that looks redundant and is not. A path checked and then re-opened by
- * path is two operations on two objects: whatever was approved may not be what gets written. The fd
- * IS the approval, so it is what the caller must be handed.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-/**
- * THE `ForbiddenWrite`. One class, exported, re-exported by every writer that uses this guard.
- *
- * There were five of these — one per writer that had a guard at all — and that is not a cosmetic duplication. Callers and
- * assertions tell "refused on purpose" from "crashed" with `instanceof`, so a guard throwing its own
- * private copy makes every one of those checks silently false: `scripts/tests/work-item.sh` reported
- * `threw ForbiddenWrite, want ForbiddenWrite` on seventeen assertions the moment this module started
- * throwing a second class with the same name. A refusal nobody can recognise as a refusal is not one.
- *
- * `detail` is always set (null when absent) rather than conditionally attached, because a property
- * that sometimes exists is a second shape for callers to handle.
- */
-class ForbiddenWrite extends Error {
-  constructor(message, detail) {
-    super(message);
-    this.name = 'ForbiddenWrite';
-    this.detail = detail || null;
-  }
-}
-
-/** Resolve a path through its real directory. Kept separate so the sink and the target are compared
- *  the same way — comparing a resolved target against an unresolved sink is a mismatch by
- *  construction, and would refuse every legitimate write on a machine where /tmp is a symlink. */
-function resolveThrough(p) {
-  return path.join(fs.realpathSync(path.dirname(path.resolve(p))), path.basename(p));
-}
-
-/**
- * Build a guard bound to ONE sink.
- *
- * @param {object} spec
- * @param {string} spec.sink     absolute path of the only file this guard will ever open.
- * @param {string} spec.what     noun for error messages, e.g. 'work-item events'.
- * @returns {{ open: function, sinkPath: function, __setSinkForTests: function }}
- *
- * The sink is a CONSTRUCTION-TIME constant, never an argument to `open`. That is defect 1 of the
- * original four, and re-admitting it as "just a parameter" is how it would come back.
- */
-function createSinkGuard(spec) {
-  if (!spec || typeof spec.sink !== 'string' || !spec.sink) {
-    throw new ForbiddenWrite('a sink guard needs a declared `sink` path — refused (fail-closed)');
-  }
-  const what = spec.what || 'records';
-  const declared = spec.sink;
-  let overrideForTests = null;
-
-  /* A seam, not a door. Gated so it cannot be reached in a production process even if something
-   * calls it — the point of A4 is that no code path lets a caller choose the destination. */
-  function __setSinkForTests(p) {
-    /* An explicit allowed set. `!process.env.PMOS_TEST` treats the STRING '0' as truthy, so
-     * PMOS_TEST=0 — the natural way an operator turns test mode OFF — OPENED the production sink
-     * override instead of closing it. A flag whose "off" value means "on" is worse than no flag. */
-    const on = (v) => v === '1' || v === 'true' || v === 'yes';
-    if (process.env.NODE_ENV !== 'test' && !on(process.env.PMOS_TEST)) {
-      throw new ForbiddenWrite('__setSinkForTests is a test seam — set NODE_ENV=test or PMOS_TEST=1 to use it');
-    }
-    overrideForTests = p;
-  }
-
-  const sinkPath = () => overrideForTests || declared;
-
-  /**
-   * Pre-flight: validate the record and confirm the target RESOLVES to the sink — without opening
-   * anything. For callers that want to ask "would this be permitted?" without a side effect.
-   *
-   * NOT AUTHORITATIVE, and the gap is deliberate rather than an oversight. Whether the sink is a
-   * symlink or carries a second hard link cannot be established without a descriptor, and a `lstat`
-   * here would answer about a path that may differ from the file eventually opened — which is the
-   * check-then-write race this module exists to close. `open` is the authority; this is a courtesy.
-   * The suite asserts the difference: a symlinked sink passes `check` and is refused by `open`.
-   */
-  function check(targetPath, validate) {
-    if (typeof targetPath !== 'string' || !targetPath) {
-      throw new ForbiddenWrite(`no target path supplied for ${what} — refused (fail-closed)`);
-    }
-    if (typeof validate === 'function') {
-      const v = validate();
-      if (!v || !v.ok) {
-        const errs = (v && v.errors) || ['invalid'];
-        throw new ForbiddenWrite(`invalid ${what} — refused: ${errs.join('; ')}`, { errors: errs });
-      }
-    }
-    let resolved;
-    try { resolved = resolveThrough(targetPath); }
-    catch { throw new ForbiddenWrite(`the sink directory does not resolve for '${targetPath}' — refused (fail-closed)`); }
-    let sinkResolved = sinkPath();
-    try { sinkResolved = resolveThrough(sinkPath()); } catch { /* not created yet */ }
-    if (resolved !== sinkResolved) {
-      throw new ForbiddenWrite(
-        `${what} are written only to ${sinkResolved}; '${targetPath}' resolves to '${resolved}'`,
-        { targetPath, resolved, sink: sinkResolved });
-    }
-    return true;
-  }
-
-  /**
-   * Vet `targetPath` against the declared sink and return a descriptor open for append.
-   *
-   * The caller MUST close it. Everything that can refuse, refuses before the file is opened, so a
-   * refusal creates nothing and leaks nothing.
-   *
-   * @param {string} targetPath   where the caller believes it is writing.
-   * @param {function} [validate] returns { ok, errors } — runs BEFORE the open (defects 2 and 3).
-   * @returns {number} a vetted file descriptor.
-   */
-  function open(targetPath, validate) {
-    if (typeof targetPath !== 'string' || !targetPath) {
-      throw new ForbiddenWrite(`no target path supplied for ${what} — refused (fail-closed)`);
-    }
-
-    /* BEFORE the open. Ordering is the whole of defects 2 and 3: validating after opening leaks a
-     * descriptor per refusal, and O_CREAT means the refused write has already made the file. */
-    if (typeof validate === 'function') {
-      const v = validate();
-      if (!v || !v.ok) {
-        const errs = (v && v.errors) || ['invalid'];
-        throw new ForbiddenWrite(`invalid ${what} — refused: ${errs.join('; ')}`, { errors: errs });
-      }
-    }
-
-    let resolved;
-    try {
-      resolved = resolveThrough(targetPath);
-    } catch {
-      throw new ForbiddenWrite(`the sink directory does not resolve for '${targetPath}' — refused (fail-closed)`);
-    }
-    let sinkResolved = sinkPath();
-    try { sinkResolved = resolveThrough(sinkPath()); } catch { /* not created yet — compare literally */ }
-
-    /* A RESOLVED comparison, not a basename one. `verify-queue.js` compared basenames and therefore
-     * accepted every directory on disk that happened to contain the right filename. */
-    if (resolved !== sinkResolved) {
-      throw new ForbiddenWrite(
-        `${what} are written only to ${sinkResolved}; '${targetPath}' resolves to '${resolved}'`,
-        { targetPath, resolved, sink: sinkResolved });
-    }
-
-    let fd;
-    try {
-      fd = fs.openSync(
-        resolved,
-        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND
-          | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK,
-        0o644);
-    } catch (e) {
-      /* O_NOFOLLOW turns "the sink is a symlink" into ELOOP here rather than a silent write to
-       * wherever it pointed. That is defect 4, and it is refused at open rather than by a stat that
-       * a hardlink does not answer.
-       *
-       * O_NONBLOCK is not about performance. Opening a FIFO for writing BLOCKS until a reader
-       * arrives, so a named pipe left at the sink path hangs the writer forever — found by the
-       * assertion below, which hung this suite past its timeout instead of failing. A refusal that
-       * never returns is worse than a wrong answer: nothing reports it and nothing times it out.
-       * With O_NONBLOCK the same case returns ENXIO immediately and lands in the refusal path, and
-       * on a regular file the flag does nothing at all. */
-      throw new ForbiddenWrite(
-        `cannot open the ${what} ledger at '${targetPath}' safely (${e.code || e.message}) — refused (fail-closed)`,
-        { code: e.code });
-    }
-
-    try {
-      /* fstat on the FD, not stat on the path: for the FINAL component this genuinely closes the
-       * check-then-open race — an independent pass swapped the target inside the resolve→open window
-       * with perfect timing and got ELOOP, nlink=2 and a refusal every time.
-       *
-       * It does NOT cover the PARENT directory. `resolveThrough` realpaths the directory and
-       * `openSync` then re-walks that resolved path, so a local process able to rename the sink's
-       * parent and drop a directory symlink in its place inside that window can redirect the append
-       * — measured, 195 bytes into a foreign directory. That needs a concurrently-racing local
-       * attacker with write access to the parent, a strictly larger capability than the symlink
-       * defect this module was built to fix, so it is stated rather than claimed away. Closing it
-       * properly needs openat-style descent, which Node does not expose. The header's "the fd IS the
-       * approval" is true of the file, not of the path walked to reach it. */
-      const st = fs.fstatSync(fd);
-      if (!st.isFile()) {
-        throw new ForbiddenWrite(`'${targetPath}' is not a regular file — refused (fail-closed)`);
-      }
-      if (st.nlink !== 1) {
-        throw new ForbiddenWrite(
-          `'${targetPath}' has ${st.nlink} hard links; a ledger with a second name is not one this ` +
-          'writer controls — refused (fail-closed)', { nlink: st.nlink });
-      }
-    } catch (e) {
-      fs.closeSync(fd);
-      throw e;
-    }
-
-    return fd;
-  }
-
-  /**
-   * The whole write, start to finish: vet, append one JSON line, close. Callers should prefer this
-   * over `open` — it is the shape that cannot forget to close, and every existing writer's append is
-   * exactly one line.
-   */
-  function appendLine(targetPath, record, validate) {
-    const fd = open(targetPath, validate);
-    const line = JSON.stringify(record) + '\n';
-    const want = Buffer.byteLength(line);
-    try {
-      /* THE RETURN VALUE IS NOT OPTIONAL. This was `fs.writeSync(fd, line)` with the result
-       * discarded, which reports a SHORT WRITE as success. Forced on a 64K tmpfs: a normal-shaped
-       * record returned true having appended a 3901-byte fragment with no trailing newline, and the
-       * next append CONCATENATED onto it — so one ENOSPC destroys two records and leaves a single
-       * line that no reader can parse. This is the append-only system of record, every reader
-       * JSON.parses line by line, and all six writers route through this one call.
-       *
-       * Loop, because a partial write is not necessarily an error — then verify the total. A torn
-       * tail is worse than a refused write, so if the bytes did not all land, say so loudly rather
-       * than returning true over a corrupted ledger. */
-      /* The size BEFORE this append, taken from the vetted fd. This is what makes the failure path a
-       * real refusal instead of a report: if the write tears, the file is truncated back to here and
-       * the ledger is left exactly as it was found. `nlink === 1` was already proven above, so no
-       * other name for this file exists and the rollback cannot reach anyone else's data. */
-      const before = fs.fstatSync(fd).size;
-      const buf = Buffer.from(line, 'utf8');
-      let written = 0;
-      let cause = null;
-      try {
-        while (written < want) {
-          const n = fs.writeSync(fd, buf, written, want - written);
-          if (!(n > 0)) break;           // no progress: stop rather than spin
-          written += n;
-        }
-      } catch (e) {
-        /* ENOSPC does NOT arrive as a short write. Measured on a full tmpfs: the first writeSync
-         * short-writes 376 of 440 bytes with no error and the SECOND one throws — so a version that
-         * only checked `written !== want` never reached its own error path, and a raw Error escaped
-         * with name 'Error'. Everything in this repo tells a deliberate refusal from a crash with
-         * `instanceof ForbiddenWrite` (workspace/test.js:1772 checks e.name), so an unwrapped throw
-         * on the worst outcome this module has is the one place that signal must not be missing. */
-        cause = e;
-      }
-
-      if (cause || written !== want) {
-        /* THE ROLLBACK MUST NOT DESTROY SOMEONE ELSE'S RECORD, and the first version did.
-         *
-         * It called ftruncateSync(fd, before) unconditionally. `before` was measured at the top of
-         * this function, so ANY append by another process in between — a complete, successful,
-         * returned-true append — was inside the range being truncated away. Measured by an
-         * independent pass across 5 of 5 rounds: records whose write returned `true` were missing
-         * from disk afterwards, and the ledger was NUL-padded. A rollback that eats a committed
-         * record is worse than the torn line it was added to prevent.
-         *
-         * O_APPEND makes the arithmetic decidable: our bytes are the last `written` of the file if
-         * and only if nobody else appended. So truncate ONLY when the file is exactly the size our
-         * own write would have made it. Otherwise the tail is not ours to remove, and the honest
-         * outcome is to say the ledger is torn rather than to fix it by deleting a stranger's data. */
-        let rolledBack = false;
-        let intervened = false;
-        try {
-          const now = fs.fstatSync(fd).size;
-          if (now === before + written) { fs.ftruncateSync(fd, before); rolledBack = true; }
-          else intervened = true;          // another writer appended; the tail is not ours
-        } catch { /* reported below */ }
-
-        const detail = { written, want, before, rolledBack, intervened, code: cause && cause.code };
-        throw new ForbiddenWrite(
-          `partial append to the ${what} ledger: ${written} of ${want} bytes landed` +
-          (cause ? ` (${cause.code || cause.message})` : '') + '. ' +
-          (rolledBack
-            ? 'The ledger was truncated back to its pre-write size, so nothing was written and the ' +
-              'next append will not concatenate onto a fragment.'
-            : intervened
-              ? 'NOT ROLLED BACK ON PURPOSE — another writer appended while this write was failing, ' +
-                'so the bytes at the end of the file are not this one\'s to remove. The ledger holds ' +
-                'a torn fragment that must be repaired by hand; truncating it here would have ' +
-                'deleted a record that committed successfully.'
-              : 'THE ROLLBACK ALSO FAILED — the ledger now ends in a torn line with no trailing ' +
-                'newline, and the next append WILL concatenate onto it, destroying a second record. ' +
-                'Repair it by hand before writing again.'),
-          detail);
-      }
-    } finally { fs.closeSync(fd); }
-    return true;
-  }
-
-  return { check, open, appendLine, sinkPath, __setSinkForTests };
-}
-
-module.exports = { createSinkGuard, ForbiddenWrite, resolveThrough };