@softure-ai/mcp-access 0.2.9 → 0.3.0

package/src/jobs/operations.ts

@@ -0,0 +1,213 @@
+// Long operations as MCP tools (#952), on top of `@softure-ai/jobs`. A tool whose work takes minutes cannot hold the
+// call open (JSON mode drops mid-call notifications, proxies cut long responses, assistants time out), so it starts a
+// job and answers an operation id at once; the assistant then asks `get_operation` until the operation ends, and may
+// stop it with `cancel_operation`.
+//
+//   server.registerTool("render_video", { inputSchema }, (args) => startOperation(ctx, identity, { queue: "video.render", payload: args }));
+//   registerOperationStatusTool(server, { ctx, identity, readResult: (job) => findRenderUrl(job.id) });
+//   registerOperationCancelTool(server, { ctx, identity });
+//
+// Ownership rides on the job itself: its origin is `mcp` and its dedup key `mcp:<userId>:<key>`, which the jobs table
+// keeps after the job ends. Any other job, or another account's, is "not found".
+import { randomUUID } from "node:crypto";
+import type { CallToolResult, McpServer } from "@modelcontextprotocol/server";
+import { err, ok, type Err, type Ok } from "@softure-ai/core";
+import { enqueueJob, requestJobCancel, type JobsContext } from "@softure-ai/jobs/server";
+import { z } from "zod";
+import type { McpServerIdentity } from "../contract.js";
+import type { McpAccessMessages } from "../messages/index.js";
+import { getMcpAccessMessages } from "../server/options.js";
+import { toolResult, withToolErrors, type ToolErrorHints } from "../server/tools.js";
+import { answerOperationTask, isTasksRequest, isTaskTtlValid, MAX_TASK_TTL_SECONDS, type OperationTaskRequest } from "./operation-tasks.js";
+import {
+  describeOperation,
+  fillToolName,
+  findOwnedJob,
+  getOwnerPrefix,
+  getPollMin,
+  MAX_OPERATION_DEDUP_KEY_LENGTH,
+  OPERATION_ORIGIN,
+  OPERATION_STATUS_TOOL_NAME,
+  OPERATION_CANCEL_TOOL_NAME,
+  type GetOperationOptions,
+  type OperationAnswer,
+  type OperationErrorCode,
+  type OperationPollOptions,
+  type ReadOperationResult,
+} from "./operation-state.js";
+
+export {
+  getOperationStatus,
+  getPollAfterSeconds,
+  MAX_OPERATION_DEDUP_KEY_LENGTH,
+  OPERATION_CANCEL_TOOL_NAME,
+  OPERATION_ORIGIN,
+  OPERATION_STATUS_TOOL_NAME,
+  OPERATION_STATUSES,
+  type GetOperationOptions,
+  type OperationAnswer,
+  type OperationErrorCode,
+  type OperationJob,
+  type OperationPollOptions,
+  type OperationStatus,
+  type ReadOperationResult,
+} from "./operation-state.js";
+
+export interface StartOperationInput {
+  /** A queue defined in `jobs({ queues })`. */
+  readonly queue: string;
+  /** The handler's payload, as `enqueueJob` takes it: ids, not personal data. */
+  readonly payload: unknown;
+  /**
+   * While an operation of this account and queue with the same key runs, starting again joins it (the answer carries
+   * its id and status). At most 150 characters. Default: a new operation every time.
+   */
+  readonly dedupKey?: string;
+  /** The status tool the answer tells the assistant to call. Default `get_operation`. */
+  readonly statusToolName?: string;
+  readonly poll?: OperationPollOptions;
+  /**
+   * The tool handler's request context (its second argument). When the client declared the MCP Tasks extension on
+   * this request, the answer is a task (`resultType: "task"`) instead of an operation id; any other client gets the
+   * operation id as before. Pair it with `registerOperationTasks` on the same server, which serves `tasks/get`.
+   */
+  readonly taskRequest?: OperationTaskRequest;
+  /** How long a task can be read after it was created, in seconds. Default 86 400 (a day). */
+  readonly taskTtlSeconds?: number;
+}
+
+interface OperationToolOptions {
+  /** `{ db, clock, config }` of the request. */
+  readonly ctx: JobsContext;
+  /** The request's identity: operations are scoped to `identity.userId`. */
+  readonly identity: McpServerIdentity;
+  /** Default: the module dictionary's description. */
+  readonly description?: string;
+}
+
+export interface OperationStatusToolOptions extends OperationToolOptions {
+  /** Default `get_operation`. */
+  readonly name?: string;
+  readonly readResult?: ReadOperationResult;
+  readonly poll?: OperationPollOptions;
+}
+
+export interface OperationCancelToolOptions extends OperationToolOptions {
+  /** Default `cancel_operation`. */
+  readonly name?: string;
+  /** The status tool the answer points to. Default `get_operation`. */
+  readonly statusToolName?: string;
+  readonly poll?: OperationPollOptions;
+}
+
+const operationInput = z.object({ operationId: z.string().min(1).max(100) });
+
+/**
+ * For a tool handler: enqueues the operation's job and answers its id with the fixed sentence (ask the status tool,
+ * do not start again). Throws on an unknown queue or a dedup key over 150 characters (a bug in the caller); database
+ * failures propagate, so call it inside `withToolErrors` or let the SDK answer the error.
+ */
+export async function startOperation(ctx: JobsContext, identity: McpServerIdentity, input: StartOperationInput): Promise<CallToolResult> {
+  if (input.dedupKey !== undefined && (input.dedupKey.length === 0 || input.dedupKey.length > MAX_OPERATION_DEDUP_KEY_LENGTH)) {
+    throw new Error(`startOperation: the dedup key of queue ${input.queue} must have 1 to ${String(MAX_OPERATION_DEDUP_KEY_LENGTH)} characters`);
+  }
+  if (input.taskTtlSeconds !== undefined && !isTaskTtlValid(input.taskTtlSeconds)) {
+    throw new Error(`startOperation: the task lifetime of queue ${input.queue} must be whole seconds from 60 to ${String(MAX_TASK_TTL_SECONDS)}`);
+  }
+  const enqueued = await enqueueJob(ctx, {
+    queue: input.queue,
+    payload: input.payload,
+    origin: OPERATION_ORIGIN,
+    dedupKey: getOwnerPrefix(identity.userId) + (input.dedupKey ?? randomUUID()),
+  });
+  const options = { ...(input.poll === undefined ? {} : { poll: input.poll }), statusToolName: input.statusToolName ?? OPERATION_STATUS_TOOL_NAME };
+  if (input.taskRequest !== undefined && isTasksRequest(input.taskRequest)) {
+    return answerOperationTask(ctx, identity, { jobId: enqueued.id, ...(input.taskTtlSeconds === undefined ? {} : { ttlSeconds: input.taskTtlSeconds }), ...(input.poll === undefined ? {} : { poll: input.poll }) });
+  }
+  if (enqueued.isDuplicate) {
+    const joined = await getOperation(ctx, identity, enqueued.id, options);
+    if (joined.ok) return toolResult(joined.value);
+  }
+  const messages = getMcpAccessMessages(ctx.config).operations;
+  const answer: OperationAnswer = {
+    operationId: enqueued.id,
+    status: "queued",
+    progress: null,
+    pollAfterSeconds: getPollMin(input.poll),
+    message: fillToolName(messages.started, options.statusToolName),
+  };
+  return toolResult(answer);
+}
+
+/** The caller's operation as `get_operation` answers it; `mcp-access.operation_not_found` for any other id. */
+export async function getOperation(
+  ctx: JobsContext,
+  identity: McpServerIdentity,
+  operationId: string,
+  options: GetOperationOptions = {},
+): Promise<Ok<OperationAnswer> | Err<"mcp-access.operation_not_found">> {
+  const job = await findOwnedJob(ctx, identity, operationId);
+  if (job === null) return err("mcp-access.operation_not_found");
+  return ok(await describeOperation(ctx, job, options));
+}
+
+/**
+ * Cancels the caller's operation: a queued one ends at once, a running one is asked to stop (its handler's `signal`
+ * aborts on the next heartbeat). `mcp-access.operation_finished` once it has ended.
+ */
+export async function cancelOperation(
+  ctx: JobsContext,
+  identity: McpServerIdentity,
+  operationId: string,
+  options: Omit<GetOperationOptions, "readResult"> = {},
+): Promise<Ok<OperationAnswer> | Err<OperationErrorCode>> {
+  const owned = await findOwnedJob(ctx, identity, operationId);
+  if (owned === null) return err("mcp-access.operation_not_found");
+  const cancelled = await requestJobCancel(ctx, owned.id);
+  if (!cancelled.ok) return err(cancelled.error === "jobs.not_found" ? "mcp-access.operation_not_found" : "mcp-access.operation_finished");
+  return ok(await describeOperation(ctx, cancelled.value, options));
+}
+
+/** Registers the read-only status tool (`get_operation`) for the request's account. */
+export function registerOperationStatusTool(server: McpServer, options: OperationStatusToolOptions): void {
+  const name = options.name ?? OPERATION_STATUS_TOOL_NAME;
+  const messages = getMcpAccessMessages(options.ctx.config).operations;
+  const getOptions: GetOperationOptions = {
+    statusToolName: name,
+    ...(options.readResult === undefined ? {} : { readResult: options.readResult }),
+    ...(options.poll === undefined ? {} : { poll: options.poll }),
+  };
+  server.registerTool(
+    name,
+    {
+      description: options.description ?? messages.statusToolDescription,
+      inputSchema: operationInput,
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    },
+    ({ operationId }) =>
+      withToolErrors(() => getOperation(options.ctx, options.identity, operationId, getOptions), { hints: getOperationHints(messages), label: name }),
+  );
+}
+
+/** Registers the cancel tool (`cancel_operation`), a write: nothing is registered without `identity.canWrite`. */
+export function registerOperationCancelTool(server: McpServer, options: OperationCancelToolOptions): void {
+  if (!options.identity.canWrite) return;
+  const name = options.name ?? OPERATION_CANCEL_TOOL_NAME;
+  const messages = getMcpAccessMessages(options.ctx.config).operations;
+  const cancelOptions = { statusToolName: options.statusToolName ?? OPERATION_STATUS_TOOL_NAME, ...(options.poll === undefined ? {} : { poll: options.poll }) };
+  server.registerTool(
+    name,
+    {
+      description: options.description ?? messages.cancelToolDescription,
+      inputSchema: operationInput,
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    },
+    ({ operationId }) =>
+      withToolErrors(() => cancelOperation(options.ctx, options.identity, operationId, cancelOptions), { hints: getOperationHints(messages), label: name }),
+  );
+}
+
+
+function getOperationHints(messages: McpAccessMessages["operations"]): ToolErrorHints {
+  return { "mcp-access.operation_not_found": messages.notFound, "mcp-access.operation_finished": messages.finished };
+}

