flowviant 0.102.2 → 0.104.0

package/bin/lib/preview.mjs

@@ -30,23 +30,12 @@
 
 import { spawn, execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import {
-  readFileSync,
-  writeFileSync,
-  renameSync,
-  existsSync,
-  mkdirSync,
-  chmodSync,
-  openSync,
-  closeSync,
-  statSync,
-  rmSync,
-  unlinkSync,
-} from 'node:fs';
+import { writeFileSync, renameSync, existsSync, mkdirSync, chmodSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir, platform, arch } from 'node:os';
 import { startAuthProxy } from './authproxy.mjs';
 import { forgetInfraPid, isListening, noteInfraPid, originFor } from './listeners.mjs';
+import { forgetPreviewPid, recordPreviewPid } from './previewRegistry.mjs';
 
 // ── cloudflared: pinned, verified, or not fetched at all ───────────────────
 
@@ -152,265 +141,6 @@ async function ensureCloudflared(log) {
  */
 export const TUNNEL_RE = /https:\/\/(?!api\.)[a-z0-9-]+\.trycloudflare\.com(?![a-z0-9.-])/i;
 
-// ── Orphan reaping ─────────────────────────────────────────────────────────
-// cloudflared is detached so we can kill its whole group — which also means it
-// SURVIVES an ungraceful daemon death (SIGKILL, crash, box sleep), leaving a
-// public hostname pointed at a worktree with nobody minding it. We record each
-// group's pid + a signature and reap ours at the next start.
-//
-// The registry is a read-modify-write over one file in a directory that TWO
-// daemons can legitimately share (the 0.51.2 instance lock is keyed on a
-// CREDENTIAL, so two daemons serving two different projects are fine and both
-// write here). It was unlocked, written back when previews were serial. A lost
-// entry is precisely the case reaping exists for.
-
-const FLOWVIANT_DIR = join(homedir(), '.flowviant');
-const PREVIEW_REGISTRY = join(FLOWVIANT_DIR, 'previews.json');
-const REGISTRY_LOCK = join(FLOWVIANT_DIR, 'previews.lock');
-const LOCK_STALE_MS = 15_000;
-
-/** Best-effort exclusive lock. Returns a release function; on failure returns
- *  null and the caller proceeds unlocked — losing an entry is bad, but refusing
- *  to record one at all is worse. */
-function acquireLock() {
-  try {
-    mkdirSync(FLOWVIANT_DIR, { recursive: true });
-  } catch {
-    return null;
-  }
-  for (let i = 0; i < 30; i++) {
-    try {
-      const fd = openSync(REGISTRY_LOCK, 'wx');
-      closeSync(fd);
-      return () => {
-        try {
-          unlinkSync(REGISTRY_LOCK);
-        } catch {
-          /* already released */
-        }
-      };
-    } catch {
-      // Held — unless it was left behind by something that died holding it.
-      try {
-        if (Date.now() - statSync(REGISTRY_LOCK).mtimeMs > LOCK_STALE_MS) {
-          unlinkSync(REGISTRY_LOCK);
-          continue;
-        }
-      } catch {
-        continue;
-      }
-      // Spin briefly. This lock is held for one file write.
-      const until = Date.now() + 20;
-      while (Date.now() < until) {
-        /* busy-wait: 20ms, 30 times, then give up entirely */
-      }
-    }
-  }
-  return null;
-}
-
-function readRegistry() {
-  try {
-    const v = JSON.parse(readFileSync(PREVIEW_REGISTRY, 'utf8'));
-    return Array.isArray(v) ? v : [];
-  } catch {
-    return [];
-  }
-}
-
-/** Atomic: write a sibling temp file and rename over the target, so a reader
- *  never sees a half-written array. */
-function writeRegistry(list) {
-  try {
-    mkdirSync(FLOWVIANT_DIR, { recursive: true });
-    const tmp = `${PREVIEW_REGISTRY}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify(list));
-    renameSync(tmp, PREVIEW_REGISTRY);
-  } catch {
-    /* best-effort */
-  }
-}
-
-function mutateRegistry(fn) {
-  const release = acquireLock();
-  try {
-    writeRegistry(fn(readRegistry()));
-  } finally {
-    release?.();
-  }
-}
-
-/**
- * WHEN a process started, as the kernel reports it — or null when this box
- * will not say. Paired with a pid it names ONE process: a pid alone is
- * recycled, and the owner check below trusted signal 0 on a bare pid.
- */
-export function processStartOf(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return null;
-  if (platform() === 'linux') {
-    try {
-      const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
-      // Field 22 (starttime), counted after the LAST ')' — the comm field in
-      // parentheses may itself hold spaces and parentheses.
-      const rest = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
-      return rest[19] ? `l:${rest[19]}` : null;
-    } catch {
-      return null;
-    }
-  }
-  if (platform() === 'darwin') {
-    try {
-      const out = execFileSync('ps', ['-p', String(pid), '-o', 'lstart='], {
-        encoding: 'utf8',
-        timeout: 5_000,
-        stdio: ['ignore', 'pipe', 'ignore'],
-      }).trim();
-      return out ? `d:${out}` : null;
-    } catch {
-      return null;
-    }
-  }
-  return null;
-}
-
-/** Signal-0 liveness (EPERM = alive and not ours), for the OWNER check below. */
-function processAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (e) {
-    return e.code === 'EPERM';
-  }
-}
-
-function recordPreviewPid(pid, sig) {
-  if (!pid) return;
-  // `owner` is the DAEMON that spawned it. The registry is shared by design —
-  // two daemons serving two projects both write here — so without an owner a
-  // starting daemon reaped its PEER's live tunnels: killed them, wiped their
-  // entries, and the peer kept heartbeating a URL that 530s (its probe watches
-  // the origin port, which was still alive).
-  //
-  // `ownerStart` pins the owner to ONE process (audit 2026-09-24). A daemon that
-  // is SIGKILLed with a share open leaves cloudflared up; if its pid is reused
-  // by the next start — any process, another user's included, since EPERM
-  // counts as alive — a pid-only check read the entry as a live peer's and
-  // skipped it forever, leaving a public hostname aimed at a dead gate's
-  // ephemeral port for anything that binds it next.
-  const ownerStart = processStartOf(process.pid);
-  mutateRegistry((list) => [...list, { pid, sig, owner: process.pid, ...(ownerStart ? { ownerStart } : {}) }]);
-}
-
-function forgetPreviewPid(pid) {
-  if (!pid) return;
-  mutateRegistry((list) => list.filter((e) => e.pid !== pid));
-}
-
-/**
- * Only kill a pid we can VERIFY is still one of ours — its command line must
- * still contain the signature we stored. A reused pid belonging to something
- * unrelated won't match, so we never kill a stranger.
- *
- * MACOS READS IT THROUGH `ps`, because "Linux-only, elsewhere just clear the
- * registry" was the worst of both. A macOS daemon killed ungracefully leaves
- * cloudflared running — it is spawned detached — so the public hostname keeps
- * resolving to this machine while the gate dies with the daemon. The reaper
- * then verified nothing, killed nothing, and DELETED the entry, so no later run
- * could ever find that process. The tunnel served 502 until anything else on
- * the box bound the gate's old port, which `startAuthProxy` obtained with
- * `listen(0)` and is therefore squarely inside the kernel's ephemeral reuse
- * pool — at which point a live public hostname forwarded straight to an
- * unrelated local service with no gate, no password and no grant check. Exactly
- * what this file's header says the reap exists to prevent.
- *
- * Three states, not two: `true` (ours), `false` (verified NOT ours, or gone),
- * and `null` (we could not look — the caller keeps the record rather than
- * dropping it).
- */
-function stillOurs(pid, sig) {
-  if (typeof sig !== 'string' || sig.length === 0) return false;
-  if (platform() === 'linux') {
-    try {
-      const cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ');
-      return cmd.includes(sig);
-    } catch {
-      return false; // process gone / unreadable
-    }
-  }
-  if (platform() === 'darwin') {
-    try {
-      const cmd = execFileSync('ps', ['-p', String(pid), '-o', 'command='], {
-        encoding: 'utf8',
-        timeout: 5_000,
-      });
-      return cmd.includes(sig);
-    } catch {
-      // `ps` exits non-zero when the pid is gone — which is a real answer.
-      return false;
-    }
-  }
-  // Windows: no way to check from here. UNKNOWN, never "not ours" — see the
-  // caller, which keeps the record so a later run on a platform that can look
-  // is still able to.
-  return null;
-}
-
-/** Reap tunnel process groups left behind by a previously-crashed daemon.
- *  Call once at daemon startup, before any work begins.
- *
- *  ORPHANS ONLY: an entry whose owning daemon is STILL ALIVE belongs to a
- *  peer serving another project (or to the process we are replacing, whose
- *  own teardown handles it) — killing those and wiping their entries was a
- *  peer daemon's startup silently breaking every live share on the box. Only
- *  the entries this pass handled are removed; a peer's records survive. */
-/** Is the daemon that recorded an entry still the process at that pid? With
- *  a recorded start time, only when the pid's start time still matches (a
- *  recycled pid is an orphaned entry); where this box cannot report a start
- *  time now, or the entry predates the field, signal 0 is all there is. */
-function ownerStillRunning(owner, ownerStart) {
-  if (!processAlive(owner)) return false;
-  if (typeof ownerStart !== 'string') return true;
-  const now = processStartOf(owner);
-  return now == null ? true : now === ownerStart;
-}
-
-export function reapOrphanPreviews(log) {
-  const list = readRegistry();
-  if (list.length === 0) return;
-  let killed = 0;
-  const handled = new Set();
-  for (const { pid, sig, owner, ownerStart } of list) {
-    if (Number.isInteger(owner) && owner !== process.pid && ownerStillRunning(owner, ownerStart)) continue;
-    const ours = stillOurs(pid, sig);
-    /**
-     * THE RECORD OUTLIVES A REAP THAT COULD NOT LOOK. `handled.add` ran BEFORE
-     * this check, so an entry was dropped whether or not anything was killed —
-     * and on any platform `stillOurs` could not read, that deleted the only
-     * trace of a tunnel still serving the public internet. Kept on `null`
-     * (unknown); removed on `true` (we killed it) and on `false` (the process
-     * is gone, or the pid now belongs to somebody else and the entry is stale
-     * either way).
-     */
-    if (ours === null) continue;
-    handled.add(pid);
-    if (!ours) continue;
-    try {
-      process.kill(-pid, 'SIGKILL'); // whole group
-      killed++;
-    } catch {
-      try {
-        process.kill(pid, 'SIGKILL');
-        killed++;
-      } catch {
-        /* already gone */
-      }
-    }
-  }
-  if (handled.size) mutateRegistry((cur) => cur.filter((e) => !handled.has(e.pid)));
-  if (killed) log?.(`reaped ${killed} orphaned preview tunnel${killed === 1 ? '' : 's'} from a previous run.`);
-}
-
 // ── The one thing this file does ───────────────────────────────────────────
 
 /** How long we wait for cloudflared to hand us a hostname. */

package/bin/lib/previewFramePolicy.mjs

@@ -0,0 +1,112 @@
+/**
+ * THE FRAME IS THE APP'S AND ONLY THE APP'S — the preview gate's frame rules,
+ * as pure functions over headers. Split out of `authproxy.mjs` (SOLID SRP,
+ * 2026-09-26): which browser may frame a share, and with which cookie
+ * attribute, changes for browser-engine reasons that have nothing to do with
+ * how the gate supervises sockets, so it gets one home the HTTP path imports
+ * and a test that reads headers in and headers out with no server running.
+ *
+ * Two rules live here (header rules 4a and 4b in `authproxy.mjs`):
+ *
+ *  (a) THE COOKIE. `SameSite=Lax` is kept for a top-level visit — it is the
+ *      CSRF boundary and works in every browser ever shipped. A FRAMED
+ *      navigation (`Sec-Fetch-Dest: iframe`) instead gets `SameSite=None;
+ *      Partitioned` (CHIPS): partitioning keys the cookie to the top-level
+ *      site that framed it, so evil.com framing this hostname gets its OWN
+ *      empty jar, never the viewer's grant — which is why None here is not
+ *      the CSRF hole it would be unpartitioned. Branching on Sec-Fetch-Dest
+ *      rather than always sending both attributes matters: Safari 18.5–26.1
+ *      DROPPED any Set-Cookie carrying `Partitioned` outright, so stamping it
+ *      unconditionally would break the working top-level path on those
+ *      builds. A browser too old to send Sec-Fetch-Dest gets Lax and the
+ *      frame fails exactly as it always did — Open remains the escape. The
+ *      backstop for the browsers that ignore `Partitioned` is
+ *      `crossSiteAbuse` in `previewGatePolicy.mjs`.
+ *  (b) THE FRAME POLICY. In grant mode the forwarded response's frame policy
+ *      is REWRITTEN to `frame-ancestors 'self' <app origin>` (origin taken
+ *      from `authorizeUrl`, the one app fact this gate already holds). That
+ *      permits exactly ONE cross-origin framer — the app the viewer is
+ *      already authenticated to — instead of switching clickjacking
+ *      protection off for everyone; enforced `frame-ancestors` outranks
+ *      `X-Frame-Options` in every current engine, and the stripped XFO is
+ *      the belt-and-braces for the rest. Password-only mode rewrites
+ *      NOTHING: there is no app origin to allow and no cookie that could
+ *      authenticate a frame, so the origin's own policy stands verbatim.
+ */
+
+/** The one app fact this gate holds: the origin allowed to frame us. Derived
+ *  from `authorizeUrl` (server-built from PUBLIC_APP_URL) rather than a new
+ *  wire field, so an older server changes nothing and no floor is needed.
+ *  Null when the gate runs password-only (`grants` false) or the URL does not
+ *  parse — and a null origin rewrites nothing. */
+export function appOriginOf(grants, authorizeUrl) {
+  let appOrigin = null;
+  try {
+    if (grants) appOrigin = new URL(authorizeUrl).origin;
+  } catch {
+    appOrigin = null;
+  }
+  return appOrigin;
+}
+
+/** FRAMED means Partitioned (rule (a) above). Sec-Fetch-Dest survives the
+ *  whole redirect chain (it describes the navigation, not the hop), so the
+ *  callback sees `iframe` exactly when the Workbench is the one asking. */
+export function grantCookieSite(secFetchDest) {
+  const dest = String(secFetchDest || '').toLowerCase();
+  const framed = dest === 'iframe' || dest === 'frame' || dest === 'embed' || dest === 'object';
+  return framed ? 'SameSite=None; Partitioned' : 'SameSite=Lax';
+}
+
+/**
+ * Replace the origin's frame policy with ours: `frame-ancestors 'self'
+ * <app origin>`. Rules that must survive any edit:
+ *  - REWRITE the directive inside an existing enforced CSP, never append a
+ *    second policy beside it — multiple CSP headers intersect, so an origin
+ *    `frame-ancestors 'none'` would still win over anything we added.
+ *  - APPEND a policy holding only our directive when the origin stated no
+ *    frame-ancestors at all — a public tunnel hostname deserves a frame
+ *    policy even when localhost never needed one.
+ *  - LEAVE Report-Only alone: browsers ignore frame-ancestors there, and
+ *    rewriting a report channel would be editing the driver's telemetry.
+ *  - DELETE X-Frame-Options: an enforced frame-ancestors makes every current
+ *    engine ignore it anyway; deleting is for the stragglers.
+ */
+export function rewriteFramePolicy(headers, appOrigin) {
+  if (!appOrigin) return headers;
+  const framePolicy = () => `frame-ancestors 'self' ${appOrigin}`;
+  const out = { ...headers };
+  delete out['x-frame-options'];
+  let sawDirective = false;
+  // Node joins duplicate response headers with ', ', so one string can hold
+  // SEVERAL policies (comma-separated), each holding several directives
+  // (semicolon-separated). Split on BOTH levels or replacing a directive
+  // eats the tail of a neighbouring policy — CSP source lists never contain
+  // a comma, so the outer split is safe.
+  const rewriteOne = (v) =>
+    String(v)
+      .split(',')
+      .map((policy) =>
+        policy
+          .split(';')
+          .map((part) => {
+            if (/^\s*frame-ancestors(\s|$)/i.test(part)) {
+              sawDirective = true;
+              return ` ${framePolicy()}`;
+            }
+            return part;
+          })
+          .join(';')
+      )
+      .join(',');
+  const csp = out['content-security-policy'];
+  if (csp !== undefined) {
+    out['content-security-policy'] = Array.isArray(csp) ? csp.map(rewriteOne) : rewriteOne(csp);
+  }
+  if (!sawDirective) {
+    const existing = out['content-security-policy'];
+    if (existing === undefined) out['content-security-policy'] = framePolicy();
+    else out['content-security-policy'] = Array.isArray(existing) ? [...existing, framePolicy()] : [existing, framePolicy()];
+  }
+  return out;
+}

package/bin/lib/previewGatePolicy.mjs

@@ -0,0 +1,236 @@
+/**
+ * WHO GETS THROUGH THE PREVIEW GATE — the credential, abuse and cross-site
+ * decisions, with no server in sight. Split out of `authproxy.mjs` (SOLID SRP,
+ * 2026-09-26): these are security rules that change on their own schedule
+ * (a threshold, a Fetch Metadata shape, a credential class), and the HTTP
+ * request path and the WebSocket upgrade path must ask them IN THE SAME ORDER.
+ * Before the split each transport spelled the order out by hand; now both ask
+ * `admit(req)` and differ only in how they write the answer onto the wire
+ * (a response vs raw bytes on an upgrade socket).
+ *
+ * `authproxy.mjs` still owns the server, the forwarding and the sockets; it
+ * builds one `createGatePolicy` per share, which holds that share's failure
+ * counts and the last expired grant seen.
+ *
+ * Two things this file gets wrong easily, both fixed here and both worth
+ * keeping fixed:
+ *  - the comparison is over a secret, so it is constant-time over a digest
+ *    rather than `===` over a string (`sameSecret`, whose one home is
+ *    `grant.mjs`).
+ *  - ONLY a wrong Basic password counts as an attempt (see `credential`).
+ */
+
+import { GRANT_COOKIE, cookieValues, sameSecret, verifyGrant } from './grant.mjs';
+
+/** Wrong-password attempts from ONE source before that source's Basic
+ *  attempts are refused outright. A quick tunnel's hostname is unguessable,
+ *  so this is not the primary control — but it is KNOWN to every past
+ *  member, tester and password recipient, whose access cannot be recalled.
+ *  The threshold is per source because one global counter made 25 wrong
+ *  guesses from any URL holder a kill switch on everyone else's share. */
+export const MAX_FAILED = 25;
+
+/** Counted failures across ALL sources before the whole share tears down.
+ *  The per-source block above answers a single abuser; this answers a
+ *  DISTRIBUTED guessing run (addresses rotating to stay under MAX_FAILED
+ *  each) — the original self-closing-incident property, kept at a threshold
+ *  ordinary use cannot reach: a blocked source stops counting, so getting
+ *  here takes eight independent sources each burning their full allowance. */
+export const MAX_FAILED_TOTAL = 200;
+
+/** Bound on the per-source map — a rotating attacker must not grow daemon
+ *  memory without limit. Eviction is oldest-first and CAN un-block an evicted
+ *  source, but cycling 500 fresh sources costs at least 500 counted failures,
+ *  and the global backstop closes the share long before that. */
+export const MAX_SOURCES = 500;
+
+/** An Authorization header in the Basic scheme — the only shape the gate's own
+ *  password ever arrives in, and so the only one it grades. */
+export const isBasic = (v) => typeof v === 'string' && /^\s*basic(\s|$)/i.test(v);
+
+/** cloudflared forwards the real client address in Cf-Connecting-Ip; a
+ *  direct local connection (the machine's own curl, the tests) has only the
+ *  socket. The header is attacker-writable in principle, but lying in it
+ *  only SPREADS one attacker across per-source counters — which is exactly
+ *  the shape MAX_FAILED_TOTAL exists to answer. */
+export const sourceOf = (req) =>
+  String(req.headers['cf-connecting-ip'] || req.socket?.remoteAddress || 'unknown');
+
+/**
+ * The CSRF backstop for the partitioned cookie (header rule 4a): a browser
+ * old enough to ignore `Partitioned` while honouring `SameSite=None` will
+ * attach the grant to cross-site requests, so a request that FETCH METADATA
+ * says is cross-site is refused unless it is a plain navigation GET/HEAD —
+ * the two shapes this product legitimately serves cross-site (the Open
+ * link, the Workbench frame's own src; a rendered attacker frame is then
+ * stopped by the frame-ancestors rewrite). Applies ONLY to grant-cookie
+ * auth: a password in an Authorization header is never attached cross-site
+ * by a browser, and clients that send no Sec-Fetch headers never held a
+ * None cookie, so absence stays permitted.
+ *
+ * Why a backstop at all: Chromium 76–113 (and same-vintage webviews/forks)
+ * sends Sec-Fetch-Dest — so it takes the framed-cookie branch — while
+ * ignoring the `Partitioned` attribute it has never heard of, storing a PLAIN
+ * unpartitioned SameSite=None cookie. Every browser in that class sends
+ * Sec-Fetch-Site (it shipped alongside Dest), and a browser sending neither
+ * never got a None cookie in the first place.
+ */
+export const crossSiteAbuse = (req) => {
+  if (String(req.headers['sec-fetch-site'] || '').toLowerCase() !== 'cross-site') return false;
+  const mode = String(req.headers['sec-fetch-mode'] || '').toLowerCase();
+  // Cross-site fetch/XHR/img/script with the cookie — nothing legitimate
+  // looks like this: the framed app's own subresources are same-origin.
+  if (mode && mode !== 'navigate') return true;
+  // A cross-site POST navigation is the classic auto-submitted CSRF form.
+  return !(req.method === 'GET' || req.method === 'HEAD');
+};
+
+/** A top-level browser navigation, and nothing else. A 302 is re-issued as
+ *  GET and drops the body, so bouncing a POST would turn an unauthenticated
+ *  write into a mystery GET; and this is what keeps curl and native clients
+ *  on the password path. */
+export const isBrowserNav = (req) =>
+  (req.method === 'GET' || req.method === 'HEAD') &&
+  /text\/html/.test(req.headers.accept || '');
+
+/**
+ * One share's gate policy. `grants` says whether the grant door is installed
+ * (all three of secret, share id and authorize URL arrived); `expected` is the
+ * full `Basic …` header the automation password produces.
+ *
+ * `onAbuse` fires once, after MAX_FAILED_TOTAL rejected attempts across all
+ * sources, so the caller can tear the whole share down rather than leaving a
+ * URL under attack. A single source is blocked on its own, at MAX_FAILED,
+ * without ending anybody else's share.
+ */
+export function createGatePolicy({ grants, grantSecret, shareId, expected, log, onAbuse }) {
+  let failedTotal = 0;
+  let abused = false;
+  /** source → wrong-password count, insertion-ordered so eviction below is
+   *  oldest-first. A source at MAX_FAILED is BLOCKED: its Basic attempts are
+   *  refused BEFORE the comparison and stop counting toward the total. */
+  const failedBySource = new Map();
+  /** The payload of the last validly-signed but EXPIRED grant seen, so a
+   *  tester can be re-bounced with the token inside it. */
+  let lastExpired = null;
+
+  const sourceBlocked = (req) => (failedBySource.get(sourceOf(req)) ?? 0) >= MAX_FAILED;
+
+  const noteFailure = (req) => {
+    const src = sourceOf(req);
+    const count = (failedBySource.get(src) ?? 0) + 1;
+    // Delete-then-set so Map insertion order tracks recency, making the
+    // eviction below an LRU rather than "whoever failed first".
+    failedBySource.delete(src);
+    failedBySource.set(src, count);
+    if (failedBySource.size > MAX_SOURCES) {
+      failedBySource.delete(failedBySource.keys().next().value);
+    }
+    if (count === MAX_FAILED) {
+      log?.(`preview gate: ${count} failed attempts from ${src} — refusing that source.`);
+    }
+    // MONOTONE, never reset by a success: a distributed run has no successes
+    // to hide behind, and a legitimate share cannot reach the backstop —
+    // every source stops counting at MAX_FAILED, so 200 needs eight distinct
+    // sources each exhausting their own allowance.
+    failedTotal += 1;
+    if (failedTotal >= MAX_FAILED_TOTAL && !abused) {
+      abused = true;
+      log?.(`preview gate: ${failedTotal} failed attempts across sources — closing the share.`);
+      try {
+        onAbuse?.();
+      } catch {
+        /* the caller's teardown is best-effort */
+      }
+    }
+  };
+
+  /**
+   * A PURE CREDENTIAL PREDICATE — no method, no Accept, no path. That is what
+   * lets the websocket upgrade handler reuse it verbatim, and it is why routing
+   * decisions live in the request handler instead.
+   *
+   * Tristate-plus: 'ok' | 'none' | 'expired' | 'forged' | 'badpass' | 'blocked'.
+   */
+  const credential = (req) => {
+    if (abused) return 'badpass';
+    // ONLY A WRONG PASSWORD COUNTS AS AN ATTEMPT, and this is a reason rather
+    // than a preference. A forged HMAC is not brute-forceable, so counting it
+    // buys nothing — while counting it would hand any stranger who finds the
+    // hostname a kill switch on the owner's share, because onAbuse tears the
+    // whole thing down. An expired-but-validly-signed grant must never count
+    // either, or a viewer who left a tab open overnight closes the share on
+    // their own reload.
+    //
+    // AND ONLY A *BASIC* HEADER IS A PASSWORD ATTEMPT (audit 2026-09-24). Any
+    // Authorization header used to be graded against the gate password, so a
+    // previewed SPA calling its own `/api` with `Authorization: Bearer …` was
+    // answered 401 with a Basic challenge — over a valid grant cookie — and 25
+    // such calls blocked that viewer, eight viewers tore the share down, and
+    // the origin never saw its own header. A Bearer (or any other scheme) is
+    // the APP's credential: it is not ours to grade and it rides through.
+    //
+    // A VALID GRANT COOKIE IS ASKED FIRST, for the same reason: an app that
+    // itself speaks Basic sends a header that is not our password, and a
+    // viewer the app has vouched for must not be graded on it. A grant is
+    // HMAC-verified, so asking it first opens no brute-force path.
+    let grantVerdict = 'none';
+    if (grants) {
+      // EVERY value for our name, not the first — a duplicate must not shadow.
+      for (const raw of cookieValues(req.headers.cookie, GRANT_COOKIE)) {
+        const r = verifyGrant(raw, { secret: grantSecret, shareId });
+        if (r.ok) return 'ok';
+        if (r.reason === 'exp' && grantVerdict === 'none') {
+          lastExpired = r.payload;
+          grantVerdict = 'expired';
+        }
+      }
+      if (grantVerdict === 'none' && String(req.headers.cookie ?? '').includes(GRANT_COOKIE)) {
+        grantVerdict = 'forged';
+      }
+    }
+
+    if (isBasic(req.headers['authorization'])) {
+      // A blocked source is refused BEFORE the comparison — a block that
+      // still grades guesses would let the brute force run to a correct hit.
+      if (sourceBlocked(req)) return 'blocked';
+      if (sameSecret(req.headers['authorization'], expected)) {
+        // Per-source only: a shared NAT recovers when one person behind it
+        // gets the password right; failedTotal stays monotone (see above).
+        failedBySource.delete(sourceOf(req));
+        return 'ok';
+      }
+      noteFailure(req);
+      return 'badpass';
+    }
+    return grantVerdict;
+  };
+
+  /** True when THIS request authenticated with the password rather than the
+   *  cookie — the credential class CSRF cannot ride. */
+  const viaPassword = (req) => sameSecret(req.headers['authorization'], expected);
+
+  /**
+   * THE ONE ADMISSION ORDER both transports ask: the credential first, then —
+   * only for a caller who HAS one — the cross-site backstop. The grant is a
+   * cookie, and a cookie can be ridden (header rule 4a's backstop); a
+   * refusal there is never a bounce, because the caller has a credential and
+   * the request SHAPE is what is refused.
+   *
+   * Returns the credential verdict ('blocked', 'none', 'expired', 'forged',
+   * 'badpass'), 'cross-site', or 'ok'.
+   */
+  const admit = (req) => {
+    const verdict = credential(req);
+    if (verdict !== 'ok') return verdict;
+    if (grants && crossSiteAbuse(req) && !viaPassword(req)) return 'cross-site';
+    return 'ok';
+  };
+
+  return {
+    admit,
+    viaPassword,
+    /** The payload of the last validly-signed but expired grant seen. */
+    lastExpired: () => lastExpired,
+  };
+}