@softure-ai/mcp-access 0.2.9 → 0.4.0

package/src/server/prune.ts

@@ -1,14 +1,27 @@
-// The module's scheduled cleanup: expired access tokens and dead OAuth records of every account, in
-// one call for a daily job (`softure-mcp prune`, a deploy `maintain` hook) instead of inline on requests.
+// The module's scheduled cleanup: expired access tokens, dead OAuth records of every account, used
+// confirmation tokens and MCP tasks past their expiry, in one call for a daily job (`softure-mcp prune`, a deploy `maintain` hook) instead of inline on requests.
+import { lte } from "drizzle-orm";
+import { operationTasks } from "../schema.js";
+import { pruneUsedConfirmations } from "./confirmation.js";
 import { pruneOAuthRecords, type PrunedOAuthRecords } from "./oauth.js";
 import { pruneAccessTokens, type McpAccessContext } from "./tokens.js";
 
 export interface PrunedMcpAccessRecords extends PrunedOAuthRecords {
   readonly accessTokens: number;
+  readonly usedConfirmations: number;
+  readonly operationTasks: number;
 }
 
-/** Runs `pruneAccessTokens`, then `pruneOAuthRecords`, and counts what each removed. */
+/** Runs `pruneAccessTokens`, `pruneOAuthRecords`, `pruneUsedConfirmations`, then `pruneOperationTasks`, and counts what each removed. */
 export async function pruneMcpAccess(ctx: McpAccessContext): Promise<PrunedMcpAccessRecords> {
   const accessTokens = await pruneAccessTokens(ctx);
-  return { accessTokens, ...(await pruneOAuthRecords(ctx)) };
+  const oauth = await pruneOAuthRecords(ctx);
+  const usedConfirmations = await pruneUsedConfirmations(ctx);
+  return { accessTokens, ...oauth, usedConfirmations, operationTasks: await pruneOperationTasks(ctx) };
+}
+
+/** Deletes the MCP tasks past their expiry (#977); the operations' jobs stay with `@softure-ai/jobs`. */
+export async function pruneOperationTasks(ctx: McpAccessContext): Promise<number> {
+  const removed = await ctx.db.delete(operationTasks).where(lte(operationTasks.expiresAt, ctx.clock.now())).returning({ taskId: operationTasks.taskId });
+  return removed.length;
 }

package/src/server/strict-input.ts

@@ -3,8 +3,8 @@
 // `withStrictToolInput` rewrites every input schema once, at registration: each object refuses a field
 // it does not know and names the ones it accepts, a field sent under its old name is refused with the
 // stable code `input.field_renamed`, and boolean and number fields also take their exact text (a client
-// on an older tool list sends a field it does not know as text). The SDK validates before the handler
-// runs, so a refused call saves nothing.
+// on an older tool list sends a field it does not know as text). A tool registered without an input schema
+// gets the strict empty object. The SDK validates before the handler runs, so a refused call saves nothing.
 //
 //   const server = withStrictToolInput(new McpServer({ name: "acme", version }), { renamedFields: { notes: "note" } });
 import type { McpServer } from "@modelcontextprotocol/server";
@@ -16,9 +16,12 @@ import { en } from "../messages/en.js";
 /** The texts of a refused field: `toolInput` of the module dictionary (`getMcpAccessMessages(config).toolInput`). */
 export type StrictToolInputMessages = typeof en.toolInput;
 
