@open-everywhere/core 0.1.0

package/agent/control/http.ts

@@ -0,0 +1,169 @@
+// Remote transport for the admin plane — the "small web app" that hosts the MCP
+// server over HTTP so a deployed instance (e.g. Vercel) is reachable, vs the local
+// stdio entry (scripts/control-mcp.ts). Same buildControlServer(); only the
+// transport differs. Eve is Next.js, so in the real deploy this mounts as a route
+// handler in the Eve app (or a sibling app sharing the Neon DB).
+//
+// STATELESS by design: per the MCP serverless pattern, each request gets a FRESH
+// server + transport (sessionIdGenerator: undefined, no session reuse) — that's
+// what fits Vercel/Lambda's ephemeral, per-invocation model. No in-memory session
+// map to lose across cold starts.
+//
+// FAIL-CLOSED AUTH: a remote MCP server MUST be an OAuth 2.1 resource server
+// (RFC 9728 + RFC 8707). That gate now exists, on the DEPLOYMENT-MOUNTED route —
+// control/mcp-route.ts, behind control/oauth-resource.ts (OPE-72). This node:http
+// handler is not that route and does not run it: it REFUSES every request unless
+// the caller passes an `authorize` hook (real auth) or explicitly opts into
+// `allowUnauthenticated` (local/dev only). So it cannot be deployed publicly-open
+// by accident — the default is 401.
+//
+// DATA DURABILITY CAVEAT: this serves the control views, which read spend/routines/
+// audit from the FILESYSTEM today. On Vercel's ephemeral FS that's empty/unshared —
+// those stores must move behind the Neon provider seam (the slice before this is
+// useful in production). The transport here is correct regardless of that move.
+
+import { createServer, type IncomingMessage, type ServerResponse, type Server } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { buildControlServer } from "./server.js";
+import { SERVICE_TOKEN_ISSUER, type AdminIdentity } from "./auth.js";
+import type { TranscriptExportReader } from "./transcript-export.js";
+import { appendAudit } from "../audit/audit.js";
+import { deploymentOrg } from "../identity/binding.js";
+
+export interface AdminHttpOptions {
+  // Federated auth: validate the request's bearer token and return the resolved admin
+  // identity (with roles), or null to refuse. Build one with makeAdminAuthenticator /
+  // adminAuthenticatorFromEnv (auth.ts). When omitted, requests are denied unless
+  // allowUnauthenticated is set.
+  readonly authenticate?: (req: IncomingMessage) => Promise<AdminIdentity | null>;
+  // If set, the identity must carry this role (RBAC gate — e.g. "admin" for the write
+  // tools, "viewer" for reads). Unset = any authenticated identity is admitted.
+  readonly requiredRole?: string;
+  // Register the mutating tools. Pair with requiredRole:"admin" on a public deploy.
+  readonly includeWrites?: boolean;
+  // Escape hatch for local/dev ONLY — bypasses auth. Never set this in a public deploy.
+  readonly allowUnauthenticated?: boolean;
+  // How this mount reads a session transcript (control/transcript-export.ts), threaded straight
+  // into buildControlServer. A transcript lives in eve's durable stream and only a ROUTE HANDLER
+  // can attach to one, so this mount reads by dialling the deployment's own transcript route — the
+  // mounting route supplies a reader built from its own environment. Unset ⇒ `session_transcript`
+  // is still registered and answers with the names to set, exactly as on the stdio entry.
+  //
+  // 🔴 SETTING THIS WIDENS WHO CAN READ A TRANSCRIPT, so set it deliberately. The control-read
+  // token lives in the reader — it is the PROCESS's credential, not the caller's — while the
+  // caller presents an OIDC identity. An identity an OE_ADMIN_ROLE_RULES rule grants the org-wide
+  // "admin" role therefore reads any session's transcript without ever holding a value listed in
+  // OE_CONTROL_READ_TOKENS. That is the audit log's trust tier, which is the tier a transcript is
+  // documented at (docs/security/control-plane.md), but the widening is the MOUNT's choice: no
+  // mount in this repository supplies a reader.
+  readonly readTranscript?: TranscriptExportReader;
+}
+
+async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  if (chunks.length === 0) return undefined;
+  const raw = Buffer.concat(chunks).toString("utf-8");
+  return raw ? JSON.parse(raw) : undefined;
+}
+
+function deny(res: ServerResponse, code: number, message: string): void {
+  res.writeHead(code, { "content-type": "application/json" });
+  res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32001, message }, id: null }));
+}
+
+// Framework-neutral request handler — works in a raw node:http server, and drops
+// into a Next.js / Vercel Node route (parse the body, call this). `parsedBody` is
+// optional: pass it when the framework already parsed the JSON, else it's read here.
+// 🔴 EXPORT KEPT FOR A CONSUMER OUTSIDE THIS REPO (OPE-1455): that self-host route, which mounts
+// this handler directly. In-repo the only caller is `createAdminHttpServer` below, and the
+// control-auth suite drives it through that wrapper.
+export async function handleControlRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  opts: AdminHttpOptions = {},
+  parsedBody?: unknown,
+): Promise<void> {
+  // Fail closed. Dev escape hatch first (no identity, no role check). Otherwise an
+  // authenticator MUST be configured and MUST return an identity; then, if a role is
+  // required, the identity MUST carry it (RBAC).
+  let actor = "local-operator"; // dev/local default; overwritten by the resolved identity
+  let roles: readonly string[] = ["admin"]; // dev/local default: the unauthenticated escape hatch is fully trusted
+  let identity: AdminIdentity | null = null;
+  if (opts.allowUnauthenticated !== true) {
+    if (!opts.authenticate) {
+      deny(res, 401, "unauthorized: the remote control plane requires OAuth (RFC 9728) — no authenticator configured");
+      return;
+    }
+    identity = await opts.authenticate(req).catch(() => null);
+    if (!identity) {
+      deny(res, 401, "unauthorized: missing or invalid bearer token");
+      return;
+    }
+    if (opts.requiredRole && !identity.roles.includes(opts.requiredRole)) {
+      deny(res, 403, `forbidden: role "${opts.requiredRole}" required`);
+      return;
+    }
+    actor = `${identity.issuer}#${identity.subject}`; // the real WHO for write-tool audit
+    roles = identity.roles; // threaded into the server so scoped tools can domain-gate a non-admin identity
+  }
+
+  let body = parsedBody;
+  if (body === undefined && req.method === "POST") {
+    try {
+      body = await readJsonBody(req);
+    } catch {
+      deny(res, 400, "invalid JSON body");
+      return;
+    }
+  }
+
+  // Service-token calls (OE_CONTROL_READ_TOKENS) are ALWAYS audited — a machine
+  // credential leaves a per-request trail even for reads, unlike an interactive admin
+  // whose reads aren't logged. Best-effort (appendAudit never throws); the JSON-RPC
+  // method + tool name are recorded when the body carries them. Token value never logged.
+  if (identity?.issuer === SERVICE_TOKEN_ISSUER) {
+    const rpc = (typeof body === "object" && body !== null ? body : {}) as { method?: unknown; params?: { name?: unknown } };
+    await appendAudit({
+      org: deploymentOrg(),
+      platform: "control",
+      workspace: "control",
+      principalId: identity.subject, // "svc:<name>"
+      action: "control.service_call",
+      detail: {
+        service: identity.subject,
+        ...(typeof rpc.method === "string" ? { method: rpc.method } : {}),
+        ...(typeof rpc.params?.name === "string" ? { tool: rpc.params.name } : {}),
+      },
+    });
+  }
+
+  // Fresh server + transport per request (stateless). Tear down when the response
+  // closes so nothing leaks across serverless invocations.
+  // readOnly (service principals) strips the write tools from THIS request's server even
+  // when the mount registered them (includeWrites) — see server.ts's single choke point.
+  const server = buildControlServer({
+    includeWrites: opts.includeWrites,
+    actor,
+    roles,
+    readOnly: identity?.readOnly === true,
+    ...(opts.readTranscript ? { readTranscript: opts.readTranscript } : {}),
+  });
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+  res.on("close", () => {
+    void transport.close();
+    void server.close();
+  });
+  await server.connect(transport);
+  await transport.handleRequest(req, res, body);
+}
+
+// Convenience: a standalone node:http server, for local testing and self-host.
+// (On Vercel you'd mount handleControlRequest in a route instead of this.)
+export function createAdminHttpServer(opts: AdminHttpOptions = {}): Server {
+  return createServer((req, res) => {
+    void handleControlRequest(req, res, opts).catch((err) => {
+      if (!res.headersSent) deny(res, 500, `control server error: ${err instanceof Error ? err.message : String(err)}`);
+    });
+  });
+}

