@bevel-software/platform-core-backend 0.30.0 → 0.31.0

package/src/modules/mcp/mcp-auth.middleware.ts

@@ -12,6 +12,23 @@ import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
 import '../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
 import '../audit/audit.contract.js'; // Express Request augmentation (req.agentConnectionId)
 
+/** Which of the four credentials below an MCP request was authenticated with. */
+export type McpCallerKind = 'key' | 'oauth' | 'internal' | 'session';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Request {
+      /**
+       * The kind of credential the MCP auth middleware admitted the request
+       * with. Only a `session` — the person signed in to the app — may name
+       * the page its call comes from (`X-Bevel-Page`).
+       */
+      mcpCallerKind?: McpCallerKind;
+    }
+  }
+}
+
 /**
  * Auth middleware for the MCP endpoint. Accepts any of:
  *
@@ -94,6 +111,7 @@ export function createMcpAuthMiddleware(
         req.userId = resolved.user.id;
         req.userEmail = resolved.user.email;
         req.externalApiKeyId = resolved.tokenId;
+        req.mcpCallerKind = 'key';
         next();
         return;
       } catch (err) {
@@ -136,6 +154,7 @@ export function createMcpAuthMiddleware(
       // Outside the try so a synchronous throw from a downstream handler isn't
       // misclassified as a token-verification failure (and doesn't try to write
       // a second response).
+      req.mcpCallerKind = 'oauth';
       next();
       return;
     }
@@ -215,6 +234,7 @@ export function createMcpAuthMiddleware(
         oauthProvider.noteConnectionUse(claim.connectionId);
         req.agentConnectionId = claim.connectionId;
       }
+      req.mcpCallerKind = 'internal';
       next();
       return;
     }
@@ -236,6 +256,7 @@ export function createMcpAuthMiddleware(
     }
     req.userId = session.userId;
     req.userEmail = session.email;
+    req.mcpCallerKind = 'session';
     next();
   };
 }

package/src/modules/mcp/mcp.routes.ts

@@ -16,6 +16,8 @@ import { MCP_LOOPBACK_TOKEN_TTL_MS, type McpService } from './mcp.service.js';
 import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
 import type { ILlmUsageMeter } from '../tool-auth/llm-usage-meter.js';
 import '../tool-auth/external-api-key.interface.js'; // req.externalApiKeyId augmentation
+import './mcp-auth.middleware.js'; // req.mcpCallerKind augmentation
+import { isPagePath } from '../audit/index.js';
 
 /** Pull the raw bearer token off an already-authenticated request. */
 function extractBearer(req: Request): string {
@@ -43,6 +45,33 @@ function jsonRpcError(res: Response, status: number, code: number, message: stri
   res.status(status).json({ jsonrpc: '2.0', error: { code, message }, id: null });
 }
 
+/** The header a page's calls carry: the page's knowledge-base path, URI-encoded. */
+export const PAGE_HEADER = 'x-bevel-page';
+
+/**
+ * The page a request names, decoded: null when it names none, an error
+ * message when it names one it may not.
+ *
+ * Only a session — the person signed in to the app, whose app is relaying a
+ * page's calls — may name one. A connection key, an OAuth token or an
+ * internal token belongs to an agent, which has an Audit log row of its own;
+ * letting it name a page would let it write its calls into a page's history.
+ */
+function pageOf(req: Request): { page: string | null } | { error: string } {
+  const raw = req.headers[PAGE_HEADER];
+  if (raw === undefined) return { page: null };
+  if (req.mcpCallerKind !== 'session') {
+    return { error: 'X-Bevel-Page names the page a signed-in person\'s call comes from; it is not accepted with this credential.' };
+  }
+  let page: string;
+  try {
+    page = decodeURIComponent(Array.isArray(raw) ? (raw[0] ?? '') : raw);
+  } catch {
+    return { error: 'X-Bevel-Page is not a URI-encoded path.' };
+  }
+  return isPagePath(page) ? { page } : { error: 'X-Bevel-Page is not a knowledge-base path.' };
+}
+
 /**
  * Routes for the remote MCP server + the connection-key management endpoints.
  *
@@ -57,6 +86,8 @@ function jsonRpcError(res: Response, status: number, code: number, message: stri
  *
  *   POST   /mcp/local-token               — exchange an MCP OAuth access token
  *                                           for a loopback internal token
+ *   POST   /mcp/page-refusals             — record a page's call its viewer
+ *                                           refused (session only)
  *
  * The `/mcp` POST accepts either a connection key or a JWT/OAuth token (see
  * McpAuthMiddleware). The `/mcp/external-api-keys/*` endpoints accept only the JWT —
@@ -100,6 +131,11 @@ export function createMcpRoutes(
    * closes — finished, or abandoned by the client mid-call.
    */
   router.post('/mcp', mcpAuthMiddleware, async (req, res) => {
+    const named = pageOf(req);
+    if ('error' in named) {
+      jsonRpcError(res, 400, TRANSPORT_ERROR, named.error);
+      return;
+    }
     let server: Server | undefined;
     res.on('close', () => {
       // Closing the server closes its transport too.
@@ -122,6 +158,9 @@ export function createMcpRoutes(
           // The proxy authenticates its loopback calls with the SAME bearer the
           // client used here, so it acts on the request exactly as the caller would.
           bearer: extractBearer(req),
+          // The page whose script made the call, when the app relays one —
+          // its calls are audited under the page (see pageOf).
+          ...(named.page ? { page: named.page } : {}),
         },
         req.body,
       );
@@ -165,6 +204,35 @@ export function createMcpRoutes(
   router.get('/mcp', methodNotAllowed);
   router.delete('/mcp', methodNotAllowed);
 
+  /**
+   * A call a page asked to make and its viewer refused. It never ran, so it
+   * never reached `/mcp`; the app reports it so the Audit log lists it
+   * under the page, as refused, beside the page's allowed calls.
+   *
+   * Body: `{ page, tool, args? }` — the page's knowledge-base path and the
+   * tool's name as the page called it. Session only, like the page header.
+   */
+  router.post('/mcp/page-refusals', mcpAuthMiddleware, async (req, res) => {
+    if (req.mcpCallerKind !== 'session') {
+      res.status(403).json({ error: 'Only the app records a page\'s refused calls.' });
+      return;
+    }
+    const body = (req.body ?? {}) as { page?: unknown; tool?: unknown; args?: unknown };
+    if (typeof body.page !== 'string' || !isPagePath(body.page) || typeof body.tool !== 'string' || !body.tool) {
+      res.status(400).json({ error: 'page (a knowledge-base path) and tool are required' });
+      return;
+    }
+    const args =
+      body.args && typeof body.args === 'object' && !Array.isArray(body.args) ? (body.args as Record<string, unknown>) : {};
+    try {
+      await mcpService.recordPageRefusal({ userId: req.userId!, bearer: extractBearer(req) }, body.page, body.tool, args);
+      res.status(204).end();
+    } catch (err) {
+      log.error('recording a page refusal failed:', { err });
+      res.status(500).json({ error: 'Failed to record the refusal' });
+    }
+  });
+
   // ── Connection-key management (JWT-only) ───────────────────────────────
 
   router.get('/mcp/external-api-keys', jwtAuthMiddleware, async (req, res) => {