+/** Old field name → new field name, as a map or a rule (`undefined`: not renamed). */
+export type RenamedFields = Readonly<Record<string, string>> | ((field: string) => string | undefined);
+
 export interface StrictToolInputOptions {
   /** Old field name → new field name, refused as `input.field_renamed` wherever an object accepts the new name. */
-  readonly renamedFields?: Readonly<Record<string, string>>;
+  readonly renamedFields?: RenamedFields;
   /** Boolean fields also take `"true"`/`"false"` and number fields a number written as text. Default: `true`. */
   readonly coerceTextScalars?: boolean;
   /** Default: the module's English dictionary. */
@@ -32,14 +35,20 @@ const strictServers = new WeakSet<McpServer>();
 
 type ToolConfig = Readonly<Record<string, unknown>> & { readonly inputSchema?: unknown };
 type RegisterTool = (name: string, config: ToolConfig, callback: unknown) => unknown;
+type ContextCallback = (ctx: unknown) => unknown;
 
 /** Makes every tool registered on the server from now on strict; wrapping a server twice changes nothing. */
 export function withStrictToolInput<Server extends McpServer>(server: Server, options: StrictToolInputOptions = {}): Server {
   if (strictServers.has(server)) return server;
   // The SDK's overloads only differ in how the schema is typed; at runtime it is one method.
   const register = server.registerTool.bind(server) as unknown as RegisterTool;
-  const registerStrict: RegisterTool = (name, config, callback) =>
-    register(name, config.inputSchema === undefined ? config : { ...config, inputSchema: toStrictToolInput(config.inputSchema, options) }, callback);
+  const registerStrict: RegisterTool = (name, config, callback) => {
+    if (config.inputSchema !== undefined) return register(name, { ...config, inputSchema: toStrictToolInput(config.inputSchema, options) }, callback);
+    // Without a schema the SDK skips validation and calls `callback(ctx)`; with the strict empty object it calls
+    // `callback(args, ctx)`, so the callback keeps receiving the context only.
+    const contextCallback = callback as ContextCallback;
+    return register(name, { ...config, inputSchema: toStrictToolInput(z.object({}), options) }, (_args: unknown, ctx: unknown) => contextCallback(ctx));
+  };
   Object.defineProperty(server, "registerTool", { value: registerStrict, configurable: true, writable: true });
   strictServers.add(server);
   return server;
@@ -50,7 +59,7 @@ export function toStrictToolInput(schema: unknown, options: StrictToolInputOptio
   const zodSchema = isZodSchema(schema) ? schema : isRawShape(schema) ? z.object(schema) : null;
   if (zodSchema === null) return schema;
   const rewriter = new StrictRewriter({
-    renamedFields: options.renamedFields ?? {},
+    renameField: toRenameRule(options.renamedFields ?? {}),
     coerceTextScalars: options.coerceTextScalars ?? true,
     messages: options.messages ?? en.toolInput,
   });
@@ -66,7 +75,19 @@ function isRawShape(value: unknown): value is Record<string, core.$ZodType> {
   return Object.values(value).every(isZodSchema);
 }
 
-type RewriteSettings = Required<StrictToolInputOptions>;
+function toRenameRule(renamedFields: RenamedFields): (field: string) => string | undefined {
+  if (typeof renamedFields === "function") return renamedFields;
+  return (field) => (Object.hasOwn(renamedFields, field) ? renamedFields[field] : undefined);
+}
+
+interface RewriteSettings {
+  readonly renameField: (field: string) => string | undefined;
+  readonly coerceTextScalars: boolean;
+  readonly messages: StrictToolInputMessages;
+}
+
+/** Wrappers that keep the value's kind: a chain of them around a scalar takes the text step around the whole chain. */
+const WRAPPER_TYPES = new Set(["optional", "nullable", "default", "prefault", "nonoptional", "readonly", "catch"]);
 
 /** A schema node as the rewriter reads it: its kind and the parts it rewrites. */
 type AnyDef = core.$ZodTypeDef & Record<string, unknown>;
@@ -98,8 +119,13 @@ class StrictRewriter {
       case "prefault":
       case "nonoptional":
       case "readonly":
-      case "catch":
+      case "catch": {
+        // Outside the chain, zod still lists its `default` (it drops one on a transforming node) and the field's
+        // optionality is the chain's own; the step passes `undefined` and `null` through to it.
+        const reader = this.findTextReader(schema);
+        if (reader !== undefined) return withTextStep(reader, schema);
         return this.cloneWith(schema, { innerType: this.rewrite(def.innerType as core.$ZodType) });
+      }
       case "union":
         return this.cloneWith(schema, { options: (def.options as core.$ZodType[]).map((option) => this.rewrite(option)) });
       case "intersection":
@@ -118,14 +144,26 @@ class StrictRewriter {
         return this.cloneWith(schema, { getter: () => this.rewrite(getter()) });
       }
       case "boolean":
-        return this.settings.coerceTextScalars && def.coerce !== true ? z.preprocess(readBooleanText, schema) : schema;
-      case "number":
-        return this.settings.coerceTextScalars && def.coerce !== true ? z.preprocess(readNumberText, schema) : schema;
+      case "number": {
+        const reader = this.findTextReader(schema);
+        return reader === undefined ? schema : withTextStep(reader, schema);
+      }
       default:
         return schema;
     }
   }
 
+  /** The text reader for a boolean or number, seen through its wrapper chain; none when text is not taken. */
+  private findTextReader(schema: core.$ZodType): ((value: unknown) => unknown) | undefined {
+    if (!this.settings.coerceTextScalars) return undefined;
+    let def = schema._zod.def as AnyDef;
+    while (WRAPPER_TYPES.has(def.type)) def = (def.innerType as core.$ZodType)._zod.def as AnyDef;
+    if (def.coerce === true) return undefined;
+    if (def.type === "boolean") return readBooleanText;
+    if (def.type === "number") return readNumberText;
+    return undefined;
+  }
+
   /** Only the input side: `in`, or `out` after a preprocess (whose `in` is the transform). */
   private rewritePipe(schema: core.$ZodType, def: AnyDef): core.$ZodType {
     const input = def.in as core.$ZodType;
@@ -162,11 +200,11 @@ class StrictRewriter {
 /** The text for an object's unknown fields: renamed ones first, then the rest with the fields it accepts. */
 function describeUnknownFields(issue: core.$ZodRawIssue, accepted: readonly string[], settings: RewriteSettings): string | undefined {
   if (issue.code !== "unrecognized_keys") return undefined;
-  const { messages, renamedFields } = settings;
+  const { messages, renameField } = settings;
   const renamed: string[] = [];
   const unknown: string[] = [];
   for (const field of issue.keys) {
-    const newName = Object.hasOwn(renamedFields, field) ? renamedFields[field] : undefined;
+    const newName = renameField(field);
     if (newName !== undefined && accepted.includes(newName)) renamed.push(formatMessage(messages.fieldRenamed, { field, renamed: newName }));
     else unknown.push(field);
   }
@@ -180,6 +218,17 @@ function quoteAll(names: readonly string[]): string {
   return names.map((name) => JSON.stringify(name)).join(", ");
 }
 
+/**
+ * `schema` behind a text step. zod gives every transform an optional input, so a step would make a required field
+ * look optional in the listed JSON Schema inside `nullable` or a union; it takes the optionality of the schema it
+ * wraps instead. That changes no parse: the step passes `undefined` on, and the schema refuses it as before.
+ */
+function withTextStep(reader: (value: unknown) => unknown, schema: core.$ZodType): core.$ZodType {
+  const step = z.preprocess(reader, schema as z.ZodType);
+  Object.defineProperty(step._zod, "optin", { value: schema._zod.optin, configurable: true, writable: true });
+  return step;
+}
+
 function readBooleanText(value: unknown): unknown {
   if (value === "true") return true;
   if (value === "false") return false;

package/src/server/tokens.ts

@@ -1,11 +1,11 @@
-// 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
+// Access tokens (an adopting app's token code, generalised). An MCP token is `sftmcp_` and 32 random
+// bytes, an API token (`api-tokens.ts`) the app's prefix 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 type { AccessTokenKind, AccessTokenView } from "../contract.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";
@@ -70,22 +70,46 @@ export type IssueAccessTokenResult =
   | Err<"mcp-access.name_required" | "mcp-access.name_too_long" | "mcp-access.token_limit_reached">;
 
 /**
- * Issues a token for its owner. The per-account limit counts unexpired tokens, in one transaction
- * that holds a per-user advisory lock, so two parallel requests cannot both take the last place.
- * The owner's expired tokens are deleted first: they would otherwise count against the limit.
+ * Issues an MCP token for its owner. The per-account limit counts unexpired tokens of both kinds, in one
+ * transaction that holds a per-user advisory lock, so two parallel requests cannot both take the last
+ * place. The owner's expired tokens are deleted first: they would otherwise count against the limit.
  * Database failures propagate.
  */
 export async function issueAccessToken(ctx: McpAccessContext, input: IssueAccessTokenInput): Promise<IssueAccessTokenResult> {
+  const options = getMcpAccessOptions(ctx.config);
+  const canWrite = input.canWrite && options.allowWrites;
+  const result = await insertToken(ctx, { userId: input.userId, name: input.name, kind: "mcp", canWrite, scopes: [], secret: createSecret(ACCESS_TOKEN_PREFIX) });
+  if (!result.ok) return result;
+  const { id, token, name, expiresAt } = result.value;
+  return ok({ id, token, name, canWrite, expiresAt });
+}
+
+/** What `insertToken` stores: the new secret with its hash, write access and scopes are already decided. */
+export interface TokenInsert {
+  readonly userId: string;
+  readonly name: string;
+  readonly kind: AccessTokenKind;
+  readonly canWrite: boolean;
+  readonly scopes: readonly string[];
+  /** The plaintext and the hash the lookup will find it by (`createSecret`, or the API token's own). */
+  readonly secret: { readonly secret: string; readonly secretHash: string };
+}
+
+export type InsertTokenResult =
+  | Ok<{ readonly id: string; readonly token: string; readonly name: string; readonly expiresAt: Date }>
+  | Err<"mcp-access.name_required" | "mcp-access.name_too_long" | "mcp-access.token_limit_reached">;
+
+/** Stores a new token of either kind under the owner's lock and limit; the plaintext is returned once. */
+export async function insertToken(ctx: McpAccessContext, input: TokenInsert): Promise<InsertTokenResult> {
   const name = input.name.trim();
   if (name === "") return err("mcp-access.name_required");
   if (name.length > MAX_TOKEN_NAME_LENGTH) return err("mcp-access.name_too_long");
 
   const options = getMcpAccessOptions(ctx.config);
-  const canWrite = input.canWrite && options.allowWrites;
   const now = ctx.clock.now();
   const expiresAt = new Date(now.getTime() + options.tokenLifetimeDays * DAY_MS);
 
-  return ctx.db.transaction(async (tx): Promise<IssueAccessTokenResult> => {
+  return ctx.db.transaction(async (tx): Promise<InsertTokenResult> => {
     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)));
     // OAuth access tokens belong to their grant and rotate every hour: they do not take places.
@@ -95,25 +119,27 @@ export async function issueAccessToken(ctx: McpAccessContext, input: IssueAccess
       .where(and(eq(accessTokens.userId, input.userId), isNull(accessTokens.grantId)));
     if ((held?.total ?? 0) >= options.maxTokensPerUser) return err("mcp-access.token_limit_reached");
 
-    const { secret: token, secretHash: tokenHash } = createSecret(ACCESS_TOKEN_PREFIX);
+    const { secret: token, secretHash: tokenHash } = input.secret;
     const [row] = await tx
       .insert(accessTokens)
-      .values({ userId: input.userId, name, tokenHash, canWrite, createdAt: now, expiresAt })
+      .values({ userId: input.userId, name, tokenHash, canWrite: input.canWrite, createdAt: now, expiresAt, kind: input.kind, scopes: [...input.scopes] })
       .returning();
     if (row === undefined) throw new Error("@softure-ai/mcp-access: inserting a token returned no row");
-    return ok({ id: row.id, token, name, canWrite, expiresAt });
+    return ok({ id: row.id, token, name, expiresAt });
   });
 }
 
 /**
- * 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.
+ * The owner's hand-issued tokens of both kinds, 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({
       id: accessTokens.id,
       name: accessTokens.name,
+      kind: accessTokens.kind,
+      scopes: accessTokens.scopes,
       canWrite: accessTokens.canWrite,
       createdAt: accessTokens.createdAt,
       expiresAt: accessTokens.expiresAt,
@@ -170,14 +196,40 @@ export async function findTokenClientName(ctx: McpAccessContext, tokenId: string
 }
 
 /**
- * The identity behind a token, or null for anything unknown, revoked or expired: the caller cannot
- * tell which, so a guess learns nothing. The expiry sits in the query, so no code path can forget
- * it. Records the use (at most once a minute per token); a failed record is logged and does not
- * fail the request. Database failures of the lookup propagate.
+ * The identity behind an MCP token, or null for anything unknown, revoked or expired, and for an API
+ * token: the caller cannot tell which, so a guess learns nothing. The expiry sits in the query, so no
+ * code path can forget it. Records the use (at most once a minute per token); a failed record is
+ * logged and does not fail the request. Database failures of the lookup propagate.
  */
 export async function verifyAccessToken(ctx: McpAccessContext, token: string): Promise<VerifiedAccessToken | null> {
   const options = getMcpAccessOptions(ctx.config);
   if (!isAcceptedTokenShape(options, token)) return null;
+  const row = await findValidToken(ctx, hashAccessToken(token), "mcp");
+  if (row === null) return null;
+  return {
+    tokenId: row.id,
+    userId: row.userId,
+    canWrite: row.canWrite && options.allowWrites,
+    expiresAt: row.expiresAt,
+    grantId: row.grantId,
+  };
+}
+
+/** A stored, unexpired token of one kind, found by the hash of its plaintext. */
+export interface ValidTokenRow {
+  readonly id: string;
+  readonly userId: string;
+  readonly canWrite: boolean;
+  readonly expiresAt: Date;
+  readonly grantId: string | null;
+  readonly scopes: readonly string[];
+}
+
+/**
+ * The unexpired token of `kind` stored under this hash, or null, after recording its use. The caller
+ * checks the shape first, so no lookup runs for a value that cannot be a token.
+ */
+export async function findValidToken(ctx: McpAccessContext, tokenHash: string, kind: AccessTokenKind): Promise<ValidTokenRow | null> {
   const now = ctx.clock.now();
   const [row] = await ctx.db
     .select({
@@ -186,19 +238,13 @@ export async function verifyAccessToken(ctx: McpAccessContext, token: string): P
       canWrite: accessTokens.canWrite,
       expiresAt: accessTokens.expiresAt,
       grantId: accessTokens.grantId,
+      scopes: accessTokens.scopes,
     })
     .from(accessTokens)
-    .where(and(eq(accessTokens.tokenHash, hashAccessToken(token)), gt(accessTokens.expiresAt, now)));
+    .where(and(eq(accessTokens.tokenHash, tokenHash), eq(accessTokens.kind, kind), gt(accessTokens.expiresAt, now)));
   if (row === undefined) return null;
-
   await recordUse(ctx, row, now);
-  return {
-    tokenId: row.id,
-    userId: row.userId,
-    canWrite: row.canWrite && options.allowWrites,
-    expiresAt: row.expiresAt,
-    grantId: row.grantId,
-  };
+  return row;
 }
 
 /** Records the use on the token and, for an OAuth token, on its grant (the connected apps list). */
@@ -222,7 +268,7 @@ async function recordUse(ctx: McpAccessContext, token: { readonly id: string; re
 }
 
 /**
- * Deletes every expired token, of every account, hand-issued and OAuth alike. Issuing already
+ * Deletes every expired token, of every account and kind, 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).
  */

package/src/server/tools.ts

@@ -19,6 +19,8 @@ export interface ToolErrorOptions {
   readonly caller?: ToolCaller;
   /** The tool's arguments, for the record: only their names are read, never their values. */
   readonly args?: Readonly<Record<string, unknown>>;
+  /** Whether the call ran on the person's confirmation, for the record (`withConfirmation` sets it). */
+  readonly confirmed?: boolean;
 }
 
 /** The client behind a call: the token's id (`McpServerIdentity.tokenId`) and its name (`findTokenClientName`). */
@@ -44,6 +46,12 @@ export interface ToolCallRecord {
   readonly tokenId: string | null;
   readonly clientName: string | null;
   readonly argumentNames: readonly string[];
+  /**
+   * For a tool wrapped in `withConfirmation`: `true` when the call carried a valid confirmation and did the work,
+   * `false` when it answered an estimate, was refused, or ran without asking (`runWithoutConfirmationWhen`). `null`
+   * for any other tool.
+   */
+  readonly confirmed: boolean | null;
   readonly outcome: ToolCallOutcome;
   readonly startedAt: Date;
   readonly durationMs: number;
@@ -96,6 +104,7 @@ async function reportToolCall(options: ToolErrorOptions, outcome: ToolCallOutcom
     tokenId: options.caller?.tokenId ?? null,
     clientName: options.caller?.clientName ?? null,
     argumentNames: Object.keys(options.args ?? {}),
+    confirmed: options.confirmed ?? null,
     outcome,
     startedAt: new Date(startedAt),
     durationMs: Date.now() - startedAt,

package/src/tokens/index.ts

@@ -0,0 +1,22 @@
+// Personal access tokens for an app's plain HTTP routes, without the MCP server (#961): nothing this
+// entry loads imports `@modelcontextprotocol/*` (tests/api-tokens-961.test.ts walks the graph). A route
+// handler checks a request with `requireApiToken` and answers a refusal with `apiTokenErrorResponse`.
+export {
+  API_RATE_LIMIT_BUCKET,
+  API_TOKEN_RATE_LIMIT_BUCKET,
+  apiTokenErrorResponse,
+  getApiTokenOptions,
+  isApiTokenShape,
+  issueApiToken,
+  requireApiToken,
+  verifyApiToken,
+  type IssueApiTokenInput,
+  type IssueApiTokenResult,
+  type IssuedApiToken,
+  type RequireApiTokenOptions,
+  type VerifiedApiToken,
+} from "../server/api-tokens.js";
+export { createMcpAccessContext } from "../server/context.js";
+export { isWritingEnabled } from "../server/writes-switch.js";
+export { hashAccessToken, listAccessTokens, pruneAccessTokens, revokeAccessToken, type McpAccessContext, type RevokeAccessTokenInput } from "../server/tokens.js";
+export type { AccessTokenKind, AccessTokenView, ApiTokenErrorCode, ApiTokenIdentity, ApiTokenRefusal } from "../contract.js";

package/src/ui/index.ts

@@ -3,6 +3,7 @@
 export { ConsentError, ConsentForm, type ConsentErrorProps, type ConsentFormProps, type ConsentFormSlot } from "./consent-form.js";
 export {
   TokenManager,
+  type TokenManagerApiScope,
   type RevokeGrantAction,
   type TokenManagerGrant,
   type IssueTokenAction,

package/src/ui/token-manager.tsx

@@ -3,12 +3,13 @@
 import { formatMessage, type Locale } from "@softure-ai/core";
 import { Button, ButtonLink, Checkbox, type ClassNames, createSlotClassGetter, FormError, TextField } from "@softure-ai/ui";
 import { useActionState, useEffect, useRef, useState } from "react";
-import type { IssuedToken, IssueTokenFormState, RevokeGrantFormState, RevokeTokenFormState } from "../contract.js";
+import type { IssuedApiTokenView, IssuedToken, IssueTokenFormState, RevokeGrantFormState, RevokeTokenFormState } from "../contract.js";
 import { getTokenErrorMessage, type McpAccessMessages } from "../messages/index.js";
 import { MAX_TOKEN_NAME_LENGTH } from "../options.js";
 
 // The token page's client part: the tool catalog, the issue form, the token just issued with its
-// setup snippets, the owner's tokens with a revoke button each, and, with OAuth on, the apps
+// setup snippets, (with API scopes) the app's scopes and a second form for tokens for other apps,
+// the owner's tokens of both kinds with a revoke button each, and, with OAuth on, the apps
 // connected through OAuth with a disconnect button each. Both forms submit to their
 // server actions through `useActionState`. The plaintext lives only in the issue form's state:
 // "Done" or leaving the page drops it. Focus follows the one-time token: its heading takes focus
@@ -29,11 +30,23 @@ export interface TokenManagerTool {
   readonly accessText: string;
 }
 
+/** One scope the app declares for API tokens, prepared on the server. */
+export interface TokenManagerApiScope {
+  readonly name: string;
+  readonly description: string;
+  /** "Reads", "Changes data", or that writes are off, already in the app's copy. */
+  readonly accessText: string;
+  /** Offered on the form: a read scope, or a write scope while the app allows writes. */
+  readonly isOffered: boolean;
+}
+
 /** One of the owner's tokens, prepared on the server. */
 export interface TokenManagerRow {
   readonly id: string;
   readonly name: string;
-  /** Read only, or read and change, already in the app's copy. */
+  /** "AI assistant" or "Other apps", while the app offers both kinds. */
+  readonly kindText?: string;
+  /** Read only, or read and change, already in the app's copy; an API token's scopes. */
   readonly scopeText: string;
   /** Active, expiring in n days, or expired. */
   readonly statusText: string;
@@ -65,6 +78,11 @@ export interface TokenManagerProps {
   readonly grants?: readonly TokenManagerGrant[];
   /** Disconnects one app; needed with `grants`. */
   readonly revokeGrantAction?: RevokeGrantAction;
+  /**
+   * The app's API scopes (`apiTokens`); with them the page lists them and offers a second form for tokens
+   * for other apps, submitted to `issueAction` with `kind=api`. Leave out, and the page offers MCP tokens only.
+   */
+  readonly apiScopes?: readonly TokenManagerApiScope[];
   readonly messages: McpAccessMessages;
   /** Locale of the built-in copy of the ui primitives. */
   readonly locale?: Locale;
@@ -211,6 +229,103 @@ function IssueForm({
   );
 }
 
+function IssuedApiTokenPanel({
+  issued,
+  onDone,
+  messages,
+  slot,
+  unstyled,
+}: {
+  issued: IssuedApiTokenView;
+  onDone: () => void;
+  messages: McpAccessMessages;
+  slot: Slot;
+  unstyled: boolean | undefined;
+}) {
+  const snippet = (title: string, value: string) => <Snippet key={title} title={title} value={value} messages={messages} slot={slot} unstyled={unstyled} />;
+  const headingRef = useRef<HTMLHeadingElement>(null);
+  useEffect(() => {
+    headingRef.current?.focus();
+  }, [issued.id]);
+  return (
+    <section className={slot("section")}>
+      <h3 ref={headingRef} tabIndex={-1} className={slot("heading")}>{formatMessage(messages.apiIssued.title, { name: issued.name })}</h3>
+      <p className={slot("text")}>{messages.apiIssued.once}</p>
+      <p className={slot("text")}>
+        {issued.expiresText} {formatMessage(messages.apiIssued.scopes, { scopes: issued.scopes.join(", ") })}
+      </p>
+      {snippet(messages.apiIssued.tokenTitle, issued.token)}
+      {snippet(messages.apiIssued.headerTitle, `Authorization: ${issued.authorizationHeader}`)}
+      {issued.examples.map((example) => snippet(example.title, example.text))}
+      <Button variant="primary" onClick={onDone} unstyled={unstyled}>
+        {messages.issued.done}
+      </Button>
+    </section>
+  );
+}
+
+function ApiIssueForm({
+  action,
+  scopes,
+  maxTokens,
+  messages,
+  locale,
+  slot,
+  unstyled,
+}: {
+  action: IssueTokenAction;
+  scopes: readonly TokenManagerApiScope[];
+  maxTokens: number;
+  messages: McpAccessMessages;
+  locale: Locale | undefined;
+  slot: Slot;
+  unstyled: boolean | undefined;
+}) {
+  const [state, formAction, isPending] = useActionState(action, { status: "idle" });
+  const [dismissedId, setDismissedId] = useState<string | null>(null);
+  const issued = state.status === "api-ok" && state.issued.id !== dismissedId ? state.issued : null;
+  const formRef = useRef<HTMLFormElement>(null);
+  function dismiss(id: string) {
+    setDismissedId(id);
+    requestAnimationFrame(() => {
+      const field = formRef.current?.elements.namedItem("name");
+      if (field instanceof HTMLInputElement) field.focus();
+    });
+  }
+  return (
+    <>
+      <section className={slot("section")}>
+        <h2 className={slot("heading")}>{messages.apiIssue.title}</h2>
+        <form ref={formRef} action={formAction} className={slot("list")}>
+          <input type="hidden" name="kind" value="api" />
+          <TextField
+            name="name"
+            label={messages.apiIssue.name}
+            hint={messages.apiIssue.nameHint}
+            maxLength={MAX_TOKEN_NAME_LENGTH}
+            required
+            autoComplete="off"
+            locale={locale}
+            unstyled={unstyled}
+          />
+          <p className={slot("heading")}>{messages.apiIssue.scopes}</p>
+          {scopes
+            .filter((scope) => scope.isOffered)
+            .map((scope) => (
+              <Checkbox key={scope.name} name={`scope:${scope.name}`} label={scope.name} description={scope.description} unstyled={unstyled} />
+            ))}
+          <p className={slot("text")}>{formatMessage(messages.issue.limit, { max: maxTokens })}</p>
+          <FormError message={state.status === "error" ? (state.message ?? getTokenErrorMessage(messages, state.error)) : undefined} unstyled={unstyled} />
+          <Button type="submit" variant="primary" pending={isPending} unstyled={unstyled}>
+            {isPending ? messages.apiIssue.pending : messages.apiIssue.submit}
+          </Button>
+        </form>
+      </section>
+      {issued === null ? null : <IssuedApiTokenPanel issued={issued} onDone={() => dismiss(issued.id)} messages={messages} slot={slot} unstyled={unstyled} />}
+    </>
+  );
+}
+
 function TokenItem({
   row,
   action,
@@ -237,6 +352,7 @@ function TokenItem({
         </form>
       </div>
       <p className={row.isExpired ? slot("details") : slot("badge")}>
+        {row.kindText === undefined ? null : `${row.kindText} · `}
         {row.statusText} · {row.scopeText}
       </p>
       <p className={slot("details")}>{row.details.join(" · ")}</p>
@@ -286,6 +402,7 @@ export function TokenManager({
   revokeAction,
   grants,
   revokeGrantAction,
+  apiScopes,
   messages,
   locale,
   classNames,
@@ -313,6 +430,26 @@ export function TokenManager({
         )}
       </section>
       <IssueForm action={issueAction} allowWrites={allowWrites} maxTokens={maxTokens} messages={messages} locale={locale} slot={slot} unstyled={unstyled} />
+      {apiScopes === undefined ? null : (
+        <>
+          <section className={slot("section")}>
+            <h2 className={slot("heading")}>{messages.apiScopes.title}</h2>
+            <p className={slot("text")}>{messages.apiScopes.lead}</p>
+            <ul className={slot("list")}>
+              {apiScopes.map((scope) => (
+                <li key={scope.name} className={slot("item")}>
+                  <div className={slot("itemHeader")}>
+                    <code className={slot("heading")}>{scope.name}</code>
+                    <span className={slot("badge")}>{scope.accessText}</span>
+                  </div>
+                  <p className={slot("text")}>{scope.description}</p>
+                </li>
+              ))}
+            </ul>
+          </section>
+          <ApiIssueForm action={issueAction} scopes={apiScopes} maxTokens={maxTokens} messages={messages} locale={locale} slot={slot} unstyled={unstyled} />
+        </>
+      )}
       <section className={slot("section")}>
         <h2 className={slot("heading")}>{messages.list.title}</h2>
         {tokens.length === 0 ? (