@critical-labs/qa-conductor 0.0.0-stage → 0.3.0

package/lib/proxy.mjs

@@ -0,0 +1,327 @@
+// Pane proxy for QA sessions. Fronts one pane's app container:
+//
+// - Holds the pane's cookies in a server-side jar. Cookies ignore ports, so
+//   two app versions behind one tailnet hostname would collide in the
+//   browser; pane Set-Cookie headers are absorbed here and never forwarded.
+// - Injects the mirror bridge <script> into text/html responses and serves
+//   the bridge file at /__qa/bridge.js (read per request, no cache). The tag
+//   carries the harness origin (data-harness), the only origin the bridge
+//   talks to.
+// - Stamps activity (onActivity) for the idle reaper.
+// - Drops tailscale serve's `Tailscale-*` identity headers before the app,
+//   which runs PR code, sees the request.
+// - Rewrites absolute http://127.0.0.1:<upstreamPort> Locations to relative
+//   so redirects stay on the pane's public origin, and drops the
+//   Referrer-Policy of a redirect that stays on the pane, so the harness's
+//   Referer still admits the next hop.
+// - Answers 421 to any request whose Host isn't loopback or an allowed
+//   hostname, before routing: a DNS-rebound page must not drive a signed-in
+//   pane. The harness server reuses the same check.
+// - Since the jar signs every request in as the operator, refuses requests
+//   other pages make, and navigations from another site that the harness did
+//   not start (lib/request-guard.mjs).
+// - Decides who may frame the pane: every response it sends carries
+//   `frame-ancestors 'self' <harness origin> <frameAncestors…>` in place of
+//   the app's own frame-ancestors directive and X-Frame-Options.
+
+import http from 'node:http'
+import { readFile } from 'node:fs/promises'
+
+import { webOrigin } from './net.mjs'
+import { paneRefusal } from './request-guard.mjs'
+
+const BRIDGE_ROUTE = '/__qa/bridge.js'
+const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '::1']
+
+const normalizeHost = h => String(h ?? '').trim().toLowerCase().replace(/^\[(.*)\]$/, '$1')
+
+// The hostname a request was addressed to: port dropped, IPv6 brackets
+// stripped, lowercased. '' when the header is missing or malformed.
+export function requestHostname(hostHeader) {
+  const h = String(hostHeader ?? '').trim().toLowerCase()
+  if (h.startsWith('[')) {
+    const end = h.indexOf(']')
+    return end === -1 ? '' : h.slice(1, end)
+  }
+  const colon = h.indexOf(':')
+  return colon === -1 ? h : h.slice(0, colon)
+}
+
+// Loopback names are always allowed; `allowedHosts` adds more hostnames.
+export function isAllowedHost(hostHeader, allowedHosts = []) {
+  const name = requestHostname(hostHeader)
+  if (!name) return false
+  return LOOPBACK_HOSTS.includes(name) || allowedHosts.some(h => normalizeHost(h) === name)
+}
+
+// `headers` adds to the 421, e.g. the pane's frame policy.
+export function misdirected(res, headers = {}) {
+  res.writeHead(421, { 'content-type': 'text/plain', ...headers })
+  res.end('421: unrecognised Host header')
+}
+
+// An http(s) origin, normalized, or null for anything else. `new URL()` alone
+// would turn a file: or data: URL into the string 'null'.
+function originOrNull(value) {
+  try { return webOrigin(value) } catch { return null }
+}
+
+// The pane's frame policy: the pane itself, the harness origin, then any
+// extra ancestors (a harness that is itself framed). Values that aren't
+// http(s) origins are dropped, and so are IPv6 literals, which a CSP source
+// can't carry. The proxy and the conductor's pane servers share it.
+export function panePolicy(harnessOrigin = null, frameAncestors = []) {
+  const sources = new Set()
+  for (const value of [harnessOrigin, ...[].concat(frameAncestors ?? [])]) {
+    const origin = originOrNull(value)
+    if (origin && !new URL(origin).hostname.startsWith('[')) sources.add(origin)
+  }
+  return ["frame-ancestors 'self'", ...sources].join(' ')
+}
+
+const escapeAttr = value => String(value).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+function bridgeTag(harnessOrigin) {
+  const data = harnessOrigin ? ` data-harness="${escapeAttr(harnessOrigin)}"` : ''
+  return `<script src="${BRIDGE_ROUTE}"${data}></script>`
+}
+
+// The upstream's own policies minus any frame-ancestors directive, plus ours.
+// Several policies in one header are comma-separated, and a browser enforces
+// each of them.
+function withFrameAncestors(upstreamCsp, frameAncestors) {
+  const upstream = Array.isArray(upstreamCsp) ? upstreamCsp.join(', ') : upstreamCsp ?? ''
+  const kept = upstream
+    .split(',')
+    .map(policy => policy.split(';').map(d => d.trim()).filter(d => d && !/^frame-ancestors(\s|$)/i.test(d)).join('; '))
+    .filter(Boolean)
+  return [...kept, frameAncestors].join(', ')
+}
+
+// Parse one Set-Cookie header into { name, value, remove }. A cookie is a
+// removal when Max-Age <= 0, Expires is in the past (Max-Age wins when both
+// are present, per RFC 6265), or the value is empty / the conventional
+// 'deleted' sentinel.
+export function parseSetCookie(header) {
+  const [pair, ...attrs] = String(header).split(';')
+  const eq = pair.indexOf('=')
+  const name = (eq === -1 ? pair : pair.slice(0, eq)).trim()
+  const value = eq === -1 ? '' : pair.slice(eq + 1).trim()
+  let maxAge = null
+  let expires = null
+  for (const attr of attrs) {
+    const i = attr.indexOf('=')
+    const key = (i === -1 ? attr : attr.slice(0, i)).trim().toLowerCase()
+    const v = i === -1 ? '' : attr.slice(i + 1).trim()
+    if (key === 'max-age') maxAge = Number(v)
+    else if (key === 'expires') expires = Date.parse(v)
+  }
+  let remove = value === '' || value === 'deleted'
+  if (maxAge !== null && !Number.isNaN(maxAge)) {
+    if (maxAge <= 0) remove = true
+  } else if (expires !== null && !Number.isNaN(expires) && expires <= Date.now()) {
+    remove = true
+  }
+  return { name, value, remove }
+}
+
+// The client's own Cookie header is kept; the jar wins on a name both have.
+function mergeCookieHeader(clientCookie, jar) {
+  const merged = new Map()
+  if (clientCookie) {
+    for (const part of String(clientCookie).split(';')) {
+      const eq = part.indexOf('=')
+      if (eq === -1) continue
+      merged.set(part.slice(0, eq).trim(), part.slice(eq + 1).trim())
+    }
+  }
+  for (const [name, value] of jar) merged.set(name, value)
+  return [...merged].map(([name, value]) => `${name}=${value}`).join('; ')
+}
+
+// tailscale serve's identity headers (the reviewer's login, name, picture)
+// are for the conductor's gate; the pane app runs PR code.
+function upstreamHeaders(req, jar) {
+  const headers = {}
+  for (const [key, value] of Object.entries(req.headers)) {
+    const k = key.toLowerCase()
+    if (k === 'host' || k === 'accept-encoding' || k === 'cookie') continue
+    if (k === 'connection' || k === 'keep-alive' || k === 'proxy-connection') continue
+    if (k.startsWith('tailscale-')) continue
+    headers[k] = value
+  }
+  headers['accept-encoding'] = 'identity'
+  const cookie = mergeCookieHeader(req.headers.cookie, jar)
+  if (cookie) headers.cookie = cookie
+  return headers
+}
+
+// A Host header's characters, as in lib/request-guard.mjs: anything else
+// (`@`, `/`) would let the URL parser read a different host from it.
+const HOST_HEADER = /^[a-z0-9.\-[\]:]+$/
+
+// True when a Location leads back to the pane that answered: a relative
+// reference, or an absolute URL whose host is the request's Host. The URL
+// parser decides, so `//x` and `/\x` count as other hosts, as in a browser.
+function staysOnPane(location, hostHeader) {
+  const host = String(hostHeader ?? '').trim().toLowerCase()
+  if (typeof location !== 'string' || !HOST_HEADER.test(host)) return false
+  try {
+    const pane = new URL(`http://${host}/`)
+    return new URL(location, pane).host === pane.host
+  } catch {
+    return false
+  }
+}
+
+function responseHeaders(upRes, upstreamPort, policy, requestHost) {
+  const headers = {}
+  for (const [key, value] of Object.entries(upRes.headers)) {
+    const k = key.toLowerCase()
+    if (k === 'set-cookie' || k === 'transfer-encoding' || k === 'connection' || k === 'keep-alive') {
+      continue
+    }
+    // X-Frame-Options would stop the harness framing the pane; our
+    // frame-ancestors (below) decides who may.
+    if (k === 'x-frame-options') continue
+    headers[k] = value
+  }
+  headers['content-security-policy'] = withFrameAncestors(headers['content-security-policy'], policy)
+  const origin = `http://127.0.0.1:${upstreamPort}`
+  if (typeof headers.location === 'string' && headers.location.startsWith(origin)) {
+    const rest = headers.location.slice(origin.length)
+    if (rest === '') headers.location = '/'
+    else if (rest.startsWith('/')) headers.location = rest
+    else if (rest.startsWith('?') || rest.startsWith('#')) headers.location = `/${rest}`
+    // anything else (e.g. a longer port sharing the prefix) is left untouched
+  }
+  // A redirect's own Referrer-Policy sets the Referer of the request it leads
+  // to. When the harness started the navigation (its iframe load, a reload,
+  // a resync, "Open in new tab"), that Referer is what admits the next hop
+  // (lib/request-guard.mjs), so an app's no-referrer or same-origin would get
+  // its own redirect refused. Without the header, the next hop keeps the
+  // policy of the page that started the navigation. Only for a redirect that
+  // stays on the pane: elsewhere the app's policy still holds.
+  const status = upRes.statusCode ?? 0
+  if (status >= 300 && status < 400 && staysOnPane(headers.location, requestHost)) delete headers['referrer-policy']
+  return headers
+}
+
+function injectBridge(body, tag) {
+  const html = body.toString('utf8')
+  const match = /<\/head>/i.exec(html)
+  const injected = match
+    ? html.slice(0, match.index) + tag + html.slice(match.index)
+    : tag + html
+  return Buffer.from(injected, 'utf8')
+}
+
+function serveBridge(bridgePath, res, policy) {
+  readFile(bridgePath).then(
+    (content) => {
+      res.writeHead(200, { 'content-type': 'text/javascript', 'content-length': content.length, 'content-security-policy': policy })
+      res.end(content)
+    },
+    () => {
+      res.writeHead(404, { 'content-type': 'text/plain', 'content-security-policy': policy })
+      res.end('bridge script not found')
+    },
+  )
+}
+
+// harnessOrigin: the origin the harness page is served at (e.g.
+// https://host:8444). Only it, the pane itself and frameAncestors may frame
+// the pane, only its Referer admits a navigation from another site, and the
+// bridge talks only to it. Without one, nothing else may frame the pane and
+// the mirror is off. Both may be values or functions resolved per request
+// (the conductor derives a port-0 harness's origin once it listens); anything
+// that isn't an http(s) origin is dropped.
+export function createPaneProxy({
+  upstreamPort, bridgePath, onActivity = () => {}, httpMod = http, allowedHosts = [], harnessOrigin = null, frameAncestors = [],
+}) {
+  // name -> value
+  const jar = new Map()
+  // A number, or a function resolved per request: the conductor points the
+  // pane at whatever port the Provisioner reserved for the running session.
+  const portOf = typeof upstreamPort === 'function' ? upstreamPort : () => upstreamPort
+  // Likewise: the conductor's pane origins may be assigned after start.
+  const hostsOf = typeof allowedHosts === 'function' ? allowedHosts : () => allowedHosts
+  const harnessOf = typeof harnessOrigin === 'function' ? harnessOrigin : () => harnessOrigin
+  const ancestorsOf = typeof frameAncestors === 'function' ? frameAncestors : () => frameAncestors
+
+  return function handler(req, res) {
+    const harness = originOrNull(harnessOf())
+    const policy = panePolicy(harness, ancestorsOf())
+    if (!isAllowedHost(req.headers.host, hostsOf())) return misdirected(res, { 'content-security-policy': policy })
+
+    const refusal = paneRefusal(req, harness)
+    if (refusal) {
+      res.writeHead(403, {
+        'content-type': 'text/plain; charset=utf-8',
+        'x-content-type-options': 'nosniff',
+        'cache-control': 'no-store',
+        'content-security-policy': policy,
+      })
+      res.end(`403: ${refusal}\n`)
+      return
+    }
+
+    const pathname = (req.url ?? '/').split('?')[0]
+    if (req.method === 'GET' && pathname === BRIDGE_ROUTE) {
+      serveBridge(bridgePath, res, policy)
+      return
+    }
+
+    onActivity()
+
+    const port = portOf()
+    if (!port) {
+      res.writeHead(503, { 'content-type': 'text/plain', 'content-security-policy': policy })
+      res.end('503: no QA session is running on this pane')
+      return
+    }
+
+    const upReq = httpMod.request(
+      {
+        host: '127.0.0.1',
+        port,
+        method: req.method,
+        path: req.url,
+        headers: upstreamHeaders(req, jar),
+      },
+      (upRes) => {
+        const rawSetCookies = upRes.headers['set-cookie'] ?? []
+        for (const raw of Array.isArray(rawSetCookies) ? rawSetCookies : [rawSetCookies]) {
+          const { name, value, remove } = parseSetCookie(raw)
+          if (!name) continue
+          if (remove) jar.delete(name)
+          else jar.set(name, value)
+        }
+
+        const headers = responseHeaders(upRes, port, policy, req.headers.host)
+        const isHtml = /^text\/html\b/i.test(upRes.headers['content-type'] ?? '')
+        if (!isHtml) {
+          res.writeHead(upRes.statusCode ?? 502, headers)
+          upRes.pipe(res)
+          return
+        }
+
+        const chunks = []
+        upRes.on('data', (chunk) => chunks.push(chunk))
+        upRes.on('end', () => {
+          const body = injectBridge(Buffer.concat(chunks), bridgeTag(harness))
+          headers['content-length'] = body.length
+          res.writeHead(upRes.statusCode ?? 502, headers)
+          res.end(body)
+        })
+      },
+    )
+
+    upReq.on('error', () => {
+      if (!res.headersSent) res.writeHead(502, { 'content-type': 'text/plain', 'content-security-policy': policy })
+      res.end('502: QA pane upstream unavailable')
+    })
+
+    req.pipe(upReq)
+  }
+}

