@softure-ai/mcp-access 0.0.0-stage → 0.1.6

package/src/next/pages.tsx

@@ -0,0 +1,80 @@
+// The token page, ready to mount with one line:
+// `export { McpAccessPage as default } from "@softure-ai/mcp-access/next"`.
+// A server component for the signed-in user; without a session it redirects to the login page and
+// back. Everything the client part shows is prepared here, so dates are formatted once, in the
+// app's locale and time zone, and never differ between the server render and hydration.
+import { requireUser } from "@softure-ai/auth/next";
+import { formatMessage, type SoftureConfig } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { Card } from "@softure-ai/ui";
+import type { AccessTokenStatus, AccessTokenView } from "../contract.js";
+import type { McpAccessMessages } from "../messages/index.js";
+import type { McpAccessOptions } from "../options.js";
+import { getLocalizedText, getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes } from "../server/options.js";
+import { listAccessTokens } from "../server/tokens.js";
+import { getAccessTokenStatus } from "../token-status.js";
+import { TokenManager, type TokenManagerRow, type TokenManagerTool } from "../ui/token-manager.js";
+import { issueTokenAction, revokeTokenAction } from "./actions.js";
+import { getMcpAccessContext } from "./context.js";
+import { formatDate, formatDateTime } from "./format.js";
+
+const LAYOUT_CLASS = "sft:mx-auto sft:box-border sft:w-full sft:sm:max-w-3xl sft:px-4 sft:py-4";
+
+function describeStatus(status: AccessTokenStatus, messages: McpAccessMessages): string {
+  switch (status.kind) {
+    case "active":
+      return messages.list.active;
+    case "expired":
+      return messages.list.expired;
+    case "expiring":
+      if (status.daysLeft === 0) return messages.list.expiresToday;
+      if (status.daysLeft === 1) return messages.list.expiresTomorrow;
+      return formatMessage(messages.list.expiresInDays, { days: status.daysLeft });
+  }
+}
+
+function toRow(token: AccessTokenView, now: Date, config: SoftureConfig, options: McpAccessOptions, messages: McpAccessMessages): TokenManagerRow {
+  const status = getAccessTokenStatus(token.expiresAt, now, { timezone: config.timezone, warningDays: options.expiryWarningDays });
+  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) });
+  return {
+    id: token.id,
+    name: token.name,
+    scopeText: token.canWrite && options.allowWrites ? messages.list.readWrite : messages.list.readOnly,
+    statusText: describeStatus(status, messages),
+    isExpired,
+    details: [formatMessage(messages.list.createdOn, { date: formatDate(config, token.createdAt) }), expiry, lastUse],
+  };
+}
+
+function toTool(tool: McpAccessOptions["tools"][number], config: SoftureConfig, options: McpAccessOptions, messages: McpAccessMessages): TokenManagerTool {
+  const accessText = tool.access === "read" ? messages.tools.read : options.allowWrites ? messages.tools.write : messages.tools.writeUnavailable;
+  return { name: tool.name, description: getLocalizedText(tool.description, config.locale), accessText };
+}
+
+export async function McpAccessPage() {
+  const config = getSoftureConfig();
+  const user = await requireUser({ next: getMcpAccessRoutes(config).page });
+  const options = getMcpAccessOptions(config);
+  const messages = getMcpAccessMessages(config);
+  const ctx = await getMcpAccessContext(config);
+  const now = ctx.clock.now();
+  const tokens = await listAccessTokens(ctx, user.id);
+  return (
+    <main className={LAYOUT_CLASS}>
+      <Card title={messages.page.title} subtitle={messages.page.lead}>
+        <TokenManager
+          tools={options.tools.map((tool) => toTool(tool, config, options, messages))}
+          tokens={tokens.map((token) => toRow(token, now, config, options, messages))}
+          allowWrites={options.allowWrites}
+          maxTokens={options.maxTokensPerUser}
+          issueAction={issueTokenAction}
+          revokeAction={revokeTokenAction}
+          messages={messages}
+          locale={config.locale}
+        />
+      </Card>
+    </main>
+  );
+}

package/src/next/route.ts

