@lowdefy/server-dev 6.1.0 → 7.1.0

package/src/middleware/staleFlag.test.mjs

@@ -0,0 +1,127 @@
+/*
+  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 { Hono } from 'hono';
+
+// The middleware reads build/buildStatus.json from process.cwd() via
+// readBuildArtifact — point it at a throwaway server directory before import.
+const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-stale-mw-test-'));
+fs.mkdirSync(path.join(fixtureDir, 'build'));
+process.chdir(fixtureDir);
+
+const statusPath = path.join(fixtureDir, 'build', 'buildStatus.json');
+
+function setBuildFailed() {
+  fs.writeFileSync(
+    statusPath,
+    JSON.stringify({ status: 'error', timestamp: '2026-02-03T04:05:06.000Z', errors: [] })
+  );
+}
+
+function setBuildOk() {
+  fs.writeFileSync(
+    statusPath,
+    JSON.stringify({ status: 'ok', timestamp: '2026-02-03T04:05:06.000Z', errors: [] })
+  );
+}
+
+const { default: staleFlag } = await import('./staleFlag.js');
+
+function createApp() {
+  const app = new Hono();
+  // Mirrors src/app.js: the MCP transport is registered BEFORE the middleware
+  // so its JSON-RPC envelopes are never given extra members.
+  app.post('/lowdefy-docs/mcp', (c) => c.json({ jsonrpc: '2.0', id: 1, result: {} }));
+  app.use('/lowdefy-docs/*', staleFlag());
+  app.get('/lowdefy-docs/object', (c) => c.json({ pageId: 'home', blocks: [] }));
+  app.get('/lowdefy-docs/own-stale', (c) => c.json({ stale: false, staleSince: 'handler' }));
+  app.get('/lowdefy-docs/array', (c) => c.json([{ type: 'Button' }]));
+  app.get('/lowdefy-docs/markdown', (c) =>
+    c.text('# Overview\n', 200, { 'Content-Type': 'text/markdown; charset=UTF-8' })
+  );
+  app.get('/lowdefy-docs/png', (c) =>
+    c.body(new Uint8Array([1, 2, 3]), 200, { 'Content-Type': 'image/png' })
+  );
+  return app;
+}
+
+test('staleFlag merges the stale fields into a JSON object body when the build failed', async () => {
+  setBuildFailed();
+  const res = await createApp().request('/lowdefy-docs/object');
+  const body = await res.json();
+  expect(body.pageId).toEqual('home');
+  expect(body.stale).toBe(true);
+  expect(body.staleSince).toEqual('2026-02-03T04:05:06.000Z');
+  expect(body.staleReason).toContain('The last build failed.');
+  expect(res.headers.get('X-Lowdefy-Stale')).toEqual('true');
+  expect(res.headers.get('X-Lowdefy-Stale-Since')).toEqual('2026-02-03T04:05:06.000Z');
+});
+
+test('staleFlag never overwrites a stale key the handler already set', async () => {
+  setBuildFailed();
+  const res = await createApp().request('/lowdefy-docs/own-stale');
+  const body = await res.json();
+  expect(body.stale).toBe(false);
+  expect(body.staleSince).toEqual('handler');
+  expect(body.staleReason).toContain('The last build failed.');
+});
+
+test('staleFlag leaves a JSON array body unchanged but still sets the headers', async () => {
+  setBuildFailed();
+  const res = await createApp().request('/lowdefy-docs/array');
+  expect(await res.json()).toEqual([{ type: 'Button' }]);
+  expect(res.headers.get('X-Lowdefy-Stale')).toEqual('true');
+  expect(res.headers.get('X-Lowdefy-Stale-Since')).toEqual('2026-02-03T04:05:06.000Z');
+});
+
+test('staleFlag prepends a banner to a markdown body when the build failed', async () => {
+  setBuildFailed();
+  const res = await createApp().request('/lowdefy-docs/markdown');
+  const body = await res.text();
+  expect(body.startsWith('> STALE: The last build failed.')).toBe(true);
+  expect(body).toContain('# Overview');
+  expect(res.headers.get('X-Lowdefy-Stale')).toEqual('true');
+});
+
+test('staleFlag leaves other content types untouched but still sets the headers', async () => {
+  setBuildFailed();
+  const res = await createApp().request('/lowdefy-docs/png');
+  expect(new Uint8Array(await res.arrayBuffer())).toEqual(new Uint8Array([1, 2, 3]));
+  expect(res.headers.get('X-Lowdefy-Stale')).toEqual('true');
+});
+
+test('staleFlag changes nothing when the last build succeeded', async () => {
+  setBuildOk();
+  const app = createApp();
+  const jsonRes = await app.request('/lowdefy-docs/object');
+  expect(await jsonRes.json()).toEqual({ pageId: 'home', blocks: [] });
+  expect(jsonRes.headers.get('X-Lowdefy-Stale')).toBe(null);
+  const markdownRes = await app.request('/lowdefy-docs/markdown');
+  expect(await markdownRes.text()).toEqual('# Overview\n');
+});
+
+// MCP results carry their own STALE notice from createDocsMcpServer; a
+// JSON-RPC envelope must not gain unknown top-level members.
+test('staleFlag does not touch a route registered before it, such as the MCP transport', async () => {
+  setBuildFailed();
+  const res = await createApp().request('/lowdefy-docs/mcp', { method: 'POST' });
+  expect(await res.json()).toEqual({ jsonrpc: '2.0', id: 1, result: {} });
+  expect(res.headers.get('X-Lowdefy-Stale')).toBe(null);
+});

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/auth.js

@@ -14,35 +14,44 @@
   limitations under the License.
 */
 
