@lowdefy/server 6.0.0 → 7.0.0

package/src/routes/mcpMemberToken.test.mjs

@@ -0,0 +1,125 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+// The real URI helpers drive the challenge strings, so the header assertions
+// below exercise the actual BETTER_AUTH_URL derivation - only createMcpServer
+// is stubbed out.
+const uriHelpers = await import('@lowdefy/api/routes/mcp/getMcpUri.js');
+
+const mockCreateMcpServer = jest.fn();
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  ...uriHelpers,
+  createMcpServer: mockCreateMcpServer,
+}));
+
+jest.unstable_mockModule('@hono/mcp', () => ({
+  StreamableHTTPTransport: class {
+    handleRequest() {
+      return new Response(JSON.stringify({ served: true }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+  },
+}));
+
+const mockAuthJson = { configured: true, oauthProvider: { consentPage: '/oauth/consent' } };
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({
+  default: mockAuthJson,
+}));
+
+const { default: mcpHandler } = await import('./mcp.js');
+
+const originalBetterAuthUrl = process.env.BETTER_AUTH_URL;
+
+const mockReadConfigFile = jest.fn();
+
+let contextOverrides;
+
+function createApp() {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', {
+      config: { basePath: '' },
+      logger: { debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() },
+      readConfigFile: mockReadConfigFile,
+      ...contextOverrides,
+    });
+    await next();
+  });
+  app.all('/api/mcp', mcpHandler);
+  return app;
+}
+
+beforeEach(() => {
+  process.env.BETTER_AUTH_URL = 'https://app.test.com';
+  mockAuthJson.oauthProvider = { consentPage: '/oauth/consent' };
+  contextOverrides = {};
+  mockReadConfigFile.mockReset();
+  mockCreateMcpServer.mockReset();
+  mockCreateMcpServer.mockResolvedValue({ connect: jest.fn() });
+  mockReadConfigFile.mockResolvedValue({ configured: true, hasPublicTool: true, endpoints: [] });
+});
+
+afterAll(() => {
+  if (originalBetterAuthUrl === undefined) {
+    delete process.env.BETTER_AUTH_URL;
+  } else {
+    process.env.BETTER_AUTH_URL = originalBetterAuthUrl;
+  }
+});
+
+test('mcpHandler answers a refused member token with its reason and no resource metadata', async () => {
+  contextOverrides.mcpAuth = {
+    tokenStatus: 'invalid',
+    memberToken: true,
+    description: 'This token has expired.',
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer error="invalid_token", error_description="This token has expired."'
+  );
+  expect(mockCreateMcpServer).not.toHaveBeenCalled();
+});
+
+test('mcpHandler answers a member token whose member is gone with that reason', async () => {
+  contextOverrides.mcpAuth = {
+    tokenStatus: 'invalid',
+    memberToken: true,
+    description: "This token's member can no longer use it.",
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(401);
+  expect(res.headers.get('WWW-Authenticate')).toEqual(
+    'Bearer error="invalid_token", error_description="This token\'s member can no longer use it."'
+  );
+});
+
+test('mcpHandler serves a valid member token caller', async () => {
+  contextOverrides.mcpAuth = {
+    tokenStatus: 'valid',
+    tokenId: 'token_1',
+    organizationId: 'org_1',
+    grantedScopes: ['mcp:read', 'mcp:write'],
+  };
+  const res = await createApp().request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(200);
+  expect(mockCreateMcpServer).toHaveBeenCalledTimes(1);
+});

package/src/routes/mcpProtectedResourceMetadata.js

@@ -0,0 +1,34 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { getAsIssuer, getMcpResourceUri, MCP_OAUTH_SCOPES } from '@lowdefy/api';
+
+import lowdefyConfig from '../../lib/build/config.js';
+
+// RFC 9728 protected-resource metadata for the MCP endpoint. Constant per
+// deployment: the URIs derive from the pinned BETTER_AUTH_URL, never a Host
+// header. The organization a token acts in is not part of the resource - it is
+// chosen at authorization and carried as a token claim.
+function mcpProtectedResourceMetadataHandler(c) {
+  return c.json({
+    resource: getMcpResourceUri({ config: lowdefyConfig }),
+    authorization_servers: [getAsIssuer({ config: lowdefyConfig })],
+    scopes_supported: MCP_OAUTH_SCOPES,
+    bearer_methods_supported: ['header'],
+  });
+}
+
+export default mcpProtectedResourceMetadataHandler;

package/src/routes/mcpProtectedResourceMetadata.test.mjs

@@ -0,0 +1,65 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+jest.unstable_mockModule('../../lib/build/config.js', () => ({
+  default: { basePath: '' },
+}));
+
+const { default: mcpProtectedResourceMetadataHandler } = await import(
+  './mcpProtectedResourceMetadata.js'
+);
+
+const originalBetterAuthUrl = process.env.BETTER_AUTH_URL;
+
+function createApp() {
+  const app = new Hono();
+  app.get('/.well-known/oauth-protected-resource/api/mcp', mcpProtectedResourceMetadataHandler);
+  return app;
+}
+
+beforeEach(() => {
+  process.env.BETTER_AUTH_URL = 'https://app.test.com';
+});
+
+afterAll(() => {
+  if (originalBetterAuthUrl === undefined) {
+    delete process.env.BETTER_AUTH_URL;
+  } else {
+    process.env.BETTER_AUTH_URL = originalBetterAuthUrl;
+  }
+});
+
+test('metadata handler serves the single MCP resource document', async () => {
+  const res = await createApp().request('/.well-known/oauth-protected-resource/api/mcp');
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({
+    resource: 'https://app.test.com/api/mcp',
+    authorization_servers: ['https://app.test.com/api/auth'],
+    scopes_supported: ['mcp:read', 'mcp:write', 'offline_access'],
+    bearer_methods_supported: ['header'],
+  });
+});
+
+test('metadata handler derives the resource from BETTER_AUTH_URL, never the request host', async () => {
+  const res = await createApp().request(
+    'http://evil.example.com/.well-known/oauth-protected-resource/api/mcp'
+  );
+  expect(res.status).toEqual(200);
+  expect((await res.json()).resource).toEqual('https://app.test.com/api/mcp');
+});

package/src/routes/mountOauthDiscovery.js

@@ -0,0 +1,44 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { createAsMetadataHandler } from '@lowdefy/api';
+import { type } from '@lowdefy/helpers';
+
+import authJson from '../../lib/build/auth.js';
+import mcpProtectedResourceMetadataHandler from './mcpProtectedResourceMetadata.js';
+
+// OAuth discovery for the MCP resource. Both documents are public,
+// unauthenticated and constant per deployment, so they mount outside the api
+// context. Nothing mounts when the app is not an authorization server - the
+// build then guaranteed an all-public tool surface with nothing to discover.
+function mountOauthDiscovery({ app, auth }) {
+  if (type.isNone(authJson.oauthProvider)) {
+    return;
+  }
+  app.get('/.well-known/oauth-protected-resource/api/mcp', mcpProtectedResourceMetadataHandler);
+  // The auth instance is absent only in dev mock mode, which runs no auth
+  // engine - the static resource document above still serves there.
+  if (type.isNone(auth)) {
+    return;
+  }
+  // The oauth-provider serves its AS metadata relative to the auth mount, so
+  // the RFC 8414 path-inserted location a client derives from the issuer must
+  // be mounted here, re-exposing the same live document.
+  const asMetadataHandler = createAsMetadataHandler({ auth });
+  app.get('/.well-known/oauth-authorization-server/api/auth', (c) => asMetadataHandler(c.req.raw));
+}
+
+export default mountOauthDiscovery;

package/src/routes/mountOauthDiscovery.test.mjs

@@ -0,0 +1,79 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+const mockCreateAsMetadataHandler = jest.fn(
+  () => async () =>
+    new Response(JSON.stringify({ issuer: 'https://app.test.com/api/auth' }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    })
+);
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  createAsMetadataHandler: mockCreateAsMetadataHandler,
+}));
+
+jest.unstable_mockModule('./mcpProtectedResourceMetadata.js', () => ({
+  default: (c) => c.json({ resource: 'mcp' }),
+}));
+
+const mockAuthJson = { configured: true };
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({
+  default: mockAuthJson,
+}));
+
+const { default: mountOauthDiscovery } = await import('./mountOauthDiscovery.js');
+
+beforeEach(() => {
+  delete mockAuthJson.oauthProvider;
+});
+
+test('mountOauthDiscovery mounts nothing when oauthProvider is not configured', async () => {
+  const app = new Hono();
+  mountOauthDiscovery({ app, auth: { api: {} } });
+  const resourceRes = await app.request('/.well-known/oauth-protected-resource/api/mcp');
+  expect(resourceRes.status).toEqual(404);
+  const asRes = await app.request('/.well-known/oauth-authorization-server/api/auth');
+  expect(asRes.status).toEqual(404);
+  expect(mockCreateAsMetadataHandler).not.toHaveBeenCalled();
+});
+
+test('mountOauthDiscovery mounts both discovery documents when oauthProvider is configured', async () => {
+  mockAuthJson.oauthProvider = { consentPage: '/oauth/consent' };
+  const app = new Hono();
+  const auth = { api: {} };
+  mountOauthDiscovery({ app, auth });
+  const resourceRes = await app.request('/.well-known/oauth-protected-resource/api/mcp');
+  expect(resourceRes.status).toEqual(200);
+  expect(await resourceRes.json()).toEqual({ resource: 'mcp' });
+  const asRes = await app.request('/.well-known/oauth-authorization-server/api/auth');
+  expect(asRes.status).toEqual(200);
+  expect(await asRes.json()).toEqual({ issuer: 'https://app.test.com/api/auth' });
+  expect(mockCreateAsMetadataHandler).toHaveBeenCalledWith({ auth });
+});
+
+test('mountOauthDiscovery serves only the static resource document without an auth instance', async () => {
+  mockAuthJson.oauthProvider = { consentPage: '/oauth/consent' };
+  const app = new Hono();
+  mountOauthDiscovery({ app, auth: null });
+  const resourceRes = await app.request('/.well-known/oauth-protected-resource/api/mcp');
+  expect(resourceRes.status).toEqual(200);
+  const asRes = await app.request('/.well-known/oauth-authorization-server/api/auth');
+  expect(asRes.status).toEqual(404);
+  expect(mockCreateAsMetadataHandler).not.toHaveBeenCalled();
+});

