@lowdefy/server 6.1.0 → 7.1.0

package/src/initServer.test.mjs

@@ -0,0 +1,116 @@
+/*
+  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 { jest } from '@jest/globals';
+
+const calls = [];
+const info = jest.fn();
+const guards = { env: { BETTER_AUTH_URL: '^https://app\\.example\\.com$' } };
+
+const checkEnvironmentGuards = jest.fn(() => {
+  calls.push('checkEnvironmentGuards');
+});
+const captureException = jest.fn();
+const flush = jest.fn(async () => true);
+const sentry = { captureException, flush };
+const initSentryServer = jest.fn(async () => {
+  calls.push('initSentryServer');
+  return null;
+});
+const createApp = jest.fn();
+
+jest.unstable_mockModule('@lowdefy/node-utils/checkEnvironmentGuards.js', () => ({
+  default: checkEnvironmentGuards,
+}));
+jest.unstable_mockModule('../lib/server/sentry/initSentry.js', () => ({
+  default: initSentryServer,
+}));
+jest.unstable_mockModule('./app.js', () => {
+  calls.push('import app');
+  return { default: createApp };
+});
+jest.unstable_mockModule('../lib/server/log/createLogger.js', () => ({
+  default: () => ({ info }),
+}));
+jest.unstable_mockModule('../lib/build/config.js', () => ({
+  default: { environment: 'prod', environments: { prod: { guards } } },
+}));
+
+const { default: initServer } = await import('./initServer.js');
+
+// The app module is imported once and then cached, so find the run that imported it rather than
+// assuming this test runs first.
+test('initServer initialises Sentry and checks the guards before importing the app', async () => {
+  const result = await initServer();
+  const importIndex = calls.indexOf('import app');
+  expect(calls.slice(importIndex - 2, importIndex + 1)).toEqual([
+    'initSentryServer',
+    'checkEnvironmentGuards',
+    'import app',
+  ]);
+  expect(result.createApp).toBe(createApp);
+});
+
+test('initServer checks the current environment guards', async () => {
+  await initServer();
+  expect(checkEnvironmentGuards.mock.calls).toEqual([[{ name: 'prod', guards }]]);
+});
+
+test('initServer throws when the current environment guards fail', async () => {
+  checkEnvironmentGuards.mockImplementationOnce(() => {
+    throw new Error('Environment "prod" guards failed.');
+  });
+  await expect(initServer()).rejects.toThrow('Environment "prod" guards failed.');
+});
+
+test('initServer sends a guard failure to Sentry and flushes it before throwing', async () => {
+  const error = new Error('Environment "prod" guards failed.');
+  initSentryServer.mockResolvedValueOnce(sentry);
+  checkEnvironmentGuards.mockImplementationOnce(() => {
+    throw error;
+  });
+  await expect(initServer()).rejects.toBe(error);
+  expect(captureException.mock.calls).toEqual([[error]]);
+  expect(flush).toHaveBeenCalled();
+});
+
+test('initServer throws a guard failure without Sentry when Sentry was not started', async () => {
+  const error = new Error('Environment "prod" guards failed.');
+  checkEnvironmentGuards.mockImplementationOnce(() => {
+    throw error;
+  });
+  await expect(initServer()).rejects.toBe(error);
+  expect(captureException).not.toHaveBeenCalled();
+});
+
+test('initServer starts Sentry for a long-running server unless the entry is serverless', async () => {
+  await initServer();
+  await initServer({ serverless: true });
+  expect(initSentryServer.mock.calls).toEqual([[{ serverless: false }], [{ serverless: true }]]);
+});
+
+test('initServer logs that Sentry is enabled and returns its SDK when Sentry was started', async () => {
+  initSentryServer.mockResolvedValueOnce(sentry);
+  const result = await initServer();
+  expect(result.sentry).toBe(sentry);
+  expect(info.mock.calls).toEqual([['Sentry enabled: server']]);
+});
+
+test('initServer does not log Sentry when Sentry was not started', async () => {
+  const result = await initServer();
+  expect(result.sentry).toBe(null);
+  expect(info).not.toHaveBeenCalled();
+});

package/src/lib/getRequestPath.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.
+*/
+
+// The rest of the request path after basePath and prefix, still encoded: the
+// page matcher decodes each segment once, and Hono's c.req.path is partly
+// decoded, so it is taken from the request URL. path goes to the matcher as it
+// arrived; matchedPath is path with one trailing "/" removed, the form the
+// client compares its navigations with.
+function getRequestPath({ c, basePath, prefix }) {
+  const pathname = new URL(c.req.url).pathname.slice(basePath.length);
+  const path = pathname.startsWith(prefix) ? pathname.slice(prefix.length) : '';
+  const matchedPath = path.endsWith('/') ? path.slice(0, -1) : path;
+  return { path, matchedPath };
+}
+
+export default getRequestPath;

