@softure-ai/mcp-access 0.1.6 → 0.1.8

package/src/server/oauth.ts

@@ -0,0 +1,315 @@
+// The OAuth 2.1 authorization server's data layer (an adopting app's OAuth code, generalised onto
+// the module context). Every secret (code, refresh token, client secret) leaves this file once and
+// is stored as its sha256; expiry sits in the queries. An access token issued here is a row of
+// `access_tokens` with its grant, so the endpoint verifies it like any other token.
+import { timingSafeEqual } from "node:crypto";
+import { err, ok, type Err, type Ok } from "@softure-ai/core";
+import { and, desc, eq, gt, isNotNull, isNull, lt, lte, notExists } from "drizzle-orm";
+import type { OAuthGrantView } from "../contract.js";
+import { accessTokens, oauthAuthorizationCodes, oauthClients, oauthGrants, type OAuthClientRow, type OAuthTokenEndpointAuthMethod } from "../schema.js";
+import { getMcpAccessOptions } from "./options.js";
+import { isPkceVerifierValid } from "./pkce.js";
+import { ACCESS_TOKEN_PREFIX, createSecret, hashAccessToken, type McpAccessContext } from "./tokens.js";
+
+/** Refresh tokens: for people and secret scanners, like the access token prefix. */
+export const REFRESH_TOKEN_PREFIX = "sftmcr_";
+/** Authorization codes. */
+export const CONSENT_CODE_PREFIX = "sftmca_";
+/** Client secrets of confidential clients. */
+export const CLIENT_SECRET_PREFIX = "sftmcs_";
+/** Client ids are public (RFC 6749 §2.2); the prefix only helps a person reading a log. */
+const CLIENT_ID_PREFIX = "sftmc_";
+
+/** Codes, refresh tokens and client secrets longer than this are not looked up. */
+const MAX_SECRET_LENGTH = 512;
+const MINUTE_MS = 60_000;
+const DAY_MS = 24 * 60 * MINUTE_MS;
+/** A registration without any grant after a day is abandoned (registration is public and free). */
+export const STALE_CLIENT_MS = DAY_MS;
+
+type Transaction = Parameters<Parameters<McpAccessContext["db"]["transaction"]>[0]>[0];
+
+export interface OAuthClientRegistration {
+  /** 1 to 60 characters, trimmed, no control characters (`parseClientRegistration` makes it so). */
+  readonly clientName: string;
+  readonly redirectUris: readonly string[];
+  readonly tokenEndpointAuthMethod: OAuthTokenEndpointAuthMethod;
+}
+
+export interface RegisteredOAuthClient {
+  readonly client: OAuthClientRow;
+  /** The plaintext secret of a confidential client, shown once; null for a public client. */
+  readonly clientSecret: string | null;
+}
+
+export interface IssuedOAuthTokens {
+  readonly accessToken: string;
+  readonly refreshToken: string;
+  /** Seconds, as `expires_in` counts them (RFC 6749 §5.1). */
+  readonly expiresIn: number;
+  readonly canWrite: boolean;
+}
+
+/**
+ * Registers a client (RFC 7591). A secret only for the methods that use one. Abandoned clients
+ * (no grant, older than a day) are deleted first, so a flood of registrations does not pile up.
+ */
+export async function registerMcpClient(ctx: McpAccessContext, input: OAuthClientRegistration): Promise<RegisteredOAuthClient> {
+  const now = ctx.clock.now();
+  await deleteStaleClients(ctx, now);
+  const secret = input.tokenEndpointAuthMethod === "none" ? null : createSecret(CLIENT_SECRET_PREFIX);
+  const [client] = await ctx.db
+    .insert(oauthClients)
+    .values({
+      clientId: `${CLIENT_ID_PREFIX}${createSecret("").secret.slice(0, 22)}`,
+      clientName: input.clientName,
+      redirectUris: [...input.redirectUris],
+      tokenEndpointAuthMethod: input.tokenEndpointAuthMethod,
+      clientSecretHash: secret?.secretHash ?? null,
+      createdAt: now,
+    })
+    .returning();
+  if (client === undefined) throw new Error("@softure-ai/mcp-access: inserting an OAuth client returned no row");
+  return { client, clientSecret: secret?.secret ?? null };
+}
+
+export async function findOAuthClient(ctx: McpAccessContext, clientId: string): Promise<OAuthClientRow | null> {
+  if (clientId === "" || clientId.length > 255) return null;
+  const [client] = await ctx.db.select().from(oauthClients).where(eq(oauthClients.clientId, clientId));
+  return client ?? null;
+}
+
+/**
+ * Whether the client authenticated: a confidential client with its secret (constant-time
+ * compare), a public client by presenting none.
+ */
+export function isClientSecretValid(client: OAuthClientRow, secret: string | null): boolean {
+  if (client.clientSecretHash === null) return secret === null;
+  if (secret === null || secret.length > MAX_SECRET_LENGTH) return false;
+  const expected = Buffer.from(client.clientSecretHash);
+  const actual = Buffer.from(hashAccessToken(secret));
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+
+export interface CreateAuthorizationCodeInput {
+  /** The client's row id (`OAuthClientRow.id`), not its public client id. */
+  readonly clientRowId: string;
+  /** The person who consented, from the session. */
+  readonly userId: string;
+  readonly redirectUri: string;
+  readonly codeChallenge: string;
+  /** Asked for by the client, allowed by the app and ticked by the person. */
+  readonly canWrite: boolean;
+}
+
+/** Issues a code after the person's consent. Expired codes are deleted on the way. */
+export async function createAuthorizationCode(ctx: McpAccessContext, input: CreateAuthorizationCodeInput): Promise<string> {
+  const now = ctx.clock.now();
+  const lifetimeMs = getMcpAccessOptions(ctx.config).oauth.authorizationCodeLifetimeMinutes * MINUTE_MS;
+  const { secret: code, secretHash: codeHash } = createSecret(CONSENT_CODE_PREFIX);
+  await ctx.db.delete(oauthAuthorizationCodes).where(lte(oauthAuthorizationCodes.expiresAt, now));
+  await ctx.db.insert(oauthAuthorizationCodes).values({
+    codeHash,
+    clientId: input.clientRowId,
+    userId: input.userId,
+    redirectUri: input.redirectUri,
+    codeChallenge: input.codeChallenge,
+    canWrite: input.canWrite,
+    expiresAt: new Date(now.getTime() + lifetimeMs),
+    createdAt: now,
+  });
+  return code;
+}
+
+export interface ExchangeAuthorizationCodeInput {
+  readonly code: string;
+  /** The authenticated client. */
+  readonly client: OAuthClientRow;
+  /** Null when the client left it out; allowed only when it registered exactly one. */
+  readonly redirectUri: string | null;
+  readonly codeVerifier: string;
+}
+
+/**
+ * Exchanges a code for tokens (RFC 6749 §4.1.3, PKCE per RFC 7636 §4.6), or null for any refusal.
+ *
+ * The code is burned first, by a conditional `UPDATE … WHERE used_at IS NULL`: a wrong verifier,
+ * another client or another redirect URI leave a dead code, not an invitation to keep guessing,
+ * and two parallel exchanges cannot both win. A second use of a used code revokes the grant
+ * issued from it (RFC 6749 §4.1.2): two parties saw the code. A new consent of the same client
+ * replaces its grant, whose tokens go by cascade.
+ */
+export async function exchangeAuthorizationCode(ctx: McpAccessContext, input: ExchangeAuthorizationCodeInput): Promise<IssuedOAuthTokens | null> {
+  if (input.code.length > MAX_SECRET_LENGTH) return null;
+  const now = ctx.clock.now();
+  const codeHash = hashAccessToken(input.code);
+  return ctx.db.transaction(async (tx): Promise<IssuedOAuthTokens | null> => {
+    const [code] = await tx
+      .update(oauthAuthorizationCodes)
+      .set({ usedAt: now })
+      .where(and(eq(oauthAuthorizationCodes.codeHash, codeHash), isNull(oauthAuthorizationCodes.usedAt), gt(oauthAuthorizationCodes.expiresAt, now)))
+      .returning();
+    if (code === undefined) {
+      await revokeGrantOfReusedCode(tx, codeHash);
+      return null;
+    }
+
+    const redirectUri = input.redirectUri ?? (input.client.redirectUris.length === 1 ? (input.client.redirectUris[0] ?? null) : null);
+    if (code.clientId !== input.client.id || code.redirectUri !== redirectUri || !isPkceVerifierValid(input.codeVerifier, code.codeChallenge)) {
+      return null;
+    }
+
+    await tx.delete(oauthGrants).where(and(eq(oauthGrants.userId, code.userId), eq(oauthGrants.clientId, code.clientId)));
+    const { secret: refreshToken, secretHash: refreshTokenHash } = createSecret(REFRESH_TOKEN_PREFIX);
+    const [grant] = await tx
+      .insert(oauthGrants)
+      .values({
+        userId: code.userId,
+        clientId: code.clientId,
+        canWrite: code.canWrite,
+        refreshTokenHash,
+        refreshExpiresAt: getRefreshExpiry(ctx, now),
+        createdAt: now,
+      })
+      .returning();
+    if (grant === undefined) throw new Error("@softure-ai/mcp-access: inserting an OAuth grant returned no row");
+    return issueGrantTokens(ctx, tx, { grant, clientName: input.client.clientName, refreshToken, now });
+  });
+}
+
+export interface RefreshOAuthGrantInput {
+  readonly refreshToken: string;
+  /** The authenticated client: a grant answers only the client it was issued to. */
+  readonly client: OAuthClientRow;
+}
+
+/**
+ * Refreshes a grant: a new access token and a new refresh token (rotation, OAuth 2.1 §4.3.1). The
+ * presented hash moves to `previous_refresh_token_hash` in the same conditional `UPDATE` that
+ * checks it is current; presenting it again later deletes the whole grant, for both parties.
+ */
+export async function refreshMcpGrant(ctx: McpAccessContext, input: RefreshOAuthGrantInput): Promise<IssuedOAuthTokens | null> {
+  if (input.refreshToken.length > MAX_SECRET_LENGTH) return null;
+  const now = ctx.clock.now();
+  const presentedHash = hashAccessToken(input.refreshToken);
+  return ctx.db.transaction(async (tx): Promise<IssuedOAuthTokens | null> => {
+    const { secret: refreshToken, secretHash: refreshTokenHash } = createSecret(REFRESH_TOKEN_PREFIX);
+    const [grant] = await tx
+      .update(oauthGrants)
+      .set({ refreshTokenHash, previousRefreshTokenHash: presentedHash, refreshExpiresAt: getRefreshExpiry(ctx, now) })
+      .where(and(eq(oauthGrants.refreshTokenHash, presentedHash), eq(oauthGrants.clientId, input.client.id), gt(oauthGrants.refreshExpiresAt, now)))
+      .returning();
+    if (grant === undefined) {
+      // A token from before a rotation: two parties hold it, so the grant goes for both.
+      await tx.delete(oauthGrants).where(eq(oauthGrants.previousRefreshTokenHash, presentedHash));
+      return null;
+    }
+    // The grant's spent access tokens; the current ones stay valid until they expire.
+    await tx.delete(accessTokens).where(and(eq(accessTokens.grantId, grant.id), lte(accessTokens.expiresAt, now)));
+    return issueGrantTokens(ctx, tx, { grant, clientName: input.client.clientName, refreshToken, now });
+  });
+}
+
+function getRefreshExpiry(ctx: McpAccessContext, now: Date): Date {
+  return new Date(now.getTime() + getMcpAccessOptions(ctx.config).oauth.refreshTokenLifetimeDays * DAY_MS);
+}
+
+/** The grant's access token, a row of `access_tokens` named after the client. */
+async function issueGrantTokens(
+  ctx: McpAccessContext,
+  tx: Transaction,
+  input: { readonly grant: { readonly id: string; readonly userId: string; readonly canWrite: boolean }; readonly clientName: string; readonly refreshToken: string; readonly now: Date },
+): Promise<IssuedOAuthTokens> {
+  const lifetimeMs = getMcpAccessOptions(ctx.config).oauth.accessTokenLifetimeMinutes * MINUTE_MS;
+  const { secret: accessToken, secretHash: tokenHash } = createSecret(ACCESS_TOKEN_PREFIX);
+  await tx.insert(accessTokens).values({
+    userId: input.grant.userId,
+    grantId: input.grant.id,
+    name: input.clientName,
+    tokenHash,
+    canWrite: input.grant.canWrite,
+    createdAt: input.now,
+    expiresAt: new Date(input.now.getTime() + lifetimeMs),
+  });
+  return { accessToken, refreshToken: input.refreshToken, expiresIn: lifetimeMs / 1000, canWrite: input.grant.canWrite };
+}
+
+/** A used code presented again revokes the grant its first use produced (same account and client). */
+async function revokeGrantOfReusedCode(tx: Transaction, codeHash: string): Promise<void> {
+  const [reused] = await tx
+    .select({ userId: oauthAuthorizationCodes.userId, clientId: oauthAuthorizationCodes.clientId })
+    .from(oauthAuthorizationCodes)
+    .where(and(eq(oauthAuthorizationCodes.codeHash, codeHash), isNotNull(oauthAuthorizationCodes.usedAt)));
+  if (reused === undefined) return;
+  await tx.delete(oauthGrants).where(and(eq(oauthGrants.userId, reused.userId), eq(oauthGrants.clientId, reused.clientId)));
+}
+
+/** The owner's unexpired grants, newest first: the connected apps list. */
+export async function listOAuthGrants(ctx: McpAccessContext, userId: string): Promise<OAuthGrantView[]> {
+  return ctx.db
+    .select({
+      id: oauthGrants.id,
+      clientName: oauthClients.clientName,
+      canWrite: oauthGrants.canWrite,
+      createdAt: oauthGrants.createdAt,
+      lastUsedAt: oauthGrants.lastUsedAt,
+    })
+    .from(oauthGrants)
+    .innerJoin(oauthClients, eq(oauthGrants.clientId, oauthClients.id))
+    .where(and(eq(oauthGrants.userId, userId), gt(oauthGrants.refreshExpiresAt, ctx.clock.now())))
+    .orderBy(desc(oauthGrants.createdAt), desc(oauthGrants.id));
+}
+
+export interface RevokeOAuthGrantInput {
+  /** The owner, from the session. */
+  readonly userId: string;
+  /** From the form: any value, including another account's grant id. */
+  readonly grantId: string;
+}
+
+const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Revokes a grant at once: its refresh token goes with the row and its access tokens by cascade,
+ * so the assistant's next request gets 401. The owner is part of the `WHERE`.
+ */
+export async function revokeOAuthGrant(ctx: McpAccessContext, input: RevokeOAuthGrantInput): Promise<Ok<undefined> | Err<"mcp-access.grant_not_found">> {
+  if (!UUID_SHAPE.test(input.grantId)) return err("mcp-access.grant_not_found");
+  const removed = await ctx.db
+    .delete(oauthGrants)
+    .where(and(eq(oauthGrants.userId, input.userId), eq(oauthGrants.id, input.grantId)))
+    .returning();
+  return removed.length > 0 ? ok() : err("mcp-access.grant_not_found");
+}
+
+export interface PrunedOAuthRecords {
+  readonly codes: number;
+  readonly grants: number;
+  readonly clients: number;
+}
+
+/**
+ * Deletes expired codes, grants whose refresh token expired (their access tokens by cascade) and
+ * abandoned clients, of every account: for a scheduled job, next to `pruneAccessTokens`.
+ */
+export async function pruneOAuthRecords(ctx: McpAccessContext): Promise<PrunedOAuthRecords> {
+  const now = ctx.clock.now();
+  const codes = await ctx.db.delete(oauthAuthorizationCodes).where(lte(oauthAuthorizationCodes.expiresAt, now)).returning();
+  const grants = await ctx.db.delete(oauthGrants).where(lte(oauthGrants.refreshExpiresAt, now)).returning();
+  const clients = await deleteStaleClients(ctx, now);
+  return { codes: codes.length, grants: grants.length, clients };
+}
+
+/** Clients without a grant, registered more than a day ago; they give nobody any access. */
+async function deleteStaleClients(ctx: McpAccessContext, now: Date): Promise<number> {
+  const removed = await ctx.db
+    .delete(oauthClients)
+    .where(
+      and(
+        lt(oauthClients.createdAt, new Date(now.getTime() - STALE_CLIENT_MS)),
+        notExists(ctx.db.select({ id: oauthGrants.id }).from(oauthGrants).where(eq(oauthGrants.clientId, oauthClients.id))),
+      ),
+    )
+    .returning();
+  return removed.length;
+}

package/src/server/options.ts

@@ -2,6 +2,7 @@
 import { getModule, type Locale, type SoftureConfig } from "@softure-ai/core";
 import type { McpAccessMessages } from "../messages/index.js";
 import type { McpAccessOptions } from "../options.js";
+import type { McpOrigins } from "../origins.js";
 
 const MODULE_ID = "mcp-access";
 
@@ -24,6 +25,14 @@ export interface McpAccessRoutes {
   readonly page: string;
   /** `POST` MCP endpoint. */
   readonly endpoint: string;
+  /** OAuth consent page (`GET`): the authorization endpoint clients send the person to. */
+  readonly oauthConsent: string;
+  /** `POST` target of the consent form; answers `303` to the client's redirect URI. */
+  readonly oauthDecision: string;
+  /** `POST` OAuth token endpoint. */
+  readonly oauthToken: string;
+  /** `POST` dynamic client registration (RFC 7591). */
+  readonly oauthRegister: string;
 }
 
 export function getMcpAccessRoutes(config: SoftureConfig): McpAccessRoutes {
@@ -34,12 +43,19 @@ export function getMcpAccessRoutes(config: SoftureConfig): McpAccessRoutes {
     if (path === undefined) throw new Error(`@softure-ai/mcp-access: route "${name}" is missing from the module manifest`);
     return path;
   };
-  return { page: read("page"), endpoint: read("endpoint") };
+  return {
+    page: read("page"),
+    endpoint: read("endpoint"),
+    oauthConsent: read("oauthConsent"),
+    oauthDecision: read("oauthDecision"),
+    oauthToken: read("oauthToken"),
+    oauthRegister: read("oauthRegister"),
+  };
 }
 
-/** The absolute URL MCP clients call: the app's origin and the endpoint route. */
-export function getMcpEndpointUrl(config: SoftureConfig): string {
-  return new URL(getMcpAccessRoutes(config).endpoint, config.appOrigin).toString();
+/** The absolute URL MCP clients call: the app's origin (the request's, when given) and the endpoint route. */
+export function getMcpEndpointUrl(config: SoftureConfig, origins?: McpOrigins): string {
+  return new URL(getMcpAccessRoutes(config).endpoint, origins?.appOrigin ?? config.appOrigin).toString();
 }
 
 /** The module's copy in the app's locale, with the app's overrides applied. */

package/src/server/origins.ts

@@ -0,0 +1,19 @@
+// The origins of one request, from the app's options: `resolveAppOrigin` when it answers, else the
+// configured `appOrigin`, plus `resourceOrigins`.
+import type { SoftureConfig } from "@softure-ai/core";
+import { isBareOrigin } from "../options.js";
+import type { McpOriginRequest, McpOrigins } from "../origins.js";
+import { getMcpAccessOptions } from "./options.js";
+
+/**
+ * The origins for `request`, or the configured ones without a request. A resolver that returns
+ * something other than a bare http(s) origin is a setup bug: thrown by name, never served.
+ */
+export function resolveMcpOrigins(config: SoftureConfig, request?: McpOriginRequest | null): McpOrigins {
+  const options = getMcpAccessOptions(config);
+  const resolved = request === undefined || request === null || options.resolveAppOrigin === undefined ? null : options.resolveAppOrigin(request);
+  if (resolved !== null && !isBareOrigin(resolved)) {
+    throw new Error(`@softure-ai/mcp-access: resolveAppOrigin returned "${resolved.slice(0, 100)}", which is not an http(s) origin without a path`);
+  }
+  return { appOrigin: new URL(resolved ?? config.appOrigin).origin, resourceOrigins: options.resourceOrigins };
+}

package/src/server/pkce.ts

@@ -0,0 +1,27 @@
+// PKCE S256 (RFC 7636 §4.6), the only method accepted: OAuth 2.1 and the MCP authorization spec
+// require it, and `plain` hands the verifier to anyone who saw the authorization URL.
+import { createHash, timingSafeEqual } from "node:crypto";
+
+export const PKCE_METHOD = "S256";
+
+/** RFC 7636 §4.1: 43 to 128 unreserved characters. A shorter one carries too little entropy. */
+const VERIFIER_PATTERN = /^[A-Za-z0-9._~-]{43,128}$/;
+/** base64url of a sha256 without padding: always 43 characters. */
+const CHALLENGE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+
+export function isValidCodeChallenge(challenge: string): boolean {
+  return CHALLENGE_PATTERN.test(challenge);
+}
+
+/** `BASE64URL(SHA256(ASCII(code_verifier)))`. */
+export function getCodeChallenge(verifier: string): string {
+  return createHash("sha256").update(verifier, "ascii").digest("base64url");
+}
+
+/** Whether the verifier matches the challenge stored with the code; compared in constant time. */
+export function isPkceVerifierValid(verifier: string, challenge: string): boolean {
+  if (!VERIFIER_PATTERN.test(verifier) || !isValidCodeChallenge(challenge)) return false;
+  const expected = Buffer.from(challenge);
+  const actual = Buffer.from(getCodeChallenge(verifier));
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}

package/src/server/privacy.ts

@@ -1,10 +1,10 @@
 // The mcp-access part of a GDPR export and deletion (`@softure-ai/privacy`): the user's access
-// tokens, by name and dates. Never a token hash. Deletion removes the tokens by name before auth
-// deletes the account, so it does not rest on the foreign key's cascade alone.
+// tokens and connected apps (OAuth grants), by name and dates. Never a hash. Deletion removes them
+// by name before auth deletes the account, so it does not rest on the foreign keys' cascade alone.
 import { ok, type ModuleContext, type Ok, type PrivacyContributor } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
-import { asc, eq } from "drizzle-orm";
-import { accessTokens } from "../schema.js";
+import { and, asc, eq, isNull } from "drizzle-orm";
+import { accessTokens, oauthAuthorizationCodes, oauthClients, oauthGrants } from "../schema.js";
 
 /** What mcp-access holds about one user, as it appears in their export. */
 export interface McpAccessUserData {
@@ -15,15 +15,22 @@ export interface McpAccessUserData {
     readonly expiresAt: Date;
     readonly lastUsedAt: Date | null;
   }[];
+  /** Apps connected through OAuth; their short-lived access tokens are not listed one by one. */
+  readonly connectedApps: readonly {
+    readonly clientName: string;
+    readonly canWrite: boolean;
+    readonly createdAt: Date;
+    readonly lastUsedAt: Date | null;
+  }[];
 }
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 export async function exportMcpAccessUserData(context: ModuleContext, userId: string): Promise<Ok<McpAccessUserData>> {
-  if (!UUID.test(userId)) return ok({ accessTokens: [] });
+  if (!UUID.test(userId)) return ok({ accessTokens: [], connectedApps: [] });
   // Core types `db` as unknown; privacy passes the @softure-ai/db handle or its transaction.
   const db = context.db as Queryable;
-  const rows = await db
+  const tokens = await db
     .select({
       name: accessTokens.name,
       canWrite: accessTokens.canWrite,
@@ -32,14 +39,24 @@ export async function exportMcpAccessUserData(context: ModuleContext, userId: st
       lastUsedAt: accessTokens.lastUsedAt,
     })
     .from(accessTokens)
-    .where(eq(accessTokens.userId, userId))
+    .where(and(eq(accessTokens.userId, userId), isNull(accessTokens.grantId)))
     .orderBy(asc(accessTokens.createdAt));
-  return ok({ accessTokens: rows });
+  const connectedApps = await db
+    .select({ clientName: oauthClients.clientName, canWrite: oauthGrants.canWrite, createdAt: oauthGrants.createdAt, lastUsedAt: oauthGrants.lastUsedAt })
+    .from(oauthGrants)
+    .innerJoin(oauthClients, eq(oauthGrants.clientId, oauthClients.id))
+    .where(eq(oauthGrants.userId, userId))
+    .orderBy(asc(oauthGrants.createdAt));
+  return ok({ accessTokens: tokens, connectedApps });
 }
 
 export async function deleteMcpAccessUserData(context: ModuleContext, userId: string): Promise<Ok<undefined>> {
   if (!UUID.test(userId)) return ok();
-  await (context.db as Queryable).delete(accessTokens).where(eq(accessTokens.userId, userId));
+  const db = context.db as Queryable;
+  await db.delete(oauthAuthorizationCodes).where(eq(oauthAuthorizationCodes.userId, userId));
+  // A grant's access tokens go with it by cascade; the next line takes the hand-issued ones.
+  await db.delete(oauthGrants).where(eq(oauthGrants.userId, userId));
+  await db.delete(accessTokens).where(eq(accessTokens.userId, userId));
   return ok();
 }
 

package/src/server/scopes.ts

@@ -0,0 +1,6 @@
+// The two scopes of the MCP endpoint, shared by the Bearer check and the OAuth server.
+
+/** 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";

package/src/server/tokens.ts

@@ -1,13 +1,13 @@
-// Access tokens (FIRE_TRACKER `src/db/access-tokens.ts`, generalised). A token is `sftmcp_` and 32
-// random bytes; the database holds only its sha256, so a leaked row cannot be replayed. The
-// plaintext leaves this file once, in the result of `issueAccessToken`.
+// Access tokens (an adopting app's token code, generalised). A token is `sftmcp_` and 32 random
+// bytes; the database holds only its sha256, so a leaked row cannot be replayed. The plaintext
+// leaves this file once, in the result of `issueAccessToken` (or of an OAuth exchange, `oauth.ts`).
 import { createHash, randomBytes } from "node:crypto";
 import { err, errorLogLabel, ok, type Err, type ModuleContext, type Ok } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
 import { and, count, desc, eq, gt, isNull, lt, lte, or, sql } from "drizzle-orm";
 import type { AccessTokenView } from "../contract.js";
-import { MAX_TOKEN_NAME_LENGTH } from "../options.js";
-import { accessTokens } from "../schema.js";
+import { MAX_PRESENTED_TOKEN_LENGTH, MAX_TOKEN_NAME_LENGTH, type McpAccessOptions } from "../options.js";
+import { accessTokens, oauthGrants } from "../schema.js";
 import { getMcpAccessOptions } from "./options.js";
 
 export type McpAccessContext = ModuleContext<Queryable>;
@@ -27,14 +27,25 @@ export function hashAccessToken(token: string): string {
   return createHash("sha256").update(token, "utf8").digest("hex");
 }
 
-/** Whether a presented value could be a token at all; anything else is not looked up. */
+/** Whether a presented value has the module's token shape. */
 export function isAccessTokenShape(token: string): boolean {
   return TOKEN_SHAPE.test(token);
 }
 
-function createAccessTokenSecret(): { readonly token: string; readonly tokenHash: string } {
-  const token = `${ACCESS_TOKEN_PREFIX}${randomBytes(TOKEN_BYTES).toString("base64url")}`;
-  return { token, tokenHash: hashAccessToken(token) };
+/**
+ * Whether a presented value is looked up at all: the module's shape, or the app's
+ * `legacyTokenPattern` for tokens issued before the module. The length cap runs first, so no
+ * pattern ever sees a huge header.
+ */
+function isAcceptedTokenShape(options: McpAccessOptions, token: string): boolean {
+  if (token.length > MAX_PRESENTED_TOKEN_LENGTH) return false;
+  return isAccessTokenShape(token) || (options.legacyTokenPattern?.test(token) ?? false);
+}
+
+/** A new secret with the given prefix and its hash; the plaintext is returned once, never stored. */
+export function createSecret(prefix: string): { readonly secret: string; readonly secretHash: string } {
+  const secret = `${prefix}${randomBytes(TOKEN_BYTES).toString("base64url")}`;
+  return { secret, secretHash: hashAccessToken(secret) };
 }
 
 export interface IssueAccessTokenInput {
@@ -77,10 +88,14 @@ export async function issueAccessToken(ctx: McpAccessContext, input: IssueAccess
   return ctx.db.transaction(async (tx): Promise<IssueAccessTokenResult> => {
     await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${`mcp-access:${input.userId}`}, 0))`);
     await tx.delete(accessTokens).where(and(eq(accessTokens.userId, input.userId), lte(accessTokens.expiresAt, now)));
-    const [held] = await tx.select({ total: count() }).from(accessTokens).where(eq(accessTokens.userId, input.userId));
+    // OAuth access tokens belong to their grant and rotate every hour: they do not take places.
+    const [held] = await tx
+      .select({ total: count() })
+      .from(accessTokens)
+      .where(and(eq(accessTokens.userId, input.userId), isNull(accessTokens.grantId)));
     if ((held?.total ?? 0) >= options.maxTokensPerUser) return err("mcp-access.token_limit_reached");
 
-    const { token, tokenHash } = createAccessTokenSecret();
+    const { secret: token, secretHash: tokenHash } = createSecret(ACCESS_TOKEN_PREFIX);
     const [row] = await tx
       .insert(accessTokens)
       .values({ userId: input.userId, name, tokenHash, canWrite, createdAt: now, expiresAt })
@@ -90,7 +105,10 @@ export async function issueAccessToken(ctx: McpAccessContext, input: IssueAccess
   });
 }
 
-/** The owner's tokens, newest first, expired ones included (the list marks them). */
+/**
+ * The owner's hand-issued tokens, newest first, expired ones included (the list marks them).
+ * OAuth access tokens are left out: the page shows their grants instead.
+ */
 export async function listAccessTokens(ctx: McpAccessContext, userId: string): Promise<AccessTokenView[]> {
   return ctx.db
     .select({
@@ -102,7 +120,7 @@ export async function listAccessTokens(ctx: McpAccessContext, userId: string): P
       lastUsedAt: accessTokens.lastUsedAt,
     })
     .from(accessTokens)
-    .where(eq(accessTokens.userId, userId))
+    .where(and(eq(accessTokens.userId, userId), isNull(accessTokens.grantId)))
     .orderBy(desc(accessTokens.createdAt), desc(accessTokens.id));
 }
 
@@ -114,8 +132,9 @@ export interface RevokeAccessTokenInput {
 }
 
 /**
- * Deletes a token at once; the next request with it gets 401. The owner is part of the `WHERE`,
- * so another account's id matches no row instead of relying on a comparison here.
+ * Deletes a hand-issued token at once; the next request with it gets 401. The owner is part of the
+ * `WHERE`, so another account's id matches no row instead of relying on a comparison here. An
+ * OAuth access token is revoked with its grant (`revokeOAuthGrant`).
  */
 export async function revokeAccessToken(
   ctx: McpAccessContext,
@@ -124,7 +143,7 @@ export async function revokeAccessToken(
   if (!UUID_SHAPE.test(input.tokenId)) return err("mcp-access.token_not_found");
   const removed = await ctx.db
     .delete(accessTokens)
-    .where(and(eq(accessTokens.userId, input.userId), eq(accessTokens.id, input.tokenId)))
+    .where(and(eq(accessTokens.userId, input.userId), eq(accessTokens.id, input.tokenId), isNull(accessTokens.grantId)))
     .returning();
   return removed.length > 0 ? ok() : err("mcp-access.token_not_found");
 }
@@ -136,6 +155,8 @@ export interface VerifiedAccessToken {
   /** Effective write access: the token was issued for writes and the app allows them now. */
   readonly canWrite: boolean;
   readonly expiresAt: Date;
+  /** The OAuth grant the token was issued from; null for a hand-issued token. */
+  readonly grantId: string | null;
 }
 
 /**
@@ -145,39 +166,55 @@ export interface VerifiedAccessToken {
  * fail the request. Database failures of the lookup propagate.
  */
 export async function verifyAccessToken(ctx: McpAccessContext, token: string): Promise<VerifiedAccessToken | null> {
-  if (!isAccessTokenShape(token)) return null;
+  const options = getMcpAccessOptions(ctx.config);
+  if (!isAcceptedTokenShape(options, token)) return null;
   const now = ctx.clock.now();
   const [row] = await ctx.db
-    .select({ id: accessTokens.id, userId: accessTokens.userId, canWrite: accessTokens.canWrite, expiresAt: accessTokens.expiresAt })
+    .select({
+      id: accessTokens.id,
+      userId: accessTokens.userId,
+      canWrite: accessTokens.canWrite,
+      expiresAt: accessTokens.expiresAt,
+      grantId: accessTokens.grantId,
+    })
     .from(accessTokens)
     .where(and(eq(accessTokens.tokenHash, hashAccessToken(token)), gt(accessTokens.expiresAt, now)));
   if (row === undefined) return null;
 
-  await recordUse(ctx, row.id, now);
+  await recordUse(ctx, row, now);
   return {
     tokenId: row.id,
     userId: row.userId,
-    canWrite: row.canWrite && getMcpAccessOptions(ctx.config).allowWrites,
+    canWrite: row.canWrite && options.allowWrites,
     expiresAt: row.expiresAt,
+    grantId: row.grantId,
   };
 }
 
-async function recordUse(ctx: McpAccessContext, tokenId: string, now: Date): Promise<void> {
+/** Records the use on the token and, for an OAuth token, on its grant (the connected apps list). */
+async function recordUse(ctx: McpAccessContext, token: { readonly id: string; readonly grantId: string | null }, now: Date): Promise<void> {
   const staleBefore = new Date(now.getTime() - LAST_USED_RESOLUTION_MS);
   try {
     await ctx.db
       .update(accessTokens)
       .set({ lastUsedAt: now })
-      .where(and(eq(accessTokens.id, tokenId), or(isNull(accessTokens.lastUsedAt), lt(accessTokens.lastUsedAt, staleBefore))));
+      .where(and(eq(accessTokens.id, token.id), or(isNull(accessTokens.lastUsedAt), lt(accessTokens.lastUsedAt, staleBefore))));
+    if (token.grantId !== null) {
+      await ctx.db
+        .update(oauthGrants)
+        .set({ lastUsedAt: now })
+        .where(and(eq(oauthGrants.id, token.grantId), or(isNull(oauthGrants.lastUsedAt), lt(oauthGrants.lastUsedAt, staleBefore))));
+    }
   } catch (error) {
     // The token id is not a secret; the token is never logged.
-    console.error(`@softure-ai/mcp-access: recording the use of token ${tokenId} failed: ${errorLogLabel(error)}`);
+    console.error(`@softure-ai/mcp-access: recording the use of token ${token.id} failed: ${errorLogLabel(error)}`);
   }
 }
 
 /**
- * Deletes every expired token, of every account. Issuing already removes the issuer's own; an app
- * may call this from a scheduled job so abandoned accounts do not keep dead rows.
+ * Deletes every expired token, of every account, hand-issued and OAuth alike. Issuing already
+ * removes the issuer's own; an app may call this from a scheduled job so abandoned accounts do not
+ * keep dead rows (with `pruneOAuthRecords` for codes, grants and clients).
  */
 export async function pruneAccessTokens(ctx: McpAccessContext): Promise<number> {
   const removed = await ctx.db