@@ -0,0 +1,24 @@
+// `POST /api/mcp`, built around the app's MCP server factory and mounted with one line:
+// `app/api/mcp/route.ts → export const POST = createMcpRoute({ createServer });`
+// The factory lives in the app, next to its tools; the module brings the rate limit, the token
+// check and the identity the factory receives. GET and DELETE are not exported, so Next answers
+// them with 405: the endpoint is stateless and keeps no sessions.
+import { errorLogLabel } from "@softure-ai/core";
+import { createMcpEndpoint, type McpEndpointOptions } from "../server/endpoint.js";
+import { getMcpAccessContext } from "./context.js";
+
+const NO_STORE = { "cache-control": "no-store" };
+
+export function createMcpRoute(options: McpEndpointOptions): (request: Request) => Promise<Response> {
+  const endpoint = createMcpEndpoint(options);
+  return async (request) => {
+    let ctx;
+    try {
+      ctx = await getMcpAccessContext();
+    } catch (error) {
+      console.error(`@softure-ai/mcp-access: opening the database failed: ${errorLogLabel(error)}`);
+      return Response.json({ error: "temporarily_unavailable" }, { status: 503, headers: NO_STORE });
+    }
+    return endpoint(ctx, request);
+  };
+}

package/src/options.ts

@@ -0,0 +1,58 @@
+// The options an app passes to `mcpAccess({ ... })` in softure.config.ts, parsed at startup.
+import { LOCALES } from "@softure-ai/core";
+import { z } from "zod";
+
+/** The name an MCP client lists the server under: no spaces, so a shell command needs no quotes. */
+export const SERVER_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+
+/** The MCP rule for tool names: 1 to 128 of A-Z, a-z, 0-9, `_`, `-` and `.`. */
+export const TOOL_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
+
+/** The longest token name the table takes (`access_tokens.name`). */
+export const MAX_TOKEN_NAME_LENGTH = 60;
+
+/** Copy per locale; a locale without its own text falls back to `en`. */
+const localizedTextSchema = z.partialRecord(z.enum(LOCALES), z.string().trim().min(1).max(500));
+
+const toolSchema = z.strictObject({
+  /** The tool's name as the app's MCP server registers it. */
+  name: z.string().regex(TOOL_NAME_PATTERN, "must be 1 to 128 of A-Z, a-z, 0-9, _, - and ."),
+  /**
+   * `write` tools change data: the app registers them only for a token that can write. They stay
+   * listed while `allowWrites` is off, marked as unavailable.
+   */
+  access: z.enum(["read", "write"]),
+  /** What the tool does, for the owner deciding which token to issue. */
+  description: localizedTextSchema.refine((text) => text.en !== undefined, "needs at least an en text"),
+});
+
+export const mcpAccessOptionsSchema = z
+  .strictObject({
+    /** The name MCP clients list the server under, e.g. "acme". Used in the setup instructions. */
+    serverName: z.string().regex(SERVER_NAME_PATTERN, "must be lowercase letters, digits and inner dashes, at most 64 characters"),
+    /** The app's tool catalog, shown on the token page. The MCP server itself comes from the route. */
+    tools: z.array(toolSchema).default([]),
+    /** Lets write tokens be issued and used. Off, every token reads only, write tokens included. */
+    allowWrites: z.boolean().default(false),
+    /** How long a token works. A choice: longer than a session, never forever. */
+    tokenLifetimeDays: z.int().min(1).max(365).default(90),
+    /** How many unexpired tokens one account may hold. */
+    maxTokensPerUser: z.int().min(1).max(100).default(20),
+    /** From how many calendar days before its expiry the page warns about a token. */
+    expiryWarningDays: z.int().min(0).max(60).default(14),
+  })
+  .superRefine((options, context) => {
+    const names = new Set<string>();
+    options.tools.forEach((tool, index) => {
+      if (names.has(tool.name)) {
+        context.addIssue({ code: "custom", path: ["tools", index, "name"], message: `"${tool.name}" is listed twice` });
+      }
+      names.add(tool.name);
+    });
+  });
+
+export type McpAccessOptionsInput = z.input<typeof mcpAccessOptionsSchema>;
+export type McpAccessOptions = z.output<typeof mcpAccessOptionsSchema>;
+export type McpToolDefinitionInput = z.input<typeof toolSchema>;
+export type McpToolDefinition = z.output<typeof toolSchema>;
+export type McpToolAccess = McpToolDefinition["access"];

package/src/schema.ts

@@ -0,0 +1,19 @@
+// Drizzle view of the module's table (migrations/0001_create_access_tokens.sql). The migration is
+// the source of truth; this file only types the queries.
+import { users } from "@softure-ai/auth";
+import { boolean, pgSchema, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+export const mcpSchema = pgSchema("mcp");
+
+export const accessTokens = mcpSchema.table("access_tokens", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  name: text("name").notNull(),
+  tokenHash: text("token_hash").notNull().unique("access_tokens_token_hash_key"),
+  canWrite: boolean("can_write").notNull(),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+  expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+  lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
+});