-import { authHandler } from '@hono/auth-js';
+import { handleAuthRequest } from '@lowdefy/api';
+import { type } from '@lowdefy/helpers';
 
 import authJson from '../../lib/build/auth.js';
-import getDevSession from '../../lib/server/auth/getDevSession.js';
+import getAuth from '../../lib/server/auth/getAuth.js';
+import getClientAddress from '../../lib/server/getClientAddress.js';
+import getMockUser from '../../lib/server/auth/getMockUser.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. BetterAuth rate-limits by the client address
+// getClientAddress resolves.
+function authMiddleware({ logger }) {
+  return async function auth(c) {
     if (authJson.configured !== true) {
       return c.json({ message: 'Auth not configured' }, 404);
     }
+    if (getMockUser()) {
+      // Mock user active - no auth engine runs; the get-session stub in
+      // app.js is the only auth endpoint.
+      return c.json({ message: 'Auth engine disabled while dev.mockUser is active' }, 404);
+    }
+    if (!type.isNone(c.get('lowdefyContext')?.dataSet)) {
+      // A journey on a data set: the auth engine is bound to the app's real auth database, so its
+      // browser contexts never reach it. Data set users are injected callers; the get-session stub
+      // in app.js answers for them.
+      return c.json({ message: 'Auth engine disabled for journeys on a data set' }, 404);
+    }
     if (c.req.method === 'HEAD') {
       return c.body(null, 200);
     }
-    // Dev sessions (mock user, headless renderer cookie) exist outside
-    // Auth.js. getDevSession is the same function the server request
-    // context uses (lib/server/auth/session.js), so the session the browser
-    // client sees here is identical to the one requests authenticate with.
-    if (c.req.method === 'GET' && c.req.path.endsWith('/api/auth/session')) {
-      const devSession = await getDevSession(c);
-      if (devSession) {
-        return c.json(devSession);
-      }
-    }
-    return handler(c, next);
+    return handleAuthRequest({
+      auth: getAuth({ logger }),
+      request: c.req.raw,
+      clientAddress: getClientAddress(c),
+    });
   };
 }
 

package/src/routes/auth.test.mjs

@@ -14,71 +14,45 @@
   limitations under the License.
 */
 
-import { Hono } from 'hono';
 import { jest } from '@jest/globals';
 
