@lowdefy/server 6.0.0 → 7.0.0

package/src/initServer.js

@@ -0,0 +1,61 @@
+/*
+  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 checkEnvironmentGuards from '@lowdefy/node-utils/checkEnvironmentGuards.js';
+
+import initSentryServer from '../lib/server/sentry/initSentry.js';
+
+// The startup every production entry runs before it serves: the Node server (src/index.js) and the
+// Vercel function entry that `lowdefy vercel-output` generates. Keeping it in one place stops the
+// entries drifting apart. The build artifacts are read relative to process.cwd(), so an entry that
+// has to change directory imports this module dynamically, after the chdir. A serverless entry
+// passes serverless: true, so Sentry reports errors only unless the app turns tracing on.
+async function initServer({ serverless = false } = {}) {
+  const sentry = await initSentryServer({ serverless });
+
+  // The build checked the current environment's guards, but an image built once can be started
+  // with different variables, so they are checked again before the server takes any traffic — and
+  // before the app loads, so a misconfigured start fails without importing every plugin under the
+  // wrong variables. The failure is sent to Sentry here because the Vercel launcher catches errors
+  // thrown while it imports the function entry, so no global handler would report it, and the
+  // instance can be torn down before a queued event is sent.
+  const { default: config } = await import('../lib/build/config.js');
+  try {
+    checkEnvironmentGuards({
+      name: config.environment,
+      guards: config.environments?.[config.environment]?.guards,
+    });
+  } catch (error) {
+    if (sentry) {
+      sentry.captureException(error);
+      await sentry.flush(2000);
+    }
+    throw error;
+  }
+
+  // Import after Sentry init so instrumentation observes the module graph.
+  const { default: createApp } = await import('./app.js');
+  const { default: createLogger } = await import('../lib/server/log/createLogger.js');
+
+  const logger = createLogger({ server: 'lowdefy' });
+  if (sentry) {
+    logger.info('Sentry enabled: server');
+  }
+
+  return { createApp, logger, sentry };
+}
+
+export default initServer;

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,21 +30,25 @@ 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';
 import loggerConfig from '../../lib/build/logger.js';
+import scrubSecrets from '../../lib/server/scrubSecrets.js';
 import notifications, {
   interpolateProperties,
   renderEmail,
 } 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();
@@ -55,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.
@@ -83,6 +102,7 @@ function apiContext() {
       interpolateProperties,
       jsMap,
       logger: createLogger({ rid }),
+      mode: 'prod',
       notifications,
       operators,
       renderEmail,
@@ -91,7 +111,15 @@ function apiContext() {
         method: c.req.method,
         hostname: c.req.header('host'),
       },
+      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.
@@ -100,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

@@ -0,0 +1,178 @@
+/*
+  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 fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+const secret = 'planted-apicontext-secret';
+process.env.LOWDEFY_SECRET_TEST = secret;
+
+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: {} }));
+jest.unstable_mockModule('../../lib/build/logger.js', () => ({ default: { sentry: {} } }));
+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(),
+  })),
+}));
+jest.unstable_mockModule('../../lib/server/fileCache.js', () => ({ default: {} }));
+jest.unstable_mockModule('../../lib/server/auth/getAuth.js', () => ({
+  default: jest.fn(() => 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', () => ({
+  default: jest.fn(),
+}));
+
+// apiContext statically imports the app build's plugin artifacts, which only
+// exist in a built app (build/** is gitignored). Materialize the minimal set
+// it needs so the import resolves; clean up only what this test created.
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+const pluginsDir = path.resolve(dirname, '../../build/plugins');
+const fixtures = [
+  { file: 'agents.js', content: 'export default {};\n' },
+  { file: 'connections.js', content: 'export default {};\n' },
+  {
+    file: 'notifications.js',
+    content:
+      'export default {};\nexport const interpolateProperties = () => {};\nexport const renderEmail = () => {};\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 }));
+
+const createdFixtures = [];
+fixtures.forEach(({ absolutePath, content }) => {
+  if (!fs.existsSync(absolutePath)) {
+    fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+    fs.writeFileSync(absolutePath, content);
+    createdFixtures.push(absolutePath);
+  }
+});
+
+// A checkout that has built an app already holds real artifacts here, which import plugins this
+// package does not depend on, so the stubs are also mocked over whatever is on disk.
+fixtures.forEach(({ absolutePath }) => {
+  jest.unstable_mockModule(absolutePath, () => ({
+    default: {},
+    interpolateProperties: () => {},
+    renderEmail: () => {},
+  }));
+});
+
+afterAll(() => {
+  createdFixtures.forEach((absolutePath) => fs.rmSync(absolutePath, { force: true }));
+});
+
+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();
+  app.use('*', apiContext());
+  app.get('/api/ping', (c) => {
+    const context = c.get('lowdefyContext');
+    return c.json({
+      mode: context.mode,
+      scrubbed: context.scrubSecrets(`token ${secret} end`),
+    });
+  });
+  return app;
+}
+
+test('apiContext sets mode to prod', async () => {
+  const res = await createApp().request('/api/ping');
+  expect(res.status).toEqual(200);
+  const body = await res.json();
+  expect(body.mode).toEqual('prod');
+});
+
+test('apiContext scrubSecrets redacts a planted secret', async () => {
+  const res = await createApp().request('/api/ping');
+  expect(res.status).toEqual(200);
+  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);
+});