flowviant 0.102.2 → 0.104.0

package/bin/lib/authproxy.mjs

@@ -36,41 +36,23 @@
  *    old "cannot be embedded, the Workbench must not try" rule deliberately —
  *    the Workbench now DOES frame the share, so both halves are re-argued
  *    here). Two changes, one per blocker:
- *    (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 have broken 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.
- *        AND THE PARTITIONING CLAIM HAS A BACKSTOP, because one browser class
- *        breaks it: Chromium 76–113 (and same-vintage webviews/forks) sends
- *        Sec-Fetch-Dest — so it takes this branch — while ignoring the
- *        `Partitioned` attribute it has never heard of, storing a PLAIN
- *        unpartitioned SameSite=None cookie: the exact CSRF hole the sentence
- *        above says partitioning prevents. So `crossSiteAbuse` refuses a
- *        GRANT-authenticated request that Fetch Metadata marks cross-site
- *        unless it is a top-level GET/HEAD navigation (the Open link, the
- *        frame's own src). Every browser in the vulnerable class sends
- *        Sec-Fetch-Site (it shipped alongside Dest), a browser sending
- *        neither never got a None cookie in the first place, and the password
- *        path is exempt — Basic auth is never attached cross-site by a
- *        browser, so curl and Playwright feel nothing.
+ *    (a) THE COOKIE. A top-level visit's grant cookie stays `SameSite=Lax`;
+ *        a framed navigation gets a partitioned one. The attribute and its
+ *        argument (CHIPS, the Safari Partitioned drop) live in
+ *        `previewFramePolicy.mjs` (`grantCookieSite`); its CSRF backstop is
+ *        `crossSiteAbuse` in `previewGatePolicy.mjs`. What stays here is only
+ *        the server's own callback, which asks `grantCookieSite` with the
+ *        request's `Sec-Fetch-Dest` when it sets the cookie.
  *    (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.
+ *        is REWRITTEN to `frame-ancestors 'self' <app origin>`; password-only
+ *        mode rewrites NOTHING. The rule and its argument live in
+ *        `previewFramePolicy.mjs` (`rewriteFramePolicy`).
+ *
+ * WHO GETS IN — the credential predicate, the per-source and global failure
+ * counts, the cross-site backstop and the admission order both transports ask
+ * — is `previewGatePolicy.mjs` (split out 2026-09-26, SOLID SRP). This file is
+ * the server: it answers the callback, forwards HTTP, pipes upgrades and owns
+ * every socket's lifetime.
  *
  * Three things this file gets wrong easily, all of them fixed here and all of
  * them worth keeping fixed:
@@ -78,7 +60,8 @@
  *    `authorization` verbatim, handing the gate password to whatever code the
  *    branch happens to be running. It is stripped now.
  *  - the comparison is over a secret, so it is constant-time over a digest
- *    rather than `===` over a string.
+ *    rather than `===` over a string (`sameSecret`, `grant.mjs`, asked by
+ *    `previewGatePolicy.mjs`).
  *  - the grant cookie must be stripped from the forwarded request too, and
  *    ONLY ours: deleting the whole `cookie` header breaks the driver's own app,
  *    which legitimately owns its session cookies.
@@ -89,46 +72,10 @@
  */
 
 import { createServer, request } from 'node:http';
-import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
-import { GRANT_COOKIE, cookieValues, safePathname, safeRelative, stripCookie, 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. */
-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. */
-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. */
-const MAX_SOURCES = 500;
-
-const digest = (s) => createHash('sha256').update(String(s)).digest();
-
-/** 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. */
-const isBasic = (v) => typeof v === 'string' && /^\s*basic(\s|$)/i.test(v);
-
-/** Constant-time over sha256 digests, so length never leaks and a missing
- *  header costs the same as a wrong one. */
-function sameSecret(a, b) {
-  try {
-    return timingSafeEqual(digest(a ?? ''), digest(b ?? ''));
-  } catch {
-    return false;
-  }
-}
+import { randomBytes } from 'node:crypto';
+import { GRANT_COOKIE, safePathname, safeRelative, stripCookie, verifyGrant } from './grant.mjs';
+import { createGatePolicy, isBrowserNav } from './previewGatePolicy.mjs';
+import { appOriginOf, grantCookieSite, rewriteFramePolicy } from './previewFramePolicy.mjs';
 
 /**
  * Start the gate in front of a dev server on `targetPort`. Resolves
@@ -139,7 +86,7 @@ function sameSecret(a, b) {
  * `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.
+ * without ending anybody else's share (`previewGatePolicy.mjs`).
  */
 export function startAuthProxy({
   targetPort,
@@ -167,204 +114,11 @@ export function startAuthProxy({
   const password = randomBytes(24).toString('base64url');
   const expected = 'Basic ' + Buffer.from(`${user}:${password}`).toString('base64');
 
-  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;
-
-  /** 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. */
-  const sourceOf = (req) =>
-    String(req.headers['cf-connecting-ip'] || req.socket?.remoteAddress || 'unknown');
-
-  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;
-  };
-
-  /**
-   * 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.
-   */
-  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');
-  };
-
-  /** 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 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. */
-  let appOrigin = null;
-  try {
-    if (grants) appOrigin = new URL(authorizeUrl).origin;
-  } catch {
-    appOrigin = null;
-  }
-
-  /**
-   * 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.
-   */
-  const framePolicy = () => `frame-ancestors 'self' ${appOrigin}`;
-  const rewriteFramePolicy = (headers) => {
-    if (!grants || !appOrigin) return headers;
-    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;
-  };
+  // Who gets in, and this share's failure counts (`previewGatePolicy.mjs`).
+  const policy = createGatePolicy({ grants, grantSecret, shareId, expected, log, onAbuse });
+  // The one origin allowed to frame us, null in password-only mode
+  // (`previewFramePolicy.mjs`).
+  const appOrigin = appOriginOf(grants, authorizeUrl);
 
   // The gate credential is OURS and stops here. Everything else is passed
   // through untouched: the origin is the driver's own dev server and rewriting
@@ -374,7 +128,7 @@ export function startAuthProxy({
     // Only when it IS the gate credential. Anything else in Authorization is
     // the previewed app's own (a Bearer to its API, its own Basic realm) and
     // the app breaks without it; ours must still never reach branch code.
-    if (sameSecret(headers.authorization, expected)) delete headers.authorization;
+    if (policy.viaPassword(req)) delete headers.authorization;
     delete headers['proxy-authorization'];
     // ONLY OURS. The driver's app owns its own cookies and breaks without them;
     // our grant is a signed bearer token and must not reach branch code.
@@ -408,14 +162,6 @@ export function startAuthProxy({
   // Every live socket, so stop() can actually end the ones already talking.
   const sockets = new Set();
 
-  /** 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. */
-  const isBrowserNav = (req) =>
-    (req.method === 'GET' || req.method === 'HEAD') &&
-    /text\/html/.test(req.headers.accept || '');
-
   const noStore = { 'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer' };
 
   /** Send them to the app to be vouched for. The gate never names its own
@@ -429,6 +175,7 @@ export function startAuthProxy({
     // Re-bounce a tester with the token that was inside their expired grant —
     // they no longer hold the original link, and the server re-checks the hash
     // ONLINE, which is what makes a tester link revocable at all.
+    const lastExpired = policy.lastExpired();
     if (verdict === 'expired' && lastExpired?.k === 't' && lastExpired?.r) {
       u.searchParams.set('t', String(lastExpired.r));
       u.searchParams.set('x', '1');
@@ -448,12 +195,8 @@ export function startAuthProxy({
     if (!r.ok) return challenge(res);
     const to = safeRelative(u.searchParams.get('to'));
     const maxAge = Math.max(0, r.payload.exp - Math.floor(Date.now() / 1000));
-    // FRAMED means Partitioned (header rule 4a). 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.
-    const dest = String(req.headers['sec-fetch-dest'] || '').toLowerCase();
-    const framed = dest === 'iframe' || dest === 'frame' || dest === 'embed' || dest === 'object';
-    const site = framed ? 'SameSite=None; Partitioned' : 'SameSite=Lax';
+    // FRAMED means Partitioned (header rule 4a, `previewFramePolicy.mjs`).
+    const site = grantCookieSite(req.headers['sec-fetch-dest']);
     // The immediate 302 to a clean path is MANDATORY, not cosmetic: it takes
     // `?g=` out of the address bar, out of the Referer every subresource would
     // carry, and out of browser history. It cannot take it out of cloudflared's
@@ -476,8 +219,8 @@ export function startAuthProxy({
       res.end('not found');
       return;
     }
-    // 3. One predicate.
-    const verdict = credential(req);
+    // 3. One admission, the same one the upgrade path asks.
+    const verdict = policy.admit(req);
     // A blocked source gets 429, not the challenge — a WWW-Authenticate here
     // would invite the retry the block exists to end. Only that source's
     // Basic attempts are refused; every other viewer's share is untouched.
@@ -486,22 +229,22 @@ export function startAuthProxy({
       res.end('too many failed attempts from this address');
       return;
     }
-    if (verdict !== 'ok') {
-      if (grants && verdict !== 'badpass' && isBrowserNav(req)) return bounce(req, res, verdict);
-      return challenge(res);
-    }
     // 4. The grant is a cookie, and a cookie can be ridden (header rule 4a's
     // backstop). Never a bounce — the caller HAS a credential; the request
     // SHAPE is what is refused.
-    if (grants && crossSiteAbuse(req) && !viaPassword(req)) {
+    if (verdict === 'cross-site') {
       res.writeHead(403, { 'Content-Type': 'text/plain', ...noStore });
       res.end('cross-site request refused');
       return;
     }
+    if (verdict !== 'ok') {
+      if (grants && verdict !== 'badpass' && isBrowserNav(req)) return bounce(req, res, verdict);
+      return challenge(res);
+    }
     const proxyReq = request(forwardOpts(req), (proxyRes) => {
       // The one RESPONSE rewrite this gate performs (header rule 4b): the
       // frame policy. Everything else is the driver's own app talking.
-      res.writeHead(proxyRes.statusCode || 502, rewriteFramePolicy(proxyRes.headers));
+      res.writeHead(proxyRes.statusCode || 502, rewriteFramePolicy(proxyRes.headers, appOrigin));
       proxyRes.pipe(res);
     });
     proxyReq.on('error', () => {
@@ -537,25 +280,25 @@ export function startAuthProxy({
     // upgrade stays a 401 and the page's HMR client reconnects once the human
     // has re-authenticated in the main document. A blocked source's Basic
     // handshake gets the same 429 the request path sends, and no challenge.
-    const upgradeVerdict = credential(req);
+    const upgradeVerdict = policy.admit(req);
     if (upgradeVerdict === 'blocked') {
       socket.write('HTTP/1.1 429 Too Many Requests\r\n\r\n');
       socket.destroy();
       return;
     }
-    if (upgradeVerdict !== 'ok') {
-      socket.write('HTTP/1.1 401 Unauthorized\r\nWWW-Authenticate: Basic realm="Flowviant preview"\r\n\r\n');
-      socket.destroy();
-      return;
-    }
     // The same cross-site backstop as the request path: a cookie-ridden
     // cross-site handshake (Sec-Fetch-Mode: websocket) is refused; the framed
     // app's own HMR socket is same-origin and never trips it.
-    if (grants && crossSiteAbuse(req) && !viaPassword(req)) {
+    if (upgradeVerdict === 'cross-site') {
       socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
       socket.destroy();
       return;
     }
+    if (upgradeVerdict !== 'ok') {
+      socket.write('HTTP/1.1 401 Unauthorized\r\nWWW-Authenticate: Basic realm="Flowviant preview"\r\n\r\n');
+      socket.destroy();
+      return;
+    }
     const proxyReq = request(forwardOpts(req));
     proxyReq.on('upgrade', (proxyRes, proxySocket, proxyHead) => {
       const headerLines = Object.entries(proxyRes.headers).map(([k, v]) => `${k}: ${v}`);