flowviant 0.55.2 → 0.56.0

package/bin/cli.mjs

@@ -237,13 +237,22 @@ if (process.argv[2] === 'env') {
 // auto-updated daemon's child sees two TTYs; without this it would stop on the
 // binding confirm below and the machine would stay dark until somebody typed a
 // key. Same reasoning as the headless case, and the same answer.
-const interactive =
-  Boolean(process.stdin.isTTY && process.stdout.isTTY) && process.env.FLOWVIANT_REEXEC !== '1';
+// `canPrompt()`, not a bare isTTY pair: a BACKGROUNDED job (`flowviant &`) has
+// two TTYs and cannot be asked anything — the first read raises SIGTTIN and the
+// kernel STOPS the process, which is why 0.55.2's timeout did not save it (a
+// stopped process runs no timers). See tty.mjs.
+const { canPrompt, askWithTimeout } = await import('./lib/tty.mjs');
+const interactive = canPrompt() && process.env.FLOWVIANT_REEXEC !== '1';
 
 /** How long the one-time binding confirm waits before serving unbound. A person
  *  who just typed `flowviant` answers in seconds; anything longer is a restart
  *  nobody is watching, and the machine must not sit dark for it. */
 const CONFIRM_TIMEOUT_MS = 20_000;
+
+/** The picker's own budget. Longer than the confirm: this one asks you to READ
+ *  a list before answering, and its fallback costs you a start rather than
+ *  costing you a binding. */
+const PICK_TIMEOUT_MS = 60_000;
 const externalToken = process.argv.includes('--fleet') || Boolean(process.env.FLOWVIANT_FLEET);
 
 /** Re-exec a plain `flowviant` after an inline login — the login command's own
@@ -283,12 +292,22 @@ if (!FLEET_TOKEN) {
     );
     console.log(listLines(choices, creds));
     console.log(`  ${choices.length + 1}. connect ${repoRoot ? 'this repo' : 'a repo'} to a different project (flowviant login)`);
-    const rl = (await import('node:readline/promises')).createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-    const raw = (await rl.question(`Which project should this daemon serve? [1-${choices.length + 1}] `)).trim();
-    rl.close();
+    // Bounded like the confirm below, and for the same reason — but silence
+    // means something DIFFERENT here and the difference is load-bearing. There
+    // is a real ambiguity to resolve; serving a guess is the skadooble bug.
+    // So no answer REFUSES, which is exactly what this branch already does
+    // headless, and the message says how to answer without being present.
+    const raw = await askWithTimeout(
+      `Which project should this daemon serve? [1-${choices.length + 1}] `,
+      PICK_TIMEOUT_MS
+    );
+    if (raw === null) {
+      console.error(
+        `\nno answer in ${Math.round(PICK_TIMEOUT_MS / 1000)}s — nothing started. ` +
+          `Name one with \`--project <name|id>\`, or run \`flowviant\` here in the foreground and pick.`
+      );
+      process.exit(1);
+    }
     const n = Number.parseInt(raw, 10);
     if (n === choices.length + 1) await reexecAfterLogin();
     const picked = Number.isInteger(n) ? choices[n - 1] : undefined;
@@ -346,26 +365,11 @@ if (!FLEET_TOKEN) {
   //    which is the only person it could ever have been fixed for.
   const creds = await import('./lib/credentials.mjs');
   const label = creds.projectLabel(CREDENTIAL.entry);
-  const rl = (await import('node:readline/promises')).createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-  const ac = new AbortController();
-  const timer = setTimeout(() => ac.abort(), CONFIRM_TIMEOUT_MS);
-  let raw = null; // null = nobody answered
-  try {
-    raw = (
-      await rl.question(
-        `This machine's one connected project is ${label}. Serve this repo (${CREDENTIAL.repoRoot}) as ${label}? [Y/n] `,
-        { signal: ac.signal }
-      )
-    ).trim().toLowerCase();
-  } catch {
-    /* aborted — nobody is at this terminal */
-  } finally {
-    clearTimeout(timer);
-    rl.close();
-  }
+  const answered = await askWithTimeout(
+    `This machine's one connected project is ${label}. Serve this repo (${CREDENTIAL.repoRoot}) as ${label}? [Y/n] `,
+    CONFIRM_TIMEOUT_MS
+  );
+  const raw = answered === null ? null : answered.toLowerCase(); // null = nobody answered
   if (raw === null) {
     console.log(
       `\n  no answer in ${Math.round(CONFIRM_TIMEOUT_MS / 1000)}s — serving ${label} for this run ` +

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/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/install.mjs

@@ -27,17 +27,23 @@ export function addLocalBinToPath() {
   }
 }
 
-/** TTY-guarded y/N. Non-interactive (no TTY) never auto-installs → returns false
- *  so a headless/cron run just prints the manual instructions instead. */
+/** TTY-guarded y/N. Non-interactive never auto-installs → returns false so a
+ *  headless/cron run just prints the manual instructions instead.
+ *
+ *  `canPrompt()` rather than `stdin.isTTY`, and BOUNDED: preflight runs before
+ *  the daemon serves anything, so a question here that cannot be answered is a
+ *  machine that never starts. A backgrounded job has a TTY and cannot be asked
+ *  — the read raises SIGTTIN and the kernel stops the process. Silence is `no`,
+ *  which is already what this returns when nobody is there. */
 export async function promptYesNo(question, defaultYes) {
-  if (!process.stdin.isTTY) return false;
-  const { createInterface } = await import('node:readline');
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const answer = await new Promise((res) =>
-    rl.question(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `, res),
+  const { canPrompt, askWithTimeout } = await import('./tty.mjs');
+  if (!canPrompt()) return false;
+  const answer = await askWithTimeout(
+    `${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `,
+    30_000
   );
-  rl.close();
-  const a = answer.trim().toLowerCase();
+  if (answer === null) return false;
+  const a = answer.toLowerCase();
   if (!a) return defaultYes;
   return a === 'y' || a === 'yes';
 }

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/tty.mjs

@@ -0,0 +1,111 @@
+/**
+ * NO PROMPT ON THE START PATH MAY STOP THE DAEMON.
+ *
+ * This exists because 0.55.2 added a 20-second timeout to the repo-binding
+ * confirm and it did not work in the one case that mattered most. `flowviant &`
+ * from an interactive shell puts the process in a background process group; the
+ * first TTY read raises SIGTTIN (and a TTY write SIGTTOU), whose DEFAULT
+ * disposition is to STOP the process. A stopped process runs no timers, so the
+ * AbortController never fires — the guard was on the wrong side of the thing it
+ * was guarding against. The shell prints `[1]+ Stopped` and nothing else: no
+ * banner, no error, no poll, forever, and `bg` does not rescue it.
+ *
+ * Two independent defences, because either one alone has a hole:
+ *
+ *  1. `canPrompt()` — do not ask at all unless we are the terminal's FOREGROUND
+ *     process group. `stdin.isTTY` is true for a backgrounded job, so it cannot
+ *     answer this on its own; the foreground group is what actually decides
+ *     whether a read will succeed or be signalled.
+ *
+ *  2. `askWithTimeout()` — while asking, install no-op SIGTTIN/SIGTTOU handlers.
+ *     A handler (even an empty one) replaces the default STOP, so a misjudged
+ *     foreground check degrades to a read that fails or hangs — and a hang is
+ *     something the timer can now actually interrupt, because the process is
+ *     still running.
+ *
+ * The detection is best-effort by design and FAILS TOWARDS ASKING: an unknown
+ * platform returns true, because refusing to prompt a human who IS there is a
+ * worse failure than a prompt that times out on its own.
+ */
+
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Is this process in the controlling terminal's foreground process group?
+ *
+ * Linux: BOTH numbers come out of one `/proc/self/stat` read — field 5 is our
+ * own `pgrp` and field 8 is `tpgid`, the foreground group of our controlling
+ * terminal. Parsed from AFTER the last ')' because field 2 is the executable
+ * name and may itself contain spaces and parentheses.
+ *
+ * NOT `process.getpgrp()`: it DOES NOT EXIST in Node (verified on 24.16 — it
+ * throws `TypeError: process.getpgrp is not a function`). The first cut of this
+ * file called it, the throw was swallowed by the fail-open catch below, and the
+ * function therefore returned `true` unconditionally — a detector that always
+ * says "yes, a human is here" is not a detector, and only the signal handlers
+ * in `askWithTimeout` were doing any work. Caught by probing this function in
+ * isolation on a real pty; nothing else would have shown it, because the
+ * fallback it degraded to still behaves acceptably.
+ *
+ * Elsewhere: ask `ps` for both. Unknown: assume foreground (see the header).
+ */
+export function inForeground() {
+  try {
+    if (process.platform === 'linux') {
+      const stat = readFileSync('/proc/self/stat', 'utf8');
+      const after = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/);
+      const pgrp = Number(after[2]); // state ppid PGRP session tty_nr tpgid
+      const tpgid = Number(after[5]);
+      if (!Number.isFinite(tpgid) || !Number.isFinite(pgrp)) return true;
+      if (tpgid <= 0) return true; // no controlling terminal — nothing to be behind
+      return tpgid === pgrp;
+    }
+    const out = execFileSync('ps', ['-o', 'tpgid=,pgid=', '-p', String(process.pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 2000,
+    }).trim().split(/\s+/);
+    const tpgid = Number(out[0]);
+    const pgrp = Number(out[1]);
+    if (!Number.isFinite(tpgid) || !Number.isFinite(pgrp) || tpgid <= 0) return true;
+    return tpgid === pgrp;
+  } catch {
+    return true;
+  }
+}
+
+/** A human is at this terminal AND can actually be reached by a question. */
+export function canPrompt() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY) && inForeground();
+}
+
+/**
+ * Ask, and come back no matter what. Resolves the trimmed answer, or `null`
+ * when nobody answered within `timeoutMs` — the caller decides what silence
+ * means, because it is not the same answer everywhere (the binding confirm
+ * serves unbound; the project picker refuses, exactly as it does headless).
+ */
+export async function askWithTimeout(query, timeoutMs) {
+  const noop = () => {};
+  // Replacing the DEFAULT disposition is the whole point — an empty handler is
+  // enough, and it is what keeps the timer below able to run at all.
+  process.on('SIGTTIN', noop);
+  process.on('SIGTTOU', noop);
+  const rl = (await import('node:readline/promises')).createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    return (await rl.question(query, { signal: ac.signal })).trim();
+  } catch {
+    return null; // aborted, or the read failed because we are not in front
+  } finally {
+    clearTimeout(timer);
+    rl.close();
+    process.off('SIGTTIN', noop);
+    process.off('SIGTTOU', noop);
+  }
+}

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.2",
+  "version": "0.56.0",
   "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",