@vzn/vx-devtools 0.0.0-stage → 0.0.648

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VZN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @vzn/vx-devtools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Website: <https://vznjs.github.io/vx/> · source: <https://github.com/vznjs/vx>
+
+Code vx's servers and plugins share. Core never imports it.
+
+## Purpose
+
+First, the CI tokens vx's servers take. `@vzn/vx-cache-server` and
+`@vzn/vx-history-server` take one kind of token: a CI job's OIDC token
+(GitHub Actions, GitLab CI). This package is the check both share. It imports only jose, so a server on Workers
+bundles it alone. Clients never import it: each plugin asks its CI for
+its own token. The token alone decides
+what a request reads and where it writes, never a header or a client
+option.
+
+## API
+
+- `parseAllow(list)` reads `ALLOW` (space-separated `issuer:owner/repo:workflow` entries, the string the DTE relay reads) into `Allowed`s; `oidcAuth(options)` is the `Authorize` checking a request's CI token against
+  them (its options an `OidcOptions`), answering its `Access` or throwing a `Refusal` (`status` and what
+  to fix). `oidcTokenAuth(options)` is the check for a server whose
+  requests name their repository plainly, in the body (`@vzn/vx-history-server`):
+  `(req, named?)`, `named` a `Repo`, answers the token's `Access`, refusing a token of
+  another repository than `named`; with no token where `readAccess` is
+  `public`, `named` when ALLOW names it, or `undefined` when none is named.
+- `errorJson(status, message)` is every server's refusal, `{ code, message }`
+  (Turbo's spec's `Error`); `notAllowed(allow)` its `405`, naming the methods in `Allow`.
+- `hashPart(text)` is what a server stores in place of an issuer, a repository name or a scope: the first
+  128 bits of its SHA-256 in hex (Web Crypto, so Bun and Workers agree), never the plain value.
+- `statusLine(tone, name, text)` is the line a server prints when it starts (`'ok'`) or refuses to
+  (`'err'`): `✓ vx-cache-server  listening on …`, painted as vx's own status lines (NO_COLOR, then
+  FORCE_COLOR, then a terminal whose `TERM` is not `dumb`), with any lines after the first dim.
+
+```ts
+export class Refusal extends Error {
+  readonly status: number
+}
+export function errorJson(status: number, message: string): Response
+export function notAllowed(allow: string): Response
+export interface Allowed {
+  readonly issuer: string
+  readonly repository: string
+  readonly workflow: string
+}
+export interface Access {
+  readonly issuer: string
+  readonly repository: string
+  readonly write?: string
+}
+export type Authorize = (req: Request) => Promise<Access>
+export interface OidcOptions {
+  readonly allow: readonly Allowed[]
+  readonly audience?: string
+  readonly fetchJson?: (url: string) => Promise<unknown>
+  readonly now?: () => number
+  readonly readAccess?: string
+}
+export function parseAllow(list: string): Allowed[]
+export function oidcAuth(opts: OidcOptions): Authorize
+export interface Repo {
+  readonly issuer: string
+  readonly repository: string
+}
+export function oidcTokenAuth(
+  opts: OidcOptions,
+): (req: Request, named?: Repo) => Promise<Access | undefined>
+```
+
+## How it decides
+
+- jose checks the JWT: `RS256`, the signature against the issuer's keys
+  (found through its `/.well-known/openid-configuration`, kept and
+  refetched by `createRemoteJWKSet`), `aud`, `exp` and `nbf` within 60 s.
+- With `oidcAuth`, every request names its repository: `vx-issuer` and `vx-repository`,
+  the `hashPart`s of the issuer's URL (no trailing slash) and of its
+  `org/name` lowercased; one missing or not a hash is `400`.
+- The token's repository is its issuer (a trailing slash, in `ALLOW` or
+  the token, is the same issuer) and its name, `org/name` lowercased: `repository` (GitHub) or `project_path` (GitLab), what a
+  checkout's origin names (2026-10-25). One `ALLOW` does not name is
+  `403`, and so is one other than the request names.
+- The token's workflow (`job_workflow_ref` on GitHub, `ci_config_ref_uri`
+  on GitLab, up to the `@` before its ref) must be one an entry names for that
+  repository: any other is `403`.
+- With `readAccess: 'public'` (`READ_ACCESS`), a request with no token
+  reads the repository it names when `ALLOW` names it (else `403`), and
+  writes nothing. Any other value than `public` or unset throws.
+- A token writes its `ref` (GitLab's `ref_path`): a `pull_request` run
+  its merge ref, `refs/pull/<n>/merge`, never its `head_ref`, which a fork
+  names; a `merge_group` run its base branch for a
+  `refs/heads/gh-readonly-queue/<base>/pr-<n>-<sha>` ref. A
+  `pull_request_target`, `issue_comment` or `workflow_run` run writes
+  nothing: its `ref` is the base while it may run a pull request's code.
+  Nor does a GitLab merge request pipeline unless `source_project_path` (GitLab
+  19.5+) names its own project: a fork's runs in the parent project.

package/index.ts

@@ -0,0 +1,4 @@
+// Root entry shim: Bun's `--compile` binaries resolve an on-disk package
+// by `<pkg>/index.ts` and ignore package.json `exports` / `main` (see
+// packages/vx/index.ts). Same module as the exports map names.
+export * from './src/index.js'

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@vzn/vx-devtools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.648",
+  "license": "MIT",
+  "description": "Code vx's servers and plugins share, never core: first, the CI OIDC token check.",
+  "keywords": [
+    "vx",
+    "monorepo",
+    "oidc",
+    "ci"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.4.4"
+  },
+  "//": [
+    "jose: checks each JWT (signature, algorithm, audience, times) and keeps the issuers' key sets.",
+    "@vzn/vx: vx.config.ts's core, for the tasks only; the package never imports it."
+  ],
+  "dependencies": {
+    "jose": "6.2.13"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vznjs/vx.git",
+    "directory": "packages/vx-devtools"
+  },
+  "homepage": "https://github.com/vznjs/vx/tree/main/packages/vx-devtools#readme",
+  "bugs": "https://github.com/vznjs/vx/issues"
+}

