create-ailk 0.29.1 → 0.31.0

package/templates/apps/web/lib/mcp-oauth.ts

@@ -0,0 +1,702 @@
+/**
+ * The AILK half of the site's MCP authorization server (#10357 D5).
+ *
+ * better-auth's `mcp` plugin (configured in `auth.ts`) registers clients and
+ * issues opaque access and refresh tokens. This plugin sits beside it and adds
+ * what the plugin lacks, as hooks and endpoints — the plugin is configured,
+ * never patched:
+ *
+ * - every authorization passes AILK's consent step (`/consent`), where the
+ *   person picks one workspace and approves scopes their role there holds; the
+ *   chosen workspace is bound into the token's `scopes` as one
+ *   `ailk:workspace:<id>` entry (D2, D3);
+ * - `/mcp/token` refuses any code that did not pass that step, rotates refresh
+ *   tokens and ends a line whose used refresh token is replayed (D5);
+ * - RFC 7009 revocation, the person's own per-client revoke, and a
+ *   stored-token self-check (`/mcp/token-info`, decision (a): lookup, never
+ *   JWKS — D1);
+ * - registration refuses unsafe redirect URIs and metadata and normalises the
+ *   self-claimed client name.
+ *
+ * Every refusal is code-shaped: no English string reaches a client. No answer
+ * or log line carries a token, code, verifier or client secret.
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+
+import {
+  lowerRole,
+  MCP_SCOPES,
+  type McpScope,
+  type MembershipRole,
+  grantsForWorkspace,
+  parseGrantedScopes,
+  scopesForRole,
+  WORKSPACE_SCOPE_PREFIX,
+} from "@working-theory/validation";
+import type { BetterAuthPlugin } from "better-auth";
+import {
+  APIError,
+  createAuthEndpoint,
+  createAuthMiddleware,
+  sessionMiddleware,
+} from "better-auth/api";
+import { expireCookie } from "better-auth/cookies";
+import { generateRandomString } from "better-auth/crypto";
+import * as z from "zod";
+
+/** One workspace a person may bind a token to, with their role in its organization. */
+export interface McpMembership {
+  workspaceId: string;
+  workspaceName: string;
+  organizationName: string;
+  role: string;
+}
+
+export interface McpOAuthDeps {
+  /**
+   * The person's workspaces, `listTenancy`'s rule: every workspace of every
+   * organization they hold a membership in, with that membership's role.
+   */
+  readMemberships(userId: string): Promise<McpMembership[]>;
+}
+
+/** The scopes `/mcp/authorize` accepts a request for. */
+const REQUESTABLE_SCOPES: ReadonlySet<string> = new Set([
+  "openid",
+  "profile",
+  "email",
+  "offline_access",
+  ...MCP_SCOPES,
+]);
+
+const CONSENT_COOKIE = "oidc_consent_prompt";
+const LOGIN_COOKIE = "oidc_login_prompt";
+const ROTATED_PREFIX = "mcp-rotated:";
+const NO_STORE_PATHS: ReadonlySet<string> = new Set([
+  "/mcp/token",
+  "/mcp/consent-details",
+  "/mcp/consent",
+  "/mcp/revoke",
+  "/mcp/revoke-client",
+  "/mcp/token-info",
+]);
+
+/** Registration caps (SEC-10357-02, -03). */
+const MAX_REDIRECT_URIS = 5;
+const MAX_URI_LENGTH = 512;
+const MAX_METADATA_BYTES = 2048;
+const MAX_CLIENT_NAME = 60;
+/** An application unused this long after registering is swept (SEC-10357-03). */
+const UNUSED_CLIENT_TTL_MS = 24 * 60 * 60 * 1000;
+/** Rows one sweep may look at, so a register never pays for a backlog at once. */
+const SWEEP_BATCH = 100;
+/**
+ * Where the last sweep stopped: the `createdAt` it reached, so applications
+ * that stay (used ones) never pin every later sweep to the same batch.
+ */
+const SWEEP_CURSOR = "mcp-sweep-cursor";
+/**
+ * An authorization code's shape — the plugin's and the consent step's
+ * `generateRandomString(32, …)`. The plugin consumes whatever verification row
+ * a `code` names, on every grant type, so anything else is refused first: a
+ * tombstone or the sweep cursor has a name a caller can compute.
+ */
+const CODE_SHAPE = /^[A-Za-z0-9]{32}$/;
+/** `/mcp/token` body fields, each a string when present. */
+const TOKEN_FIELDS = [
+  "grant_type",
+  "code",
+  "code_verifier",
+  "redirect_uri",
+  "refresh_token",
+  "client_id",
+  "client_secret",
+] as const;
+
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+const PRIVATE_SCHEME = /^[a-z][a-z0-9+.-]*$/;
+const REFUSED_SCHEMES = new Set([
+  "http",
+  "https",
+  "file",
+  "javascript",
+  "data",
+  "vbscript",
+  "blob",
+  "about",
+  "ws",
+  "wss",
+  "ftp",
+  "intent",
+]);
+
+/** Control, zero-width and bidi-override characters (SEC-10357-11). */
+const UNSAFE_NAME_CHARS =
+  /[\p{Cc}\u200B-\u200F\u2028-\u202E\u2060-\u206F\uFEFF\u061C]/gu;
+
+function refuse(
+  status: "BAD_REQUEST" | "UNAUTHORIZED" | "NOT_FOUND",
+  error: string,
+  headers?: Record<string, string>,
+): APIError {
+  return new APIError(status, { error, message: error }, { "Cache-Control": "no-store", ...headers });
+}
+
+/** A redirect URI a self-registered client may name (D5). */
+export function isAllowedRedirectUri(value: unknown): boolean {
+  if (typeof value !== "string" || value.length > MAX_URI_LENGTH || value.includes(",")) return false;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol === "https:") return true;
+  if (url.protocol === "http:") return LOOPBACK_HOSTS.has(url.hostname);
+  const scheme = url.protocol.slice(0, -1);
+  return PRIVATE_SCHEME.test(scheme) && !REFUSED_SCHEMES.has(scheme);
+}
+
+/** The client's self-claimed name, made safe to show (SEC-10357-11). */
+export function normaliseClientName(value: unknown): string {
+  const raw = typeof value === "string" ? value : "";
+  const name = raw.normalize("NFKC").replace(UNSAFE_NAME_CHARS, "").trim().slice(0, MAX_CLIENT_NAME).trim();
+  return name === "" ? "Unnamed app" : name;
+}
+
+/** Where a code will be sent, as the consent page names it. */
+function redirectOriginOf(redirectURI: string): string {
+  const url = new URL(redirectURI);
+  return url.protocol === "http:" || url.protocol === "https:" ? url.origin : url.protocol;
+}
+
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function secretsMatch(stored: string, presented: string): boolean {
+  // Equal-length digests, so the comparison time never depends on the secret.
+  return timingSafeEqual(Buffer.from(sha256(stored)), Buffer.from(sha256(presented)));
+}
+
+/** A form or JSON body as a plain object. */
+function bodyOf(body: unknown): Record<string, unknown> {
+  if (body instanceof FormData) return Object.fromEntries(body.entries());
+  return body !== null && typeof body === "object" ? (body as Record<string, unknown>) : {};
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/** What `/mcp/authorize` stored in the verification row's value. */
+interface AuthorizationValue {
+  clientId: string;
+  redirectURI: string;
+  scope: string[];
+  userId: string;
+  requireConsent: boolean;
+  state: string | null;
+  ailkConsent?: boolean;
+  /** The session that approved the code; the code dies with it. */
+  sessionId?: string;
+}
+
+interface OAuthApplicationRow {
+  clientId: string;
+  clientSecret?: string | null;
+  type?: string | null;
+  name?: string | null;
+  createdAt: Date;
+}
+
+interface OAuthAccessTokenRow {
+  accessToken: string;
+  refreshToken: string;
+  accessTokenExpiresAt: Date;
+  refreshTokenExpiresAt: Date;
+  clientId: string;
+  userId: string;
+  scopes: string;
+}
+
+function parseValue(raw: string): AuthorizationValue | null {
+  try {
+    const value = JSON.parse(raw) as AuthorizationValue;
+    return typeof value === "object" && value !== null ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function mcpOAuthPlugin(deps: McpOAuthDeps) {
+  type AuthCtx = Parameters<Parameters<typeof createAuthMiddleware>[0]>[0]["context"];
+  /** What the helpers below need of an endpoint's or a hook's context. */
+  interface Ctx {
+    context: AuthCtx;
+    getSignedCookie(key: string, secret: string): Promise<string | null | false>;
+  }
+
+  /**
+   * The five consent checks (D5): the row exists, is unexpired and awaits
+   * consent, was issued to the signed-in person, and is the code in this
+   * browser's signed consent cookie.
+   */
+  async function pendingConsent(ctx: Ctx, consentCode: unknown, userId: string) {
+    if (typeof consentCode !== "string" || consentCode === "") throw refuse("NOT_FOUND", "invalid_request");
+    const row = await ctx.context.internalAdapter.findVerificationValue(consentCode);
+    const value = row ? parseValue(row.value) : null;
+    const cookie = await ctx.getSignedCookie(CONSENT_COOKIE, ctx.context.secret);
+    if (
+      !row ||
+      !value ||
+      new Date(row.expiresAt) < new Date() ||
+      value.requireConsent !== true ||
+      value.userId !== userId ||
+      cookie !== consentCode
+    ) {
+      throw refuse("NOT_FOUND", "invalid_request");
+    }
+    return value;
+  }
+
+  /** Each workspace with the scopes the request may approve there. */
+  async function offeredWorkspaces(userId: string, requested: string[]) {
+    const asked = requested.filter((s): s is McpScope => (MCP_SCOPES as readonly string[]).includes(s));
+    const pool = asked.length > 0 ? asked : [...MCP_SCOPES];
+    const memberships = await deps.readMemberships(userId);
+    return memberships.map((m) => {
+      const allowed = new Set(scopesForRole(m.role));
+      return {
+        id: m.workspaceId,
+        name: m.workspaceName,
+        organizationName: m.organizationName,
+        role: m.role,
+        offered: pool.filter((s) => allowed.has(s)),
+      };
+    });
+  }
+
+  /** Bounded cleanup on every registration (SEC-10357-03). */
+  async function sweep(ctx: Ctx): Promise<void> {
+    const adapter = ctx.context.adapter;
+    await adapter.deleteMany({
+      model: "oauthAccessToken",
+      where: [{ field: "refreshTokenExpiresAt", value: new Date(), operator: "lt" }],
+    });
+    const internal = ctx.context.internalAdapter;
+    const cursorRow = await internal.findVerificationValue(SWEEP_CURSOR);
+    const after = cursorRow ? new Date(cursorRow.value) : null;
+    const stale = await adapter.findMany<OAuthApplicationRow>({
+      model: "oauthApplication",
+      where: [
+        { field: "createdAt", value: new Date(Date.now() - UNUSED_CLIENT_TTL_MS), operator: "lt" },
+        ...(after && !Number.isNaN(after.getTime()) ? [{ field: "createdAt", value: after, operator: "gt" as const }] : []),
+      ],
+      sortBy: { field: "createdAt", direction: "asc" },
+      limit: SWEEP_BATCH,
+    });
+    // A full batch moves the cursor to its last row; a short one has reached
+    // the end, so the next sweep starts over.
+    if (cursorRow) await internal.deleteVerificationByIdentifier(SWEEP_CURSOR);
+    const last = stale.length === SWEEP_BATCH ? stale[stale.length - 1] : undefined;
+    if (last) {
+      await internal.createVerificationValue({
+        identifier: SWEEP_CURSOR,
+        value: new Date(last.createdAt).toISOString(),
+        expiresAt: new Date(Date.now() + UNUSED_CLIENT_TTL_MS),
+      });
+    }
+    for (const app of stale) {
+      const used =
+        (await adapter.findOne({ model: "oauthAccessToken", where: [{ field: "clientId", value: app.clientId }] })) ??
+        (await adapter.findOne({ model: "oauthConsent", where: [{ field: "clientId", value: app.clientId }] }));
+      if (!used) await adapter.delete({ model: "oauthApplication", where: [{ field: "clientId", value: app.clientId }] });
+    }
+  }
+
+  async function deleteTokensOf(ctx: Ctx, where: Array<{ field: string; value: string }>): Promise<number> {
+    return ctx.context.adapter.deleteMany({ model: "oauthAccessToken", where });
+  }
+
+  return {
+    id: "ailk-mcp-oauth",
+    hooks: {
+      before: [
+        {
+          matcher: (ctx) => ctx.path === "/mcp/authorize",
+          // Site-local refusals before the plugin can redirect an error to a
+          // self-registered `redirect_uri` (SEC-10357-07, -08); then consent,
+          // always (D2).
+          handler: createAuthMiddleware(async (ctx) => {
+            const query = (ctx.query ?? {}) as Record<string, unknown>;
+            if (query.response_type !== "code") throw refuse("BAD_REQUEST", "unsupported_response_type");
+            if (!str(query.code_challenge) || query.code_challenge_method !== "S256") {
+              throw refuse("BAD_REQUEST", "invalid_request");
+            }
+            const scopes = typeof query.scope === "string" ? query.scope.split(" ").filter(Boolean) : [];
+            if (scopes.some((s) => !REQUESTABLE_SCOPES.has(s))) throw refuse("BAD_REQUEST", "invalid_scope");
+            return { context: { query: { ...query, prompt: "consent" } } };
+          }),
+        },
+        {
+          matcher: (ctx) => ctx.path === "/mcp/register",
+          handler: createAuthMiddleware(async (ctx) => {
+            const body = bodyOf(ctx.body);
+            const uris = body.redirect_uris;
+            if (!Array.isArray(uris) || uris.length === 0 || !uris.every(isAllowedRedirectUri)) {
+              throw refuse("BAD_REQUEST", "invalid_redirect_uri");
+            }
+            const grants = body.grant_types;
+            const responses = body.response_types;
+            const tooLong = ["logo_uri", "client_uri", "tos_uri", "policy_uri"].some(
+              (key) => typeof body[key] === "string" && (body[key] as string).length > MAX_URI_LENGTH,
+            );
+            const metadataTooBig =
+              body.metadata !== undefined && JSON.stringify(body.metadata).length > MAX_METADATA_BYTES;
+            if (
+              uris.length > MAX_REDIRECT_URIS ||
+              (grants !== undefined &&
+                (!Array.isArray(grants) || grants.some((g) => g !== "authorization_code" && g !== "refresh_token"))) ||
+              (responses !== undefined && (!Array.isArray(responses) || responses.some((r) => r !== "code"))) ||
+              tooLong ||
+              metadataTooBig
+            ) {
+              throw refuse("BAD_REQUEST", "invalid_client_metadata");
+            }
+            // The register endpoint answers with a raw Response, which skips
+            // every after-hook, so the sweep runs here.
+            await sweep(ctx);
+            return { context: { body: { ...body, client_name: normaliseClientName(body.client_name) } } };
+          }),
+        },
+        {
+          matcher: (ctx) => ctx.path === "/mcp/token",
+          handler: createAuthMiddleware(async (ctx) => {
+            const body = bodyOf(ctx.body);
+            // The plugin `toString()`s these, so an array would pass every
+            // `typeof` check below unexamined (SEC-10357-01, -04).
+            if (TOKEN_FIELDS.some((key) => body[key] !== undefined && typeof body[key] !== "string")) {
+              throw refuse("BAD_REQUEST", "invalid_request");
+            }
+            if (typeof body.code === "string" && !CODE_SHAPE.test(body.code)) {
+              throw refuse("BAD_REQUEST", "invalid_grant");
+            }
+            if (body.grant_type === "authorization_code" && typeof body.code === "string") {
+              // Only a code AILK's consent minted is exchangeable: the
+              // `consent_code` in the consent page's URL is otherwise one too
+              // (SEC-10357-01). Any other code is burnt.
+              const row = await ctx.context.internalAdapter.findVerificationValue(body.code);
+              const value = row ? parseValue(row.value) : null;
+              // And only while the session that approved it lives: a password
+              // reset revokes every session, so no approved code outlives a
+              // recovery (SEC-10357, D9).
+              const approver =
+                value?.ailkConsent === true && typeof value.sessionId === "string"
+                  ? await ctx.context.adapter.findOne<{ expiresAt: Date }>({
+                      model: "session",
+                      where: [{ field: "id", value: value.sessionId }],
+                    })
+                  : null;
+              if (!approver || new Date(approver.expiresAt) <= new Date()) {
+                if (row) await ctx.context.internalAdapter.deleteVerificationByIdentifier(body.code);
+                throw refuse("BAD_REQUEST", "invalid_grant");
+              }
+            }
+            if (body.grant_type === "refresh_token" && typeof body.refresh_token === "string") {
+              const live = await ctx.context.adapter.findOne({
+                model: "oauthAccessToken",
+                where: [{ field: "refreshToken", value: body.refresh_token }],
+              });
+              if (!live) {
+                // A rotated refresh token presented again: end the whole line
+                // (RFC 9700 §4.14.2, SEC-10357-04).
+                const tombstone = await ctx.context.internalAdapter.findVerificationValue(
+                  ROTATED_PREFIX + sha256(body.refresh_token),
+                );
+                const owner = tombstone ? (JSON.parse(tombstone.value) as { userId: string; clientId: string }) : null;
+                if (owner) {
+                  await deleteTokensOf(ctx, [
+                    { field: "userId", value: owner.userId },
+                    { field: "clientId", value: owner.clientId },
+                  ]);
+                  throw refuse("BAD_REQUEST", "invalid_grant");
+                }
+              }
+            }
+          }),
+        },
+      ],
+      after: [
+        {
+          // Every answer of the token endpoint (the plugin sets these on the
+          // code grant only — SEC-10357-17) and of AILK's own endpoints.
+          matcher: (ctx) => NO_STORE_PATHS.has(ctx.path ?? ""),
+          handler: createAuthMiddleware(async (ctx) => {
+            ctx.setHeader("Cache-Control", "no-store");
+            ctx.setHeader("Pragma", "no-cache");
+          }),
+        },
+        {
+          matcher: (ctx) => ctx.path === "/mcp/token",
+          handler: createAuthMiddleware(async (ctx) => {
+            const body = bodyOf(ctx.body);
+            const returned = ctx.context.returned as Record<string, unknown> | undefined;
+            if (
+              body.grant_type !== "refresh_token" ||
+              typeof body.refresh_token !== "string" ||
+              !returned ||
+              typeof returned.access_token !== "string"
+            ) {
+              return;
+            }
+            // Rotation (D5): the used refresh token, and the access token
+            // minted with it, stop working now; a later replay of it ends the
+            // line.
+            const used = await ctx.context.adapter.findOne<OAuthAccessTokenRow>({
+              model: "oauthAccessToken",
+              where: [{ field: "refreshToken", value: body.refresh_token }],
+            });
+            if (!used) return;
+            await deleteTokensOf(ctx, [{ field: "refreshToken", value: body.refresh_token }]);
+            await ctx.context.internalAdapter.createVerificationValue({
+              identifier: ROTATED_PREFIX + sha256(body.refresh_token),
+              value: JSON.stringify({ userId: used.userId, clientId: used.clientId }),
+              expiresAt: new Date(used.refreshTokenExpiresAt),
+            });
+          }),
+        },
+        {
+          matcher: (ctx) => ctx.path === "/change-password",
+          // A changed password ends every MCP token the person holds (D9).
+          handler: createAuthMiddleware(async (ctx) => {
+            const returned = ctx.context.returned as { user?: { id?: unknown } } | undefined;
+            const userId = returned?.user?.id;
+            if (typeof userId !== "string") return;
+            try {
+              await deleteTokensOf(ctx, [{ field: "userId", value: userId }]);
+            } catch {
+              console.warn(
+                `[auth-email] ${JSON.stringify({ userId, kind: "password-change", reason: "mcp_token_revocation_failed" })}`,
+              );
+            }
+          }),
+        },
+      ],
+    },
+    endpoints: {
+      /**
+       * The `loginPage`: the site's own sign-in, resuming at `/mcp/authorize`
+       * — which forces consent again — rather than the plugin's cookie resume,
+       * which would skip AILK's before-hook.
+       */
+      mcpSignIn: createAuthEndpoint(
+        "/mcp/sign-in",
+        { method: "GET", query: z.record(z.string(), z.any()) },
+        async (ctx) => {
+          expireCookie(ctx, { name: LOGIN_COOKIE, attributes: { path: "/" } });
+          const params = new URLSearchParams();
+          for (const [key, value] of Object.entries(ctx.query ?? {})) {
+            if (typeof value === "string") params.set(key, value);
+          }
+          const next = `/api/auth/mcp/authorize?${params.toString()}`;
+          throw ctx.redirect(`/sign-in?next=${encodeURIComponent(next)}`);
+        },
+      ),
+
+      mcpConsentDetails: createAuthEndpoint(
+        "/mcp/consent-details",
+        { method: "GET", query: z.object({ consent_code: z.string().optional() }), use: [sessionMiddleware] },
+        async (ctx) => {
+          const userId = ctx.context.session.user.id;
+          const value = await pendingConsent(ctx, ctx.query.consent_code, userId);
+          const client = await ctx.context.adapter.findOne<OAuthApplicationRow>({
+            model: "oauthApplication",
+            where: [{ field: "clientId", value: value.clientId }],
+          });
+          if (!client) throw refuse("NOT_FOUND", "invalid_request");
+          return ctx.json({
+            client: { name: normaliseClientName(client.name), redirectOrigin: redirectOriginOf(value.redirectURI) },
+            workspaces: await offeredWorkspaces(userId, value.scope),
+          });
+        },
+      ),
+
+      mcpConsent: createAuthEndpoint(
+        "/mcp/consent",
+        {
+          method: "POST",
+          body: z.object({
+            consent_code: z.string(),
+            accept: z.boolean(),
+            workspace_id: z.string().optional(),
+            scopes: z.array(z.string()).optional(),
+          }),
+          use: [sessionMiddleware],
+        },
+        async (ctx) => {
+          const userId = ctx.context.session.user.id;
+          const consentCode = ctx.body.consent_code;
+          const value = await pendingConsent(ctx, consentCode, userId);
+          const redirect = new URL(value.redirectURI);
+
+          if (!ctx.body.accept) {
+            await ctx.context.internalAdapter.deleteVerificationByIdentifier(consentCode);
+            expireCookie(ctx, { name: CONSENT_COOKIE, attributes: { path: "/" } });
+            redirect.searchParams.set("error", "access_denied");
+            if (value.state) redirect.searchParams.set("state", value.state);
+            return ctx.json({ redirectURI: redirect.toString() });
+          }
+
+          const workspace = (await offeredWorkspaces(userId, value.scope)).find(
+            (w) => w.id === ctx.body.workspace_id,
+          );
+          const chosen = ctx.body.scopes ?? [];
+          if (!workspace || chosen.some((s) => !(workspace.offered as string[]).includes(s))) {
+            throw refuse("BAD_REQUEST", "invalid_scope");
+          }
+
+          // The plugin's token endpoint treats anything but "public" as
+          // confidential, so the type is re-derived here from what the
+          // register stored, whatever it wrote: a public client has an empty
+          // secret.
+          const client = await ctx.context.adapter.findOne<OAuthApplicationRow>({
+            model: "oauthApplication",
+            where: [{ field: "clientId", value: value.clientId }],
+          });
+          if (!client) throw refuse("NOT_FOUND", "invalid_request");
+          const type = client.clientSecret ? "web" : "public";
+          if (client.type !== type) {
+            await ctx.context.adapter.update({
+              model: "oauthApplication",
+              where: [{ field: "clientId", value: value.clientId }],
+              update: { type },
+            });
+          }
+
+          // `openid`, `profile` and `email` are never bound: no id_token.
+          const scope = ["offline_access", ...new Set(chosen), WORKSPACE_SCOPE_PREFIX + workspace.id];
+          const code = generateRandomString(32, "a-z", "A-Z", "0-9");
+          await ctx.context.internalAdapter.updateVerificationByIdentifier(consentCode, {
+            value: JSON.stringify({
+              ...value,
+              scope,
+              requireConsent: false,
+              ailkConsent: true,
+              sessionId: ctx.context.session.session.id,
+            }),
+            identifier: code,
+            expiresAt: new Date(Date.now() + 600 * 1000),
+          });
+          await ctx.context.adapter.create({
+            model: "oauthConsent",
+            data: {
+              clientId: value.clientId,
+              userId,
+              scopes: scope.join(" "),
+              consentGiven: true,
+              createdAt: new Date(),
+              updatedAt: new Date(),
+            },
+          });
+          expireCookie(ctx, { name: CONSENT_COOKIE, attributes: { path: "/" } });
+          redirect.searchParams.set("code", code);
+          if (value.state) redirect.searchParams.set("state", value.state);
+          const issuer = ctx.context.options.baseURL;
+          if (typeof issuer === "string") redirect.searchParams.set("iss", issuer);
+          return ctx.json({ redirectURI: redirect.toString() });
+        },
+      ),
+
+      /** RFC 7009 revocation, advertised as `revocation_endpoint`. */
+      mcpRevoke: createAuthEndpoint(
+        "/mcp/revoke",
+        {
+          method: "POST",
+          body: z.record(z.string(), z.any()),
+          metadata: { allowedMediaTypes: ["application/x-www-form-urlencoded", "application/json"] },
+        },
+        async (ctx) => {
+          const body = bodyOf(ctx.body);
+          let clientId = str(body.client_id);
+          let clientSecret = str(body.client_secret);
+          const authorization = ctx.request?.headers.get("authorization") ?? "";
+          if (authorization.startsWith("Basic ")) {
+            const decoded = Buffer.from(authorization.slice(6), "base64").toString("utf8");
+            const colon = decoded.indexOf(":");
+            if (colon > 0) {
+              try {
+                clientId = decodeURIComponent(decoded.slice(0, colon));
+                clientSecret = decodeURIComponent(decoded.slice(colon + 1));
+              } catch {
+                throw refuse("UNAUTHORIZED", "invalid_client");
+              }
+            }
+          }
+          const token = str(body.token);
+          if (!clientId) throw refuse("UNAUTHORIZED", "invalid_client");
+          const client = await ctx.context.adapter.findOne<OAuthApplicationRow>({
+            model: "oauthApplication",
+            where: [{ field: "clientId", value: clientId }],
+          });
+          if (!client) throw refuse("UNAUTHORIZED", "invalid_client");
+          if (client.clientSecret && !(clientSecret && secretsMatch(client.clientSecret, clientSecret))) {
+            throw refuse("UNAUTHORIZED", "invalid_client");
+          }
+          if (!token) throw refuse("BAD_REQUEST", "invalid_request");
+          await deleteTokensOf(ctx, [
+            { field: "clientId", value: clientId },
+            { field: "accessToken", value: token },
+          ]);
+          await deleteTokensOf(ctx, [
+            { field: "clientId", value: clientId },
+            { field: "refreshToken", value: token },
+          ]);
+          return ctx.json({});
+        },
+      ),
+
+      /** The person's own kill switch for one client (SEC-10357-10). */
+      mcpRevokeClient: createAuthEndpoint(
+        "/mcp/revoke-client",
+        { method: "POST", body: z.object({ client_id: z.string() }), use: [sessionMiddleware] },
+        async (ctx) => {
+          const revoked = await deleteTokensOf(ctx, [
+            { field: "clientId", value: ctx.body.client_id },
+            { field: "userId", value: ctx.context.session.user.id },
+          ]);
+          return ctx.json({ revoked });
+        },
+      ),
+
+      /** The stored-token lookup of decision (a) (D1, D16). Never echoes a token. */
+      mcpTokenInfo: createAuthEndpoint("/mcp/token-info", { method: "GET", requireHeaders: true }, async (ctx) => {
+        const invalid = () =>
+          refuse("UNAUTHORIZED", "invalid_token", { "WWW-Authenticate": 'Bearer error="invalid_token"' });
+        const authorization = ctx.headers?.get("authorization") ?? "";
+        const accessToken = authorization.startsWith("Bearer ") ? authorization.slice(7) : "";
+        if (!accessToken) throw invalid();
+        const row = await ctx.context.adapter.findOne<OAuthAccessTokenRow>({
+          model: "oauthAccessToken",
+          where: [{ field: "accessToken", value: accessToken }],
+        });
+        if (!row || new Date(row.accessTokenExpiresAt) < new Date() || !row.userId) throw invalid();
+        const { workspaceId } = parseGrantedScopes(row.scopes);
+        if (!workspaceId) throw invalid();
+        const membership = (await deps.readMemberships(row.userId)).find((m) => m.workspaceId === workspaceId);
+        if (!membership) throw invalid();
+        return ctx.json({
+            active: true,
+            userId: row.userId,
+            clientId: row.clientId,
+            workspaceId,
+            // The member clamp an agent acts at — never the person's own role
+            // (SEC-10357-09).
+            actingRole: lowerRole(membership.role as MembershipRole, "member"),
+            grants: grantsForWorkspace(row.scopes, workspaceId, membership.role) ?? [],
+            expiresAt: new Date(row.accessTokenExpiresAt).toISOString(),
+        });
+      }),
+    },
+  } satisfies BetterAuthPlugin;
+}