package/src/server/endpoint.ts

@@ -0,0 +1,141 @@
+// The MCP endpoint (FIRE_TRACKER `src/app/api/mcp/route.ts`, generalised). It takes a Web
+// `Request` and returns a `Response`, so it runs under any fetch-shaped host; the Next adapter only
+// supplies the context. Order: identify the client, count the request, verify the Bearer token,
+// then hand the request to a fresh server from the app's factory. Each refusal happens before the
+// next step costs anything.
+import {
+  bearerAuthChallengeResponse,
+  createMcpHandler,
+  OAuthError,
+  OAuthErrorCode,
+  type AuthInfo,
+  type McpServer,
+  type Server,
+} from "@modelcontextprotocol/server";
+import { errorLogLabel, getModule } from "@softure-ai/core";
+import { consumeRateLimit, identifyClient } from "@softure-ai/security/server";
+import type { McpServerIdentity } from "../contract.js";
+import { verifyAccessToken, type McpAccessContext } from "./tokens.js";
+
+/** Every valid token reads. */
+export const MCP_READ_SCOPE = "mcp:read";
+/** A token that may write: issued for writes, and the app allows them. */
+export const MCP_WRITE_SCOPE = "mcp:write";
+
+/** The security bucket the endpoint counts in; `MCP_RATE_LIMIT_BUCKETS` holds its default. */
+export const MCP_RATE_LIMIT_BUCKET = "mcp";
+
+/** Larger bodies get 413 from the SDK before anything is parsed. No tool call needs more. */
+export const MAX_MCP_REQUEST_BYTES = 1024 * 1024;
+
+/** `AuthInfo.extra` key that carries the owner's user id to the factory. */
+const USER_ID_CLAIM = "userId";
+const BEARER_PREFIX = /^Bearer[ \t]+/i;
+const NO_STORE = { "cache-control": "no-store" };
+
+/** The app's MCP server for one request. It registers write tools only when `canWrite` is true. */
+export type McpServerFactory = (identity: McpServerIdentity) => McpServer | Server | Promise<McpServer | Server>;
+
+export interface McpEndpointOptions {
+  readonly createServer: McpServerFactory;
+}
+
+/** Serves one request to the MCP endpoint. */
+export type McpEndpoint = (ctx: McpAccessContext, request: Request) => Promise<Response>;
+
+/**
+ * The endpoint around the app's factory. The factory runs once per request with that request's
+ * identity, so one account's server never answers another's request. Answers are plain JSON
+ * (`responseMode: "json"`): a stream would add proxy buffering and timeouts for no tool that needs
+ * it, and mid-call notifications are dropped.
+ */
+export function createMcpEndpoint({ createServer }: McpEndpointOptions): McpEndpoint {
+  const handler = createMcpHandler(
+    (requestContext) => createServer(readIdentity(requestContext.authInfo)),
+    {
+      responseMode: "json",
+      maxRequestBodySize: MAX_MCP_REQUEST_BYTES,
+      onerror: (error) => console.error(`@softure-ai/mcp-access: the MCP handler reported: ${errorLogLabel(error)}`),
+    },
+  );
+
+  return async (ctx, request) => {
+    assertRateLimitBucket(ctx);
+    const client = identifyClient(ctx, request.headers);
+    if (!client.ok) return Response.json({ error: "client_unidentified" }, { status: 400, headers: NO_STORE });
+
+    let limit;
+    try {
+      // Counted before verification, so a flood of guesses is stopped before any lookup.
+      limit = await consumeRateLimit(ctx, { bucket: MCP_RATE_LIMIT_BUCKET, key: client.value });
+    } catch (error) {
+      // Fails closed and says nothing: the route is public and this runs before authentication.
+      console.error(`@softure-ai/mcp-access: counting a request failed: ${errorLogLabel(error)}`);
+      return Response.json({ error: "temporarily_unavailable" }, { status: 503, headers: NO_STORE });
+    }
+    if (!limit.ok) {
+      return Response.json(
+        { error: "too_many_requests" },
+        { status: 429, headers: { ...NO_STORE, "retry-after": String(limit.retryAfterSeconds) } },
+      );
+    }
+
+    const authInfo = await authenticate(ctx, request.headers.get("authorization"));
+    if (authInfo instanceof Response) return authInfo;
+    return handler.fetch(request, { authInfo });
+  };
+}
+
+/**
+ * The verified identity as the SDK's `AuthInfo`, or the challenge response. Unknown, revoked,
+ * expired and malformed tokens get the same `401 invalid_token`. Expiry is decided by the query on
+ * the module's clock, not by the SDK's own check on the wall clock.
+ */
+async function authenticate(ctx: McpAccessContext, header: string | null): Promise<AuthInfo | Response> {
+  const challenge = { requiredScopes: [MCP_READ_SCOPE] };
+  if (header === null || !BEARER_PREFIX.test(header)) {
+    return bearerAuthChallengeResponse(new OAuthError(OAuthErrorCode.InvalidToken, "Missing Bearer token"), challenge);
+  }
+  const token = header.replace(BEARER_PREFIX, "").trim();
+
+  let verified;
+  try {
+    verified = await verifyAccessToken(ctx, token);
+  } catch (error) {
+    console.error(`@softure-ai/mcp-access: verifying a token failed: ${errorLogLabel(error)}`);
+    return bearerAuthChallengeResponse(new OAuthError(OAuthErrorCode.ServerError, "Internal Server Error"), challenge);
+  }
+  if (verified === null) {
+    return bearerAuthChallengeResponse(new OAuthError(OAuthErrorCode.InvalidToken, "Invalid access token"), challenge);
+  }
+  return {
+    token,
+    // The client is the token: it is what gets revoked, and its id may be logged.
+    clientId: verified.tokenId,
+    scopes: verified.canWrite ? [MCP_READ_SCOPE, MCP_WRITE_SCOPE] : [MCP_READ_SCOPE],
+    // AuthInfo counts seconds; Date counts milliseconds.
+    expiresAt: Math.floor(verified.expiresAt.getTime() / 1000),
+    extra: { [USER_ID_CLAIM]: verified.userId },
+  };
+}
+
+/** The factory's input from the request's `AuthInfo`; throws when the two sides disagree. */
+function readIdentity(authInfo: AuthInfo | undefined): McpServerIdentity {
+  const userId = authInfo?.extra?.[USER_ID_CLAIM];
+  if (authInfo === undefined || typeof userId !== "string" || userId === "") {
+    // Unreachable through the endpoint, which always passes a verified identity. A server built
+    // without one would run queries with no account scope, so this refuses instead.
+    throw new Error("@softure-ai/mcp-access: an MCP request reached the factory without a verified identity");
+  }
+  return { userId, canWrite: authInfo.scopes.includes(MCP_WRITE_SCOPE), tokenId: authInfo.clientId };
+}
+
+/** A missing bucket is a setup bug: thrown, so it reaches the log by name instead of a quiet 503. */
+function assertRateLimitBucket(ctx: McpAccessContext): void {
+  const options = getModule(ctx.config, "security")?.options as { buckets?: Record<string, unknown> } | undefined;
+  if (options?.buckets?.[MCP_RATE_LIMIT_BUCKET] === undefined) {
+    throw new Error(
+      `@softure-ai/mcp-access: the security module has no "${MCP_RATE_LIMIT_BUCKET}" bucket; spread MCP_RATE_LIMIT_BUCKETS into security({ buckets })`,
+    );
+  }
+}

