@raybase/core 0.0.2 → 0.3.3

package/dist/mcp.js

@@ -0,0 +1,2480 @@
+import { z } from "zod";
+import { withHostUserRoleCeiling } from "./host-user.js";
+import { redactSecretColumnKeys, secretColumnKeys } from "./data-secrets.js";
+import { audit, base64url, normalizeRoles } from "./auth.js";
+import { hasAdminAccess, normalizeStoredAdminRole } from "./admin-role.js";
+import { inputSchemaForTable } from "./data-client.js";
+import { createRaybaseDb, dataStub } from "./db.js";
+import { sha256Hex } from "./internal.js";
+import { jsonSchemaFor } from "./json-schema.js";
+import { searchIndex, updateSearchForDataChange } from "./search.js";
+import { id, longText, raybaseSystemTable, text } from "./schema.js";
+import { randomId } from "./sql.js";
+import { wallNowIso as nowIso, wallNowMs } from "./clock.js";
+import { ensureManifestTables } from "./system-tables.js";
+export const mcpAppsExtensionId = "io.modelcontextprotocol/ui";
+export const mcpAppResourceMimeType = "text/html;profile=mcp-app";
+const jsonHeaders = { "content-type": "application/json; charset=utf-8" };
+const defaultAccessTokenTtlSeconds = 60 * 60;
+const defaultRefreshTokenTtlSeconds = 60 * 60 * 24 * 30;
+const defaultGrantTtlSeconds = 60 * 60 * 24 * 90;
+// Best-effort per-isolate limits. Durable/fleet-wide abuse controls belong at
+// the edge or in a future persistent limiter.
+const rateLimitWindows = new Map();
+export const raybaseMcpSystemTables = [
+    raybaseSystemTable("_oauth_clients", {
+        id: text({ primaryKey: true, required: true }),
+        clientId: text({ required: true, unique: true }),
+        clientName: text({ required: true }),
+        redirectUris: longText({ required: true }),
+        metadata: longText(),
+        createdAt: text({ required: true }),
+        revokedAt: text(),
+        // Confidential clients (client_credentials). Public PKCE clients leave
+        // these null; the secret is stored only as a SHA-256 hash.
+        clientSecretHash: longText(),
+        tokenEndpointAuthMethod: text(),
+        grantTypes: longText(),
+        scopes: longText(),
+        resource: longText(),
+        grantId: text(),
+        createdByUserId: text(),
+        organizationId: text()
+    }, { indexes: [["clientId"], ["createdByUserId"], ["grantId"]] }),
+    raybaseSystemTable("_oauth_authorization_codes", {
+        id: id(),
+        codeHash: longText({ required: true, unique: true }),
+        clientId: text({ required: true }),
+        redirectUri: longText({ required: true }),
+        scope: longText({ required: true }),
+        resource: longText({ required: true }),
+        codeChallenge: longText({ required: true }),
+        codeChallengeMethod: text({ required: true }),
+        grantId: text({ required: true }),
+        userId: text({ required: true }),
+        hostAccount: text(),
+        state: longText(),
+        expiresAt: text({ required: true }),
+        consumedAt: text(),
+        createdAt: text({ required: true })
+    }, { indexes: [["clientId"], ["grantId"], ["userId"]] }),
+    raybaseSystemTable("_oauth_access_tokens", {
+        id: id(),
+        tokenHash: longText({ required: true, unique: true }),
+        grantId: text({ required: true }),
+        clientId: text({ required: true }),
+        userId: text({ required: true }),
+        resource: longText({ required: true }),
+        scope: longText({ required: true }),
+        expiresAt: text({ required: true }),
+        revokedAt: text(),
+        createdAt: text({ required: true }),
+        lastUsedAt: text()
+    }, { indexes: [["grantId"], ["clientId"], ["userId"]] }),
+    raybaseSystemTable("_oauth_refresh_tokens", {
+        id: id(),
+        tokenHash: longText({ required: true, unique: true }),
+        grantId: text({ required: true }),
+        clientId: text({ required: true }),
+        userId: text({ required: true }),
+        scope: longText({ required: true }),
+        expiresAt: text({ required: true }),
+        revokedAt: text(),
+        replacedBy: text(),
+        createdAt: text({ required: true })
+    }, { indexes: [["grantId"], ["clientId"], ["userId"]] }),
+    raybaseSystemTable("_mcp_grants", {
+        id: id(),
+        subjectType: text({ required: true }),
+        subjectId: text({ required: true }),
+        userId: text(),
+        hostAccount: text(),
+        clientId: text({ required: true }),
+        clientName: text({ required: true }),
+        scopes: longText({ required: true }),
+        resource: longText({ required: true }),
+        createdAt: text({ required: true }),
+        expiresAt: text(),
+        revokedAt: text(),
+        lastUsedAt: text(),
+        organizationId: text(),
+        grantType: text()
+    }, { indexes: [["clientId"], ["userId"], ["hostAccount"]] }),
+    raybaseSystemTable("_mcp_grant_events", {
+        id: id(),
+        grantId: text({ required: true }),
+        clientId: text({ required: true }),
+        action: text({ required: true }),
+        toolName: text(),
+        metadata: longText(),
+        createdAt: text({ required: true })
+    }, { indexes: [["grantId"], ["clientId"], ["action"]] }),
+    raybaseSystemTable("_mcp_pending_authorizations", {
+        id: id(),
+        clientId: text({ required: true }),
+        redirectUri: longText({ required: true }),
+        scope: longText({ required: true }),
+        resource: longText({ required: true }),
+        state: longText(),
+        codeChallenge: longText({ required: true }),
+        hostAccount: text(),
+        expiresAt: text({ required: true }),
+        createdAt: text({ required: true })
+    }, { indexes: [["clientId"], ["hostAccount"]] }),
+    raybaseSystemTable("_mcp_approval_tickets", {
+        id: id(),
+        ticketHash: longText({ required: true, unique: true }),
+        pendingAuthId: text({ required: true }),
+        hostAccount: text({ required: true }),
+        clientId: text({ required: true }),
+        scope: longText({ required: true }),
+        expiresAt: text({ required: true }),
+        consumedAt: text(),
+        createdAt: text({ required: true })
+    }, { indexes: [["pendingAuthId"], ["hostAccount"], ["clientId"]] })
+];
+async function ensureMcpSystemTables(db) {
+    await ensureManifestTables(db, raybaseMcpSystemTables);
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function asString(value) {
+    return typeof value === "string" ? value : "";
+}
+function isRecordValue(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function splitScopes(value) {
+    const raw = Array.isArray(value) ? value.join(" ") : value ?? "";
+    return [...new Set(raw.split(/\s+/).map((scope) => scope.trim()).filter(Boolean))];
+}
+export function normalizeMcpAppVisibility(value) {
+    if (value === undefined)
+        return ["model", "app"];
+    if (!Array.isArray(value))
+        throw new Error("MCP Apps tool visibility must be an array");
+    const output = [];
+    for (const entry of value) {
+        if (entry !== "model" && entry !== "app")
+            throw new Error(`Unsupported MCP Apps tool visibility: ${String(entry)}`);
+        if (!output.includes(entry))
+            output.push(entry);
+    }
+    return output.length ? output : ["model", "app"];
+}
+export function isMcpAppResource(resource) {
+    return resource.uri.startsWith("ui://") || resource.mimeType === mcpAppResourceMimeType;
+}
+export function validateMcpAppResourceMeta(meta) {
+    const ui = meta?.ui;
+    if (ui === undefined)
+        return;
+    if (!isRecordValue(ui))
+        throw new Error("MCP Apps resource _meta.ui must be an object");
+    for (const key of ["connectDomains", "resourceDomains", "frameDomains", "baseUriDomains"]) {
+        if (key in ui)
+            throw new Error(`MCP Apps resource _meta.ui.${key} moved to _meta.ui.csp.${key}`);
+    }
+    if (ui.csp !== undefined) {
+        if (!isRecordValue(ui.csp))
+            throw new Error("MCP Apps resource _meta.ui.csp must be an object");
+        const csp = ui.csp;
+        for (const key of ["connectDomains", "resourceDomains", "frameDomains", "baseUriDomains"]) {
+            const value = csp[key];
+            if (value !== undefined && (!Array.isArray(value) || value.some((entry) => typeof entry !== "string"))) {
+                throw new Error(`MCP Apps resource _meta.ui.csp.${key} must be a string array`);
+            }
+        }
+    }
+    if (ui.permissions !== undefined) {
+        if (!isRecordValue(ui.permissions))
+            throw new Error("MCP Apps resource _meta.ui.permissions must be an object");
+        const permissions = ui.permissions;
+        for (const key of Object.keys(permissions)) {
+            if (!["camera", "microphone", "geolocation", "clipboardWrite"].includes(key))
+                throw new Error(`Unsupported MCP Apps resource permission: ${key}`);
+            const permission = permissions[key];
+            if (!isRecordValue(permission))
+                throw new Error(`MCP Apps resource permission ${key} must be an object`);
+            if (Object.keys(permission).length)
+                throw new Error(`MCP Apps resource permission ${key} must be an empty object`);
+        }
+    }
+    if (ui.domain !== undefined && typeof ui.domain !== "string")
+        throw new Error("MCP Apps resource _meta.ui.domain must be a string");
+    if (ui.prefersBorder !== undefined && typeof ui.prefersBorder !== "boolean")
+        throw new Error("MCP Apps resource _meta.ui.prefersBorder must be a boolean");
+}
+export function validateMcpAppResource(resource) {
+    if (!isMcpAppResource(resource)) {
+        validateMcpAppResourceMeta(resource._meta);
+        return;
+    }
+    if (!resource.uri.startsWith("ui://"))
+        throw new Error(`MCP Apps resource ${resource.name} must use a ui:// URI`);
+    if (resource.mimeType !== mcpAppResourceMimeType)
+        throw new Error(`MCP Apps resource ${resource.uri} must use MIME type ${mcpAppResourceMimeType}`);
+    validateMcpAppResourceMeta(resource._meta);
+}
+export function validateMcpAppTool(tool, resources) {
+    const ui = tool._meta?.ui;
+    if (ui === undefined)
+        return;
+    if (!isRecordValue(ui))
+        throw new Error(`MCP Apps tool ${tool.name} _meta.ui must be an object`);
+    normalizeMcpAppVisibility(ui.visibility);
+    if (ui.resourceUri !== undefined) {
+        if (typeof ui.resourceUri !== "string" || !ui.resourceUri)
+            throw new Error(`MCP Apps tool ${tool.name} _meta.ui.resourceUri must be a non-empty string`);
+        if (!resources.some((resource) => resource.uri === ui.resourceUri))
+            throw new Error(`MCP Apps tool ${tool.name} references missing UI resource: ${ui.resourceUri}`);
+    }
+}
+function mcpAppResourceMeta(meta) {
+    if (!meta)
+        return undefined;
+    validateMcpAppResourceMeta(meta);
+    return meta;
+}
+function mergeMcpResourceReadMeta(resourceMeta, readMeta) {
+    if (!resourceMeta && !readMeta)
+        return undefined;
+    const merged = { ...(resourceMeta ?? {}), ...(readMeta ?? {}) };
+    validateMcpAppResourceMeta(merged);
+    return merged;
+}
+function normalizeMcpAppResourceRead(resource, read) {
+    if (!isMcpAppResource(resource))
+        return read;
+    if (read.uri && read.uri !== resource.uri)
+        throw new Error(`MCP Apps resource read URI must match ${resource.uri}`);
+    if (read.mimeType && read.mimeType !== mcpAppResourceMimeType)
+        throw new Error(`MCP Apps resource read MIME type must be ${mcpAppResourceMimeType}`);
+    if (read.text === undefined && read.blob === undefined)
+        throw new Error(`MCP Apps resource ${resource.uri} must return text or blob content`);
+    const meta = mergeMcpResourceReadMeta(resource._meta, read._meta);
+    return {
+        ...read,
+        uri: resource.uri,
+        mimeType: mcpAppResourceMimeType,
+        ...(meta ? { _meta: meta } : {})
+    };
+}
+function toolMcpAppVisibility(tool) {
+    return normalizeMcpAppVisibility(tool._meta?.ui?.visibility);
+}
+function toolVisibleToModel(tool) {
+    return toolMcpAppVisibility(tool).includes("model");
+}
+function supportsMcpAppUi(tools, resources) {
+    return tools.some((tool) => Boolean(tool._meta?.ui)) || resources.some(isMcpAppResource);
+}
+function clientAcceptsMcpAppUi(params) {
+    const capabilities = asRecord(asRecord(params).capabilities);
+    const extensions = asRecord(capabilities.extensions);
+    const ui = extensions[mcpAppsExtensionId];
+    if (!isRecordValue(ui))
+        return false;
+    const mimeTypes = ui.mimeTypes;
+    return mimeTypes === undefined || (Array.isArray(mimeTypes) && mimeTypes.includes(mcpAppResourceMimeType));
+}
+export function withMcpAppUi(tool, ui) {
+    const normalizedUi = {
+        ...ui,
+        visibility: normalizeMcpAppVisibility(ui.visibility)
+    };
+    return {
+        ...tool,
+        _meta: {
+            ...(tool._meta ?? {}),
+            ui: {
+                ...(tool._meta?.ui ?? {}),
+                ...normalizedUi
+            }
+        }
+    };
+}
+export function createMcpAppResource(input) {
+    const hasHtml = input.html !== undefined;
+    const hasBlob = input.blob !== undefined;
+    if (!hasHtml && !hasBlob && !input.read)
+        throw new Error(`MCP Apps resource ${input.uri} must provide html, blob, or read`);
+    const resource = {
+        uri: input.uri,
+        name: input.name,
+        description: input.description,
+        mimeType: mcpAppResourceMimeType,
+        scopes: input.scopes,
+        _meta: mcpAppResourceMeta(input._meta),
+        read: input.read
+            ? async (ctx) => normalizeMcpAppResourceRead(resource, await input.read(ctx))
+            : async () => normalizeMcpAppResourceRead(resource, {
+                uri: input.uri,
+                mimeType: mcpAppResourceMimeType,
+                ...(hasHtml ? { text: input.html } : { blob: input.blob }),
+                ...(input._meta ? { _meta: input._meta } : {})
+            })
+    };
+    validateMcpAppResource(resource);
+    return resource;
+}
+function hasScope(granted, required) {
+    return granted.includes(required);
+}
+function hasAnyScope(granted, required) {
+    return required.length === 0 || required.some((scope) => hasScope(granted, scope));
+}
+function requiredScopesForTool(tool) {
+    if (tool.scopes?.length)
+        return tool.scopes;
+    if (tool.annotations?.readOnlyHint)
+        return ["mcp:read", `mcp:tool:${tool.name}`];
+    return ["mcp:write", `mcp:tool:${tool.name}`];
+}
+function requiredScopesForResource(resource) {
+    return resource?.scopes?.length ? resource.scopes : ["mcp:read"];
+}
+function jsonResponse(body, init = {}) {
+    const headers = new Headers(init.headers);
+    if (!headers.has("content-type"))
+        headers.set("content-type", jsonHeaders["content-type"]);
+    return new Response(JSON.stringify(body), { ...init, headers });
+}
+function methodNotAllowed() {
+    return jsonResponse({ error: "Method not allowed" }, { status: 405, headers: { allow: "POST, OPTIONS" } });
+}
+function serverOrigin(request) {
+    const url = new URL(request.url);
+    return `${url.protocol}//${url.host}`;
+}
+function endpointPath(config) {
+    const raw = config.mcp?.endpoint || "/mcp";
+    return raw.startsWith("/") ? raw : `/${raw}`;
+}
+export function canonicalMcpResource(request, config) {
+    return `${serverOrigin(request)}${endpointPath(config)}`;
+}
+function normalizeEndpointPath(raw, fallback) {
+    const value = raw || fallback;
+    return value.startsWith("/") ? value : `/${value}`;
+}
+export function operatorMcpEndpoint(config) {
+    return normalizeEndpointPath(config.mcp?.operator?.endpoint, "/mcp/operator");
+}
+export function operatorMcpEnabled(config) {
+    return config.mcp?.enabled === true && config.mcp?.operator?.enabled !== false;
+}
+export function canonicalOperatorMcpResource(request, config) {
+    return `${serverOrigin(request)}${operatorMcpEndpoint(config)}`;
+}
+function canonicalMcpResourceForSurface(request, config, surface = "app") {
+    return surface === "operator" ? canonicalOperatorMcpResource(request, config) : canonicalMcpResource(request, config);
+}
+export const operatorMcpScopes = [
+    "operator:read",
+    "operator:health:read",
+    "operator:schema:read",
+    "operator:policy:read",
+    "operator:users:read",
+    "operator:orgs:read",
+    "operator:audit:read",
+    "operator:imports:read",
+    "operator:jobs:read",
+    "operator:retrieval:read",
+    "operator:search:read",
+    "operator:mcp-grants:read",
+    "operator:backups:read",
+    "operator:storage:read",
+    "operator:app-data:read",
+    "operator:app-data:write",
+    "operator:app-data:delete",
+    "operator:settings:write",
+    "operator:users:invite",
+    "operator:users:lifecycle",
+    "operator:findings:read",
+    "operator:feedback:read",
+    "operator:support:read",
+    "operator:agent:read",
+    "operator:agent-skills:read",
+    "operator:agent-skills:write",
+    "operator:agent-remote-mcp:read",
+    "operator:agent-remote-mcp:write",
+    "operator:ai:read",
+    "operator:fleet:read"
+];
+/** The connector's name: `mcp.name`, else the app's name. */
+export function mcpConnectorName(config) {
+    return config.mcp?.name?.trim() || config.appName || "Raybase";
+}
+const maxMcpInstructionsLength = 8192;
+/** `mcp.instructions` as `initialize` returns it, or undefined when unset. */
+export function mcpInstructions(config) {
+    const value = config.mcp?.instructions;
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error("mcp.instructions must be a string");
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.length > maxMcpInstructionsLength)
+        throw new Error(`mcp.instructions is ${trimmed.length} characters; the limit is ${maxMcpInstructionsLength}`);
+    return trimmed;
+}
+function operatorScopes(options = {}) {
+    return [...new Set([...operatorMcpScopes, ...(options.operatorPermissions ?? [])])];
+}
+function mcpSurfaces(request, config, options = {}) {
+    const surfaces = [
+        {
+            id: "app",
+            label: mcpConnectorName(config),
+            resource: canonicalMcpResource(request, config),
+            defaultScope: "mcp:read mcp:write",
+            scopesSupported: ["mcp:read", "mcp:write"]
+        }
+    ];
+    if (operatorMcpEnabled(config)) {
+        surfaces.push({
+            id: "operator",
+            label: "Operator MCP",
+            resource: canonicalOperatorMcpResource(request, config),
+            defaultScope: "operator:read",
+            scopesSupported: operatorScopes(options)
+        });
+    }
+    return surfaces;
+}
+function mcpSurfaceForResource(request, config, resource, options = {}) {
+    return mcpSurfaces(request, config, options).find((surface) => surface.resource === resource) ?? null;
+}
+function isOperatorScope(scope) {
+    return scope.startsWith("operator:");
+}
+function isCoreOperatorOnlyScope(scope) {
+    return scope === "operator:fleet:read" || /^operator:org:[^:]+:read$/.test(scope);
+}
+function canApproveOperatorMcp(user) {
+    return hasAdminAccess(user.operatorRole);
+}
+function oauthConfig(config) {
+    return {
+        enabled: config.mcp?.oauth?.enabled !== false,
+        dynamicClientRegistration: config.mcp?.oauth?.dynamicClientRegistration !== false,
+        clientCredentials: config.mcp?.oauth?.clientCredentials !== false,
+        allowedClientRedirectHosts: config.mcp?.oauth?.allowedClientRedirectHosts ?? [],
+        allowedClientMetadataHosts: config.mcp?.oauth?.allowedClientMetadataHosts ?? [],
+        accessTokenTtlSeconds: config.mcp?.oauth?.accessTokenTtlSeconds ?? defaultAccessTokenTtlSeconds,
+        refreshTokenTtlSeconds: config.mcp?.oauth?.refreshTokenTtlSeconds ?? defaultRefreshTokenTtlSeconds
+    };
+}
+function rateLimitKey(request, bucket) {
+    const ip = request.headers.get("cf-connecting-ip") || request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() || "unknown";
+    const origin = request.headers.get("origin") || new URL(request.url).origin;
+    return `${bucket}:${ip}:${origin}`;
+}
+export function checkMcpRateLimit(request, bucket, limit = 60, windowMs = 60_000) {
+    const key = rateLimitKey(request, bucket);
+    const now = wallNowMs();
+    const current = rateLimitWindows.get(key);
+    if (!current || current.resetAt <= now) {
+        rateLimitWindows.set(key, { count: 1, resetAt: now + windowMs });
+        return null;
+    }
+    current.count += 1;
+    if (current.count <= limit)
+        return null;
+    return jsonResponse({ error: "Rate limit exceeded" }, { status: 429, headers: { "retry-after": String(Math.ceil((current.resetAt - now) / 1000)) } });
+}
+function corsHeaders(request, config) {
+    const headers = new Headers();
+    const origin = request.headers.get("origin");
+    if (origin && isAllowedOrigin(origin, request, config)) {
+        headers.set("access-control-allow-origin", origin);
+        headers.set("vary", "Origin");
+        headers.set("access-control-allow-methods", "POST, OPTIONS");
+        headers.set("access-control-allow-headers", "authorization, content-type, accept, mcp-protocol-version");
+        headers.set("access-control-max-age", "600");
+    }
+    return headers;
+}
+export function isAllowedOrigin(origin, request, config) {
+    let parsed;
+    try {
+        parsed = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    const current = new URL(request.url);
+    if (parsed.origin === current.origin)
+        return true;
+    const allowedHosts = oauthConfig(config).allowedClientRedirectHosts;
+    if (allowedHosts.includes("*"))
+        return true;
+    if (!allowedHosts.length) {
+        return config.mcp?.enabled === true && config.mcp?.oauth?.enabled !== false && config.mcp?.oauth?.dynamicClientRegistration !== false;
+    }
+    return hostnameAllowed(parsed.host, allowedHosts) || hostnameAllowed(parsed.hostname, allowedHosts);
+}
+function validateOrigin(request, config) {
+    const origin = request.headers.get("origin");
+    if (!origin || isAllowedOrigin(origin, request, config))
+        return null;
+    return jsonResponse({ error: "Origin is not allowed" }, { status: 403 });
+}
+function validateAccept(request) {
+    const accept = request.headers.get("accept");
+    if (!accept || accept.includes("*/*") || accept.includes("application/json") || accept.includes("text/event-stream"))
+        return null;
+    return jsonResponse({ error: "MCP endpoint requires Accept: application/json or text/event-stream" }, { status: 406 });
+}
+/**
+ * Which connector a metadata request is about, from the path after
+ * `/.well-known/oauth-protected-resource` or `/.well-known/oauth-authorization-server`:
+ * nothing or the app's endpoint is the app connector, the operator endpoint is
+ * the operator connector (when it is on), anything else is no connector.
+ */
+export function mcpMetadataSurface(config, suffix) {
+    const path = suffix.replace(/\/+$/, "");
+    if (path === "" || path === endpointPath(config))
+        return "app";
+    if (operatorMcpEnabled(config) && path === operatorMcpEndpoint(config))
+        return "operator";
+    return null;
+}
+function surfaceScopes(config, options, surface) {
+    return surface === "operator" && operatorMcpEnabled(config) ? operatorScopes(options) : ["mcp:read", "mcp:write"];
+}
+/**
+ * RFC 9728 metadata for one connector. It announces that connector's scopes
+ * and nothing else, so a product that asks for every scope it is told about
+ * asks only for what the connector grants.
+ */
+export function protectedResourceMetadata(request, config, options = {}, authorizationServer, surface = "app") {
+    const resource = canonicalMcpResourceForSurface(request, config, surface);
+    const issuer = authorizationServer ?? serverOrigin(request);
+    return {
+        resource,
+        resource_name: surface === "operator" ? `${mcpConnectorName(config)} (operator)` : mcpConnectorName(config),
+        authorization_servers: [issuer],
+        bearer_methods_supported: ["header"],
+        scopes_supported: surfaceScopes(config, options, surface),
+        resource_documentation: `${issuer}/docs/mcp`
+    };
+}
+/**
+ * RFC 8414 metadata. `scopes_supported` is the app connector's unless the
+ * request names the operator connector (`/.well-known/oauth-authorization-server/mcp/operator`).
+ */
+export function authorizationServerMetadata(request, options = {}, authorizationServer, surface = "app", config) {
+    const issuer = authorizationServer ?? serverOrigin(request);
+    const scopeConfig = config ?? { appName: "Raybase", mcp: { enabled: true } };
+    return {
+        issuer,
+        authorization_endpoint: `${issuer}/api/auth/oauth/authorize`,
+        token_endpoint: `${issuer}/api/auth/oauth/token`,
+        registration_endpoint: `${issuer}/api/auth/oauth/register`,
+        revocation_endpoint: `${issuer}/api/auth/oauth/revoke`,
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code", "refresh_token", "client_credentials"],
+        code_challenge_methods_supported: ["S256"],
+        token_endpoint_auth_methods_supported: ["none", "client_secret_basic", "client_secret_post"],
+        scopes_supported: surfaceScopes(scopeConfig, options, surface),
+        // A client may name itself by the HTTPS address of its metadata document
+        // (OAuth Client ID Metadata Documents) instead of registering.
+        client_id_metadata_document_supported: true,
+        // RFC 9207: the redirect back from consent carries `iss`.
+        authorization_response_iss_parameter_supported: true
+    };
+}
+export function wwwAuthenticate(request, config, surface = "app") {
+    const resource = canonicalMcpResourceForSurface(request, config, surface);
+    const metadataPath = surface === "operator" ? `/.well-known/oauth-protected-resource${operatorMcpEndpoint(config)}` : "/.well-known/oauth-protected-resource";
+    const scope = surface === "operator" ? "operator:read" : "mcp:read mcp:write";
+    return `Bearer resource_metadata="${serverOrigin(request)}${metadataPath}", resource="${resource}", scope="${scope}"`;
+}
+function unauthorizedMcpResponse(request, config, error, surface = "app") {
+    return jsonResponse({ error }, {
+        status: 401,
+        headers: { "www-authenticate": wwwAuthenticate(request, config, surface), ...Object.fromEntries(corsHeaders(request, config)) }
+    });
+}
+async function sha256Base64url(value) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+    return base64url(new Uint8Array(digest));
+}
+function randomToken(prefix) {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return `${prefix}_${base64url(bytes)}`;
+}
+function addSeconds(seconds) {
+    return new Date(wallNowMs() + seconds * 1000).toISOString();
+}
+function parseJson(value) {
+    if (typeof value !== "string" || !value)
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function formOrJson(request) {
+    const contentType = request.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        return request.json().then(asRecord).catch(() => ({}));
+    }
+    return request.formData().then((form) => {
+        const body = {};
+        for (const [key, value] of form.entries())
+            body[key] = typeof value === "string" ? value : value.name;
+        return body;
+    });
+}
+function parseRedirectUris(value) {
+    if (Array.isArray(value))
+        return value.map(String);
+    if (typeof value === "string") {
+        const parsed = parseJson(value);
+        if (Array.isArray(parsed))
+            return parsed.map(String);
+        return [value];
+    }
+    return [];
+}
+function hostnameAllowed(hostname, allowlist) {
+    if (!allowlist.length || allowlist.includes("*"))
+        return true;
+    return allowlist.includes(hostname);
+}
+function isLoopbackHost(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname.endsWith(".localhost");
+}
+function isPrivateIp(hostname) {
+    return (hostname === "0.0.0.0" ||
+        /^10\./.test(hostname) ||
+        /^127\./.test(hostname) ||
+        /^169\.254\./.test(hostname) ||
+        /^172\.(1[6-9]|2\d|3[0-1])\./.test(hostname) ||
+        /^192\.168\./.test(hostname) ||
+        hostname === "::1" ||
+        hostname.toLowerCase().startsWith("fc") ||
+        hostname.toLowerCase().startsWith("fd") ||
+        hostname.toLowerCase().startsWith("fe80:"));
+}
+function isUrlLikeClientId(value) {
+    return /^https:\/\//i.test(value);
+}
+export function validateRedirectUri(uri, allowedHosts = []) {
+    let parsed;
+    try {
+        parsed = new URL(uri);
+    }
+    catch {
+        throw new Error("redirect_uri must be an absolute URL");
+    }
+    if (uri.includes("*"))
+        throw new Error("Wildcard redirect URIs are not allowed");
+    const loopback = isLoopbackHost(parsed.hostname);
+    if (parsed.protocol !== "https:" && !(loopback && parsed.protocol === "http:")) {
+        throw new Error("redirect_uri must use HTTPS except loopback localhost");
+    }
+    if (!hostnameAllowed(parsed.hostname, allowedHosts) && !hostnameAllowed(parsed.host, allowedHosts)) {
+        throw new Error("redirect_uri host is not allowed");
+    }
+    return parsed.toString();
+}
+export function validateClientMetadataUrl(raw, allowedHosts = []) {
+    const parsed = new URL(raw);
+    if (parsed.protocol !== "https:")
+        throw new Error("Client metadata URLs must use HTTPS");
+    if (parsed.username || parsed.password)
+        throw new Error("Client metadata URLs must not contain credentials");
+    // Workers do not expose DNS resolution results before fetch. Keep URL-form
+    // client metadata constrained with HTTPS, private literal host rejection,
+    // redirect re-validation, and production allowlists.
+    if (isLoopbackHost(parsed.hostname) || isPrivateIp(parsed.hostname))
+        throw new Error("Private client metadata URLs are not allowed");
+    if (!hostnameAllowed(parsed.hostname, allowedHosts) && !hostnameAllowed(parsed.host, allowedHosts)) {
+        throw new Error("client metadata host is not allowed");
+    }
+    return parsed.toString();
+}
+export async function fetchClientMetadataDocument(raw, options = {}) {
+    const allowedHosts = options.allowedHosts ?? [];
+    const fetcher = options.fetcher ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 3000;
+    const maxBytes = options.maxBytes ?? 64 * 1024;
+    const maxRedirects = options.maxRedirects ?? 2;
+    let url = validateClientMetadataUrl(raw, allowedHosts);
+    for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount += 1) {
+        const abort = new AbortController();
+        const timeout = setTimeout(() => abort.abort(), timeoutMs);
+        let response;
+        try {
+            response = await fetcher(url, {
+                method: "GET",
+                redirect: "manual",
+                headers: { accept: "application/json" },
+                signal: abort.signal
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        const location = response.headers.get("location");
+        if (response.status >= 300 && response.status < 400 && location) {
+            if (redirectCount >= maxRedirects)
+                throw new Error("Client metadata redirect limit exceeded");
+            url = validateClientMetadataUrl(new URL(location, url).toString(), allowedHosts);
+            continue;
+        }
+        if (!response.ok)
+            throw new Error(`Client metadata document returned ${response.status}`);
+        const length = response.headers.get("content-length");
+        if (length && Number(length) > maxBytes)
+            throw new Error("Client metadata document is too large");
+        const text = await limitedResponseText(response, maxBytes);
+        const parsed = asRecord(JSON.parse(text));
+        const clientId = asString(parsed.client_id);
+        const clientName = asString(parsed.client_name).trim();
+        const redirectUris = parseRedirectUris(parsed.redirect_uris);
+        if (clientId !== raw)
+            throw new Error("Client metadata client_id must exactly match the metadata URL");
+        if (!clientName)
+            throw new Error("Client metadata document requires client_name");
+        if (!redirectUris.length)
+            throw new Error("Client metadata document requires redirect_uris");
+        return { ...parsed, client_id: clientId, client_name: clientName, redirect_uris: redirectUris };
+    }
+    throw new Error("Client metadata document could not be fetched");
+}
+async function limitedResponseText(response, maxBytes) {
+    if (!response.body) {
+        const text = await response.text();
+        if (new TextEncoder().encode(text).byteLength > maxBytes)
+            throw new Error("Client metadata document is too large");
+        return text;
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            throw new Error("Client metadata document is too large");
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(bytes);
+}
+const oauthClientColumns = `"clientId", "clientName", "redirectUris", "revokedAt", "clientSecretHash", "tokenEndpointAuthMethod", "grantTypes", "scopes", "resource", "grantId", "createdByUserId", "organizationId", "createdAt"`;
+async function clientById(db, clientId) {
+    return db.first(`SELECT ${oauthClientColumns} FROM "_oauth_clients" WHERE "clientId" = ?`, [clientId]);
+}
+function clientGrantTypes(client) {
+    const parsed = parseJson(client.grantTypes ?? null);
+    return Array.isArray(parsed) ? parsed.map(String) : ["authorization_code", "refresh_token"];
+}
+function isConfidentialClient(client) {
+    return Boolean(client.clientSecretHash) && clientGrantTypes(client).includes("client_credentials");
+}
+function oauthClientSummary(client) {
+    return {
+        clientId: client.clientId,
+        clientName: client.clientName,
+        grantId: client.grantId ?? null,
+        grantTypes: clientGrantTypes(client),
+        tokenEndpointAuthMethod: client.tokenEndpointAuthMethod ?? "none",
+        scopes: splitScopes(parseJson(client.scopes ?? null)),
+        resource: client.resource ?? null,
+        organizationId: client.organizationId ?? null,
+        createdByUserId: client.createdByUserId ?? null,
+        createdAt: client.createdAt ?? "",
+        revokedAt: client.revokedAt,
+        lastUsedAt: client.lastUsedAt ?? null
+    };
+}
+function timingSafeEqualStrings(left, right) {
+    const a = new TextEncoder().encode(left);
+    const b = new TextEncoder().encode(right);
+    let diff = a.length ^ b.length;
+    for (let index = 0; index < Math.max(a.length, b.length); index += 1)
+        diff |= (a[index] ?? 0) ^ (b[index] ?? 0);
+    return diff === 0;
+}
+/** RFC 6749 §2.3.1 client authentication: HTTP Basic first, then form/JSON parameters. */
+function clientCredentialsFromRequest(request, body) {
+    const header = request.headers.get("authorization") ?? "";
+    const basic = /^Basic\s+(.+)$/i.exec(header);
+    if (basic) {
+        let decoded = "";
+        try {
+            decoded = atob(basic[1].trim());
+        }
+        catch {
+            return null;
+        }
+        const separator = decoded.indexOf(":");
+        if (separator === -1)
+            return null;
+        try {
+            return {
+                clientId: decodeURIComponent(decoded.slice(0, separator)),
+                clientSecret: decodeURIComponent(decoded.slice(separator + 1)),
+                method: "client_secret_basic"
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    const clientId = asString(body.client_id);
+    const clientSecret = asString(body.client_secret);
+    return clientId && clientSecret ? { clientId, clientSecret, method: "client_secret_post" } : null;
+}
+/**
+ * Registers a confidential OAuth client for the `client_credentials` grant.
+ * Called from `registerMcpOAuthClient` when the RFC 7591 body asks for that
+ * grant type; needs a signed-in user because the credential acts as that user
+ * (the grant's subject) with the scopes approved here, without a browser.
+ */
+async function registerConfidentialClient(request, config, db, body, user, options, binding) {
+    const cfg = oauthConfig(config);
+    if (!cfg.clientCredentials)
+        return jsonResponse({ error: "invalid_client_metadata", error_description: "client_credentials clients are disabled" }, { status: 400 });
+    if (!user) {
+        return jsonResponse({ error: "invalid_client_metadata", error_description: "client_credentials clients must be registered by a signed-in user" }, { status: 401 });
+    }
+    const clientName = asString(body.client_name).trim();
+    if (!clientName)
+        return jsonResponse({ error: "invalid_client_metadata", error_description: "client_name is required" }, { status: 400 });
+    const requestedGrantTypes = Array.isArray(body.grant_types) ? body.grant_types.map(String) : [];
+    if (requestedGrantTypes.some((type) => type !== "client_credentials")) {
+        return jsonResponse({ error: "invalid_client_metadata", error_description: "A client_credentials client cannot also use browser grants" }, { status: 400 });
+    }
+    if (parseRedirectUris(body.redirect_uris).length) {
+        return jsonResponse({ error: "invalid_client_metadata", error_description: "client_credentials clients do not take redirect_uris" }, { status: 400 });
+    }
+    const authMethod = asString(body.token_endpoint_auth_method) || "client_secret_basic";
+    if (authMethod !== "client_secret_basic" && authMethod !== "client_secret_post") {
+        return jsonResponse({ error: "invalid_client_metadata", error_description: "token_endpoint_auth_method must be client_secret_basic or client_secret_post" }, { status: 400 });
+    }
+    const resource = asString(body.resource) || canonicalMcpResource(request, config);
+    let created;
+    try {
+        created = await createMcpMachineCredential(db, config, {
+            user,
+            clientName,
+            resource,
+            scope: asString(body.scope) || undefined,
+            organizationId: binding.organizationId ?? null,
+            tokenEndpointAuthMethod: authMethod,
+            metadata: { ...body, client_secret: undefined }
+        }, options);
+    }
+    catch (error) {
+        if (error instanceof McpMachineCredentialError)
+            return jsonResponse({ error: error.code, error_description: error.message }, { status: 400 });
+        throw error;
+    }
+    return jsonResponse({
+        client_id: created.clientId,
+        client_secret: created.clientSecret,
+        client_name: clientName,
+        grant_types: ["client_credentials"],
+        response_types: [],
+        token_endpoint_auth_method: authMethod,
+        scope: created.scopes.join(" "),
+        resource,
+        ...(created.organizationId ? { organization_id: created.organizationId } : {}),
+        grant_id: created.grantId,
+        client_id_issued_at: Math.floor(wallNowMs() / 1000),
+        client_secret_expires_at: 0
+    }, { status: 201 });
+}
+class McpMachineCredentialError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * Makes a machine credential (a confidential `client_credentials` client and
+ * its grant) that acts as `user`, without a browser: for an app's own server
+ * code to hand a command-line tool or another service a way in. `resource` is
+ * the connector's absolute address (the app's `/mcp`, or `/mcp/operator`);
+ * `scope` defaults to that connector's default. The secret is returned once.
+ * Revoke with `revokeMcpOAuthClient`.
+ */
+export async function createMcpMachineCredential(db, config, input, options = {}) {
+    await ensureMcpSystemTables(db);
+    if (!oauthConfig(config).clientCredentials)
+        throw new McpMachineCredentialError("invalid_client_metadata", "client_credentials clients are disabled");
+    const clientName = input.clientName.trim();
+    if (!clientName)
+        throw new McpMachineCredentialError("invalid_client_metadata", "clientName is required");
+    let origin;
+    try {
+        origin = new URL(input.resource).origin;
+    }
+    catch {
+        throw new McpMachineCredentialError("invalid_target", "resource must be the connector's absolute address");
+    }
+    const resource = input.resource;
+    const surface = mcpSurfaceForResource(new Request(origin), config, resource, options);
+    if (!surface)
+        throw new McpMachineCredentialError("invalid_target", "Unknown MCP resource");
+    const scopes = splitScopes(input.scope || surface.defaultScope);
+    const scopeError = authorizeMcpScopes(input.user, scopes, surface, options);
+    if (scopeError)
+        throw new McpMachineCredentialError("invalid_scope", scopeError);
+    const authMethod = input.tokenEndpointAuthMethod ?? "client_secret_basic";
+    const user = input.user;
+    const clientId = `raybase_cc_${randomId("client")}`;
+    const clientSecret = randomToken("rb_cs");
+    const grantId = randomId("mcp_grant");
+    const now = nowIso();
+    const subjectType = surface.id === "operator" ? "raybase-operator" : "raybase-user";
+    const organizationId = input.organizationId ?? null;
+    // Machine credentials carry no consent expiry of their own: they live until
+    // the client or the grant is revoked.
+    await db.run(`INSERT INTO "_mcp_grants" ("id", "subjectType", "subjectId", "userId", "hostAccount", "clientId", "clientName", "scopes", "resource", "createdAt", "expiresAt", "organizationId", "grantType")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [grantId, subjectType, user.id, user.id, null, clientId, clientName, JSON.stringify(scopes), resource, now, null, organizationId, "client_credentials"]);
+    await db.run(`INSERT INTO "_oauth_clients" ("id", "clientId", "clientName", "redirectUris", "metadata", "createdAt", "clientSecretHash", "tokenEndpointAuthMethod", "grantTypes", "scopes", "resource", "grantId", "createdByUserId", "organizationId")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        randomId("oauth_client"),
+        clientId,
+        clientName,
+        "[]",
+        JSON.stringify(input.metadata ?? { client_name: clientName, scope: scopes.join(" "), resource }),
+        now,
+        await sha256Hex(clientSecret),
+        authMethod,
+        JSON.stringify(["client_credentials"]),
+        JSON.stringify(scopes),
+        resource,
+        grantId,
+        user.id,
+        organizationId
+    ]);
+    await audit(db, user.id, surface.id === "operator" ? "operator_mcp.client.create" : "mcp.client.create", "_oauth_clients", clientId, {
+        grantId,
+        scopes,
+        resource,
+        surface: surface.id,
+        organizationId,
+        tokenEndpointAuthMethod: authMethod
+    });
+    await event(db, grantId, clientId, "grant.created", undefined, { grantType: "client_credentials" });
+    return { clientId, clientSecret, grantId, scopes, resource, organizationId };
+}
+export async function listMcpOAuthClientsForUser(db, userId) {
+    await ensureMcpSystemTables(db);
+    const rows = await db.all(`SELECT c."clientId", c."clientName", c."redirectUris", c."revokedAt", c."clientSecretHash", c."tokenEndpointAuthMethod", c."grantTypes", c."scopes", c."resource", c."grantId", c."createdByUserId", c."organizationId", c."createdAt", g."lastUsedAt"
+     FROM "_oauth_clients" c
+     LEFT JOIN "_mcp_grants" g ON g."id" = c."grantId"
+     WHERE c."createdByUserId" = ?
+     ORDER BY c."createdAt" DESC LIMIT 200`, [userId]);
+    return rows.map(oauthClientSummary);
+}
+/**
+ * Revokes a confidential client and its grant family. When `ownerUserId` is
+ * given only that user's clients are revoked; admins pass null.
+ */
+export async function revokeMcpOAuthClient(db, clientId, actor) {
+    await ensureMcpSystemTables(db);
+    const client = await clientById(db, clientId);
+    if (!client || !client.clientSecretHash)
+        return false;
+    if (actor.ownerUserId && client.createdByUserId !== actor.ownerUserId)
+        return false;
+    const now = nowIso();
+    await db.run(`UPDATE "_oauth_clients" SET "revokedAt" = ? WHERE "clientId" = ? AND "revokedAt" IS NULL`, [now, clientId]);
+    if (client.grantId)
+        await revokeGrantFamily(db, client.grantId, "client_revoked");
+    await audit(db, actor.userId, "mcp.client.revoke", "_oauth_clients", clientId, { grantId: client.grantId ?? null });
+    return true;
+}
+async function resolveOAuthClient(config, db, clientId) {
+    const stored = await clientById(db, clientId);
+    if (stored || !isUrlLikeClientId(clientId))
+        return stored;
+    const cfg = oauthConfig(config);
+    const metadata = await fetchClientMetadataDocument(clientId, { allowedHosts: cfg.allowedClientMetadataHosts });
+    const redirectUris = metadata.redirect_uris.map((uri) => validateRedirectUri(uri, cfg.allowedClientRedirectHosts));
+    const now = nowIso();
+    await db.run(`INSERT OR IGNORE INTO "_oauth_clients" ("id", "clientId", "clientName", "redirectUris", "metadata", "createdAt")
+     VALUES (?, ?, ?, ?, ?, ?)`, [randomId("oauth_client"), metadata.client_id, metadata.client_name, JSON.stringify(redirectUris), JSON.stringify(metadata), now]);
+    return (await clientById(db, clientId)) ?? {
+        clientId: metadata.client_id,
+        clientName: metadata.client_name,
+        redirectUris: JSON.stringify(redirectUris),
+        revokedAt: null
+    };
+}
+/**
+ * RFC 7591 registration. Public PKCE clients register anonymously as before.
+ * A body whose `grant_types` is `["client_credentials"]` registers a
+ * confidential client instead: it needs the signed-in `user`, takes `scope`
+ * (and optionally `resource`), and answers with a one-time `client_secret`.
+ */
+export async function registerMcpOAuthClient(request, config, db, user = null, options = {}, binding = {}) {
+    const limited = checkMcpRateLimit(request, "oauth-register", 20);
+    if (limited)
+        return limited;
+    const cfg = oauthConfig(config);
+    if (!cfg.enabled)
+        return jsonResponse({ error: "OAuth is disabled" }, { status: 404 });
+    const body = await request.json().then(asRecord).catch(() => ({}));
+    const requestedGrantTypes = Array.isArray(body.grant_types) ? body.grant_types.map(String) : [];
+    if (requestedGrantTypes.includes("client_credentials")) {
+        return registerConfidentialClient(request, config, db, body, user, options, binding);
+    }
+    if (!cfg.dynamicClientRegistration)
+        return jsonResponse({ error: "Dynamic client registration is disabled" }, { status: 404 });
+    if (requestedGrantTypes.some((type) => type !== "authorization_code" && type !== "refresh_token")) {
+        return jsonResponse({ error: "invalid_client_metadata", error_description: "Unsupported grant_types" }, { status: 400 });
+    }
+    const clientName = asString(body.client_name).trim();
+    if (!clientName)
+        return jsonResponse({ error: "client_name is required" }, { status: 400 });
+    const redirectUris = parseRedirectUris(body.redirect_uris);
+    if (!redirectUris.length)
+        return jsonResponse({ error: "redirect_uris is required" }, { status: 400 });
+    let normalizedRedirects;
+    try {
+        normalizedRedirects = redirectUris.map((uri) => validateRedirectUri(uri, cfg.allowedClientRedirectHosts));
+        const metadataUrl = asString(body.client_uri || body.logo_uri || body.tos_uri || body.policy_uri);
+        if (metadataUrl)
+            validateClientMetadataUrl(metadataUrl, cfg.allowedClientMetadataHosts);
+    }
+    catch (error) {
+        return jsonResponse({ error: error instanceof Error ? error.message : "Invalid client metadata" }, { status: 400 });
+    }
+    const clientId = `raybase_dcr_${randomId("client")}`;
+    const now = nowIso();
+    await db.run(`INSERT INTO "_oauth_clients" ("id", "clientId", "clientName", "redirectUris", "metadata", "createdAt")
+     VALUES (?, ?, ?, ?, ?, ?)`, [randomId("oauth_client"), clientId, clientName, JSON.stringify(normalizedRedirects), JSON.stringify(body), now]);
+    return jsonResponse({
+        client_id: clientId,
+        client_name: clientName,
+        redirect_uris: normalizedRedirects,
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none",
+        client_id_issued_at: Math.floor(wallNowMs() / 1000)
+    }, { status: 201 });
+}
+function redirectWithError(redirectUri, state, error) {
+    const url = new URL(redirectUri);
+    url.searchParams.set("error", error);
+    if (state)
+        url.searchParams.set("state", state);
+    return Response.redirect(url.toString(), 302);
+}
+function operatorConsentCopy(config, scopeValue, surface) {
+    if (surface.id !== "operator") {
+        return `${config.appName} will allow this AI client to use the requested MCP tools with your account permissions.`;
+    }
+    const scopes = splitScopes(scopeValue || surface.defaultScope);
+    const writeCapabilities = [
+        scopes.includes("operator:app-data:write") ? "create and update app-defined data rows" : null,
+        scopes.includes("operator:app-data:delete") ? "delete app-defined data rows" : null,
+        scopes.includes("operator:settings:write") ? "set and reset app-scoped settings" : null,
+        scopes.includes("operator:users:invite") ? "create normal user invites" : null,
+        scopes.includes("operator:users:lifecycle") ? "deactivate and reactivate users, and revoke user sessions" : null
+    ].filter(Boolean);
+    if (!writeCapabilities.length) {
+        return `${config.appName} will allow this AI client to inspect read-only production evidence through Operator MCP. It cannot mutate schema, data, users, jobs, deployments, or code.`;
+    }
+    return `${config.appName} will allow this AI client to inspect Operator MCP evidence and perform these audited operator actions: ${writeCapabilities.join("; ")}. Operator MCP still cannot run raw SQL, mutate schema, edit code, deploy, restore, destroy the app, mutate secrets or bindings, escalate operator roles, or perform broad unbounded exports.`;
+}
+function consentChoice(consent) {
+    const choice = consent?.choice;
+    if (!choice || !choice.name || !Array.isArray(choice.options) || choice.options.length < 2)
+        return null;
+    return choice;
+}
+function consentStylesheetHref(config) {
+    const href = config.mcp?.consent?.stylesheet?.trim();
+    if (!href)
+        return null;
+    if (href.startsWith("/") && !href.startsWith("//"))
+        return href;
+    try {
+        if (new URL(href).protocol === "https:")
+            return href;
+    }
+    catch {
+        // Fall through to the refusal below.
+    }
+    throw new Error("mcp.consent.stylesheet must be a root-relative path or an HTTPS URL");
+}
+/** What a consent page shows, and the fields it posts back. */
+function consentView(config, validated, consent) {
+    const choice = consentChoice(consent);
+    const fields = Object.fromEntries(Object.entries(validated.values).filter(([key]) => !choice || key !== choice.name));
+    const scopes = splitScopes(validated.values.scope || validated.surface.defaultScope);
+    return {
+        client: { name: validated.clientName },
+        connector: { name: validated.surface.label, kind: validated.surface.id },
+        description: operatorConsentCopy(config, validated.values.scope, validated.surface),
+        scopes,
+        choice: choice
+            ? { ...choice, selected: choice.selected && choice.options.some((option) => option.value === choice.selected) ? choice.selected : choice.options[0].value }
+            : null,
+        action: "/api/auth/oauth/authorize",
+        method: "POST",
+        fields
+    };
+}
+function consentPage(config, view) {
+    const hidden = Object.entries(view.fields)
+        .map(([key, value]) => `<input type="hidden" name="${escapeHtml(key)}" value="${escapeHtml(value)}">`)
+        .join("");
+    const stylesheet = consentStylesheetHref(config);
+    const css = config.mcp?.consent?.css ?? "";
+    const choice = view.choice
+        ? `<label class="rb-consent-choice">${escapeHtml(view.choice.label)}
+        <select name="${escapeHtml(view.choice.name)}">${view.choice.options
+            .map((option) => `<option value="${escapeHtml(option.value)}"${option.value === view.choice.selected ? " selected" : ""}>${escapeHtml(option.label)}</option>`)
+            .join("")}</select></label>`
+        : "";
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Connect ${escapeHtml(view.client.name)} to ${escapeHtml(view.connector.name)}</title>
+  <style>
+    :root { color-scheme: light dark; --rb-consent-bg: Canvas; --rb-consent-fg: CanvasText; --rb-consent-muted: color-mix(in srgb, CanvasText 65%, Canvas); --rb-consent-border: color-mix(in srgb, CanvasText 18%, Canvas); --rb-consent-accent: #2457d6; --rb-consent-accent-fg: #fff; --rb-consent-radius: 10px; --rb-consent-font: system-ui, -apple-system, "Segoe UI", sans-serif; }
+    body { margin: 0; background: var(--rb-consent-bg); color: var(--rb-consent-fg); font-family: var(--rb-consent-font); line-height: 1.5; }
+    .rb-consent { max-width: 480px; margin: 12vh auto 48px; padding: 0 20px; }
+    .rb-consent h1 { font-size: 1.4rem; line-height: 1.25; margin: 0 0 12px; }
+    .rb-consent p { margin: 0 0 16px; }
+    .rb-consent-scopes { color: var(--rb-consent-muted); font-size: 0.9rem; }
+    .rb-consent-choice { display: grid; gap: 6px; margin: 0 0 20px; font-weight: 600; }
+    .rb-consent-choice select { font: inherit; font-weight: 400; padding: 8px 10px; border: 1px solid var(--rb-consent-border); border-radius: var(--rb-consent-radius); background: var(--rb-consent-bg); color: var(--rb-consent-fg); }
+    .rb-consent-actions { display: flex; gap: 10px; }
+    .rb-consent button { font: inherit; padding: 9px 18px; border-radius: var(--rb-consent-radius); border: 1px solid var(--rb-consent-border); background: transparent; color: var(--rb-consent-fg); cursor: pointer; }
+    .rb-consent button[value="approve"] { background: var(--rb-consent-accent); border-color: var(--rb-consent-accent); color: var(--rb-consent-accent-fg); }
+  </style>${stylesheet ? `\n  <link rel="stylesheet" href="${escapeHtml(stylesheet)}">` : ""}${css ? `\n  <style>${css.replace(/<\/style/gi, "<\\/style")}</style>` : ""}
+</head><body>
+  <main class="rb-consent">
+    <h1>Connect ${escapeHtml(view.client.name)} to ${escapeHtml(view.connector.name)}</h1>
+    <p>${escapeHtml(view.description)}</p>
+    <p class="rb-consent-scopes">Permissions: ${escapeHtml(view.scopes.join(" "))}</p>
+    <form method="post" action="${escapeHtml(view.action)}">${hidden}${choice}
+      <div class="rb-consent-actions"><button name="decision" value="approve">Approve</button>
+      <button name="decision" value="deny">Deny</button></div>
+    </form>
+  </main>
+</body></html>`;
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char] ?? char);
+}
+async function authorizationInput(request) {
+    const url = new URL(request.url);
+    return request.method === "POST"
+        ? Object.fromEntries(Object.entries(await formOrJson(request)).map(([key, value]) => [key, asString(value)]))
+        : Object.fromEntries(url.searchParams.entries());
+}
+async function validateAuthorizationInput(request, config, db, input, options = {}) {
+    const state = input.state || null;
+    if (input.response_type !== "code")
+        return jsonResponse({ error: "Only response_type=code is supported" }, { status: 400 });
+    if (!input.client_id)
+        return jsonResponse({ error: "client_id is required" }, { status: 400 });
+    if (!input.redirect_uri)
+        return jsonResponse({ error: "redirect_uri is required" }, { status: 400 });
+    let client;
+    try {
+        client = await resolveOAuthClient(config, db, input.client_id);
+    }
+    catch (error) {
+        return jsonResponse({ error: error instanceof Error ? error.message : "Invalid client metadata document" }, { status: 400 });
+    }
+    if (!client || client.revokedAt)
+        return jsonResponse({ error: "Unknown or revoked OAuth client" }, { status: 400 });
+    const redirects = parseRedirectUris(client.redirectUris);
+    let redirectUri;
+    try {
+        redirectUri = validateRedirectUri(input.redirect_uri, oauthConfig(config).allowedClientRedirectHosts);
+    }
+    catch {
+        return jsonResponse({ error: "Invalid redirect_uri" }, { status: 400 });
+    }
+    if (!redirects.includes(redirectUri))
+        return jsonResponse({ error: "redirect_uri is not registered for this client" }, { status: 400 });
+    if (!input.code_challenge || input.code_challenge_method !== "S256") {
+        return redirectWithError(redirectUri, state, "invalid_request");
+    }
+    const resource = input.resource || canonicalMcpResource(request, config);
+    const surface = mcpSurfaceForResource(request, config, resource, options);
+    if (!surface)
+        return redirectWithError(redirectUri, state, "invalid_target");
+    return {
+        clientName: client.clientName,
+        values: {
+            // The consent form posts every value back and the POST is validated
+            // like the GET, so the two fixed ones travel too.
+            response_type: "code",
+            code_challenge_method: "S256",
+            client_id: input.client_id,
+            redirect_uri: redirectUri,
+            scope: input.scope || surface.defaultScope,
+            resource,
+            state: input.state || "",
+            code_challenge: input.code_challenge,
+            // Carried through the consent form so the POST can re-resolve it.
+            ...(input.org ? { org: input.org } : {})
+        },
+        surface
+    };
+}
+/**
+ * The `org` hint an authorization request carries: the query string on GET,
+ * the form or JSON body on POST. Consumes the body, so callers that go on to
+ * call `authorizeMcpOAuthRequest` pass `request.clone()`. Core records
+ * nothing for it; a layered runtime resolves it to an organization the
+ * signed-in user belongs to and passes that as the grant binding.
+ */
+export async function mcpAuthorizationOrganizationHint(request) {
+    const input = await authorizationInput(request);
+    const value = asString(input.org).trim();
+    return value || null;
+}
+/** The identity a host-account grant acts as: a plain app user, never an operator. */
+function hostAccountUser(hostAccount, subject) {
+    return {
+        id: subject.id,
+        email: subject.email,
+        name: hostAccount,
+        operatorRole: null,
+        appRoles: ["user"]
+    };
+}
+function resolveHostSubject(hostApproval, hostAccount) {
+    const subject = hostApproval.subject(hostAccount);
+    if (!subject?.type || !subject.id)
+        throw new Error("Host approval subject needs a type and an id");
+    // Core's own subject types carry meaning (operator grants); a host subject may not claim them.
+    if (subject.type.startsWith("raybase-"))
+        throw new Error("Host approval subject type may not start with raybase-");
+    return subject;
+}
+/** The user a stored grant acts as, or null when it no longer resolves. */
+async function grantUser(db, grant, userId, options) {
+    if (!grant.hostAccount)
+        return (await (options.resolveOAuthUser?.(db, userId) ?? loadUser(db, userId))) ?? null;
+    // A host-account grant resolves only while host approval is configured, and
+    // only to the subject it was made for.
+    if (!options.hostApproval)
+        return null;
+    let subject;
+    try {
+        subject = resolveHostSubject(options.hostApproval, grant.hostAccount);
+    }
+    catch {
+        return null;
+    }
+    if (subject.type !== grant.subjectType || subject.id !== grant.subjectId)
+        return null;
+    return hostAccountUser(grant.hostAccount, subject);
+}
+async function createGrantAndCode(db, config, request, user, values, clientName, options = {}, binding = {}, host) {
+    const resource = values.resource || canonicalMcpResource(request, config);
+    const surface = mcpSurfaceForResource(request, config, resource, options);
+    if (!surface)
+        return redirectWithError(values.redirect_uri, values.state || null, "invalid_target");
+    const hostAccount = host?.account ?? null;
+    const scopes = splitScopes(values.scope || "mcp:read mcp:write");
+    const scopeError = authorizeMcpScopes(user, scopes, surface, options);
+    if (scopeError)
+        return redirectWithError(values.redirect_uri, values.state || null, "invalid_scope");
+    const grantId = randomId("mcp_grant");
+    const now = nowIso();
+    const subjectType = host ? host.subject.type : surface.id === "operator" ? "raybase-operator" : "raybase-user";
+    const subjectId = host ? host.subject.id : user.id;
+    const organizationId = host ? null : binding.organizationId ?? null;
+    await db.run(`INSERT INTO "_mcp_grants" ("id", "subjectType", "subjectId", "userId", "hostAccount", "clientId", "clientName", "scopes", "resource", "createdAt", "expiresAt", "organizationId", "grantType")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [grantId, subjectType, subjectId, user.id, hostAccount, values.client_id, clientName, JSON.stringify(scopes), resource, now, addSeconds(defaultGrantTtlSeconds), organizationId, "authorization_code"]);
+    const code = randomToken("rb_code");
+    await db.run(`INSERT INTO "_oauth_authorization_codes"
+      ("id", "codeHash", "clientId", "redirectUri", "scope", "resource", "codeChallenge", "codeChallengeMethod", "grantId", "userId", "hostAccount", "state", "expiresAt", "createdAt")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        randomId("oauth_code"),
+        await sha256Hex(code),
+        values.client_id,
+        values.redirect_uri,
+        JSON.stringify(scopes),
+        resource,
+        values.code_challenge,
+        "S256",
+        grantId,
+        user.id,
+        hostAccount,
+        values.state || null,
+        addSeconds(300),
+        now
+    ]);
+    await audit(db, host ? null : user.id, surface.id === "operator" ? "operator_mcp.grant.create" : "mcp.grant.create", "_mcp_grants", grantId, {
+        clientId: values.client_id,
+        scopes,
+        resource,
+        surface: surface.id,
+        hostAccount,
+        organizationId
+    });
+    const redirect = new URL(values.redirect_uri);
+    redirect.searchParams.set("code", code);
+    if (values.state)
+        redirect.searchParams.set("state", values.state);
+    // RFC 9207: name the issuer, so a client talking to several can tell which answered.
+    redirect.searchParams.set("iss", serverOrigin(request));
+    return Response.redirect(redirect.toString(), 302);
+}
+function authorizeMcpScopes(user, scopes, surface, options = {}) {
+    if (surface.id === "operator") {
+        if (!canApproveOperatorMcp(user))
+            return "Operator role owner or admin is required";
+        if (!scopes.length || scopes.some((scope) => !isOperatorScope(scope)))
+            return "Operator MCP grants may only request operator scopes";
+        const unsupported = scopes.find((scope) => !surface.scopesSupported.includes(scope)
+            && !(options.allowExtendedOperatorScopes && /^operator:org:[^:]+:(?:read|write)$/.test(scope)));
+        if (unsupported)
+            return `Unsupported Operator MCP scope: ${unsupported}`;
+        if (!options.allowExtendedOperatorScopes && scopes.some(isCoreOperatorOnlyScope)) {
+            return "Core Operator MCP does not support fleet or organization scopes";
+        }
+        if (options.allowExtendedOperatorScopes) {
+            if (scopes.includes("operator:fleet:read") && user.operatorRole !== "owner") {
+                return "Owner role is required for fleet scope";
+            }
+            const requestsOrganizationWrite = scopes.some((scope) => [
+                "operator:app-data:write",
+                "operator:app-data:delete",
+                "operator:settings:write",
+                "operator:users:invite",
+                "operator:users:lifecycle"
+            ].includes(scope));
+            if (requestsOrganizationWrite && !scopes.some((scope) => /^operator:org:[^:]+:write$/.test(scope))) {
+                return "Organization write scope is required for mutating Operator MCP permissions";
+            }
+        }
+        return null;
+    }
+    if (scopes.some(isOperatorScope))
+        return "App MCP grants cannot request operator scopes";
+    return null;
+}
+function mcpSignInPath(config) {
+    const raw = config.mcp?.oauth?.signInPath?.trim() || "/login";
+    if (!raw.startsWith("/") || raw.startsWith("//"))
+        throw new Error("mcp.oauth.signInPath must be a root-relative path");
+    return raw;
+}
+/** The authorization request as a GET address on this origin, path and query only. */
+function authorizationRequestPath(values, choice, input) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(values))
+        if (value)
+            query.set(key, value);
+    if (choice && input[choice.name])
+        query.set(choice.name, input[choice.name]);
+    return `/api/auth/oauth/authorize?${query.toString()}`;
+}
+/** Sends a person with no session to sign in, with the whole request kept as `next`. */
+function signInRedirect(request, config, values, input, consent) {
+    const signIn = new URL(mcpSignInPath(config), request.url);
+    signIn.searchParams.set("next", authorizationRequestPath(values, consentChoice(consent), input));
+    return new Response(null, { status: 302, headers: { location: signIn.toString(), "cache-control": "no-store" } });
+}
+export async function authorizeMcpOAuthRequest(request, config, db, user, options = {}, binding = {}, consent = {}) {
+    const limited = checkMcpRateLimit(request, "oauth-authorize", 120);
+    if (limited)
+        return limited;
+    if (!oauthConfig(config).enabled)
+        return jsonResponse({ error: "OAuth is disabled" }, { status: 404 });
+    const input = await authorizationInput(request);
+    const validated = await validateAuthorizationInput(request, config, db, input, options);
+    if (validated instanceof Response)
+        return validated;
+    if (!user)
+        return signInRedirect(request, config, validated.values, input, consent);
+    const scopeError = authorizeMcpScopes(user, splitScopes(validated.values.scope), validated.surface, options);
+    if (scopeError)
+        return redirectWithError(validated.values.redirect_uri, validated.values.state || null, "invalid_scope");
+    if (request.method === "POST") {
+        if (input.decision !== "approve")
+            return redirectWithError(validated.values.redirect_uri, validated.values.state || null, "access_denied");
+        return createGrantAndCode(db, config, request, user, validated.values, validated.clientName, options, binding);
+    }
+    const ownPage = config.mcp?.consent?.path?.trim();
+    if (ownPage) {
+        if (!ownPage.startsWith("/") || ownPage.startsWith("//"))
+            throw new Error("mcp.consent.path must be a root-relative path");
+        const target = new URL(ownPage, request.url);
+        target.search = new URL(request.url).search;
+        return new Response(null, { status: 302, headers: { location: target.toString(), "cache-control": "no-store" } });
+    }
+    return new Response(consentPage(config, consentView(config, validated, consent)), {
+        headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "x-frame-options": "DENY", "content-security-policy": "frame-ancestors 'none'" }
+    });
+}
+/**
+ * `GET /api/auth/oauth/consent`: what an app's own consent page (`mcp.consent.path`)
+ * shows, for the authorization request in the query. Answers 401 with
+ * `signIn` when nobody is signed in.
+ */
+export async function mcpOAuthConsentContext(request, config, db, user, options = {}, consent = {}) {
+    const limited = checkMcpRateLimit(request, "oauth-authorize", 120);
+    if (limited)
+        return limited;
+    if (!oauthConfig(config).enabled)
+        return jsonResponse({ error: "OAuth is disabled" }, { status: 404 });
+    const input = Object.fromEntries(new URL(request.url).searchParams.entries());
+    const validated = await validateAuthorizationInput(request, config, db, input, options);
+    if (validated instanceof Response) {
+        if (validated.status === 302)
+            return jsonResponse({ error: "invalid_request", redirect: validated.headers.get("location") }, { status: 400 });
+        return validated;
+    }
+    if (!user) {
+        const signIn = signInRedirect(request, config, validated.values, input, consent).headers.get("location");
+        return jsonResponse({ error: "Authentication required", signIn }, { status: 401, headers: { "cache-control": "no-store" } });
+    }
+    const scopeError = authorizeMcpScopes(user, splitScopes(validated.values.scope), validated.surface, options);
+    if (scopeError)
+        return jsonResponse({ error: "invalid_scope", error_description: scopeError }, { status: 403 });
+    return jsonResponse(consentView(config, validated, consent), { headers: { "cache-control": "no-store" } });
+}
+function mcpHostApprovalPath(options, key) {
+    const defaults = { adminAuthPath: "/auth-mcp", connectPath: "/mcp/connect", oauthCompletePath: "/mcp/oauth/complete" };
+    const raw = options[key] ?? defaults[key];
+    return raw.startsWith("/") ? raw : `/${raw}`;
+}
+function hostAccountParam(options) {
+    return options.hostAccountParam || "host_account";
+}
+function connectPage(request, config, options) {
+    const url = new URL(request.url);
+    const param = hostAccountParam(options);
+    const copy = {
+        title: "Connect an account",
+        description: "Enter the account to connect, then continue to approve the connection there.",
+        label: "Account",
+        placeholder: "",
+        ...options.connectPage
+    };
+    const hidden = [...url.searchParams.entries()]
+        .filter(([key]) => key !== param)
+        .map(([key, value]) => `<input type="hidden" name="${escapeHtml(key)}" value="${escapeHtml(value)}">`)
+        .join("");
+    const placeholder = copy.placeholder ? ` placeholder="${escapeHtml(copy.placeholder)}"` : "";
+    return `<!doctype html><html><head><meta charset="utf-8"><title>Connect ${escapeHtml(config.appName)}</title></head><body>
+    <main style="font-family: system-ui, sans-serif; max-width: 560px; margin: 48px auto; line-height: 1.5;">
+      <h1>${escapeHtml(copy.title)}</h1>
+      <p>${escapeHtml(copy.description)}</p>
+      <form method="post">
+        ${hidden}
+        <label>${escapeHtml(copy.label)} <input name="${escapeHtml(param)}"${placeholder} required></label>
+        <button type="submit">Continue</button>
+      </form>
+    </main>
+  </body></html>`;
+}
+/** The page that asks which host account to connect (GET), and its submit (POST) back into authorization. */
+export async function handleMcpHostConnect(request, config, options) {
+    const hostOptions = options;
+    if (request.method === "GET")
+        return new Response(connectPage(request, config, hostOptions), { headers: { "content-type": "text/html; charset=utf-8" } });
+    if (request.method !== "POST")
+        return methodNotAllowed();
+    const param = hostAccountParam(options);
+    const body = await formOrJson(request);
+    const hostAccount = options.normalizeHostAccount(asString(body[param]));
+    const url = new URL("/api/auth/oauth/authorize", request.url);
+    for (const [key, value] of Object.entries(body)) {
+        if (key !== param)
+            url.searchParams.set(key, asString(value));
+    }
+    url.searchParams.set(param, hostAccount);
+    return Response.redirect(url.toString(), 302);
+}
+/**
+ * The authorization endpoint when host approval is on: records a pending
+ * authorization for the requested host account and sends the person to the
+ * host's admin to approve it. With no host account, sends them to the connect
+ * page first.
+ */
+export async function beginMcpHostAuthorization(request, config, db, env, options) {
+    const limited = checkMcpRateLimit(request, "host-oauth-authorize", 120);
+    if (limited)
+        return limited;
+    const param = hostAccountParam(options);
+    const input = await authorizationInput(request);
+    if (!input[param]) {
+        const connect = new URL(mcpHostApprovalPath(options, "connectPath"), request.url);
+        for (const [key, value] of Object.entries(input))
+            connect.searchParams.set(key, value);
+        return Response.redirect(connect.toString(), 302);
+    }
+    const validated = await validateAuthorizationInput(request, config, db, input);
+    if (validated instanceof Response)
+        return validated;
+    if (validated.surface.id !== "app")
+        return jsonResponse({ error: "Host-account MCP grants are only supported for the app MCP resource" }, { status: 400 });
+    const resource = validated.values.resource || canonicalMcpResource(request, config);
+    if (resource !== canonicalMcpResource(request, config))
+        return redirectWithError(validated.values.redirect_uri, validated.values.state || null, "invalid_target");
+    const hostAccount = options.normalizeHostAccount(input[param]);
+    const pendingId = randomId("mcp_pending");
+    await db.run(`INSERT INTO "_mcp_pending_authorizations"
+       ("id", "clientId", "redirectUri", "scope", "resource", "state", "codeChallenge", "hostAccount", "expiresAt", "createdAt")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        pendingId,
+        validated.values.client_id,
+        validated.values.redirect_uri,
+        JSON.stringify(splitScopes(validated.values.scope)),
+        resource,
+        validated.values.state || null,
+        validated.values.code_challenge,
+        hostAccount,
+        addSeconds(600),
+        nowIso()
+    ]);
+    const redirect = options.approvalUrl({
+        hostAccount,
+        pendingAuthId: pendingId,
+        adminAuthPath: mcpHostApprovalPath(options, "adminAuthPath"),
+        env
+    });
+    return Response.redirect(redirect.toString(), 302);
+}
+export async function getMcpPendingAuthorization(db, pendingAuthId) {
+    const row = await db.first(`SELECT p."id", p."clientId", p."redirectUri", p."scope", p."resource", p."state", p."codeChallenge",
+            p."hostAccount", p."expiresAt", p."createdAt", c."clientName" AS "clientName"
+     FROM "_mcp_pending_authorizations" p
+     JOIN "_oauth_clients" c ON c."clientId" = p."clientId"
+     WHERE p."id" = ?`, [pendingAuthId]);
+    if (!row || Date.parse(row.expiresAt) <= wallNowMs())
+        return null;
+    return { ...row, scope: splitScopes(parseJson(row.scope)) };
+}
+// Every stored host account went through normalizeHostAccount, so a caller's
+// value is normalised the same way before it is compared; one it rejects (or
+// turns into nothing) is an error, never a match on nothing.
+function requireHostAccount(hostApproval, input) {
+    if (!hostApproval || typeof hostApproval.normalizeHostAccount !== "function") {
+        throw new Error("Pass the app's mcp.hostApproval options (normalizeHostAccount) to normalise the host account");
+    }
+    let normalized;
+    try {
+        normalized = hostApproval.normalizeHostAccount(String(input ?? ""));
+    }
+    catch (error) {
+        throw new Error(`Host account ${JSON.stringify(input)} is not valid: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof normalized !== "string" || !normalized)
+        throw new Error(`Host account ${JSON.stringify(input)} is not valid`);
+    return normalized;
+}
+/**
+ * Issues the single-use ticket that completes a pending authorization. Call it
+ * from the app's approval page only after verifying the host's own session;
+ * `hostAccount` is the account that session proves, in any form the app's
+ * `normalizeHostAccount` accepts: it is normalised here and must then equal
+ * the pending authorization's account. Pass the same `hostApproval` options
+ * the app gives `mcp.hostApproval`.
+ */
+export async function createMcpApprovalTicket(db, hostApproval, input) {
+    const hostAccount = requireHostAccount(hostApproval, input.hostAccount);
+    const pending = await getMcpPendingAuthorization(db, input.pendingAuthId);
+    if (!pending)
+        throw new Error("Pending MCP authorization not found or expired");
+    if (pending.hostAccount !== hostAccount) {
+        throw new Error("Pending MCP authorization host account does not match the verified host session");
+    }
+    const ticket = randomToken("rb_mcp_ticket");
+    const expiresAt = addSeconds(300);
+    await db.run(`INSERT INTO "_mcp_approval_tickets" ("id", "ticketHash", "pendingAuthId", "hostAccount", "clientId", "scope", "expiresAt", "createdAt")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [randomId("mcp_ticket"), await sha256Hex(ticket), pending.id, hostAccount, pending.clientId, JSON.stringify(pending.scope), expiresAt, nowIso()]);
+    return { ticket, expiresAt };
+}
+export function topLevelMcpApprovalRedirectHtml(url) {
+    const escaped = escapeHtml(url);
+    return `<!doctype html><html><head><meta charset="utf-8"><title>Completing MCP authorization</title></head><body>
+    <main style="font-family: system-ui, sans-serif; max-width: 560px; margin: 48px auto; line-height: 1.5;">
+      <h1>Completing authorization</h1>
+      <p>If the browser does not continue automatically, use the button below.</p>
+      <p><a target="_top" href="${escaped}">Continue</a></p>
+    </main>
+    <script>window.top.location.href = ${JSON.stringify(url)};</script>
+  </body></html>`;
+}
+export function redirectMcpPendingAuthorizationError(pending, error) {
+    return redirectWithError(pending.redirectUri, pending.state, error);
+}
+/** Redeems an approval ticket (once) and makes the grant bound to its host account. */
+export async function completeMcpHostApproval(request, config, db, options) {
+    const limited = checkMcpRateLimit(request, "host-oauth-complete", 120);
+    if (limited)
+        return limited;
+    const ticket = new URL(request.url).searchParams.get("ticket") ?? "";
+    if (!ticket)
+        return jsonResponse({ error: "ticket is required" }, { status: 400 });
+    const consumedAt = nowIso();
+    const rows = await db.all(`UPDATE "_mcp_approval_tickets"
+     SET "consumedAt" = ?
+     WHERE "ticketHash" = ? AND "consumedAt" IS NULL AND "expiresAt" > ?
+     RETURNING "id", "pendingAuthId", "hostAccount", "clientId", "scope", "expiresAt"`, [consumedAt, await sha256Hex(ticket), consumedAt]);
+    const consumed = rows[0];
+    if (!consumed)
+        return jsonResponse({ error: "Approval ticket is invalid, expired, or already used" }, { status: 400 });
+    const pending = await getMcpPendingAuthorization(db, consumed.pendingAuthId);
+    if (!pending || pending.clientId !== consumed.clientId || pending.hostAccount !== consumed.hostAccount) {
+        return jsonResponse({ error: "Pending MCP authorization is no longer valid" }, { status: 400 });
+    }
+    const subject = resolveHostSubject(options, consumed.hostAccount);
+    return createGrantAndCode(db, config, request, hostAccountUser(consumed.hostAccount, subject), {
+        client_id: pending.clientId,
+        redirect_uri: pending.redirectUri,
+        scope: pending.scope.join(" "),
+        resource: pending.resource,
+        state: pending.state ?? "",
+        code_challenge: pending.codeChallenge
+    }, pending.clientName, {}, {}, { account: consumed.hostAccount, subject });
+}
+async function loadGrant(db, grantId) {
+    return db.first(`SELECT * FROM "_mcp_grants" WHERE "id" = ?`, [grantId]);
+}
+async function loadUser(db, userId) {
+    const row = await db.first(`SELECT "id", "email", "name", "operatorRole", "appRoles", "banned" FROM "_auth_users" WHERE "id" = ?`, [userId]);
+    if (!row || row.banned)
+        return null;
+    const operatorRole = normalizeStoredAdminRole(row.operatorRole);
+    const appRoles = row.appRoles ? normalizeRoles(String(row.appRoles).startsWith("[") ? JSON.parse(row.appRoles) : row.appRoles.split(",")) : ["user"];
+    return withHostUserRoleCeiling({ id: row.id, email: row.email, name: row.name, operatorRole, appRoles });
+}
+export async function exchangeMcpOAuthToken(request, config, db, options = {}) {
+    const limited = checkMcpRateLimit(request, "oauth-token", 120);
+    if (limited)
+        return limited;
+    if (!oauthConfig(config).enabled)
+        return jsonResponse({ error: "OAuth is disabled" }, { status: 404 });
+    const body = await formOrJson(request);
+    const grantType = asString(body.grant_type);
+    if (grantType === "authorization_code") {
+        return exchangeAuthorizationCode(request, config, db, body, options);
+    }
+    if (grantType === "refresh_token") {
+        return exchangeRefreshToken(config, db, body, options);
+    }
+    if (grantType === "client_credentials") {
+        return exchangeClientCredentials(request, config, db, body, options);
+    }
+    return jsonResponse({ error: "unsupported_grant_type" }, { status: 400 });
+}
+function invalidClientResponse(description) {
+    return jsonResponse({ error: "invalid_client", error_description: description }, { status: 401, headers: { "www-authenticate": 'Basic realm="oauth"' } });
+}
+/**
+ * RFC 6749 §4.4. The client authenticates with its secret; the token it gets
+ * carries the grant approved at registration (subject, scopes, resource,
+ * organization). No refresh token is issued: the client re-authenticates
+ * when the access token expires.
+ */
+async function exchangeClientCredentials(request, config, db, body, options) {
+    if (!oauthConfig(config).clientCredentials)
+        return jsonResponse({ error: "unsupported_grant_type" }, { status: 400 });
+    const credentials = clientCredentialsFromRequest(request, body);
+    if (!credentials)
+        return invalidClientResponse("Client authentication is required");
+    const client = await clientById(db, credentials.clientId);
+    if (!client || client.revokedAt || !isConfidentialClient(client) || !client.grantId)
+        return invalidClientResponse("Unknown or revoked client");
+    if (client.tokenEndpointAuthMethod && client.tokenEndpointAuthMethod !== credentials.method) {
+        return invalidClientResponse(`Client must authenticate with ${client.tokenEndpointAuthMethod}`);
+    }
+    if (!timingSafeEqualStrings(await sha256Hex(credentials.clientSecret), client.clientSecretHash ?? "")) {
+        await audit(db, null, "mcp.client.auth_failed", "_oauth_clients", client.clientId);
+        return invalidClientResponse("Invalid client secret");
+    }
+    const grant = await loadGrant(db, client.grantId);
+    if (!grant || grant.revokedAt || (grant.expiresAt && Date.parse(grant.expiresAt) <= wallNowMs()))
+        return jsonResponse({ error: "invalid_grant" }, { status: 400 });
+    const grantScopes = splitScopes(parseJson(grant.scopes));
+    const requested = splitScopes(asString(body.scope));
+    if (requested.some((scope) => !grantScopes.includes(scope)))
+        return jsonResponse({ error: "invalid_scope" }, { status: 400 });
+    const scopes = requested.length ? requested : grantScopes;
+    const requestedResource = asString(body.resource);
+    if (requestedResource && requestedResource !== grant.resource)
+        return jsonResponse({ error: "invalid_target" }, { status: 400 });
+    if (!grant.userId)
+        return jsonResponse({ error: "invalid_grant" }, { status: 400 });
+    const user = await (options.resolveOAuthUser?.(db, grant.userId) ?? loadUser(db, grant.userId));
+    if (!user)
+        return jsonResponse({ error: "invalid_grant" }, { status: 400 });
+    const issued = await issueAccessToken(config, db, grant.id, client.clientId, grant.userId, scopes, grant.resource);
+    await event(db, grant.id, client.clientId, "token.issued", undefined, { grantType: "client_credentials" });
+    return jsonResponse({
+        access_token: issued.token,
+        token_type: "Bearer",
+        expires_in: oauthConfig(config).accessTokenTtlSeconds,
+        scope: scopes.join(" "),
+        resource: grant.resource
+    });
+}
+async function issueAccessToken(config, db, grantId, clientId, userId, scopes, resource) {
+    const access = randomToken("rb_at");
+    const now = nowIso();
+    const expiresAt = addSeconds(oauthConfig(config).accessTokenTtlSeconds);
+    await db.run(`INSERT INTO "_oauth_access_tokens" ("id", "tokenHash", "grantId", "clientId", "userId", "resource", "scope", "expiresAt", "createdAt")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [randomId("oauth_access"), await sha256Hex(access), grantId, clientId, userId, resource, JSON.stringify(scopes), expiresAt, now]);
+    await db.run(`UPDATE "_mcp_grants" SET "lastUsedAt" = ? WHERE "id" = ?`, [now, grantId]);
+    return { token: access, expiresAt };
+}
+async function exchangeAuthorizationCode(request, config, db, body, options) {
+    const code = asString(body.code);
+    const verifier = asString(body.code_verifier);
+    const redirectUri = asString(body.redirect_uri);
+    const clientId = asString(body.client_id);
+    if (!code || !verifier || !redirectUri || !clientId)
+        return jsonResponse({ error: "invalid_request" }, { status: 400 });
+    const row = await db.first(`SELECT * FROM "_oauth_authorization_codes" WHERE "codeHash" = ?`, [await sha256Hex(code)]);
+    if (!row || row.consumedAt || row.clientId !== clientId || row.redirectUri !== redirectUri || Date.parse(row.expiresAt) <= wallNowMs()) {
+        return jsonResponse({ error: "invalid_grant" }, { status: 400 });
+    }
+    if (row.codeChallengeMethod !== "S256" || (await sha256Base64url(verifier)) !== row.codeChallenge) {
+        return jsonResponse({ error: "invalid_grant" }, { status: 400 });
+    }
+    await db.run(`UPDATE "_oauth_authorization_codes" SET "consumedAt" = ? WHERE "id" = ? AND "consumedAt" IS NULL`, [nowIso(), row.id]);
+    return issueTokens(config, db, row.grantId, row.clientId, row.userId, splitScopes(parseJson(row.scope)), row.resource, options);
+}
+async function exchangeRefreshToken(config, db, body, options) {
+    const token = asString(body.refresh_token);
+    const clientId = asString(body.client_id);
+    const row = await db.first(`SELECT * FROM "_oauth_refresh_tokens" WHERE "tokenHash" = ?`, [await sha256Hex(token)]);
+    if (!row || row.revokedAt || row.clientId !== clientId || Date.parse(row.expiresAt) <= wallNowMs()) {
+        if (row?.revokedAt || (row && row.clientId !== clientId))
+            await revokeGrantFamily(db, row.grantId, "refresh_reuse");
+        return jsonResponse({ error: "invalid_grant" }, { status: 400 });
+    }
+    const replacement = randomId("oauth_refresh");
+    await db.run(`UPDATE "_oauth_refresh_tokens" SET "revokedAt" = ?, "replacedBy" = ? WHERE "id" = ?`, [nowIso(), replacement, row.id]);
+    const grant = await loadGrant(db, row.grantId);
+    return issueTokens(config, db, row.grantId, row.clientId, row.userId, splitScopes(parseJson(row.scope)), grant?.resource ?? "", options, replacement);
+}
+async function revokeGrantFamily(db, grantId, reason) {
+    const grant = await loadGrant(db, grantId);
+    await revokeGrantAndDependents(db, grantId);
+    await event(db, grantId, grant?.clientId ?? "unknown", "grant.revoked", undefined, { reason });
+}
+async function issueTokens(config, db, grantId, clientId, userId, scopes, resource, options, refreshTokenId = randomId("oauth_refresh")) {
+    const grant = await loadGrant(db, grantId);
+    if (!grant || grant.revokedAt)
+        return jsonResponse({ error: "invalid_grant" }, { status: 400 });
+    const user = await grantUser(db, grant, userId, options);
+    if (!user)
+        return jsonResponse({ error: "invalid_grant" }, { status: 400 });
+    if (grant.grantType === "client_credentials")
+        return jsonResponse({ error: "invalid_grant" }, { status: 400 });
+    const { token: access } = await issueAccessToken(config, db, grantId, clientId, userId, scopes, resource);
+    const refresh = randomToken("rb_rt");
+    const now = nowIso();
+    const refreshExpiresAt = addSeconds(oauthConfig(config).refreshTokenTtlSeconds);
+    await db.run(`INSERT INTO "_oauth_refresh_tokens" ("id", "tokenHash", "grantId", "clientId", "userId", "scope", "expiresAt", "createdAt")
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [refreshTokenId, await sha256Hex(refresh), grantId, clientId, userId, JSON.stringify(scopes), refreshExpiresAt, now]);
+    return jsonResponse({
+        access_token: access,
+        token_type: "Bearer",
+        expires_in: oauthConfig(config).accessTokenTtlSeconds,
+        refresh_token: refresh,
+        scope: scopes.join(" "),
+        resource
+    });
+}
+export async function revokeMcpOAuthToken(request, db) {
+    const limited = checkMcpRateLimit(request, "oauth-revoke", 120);
+    if (limited)
+        return limited;
+    const body = await formOrJson(request);
+    const token = asString(body.token);
+    if (!token)
+        return jsonResponse({ error: "token is required" }, { status: 400 });
+    const tokenHash = await sha256Hex(token);
+    const now = nowIso();
+    await db.run(`UPDATE "_oauth_access_tokens" SET "revokedAt" = ? WHERE "tokenHash" = ? AND "revokedAt" IS NULL`, [now, tokenHash]);
+    await db.run(`UPDATE "_oauth_refresh_tokens" SET "revokedAt" = ? WHERE "tokenHash" = ? AND "revokedAt" IS NULL`, [now, tokenHash]);
+    return new Response(null, { status: 200 });
+}
+export async function validateMcpBearerToken(request, config, db, expectedSurface = "app", options = {}, resourceOverride) {
+    const header = request.headers.get("authorization") ?? "";
+    const match = /^Bearer\s+(.+)$/i.exec(header);
+    if (!match) {
+        return unauthorizedMcpResponse(request, config, "Unauthorized", expectedSurface);
+    }
+    const tokenHash = await sha256Hex(match[1]);
+    const row = await db.first(`SELECT * FROM "_oauth_access_tokens" WHERE "tokenHash" = ?`, [tokenHash]);
+    if (!row || row.revokedAt || Date.parse(row.expiresAt) <= wallNowMs()) {
+        return unauthorizedMcpResponse(request, config, "Invalid or expired token", expectedSurface);
+    }
+    const expectedResource = resourceOverride ?? canonicalMcpResourceForSurface(request, config, expectedSurface);
+    if (row.resource !== expectedResource)
+        return unauthorizedMcpResponse(request, config, "Token audience does not match this MCP resource", expectedSurface);
+    const grant = await loadGrant(db, row.grantId);
+    if (!grant || grant.revokedAt || grant.clientId !== row.clientId || grant.resource !== expectedResource) {
+        return unauthorizedMcpResponse(request, config, "MCP grant is no longer active", expectedSurface);
+    }
+    if (grant.expiresAt && Date.parse(grant.expiresAt) <= wallNowMs())
+        return unauthorizedMcpResponse(request, config, "MCP grant has expired", expectedSurface);
+    const user = await grantUser(db, grant, row.userId, options);
+    if (!user)
+        return unauthorizedMcpResponse(request, config, "MCP subject is no longer valid", expectedSurface);
+    const resourceRequest = resourceOverride ? new Request(expectedResource) : request;
+    const surface = mcpSurfaceForResource(resourceRequest, config, expectedResource, options);
+    if (!surface)
+        return unauthorizedMcpResponse(request, config, "Unknown MCP resource", expectedSurface);
+    if (surface.id === "operator") {
+        if (grant.subjectType !== "raybase-operator" || grant.subjectId !== user.id) {
+            return unauthorizedMcpResponse(request, config, "MCP grant is not valid for Operator MCP", expectedSurface);
+        }
+        const grantScopes = splitScopes(parseJson(grant.scopes));
+        if (authorizeMcpScopes(user, grantScopes, surface, options)) {
+            return unauthorizedMcpResponse(request, config, "Operator MCP grant is no longer authorized", expectedSurface);
+        }
+    }
+    else if (grant.subjectType === "raybase-operator" || row.scope.includes("operator:")) {
+        return unauthorizedMcpResponse(request, config, "Operator MCP tokens cannot be used on the app MCP resource", expectedSurface);
+    }
+    const tokenHostAccount = grant.hostAccount || undefined;
+    if (options.hostApproval) {
+        // A request that names a host account must name the token's.
+        const requested = new URL(request.url).searchParams.get(hostAccountParam(options.hostApproval));
+        if (requested) {
+            let normalized;
+            try {
+                normalized = options.hostApproval.normalizeHostAccount(requested);
+            }
+            catch {
+                normalized = null;
+            }
+            if (normalized !== tokenHostAccount)
+                return jsonResponse({ error: "Requested host account does not match the token's host account" }, { status: 403 });
+        }
+    }
+    const now = nowIso();
+    await db.run(`UPDATE "_oauth_access_tokens" SET "lastUsedAt" = ? WHERE "id" = ?`, [now, row.id]);
+    await db.run(`UPDATE "_mcp_grants" SET "lastUsedAt" = ? WHERE "id" = ?`, [now, grant.id]);
+    return {
+        tokenId: row.id,
+        grantId: grant.id,
+        user,
+        subjectType: grant.subjectType,
+        subjectId: grant.subjectId,
+        clientId: row.clientId,
+        clientName: grant.clientName,
+        scopes: splitScopes(parseJson(row.scope)),
+        resource: row.resource,
+        hostAccount: tokenHostAccount,
+        organizationId: grant.organizationId ?? null,
+        grantType: grant.grantType === "client_credentials" ? "client_credentials" : "authorization_code"
+    };
+}
+function jsonSchema(inputSchema) {
+    return jsonSchemaFor(inputSchema);
+}
+function mcpToolMeta(tool) {
+    if (!tool._meta)
+        return undefined;
+    const meta = { ...tool._meta };
+    if (meta.ui) {
+        meta.ui = {
+            ...meta.ui,
+            visibility: toolMcpAppVisibility(tool)
+        };
+    }
+    return meta;
+}
+function mcpToolDescriptor(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: jsonSchema(tool.inputSchema),
+        annotations: tool.annotations,
+        _meta: mcpToolMeta(tool)
+    };
+}
+function parseToolArgs(tool, raw) {
+    if (typeof tool.inputSchema.parse === "function")
+        return tool.inputSchema.parse(raw);
+    return raw ?? {};
+}
+function rpcResult(id, result) {
+    return { jsonrpc: "2.0", id: id ?? null, result };
+}
+function rpcError(id, code, message, data) {
+    return { jsonrpc: "2.0", id: id ?? null, error: { code, message, data } };
+}
+function isJsonRpcRequest(value) {
+    const candidate = asRecord(value);
+    return candidate.jsonrpc === "2.0" && typeof candidate.method === "string";
+}
+function zodListSchema() {
+    return z
+        .object({
+        limit: z.coerce.number().int().min(1).max(500).optional(),
+        offset: z.coerce.number().int().min(0).optional(),
+        search: z.string().optional(),
+        filter: z.record(z.string(), z.unknown()).optional(),
+        sort: z.object({ column: z.string(), direction: z.enum(["asc", "desc"]).optional() }).optional()
+    })
+        .strict();
+}
+function zodIdSchema() {
+    return z.object({ id: z.string().min(1) }).strict();
+}
+function generatedToolName(action, table) {
+    const singular = table.name.endsWith("s") ? table.name.slice(0, -1) : table.name;
+    return action === "list" ? `list_${table.name}` : `${action}_${singular}`;
+}
+export function generatedMcpTools(schema, config) {
+    const tools = [];
+    for (const [tableKey, actions] of Object.entries(config?.tables ?? {})) {
+        const entry = schema.tables[tableKey]
+            ? [tableKey, schema.tables[tableKey]]
+            : Object.entries(schema.tables).find(([, candidate]) => candidate.name === tableKey);
+        const table = entry?.[1];
+        if (!table)
+            throw new Error(`Unknown table for generated MCP tools: ${tableKey}`);
+        const clientTableKey = entry[0];
+        for (const action of actions) {
+            const name = generatedToolName(action, table);
+            if (action === "list") {
+                tools.push({
+                    name,
+                    description: `List ${table.label ?? table.name}`,
+                    inputSchema: zodListSchema(),
+                    annotations: { readOnlyHint: true },
+                    scopes: ["mcp:read", `mcp:table:${table.name}:read`, `mcp:tool:${name}`],
+                    handler: async (args, ctx) => {
+                        const input = asRecord(args);
+                        const result = await ctx.db.list(clientTableKey, input);
+                        return { content: [{ type: "text", text: `Found ${result.total} ${table.name} row(s).` }], structuredContent: result };
+                    }
+                });
+            }
+            else if (action === "get") {
+                tools.push({
+                    name,
+                    description: `Get one ${table.label ?? table.name} row`,
+                    inputSchema: zodIdSchema(),
+                    annotations: { readOnlyHint: true },
+                    scopes: ["mcp:read", `mcp:table:${table.name}:read`, `mcp:tool:${name}`],
+                    handler: async (args, ctx) => {
+                        const row = await ctx.db.get(clientTableKey, String(asRecord(args).id));
+                        return row
+                            ? { content: [{ type: "text", text: `Loaded ${table.name} ${row.id}.` }], structuredContent: row }
+                            : { content: [{ type: "text", text: `${table.name} row not found.` }], isError: true };
+                    }
+                });
+            }
+            else if (action === "create") {
+                tools.push({
+                    name,
+                    description: `Create a ${table.label ?? table.name} row`,
+                    inputSchema: inputSchemaForTable(table, "create"),
+                    annotations: { idempotentHint: false },
+                    scopes: ["mcp:write", `mcp:table:${table.name}:write`, `mcp:tool:${name}`],
+                    handler: async (args, ctx) => {
+                        const row = await ctx.db.create(clientTableKey, asRecord(args));
+                        return { content: [{ type: "text", text: `Created ${table.name} ${row.id}.` }], structuredContent: row };
+                    }
+                });
+            }
+            else if (action === "update") {
+                tools.push({
+                    name,
+                    description: `Update a ${table.label ?? table.name} row`,
+                    inputSchema: z.object({ id: z.string().min(1), patch: inputSchemaForTable(table, "update").partial() }).strict(),
+                    annotations: { idempotentHint: true },
+                    scopes: ["mcp:write", `mcp:table:${table.name}:write`, `mcp:tool:${name}`],
+                    handler: async (args, ctx) => {
+                        const input = asRecord(args);
+                        const row = await ctx.db.update(clientTableKey, String(input.id), asRecord(input.patch));
+                        return { content: [{ type: "text", text: `Updated ${table.name} ${row.id}.` }], structuredContent: row };
+                    }
+                });
+            }
+            else if (action === "delete") {
+                tools.push({
+                    name,
+                    description: `Delete a ${table.label ?? table.name} row`,
+                    inputSchema: zodIdSchema(),
+                    annotations: { destructiveHint: true, idempotentHint: false },
+                    scopes: ["mcp:write", `mcp:table:${table.name}:write`, `mcp:tool:${name}`],
+                    handler: async (args, ctx) => {
+                        const id = String(asRecord(args).id);
+                        await ctx.db.delete(clientTableKey, id);
+                        return { content: [{ type: "text", text: `Deleted ${table.name} ${id}.` }], structuredContent: { ok: true } };
+                    }
+                });
+            }
+        }
+    }
+    return tools;
+}
+function generatedSearchMcpTools(options) {
+    if (!options.search)
+        return [];
+    const tools = [];
+    const usedNames = new Set();
+    const inputSchema = z
+        .object({
+        query: z.string().min(1),
+        limit: z.coerce.number().int().min(1).max(20).default(10)
+    })
+        .strict();
+    const pushTool = (tool) => {
+        if (usedNames.has(tool.name))
+            return;
+        usedNames.add(tool.name);
+        tools.push(tool);
+    };
+    for (const index of Object.values(options.search.indexes)) {
+        pushTool({
+            name: mcpToolName(`search_${index.name}`),
+            description: `Search ${index.title ?? index.name}`,
+            inputSchema,
+            annotations: { readOnlyHint: true },
+            scopes: ["mcp:read", "mcp:search:read", `mcp:tool:${mcpToolName(`search_${index.name}`)}`],
+            handler: async (args, ctx) => {
+                const input = asRecord(args);
+                const db = createRaybaseDb(ctx.env, options.schema, options.appMigrations);
+                const result = await searchIndex({
+                    schema: options.schema,
+                    db: ctx.db,
+                    control: db.control,
+                    search: options.search,
+                    indexName: index.name,
+                    query: String(input.query ?? ""),
+                    limit: Number(input.limit ?? 10)
+                });
+                return {
+                    content: [{ type: "text", text: `Found ${result.results.length} search result(s).` }],
+                    structuredContent: { results: result.results, query: result.query?.raw ?? "" }
+                };
+            }
+        });
+        const tableSources = index.sources.filter((source) => source.kind === "table");
+        for (const source of tableSources) {
+            const name = mcpToolName(`search_${source.table.name}`);
+            pushTool({
+                name,
+                description: `Search ${source.table.label ?? source.table.name}`,
+                inputSchema,
+                annotations: { readOnlyHint: true },
+                scopes: ["mcp:read", "mcp:search:read", `mcp:table:${source.table.name}:read`, `mcp:tool:${name}`],
+                handler: async (args, ctx) => {
+                    const input = asRecord(args);
+                    const db = createRaybaseDb(ctx.env, options.schema, options.appMigrations);
+                    const result = await searchIndex({
+                        schema: options.schema,
+                        db: ctx.db,
+                        control: db.control,
+                        search: options.search,
+                        indexName: index.name,
+                        query: String(input.query ?? ""),
+                        limit: Number(input.limit ?? 10),
+                        sourceTables: [source.table.name]
+                    });
+                    return {
+                        content: [{ type: "text", text: `Found ${result.results.length} ${source.table.name} result(s).` }],
+                        structuredContent: { results: result.results, query: result.query?.raw ?? "" }
+                    };
+                }
+            });
+        }
+    }
+    return tools;
+}
+function mcpToolName(value) {
+    return value.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 64) || "search";
+}
+async function event(db, grantId, clientId, action, toolName, metadata) {
+    await db.run(`INSERT INTO "_mcp_grant_events" ("id", "grantId", "clientId", "action", "toolName", "metadata", "createdAt")
+     VALUES (?, ?, ?, ?, ?, ?, ?)`, [randomId("mcp_event"), grantId, clientId, action, toolName ?? null, metadata === undefined ? null : JSON.stringify(metadata), nowIso()]);
+}
+export function createMcpHandler(options) {
+    const surface = options.surface ?? "app";
+    const secretColumns = secretColumnKeys(options.schema, options.systemTables);
+    const allTools = [
+        ...generatedMcpTools(options.schema, options.generatedTools),
+        ...generatedSearchMcpTools(options),
+        ...(options.tools ?? [])
+    ];
+    const resources = options.resources ?? [];
+    for (const resource of resources)
+        validateMcpAppResource(resource);
+    for (const tool of allTools)
+        validateMcpAppTool(tool, resources);
+    const mcpAppUiEnabled = surface === "app" && supportsMcpAppUi(allTools, resources);
+    return async function handleMcp(request, env) {
+        if (request.method === "OPTIONS")
+            return new Response(null, { status: 204, headers: corsHeaders(request, options.config) });
+        if (request.method !== "POST")
+            return methodNotAllowed();
+        const originError = validateOrigin(request, options.config);
+        if (originError)
+            return originError;
+        const acceptError = validateAccept(request);
+        if (acceptError)
+            return acceptError;
+        let runtimeEnv = env;
+        const realtimeEnabled = options.realtime?.config.enabled === true;
+        const expectedResource = canonicalMcpResourceForSurface(request, options.config, surface);
+        let token;
+        if (options.validateAccessToken) {
+            token = await options.validateAccessToken({
+                request,
+                env,
+                surface,
+                expectedResource
+            });
+        }
+        else {
+            const initialDb = createRaybaseDb(runtimeEnv, options.schema, options.appMigrations);
+            await ensureMcpSystemTables(initialDb.control);
+            token = await validateMcpBearerToken(request, options.config, initialDb.control, surface, options.scopeOptions);
+        }
+        if (token instanceof Response)
+            return token;
+        runtimeEnv = await options.resolveRuntimeEnv?.({ request, env, token, surface }) ?? env;
+        const dbEnv = runtimeEnv;
+        const db = createRaybaseDb(dbEnv, options.schema, options.appMigrations, {
+            ...(realtimeEnabled ? { realtime: options.realtime?.config } : {}),
+            ...(options.search
+                ? {
+                    afterMutation: async (change) => {
+                        const searchDb = createRaybaseDb(dbEnv, options.schema, options.appMigrations);
+                        await updateSearchForDataChange({
+                            schema: options.schema,
+                            control: searchDb.control,
+                            search: options.search,
+                            change
+                        });
+                    }
+                }
+                : {})
+        });
+        const operatorRequest = token.scopes.some(isOperatorScope);
+        const limited = checkMcpRateLimit(request, operatorRequest ? `mcp-operator:${token.grantId}:${token.clientId}` : `mcp:${token.grantId}:${token.clientId}`, operatorRequest ? 120 : 300);
+        if (limited)
+            return limited;
+        const mcpContext = {
+            clientId: token.clientId,
+            clientName: token.clientName,
+            grantId: token.grantId,
+            scopes: token.scopes,
+            subject: token.subjectId,
+            hostAccount: token.hostAccount,
+            organizationId: token.organizationId ?? null,
+            auditMetadata: {
+                mcpGrantId: token.grantId,
+                mcpClientId: token.clientId,
+                mcpClientName: token.clientName,
+                mcpScopes: token.scopes,
+                mcpSubjectType: token.subjectType,
+                mcpSubject: token.subjectId,
+                mcpOrganizationId: token.organizationId ?? null,
+                hostAccount: token.hostAccount
+            }
+        };
+        try {
+            const extra = await options.resolveContext?.({ request, env: runtimeEnv, token });
+            Object.assign(mcpContext, extra ?? {});
+        }
+        catch (error) {
+            return jsonResponse({ error: error instanceof Error ? error.message : "MCP context rejected" }, { status: 403 });
+        }
+        const client = db.for({
+            user: token.user,
+            source: { surface: "mcp", requestId: request.headers.get("cf-ray") ?? undefined },
+            audit: (entry) => audit(db.control, token.user.id, entry.action, entry.target.type, entry.target.id ?? undefined, { ...asRecord(entry.metadata), ...mcpContext.auditMetadata }),
+            notify: realtimeEnabled
+                ? async (change) => {
+                    if (!("seq" in change))
+                        return;
+                    await dataStub(dbEnv).notifyDataChange({
+                        change: change,
+                        config: options.realtime.config,
+                        schema: options.realtime.schema
+                    });
+                }
+                : undefined,
+            realtime: options.realtime?.config
+        });
+        const extraToolContext = await options.toolContext?.({
+            request,
+            env: runtimeEnv,
+            user: token.user,
+            control: db.control,
+            mcp: mcpContext
+        });
+        const toolCtx = {
+            ...extraToolContext,
+            request,
+            env: runtimeEnv,
+            config: options.config,
+            user: token.user,
+            principal: token.user,
+            db: client,
+            control: db.control,
+            mcp: mcpContext,
+            audit: (action, metadata) => options.recordEvent
+                ? options.recordEvent({ env: runtimeEnv, token, action, metadata })
+                : event(db.control, mcpContext.grantId, mcpContext.clientId, action, undefined, metadata)
+        };
+        const body = await request.json().catch(() => null);
+        const requests = Array.isArray(body) ? body : [body];
+        const responses = [];
+        for (const rpc of requests) {
+            if (!isJsonRpcRequest(rpc)) {
+                responses.push(rpcError(null, -32600, "Invalid JSON-RPC request"));
+                continue;
+            }
+            const response = await handleRpc(rpc, allTools, resources, toolCtx, db.control, surface, mcpAppUiEnabled, secretColumns, options.recordEvent
+                ? (action, toolName, metadata) => options.recordEvent({ env: runtimeEnv, token, action, toolName, metadata })
+                : undefined, options.recordOperatorAudit
+                ? (action, targetType, targetId, metadata) => options.recordOperatorAudit({
+                    env: runtimeEnv,
+                    token,
+                    action,
+                    targetType,
+                    targetId,
+                    metadata
+                })
+                : undefined);
+            if (rpc.id !== undefined)
+                responses.push(response);
+        }
+        if (responses.length === 0)
+            return new Response(null, { status: 202, headers: corsHeaders(request, options.config) });
+        const headers = corsHeaders(request, options.config);
+        headers.set("content-type", "application/json; charset=utf-8");
+        return new Response(JSON.stringify(Array.isArray(body) ? responses : responses[0]), { headers });
+    };
+}
+function hasOperatorScope(scopes) {
+    return (scopes ?? []).some(isOperatorScope);
+}
+// Tool arguments reach the audit trail by key name. A secret() column can
+// have any name, so its keys are redacted first.
+function auditArguments(secretColumns, args) {
+    return sanitizeAuditValue(redactSecretColumnKeys(secretColumns, args));
+}
+function sanitizeAuditValue(value, depth = 0) {
+    if (depth > 4)
+        return "[truncated]";
+    if (value === null || value === undefined || typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (typeof value === "string")
+        return value.length > 500 ? `${value.slice(0, 500)}...[truncated]` : value;
+    if (Array.isArray(value))
+        return value.slice(0, 50).map((item) => sanitizeAuditValue(item, depth + 1));
+    const output = {};
+    for (const [key, entry] of Object.entries(asRecord(value))) {
+        if (/password|token|secret|accessToken|refreshToken|idToken|codeHash|tokenHash|publicKey|credential/i.test(key)) {
+            output[key] = "[redacted]";
+        }
+        else {
+            output[key] = sanitizeAuditValue(entry, depth + 1);
+        }
+    }
+    return output;
+}
+function operatorResultAuditMetadata(ctx, secretColumns, name, args, result) {
+    const content = asRecord(result?.structuredContent);
+    return {
+        ...ctx.mcp.auditMetadata,
+        toolName: name,
+        arguments: auditArguments(secretColumns, args),
+        appliedFilters: sanitizeAuditValue(content.appliedFilters),
+        rowCount: content.rowCount,
+        returned: content.returned,
+        truncated: content.truncated
+    };
+}
+function operatorErrorAuditMetadata(ctx, secretColumns, name, args, error) {
+    return {
+        ...ctx.mcp.auditMetadata,
+        toolName: name,
+        arguments: auditArguments(secretColumns, args),
+        error: error instanceof Error ? error.message : String(error)
+    };
+}
+async function handleRpc(rpc, tools, resources, ctx, control, surface, mcpAppUiEnabled, secretColumns, recordEvent, recordOperatorAudit) {
+    try {
+        switch (rpc.method) {
+            case "initialize":
+                const capabilities = {
+                    tools: {},
+                    resources: {}
+                };
+                if (surface === "app" && mcpAppUiEnabled && clientAcceptsMcpAppUi(rpc.params)) {
+                    capabilities.extensions = { [mcpAppsExtensionId]: {} };
+                }
+                return rpcResult(rpc.id, {
+                    protocolVersion: "2025-06-18",
+                    capabilities,
+                    serverInfo: { name: "raybase", title: ctx.config ? mcpConnectorName(ctx.config) : undefined, version: "0.1.0" },
+                    ...(surface === "app" && ctx.config && mcpInstructions(ctx.config) ? { instructions: mcpInstructions(ctx.config) } : {})
+                });
+            case "ping":
+                return rpcResult(rpc.id, {});
+            case "tools/list": {
+                const visibleTools = tools.filter((tool) => hasAnyScope(ctx.mcp.scopes, requiredScopesForTool(tool)));
+                return rpcResult(rpc.id, { tools: visibleTools.map(mcpToolDescriptor) });
+            }
+            case "tools/call": {
+                const params = asRecord(rpc.params);
+                const name = asString(params.name);
+                const tool = tools.find((candidate) => candidate.name === name);
+                if (!tool)
+                    return rpcError(rpc.id, -32602, `Unknown tool: ${name}`);
+                if (!hasAnyScope(ctx.mcp.scopes, requiredScopesForTool(tool))) {
+                    if (surface === "operator" && hasOperatorScope(tool.scopes)) {
+                        const metadata = operatorErrorAuditMetadata(ctx, secretColumns, name, params.arguments ?? {}, new Error(`Token scope does not allow tool: ${name}`));
+                        await (recordOperatorAudit
+                            ? recordOperatorAudit("operator_mcp.tool.error", "_mcp_grants", ctx.mcp.grantId, metadata)
+                            : audit(control, ctx.user.id, "operator_mcp.tool.error", "_mcp_grants", ctx.mcp.grantId, metadata)).catch(() => { });
+                    }
+                    return rpcError(rpc.id, -32001, `Token scope does not allow tool: ${name}`);
+                }
+                let args = params.arguments ?? {};
+                try {
+                    args = parseToolArgs(tool, params.arguments ?? {});
+                    if (recordEvent) {
+                        await recordEvent("tool.call", name, { arguments: auditArguments(secretColumns, args) });
+                    }
+                    else {
+                        await event(control, ctx.mcp.grantId, ctx.mcp.clientId, "tool.call", name, { arguments: auditArguments(secretColumns, args) });
+                    }
+                    const result = await tool.handler(args, ctx);
+                    if (hasOperatorScope(tool.scopes)) {
+                        const metadata = operatorResultAuditMetadata(ctx, secretColumns, name, args, result);
+                        await (recordOperatorAudit
+                            ? recordOperatorAudit("operator_mcp.tool.call", "_mcp_grants", ctx.mcp.grantId, metadata)
+                            : audit(control, ctx.user.id, "operator_mcp.tool.call", "_mcp_grants", ctx.mcp.grantId, metadata));
+                    }
+                    return rpcResult(rpc.id, result);
+                }
+                catch (error) {
+                    if (surface === "operator" && hasOperatorScope(tool.scopes)) {
+                        const metadata = operatorErrorAuditMetadata(ctx, secretColumns, name, args, error);
+                        await (recordOperatorAudit
+                            ? recordOperatorAudit("operator_mcp.tool.error", "_mcp_grants", ctx.mcp.grantId, metadata)
+                            : audit(control, ctx.user.id, "operator_mcp.tool.error", "_mcp_grants", ctx.mcp.grantId, metadata)).catch(() => { });
+                    }
+                    return rpcError(rpc.id, -32000, error instanceof Error ? error.message : "MCP request failed");
+                }
+            }
+            case "resources/list": {
+                const visibleResources = resources.filter((resource) => hasAnyScope(ctx.mcp.scopes, requiredScopesForResource(resource)));
+                return rpcResult(rpc.id, {
+                    resources: visibleResources.map((resource) => ({
+                        uri: resource.uri,
+                        name: resource.name,
+                        description: resource.description,
+                        mimeType: resource.mimeType,
+                        _meta: resource._meta
+                    }))
+                });
+            }
+            case "resources/read": {
+                const uri = asString(asRecord(rpc.params).uri);
+                const resource = resources.find((candidate) => candidate.uri === uri);
+                if (!resource)
+                    return rpcError(rpc.id, -32602, `Unknown resource: ${uri}`);
+                if (!hasAnyScope(ctx.mcp.scopes, requiredScopesForResource(resource)))
+                    return rpcError(rpc.id, -32001, "Token scope does not allow resources/read");
+                const read = normalizeMcpAppResourceRead(resource, await resource.read(ctx));
+                if (recordEvent) {
+                    await recordEvent("resource.read", undefined, { uri });
+                }
+                else {
+                    await event(control, ctx.mcp.grantId, ctx.mcp.clientId, "resource.read", undefined, { uri });
+                }
+                if (hasOperatorScope(resource.scopes)) {
+                    await audit(control, ctx.user.id, "operator_mcp.resource.read", "_mcp_grants", ctx.mcp.grantId, {
+                        ...ctx.mcp.auditMetadata,
+                        uri
+                    });
+                }
+                return rpcResult(rpc.id, { contents: [read] });
+            }
+            default:
+                return rpcError(rpc.id, -32601, `Method not found: ${rpc.method}`);
+        }
+    }
+    catch (error) {
+        return rpcError(rpc.id, -32000, error instanceof Error ? error.message : "MCP request failed");
+    }
+}
+export async function listMcpGrants(db) {
+    await ensureMcpSystemTables(db);
+    return db.all(`SELECT "id", "subjectType", "subjectId", "userId", "hostAccount", "clientId", "clientName", "scopes", "resource", "createdAt", "expiresAt", "revokedAt", "lastUsedAt", "organizationId", "grantType"
+     FROM "_mcp_grants" ORDER BY "createdAt" DESC LIMIT 500`);
+}
+/**
+ * Revokes one grant and everything that lives off it: its access and refresh
+ * tokens, and any confidential client bound to it. Every revoke path goes
+ * through here so they cannot drift; callers record their own audit or event.
+ */
+async function revokeGrantAndDependents(db, grantId) {
+    const now = nowIso();
+    await db.run(`UPDATE "_mcp_grants" SET "revokedAt" = ? WHERE "id" = ? AND "revokedAt" IS NULL`, [now, grantId]);
+    await db.run(`UPDATE "_oauth_access_tokens" SET "revokedAt" = ? WHERE "grantId" = ? AND "revokedAt" IS NULL`, [now, grantId]);
+    await db.run(`UPDATE "_oauth_refresh_tokens" SET "revokedAt" = ? WHERE "grantId" = ? AND "revokedAt" IS NULL`, [now, grantId]);
+    // A confidential client is only ever as alive as its grant.
+    await db.run(`UPDATE "_oauth_clients" SET "revokedAt" = ? WHERE "grantId" = ? AND "revokedAt" IS NULL`, [now, grantId]);
+}
+export async function revokeMcpGrant(db, grantId, actorId) {
+    await ensureMcpSystemTables(db);
+    await revokeGrantAndDependents(db, grantId);
+    await audit(db, actorId, "mcp.grant.revoke", "_mcp_grants", grantId);
+}
+/**
+ * Revokes every live grant bound to a host account, and their tokens, for
+ * example when the host reports that the account uninstalled the app.
+ * `hostAccount` may be in any form the app's `normalizeHostAccount` accepts;
+ * it is normalised here (pass the same `hostApproval` options the app gives
+ * `mcp.hostApproval`), and a value it rejects throws. Returns how many grants
+ * were revoked.
+ */
+export async function revokeMcpGrantsForHostAccount(db, hostApproval, hostAccountInput, actorId = null) {
+    const hostAccount = requireHostAccount(hostApproval, hostAccountInput);
+    await ensureMcpSystemTables(db);
+    const grants = await db.all(`SELECT "id" FROM "_mcp_grants" WHERE "hostAccount" = ? AND "revokedAt" IS NULL`, [hostAccount]);
+    for (const grant of grants) {
+        await revokeGrantAndDependents(db, grant.id);
+        await audit(db, actorId, "mcp.grant.revoke.host_account", "_mcp_grants", grant.id, { hostAccount });
+    }
+    return grants.length;
+}
+//# sourceMappingURL=mcp.js.map