@bevel-software/platform-core-backend 0.10.0 → 0.11.1

package/src/modules/mcp/__tests__/mcp.routes.local-token.test.ts

@@ -0,0 +1,301 @@
+import type { Server as HttpServer } from 'node:http';
+import type { RequestHandler } from 'express';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { createMcpRoutes } from '../mcp.routes.js';
+import { MCP_LOOPBACK_TOKEN_TTL_MS } from '../mcp.service.js';
+import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import { createTokenVerifier } from '../../tool-auth/tool-auth.middleware.js';
+import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
+import type { BevelOAuthProvider } from '../oauth/bevel-oauth-provider.js';
+
+/**
+ * Coverage for POST /api/mcp/local-token — the OAuth-access-token → internal
+ * loopback-token exchange the LOCAL MCP server uses to reach the
+ * keys+internal-tokens-only `/api/agent/*` surface. Locks down:
+ *
+ *   - a verified OAuth token mints an internal token that the tool-auth
+ *     verifier resolves to the SAME identity createSession's loopback bearer
+ *     gets (right userId, externalProxy → source 'external'), with the shared
+ *     MCP_LOOPBACK_TOKEN_TTL_MS lifetime;
+ *   - an expired/revoked OAuth token re-challenges (401 + resource_metadata),
+ *     mirroring McpAuthMiddleware's OAuth branch — including a grant the
+ *     provider verifies but reports as out of lifetime, which must never
+ *     become a 200 carrying a dead token;
+ *   - every other credential shape (connection key, JWT) is 403 — those need
+ *     no exchange, so accepting them would mint a second credential from a
+ *     first;
+ *   - missing/garbage auth is 401 with the discovery challenge.
+ */
+
+const RESOURCE_METADATA_URL = 'https://bevel.example/.well-known/oauth-protected-resource/api/mcp';
+
+// Stand-in for routes this suite never exercises.
+const fakeAuth: RequestHandler = (req, _res, next) => {
+  req.userId = 'user-A';
+  next();
+};
+
+let httpServer: HttpServer | undefined;
+
+afterEach(async () => {
+  if (httpServer) {
+    await new Promise<void>((resolve) => httpServer!.close(() => resolve()));
+    httpServer = undefined;
+  }
+  vi.restoreAllMocks();
+});
+
+function makeOAuthProvider(
+  verify?: (t: string) => Promise<{ extra?: Record<string, unknown>; expiresAt?: number }>,
+) {
+  return {
+    looksLikeAccessToken: (t: string) => typeof t === 'string' && t.startsWith('bevel-mcp_'),
+    verifyAccessToken: vi.fn(
+      verify ??
+        (async () => {
+          throw new InvalidTokenError('unknown token');
+        }),
+    ),
+  } as unknown as BevelOAuthProvider;
+}
+
+async function mount(oauth: BevelOAuthProvider): Promise<{
+  baseUrl: string;
+  internalTokens: InternalTokenService;
+}> {
+  const internalTokens = new InternalTokenService({ secret: 'test-secret' });
+  const externalApiKeyService = {
+    looksLikeExternalApiKey: (t: string) => typeof t === 'string' && t.startsWith('bevel_'),
+  } as unknown as IExternalApiKeyService;
+  // createMcpRoutes only touches mcpService.onSessionEvicted at construction.
+  const mcpService = { onSessionEvicted: () => {} } as never;
+  const stub = {} as never;
+
+  const app = express();
+  app.use(express.json());
+  app.use(
+    '/api',
+    createMcpRoutes(
+      mcpService,
+      externalApiKeyService,
+      fakeAuth,
+      fakeAuth,
+      stub,
+      internalTokens,
+      oauth,
+      RESOURCE_METADATA_URL,
+    ),
+  );
+
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const port = (httpServer.address() as { port: number }).port;
+  return { baseUrl: `http://127.0.0.1:${port}`, internalTokens };
+}
+
+async function exchange(baseUrl: string, authorization?: string): Promise<Response> {
+  return fetch(`${baseUrl}/api/mcp/local-token`, {
+    method: 'POST',
+    headers: authorization ? { Authorization: authorization } : {},
+  });
+}
+
+describe('POST /mcp/local-token', () => {
+  it('exchanges a valid OAuth access token for an internal token with the loopback identity + TTL', async () => {
+    const oauth = makeOAuthProvider(async () => ({
+      extra: { userId: 'user-5', userEmail: 'eve@example.com' },
+      // A grant with plenty of life left: the loopback constant is the binding cap.
+      expiresAt: Math.floor(Date.now() / 1000) + 24 * 60 * 60,
+    }));
+    const { baseUrl, internalTokens } = await mount(oauth);
+
+    const res = await exchange(baseUrl, 'Bearer bevel-mcp_valid123');
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { token: string; expiresInMs: number };
+    // Same TTL constant createSession's loopback bearer uses — the grant
+    // above outlives it, so the constant is the cap that binds.
+    expect(body.expiresInMs).toBe(MCP_LOOPBACK_TOKEN_TTL_MS);
+    // The minted token verifies to the resolved user with the externalProxy
+    // flag — identical shape to the hosted session's loopback bearer.
+    expect(internalTokens.verify(body.token)).toEqual({ userId: 'user-5', externalProxy: true });
+    // …and the tool-auth verifier resolves it to source 'external', exactly
+    // how /api/agent/* will treat the local server.
+    const verify = createTokenVerifier(
+      { looksLikeExternalApiKey: () => false } as unknown as IExternalApiKeyService,
+      internalTokens,
+    );
+    await expect(verify(body.token)).resolves.toEqual({
+      ok: true,
+      auth: { source: 'external', userId: 'user-5', scope: 'write' },
+    });
+    expect((oauth as any).verifyAccessToken).toHaveBeenCalledWith('bevel-mcp_valid123');
+  });
+
+  /**
+   * The binding that keeps the exchange from OUTLIVING its grant: an access
+   * token with less life left than the loopback constant caps the minted
+   * token's TTL at that remainder — otherwise a nearly-expired OAuth grant
+   * would buy five more hours of internal-token access.
+   */
+  it('caps expiresInMs at the access token\'s remaining lifetime when that is shorter', async () => {
+    const remainingSeconds = 90;
+    const oauth = makeOAuthProvider(async () => ({
+      extra: { userId: 'user-5' },
+      expiresAt: Math.floor(Date.now() / 1000) + remainingSeconds,
+    }));
+    const { baseUrl, internalTokens } = await mount(oauth);
+
+    const res = await exchange(baseUrl, 'Bearer bevel-mcp_shortlived');
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { token: string; expiresInMs: number };
+    // The returned number is the ACTUAL lifetime: at most the remainder,
+    // and nowhere near the 5h constant. (A tolerance below, for the
+    // seconds-granularity of expiresAt and the time the request takes.)
+    expect(body.expiresInMs).toBeLessThanOrEqual(remainingSeconds * 1000);
+    expect(body.expiresInMs).toBeGreaterThan((remainingSeconds - 10) * 1000);
+    expect(internalTokens.verify(body.token)).toEqual({ userId: 'user-5', externalProxy: true });
+  });
+
+  /**
+   * A provider that reports no expiry (the AuthInfo field is optional) falls
+   * back to the constant alone — absence must not read as "expires now".
+   */
+  it('falls back to the loopback constant when the provider reports no expiresAt', async () => {
+    const oauth = makeOAuthProvider(async () => ({
+      extra: { userId: 'user-5' },
+    }));
+    const { baseUrl } = await mount(oauth);
+
+    const res = await exchange(baseUrl, 'Bearer bevel-mcp_noexpiry');
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { expiresInMs: number };
+    expect(body.expiresInMs).toBe(MCP_LOOPBACK_TOKEN_TTL_MS);
+  });
+
+  /**
+   * The other end of the lifetime binding: a grant the provider verifies but
+   * reports as ALREADY out of lifetime must be a 401, not a 200 carrying a
+   * token that is dead on arrival — the caller would read that as success and
+   * fail somewhere far from the cause.
+   */
+  it('401s — never 200 with a dead token — when the verified grant has no remaining lifetime', async () => {
+    const oauth = makeOAuthProvider(async () => ({
+      extra: { userId: 'user-5' },
+      expiresAt: Math.floor(Date.now() / 1000) - 60,
+    }));
+    const { baseUrl } = await mount(oauth);
+
+    const res = await exchange(baseUrl, 'Bearer bevel-mcp_outlived');
+
+    expect(res.status).toBe(401);
+    expect(res.headers.get('www-authenticate')).toContain(
+      `resource_metadata="${RESOURCE_METADATA_URL}"`,
+    );
+    await expect(res.json()).resolves.toEqual(
+      expect.objectContaining({ error: expect.stringMatching(/invalid|expired|revoked/i) }),
+    );
+  });
+
+  it('401s on a garbage (non-finite) expiresAt rather than minting with a NaN TTL', async () => {
+    const oauth = makeOAuthProvider(async () => ({
+      extra: { userId: 'user-5' },
+      expiresAt: Number.NaN,
+    }));
+    const { baseUrl } = await mount(oauth);
+
+    const res = await exchange(baseUrl, 'Bearer bevel-mcp_garbage-expiry');
+
+    expect(res.status).toBe(401);
+    expect(res.headers.get('www-authenticate')).toContain('resource_metadata=');
+  });
+
+  it('401s with the resource_metadata challenge on an expired/revoked OAuth token', async () => {
+    const { baseUrl } = await mount(makeOAuthProvider()); // default verify throws InvalidTokenError
+
+    const res = await exchange(baseUrl, 'Bearer bevel-mcp_expired');
+
+    expect(res.status).toBe(401);
+    expect(res.headers.get('www-authenticate')).toContain(
+      `resource_metadata="${RESOURCE_METADATA_URL}"`,
+    );
+    await expect(res.json()).resolves.toEqual(
+      expect.objectContaining({ error: expect.stringMatching(/invalid|expired|revoked/i) }),
+    );
+  });
+
+  it('500s — not 401s — when OAuth verification fails on a backend error', async () => {
+    const { baseUrl } = await mount(
+      makeOAuthProvider(async () => {
+        throw new Error('db down');
+      }),
+    );
+    const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const res = await exchange(baseUrl, 'Bearer bevel-mcp_token');
+
+    expect(res.status).toBe(500);
+    err.mockRestore();
+  });
+
+  it('403s a connection key — a key holder needs no exchange', async () => {
+    const { baseUrl } = await mount(makeOAuthProvider());
+
+    const res = await exchange(baseUrl, 'Bearer bevel_connectionkey');
+
+    expect(res.status).toBe(403);
+    await expect(res.json()).resolves.toEqual(
+      expect.objectContaining({ error: expect.stringMatching(/OAuth access tokens only/i) }),
+    );
+  });
+
+  it('403s a JWT', async () => {
+    const { baseUrl } = await mount(makeOAuthProvider());
+
+    const res = await exchange(baseUrl, 'Bearer eyJhbGciOiJIUzI1NiJ9.payload.sig');
+
+    expect(res.status).toBe(403);
+    await expect(res.json()).resolves.toEqual(
+      expect.objectContaining({ error: expect.stringMatching(/OAuth access tokens only/i) }),
+    );
+  });
+
+  it('403s an internal token — it IS the exchange output, never its input', async () => {
+    const { baseUrl, internalTokens } = await mount(makeOAuthProvider());
+
+    const res = await exchange(baseUrl, `Bearer ${internalTokens.mint({ userId: 'user-A' })}`);
+
+    expect(res.status).toBe(403);
+  });
+
+  it('401s with the challenge when the Authorization header is missing', async () => {
+    const { baseUrl } = await mount(makeOAuthProvider());
+
+    const res = await exchange(baseUrl);
+
+    expect(res.status).toBe(401);
+    expect(res.headers.get('www-authenticate')).toContain('resource_metadata=');
+  });
+
+  it('401s with the challenge on a garbage bearer token', async () => {
+    const { baseUrl } = await mount(makeOAuthProvider());
+
+    const res = await exchange(baseUrl, 'Bearer total-garbage');
+
+    expect(res.status).toBe(401);
+    expect(res.headers.get('www-authenticate')).toContain('resource_metadata=');
+  });
+
+  it('401s on a non-Bearer scheme', async () => {
+    const { baseUrl } = await mount(makeOAuthProvider());
+
+    const res = await exchange(baseUrl, 'Basic abc:123');
+
+    expect(res.status).toBe(401);
+  });
+});

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

