@vzn/vx-dte-server 0.0.0 → 0.0.650

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/PROTOCOL.md

@@ -0,0 +1,212 @@
+# Switchboard protocol, v1
+
+Switchboard connects one **host** to any number of **peers** through a
+relay, when none of them takes an inbound connection (CI runners, laptops
+behind NAT). Each participant dials out: one websocket, which joins as it
+opens and carries the rest. The shape is a star: the host talks to every
+peer, a peer talks only to the host, and the relay passes each message on
+without reading it. What host and peers say to each other is their own
+protocol, versioned on its own.
+
+`@vzn/vx-dte-server` is one relay that speaks it (on Bun and on Cloudflare
+Workers); any server that does can stand in for it.
+
+## Versions
+
+A client names the versions it speaks in the websocket's subprotocol
+header, on the request that joins, so negotiation costs no round trip:
+
+```
+Sec-WebSocket-Protocol: switchboard.v2, switchboard.v1
+```
+
+The relay answers with the highest version both speak. If none is, it
+answers with the first one offered (a client offered nothing it can read
+otherwise) and closes the socket `4406`, reason `supported:
+switchboard.v<lowest>-v<highest>`. A request offering none is refused the
+same way. This document is `switchboard.v1`.
+
+The path names the API version apart from the protocol's: every route is
+under `/v1/`. A change to the routes ships under `/v2/`, beside `/v1/` for
+as long as the relay keeps it, while the messages keep their subprotocol.
+
+## Sessions
+
+One request is HTTP, a websocket upgrade of `GET
+<relay>/v1/sessions/<session>/socket`. `<session>` is the session id, a random
+(v4) UUID, so no one can guess it; another answers `400`, another path
+`404`, another method `405` (`Allow: GET`), a request that is no upgrade `426`. It carries
+`Authorization: Bearer <token>` (§ Tokens).
+
+| Query       | Does                                                                         |
+| ----------- | ---------------------------------------------------------------------------- |
+| `?join=<j>` | joins: `<j>` is `{ "role": "host" \| "peer", "info"?: any, "key"?: string }` |
+| `?id=<id>`  | a participant's socket dialed again (§ Sockets)                              |
+
+- A join's socket says first `{ "joined": { "id", "heartbeatMs" } }`. The
+  `id` is a secret the relay picked: whoever holds it, with a token of this
+  session, acts as that participant.
+- The host's join opens the session; a session has one host, and a second
+  host's join is refused `409`. A peer's join of a session with no host is
+  refused `410`.
+- A session lives while its host does. The host's `leave` is its final
+  call: it closes the session at once, and the relay keeps nothing of it.
+  A host whose socket dropped without it has the grace (§ Liveness) to
+  dial again; the session waits for it. When the grace passes, the relay
+  forgets the session and closes each peer's socket with no code: the
+  host may still join it again, and a peer's redial, closed `4404`, joins
+  again too.
+
+## The host's key
+
+The host's join names `key`, a P-256 public key (raw, base64url), which
+the relay keeps for the session; one without it is refused `400`. Each of
+the host's socket requests, its join too, carries `relay-proof: <ms>.<nonce>.<signature>`, an
+ECDSA SHA-256 signature by that key of
+
+```
+switchboard-proof\0GET\0<path and query>\0<ms>\0<nonce>\0
+```
+
+`<ms>` is when it was made, within two minutes of the relay's clock, and
+`<nonce>` 16 to 64 base64url characters the relay takes once; else `403`.
+So only the side holding the private key acts as the host, and a leaked
+host `id` acts as it nowhere. A frame carries no proof: its socket's
+upgrade did.
+
+## Frames
+
+Frames are JSON text, each at most 1 MiB of UTF-8 (bytes, not characters).
+
+The relay pushes:
+
+- `{ "messages": [{ "from", "body" }] }` as messages arrive. `from` is
+  `"host"`, a peer's `id`, or `"relay"` (§ Notices);
+- `{ "close": <code>, "error"? }` just before it closes the socket, `0`
+  for no code. A client acts on this frame: a host may never end TCP after
+  its close.
+
+A participant sends:
+
+| Frame                                  | Does                                                       |
+| -------------------------------------- | ---------------------------------------------------------- |
+| `{ "n", "sends": [{ "to", "body" }] }` | passes each `body` to `to`                                 |
+| `{ "n", "leave": true }`               | removes the participant; its answer is the socket's close  |
+| `{ "n", "remove": "<peer id>" }`       | the host only (`403` else): takes the peer off the session |
+
+- The host sends to any peer `id`; a peer sends only to `"host"`. An
+  unknown or gone `to` is `404`.
+- A frame with a number `n` is answered `{ "n" }` when all went, else
+  `{ "n", "results" }` with `null` or `{ "status", "error" }` for each
+  send. A frame of sends with no `n` is answered only if a send in it
+  fails, `n` then `null`.
+- A frame that fails is answered `{ "n", "status", "error" }`; one that is
+  no JSON object, or none of the above, `400`; one over 1 MiB `413`,
+  answered by its `n` when the frame starts `{"n":`.
+- A removed peer's socket is closed `4404` after what waited for it; the
+  host is not told it left.
+
+## Delivery
+
+The relay holds no participant's message. One it cannot push now (no
+socket, or a push that failed) is dropped. Delivery is the clients': a
+sender numbers each send, the receiver acknowledges it end to end, and
+the sender sends again what is not acknowledged, at once on a new socket.
+How they number and acknowledge is inside `body`, their own protocol;
+`@vzn/vx-dte` puts `{ "n" }` and `{ "acked" }` beside its payload.
+
+Only the relay's notices wait, in memory, for the participant's next
+socket.
+
+## Notices
+
+The relay itself sends, `"from": "relay"`:
+
+- to the host, `{ "type": "joined", "id", "info" }` for each peer, its
+  `info` as its join said, then forgotten;
+- to the host, `{ "type": "left", "id" }` when a peer leaves, or its
+  grace passes with no socket;
+- to every peer, `{ "type": "closed" }` when the host leaves: the
+  session is over. A peer on a socket is told and let go; one with no
+  socket gets `4404` when it opens one.
+
+## Sockets
+
+The socket a frame comes down is its participant's from then on. A
+client that gave up on a socket whose close never reached the relay dials
+again by its `id`: the relay closes the earlier one and pushes what
+waited. The relay closes `4404` the socket of a participant that left, was
+removed or lost, or that it never knew (a failed upgrade tells a client
+nothing it can read, so the request is let in and closed). It closes a
+socket a push failed on with no code.
+
+## Liveness
+
+Only `leave` ends a participant at once. One whose socket closed
+without it, the host too, may dial again by its `id` for a grace, 10 s
+on `@vzn/vx-dte-server`, and is gone when the grace passes with no socket:
+a peer as if it left, the host closing its session. The relay keeps no
+timer and counts no heartbeat: it finds a grace passed as the session is
+next used. A join whose socket never opened (its client dropped during
+the upgrade) has the same grace from the join. A client whose socket drops dials again, and says its `leave`
+again on a new socket if the first dropped under it.
+`heartbeatMs` is how often participants should hear from each other: a
+peer quiet on a socket that never closed is its peers' to lose. The
+clients probe a quiet peer with an empty numbered send, which it
+acknowledges at once, and lose one quiet for two `heartbeatMs`. A
+numbered frame the relay leaves unanswered a heartbeat is a dead socket.
+
+## Close codes
+
+A refused request is let in and its socket closed with `4000 + status`,
+said first in a `{ "close", "error" }` frame:
+
+| Code   | Why                                                                        |
+| ------ | -------------------------------------------------------------------------- |
+| `4400` | a malformed request or join                                                |
+| `4401` | no token, or an invalid one                                                |
+| `4403` | a token the relay does not accept, or a host request not signed by its key |
+| `4404` | an unknown, left or removed participant (and every socket it let go)       |
+| `4406` | no version both speak; the reason names the relay's range                  |
+| `4409` | a second host                                                              |
+| `4410` | a closed session                                                           |
+| `4413` | a join over 1 MiB                                                          |
+| `4502` | the relay could not read the token issuer's keys; retry                    |
+| `4503` | the relay's host refused the session (a plan's limit)                      |
+
+A request that is no upgrade is answered its status and `{ "error" }`.
+
+## Tokens
+
+The relay checks the bearer token. `@vzn/vx-dte-server` takes CI OIDC
+tokens: their signature by the issuer's published keys
+(`<iss>/.well-known/openid-configuration`, then `jwks_uri`; RS256), `exp`
+and `nbf`, an issuer it trusts, an `aud` naming its audience, and a
+repository and workflow it allows (`403` else). Keys it cannot read
+are the issuer's outage, not the token's fault: `502`, which a client
+retries. Keys are read again once ten minutes old, so a key the issuer
+withdraws stops admitting tokens, and for a key the relay does not hold
+at most once a minute. A session is its id
+within its token's issuer and repository claims (`repository_id` on
+GitHub Actions, `project_id` on GitLab), so a tenant that learns another's
+session id cannot open or join it.
+
+## What the relay knows
+
+A relay stores nothing. It writes no message, participant or session to
+any file, database, key-value store or alarm: what it knows lives in
+memory and in its open sockets, and a restart forgets it. Its host and
+peers carry a session across one by joining it again. The one thing a
+relay may cache is an issuer's published public keys (§ Tokens).
+
+It holds only what routing needs, and no longer:
+
+- A session is a SHA-256 of its id and its tokens' issuer and claims: no
+  name says whose it is. A token is checked, never kept.
+- A peer's `info` is held until the host is told it joined.
+- A message is pushed or dropped, never held; a notice waits in memory.
+- A closed session is gone at once; while open, each participant's role
+  is kept, and when a socket dropped. A relay restart keeps a session whose
+  host's socket, or a peer's naming that host, it kept; one whose host's
+  socket it did not keep waits the grace from the restart.
+- It logs nothing. It still sees each message's size, time and recipient.

