@raybase/core 0.3.6 → 0.3.7

package/dist/mcp.js

@@ -2,17 +2,21 @@ import { z } from "zod";
 import { RAYBASE_CORE_VERSION } from "./version.js";
 import { withHostUserRoleCeiling } from "./host-user.js";
 import { redactSecretColumnKeys, secretColumnKeys } from "./data-secrets.js";
+import { actorAuditRef, recordAudit } from "./audit.js";
 import { audit, base64url, normalizeRoles } from "./auth.js";
+import { servicePrincipal } from "./principal.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 { actionInputIssues } from "./actions.js";
+import { jsonSchemaFor, parseWithSchema } 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";
+import { sameOriginPath } from "./same-origin-path.js";
 export const mcpAppsExtensionId = "io.modelcontextprotocol/ui";
 export const mcpAppResourceMimeType = "text/html;profile=mcp-app";
 const jsonHeaders = { "content-type": "application/json; charset=utf-8" };
@@ -596,7 +600,29 @@ export function wwwAuthenticate(request, config, surface = "app") {
     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") {
+/**
+ * The answer to an app connector request that names a host account but has
+ * no usable token. The connector's address is the plain one: its protected
+ * resource metadata names it without a query (RFC 9728 section 2 discourages
+ * one), and section 3.3 forbids a client to use metadata whose resource is not
+ * the address it was given. So an address carrying the account cannot get a
+ * token; a 401 would leave the client stuck without a word. This says why, and
+ * which address to give the agent. The account is asked for when the person
+ * connects, and confirmed by the host.
+ */
+function hostAccountAddressResponse(request, config, param) {
+    const address = canonicalMcpResource(request, config);
+    return jsonResponse({
+        error: `This connector's address is ${address}, without "${param}". Give the agent that address; it asks which account to connect when the person signs in.`,
+        address
+    }, { status: 400, headers: Object.fromEntries(corsHeaders(request, config)) });
+}
+function unauthorizedMcpResponse(request, config, error, surface = "app", options = {}) {
+    if (surface === "app" && options.hostApproval) {
+        const param = hostAccountParam(options.hostApproval);
+        if (new URL(request.url).searchParams.has(param))
+            return hostAccountAddressResponse(request, config, param);
+    }
     return jsonResponse({ error }, {
         status: 401,
         headers: { "www-authenticate": wwwAuthenticate(request, config, surface), ...Object.fromEntries(corsHeaders(request, config)) }
@@ -876,6 +902,12 @@ async function registerConfidentialClient(request, config, db, body, user, optio
         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);
+    // The credential is for one of this app's own connectors, at the address
+    // this request reached: never a resource on another origin.
+    if (!mcpSurfaceForResource(request, config, resource, options)) {
+        const connectors = mcpSurfaces(request, config, options).map((surface) => surface.resource).join(" or ");
+        return jsonResponse({ error: "invalid_target", error_description: `resource must be this app's connector: ${connectors}` }, { status: 400 });
+    }
     let created;
     try {
         created = await createMcpMachineCredential(db, config, {
@@ -945,6 +977,15 @@ export async function createMcpMachineCredential(db, config, input, options = {}
     const scopeError = authorizeMcpScopes(input.user, scopes, surface, options);
     if (scopeError)
         throw new McpMachineCredentialError("invalid_scope", scopeError);
+    // A credential holds only scopes its connector honours: one no tool or
+    // resource answers to would sit on the grant, unexplained, until a later
+    // tool happened to take its name. (authorizeMcpScopes already holds the
+    // operator connector to its own list.)
+    const offered = new Set([...surface.scopesSupported, ...(options.appScopes ?? [])]);
+    const unoffered = surface.id === "app" ? scopes.filter((scope) => !offered.has(scope)) : [];
+    if (unoffered.length) {
+        throw new McpMachineCredentialError("invalid_scope", `${surface.label} does not offer ${unoffered.length === 1 ? "the scope" : "the scopes"} ${unoffered.join(", ")}`);
+    }
     const authMethod = input.tokenEndpointAuthMethod ?? "client_secret_basic";
     const user = input.user;
     const clientId = `raybase_cc_${randomId("client")}`;
@@ -1116,8 +1157,12 @@ function consentStylesheetHref(config) {
     const href = config.mcp?.consent?.stylesheet?.trim();
     if (!href)
         return null;
-    if (href.startsWith("/") && !href.startsWith("//"))
-        return href;
+    if (href.startsWith("/")) {
+        const path = sameOriginPath(href);
+        if (path)
+            return path;
+        throw new Error("mcp.consent.stylesheet must be a root-relative path or an HTTPS URL");
+    }
     try {
         if (new URL(href).protocol === "https:")
             return href;
@@ -1258,6 +1303,18 @@ export async function mcpAuthorizationOrganizationHint(request) {
     const value = asString(input.org).trim();
     return value || null;
 }
+/**
+ * Who a grant's writes are audited as. A host-account grant acts as the
+ * host's subject, which is no Raybase user, while `_audit.actorId` names
+ * one; so it is audited as a service principal, the way Core audits every
+ * actor that is not a user, and the account, subject and grant travel in the
+ * entry's metadata. Every other grant acts as its user.
+ */
+function mcpGrantAuditActor(grant) {
+    if (grant.hostAccount)
+        return servicePrincipal("raybase-mcp-host-account", { id: grant.subjectId });
+    return actorAuditRef(grant.userId);
+}
 /** The identity a host-account grant acts as: a plain app user, never an operator. */
 function hostAccountUser(hostAccount, subject) {
     return {
@@ -1332,13 +1389,18 @@ async function createGrantAndCode(db, config, request, user, values, clientName,
         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
+    await recordAudit(db, {
+        actor: mcpGrantAuditActor({ hostAccount, subjectId, userId: user.id }),
+        action: surface.id === "operator" ? "operator_mcp.grant.create" : "mcp.grant.create",
+        target: { type: "_mcp_grants", id: grantId },
+        metadata: {
+            clientId: values.client_id,
+            scopes,
+            resource,
+            surface: surface.id,
+            hostAccount,
+            organizationId
+        }
     });
     const redirect = new URL(values.redirect_uri);
     redirect.searchParams.set("code", code);
@@ -1383,10 +1445,10 @@ function authorizeMcpScopes(user, scopes, surface, options = {}) {
     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;
+    const path = sameOriginPath(config.mcp?.oauth?.signInPath?.trim() || "/login");
+    if (!path)
+        throw new Error("mcp.oauth.signInPath must be a root-relative path on this origin");
+    return path;
 }
 /** The authorization request as a GET address on this origin, path and query only. */
 function authorizationRequestPath(values, choice, input) {
@@ -1424,10 +1486,11 @@ export async function authorizeMcpOAuthRequest(request, config, db, user, option
             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 ownPageSetting = config.mcp?.consent?.path?.trim();
+    if (ownPageSetting) {
+        const ownPage = sameOriginPath(ownPageSetting);
+        if (!ownPage)
+            throw new Error("mcp.consent.path must be a root-relative path on this origin");
         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" } });
@@ -1519,8 +1582,9 @@ export async function handleMcpHostConnect(request, config, options) {
 /**
  * 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.
+ * host's admin to approve it. With no host account, sends the person to the
+ * connect page first; an authorization request for any resource other than
+ * the app connector is refused.
  */
 export async function beginMcpHostAuthorization(request, config, db, env, options) {
     const limited = checkMcpRateLimit(request, "host-oauth-authorize", 120);
@@ -1528,7 +1592,10 @@ export async function beginMcpHostAuthorization(request, config, db, env, option
         return limited;
     const param = hostAccountParam(options);
     const input = await authorizationInput(request);
-    if (!input[param]) {
+    const canonical = canonicalMcpResource(request, config);
+    // Only a request for the connector itself is sent to ask for an account;
+    // one for any other resource is refused below, before anyone types one.
+    if (!input[param] && (!input.resource || input.resource === canonical)) {
         const connect = new URL(mcpHostApprovalPath(options, "connectPath"), request.url);
         for (const [key, value] of Object.entries(input))
             connect.searchParams.set(key, value);
@@ -1539,8 +1606,8 @@ export async function beginMcpHostAuthorization(request, config, db, env, option
         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))
+    const resource = validated.values.resource || canonical;
+    if (resource !== canonical)
         return redirectWithError(validated.values.redirect_uri, validated.values.state || null, "invalid_target");
     const hostAccount = options.normalizeHostAccount(input[param]);
     const pendingId = randomId("mcp_pending");
@@ -1828,40 +1895,40 @@ export async function validateMcpBearerToken(request, config, db, expectedSurfac
     const header = request.headers.get("authorization") ?? "";
     const match = /^Bearer\s+(.+)$/i.exec(header);
     if (!match) {
-        return unauthorizedMcpResponse(request, config, "Unauthorized", expectedSurface);
+        return unauthorizedMcpResponse(request, config, "Unauthorized", expectedSurface, options);
     }
     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);
+        return unauthorizedMcpResponse(request, config, "Invalid or expired token", expectedSurface, options);
     }
     const expectedResource = resourceOverride ?? canonicalMcpResourceForSurface(request, config, expectedSurface);
     if (row.resource !== expectedResource)
-        return unauthorizedMcpResponse(request, config, "Token audience does not match this MCP resource", expectedSurface);
+        return unauthorizedMcpResponse(request, config, "Token audience does not match this MCP resource", expectedSurface, options);
     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);
+        return unauthorizedMcpResponse(request, config, "MCP grant is no longer active", expectedSurface, options);
     }
     if (grant.expiresAt && Date.parse(grant.expiresAt) <= wallNowMs())
-        return unauthorizedMcpResponse(request, config, "MCP grant has expired", expectedSurface);
+        return unauthorizedMcpResponse(request, config, "MCP grant has expired", expectedSurface, options);
     const user = await grantUser(db, grant, row.userId, options);
     if (!user)
-        return unauthorizedMcpResponse(request, config, "MCP subject is no longer valid", expectedSurface);
+        return unauthorizedMcpResponse(request, config, "MCP subject is no longer valid", expectedSurface, options);
     const resourceRequest = resourceOverride ? new Request(expectedResource) : request;
     const surface = mcpSurfaceForResource(resourceRequest, config, expectedResource, options);
     if (!surface)
-        return unauthorizedMcpResponse(request, config, "Unknown MCP resource", expectedSurface);
+        return unauthorizedMcpResponse(request, config, "Unknown MCP resource", expectedSurface, options);
     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);
+            return unauthorizedMcpResponse(request, config, "MCP grant is not valid for Operator MCP", expectedSurface, options);
         }
         const grantScopes = splitScopes(parseJson(grant.scopes));
         if (authorizeMcpScopes(user, grantScopes, surface, options)) {
-            return unauthorizedMcpResponse(request, config, "Operator MCP grant is no longer authorized", expectedSurface);
+            return unauthorizedMcpResponse(request, config, "Operator MCP grant is no longer authorized", expectedSurface, options);
         }
     }
     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);
+        return unauthorizedMcpResponse(request, config, "Operator MCP tokens cannot be used on the app MCP resource", expectedSurface, options);
     }
     const tokenHostAccount = grant.hostAccount || undefined;
     if (options.hostApproval) {
@@ -1921,10 +1988,44 @@ function mcpToolDescriptor(tool) {
         _meta: mcpToolMeta(tool)
     };
 }
+/**
+ * Validates a call's arguments against the tool's input schema, Zod or JSON
+ * Schema, the way an action validates its input. A failure comes back as the
+ * issues, each naming the field and what it must be.
+ */
 function parseToolArgs(tool, raw) {
-    if (typeof tool.inputSchema.parse === "function")
-        return tool.inputSchema.parse(raw);
-    return raw ?? {};
+    try {
+        return { ok: true, value: parseWithSchema(tool.inputSchema, raw, "arguments") };
+    }
+    catch (error) {
+        return { ok: false, issues: actionInputIssues(error) };
+    }
+}
+function invalidToolArgumentsMessage(toolName, issues) {
+    const listed = issues.map((issue) => (issue.path === "(root)" ? issue.message : `${issue.path}: ${issue.message}`));
+    return listed.length
+        ? `The arguments for ${toolName} do not match its input schema. ${listed.join("; ")}.`
+        : `The arguments for ${toolName} do not match its input schema.`;
+}
+/** The tool result for arguments its schema refuses, shaped like an action's invalid_input error. */
+function invalidToolArgumentsResult(toolName, issues) {
+    const message = invalidToolArgumentsMessage(toolName, issues);
+    const guidance = issues.length
+        ? `Fix the fields named above and call ${toolName} again.`
+        : `Call ${toolName} again with arguments that match its input schema.`;
+    return {
+        content: [{ type: "text", text: `${message} ${guidance}` }],
+        structuredContent: {
+            ok: false,
+            tool: toolName,
+            code: "invalid_input",
+            message,
+            guidance,
+            retryable: true,
+            ...(issues.length ? { details: { issues } } : {})
+        },
+        isError: true
+    };
 }
 function rpcResult(id, result) {
     return { jsonrpc: "2.0", id: id ?? null, result };
@@ -2121,14 +2222,32 @@ 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 = [
+function connectorTools(options) {
+    return [
         ...generatedMcpTools(options.schema, options.generatedTools),
         ...generatedSearchMcpTools(options),
         ...(options.tools ?? [])
     ];
+}
+/**
+ * Every scope the app connector's tools and resources answer to, given the
+ * options its `createMcpHandler` gets: what a machine credential for it may
+ * ask for (`RaybaseMcpScopeOptions.appScopes`).
+ */
+export function mcpAppConnectorScopes(options) {
+    const scopes = new Set();
+    for (const tool of connectorTools(options))
+        for (const scope of requiredScopesForTool(tool))
+            scopes.add(scope);
+    for (const resource of options.resources ?? [])
+        for (const scope of requiredScopesForResource(resource))
+            scopes.add(scope);
+    return [...scopes].filter((scope) => !isOperatorScope(scope)).sort();
+}
+export function createMcpHandler(options) {
+    const surface = options.surface ?? "app";
+    const secretColumns = secretColumnKeys(options.schema, options.systemTables);
+    const allTools = connectorTools(options);
     const resources = options.resources ?? [];
     for (const resource of resources)
         validateMcpAppResource(resource);
@@ -2216,7 +2335,12 @@ export function createMcpHandler(options) {
         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 }),
+            audit: (entry, auditDb) => recordAudit(auditDb, {
+                actor: mcpGrantAuditActor({ hostAccount: token.hostAccount, subjectId: token.subjectId, userId: token.user.id }),
+                action: entry.action,
+                target: entry.target,
+                metadata: { ...asRecord(entry.metadata), ...mcpContext.auditMetadata }
+            }),
             notify: realtimeEnabled
                 ? async (change) => {
                     if (!("seq" in change))
@@ -2367,9 +2491,21 @@ async function handleRpc(rpc, tools, resources, ctx, control, surface, mcpAppUiE
                     }
                     return rpcError(rpc.id, -32001, `Token scope does not allow tool: ${name}`);
                 }
-                let args = params.arguments ?? {};
+                const parsed = parseToolArgs(tool, params.arguments ?? {});
+                if (!parsed.ok) {
+                    // Arguments that fail the tool's schema are a tool execution error
+                    // (MCP 2025-06-18, "Error Handling"): the model reads which fields
+                    // are wrong and calls again. A JSON-RPC error would stop it there.
+                    if (surface === "operator" && hasOperatorScope(tool.scopes)) {
+                        const metadata = operatorErrorAuditMetadata(ctx, secretColumns, name, params.arguments ?? {}, new Error(invalidToolArgumentsMessage(name, parsed.issues)));
+                        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 rpcResult(rpc.id, invalidToolArgumentsResult(name, parsed.issues));
+                }
+                const args = parsed.value;
                 try {
-                    args = parseToolArgs(tool, params.arguments ?? {});
                     if (recordEvent) {
                         await recordEvent("tool.call", name, { arguments: auditArguments(secretColumns, args) });
                     }