package/src/middleware/apiContext.js

@@ -15,7 +15,14 @@
 */
 
 import path from 'node:path';
-import { createApiContext } from '@lowdefy/api';
+import {
+  createApiContext,
+  createRequestSignal,
+  ensureMcpOauthResource,
+  resolveAuthentication,
+  resolvePinnedOrganization,
+  resolveTenantPreflight,
+} from '@lowdefy/api';
 import { getSecretsFromEnv } from '@lowdefy/node-utils';
 import { v4 as uuid } from 'uuid';
 
@@ -23,11 +30,13 @@ import agents from '../../build/plugins/agents.js';
 import appMeta from '../../lib/build/appMeta.js';
 import config from '../../lib/build/config.js';
 import connections from '../../build/plugins/connections.js';
+import captureSentryError from '../../lib/server/sentry/captureSentryError.js';
 import createHandleError from '../../lib/server/log/createHandleError.js';
 import createLogger from '../../lib/server/log/createLogger.js';
 import fileCache from '../../lib/server/fileCache.js';
-import getSession from '../../lib/server/auth/session.js';
-import getStrategyCaller from '../../lib/server/auth/strategies.js';
+import getAuth from '../../lib/server/auth/getAuth.js';
+import getClientAddress from '../../lib/server/getClientAddress.js';
+import getStrategies from '../../lib/server/auth/getStrategies.js';
 import i18nConfig from '../../lib/build/i18n.js';
 import jsMap from '../../build/plugins/operators/serverJsMap.js';
 import logRequest from '../../lib/server/log/logRequest.js';
@@ -39,6 +48,7 @@ import notifications, {
 } from '../../build/plugins/notifications.js';
 import operators from '../../build/plugins/operators/server.js';
 import setSentryUser from '../../lib/server/sentry/setSentryUser.js';
+import steps from '../../build/plugins/steps.js';
 import websockets from '../../build/plugins/websockets.js';
 
 const secrets = getSecretsFromEnv();
@@ -56,11 +66,19 @@ function getRequestId(c) {
   return uuid();
 }
 
+// The MCP route authenticates by access token alone - the mcp option switches
+// resolveAuthentication onto its bearer branch, so it is set only for the MCP
+// path. Every other path leaves it false and authentication behaves as before.
+function isMcpPath(path) {
+  return path.endsWith('/api/mcp');
+}
+
 // Replaces lib/server/apiWrapper.js. Builds the request context consumed by
 // @lowdefy/api functions. Errors thrown by handlers are routed by Hono to the
 // app-level error handler (src/middleware/errorHandler.js), which reads this
