@softure-ai/mcp-access 0.1.6 → 0.1.7

package/module.json

@@ -1,15 +1,29 @@
 {
   "id": "mcp-access",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "dependsOn": { "security": "^0.1.0", "auth": "^0.1.0" },
   "dbSchema": "mcp",
-  "tables": ["access_tokens"],
+  "tables": ["access_tokens", "oauth_clients", "oauth_authorization_codes", "oauth_grants"],
   "env": [],
   "switches": [],
-  "routes": { "page": "/account/mcp", "endpoint": "/api/mcp" },
+  "routes": {
+    "page": "/account/mcp",
+    "endpoint": "/api/mcp",
+    "oauthConsent": "/oauth/authorize",
+    "oauthDecision": "/api/oauth/authorize",
+    "oauthToken": "/api/oauth/token",
+    "oauthRegister": "/api/oauth/register"
+  },
   "mount": [
     { "kind": "page", "path": "app/account/mcp/page.tsx", "export": "McpAccessPage" },
-    { "kind": "route-handler", "path": "app/api/mcp/route.ts", "export": "createMcpRoute" }
+    { "kind": "route-handler", "path": "app/api/mcp/route.ts", "export": "createMcpRoute" },
+    { "kind": "page", "path": "app/oauth/authorize/page.tsx", "export": "OAuthConsentPage" },
+    { "kind": "route-handler", "path": "app/api/oauth/authorize/route.ts", "export": "decideOAuthAuthorizationRoute" },
+    { "kind": "route-handler", "path": "app/api/oauth/token/route.ts", "export": "exchangeOAuthTokenRoute" },
+    { "kind": "route-handler", "path": "app/api/oauth/register/route.ts", "export": "registerOAuthClientRoute" },
+    { "kind": "route-handler", "path": "app/.well-known/oauth-authorization-server/route.ts", "export": "getAuthorizationServerMetadataRoute" },
+    { "kind": "route-handler", "path": "app/.well-known/oauth-protected-resource/route.ts", "export": "getProtectedResourceMetadataRoute" },
+    { "kind": "route-handler", "path": "app/.well-known/oauth-protected-resource/api/mcp/route.ts", "export": "getProtectedResourceMetadataRoute" }
   ],
   "privacy": { "exports": true, "deletes": true }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/mcp-access",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "SOFTURE AI MCP access module: hashed, scoped, expiring access tokens, a rate-limited Bearer endpoint around the app's MCP server factory, and a token page with client setup instructions for Next.js.",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
     "migrations",
+    "adoption",
     "module.json"
   ],
   "publishConfig": {

package/src/contract.ts

@@ -6,7 +6,8 @@ export type McpAccessErrorCode =
   | "mcp-access.name_required"
   | "mcp-access.name_too_long"
   | "mcp-access.token_limit_reached"
-  | "mcp-access.token_not_found";
+  | "mcp-access.token_not_found"
+  | "mcp-access.grant_not_found";
 
 /** Every code the token page can show: its own, a missing session and the generic ones. */
 export type TokenFormErrorCode = McpAccessErrorCode | "auth.unauthenticated" | CoreErrorCode;
@@ -73,8 +74,22 @@ export type IssueTokenFormState =
   | { readonly status: "ok"; readonly issued: IssuedToken }
   | { readonly status: "error"; readonly error: TokenFormErrorCode };
 
+/** A connected app (an OAuth grant) as its owner sees it. */
+export interface OAuthGrantView {
+  readonly id: string;
+  /** The name the client registered with, cut to 60 characters. */
+  readonly clientName: string;
+  /** Granted with write access (it still writes only while the app allows writes). */
+  readonly canWrite: boolean;
+  readonly createdAt: Date;
+  readonly lastUsedAt: Date | null;
+}
+
 /** What the revoke action returns to one token's form. */
 export type RevokeTokenFormState =
   | { readonly status: "idle" }
   | { readonly status: "ok" }
   | { readonly status: "error"; readonly error: TokenFormErrorCode };
+
+/** What the disconnect action returns to one connected app's form. */
+export type RevokeGrantFormState = RevokeTokenFormState;

package/src/index.ts

@@ -17,6 +17,12 @@ export const MODULE_ID = "mcp-access";
  */
 export const MCP_RATE_LIMIT_BUCKETS = {
   mcp: { limit: 200, windowMinutes: 15 },
+  /**
+   * OAuth registration (per address) and token requests (per address and client id), when
+   * `oauth.enabled`. Enough for an assistant platform refreshing many users' tokens per client,
+   * too little for a script filling the clients table.
+   */
+  "mcp-oauth": { limit: 60, windowMinutes: 15 },
 } as const;
 
 /**
@@ -26,16 +32,30 @@ export const MCP_RATE_LIMIT_BUCKETS = {
 export const mcpAccess = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.1.6",
+    version: "0.1.7",
     dependsOn: { security: "^0.1.0", auth: "^0.1.0" },
     dbSchema: "mcp",
-    tables: ["access_tokens"],
+    tables: ["access_tokens", "oauth_clients", "oauth_authorization_codes", "oauth_grants"],
     env: [],
     switches: [],
-    routes: { page: "/account/mcp", endpoint: "/api/mcp" },
+    routes: {
+      page: "/account/mcp",
+      endpoint: "/api/mcp",
+      oauthConsent: "/oauth/authorize",
+      oauthDecision: "/api/oauth/authorize",
+      oauthToken: "/api/oauth/token",
+      oauthRegister: "/api/oauth/register",
+    },
     mount: [
       { kind: "page", path: "app/account/mcp/page.tsx", export: "McpAccessPage" },
       { kind: "route-handler", path: "app/api/mcp/route.ts", export: "createMcpRoute" },
+      { kind: "page", path: "app/oauth/authorize/page.tsx", export: "OAuthConsentPage" },
+      { kind: "route-handler", path: "app/api/oauth/authorize/route.ts", export: "decideOAuthAuthorizationRoute" },
+      { kind: "route-handler", path: "app/api/oauth/token/route.ts", export: "exchangeOAuthTokenRoute" },
+      { kind: "route-handler", path: "app/api/oauth/register/route.ts", export: "registerOAuthClientRoute" },
+      { kind: "route-handler", path: "app/.well-known/oauth-authorization-server/route.ts", export: "getAuthorizationServerMetadataRoute" },
+      { kind: "route-handler", path: "app/.well-known/oauth-protected-resource/route.ts", export: "getProtectedResourceMetadataRoute" },
+      { kind: "route-handler", path: "app/.well-known/oauth-protected-resource/api/mcp/route.ts", export: "getProtectedResourceMetadataRoute" },
     ],
     privacy: { exports: true, deletes: true },
   },
@@ -63,19 +83,23 @@ export type {
   McpAccessErrorCode,
   McpClientSetup,
   McpServerIdentity,
+  OAuthGrantView,
+  RevokeGrantFormState,
   RevokeTokenFormState,
   TokenFormErrorCode,
 } from "./contract.js";
 export { getTokenErrorMessage, mcpAccessMessages, type McpAccessMessages } from "./messages/index.js";
 export {
+  MAX_PRESENTED_TOKEN_LENGTH,
   MAX_TOKEN_NAME_LENGTH,
   SERVER_NAME_PATTERN,
   TOOL_NAME_PATTERN,
   type McpAccessOptions,
   type McpAccessOptionsInput,
+  type McpOAuthOptions,
   type McpToolAccess,
   type McpToolDefinition,
   type McpToolDefinitionInput,
 } from "./options.js";
-export { accessTokens } from "./schema.js";
+export { accessTokens, oauthAuthorizationCodes, oauthClients, oauthGrants } from "./schema.js";
 export { getAccessTokenStatus, type AccessTokenStatusOptions } from "./token-status.js";

package/src/messages/en.ts

@@ -58,12 +58,40 @@ export const en = {
     revoke: "Revoke",
     revoking: "Revoking…",
   },
+  grants: {
+    title: "Connected apps",
+    lead: "Assistants you connected by signing in, such as claude.ai or ChatGPT. Disconnecting one stops its access at once.",
+    empty: "No app is connected.",
+    connectedOn: "Connected {date}",
+    disconnect: "Disconnect",
+    disconnecting: "Disconnecting…",
+  },
+  consent: {
+    title: "{client} wants access to your account",
+    lead: "The assistant can answer questions with your data in this app. You can disconnect it at any time on the AI assistant access page.",
+    app: "App",
+    returnsTo: "returns to {target}",
+    account: "Account",
+    access: "Access",
+    readAccess: "Read your data",
+    allowWrite: "Also allow changes",
+    allowWriteHint: "Without it, the assistant can only read.",
+    allow: "Allow",
+    deny: "Deny",
+    errorTitle: "The assistant cannot be connected",
+    unknownClient: "The app that sent you here is not registered. Connect it again from the assistant.",
+    redirectMismatch: "The return address does not match the one the app registered. Connect it again from the assistant.",
+    invalidRequest: "The app sent a connection request this app cannot accept.",
+    nothingGranted: "No access was granted.",
+    backToApp: "Back to the app ({target})",
+  },
   errors: {
     "mcp-access": {
       name_required: "Give the token a name, so you can tell it from the others.",
       name_too_long: "The name is too long.",
       token_limit_reached: "You already hold the most active tokens allowed. Revoke one before creating another.",
       token_not_found: "This token no longer exists. It may have been revoked already.",
+      grant_not_found: "This app is no longer connected.",
     },
     auth: {
       unauthenticated: "Your session has ended. Log in again.",

package/src/messages/pl.ts

@@ -60,12 +60,40 @@ export const pl: typeof en = {
     revoke: "Unieważnij",
     revoking: "Unieważnianie…",
   },
+  grants: {
+    title: "Połączone aplikacje",
+    lead: "Asystenci połączeni przez logowanie, na przykład claude.ai albo ChatGPT. Odłączenie od razu odbiera im dostęp.",
+    empty: "Żadna aplikacja nie jest połączona.",
+    connectedOn: "Połączono {date}",
+    disconnect: "Odłącz",
+    disconnecting: "Odłączanie…",
+  },
+  consent: {
+    title: "{client} prosi o dostęp do Twojego konta",
+    lead: "Asystent odpowie na pytania, korzystając z Twoich danych w tej aplikacji. Możesz go odłączyć w każdej chwili na stronie dostępu dla asystenta AI.",
+    app: "Aplikacja",
+    returnsTo: "wróci na {target}",
+    account: "Konto",
+    access: "Dostęp",
+    readAccess: "Odczyt Twoich danych",
+    allowWrite: "Pozwól też na zmiany",
+    allowWriteHint: "Bez tego asystent może tylko czytać.",
+    allow: "Zezwól",
+    deny: "Odmów",
+    errorTitle: "Nie da się połączyć asystenta",
+    unknownClient: "Aplikacja, która Cię tu przysłała, nie jest zarejestrowana. Połącz ją od nowa z poziomu asystenta.",
+    redirectMismatch: "Adres powrotu nie zgadza się z tym, który aplikacja zarejestrowała. Połącz ją od nowa z poziomu asystenta.",
+    invalidRequest: "Aplikacja wysłała żądanie połączenia, którego ta aplikacja nie może przyjąć.",
+    nothingGranted: "Nie nadano żadnego dostępu.",
+    backToApp: "Wróć do aplikacji ({target})",
+  },
   errors: {
     "mcp-access": {
       name_required: "Nadaj tokenowi nazwę, żeby odróżnić go od pozostałych.",
       name_too_long: "Nazwa jest za długa.",
       token_limit_reached: "Masz już najwięcej aktywnych tokenów, ile można. Unieważnij któryś, zanim utworzysz nowy.",
       token_not_found: "Ten token już nie istnieje. Mógł zostać unieważniony.",
+      grant_not_found: "Ta aplikacja nie jest już połączona.",
     },
     auth: {
       unauthenticated: "Twoja sesja wygasła. Zaloguj się ponownie.",

package/src/next/actions.ts

@@ -9,9 +9,10 @@ import { getSoftureConfig } from "@softure-ai/core/next";
 import { revalidatePath } from "next/cache";
 import { z } from "zod";
 import { getMcpClientSetup } from "../client-setup.js";
-import type { IssueTokenFormState, RevokeTokenFormState } from "../contract.js";
+import type { IssueTokenFormState, RevokeGrantFormState, RevokeTokenFormState } from "../contract.js";
 import { MAX_TOKEN_NAME_LENGTH } from "../options.js";
 import { getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes, getMcpEndpointUrl } from "../server/options.js";
+import { revokeOAuthGrant } from "../server/oauth.js";
 import { issueAccessToken, revokeAccessToken } from "../server/tokens.js";
 import { getMcpAccessContext } from "./context.js";
 import { formatDate } from "./format.js";
@@ -89,3 +90,20 @@ export async function revokeTokenAction(_previous: RevokeTokenFormState, formDat
     return { status: "error", error: reportFailure("revoking a token", error) };
   }
 }
+
+/** Disconnects one of the signed-in user's OAuth apps: the grant and its access tokens go at once. */
+export async function revokeGrantAction(_previous: RevokeGrantFormState, formData: FormData): Promise<RevokeGrantFormState> {
+  const config = getSoftureConfig();
+  const user = await getCurrentUser();
+  if (user === null) return { status: "error", error: "auth.unauthenticated" };
+
+  const input = revokeInput.parse({ id: formData.get("id") });
+  try {
+    const result = await revokeOAuthGrant(await getMcpAccessContext(config), { userId: user.id, grantId: input.id });
+    if (!result.ok) return { status: "error", error: result.error };
+    refreshPage(config);
+    return { status: "ok" };
+  } catch (error) {
+    return { status: "error", error: reportFailure("disconnecting an app", error) };
+  }
+}

package/src/next/index.ts

@@ -1,5 +1,14 @@
 // The Next.js adapter of @softure-ai/mcp-access: the MCP route factory, the token page and its
-// server actions (docs/02-module-standard.md §8).
-export { issueTokenAction, revokeTokenAction } from "./actions.js";
+// server actions, and the OAuth routes and consent page (docs/02-module-standard.md §8).
+export { issueTokenAction, revokeGrantAction, revokeTokenAction } from "./actions.js";
+export { OAuthConsentPage, type OAuthConsentPageProps } from "./oauth-page.js";
+export {
+  answerOAuthPreflight,
+  decideOAuthAuthorizationRoute,
+  exchangeOAuthTokenRoute,
+  getAuthorizationServerMetadataRoute,
+  getProtectedResourceMetadataRoute,
+  registerOAuthClientRoute,
+} from "./oauth-routes.js";
 export { McpAccessPage } from "./pages.js";
 export { createMcpRoute } from "./route.js";

package/src/next/oauth-page.tsx

@@ -0,0 +1,67 @@
+// The OAuth consent page, ready to mount with one line:
+// `export { OAuthConsentPage as default } from "@softure-ai/mcp-access/next"`.
+// The authorization endpoint clients send the person to. Without a session it redirects to the
+// login page and back with every parameter (state, challenge, resource). Errors before the client
+// and its redirect URI are confirmed are shown here, never redirected; later ones offer a link back
+// to the client, never an automatic redirect (anyone can register a redirect URI).
+import { requireUser } from "@softure-ai/auth/next";
+import { formatMessage } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { Card } from "@softure-ai/ui";
+import { notFound } from "next/navigation";
+import { getConsentPath, isOAuthEnabled, readAuthorizationParams, validateAuthorizationRequest } from "../server/oauth-http.js";
+import { describeRedirectUri } from "../server/oauth-validation.js";
+import { getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes } from "../server/options.js";
+import { ConsentError, ConsentForm } from "../ui/consent-form.js";
+import { getMcpAccessContext } from "./context.js";
+
+type SearchParams = Promise<Record<string, string | string[] | undefined>>;
+
+export interface OAuthConsentPageProps {
+  readonly searchParams?: SearchParams;
+}
+
+const LAYOUT_CLASS = "sft:mx-auto sft:box-border sft:w-full sft:sm:max-w-md sft:px-4 sft:py-4";
+
+export async function OAuthConsentPage({ searchParams }: OAuthConsentPageProps) {
+  const config = getSoftureConfig();
+  if (!isOAuthEnabled(config)) notFound();
+  const query = (await searchParams) ?? {};
+  const params = readAuthorizationParams({ get: (name: string) => query[name] });
+  const user = await requireUser({ next: getConsentPath(config, params), searchParams: query });
+
+  const messages = getMcpAccessMessages(config);
+  const outcome = await validateAuthorizationRequest(await getMcpAccessContext(config), params);
+  if (outcome.kind !== "valid") {
+    const message =
+      outcome.kind === "redirect-error" ? messages.consent.invalidRequest : outcome.reason === "unknown_client" ? messages.consent.unknownClient : messages.consent.redirectMismatch;
+    return (
+      <main className={LAYOUT_CLASS}>
+        <Card title={messages.consent.errorTitle}>
+          <ConsentError
+            message={message}
+            {...(outcome.kind === "redirect-error" ? { backLocation: outcome.location, backTarget: describeRedirectUri(outcome.redirectUri) } : {})}
+            messages={messages}
+          />
+        </Card>
+      </main>
+    );
+  }
+
+  const { client, redirectUri, isWriteRequested } = outcome.request;
+  return (
+    <main className={LAYOUT_CLASS}>
+      <Card title={formatMessage(messages.consent.title, { client: client.clientName })} subtitle={messages.consent.lead}>
+        <ConsentForm
+          action={getMcpAccessRoutes(config).oauthDecision}
+          params={[...params.entries()]}
+          clientName={client.clientName}
+          redirectTarget={describeRedirectUri(redirectUri)}
+          accountEmail={user.email}
+          isWriteOffered={isWriteRequested && getMcpAccessOptions(config).allowWrites}
+          messages={messages}
+        />
+      </Card>
+    </main>
+  );
+}

package/src/next/oauth-routes.ts

@@ -0,0 +1,65 @@
+// The OAuth routes, each mounted with one line (README §4), e.g.
+// `app/api/oauth/token/route.ts → export { exchangeOAuthTokenRoute as POST, answerOAuthPreflight as OPTIONS } from "@softure-ai/mcp-access/next";`
+// They supply the module context (and, for the decision, the session's user) to the handlers in
+// `/server`. With `oauth.enabled` off every one answers 404.
+import { getCurrentUser } from "@softure-ai/auth/next";
+import { errorLogLabel } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import {
+  answerOAuthPreflight,
+  getAuthorizationServerMetadata,
+  getProtectedResourceMetadata,
+  handleAuthorizationDecision,
+  handleClientRegistration,
+  handleTokenRequest,
+  serveDiscoveryDocument,
+} from "../server/oauth-http.js";
+import type { McpAccessContext } from "../server/tokens.js";
+import { getMcpAccessContext } from "./context.js";
+
+const UNAVAILABLE = { status: 503, headers: { "cache-control": "no-store" } };
+
+async function withContext(request: Request, handle: (ctx: McpAccessContext, request: Request) => Promise<Response>): Promise<Response> {
+  let ctx;
+  try {
+    ctx = await getMcpAccessContext();
+  } catch (error) {
+    console.error(`@softure-ai/mcp-access: opening the database failed: ${errorLogLabel(error)}`);
+    return Response.json({ error: "temporarily_unavailable" }, UNAVAILABLE);
+  }
+  return handle(ctx, request);
+}
+
+/** `GET /.well-known/oauth-authorization-server`. */
+export function getAuthorizationServerMetadataRoute(): Response {
+  return serveDiscoveryDocument(getSoftureConfig(), getAuthorizationServerMetadata);
+}
+
+/**
+ * `GET /.well-known/oauth-protected-resource` and `…/oauth-protected-resource/api/mcp`: the same
+ * export at both paths; the request's path picks the variant.
+ */
+export function getProtectedResourceMetadataRoute(request: Request): Response {
+  const variant = new URL(request.url).pathname.replace(/\/+$/, "").endsWith("/oauth-protected-resource") ? "root" : "endpoint";
+  return serveDiscoveryDocument(getSoftureConfig(), (config) => getProtectedResourceMetadata(config, variant));
+}
+
+/** `POST /api/oauth/register`. */
+export function registerOAuthClientRoute(request: Request): Promise<Response> {
+  return withContext(request, handleClientRegistration);
+}
+
+/** `POST /api/oauth/token`. */
+export function exchangeOAuthTokenRoute(request: Request): Promise<Response> {
+  return withContext(request, handleTokenRequest);
+}
+
+/** `POST /api/oauth/authorize`: the consent form's decision, answered with `303`. */
+export function decideOAuthAuthorizationRoute(request: Request): Promise<Response> {
+  return withContext(request, async (ctx, req) => {
+    const user = await getCurrentUser();
+    return handleAuthorizationDecision(ctx, req, user?.id ?? null);
+  });
+}
+
+export { answerOAuthPreflight };

package/src/next/pages.tsx

@@ -7,14 +7,15 @@ import { requireUser } from "@softure-ai/auth/next";
 import { formatMessage, type SoftureConfig } from "@softure-ai/core";
 import { getSoftureConfig } from "@softure-ai/core/next";
 import { Card } from "@softure-ai/ui";
-import type { AccessTokenStatus, AccessTokenView } from "../contract.js";
+import type { AccessTokenStatus, AccessTokenView, OAuthGrantView } from "../contract.js";
 import type { McpAccessMessages } from "../messages/index.js";
 import type { McpAccessOptions } from "../options.js";
 import { getLocalizedText, getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes } from "../server/options.js";
+import { listOAuthGrants } from "../server/oauth.js";
 import { listAccessTokens } from "../server/tokens.js";
 import { getAccessTokenStatus } from "../token-status.js";
-import { TokenManager, type TokenManagerRow, type TokenManagerTool } from "../ui/token-manager.js";
-import { issueTokenAction, revokeTokenAction } from "./actions.js";
+import { TokenManager, type TokenManagerGrant, type TokenManagerRow, type TokenManagerTool } from "../ui/token-manager.js";
+import { issueTokenAction, revokeGrantAction, revokeTokenAction } from "./actions.js";
 import { getMcpAccessContext } from "./context.js";
 import { formatDate, formatDateTime } from "./format.js";
 
@@ -48,6 +49,16 @@ function toRow(token: AccessTokenView, now: Date, config: SoftureConfig, options
   };
 }
 