package/src/server/health.ts

@@ -0,0 +1,12 @@
+// The module's readiness probe for `GET /api/health` of `@softure-ai/ops`: the tokens table exists
+// and answers, i.e. `softure migrate` ran. It reads no rows.
+import { ok, type HealthCheck } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { sql } from "drizzle-orm";
+
+export const checkAccessTokensTable: HealthCheck = async (context) => {
+  // Core types `db` as unknown; the health route passes the @softure-ai/db handle.
+  const db = context.db as Queryable;
+  await db.execute(sql`select 1 from mcp.access_tokens limit 0`);
+  return ok();
+};

package/src/server/index.ts

@@ -0,0 +1,36 @@
+// Server-only API of @softure-ai/mcp-access. Every function receives the module context
+// (`{ db, clock, config }`) and never reads request scope; the endpoint takes a Web `Request`.
+export {
+  createMcpEndpoint,
+  MAX_MCP_REQUEST_BYTES,
+  MCP_RATE_LIMIT_BUCKET,
+  MCP_READ_SCOPE,
+  MCP_WRITE_SCOPE,
+  type McpEndpoint,
+  type McpEndpointOptions,
+  type McpServerFactory,
+} from "./endpoint.js";
+export { checkAccessTokensTable } from "./health.js";
+export { getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes, getMcpEndpointUrl, type McpAccessRoutes } from "./options.js";
+export {
+  deleteMcpAccessUserData,
+  exportMcpAccessUserData,
+  mcpAccessPrivacyContributor,
+  type McpAccessUserData,
+} from "./privacy.js";
+export {
+  ACCESS_TOKEN_PREFIX,
+  hashAccessToken,
+  isAccessTokenShape,
+  issueAccessToken,
+  listAccessTokens,
+  pruneAccessTokens,
+  revokeAccessToken,
+  verifyAccessToken,
+  type IssueAccessTokenInput,
+  type IssueAccessTokenResult,
+  type IssuedAccessToken,
+  type McpAccessContext,
+  type RevokeAccessTokenInput,
+  type VerifiedAccessToken,
+} from "./tokens.js";