package/src/messages/en.ts

@@ -20,6 +20,28 @@ export const en = {
     pending: "Creating…",
     limit: "You can hold up to {max} active tokens.",
   },
+  apiScopes: {
+    title: "What a token for other apps can do",
+    lead: "Tokens for other apps, such as a phone Shortcut, an automation tool or a script, call this app's HTTP routes. Each one gets only the access you tick.",
+    read: "Reads",
+    write: "Changes data",
+    writeUnavailable: "Changes data (turned off in this app)",
+  },
+  apiIssue: {
+    title: "New token for other apps",
+    name: "Name",
+    nameHint: "Where you will use it, e.g. iPhone Shortcut or Make.",
+    scopes: "Access",
+    submit: "Create token",
+    pending: "Creating…",
+  },
+  apiIssued: {
+    title: "Token created: {name}",
+    once: "Copy it now. It is shown only once; after you leave this page, only its name remains.",
+    scopes: "Access: {scopes}.",
+    tokenTitle: "Token",
+    headerTitle: "Authorization header",
+  },
   issued: {
     title: "Token created: {name}",
     once: "Copy it now. It is shown only once; after you leave this page, only its name remains.",
@@ -42,6 +64,8 @@ export const en = {
   },
   list: {
     title: "Your tokens",
+    kindMcp: "AI assistant",
+    kindApi: "Other apps",
     empty: "You have no tokens yet.",
     readOnly: "Read only",
     readWrite: "Read and change",
@@ -91,10 +115,39 @@ export const en = {
     noFields: "none",
     fieldRenamed: "input.field_renamed: the field \"{field}\" is now \"{renamed}\". Send it as \"{renamed}\".",
   },
+  confirmation: {
+    ask: "Nothing was done yet. Show the person this estimate and ask whether to go ahead. Only after they agree in the chat, call the tool again with the same arguments and \"confirmation\" set to the value above, before {expiresAt}.",
+    fieldDescription: "Leave it out on the first call. Set it only to the confirmation the first call answered, after the person agreed to its estimate.",
+    invalid: "input.confirmation_invalid: this is not a confirmation this tool issued. Call the tool again without \"confirmation\" for a new estimate.",
+    otherTool: "input.confirmation_other_tool: the confirmation was issued for another tool. Call this tool without \"confirmation\" for its own estimate.",
+    otherAccount: "input.confirmation_other_account: the confirmation was issued to another account or access token. Call the tool again without \"confirmation\" for a new estimate.",
+    expired: "input.confirmation_expired: the confirmation has expired. Call the tool again without \"confirmation\" for a new estimate and ask the person again.",
+    argumentsChanged: "input.confirmation_arguments_changed: the arguments differ from the ones the person agreed to. Call the tool again without \"confirmation\" for an estimate of these arguments and ask the person again.",
+    estimateChanged: "input.confirmation_estimate_changed: the estimate has changed since the person agreed. Call the tool again without \"confirmation\" for the new estimate and ask the person again.",
+    used: "input.confirmation_used: the confirmation was used already; nothing was done again. Call the tool again without \"confirmation\" if the person wants it done once more.",
+  },
   serverInfoTool: {
     description:
       "Tells which build of this server answers: its name and version (the version changes whenever a tool changes), the release, the commit, when it was built and started, and the changelog when the app publishes one. Use it to check that a change is live.",
   },
+  operations: {
+    statusToolDescription:
+      "Tells how a long operation started by another tool is going: queued, running (with its progress), succeeded (with its result), failed (with an error code) or cancelled. Call it again after pollAfterSeconds while the operation runs.",
+    cancelToolDescription: "Stops a long operation started by another tool. A queued one ends at once; a running one stops at its next safe point.",
+    started: "The operation has started and runs in the background. Call {tool} with this operationId after pollAfterSeconds to follow it. Do not call the starting tool again.",
+    queued: "The operation is waiting to start. Call {tool} again after pollAfterSeconds.",
+    running: "The operation is running. Call {tool} again after pollAfterSeconds.",
+    cancelRequested: "The operation was asked to stop and will end shortly. Call {tool} again after pollAfterSeconds.",
+    succeeded: "The operation has finished.",
+    failed: "The operation failed. Tell the user; start it again only if they ask.",
+    cancelled: "The operation was cancelled.",
+    notFound: "No operation with this id belongs to this account.",
+    finished: "The operation has already ended, so it cannot be cancelled.",
+    /** The `statusMessage` of an MCP task (#977) while its operation has not ended. */
+    taskQueued: "The operation is waiting to start.",
+    taskRunning: "The operation is running.",
+    taskCancelRequested: "The operation was asked to stop and will end shortly.",
+  },
   errors: {
     "mcp-access": {
       name_required: "Give the token a name, so you can tell it from the others.",
@@ -104,6 +157,9 @@ export const en = {
       grant_not_found: "This app is no longer connected.",
       issue_refused: "Your account cannot create tokens right now.",
       write_refused: "Your account cannot create tokens with write access. Create a read-only token instead.",
+      api_disabled: "This app does not offer tokens for other apps.",
+      scope_required: "Tick at least one kind of access.",
+      scope_unknown: "This app does not offer that access. Reload the page and try again.",
     },
     auth: {
       unauthenticated: "Your session has ended. Log in again.",

package/src/next/issue-token.ts

@@ -16,10 +16,11 @@ 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, McpIssueRefusal, McpIssueRefusalCode } from "../contract.js";
+import type { AccessTokenKind, IssueTokenFormState, McpIssueRefusal, McpIssueRefusalCode } from "../contract.js";
 import { MAX_TOKEN_NAME_LENGTH } from "../options.js";
-import { getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes, getMcpEndpointUrl } from "../server/options.js";
-import { issueAccessToken } from "../server/tokens.js";
+import { getLocalizedText, getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes, getMcpEndpointUrl } from "../server/options.js";
+import { getApiTokenOptions, issueApiToken } from "../server/api-tokens.js";
+import { issueAccessToken, type McpAccessContext } from "../server/tokens.js";
 import { getMcpAccessContext, getRequestOrigins } from "./context.js";
 import { formatDate } from "./format.js";
 
@@ -38,7 +39,24 @@ const issueInput = z.object({
 /** What the gate learns about the token about to be issued. */
 export interface IssueGateInput {
   readonly userId: string;
+  /** For an API token: whether any asked scope writes. */
   readonly canWrite: boolean;
+  /** `mcp` for an assistant, `api` for the app's HTTP routes (the form's `kind` field). */
+  readonly kind: AccessTokenKind;
+  /** The scopes asked for an API token, as the form sent them; empty for an MCP token. */
+  readonly scopes: readonly string[];
+}
+
+/** The form fields of the API scopes: a ticked checkbox `scope:<name>` sends "on". */
+const SCOPE_FIELD_PREFIX = "scope:";
+
+/** The scope names the form ticked, at most as many as the app could declare. */
+function readScopes(formData: FormData): string[] {
+  const names: string[] = [];
+  for (const key of formData.keys()) {
+    if (key.startsWith(SCOPE_FIELD_PREFIX) && names.length < 64) names.push(key.slice(SCOPE_FIELD_PREFIX.length, SCOPE_FIELD_PREFIX.length + 200));
+  }
+  return [...new Set(names)];
 }
 
 /**
@@ -54,7 +72,11 @@ export interface IssueTokenOptions {
   readonly beforeIssue?: BeforeIssueGate;
 }
 
-/** Issues a token for the signed-in user, after the gate, and returns its plaintext with the setup snippets, once. */
+/**
+ * Issues a token for the signed-in user, after the gate, and returns its plaintext once: an MCP token with
+ * the setup snippets (`ok`), or, when the form sends `kind=api`, an API token with the ticked `scope:<name>`
+ * fields and the app's examples (`api-ok`).
+ */
 export async function issueToken(_previous: IssueTokenFormState, formData: FormData, options: IssueTokenOptions = {}): Promise<IssueTokenFormState> {
   const config = getSoftureConfig();
   const user = await getCurrentUser();
@@ -62,19 +84,46 @@ export async function issueToken(_previous: IssueTokenFormState, formData: FormD
 
   // Every field has a `catch`, so parsing cannot fail.
   const input = issueInput.parse({ name: formData.get("name"), canWrite: formData.get("canWrite") });
-  const canWrite = input.canWrite !== null;
+  const kind: AccessTokenKind = formData.get("kind") === "api" ? "api" : "mcp";
+  const scopes = kind === "api" ? readScopes(formData) : [];
   try {
+    const ctx = await getMcpAccessContext(config);
+    const canWrite = kind === "api" ? isAnyWriteScope(ctx, scopes) : input.canWrite !== null;
     if (options.beforeIssue !== undefined) {
-      const gate = await options.beforeIssue({ userId: user.id, canWrite });
+      const gate = await options.beforeIssue({ userId: user.id, canWrite, kind, scopes });
       if (!gate.ok) return getRefusalState(gate.error, "message" in gate ? gate.message : undefined);
     }
     // Resolved before issuing: a failure afterwards would leave a token nobody received.
-    const endpointUrl = getMcpEndpointUrl(config, await getRequestOrigins(config, getMcpAccessRoutes(config).page));
-    const result = await issueAccessToken(await getMcpAccessContext(config), { userId: user.id, name: input.name, canWrite });
+    const origins = await getRequestOrigins(config, getMcpAccessRoutes(config).page);
+    const messages = getMcpAccessMessages(config);
+    if (kind === "api") {
+      const result = await issueApiToken(ctx, { userId: user.id, name: input.name, scopes });
+      if (!result.ok) return { status: "error", error: result.error };
+      revalidatePath(getMcpAccessRoutes(config).page);
+      const issued = result.value;
+      const examples = getApiTokenOptions(ctx)?.examples ?? [];
+      return {
+        status: "api-ok",
+        issued: {
+          id: issued.id,
+          name: issued.name,
+          scopes: issued.scopes,
+          expiresText: formatMessage(messages.issued.expires, { date: formatDate(config, issued.expiresAt) }),
+          expiresAt: issued.expiresAt.toISOString(),
+          token: issued.token,
+          authorizationHeader: `Bearer ${issued.token}`,
+          examples: examples.map((example) => ({
+            title: getLocalizedText(example.title, config.locale),
+            text: formatMessage(getLocalizedText(example.text, config.locale), { token: issued.token, appOrigin: origins.appOrigin }),
+          })),
+        },
+      };
+    }
+    const endpointUrl = getMcpEndpointUrl(config, origins);
+    const result = await issueAccessToken(ctx, { userId: user.id, name: input.name, canWrite });
     if (!result.ok) return { status: "error", error: result.error };
     revalidatePath(getMcpAccessRoutes(config).page);
     const issued = result.value;
-    const messages = getMcpAccessMessages(config);
     const accessOptions = getMcpAccessOptions(config);
     return {
       status: "ok",
@@ -101,6 +150,12 @@ export async function issueToken(_previous: IssueTokenFormState, formData: FormD
   }
 }
 
+/** Whether any of the asked scopes is one the app declares as a write scope. */
+function isAnyWriteScope(ctx: McpAccessContext, scopes: readonly string[]): boolean {
+  const declared = getApiTokenOptions(ctx)?.scopes ?? [];
+  return declared.some((scope) => scope.access === "write" && scopes.includes(scope.name));
+}
+
 /** A gate's refusal with the app's own text, which the token page shows instead of the code's copy. */
 export function refuseIssue(code: McpIssueRefusalCode, message: string): McpIssueRefusal {
   return { ok: false, error: code, message };

package/src/next/token-manager-props.ts

@@ -10,12 +10,12 @@ import { getLocalizedText, getMcpAccessMessages, getMcpAccessOptions } from "../
 import { listOAuthGrants } from "../server/oauth.js";
 import { listAccessTokens } from "../server/tokens.js";
 import { getAccessTokenStatus } from "../token-status.js";
-import type { TokenManagerGrant, TokenManagerProps, TokenManagerRow, TokenManagerTool } from "../ui/token-manager.js";
+import type { TokenManagerApiScope, TokenManagerGrant, TokenManagerProps, TokenManagerRow, TokenManagerTool } from "../ui/token-manager.js";
 import { getMcpAccessContext } from "./context.js";
 import { formatDate, formatDateTime } from "./format.js";
 
 /** Every prop of `TokenManager` but the actions and the styling. */
-export type TokenManagerData = Pick<TokenManagerProps, "tools" | "tokens" | "grants" | "allowWrites" | "maxTokens" | "messages" | "locale">;
+export type TokenManagerData = Pick<TokenManagerProps, "tools" | "tokens" | "grants" | "apiScopes" | "allowWrites" | "maxTokens" | "messages" | "locale">;
 
 export interface TokenManagerPropsInput {
   /** The signed-in user's id, from the app's session check: only this user's tokens and apps are listed. */
@@ -44,10 +44,13 @@ function toRow(token: AccessTokenView, now: Date, config: SoftureConfig, options
   const isExpired = status.kind === "expired";
   const expiry = formatMessage(isExpired ? messages.list.expiredOn : messages.list.expiresOn, { date: formatDate(config, token.expiresAt) });
   const lastUse = token.lastUsedAt === null ? messages.list.neverUsed : formatMessage(messages.list.lastUsed, { date: formatDateTime(config, token.lastUsedAt) });
+  const mcpScopeText = token.canWrite && options.allowWrites ? messages.list.readWrite : messages.list.readOnly;
   return {
     id: token.id,
     name: token.name,
-    scopeText: token.canWrite && options.allowWrites ? messages.list.readWrite : messages.list.readOnly,
+    scopeText: token.kind === "api" ? token.scopes.join(", ") : mcpScopeText,
+    // Named only while the app offers both kinds; an MCP-only page stays as it was.
+    ...(options.apiTokens === undefined ? {} : { kindText: token.kind === "api" ? messages.list.kindApi : messages.list.kindMcp }),
     statusText: describeStatus(status, messages),
     isExpired,
     details: [formatMessage(messages.list.createdOn, { date: formatDate(config, token.createdAt) }), expiry, lastUse],
@@ -69,8 +72,15 @@ function toTool(tool: McpAccessOptions["tools"][number], config: SoftureConfig,
   return { name: tool.name, description: getLocalizedText(tool.description, config.locale), accessText };
 }
 
+function toApiScope(scope: NonNullable<McpAccessOptions["apiTokens"]>["scopes"][number], config: SoftureConfig, options: McpAccessOptions, messages: McpAccessMessages): TokenManagerApiScope {
+  const isOffered = scope.access === "read" || options.allowWrites;
+  const accessText = scope.access === "read" ? messages.apiScopes.read : isOffered ? messages.apiScopes.write : messages.apiScopes.writeUnavailable;
+  return { name: scope.name, description: getLocalizedText(scope.description, config.locale), accessText, isOffered };
+}
+
 /**
- * The tools, the user's tokens and (while OAuth is on) connected apps, and the page settings, ready to
+ * The tools, the user's tokens of both kinds, (while OAuth is on) connected apps, (with `apiTokens`) the
+ * app's API scopes, and the page settings, ready to
  * spread into `TokenManager` next to the actions. Reads the database; it checks no session itself.
  */
 export async function getTokenManagerProps({ userId, config = getSoftureConfig(), now }: TokenManagerPropsInput): Promise<TokenManagerData> {
@@ -84,6 +94,7 @@ export async function getTokenManagerProps({ userId, config = getSoftureConfig()
     tools: options.tools.map((tool) => toTool(tool, config, options, messages)),
     tokens: tokens.map((token) => toRow(token, at, config, options, messages)),
     ...(grants === null ? {} : { grants: grants.map((grant) => toGrant(grant, config, options, messages)) }),
+    ...(options.apiTokens === undefined ? {} : { apiScopes: options.apiTokens.scopes.map((scope) => toApiScope(scope, config, options, messages)) }),
     allowWrites: options.allowWrites,
     maxTokens: options.maxTokensPerUser,
     messages,

package/src/options.ts

@@ -122,6 +122,60 @@ const oauthSchema = z.strictObject({
     .prefault({}),
 });
 
+/** An app scope of an API token: `recipes:write`, `orders`, `files:read` (segments of a-z, 0-9, `_` and `-`). */
+export const API_SCOPE_PATTERN = /^[a-z][a-z0-9_-]{0,31}(?::[a-z][a-z0-9_-]{0,31}){0,3}$/;
+
+/** The prefix of an API token: lowercase letters and digits ending in `_`, e.g. `sftapi_` or `acme_`. */
+export const API_TOKEN_PREFIX_PATTERN = /^[a-z][a-z0-9]{1,14}_$/;
+
+/** The module's own secrets start with this (`sftmcp_`, the OAuth `sftmc*_` prefixes): an API prefix may not. */
+const RESERVED_PREFIX_START = "sftmc";
+
+/** The most scopes one API token holds (`access_tokens.scopes`). */
+export const MAX_API_TOKEN_SCOPES = 32;
+
+const apiScopeSchema = z.strictObject({
+  /** The scope a route asks for in `requireApiToken`, e.g. `recipes:write`. `mcp:` scopes belong to the MCP endpoint. */
+  name: z
+    .string()
+    .regex(API_SCOPE_PATTERN, "must be lowercase segments joined by ':', e.g. recipes:write")
+    .refine((name) => name !== "mcp" && !name.startsWith("mcp:"), "mcp scopes belong to the MCP endpoint"),
+  /** `write` scopes are granted only with `allowWrites` and work only while the writes switch is on. */
+  access: z.enum(["read", "write"]),
+  /** What the scope lets a token do, for the owner choosing scopes on the token page. */
+  description: localizedTextSchema.refine((text) => text.en !== undefined, "needs at least an en text"),
+});
+
+const apiExampleSchema = z.strictObject({
+  /** The snippet's title, e.g. "iPhone Shortcut" or "curl". */
+  title: localizedTextSchema.refine((text) => text.en !== undefined, "needs at least an en text"),
+  /** The snippet; `{token}` and `{appOrigin}` are filled in when the token is revealed. */
+  text: z
+    .record(z.string().refine(isLocale, "must be a BCP 47 language tag"), z.string().trim().min(1).max(4000))
+    .refine((text) => text.en !== undefined, "needs at least an en text"),
+});
+
+const apiTokensSchema = z
+  .strictObject({
+    /** Marks the app's API tokens for people and secret scanners. MCP tokens keep `sftmcp_`. */
+    prefix: z
+      .string()
+      .regex(API_TOKEN_PREFIX_PATTERN, "must be 2 to 15 lowercase letters or digits followed by _, e.g. acme_")
+      .refine((prefix) => !prefix.startsWith(RESERVED_PREFIX_START), `must not start with ${RESERVED_PREFIX_START}, the module's own prefixes`)
+      .default("sftapi_"),
+    /** The scopes the app's HTTP routes ask for; the token page offers them. */
+    scopes: z.array(apiScopeSchema).min(1, "needs at least one scope").max(MAX_API_TOKEN_SCOPES),
+    /** Ready-made recipes shown once with a new token (a phone Shortcut, a curl call). */
+    examples: z.array(apiExampleSchema).max(8).default([]),
+  })
+  .superRefine((options, context) => {
+    const names = new Set<string>();
+    options.scopes.forEach((scope, index) => {
+      if (names.has(scope.name)) context.addIssue({ code: "custom", path: ["scopes", index, "name"], message: `"${scope.name}" is listed twice` });
+      names.add(scope.name);
+    });
+  });
+
 /** A pattern for tokens an app issued before adopting the module: anchored, and stateless. */
 const legacyTokenPatternSchema = z
   .instanceof(RegExp, { message: "must be a RegExp" })
@@ -170,6 +224,11 @@ export const mcpAccessOptionsSchema = z
     resourceOrigins: z.array(originSchema).max(16, "takes at most 16 origins").default([]),
     /** OAuth 2.1 for MCP clients that connect without a pasted token (claude.ai, ChatGPT). */
     oauth: oauthSchema.prefault({}),
+    /**
+     * Personal tokens for the app's plain HTTP routes (a phone Shortcut, Make, a script), checked with
+     * `requireApiToken` from `@softure-ai/mcp-access/tokens`. Unset, the token page issues MCP tokens only.
+     */
+    apiTokens: apiTokensSchema.optional(),
   })
   .superRefine((options, context) => {
     const names = new Set<string>();
@@ -187,3 +246,6 @@ 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>;
+export type ApiTokenOptions = z.output<typeof apiTokensSchema>;
+export type ApiTokenOptionsInput = z.input<typeof apiTokensSchema>;
+export type ApiScopeDefinition = z.output<typeof apiScopeSchema>;

package/src/schema.ts

@@ -1,8 +1,8 @@
 // Drizzle view of the module's tables (migrations/0001_create_access_tokens.sql,
-// 0002_create_oauth_grants.sql and 0003_create_oauth_registration_window.sql). The migrations are the
-// source of truth; this file only types the queries.
+// 0002_create_oauth_grants.sql, 0003_create_oauth_registration_window.sql, 0004_create_used_confirmations.sql,
+// 0005_add_api_tokens.sql and 0006_create_operation_tasks.sql). The migrations are the source of truth; this file only types the queries.
 import { users } from "@softure-ai/auth";
-import { boolean, jsonb, pgSchema, smallint, text, timestamp, uuid, type AnyPgColumn } from "drizzle-orm/pg-core";
+import { bigint, boolean, jsonb, pgSchema, smallint, text, timestamp, uuid, type AnyPgColumn } from "drizzle-orm/pg-core";
 
 export const mcpSchema = pgSchema("mcp");
 
@@ -61,6 +61,9 @@ export const accessTokens = mcpSchema.table("access_tokens", {
   expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
   lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
   grantId: uuid("grant_id").references((): AnyPgColumn => oauthGrants.id, { onDelete: "cascade" }),
+  /** `mcp` opens the MCP endpoint; `api` passes `requireApiToken` with its `scopes` (migration 0005). */
+  kind: text("kind").$type<"mcp" | "api">().notNull().default("mcp"),
+  scopes: text("scopes").array().$type<string[]>().notNull().default([]),
 });
 
 export const oauthRegistrationWindow = mcpSchema.table("oauth_registration_window", {
@@ -69,5 +72,22 @@ export const oauthRegistrationWindow = mcpSchema.table("oauth_registration_windo
   openUntil: timestamp("open_until", { withTimezone: true }).notNull(),
 });
 
+export const usedConfirmations = mcpSchema.table("used_confirmations", {
+  tokenHash: text("token_hash").primaryKey(),
+  usedAt: timestamp("used_at", { withTimezone: true }).notNull(),
+  expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+});
+
+/** MCP Tasks over long operations (#977): a random task id per account and job, until `expiresAt`. */
+export const operationTasks = mcpSchema.table("operation_tasks", {
+  taskId: text("task_id").primaryKey(),
+  userId: uuid("user_id")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  jobId: bigint("job_id", { mode: "bigint" }).notNull(),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+  expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+});
+
 export type OAuthClientRow = typeof oauthClients.$inferSelect;
 export type OAuthTokenEndpointAuthMethod = OAuthClientRow["tokenEndpointAuthMethod"];