@open-everywhere/core 0.1.0

package/agent/control/oauth-resource.ts

@@ -0,0 +1,200 @@
+// The control plane's OAuth 2.1 RESOURCE server — the door the control MCP transport sits behind.
+//
+// 🔴 EVE-PARITY FIRST, AND HERE IT REACHES ALMOST ALL THE WAY. eve 0.54.3 ships the whole
+// resource-server arm and this file uses it rather than re-implementing it:
+//   • `jwtHmac()`      — verifies the bearer JWT's signature, `exp`/`nbf` (with clock skew), `aud`
+//                        and `iss`, and projects the non-registered claims (our `scope`,
+//                        `client_id`) onto the caller snapshot's `attributes`
+//                        (node_modules/eve/dist/src/channel/auth/token-claims.js
+//                        createJwtAttributeProjection).
+//   • `oauthResource()`— decorates that `AuthFn` with RFC 9728 protected-resource metadata.
+//   • `routeAuth()`    — the ordered walk, and the 401 with a real `WWW-Authenticate: Bearer`
+//                        challenge when it exhausts.
+// This is the SAME walk PR #652 put the service-token doors on. There is no second auth walk here.
+//
+// 🔴 WHERE EVE STOPS, exactly (the parity test pins each of these):
+//   1. eve has NO authorization server — no token endpoint, no PKCE, no client registry, no code
+//      exchange. `oauthResource` only DECLARES where an authorization server is. That half is ours
+//      (oauth-route.ts, oauth-tokens.ts, oauth-clients.ts).
+//   2. eve does not ENFORCE scopes. `jwtHmac`'s `claims` matcher is a membership test over a whole
+//      claim VALUE, and an OAuth `scope` claim is a space-delimited SET, so it cannot express
+//      "holds control:write". Scope → role mapping is ours (oauth-clients.ts `scopesToGrant`), and
+//      it maps onto the roles `scopeDenial` already takes — never a parallel role model.
+//   3. eve PUBLISHES the RFC 9728 metadata document and merges `resource_metadata` into the 401
+//      challenge only inside `mcpChannel`, through `#internal/mcp/protected-resource.js`, which no
+//      public subpath exports. `mcpChannel` serves eve's own agent-invocation tools, not
+//      `buildControlServer`, so we cannot mount on it. We therefore publish the document ourselves
+//      ({@link controlProtectedResourceMetadata}) — read back off eve's own decoration via
+//      `readOAuthResourceOptions`, so the document and the door cannot drift apart.
+
+import { jwtHmac, oauthResource, readOAuthResourceOptions, routeAuth, type AuthFn } from "eve/channels/auth";
+import {
+  CONTROL_OAUTH_ISSUER,
+  controlOAuthAudiences,
+  isValidIssuer,
+  SCOPE_CONTROL_ADMIN,
+  SCOPE_CONTROL_WRITE,
+  parseScopeString,
+  scopesToGrant,
+  type ControlGrant,
+} from "./oauth-clients.js";
+import { oauthSigningSecret } from "./oauth-tokens.js";
+
+/** Where the control MCP write transport is mounted. */
+export const CONTROL_MCP_PATH = "/control/v1/mcp";
+/** RFC 9728 discovery path for {@link CONTROL_MCP_PATH}. */
+export const CONTROL_PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource/control/v1/mcp";
+
+/**
+ * The scopes this resource server advertises. Domain scopes are deployment-specific
+ * (`control:domain:<name>`) so they are not enumerable here; the two fixed ones are.
+ */
+export const CONTROL_ADVERTISED_SCOPES: readonly string[] = [SCOPE_CONTROL_ADMIN, SCOPE_CONTROL_WRITE];
+
+/**
+ * This deployment's OAuth issuer identifier (RFC 8414), or null when it is not declared or is
+ * malformed — and null means the plane is OFF, exactly like a missing signing secret.
+ *
+ * 🔴 IT IS NEVER READ FROM THE REQUEST. An earlier revision derived it from
+ * `new URL(req.url).origin`, i.e. from the caller's `Host` header. That let the caller name the
+ * audience its own token was bound to, so `aud` — the one thing RFC 8707 binding rests on, and (see
+ * oauth-tokens.ts) the one thing separating an authorization code from an access token at eve's
+ * verifier — stopped meaning anything. The value is a tracked literal in oauth-clients.ts,
+ * `issuer` exists as a parameter only so a test can drive a deployment that declared one.
+ */
+export function controlOAuthIssuer(issuer: string = CONTROL_OAUTH_ISSUER): string | null {
+  return isValidIssuer(issuer) ? issuer : null;
+}
+
+/**
+ * This deployment's own resource identifier — the MCP mount's URL. It is the default `aud` of a
+ * minted token and the `resource` the RFC 9728 document publishes, so the two cannot disagree.
+ */
+export function controlMcpResource(issuer: string): string {
+  return new URL(CONTROL_MCP_PATH, issuer).toString();
+}
+
+/**
+ * The resource-server `AuthFn` — eve's HMAC bearer verifier, decorated with RFC 9728 metadata.
+ * Returns null when the plane is UNARMED (no signing secret), which callers turn into a 404: an
+ * unarmed deployment does not disclose that the seam exists.
+ */
+export function controlResourceAuth(env: NodeJS.ProcessEnv = process.env, declaredIssuer: string = CONTROL_OAUTH_ISSUER): AuthFn<Request> | null {
+  const secret = oauthSigningSecret(env);
+  if (secret === null) return null;
+  const issuer = controlOAuthIssuer(declaredIssuer);
+  if (issuer === null) return null; // no declared issuer → the plane is off, same as no secret
+  const resource = controlMcpResource(issuer);
+  return oauthResource(
+    jwtHmac({
+      algorithm: "HS256",
+      audiences: controlOAuthAudiences(resource, issuer),
+      issuer,
+      secret,
+      // Tight, because the issuer and the verifier are the SAME process on the same clock — the
+      // tolerance exists only for a serverless instance whose clock drifted, not for a third party's.
+      clockSkewSeconds: 30,
+    }),
+    { issuer, resource, scopes: CONTROL_ADVERTISED_SCOPES },
+  );
+}
+
+/** A verified control-plane caller, in the vocabulary buildControlServer already takes. */
+export interface ControlOAuthPrincipal extends ControlGrant {
+  /** The audit principal — `oauth-client:<id>` for a machine, `<issuer>#<subject>` for a person. */
+  readonly subject: string;
+  readonly clientId: string;
+  readonly scopes: readonly string[];
+}
+
+/**
+ * Run eve's walk and map the verified caller onto roles. Returns a `Response` (eve's own 401, or
+ * our 404 when unarmed) or the principal.
+ *
+ * 🔴 A TOKEN THAT CARRIES NO ROLE SCOPE IS REFUSED HERE, not admitted with `roles: []`. Admitting it
+ * would rest the whole gate on every downstream view remembering to call `scopeDenial` — and
+ * `roleCoversScope`'s own doc records a view that copied the shape and skipped that gate. A caller
+ * who can reach no view is refused at the door instead, with `insufficient_scope` so the client
+ * knows to ask for more rather than retrying the same token.
+ */
+export async function authorizeControlMcp(
+  req: Request,
+  env: NodeJS.ProcessEnv = process.env,
+  declaredIssuer: string = CONTROL_OAUTH_ISSUER,
+): Promise<ControlOAuthPrincipal | Response> {
+  const auth = controlResourceAuth(env, declaredIssuer);
+  const issuer = controlOAuthIssuer(declaredIssuer);
+  if (auth === null || issuer === null) return new Response("not found", { status: 404 }); // unarmed → the route does not exist
+  const verified = await routeAuth(req, auth);
+  if (verified instanceof Response) return withResourceMetadata(verified, issuer);
+
+  const scopes = parseScopeString(readAttribute(verified.attributes, "scope"));
+  const grant = scopesToGrant(scopes);
+  if (grant.roles.length === 0) {
+    return withResourceMetadata(
+      new Response(JSON.stringify({ ok: false, code: "insufficient_scope", error: "the token carries no control-plane role scope" }), {
+        status: 403,
+        headers: {
+          "content-type": "application/json",
+          "cache-control": "no-store",
+          "www-authenticate": `Bearer error="insufficient_scope", scope="${CONTROL_ADVERTISED_SCOPES.join(" ")}"`,
+        },
+      }),
+      issuer,
+    );
+  }
+  return {
+    ...grant,
+    scopes,
+    subject: verified.subject ?? verified.principalId,
+    clientId: readAttribute(verified.attributes, "client_id") ?? "unknown",
+  };
+}
+
+function readAttribute(attributes: Readonly<Record<string, string | readonly string[]>>, name: string): string | undefined {
+  const value = attributes[name];
+  return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * Add `resource_metadata` to a refusal's `WWW-Authenticate`, per RFC 9728 §5.1 — the pointer an MCP
+ * client follows to discover where to get a token. eve does this inside `mcpChannel` only (see the
+ * file header), so the control mount does it here. Appends rather than replaces, so eve's own
+ * `error="invalid_token"` survives.
+ */
+function withResourceMetadata(res: Response, issuer: string): Response {
+  if (res.status !== 401 && res.status !== 403) return res;
+  const metadata = new URL(CONTROL_PROTECTED_RESOURCE_METADATA_PATH, issuer).toString();
+  const headers = new Headers(res.headers);
+  const existing = headers.get("www-authenticate");
+  if (existing === null) headers.set("www-authenticate", `Bearer resource_metadata="${metadata}"`);
+  else if (!/(?:^|[\s,])resource_metadata\s*=/i.test(existing)) {
+    headers.set("www-authenticate", `${existing}${existing.trim().toLowerCase() === "bearer" ? " " : ", "}resource_metadata="${metadata}"`);
+  }
+  return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+}
+
+/**
+ * The RFC 9728 protected-resource metadata document. Built from the options eve's `oauthResource`
+ * decoration actually carries (`readOAuthResourceOptions`), so the published document cannot claim
+ * an issuer or a scope set the door does not use. Returns null when the plane is unarmed.
+ */
+export function controlProtectedResourceMetadata(
+  env: NodeJS.ProcessEnv = process.env,
+  declaredIssuer: string = CONTROL_OAUTH_ISSUER,
+): Record<string, unknown> | null {
+  const auth = controlResourceAuth(env, declaredIssuer);
+  const issuer = controlOAuthIssuer(declaredIssuer);
+  if (auth === null || issuer === null) return null;
+  const options = readOAuthResourceOptions(auth);
+  if (options === undefined) return null;
+  const authorizationServers = options.issuer === undefined ? [...(options.authorizationServers ?? [])] : [options.issuer];
+  return {
+    // Also the RFC 8707 value a client passes as `resource` at the token endpoint, and the `aud`
+    // the minted token then carries — one string for all three, so nothing can drift.
+    resource: options.resource ?? controlMcpResource(issuer),
+    authorization_servers: authorizationServers,
+    scopes_supported: [...(options.scopes ?? [])],
+    bearer_methods_supported: ["header"],
+  };
+}

package/agent/control/oauth-route.ts

@@ -0,0 +1,397 @@
+// The control plane's small AUTHORIZATION server — the half eve does not ship.
+//
+// FOUR ROUTES, all mounted by channels/control-mcp.ts:
+//   GET  /.well-known/oauth-authorization-server            RFC 8414 metadata
+//   GET  /.well-known/oauth-protected-resource/control/v1/mcp   RFC 9728 metadata (oauth-resource.ts)
+//   GET  /control/v1/oauth/authorize                        authorization code + PKCE, for a person
+//   POST /control/v1/oauth/token                            client_credentials, and the code exchange
+//
+// FAIL-CLOSED AT TWO RUNGS, in this order, on every route:
+//   1. no signing secret ⇒ 404. The plane is off and does not disclose that the seam exists — the
+//      same posture control/read-route.ts takes when its token family is unset.
+//   2. an unregistered client, a bad secret, a bad code, a bad PKCE verifier ⇒ a spec-shaped refusal
+//      that never says WHICH check failed.
+//
+// 🔴 WHO A PERSON IS, AND WHAT IS NOT BUILT YET. The authorize endpoint does not log a human in: it
+// requires the caller to present a credential this deployment's EXISTING admin door already accepts
+// (auth.ts `adminAuthenticatorFromEnv` — a configured OIDC issuer, a GitHub user token, or the
+// single-operator static token) and mints a code for THAT identity, downscoped to the roles the
+// identity's own role rules grant. So the flow is a correct authorization-code + PKCE round trip for
+// a CLI or programmatic client that can set an `Authorization` header. It is NOT a browser login:
+// there is no consent page and no session cookie, because federated human identity is the ticket's
+// separate leg (OPE-72 (a), TRIAGE 2026-09-08 — "build (c) first"). A browser that opens the
+// authorize URL with no bearer gets a 401, not a login form. Say that plainly wherever this is
+// documented; a doc claiming a browser login would overclaim.
+
+import type { IncomingMessage } from "node:http";
+import { adminAuthenticatorFromEnv, SERVICE_TOKEN_ISSUER, type AdminIdentity } from "./auth.js";
+import {
+  CONTROL_OAUTH_CLIENTS,
+  CONTROL_OAUTH_ISSUER,
+  clientSecretMatches,
+  controlOAuthAudiences,
+  findControlOAuthClient,
+  grantedScopes,
+  parseScopeString,
+  resolveAudience,
+  SCOPE_CONTROL_ADMIN,
+  SCOPE_CONTROL_DOMAIN_PREFIX,
+  SCOPE_CONTROL_WRITE,
+  type ControlOAuthClient,
+} from "./oauth-clients.js";
+import {
+  ACCESS_TOKEN_TTL_SECONDS,
+  mintAccessToken,
+  mintAuthorizationCode,
+  oauthSigningSecret,
+  pkceVerifierMatches,
+  redeemAuthorizationCode,
+  verifyAuthorizationCode,
+  type MarkCodeSpentFn,
+} from "./oauth-tokens.js";
+import { CONTROL_ADVERTISED_SCOPES, CONTROL_MCP_PATH, controlMcpResource, controlOAuthIssuer, controlProtectedResourceMetadata } from "./oauth-resource.js";
+import { appendAudit } from "../audit/audit.js";
+import { deploymentOrg } from "../identity/binding.js";
+
+export const CONTROL_OAUTH_AUTHORIZE_PATH = "/control/v1/oauth/authorize";
+export const CONTROL_OAUTH_TOKEN_PATH = "/control/v1/oauth/token";
+export const CONTROL_OAUTH_SERVER_METADATA_PATH = "/.well-known/oauth-authorization-server";
+
+/** Injectable edges, so every leg below is drivable without a store or a live IdP. */
+export interface ControlOAuthDeps {
+  readonly env?: NodeJS.ProcessEnv;
+  /** The client registry to resolve against. Default: the tracked one in oauth-clients.ts. */
+  readonly clients?: readonly ControlOAuthClient[];
+  /** The declared issuer to resolve against. Default: the tracked literal in oauth-clients.ts. */
+  readonly issuer?: string;
+  /** Resolve the person behind an authorize call. Default: the deployment's configured admin door. */
+  readonly adminIdentity?: (req: Request) => Promise<AdminIdentity | null>;
+  readonly markCodeSpent?: MarkCodeSpentFn;
+  readonly now?: Date;
+}
+
+function json(status: number, body: unknown, headers: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", "cache-control": "no-store", ...headers } });
+}
+
+/** RFC 6749 §5.2 error body. Never names which check failed beyond the registered code. */
+function oauthError(status: number, code: string, description: string, headers: Record<string, string> = {}): Response {
+  return json(status, { error: code, error_description: description }, headers);
+}
+
+const NOT_FOUND = () => new Response("not found", { status: 404 });
+
+/**
+ * The two things that arm this plane: the signing secret (env — infrastructure) and the declared
+ * issuer (tracked config). Either missing ⇒ null ⇒ the caller answers 404. Both are read per call,
+ * so nothing caches an unarmed state past a redeploy.
+ */
+function armed(deps: ControlOAuthDeps): { secret: string; issuer: string } | null {
+  const secret = oauthSigningSecret(deps.env ?? process.env);
+  const issuer = controlOAuthIssuer(deps.issuer ?? CONTROL_OAUTH_ISSUER);
+  return secret === null || issuer === null ? null : { secret, issuer };
+}
+
+/**
+ * `GET /.well-known/oauth-authorization-server` — RFC 8414. Advertises only what is implemented:
+ * the two grants, S256 PKCE, and `client_secret_basic`/`client_secret_post` for confidential
+ * clients. Deliberately advertises NO registration endpoint: dynamic client registration would let
+ * an unauthenticated caller create a client, and this deployment's clients are tracked literals that
+ * change by pull request (oauth-clients.ts).
+ */
+export function handleAuthorizationServerMetadata(_req: Request, deps: ControlOAuthDeps = {}): Response {
+  const live = armed(deps);
+  if (live === null) return NOT_FOUND();
+  const issuer = live.issuer;
+  return json(200, {
+    issuer,
+    authorization_endpoint: new URL(CONTROL_OAUTH_AUTHORIZE_PATH, issuer).toString(),
+    token_endpoint: new URL(CONTROL_OAUTH_TOKEN_PATH, issuer).toString(),
+    response_types_supported: ["code"],
+    grant_types_supported: ["authorization_code", "client_credentials"],
+    code_challenge_methods_supported: ["S256"],
+    token_endpoint_auth_methods_supported: ["client_secret_basic", "client_secret_post", "none"],
+    scopes_supported: CONTROL_ADVERTISED_SCOPES,
+    // RFC 8707 — the resource indicator a client may pass at the token endpoint.
+    resource_indicators_supported: true,
+    // RFC 9207 — the authorization response carries `iss`, so a client registered against two
+    // authorization servers behind one redirect URI can tell which of them answered (the mix-up
+    // attack). Advertised because handleAuthorize really sets it.
+    authorization_response_iss_parameter_supported: true,
+    // RFC 8414 defines this as HUMAN-readable developer documentation. It is deliberately NOT the
+    // MCP endpoint: that URL is the protected resource, and following it gets a 401 JSON body.
+    service_documentation: "https://github.com/open-everywhere/open-everywhere/blob/main/docs/security/control-plane.md#control-plane-mcp-over-https-oauth-21",
+  });
+}
+
+/** `GET /.well-known/oauth-protected-resource/control/v1/mcp` — RFC 9728, built in oauth-resource.ts. */
+export function handleProtectedResourceMetadata(_req: Request, deps: ControlOAuthDeps = {}): Response {
+  const doc = controlProtectedResourceMetadata(deps.env ?? process.env, deps.issuer ?? CONTROL_OAUTH_ISSUER);
+  if (doc === null) return NOT_FOUND();
+  return json(200, doc, { "access-control-allow-origin": "*" });
+}
+
+/**
+ * Adapt a WHATWG `Request` to the `IncomingMessage` shape auth.ts's authenticator reads.
+ *
+ * 🔴 THIS SHIM PASSES EXACTLY ONE FIELD, AND THAT IS THE WHOLE CONTRACT IT RELIES ON: `auth.ts`'s
+ * `bearer()` reads `req.headers["authorization"]` and nothing else, and none of the three shipped
+ * verifiers (`genericOidcVerifier`, `githubOAuthVerifier`, `staticTokenVerifier`) touches its `req`
+ * argument at all. A verifier added later that reads the socket, a cookie or another header would
+ * see `undefined` here rather than a wrong value — so it fails CLOSED, which is why the shim is
+ * safe to keep narrow instead of faking a whole request.
+ */
+function asIncomingMessage(req: Request): IncomingMessage {
+  const authorization = req.headers.get("authorization") ?? undefined;
+  return { headers: { authorization } } as unknown as IncomingMessage;
+}
+
+async function resolveAdminIdentity(req: Request, deps: ControlOAuthDeps): Promise<AdminIdentity | null> {
+  if (deps.adminIdentity) return deps.adminIdentity(req);
+  // `adminAuthenticatorFromEnv` THROWS on a malformed OE_ADMIN_ROLE_RULES. A misconfigured identity
+  // door must refuse the authorize call, not answer 500 — a distinct status class on a public
+  // endpoint tells a caller something about the deployment that a refusal does not.
+  let authenticate: ((req: IncomingMessage) => Promise<AdminIdentity | null>) | null = null;
+  try {
+    authenticate = adminAuthenticatorFromEnv();
+  } catch {
+    return null;
+  }
+  if (!authenticate) return null; // no identity door configured → nobody can authorize
+  return authenticate(asIncomingMessage(req)).catch(() => null);
+}
+
+/**
+ * The scopes an authenticated person may receive — derived from the roles their EXISTING role rules
+ * already grant (auth.ts `resolveRoles`), never from a second permission table. `control:write` is
+ * withheld from a `readOnly` principal, which is the same flag server.ts uses to strip every write
+ * tool, so the token cannot out-reach the credential that authorized it.
+ */
+export function scopesAllowedForIdentity(identity: AdminIdentity): string[] {
+  const allowed: string[] = [];
+  if (identity.readOnly !== true) allowed.push(SCOPE_CONTROL_WRITE);
+  for (const role of identity.roles) {
+    if (role === "admin") allowed.push(SCOPE_CONTROL_ADMIN);
+    else if (role.startsWith("domain:")) allowed.push(`${SCOPE_CONTROL_DOMAIN_PREFIX}${role.slice("domain:".length)}`);
+  }
+  return allowed;
+}
+
+/**
+ * `GET /control/v1/oauth/authorize` — the person leg. On success, a 302 to the client's registered
+ * redirect URI carrying `code` and the caller's `state`.
+ *
+ * The parameter checks run in the RFC 6749 §4.1.2.1 order: `client_id` and `redirect_uri` are
+ * validated FIRST and a failure on either answers DIRECTLY (never a redirect, or the endpoint would
+ * be an open redirector); every later failure redirects the error back to the now-trusted URI.
+ */
+export async function handleAuthorize(req: Request, deps: ControlOAuthDeps = {}): Promise<Response> {
+  const live = armed(deps);
+  if (live === null) return NOT_FOUND();
+  const { secret, issuer } = live;
+
+  const url = new URL(req.url);
+  const q = (name: string): string => (url.searchParams.get(name) ?? "").trim();
+
+  const client = findControlOAuthClient(q("client_id"), deps.clients ?? CONTROL_OAUTH_CLIENTS);
+  if (!client || client.grant !== "authorization_code") {
+    return oauthError(400, "invalid_client", "unknown client_id, or the client is not registered for the authorization_code grant");
+  }
+  const redirectUri = q("redirect_uri");
+  if (!client.redirectUris.includes(redirectUri)) {
+    return oauthError(400, "invalid_request", "redirect_uri does not exactly match a registered redirect URI for this client");
+  }
+  const state = q("state");
+  const fail = (code: string, description: string): Response => redirectError(redirectUri, code, description, state);
+
+  if (q("response_type") !== "code") return fail("unsupported_response_type", "only response_type=code is supported");
+  // OAuth 2.1 removes `plain`, so S256 is required and its absence is not a fallback.
+  if (q("code_challenge_method") !== "S256") return fail("invalid_request", "code_challenge_method must be S256");
+  const codeChallenge = q("code_challenge");
+  if (codeChallenge.length < 43) return fail("invalid_request", "code_challenge is missing or too short for S256");
+  const audience = resolveAudience(url.searchParams.get("resource"), controlOAuthAudiences(controlMcpResource(issuer), issuer));
+  if (audience === null) return fail("invalid_target", "the requested resource is not served by this deployment");
+
+  const identity = await resolveAdminIdentity(req, deps);
+  if (!identity) {
+    // 401, not a redirect: nothing has authenticated, so there is no user to send an error back to.
+    return oauthError(401, "access_denied", "authorize requires a credential this deployment's admin door accepts", {
+      "www-authenticate": 'Bearer realm="open-everywhere-control"',
+    });
+  }
+
+  // 🔴 THE CREDENTIAL FAMILIES STAY DISJOINT, AND THIS IS WHERE THAT IS ENFORCED.
+  // `adminAuthenticatorFromEnv` composes the OE_CONTROL_READ_TOKENS service-token authenticator
+  // (auth.ts), and `verifyServiceToken` mints roles ["admin"] with `readOnly: true`. Without this
+  // gate a READ service token could walk the PKCE flow and come back holding a control-plane access
+  // token — a read credential upgraded into a control-plane one, which is exactly the fallback
+  // OPE-136 removed and which both docs promise does not exist. A machine that should reach this
+  // plane gets its own registered `client_credentials` client, not a borrowed read token.
+  if (identity.issuer === SERVICE_TOKEN_ISSUER) {
+    await audit("control.oauth_refused", identity.subject, { grant: "authorization_code", reason: "service_token_family_refused" });
+    return oauthError(403, "access_denied", "a service token cannot authorize a control-plane client — register a client_credentials client instead");
+  }
+
+  const allowed = scopesAllowedForIdentity(identity);
+  const requested = parseScopeString(url.searchParams.get("scope"));
+  const asked = requested.length > 0 ? requested : client.scopes.filter((s) => allowed.includes(s));
+  const subject = `${identity.issuer}#${identity.subject}`;
+  if (asked.length === 0 || !asked.every((s) => allowed.includes(s) && client.scopes.includes(s))) {
+    // The principal is known and registered by this point, so the refusal owes a row — an operator
+    // reviewing `control.oauth_refused` must see a valid credential probing for scopes it cannot have.
+    await audit("control.oauth_refused", subject, { grant: "authorization_code", reason: "invalid_scope", client: client.clientId });
+    return fail("invalid_scope", "the requested scope exceeds this client's registration or this identity's roles");
+  }
+
+  const code = await mintAuthorizationCode(
+    { clientId: client.clientId, subject, scopes: asked, audience, redirectUri, codeChallenge },
+    { issuer, secret, ...(deps.now ? { now: deps.now } : {}) },
+  );
+  await audit("control.oauth_code_issued", subject, { client: client.clientId, scope: asked.join(" ") });
+
+  const location = new URL(redirectUri);
+  location.searchParams.set("code", code);
+  if (state) location.searchParams.set("state", state);
+  // RFC 9207: name the authorization server that answered. A client registered against two servers
+  // behind one redirect URI cannot otherwise tell them apart, which is the mix-up attack.
+  location.searchParams.set("iss", issuer);
+  return new Response(null, { status: 302, headers: { location: location.toString(), "cache-control": "no-store" } });
+}
+
+function redirectError(redirectUri: string, code: string, description: string, state: string): Response {
+  const location = new URL(redirectUri);
+  location.searchParams.set("error", code);
+  location.searchParams.set("error_description", description);
+  if (state) location.searchParams.set("state", state);
+  return new Response(null, { status: 302, headers: { location: location.toString(), "cache-control": "no-store" } });
+}
+
+/**
+ * `POST /control/v1/oauth/token` — both grants. Always `cache-control: no-store` (RFC 6749 §5.1),
+ * and a refusal never distinguishes "unknown client" from "wrong secret".
+ */
+export async function handleToken(req: Request, deps: ControlOAuthDeps = {}): Promise<Response> {
+  const live = armed(deps);
+  if (live === null) return NOT_FOUND();
+  const { secret } = live;
+
+  let form: URLSearchParams;
+  try {
+    form = new URLSearchParams(await req.text());
+  } catch {
+    return oauthError(400, "invalid_request", "expected an application/x-www-form-urlencoded body");
+  }
+  const f = (name: string): string => (form.get(name) ?? "").trim();
+
+  const grantType = f("grant_type");
+  if (grantType === "client_credentials") return tokenByClientCredentials(req, form, secret, deps);
+  if (grantType === "authorization_code") return tokenByAuthorizationCode(form, secret, deps);
+  return oauthError(400, "unsupported_grant_type", `grant_type must be client_credentials or authorization_code (got "${grantType || "none"}")`);
+}
+
+/** `client_secret_basic` first (RFC 6749 §2.3.1 prefers it), then `client_secret_post`. */
+function clientCredentialsFromRequest(req: Request, form: URLSearchParams): { clientId: string; clientSecret: string } {
+  const header = req.headers.get("authorization") ?? "";
+  const basic = /^Basic\s+(.+)$/i.exec(header.trim());
+  if (basic) {
+    // 🔴 `decodeURIComponent` THROWS on a malformed percent-escape ("%"), and an unhandled throw
+    // here answers 500. That would hand an unauthenticated caller a response class the refusals
+    // deliberately do not have — a 500 says "your encoding was bad" where every real credential
+    // failure says only `invalid_client`. A malformed credential is a bad credential.
+    try {
+      const decoded = Buffer.from(basic[1], "base64").toString("utf-8");
+      const at = decoded.indexOf(":");
+      if (at > 0) {
+        return { clientId: decodeURIComponent(decoded.slice(0, at)), clientSecret: decodeURIComponent(decoded.slice(at + 1)) };
+      }
+    } catch {
+      return { clientId: "", clientSecret: "" }; // an empty id matches no registration, so the caller refuses
+    }
+  }
+  return { clientId: (form.get("client_id") ?? "").trim(), clientSecret: form.get("client_secret") ?? "" };
+}
+
+async function tokenByClientCredentials(req: Request, form: URLSearchParams, secret: string, deps: ControlOAuthDeps): Promise<Response> {
+  const { clientId, clientSecret } = clientCredentialsFromRequest(req, form);
+  const client = findControlOAuthClient(clientId, deps.clients ?? CONTROL_OAUTH_CLIENTS);
+  const authenticated = client !== null && client.grant === "client_credentials" && clientSecretMatches(clientSecret, client);
+  if (!authenticated || client === null) {
+    // 🔴 A ROW IS WRITTEN ONLY FOR A CLIENT THIS DEPLOYMENT REGISTERED. `clientId` here is
+    // unauthenticated caller-supplied text of unbounded length, and `appendAudit` takes the
+    // per-org lock and appends to the hash-chained log — so auditing an UNKNOWN id would let
+    // anyone write attacker-named rows into that chain in a loop, and serialise against every
+    // legitimate audit write. Every other control door in this repo refuses BEFORE it audits
+    // (control/read-route.ts); this one now does too. A wrong secret from a REGISTERED client is
+    // still worth a row: that is a real principal failing a real check.
+    if (client !== null) await audit("control.oauth_refused", `oauth-client:${client.clientId}`, { grant: "client_credentials", reason: "invalid_client" });
+    return oauthError(401, "invalid_client", "client authentication failed", { "www-authenticate": 'Basic realm="open-everywhere-control"' });
+  }
+  return issueAccessToken(client, parseScopeString(form.get("scope")), form.get("resource"), `oauth-client:${client.clientId}`, secret, deps);
+}
+
+async function tokenByAuthorizationCode(form: URLSearchParams, secret: string, deps: ControlOAuthDeps): Promise<Response> {
+  const f = (name: string): string => (form.get(name) ?? "").trim();
+  const client = findControlOAuthClient(f("client_id"), deps.clients ?? CONTROL_OAUTH_CLIENTS);
+  if (!client || client.grant !== "authorization_code") {
+    return oauthError(401, "invalid_client", "client authentication failed");
+  }
+  const verified = await verifyAuthorizationCode(f("code"), { issuer: controlOAuthIssuer(deps.issuer ?? CONTROL_OAUTH_ISSUER) ?? "", secret });
+  // Every mismatch below is one `invalid_grant`: a caller learns the code is unusable, never why.
+  const bound =
+    verified !== null &&
+    verified.clientId === client.clientId &&
+    verified.redirectUri === f("redirect_uri") &&
+    pkceVerifierMatches(f("code_verifier"), verified.codeChallenge);
+  if (!verified || !bound) {
+    await audit("control.oauth_refused", `oauth-client:${client.clientId}`, { grant: "authorization_code", reason: "invalid_grant" });
+    return oauthError(400, "invalid_grant", "the authorization code is invalid, expired, or does not match this request");
+  }
+  // Single use, claimed atomically and LAST — so a request that would fail anyway never burns a code.
+  const spent = await redeemAuthorizationCode(verified, deploymentOrg(), {
+    ...(deps.markCodeSpent ? { markSpent: deps.markCodeSpent } : {}),
+    ...(deps.now ? { now: deps.now } : {}),
+  });
+  if (!spent) {
+    await audit("control.oauth_refused", verified.subject, { grant: "authorization_code", reason: "code_replayed_or_store_unavailable" });
+    return oauthError(400, "invalid_grant", "the authorization code is invalid, expired, or does not match this request");
+  }
+  return issueAccessToken(client, verified.scopes, verified.audience, verified.subject, secret, deps);
+}
+
+async function issueAccessToken(
+  client: ControlOAuthClient,
+  requested: readonly string[],
+  resource: string | null,
+  subject: string,
+  secret: string,
+  deps: ControlOAuthDeps,
+): Promise<Response> {
+  const scopes = grantedScopes(requested, client);
+  if (scopes === null) {
+    await audit("control.oauth_refused", subject, { grant: client.grant, reason: "invalid_scope" });
+    return oauthError(400, "invalid_scope", "the requested scope exceeds this client's registration");
+  }
+  const issuer = controlOAuthIssuer(deps.issuer ?? CONTROL_OAUTH_ISSUER) ?? "";
+  const audience = resolveAudience(resource, controlOAuthAudiences(controlMcpResource(issuer), issuer));
+  if (audience === null) {
+    await audit("control.oauth_refused", subject, { grant: client.grant, reason: "invalid_target" });
+    return oauthError(400, "invalid_target", "the requested resource is not served by this deployment");
+  }
+  const token = await mintAccessToken({
+    subject,
+    clientId: client.clientId,
+    scopes,
+    audience,
+    issuer,
+    secret,
+    ...(deps.now ? { now: deps.now } : {}),
+  });
+  await audit("control.oauth_token_issued", subject, { client: client.clientId, grant: client.grant, scope: scopes.join(" "), audience });
+  // No refresh token, by design — see oauth-tokens.ts on why the lifetime IS the revocation window.
+  return json(200, { access_token: token, token_type: "Bearer", expires_in: ACCESS_TOKEN_TTL_SECONDS, scope: scopes.join(" ") });
+}
+
+/** Every issue and every refusal leaves a row naming the principal. Best-effort: appendAudit never throws. */
+async function audit(action: string, principalId: string, detail: Record<string, unknown>): Promise<void> {
+  await appendAudit({ org: deploymentOrg(), platform: "control", workspace: "control", principalId, action, detail });
+}