package/lib/request-guard.mjs

@@ -0,0 +1,95 @@
+// Which page made a request (homefree #307, ported from its #329). The Host
+// allowlist stops DNS rebinding, but not a page the reviewer has open in the
+// same browser: that page can make the browser send requests to the harness
+// and the panes, and a front door that authenticates the device (tailscale
+// serve) vouches for those too. These checks keep such pages out of the
+// harness API and the panes.
+//
+// `same-site` is never enough: on loopback every port is same-site, and
+// ts.net is on the Public Suffix List, so every host in a tailnet, and every
+// port of this one, is same-site as well.
+
+import { isLoopbackHost } from './net.mjs'
+
+// A Host header's characters: a hostname, an IPv6 literal and a port. Anything
+// else (`@`, `/`) would let the URL parser read a different host from it.
+const HOST_HEADER = /^[a-z0-9.\-[\]:]+$/
+
+// True when a browser request comes from the target's own origin, or from
+// no page at all. Browsers send Sec-Fetch-Site (on trustworthy origins) or at
+// least Origin on every write; a request with neither is a non-browser client
+// (curl, a platform's own script).
+export function isSameOriginRequest(headers) {
+  const site = headers['sec-fetch-site']
+  if (site !== undefined) return site === 'same-origin' || site === 'none'
+  if (headers.origin !== undefined) {
+    try { return new URL(headers.origin).host === headers.host } catch { return false }
+  }
+  return true
+}
+
+// True unless a browser reached the harness at a host or port other than the
+// harness origin's. A page served by another handler that proxies to the
+// harness (a stale `tailscale serve` mount on another port, say) is
+// same-origin with that handler, so isSameOriginRequest admits its calls;
+// this check doesn't. Exempt:
+// - non-browser clients (neither Sec-Fetch-Site nor Origin);
+// - a null harness origin, which the conductor reports at startup;
+// - a loopback Host: the harness opened at localhost (to show its banner), a
+//   harness on port 0 that derives its origin per request, and a nested demo,
+//   whose outer pane proxy forwards with a loopback Host.
+export function isHarnessHost(headers, harnessOrigin) {
+  if (headers['sec-fetch-site'] === undefined && headers.origin === undefined) return true
+  if (harnessOrigin == null) return true
+  const host = String(headers.host ?? '').trim().toLowerCase()
+  if (!HOST_HEADER.test(host)) return false
+  let harness, request
+  try {
+    harness = new URL(harnessOrigin)
+    // Parsed with the harness's scheme, so its default port drops out too.
+    request = new URL(`${harness.protocol}//${host}`)
+  } catch {
+    return false
+  }
+  return isLoopbackHost(request.hostname) || request.host === harness.host
+}
+
+const FRAME_DESTS = new Set(['iframe', 'frame', 'embed', 'object', 'fencedframe'])
+const OTHER_SITES = new Set(['same-site', 'cross-site'])
+const NAVIGATE_MODES = new Set(['navigate', 'nested-navigate'])
+
+// The origin a Referer names, or null.
+function refererOrigin(headers) {
+  try { return new URL(headers.referer).origin } catch { return null }
+}
+
+// Why a pane proxy must refuse this request, or null to serve it. The proxy
+// adds the operator's session from its own cookie jar, so the app's SameSite
+// cookies protect nothing behind it, and the app acts as the operator on
+// every request that reaches it, whether or not the page that made it can
+// read the answer:
+// - writes and preflights must come from the pane's own pages;
+// - so must CORS reads and WebSockets (an app that echoes Origin back would
+//   otherwise hand the operator's data to the page that asked);
+// - so must subresource loads (<img>, <script>, <link>, a no-cors fetch):
+//   Sec-Fetch-Site same-site or cross-site is refused;
+// - a navigation from another site, into a frame or top-level, must come
+//   from the harness, which loads the panes in its iframes and opens them in
+//   new tabs: its Referer must be harnessOrigin (browsers send the referring
+//   origin by default). frame-ancestors, set on every response, stops only
+//   the render, after the app has handled the request.
+// A navigation the operator starts (Sec-Fetch-Site none) is served. A
+// request with no Sec-Fetch-Site (curl, or a browser too old to send it) is
+// judged by its Origin alone.
+export function paneRefusal(req, harnessOrigin = null) {
+  const headers = req.headers
+  const site = headers['sec-fetch-site']
+  const mode = headers['sec-fetch-mode']
+  const read = req.method === 'GET' || req.method === 'HEAD'
+  const fromPage = !read || mode === 'cors' || mode === 'websocket' || headers.origin !== undefined
+  if (fromPage && !isSameOriginRequest(headers)) return 'cross-site request refused'
+  if (!OTHER_SITES.has(site)) return null
+  if (!NAVIGATE_MODES.has(mode)) return 'cross-site request refused'
+  if (harnessOrigin !== null && refererOrigin(headers) === harnessOrigin) return null
+  return FRAME_DESTS.has(headers['sec-fetch-dest']) ? 'cross-site framing refused' : 'cross-site navigation refused'
+}