+function toGrant(grant: OAuthGrantView, config: SoftureConfig, options: McpAccessOptions, messages: McpAccessMessages): TokenManagerGrant {
+  const lastUse = grant.lastUsedAt === null ? messages.list.neverUsed : formatMessage(messages.list.lastUsed, { date: formatDateTime(config, grant.lastUsedAt) });
+  return {
+    id: grant.id,
+    clientName: grant.clientName,
+    scopeText: grant.canWrite && options.allowWrites ? messages.list.readWrite : messages.list.readOnly,
+    details: [formatMessage(messages.grants.connectedOn, { date: formatDate(config, grant.createdAt) }), lastUse],
+  };
+}
+
 function toTool(tool: McpAccessOptions["tools"][number], config: SoftureConfig, options: McpAccessOptions, messages: McpAccessMessages): TokenManagerTool {
   const accessText = tool.access === "read" ? messages.tools.read : options.allowWrites ? messages.tools.write : messages.tools.writeUnavailable;
   return { name: tool.name, description: getLocalizedText(tool.description, config.locale), accessText };
@@ -61,6 +72,7 @@ export async function McpAccessPage() {
   const ctx = await getMcpAccessContext(config);
   const now = ctx.clock.now();
   const tokens = await listAccessTokens(ctx, user.id);
+  const grants = options.oauth.enabled ? await listOAuthGrants(ctx, user.id) : null;
   return (
     <main className={LAYOUT_CLASS}>
       <Card title={messages.page.title} subtitle={messages.page.lead}>
@@ -71,6 +83,7 @@ export async function McpAccessPage() {
           maxTokens={options.maxTokensPerUser}
           issueAction={issueTokenAction}
           revokeAction={revokeTokenAction}
+          {...(grants === null ? {} : { grants: grants.map((grant) => toGrant(grant, config, options, messages)), revokeGrantAction })}
           messages={messages}
           locale={config.locale}
         />

package/src/options.ts

@@ -11,6 +11,9 @@ export const TOOL_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
 /** The longest token name the table takes (`access_tokens.name`). */
 export const MAX_TOKEN_NAME_LENGTH = 60;
 
+/** The longest value the token check looks at: a longer header is refused before any pattern runs. */
+export const MAX_PRESENTED_TOKEN_LENGTH = 512;
+
 /** Copy per locale; a locale without its own text falls back to `en`. */
 const localizedTextSchema = z.partialRecord(z.enum(LOCALES), z.string().trim().min(1).max(500));
 
@@ -26,6 +29,26 @@ const toolSchema = z.strictObject({
   description: localizedTextSchema.refine((text) => text.en !== undefined, "needs at least an en text"),
 });
 
+const oauthSchema = z.strictObject({
+  /**
+   * Makes the module an OAuth 2.1 authorization server for its endpoint: discovery metadata,
+   * dynamic client registration, a consent page and a token endpoint. The app mounts those routes.
+   */
+  enabled: z.boolean().default(false),
+  /** How long an access token issued through OAuth works. Clients refresh it themselves. */
+  accessTokenLifetimeMinutes: z.int().min(5).max(1440).default(60),
+  /** How long a refresh token works, counted from the last refresh: a grant in use never expires. */
+  refreshTokenLifetimeDays: z.int().min(1).max(365).default(90),
+  /** How long an authorization code works; RFC 6749 §4.1.2 recommends at most ten minutes. */
+  authorizationCodeLifetimeMinutes: z.int().min(1).max(10).default(10),
+});
+
+/** A pattern for tokens an app issued before adopting the module: anchored, and stateless. */
+const legacyTokenPatternSchema = z
+  .instanceof(RegExp, { message: "must be a RegExp" })
+  .refine((pattern) => pattern.source.startsWith("^") && pattern.source.endsWith("$"), "must be anchored with ^ and $")
+  .refine((pattern) => !pattern.global && !pattern.sticky, "must not use the g or y flag");
+
 export const mcpAccessOptionsSchema = z
   .strictObject({
     /** The name MCP clients list the server under, e.g. "acme". Used in the setup instructions. */
@@ -34,12 +57,19 @@ export const mcpAccessOptionsSchema = z
     tools: z.array(toolSchema).default([]),
     /** Lets write tokens be issued and used. Off, every token reads only, write tokens included. */
     allowWrites: z.boolean().default(false),
-    /** How long a token works. A choice: longer than a session, never forever. */
+    /** How long a token issued on the token page works. A choice: longer than a session, never forever. */
     tokenLifetimeDays: z.int().min(1).max(365).default(90),
     /** How many unexpired tokens one account may hold. */
     maxTokensPerUser: z.int().min(1).max(100).default(20),
     /** From how many calendar days before its expiry the page warns about a token. */
     expiryWarningDays: z.int().min(0).max(60).default(14),
+    /**
+     * Tokens an app issued before it adopted the module, e.g. `/^[0-9a-f]{64}$/`. Such a value is
+     * looked up by its sha256 like a token of the module's own shape; new tokens keep the prefix.
+     */
+    legacyTokenPattern: legacyTokenPatternSchema.optional(),
+    /** OAuth 2.1 for MCP clients that connect without a pasted token (claude.ai, ChatGPT). */
+    oauth: oauthSchema.prefault({}),
   })
   .superRefine((options, context) => {
     const names = new Set<string>();
@@ -56,3 +86,4 @@ export type McpAccessOptions = z.output<typeof mcpAccessOptionsSchema>;
 export type McpToolDefinitionInput = z.input<typeof toolSchema>;
 export type McpToolDefinition = z.output<typeof toolSchema>;
 export type McpToolAccess = McpToolDefinition["access"];
+export type McpOAuthOptions = z.output<typeof oauthSchema>;

package/src/schema.ts

@@ -1,10 +1,54 @@
-// Drizzle view of the module's table (migrations/0001_create_access_tokens.sql). The migration is
-// the source of truth; this file only types the queries.
+// Drizzle view of the module's tables (migrations/0001_create_access_tokens.sql and
+// 0002_create_oauth_grants.sql). The migrations are the source of truth; this file only types the
+// queries.
 import { users } from "@softure-ai/auth";
-import { boolean, pgSchema, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { boolean, jsonb, pgSchema, text, timestamp, uuid, type AnyPgColumn } from "drizzle-orm/pg-core";
 
 export const mcpSchema = pgSchema("mcp");
 
+export const oauthClients = mcpSchema.table("oauth_clients", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  clientId: text("client_id").notNull().unique("oauth_clients_client_id_key"),
+  clientName: text("client_name").notNull(),
+  redirectUris: jsonb("redirect_uris").$type<string[]>().notNull(),
+  tokenEndpointAuthMethod: text("token_endpoint_auth_method").$type<"none" | "client_secret_post" | "client_secret_basic">().notNull(),
+  clientSecretHash: text("client_secret_hash"),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+});
+
+export const oauthAuthorizationCodes = mcpSchema.table("oauth_authorization_codes", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  codeHash: text("code_hash").notNull().unique("oauth_authorization_codes_code_hash_key"),
+  clientId: uuid("client_id")
+    .notNull()
+    .references(() => oauthClients.id, { onDelete: "cascade" }),
+  userId: uuid("user_id")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  redirectUri: text("redirect_uri").notNull(),
+  codeChallenge: text("code_challenge").notNull(),
+  canWrite: boolean("can_write").notNull(),
+  expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+  usedAt: timestamp("used_at", { withTimezone: true }),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+});
+
+export const oauthGrants = mcpSchema.table("oauth_grants", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  clientId: uuid("client_id")
+    .notNull()
+    .references(() => oauthClients.id, { onDelete: "cascade" }),
+  canWrite: boolean("can_write").notNull(),
+  refreshTokenHash: text("refresh_token_hash").notNull().unique("oauth_grants_refresh_token_hash_key"),
+  previousRefreshTokenHash: text("previous_refresh_token_hash"),
+  refreshExpiresAt: timestamp("refresh_expires_at", { withTimezone: true }).notNull(),
+  lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+});
+
 export const accessTokens = mcpSchema.table("access_tokens", {
   id: uuid("id").primaryKey().defaultRandom(),
   userId: uuid("user_id")
@@ -16,4 +60,8 @@ export const accessTokens = mcpSchema.table("access_tokens", {
   createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
   expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
   lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
+  grantId: uuid("grant_id").references((): AnyPgColumn => oauthGrants.id, { onDelete: "cascade" }),
 });
+
+export type OAuthClientRow = typeof oauthClients.$inferSelect;
+export type OAuthTokenEndpointAuthMethod = OAuthClientRow["tokenEndpointAuthMethod"];

package/src/server/endpoint.ts

@@ -1,4 +1,4 @@
-// The MCP endpoint (FIRE_TRACKER `src/app/api/mcp/route.ts`, generalised). It takes a Web
+// The MCP endpoint (an adopting app's MCP route, generalised). It takes a Web
 // `Request` and returns a `Response`, so it runs under any fetch-shaped host; the Next adapter only
 // supplies the context. Order: identify the client, count the request, verify the Bearer token,
 // then hand the request to a fresh server from the app's factory. Each refusal happens before the
@@ -15,12 +15,11 @@ import {
 import { errorLogLabel, getModule } from "@softure-ai/core";
 import { consumeRateLimit, identifyClient } from "@softure-ai/security/server";
 import type { McpServerIdentity } from "../contract.js";
+import { getProtectedResourceMetadataUrl, isOAuthEnabled } from "./oauth-http.js";
+import { MCP_READ_SCOPE, MCP_WRITE_SCOPE } from "./scopes.js";
 import { verifyAccessToken, type McpAccessContext } from "./tokens.js";
 
-/** Every valid token reads. */
-export const MCP_READ_SCOPE = "mcp:read";
-/** A token that may write: issued for writes, and the app allows them. */
-export const MCP_WRITE_SCOPE = "mcp:write";
+export { MCP_READ_SCOPE, MCP_WRITE_SCOPE };
 
 /** The security bucket the endpoint counts in; `MCP_RATE_LIMIT_BUCKETS` holds its default. */
 export const MCP_RATE_LIMIT_BUCKET = "mcp";
@@ -89,10 +88,14 @@ export function createMcpEndpoint({ createServer }: McpEndpointOptions): McpEndp
 /**
  * The verified identity as the SDK's `AuthInfo`, or the challenge response. Unknown, revoked,
  * expired and malformed tokens get the same `401 invalid_token`. Expiry is decided by the query on
- * the module's clock, not by the SDK's own check on the wall clock.
+ * the module's clock, not by the SDK's own check on the wall clock. With OAuth on, the challenge
+ * names the protected resource metadata (RFC 9728 §5.1): that is how claude.ai and ChatGPT find
+ * the authorization server.
  */
 async function authenticate(ctx: McpAccessContext, header: string | null): Promise<AuthInfo | Response> {
-  const challenge = { requiredScopes: [MCP_READ_SCOPE] };
+  const challenge = isOAuthEnabled(ctx.config)
+    ? { requiredScopes: [MCP_READ_SCOPE], resourceMetadataUrl: getProtectedResourceMetadataUrl(ctx.config) }
+    : { requiredScopes: [MCP_READ_SCOPE] };
   if (header === null || !BEARER_PREFIX.test(header)) {
     return bearerAuthChallengeResponse(new OAuthError(OAuthErrorCode.InvalidToken, "Missing Bearer token"), challenge);
   }