package/agent/control/mcp-route.ts

@@ -0,0 +1,105 @@
+// The control MCP WRITE transport over HTTPS — the deployment-mounted door that makes
+// `decide_pending_action` and every other control tool reachable without stdio and without the
+// deployment's DATABASE_URL on an operator's laptop (OPE-72).
+//
+// STATELESS, like control/http.ts and for the same reason: each request gets a FRESH server and
+// transport (`sessionIdGenerator: undefined`), which is what fits a serverless invocation model with
+// no in-memory session map to lose across cold starts.
+//
+// WHY THIS IS NOT control/http.ts. That module is a `node:http` handler kept for a self-host
+// consumer outside this repo (OPE-1455). An eve route hands us a WHATWG `Request` and wants a
+// `Response`, so this module uses the MCP SDK's own web-standard transport
+// (`WebStandardStreamableHTTPServerTransport`) rather than bridging one shape to the other. Both
+// mount the SAME `buildControlServer`, so there is one set of tools and one set of gates.
+//
+// THREE GATES, AND ALL THREE ARE SOMEONE ELSE'S CODE OR AN EXISTING CHOKE POINT:
+//   1. the OAuth 2.1 resource server (oauth-resource.ts) — eve's `routeAuth` walk over eve's
+//      `jwtHmac`, answering 404 unarmed and 401/403 with a real `WWW-Authenticate` challenge;
+//   2. the token's scopes → the EXISTING roles (`scopeDenial`) and the EXISTING `readOnly` flag;
+//   3. server.ts's single `includeWrites && readOnly !== true` choke point, which strips every
+//      mutating tool from a read-only token's server rather than refusing it per call.
+// Nothing here decides a permission on its own.
+
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { buildControlServer } from "./server.js";
+import { authorizeControlMcp, CONTROL_MCP_PATH } from "./oauth-resource.js";
+import { CONTROL_OAUTH_ISSUER } from "./oauth-clients.js";
+import { appendAudit } from "../audit/audit.js";
+import { deploymentOrg } from "../identity/binding.js";
+
+export { CONTROL_MCP_PATH };
+
+/**
+ * Handle one MCP request on {@link CONTROL_MCP_PATH}.
+ *
+ * 🔴 EVERY AUTHENTICATED CALL IS AUDITED, INCLUDING A READ. The MCP transport's own callers are
+ * machines and remote operators, so the row is the only record that the call happened — the same
+ * rule control/http.ts applies to service-token calls, and for the same reason. The row names the
+ * principal from the token (`oauth-client:<id>`, or `<issuer>#<subject>` for a person) and the
+ * JSON-RPC method plus tool name when the body carries them. No token value is ever logged.
+ */
+export async function handleControlMcpRequest(
+  req: Request,
+  env: NodeJS.ProcessEnv = process.env,
+  declaredIssuer: string = CONTROL_OAUTH_ISSUER,
+): Promise<Response> {
+  const principal = await authorizeControlMcp(req, env, declaredIssuer);
+  if (principal instanceof Response) return principal;
+
+  // Peek at the body on a CLONE — the transport must still receive an unread stream.
+  const rpc = await readRpcSummary(req);
+  await appendAudit({
+    org: deploymentOrg(),
+    platform: "control",
+    workspace: "control",
+    principalId: principal.subject,
+    action: "control.service_call",
+    detail: {
+      service: principal.subject,
+      client: principal.clientId,
+      scope: principal.scopes.join(" "),
+      readOnly: principal.readOnly,
+      ...(rpc.method ? { method: rpc.method } : {}),
+      ...(rpc.tool ? { tool: rpc.tool } : {}),
+    },
+  });
+
+  const server = buildControlServer({
+    includeWrites: true, // the mount registers them; `readOnly` is what actually strips them
+    // 🔴 THE ACTOR IS THE PRINCIPAL VERBATIM, WITH NO PREFIX. `principal.subject` is ALREADY
+    // `oauth-client:<id>` or `<issuer>#<subject>`, and `actor` becomes `principalId` on every
+    // write-tool audit row plus `setBy` on a stored override and `clickerId` on an approval
+    // decision (control/writes.ts). Prefixing it produced `control-oauth#<issuer>#<subject>` —
+    // a string that parses under no convention and that an auditor joining the write row to this
+    // request's `control.service_call` row would find no match for.
+    actor: principal.subject,
+    roles: principal.roles,
+    readOnly: principal.readOnly,
+  });
+  // `enableJsonResponse` returns one JSON body instead of opening an SSE stream. That is the right
+  // shape here for the same reason the mount is stateless: a serverless invocation cannot hold a
+  // stream open past its own lifetime, so a stream would be a promise the host cannot keep. MCP
+  // clients advertise `Accept: application/json, text/event-stream`, so a JSON answer is compliant.
+  const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+  try {
+    await server.connect(transport);
+    return await transport.handleRequest(req);
+  } finally {
+    await transport.close().catch(() => {});
+    await server.close().catch(() => {});
+  }
+}
+
+/** The JSON-RPC method and tool name, when the body is a single readable JSON-RPC call. */
+async function readRpcSummary(req: Request): Promise<{ method?: string; tool?: string }> {
+  if (req.method !== "POST") return {};
+  try {
+    const body = (await req.clone().json()) as { method?: unknown; params?: { name?: unknown } };
+    return {
+      ...(typeof body.method === "string" ? { method: body.method } : {}),
+      ...(typeof body.params?.name === "string" ? { tool: body.params.name } : {}),
+    };
+  } catch {
+    return {}; // a batch, an SSE re-attach, or an unparseable body — the row still names the principal
+  }
+}

