@lowdefy/server 6.0.0 → 7.0.0

package/src/middleware/requestTimeout.js

@@ -0,0 +1,38 @@
+/*
+  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 { HTTPException } from 'hono/http-exception';
+import { timeout } from 'hono/timeout';
+
+// Caps how long a request may run, and cancels the work it leaves behind. The 504 is
+// answered while the handler is still running; the TimeoutError on the request's
+// timeout signal (which apiContext folds into context.signal) cancels the upstream
+// calls the handler is waiting on, such as an AI provider call, instead of letting
+// them run, and bill, after the response has gone.
+function requestTimeout({ timeoutMs }) {
+  return function requestTimeoutMiddleware(c, next) {
+    const controller = new AbortController();
+    c.set('requestTimeoutSignal', controller.signal);
+    return timeout(timeoutMs, () => {
+      controller.abort(
+        new DOMException(`The request timeout of ${timeoutMs}ms was exceeded.`, 'TimeoutError')
+      );
+      return new HTTPException(504, { message: 'Gateway Timeout' });
+    })(c, next);
+  };
+}
+
+export default requestTimeout;

package/src/middleware/sentry.js

@@ -14,16 +14,24 @@
   limitations under the License.
 */
 
-import * as Sentry from '@sentry/node';
+import { bindCredentialScrub } from '@lowdefy/node-utils';
 
