@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/server/jitPageBuilder.skipPluginChecks.test.mjs

@@ -0,0 +1,78 @@
+/*
+  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 os from 'os';
+import path from 'path';
+import { jest } from '@jest/globals';
+
+const actualBuildDev = await import('@lowdefy/build/dev');
+const mockCreateContext = jest.fn(actualBuildDev.createContext);
+
+jest.unstable_mockModule('@lowdefy/build/dev', () => ({
+  ...actualBuildDev,
+  createContext: mockCreateContext,
+}));
+
+const savedSkip = process.env.LOWDEFY_BUILD_SKIP_PLUGIN_CHECKS;
+let loadCount = 0;
+let root;
+
+// The build context is kept at module scope, so each case loads a fresh
+// module instance.
+async function createBuildContext() {
+  loadCount += 1;
+  const { getBuildContext } = await import(`./jitPageBuilder.js?case=${loadCount}`);
+  return getBuildContext(path.join(root, 'build'), path.join(root, 'config'));
+}
+
+beforeEach(() => {
+  delete process.env.LOWDEFY_BUILD_SKIP_PLUGIN_CHECKS;
+  mockCreateContext.mockClear();
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'ldf-jit-skip-checks-'));
+  fs.mkdirSync(path.join(root, 'build'), { recursive: true });
+  fs.writeFileSync(
+    path.join(root, 'build', 'idCounter.json'),
+    JSON.stringify({ prefix: 'test_', counter: 0 })
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+afterAll(() => {
+  if (savedSkip === undefined) {
+    delete process.env.LOWDEFY_BUILD_SKIP_PLUGIN_CHECKS;
+  } else {
+    process.env.LOWDEFY_BUILD_SKIP_PLUGIN_CHECKS = savedSkip;
+  }
+});
+
+test('the JIT build context skips plugin checks when LOWDEFY_BUILD_SKIP_PLUGIN_CHECKS is true', async () => {
+  process.env.LOWDEFY_BUILD_SKIP_PLUGIN_CHECKS = 'true';
+  const context = await createBuildContext();
+  expect(mockCreateContext).toHaveBeenCalledTimes(1);
+  expect(mockCreateContext.mock.calls[0][0].skipPluginChecks).toBe(true);
+  expect(context.skipPluginChecks).toBe(true);
+});
+
+test('the JIT build context runs plugin checks when LOWDEFY_BUILD_SKIP_PLUGIN_CHECKS is unset', async () => {
+  const context = await createBuildContext();
+  expect(mockCreateContext).toHaveBeenCalledTimes(1);
+  expect(mockCreateContext.mock.calls[0][0].skipPluginChecks).toBe(false);
+  expect(context.skipPluginChecks).toBe(false);
+});

package/lib/server/jitPageBuilder.test.mjs

@@ -0,0 +1,218 @@
+/*
+  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 os from 'os';
+import path from 'path';
+import { jest } from '@jest/globals';
+import { ConfigError } from '@lowdefy/errors';
+import { serializer } from '@lowdefy/helpers';
+
+import buildPageIfNeeded, { getBuildContext } from './jitPageBuilder.js';
+import createHandleError from './log/createHandleError.js';
+import pageBuildRecords from './pageBuildRecords.js';
+import readMergedMaps from './readMergedMaps.js';
+
+// The dev page build context restores the tenant facts the skeleton build
+// wrote, so page requests get the same tenant pipeline checks as a full build.
+test('getBuildContext restores the scoped connections, walled collections and shared connections', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ldf-jit-context-'));
+  const buildDirectory = path.join(root, 'build');
+  fs.mkdirSync(buildDirectory, { recursive: true });
+  const walledKey = JSON.stringify(['MongoDBCollection', ['uri'], 'totals']);
+  const shared = {
+    connection: { type: 'MongoDBCollection', properties: { databaseUri: 'uri' } },
+    tenantTarget: { database: ['databaseUri'], collection: 'collection' },
+  };
+  fs.writeFileSync(
+    path.join(buildDirectory, 'idCounter.json'),
+    JSON.stringify({ prefix: 'test_', counter: 0 })
+  );
+  fs.writeFileSync(
+    path.join(buildDirectory, 'tenantTargets.json'),
+    serializer.serializeToString({
+      tenantConnectionIds: ['totals'],
+      walledTargets: [[walledKey, { connectionId: 'totals', field: 'organization_id' }]],
+      sharedTargets: [['orders_all', shared]],
+    })
+  );
+
+  const context = getBuildContext(buildDirectory, path.join(root, 'config'));
+
+  expect([...context.tenantConnectionIds]).toEqual(['totals']);
+  expect(context.walledTargets.get(walledKey)).toEqual({
+    connectionId: 'totals',
+    field: 'organization_id',
+  });
+  expect(context.sharedTargets.get('orders_all')).toEqual(shared);
+});
+
+// A JIT page build loads the build package's plugins on first use.
+jest.setTimeout(30000);
+
+function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data));
+}
+
+// A config build's output, as far as a JIT page build reads it.
+function createApp({ pages }) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ldf-jit-maps-'));
+  const buildDirectory = path.join(root, 'server', 'build');
+  const configDirectory = path.join(root, 'config');
+  writeJson(path.join(buildDirectory, 'idCounter.json'), { prefix: 'cfg1_', counter: 10 });
+  writeJson(path.join(buildDirectory, 'keyMap.json'), {
+    cfg1_1: { key: 'root', '~r': 'cfg1_r' },
+  });
+  writeJson(path.join(buildDirectory, 'refMap.json'), {
+    cfg1_r: { parent: null, path: 'lowdefy.yaml' },
+  });
+  writeJson(path.join(buildDirectory, 'installedPluginPackages.json'), [
+    '@lowdefy/actions-core',
+    '@lowdefy/blocks-antd',
+    '@lowdefy/blocks-basic',
+    '@lowdefy/operators-js',
+  ]);
+  writeJson(path.join(buildDirectory, 'theme.json'), {});
+  const registry = {};
+  for (const [pageId, content] of Object.entries(pages)) {
+    fs.mkdirSync(path.join(configDirectory, 'pages'), { recursive: true });
+    fs.writeFileSync(path.join(configDirectory, 'pages', `${pageId}.yaml`), content);
+    registry[pageId] = {
+      pageId,
+      auth: { public: true },
+      refId: `ref-${pageId}`,
+      refPath: `pages/${pageId}.yaml`,
+    };
+  }
+  writeJson(path.join(buildDirectory, 'pageRegistry.json'), registry);
+  return { root, buildDirectory, configDirectory };
+}
+
+function listJitMaps(buildDirectory) {
+  const directory = path.join(buildDirectory, 'jitMaps');
+  return fs.existsSync(directory) ? fs.readdirSync(directory).sort() : [];
+}
+
+// A config build publish renames a new page registry into place.
+function publishRegistry(buildDirectory) {
+  const registryPath = path.join(buildDirectory, 'pageRegistry.json');
+  const stagedPath = `${registryPath}.staged`;
+  fs.copyFileSync(registryPath, stagedPath);
+  fs.renameSync(stagedPath, registryPath);
+}
+
+test('a JIT page build leaves keyMap.json and refMap.json as the config build wrote them', async () => {
+  const { root, buildDirectory, configDirectory } = createApp({
+    pages: { home: 'id: home\ntype: Box\nblocks:\n  - id: title\n    type: Box\n' },
+  });
+  const keyMapBefore = fs.readFileSync(path.join(buildDirectory, 'keyMap.json'), 'utf8');
+  const refMapBefore = fs.readFileSync(path.join(buildDirectory, 'refMap.json'), 'utf8');
+
+  await buildPageIfNeeded({ pageId: 'home', buildDirectory, configDirectory });
+
+  expect(fs.readFileSync(path.join(buildDirectory, 'keyMap.json'), 'utf8')).toBe(keyMapBefore);
+  expect(fs.readFileSync(path.join(buildDirectory, 'refMap.json'), 'utf8')).toBe(refMapBefore);
+  const files = listJitMaps(buildDirectory);
+  expect(files).toHaveLength(1);
+  expect(files[0]).toMatch(/^[0-9a-f]{6}-\d+-1\.json$/);
+  const { keyMap } = await readMergedMaps({ buildDirectory });
+  const titleKey = Object.keys(keyMap).find((key) => keyMap[key].key?.includes('title'));
+  // Config build prefix, then this process's id: <cfg prefix><child id>_<counter>.
+  expect(titleKey).toMatch(/^cfg1_[0-9a-f]{6}_[0-9a-z]+$/);
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+test('an error a failing JIT page build throws after its keys were added resolves to its source line', async () => {
+  const { root, buildDirectory, configDirectory } = createApp({
+    pages: {
+      broken:
+        'id: broken\ntype: Box\nblocks:\n  - id: button\n    type: Button\n    events:\n' +
+        '      onClick:\n        - id: act\n          type: UndefinedAction\n',
+    },
+  });
+
+  const error = await buildPageIfNeeded({
+    pageId: 'broken',
+    buildDirectory,
+    configDirectory,
+  }).catch((caught) => caught);
+  const buildError = (error.buildErrors ?? [error]).find((item) => item.configKey);
+  const context = {
+    configDirectory,
+    logger: { error: jest.fn() },
+    readConfigFile: jest.fn(),
+    readMaps: () => readMergedMaps({ buildDirectory }),
+  };
+  // A fresh copy, as the request that logs it would see it.
+  const logged = new ConfigError(buildError.message, { configKey: buildError.configKey });
+  await createHandleError({ context })(logged);
+
+  expect(logged.source).toBe(`${path.join(configDirectory, 'pages', 'broken.yaml')}:8`);
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+test('after two config publishes only the current and previous build contexts keep jitMaps files', async () => {
+  const { root, buildDirectory, configDirectory } = createApp({
+    pages: {
+      a: 'id: a\ntype: Box\n',
+      b: 'id: b\ntype: Box\n',
+      c: 'id: c\ntype: Box\n',
+    },
+  });
+
+  await buildPageIfNeeded({ pageId: 'a', buildDirectory, configDirectory });
+  const [first] = listJitMaps(buildDirectory);
+  publishRegistry(buildDirectory);
+  await buildPageIfNeeded({ pageId: 'b', buildDirectory, configDirectory });
+  publishRegistry(buildDirectory);
+  await buildPageIfNeeded({ pageId: 'c', buildDirectory, configDirectory });
+
+  const files = listJitMaps(buildDirectory);
+  expect(files).toHaveLength(2);
+  expect(files).not.toContain(first);
+  const generations = files.map((file) => Number(file.split('-')[1]));
+  expect(generations[1] - generations[0]).toBe(1);
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+test('a page build that loads app code is recorded as having run it, a YAML-only one is not', async () => {
+  const { root, buildDirectory, configDirectory } = createApp({
+    pages: {
+      plain: 'id: plain\ntype: Box\nblocks:\n  - _ref: blocks/shared.yaml\n',
+      coded: 'id: coded\ntype: Box\nblocks:\n  - _ref: blocks/banner.js\n',
+    },
+  });
+  fs.writeFileSync(path.join(configDirectory, 'package.json'), '{"type":"module"}');
+  fs.mkdirSync(path.join(configDirectory, 'blocks'));
+  fs.writeFileSync(path.join(configDirectory, 'blocks', 'shared.yaml'), 'id: shared\ntype: Box\n');
+  fs.writeFileSync(
+    path.join(configDirectory, 'blocks', 'banner.js'),
+    "export default { id: 'banner', type: 'Box' };\n"
+  );
+
+  await buildPageIfNeeded({ pageId: 'plain', buildDirectory, configDirectory });
+  await buildPageIfNeeded({ pageId: 'coded', buildDirectory, configDirectory });
+
+  const plain = pageBuildRecords.get('plain');
+  expect(plain.ranAppCode).toBe(false);
+  expect([...plain.files.keys()]).toEqual([
+    path.join(configDirectory, 'pages', 'plain.yaml'),
+    path.join(configDirectory, 'blocks', 'shared.yaml'),
+  ]);
+  expect(pageBuildRecords.get('coded').ranAppCode).toBe(true);
+  fs.rmSync(root, { recursive: true, force: true });
+});

package/lib/server/journeyCookies/JOURNEY_COOKIES.js

@@ -0,0 +1,37 @@
+/*
+  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.
+*/
+
+// Every cookie the dev server's own headless browser sets on a journey
+// context. Each value is "<journeyActorToken>.<payload>", so only that browser
+// can set one: a cookie from anywhere else fails verification and is ignored.
+// The production server never reads any of them.
+//
+// kind: an inline cookie carries its whole meaning in the payload (an actor's
+// client address); a registry cookie carries the id of an entry the dev server
+// keeps in memory for the length of one journey run.
+//
+// loopback: a detached CallApi loops back through /api/detached/* as a fresh
+// request, so a cookie whose state must reach that request (the data set, the
+// mutant) is forwarded on it - see forwardJourneyCookies. The actor and
+// recording cookies describe the browser, not the work, and stay behind.
+const JOURNEY_COOKIES = {
+  actor: { name: 'lowdefy_journey_actor', kind: 'inline', loopback: false },
+  recording: { name: 'lowdefy_recording', kind: 'inline', loopback: false },
+  data: { name: 'lowdefy_journey_data', kind: 'registry', loopback: true },
+  mutant: { name: 'lowdefy_journey_mutant', kind: 'registry', loopback: true },
+};
+
+export default JOURNEY_COOKIES;

