@lowdefy/server-e2e 6.1.0 → 7.1.0

package/src/middleware/apiContext.test.mjs

@@ -24,21 +24,31 @@ import { jest } from '@jest/globals';
 const secret = 'planted-e2e-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 }) => clientSignal),
+  normalizeInjectedCaller: jest.fn((user) => user),
+}));
 jest.unstable_mockModule('../../lib/build/appMeta.js', () => ({ default: {} }));
 jest.unstable_mockModule('../../lib/build/config.js', () => ({ default: {} }));
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({ default: {} }));
 jest.unstable_mockModule('../../lib/build/i18n.js', () => ({ default: {} }));
 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/getE2eSecrets.js', () => ({
   default: jest.fn(() => ({ TEST: process.env.LOWDEFY_SECRET_TEST })),
 }));
-jest.unstable_mockModule('../../lib/server/auth/session.js', () => ({
+jest.unstable_mockModule('../../lib/server/auth/getUser.js', () => ({
   default: jest.fn(() => undefined),
 }));
 jest.unstable_mockModule('../../lib/server/log/logRequest.js', () => ({ default: jest.fn() }));
@@ -53,6 +63,7 @@ const fixtures = [
   { file: 'connections.js', content: 'export default {};\n' },
   { 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 }));
 

package/src/middleware/errorHandler.js

@@ -15,20 +15,79 @@
 */
 
 import { redactErrorResponse } from '@lowdefy/api';
+import { HTTPException } from 'hono/http-exception';
 
 // Hono routes every handler error to the app-level error handler — upstream
-// middleware try/catch never sees them (compose catches per dispatch level).
-// API routes get the serialized error JSON the old apiWrapper returned;
-// page routes get a plain 500.
+// middleware try/catch never sees them. API routes get the serialized error
+// JSON the old apiWrapper returned; page routes get a plain 500.
 function createErrorHandler({ basePath = '', logger }) {
   return async function errorHandler(error, c) {
+    const path = basePath ? c.req.path.replace(basePath, '') : c.req.path;
+    // Unauthenticated requests to protected endpoints are expected traffic -
+    // one warning line and a 401, skipping the structured error log so
+    // probing cannot flood it. Keys strictly on the error name; the 500 path
+    // below is untouched.
+    if (error.name === 'AuthenticationError') {
+      logger.warn(`Unauthenticated request: ${c.req.method} ${c.req.path}`);
+      if (path.startsWith('/api/')) {
+        return c.json({ name: error.name, message: error.message }, 401);
+      }
+      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) {
       await context.handleError(error);
     } else {
       logger.error(error);
     }
-    const path = basePath ? c.req.path.replace(basePath, '') : c.req.path;
     if (path.startsWith('/api/')) {
       return c.json(redactErrorResponse(context, error), 500);
     }

package/src/middleware/errorHandler.test.mjs

@@ -0,0 +1,402 @@
+/*
+  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 { HTTPException } from 'hono/http-exception';
+import { jest } from '@jest/globals';
+
+import createErrorHandler from './errorHandler.js';
+
+// The handler here is byte-identical to its `server-e2e` counterpart (and to
+// `server`'s apart from the Sentry capture, which `server` tests separately).
+// Keep the three in sync when changing any of them.
+
+// A string that must never reach a client. It is put on `received` at every
+// level of the cause chain, so a single JSON.stringify search over the body
+// proves the redaction reached that level.
+const SECRET = 'SECRET-RECEIVED-VALUE';
+
+function createLogger() {
+  return { error: jest.fn(), warn: jest.fn() };
+}
+
+// The error handler is only reachable through hono's app-level onError, so the
+// handler is driven the way production drives it: a route that throws, with the
+// lowdefyContext set by upstream middleware when there is one.
+function createApp({ basePath = '', context, error, logger }) {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    if (context) c.set('lowdefyContext', context);
+    await next();
+  });
+  app.all('*', () => {
+    throw error;
+  });
+  app.onError(createErrorHandler({ basePath, logger }));
+  return app;
+}
+
+function createAuthenticationError(message) {
+  const error = new Error(message);
+  error.name = 'AuthenticationError';
+  error.received = SECRET;
+  return error;
+}
+
+function createAuthorizationError(message) {
+  const error = new Error(message);
+  error.name = 'AuthorizationError';
+  error.received = SECRET;
+  return error;
+}
+
+function createTwoFactorEnrolmentRequiredError(message) {
+  const error = new Error(message);
+  error.name = 'TwoFactorEnrolmentRequiredError';
+  error.received = SECRET;
+  return error;
+}
+
+function createUserError(message) {
+  const error = new Error(message);
+  error.name = 'UserError';
+  error.received = SECRET;
+  return error;
+}
+
+// Two Error levels, each with a stack (every Error has one) and a recognisable
+// `received`, plus a configKey the policy keeps.
+function createErrorWithCause() {
+  const cause = new Error('Cause message.');
+  cause.received = `${SECRET}-cause`;
+  const error = new Error('Top message.', { cause });
+  error.received = `${SECRET}-top`;
+  error.configKey = 'page:home.blocks.0';
+  return error;
+}
+
+test('errorHandler returns 401 with only name and message for an AuthenticationError on an api path', async () => {
+  const logger = createLogger();
+  const context = { handleError: jest.fn() };
+  const res = await createApp({
+    context,
+    error: createAuthenticationError('Unauthenticated.'),
+    logger,
+  }).request('/api/request/getUsers');
+
+  expect(res.status).toEqual(401);
+  expect(await res.json()).toEqual({ name: 'AuthenticationError', message: 'Unauthenticated.' });
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.warn.mock.calls[0][0]).toMatch(/Unauthenticated request/);
+  expect(logger.error).not.toHaveBeenCalled();
+  expect(context.handleError).not.toHaveBeenCalled();
+});
+
+test('errorHandler does not send an AuthenticationError through the redactor', async () => {
+  const res = await createApp({
+    error: createAuthenticationError('Unauthenticated.'),
+    logger: createLogger(),
+  }).request('/api/request/getUsers');
+
+  const body = await res.json();
+  expect(body['~e']).toBeUndefined();
+});
+
+test('errorHandler returns text Unauthorized at 401 for an AuthenticationError on a page path', async () => {
+  const logger = createLogger();
+  const res = await createApp({
+    error: createAuthenticationError('Unauthenticated.'),
+    logger,
+  }).request('/home');
+
+  expect(res.status).toEqual(401);
+  expect(await res.text()).toEqual('Unauthorized');
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+});
+
+test('errorHandler returns 403 with only name and message for an AuthorizationError on an api path', async () => {
+  const logger = createLogger();
+  const context = { handleError: jest.fn() };
+  const res = await createApp({
+    context,
+    error: createAuthorizationError('Forbidden.'),
+    logger,
+  }).request('/api/request/getUsers');
+
+  expect(res.status).toEqual(403);
+  expect(await res.json()).toEqual({ name: 'AuthorizationError', message: 'Forbidden.' });
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.warn.mock.calls[0][0]).toMatch(/Forbidden: GET \/api\/request\/getUsers/);
+  expect(logger.error).not.toHaveBeenCalled();
+  expect(context.handleError).not.toHaveBeenCalled();
+});
+
+test('errorHandler does not send an AuthorizationError through the redactor', async () => {
+  const res = await createApp({
+    error: createAuthorizationError('Forbidden.'),
+    logger: createLogger(),
+  }).request('/api/request/getUsers');
+
+  const body = await res.json();
+  expect(body['~e']).toBeUndefined();
+  expect(JSON.stringify(body)).not.toContain(SECRET);
+});
+
+test('errorHandler returns text Forbidden at 403 for an AuthorizationError on a page path', async () => {
+  const logger = createLogger();
+  const res = await createApp({
+    error: createAuthorizationError('Forbidden.'),
+    logger,
+  }).request('/home');
+
+  expect(res.status).toEqual(403);
+  expect(await res.text()).toEqual('Forbidden');
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.error).not.toHaveBeenCalled();
+});
+
+test('errorHandler returns 403 with only name and message for a TwoFactorEnrolmentRequiredError on an api path', async () => {
+  const logger = createLogger();
+  const context = { handleError: jest.fn() };
+  const res = await createApp({
+    context,
+    error: createTwoFactorEnrolmentRequiredError('Two-factor enrolment required.'),
+    logger,
+  }).request('/api/request/getUsers');
+
+  expect(res.status).toEqual(403);
+  expect(await res.json()).toEqual({
+    name: 'TwoFactorEnrolmentRequiredError',
+    message: 'Two-factor enrolment required.',
+  });
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.warn.mock.calls[0][0]).toMatch(/Two-factor enrolment required/);
+  expect(logger.error).not.toHaveBeenCalled();
+  expect(context.handleError).not.toHaveBeenCalled();
+});
+
+test('errorHandler does not send a TwoFactorEnrolmentRequiredError through the redactor', async () => {
+  const res = await createApp({
+    error: createTwoFactorEnrolmentRequiredError('Two-factor enrolment required.'),
+    logger: createLogger(),
+  }).request('/api/request/getUsers');
+
+  const body = await res.json();
+  expect(body['~e']).toBeUndefined();
+});
+
+test('errorHandler returns text at 403 for a TwoFactorEnrolmentRequiredError on a page path', async () => {
+  const logger = createLogger();
+  const context = { handleError: jest.fn() };
+  const res = await createApp({
+    context,
+    error: createTwoFactorEnrolmentRequiredError('Two-factor enrolment required.'),
+    logger,
+  }).request('/home');
+
+  expect(res.status).toEqual(403);
+  expect(await res.text()).toEqual('Two-factor enrolment required');
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(context.handleError).not.toHaveBeenCalled();
+});
+
+test('errorHandler returns 400 with only name and message for a UserError on an api path', async () => {
+  const logger = createLogger();
+  const context = { handleError: jest.fn() };
+  const res = await createApp({
+    context,
+    error: createUserError('Payload for endpoint "x" does not match its payloadSchema.'),
+    logger,
+  }).request('/api/endpoints/x', { method: 'POST' });
+
+  expect(res.status).toEqual(400);
+  expect(await res.json()).toEqual({
+    name: 'UserError',
+    message: 'Payload for endpoint "x" does not match its payloadSchema.',
+  });
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.warn.mock.calls[0][0]).toMatch(/Bad request: POST \/api\/endpoints\/x/);
+  expect(logger.error).not.toHaveBeenCalled();
+  expect(context.handleError).not.toHaveBeenCalled();
+});
+
+test('errorHandler does not send a UserError through the redactor', async () => {
+  const res = await createApp({
+    error: createUserError('Bad payload.'),
+    logger: createLogger(),
+  }).request('/api/endpoints/x');
+
+  const body = await res.json();
+  expect(body['~e']).toBeUndefined();
+  expect(JSON.stringify(body)).not.toContain(SECRET);
+});
+
+test('errorHandler returns text Bad Request at 400 for a UserError on a page path', async () => {
+  const logger = createLogger();
+  const res = await createApp({
+    error: createUserError('Bad payload.'),
+    logger,
+  }).request('/home');
+
+  expect(res.status).toEqual(400);
+  expect(await res.text()).toEqual('Bad Request');
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.error).not.toHaveBeenCalled();
+});
+
+test('errorHandler sends an HTTPException response as-is with one warning and no error log', async () => {
+  const logger = createLogger();
+  const error = new HTTPException(404, {
+    res: Response.json(
+      { jsonrpc: '2.0', error: { code: -32000, message: 'Unsupported protocol version' } },
+      { status: 404 }
+    ),
+  });
+  const res = await createApp({ error, logger }).request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(404);
+  expect(await res.json()).toEqual({
+    jsonrpc: '2.0',
+    error: { code: -32000, message: 'Unsupported protocol version' },
+  });
+  expect(logger.warn).toHaveBeenCalledWith('404 answered by the route: POST /api/mcp');
+  expect(logger.error).not.toHaveBeenCalled();
+});
+
+test('errorHandler returns 500 with the serialized error envelope on an api path', async () => {
+  const res = await createApp({
+    error: createErrorWithCause(),
+    logger: createLogger(),
+  }).request('/api/request/getUsers');
+
+  expect(res.status).toEqual(500);
+  const body = await res.json();
+  expect(body['~e'].name).toEqual('Error');
+  expect(body['~e'].message).toEqual('Something went wrong.');
+  expect(body['~e'].cause).toBeUndefined();
+});
+
+test('errorHandler omits stack and received from the 500 envelope at the top level', async () => {
+  const res = await createApp({
+    error: createErrorWithCause(),
+    logger: createLogger(),
+  }).request('/api/request/getUsers');
+
+  const body = await res.json();
+  expect(body['~e'].stack).toBeUndefined();
+  expect(body['~e'].received).toBeUndefined();
+});
+
+test('errorHandler omits the cause chain from the 500 envelope', async () => {
+  const res = await createApp({
+    error: createErrorWithCause(),
+    logger: createLogger(),
+  }).request('/api/request/getUsers');
+
+  const body = await res.json();
+  expect(body['~e'].cause).toBeUndefined();
+  expect(JSON.stringify(body)).not.toContain(SECRET);
+  expect(JSON.stringify(body)).not.toContain('Cause message.');
+});
+
+test('errorHandler keeps configKey on the 500 envelope so the fault can be located in config', async () => {
+  const res = await createApp({
+    error: createErrorWithCause(),
+    logger: createLogger(),
+  }).request('/api/request/getUsers');
+
+  const body = await res.json();
+  expect(body['~e'].configKey).toEqual('page:home.blocks.0');
+});
+
+test('errorHandler returns text Internal Server Error at 500 on a page path with no payload', async () => {
+  const res = await createApp({
+    error: createErrorWithCause(),
+    logger: createLogger(),
+  }).request('/home');
+
+  expect(res.status).toEqual(500);
+  expect(await res.text()).toEqual('Internal Server Error');
+});
+
+test('errorHandler awaits context.handleError before serializing the response', async () => {
+  const context = {
+    handleError: jest.fn(async (error) => {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      error.handled = true;
+    }),
+  };
+  const error = createErrorWithCause();
+  const res = await createApp({ context, error, logger: createLogger() }).request(
+    '/api/request/getUsers'
+  );
+
+  expect(context.handleError).toHaveBeenCalledTimes(1);
+  expect(context.handleError).toHaveBeenCalledWith(error);
+  const body = await res.json();
+  expect(body['~e'].handled).toBe(true);
+});
+
+// createHandleError sets error.handled once it has logged. The client reads it
+// to decide whether to POST the error back for logging, so it has to survive
+// serialization or the error is logged a second time.
+test('errorHandler returns handled true on the 500 envelope after handleError sets it', async () => {
+  const context = {
+    handleError: jest.fn(async (error) => {
+      error.handled = true;
+    }),
+  };
+  const res = await createApp({
+    context,
+    error: createErrorWithCause(),
+    logger: createLogger(),
+  }).request('/api/request/getUsers');
+
+  const body = await res.json();
+  expect(body['~e'].handled).toBe(true);
+});
+
+test('errorHandler logs with logger.error when the request has no lowdefyContext', async () => {
+  const logger = createLogger();
+  const error = createErrorWithCause();
+  const res = await createApp({ error, logger }).request('/api/request/getUsers');
+
+  expect(res.status).toEqual(500);
+  expect(logger.error).toHaveBeenCalledTimes(1);
+  expect(logger.error).toHaveBeenCalledWith(error);
+});
+
+test('errorHandler treats a basePath prefixed api path as an api path', async () => {
+  const res = await createApp({
+    basePath: '/base',
+    error: createErrorWithCause(),
+    logger: createLogger(),
+  }).request('/base/api/request/getUsers');
+
+  expect(res.status).toEqual(500);
+  const body = await res.json();
+  expect(body['~e'].message).toEqual('Something went wrong.');
+});
+
+test('errorHandler treats a basePath prefixed page path as a page path', async () => {
+  const res = await createApp({
+    basePath: '/base',
+    error: createErrorWithCause(),
+    logger: createLogger(),
+  }).request('/base/home');
+
+  expect(res.status).toEqual(500);
+  expect(await res.text()).toEqual('Internal Server Error');
+});

package/src/routes/apiPage.js

@@ -16,22 +16,27 @@
 
 import { getPageConfig } from '@lowdefy/api';
 
-import getPathSegments from '../lib/getPathSegments.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 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 !== '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 });
+  return c.json({ pageId, pathParams, matchedPath, pageConfig: result.pageConfig });
 }
 
 export default apiPageHandler;

package/src/routes/apiPage.test.mjs

@@ -0,0 +1,92 @@
+/*
+  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: 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({
+    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({
+    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 });
+});