package/README.md

@@ -1,3 +1,166 @@
 # @vzn/vx-dte-server
 
-Placeholder. Part of [vx](https://github.com/vznjs/vx).
+Website: <https://vznjs.github.io/vx/> · source: <https://github.com/vznjs/vx>
+
+The reference relay for `@vzn/vx-dte`, which spreads one `vx run` over CI
+workers. CI runners take no inbound connection, so the run's orchestrator
+and its workers all dial out to a relay, which passes their messages on.
+It admits only CI OIDC tokens of the repositories it names, and binds
+each run to the repository that started it.
+
+The relay is one package whose one runtime dependency is `jose`, which checks
+the CI tokens; not even vx itself. It speaks the
+[Switchboard protocol](./PROTOCOL.md) (`switchboard.v1`): one host, the
+run's orchestrator, and its peers, the workers, behind one relay. Any
+server that speaks it can take its place, and any tool can use it.
+
+## Run it
+
+### On Cloudflare Workers
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/vznjs/vx/tree/main/packages/vx-dte-server)
+
+The button copies this directory into a new repository of yours and
+deploys it. It asks for one var, `ALLOW`: who may take part, space
+separated, each `issuer:owner/repo:workflow`. It is not a secret: keep it
+in your copy's `wrangler.jsonc`, since each deploy sets vars from that file.
+`https://token.actions.githubusercontent.com:vznjs/vx:ci.yml` admits the
+jobs of `.github/workflows/ci.yml` in `vznjs/vx`;
+`https://gitlab.com:group/project:.gitlab-ci.yml` a GitLab project's.
+Repeat an entry for each repository and workflow, the orchestrator's and
+the workers'. Every other token is refused. The relay's URL is the Cloudflare Worker's URL, such
+as `https://vx-dte-server.<you>.workers.dev`. Name it as `relay` in
+`dte()`.
+
+Or deploy from this directory with Cloudflare's
+[`wrangler`](https://developers.cloudflare.com/workers/wrangler/):
+
+```sh
+bun install
+bunx wrangler login
+bunx wrangler deploy
+```
+
+Set `ALLOW` in `wrangler.jsonc`'s `vars` first.
+
+`src/worker.ts` is the same relay as the one on Bun. Each run is one
+Durable Object, so its sockets meet in one place. Participants hold
+websockets, which the object hibernates between messages: the run is kept
+in their attachments, and the object writes no storage. It sets no alarm and counts no heartbeat: a
+socket's close loses its participant, and a peer quiet on a socket that
+never closed is its peers' to lose. Issuers' keys
+are read once per isolate and held ten minutes in the data center's
+cache, so a run's object does not fetch them again; a token naming a key
+they lack is checked against a fresh read.
+It fits Workers' free plan: each participant joins on the socket it
+opens, one request, and its websocket messages count 20 to one Durable
+Object request, against 100 000 a day; it writes no row.
+`wrangler.jsonc` sets the rest; change a value there, in the repository
+the button made, or in the Worker's settings in the Cloudflare dashboard:
+
+- `AUDIENCE`, unset, is the URL the relay is reached at. Set it only
+  when tokens name another one. Blanks around it are dropped, and a
+  blank one is refused, as on Bun.
+
+### On Bun
+
+```sh
+ALLOW=https://gitlab.com:group/app:.gitlab-ci.yml AUDIENCE=https://relay.example.com \
+bunx @vzn/vx-dte-server --port 8080
+```
+
+Or as a container:
+
+```sh
+docker run -p 8080:8080 -e ALLOW=https://gitlab.com:group/app:.gitlab-ci.yml \
+  -e AUDIENCE=https://relay.example.com ghcr.io/vznjs/vx-dte-server
+```
+
+All vx servers at once, this relay with its state on a volume included:
+[`private/vx-servers/compose.yaml`](../../private/vx-servers/compose.yaml)
+(`docker compose up`).
+
+- `ALLOW` is the same list as on Workers (above), read from the
+  environment as every vx server reads it. GitLab names a project by
+  its full path, `group/subgroup/project`.
+- `AUDIENCE` is the `aud` every token must name: the URL the CI job
+  asks its ID token for.
+- `--port` (default 8080) and `--host` (default `0.0.0.0`) set where it
+  listens.
+- `--no-auth` admits every request. Use it only to try `@vzn/vx-dte`
+  locally: it listens on loopback only.
+
+CI builds this image and carries one run through it (`test.live`).
+
+Runs live in memory. A restarted relay forgets the runs it was carrying,
+and vx-dte joins each again.
+Participants hold websockets here too, so a message reaches its receiver
+the moment it is sent.
+
+Each participant is one socket and one file descriptor. Bun raises the
+open-file limit to the container's hard limit (Docker's is 524288 or
+more), so it never needs a `--ulimit`. Measured on 4 cores (2026-10-24):
+10,000 sockets over 100 runs take 41 MB over an idle relay (about 4 KB
+each) and 6% of a core idle; with each worker sending one message a
+second (10,000 a second) 43% of a core, every message delivered.
+
+## Environment
+
+- `RELAY`: on Workers, the `RelayRun` Durable Object binding
+  (`wrangler.jsonc`); the relay refuses every request without it.
+- `NO_COLOR`, then `FORCE_COLOR`, then a terminal whose `TERM` is not
+  dumb: whether the Bun relay's status lines print in colour.
+
+## API
+
+The same relay as a `fetch` handler, to mount in a server of your own
+(`src/index.ts`):
+
+- `createRelay(options?: RelayOptions): Relay`. `RelayOptions` is
+  `{ verify?, heartbeatMs?, graceMs? }`: `verify` checks a request's bearer token
+  (none admits every request) and gets the request too, `heartbeatMs` (default 2000) is how often
+  participants hear from each other, said in each join's answer, and
+  `graceMs` (default 10 000) how long a participant whose socket dropped
+  without `leave` may dial again before it is gone (PROTOCOL.md § Liveness). A `Relay` is `{ fetch(req) }`,
+  plus the hooks a host of websockets drives (`src/worker.ts` is their
+  user): the options `sockets`, the `[Kept, RelaySocket]` pairs a host
+  kept across a restart, from which the sessions are rebuilt (PROTOCOL.md
+  § What the relay knows), and `upgrade`, which answers a `socket`
+  request; and the methods `attach` and `detach` (its socket closed: the
+  participant is gone unless it dials again within `graceMs`), which hand the relay a participant's
+  `RelaySocket` (`{ send, close }`), and `frame`, which returns the
+  answer to send down the socket, or `undefined` for none. `attach`
+  returns the `Kept` its host keeps with the socket (a Durable Object's
+  attachment: session, id, role, the host's key, and a peer's host's id), or
+  `false`. A host closes a socket `attach` refuses
+  with `closeSocket(socket, GONE)` (`GONE` is 4404), which says the close in a frame first
+  (PROTOCOL.md § Sockets).
+- `serveRelay(options: ServeOptions): RelayServer` serves the relay on
+  `Bun.serve`, websockets included. `ServeOptions` is
+  `{ hostname, port, verify?, heartbeatMs? }`, and a `RelayServer` is
+  `{ url, stop() }`.
+- `createProver(): Promise<Prover>` makes the host's key for one
+  session (PROTOCOL.md § The host's key). A `Prover` is
+  `{ key, proof(method, path, body) }`: `key` is what its `join` names,
+  and `proof` is the value of the `PROOF_HEADER` (`relay-proof`) header of
+  each request as the host.
+- `createVerifier(options: OidcOptions)` returns that `verify`.
+  `OidcOptions` is
+  `{ allow, audience, runClaims?, fetchJson?, now? }`: who may take part,
+  `Allowed`s `{ issuer, repository?, workflow? }` (an unset part admits
+  any; a token's `repositoryClaimOf(iss)` and `workflowClaimOf(iss)` up to
+  its `@` are matched without case), the `aud` a token must name, run claims per issuer (default
+  `runClaimsOf(iss)`), and a key reader and clock for tests. It
+  resolves a `VerifiedToken`, `{ iss, run }`, or rejects with a
+  `TokenError` carrying the `status` (401 or 403) the relay answers.
+- `parseAllow(list)` reads `ALLOW`'s entries into `Allowed`s, each
+  `issuer:owner/repo:workflow` read from the right (an issuer holds `:`s),
+  or throws naming the entry it cannot read. An issuer is `https://`, or
+  plain `http://` only to `127.0.0.1`, as the cache and history servers read it.
+- `runClaimsOf(iss)` names the claims that bind a run: `repository_id`
+  for GitHub Actions, `project_id` otherwise.
+- `repositoryClaimOf(iss)` names the claim that names a token's
+  repository: `repository` for GitHub Actions, `project_path` otherwise.
+- `workflowClaimOf(iss)` names the claim that names the workflow a
+  token's job is defined in: `job_workflow_ref` for GitHub Actions,
+  `ci_config_ref_uri` otherwise.

package/index.ts

@@ -0,0 +1,4 @@
+// Root entry shim: Bun 1.4.0'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,8 +1,63 @@
 {
   "name": "@vzn/vx-dte-server",
-  "version": "0.0.0",
-  "description": "Placeholder; real releases are published by CI.",
+  "version": "0.0.650",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/vznjs/vx.git" },
-  "publishConfig": { "access": "public" }
+  "description": "The reference relay for @vzn/vx-dte: carries messages between a vx run's orchestrator and its CI agents, admitting only CI OIDC tokens of the same repository.",
+  "keywords": [
+    "vx",
+    "monorepo",
+    "distributed",
+    "ci",
+    "relay"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "vx-dte-server": "./src/bun.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./worker": {
+      "types": "./src/worker.ts",
+      "import": "./src/worker.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "PROTOCOL.md",
+    "wrangler.jsonc",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.4.4"
+  },
+  "//": [
+    "wrangler: deploys src/worker.ts by wrangler.jsonc, which the Deploy to Cloudflare button reads (it parses no other config).",
+    "@vzn/vx: vx.config.ts's core, the workspace's own here; `*`, not workspace:, which npm refuses when the button installs this directory alone.",
+    "miniflare: tests/worker-sockets.test.ts runs src/worker.ts in workerd, the runtime Workers deploy to.",
+    "jose: checks the CI OIDC tokens (signature, algorithm, audience, times) with a widely used, dependency-free JWT library instead of hand-rolled WebCrypto; it runs in Bun and workerd alike."
+  ],
+  "cloudflare": {
+    "bindings": {
+      "ALLOW": {
+        "description": "Who may take part, space separated, each `issuer:owner/repo:workflow`: `https://token.actions.githubusercontent.com:vznjs/vx:ci.yml` admits jobs of `.github/workflows/ci.yml` in vznjs/vx (GitLab: `https://gitlab.com:group/project:.gitlab-ci.yml`). List the orchestrator's workflow and the agents'."
+      }
+    }
+  },
+  "dependencies": {
+    "jose": "6.2.13"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vznjs/vx.git",
+    "directory": "packages/vx-dte-server"
+  },
+  "homepage": "https://github.com/vznjs/vx/tree/main/packages/vx-dte-server#readme",
+  "bugs": "https://github.com/vznjs/vx/issues"
 }

package/src/bun.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env -S bun --no-env-file --no-install
+// `bunx @vzn/vx-dte-server`: the relay on Bun, runs in memory (PROTOCOL.md).
+
+import { parseArgs } from 'node:util'
+import { createVerifier, parseAllow } from './oidc.js'
+import { serveRelay } from './serve.js'
+
+const USAGE = `usage: vx-dte-server [--port 8080] [--host 0.0.0.0]
+       vx-dte-server --no-auth [--port 8080]   (loopback only)
+  ALLOW      who may take part, space separated, each issuer:owner/repo:workflow
+  AUDIENCE   the aud every CI token names: the URL CI reaches the relay at`
+
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost'])
+
+function main(argv: string[]): void {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      port: { type: 'string', default: '8080' },
+      host: { type: 'string' },
+      'no-auth': { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  })
+  if (values.help) {
+    console.log(USAGE)
+    return
+  }
+  const noAuth = values['no-auth']
+  const host = values.host ?? (noAuth ? '127.0.0.1' : '0.0.0.0')
+  // Bun.serve reads '' as localhost: unreachable from another host or container.
+  if (host.trim() === '') fail(`--host: needs an address, got '${host}'`)
+  if (noAuth && !LOOPBACK.has(host)) fail('--no-auth listens on loopback only')
+  // Read from the environment, as the cache and history servers and the
+  // relay's Worker read them: one way to configure every vx server.
+  const env = Bun.env
+  const audience = env.AUDIENCE?.trim() ?? ''
+  // The bare usage said nothing of which was missing.
+  if (!noAuth) {
+    const missing = [
+      // An empty one is missing too: it started a relay that refused every token.
+      ...((env.ALLOW ?? '').trim() === '' ? ['ALLOW'] : []),
+      ...(audience === '' ? ['AUDIENCE'] : []),
+    ]
+    if (missing.length > 0) fail(`missing ${missing.join(' and ')} (or --no-auth)\n${USAGE}`)
+  }
+  let allow: ReturnType<typeof parseAllow> = []
+  try {
+    allow = parseAllow(env.ALLOW ?? '')
+  } catch (err) {
+    fail(`ALLOW: ${(err as Error).message}`)
+  }
+  // Digits only, as the cache and history servers read it: Number('') is
+  // 0, a random port for `--port "$PORT"` with PORT unset, and Number read
+  // 0x50 as 80 and 1e1 as 10.
+  const port = /^\d+$/.test(values.port) ? Number(values.port) : Number.NaN
+  if (!Number.isInteger(port) || port < 0 || port > 65_535)
+    fail(`--port: not a port: ${values.port}`)
+  const server = serveRelay({
+    hostname: host,
+    port,
+    verify: noAuth ? undefined : createVerifier({ allow, audience }),
+  })
+  process.stdout.write(statusLine('ok', `listening on ${server.url}`))
+  const stop = (): void => {
+    void server.stop().then(() => process.exit(0))
+  }
+  process.on('SIGINT', stop)
+  process.on('SIGTERM', stop)
+}
+
+function fail(message: string): never {
+  process.stderr.write(statusLine('err', message))
+  process.exit(2)
+}
+
+try {
+  main(process.argv.slice(2))
+} catch (err) {
+  // parseArgs names the flag it refused, not the ones there are.
+  const usage = (err as { code?: string }).code?.startsWith('ERR_PARSE_ARGS') ? `\n${USAGE}` : ''
+  fail(`${err instanceof Error ? err.message : String(err)}${usage}`)
+}
+
+/**
+ * `✓ vx-dte-server  listening on …` / `✗ vx-dte-server  <why>`, painted as
+ * vx's status lines are (NO_COLOR, then FORCE_COLOR, then a terminal). The
+ * relay imports only jose, so this is @vzn/vx-devtools' `statusLine` kept
+ * here; usage lines under a refusal print dim.
+ */
+function statusLine(tone: 'ok' | 'err', text: string): string {
+  const stream = tone === 'ok' ? process.stdout : process.stderr
+  const env = process.env
+  const force = env['FORCE_COLOR']
+  const on = env['NO_COLOR']
+    ? false
+    : force !== undefined
+      ? force !== '0' && force !== 'false'
+      : stream.isTTY === true && env['TERM'] !== 'dumb'
+  const [head = '', ...rest] = text.split('\n')
+  const symbol = tone === 'ok' ? '✓' : '✗'
+  if (!on) return `${[`${symbol} vx-dte-server  ${head}`, ...rest].join('\n')}\n`
+  const hue = tone === 'ok' ? '34;197;94' : '239;68;68'
+  const url = head.replace(/(https?:\/\/\S+)/g, '\x1b[38;2;6;182;212m$1\x1b[0m')
+  const first = `\x1b[38;2;${hue}m${symbol}\x1b[0m \x1b[1mvx-dte-server\x1b[0m  ${url}`
+  return `${[first, ...rest.map((l) => (l === '' ? l : `\x1b[2m${l}\x1b[0m`))].join('\n')}\n`
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+export {
+  closeSocket,
+  createRelay,
+  GONE,
+  type Kept,
+  type Relay,
+  type RelayOptions,
+} from './relay.js'
+export { serveRelay, type RelayServer, type ServeOptions } from './serve.js'
+export {
+  createVerifier,
+  parseAllow,
+  repositoryClaimOf,
+  runClaimsOf,
+  workflowClaimOf,
+  TokenError,
+  type Allowed,
+  type OidcOptions,
+  type VerifiedToken,
+} from './oidc.js'
+export { createProver, PROOF_HEADER, type Prover } from './proof.js'