package/lib/server/journeyCookies/forwardJourneyCookies.js

@@ -0,0 +1,46 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+import JOURNEY_COOKIES from './JOURNEY_COOKIES.js';
+import readJourneyCookie from './readJourneyCookie.js';
+import { journeyActorToken } from '../auth/journeyActor.js';
+
+// The Cookie header a detached loopback call carries, so its target runs with
+// the same data set and mutant as the journey request that dispatched it. Only
+// verified cookies are forwarded. `dataSessionId` names a data session a dev
+// tool call opened itself (run_request, run_endpoint with data): that call has
+// no data cookie, but its detached hop must still read the data set, never the
+// app's own database.
+function forwardJourneyCookies({ cookieHeader, dataSessionId }) {
+  return Object.values(JOURNEY_COOKIES)
+    .filter((cookie) => cookie.loopback)
+    .map((cookie) => {
+      if (cookie === JOURNEY_COOKIES.data && !type.isNone(dataSessionId)) {
+        return `${cookie.name}=${journeyActorToken}.${dataSessionId}`;
+      }
+      const payload = readJourneyCookie({ cookieHeader, name: cookie.name });
+      if (payload === null) {
+        return null;
+      }
+      return `${cookie.name}=${journeyActorToken}.${payload}`;
+    })
+    .filter((pair) => pair !== null)
+    .join('; ');
+}
+
+export default forwardJourneyCookies;

