@lowdefy/server-dev 5.5.1 → 6.0.0

package/src/middleware/errorHandler.test.mjs

@@ -0,0 +1,235 @@
+/*
+  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';
+
+import createErrorHandler from './errorHandler.js';
+
+// This is the only test coverage of the hono 500 redaction path: the file here is
+// byte-identical to its `server` and `server-e2e` counterparts, and `server` has no
+// test script at all. 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;
+}
+
+// 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 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('Top message.');
+  expect(body['~e'].cause.message).toEqual('Cause message.');
+});
+
+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();
+});
+
+// The regression test for the real bug: the four inline `delete` statements this
+// replaces only ever reached depth 0, so a `received` or `stack` on the cause
+// still crossed the wire. The policy is now applied at every error node.
+test('errorHandler omits stack and received from the 500 envelope on the cause at depth 1', async () => {
+  const res = await createApp({
+    error: createErrorWithCause(),
+    logger: createLogger(),
+  }).request('/api/request/getUsers');
+
+  const body = await res.json();
+  expect(body['~e'].cause.stack).toBeUndefined();
+  expect(body['~e'].cause.received).toBeUndefined();
+  expect(JSON.stringify(body)).not.toContain(SECRET);
+});
+
+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.awaited = 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'].awaited).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('Top message.');
+});
+
+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/agent.js

@@ -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 { callAgent } from '@lowdefy/api';
+import { translate, type } from '@lowdefy/helpers';
+
+import getPathSegments from '../lib/getPathSegments.js';
+
+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'));
+  }
+  const segments = getPathSegments(c, '/api/agent/');
+  if (segments.length < 2) {
+    return c.json({ error: t('agent.runtime.invalidPath') }, 400);
+  }
+  const agentId = segments[segments.length - 1];
+  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();
+  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 (sharedState != null && !type.isObject(sharedState)) {
+    return c.json({ error: t('agent.runtime.sharedStateMustBeObject') }, 400);
+  }
+  const { response: webResponse } = await callAgent(context, {
+    agentId,
+    pageId,
+    messages,
+    conversationId: conversationId ?? undefined,
+    sharedState: sharedState ?? undefined,
+    urlQuery: urlQuery ?? undefined,
+  });
+
+  // callAgent returns a Web Response — stream its body straight through.
+  return c.body(webResponse.body, 200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+    'Content-Encoding': 'none',
+  });
+}
+
+export default agentHandler;

package/src/routes/apiPage.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.
+*/
+
+import { getPageConfig } from '@lowdefy/api';
+
+import getPathSegments from '../lib/getPathSegments.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.
+async function apiPageHandler(c) {
+  const context = c.get('lowdefyContext');
+  const pageId = getPathSegments(c, '/api/page/').join('/');
+  // 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 });
+    return c.json({ pageConfig: null }, 404);
+  }
+  context.logger.info({ event: 'api_page_view', pageId });
+  return c.json({ pageConfig });
+}
+
+export default apiPageHandler;

package/src/routes/auth.js