package/src/server/options.ts

@@ -0,0 +1,54 @@
+// The mcp-access options of the running app, read from the configuration in the module context.
+import { getModule, type Locale, type SoftureConfig } from "@softure-ai/core";
+import type { McpAccessMessages } from "../messages/index.js";
+import type { McpAccessOptions } from "../options.js";
+
+const MODULE_ID = "mcp-access";
+
+/** The enabled module. Throws when the app did not enable it: calling its functions then is a bug. */
+export function getMcpAccessModule(config: SoftureConfig) {
+  const module = getModule(config, MODULE_ID);
+  if (module === undefined) {
+    throw new Error("@softure-ai/mcp-access: the module is not enabled; add mcpAccess({ ... }) to modules in softure.config.ts");
+  }
+  return module;
+}
+
+export function getMcpAccessOptions(config: SoftureConfig): McpAccessOptions {
+  // The module factory parsed these options with mcpAccessOptionsSchema.
+  return getMcpAccessModule(config).options as McpAccessOptions;
+}
+
+export interface McpAccessRoutes {
+  /** The token page. */
+  readonly page: string;
+  /** `POST` MCP endpoint. */
+  readonly endpoint: string;
+}
+
+export function getMcpAccessRoutes(config: SoftureConfig): McpAccessRoutes {
+  const routes = getMcpAccessModule(config).routes;
+  const read = (name: keyof McpAccessRoutes): string => {
+    const path = routes[name];
+    // The manifest declares every route, so a missing one means a broken module definition.
+    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") };
+}
+
+/** 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 module's copy in the app's locale, with the app's overrides applied. */
+export function getMcpAccessMessages(config: SoftureConfig): McpAccessMessages {
+  // The module factory merged the dictionaries; their shape is the module's own.
+  return getMcpAccessModule(config).messages[config.locale] as McpAccessMessages;
+}
+
+/** The text in `locale`, else in `en`. */
+export function getLocalizedText(text: Partial<Record<Locale, string>>, locale: Locale): string {
+  return text[locale] ?? text.en ?? "";
+}

package/src/server/privacy.ts

@@ -0,0 +1,49 @@
+// 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.
+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";
+
+/** What mcp-access holds about one user, as it appears in their export. */
+export interface McpAccessUserData {
+  readonly accessTokens: readonly {
+    readonly name: string;
+    readonly canWrite: boolean;
+    readonly createdAt: Date;
+    readonly expiresAt: 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: [] });
+  // 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
+    .select({
+      name: accessTokens.name,
+      canWrite: accessTokens.canWrite,
+      createdAt: accessTokens.createdAt,
+      expiresAt: accessTokens.expiresAt,
+      lastUsedAt: accessTokens.lastUsedAt,
+    })
+    .from(accessTokens)
+    .where(eq(accessTokens.userId, userId))
+    .orderBy(asc(accessTokens.createdAt));
+  return ok({ accessTokens: rows });
+}
+
+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));
+  return ok();
+}
+
+export const mcpAccessPrivacyContributor: PrivacyContributor = {
+  exportUserData: exportMcpAccessUserData,
+  deleteUserData: deleteMcpAccessUserData,
+};

package/src/server/tokens.ts