package/src/routes/mountPageRoutes.js

@@ -0,0 +1,29 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import getRequestPath from '../lib/getRequestPath.js';
+
+// `/` (home) and `/404` are fixed routes ahead of the page matcher; every other
+// path renders the page it matches. `.*`, not `.+`: under a basePath,
+// `<basePath>/` arrives with an empty rest, and is the app root like
+// `<basePath>` itself.
+function mountPageRoutes({ app, basePath, renderPage }) {
+  app.get('/', (c) => renderPage(c, { path: '', matchedPath: '' }));
+  app.get('/404', (c) => renderPage(c, { path: '404', matchedPath: '404', status: 404 }));
+  app.get('/:rest{.*}', (c) => renderPage(c, getRequestPath({ c, basePath, prefix: '/' })));
+}
+
+export default mountPageRoutes;

package/src/routes/mountPageRoutes.test.mjs

@@ -0,0 +1,56 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+
+import mountPageRoutes from './mountPageRoutes.js';
+
+function request({ basePath, path }) {
+  const app = basePath === '' ? new Hono() : new Hono().basePath(basePath);
+  mountPageRoutes({
+    app,
+    basePath,
+    renderPage: (c, { path: pagePath, matchedPath, status = 200 }) =>
+      c.json({ path: pagePath, matchedPath }, status),
+  });
+  return app.request(path);
+}
+
+test.each([
+  ['', '/', '', ''],
+  ['/app', '/app', '', ''],
+  ['/app', '/app/', '', ''],
+  ['/app', '/app/invoices', 'invoices', 'invoices'],
+  ['', '/support/tickets/1234/', 'support/tickets/1234/', 'support/tickets/1234'],
+  ['', '/support/tickets/a%2Fb%20c', 'support/tickets/a%2Fb%20c', 'support/tickets/a%2Fb%20c'],
+  ['/app', '/app/tickets//1', 'tickets//1', 'tickets//1'],
+])(
+  'with basePath "%s", %s renders path "%s" matched as "%s"',
+  async (basePath, url, path, matchedPath) => {
+    const res = await request({ basePath, path: url });
+    expect(res.status).toEqual(200);
+    expect(await res.json()).toEqual({ path, matchedPath });
+  }
+);
+
+test.each([[''], ['/app']])(
+  'with basePath "%s", /404 is a fixed route with status 404',
+  async (basePath) => {
+    const res = await request({ basePath, path: `${basePath}/404` });
+    expect(res.status).toEqual(404);
+    expect(await res.json()).toEqual({ path: '404', matchedPath: '404' });
+  }
+);