package/src/hash-part.ts

@@ -0,0 +1,23 @@
+// What a server stores in place of an issuer, a repository name or a scope
+// (2026-10-25: "issuer and scope should be hashed"): a cache object's
+// name and a history row hold no plain value of a token's.
+
+const parts = new Map<string, Promise<string>>()
+
+/**
+ * SHA-256's first 128 bits of `text` in hex. Web Crypto, so Bun and
+ * Workers name alike; a few strings recur per node, so each is hashed once.
+ */
+export function hashPart(text: string): Promise<string> {
+  let got = parts.get(text)
+  if (got === undefined) {
+    if (parts.size >= 10_000) parts.clear()
+    got = crypto.subtle
+      .digest('SHA-256', new TextEncoder().encode(text))
+      .then((d) =>
+        [...new Uint8Array(d, 0, 16)].map((b) => b.toString(16).padStart(2, '0')).join(''),
+      )
+    parts.set(text, got)
+  }
+  return got
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// @vzn/vx-devtools: code vx's servers and plugins share, never core. First,
+// the CI token check, and the hash a server stores in place of a token's values. It imports only
+// jose, so a server on Workers bundles it alone.
+
+export {
+  type Access,
+  type Allowed,
+  type Authorize,
+  oidcAuth,
+  oidcTokenAuth,
+  type OidcOptions,
+  parseAllow,
+  type Repo,
+} from './oidc.js'
+export { hashPart } from './hash-part.js'
+export { statusLine } from './terminal.js'
+export { errorJson, notAllowed, Refusal } from './refusal.js'

package/src/oidc.ts

@@ -0,0 +1,420 @@
+// CI OIDC tokens, the only tokens vx's servers take (@vzn/vx-cache-server,
+// @vzn/vx-history-server): a job's token names its repository and the one
+// scope it writes, its own branch, never a header or a client option. A
+// cache request names its issuer and repository by their hashes (2026-10-25:
+// the user names them, no client guesses), which a token must match; a
+// history request names them plainly in its body (`oidcTokenAuth`).
+// Who may take part is `ALLOW`, the string @vzn/vx-dte-server reads
+// (2026-10-26: that string and nothing else): `issuer:owner/repo:workflow`
+// entries. `READ_ACCESS=public` lets a request with no token read a
+// repository ALLOW names. Any other repository is refused. The JWT itself is
+// jose's to check: signature, algorithm, audience and times.
+
+import { hashPart } from './hash-part.js'
+import { Refusal } from './refusal.js'
+import {
+  createRemoteJWKSet,
+  customFetch,
+  decodeJwt,
+  errors,
+  jwtVerify,
+  type JWTPayload,
+} from 'jose'
+
+/** One entry of `ALLOW`: the jobs of one workflow file of one repository at one issuer. */
+export interface Allowed {
+  /** The issuer's URL, `https://token.actions.githubusercontent.com`. */
+  readonly issuer: string
+  /** `owner/repo` (a GitLab project's full path), matched without case. */
+  readonly repository: string
+  /** The workflow file its jobs are defined in (`ci.yml`, GitLab's `.gitlab-ci.yml`), matched without case. */
+  readonly workflow: string
+}
+
+/** What a request may do: read its repository's scopes, and write `write` when set. */
+export interface Access {
+  /**
+   * The issuer, as its tokens name it (`https://token.actions.githubusercontent.com`):
+   * it signs the token, so two platforms' repositories never meet.
+   */
+  readonly issuer: string
+  /**
+   * The repository at that issuer, lowercased: `org/name` (`repository`,
+   * GitLab's `project_path`, 2026-10-25), what a checkout's origin names.
+   */
+  readonly repository: string
+  /** The token's own ref: the one scope it writes. */
+  readonly write?: string
+}
+
+export type Authorize = (req: Request) => Promise<Access>
+
+const GITHUB = 'https://token.actions.githubusercontent.com'
+
+/** The headers naming a request's issuer and repository, each its `hashPart`. */
+const ISSUER_HEADER = 'vx-issuer'
+const REPOSITORY_HEADER = 'vx-repository'
+const PART = /^[0-9a-f]{32}$/
+
+/** The claim naming a token's repository, `org/name`. */
+const repoClaimOf = (iss: string): string => (iss === GITHUB ? 'repository' : 'project_path')
+/** The claim naming the workflow a token's job is defined in, up to the `@` before its ref. */
+const workflowClaimOf = (iss: string): string =>
+  iss === GITHUB ? 'job_workflow_ref' : 'ci_config_ref_uri'
+
+/**
+ * `ALLOW`'s entries, space separated, each
+ * `issuer:owner/repo:workflow`, as @vzn/vx-dte-server reads it: read from
+ * the right, since the issuer holds `:`s of its own.
+ */
+export function parseAllow(list: string): Allowed[] {
+  return list
+    .split(/\s+/)
+    .filter((e) => e !== '')
+    .map((e) => {
+      // One grammar on every server: read as a separator nowhere, a comma
+      // would end up inside a workflow name no token ever carries.
+      if (e.includes(','))
+        throw new Error(`${e} is not issuer:owner/repo:workflow: entries are space separated`)
+      const w = e.lastIndexOf(':')
+      const r = e.lastIndexOf(':', w - 1)
+      const [issuer, repository, workflow] = [e.slice(0, r), e.slice(r + 1, w), e.slice(w + 1)]
+      // Loopback over plain HTTP too: a server's own tests (its container's)
+      // run an issuer beside it, and no one else reaches that address.
+      // Its host, not its spelling: `http://127.0.0.1:80@x.example` is x.example.
+      const https =
+        issuer.startsWith('https://') ||
+        (issuer.startsWith('http://') && URL.parse(issuer)?.hostname === '127.0.0.1')
+      // An entry missing a part splits elsewhere: its issuer is then no URL.
+      const url = /^[a-z][a-z0-9+.-]*:\/\/[^/]/i.test(issuer)
+      if (r < 0 || !url || !repository.includes('/') || workflow === '') {
+        throw new Error(`${e} is not issuer:owner/repo:workflow`)
+      }
+      if (!https)
+        throw new Error(
+          `${e}: the issuer is https://, not ${issuer} (plain http only on 127.0.0.1)`,
+        )
+      return { issuer, repository, workflow }
+    })
+}
+
+/** What `workflowClaimOf(iss)` says, up to the `@` before its ref, for a job of `workflow` in `repository`. */
+function workflowPath(iss: string, repository: string, workflow: string): string {
+  return iss === GITHUB
+    ? `${repository}/.github/workflows/${workflow}`
+    : `${iss.replace(/^https?:\/\//, '').replace(/\/$/, '')}/${repository}//${workflow}`
+}
+
+const same = (a: string, b: string): boolean => a.toLowerCase() === b.toLowerCase()
+
+/** GitHub's merge queue ref, `refs/heads/gh-readonly-queue/<base>/pr-<n>-<sha>`. */
+const QUEUE = /^refs\/heads\/gh-readonly-queue\/(.+)\/pr-\d+-(?:[0-9a-f]{40}|[0-9a-f]{64})$/
+
+/**
+ * GitHub events that run in the base branch's context on a pull request's
+ * behalf (design cache-signing-2026-10.md, "Events"): the token carries the
+ * base's `ref` while the job may run the pull request's code, a fork's
+ * included, which must never write the base.
+ */
+const ON_BEHALF = new Set(['pull_request_target', 'issue_comment', 'workflow_run'])
+
+/**
+ * The scope a token writes: its `ref`, GitLab's `ref_path`. A GitHub pull
+ * request's run writes its merge ref, `refs/pull/<n>/merge`, never its
+ * `head_ref`: a fork names that, and no claim tells a fork's from the
+ * repository's own, so a fork's branch `release` wrote release. A merge
+ * queue's (`merge_group`) run writes its base branch, which its code is
+ * about to become (2026-10-25: "just strip it"); only its ref is renamed:
+ * anyone can push a branch named like a queue ref. A run of an event in
+ * `ON_BEHALF` writes nothing. A GitLab merge request pipeline writes its source branch
+ * only when `source_project_path` names its own project: a fork's runs in
+ * the parent project with the fork's branch as its `ref_path`, and a
+ * GitLab before 19.5 names no source project.
+ */
+function branchOf(iss: string, claims: JWTPayload): string | undefined {
+  if (iss !== GITHUB && claims['pipeline_source'] === 'merge_request_event') {
+    const own = (claim: string) => {
+      const p = claims[claim]
+      return typeof p === 'string' && same(p, String(claims['project_path']))
+    }
+    if (
+      !own('source_project_path') ||
+      (claims['job_project_path'] !== undefined && !own('job_project_path'))
+    )
+      return undefined
+  }
+  const event = claims['event_name']
+  if (ON_BEHALF.has(event as string)) return undefined
+  const ref = iss === GITHUB ? claims['ref'] : claims['ref_path']
+  if (typeof ref !== 'string' || !ref.startsWith('refs/') || ref.length > 512) return undefined
+  const queued = iss === GITHUB && event === 'merge_group' ? QUEUE.exec(ref) : null
+  return queued === null ? ref : `refs/heads/${queued[1]}`
+}
+
+export interface OidcOptions {
+  /** `ALLOW` (`parseAllow`): who may take part. */
+  readonly allow: readonly Allowed[]
+  /** The `aud` a token must name; unset, the origin the server is reached at. */
+  readonly audience?: string
+  /** Reads a URL as JSON; tests serve keys without a network. */
+  readonly fetchJson?: (url: string) => Promise<unknown>
+  /** Seconds since the epoch; tests move the clock. */
+  readonly now?: () => number
+  /** `READ_ACCESS`: `public` lets a request with no token read a repository ALLOW names. */
+  readonly readAccess?: string | undefined
+}
+
+/** Clock skew a token's `exp` / `nbf` may be off by. */
+const LEEWAY_S = 60
+
+/** The `Access` a request's verified CI token has; a refused one throws a 401 or 403. */
+export function oidcAuth(opts: OidcOptions): Authorize {
+  const open = readAccessOf(opts)
+  // The repositories ALLOW names, by their hashes: what a public read may name.
+  let named: Promise<Map<string, Access>> | undefined
+  const allowed = () =>
+    (named ??= Promise.all(
+      opts.allow.map(async (a) => {
+        const repo = { issuer: issuerOf(a.issuer), repository: a.repository.toLowerCase() }
+        return [`${await hashPart(repo.issuer)}/${await hashPart(repo.repository)}`, repo] as [
+          string,
+          Access,
+        ]
+      }),
+    ).then((pairs) => new Map(pairs)))
+  const verify = tokenVerifier(opts)
+
+  return async (req) => {
+    if (opts.allow.length === 0)
+      throw new Refusal(401, 'ALLOW is empty: set it to the CI workflows this server serves')
+    const asked = `${req.headers.get(ISSUER_HEADER)}/${req.headers.get(REPOSITORY_HEADER)}`
+    if (!asked.split('/').every((p) => PART.test(p)))
+      throw new Refusal(
+        400,
+        `${ISSUER_HEADER} and ${REPOSITORY_HEADER}: the issuer's and the repository's hashes (PROTOCOL.md § Keys)`,
+      )
+    const bearer = bearerOf(req)
+    if (bearer === undefined) {
+      if (!open) throw new Refusal(401, 'no bearer token')
+      const repo = (await allowed()).get(asked)
+      if (repo === undefined)
+        throw new Refusal(403, "the repository named is not in this server's ALLOW")
+      return repo
+    }
+    const access = await verify(bearer, req)
+    if (`${await hashPart(access.issuer)}/${await hashPart(access.repository)}` !== asked)
+      throw new Refusal(
+        403,
+        `the token is of ${repoClaimOf(access.issuer)} ${access.repository} at ${access.issuer}, not the repository named`,
+      )
+    return access
+  }
+}
+
+/** A repository as a request names it plainly: the issuer's URL and `org/name` there. */
+export interface Repo {
+  readonly issuer: string
+  readonly repository: string
+}
+
+/**
+ * A server whose requests name their repository plainly, in the body
+ * (@vzn/vx-history-server). A token must be of `named`, when one is named;
+ * with no token, `READ_ACCESS=public` reads a repository ALLOW names, and
+ * answers `undefined` where none is named. Else a 401 or 403.
+ */
+export function oidcTokenAuth(
+  opts: OidcOptions,
+): (req: Request, named?: Repo) => Promise<Access | undefined> {
+  const open = readAccessOf(opts)
+  const check = tokenVerifier(opts)
+  // A request is asked twice, before its body names the repository and
+  // after: its token is verified once.
+  const verified = new WeakMap<Request, Promise<Access>>()
+  const verify = (token: string, req: Request): Promise<Access> => {
+    let got = verified.get(req)
+    if (got === undefined) verified.set(req, (got = check(token, req)))
+    return got
+  }
+  return async (req, asked) => {
+    if (opts.allow.length === 0)
+      throw new Refusal(401, 'ALLOW is empty: set it to the CI workflows this server serves')
+    const named = asked === undefined ? undefined : repoOf(asked)
+    const bearer = bearerOf(req)
+    if (bearer === undefined) {
+      if (!open) throw new Refusal(401, 'no bearer token')
+      if (named === undefined) return undefined
+      if (
+        !opts.allow.some(
+          (a) => issuerOf(a.issuer) === named.issuer && same(a.repository, named.repository),
+        )
+      )
+        throw new Refusal(403, `${named.repository} is not in this server's ALLOW`)
+      return named
+    }
+    const access = await verify(bearer, req)
+    if (
+      named !== undefined &&
+      (access.issuer !== named.issuer || access.repository !== named.repository)
+    )
+      throw new Refusal(
+        403,
+        `the token is of ${access.repository} at ${access.issuer}, not ${named.repository} at ${named.issuer}`,
+      )
+    return access
+  }
+}
+
+/** A named repository as a token names it: the issuer's URL with no trailing slash, `org/name` lowercased. */
+const repoOf = (r: Repo): Repo => ({
+  issuer: issuerOf(r.issuer),
+  repository: r.repository.toLowerCase(),
+})
+
+function readAccessOf(opts: OidcOptions): boolean {
+  const given: unknown = opts.readAccess
+  // A Worker var may be JSON: a list was refused "not public".
+  if (given !== undefined && given !== '' && given !== 'public')
+    throw new Error(
+      `READ_ACCESS: public, or unset, not ${typeof given === 'string' ? given : JSON.stringify(given)}`,
+    )
+  return opts.readAccess === 'public'
+}
+
+const bearerOf = (req: Request): string | undefined =>
+  /^Bearer\s+(\S+)$/i.exec(req.headers.get('authorization') ?? '')?.[1]
+
+/** A token checked: jose's checks, then ALLOW's repository and workflow, and the branch it may write. */
+function tokenVerifier(opts: OidcOptions): (token: string, req: Request) => Promise<Access> {
+  // A blank one is no origin a token names: every token was "wrong audience".
+  if (opts.audience !== undefined && opts.audience.trim() === '')
+    throw new Error('AUDIENCE: the aud CI tokens name, or unset, not blank')
+  const fetchJson = opts.fetchJson ?? defaultFetchJson
+  const now = opts.now ?? (() => Date.now() / 1000)
+  // jose keeps each issuer's keys, and refetches them for a key it lacks.
+  const keys = new Map<string, Promise<ReturnType<typeof createRemoteJWKSet>>>()
+  const keysOf = (iss: string) => {
+    let set = keys.get(iss)
+    if (set === undefined) {
+      set = fetchJson(`${iss.replace(/\/$/, '')}/.well-known/openid-configuration`).then((c) => {
+        const uri = (c as { jwks_uri?: unknown }).jwks_uri
+        if (typeof uri !== 'string') throw new Error('no jwks_uri')
+        return createRemoteJWKSet(new URL(uri), {
+          [customFetch]: async (url: string) => Response.json(await fetchJson(url)),
+        })
+      })
+      keys.set(iss, set)
+      // A failed discovery is not kept: the next token tries again.
+      // quiet: the awaited set rethrows it; this only forgets it
+      set.catch(() => keys.get(iss) === set && keys.delete(iss))
+    }
+    // The issuer's outage, not the token's fault: a 401 tells a client its
+    // token is refused, and vx-cache turns the remote off for the run.
+    return set.catch((err: unknown) => {
+      throw keysUnread(iss, err)
+    })
+  }
+
+  return async (token, req) => {
+    let said: unknown
+    try {
+      said = decodeJwt(token).iss
+    } catch {
+      throw new Refusal(401, 'not a JWT')
+    }
+    // A trailing slash is no other issuer, as a key and a tokenless read
+    // name it: one in ALLOW or in the token refused every token.
+    const iss = typeof said === 'string' ? issuerOf(said) : undefined
+    if (iss === undefined || !opts.allow.some((a) => issuerOf(a.issuer) === iss)) {
+      throw new Refusal(
+        401,
+        typeof said === 'string'
+          ? `issuer ${said.slice(0, 200)} is not in this server's ALLOW: add issuer:owner/repo:workflow for it`
+          : 'the token names no issuer (iss)',
+      )
+    }
+    const audience = opts.audience ?? new URL(req.url).origin
+    let claims: JWTPayload
+    try {
+      claims = (
+        await jwtVerify(token, await keysOf(iss), {
+          algorithms: ['RS256'],
+          audience,
+          clockTolerance: LEEWAY_S,
+          currentDate: new Date(now() * 1000),
+          requiredClaims: ['exp'],
+        })
+      ).payload
+    } catch (err) {
+      throw refusal(err, iss, audience)
+    }
+    const claim = repoClaimOf(iss)
+    const named = claims[claim]
+    if (typeof named !== 'string') throw new Refusal(403, `no ${claim} claim`)
+    // GitHub and GitLab names ignore case; a checkout's origin may spell it either way.
+    const repository = named.toLowerCase()
+    const ofRepo = opts.allow.filter(
+      (a) => issuerOf(a.issuer) === iss && same(a.repository, repository),
+    )
+    if (ofRepo.length === 0)
+      throw new Refusal(403, `${claim} ${repository} is not in this server's ALLOW`)
+    const wclaim = workflowClaimOf(iss)
+    const ran = claims[wclaim]
+    if (typeof ran !== 'string') throw new Refusal(403, `no ${wclaim} claim`)
+    // Cut at the `@` before the ref: GitLab's CI file may itself hold one
+    // (`.gitlab-ci.yml@group/project`, a file kept in another project).
+    const workflow = ran.replace(/@(?:refs\/.*)?$/, '')
+    if (!ofRepo.some((a) => same(workflow, workflowPath(iss, a.repository, a.workflow))))
+      throw new Refusal(403, `${wclaim} ${workflow} is not in this server's ALLOW`)
+    const repo = { issuer: iss, repository }
+    const branch = branchOf(iss, claims)
+    return branch === undefined ? repo : { ...repo, write: branch }
+  }
+}
+
+/** An issuer as a key names it: its URL, no trailing slash. */
+const issuerOf = (iss: string): string => iss.replace(/\/$/, '')
+
+/** What jose's refusal of a token says. */
+function refusal(err: unknown, iss: string, audience: string): Refusal {
+  if (err instanceof Refusal) return err
+  // A refetch of the keys for a kid not held failed, or the issuer served
+  // no key set, or one with two keys for a kid: the issuer, not the token.
+  // A broken set read "not a JWT".
+  if (
+    !(err instanceof errors.JOSEError) ||
+    err instanceof errors.JWKSTimeout ||
+    err instanceof errors.JWKSInvalid ||
+    err instanceof errors.JWKSMultipleMatchingKeys
+  )
+    return keysUnread(iss, err)
+  if (err instanceof errors.JOSEAlgNotAllowed) return new Refusal(401, 'alg is not RS256')
+  if (err instanceof errors.JWKSNoMatchingKey) return new Refusal(401, 'unknown signing key')
+  if (err instanceof errors.JWSSignatureVerificationFailed) return new Refusal(401, 'bad signature')
+  if (err instanceof errors.JWTExpired) return new Refusal(401, 'expired')
+  if (err instanceof errors.JWTClaimValidationFailed) {
+    if (err.claim === 'aud')
+      return new Refusal(
+        401,
+        `the token's aud is ${audOf(err.payload)}, not this server's ${audience}: ask CI for a token for ${audience}, or set the server's AUDIENCE`,
+      )
+    if (err.claim === 'nbf') return new Refusal(401, 'not yet valid')
+    if (err.reason === 'missing') return new Refusal(401, `no ${err.claim} claim`)
+  }
+  return new Refusal(401, 'not a JWT')
+}
+
+/** A token's `aud`, as a refusal names it: "wrong audience" alone left the fix to a guess. */
+const audOf = (claims: JWTPayload): string => [claims.aud ?? 'unset'].flat().join(', ')
+/** The issuer's keys out of reach, with why: a 503 and a missing jwks_uri read the same. */
+const keysUnread = (iss: string, err: unknown): Refusal =>
+  new Refusal(
+    502,
+    `could not read ${iss}'s keys: ${err instanceof Error ? err.message : String(err)}`,
+  )
+
+async function defaultFetchJson(url: string): Promise<unknown> {
+  const res = await fetch(url, { signal: AbortSignal.timeout(10_000) })
+  if (!res.ok) throw new Error(`${url}: ${res.status}`)
+  return res.json()
+}

package/src/refusal.ts

@@ -0,0 +1,36 @@
+// How vx's servers refuse a request: one body, `{ code, message }`, the
+// shape of Turbo's spec's `Error`, so a client reads every server's
+// refusal the same way and warns with its message.
+
+/** A request refused: its HTTP status and what to fix. */
+export class Refusal extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+const CODES: Record<number, string> = {
+  400: 'bad_request',
+  401: 'unauthorized',
+  403: 'forbidden',
+  404: 'not_found',
+  405: 'method_not_allowed',
+  413: 'payload_too_large',
+  500: 'internal_error',
+  502: 'bad_gateway',
+}
+
+/** A refusal's answer: `{ code, message }`, the message saying what to fix. */
+export function errorJson(status: number, message: string): Response {
+  return Response.json({ code: CODES[status] ?? 'error', message }, { status })
+}
+
+/** A route's wrong method: `405`, naming the ones it takes in `Allow` and the message. */
+export function notAllowed(allow: string): Response {
+  const res = errorJson(405, `this route takes ${allow}`)
+  res.headers.set('allow', allow)
+  return res
+}

package/src/terminal.ts

@@ -0,0 +1,32 @@
+// The one line a server prints at start or when it refuses to start,
+// painted as vx's own status lines are: a server's log is read beside
+// vx's, and plain white read as noise there.
+
+const HUE = { ok: '34;197;94', err: '239;68;68' } as const
+const SYMBOL = { ok: '✓', err: '✗' } as const
+
+/** Colour as vx decides it: NO_COLOR, then FORCE_COLOR, then a terminal. */
+function paints(stream: { isTTY?: boolean }): boolean {
+  const env = process.env
+  if (env['NO_COLOR']) return false
+  const force = env['FORCE_COLOR']
+  if (force !== undefined) return force !== '0' && force !== 'false'
+  return stream.isTTY === true && env['TERM'] !== 'dumb'
+}
+
+/**
+ * `✓ vx-cache-server  listening on http://…` or `✗ vx-cache-server  <why>`.
+ * Lines after the first (a usage text) print dim under it.
+ */
+export function statusLine(
+  tone: 'ok' | 'err',
+  name: string,
+  text: string,
+  stream: { isTTY?: boolean } = tone === 'ok' ? process.stdout : process.stderr,
+): string {
+  const [head = '', ...rest] = text.split('\n')
+  if (!paints(stream)) return `${[`${SYMBOL[tone]} ${name}  ${head}`, ...rest].join('\n')}\n`
+  const url = head.replace(/(https?:\/\/\S+)/g, '\x1b[38;2;6;182;212m$1\x1b[0m')
+  const first = `\x1b[38;2;${HUE[tone]}m${SYMBOL[tone]}\x1b[0m \x1b[1m${name}\x1b[0m  ${url}`
+  return `${[first, ...rest.map((l) => (l === '' ? l : `\x1b[2m${l}\x1b[0m`))].join('\n')}\n`
+}