package/agent/control/oauth-clients.ts

@@ -0,0 +1,278 @@
+// The control plane's OAuth 2.1 CONFIG — tracked literals, in Git, changed by pull request.
+//
+// 🔴 WHY NOTHING HERE IS AN ENV VAR. A client id, a redirect URI, an allowed audience and a
+// client secret's DIGEST are declarations of who this deployment trusts. AGENTS.md rules that a
+// trust declaration is a tracked literal: env carries INFRASTRUCTURE (connection strings, and the
+// bootstrap credentials that reach a store), never a roster. So the whole registry lives here and
+// changes the way behaviour changes — by review. The ONE env var this plane adds is the signing
+// secret ({@link ../control/oauth-tokens.ts}), which is infrastructure by that same rule: it is a
+// key, not a list.
+//
+// 🔴 THE CLIENT SECRET IS NEVER IN THE TREE — its sha256 DIGEST is. Same shape, same reason, as
+// `OE_CONTROL_READ_TOKENS` (auth.ts): the operator mints a random secret, commits the digest here,
+// and hands the secret to the one agent that uses it. A digest authenticates nothing on its own, so
+// a source-open repository can carry it; the token endpoint hashes the presented secret and
+// constant-time-compares. Losing the tree loses no credential.
+//
+// SCOPES ARE THE EXISTING ROLES, NOT A SECOND ROLE MODEL. `scopesToGrant` maps a token's `scope`
+// claim onto the SAME `readonly string[]` roles that `scopeDenial(roles, { org })` (auth.ts) has
+// always taken, and onto the SAME `readOnly` flag that strips every write tool at server.ts's one
+// choke point. There is no third place a permission can be decided.
+
+import { createHash, timingSafeEqual } from "node:crypto";
+
+/**
+ * EXTRA audiences this deployment's resource server accepts, beyond its own canonical resource URL.
+ * Tracked literals, so widening the set is a reviewed change — an audience is a declaration of
+ * which resource a token may act on, and that is a trust declaration.
+ *
+ * The deployment's OWN resource URL is always accepted and is NOT listed here: it is derived from
+ * the declared {@link CONTROL_OAUTH_ISSUER} (`<issuer>/control/v1/mcp`), so listing it would be
+ * restating one tracked literal in another. Add an entry only for an alias host or a proxy that
+ * fronts this deployment under a second name.
+ */
+export const CONTROL_OAUTH_EXTRA_AUDIENCES: readonly string[] = [];
+
+/**
+ * Every audience the resource server accepts: this deployment's own resource, then the tracked
+ * extras.
+ *
+ * 🔴 THREE VALUES ARE DROPPED, AND ONE OF THEM IS LOAD-BEARING. eve's `jwtHmac` checks `aud` and
+ * never reads the `typ` header, so `aud` is the ONLY thing separating an authorization code from an
+ * access token at the resource server. A code's `aud` is {@link authorizationCodeAudience} —
+ * `<issuer>#authorization-code` — so an extra audience spelling THAT value would make a raw code
+ * validate as a bearer token, skipping PKCE and the single-use claim entirely. That entry is the
+ * one this guard exists for.
+ *
+ * The bare `issuer` and `issuer/` entries are dropped as defence in depth, not because they are
+ * exploitable today: the `#authorization-code` suffix already keeps a code's audience away from
+ * them. They are refused because the extras list is exactly where an operator would paste their own
+ * origin, and a future change that shortened the code audience back to the plain issuer would then
+ * find the hole already closed. 🔴 Do not read the suffix as redundant with this filter — remove the
+ * suffix and the filter's `issuer` entry becomes the only thing standing between a code and a
+ * bearer token.
+ */
+export function controlOAuthAudiences(
+  selfResource: string,
+  issuer: string,
+  extras: readonly string[] = CONTROL_OAUTH_EXTRA_AUDIENCES,
+): string[] {
+  const forbidden = new Set([issuer, `${issuer}/`, authorizationCodeAudience(issuer)]);
+  const accepted = extras.filter((a) => {
+    if (!forbidden.has(a)) return true;
+    console.warn(
+      `[open-everywhere:control] CONTROL_OAUTH_EXTRA_AUDIENCES entry ignored — an audience equal to the issuer (or to the authorization-code audience) would let a raw authorization code validate as an access token.`,
+    );
+    return false;
+  });
+  return [selfResource, ...accepted];
+}
+
+/** The audience an authorization code carries — issuer-derived, and never an accepted token audience. */
+export function authorizationCodeAudience(issuer: string): string {
+  return `${issuer}#authorization-code`;
+}
+
+/**
+ * This deployment's OAuth issuer identifier (RFC 8414) — its public origin, `https://<host>`, with
+ * no path and no trailing slash. EMPTY BY DEFAULT, and empty means the plane is OFF: every route
+ * 404s until an operator declares it here, in the same pull request that registers a client.
+ *
+ * 🔴 IT IS A TRACKED LITERAL, NOT THE REQUEST'S `Host` HEADER, AND THAT IS THE WHOLE CONTROL. The
+ * issuer feeds the `iss` a minted token carries and the `aud` derived from it
+ * ({@link controlOAuthAudiences}), and both are checked by the resource server. Deriving them from
+ * `new URL(req.url).origin` would let the CALLER name the audience its own token is bound to, which
+ * empties RFC 8707 audience binding of meaning: a token minted under one claimed host validates
+ * under the same claimed host, so `aud` stops separating this resource from any other. Declaring it
+ * pins both sides to one value nobody outside a pull request can move.
+ */
+export const CONTROL_OAUTH_ISSUER = "";
+
+/** Is `issuer` a usable issuer identifier — an absolute https origin with no path? */
+export function isValidIssuer(issuer: string): boolean {
+  try {
+    const url = new URL(issuer);
+    return url.protocol === "https:" && url.pathname === "/" && url.search === "" && url.hash === "" && issuer === url.origin;
+  } catch {
+    return false;
+  }
+}
+
+// --- the scope grammar ---------------------------------------------------------------------
+//
+// Four shapes, and NOTHING ELSE parses:
+//   control:write            — register the mutating tools for this token. ABSENT ⇒ read-only.
+//   control:admin            — role "admin" (covers every scope in the deployment).
+//   control:domain:<name>    — role "domain:<name>" (covers that memory domain).
+// An unknown scope string is not ignored — it is REFUSED at mint time, so a typo in a client's
+// declaration fails loudly at the token endpoint instead of quietly granting less than intended.
+
+/** The scope that turns the write tools on. Its absence is what makes a token read-only. */
+export const SCOPE_CONTROL_WRITE = "control:write";
+/** The scope carrying the org-admin role. */
+export const SCOPE_CONTROL_ADMIN = "control:admin";
+/** Prefix of the domain-scoped role scopes: `control:domain:<name>` → role `domain:<name>`. */
+export const SCOPE_CONTROL_DOMAIN_PREFIX = "control:domain:";
+
+/** What a verified token's scopes BUY, in the vocabulary the control plane already speaks. */
+export interface ControlGrant {
+  /** Roles for `scopeDenial(roles, { org })` / `siloScopeDenial` — never a parallel model. */
+  readonly roles: readonly string[];
+  /** True unless `control:write` is present — server.ts then registers no mutating tool. */
+  readonly readOnly: boolean;
+}
+
+/** Is `scope` a shape this plane understands? Used to refuse a typo at mint time. */
+export function isKnownControlScope(scope: string): boolean {
+  if (scope === SCOPE_CONTROL_WRITE || scope === SCOPE_CONTROL_ADMIN) return true;
+  return scope.startsWith(SCOPE_CONTROL_DOMAIN_PREFIX) && scope.length > SCOPE_CONTROL_DOMAIN_PREFIX.length;
+}
+
+/**
+ * Map a token's scopes onto the existing role vocabulary. FAIL-CLOSED in both directions: an
+ * unknown scope contributes nothing, and a token with no role scope gets `roles: []`, which
+ * `scopeDenial` refuses for every ask including an org-wide one. `readOnly` defaults TRUE, so a
+ * token that forgot `control:write` reads and cannot write — never the reverse.
+ */
+export function scopesToGrant(scopes: readonly string[]): ControlGrant {
+  const roles = new Set<string>();
+  let write = false;
+  for (const scope of scopes) {
+    if (scope === SCOPE_CONTROL_WRITE) {
+      write = true;
+      continue;
+    }
+    if (scope === SCOPE_CONTROL_ADMIN) {
+      roles.add("admin");
+      continue;
+    }
+    if (scope.startsWith(SCOPE_CONTROL_DOMAIN_PREFIX)) {
+      const name = scope.slice(SCOPE_CONTROL_DOMAIN_PREFIX.length);
+      if (name.length > 0) roles.add(`domain:${name}`);
+    }
+  }
+  return { roles: [...roles], readOnly: !write };
+}
+
+/** Parse an OAuth `scope` parameter/claim — space-delimited per RFC 6749 §3.3, blanks dropped. */
+export function parseScopeString(raw: string | null | undefined): string[] {
+  if (!raw) return [];
+  return raw.split(/\s+/).filter((s) => s.length > 0);
+}
+
+// --- the client registry -------------------------------------------------------------------
+
+/**
+ * A registered OAuth client. Exactly one grant per client — a client that may do both is two
+ * registrations, so a leaked machine secret can never walk the person flow.
+ */
+export type ControlOAuthClient =
+  | {
+      /** Machine-to-machine: an agent this deployment's operator minted a secret for. */
+      readonly grant: "client_credentials";
+      readonly clientId: string;
+      /** Lowercase sha256 hex of the client SECRET. The secret itself is never in the tree. */
+      readonly clientSecretSha256: string;
+      /** The most this client may ever receive. A request for more is narrowed to this set. */
+      readonly scopes: readonly string[];
+      readonly label: string;
+    }
+  | {
+      /** A person's MCP client: public (no secret), PKCE S256 required. */
+      readonly grant: "authorization_code";
+      readonly clientId: string;
+      /** Exact-match redirect URIs. No prefix matching, no wildcards — the open-redirect vector. */
+      readonly redirectUris: readonly string[];
+      readonly scopes: readonly string[];
+      readonly label: string;
+    };
+
+/**
+ * The registered clients. EMPTY BY DEFAULT, and that is the fail-closed posture: a deployment that
+ * registers nobody issues no token, so arming only the signing secret opens nothing.
+ *
+ * TO REGISTER A MACHINE CLIENT. `npm run mint:control-token -w @open-everywhere/core -- <name>`
+ * prints TWO lines. Take the 64-hex digest from the second one
+ * (`OE_CONTROL_READ_TOKENS=<name>:<hash>`) and commit just that hex as `clientSecretSha256`; hand
+ * the value on the first line (`E2E_CONTROL_READ_TOKEN=<token>`) to the agent as its
+ * `client_secret`.
+ *
+ * 🔴 SET NEITHER ENV VAR. The script prints those names because it was written for the read
+ * service-token family, and its own closing line says the families are disjoint. An OAuth client
+ * secret is not a read service token: pasting the printed entry into `OE_CONTROL_READ_TOKENS`
+ * would silently arm a second, unrelated credential that opens the READ routes. The generator is
+ * borrowed for its random value and its digest, not for its destination.
+ *
+ * TO REGISTER A PERSON'S CLIENT: add the `authorization_code` entry with its exact redirect URI.
+ * It is public — no secret at all — because PKCE, not a secret, is what binds the exchange.
+ *
+ * Both are pull requests, by design.
+ */
+export const CONTROL_OAUTH_CLIENTS: readonly ControlOAuthClient[] = [];
+
+const CLIENT_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/**
+ * Look a client up by id. Returns null for an unknown id, and ALSO for a registration this file's
+ * own rules reject (a malformed id, a bad digest, an unknown scope, a non-absolute redirect URI) —
+ * a broken entry authenticates nobody rather than half-working. Validation lives at the lookup, not
+ * at module load, so one bad entry cannot take the deployment's boot down with it.
+ */
+export function findControlOAuthClient(
+  clientId: string,
+  registry: readonly ControlOAuthClient[] = CONTROL_OAUTH_CLIENTS,
+): ControlOAuthClient | null {
+  const client = registry.find((c) => c.clientId === clientId);
+  if (!client || !CLIENT_ID.test(client.clientId)) return null;
+  if (client.scopes.length === 0 || !client.scopes.every(isKnownControlScope)) return null;
+  if (client.grant === "client_credentials") {
+    return SHA256_HEX.test(client.clientSecretSha256) ? client : null;
+  }
+  if (client.redirectUris.length === 0) return null;
+  return client.redirectUris.every(isAbsoluteRedirectUri) ? client : null;
+}
+
+/** An exact, absolute, fragment-free redirect URI. Anything else is refused at lookup. */
+function isAbsoluteRedirectUri(uri: string): boolean {
+  try {
+    const parsed = new URL(uri);
+    return parsed.hash === "" && (parsed.protocol === "https:" || parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Constant-time check of a presented client secret against the registration's digest. The compare
+ * is over two fixed 32-byte digests, exactly as {@link ../control/auth.ts matchServiceToken} does,
+ * so a timing side channel cannot walk the secret out.
+ */
+export function clientSecretMatches(presented: string, client: ControlOAuthClient): boolean {
+  if (client.grant !== "client_credentials" || !presented) return false;
+  const expected = Buffer.from(client.clientSecretSha256, "hex");
+  const actual = createHash("sha256").update(presented, "utf-8").digest();
+  return expected.length === actual.length && timingSafeEqual(actual, expected);
+}
+
+/**
+ * The scopes a request actually gets: the intersection of what it asked for and what the client may
+ * ever hold. An empty ask means "everything this client may hold" (RFC 6749 §3.3). Returns null
+ * when the ask names a scope the client does not hold — REFUSED, not silently narrowed, so a client
+ * never believes it holds a power the token lacks.
+ */
+export function grantedScopes(requested: readonly string[], client: ControlOAuthClient): string[] | null {
+  if (requested.length === 0) return [...client.scopes];
+  return requested.every((s) => client.scopes.includes(s)) ? [...requested] : null;
+}
+
+/**
+ * The audience a `resource` parameter (RFC 8707) names, or null when it is not one this deployment
+ * serves. An absent parameter takes the deployment's own resource — `allowed[0]` by construction of
+ * {@link controlOAuthAudiences} — so a client that does not speak resource indicators still gets a
+ * token bound to exactly one resource.
+ */
+export function resolveAudience(resource: string | null | undefined, allowed: readonly string[]): string | null {
+  if (!resource) return allowed[0] ?? null;
+  return allowed.includes(resource) ? resource : null;
+}