package/lib/server/journeyCookies/readJourneyCookie.js

@@ -0,0 +1,52 @@
+/*
+  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 crypto from 'node:crypto';
+
+import { journeyActorToken } from '../auth/journeyActor.js';
+
+const tokenBuffer = Buffer.from(journeyActorToken);
+
+function findCookieValue({ cookieHeader, name }) {
+  for (const pair of (cookieHeader ?? '').split(';')) {
+    const separator = pair.indexOf('=');
+    if (separator !== -1 && pair.slice(0, separator).trim() === name) {
+      return pair.slice(separator + 1).trim();
+    }
+  }
+  return null;
+}
+
+// Returns the payload of a journey cookie the dev server's own headless
+// browser wrote (writeJourneyCookie), or null when the cookie is absent or
+// its token is not this process's journeyActorToken.
+function readJourneyCookie({ cookieHeader, name }) {
+  const value = findCookieValue({ cookieHeader, name });
+  if (value === null) {
+    return null;
+  }
+  const separator = value.indexOf('.');
+  if (separator === -1) {
+    return null;
+  }
+  const token = Buffer.from(value.slice(0, separator));
+  if (token.length !== tokenBuffer.length || !crypto.timingSafeEqual(token, tokenBuffer)) {
+    return null;
+  }
+  return value.slice(separator + 1);
+}
+
+export default readJourneyCookie;

package/lib/server/journeyCookies/writeJourneyCookie.js

@@ -0,0 +1,46 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+import JOURNEY_COOKIES from './JOURNEY_COOKIES.js';
+import { journeyActorToken } from '../auth/journeyActor.js';
+
+const names = new Set(Object.values(JOURNEY_COOKIES).map((cookie) => cookie.name));
+
+// The object a journey context passes to Playwright's context.addCookies.
+// httpOnly, so page JavaScript cannot read the token. Lax, not Strict: a
+// journey opens an emailed link from a data: URL, a cross-site navigation that
+// a Strict cookie does not ride.
+function writeJourneyCookie({ name, payload, origin }) {
+  if (!names.has(name)) {
+    throw new Error(`"${name}" is not a journey cookie.`);
+  }
+  if (!type.isString(payload)) {
+    throw new Error(
+      `Journey cookie payload must be a string. Received ${JSON.stringify(payload)}.`
+    );
+  }
+  return {
+    name,
+    value: `${journeyActorToken}.${payload}`,
+    url: origin,
+    httpOnly: true,
+    sameSite: 'Lax',
+  };
+}
+
+export default writeJourneyCookie;

package/lib/server/journeyCookies.js

@@ -0,0 +1,22 @@
+/*
+  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 JOURNEY_COOKIES from './journeyCookies/JOURNEY_COOKIES.js';
+import forwardJourneyCookies from './journeyCookies/forwardJourneyCookies.js';
+import readJourneyCookie from './journeyCookies/readJourneyCookie.js';
+import writeJourneyCookie from './journeyCookies/writeJourneyCookie.js';
+
+export { JOURNEY_COOKIES, forwardJourneyCookies, readJourneyCookie, writeJourneyCookie };

package/lib/server/journeyCookies.test.mjs

@@ -0,0 +1,145 @@
+/*
+  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 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { journeyActorToken } from './auth/journeyActor.js';
+import {
+  JOURNEY_COOKIES,
+  forwardJourneyCookies,
+  readJourneyCookie,
+  writeJourneyCookie,
+} from './journeyCookies.js';
+
+const origin = 'http://localhost:3111';
+const forgedToken = '0'.repeat(journeyActorToken.length);
+
+function header(cookies) {
+  return cookies.map(({ name, value }) => `${name}=${value}`).join('; ');
+}
+
+test('writeJourneyCookie writes a signed, httpOnly, Lax cookie scoped to the origin', () => {
+  expect(
+    writeJourneyCookie({ name: JOURNEY_COOKIES.mutant.name, payload: 'run1', origin })
+  ).toEqual({
+    name: 'lowdefy_journey_mutant',
+    value: `${journeyActorToken}.run1`,
+    url: origin,
+    httpOnly: true,
+    sameSite: 'Lax',
+  });
+});
+
+test('writeJourneyCookie throws for a name outside the journey cookie table', () => {
+  expect(() => writeJourneyCookie({ name: 'session', payload: 'x', origin })).toThrow(
+    '"session" is not a journey cookie.'
+  );
+});
+
+test('readJourneyCookie returns the payload of a cookie writeJourneyCookie wrote', () => {
+  const cookie = writeJourneyCookie({
+    name: JOURNEY_COOKIES.actor.name,
+    payload: '203.0.113.7',
+    origin,
+  });
+  expect(
+    readJourneyCookie({
+      cookieHeader: `session=abc; ${header([cookie])}; other=1`,
+      name: JOURNEY_COOKIES.actor.name,
+    })
+  ).toEqual('203.0.113.7');
+});
+
+test.each([
+  ['a wrong token', `lowdefy_journey_mutant=${forgedToken}.run1`],
+  ['a shorter token', 'lowdefy_journey_mutant=abc.run1'],
+  ['a missing separator', `lowdefy_journey_mutant=${journeyActorToken}`],
+  ['only another cookie name', `lowdefy_journey_data=${journeyActorToken}.run1`],
+  ['a cookie whose name only ends in the name', `x_lowdefy_journey_mutant=${journeyActorToken}.r`],
+  ['no cookie header', undefined],
+  ['an empty cookie header', ''],
+])('readJourneyCookie returns null for %s', (_, cookieHeader) => {
+  expect(readJourneyCookie({ cookieHeader, name: JOURNEY_COOKIES.mutant.name })).toBeNull();
+});
+
+test('forwardJourneyCookies joins the verified data and mutant cookies and leaves out the rest', () => {
+  const cookieHeader = header([
+    { name: 'session', value: 'abc' },
+    writeJourneyCookie({ name: JOURNEY_COOKIES.actor.name, payload: '203.0.113.7', origin }),
+    writeJourneyCookie({ name: JOURNEY_COOKIES.recording.name, payload: 'rec', origin }),
+    writeJourneyCookie({ name: JOURNEY_COOKIES.data.name, payload: 'data1', origin }),
+    writeJourneyCookie({ name: JOURNEY_COOKIES.mutant.name, payload: 'mutant1', origin }),
+  ]);
+  expect(forwardJourneyCookies({ cookieHeader })).toEqual(
+    `lowdefy_journey_data=${journeyActorToken}.data1; lowdefy_journey_mutant=${journeyActorToken}.mutant1`
+  );
+});
+
+test('forwardJourneyCookies leaves out a loopback cookie that fails verification', () => {
+  const cookieHeader = header([
+    { name: JOURNEY_COOKIES.data.name, value: `${forgedToken}.data1` },
+    writeJourneyCookie({ name: JOURNEY_COOKIES.mutant.name, payload: 'mutant1', origin }),
+  ]);
+  expect(forwardJourneyCookies({ cookieHeader })).toEqual(
+    `lowdefy_journey_mutant=${journeyActorToken}.mutant1`
+  );
+});
+
+test('forwardJourneyCookies forwards a data session the call opened itself in place of a data cookie', () => {
+  const cookieHeader = header([
+    writeJourneyCookie({ name: JOURNEY_COOKIES.data.name, payload: 'data1', origin }),
+    writeJourneyCookie({ name: JOURNEY_COOKIES.mutant.name, payload: 'mutant1', origin }),
+  ]);
+  expect(forwardJourneyCookies({ cookieHeader, dataSessionId: 'own1' })).toEqual(
+    `lowdefy_journey_data=${journeyActorToken}.own1; lowdefy_journey_mutant=${journeyActorToken}.mutant1`
+  );
+  expect(forwardJourneyCookies({ cookieHeader: undefined, dataSessionId: 'own1' })).toEqual(
+    `lowdefy_journey_data=${journeyActorToken}.own1`
+  );
+});
+
+test('forwardJourneyCookies returns an empty string with no journey cookies', () => {
+  expect(forwardJourneyCookies({ cookieHeader: undefined })).toEqual('');
+  expect(forwardJourneyCookies({ cookieHeader: 'session=abc' })).toEqual('');
+});
+
+// One writer, so a wrapper (data set, mutant) can never drop another's cookie
+// from the detached hop.
+test('createLowdefyContext is the only writer of loopbackHeaders in server-dev', () => {
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+  const writers = [];
+  function walk(directory) {
+    fs.readdirSync(directory, { withFileTypes: true }).forEach((entry) => {
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        walk(entryPath);
+        return;
+      }
+      if (!/\.(js|mjs|jsx)$/.test(entry.name) || /\.test\.mjs$/.test(entry.name)) {
+        return;
+      }
+      if (/loopbackHeaders\s*(=[^=]|\]\s*=|:)/.test(fs.readFileSync(entryPath, 'utf8'))) {
+        writers.push(path.relative(packageRoot, entryPath));
+      }
+    });
+  }
+  ['lib', 'src', 'client', 'manager'].forEach((directory) =>
+    walk(path.join(packageRoot, directory))
+  );
+  expect(writers).toEqual([path.join('lib', 'server', 'createLowdefyContext.js')]);
+});