@open-everywhere/core 0.1.0

package/agent/control/auth.ts

@@ -0,0 +1,663 @@
+// Admin-plane authentication — the pluggable auth layer for the remote control
+// surface (the `authenticate` hook in http.ts). The MCP server is a RESOURCE server:
+// it does not issue tokens or run login flows; it VALIDATES a bearer token an MCP
+// client presents and maps the resulting identity → roles. Authentication is
+// federated (no user table, no passwords) and pluggable by ISSUER, because OIDC is
+// standardised: one generic JWKS verifier covers Google, Auth0, Okta, Entra, WorkOS,
+// "Sign in with Vercel" — they differ only by the issuer URL (config, not code).
+//
+// IDENTITY MODEL (the security-load-bearing decision): the stable identity key is
+// (issuer, subject), NEVER email alone. Email is a CLAIM, not an identity — auto-
+// linking accounts by email is the classic account-takeover vector. We don't create
+// unified accounts; instead role grants are config RULES matched against claims. A
+// rule keyed on a verified email therefore lets the SAME human reach the same access
+// via Google AND GitHub — but only because two guardrails are enforced here, not in
+// config: (1) any email/domain rule requires email_verified === true; (2) only
+// configured (trusted) issuers are accepted. Email-linking is unsafe only with
+// arbitrary untrusted issuers — ours are pinned.
+//
+// ROLE CONVENTION (RBAC, matches access/roles.ts): roles are free-form strings granted by
+// OE_ADMIN_ROLE_RULES / RoleRule — no parser change needed to add a new one, just a
+// convention every consumer honours:
+//   "admin"            — org-admin. Covers every scope in the deployment (roleCoversScope
+//                         short-circuits true) — the existing single mount-level gate.
+//   "domain:<name>"     — scoped to one memory domain (memory/domain.ts Domain.name).
+//                         Covers that domain's own scope AND any surfaceKey whose channel
+//                         resolves to it (domainForChannel) — same resolution access/roles.ts
+//                         uses for the agent-tool side of RBAC.
+// "Anyone-in-the-domain" (Slack channel membership) is NOT expressible here — OIDC identity
+// (email/subject) isn't Slack membership, so that tier only exists on the Slack-native
+// tools, never over this MCP surface.
+
+import { extractBearerToken, withAuthChallenges, type AuthFn } from "eve/channels/auth";
+import { jwtVerify, createRemoteJWKSet, type JWTVerifyGetKey } from "jose";
+import { createHash, timingSafeEqual } from "node:crypto";
+import type { IncomingMessage } from "node:http";
+import { domainForChannel, memoryRefs, type Domain } from "../memory/domain.js";
+import { getConfig } from "../access/config.js";
+import { deploymentOrg } from "../identity/binding.js";
+import { serviceTokenFireAttributes } from "../routines/fire-auth.js";
+
+/** A resolved admin identity — what the http.ts handler gates on. */
+export interface AdminIdentity {
+  /** The issuer that authenticated this principal (the trust anchor). */
+  readonly issuer: string;
+  /** Stable per-issuer subject — the real identity key. */
+  readonly subject: string;
+  readonly email?: string;
+  /** Only ever true when the issuer asserted it; gates email-based role rules. */
+  readonly emailVerified: boolean;
+  /** Roles granted by the rules (e.g. ["admin"] / ["viewer"]). */
+  readonly roles: readonly string[];
+  /**
+   * READ-ONLY principal (service tokens, OE_CONTROL_READ_TOKENS): when true, http.ts
+   * builds this request's control server with the mutating tools UNREGISTERED
+   * (server.ts's `includeWrites && readOnly !== true` gate — the single choke point
+   * every write tool passes through), regardless of the mount's includeWrites. The
+   * roles then govern READ scope only. Absent/false = the pre-existing behaviour.
+   *
+   * The label is now LITERALLY true (OPE-136). It used not to be: the test-wake
+   * INJECTION route authenticated against this same OE_CONTROL_READ_TOKENS family, and
+   * wake injection transitively WRITES — so a "read-only" token could mint a full-kit
+   * task seat. Injection moved to its own {@link INJECT_TOKEN_ENV} family, verified by
+   * {@link verifyInjectToken}, which never produces an AdminIdentity at all.
+   */
+  readonly readOnly?: boolean;
+}
+
+/** The pre-role identity a verifier extracts from a token. */
+export interface RawIdentity {
+  readonly issuer: string;
+  readonly subject: string;
+  readonly email?: string;
+  readonly emailVerified: boolean;
+}
+
+/** A token verifier: validate a bearer token, return a raw identity or null. */
+export type TokenVerifier = (token: string, req: IncomingMessage) => Promise<RawIdentity | null>;
+
+/**
+ * A role-grant rule. `roles` are granted when every present matcher holds. Email /
+ * emailDomain matchers ALSO require emailVerified === true (enforced below) — so an
+ * unverified-email token can never satisfy them. Match on (issuer, subject) for a
+ * single exact identity; on (verified) email/domain to recognise one human across
+ * providers.
+ */
+export interface RoleRule {
+  readonly roles: readonly string[];
+  readonly issuer?: string;
+  readonly subject?: string;
+  readonly email?: string;
+  readonly emailDomain?: string;
+}
+
+/** Roles granted to a raw identity by the rule set (deduped). Default-deny: [] if none match. */
+export function resolveRoles(id: RawIdentity, rules: readonly RoleRule[]): string[] {
+  const granted = new Set<string>();
+  for (const rule of rules) {
+    if (rule.issuer !== undefined && rule.issuer !== id.issuer) continue;
+    if (rule.subject !== undefined && rule.subject !== id.subject) continue;
+    // Email / domain matchers are GATED on verified email — never match an unverified claim.
+    if (rule.email !== undefined) {
+      if (!id.emailVerified || id.email?.toLowerCase() !== rule.email.toLowerCase()) continue;
+    }
+    if (rule.emailDomain !== undefined) {
+      const domain = id.email?.split("@")[1]?.toLowerCase();
+      if (!id.emailVerified || domain !== rule.emailDomain.toLowerCase()) continue;
+    }
+    // A rule with NO matchers is rejected (would grant to everyone) — must constrain something.
+    if (rule.issuer === undefined && rule.subject === undefined && rule.email === undefined && rule.emailDomain === undefined) {
+      continue;
+    }
+    for (const r of rule.roles) granted.add(r);
+  }
+  return [...granted];
+}
+
+/** A control-plane request's scope, for the domain-role gate. `surfaceKey`/`domain` are
+ *  the SAME two ways a scope can be named as elsewhere (roles.ts): a fully-qualified
+ *  channel key, or the domain name directly. `org` names the partition the answer comes
+ *  from — see docs/security/control-plane.md for the org partitioning story.
+ *
+ *  🔴 CARRYING AN `org` IS NOT THE SAME AS CHECKING IT. {@link scopeDenial} and
+ *  {@link siloScopeDenial} refuse a foreign org ({@link foreignOrgDenial}) before they ask the
+ *  role question. {@link roleCoversScope} does NOT: it is a pure role predicate and never reads
+ *  `scope.org`, so a caller that uses it directly — a row-filtering view, as `pendingActionsView`
+ *  does — must call {@link foreignOrgDenial} itself, the way `control/server.ts` does for
+ *  `memory_list` and `pending_actions_list`. A view that copies the shape and skips that gate
+ *  filters another tenant's rows by role and answers with them. */
+export interface ScopeRequest {
+  readonly org: string;
+  readonly surfaceKey?: string;
+  readonly domain?: string;
+}
+
+/**
+ * Does this identity's roles cover the requested scope? "admin" covers everything.
+ * "domain:<name>" covers that domain by name, or by surfaceKey resolving to it
+ * (domainForChannel — the same channel→domain hop access/roles.ts uses). FAIL-CLOSED: an
+ * unscoped request (no surfaceKey/domain — an org-wide ask) is covered ONLY by "admin";
+ * an unresolvable surfaceKey (no matching domain) is covered by nothing. Pure — domains
+ * passed explicitly so this is matrix-testable without a registered AppConfig.
+ */
+export function roleCoversScope(roles: readonly string[], scope: ScopeRequest, domains: readonly Domain[]): boolean {
+  if (roles.includes("admin")) return true;
+  const domainRoles = new Set(roles.filter((r) => r.startsWith("domain:")).map((r) => r.slice("domain:".length)));
+  if (domainRoles.size === 0) return false;
+  // scope.surfaceKey here is an EXPLICIT admin/MCP-supplied key, never a live turn's
+  // partition — so no thread→parent grain mapping applies (item 22 resolves that at
+  // ingress). A caller passing a Discord THREAD key resolves no domain and fails
+  // closed to admin-only, which is the correct posture for an ambiguous ask.
+  const resolved = scope.domain ?? (scope.surfaceKey ? domainForChannel(scope.surfaceKey, domains)?.name : undefined);
+  return resolved !== undefined && domainRoles.has(resolved);
+}
+
+/**
+ * Call-site convenience for control-plane tool handlers: like roleCoversScope, but pulls
+ * domains from the registered AppConfig LAZILY — only when a non-"admin" role actually
+ * needs domain resolution — so an admin caller (the common case, and every existing test)
+ * never requires getConfig() to be registered. Returns a denial message (drop straight into
+ * the tool's error result) or null when the scope is covered.
+ */
+export function scopeDenial(roles: readonly string[], scope: ScopeRequest): string | null {
+  const foreign = foreignOrgDenial(scope.org);
+  if (foreign) return foreign;
+  if (roles.includes("admin")) return null;
+  if (roleCoversScope(roles, scope, getConfig().loadDomains())) return null;
+  const label = scope.surfaceKey ?? scope.domain ?? `org "${scope.org}" (org-wide)`;
+  return `forbidden: no role covers ${label} (have: ${roles.length ? roles.join(", ") : "none"}; need "admin" or a covering "domain:<name>").`;
+}
+
+/**
+ * Refuse a control-plane ask whose `org` is not this deployment's, naming both. Null when
+ * the ask names this deployment's org.
+ *
+ * 🔴 THE ORG CHECK RUNS BEFORE THE ROLE CHECK, AND THAT ORDER IS THE WHOLE CONTROL (OPE-1438).
+ * `scopeDenial` used to short-circuit `null` on the "admin" role and never read
+ * `ScopeRequest.org` at all, so every gated read took its partition key from the CALLER: an
+ * admin-scoped principal — an org admin, or any read-only service token, which
+ * {@link verifyServiceToken} mints with roles ["admin"] — passed `org: "other-tenant"` to
+ * `routines_list` and was answered from that tenant's rows, routine PROMPTS included. The same
+ * hole stood behind `usage_window`, `usage_summary`, `overrides_list` and
+ * `unified_domain_audit`. A role model that scopes by DOMAIN cannot express "this org and no
+ * other", so the org is not a role question: it is a property of the deployment, read here from
+ * `deploymentOrg()` exactly as `audit_query` and the HTTP read route read it (OPE-1129).
+ *
+ * The deployment is SINGLE-ORG today, so this refuses nothing a real operator sends. A
+ * deployment that grows a second org builds a real multi-org role model; this refusal is what
+ * makes that a visible task rather than a quiet cross-tenant read.
+ */
+export function foreignOrgDenial(org: string): string | null {
+  const mine = deploymentOrg();
+  if (org === mine) return null;
+  return `forbidden: org "${org}" is not this deployment's org ("${mine}"). The control plane answers about one org — no role covers another.`;
+}
+
+/**
+ * The EXPLICIT domain names that reference a memory silo (memory/domain.ts Domain.memory)
+ * — the memory-admin MCP's (control/views.ts memory_list/memory_read) scope-covering set
+ * for that silo. Deliberately excludes CRITERIA pseudo-domains (`org`/`public`/`dm` — the
+ * ones declared with `match`): the conventional org-wide brain (silo name "org-brain",
+ * referenced by the `org` pseudo-domain) and anything referenced only by `public`/`dm`
+ * stay admin-only even if a caller somehow holds "domain:org" — there is no legitimate
+ * way to grant that via OE_ADMIN_ROLE_RULES, but the exclusion is explicit rather than
+ * accidental (docs/control-plane.md "memory-admin"). A silo referenced by no domain at
+ * all (config drift, or a silo not yet wired to a domain) is likewise admin-only —
+ * nothing to attribute a covering domain role to.
+ */
+export function siloCoveringDomains(siloName: string, domains: readonly Domain[]): string[] {
+  // `match === undefined` IS "is an explicit domain" (see access/roles.ts adminControlRoles for
+  // the same swap): since OPE-205 a domain's reach may be a whole tenant with no exact entry at
+  // all, and a container-only domain must still cover its own silo.
+  return domains.filter((d) => d.match === undefined && memoryRefs(d).includes(siloName)).map((d) => d.name);
+}
+
+/**
+ * Is a memory SILO covered by this identity's roles? Like roleCoversScope, but a silo
+ * can be referenced by SEVERAL explicit domains at once (a shared brain) — covered by
+ * "admin", or by a "domain:<name>" role matching ANY of {@link siloCoveringDomains}.
+ */
+export function siloScopeDenial(roles: readonly string[], org: string, siloName: string, domains: readonly Domain[]): string | null {
+  // Same order, same reason as scopeDenial: the org gate runs BEFORE the role gate, or "admin"
+  // short-circuits past it (OPE-1438). `org` here is a memory PARTITION key
+  // (control/views.ts controlPartition), so an unchecked one reads another tenant's silo files.
+  const foreign = foreignOrgDenial(org);
+  if (foreign) return foreign;
+  if (roles.includes("admin")) return null;
+  const covering = siloCoveringDomains(siloName, domains);
+  const domainRoles = new Set(roles.filter((r) => r.startsWith("domain:")).map((r) => r.slice("domain:".length)));
+  if (covering.some((d) => domainRoles.has(d))) return null;
+  return `forbidden: no role covers memory silo "${siloName}" in org "${org}" (have: ${roles.length ? roles.join(", ") : "none"}; need "admin" or a covering "domain:<name>").`;
+}
+
+function bearer(req: IncomingMessage): string | null {
+  const h = req.headers["authorization"];
+  if (typeof h !== "string") return null;
+  const m = /^Bearer\s+(.+)$/i.exec(h.trim());
+  return m ? m[1] : null;
+}
+
+/**
+ * Generic OIDC verifier — covers any standards-compliant OIDC issuer (Google, Auth0,
+ * Okta, Entra, WorkOS, …). Verifies the JWT's signature against the issuer's JWKS and
+ * checks iss + aud. Pass `jwks` to inject a key set (tests / non-discoverable issuers);
+ * otherwise the issuer's published JWKS is used (discovered from jwks_uri, or the
+ * conventional {issuer}/.well-known/jwks.json).
+ */
+export function genericOidcVerifier(opts: {
+  issuer: string;
+  audience: string;
+  jwks?: JWTVerifyGetKey;
+  jwksUri?: string;
+}): TokenVerifier {
+  const keySet =
+    opts.jwks ??
+    createRemoteJWKSet(new URL(opts.jwksUri ?? `${opts.issuer.replace(/\/$/, "")}/.well-known/jwks.json`));
+  return async (token) => {
+    try {
+      const { payload } = await jwtVerify(token, keySet, { issuer: opts.issuer, audience: opts.audience });
+      if (!payload.sub) return null;
+      return {
+        issuer: opts.issuer,
+        subject: payload.sub,
+        email: typeof payload.email === "string" ? payload.email : undefined,
+        emailVerified: payload.email_verified === true,
+      };
+    } catch {
+      return null; // bad signature / expired / wrong iss|aud → not this verifier's principal
+    }
+  };
+}
+
+/**
+ * GitHub user-login verifier. GitHub is NOT a true OIDC IdP for user identity (OAuth2
+ * + REST, no ID token), so we validate the access token by calling the user API and
+ * read the verified primary email. `fetchUser` is injectable for tests.
+ */
+export function githubOAuthVerifier(opts?: {
+  fetchUser?: (token: string) => Promise<{ id: number | string; login: string; email?: string; emailVerified?: boolean } | null>;
+}): TokenVerifier {
+  const fetchUser =
+    opts?.fetchUser ??
+    (async (token: string) => {
+      const headers = { authorization: `Bearer ${token}`, accept: "application/vnd.github+json", "user-agent": "open-everywhere" };
+      const u = await fetch("https://api.github.com/user", { headers });
+      if (!u.ok) return null;
+      const user = (await u.json()) as { id: number; login: string };
+      // Primary verified email lives on a separate endpoint.
+      let email: string | undefined;
+      let emailVerified = false;
+      const e = await fetch("https://api.github.com/user/emails", { headers });
+      if (e.ok) {
+        const emails = (await e.json()) as { email: string; primary: boolean; verified: boolean }[];
+        const primary = emails.find((x) => x.primary) ?? emails.find((x) => x.verified);
+        if (primary) {
+          email = primary.email;
+          emailVerified = primary.verified;
+        }
+      }
+      return { id: user.id, login: user.login, email, emailVerified };
+    });
+  return async (token) => {
+    const user = await fetchUser(token).catch(() => null);
+    if (!user) return null;
+    return {
+      issuer: "https://github.com",
+      subject: `github:${user.id}`,
+      email: user.email,
+      emailVerified: user.emailVerified === true,
+    };
+  };
+}
+
+/**
+ * Static shared-token verifier — for trivial self-host (one operator, one secret).
+ * No federation; the token IS the credential. Grants a fixed identity (default-admin)
+ * so a single-operator deploy needs no IdP.
+ */
+export function staticTokenVerifier(opts: { token: string; subject?: string }): TokenVerifier {
+  return async (token) => {
+    if (!opts.token || token !== opts.token) return null;
+    return { issuer: "static", subject: opts.subject ?? "local-admin", emailVerified: false };
+  };
+}
+
+// --- service tokens: TWO DISJOINT FAMILIES, same wire shape, different power ---------
+//
+// Both families are "name:sha256hex" comma-separated lists parsed by
+// {@link parseServiceTokenEntries}: the env holds only sha256 HASHES, so the deployed env
+// never contains a usable credential; the token value lives only wherever the operator
+// minted it. Verification hashes the presented bearer and compares digests with
+// timingSafeEqual (both sides are fixed 32-byte digests). Token values are NEVER logged —
+// parse warnings deliberately omit the entry content, because a malformed entry is exactly
+// where an accidentally-pasted raw token would sit.
+//
+// What differs is the POWER each family carries, and they are deliberately NOT
+// interchangeable — no fallback in either direction (OPE-136):
+//
+//   OE_CONTROL_READ_TOKENS   ({@link verifyServiceToken} → an AdminIdentity with
+//     `readOnly: true`) — a HARNESS/CI credential for READ views only: the MCP mount
+//     (makeServiceTokenAuthenticator), the deployment-mounted read routes
+//     (control/read-route.ts). No write tool is ever registered for it (server.ts's
+//     `includeWrites && readOnly !== true` choke point). This is the family handed to the
+//     deploy health-probe in the standard checklist, so "read-only" has to be literally
+//     true of it.
+//
+//   OE_CONTROL_INJECT_TOKENS ({@link verifyInjectToken} → a bare {@link InjectIdentity},
+//     NOT an AdminIdentity) — the WAKE-INJECTION credential for the spoofed-ingest seam
+//     (control/test-route.ts, `POST /control/v1/test/wake`). Injection is a WRITE and a
+//     spoofing vector: the caller names the surface, supplies authAttributes that override
+//     the host-derived ones, and can select a TASK-grain seat (full kit, no narrowing row).
+//     That is categorically not a read power, which is why it does not ride the read family.
+//
+// WHY DISJOINT AND NOT ADDITIVE. Accepting the read family at the injection route "for
+// compatibility" would preserve the exact defect this split exists to remove — the read
+// token would still be a wake-injection credential, and the READ-ONLY label would still be
+// false. So test-route.ts verifies against the inject family INSTEAD OF, never in addition
+// to. Each family is independently fail-closed: unset/blank ⇒ [] ⇒ its routes 404.
+//
+// Nothing composes the inject family into the admin authenticator
+// ({@link adminAuthenticatorFromEnv} parses only OE_CONTROL_READ_TOKENS), so an inject
+// token cannot read the control plane either. The split cuts both ways on purpose.
+
+export const SERVICE_TOKEN_ISSUER = "service-token";
+
+/** The env var holding the READ-family entries (read views; never injection). */
+const READ_TOKEN_ENV = "OE_CONTROL_READ_TOKENS";
+/** The env var holding the WAKE-INJECTION family entries (test-route.ts only). */
+export const INJECT_TOKEN_ENV = "OE_CONTROL_INJECT_TOKENS";
+
+export interface ServiceTokenEntry {
+  /** Lowercase machine name ("e2e-harness") — becomes principal `svc:<name>`. */
+  readonly name: string;
+  /** Lowercase sha256 hex of the token VALUE (64 chars). */
+  readonly sha256: string;
+}
+
+const SERVICE_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/**
+ * Parse a service-token env ("name:sha256hex,name2:sha256hex") — the SHARED wire shape of
+ * both families (READ and INJECT), so `envName` exists only to name the offending variable
+ * in a warning. FAIL-CLOSED: unset/blank → [] (that family is fully off); a malformed entry
+ * is DROPPED (it can never authenticate anything), warned by POSITION ONLY — never echoing
+ * the entry, which could be a mis-pasted raw token. Rules: name must be lowercase [a-z0-9_-]
+ * starting alphanumeric (it becomes an audit principal — one canonical casing, no spoofing a
+ * twin by case); hash must be 64 hex chars (uppercase tolerated, normalised down).
+ */
+export function parseServiceTokenEntries(raw: string | undefined, envName: string = READ_TOKEN_ENV): ServiceTokenEntry[] {
+  if (!raw || raw.trim().length === 0) return [];
+  const out: ServiceTokenEntry[] = [];
+  raw.split(",").forEach((part, i) => {
+    const entry = part.trim();
+    if (!entry) return;
+    const at = entry.indexOf(":");
+    const name = at > 0 ? entry.slice(0, at) : "";
+    const hash = at > 0 ? entry.slice(at + 1).toLowerCase() : "";
+    if (!SERVICE_NAME.test(name) || !SHA256_HEX.test(hash)) {
+      console.warn(
+        `[open-everywhere:control] ${envName} entry #${i + 1} ignored — expected "name:sha256hex" (lowercase name, 64-hex-char sha256 of the token). Entry content not shown.`,
+      );
+      return;
+    }
+    out.push({ name, sha256: hash });
+  });
+  return out;
+}
+
+/** The configured WAKE-INJECTION entries ({@link INJECT_TOKEN_ENV}). Fail-closed: unset ⇒ []
+ *  ⇒ `POST /control/v1/test/wake` 404s. Read at call time, never cached, so a test (and the
+ *  route's own gate) sees the live env exactly like the read family's parse does. */
+export function injectTokenEntries(env: NodeJS.ProcessEnv = process.env): ServiceTokenEntry[] {
+  return parseServiceTokenEntries(env[INJECT_TOKEN_ENV], INJECT_TOKEN_ENV);
+}
+
+/**
+ * The ONE constant-time credential compare both families share: sha256 the presented
+ * bearer, `timingSafeEqual` against each configured digest, return the matched entry (or
+ * null). Factored out so the two verifiers below cannot drift into two different compares —
+ * what they differ in is the PRINCIPAL each mints, never the cryptography.
+ */
+function matchServiceToken(token: string, entries: readonly ServiceTokenEntry[]): ServiceTokenEntry | null {
+  if (!token || entries.length === 0) return null;
+  const presented = createHash("sha256").update(token, "utf-8").digest();
+  for (const e of entries) {
+    const digest = Buffer.from(e.sha256, "hex");
+    if (digest.length === presented.length && timingSafeEqual(presented, digest)) return e;
+  }
+  return null;
+}
+
+/** A WAKE-INJECTION principal — deliberately NOT an {@link AdminIdentity}. It carries no
+ *  roles and no `readOnly` flag because it is not a control-plane reader at all: its only
+ *  consumer is test-route.ts, which needs a name to stamp on the `control.service_call`
+ *  audit row. Keeping the type separate is what stops an inject token from ever being
+ *  handed to `buildControlServer` (which takes roles + readOnly) by a later refactor. */
+export interface InjectIdentity {
+  /** Audit principal, `svc:<name>` — same naming convention as a read service token. */
+  readonly subject: string;
+}
+
+/**
+ * Verify a presented WAKE-INJECTION token value against {@link injectTokenEntries}. Same
+ * constant-time compare as {@link verifyServiceToken}; the difference is what a match
+ * BUYS. This grants nothing on the control plane — no roles, no read views, no MCP mount —
+ * only the identity test-route.ts audits its injection under. FAIL-CLOSED: no entries
+ * (family unset) or no match ⇒ null ⇒ the route refuses.
+ *
+ * There is deliberately NO cross-check against the READ family here. A read token
+ * presented at the injection route hashes to no inject entry and is refused, which is the
+ * whole point of OPE-136 — see the family comment above for why additive was rejected.
+ */
+export function verifyInjectToken(token: string, entries: readonly ServiceTokenEntry[]): InjectIdentity | null {
+  const e = matchServiceToken(token, entries);
+  return e ? { subject: `svc:${e.name}` } : null;
+}
+
+/**
+ * Verify a presented service-token VALUE against the configured entries: sha256 the
+ * bearer, constant-time-compare against each hash. A match authenticates as the
+ * READ-ONLY service principal `svc:<name>` — `readOnly: true` structurally strips
+ * every write tool from the per-request server (see AdminIdentity.readOnly); roles
+ * are ["admin"] so READ views with an org-wide scope gate (usage_window,
+ * overrides_list, usage_summary unscoped) are reachable, which is the point of a
+ * deployment-level harness credential. Pure and transport-neutral: the node:http MCP
+ * mount (makeServiceTokenAuthenticator) and the WHATWG-Request read route
+ * (control/read-route.ts) both resolve their bearer through this one compare.
+ *
+ * Callers must pass READ-family entries. It is NOT the injection verifier — the
+ * wake-injection seam uses {@link verifyInjectToken} over a disjoint env family, so this
+ * function's "READ-ONLY" contract is now structurally honest (OPE-136).
+ */
+export function verifyServiceToken(token: string, entries: readonly ServiceTokenEntry[]): AdminIdentity | null {
+  const e = matchServiceToken(token, entries);
+  if (!e) return null;
+  return { issuer: SERVICE_TOKEN_ISSUER, subject: `svc:${e.name}`, emailVerified: false, roles: ["admin"], readOnly: true };
+}
+
+/**
+ * Authenticator for service tokens over the node:http MCP transport — extracts the
+ * bearer and delegates to {@link verifyServiceToken}. No match / no bearer → null
+ * (compose with the OIDC authenticator; falls through).
+ */
+export function makeServiceTokenAuthenticator(entries: readonly ServiceTokenEntry[]): (req: IncomingMessage) => Promise<AdminIdentity | null> {
+  return async (req) => {
+    const token = bearer(req);
+    return token ? verifyServiceToken(token, entries) : null;
+  };
+}
+
+/**
+ * Compose verifiers + role rules into the `authenticate` hook http.ts expects. Tries
+ * each verifier until one claims the token, then resolves roles. Returns null when no
+ * verifier matches OR the identity earns no roles (default-deny — an authenticated but
+ * un-granted principal is NOT admitted).
+ */
+export function makeAdminAuthenticator(
+  verifiers: readonly TokenVerifier[],
+  rules: readonly RoleRule[],
+): (req: IncomingMessage) => Promise<AdminIdentity | null> {
+  return async (req) => {
+    const token = bearer(req);
+    if (!token) return null;
+    for (const verify of verifiers) {
+      const raw = await verify(token, req).catch(() => null);
+      if (!raw) continue;
+      const roles = resolveRoles(raw, rules);
+      if (roles.length === 0) return null; // authenticated but un-granted → denied
+      return { ...raw, roles };
+    }
+    return null;
+  };
+}
+
+/**
+ * Build the authenticator from env — the zero-code deploy path. Returns null when
+ * nothing is configured (so the caller stays FAIL-CLOSED rather than open):
+ *   OE_ADMIN_OIDC_ISSUER   + OE_ADMIN_OIDC_AUDIENCE   → generic OIDC (any provider)
+ *   OE_ADMIN_GITHUB=1                                       → GitHub user-login
+ *   OE_ADMIN_STATIC_TOKEN                                   → shared-token self-host
+ *   OE_ADMIN_ROLE_RULES  (JSON RoleRule[])                  → who gets which roles
+ *   OE_CONTROL_READ_TOKENS ("name:sha256hex,…")             → READ-ONLY service tokens
+ * A static token with no rules implies single-operator admin (a default admin rule).
+ * Service tokens are checked FIRST (a cheap constant-time hash compare, no network);
+ * a non-matching bearer falls through to the identity verifiers. OE_CONTROL_READ_TOKENS
+ * unset → the composed authenticator is byte-identical to before the mode existed.
+ *
+ * OE_CONTROL_INJECT_TOKENS is deliberately ABSENT from this list and must stay absent: the
+ * wake-injection family authenticates exactly one route (control/test-route.ts) via
+ * {@link verifyInjectToken}, and composing it here would silently make an injection
+ * credential a control-plane reader — the mirror image of the OPE-136 defect.
+ */
+export function adminAuthenticatorFromEnv(): ((req: IncomingMessage) => Promise<AdminIdentity | null>) | null {
+  const verifiers: TokenVerifier[] = [];
+  const rules: RoleRule[] = [];
+  const serviceTokens = parseServiceTokenEntries(process.env[READ_TOKEN_ENV], READ_TOKEN_ENV);
+
+  const issuer = process.env.OE_ADMIN_OIDC_ISSUER;
+  const audience = process.env.OE_ADMIN_OIDC_AUDIENCE;
+  if (issuer && audience) verifiers.push(genericOidcVerifier({ issuer, audience }));
+
+  if (process.env.OE_ADMIN_GITHUB === "1") verifiers.push(githubOAuthVerifier());
+
+  const staticToken = process.env.OE_ADMIN_STATIC_TOKEN;
+  if (staticToken) {
+    verifiers.push(staticTokenVerifier({ token: staticToken }));
+    rules.push({ roles: ["admin"], issuer: "static" }); // the shared token IS the admin credential
+  }
+
+  if (process.env.OE_ADMIN_ROLE_RULES) {
+    try {
+      const parsed = JSON.parse(process.env.OE_ADMIN_ROLE_RULES) as RoleRule[];
+      if (Array.isArray(parsed)) rules.push(...parsed);
+    } catch {
+      throw new Error("OE_ADMIN_ROLE_RULES is not valid JSON (expected a RoleRule[] array)");
+    }
+  }
+
+  if (verifiers.length === 0 && serviceTokens.length === 0) return null; // nothing configured → caller stays fail-closed
+  const base = verifiers.length > 0 ? makeAdminAuthenticator(verifiers, rules) : null;
+  const service = serviceTokens.length > 0 ? makeServiceTokenAuthenticator(serviceTokens) : null;
+  if (!service) return base; // no service tokens → exactly the pre-existing authenticator
+  return async (req) => (await service(req)) ?? (base ? await base(req) : null);
+}
+
+// --- eve's route-auth walk over OUR credential (OPE-1613) -----------------------------------
+//
+// eve 0.54.3 ships the WALK and the 401 primitives — `routeAuth`, `withAuthChallenges`,
+// `extractBearerToken`, `createUnauthorizedResponse` — and five strategy helpers: `httpBasic`,
+// `jwtHmac`, `jwtEcdsa`, `oidc`, `vercelOidc` (node_modules/eve/dist/src/public/channels/auth.d.ts).
+// NONE of them verifies an OPAQUE SHARED SECRET, and that is what both service-token families are.
+// The env holds only a sha256 DIGEST, so a deployed environment never carries a usable credential;
+// `httpBasic()` takes the plaintext password and `jwtHmac()` takes the signing secret, so adopting
+// either would put a mintable credential back in env AND change the wire shape every existing
+// caller sends. eve names the supported answer for exactly this case — a custom `AuthFn` wrapped in
+// `withAuthChallenges` (node_modules/eve/docs/guides/auth-and-route-protection.md:137-142). So the
+// CREDENTIAL stays ours (one constant-time digest compare, {@link matchServiceToken}) and
+// everything around it — the ordered walk, the `WWW-Authenticate` challenge, the 401 body — is
+// eve's, one implementation instead of eight hand-rolled copies of `/^Bearer\s+(.+)$/i`.
+//
+// ONE COPY OF THAT REGEX SURVIVES ON PURPOSE: {@link bearer} above, which reads a node:http
+// `IncomingMessage` for the MCP mount. eve's `extractBearerToken` takes a header STRING, so it
+// would fit — but the MCP transport is not a route and runs no walk, so moving it would buy a
+// shared helper and no shared behaviour. It is not an oversight.
+//
+// The doors that CANNOT move here are the SIGNED ones: Slack's `v0=` HMAC, GitHub's, and our own
+// `self-dispatch` (channels/self-dispatch.ts) all authenticate a signature over the RAW BODY, not a
+// presented token. An `AuthFn` receives the `Request` before the handler and reading its body there
+// consumes the stream the handler must still hash and parse, so the walk is the wrong seam for them.
+
+/**
+ * eve's verified-caller snapshot. eve does not export the `SessionAuthContext` NAME from any public
+ * subpath (it lives behind `#channel/types.js`), so it is derived structurally from the public
+ * {@link AuthFn} contract. An eve bump that changes the shape therefore reds `typecheck:all` here
+ * rather than at every call site.
+ */
+export type EveSessionAuth = NonNullable<Awaited<ReturnType<AuthFn<Request>>>>;
+
+/** `authenticator` stamped on a caller verified by the READ family. */
+export const SERVICE_TOKEN_AUTHENTICATOR = "oe-service-token";
+/** `authenticator` stamped on a caller verified by the WAKE-INJECTION family. */
+export const INJECT_TOKEN_AUTHENTICATOR = "oe-inject-token";
+
+/**
+ * eve route auth for the READ family ({@link verifyServiceToken}). A match becomes the service
+ * principal `svc:<name>` on `principalId`, the same string the hand-rolled gate audited. The
+ * `oe_token_family` attribute records WHICH family admitted the caller: the two families are
+ * disjoint by design (OPE-136), and a caller snapshot that cannot say which one verified it would
+ * hide the difference the split exists to keep.
+ *
+ * The bag comes from routines/fire-auth.ts {@link serviceTokenFireAttributes}, so it also carries
+ * the UNATTENDED-ORIGIN marker: `svc:<name>` is a non-empty principal, and a presence gate that
+ * read it WITHOUT the marker would answer as if a human were acting (OPE-278). No route hands this
+ * snapshot to a session today — read-route.ts takes `principalId` for its audit row and nothing
+ * else — so the marker is a STANDING property of the door, not a refusal any path exercises today.
+ * `serviceTokenFireAttributes` states that limit in full.
+ */
+export function serviceTokenAuth(entries: readonly ServiceTokenEntry[]): AuthFn<Request> {
+  return withAuthChallenges((req) => {
+    const token = extractBearerToken(req.headers.get("authorization"));
+    const identity = token ? verifyServiceToken(token, entries) : null;
+    if (!identity) return null; // skip → the walk exhausts → eve's 401
+    return {
+      authenticator: SERVICE_TOKEN_AUTHENTICATOR,
+      issuer: SERVICE_TOKEN_ISSUER,
+      principalId: identity.subject,
+      principalType: "service",
+      subject: identity.subject,
+      // 🔴 KEEP THIS KEY BELOW `principalType`, AND THE BUILDER CALL ON THIS ONE LINE.
+      // scripts/principal-gate-lint.ts (RULE 4, access/principal-gate-manifest.ts
+      // findUnattendedDispatchSites) is line-based: from each `principalType: "service"` it scans
+      // FORWARD for the first `attributes:` line and requires a `…FireAttributes(` call ON IT.
+      // An `attributes:` key placed ABOVE `principalType` is not this site's — the scan runs on and
+      // reads the NEXT door's bag 40 lines down, which greens a site on a neighbour's evidence.
+      attributes: serviceTokenFireAttributes("read"),
+    };
+  }, [{ scheme: "Bearer" }]);
+}
+
+/**
+ * eve route auth for the WAKE-INJECTION family ({@link verifyInjectToken}). Deliberately a SEPARATE
+ * factory over a separate entry list: a read token hashes to no inject entry and is refused here,
+ * exactly as the hand-rolled gate refused it. Nothing composes the two into one walk.
+ *
+ * The bag comes from the same builder the READ door uses, with the other family value — so the
+ * UNATTENDED-ORIGIN marker cannot be present on one door and missing on the other.
+ */
+export function injectTokenAuth(entries: readonly ServiceTokenEntry[]): AuthFn<Request> {
+  return withAuthChallenges((req) => {
+    const token = extractBearerToken(req.headers.get("authorization"));
+    const identity = token ? verifyInjectToken(token, entries) : null;
+    if (!identity) return null;
+    return {
+      authenticator: INJECT_TOKEN_AUTHENTICATOR,
+      issuer: SERVICE_TOKEN_ISSUER,
+      principalId: identity.subject,
+      principalType: "service",
+      subject: identity.subject,
+      // 🔴 BELOW `principalType`, BUILDER CALL ON ONE LINE — see the READ door above for why.
+      attributes: serviceTokenFireAttributes("inject"),
+    };
+  }, [{ scheme: "Bearer" }]);
+}