package/src/routes/normalizeMcpProtocolVersionHeader.js

@@ -0,0 +1,46 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// Claude Code merges the protocol version it negotiated (mcp-protocol-version)
+// with a static MCP-Protocol-Version it sets on every request, and the Fetch
+// Headers constructor folds the two spellings of one header into a single
+// comma-joined value: "2025-11-25, 2025-11-25". @hono/mcp compares that raw
+// string against its supported list, so a client that agrees with the server
+// twice over is answered 404 "Unsupported protocol version" - which Claude Code
+// shows as "MCP endpoint not found". Collapsing a repeated value to the one
+// version it names is lossless; a header naming two DIFFERENT versions is left
+// for the transport to refuse. Runs before the transport reads the header: the
+// transport reads c.req.header(), which reads the raw request headers live.
+function normalizeMcpProtocolVersionHeader({ request }) {
+  const value = request.headers.get('mcp-protocol-version');
+  if (value === null || !value.includes(',')) {
+    return;
+  }
+  const versions = [
+    ...new Set(
+      value
+        .split(',')
+        .map((version) => version.trim())
+        .filter(Boolean)
+    ),
+  ];
+  if (versions.length !== 1) {
+    return;
+  }
+  request.headers.set('mcp-protocol-version', versions[0]);
+}
+
+export default normalizeMcpProtocolVersionHeader;