-// Replaces @sentry/nextjs route auto-instrumentation: every request becomes
-// an http.server transaction. Handler errors never propagate through
-// middleware in Hono — captureException happens in the app error handler.
+import sentrySdk from '../../lib/server/sentry/sentrySdk.js';
+
+// Every request becomes an http.server transaction when the server traces requests. Handler
+// errors never propagate through middleware in Hono — captureException happens in the app error
+// handler.
 function sentryMiddleware() {
   return async function sentry(c, next) {
-    if (!process.env.SENTRY_DSN) {
+    const Sentry = sentrySdk.current;
+    if (!Sentry) {
       return next();
     }
+    // The request's transaction is sent once the response is written, after its credential scope
+    // has ended, so the scope's scrub rides on the request's isolation scope to scrubEvent.
+    Sentry.getIsolationScope().setSDKProcessingMetadata({
+      scrubRequestCredentials: bindCredentialScrub(),
+    });
     return Sentry.startSpan({ name: `${c.req.method} ${c.req.path}`, op: 'http.server' }, () =>
       next()
     );

package/src/middleware/stampBuildId.js

@@ -0,0 +1,30 @@
+/*
+  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.
+*/
+
+// Stamps the server's build on auth responses. Auth calls are not refused on a
+// mismatch (they are Lowdefy's routes, not app config, and a session refetch on
+// window focus would reload away unsaved input); instead the client reloads
+// when an auth call fails and this header shows a newer build answered
+// (lib/client/auth/createFetchCheckingBuild.js). Set after next() so error responses
+// and the raw responses BetterAuth returns carry it too.
+function stampBuildId({ buildId }) {
+  return async function stampBuildIdMiddleware(c, next) {
+    await next();
+    c.header('x-lowdefy-build', buildId);
+  };
+}
+
+export default stampBuildId;

package/src/middleware/stampBuildId.test.mjs

@@ -0,0 +1,41 @@
+/*
+  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 stampBuildId from './stampBuildId.js';
+
+function createApp() {
+  const app = new Hono();
+  app.use('/api/auth/*', stampBuildId({ buildId: 'build-2' }));
+  app.get('/api/auth/ok', (c) => c.json({ ok: true }));
+  app.get('/api/auth/raw', () => new Response('not found', { status: 404 }));
+  app.get('/api/auth/throws', () => {
+    throw new Error('Auth failed.');
+  });
+  app.onError((error, c) => c.json({ message: error.message }, 500));
+  return app;
+}
+
+test.each([
+  ['/api/auth/ok', 200],
+  ['/api/auth/raw', 404],
+  ['/api/auth/throws', 500],
+])('stampBuildId sets x-lowdefy-build on %s (%i)', async (path, status) => {
+  const res = await createApp().request(path);
+  expect(res.status).toBe(status);
+  expect(res.headers.get('x-lowdefy-build')).toBe('build-2');
+});

package/src/middleware/stampCaller.js

@@ -0,0 +1,38 @@
+/*
+  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 { callerStamp } from '@lowdefy/helpers';
+
+// Stamps page, request and endpoint responses with the caller the server
+// answered as, in full (see callerStamp): user and organization, session, roles
+// there and every organization the person belongs to. The client compares it
+// with the caller it renders and reloads when the person, organization or
+// roles differ, so a tab never shows one caller's data or access after the
+// session moved on. Registered after apiContext, so the resolved caller is
+// always on the context here; set after next() so error responses carry it
+// too.
+function stampCaller() {
+  return async function stampCallerMiddleware(c, next) {
+    await next();
+    const context = c.get('lowdefyContext');
+    c.header(
+      'x-lowdefy-caller',
+      callerStamp({ user: context.user, authSession: context.authSession })
+    );
+  };
+}
+
+export default stampCaller;

package/src/middleware/stampCaller.test.mjs

@@ -0,0 +1,64 @@
+/*
+  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 stampCaller from './stampCaller.js';
+
+function createApp({ user, authSession }) {
+  const app = new Hono();
+  app.use('/api/*', async (c, next) => {
+    c.set('lowdefyContext', { user, authSession });
+    return next();
+  });
+  app.use('/api/request/*', stampCaller());
+  app.post('/api/request/page/ok', (c) => c.json({ ok: true }));
+  app.post('/api/request/page/throws', () => {
+    throw new Error('Request failed.');
+  });
+  app.onError((error, c) => c.json({ message: error.message }, 500));
+  return app;
+}
+
+test.each([
+  ['/api/request/page/ok', 200],
+  ['/api/request/page/throws', 500],
+])('stampCaller sets x-lowdefy-caller on %s (%i)', async (path, status) => {
+  const app = createApp({
+    user: { id: 'user_1', organization_id: 'org_1', roles: ['editor', 'admin'] },
+    authSession: { id: 'session_1', memberOrganizationIds: ['org_2', 'org_1'] },
+  });
+  const res = await app.request(path, { method: 'POST' });
+  expect(res.status).toBe(status);
+  // The fixed vector callerStamp's own tests pin, so server and client agree.
+  expect(res.headers.get('x-lowdefy-caller')).toBe(
+    '82e92667feb5824d; session=3a1d7b6848ba4816; roles=228d50a09b1b1e2b; memberships=476954726056d64d'
+  );
+});
+
+test('stampCaller names the caller and roles alone for a caller with no session', async () => {
+  const app = createApp({
+    user: { id: 'user_1', organization_id: 'org_1', roles: ['editor', 'admin'] },
+  });
+  const res = await app.request('/api/request/page/ok', { method: 'POST' });
+  expect(res.headers.get('x-lowdefy-caller')).toBe('82e92667feb5824d; roles=228d50a09b1b1e2b');
+});
+
+test('stampCaller sends an empty x-lowdefy-caller for an anonymous caller', async () => {
+  const app = createApp({ user: null });
+  const res = await app.request('/api/request/page/ok', { method: 'POST' });
+  expect(res.headers.get('x-lowdefy-caller')).toBe('');
+});

package/src/routes/agent.js

@@ -14,7 +14,7 @@
   limitations under the License.
 */
 
-import { callAgent } from '@lowdefy/api';
+import { callAgent, parseRequestBody } from '@lowdefy/api';
 import { translate, type } from '@lowdefy/helpers';
 
 import getPathSegments from '../lib/getPathSegments.js';
@@ -23,7 +23,9 @@ async function agentHandler(c) {
   const context = c.get('lowdefyContext');
   const t = (key, values) => translate({ key, values, i18n: context.i18n });
   if (c.req.method !== 'POST') {
-    throw new Error(t('agent.runtime.methodNotAllowed'));
+    // 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: t('agent.runtime.methodNotAllowed') }, 405);
   }
   const segments = getPathSegments(c, '/api/agent/');
   if (segments.length < 2) {
@@ -33,22 +35,32 @@ async function agentHandler(c) {
   const pageId = segments.slice(0, -1).join('/');
   context.logger.info({ event: 'call_agent', agentId, pageId });
   const { conversationId } = c.req.query();
-  const { messages, urlQuery, sharedState } = await c.req.json();
+  const { messages, pathParams, urlQuery, sharedState, sharedStateReadOnly } = parseRequestBody({
+    text: await c.req.text(),
+  });
   if (!Array.isArray(messages)) {
     return c.json({ error: t('agent.runtime.messagesMustBeArray') }, 400);
   }
   if (urlQuery != null && (typeof urlQuery !== 'object' || Array.isArray(urlQuery))) {
     return c.json({ error: t('agent.runtime.urlQueryMustBeObject') }, 400);
   }
+  if (pathParams != null && !type.isObject(pathParams)) {
+    return c.json({ error: t('agent.runtime.pathParamsMustBeObject') }, 400);
+  }
   if (sharedState != null && !type.isObject(sharedState)) {
     return c.json({ error: t('agent.runtime.sharedStateMustBeObject') }, 400);
   }
+  if (sharedStateReadOnly != null && !type.isBoolean(sharedStateReadOnly)) {
+    return c.json({ error: t('agent.runtime.sharedStateReadOnlyMustBeBoolean') }, 400);
+  }
   const { response: webResponse } = await callAgent(context, {
     agentId,
     pageId,
     messages,
     conversationId: conversationId ?? undefined,
     sharedState: sharedState ?? undefined,
+    sharedStateReadOnly: sharedStateReadOnly ?? undefined,
+    pathParams: pathParams ?? undefined,
     urlQuery: urlQuery ?? undefined,
   });
 

package/src/routes/apiPage.js

@@ -16,22 +16,67 @@
 
 import { getPageConfig } from '@lowdefy/api';
 
-import getPathSegments from '../lib/getPathSegments.js';
+import appMeta from '../../lib/build/appMeta.js';
+import authJson from '../../lib/build/auth.js';
+import lowdefyConfig from '../../lib/build/config.js';
+import getRequestPath from '../lib/getRequestPath.js';
 
-// Page config as JSON for client-side SPA navigation. The first page load is
-// served embedded in the HTML; subsequent navigations fetch from here.
+const basePath = lowdefyConfig.basePath ?? '';
+
+// Page config as JSON for client-side SPA navigation, by the page's path (for a
+// page without a path, its id). The first page load is served embedded in the
+// HTML; subsequent navigations fetch from here.
 async function apiPageHandler(c) {
   const context = c.get('lowdefyContext');
-  const pageId = getPathSegments(c, '/api/page/').join('/');
+  const { path, matchedPath } = getRequestPath({ c, basePath, prefix: '/api/page/' });
+  // The callbackUrl of the sign-in and enrolment redirects: the requested page,
+  // query included.
+  const callbackUrl = `${basePath}/${path}${new URL(c.req.url).search}`;
   // The client forwards its current query string on the fetch so Dynamic block
   // resolution sees the same urlQuery as an initial HTML load.
-  const pageConfig = await getPageConfig(context, { pageId, urlQuery: c.req.query() });
-  if (!pageConfig) {
-    context.logger.info({ event: 'api_page_not_found', pageId });
+  const result = await getPageConfig(context, { path, urlQuery: c.req.query() });
+  const { pageId, pathParams } = result;
+  if (result.status === 'unauthenticated') {
+    // The client follows this redirect with a full page load, so the login
+    // page can return to the requested page after sign-in.
+    context.logger.info({ event: 'api_page_unauthenticated', pageId, path });
+    return c.json(
+      {
+        redirect: `${basePath}${authJson.authPages.signIn}?callbackUrl=${encodeURIComponent(
+          callbackUrl
+        )}`,
+      },
+      401
+    );
+  }
+  if (result.status === 'enrol_required') {
+    // 403, not the 401 the signed-out branch above uses: a 401 is the client's
+    // dead-session signal and would bounce the user to sign-in, which is the loop
+    // the enrolment gate exists to avoid.
+    context.logger.info({ event: 'api_page_enrol_required', pageId, path });
+    return c.json(
+      {
+        redirect: `${basePath}${authJson.authPages.twoFactorEnrol}?callbackUrl=${encodeURIComponent(
+          callbackUrl
+        )}`,
+      },
+      403
+    );
+  }
+  if (result.status !== 'ok') {
+    context.logger.info({ event: 'api_page_not_found', pageId, path });
     return c.json({ pageConfig: null }, 404);
   }
-  context.logger.info({ event: 'api_page_view', pageId });
-  return c.json({ pageConfig });
+  context.logger.info({ event: 'api_page_view', pageId, path });
+  // buildId lets a tab that loaded its bundle from an earlier deploy notice
+  // that this config comes from a newer build and reload (client/Page.jsx).
+  return c.json({
+    buildId: appMeta.buildId,
+    pageId,
+    pathParams,
+    matchedPath,
+    pageConfig: result.pageConfig,
+  });
 }
 
 export default apiPageHandler;

package/src/routes/apiPage.test.mjs

@@ -0,0 +1,143 @@
+/*
+  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/appMeta.js', () => ({
+  default: { buildId: 'build-abc' },
+}));
+
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({
+  default: { authPages: { signIn: '/auth/login', twoFactorEnrol: '/two-factor-enrol' } },
+}));
+
+jest.unstable_mockModule('../../lib/build/config.js', () => ({
+  default: { basePath: '' },
+}));
+
+const { default: apiPageHandler } = await import('./apiPage.js');
+
+const routes = [
+  { pageId: 'home', path: 'home' },
+  { pageId: 'ticket', path: '{space}/tickets/{ticket_id}' },
+];
+
+const pages = {
+  home: { id: 'home' },
+  ticket: { id: 'ticket' },
+};
+
+function createApp({
+  outcome = 'allow',
+  pagesProtectedByDefault = false,
+  user = { id: 'u1' },
+} = {}) {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', {
+      authEnforcement: { pagesProtectedByDefault },
+      authorizeOutcome: () => outcome,
+      logger: { debug: jest.fn(), info: jest.fn(), error: jest.fn() },
+      readConfigFile: async (file) => {
+        if (file === 'routes.json') return routes;
+        return pages[file.slice('pages/'.length, -'.json'.length)] ?? null;
+      },
+      user,
+    });
+    await next();
+  });
+  app.get('/api/page/*', apiPageHandler);
+  return app;
+}
+
+test('apiPageHandler returns pageId, pathParams and matchedPath for a patterned page', async () => {
+  const res = await createApp().request('/api/page/support/tickets/1234');
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({
+    buildId: 'build-abc',
+    pageId: 'ticket',
+    pathParams: { space: 'support', ticket_id: '1234' },
+    matchedPath: 'support/tickets/1234',
+    pageConfig: { id: 'ticket' },
+  });
+});
+
+test('apiPageHandler decodes an encoded "/" in a value once and keeps matchedPath encoded', async () => {
+  const res = await createApp().request('/api/page/support/tickets/a%2Fb/');
+  const body = await res.json();
+  expect(body.pathParams).toEqual({ space: 'support', ticket_id: 'a/b' });
+  expect(body.matchedPath).toEqual('support/tickets/a%2Fb');
+});
+
+test('apiPageHandler serves a page without path at its id', async () => {
+  const res = await createApp().request('/api/page/home');
+  expect(res.status).toEqual(200);
+  expect(await res.json()).toEqual({
+    buildId: 'build-abc',
+    pageId: 'home',
+    pathParams: {},
+    matchedPath: 'home',
+    pageConfig: { id: 'home' },
+  });
+});
+
+test('apiPageHandler returns 404 when no page matches the path', async () => {
+  const res = await createApp().request('/api/page/support/tickets');
+  expect(res.status).toEqual(404);
+  expect(await res.json()).toEqual({ pageConfig: null });
+});
+
+test('apiPageHandler returns a 401 sign-in redirect with the path and query when no page matches under pagesProtectedByDefault', async () => {
+  const res = await createApp({ pagesProtectedByDefault: true, user: null }).request(
+    '/api/page/support/tickets?tab=2'
+  );
+  expect(res.status).toEqual(401);
+  expect(await res.json()).toEqual({
+    redirect: `/auth/login?callbackUrl=${encodeURIComponent('/support/tickets?tab=2')}`,
+  });
+});
+
+test('apiPageHandler unauthenticated redirect carries the request path and query on callbackUrl', async () => {
+  const res = await createApp({ outcome: 'deny', user: null }).request(
+    '/api/page/support/tickets/1234?tab=2'
+  );
+  expect(res.status).toEqual(401);
+  expect(await res.json()).toEqual({
+    redirect: `/auth/login?callbackUrl=${encodeURIComponent('/support/tickets/1234?tab=2')}`,
+  });
+});
+
+test('apiPageHandler enrol_required redirect carries the request query on callbackUrl', async () => {
+  const res = await createApp({ outcome: 'enrol_required' }).request('/api/page/home?id=123&tab=2');
+  expect(res.status).toEqual(403);
+  expect(await res.json()).toEqual({
+    redirect: `/two-factor-enrol?callbackUrl=${encodeURIComponent('/home?id=123&tab=2')}`,
+  });
+});
+
+test('apiPageHandler enrol_required redirect is path-only when the request has no query', async () => {
+  const res = await createApp({ outcome: 'enrol_required' }).request('/api/page/home');
+  expect(res.status).toEqual(403);
+  expect(await res.json()).toEqual({
+    redirect: `/two-factor-enrol?callbackUrl=${encodeURIComponent('/home')}`,
+  });
+});
+
+test('apiPageHandler returns 404 for a signed-in caller without access', async () => {
+  const res = await createApp({ outcome: 'deny' }).request('/api/page/home');
+  expect(res.status).toEqual(404);
+});

package/src/routes/auth.js

@@ -14,24 +14,30 @@
   limitations under the License.
 */
 
-import { authHandler } from '@hono/auth-js';
+import { handleAuthRequest } from '@lowdefy/api';
 
 import authJson from '../../lib/build/auth.js';
+import getAuth from '../../lib/server/auth/getAuth.js';
 
-// Replaces pages/api/auth/[...nextauth].js. Hono routes HEAD requests through
-// GET handlers, so the corporate-email pre-check branch must live inside the
-// middleware, before delegating to the Auth.js handler. See:
-// https://next-auth.js.org/tutorials/avoid-corporate-link-checking-email-provider
-function authMiddleware() {
-  const handler = authJson.configured === true ? authHandler() : null;
-  return async function auth(c, next) {
+// Mounts BetterAuth's Web Standard handler on /api/auth/*. Hono routes HEAD
+// requests through GET handlers, so HEAD short-circuits before the handler -
+// corporate email link-checkers pre-fetch magic-link and verification URLs
+// with HEAD, and letting those reach the handler would consume the one-time
+// token before the user clicks. The client address apiContext resolved is
+// handed to BetterAuth for its rate limits and session records.
+function authMiddleware({ logger }) {
+  return async function auth(c) {
     if (authJson.configured !== true) {
       return c.json({ message: 'Auth not configured' }, 404);
     }
     if (c.req.method === 'HEAD') {
       return c.body(null, 200);
     }
-    return handler(c, next);
+    return handleAuthRequest({
+      auth: getAuth({ logger }),
+      request: c.req.raw,
+      clientAddress: c.get('lowdefyContext').clientAddress,
+    });
   };
 }
 

package/src/routes/auth.test.mjs

@@ -0,0 +1,85 @@
+/*
+  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 { serve } from '@hono/node-server';
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+// The auth engine is replaced by one that echoes what reached it, so the route
+// is exercised on a real @hono/node-server connection: the request the engine
+// receives is rebuilt from @hono/node-server's own request object.
+const echoAuth = {
+  handler: async (request) =>
+    Response.json({
+      method: request.method,
+      clientAddress: request.headers.get('x-lowdefy-client-address'),
+      body: await request.text(),
+    }),
+};
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({ default: { configured: true } }));
+jest.unstable_mockModule('../../lib/build/config.js', () => ({ default: {} }));
+jest.unstable_mockModule('../../lib/server/auth/getAuth.js', () => ({
+  default: jest.fn(() => echoAuth),
+}));
+
+const { default: authMiddleware } = await import('./auth.js');
+const { default: getClientAddress } = await import('../../lib/server/getClientAddress.js');
+
+const logger = { debug: jest.fn(), error: jest.fn(), info: jest.fn(), warn: jest.fn() };
+
+let server;
+let baseUrl;
+
+beforeAll(async () => {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', { clientAddress: getClientAddress({ c, logger }) });
+    await next();
+  });
+  app.all('/api/auth/*', authMiddleware({ logger }));
+  await new Promise((resolve) => {
+    server = serve({ fetch: app.fetch, port: 0, hostname: '127.0.0.1' }, (info) => {
+      baseUrl = `http://127.0.0.1:${info.port}`;
+      resolve();
+    });
+  });
+});
+
+afterAll(async () => {
+  await new Promise((resolve) => server.close(resolve));
+});
+
+test('the auth route hands the engine the connection address, not the forwarded or client-sent one', async () => {
+  const response = await fetch(`${baseUrl}/api/auth/sign-in/email`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'x-forwarded-for': '203.0.113.9',
+      'x-lowdefy-client-address': '203.0.113.10',
+    },
+    body: JSON.stringify({ email: 'user@example.com' }),
+  });
+  expect(await response.json()).toEqual({
+    method: 'POST',
+    clientAddress: '127.0.0.1',
+    body: JSON.stringify({ email: 'user@example.com' }),
+  });
+});
+
+test('the auth route hands the engine a GET without a body', async () => {
+  const response = await fetch(`${baseUrl}/api/auth/get-session`);
+  expect(await response.json()).toEqual({ method: 'GET', clientAddress: '127.0.0.1', body: '' });
+});