@@ -2,6 +2,7 @@ import type { Request, Response, NextFunction } from 'express';
 import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import type { AuthService } from '../auth/auth.service.js';
 import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
+import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
 import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
 import '../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
 
@@ -13,7 +14,17 @@ import '../tool-auth/external-api-key.interface.js'; // Express Request augmenta
  *   2. An MCP OAuth access token (Bearer `bevel-mcp_…`) — issued by our own
  *      authorization server after the /connect consent flow, resolved via
  *      BevelOAuthProvider.
- *   3. A regular JWT — same shape the web app uses. Lets a logged-in user
+ *   3. An internal token (Bearer `<tenant>-int_…`) — minted server-side only
+ *      (createSession's loopback bearer, the /mcp/local-token exchange). The
+ *      local MCP server (hexis-mcp) exchanges its OAuth grant for one and
+ *      then uses it EVERYWHERE a connection key goes — the agent REST surface
+ *      already accepts it, and refusing it here made OAuth-mode hexis-mcp
+ *      fail at exactly one hop: registering this endpoint as its remote
+ *      manual. Accepting it adds no new mint path — only this server creates
+ *      them, always for an already-verified user. Only the `externalProxy`
+ *      shape is accepted: a plain in-process internal token is the loopback
+ *      surface's credential and must not double as an MCP caller.
+ *   4. A regular JWT — same shape the web app uses. Lets a logged-in user
  *      hit the MCP endpoint from their browser if we ever need it
  *      (e.g. an in-app debugger). Keeps the surface from forking.
  *
@@ -30,6 +41,7 @@ export function createMcpAuthMiddleware(
   externalApiKeyService: IExternalApiKeyService,
   oauthProvider: BevelOAuthProvider,
   resourceMetadataUrl: string,
+  internalTokens: InternalTokenService,
 ) {
   const wwwAuthenticate = `Bearer realm="bevel-mcp", resource_metadata="${resourceMetadataUrl}"`;
   const unauthorized = (res: Response, error: string) => {
@@ -111,6 +123,54 @@ export function createMcpAuthMiddleware(
       return;
     }
 
+    // Internal token — server-minted, shape-routed like the branches above so
+    // it never reaches jsonwebtoken. `verify` returns null for invalid or
+    // expired ones (a clean 401); the user row is loaded so `req.userEmail`
+    // carries the same truth every other branch provides — the tool handlers
+    // downstream resolve access against it.
+    //
+    // ONLY the `externalProxy` shape is admitted: that claim marks the
+    // loopback identity of an external caller (createSession's session
+    // bearer, the /mcp/local-token exchange), which is the one internal-token
+    // kind that has any business arriving here as an MCP client. A plain
+    // in-process internal token — the per-run credential the agent factory
+    // mints for its own code-mode client — is a loopback-surface credential,
+    // and accepting it would let it open an MCP session (createSession would
+    // even mint it a fresh externalProxy bearer, upgrading it).
+    if (internalTokens.looksLikeInternalToken(token)) {
+      // `verify` answers null for the invalid/expired cases it can see coming,
+      // but a malformed token of plausible shape can still THROW from inside
+      // it (e.g. `timingSafeEqual` on same-length strings whose byte lengths
+      // differ). That is the caller's bad token, not a backend failure — 401,
+      // never a 500 or an unhandled throw into the error handler.
+      let claim: ReturnType<InternalTokenService['verify']>;
+      try {
+        claim = internalTokens.verify(token);
+      } catch {
+        claim = null;
+      }
+      if (!claim || claim.externalProxy !== true) {
+        unauthorized(res, 'Invalid or expired internal token');
+        return;
+      }
+      let user;
+      try {
+        user = await authService.getUserById(claim.userId);
+      } catch (err) {
+        console.error('[mcp-auth] internal-token user lookup failed:', err);
+        res.status(500).json({ error: 'Authentication backend unavailable' });
+        return;
+      }
+      if (!user) {
+        unauthorized(res, 'Invalid or expired internal token');
+        return;
+      }
+      req.userId = user.id;
+      req.userEmail = user.email;
+      next();
+      return;
+    }
+
     // JWT path — same logic as `createAuthMiddleware` in modules/auth, kept
     // duplicated rather than imported because that one writes its own 401
     // body shape and we want the WWW-Authenticate header set.

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

@@ -1,5 +1,6 @@
 import express, { type Request, type RequestHandler } from 'express';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import {
@@ -8,7 +9,9 @@ import {
   TokenStillActiveError,
 } from '../tool-auth/external-api-key.errors.js';
 import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
-import type { McpService } from './mcp.service.js';
+import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
+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
 
@@ -37,10 +40,14 @@ function extractBearer(req: Request): string {
  *   POST   /mcp/external-api-keys         — mint a new key (returns plaintext ONCE)
  *   DELETE /mcp/external-api-keys/:id     — revoke
  *
+ *   POST   /mcp/local-token               — exchange an MCP OAuth access token
+ *                                           for a loopback internal token
+ *
  * The `/mcp` endpoints accept either a connection key or a JWT (see
  * McpAuthMiddleware). The `/mcp/external-api-keys/*` endpoints accept only the JWT —
  * minting/revoking via a connection key would let a leaked key roll itself
- * over and stay alive forever.
+ * over and stay alive forever. `/mcp/local-token` accepts ONLY an MCP OAuth
+ * access token — every other credential already opens the surface it bridges to.
  */
 export function createMcpRoutes(
   mcpService: McpService,
@@ -48,6 +55,11 @@ export function createMcpRoutes(
   mcpAuthMiddleware: RequestHandler,
   jwtAuthMiddleware: RequestHandler,
   llmUsageService: ILlmUsageMeter,
+  internalTokens: InternalTokenService,
+  oauthProvider: BevelOAuthProvider,
+  // RFC 9728 pointer carried on this router's own 401 challenges (the
+  // local-token exchange), same value McpAuthMiddleware advertises.
+  resourceMetadataUrl: string,
 ): express.Router {
   const router = express.Router();
 
@@ -259,5 +271,128 @@ export function createMcpRoutes(
     }
   });
 
+  // ── Local-server token exchange (OAuth-access-token-only) ──────────────
+
+  /**
+   * Exchange an MCP OAuth access token for a short-lived internal token.
+   *
+   * Why it exists: the LOCAL MCP server's REST reads — the all-tools manual,
+   * `list_local_tools`, the plugin archive — live on `/api/agent/*`, which
+   * accepts connection keys and internal tokens ONLY; an MCP OAuth access
+   * token deliberately 401s there. Hosted OAuth sessions cross that gap
+   * inside `McpService.createSession`, which mints a loopback internal token
+   * for the resolved user. This endpoint is the same exchange for an external
+   * caller: the one bridge that lets a local server configured via the
+   * deployment's MCP OAuth (instead of a connection key) reach those reads.
+   *
+   * Why it is NOT a widening of the trust boundary: the caller must present a
+   * VERIFIED OAuth grant for this exact user — the same credential that
+   * already drives full tool execution through the hosted `/mcp` endpoint.
+   * The minted token is identical in shape to createSession's loopback bearer
+   * (`{ userId, externalProxy: true }` → resolved as `source: 'external'` by
+   * the tool-auth verifier, admitted to the external surface, refused from
+   * internal-only tools) and carries the same TTL — CAPPED to the presented
+   * access token's remaining lifetime, so the exchange can never mint a
+   * credential that outlives its grant. Nothing becomes reachable that the
+   * grant did not already reach — only the credential's spelling changes.
+   *
+   * Auth semantics mirror McpAuthMiddleware's OAuth branch: an
+   * invalid/expired/revoked token is a 401 re-challenging with
+   * `resource_metadata` (RFC 9728) so the client can re-authorize; a backend
+   * failure during verification is a 500. A connection key, internal token,
+   * or JWT is a 403 — those credentials need no exchange, so accepting them
+   * here would only manufacture a second credential from a first.
+   *
+   * Response: `{ token, expiresInMs }`.
+   */
+  router.post('/mcp/local-token', async (req, res) => {
+    const wwwAuthenticate = `Bearer realm="bevel-mcp", resource_metadata="${resourceMetadataUrl}"`;
+    const unauthorized = (error: string) => {
+      res.setHeader('WWW-Authenticate', wwwAuthenticate);
+      res.status(401).json({ error });
+    };
+
+    const header = req.headers.authorization;
+    if (!header || !header.toLowerCase().startsWith('bearer ')) {
+      unauthorized('Missing or invalid Authorization header');
+      return;
+    }
+    const token = extractBearer(req);
+
+    if (!oauthProvider.looksLikeAccessToken(token)) {
+      // A recognizable non-OAuth credential gets an explicit 403: a
+      // connection key or internal token already opens `/api/agent/*`
+      // directly, and a JWT holder mints a connection key from the settings
+      // UI — none of them has anything to exchange.
+      if (
+        externalApiKeyService.looksLikeExternalApiKey(token) ||
+        internalTokens.looksLikeInternalToken(token) ||
+        token.startsWith('eyJ')
+      ) {
+        res.status(403).json({
+          error:
+            'This endpoint exchanges MCP OAuth access tokens only. Connection keys, ' +
+            'internal tokens, and JWTs need no exchange — use them directly.',
+        });
+        return;
+      }
+      // Unrecognizable bearer — re-challenge so an OAuth-capable client can
+      // discover the authorization server and obtain a real access token.
+      unauthorized('Invalid access token');
+      return;
+    }
+
+    try {
+      const info = await oauthProvider.verifyAccessToken(token);
+      const userId = String(info.extra?.userId ?? '');
+      if (!userId) {
+        unauthorized('Invalid access token');
+        return;
+      }
+      // The minted token must never OUTLIVE the grant that authorized it: an
+      // OAuth access token revoked-by-expiry would otherwise leave a live
+      // internal token behind for the rest of the loopback TTL. Bind the TTL
+      // to whichever ends first — the constant, or the access token's own
+      // remaining lifetime (AuthInfo.expiresAt is epoch SECONDS, optional; a
+      // provider that reports none falls back to the constant alone).
+      const grantRemainingMs =
+        typeof info.expiresAt === 'number' ? info.expiresAt * 1000 - Date.now() : undefined;
+      // A grant with no life left mints NOTHING: a 200 carrying an
+      // already-dead token would read as success to the caller, whose first
+      // real request then fails somewhere far from the cause. It is the same
+      // 401 an expired token gets from the verifier, challenge and all — and
+      // a non-finite expiresAt (a provider handing back garbage) is refused
+      // the same way rather than turned into a TTL. Deliberately STRICTER
+      // than the verifier at the boundary: AuthInfo floors the expiry to
+      // whole seconds, so a grant inside its final partial second computes
+      // as spent here even though the verifier (which compares the stored
+      // millisecond timestamp) just accepted it — but that sub-second
+      // remainder could only mint a token that is dead before its first use,
+      // and refusing it is exactly this guard's job.
+      if (grantRemainingMs !== undefined && !(Number.isFinite(grantRemainingMs) && grantRemainingMs > 0)) {
+        unauthorized('Invalid, expired, or revoked access token');
+        return;
+      }
+      const ttlMs =
+        grantRemainingMs === undefined
+          ? MCP_LOOPBACK_TOKEN_TTL_MS
+          : Math.min(MCP_LOOPBACK_TOKEN_TTL_MS, grantRemainingMs);
+      const minted = internalTokens.mint({ userId, externalProxy: true }, ttlMs);
+      // The ACTUAL lifetime, not the constant — the caller schedules its
+      // proactive renewal off this number.
+      res.json({ token: minted, expiresInMs: ttlMs });
+    } catch (err) {
+      // Same split as McpAuthMiddleware: a bad token is a clean 401 with the
+      // discovery challenge; a backend failure is a 500 — the credential may
+      // be fine, we just can't check it right now.
+      if (err instanceof InvalidTokenError) {
+        unauthorized('Invalid, expired, or revoked access token');
+      } else {
+        console.error('[mcp] local-token exchange failed:', err);
+        res.status(500).json({ error: 'Authentication backend unavailable' });
+      }
+    }
+  });
+
   return router;
 }

package/src/modules/mcp/mcp.service.ts

@@ -76,8 +76,13 @@ const LOOPBACK_TIMEOUT_MS = 15_000;
  * first thing to die under a session's normal lifecycle. A continuously-active
  * session CAN outlive it — its tool calls then fail at the loopback and the
  * client recovers by re-initializing, which mints a fresh token.
+ *
+ * Exported because `POST /api/mcp/local-token` (mcp.routes.ts) performs the
+ * same OAuth-access-token → internal-token exchange for the LOCAL MCP server,
+ * and must mint the exact same shape and lifetime — one constant, two
+ * consumers, so the two bridges can never drift apart.
  */
-const MCP_LOOPBACK_TOKEN_TTL_MS = 5 * 60 * 60 * 1000;
+export const MCP_LOOPBACK_TOKEN_TTL_MS = 5 * 60 * 60 * 1000;
 
 const callTemplateSerializer = new CallTemplateSerializer();