-// Only the route wiring is under test here — getDevSession's own behaviour
-// (mock/headless resolution, session-callback parity) is covered in
-// lib/server/auth/getDevSession.test.mjs, and the real Auth.js engine is
-// stubbed with a sentinel handler so "delegated to Auth.js" is observable.
-const mockAuthHandler = jest.fn(() => (c) => c.json({ delegated: true }));
-jest.unstable_mockModule('@hono/auth-js', () => ({
-  authHandler: mockAuthHandler,
-}));
-jest.unstable_mockModule('../../lib/build/auth.js', () => ({
-  default: { configured: true },
+const handleAuthRequest = jest.fn(async () => new Response('engine'));
+const getAuth = jest.fn(() => ({}));
+
+jest.unstable_mockModule('@lowdefy/api', () => ({ handleAuthRequest }));
+jest.unstable_mockModule('../../lib/build/auth.js', () => ({ default: { configured: true } }));
+jest.unstable_mockModule('../../lib/server/auth/getAuth.js', () => ({ default: getAuth }));
+jest.unstable_mockModule('../../lib/server/auth/getMockUser.js', () => ({
+  default: jest.fn(() => undefined),
 }));
-const mockGetDevSession = jest.fn(async () => undefined);
-jest.unstable_mockModule('../../lib/server/auth/getDevSession.js', () => ({
-  default: mockGetDevSession,
+jest.unstable_mockModule('../../lib/server/getClientAddress.js', () => ({
+  default: jest.fn(() => '127.0.0.1'),
 }));
 
 const { default: authMiddleware } = await import('./auth.js');
 
-function createApp() {
-  const app = new Hono();
-  app.use('/api/auth/*', authMiddleware());
-  return app;
-}
-
-afterEach(() => {
-  mockGetDevSession.mockReset();
-  mockGetDevSession.mockResolvedValue(undefined);
-});
-
-test('GET /api/auth/session returns the dev session so the client matches the server', async () => {
-  const devSession = {
-    user: {
-      id: 'dev-mock-user',
-      roles: ['admin'],
-      global_attributes: { company_ids: ['C-1'] },
-    },
-    hashed_id: 'abc',
-    expires: '2100-01-01T00:00:00.000Z',
+function createHonoContext({ context }) {
+  return {
+    get: (key) => (key === 'lowdefyContext' ? context : undefined),
+    json: (body, status) => ({ body, status }),
+    body: (body, status) => ({ body, status }),
+    req: { method: 'POST', raw: new Request('http://localhost/api/auth/sign-out') },
   };
-  mockGetDevSession.mockResolvedValue(devSession);
-
-  const res = await createApp().request('/api/auth/session');
-  expect(res.status).toEqual(200);
-  expect(await res.json()).toEqual(devSession);
-});
-
-test('GET /api/auth/session delegates to Auth.js when no dev session exists', async () => {
-  const res = await createApp().request('/api/auth/session');
-  expect(res.status).toEqual(200);
-  expect(await res.json()).toEqual({ delegated: true });
-});
-
-test('other auth routes delegate to Auth.js even when a dev session exists', async () => {
-  mockGetDevSession.mockResolvedValue({ user: { id: 'mock' } });
+}
 
-  const res = await createApp().request('/api/auth/csrf');
-  expect(await res.json()).toEqual({ delegated: true });
+test('authMiddleware refuses a data-session request without reaching the auth engine', async () => {
+  const handler = authMiddleware({ logger: {} });
+  const result = await handler(createHonoContext({ context: { dataSet: 'staging-sample' } }));
+  expect(result).toEqual({
+    body: { message: 'Auth engine disabled for journeys on a data set' },
+    status: 404,
+  });
+  expect(getAuth).not.toHaveBeenCalled();
+  expect(handleAuthRequest).not.toHaveBeenCalled();
 });
 
-test('POST /api/auth/session delegates to Auth.js even when a dev session exists', async () => {
-  mockGetDevSession.mockResolvedValue({ user: { id: 'mock' } });
-
-  const res = await createApp().request('/api/auth/session', { method: 'POST' });
-  expect(await res.json()).toEqual({ delegated: true });
+test('authMiddleware hands a request with no data session to the auth engine', async () => {
+  const handler = authMiddleware({ logger: {} });
+  await handler(createHonoContext({ context: {} }));
+  expect(handleAuthRequest).toHaveBeenCalledTimes(1);
 });

package/src/routes/clientError.js

@@ -14,30 +14,29 @@
   limitations under the License.
 */
 
-import { logClientError } from '@lowdefy/api';
+import { logClientError, parseRequestBody } from '@lowdefy/api';
 
 import clientErrorStore from '../../lib/docs/clientErrorStore.js';
+import errorRecordingStamp from '../../lib/server/recording/errorRecordingStamp.js';
+import createSameOriginGuard from '../middleware/createSameOriginGuard.js';
+
+const guardSameOrigin = createSameOriginGuard();
 
 async function clientErrorHandler(c) {
   if (c.req.method !== 'POST') {
-    throw new Error('Only POST requests are supported.');
+    // 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: 'Method not allowed.' }, 405);
   }
   const context = c.get('lowdefyContext');
 
-  const origin = c.req.header('origin');
-  if (!origin) {
-    return c.json({ error: 'Forbidden' }, 403);
-  }
-  try {
-    if (new URL(origin).host !== c.req.header('host')) {
-      return c.json({ error: 'Forbidden' }, 403);
-    }
-  } catch {
-    return c.json({ error: 'Forbidden' }, 403);
+  const forbidden = guardSameOrigin(c);
+  if (forbidden) {
+    return forbidden;
   }
 
   // Dev keeps `received` in the payload — it powers error tracing in dev tools.
-  const body = await c.req.json();
+  const body = parseRequestBody({ text: await c.req.text() });
   const { error, ...response } = await logClientError(context, body);
 
   // Feed the agent-facing feedback loop (GET /lowdefy-docs/build-status) with a
@@ -49,6 +48,7 @@ async function clientErrorHandler(c) {
     message: error?.message ?? null,
     source: response.source ?? null,
     config: response.config ?? null,
+    recording: errorRecordingStamp(context.recording),
   });
 
   return c.json(response);

package/src/routes/cron.js

@@ -26,7 +26,9 @@ import getPathSegments from '../lib/getPathSegments.js';
 // the environment whose schedules apply in `x-lowdefy-cron-environment`.
 async function cronHandler(c) {
   if (c.req.method !== 'GET') {
-    throw new Error('Only GET requests are supported.');
+    // 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: 'Method not allowed.' }, 405);
   }
   const context = c.get('lowdefyContext');
 

package/src/routes/cronForward.js

@@ -26,7 +26,9 @@ import getPathSegments from '../lib/getPathSegments.js';
 // fails closed).
 async function cronForwardHandler(c) {
   if (c.req.method !== 'GET') {
-    throw new Error('Only GET requests are supported.');
+    // 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: 'Method not allowed.' }, 405);
   }
   const context = c.get('lowdefyContext');
 

package/src/routes/detached.js

@@ -14,23 +14,34 @@
   limitations under the License.
 */
 
-import { runDetachedEndpoint } from '@lowdefy/api';
+import { acceptDetachedEndpoint, parseRequestBody } from '@lowdefy/api';
 
 import getPathSegments from '../lib/getPathSegments.js';
 
 // Target of a CallApi step with `detached: true`: the calling invocation
 // fire-and-forgets a POST here, so the endpoint runs in its OWN function
 // invocation with a fresh duration budget (chainable bounded work without a
-// queue). Same transport auth as cron (CRON_SECRET, fails closed) and the same
-// system execution context — InternalApi endpoints are callable, `_user` is
-// undefined. Delivery is at-most-once with no retry: targets must be
-// idempotent.
+// queue). Transport auth is CRON_SECRET (fails closed), which proves the
+// request originated from the deployment. The run carries the DISPATCHER'S
+// identity (Decision 4): the request body carries a server-built principal
+// snapshot that runDetachedEndpoint rehydrates, so nested calls authorize
+// against the dispatcher, not a forced system context. Delivery is at-most-once
+// with no retry: targets must be idempotent.
+//
+// The route answers 202 as soon as the call is authorized and parsed; the
+// endpoint runs after the response under this invocation's waitUntil
+// (acceptDetachedEndpoint). The dispatcher is therefore released at once
+// instead of staying alive - and billed - until the target's routine ends.
 async function detachedHandler(c) {
   if (c.req.method !== 'POST') {
-    throw new Error('Only POST requests are supported.');
+    // 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: 'Method not allowed.' }, 405);
   }
   const context = c.get('lowdefyContext');
 
+  // The secret gate stays first: an external POST without the secret is
+  // rejected before the body (and its principal assertion) is ever read.
   const secret = process.env.CRON_SECRET;
   if (!secret || c.req.header('authorization') !== `Bearer ${secret}`) {
     context.logger.warn({ event: 'detached_unauthorized' });
@@ -38,10 +49,12 @@ async function detachedHandler(c) {
   }
 
   const endpointId = getPathSegments(c, '/api/detached/').join('/');
-  const { payload } = await c.req.json();
+  const { credentials, payload, principal } = parseRequestBody({ text: await c.req.text() });
   context.logger.info({ event: 'call_detached_endpoint', endpointId });
-  const response = await runDetachedEndpoint(context, { endpointId, payload });
-  return c.json(response);
+  return c.json(
+    acceptDetachedEndpoint(context, { credentials, endpointId, payload, principal }),
+    202
+  );
 }
 
 export default detachedHandler;

package/src/routes/devInspect.js

@@ -14,7 +14,8 @@
   limitations under the License.
 */
 
-import { serializer } from '@lowdefy/helpers';
+import { parseRequestBody } from '@lowdefy/api';
+import { serializer, type } from '@lowdefy/helpers';
 
 import { readCheckpoint } from '../../lib/docs/checkpointStore.js';
 import { loadMocks } from '../../lib/docs/devMockRegistry.js';
@@ -62,15 +63,21 @@ function handleCheckpointBootstrap(c, { name }) {
   );
 }
 
-// Inspector.jsx posts { tabId, pageId } here whenever its tab navigates, so
-// the tab registry (lib/docs/tabChannel.js) knows which page each connected
-// tab is on without the tab reconnecting its event stream.
+// Inspector.jsx posts { tabId, pageId, pathParams, instanceKey } here whenever
+// the page instance on screen in its tab changes, so the tab registry
+// (lib/docs/tabChannel.js) knows which instance each connected tab shows, and
+// which it has rendered, without the tab reconnecting its event stream.
 async function handleTabPage(c) {
-  const { tabId, pageId } = await c.req.json();
+  const { tabId, pageId, pathParams, instanceKey } = parseRequestBody({
+    text: await c.req.text(),
+  });
   if (!tabId) {
     return c.json({ error: 'Missing "tabId".' }, 400);
   }
-  updateTabPage({ id: tabId, pageId });
+  if (!type.isString(pageId) || !type.isString(instanceKey)) {
+    return c.json({ error: 'Missing "pageId" or "instanceKey".' }, 400);
+  }
+  updateTabPage({ id: tabId, pageId, pathParams, instanceKey });
   return c.json({ ok: true });
 }
 
@@ -89,7 +96,9 @@ async function devInspectHandler(c) {
   }
 
   if (c.req.method !== 'POST') {
-    throw new Error('Only GET and POST requests are supported.');
+    // 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: 'Method not allowed.' }, 405);
   }
 
   if (!checkOrigin(c)) {
@@ -100,7 +109,7 @@ async function devInspectHandler(c) {
     return handleTabPage(c);
   }
 
-  const { requestId, result } = await c.req.json();
+  const { requestId, result } = parseRequestBody({ text: await c.req.text() });
   if (!requestId) {
     return c.json({ error: 'Missing "requestId".' }, 400);
   }