@@ -0,0 +1,188 @@
+// 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`.
+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 { getMcpAccessOptions } from "./options.js";
+
+export type McpAccessContext = ModuleContext<Queryable>;
+
+/** Marks a token as this module's, for people and for secret scanners. */
+export const ACCESS_TOKEN_PREFIX = "sftmcp_";
+
+const TOKEN_BYTES = 32;
+/** The prefix and base64url of 32 bytes. */
+const TOKEN_SHAPE = /^sftmcp_[A-Za-z0-9_-]{43}$/;
+const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** `last_used_at` answers "is this token still in use?"; a minute is precise enough for that. */
+const LAST_USED_RESOLUTION_MS = 60_000;
+
+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. */
+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) };
+}
+
+export interface IssueAccessTokenInput {
+  /** The auth user id of the owner, from the session. */
+  readonly userId: string;
+  readonly name: string;
+  /** Asked for write access; granted only while the app allows writes. */
+  readonly canWrite: boolean;
+}
+
+export interface IssuedAccessToken {
+  readonly id: string;
+  /** The plaintext: shown to the owner once, stored nowhere. */
+  readonly token: string;
+  readonly name: string;
+  readonly canWrite: boolean;
+  readonly expiresAt: Date;
+}
+
+export type IssueAccessTokenResult =
+  | Ok<IssuedAccessToken>
+  | 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.
+ * Database failures propagate.
+ */
+export async function issueAccessToken(ctx: McpAccessContext, input: IssueAccessTokenInput): Promise<IssueAccessTokenResult> {
+  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> => {
+    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));
+    if ((held?.total ?? 0) >= options.maxTokensPerUser) return err("mcp-access.token_limit_reached");
+
+    const { token, tokenHash } = createAccessTokenSecret();
+    const [row] = await tx
+      .insert(accessTokens)
+      .values({ userId: input.userId, name, tokenHash, canWrite, createdAt: now, expiresAt })
+      .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 });
+  });
+}
+
+/** The owner's tokens, newest first, expired ones included (the list marks them). */
+export async function listAccessTokens(ctx: McpAccessContext, userId: string): Promise<AccessTokenView[]> {
+  return ctx.db
+    .select({
+      id: accessTokens.id,
+      name: accessTokens.name,
+      canWrite: accessTokens.canWrite,
+      createdAt: accessTokens.createdAt,
+      expiresAt: accessTokens.expiresAt,
+      lastUsedAt: accessTokens.lastUsedAt,
+    })
+    .from(accessTokens)
+    .where(eq(accessTokens.userId, userId))
+    .orderBy(desc(accessTokens.createdAt), desc(accessTokens.id));
+}
+
+export interface RevokeAccessTokenInput {
+  /** The owner, from the session. */
+  readonly userId: string;
+  /** From the form: any value, including another account's token id. */
+  readonly tokenId: string;
+}
+
+/**
+ * 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.
+ */
+export async function revokeAccessToken(
+  ctx: McpAccessContext,
+  input: RevokeAccessTokenInput,
+): Promise<Ok<undefined> | Err<"mcp-access.token_not_found">> {
+  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)))
+    .returning();
+  return removed.length > 0 ? ok() : err("mcp-access.token_not_found");
+}
+
+/** The identity behind a valid token. */
+export interface VerifiedAccessToken {
+  readonly tokenId: string;
+  readonly userId: string;
+  /** Effective write access: the token was issued for writes and the app allows them now. */
+  readonly canWrite: boolean;
+  readonly expiresAt: Date;
+}
+
+/**
+ * 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.
+ */
+export async function verifyAccessToken(ctx: McpAccessContext, token: string): Promise<VerifiedAccessToken | null> {
+  if (!isAccessTokenShape(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 })
+    .from(accessTokens)
+    .where(and(eq(accessTokens.tokenHash, hashAccessToken(token)), gt(accessTokens.expiresAt, now)));
+  if (row === undefined) return null;
+
+  await recordUse(ctx, row.id, now);
+  return {
+    tokenId: row.id,
+    userId: row.userId,
+    canWrite: row.canWrite && getMcpAccessOptions(ctx.config).allowWrites,
+    expiresAt: row.expiresAt,
+  };
+}
+
+async function recordUse(ctx: McpAccessContext, tokenId: string, 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))));
+  } 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)}`);
+  }
+}
+
+/**
+ * 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.
+ */
+export async function pruneAccessTokens(ctx: McpAccessContext): Promise<number> {
+  const removed = await ctx.db
+    .delete(accessTokens)
+    .where(lte(accessTokens.expiresAt, ctx.clock.now()))
+    .returning();
+  return removed.length;
+}