-// context back from the Hono context.
-function apiContext() {
+// context back from the Hono context. clientAddressHeader is set by a platform
+// entry whose edge supplies the client address (see getClientAddress).
+function apiContext({ clientAddressHeader } = {}) {
   return async function apiContextMiddleware(c, next) {
     // The page-route mount ('/*') also matches /api/* paths that already
     // built a context — never build twice for one request.
@@ -95,6 +113,13 @@ function apiContext() {
       },
       scrubSecrets,
       secrets,
+      // Aborts when the client disconnects before the response is sent, or when the
+      // request timeout (src/middleware/requestTimeout.js) answers first.
+      signal: createRequestSignal({
+        clientSignal: c.req.raw.signal,
+        timeoutSignal: c.get('requestTimeoutSignal'),
+      }),
+      steps,
       // On Vercel (fluid compute) the platform request context keeps the
       // invocation alive until waitUntil promises settle; on long-lived hosts
       // the lookup resolves to nothing and background promises just run.
@@ -103,21 +128,48 @@ function apiContext() {
       websockets,
     };
     context.handleError = createHandleError({ context });
+    // Resolved once per request: the auth route hands it to BetterAuth, and the
+    // request log records it.
+    context.clientAddress = getClientAddress({
+      c,
+      clientAddressHeader,
+      logger: context.logger,
+    });
+    // Hoisted once per request - resolveAuthentication also needs it, and
+    // getBetterAuth memoizes the instance, but this keeps the auth engine
+    // construction to a single call site per request.
+    context.auth = getAuth({ logger: context.logger });
+    // The engine is constructed lazily on the first request, which would
+    // otherwise race the startup pinned-org ensure - await the memoized
+    // resolve so createApiContext reads a retained binding.
+    await resolvePinnedOrganization({ auth: context.auth, logger: context.logger });
+    // The one oauthResource row the MCP token audience validates against -
+    // ensured once per process, memoized like the pinned resolve above; a
+    // failure retries on the next request. No-op when the app is not an
+    // authorization server.
+    await ensureMcpOauthResource({ auth: context.auth, logger: context.logger });
     if (!c.req.path.includes('/api/auth')) {
-      context.session = await getSession(c);
-      if (!context.session?.user) {
-        const caller = await getStrategyCaller(c, context.logger);
-        if (caller) {
-          context.session = { user: caller };
-        }
-      }
+      // resolveAuthentication is the single writer of context.user.
+      await resolveAuthentication(context, {
+        auth: context.auth,
+        headers: c.req.raw.headers,
+        strategies: getStrategies({ logger: context.logger }),
+        mcp: isMcpPath(c.req.path),
+      });
       // Set Sentry user context for authenticated requests
       setSentryUser({
-        user: context.session?.user,
+        user: context.user,
         sentryConfig: loggerConfig.sentry,
       });
     }
     createApiContext(context);
+    // Under policy: tenant, report walled collections that hold unstamped rows
+    // (lazily-run-once, logged and captured once per offending collection). It
+    // never blocks or fails a request - a data fault must not take the app
+    // down - so it is started, not awaited. No-op under pinned.
+    void resolveTenantPreflight(context, {
+      captureError: (error) => captureSentryError({ error, context }),
+    });
     c.set('lowdefyContext', context);
     // Echo the request id so clients and proxies can quote it when reporting
     // a failure, and it can be matched to the rid on the server log lines.

package/src/middleware/apiContext.test.mjs

@@ -24,7 +24,18 @@ import { jest } from '@jest/globals';
 const secret = 'planted-apicontext-secret';
 process.env.LOWDEFY_SECRET_TEST = secret;
 
-jest.unstable_mockModule('@lowdefy/api', () => ({ createApiContext: jest.fn() }));
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  createApiContext: jest.fn(),
+  createRequestSignal: jest.fn(({ clientSignal, timeoutSignal }) =>
+    AbortSignal.any([clientSignal, timeoutSignal].filter(Boolean))
+  ),
+  // Returns what the server passes, so the test reads the auth-hook system context inputs.
+  createSystemContext: jest.fn((options) => options),
+  ensureMcpOauthResource: jest.fn(async () => {}),
+  resolveAuthentication: jest.fn(async () => {}),
+  resolvePinnedOrganization: jest.fn(async () => {}),
+  resolveTenantPreflight: jest.fn(async () => {}),
+}));
 jest.unstable_mockModule('../../lib/build/appMeta.js', () => ({ default: {} }));
 jest.unstable_mockModule('../../lib/build/config.js', () => ({ default: {} }));
 jest.unstable_mockModule('../../lib/build/i18n.js', () => ({ default: {} }));
