@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/contract-server.mjs

@@ -0,0 +1,776 @@
+#!/usr/bin/env node
+/**
+ * @file contract-server.mjs  -  the pipeline's client contract over HTTP, on
+ * this machine only, for as long as someone is using it.
+ *
+ * The contract has two carriers. The first is the CLI: runs-index.mjs,
+ * commands.mjs, issues.mjs, worktrees.mjs, launch-request.mjs and
+ * answer-question.mjs print JSON a client decodes. This is the second, for a
+ * client that would rather hold a socket than spawn a process per read. It
+ * adds no behaviour: every route calls the function the matching CLI calls
+ * and serializes it the same way, so for the same input the body is the same
+ * bytes the CLI prints (test/contract-parity.test.mjs holds that).
+ *
+ * Routes (pipeline/contract/manifest.json lists them with their schemas):
+ *
+ *   GET  /v1/runs            runs-index.mjs --json [--group G] [--redact]
+ *   GET  /v1/runs/{id}       runs-index.mjs --json --task-id {id} [--redact]
+ *   GET  /v1/commands        commands.mjs --json
+ *   GET  /v1/questions       launch-request.mjs questions
+ *   GET  /v1/issues          issues.mjs --json [--source S] [--project K]... [--max N]
+ *   GET  /v1/worktrees       worktrees.mjs --json [--measure] [--redact]
+ *   GET  /v1/launch-spec     launch-request.mjs spec
+ *   POST /v1/launch?repo=P   write a launch request, return launch-request.mjs plan
+ *   POST /v1/runs/{id}/answer  answer-question.mjs --question Q --answer IDS
+ *
+ * Phone routes, the same handlers behind a device signature instead of the
+ * bearer token, always redacted (features/phone-api.md):
+ *
+ *   GET  /v1/phone/runs              scope read
+ *   GET  /v1/phone/runs/{id}         scope read
+ *   POST /v1/phone/runs/{id}/answer  scope answer
+ *   POST /v1/phone/launch?repo=P     scope launch, and only after `phone-devices.mjs launch on`
+ *
+ * There is deliberately no route that merges, marks ready, runs a command or
+ * starts a host. POST /v1/launch writes the request file and returns the argv
+ * and environment launch.json declares; the client starts the process, and
+ * nothing here ever spawns `claude`.
+ *
+ * Security model. The listener binds 127.0.0.1 and nothing else: any other
+ * --host, 0.0.0.0 and :: included, is refused at startup. Each start mints a
+ * random token (32 bytes from crypto.randomBytes) and writes it to a 0600 file
+ * under ~/.claude/logs/multi-agent/contract-server/ (0700); --print-token also
+ * puts it on the ready line for a parent that spawned the server itself. Every
+ * request is checked in this order:
+ *
+ *   1. Host must be 127.0.0.1:<port> or localhost:<port>, which is what stops
+ *      a DNS-rebound page from reaching the socket under another name (403);
+ *   2. an Origin header must be one of --allow-origin; without the flag no
+ *      Origin is accepted and no CORS header is ever sent (403);
+ *   3. an allowed preflight is answered, before authentication, since a
+ *      browser sends no credentials on one (204);
+ *   4. a path under /v1/phone/ leaves here for the device-signature checks in
+ *      _phone-auth.mjs (401 per refusal, then 404 unknown-verb, 403
+ *      forbidden-scope); the bearer token is not consulted there, and a
+ *      signature is not consulted anywhere else;
+ *   5. `Authorization: Bearer <token>`, compared in constant time over SHA-256
+ *      digests so neither content nor length leaks through timing (401);
+ *   6. the route, its method and its query parameters, each validated (404,
+ *      405, 400); a POST body must be application/json (415), at most 64 KiB,
+ *      and valid against the route's schema (400).
+ *
+ * `?redact=1` is `--redact`. A request that carries an Origin is a browser
+ * page, which can relay what it reads anywhere, so it is always served
+ * redacted whatever the query says.
+ *
+ * Lifetime. The server exits after --idle-minutes without a request (15 by
+ * default) and on SIGTERM, SIGINT or SIGHUP, removing its token file either
+ * way. It is started on demand by `/multi-agent:serve` or by a client, and is
+ * never installed as a service.
+ *
+ * Zero runtime dependencies (ADR-0004): node:http, node:crypto and the
+ * producers' own modules.
+ *
+ * Usage:
+ *   node contract-server.mjs [--port N] [--idle-minutes N] [--allow-origin <origin>]... [--print-token]
+ *
+ * Stdout: one JSON line once listening - {contractVersion, url, port, pid,
+ * tokenFile, idleMinutes[, token]}.
+ * Exit: 0 stopped (idle or signal), 1 could not listen, 2 usage error.
+ *
+ * @module pipeline/scripts/contract-server
+ */
+
+import { Buffer } from "node:buffer";
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { clearTimeout, setTimeout } from "node:timers";
+import { answerStateFile } from "./answer-question.mjs";
+import { catalog } from "./commands.mjs";
+import { collect } from "./issues.mjs";
+import {
+  launchRepoAllowed,
+  launchSpec,
+  planLaunch,
+  questionsDocument,
+  requestsDir,
+  workingTreeState,
+  writeRequestFile,
+} from "./launch-request.mjs";
+import { GROUP_NAMES, envelope, selectRuns } from "./runs-index.mjs";
+import {
+  PHONE_PREFIX,
+  appendAudit,
+  createNonceStore,
+  noncesPath,
+  readRegistry,
+  verbOf,
+  verifyRequest,
+} from "./_phone-auth.mjs";
+import { buildList } from "./worktrees.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+/** The contract as a whole; pipeline/contract/manifest.json carries the same. */
+export const CONTRACT_VERSION = "1.2.0";
+/** The majors `?v=` accepts. A new major keeps the previous one here for one minor. */
+export const SUPPORTED_MAJORS = [1];
+export const BIND_HOST = "127.0.0.1";
+export const MAX_BODY_BYTES = 64 * 1024;
+/** How much of an oversized body is drained before the socket is dropped. */
+const MAX_DRAIN_BYTES = 1024 * 1024;
+const DEFAULT_IDLE_MINUTES = 15;
+const MAX_IDLE_MINUTES = 24 * 60;
+const RUN_ID = /^[A-Za-z0-9#][A-Za-z0-9#._-]{0,127}$/;
+const PROJECT_KEY = /^[A-Z][A-Z0-9_]*$/;
+const QUESTION_ID = /^[a-z][a-z0-9-]*$/;
+const OPTION_ID = /^[a-z0-9][a-z0-9+_-]*$/;
+
+/** Where token files live. Fixed under HOME, never under LOGS_ROOT. */
+export function tokenDir() {
+  return join(homedir(), ".claude", "logs", "multi-agent", "contract-server");
+}
+
+/** The exact bytes a CLI prints for the same object. */
+export const serialize = (obj) => JSON.stringify(obj, null, 2) + "\n";
+
+class HttpError extends Error {
+  constructor(status, code, message, extra = {}) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.extra = extra;
+  }
+}
+
+const flag = (v) => v === "1";
+const one = (q, name) => (q[name] === undefined ? null : q[name][0]);
+
+/** Query-parameter rules: name -> {repeat?, check(value) -> ok}. */
+const Q = {
+  redact: { check: (v) => v === "0" || v === "1" },
+  group: { check: (v) => GROUP_NAMES.includes(v) },
+  measure: { check: (v) => v === "0" || v === "1" },
+  source: { check: (v) => ["jira", "github", "all"].includes(v) },
+  project: { repeat: true, check: (v) => PROJECT_KEY.test(v) },
+  max: { check: (v) => /^[0-9]{1,3}$/.test(v) && Number(v) >= 1 && Number(v) <= 200 },
+  repo: { check: (v) => v.length <= 4096 && isAbsolute(v) },
+};
+
+function runRecordFor(id) {
+  if (!RUN_ID.test(id)) throw new HttpError(404, "not-found", "no such run");
+  const { found, records } = selectRuns({ taskId: id });
+  if (!found) throw new HttpError(404, "not-found", "no such run");
+  return records;
+}
+
+function stateFileOf(record) {
+  for (const p of [
+    join(record.dir, "agent-state.json"),
+    join(record.dir, "artifacts", "agent-state.json"),
+  ]) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/** answer-request.schema.json, checked by hand (ADR-0004). */
+export function answerBodyErrors(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body))
+    return ["body is not a JSON object"];
+  const errors = [];
+  for (const k of Object.keys(body)) {
+    if (k !== "questionId" && k !== "optionIds") errors.push(`unknown field ${k}`);
+  }
+  if (
+    typeof body.questionId !== "string" ||
+    body.questionId.length > 100 ||
+    !QUESTION_ID.test(body.questionId)
+  ) {
+    errors.push("questionId must be a question id");
+  }
+  const ids = body.optionIds;
+  if (!Array.isArray(ids) || ids.length < 1 || ids.length > 50) {
+    errors.push("optionIds must be an array of 1 to 50 option ids");
+  } else if (!ids.every((id) => typeof id === "string" && id.length <= 100 && OPTION_ID.test(id))) {
+    errors.push("every optionIds entry must be an option id");
+  }
+  return errors;
+}
+
+const PHONE_REFUSAL = {
+  unsigned: "a device signature is required",
+  "unknown-device": "this device is not enrolled here",
+  "stale-request": "the timestamp is outside the accepted window",
+  "bad-signature": "the signature does not match the request",
+  "revoked-device": "this device was revoked",
+  replayed: "this request was already received",
+  "replay-store-full": "too many requests in the window; retry shortly",
+};
+
+const ANSWER_REFUSAL = {
+  "no-state": [409, "not-waiting"],
+  "not-waiting": [409, "not-waiting"],
+  "wrong-question": [409, "wrong-question"],
+  "state-moved": [409, "state-moved"],
+  "no-answer": [422, "wrong-arity"],
+  arity: [422, "wrong-arity"],
+  "not-an-option": [422, "not-an-option"],
+};
+
+/**
+ * POST /v1/launch and /v1/phone/launch. `channel` decides what the input may
+ * be (launch-request.mjs inputErrors): the phone takes structured references
+ * only. Either way the repo must be a configured or registered one.
+ */
+function launchRun({ q, body, redact, channel = "desktop" }) {
+  const repoPath = one(q, "repo");
+  if (!repoPath) throw new HttpError(400, "invalid-query", "repo is required");
+  if (!existsSync(repoPath) || !statSync(repoPath).isDirectory()) {
+    throw new HttpError(400, "invalid-query", "repo is not a directory");
+  }
+  if (!launchRepoAllowed(repoPath)) {
+    throw new HttpError(
+      403,
+      "repo-not-allowed",
+      "repo is neither a configured autopilot repo nor one registered with launch-request.mjs register-repo",
+    );
+  }
+  const sessionId = randomUUID();
+  const planned = join(requestsDir(), `${sessionId}.json`);
+  const args = {
+    request: body,
+    requestFile: planned,
+    repoPath,
+    sessionId,
+    workingTree: workingTreeState(repoPath),
+    channel,
+  };
+  const dry = planLaunch(args);
+  if (dry.code !== 0) {
+    const status = dry.reason === "no-launch-shape" ? 422 : 400;
+    throw new HttpError(status, dry.reason, "the launch request was refused", {
+      errors: dry.out.errors,
+    });
+  }
+  const written = writeRequestFile(body, sessionId);
+  return planLaunch({ ...args, requestFile: written, redact }).out;
+}
+
+function answerRun({ params, body }) {
+  const errors = answerBodyErrors(body);
+  if (errors.length) {
+    throw new HttpError(
+      400,
+      "invalid-body",
+      "the answer does not match answer-request.schema.json",
+      {
+        errors,
+      },
+    );
+  }
+  const [record] = runRecordFor(params.id);
+  const file = stateFileOf(record);
+  if (!file) throw new HttpError(409, "not-waiting", "this run is not waiting on a question");
+  const r = answerStateFile(file, body.optionIds, { questionId: body.questionId });
+  if (r.code === 0) return r.out;
+  const [status, code] = ANSWER_REFUSAL[r.reason] ?? [500, "internal"];
+  throw new HttpError(status, code, status === 500 ? "the answer could not be written" : r.error);
+}
+
+const listRuns = ({ q, redact }) =>
+  envelope(selectRuns({ group: one(q, "group") }).records, { redact });
+const oneRun = ({ params, redact }) => envelope(runRecordFor(params.id), { redact });
+
+/**
+ * Every route. `query` names the parameters beyond `v` and `redact` that a
+ * route accepts; `body` marks a route that reads a JSON body. A route with
+ * `scope` is a phone route: it is reached only with a device signature, never
+ * with the bearer token, and is always served redacted.
+ */
+export const ROUTES = [
+  { method: "GET", path: "/v1/runs", query: ["group"], handle: listRuns },
+  { method: "GET", path: "/v1/runs/{id}", query: [], handle: oneRun },
+  {
+    method: "GET",
+    path: "/v1/commands",
+    query: [],
+    handle: () => {
+      const out = catalog();
+      if (!out) throw new HttpError(500, "internal", "no command tree found");
+      return out;
+    },
+  },
+  { method: "GET", path: "/v1/questions", query: [], handle: () => questionsDocument() },
+  {
+    method: "GET",
+    path: "/v1/issues",
+    query: ["source", "project", "max"],
+    handle: ({ q }) =>
+      collect({
+        source: one(q, "source") ?? "all",
+        projects: q.project ?? [],
+        max: Number(one(q, "max") ?? 50),
+      }),
+  },
+  {
+    method: "GET",
+    path: "/v1/worktrees",
+    query: ["measure"],
+    handle: ({ q, redact }) => buildList({ doMeasure: flag(one(q, "measure")), redact }),
+  },
+  { method: "GET", path: "/v1/launch-spec", query: [], handle: () => launchSpec() },
+  { method: "POST", path: "/v1/launch", query: ["repo"], body: true, handle: launchRun },
+  { method: "POST", path: "/v1/runs/{id}/answer", query: [], body: true, handle: answerRun },
+  { method: "GET", path: "/v1/phone/runs", query: ["group"], scope: "read", handle: listRuns },
+  { method: "GET", path: "/v1/phone/runs/{id}", query: [], scope: "read", handle: oneRun },
+  {
+    method: "POST",
+    path: "/v1/phone/runs/{id}/answer",
+    query: [],
+    body: true,
+    scope: "answer",
+    handle: answerRun,
+  },
+  {
+    method: "POST",
+    path: "/v1/phone/launch",
+    query: ["repo"],
+    body: true,
+    scope: "launch",
+    handle: (ctx) => {
+      if (!ctx.registry.launchEnabled) {
+        throw new HttpError(403, "launch-disabled", "launch from a phone is not enabled here");
+      }
+      return launchRun({ ...ctx, channel: "phone" });
+    },
+  },
+].map((r) => ({
+  ...r,
+  phone: r.path.startsWith(PHONE_PREFIX),
+  pattern: new RegExp(`^${r.path.replace("{id}", "(?<id>[^/]+)")}$`),
+}));
+
+/**
+ * The route for a path and method, or the HttpError that says why not. A phone
+ * path is looked up among phone routes only and a desktop path among desktop
+ * routes only, so neither credential can reach the other family.
+ */
+export function match(method, pathname) {
+  const phone = isPhonePath(pathname);
+  const hits = [];
+  for (const r of ROUTES) {
+    if (r.phone !== phone) continue;
+    const m = r.pattern.exec(pathname);
+    if (m) hits.push({ route: r, params: m.groups ?? {} });
+  }
+  if (!hits.length) {
+    if (phone) throw new HttpError(404, "unknown-verb", "the phone API has no such verb");
+    throw new HttpError(404, "not-found", "no such route");
+  }
+  const hit = hits.find((h) => h.route.method === method);
+  if (!hit) {
+    throw new HttpError(
+      405,
+      "method-not-allowed",
+      `use ${hits.map((h) => h.route.method).join(", ")}`,
+      {
+        allow: hits.map((h) => h.route.method).join(", "),
+      },
+    );
+  }
+  if (hit.params.id !== undefined) {
+    try {
+      hit.params.id = decodeURIComponent(hit.params.id);
+    } catch {
+      throw new HttpError(404, "not-found", "no such run");
+    }
+  }
+  return hit;
+}
+
+/** Query parameters as {name: [values]}, after every rule a route declares. */
+export function parseQuery(route, searchParams) {
+  const q = {};
+  for (const [k, v] of searchParams) {
+    if (k !== "v" && k !== "redact" && !route.query.includes(k)) {
+      throw new HttpError(400, "invalid-query", `unknown query parameter ${k}`);
+    }
+    (q[k] ??= []).push(v);
+  }
+  for (const [k, values] of Object.entries(q)) {
+    if (k === "v") {
+      if (
+        values.length !== 1 ||
+        !SUPPORTED_MAJORS.includes(Number(values[0])) ||
+        !/^[0-9]+$/.test(values[0])
+      ) {
+        throw new HttpError(400, "unsupported-version", "this server does not serve that major", {
+          supported: SUPPORTED_MAJORS,
+        });
+      }
+      continue;
+    }
+    const rule = Q[k];
+    if (values.length > 1 && !rule.repeat)
+      throw new HttpError(400, "invalid-query", `${k} is given twice`);
+    for (const v of values) {
+      if (!rule.check(v)) throw new HttpError(400, "invalid-query", `${k} has an invalid value`);
+    }
+  }
+  return q;
+}
+
+const sha = (s) => createHash("sha256").update(s).digest();
+
+/** Does this path belong to the phone family? */
+export const isPhonePath = (pathname) =>
+  pathname === PHONE_PREFIX.slice(0, -1) || pathname.startsWith(PHONE_PREFIX);
+
+/** Constant-time bearer check: equal-length digests, whatever the input. */
+export function authorized(header, tokenDigest) {
+  const m = /^Bearer ([A-Za-z0-9_-]{1,512})$/.exec(String(header ?? ""));
+  return timingSafeEqual(sha(m ? m[1] : ""), tokenDigest) && Boolean(m);
+}
+
+function readRawBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    let over = false;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) over = true;
+      if (size > MAX_DRAIN_BYTES) req.destroy();
+      if (!over) chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (over) {
+        reject(new HttpError(400, "invalid-body", `the body is over ${MAX_BODY_BYTES} bytes`));
+        return;
+      }
+      resolve(Buffer.concat(chunks));
+    });
+    req.on("close", () => {
+      if (!req.complete) reject(new HttpError(400, "invalid-body", "the body was cut off"));
+    });
+    req.on("error", reject);
+  });
+}
+
+function parseJson(raw) {
+  try {
+    return JSON.parse(raw.toString("utf8"));
+  } catch {
+    throw new HttpError(400, "invalid-body", "the body is not JSON");
+  }
+}
+
+const readBody = async (req) => parseJson(await readRawBody(req));
+
+function drain(req) {
+  let size = 0;
+  req.on("data", (chunk) => {
+    size += chunk.length;
+    if (size > MAX_DRAIN_BYTES) req.destroy();
+  });
+  req.resume();
+}
+
+function parseArgs(argv) {
+  const opts = { port: 0, idleMinutes: DEFAULT_IDLE_MINUTES, origins: [], printToken: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const value = () => {
+      const v = argv[++i];
+      if (v === undefined) throw new Error(`${a} needs a value`);
+      return v;
+    };
+    if (a === "--host") {
+      const h = value();
+      if (h !== BIND_HOST) throw new Error(`binds only ${BIND_HOST}; --host ${h} is refused`);
+    } else if (a === "--port") {
+      const p = value();
+      if (!/^[0-9]{1,5}$/.test(p) || Number(p) > 65535) throw new Error("--port is 0 to 65535");
+      opts.port = Number(p);
+    } else if (a === "--idle-minutes") {
+      const n = Number(value());
+      if (!Number.isFinite(n) || n <= 0 || n > MAX_IDLE_MINUTES) {
+        throw new Error(`--idle-minutes is more than 0 and at most ${MAX_IDLE_MINUTES}`);
+      }
+      opts.idleMinutes = n;
+    } else if (a === "--allow-origin") {
+      const o = value();
+      let parsed;
+      try {
+        parsed = new URL(o);
+      } catch {
+        parsed = null;
+      }
+      if (!parsed || !/^https?:$/.test(parsed.protocol) || parsed.origin !== o) {
+        throw new Error(`--allow-origin takes an origin like http://127.0.0.1:5173, not ${o}`);
+      }
+      opts.origins.push(o);
+    } else if (a === "--print-token") opts.printToken = true;
+    else if (a === "-h" || a === "--help") opts.help = true;
+    else throw new Error(`unknown argument ${a}`);
+  }
+  return opts;
+}
+
+/** The token file this process wrote, removed on every way out. */
+let liveTokenFile = null;
+const removeTokenFile = () => {
+  if (liveTokenFile) rmSync(liveTokenFile, { force: true });
+  liveTokenFile = null;
+};
+
+function writeTokenFile(record) {
+  const dir = tokenDir();
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const file = join(dir, `${process.pid}.json`);
+  rmSync(file, { force: true });
+  writeFileSync(file, JSON.stringify(record, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+  liveTokenFile = file;
+  return file;
+}
+
+/**
+ * Start listening. Resolves with the ready record once the port is known.
+ *
+ * @param {{port?: number, idleMinutes?: number, origins?: string[], printToken?: boolean}} opts
+ */
+export function serve(opts) {
+  const token = randomBytes(32).toString("base64url");
+  const tokenDigest = sha(token);
+  const origins = new Set(opts.origins ?? []);
+  const idleMs = Math.round((opts.idleMinutes ?? DEFAULT_IDLE_MINUTES) * 60000);
+  let hosts = new Set();
+  let startSec = Infinity;
+  const nonces = createNonceStore({ file: noncesPath() });
+  let tokenFile = null;
+  let idleTimer = null;
+  let stopping = false;
+
+  // requireHostHeader off: a request without Host reaches the Host check below
+  // and is refused there with a contract error body, like any other wrong Host.
+  const server = createServer({
+    requestTimeout: 120000,
+    headersTimeout: 10000,
+    requireHostHeader: false,
+  });
+  server.maxHeadersCount = 50;
+
+  const send = (res, status, obj, extra = {}) => {
+    const body = serialize(obj);
+    res.writeHead(status, {
+      "Content-Type": "application/json; charset=utf-8",
+      "Content-Length": Buffer.byteLength(body),
+      "Cache-Control": "no-store",
+      "X-Content-Type-Options": "nosniff",
+      "X-Contract-Version": CONTRACT_VERSION,
+      ...extra,
+    });
+    res.end(body);
+  };
+  const fail = (res, err, extra) => {
+    const body = { contractVersion: CONTRACT_VERSION, error: err.code, message: err.message };
+    if (err.extra?.errors) body.errors = err.extra.errors;
+    if (err.extra?.supported) body.supported = err.extra.supported;
+    const headers = { ...extra };
+    if (err.extra?.allow) headers.Allow = err.extra.allow;
+    if (err.status === 401) headers["WWW-Authenticate"] = err.extra?.scheme ?? "Bearer";
+    send(res, err.status, body, headers);
+  };
+
+  const stop = (why) => {
+    if (stopping) return;
+    stopping = true;
+    clearTimeout(idleTimer);
+    removeTokenFile();
+    process.stderr.write(`contract-server: stopping (${why})\n`);
+    server.close(() => process.exit(0));
+    server.closeAllConnections();
+    setTimeout(() => process.exit(0), 2000).unref();
+  };
+  const arm = () => {
+    clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => stop("idle"), idleMs);
+  };
+
+  /**
+   * A phone request: the signature decides who is asking, before the route is
+   * even looked up, and the device's scopes decide what it may ask for. The
+   * bearer token plays no part in either direction. Every outcome is audited.
+   */
+  const servePhone = async (req, res, url, cors) => {
+    const audit = { deviceId: null, method: req.method, verb: verbOf(url.pathname) };
+    let insecure = null;
+    try {
+      const raw = await readRawBody(req);
+      const registry = readRegistry();
+      insecure = registry.insecure;
+      const v = verifyRequest({
+        method: req.method,
+        target: req.url ?? "",
+        headers: req.headers,
+        body: raw,
+        registry,
+        nonces,
+        nowSec: Math.floor(Date.now() / 1000),
+        notBeforeSec: startSec,
+      });
+      audit.deviceId = v.ok ? v.device.id : v.deviceId;
+      if (!v.ok) {
+        throw new HttpError(v.status, v.code, PHONE_REFUSAL[v.code], {
+          scheme: "MA-Phone-Signature",
+        });
+      }
+      const { route, params } = match(req.method, url.pathname);
+      if (!Array.isArray(v.device.scopes) || !v.device.scopes.includes(route.scope)) {
+        throw new HttpError(403, "forbidden-scope", `this device has no ${route.scope} scope`);
+      }
+      const q = parseQuery(route, url.searchParams);
+      if (q.redact && one(q, "redact") !== "1") {
+        throw new HttpError(400, "invalid-query", "phone responses are always redacted");
+      }
+      let body = null;
+      if (route.body) {
+        const type = String(req.headers["content-type"] ?? "");
+        if (!/^application\/json(\s*;.*)?$/i.test(type)) {
+          throw new HttpError(415, "unsupported-media-type", "the body must be application/json");
+        }
+        body = parseJson(raw);
+      }
+      send(res, 200, route.handle({ q, params, body, redact: true, registry }), cors);
+      appendAudit({ ...audit, status: 200, outcome: "accepted" });
+    } catch (err) {
+      const e = err instanceof HttpError ? err : new HttpError(500, "internal", "internal error");
+      if (!(err instanceof HttpError))
+        process.stderr.write(`contract-server: ${err?.message ?? err}\n`);
+      fail(res, e, cors);
+      const outcome = e.code === "unknown-device" && insecure ? insecure : e.code;
+      appendAudit({ ...audit, status: e.status, outcome });
+    }
+  };
+
+  server.on("request", async (req, res) => {
+    arm();
+    res.on("finish", arm);
+    const origin = req.headers.origin;
+    const cors =
+      origin && origins.has(origin)
+        ? { "Access-Control-Allow-Origin": origin, Vary: "Origin" }
+        : {};
+    try {
+      if (!hosts.has(String(req.headers.host ?? "").toLowerCase())) {
+        throw new HttpError(403, "forbidden-host", "the Host header does not name this server");
+      }
+      if (origin !== undefined && !origins.has(origin)) {
+        throw new HttpError(403, "forbidden-origin", "this origin is not allowed");
+      }
+      if (req.method === "OPTIONS" && origin !== undefined) {
+        drain(req);
+        res.writeHead(204, {
+          ...cors,
+          "Access-Control-Allow-Methods": "GET, POST",
+          "Access-Control-Allow-Headers": "Authorization, Content-Type",
+          "Access-Control-Max-Age": "600",
+          "Cache-Control": "no-store",
+        });
+        res.end();
+        return;
+      }
+      const url = new URL(req.url ?? "/", `http://${BIND_HOST}`);
+      if (isPhonePath(url.pathname)) {
+        await servePhone(req, res, url, cors);
+        return;
+      }
+      if (!authorized(req.headers.authorization, tokenDigest)) {
+        throw new HttpError(401, "unauthorized", "a bearer token is required");
+      }
+      const { route, params } = match(req.method, url.pathname);
+      const q = parseQuery(route, url.searchParams);
+      const redact = flag(one(q, "redact")) || origin !== undefined;
+      let body = null;
+      if (route.body) {
+        const type = String(req.headers["content-type"] ?? "");
+        if (!/^application\/json(\s*;.*)?$/i.test(type)) {
+          drain(req);
+          throw new HttpError(415, "unsupported-media-type", "the body must be application/json");
+        }
+        body = await readBody(req);
+      } else {
+        drain(req);
+      }
+      send(res, 200, route.handle({ q, params, body, redact }), cors);
+    } catch (err) {
+      if (err instanceof HttpError) {
+        fail(res, err, cors);
+        return;
+      }
+      process.stderr.write(`contract-server: ${err?.message ?? err}\n`);
+      fail(res, new HttpError(500, "internal", "internal error"), cors);
+    }
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(opts.port ?? 0, BIND_HOST, () => {
+      const { port } = server.address();
+      hosts = new Set([`${BIND_HOST}:${port}`, `localhost:${port}`]);
+      const record = {
+        contractVersion: CONTRACT_VERSION,
+        url: `http://${BIND_HOST}:${port}`,
+        port,
+        pid: process.pid,
+        idleMinutes: opts.idleMinutes ?? DEFAULT_IDLE_MINUTES,
+      };
+      const started = new Date();
+      startSec = Math.floor(started.getTime() / 1000);
+      tokenFile = writeTokenFile({ ...record, token, startedAt: started.toISOString() });
+      for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) process.on(sig, () => stop(sig));
+      arm();
+      resolve({ ...record, tokenFile, ...(opts.printToken ? { token } : {}) });
+    });
+  });
+}
+
+async function main(argv) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    process.stderr.write(`contract-server: ${err.message}\n`);
+    return 2;
+  }
+  if (opts.help) {
+    process.stdout.write(
+      "Usage: contract-server.mjs [--port N] [--idle-minutes N] [--allow-origin <origin>]... [--print-token]\n",
+    );
+    return 0;
+  }
+  try {
+    const ready = await serve(opts);
+    process.stdout.write(JSON.stringify(ready) + "\n");
+  } catch (err) {
+    process.stderr.write(`contract-server: could not listen (${err.code ?? err.message})\n`);
+    return 1;
+  }
+  return undefined;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain(
+    "contract-server",
+    async () => {
+      const code = await main(process.argv.slice(2));
+      if (code !== undefined) process.exitCode = code;
+    },
+    { cleanup: removeTokenFile },
+  );
+}