@@ -0,0 +1,49 @@
+/*
+  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 { authHandler } from '@hono/auth-js';
+
+import authJson from '../../lib/build/auth.js';
+import getDevSession from '../../lib/server/auth/getDevSession.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) {
+    if (authJson.configured !== true) {
+      return c.json({ message: 'Auth not configured' }, 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);
+  };
+}
+
+export default authMiddleware;

package/src/routes/auth.test.mjs

@@ -0,0 +1,84 @@
+/*
+  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';
+
+// 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 mockGetDevSession = jest.fn(async () => undefined);
+jest.unstable_mockModule('../../lib/server/auth/getDevSession.js', () => ({
+  default: mockGetDevSession,
+}));
+
+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',
+  };
+  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('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 });
+});

package/src/routes/clientError.js

@@ -0,0 +1,57 @@
+/*
+  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 { logClientError } from '@lowdefy/api';
+
+import clientErrorStore from '../../lib/docs/clientErrorStore.js';
+
+async function clientErrorHandler(c) {
+  if (c.req.method !== 'POST') {
+    throw new Error('Only POST requests are supported.');
+  }
+  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);
+  }
+
+  // Dev keeps `received` in the payload — it powers error tracing in dev tools.
+  const body = await c.req.json();
+  const { error, ...response } = await logClientError(context, body);
+
+  // Feed the agent-facing feedback loop (GET /lowdefy-docs/build-status) with a
+  // serializable summary — not the full error object, which may carry
+  // non-serializable `received` values.
+  clientErrorStore.push({
+    timestamp: new Date().toISOString(),
+    name: error?.name ?? 'Error',
+    message: error?.message ?? null,
+    source: response.source ?? null,
+    config: response.config ?? null,
+  });
+
+  return c.json(response);
+}
+
+export default clientErrorHandler;

package/src/routes/cron.js

@@ -0,0 +1,47 @@
+/*
+  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 { runScheduledEndpoint } from '@lowdefy/api';
+
+import getPathSegments from '../lib/getPathSegments.js';
+
+// Triggered by Vercel Cron in production: an HTTP GET to /api/cron/<endpointId>. Available in dev so
+// scheduled endpoints can be triggered locally with curl. Vercel auto-sends the value of the project
+// env var named exactly CRON_SECRET as `Authorization: Bearer <value>`, and the firing cron
+// expression in the `x-vercel-cron-schedule` header. Fails closed if CRON_SECRET is unset. A request
+// forwarded from the production deployment of another environment (see cronForward.js) also names
+// 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.');
+  }
+  const context = c.get('lowdefyContext');
+
+  const secret = process.env.CRON_SECRET;
+  if (!secret || c.req.header('authorization') !== `Bearer ${secret}`) {
+    context.logger.warn({ event: 'cron_unauthorized' });
+    return c.json({ error: 'Unauthorized' }, 401);
+  }
+
+  const endpointId = getPathSegments(c, '/api/cron/').join('/');
+  const cron = c.req.header('x-vercel-cron-schedule');
+  const environment = c.req.header('x-lowdefy-cron-environment');
+  context.logger.info({ event: 'call_cron_endpoint', endpointId, cron, environment });
+  const response = await runScheduledEndpoint(context, { endpointId, cron, environment });
+  return c.json(response);
+}
+
+export default cronHandler;

package/src/routes/cronForward.js

@@ -0,0 +1,47 @@
+/*
+  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 { forwardScheduledEndpoint } from '@lowdefy/api';
+
+import getPathSegments from '../lib/getPathSegments.js';
+
+// Triggered by Vercel Cron on the production deployment: an HTTP GET to
+// /api/cron-forward/<environment>/<endpointId>, registered by `lowdefy vercel-output` for the
+// schedules of every environment declared with a url in config.cron.environments. Vercel fires crons
+// only on production, so production pings that environment's own /api/cron/<endpointId> (with the
+// environment's CRON_SECRET) and answers immediately. Same transport auth as cron (CRON_SECRET,
+// fails closed).
+async function cronForwardHandler(c) {
+  if (c.req.method !== 'GET') {
+    throw new Error('Only GET requests are supported.');
+  }
+  const context = c.get('lowdefyContext');
+
+  const secret = process.env.CRON_SECRET;
+  if (!secret || c.req.header('authorization') !== `Bearer ${secret}`) {
+    context.logger.warn({ event: 'cron_forward_unauthorized' });
+    return c.json({ error: 'Unauthorized' }, 401);
+  }
+
+  const [environment, ...endpointSegments] = getPathSegments(c, '/api/cron-forward/');
+  const endpointId = endpointSegments.join('/');
+  const cron = c.req.header('x-vercel-cron-schedule');
+  context.logger.info({ event: 'call_cron_forward', environment, endpointId, cron });
+  const response = await forwardScheduledEndpoint(context, { environment, endpointId, cron });
+  return c.json(response);
+}
+
+export default cronForwardHandler;

package/src/routes/detached.js

@@ -0,0 +1,47 @@
+/*
+  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 { runDetachedEndpoint } 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.
+async function detachedHandler(c) {
+  if (c.req.method !== 'POST') {
+    throw new Error('Only POST requests are supported.');
+  }
+  const context = c.get('lowdefyContext');
+
+  const secret = process.env.CRON_SECRET;
+  if (!secret || c.req.header('authorization') !== `Bearer ${secret}`) {
+    context.logger.warn({ event: 'detached_unauthorized' });
+    return c.json({ error: 'Unauthorized' }, 401);
+  }
+
+  const endpointId = getPathSegments(c, '/api/detached/').join('/');
+  const { payload } = await c.req.json();
+  context.logger.info({ event: 'call_detached_endpoint', endpointId });
+  const response = await runDetachedEndpoint(context, { endpointId, payload });
+  return c.json(response);
+}
+
+export default detachedHandler;