@@ -33,14 +44,19 @@ jest.unstable_mockModule('../../lib/server/log/createHandleError.js', () => ({
   default: jest.fn(() => jest.fn()),
 }));
 jest.unstable_mockModule('../../lib/server/log/createLogger.js', () => ({
-  default: jest.fn(() => ({ debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() })),
+  default: jest.fn(() => ({
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+  })),
 }));
 jest.unstable_mockModule('../../lib/server/fileCache.js', () => ({ default: {} }));
-jest.unstable_mockModule('../../lib/server/auth/session.js', () => ({
-  default: jest.fn(async () => undefined),
+jest.unstable_mockModule('../../lib/server/auth/getAuth.js', () => ({
+  default: jest.fn(() => null),
 }));
-jest.unstable_mockModule('../../lib/server/auth/strategies.js', () => ({
-  default: jest.fn(async () => null),
+jest.unstable_mockModule('../../lib/server/auth/getStrategies.js', () => ({
+  default: jest.fn(() => null),
 }));
 jest.unstable_mockModule('../../lib/server/log/logRequest.js', () => ({ default: jest.fn() }));
 jest.unstable_mockModule('../../lib/server/sentry/setSentryUser.js', () => ({
@@ -62,6 +78,7 @@ const fixtures = [
   },
   { file: path.join('operators', 'server.js'), content: 'export default {};\n' },
   { file: path.join('operators', 'serverJsMap.js'), content: 'export default {};\n' },
+  { file: 'steps.js', content: 'export default {};\n' },
   { file: 'websockets.js', content: 'export default {};\n' },
 ].map(({ file, content }) => ({ absolutePath: path.join(pluginsDir, file), content }));
 
@@ -89,6 +106,10 @@ afterAll(() => {
 });
 
 const { default: apiContext } = await import('./apiContext.js');
+const { default: requestTimeout } = await import('./requestTimeout.js');
+const { default: createSystemContext } = await import(
+  '../../lib/server/auth/createSystemContext.js'
+);
 
 function createApp() {
   const app = new Hono();
@@ -116,3 +137,42 @@ test('apiContext scrubSecrets redacts a planted secret', async () => {
   const body = await res.json();
   expect(body.scrubbed).toEqual('token [REDACTED] end');
 });
+
+test('the auth-hook system context is built with mode prod and a scrubSecrets that redacts', () => {
+  const context = createSystemContext({ auth: null });
+  expect(context.mode).toEqual('prod');
+  expect(context.scrubSecrets(`token ${secret} end`)).toEqual('token [REDACTED] end');
+});
+
+test('the request timeout answers 504 and cancels the work the request left running', async () => {
+  const app = new Hono();
+  app.use('*', requestTimeout({ timeoutMs: 20 }));
+  app.use('*', apiContext());
+  let reason;
+  app.get('/api/slow', async (c) => {
+    const { signal } = c.get('lowdefyContext');
+    reason = await new Promise((resolve) => {
+      signal.addEventListener('abort', () => resolve(signal.reason), { once: true });
+    });
+    return c.json({ finished: true });
+  });
+  const res = await app.request('/api/slow');
+  expect(res.status).toEqual(504);
+  expect(reason.name).toEqual('TimeoutError');
+  expect(reason.message).toEqual('The request timeout of 20ms was exceeded.');
+});
+
+test('a request that answers within the timeout leaves its signal unaborted', async () => {
+  const app = new Hono();
+  app.use('*', requestTimeout({ timeoutMs: 20 }));
+  app.use('*', apiContext());
+  let signal;
+  app.get('/api/fast', (c) => {
+    signal = c.get('lowdefyContext').signal;
+    return c.json({ finished: true });
+  });
+  const res = await app.request('/api/fast');
+  expect(res.status).toEqual(200);
+  await new Promise((resolve) => setTimeout(resolve, 40));
+  expect(signal.aborted).toBe(false);
+});

package/src/middleware/createSameOriginGuard.js

@@ -0,0 +1,36 @@
+/*
+  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 { isSameOriginRequest } from '@lowdefy/api';
+
+// The cross-site defence for /api/client-error, which only this app's own
+// pages call. The rule itself - Sec-Fetch-Site, then Origin against Host - is
+// isSameOriginRequest in @lowdefy/api, which every server shares. Unlike a
+// websocket handshake, a fetch can carry X-Forwarded-Host where a CORS
+// preflight allows it, so HTTP routes compare the Origin with Host only.
+function createSameOriginGuard({ allowNoOrigin = false } = {}) {
+  // Returns the 403 response to answer with, or null when the request may
+  // proceed. A guard, not Hono middleware, so a route keeps one entry point
+  // and the refusal is visible at the top of the handler that owns it.
+  return function guardSameOrigin(c) {
+    if (isSameOriginRequest({ getHeader: (name) => c.req.header(name), allowNoOrigin })) {
+      return null;
+    }
+    return c.json({ error: 'Forbidden' }, 403);
+  };
+}
+
+export default createSameOriginGuard;

package/src/middleware/createSameOriginGuard.test.mjs

@@ -0,0 +1,102 @@
+/*
+  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 createSameOriginGuard from './createSameOriginGuard.js';
+
+function createApp({ allowNoOrigin } = {}) {
+  const guardSameOrigin = createSameOriginGuard({ allowNoOrigin });
+  const app = new Hono();
+  app.all('/post', (c) => {
+    const forbidden = guardSameOrigin(c);
+    if (forbidden) {
+      return forbidden;
+    }
+    return c.json({ allowed: true });
+  });
+  return app;
+}
+
+function post({ allowNoOrigin, headers }) {
+  return createApp({ allowNoOrigin }).request('/post', { headers, method: 'POST' });
+}
+
+test.each([
+  ['origin matches the host', { host: 'app.test', origin: 'https://app.test' }],
+  [
+    'sec-fetch-site says same-origin',
+    { host: 'app.test', origin: 'https://app.test', 'sec-fetch-site': 'same-origin' },
+  ],
+  [
+    'sec-fetch-site says none',
+    { host: 'app.test', origin: 'https://app.test', 'sec-fetch-site': 'none' },
+  ],
+  [
+    'the origin carries a port matching the host',
+    { host: 'app.test:3000', origin: 'http://app.test:3000' },
+  ],
+])('the guard allows a post when %s', async (_, headers) => {
+  const res = await post({ headers });
+
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({ allowed: true });
+});
+
+test.each([
+  ['the origin is another site', { host: 'app.test', origin: 'https://evil.test' }],
+  ['the origin is a sibling subdomain', { host: 'app.test', origin: 'https://other.app.test' }],
+  ['the origin is not a url', { host: 'app.test', origin: 'not a url' }],
+  [
+    'sec-fetch-site says cross-site',
+    { host: 'app.test', origin: 'https://app.test', 'sec-fetch-site': 'cross-site' },
+  ],
+  [
+    'sec-fetch-site says same-site',
+    { host: 'app.test', origin: 'https://app.test', 'sec-fetch-site': 'same-site' },
+  ],
+  ['there is no origin', { host: 'app.test' }],
+])('the guard answers 403 when %s', async (_, headers) => {
+  const res = await post({ headers });
+
+  expect(res.status).toEqual(403);
+  expect(await res.json()).toEqual({ error: 'Forbidden' });
+});
+
+test('the guard lets a caller that sends no origin through when the route allows it', async () => {
+  const res = await post({ allowNoOrigin: true, headers: { host: 'app.test' } });
+
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({ allowed: true });
+});
+
+test('allowNoOrigin does not excuse a browser posting cross-site', async () => {
+  const res = await post({
+    allowNoOrigin: true,
+    headers: { host: 'app.test', origin: 'https://evil.test' },
+  });
+
+  expect(res.status).toEqual(403);
+});
+
+test('allowNoOrigin does not excuse a cross-site sec-fetch-site with no origin', async () => {
+  const res = await post({
+    allowNoOrigin: true,
+    headers: { host: 'app.test', 'sec-fetch-site': 'cross-site' },
+  });
+
+  expect(res.status).toEqual(403);
+});

package/src/middleware/errorHandler.js

@@ -14,8 +14,10 @@
   limitations under the License.
 */
 
-import * as Sentry from '@sentry/node';
 import { redactErrorResponse } from '@lowdefy/api';
+import { HTTPException } from 'hono/http-exception';
+
+import sentrySdk from '../../lib/server/sentry/sentrySdk.js';
 
 // Hono routes every handler error to the app-level error handler — upstream
 // middleware try/catch never sees them (compose catches per dispatch level).
@@ -35,14 +37,64 @@ function createErrorHandler({ basePath = '', logger }) {
       }
       return c.text('Unauthorized', 401);
     }
+    // An authenticated caller whose roles do not permit the resource. Expected
+    // traffic, not a fault: one warning line, no structured error log and no
+    // Sentry capture.
+    if (error.name === 'AuthorizationError') {
+      logger.warn(`Forbidden: ${c.req.method} ${c.req.path}`);
+      if (path.startsWith('/api/')) {
+        return c.json({ name: error.name, message: error.message }, 403);
+      }
+      return c.text('Forbidden', 403);
+    }
+    // An authorized caller who has not enrolled a second factor under
+    // auth.twoFactor.required. 403, not 401 - a 401 reads to the client as a dead
+    // session and bounces the user to sign-in, which is the loop the gate exists to
+    // avoid. Expected traffic under required: true, so one warning line and no
+    // Sentry capture, exactly as for AuthenticationError.
+    if (error.name === 'TwoFactorEnrolmentRequiredError') {
+      logger.warn(`Two-factor enrolment required: ${c.req.method} ${c.req.path}`);
+      if (path.startsWith('/api/')) {
+        return c.json({ name: error.name, message: error.message }, 403);
+      }
+      return c.text('Two-factor enrolment required', 403);
+    }
+    // An API client whose payload does not match the endpoint's declared
+    // payloadSchema (or any other UserError raised before a routine starts). A
+    // page's CallAPI payload the schema refuses is a ConfigError instead: the
+    // page's own config built it (validatePayload). The caller's own
+    // request is wrong, not the config or the server: a 400 with the message the
+    // caller needs, one warning line, no structured error log and no Sentry
+    // capture. A UserError raised inside a routine never gets here - it returns
+    // 200 with success: false through buildEndpointResult.
+    if (error.name === 'UserError') {
+      logger.warn(`Bad request: ${c.req.method} ${c.req.path} - ${error.message}`);
+      if (path.startsWith('/api/')) {
+        return c.json({ name: error.name, message: error.message }, 400);
+      }
+      return c.text('Bad Request', 400);
+    }
+    // A route or transport that has already decided its own HTTP answer - hono's
+    // HTTPException carries the response to send. The MCP transport refuses an
+    // unsupported protocol-version header this way (a 404 with a JSON-RPC body
+    // that the client SDK falls back on to negotiate a version both sides
+    // know). Not a fault: send its response and log one warning line, no
+    // structured error log and no Sentry capture. Turning it into a 500 would
+    // hide the status the client acts on.
+    if (error instanceof HTTPException) {
+      logger.warn(`${error.status} answered by the route: ${c.req.method} ${c.req.path}`);
+      return error.getResponse();
+    }
     const context = c.get('lowdefyContext');
     if (context) {
+      // context.handleError already captures to Sentry (createHandleError ->
+      // captureSentryError), so capturing here too would report the fault twice.
       await context.handleError(error);
     } else {
       logger.error(error);
-    }
-    if (process.env.SENTRY_DSN) {
-      Sentry.captureException(error);
+      if (sentrySdk.current) {
+        sentrySdk.current.captureException(error);
+      }
     }
     if (path.startsWith('/api/')) {
       return c.json(redactErrorResponse(context, error), 500);