package/src/routes/normalizeMcpProtocolVersionHeader.test.mjs

@@ -0,0 +1,62 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+
+import normalizeMcpProtocolVersionHeader from './normalizeMcpProtocolVersionHeader.js';
+
+function createApp() {
+  const app = new Hono();
+  app.post('/api/mcp', (c) => {
+    normalizeMcpProtocolVersionHeader({ request: c.req.raw });
+    return c.json({ protocolVersion: c.req.header('mcp-protocol-version') ?? null });
+  });
+  return app;
+}
+
+async function send(headerValue) {
+  const headers = new Headers();
+  if (headerValue !== undefined) {
+    headers.set('mcp-protocol-version', headerValue);
+  }
+  const res = await createApp().request('/api/mcp', { method: 'POST', headers });
+  return (await res.json()).protocolVersion;
+}
+
+test('collapses a repeated protocol version to the single version it names', async () => {
+  expect(await send('2025-11-25, 2025-11-25')).toEqual('2025-11-25');
+});
+
+test('collapses the value the Fetch Headers constructor builds from both header spellings', async () => {
+  const headers = new Headers({
+    'mcp-protocol-version': '2025-11-25',
+    'MCP-Protocol-Version': '2025-11-25',
+  });
+  const res = await createApp().request('/api/mcp', { method: 'POST', headers });
+  expect((await res.json()).protocolVersion).toEqual('2025-11-25');
+});
+
+test('leaves a single protocol version untouched', async () => {
+  expect(await send('2025-06-18')).toEqual('2025-06-18');
+});
+
+test('leaves a header naming two different versions for the transport to refuse', async () => {
+  expect(await send('2025-11-25, 2025-06-18')).toEqual('2025-11-25, 2025-06-18');
+});
+
+test('leaves an absent header absent', async () => {
+  expect(await send(undefined)).toEqual(null);
+});

package/src/routes/request.js

@@ -14,13 +14,15 @@
   limitations under the License.
 */
 
-import { callRequest } from '@lowdefy/api';
+import { callRequest, parseRequestBody } from '@lowdefy/api';
 
 import getPathSegments from '../lib/getPathSegments.js';
 
 async function requestHandler(c) {
   if (c.req.method !== 'POST') {
-    throw new Error('Only POST requests are supported.');
+    // A wrong-method request is client-caused: answer 405 rather than raising a
+    // fault that would be logged at error level and answered with a 500.
+    return c.json({ error: 'Method not allowed.' }, 405);
   }
   const context = c.get('lowdefyContext');
   const segments = getPathSegments(c, '/api/request/');
@@ -29,7 +31,7 @@ async function requestHandler(c) {
   }
   const requestId = segments[segments.length - 1];
   const pageId = segments.slice(0, -1).join('/');
-  const { actionId, blockId, payload } = await c.req.json();
+  const { actionId, blockId, payload } = parseRequestBody({ text: await c.req.text() });
   context.logger.info({ event: 'call_request', pageId, requestId, blockId, actionId });
   const response = await callRequest(context, { blockId, pageId, payload, requestId });
   return c.json(response);