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

package/lib/exposure.mjs

@@ -0,0 +1,193 @@
+// The Exposure seam's pure core: the public endpoints the conductor declares,
+// and one reconcile pass over an adapter that makes them exist.
+//
+// An Exposure adapter (optional, injected by the platform; the core never
+// constructs one) publishes Mounts on a front door such as tailscale serve:
+//   Mount    = { name: 'harness'|'base'|'pr', host, port, path, target }
+//   Drift    = { mount: Mount, actual: string | null }
+//   Exposure = { ensure(mounts) -> Promise<{ added: Mount[], ok: Mount[] }>,
+//                check(mounts)  -> Promise<{ ok: boolean, drift: Drift[] }> }
+// `host` and `port` are the mount's public side, from its own origin;
+// `target` is where the conductor listens, on cfg.host. A mount is the
+// conductor's own (port, path): an adapter never touches any other handler.
+//
+// mountsFor derives every mount from the origins viewers open, so the URL a
+// viewer sees and the mount behind it can't disagree. No I/O here: the
+// adapter owns every effect, and runExpose (the qa-conductor-expose bin's
+// core) prints through the log it is given.
+
+import { defaultExposure, defaultHarnessOrigin, EXPOSURE_MODES, HARNESS_PATH } from './config.mjs'
+import { hostPort, isLoopbackHost, portOf, webOrigin } from './net.mjs'
+
+const ORIGINS = [
+  ['harness', 'the harness origin (QA_HARNESS_ORIGIN)'],
+  ['base', 'the base pane origin (QA_BASE_ORIGIN)'],
+  ['pr', 'the PR pane origin (QA_PR_ORIGIN)'],
+]
+
+const shown = value => (typeof value === 'string' ? JSON.stringify(value) : String(value))
+
+// The three mounts for `cfg`: the harness under HARNESS_PATH at
+// cfg.harnessOrigin's port, each pane at / at its origin's port. `ports` are
+// the listen ports the targets point at; pass the bound ones when cfg.ports
+// holds 0. Throws on a layout no adapter can publish.
+export function mountsFor(cfg, { ports = cfg.ports } = {}) {
+  if (!cfg.harnessOrigin) throw new Error('exposure: no harness origin to mount (set QA_HARNESS_ORIGIN)')
+  const bind = cfg.host ?? '127.0.0.1'
+  const mounts = ORIGINS.map(([name, what]) => {
+    const value = name === 'harness' ? cfg.harnessOrigin : cfg.paneOrigins?.[name]
+    if (value == null || value === '') throw new Error(`exposure: ${what} is missing`)
+    const origin = webOrigin(value, `exposure: ${what}`)
+    // tailscale serve publishes https only
+    if (!origin.startsWith('https:')) throw new Error(`exposure: ${what} ${origin} is not https, and only an https origin can be mounted`)
+    // The URL parser takes port 0, and no front door can listen there.
+    const port = portOf(origin)
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`exposure: ${what} ${origin} has no port a front door can listen on`)
+    const listen = ports?.[name]
+    if (!Number.isInteger(listen) || listen < 1 || listen > 65535) {
+      throw new Error(`exposure: the ${name} listen port must be an integer from 1 to 65535, got ${shown(listen)} (pass the bound ports)`)
+    }
+    return {
+      name,
+      host: new URL(origin).hostname,
+      port,
+      path: name === 'harness' ? HARNESS_PATH : '/',
+      target: `http://${hostPort(bind, listen)}`,
+    }
+  })
+  // `serve --https=<port>` publishes on this node's name whatever the host, so
+  // two mounts on one port would share an origin, and the harness and the
+  // two panes must be three different origins.
+  for (const [i, a] of mounts.entries()) {
+    for (const b of mounts.slice(i + 1)) {
+      if (a.port === b.port) throw new Error(`exposure: the ${a.name} and ${b.name} mounts are both on port ${a.port}: each needs a port of its own`)
+    }
+  }
+  return mounts
+}
+
+// One pass: ensure then check, or check alone with checkOnly. Never rejects:
+// exposure trouble must not take the conductor down, so an error comes back
+// as { ok: false, error }, keeping whatever ensure added: all of it when the
+// check fails, and the error's own `added` list when ensure fails part way.
+export async function reconcileExposure(exposure, mounts, { checkOnly = false, now = Date.now } = {}) {
+  let added = []
+  try {
+    if (!checkOnly) {
+      const ensured = await exposure.ensure(mounts)
+      if (!Array.isArray(ensured?.added)) throw new Error('the exposure adapter\'s ensure returned no added list')
+      added = ensured.added
+    }
+    const checked = await exposure.check(mounts)
+    if (!Array.isArray(checked?.drift)) throw new Error('the exposure adapter\'s check returned no drift list')
+    return { ok: checked.ok === true && checked.drift.length === 0, checkedAt: now(), drift: checked.drift, added, error: null }
+  } catch (err) {
+    return { ok: false, checkedAt: now(), drift: [], added: addedOn(err) ?? added, error: messageOf(err) }
+  }
+}
+
+// The adapter is platform code and may throw anything: a value with no
+// primitive form (Object.create(null)), or one whose getters throw, must not
+// turn the result into a rejection.
+function messageOf(err) {
+  try {
+    return String(err?.message ?? err)
+  } catch {
+    return 'the exposure adapter threw a value that is not an Error'
+  }
+}
+
+function addedOn(err) {
+  try {
+    return Array.isArray(err?.added) ? err.added : null
+  } catch {
+    return null
+  }
+}
+
+// The expose CLI's core: one pass for `cfg` over `exposure`, printed for an
+// operator, as an exit code. It is the conductor's own pass (mountsFor, then
+// reconcileExposure) on the configured ports, so the two can't disagree
+// about what should be mounted. 0: nothing to do (none mode), or every mount
+// in place; 1: drift remains, or the adapter failed; 2: a mode, bind host or
+// mount layout the conductor would refuse or no front door can publish.
+// Never rejects for anything the adapter does.
+export async function runExpose({ cfg, exposure, checkOnly = false, log = console }) {
+  // A cfg with no exposure or harnessOrigin resolves both as startConductor
+  // does; loadConfig's always has both.
+  let host, harnessOrigin, mode, because
+  try {
+    host = cfg.host ?? '127.0.0.1'
+    // startConductor refuses this too: every target would be http://[[::1]]:port.
+    if (/^\[.*\]$/.test(host)) {
+      throw new Error(`the bind host (QA_BIND_HOST, cfg.host) takes an IPv6 literal without brackets, as the conductor requires: use ${JSON.stringify(host.slice(1, -1))}, not ${JSON.stringify(host)}`)
+    }
+    harnessOrigin = cfg.harnessOrigin ?? defaultHarnessOrigin({ publicHost: cfg.publicHost, host, port: cfg.ports?.harness })
+    // `because` names what made a defaulted mode tailscale, for the error below
+    const resolved = cfg.exposure != null ? { mode: cfg.exposure, because: null } : defaultExposure({
+      harnessOrigin, paneOrigins: cfg.paneOrigins, publicHost: cfg.publicHost, allowedHosts: cfg.allowedHosts ?? [], host,
+    })
+    mode = resolved.mode
+    because = resolved.because
+  } catch (err) {
+    log.error(`qa exposure: ${err.message}`)
+    return 2
+  }
+  if (!EXPOSURE_MODES.includes(mode)) {
+    log.error(`qa exposure: QA_EXPOSURE must be none or tailscale, got ${shown(mode)}`)
+    return 2
+  }
+  // An ungated conductor must not publish itself, so there is nothing to do.
+  if (mode === 'none') {
+    log.log('qa exposure: QA_EXPOSURE=none, nothing to do')
+    return 0
+  }
+  // The identity gate trusts Tailscale-User-Login only on a loopback bind, so
+  // loadConfig and startConductor refuse tailscale mode anywhere else, and
+  // the CLI must not publish a layout the conductor won't run.
+  if (!isLoopbackHost(host)) {
+    const why = because ? `QA_EXPOSURE defaults to tailscale because ${because} is not loopback` : 'QA_EXPOSURE is tailscale'
+    log.error(`qa exposure: ${why}, and the conductor runs tailscale mode only on a loopback bind host (QA_BIND_HOST, cfg.host), got ${JSON.stringify(host)}`)
+    return 2
+  }
+  let mounts
+  try {
+    mounts = mountsFor({ ...cfg, harnessOrigin })
+  } catch (err) {
+    log.error(`qa exposure: ${String(err.message).replace(/^exposure: /, '')}`)
+    return 2
+  }
+  const result = await reconcileExposure(exposure, mounts, { checkOnly })
+  try {
+    report(result, log)
+  } catch {
+    // The adapter is platform code: a mount whose getters throw.
+    log.error('qa exposure: the adapter returned a result that cannot be printed')
+    return 1
+  }
+  if (result.ok) {
+    log.log(`qa exposure: ok (harness ${webOrigin(harnessOrigin)}${HARNESS_PATH}/)`)
+    return 0
+  }
+  return 1
+}
+
+function report(result, log) {
+  for (const m of result.added) log.log(`qa exposure: mounted ${at(m)} -> ${field(m?.target)}`)
+  for (const { mount, actual } of result.drift) {
+    // A handler under the mount's path, which check names by its path: no
+    // ensure replaces it, since it isn't the conductor's.
+    if (typeof actual === 'string' && actual.startsWith('/')) {
+      log.error(`qa exposure: drift ${at(mount)}: the handler at ${actual} takes some of its requests; remove it`)
+    } else {
+      log.error(`qa exposure: drift ${at(mount)}: want ${field(mount?.target)}, have ${typeof actual === 'string' ? actual : 'nothing'}`)
+    }
+  }
+  if (result.error !== null) log.error(`qa exposure: ${result.error}`)
+  else if (!result.ok && result.drift.length === 0) log.error('qa exposure: the adapter reported drift but named no mount')
+}
+
+// A mount as the adapter returned it, printed: only the Mount type's own
+// values (a string, an integer port) are shown, anything else as `?`.
+const field = value => (typeof value === 'string' || Number.isInteger(value) ? String(value) : '?')
+const at = m => `${field(m?.port)}${field(m?.path)}`

