flowviant 0.55.3 → 0.56.1

package/bin/lib/authproxy.mjs

@@ -13,6 +13,30 @@
  * browser re-sends the cached Basic-auth header on same-origin upgrades, so HMR
  * still authenticates.
  *
+ * TWO DOORS SINCE 0.56.0. The password above is now the AUTOMATION path (curl,
+ * Playwright, a native mobile client); the default for a human is a Flowviant
+ * session. A cookie-less browser NAVIGATION is bounced to the app, which checks
+ * the visitor is signed in and on the project and hands back an HMAC grant this
+ * gate verifies offline (`grant.mjs`) before setting a cookie. Four rules that
+ * fall out of that and must survive any edit:
+ *
+ *  - `/__fv/` IS RESERVED on this origin. The callback must be answered here,
+ *    before the auth check (it is by definition the unauthenticated request
+ *    that establishes authentication) and before forwarding (or the grant lands
+ *    in the dev server's access log). The gate therefore stops being a pure
+ *    pass-through, which is a deliberate, documented loss.
+ *  - NEVER 302 A NON-NAVIGATION. A 302 is re-issued as GET and silently drops
+ *    the body, so an unauthenticated POST from the previewed app would become a
+ *    mystery GET instead of a visible 401. This is also exactly what keeps
+ *    curl, Playwright and native clients on the password path.
+ *  - NEVER 302 A WEBSOCKET UPGRADE. Browsers do not follow 3xx on an upgrade,
+ *    they fail the connection — HMR would break in a way that looks like a dead
+ *    dev server. A cookie-less upgrade stays a 401.
+ *  - `SameSite=Lax` is chosen, so this gate CANNOT be embedded in a
+ *    cross-site iframe. The Workbench must not try; making it work would mean
+ *    `SameSite=None`, which is a different security posture and a conscious
+ *    re-argument, not a quiet flag change.
+ *
  * Three things this file gets wrong easily, all of them fixed here and all of
  * them worth keeping fixed:
  *  - the credential must NOT reach the origin. `headers: req.headers` forwarded
@@ -20,6 +44,9 @@
  *    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.
+ *  - 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.
  *  - `stop()` was a bare `server.close()`, which refuses NEW connections and
  *    leaves live ones alone — so a held HMR websocket kept the page alive for
  *    the one most-engaged viewer after teardown. Live sockets are tracked and
@@ -28,6 +55,7 @@
 
 import { createServer, request } from 'node:http';
 import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
+import { GRANT_COOKIE, cookieValues, safePathname, safeRelative, stripCookie, verifyGrant } from './grant.mjs';
 
 /** Failed attempts before the proxy stops answering at all. A quick tunnel's
  *  hostname is unguessable, so this is not the primary control — it is what
@@ -56,7 +84,14 @@ function sameSecret(a, b) {
  * `onAbuse` fires once, after MAX_FAILED rejected attempts, so the caller can
  * tear the whole share down rather than leaving a URL under attack.
  */
-export function startAuthProxy({ targetPort, log, onAbuse }) {
+export function startAuthProxy({ targetPort, log, onAbuse, grantSecret, shareId, authorizeUrl }) {
+  // ALL THREE OR NONE. Two of the three is a gate that cannot bounce anybody:
+  // a secret with no authorize URL has nowhere to send them, an authorize URL
+  // with no secret cannot verify what comes back. An older SERVER sends none of
+  // them, and that degrades to exactly today's behaviour — password only.
+  // A MISSING SECRET MUST NEVER DEGRADE TO OPEN: the mandatory-gate invariant
+  // above is unchanged, and a null return still aborts the share.
+  const grants = Boolean(grantSecret && shareId && authorizeUrl);
   const user = 'preview';
   // 24 bytes → 32 url-safe chars. It was 9 bytes, chosen when this was an
   // opt-in convenience; it is the only thing between a public hostname and a
@@ -66,27 +101,60 @@ export function startAuthProxy({ targetPort, log, onAbuse }) {
 
   let failed = 0;
   let abused = false;
-  const authed = (req) => {
-    if (abused) return false;
+  /** 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;
+
+  /**
+   * 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'.
+   */
+  const credential = (req) => {
+    if (abused) return 'badpass';
     if (sameSecret(req.headers['authorization'], expected)) {
       failed = 0;
-      return true;
+      return 'ok';
     }
-    // A bare GET with no header is the browser's first move on every load, and
-    // it is answered with a 401 challenge — it is not an attempt.
-    if (req.headers['authorization']) failed += 1;
-    if (failed >= MAX_FAILED && !abused) {
-      abused = true;
-      log?.(`preview gate: ${failed} failed attempts — closing the share.`);
-      try {
-        onAbuse?.();
-      } catch {
-        /* the caller's teardown is best-effort */
+    // 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 25-request 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. MAX_FAILED keeps its exact meaning, which is
+    // also why the 'abuse' ended-reason sentence stays true.
+    if (req.headers['authorization']) {
+      failed += 1;
+      if (failed >= MAX_FAILED && !abused) {
+        abused = true;
+        log?.(`preview gate: ${failed} failed attempts — closing the share.`);
+        try {
+          onAbuse?.();
+        } catch {
+          /* the caller's teardown is best-effort */
+        }
       }
+      return 'badpass';
     }
-    return false;
+
+    if (!grants) return 'none';
+    // 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') {
+        lastExpired = r.payload;
+        return 'expired';
+      }
+    }
+    return String(req.headers.cookie ?? '').includes(GRANT_COOKIE) ? 'forged' : 'none';
   };
 
+  const authed = (req) => credential(req) === 'ok';
+
   // 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
   // its request would be us editing their app's input.
@@ -94,6 +162,11 @@ export function startAuthProxy({ targetPort, log, onAbuse }) {
     const headers = { ...req.headers };
     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.
+    const rest = stripCookie(headers.cookie, GRANT_COOKIE);
+    if (rest) headers.cookie = rest;
+    else delete headers.cookie; // never send a bare empty `cookie:`
     return {
       host: '127.0.0.1',
       port: targetPort,
@@ -111,14 +184,84 @@ export function startAuthProxy({ targetPort, log, onAbuse }) {
       // in a cache the viewer cannot see.
       'Cache-Control': 'no-store',
     });
-    res.end('This preview is password-protected. Enter the password shown in Flowviant.');
+    res.end(
+      grants
+        ? 'This preview needs a Flowviant session, or the automation password shown in Flowviant.'
+        : 'This preview is password-protected. Enter the password shown in Flowviant.'
+    );
   };
 
   // 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
+   *  hostname: it sends the share id, and the SERVER builds the absolute
+   *  callback from the URL it already stored — so the app never trusts a
+   *  hostname supplied by the tunnel side. */
+  const bounce = (req, res, verdict) => {
+    const u = new URL(authorizeUrl);
+    u.searchParams.set('s', shareId);
+    u.searchParams.set('to', safeRelative(req.url));
+    // 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.
+    if (verdict === 'expired' && lastExpired?.k === 't' && lastExpired?.r) {
+      u.searchParams.set('t', String(lastExpired.r));
+      u.searchParams.set('x', '1');
+    } else if (verdict === 'expired') {
+      u.searchParams.set('x', '1');
+    }
+    res.writeHead(302, { Location: u.toString(), ...noStore });
+    res.end();
+  };
+
+  /** The callback. Answered ENTIRELY here — it never touches the origin. */
+  const handleCallback = (req, res) => {
+    const u = new URL(req.url, 'http://x');
+    const r = verifyGrant(u.searchParams.get('g'), { secret: grantSecret, shareId });
+    // NOT a redirect: bouncing a failed callback back to the app is how you
+    // build an infinite loop out of a clock skew.
+    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));
+    // 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
+    // access log — which is why the grant is short-lived and share-bound.
+    res.writeHead(302, {
+      'Set-Cookie': `${GRANT_COOKIE}=${r.raw}; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=${maxAge}`,
+      Location: to,
+      ...noStore,
+    });
+    res.end();
+  };
+
   const server = createServer((req, res) => {
-    if (!authed(req)) return challenge(res);
+    const path = safePathname(req.url);
+    // 1. The callback, BEFORE the auth check and BEFORE any forwarding.
+    if (grants && path === '/__fv/cb') return handleCallback(req, res);
+    // 2. Reserve the prefix so nothing under it is ever proxied.
+    if (path.startsWith('/__fv/')) {
+      res.writeHead(404, { 'Content-Type': 'text/plain', ...noStore });
+      res.end('not found');
+      return;
+    }
+    // 3. One predicate.
+    const verdict = credential(req);
+    if (verdict !== 'ok') {
+      if (grants && verdict !== 'badpass' && isBrowserNav(req)) return bounce(req, res, verdict);
+      return challenge(res);
+    }
     const proxyReq = request(forwardOpts(req), (proxyRes) => {
       res.writeHead(proxyRes.statusCode || 502, proxyRes.headers);
       proxyRes.pipe(res);
@@ -138,6 +281,16 @@ export function startAuthProxy({ targetPort, log, onAbuse }) {
   // WS upgrade (HMR). The browser resends the Basic-auth header on same-origin
   // upgrades, so we gate it too, then pipe the two sockets together.
   server.on('upgrade', (req, socket, head) => {
+    // Nothing under the reserved prefix is ever piped to the origin.
+    if (safePathname(req.url).startsWith('/__fv/')) {
+      socket.destroy();
+      return;
+    }
+    // NEVER 302 HERE — browsers fail an upgrade rather than following a 3xx, so
+    // a bounce would read as a dead dev server. The cookie IS sent on a
+    // same-origin handshake, so `authed` works unchanged; a cookie-less upgrade
+    // stays a 401 and the page's HMR client reconnects once the human has
+    // re-authenticated in the main document.
     if (!authed(req)) {
       socket.write('HTTP/1.1 401 Unauthorized\r\nWWW-Authenticate: Basic realm="Flowviant preview"\r\n\r\n');
       socket.destroy();
@@ -171,6 +324,9 @@ export function startAuthProxy({ targetPort, log, onAbuse }) {
         port,
         user,
         password,
+        // What was ACTUALLY installed, reported back so the app never asserts a
+        // door nobody observed.
+        gateMode: grants ? 'grant' : 'password',
         stop: () => {
           try {
             server.close();

package/bin/lib/childEnv.mjs

@@ -0,0 +1,113 @@
+/**
+ * THE ENVIRONMENT A SPAWNED COMMAND GETS — and, more to the point, what it does
+ * not get.
+ *
+ * WHY THIS FILE EXISTS: `deploy.mjs` carried
+ *
+ *     const env = { ...process.env, ...deployCreds() };
+ *     delete env.FLEET_TOKEN; // ... keep it out of a command that might echo its env
+ *
+ * and that `delete` was a LIVE NO-OP. `FLEET_TOKEN` is a JS module constant in
+ * `config.mjs`; the environment variable is `FLOWVIANT_FLEET`. So the machine
+ * credential sat in the environment of every deploy command — including
+ * `target.build`, which is a string the REPO controls — under a confident
+ * comment saying it did not. That is the whole argument for an allowlist: a
+ * denylist is a claim about a set you cannot see, and it rots into a lie the
+ * moment one identifier is wrong or one new secret is added upstream.
+ *
+ * SO: BUILT FROM `{}`, NEVER FROM `{...process.env}` MINUS NAMES. Anything not
+ * named below is absent by construction, and a secret added to the daemon's
+ * environment next year is absent without anybody remembering this file.
+ *
+ * WHAT THIS IS NOT. A spawned command runs as the SAME UID as the daemon.
+ * `~/.flowviant/credentials.json` and `~/.flowviant/env-keypair.json` are 0600
+ * and readable by it. This is a control against ACCIDENT AND INHERITANCE — a
+ * crash reporter, a framework error page that dumps `process.env`, a build log,
+ * a process that echoes its own environment — and it is NOT confinement. Real
+ * confinement is a separate uid or a namespace and is not in this product. No
+ * surface may describe anything here as "sandboxed" or "isolated".
+ */
+
+/**
+ * The complete kept set. Two groups, and both are here for a reason that bit
+ * somebody:
+ *
+ *  - the basics a process needs to exist at all;
+ *  - the TOOLCHAIN SHIMS. An operator on nvm, asdf, volta, pnpm or bun has a
+ *    PATH that points into a version-manager directory, and without these the
+ *    PATH we hand over resolves to nothing — the command fails with ENOENT and
+ *    the failure looks like a bad command rather than a stripped environment.
+ */
+const KEEP = [
+  'PATH',
+  'HOME',
+  'USER',
+  'LOGNAME',
+  'SHELL',
+  'TZ',
+  'LANG',
+  'LC_ALL',
+  'TMPDIR',
+  // Toolchain shims.
+  'NVM_DIR',
+  'NVM_BIN',
+  'ASDF_DIR',
+  'ASDF_DATA_DIR',
+  'VOLTA_HOME',
+  'PNPM_HOME',
+  'BUN_INSTALL',
+  'N_PREFIX',
+  'XDG_CACHE_HOME',
+  'XDG_DATA_HOME',
+];
+
+/**
+ * A child environment for a command Flowviant runs on the operator's behalf.
+ *
+ * `extra` is layered LAST and is the caller's own material — deploy
+ * credentials, or nothing. It is never repo-supplied: the deleted preview
+ * feature let `.flowviant/preview.json` contribute an `env` map that was
+ * layered last and therefore won every collision, which is how a branch got to
+ * set `PATH`.
+ */
+export function childEnv({ cwd, extra } = {}) {
+  const env = {};
+  for (const k of KEEP) {
+    if (typeof process.env[k] === 'string') env[k] = process.env[k];
+  }
+  // Set by us rather than inherited.
+  //
+  // TERM=dumb: a process that believes it owns a TTY draws progress bars and
+  // spinners into a pipe forever, which is unreadable in a log tail and pins a
+  // CPU on some tools.
+  env.TERM = 'dumb';
+  // BROWSER=none: nothing should try to open a browser on a headless box. This
+  // is the one survivor of the deleted feature's env extras, and it is
+  // anti-annoyance rather than security.
+  env.BROWSER = 'none';
+  if (cwd) env.PWD = cwd;
+  // Deliberately NOT set: NODE_ENV (asserting 'development' would be Flowviant
+  // choosing what the framework should decide) and PORT (we never hint a port —
+  // the port is DISCOVERED by cwd attribution, and a hinted one has no
+  // attribution behind it).
+  return extra ? { ...env, ...extra } : env;
+}
+
+/** The names this deliberately drops, for the test to assert against. NOT the
+ *  mechanism — the mechanism is the allowlist above, and this list is only ever
+ *  a sample of what it excludes. Adding a name here changes nothing. */
+export const DROPPED_SAMPLE = [
+  'FLOWVIANT_FLEET',
+  'FLOWVIANT_FLEET_URL',
+  'FLOWVIANT_API_URL',
+  'FLOWVIANT_MCP_URL',
+  'FLOWVIANT_MODEL',
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_AUTH_TOKEN',
+  'GH_TOKEN',
+  'GITHUB_TOKEN',
+  'SSH_AUTH_SOCK',
+  'CLOUDFLARE_API_TOKEN',
+  'AWS_SECRET_ACCESS_KEY',
+  'npm_config__authToken',
+];

package/bin/lib/deploy.mjs

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT, DAEMON_INSTANCE } from './config.mjs';
 import { c, note, ok, warn } from './ui.mjs';
 import { deployCreds, appSecretsFor, scrub, myPubB64 } from './env.mjs';
+import { childEnv } from './childEnv.mjs';
 
 const deployUrl = (tail) => FLEET_URL.replace(/\/agents\/?$/, `/${tail}`);
 
@@ -206,8 +207,18 @@ export function processDeployJobs(jobs, ctx) {
 }
 
 async function runDeploy(job, target, ctx) {
-  const env = { ...process.env, ...deployCreds() }; // inject infra creds; never a file
-  delete env.FLEET_TOKEN; // the deploy command has no business reading it; keep it out of a command that might echo its env
+  // AN ALLOWLIST, not `{...process.env}` minus names. What stood here was
+  //
+  //     const env = { ...process.env, ...deployCreds() };
+  //     delete env.FLEET_TOKEN;
+  //
+  // and that delete was a NO-OP: `FLEET_TOKEN` is a module constant in
+  // config.mjs, while the environment variable is `FLOWVIANT_FLEET`. The
+  // machine credential was therefore in the environment of every deploy
+  // command — and of `target.build`, which is a string the REPO controls —
+  // under a comment asserting the opposite. A denylist is a claim about a set
+  // you cannot see; this is built from {} instead.
+  const env = childEnv({ cwd: ctx.repoRoot, extra: deployCreds() }); // infra creds; never a file
   const logs = [];
   // Rollback is a single wrangler command; deploy is build → secrets → deploy.
   if (job.kind === 'rollback') {

package/bin/lib/grant.mjs

@@ -0,0 +1,182 @@
+/**
+ * THE GATE'S HALF OF THE GRANT — verify only. This file never mints.
+ *
+ * A shared preview is served AROUND Flowviant: cloudflared → the gate in
+ * `authproxy.mjs` → the dev server the driver started. When the gate meets a
+ * browser with no cookie it bounces to the app, which checks the visitor is
+ * signed in and on the project, and hands back an HMAC grant signed with the
+ * per-share secret the roster gave this machine. The gate verifies that grant
+ * HERE, offline, and sets a cookie.
+ *
+ * OFFLINE IS THE WHOLE DESIGN. The daemon is a pull client with no
+ * server→daemon request path, and the gate is listening before cloudflared
+ * spawns — so a gate that had to reach api.flowviant.com to answer its first
+ * request would either delay the tunnel or open a window where the public
+ * hostname is un-gated. It also means a network blip cannot turn somebody's
+ * working preview into a 502.
+ *
+ * THIS FILE IS ONE HALF OF A WIRE CONTRACT. The other half is
+ * `apps/api/src/lib/agent-runner/previewGrant.ts` in the Flowviant repo, and
+ * the two are tested against the same vectors. A change here that the server
+ * does not follow shows up as a preview nobody can open.
+ *
+ * NO CANONICAL-ENCODING CONTRACT, deliberately: the signature covers the
+ * RECEIVED payload string bytes and the JSON is parsed only afterwards. Field
+ * order, whitespace and key set are therefore irrelevant to verification, which
+ * removes an entire failure mode — an unbootstrappable redirect loop caused by
+ * two languages disagreeing about how to serialise an object.
+ */
+
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+
+export const GRANT_VERSION = 1;
+const DOMAIN = `fvgrant.v${GRANT_VERSION}.`;
+
+/** `__Host-` is required rather than decorative: every quick tunnel is a
+ *  hostname under the shared `trycloudflare.com` parent, so without the prefix
+ *  a neighbour with their own tunnel could set a Domain-scoped cookie the
+ *  browser would also send to ours. The prefix makes the browser refuse any
+ *  Domain attribute and forces host-only + Secure + Path=/. */
+export const GRANT_COOKIE = '__Host-fv_grant';
+
+/** Tolerance past `exp`, one direction only. Absorbs ordinary clock drift
+ *  between the Worker and this box. */
+export const GRANT_SKEW_MS = 60_000;
+
+const b64url = (buf) => buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+
+/** Constant-time over sha256 digests, so length never leaks and a missing
+ *  value costs the same as a wrong one. Never `===` on a signature. */
+function sameDigest(a, b) {
+  try {
+    const da = createHash('sha256').update(String(a ?? '')).digest();
+    const db = createHash('sha256').update(String(b ?? '')).digest();
+    return timingSafeEqual(da, db);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verify a grant against this share's secret.
+ *
+ * Returns `{ ok: true, raw, payload }`, or `{ ok: false, reason, payload? }`
+ * where reason is one of empty | shape | sig | version | share | exp. The
+ * payload rides back on an EXPIRY (and only after the signature checked out) so
+ * the caller can re-bounce a tester using the token inside it.
+ */
+export function verifyGrant(raw, { secret, shareId, nowMs, skewMs } = {}) {
+  // An empty secret is refused BEFORE anything is hashed. Every share created
+  // before this feature has none, and null must read as "no SSO gate here",
+  // never as "the empty key".
+  if (!raw || !secret) return { ok: false, reason: 'empty' };
+  const s = String(raw);
+  const dot = s.indexOf('.');
+  if (dot <= 0 || dot === s.length - 1) return { ok: false, reason: 'shape' };
+  const body = s.slice(0, dot);
+  const sig = s.slice(dot + 1);
+  if (!/^[A-Za-z0-9_-]+$/.test(body) || !/^[A-Za-z0-9_-]+$/.test(sig)) {
+    return { ok: false, reason: 'shape' };
+  }
+
+  const expected = b64url(createHmac('sha256', String(secret)).update(DOMAIN + body).digest());
+  if (!sameDigest(sig, expected)) return { ok: false, reason: 'sig' };
+
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(body.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'));
+  } catch {
+    return { ok: false, reason: 'shape' };
+  }
+  if (!payload || typeof payload !== 'object') return { ok: false, reason: 'shape' };
+  if (payload.v !== GRANT_VERSION) return { ok: false, reason: 'version' };
+  // Binds the grant to THIS share. One machine may serve several; a grant for
+  // one must not open another.
+  if (payload.s !== shareId) return { ok: false, reason: 'share' };
+
+  const now = nowMs ?? Date.now();
+  const skew = skewMs ?? GRANT_SKEW_MS;
+  if (typeof payload.exp !== 'number' || now > payload.exp * 1000 + skew) {
+    return { ok: false, reason: 'exp', payload };
+  }
+  return { ok: true, raw: s, payload };
+}
+
+/**
+ * EVERY value for `name` in a Cookie header, not just the first.
+ *
+ * A `__Host-` cookie cannot be shadowed by a Domain-scoped one, but a page on
+ * the origin can still call `document.cookie` and a malformed header can carry
+ * a duplicate. Checking only the first match would let a planted value shadow
+ * the real one and lock the viewer out; checking all of them cannot.
+ */
+export function cookieValues(header, name) {
+  if (!header) return [];
+  const out = [];
+  for (const part of String(header).split(';')) {
+    const eq = part.indexOf('=');
+    if (eq < 0) continue;
+    if (part.slice(0, eq).trim() !== name) continue;
+    out.push(part.slice(eq + 1).trim());
+  }
+  return out;
+}
+
+/**
+ * Drop ONLY our cookie from a Cookie header, preserving everything else.
+ *
+ * The whole header must not be deleted: the driver's own app legitimately owns
+ * its session cookies and would break. And ours must not be forwarded: a signed
+ * grant handed to whatever code the branch happens to be running is a bearer
+ * token given to the untrusted side of this boundary — the same bug the
+ * `authorization` strip already encodes, and that one shipped once.
+ *
+ * Returns the remaining header, or '' when nothing is left (the caller must
+ * then delete the header rather than send an empty one).
+ */
+export function stripCookie(header, name) {
+  if (!header) return '';
+  const kept = String(header)
+    .split(';')
+    .filter((part) => {
+      const eq = part.indexOf('=');
+      const key = eq < 0 ? part.trim() : part.slice(0, eq).trim();
+      return key !== name;
+    })
+    .map((p) => p.trim())
+    .filter(Boolean);
+  return kept.join('; ');
+}
+
+/**
+ * The pathname of a request, PARSED rather than prefix-matched.
+ *
+ * `req.url.startsWith('/__fv/cb')` also matches `/__fv/cbXYZ`, and an equality
+ * test against `req.url` misses a reordered query string, a bare path with no
+ * query, and a fragment. Both mistakes are the difference between the callback
+ * being handled and being proxied to somebody's dev server with the grant in
+ * its access log.
+ */
+export function safePathname(url) {
+  try {
+    return new URL(String(url ?? '/'), 'http://x').pathname;
+  } catch {
+    return '/';
+  }
+}
+
+/**
+ * A destination that cannot be read as an origin.
+ *
+ * `//evil.com` and `/\evil.com` are protocol-relative to a browser, so a naive
+ * "starts with /" check turns the callback into an open redirect on the tunnel
+ * origin. Anything that is not a single-slash relative path becomes '/'.
+ */
+export function safeRelative(raw) {
+  if (!raw) return '/';
+  const s = String(raw);
+  if (s.length > 512) return '/';
+  if (/[\r\n]/.test(s)) return '/';
+  if (!/^\/(?![/\\])/.test(s)) return '/';
+  return s;
+}

package/bin/lib/preview.mjs

@@ -311,7 +311,7 @@ const TAIL_BYTES = 2000;
 /**
  * Gate `port` behind a password and publish it on a quick tunnel.
  *
- * Resolves { url, user, password, stop } on success, or { error } — a sentence
+ * Resolves { url, user, password, gateMode, stop } on success, or { error } — a sentence
  * from this machine, to be relayed as-is. It never resolves a URL without a
  * password, and it never returns a tunnel whose origin was not listening when
  * we checked.
@@ -348,6 +348,11 @@ export async function openTunnel({
   onTunnelGone,
   stillServing,
   probeMs = 20_000,
+  // The members-gate triple, all three or none. Absent = an older server, or a
+  // password-mode share: the gate runs exactly as it always has.
+  grantSecret,
+  shareId,
+  authorizeUrl,
 }) {
   // Re-validate at the machine. The server checked this port against the last
   // report; reports are up to a minute old and a dev server is a process a
@@ -392,6 +397,13 @@ export async function openTunnel({
   gate = await startAuthProxy({
     targetPort: port,
     log,
+    // Never logged, never written to previews.json, never in the reap
+    // signature, never in argv or a child env — /proc/<pid>/cmdline is
+    // world-readable and this box also runs the driver's dev server and every
+    // CLI turn. In-process only.
+    grantSecret,
+    shareId,
+    authorizeUrl,
     onAbuse: () => {
       stop();
       try {
@@ -483,7 +495,7 @@ export async function openTunnel({
         }
       });
 
-      finish({ url: m[0], user: gate.user, password: gate.password, stop });
+      finish({ url: m[0], user: gate.user, password: gate.password, gateMode: gate.gateMode, stop });
     };
 
     tunnel.stdout.on('data', onOut);

package/bin/lib/work.mjs

@@ -519,8 +519,34 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
       }
 
       if (!Number.isInteger(port) || port <= 0 || port > 65535) continue;
+
+      // VALIDATE THE MEMBERS-GATE TRIPLE AT THE BOUNDARY, the way sessionId and
+      // port already are — one place doing the check is one deploy away from
+      // being zero places. A malformed value is DROPPED rather than errored and
+      // the share opens password-only: a gate is never degraded to open, but it
+      // is also never left un-opened over a field we could not read.
+      const secret = /^[A-Za-z0-9_-]{32,128}$/.test(String(job?.secret ?? ''))
+        ? String(job.secret)
+        : null;
+      const shareId = isSafePathSegment(String(job?.shareId ?? '')) ? String(job.shareId) : null;
+      let authorizeUrl = null;
+      try {
+        const u = new URL(String(job?.authorizeUrl ?? ''));
+        if (u.protocol === 'https:') authorizeUrl = u.toString();
+      } catch {
+        /* not a URL — password-only, which is honest */
+      }
+      // All three or none: two of the three is a gate that cannot bounce.
+      const gateOk = Boolean(secret && shareId && authorizeUrl);
+
       // Already serving exactly this. Re-opening would replace a working URL
       // somebody may be looking at right now.
+      //
+      // NOTE this key is (session, port) and NOT the secret. Rotating a secret
+      // under a LIVE share is deliberately unsupported: `requestPreview`
+      // early-returns on a live row of the same port, so a new secret only ever
+      // arrives with a genuinely new row, by which time this map has been
+      // cleared. Anyone adding rotation must widen the key first.
       if (livePreviews.get(sessionId)?.port === port) continue;
       if (previewClaiming.has(sessionId)) continue;
       previewClaiming.add(sessionId);
@@ -566,6 +592,7 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
             // a bare TCP probe green, and the share's URL+password would serve
             // a worktree nobody consented to publish.
             stillServing: async () => listenersIn(wt).some((l) => l.port === port),
+            ...(gateOk ? { grantSecret: secret, shareId, authorizeUrl } : {}),
             // The gate closed itself after repeated failed passwords. Stored,
             // so the incident is visible — and the entry is dropped so the
             // owner can re-share the port without restarting the daemon.
@@ -588,7 +615,15 @@ export function createWorkManager({ repoRoot, baseDir, baseRef, getMcpUrl, getLe
             return;
           }
           livePreviews.set(sessionId, { port, url: t.url, stop: t.stop });
-          await postPreview({ sessionId, url: t.url, user: t.user, password: t.password });
+          // The gate we ACTUALLY installed, so the app never asserts a door
+          // nobody observed. An older server ignores the field.
+          await postPreview({
+            sessionId,
+            url: t.url,
+            user: t.user,
+            password: t.password,
+            gate: t.gateMode,
+          });
         } finally {
           previewClaiming.delete(sessionId);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.55.3",
+  "version": "0.56.1",
   "description": "Run your own coding CLIs as build agents for Flowviant \u2014 Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {
@@ -8,12 +8,16 @@
   },
   "files": [
     "bin",
+    "!bin/lib/*.test.mjs",
     "README.md",
     "LICENSE"
   ],
   "engines": {
     "node": ">=20"
   },
+  "scripts": {
+    "test": "node --test bin/lib/*.test.mjs"
+  },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.0",
     "libsodium-wrappers-sumo": "^0.8.4",