package/lib/github.mjs

@@ -0,0 +1,218 @@
+// GitHub API client for the QA conductor. All effects go through the injected
+// fetchFn (and sleepFn for polling) so tests never touch the network.
+
+const API = 'https://api.github.com'
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+// `packageName` is the GHCR container package the GHCR helpers (tag lookup,
+// RC baseline, preview-image wait) read; only those helpers need it. The
+// versions endpoint is the authed-user path (`/user/...`); GHCR-under-an-org
+// would need `/orgs/{owner}/...` — a follow-up when a consumer needs it.
+//
+// `token` authorizes the repo calls (pulls, collaborators, workflow dispatch
+// and runs, issue comments and labels). `packagesToken` authorizes only the
+// package versions listing, which a fine-grained PAT cannot call: pass a
+// classic PAT with read:packages there (cfg.ghcrToken). It defaults to
+// `token`.
+export function createGithub({
+  token,
+  packagesToken = token,
+  repo,
+  fetchFn = fetch,
+  packageName = null,
+  // which GHCR tags count as release candidates for latestRcTag
+  rcTagPattern = /-rc\.\d+$/,
+  // the workflow that builds PR preview images, and the ref it is dispatched on
+  previewWorkflow = 'pr-preview.yml',
+  previewRef = 'main',
+  // the exclusive verdict label pair: [accept, reject]
+  qaLabels = ['qa-approved', 'qa-changes-requested'],
+}) {
+  const packageVersionsPath = () => {
+    if (!packageName) throw new Error('createGithub: packageName is required for GHCR lookups')
+    return `/user/packages/container/${packageName}/versions`
+  }
+  async function request(method, path, body, auth = token) {
+    return fetchFn(`${API}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${auth}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    })
+  }
+
+  async function requestJson(method, path, body, auth = token) {
+    const res = await request(method, path, body, auth)
+    if (!res.ok) {
+      const text = await res.text()
+      throw new Error(`github ${method} ${path} -> ${res.status}: ${text.slice(0, 200)}`)
+    }
+    if (res.status === 204) return null
+    return res.json()
+  }
+
+  async function* packageVersions() {
+    for (let page = 1; ; page++) {
+      const versions = await requestJson('GET', `${packageVersionsPath()}?per_page=100&page=${page}`, undefined, packagesToken)
+      for (const version of versions) yield version
+      if (versions.length < 100) return
+    }
+  }
+
+  function versionTags(version) {
+    return version.metadata?.container?.tags ?? []
+  }
+
+  // Who opened a PR and where its head lives: the inputs a BuildConvention's
+  // trust gate judges. head.repo is null when the head repository was deleted.
+  function trustFields(pr) {
+    return {
+      authorAssociation: pr.author_association ?? null,
+      headRepo: pr.head.repo?.full_name ?? null,
+      headOwner: pr.head.repo?.owner?.login ?? null,
+    }
+  }
+
+  async function listOpenPrs() {
+    const prs = await requestJson('GET', `/repos/${repo}/pulls?state=open&per_page=50`)
+    return prs.map((pr) => ({
+      number: pr.number,
+      title: pr.title,
+      headSha: pr.head.sha,
+      headRef: pr.head.ref,
+      author: pr.user.login,
+      ...trustFields(pr),
+    }))
+  }
+
+  async function prHead(num) {
+    const pr = await requestJson('GET', `/repos/${repo}/pulls/${num}`)
+    return pr.head.sha
+  }
+
+  async function prInfo(num) {
+    const pr = await requestJson('GET', `/repos/${repo}/pulls/${num}`)
+    const { authorAssociation, headRepo, headOwner } = trustFields(pr)
+    return {
+      number: pr.number,
+      headSha: pr.head.sha,
+      author: pr.user?.login ?? null,
+      authorAssociation,
+      isDraft: Boolean(pr.draft),
+      headRepo,
+      headOwner,
+    }
+  }
+
+  // The login's effective permission on the repo: admin | write | read | none.
+  // author_association alone is no access check (a read-only outside
+  // collaborator is still COLLABORATOR), so trust gates ask this too.
+  async function authorPermission(login) {
+    const res = await requestJson('GET', `/repos/${repo}/collaborators/${encodeURIComponent(login)}/permission`)
+    return res.permission
+  }
+
+  async function ghcrTagExists(tag) {
+    for await (const version of packageVersions()) {
+      if (versionTags(version).includes(tag)) return true
+    }
+    return false
+  }
+
+  async function latestRcTag() {
+    let bestTag = null
+    let bestUpdated = ''
+    for await (const version of packageVersions()) {
+      const tag = versionTags(version).find((t) => rcTagPattern.test(t))
+      if (tag && (!bestTag || version.updated_at > bestUpdated)) {
+        bestTag = tag
+        bestUpdated = version.updated_at
+      }
+    }
+    return bestTag
+  }
+
+  async function dispatchPreviewBuild(num) {
+    await requestJson('POST', `/repos/${repo}/actions/workflows/${previewWorkflow}/dispatches`, {
+      ref: previewRef,
+      inputs: { pr: String(num) },
+    })
+  }
+
+  async function awaitPreviewImage(num, sha, { timeoutMs = 900000, pollMs = 15000, sleepFn = defaultSleep, signal } = {}) {
+    const tag = `pr-${num}-${sha.slice(0, 12)}`
+    let waited = 0
+    for (;;) {
+      // A cancelled boot (teardown/takeover) must stop polling promptly rather
+      // than hold its wait for up to timeoutMs.
+      if (signal?.aborted) throw Object.assign(new Error(`aborted waiting for GHCR tag ${tag}`), { name: 'AbortError' })
+      if (await ghcrTagExists(tag)) return tag
+      if (waited >= timeoutMs) throw new Error(`timed out after ${timeoutMs}ms waiting for GHCR tag ${tag}`)
+      await sleepFn(pollMs)
+      waited += pollMs
+    }
+  }
+
+  function runReferencesPr(run, num) {
+    const hay = `${run.display_title ?? ''} ${run.head_branch ?? ''} ${run.name ?? ''}`
+    return new RegExp(`(^|[^0-9])${num}([^0-9]|$)`).test(hay)
+  }
+
+  async function findPreviewRun(num) {
+    const data = await requestJson('GET', `/repos/${repo}/actions/workflows/${previewWorkflow}/runs?per_page=10`)
+    const runs = Array.isArray(data) ? data : (data?.workflow_runs ?? [])
+    if (runs.length === 0) return null
+    const byRecency = [...runs].sort((a, b) => (b.created_at ?? '').localeCompare(a.created_at ?? ''))
+    const chosen = byRecency.find((run) => runReferencesPr(run, num)) ?? byRecency[0]
+    return {
+      url: chosen.html_url,
+      status: chosen.status,
+      conclusion: chosen.conclusion ?? null,
+      startedAt: chosen.run_started_at ?? chosen.created_at,
+    }
+  }
+
+  async function listPrImageTags() {
+    const tags = new Set()
+    for await (const version of packageVersions()) {
+      for (const tag of versionTags(version)) tags.add(tag)
+    }
+    return [...tags]
+  }
+
+  async function postComment(num, body) {
+    const comment = await requestJson('POST', `/repos/${repo}/issues/${num}/comments`, { body })
+    return comment.html_url
+  }
+
+  async function setQaLabel(num, label) {
+    if (!qaLabels.includes(label)) throw new Error(`unknown QA label: ${label}`)
+    const opposite = qaLabels.find((l) => l !== label)
+    await requestJson('POST', `/repos/${repo}/issues/${num}/labels`, { labels: [label] })
+    const res = await request('DELETE', `/repos/${repo}/issues/${num}/labels/${encodeURIComponent(opposite)}`)
+    if (!res.ok && res.status !== 404) {
+      const text = await res.text()
+      throw new Error(`github DELETE label ${opposite} -> ${res.status}: ${text.slice(0, 200)}`)
+    }
+  }
+
+  return {
+    listOpenPrs,
+    prHead,
+    prInfo,
+    authorPermission,
+    ghcrTagExists,
+    latestRcTag,
+    dispatchPreviewBuild,
+    awaitPreviewImage,
+    findPreviewRun,
+    listPrImageTags,
+    postComment,
+    setQaLabel,
+  }
+}

package/lib/identity.mjs

@@ -0,0 +1,51 @@
+// Tailscale identity gate for the harness and both pane proxies (#307).
+//
+// tailscale serve sets Tailscale-User-Login on the requests it proxies from a
+// user's device, strips any copy the client sent, and sets none for tagged
+// devices. The header can be trusted only because the conductor listens on
+// loopback (cfg.host), so serve on the same host is the only way in.
+//
+// The allowlist is cfg.allowedLogins, from the comma-separated
+// QA_ALLOWED_LOGINS. The names and refusal strings are homefree #329's, which
+// its access-guard tests assert.
+
+const LOGIN_HEADER = 'tailscale-user-login'
+
+function headerValue(headers, name) {
+  for (const [key, value] of Object.entries(headers ?? {})) {
+    if (key.toLowerCase() === name) return Array.isArray(value) ? value.join(', ') : String(value)
+  }
+  return undefined
+}
+
+export function normalizeLogins(list) {
+  return (list ?? []).map(login => String(login).trim().toLowerCase()).filter(Boolean)
+}
+
+// Why a request must be refused, or null to serve it. An empty allowlist
+// refuses everyone.
+export function refusalReason(headers, allowlist) {
+  const login = headerValue(headers, LOGIN_HEADER)?.trim()
+  if (!login) return 'no Tailscale identity: open this through tailscale serve from an allowed user\'s device'
+  if (!normalizeLogins(allowlist).includes(login.toLowerCase())) return `${login} is not in QA_ALLOWED_LOGINS`
+  return null
+}
+
+export function isAllowed(headers, allowlist) {
+  return refusalReason(headers, allowlist) === null
+}
+
+// Wraps a request handler so that only allowed logins reach it; the rest get
+// a short plain-text 403 that carries no conductor state.
+export function identityGate(handler, allowlist) {
+  return (req, res) => {
+    const reason = refusalReason(req.headers, allowlist)
+    if (reason === null) return handler(req, res)
+    res.writeHead(403, {
+      'content-type': 'text/plain; charset=utf-8',
+      'x-content-type-options': 'nosniff',
+      'cache-control': 'no-store',
+    })
+    res.end(`403: ${reason}\n`)
+  }
+}

package/lib/net.mjs

@@ -0,0 +1,56 @@
+// Address and origin helpers shared by the config loader, the servers and the
+// request guards. Pure: no I/O.
+
+import { isIPv4 } from 'node:net'
+
+// A hostname a CSP source and a Host allowlist can both carry: DNS labels
+// (letters, digits, `-`) or a bracketed IPv6 literal. The URL parser accepts
+// more (`;`, `,`, `'`, `*`), and those would change a policy's meaning.
+const SAFE_HOSTNAME = /^(?:[a-z0-9-]+(?:\.[a-z0-9-]+)*\.?|\[[0-9a-f:.]+\])$/
+
+// host:port, with brackets around an IPv6 literal.
+export const hostPort = (host, port) => (host.includes(':') ? `[${host}]:${port}` : `${host}:${port}`)
+
+// True for 127.0.0.0/8, ::1 and localhost. `[]` is stripped, since
+// URL.hostname keeps it on an IPv6 literal.
+export function isLoopbackHost(name) {
+  const h = String(name ?? '').toLowerCase().replace(/^\[(.*)\]$/, '$1')
+  return h === '::1' || h === 'localhost' || (isIPv4(h) && h.startsWith('127.'))
+}
+
+// A web origin, normalized: scheme and host lowercased, a default port, any
+// path and a trailing slash dropped. Anything that isn't an http(s) URL with
+// a plain hostname throws, naming `what` (a config key or a cfg field).
+// `new URL('file:///x').origin` and a data: URL's are the string 'null'.
+export function webOrigin(value, what = 'an origin') {
+  let url
+  try { url = new URL(value) } catch { url = null }
+  if ((url?.protocol !== 'https:' && url?.protocol !== 'http:') || !SAFE_HOSTNAME.test(url.hostname)) {
+    const shown = typeof value === 'string' ? JSON.stringify(value) : String(value)
+    throw new Error(`${what} must be an origin such as https://host:8444, got ${shown}`)
+  }
+  return url.origin
+}
+
+// The port an http(s) origin is served on: its own, else the scheme's default
+// (443 for https, 80 for http), which URL.port leaves empty.
+export function portOf(origin) {
+  const url = new URL(origin)
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') throw new Error(`portOf needs an http(s) origin, got ${JSON.stringify(String(origin))}`)
+  return Number(url.port || (url.protocol === 'https:' ? 443 : 80))
+}
+
+// Throws unless browsers send Fetch Metadata (Sec-Fetch-*) to `origin`, a
+// webOrigin() result. They send it only to potentially trustworthy origins:
+// https, and http on a loopback host. Without it, and with no Origin on a
+// GET, another page's <img>, <iframe> or link looks like a non-browser
+// client, so `guard` (the request guard that depends on it) would admit it.
+// The message names `what` (a config key or a cfg field).
+export function requireFetchMetadata(origin, what, guard) {
+  const url = new URL(origin)
+  if (url.protocol === 'https:' || isLoopbackHost(url.hostname)) return
+  throw new Error(
+    `${what} ${origin}: browsers send no Sec-Fetch-* headers to a plain-http origin off loopback, ` +
+      `so the ${guard} can't tell other pages apart; use https or a loopback address`,
+  )
+}