@lowdefy/server-dev 6.0.0 → 7.0.0

package/src/middleware/errorHandler.test.mjs

@@ -15,13 +15,14 @@
 */
 
 import { Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
 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.
+// The handler here is byte-identical to its `server-e2e` counterpart (and to
+// `server`'s apart from the Sentry capture, which `server` tests separately).
+// Keep the three in sync when changing any of them.
 
 // A string that must never reach a client. It is put on `received` at every
 // level of the cause chain, so a single JSON.stringify search over the body
@@ -55,6 +56,27 @@ function createAuthenticationError(message) {
   return error;
 }
 
+function createAuthorizationError(message) {
+  const error = new Error(message);
+  error.name = 'AuthorizationError';
+  error.received = SECRET;
+  return error;
+}
+
+function createTwoFactorEnrolmentRequiredError(message) {
+  const error = new Error(message);
+  error.name = 'TwoFactorEnrolmentRequiredError';
+  error.received = SECRET;
+  return error;
+}
+
+function createUserError(message) {
+  const error = new Error(message);
+  error.name = 'UserError';
+  error.received = SECRET;
+  return error;
+}
+
 // Two Error levels, each with a stack (every Error has one) and a recognisable
 // `received`, plus a configKey the policy keeps.
 function createErrorWithCause() {
@@ -105,6 +127,154 @@ test('errorHandler returns text Unauthorized at 401 for an AuthenticationError o
   expect(logger.warn).toHaveBeenCalledTimes(1);
 });
 
+test('errorHandler returns 403 with only name and message for an AuthorizationError on an api path', async () => {
+  const logger = createLogger();
+  const context = { handleError: jest.fn() };
+  const res = await createApp({
+    context,
+    error: createAuthorizationError('Forbidden.'),
+    logger,
+  }).request('/api/request/getUsers');
+
+  expect(res.status).toEqual(403);
+  expect(await res.json()).toEqual({ name: 'AuthorizationError', message: 'Forbidden.' });
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.warn.mock.calls[0][0]).toMatch(/Forbidden: GET \/api\/request\/getUsers/);
+  expect(logger.error).not.toHaveBeenCalled();
+  expect(context.handleError).not.toHaveBeenCalled();
+});
+
+test('errorHandler does not send an AuthorizationError through the redactor', async () => {
+  const res = await createApp({
+    error: createAuthorizationError('Forbidden.'),
+    logger: createLogger(),
+  }).request('/api/request/getUsers');
+
+  const body = await res.json();
+  expect(body['~e']).toBeUndefined();
+  expect(JSON.stringify(body)).not.toContain(SECRET);
+});
+
+test('errorHandler returns text Forbidden at 403 for an AuthorizationError on a page path', async () => {
+  const logger = createLogger();
+  const res = await createApp({
+    error: createAuthorizationError('Forbidden.'),
+    logger,
+  }).request('/home');
+
+  expect(res.status).toEqual(403);
+  expect(await res.text()).toEqual('Forbidden');
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.error).not.toHaveBeenCalled();
+});
+
+test('errorHandler returns 403 with only name and message for a TwoFactorEnrolmentRequiredError on an api path', async () => {
+  const logger = createLogger();
+  const context = { handleError: jest.fn() };
+  const res = await createApp({
+    context,
+    error: createTwoFactorEnrolmentRequiredError('Two-factor enrolment required.'),
+    logger,
+  }).request('/api/request/getUsers');
+
+  expect(res.status).toEqual(403);
+  expect(await res.json()).toEqual({
+    name: 'TwoFactorEnrolmentRequiredError',
+    message: 'Two-factor enrolment required.',
+  });
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.warn.mock.calls[0][0]).toMatch(/Two-factor enrolment required/);
+  expect(logger.error).not.toHaveBeenCalled();
+  expect(context.handleError).not.toHaveBeenCalled();
+});
+
+test('errorHandler does not send a TwoFactorEnrolmentRequiredError through the redactor', async () => {
+  const res = await createApp({
+    error: createTwoFactorEnrolmentRequiredError('Two-factor enrolment required.'),
+    logger: createLogger(),
+  }).request('/api/request/getUsers');
+
+  const body = await res.json();
+  expect(body['~e']).toBeUndefined();
+});
+
+test('errorHandler returns text at 403 for a TwoFactorEnrolmentRequiredError on a page path', async () => {
+  const logger = createLogger();
+  const context = { handleError: jest.fn() };
+  const res = await createApp({
+    context,
+    error: createTwoFactorEnrolmentRequiredError('Two-factor enrolment required.'),
+    logger,
+  }).request('/home');
+
+  expect(res.status).toEqual(403);
+  expect(await res.text()).toEqual('Two-factor enrolment required');
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(context.handleError).not.toHaveBeenCalled();
+});
+
+test('errorHandler returns 400 with only name and message for a UserError on an api path', async () => {
+  const logger = createLogger();
+  const context = { handleError: jest.fn() };
+  const res = await createApp({
+    context,
+    error: createUserError('Payload for endpoint "x" does not match its payloadSchema.'),
+    logger,
+  }).request('/api/endpoints/x', { method: 'POST' });
+
+  expect(res.status).toEqual(400);
+  expect(await res.json()).toEqual({
+    name: 'UserError',
+    message: 'Payload for endpoint "x" does not match its payloadSchema.',
+  });
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.warn.mock.calls[0][0]).toMatch(/Bad request: POST \/api\/endpoints\/x/);
+  expect(logger.error).not.toHaveBeenCalled();
+  expect(context.handleError).not.toHaveBeenCalled();
+});
+
+test('errorHandler does not send a UserError through the redactor', async () => {
+  const res = await createApp({
+    error: createUserError('Bad payload.'),
+    logger: createLogger(),
+  }).request('/api/endpoints/x');
+
+  const body = await res.json();
+  expect(body['~e']).toBeUndefined();
+  expect(JSON.stringify(body)).not.toContain(SECRET);
+});
+
+test('errorHandler returns text Bad Request at 400 for a UserError on a page path', async () => {
+  const logger = createLogger();
+  const res = await createApp({
+    error: createUserError('Bad payload.'),
+    logger,
+  }).request('/home');
+
+  expect(res.status).toEqual(400);
+  expect(await res.text()).toEqual('Bad Request');
+  expect(logger.warn).toHaveBeenCalledTimes(1);
+  expect(logger.error).not.toHaveBeenCalled();
+});
+
+test('errorHandler sends an HTTPException response as-is with one warning and no error log', async () => {
+  const logger = createLogger();
+  const error = new HTTPException(404, {
+    res: Response.json(
+      { jsonrpc: '2.0', error: { code: -32000, message: 'Unsupported protocol version' } },
+      { status: 404 }
+    ),
+  });
+  const res = await createApp({ error, logger }).request('/api/mcp', { method: 'POST' });
+  expect(res.status).toEqual(404);
+  expect(await res.json()).toEqual({
+    jsonrpc: '2.0',
+    error: { code: -32000, message: 'Unsupported protocol version' },
+  });
+  expect(logger.warn).toHaveBeenCalledWith('404 answered by the route: POST /api/mcp');
+  expect(logger.error).not.toHaveBeenCalled();
+});
+
 test('errorHandler returns 500 with the serialized error envelope on an api path', async () => {
   const res = await createApp({
     error: createErrorWithCause(),
@@ -114,8 +284,8 @@ test('errorHandler returns 500 with the serialized error envelope on an api path
   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.');
+  expect(body['~e'].message).toEqual('Something went wrong.');
+  expect(body['~e'].cause).toBeUndefined();
 });
 
 test('errorHandler omits stack and received from the 500 envelope at the top level', async () => {
@@ -129,19 +299,31 @@ test('errorHandler omits stack and received from the 500 envelope at the top lev
   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 () => {
+test('errorHandler omits the cause chain from the 500 envelope', async () => {
   const res = await createApp({
     error: createErrorWithCause(),
     logger: createLogger(),
   }).request('/api/request/getUsers');
 
   const body = await res.json();
-  expect(body['~e'].cause.stack).toBeUndefined();
-  expect(body['~e'].cause.received).toBeUndefined();
+  expect(body['~e'].cause).toBeUndefined();
   expect(JSON.stringify(body)).not.toContain(SECRET);
+  expect(JSON.stringify(body)).not.toContain('Cause message.');
+});
+
+test('errorHandler adds devError with the full error to the 500 envelope in dev mode', async () => {
+  const context = { handleError: jest.fn(), mode: 'dev', rid: 'rid-1' };
+  const res = await createApp({
+    context,
+    error: createErrorWithCause(),
+    logger: createLogger(),
+  }).request('/api/request/getUsers');
+
+  const body = await res.json();
+  expect(body['~e'].message).toEqual('Something went wrong.');
+  expect(body.devError['~e'].message).toEqual('Top message.');
+  expect(body.devError['~e'].requestId).toEqual('rid-1');
+  expect(body.devError['~e'].cause.message).toEqual('Cause message.');
 });
 
 test('errorHandler keeps configKey on the 500 envelope so the fault can be located in config', async () => {
@@ -168,7 +350,7 @@ test('errorHandler awaits context.handleError before serializing the response',
   const context = {
     handleError: jest.fn(async (error) => {
       await new Promise((resolve) => setTimeout(resolve, 10));
-      error.awaited = true;
+      error.handled = true;
     }),
   };
   const error = createErrorWithCause();
@@ -179,7 +361,7 @@ test('errorHandler awaits context.handleError before serializing the response',
   expect(context.handleError).toHaveBeenCalledTimes(1);
   expect(context.handleError).toHaveBeenCalledWith(error);
   const body = await res.json();
-  expect(body['~e'].awaited).toBe(true);
+  expect(body['~e'].handled).toBe(true);
 });
 
 // createHandleError sets error.handled once it has logged. The client reads it
@@ -220,7 +402,7 @@ test('errorHandler treats a basePath prefixed api path as an api path', async ()
 
   expect(res.status).toEqual(500);
   const body = await res.json();
-  expect(body['~e'].message).toEqual('Top message.');
+  expect(body['~e'].message).toEqual('Something went wrong.');
 });
 
 test('errorHandler treats a basePath prefixed page path as a page path', async () => {

package/src/middleware/isRebindingSafeHost.js

@@ -0,0 +1,44 @@
+/*
+  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 net from 'net';
+
+import { type } from '@lowdefy/helpers';
+
+function getHostname(host) {
+  const trimmed = host.trim();
+  if (trimmed.startsWith('[')) {
+    return trimmed.slice(1, trimmed.indexOf(']'));
+  }
+  return trimmed.split(':')[0];
+}
+
+// Whether a Host header is one DNS rebinding cannot produce - the rule Vite's
+// dev server applies to every HTTP request: an IP address, localhost or a
+// *.localhost name. A page that rebinds its own domain to this machine still
+// sends that domain as the Host. A request with no Host is not a browser's.
+function isRebindingSafeHost({ host }) {
+  if (type.isNone(host)) {
+    return true;
+  }
+  const hostname = getHostname(host).toLowerCase();
+  if (net.isIP(hostname) !== 0) {
+    return true;
+  }
+  return hostname === 'localhost' || hostname.endsWith('.localhost');
+}
+
+export default isRebindingSafeHost;

package/src/middleware/isRebindingSafeHost.test.mjs

@@ -0,0 +1,32 @@
+/*
+  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 isRebindingSafeHost from './isRebindingSafeHost.js';
+
+test.each([
+  ['localhost:4100', true],
+  ['LOCALHOST', true],
+  ['app.localhost:4100', true],
+  ['127.0.0.1:4100', true],
+  ['192.168.1.20', true],
+  ['[::1]:4100', true],
+  [undefined, true],
+  ['rebound.test:4100', false],
+  ['localhost.rebound.test', false],
+  ['127.0.0.1.rebound.test', false],
+])('isRebindingSafeHost(%s) is %s', (host, expected) => {
+  expect(isRebindingSafeHost({ host })).toBe(expected);
+});

package/src/middleware/localDevToolsOnly.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 createSameOriginGuard from './createSameOriginGuard.js';
+
+// The dev tools under /lowdefy-docs run requests, endpoints and journeys
+// against real connections, and several accept a CORS-simple request (a
+// text/plain POST, a GET with query parameters) - so without this any website
+// the developer visits could drive them. The guard refuses a request a
+// browser marks cross-site or same-site, and one whose Origin is not this
+// server. Agents and curl send neither header and pass. DNS rebinding never
+// reaches here: Vite's host check refuses a Host that is not local first.
+const guardSameOrigin = createSameOriginGuard({ allowNoOrigin: true });
+
+function localDevToolsOnly() {
+  return async function localDevToolsOnlyMiddleware(c, next) {
+    const refusal = guardSameOrigin(c);
+    if (refusal !== null) {
+      return refusal;
+    }
+    await next();
+  };
+}
+
+export default localDevToolsOnly;

package/src/middleware/localDevToolsOnly.test.mjs

@@ -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 { Hono } from 'hono';
+
+import localDevToolsOnly from './localDevToolsOnly.js';
+
+function request({ headers, method = 'POST' }) {
+  const app = new Hono();
+  app.use('/lowdefy-docs/*', localDevToolsOnly());
+  app.all('/lowdefy-docs/run-endpoint', (c) => c.json({ allowed: true }));
+  return app.request('/lowdefy-docs/run-endpoint', { headers, method });
+}
+
+test.each([
+  ['an agent or curl calls with no origin', { host: 'localhost:4102' }],
+  [
+    'the dev app page calls its own server',
+    { host: 'localhost:4102', origin: 'http://localhost:4102', 'sec-fetch-site': 'same-origin' },
+  ],
+])('localDevToolsOnly allows the request when %s', async (_, headers) => {
+  const res = await request({ headers });
+  expect(res.status).toEqual(200);
+});
+
+test.each([
+  [
+    'a page on another site posts text/plain to localhost',
+    {
+      host: 'localhost:4102',
+      origin: 'https://attacker.example',
+      'sec-fetch-site': 'cross-site',
+      'content-type': 'text/plain',
+    },
+  ],
+  [
+    'a page on another site loads a GET with no origin',
+    { host: 'localhost:4102', 'sec-fetch-site': 'cross-site' },
+  ],
+  [
+    'a page on another localhost port calls in',
+    { host: 'localhost:4102', origin: 'http://localhost:3000', 'sec-fetch-site': 'same-site' },
+  ],
+  ['the origin is opaque', { host: 'localhost:4102', origin: 'null' }],
+])('localDevToolsOnly refuses the request when %s', async (_, headers) => {
+  const res = await request({ headers });
+  expect(res.status).toEqual(403);
+});

package/src/middleware/noStore.js

@@ -0,0 +1,27 @@
+/*
+  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.
+*/
+
+// Pages and API responses carry the caller's data, so neither the browser nor a
+// shared proxy may store them. Set after next() so redirects and error responses
+// carry it too.
+function noStore() {
+  return async function noStoreMiddleware(c, next) {
+    await next();
+    c.header('Cache-Control', 'private, no-store');
+  };
+}
+
+export default noStore;

package/src/middleware/noStore.test.mjs

@@ -0,0 +1,48 @@
+/*
+  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 noStore from './noStore.js';
+
+function createApp() {
+  const app = new Hono();
+  app.use('/api/page/*', noStore());
+  app.get('/api/page/:pageId', (c) => c.json({ pageId: c.req.param('pageId') }));
+  app.use('/api/fail/*', noStore());
+  app.get('/api/fail/:id', () => {
+    throw new Error('Request failed.');
+  });
+  app.get('/icon.svg', (c) => c.body('<svg></svg>'));
+  app.onError((error, c) => c.json({ error: error.message }, 500));
+  return app;
+}
+
+test('noStore sets Cache-Control private, no-store on the routes it is registered for', async () => {
+  const res = await createApp().request('/api/page/home');
+  expect(res.headers.get('cache-control')).toEqual('private, no-store');
+});
+
+test('noStore sets Cache-Control on an error response', async () => {
+  const res = await createApp().request('/api/fail/1');
+  expect(res.status).toEqual(500);
+  expect(res.headers.get('cache-control')).toEqual('private, no-store');
+});
+
+test('noStore leaves other routes alone', async () => {
+  const res = await createApp().request('/icon.svg');
+  expect(res.headers.get('cache-control')).toBeNull();
+});

package/src/middleware/requestTimeout.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 { HTTPException } from 'hono/http-exception';
+import { timeout } from 'hono/timeout';
+
+// Caps how long a request may run, and cancels the work it leaves behind. The 504 is
+// answered while the handler is still running; the TimeoutError on the request's
+// timeout signal (which apiContext folds into context.signal) cancels the upstream
+// calls the handler is waiting on, such as an AI provider call, instead of letting
+// them run, and bill, after the response has gone.
+function requestTimeout({ timeoutMs }) {
+  return function requestTimeoutMiddleware(c, next) {
+    const controller = new AbortController();
+    c.set('requestTimeoutSignal', controller.signal);
+    return timeout(timeoutMs, () => {
+      controller.abort(
+        new DOMException(`The request timeout of ${timeoutMs}ms was exceeded.`, 'TimeoutError')
+      );
+      return new HTTPException(504, { message: 'Gateway Timeout' });
+    })(c, next);
+  };
+}
+
+export default requestTimeout;

package/src/middleware/staleFlag.js

@@ -0,0 +1,76 @@
+/*
+  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 getStaleStatus from '../../lib/docs/getStaleStatus.js';
+
+// Marks every /lowdefy-docs response while the last dev build failed, so an
+// agent reading a page config or a schema is told the answer comes from the
+// previous build rather than from its own edits. One mechanical hook for the
+// whole route group — the MCP surface has its own in createDocsMcpServer.
+function staleFlag() {
+  return async function staleFlagMiddleware(c, next) {
+    await next();
+    // The build manager rewrites buildStatus.json while the server is
+    // answering, so a half-written artifact is a real race — flagging must
+    // never be the reason a docs response fails.
+    let status;
+    try {
+      status = getStaleStatus();
+    } catch {
+      return;
+    }
+    if (type.isNone(status)) return;
+
+    // The headers carry the flag on every content type, including the ones
+    // whose body is left alone below.
+    c.res.headers.set('X-Lowdefy-Stale', 'true');
+    if (!type.isNone(status.staleSince)) {
+      c.res.headers.set('X-Lowdefy-Stale-Since', status.staleSince);
+    }
+
+    const contentType = c.res.headers.get('Content-Type') ?? '';
+
+    if (contentType.includes('application/json')) {
+      const body = await c.res.clone().json();
+      // A JSON array body would have to change shape to carry a field, and
+      // shape stability beats uniformity here — the headers still flag it.
+      if (!type.isObject(body)) return;
+      const merged = { ...body };
+      // Never overwrite a key the handler already set.
+      for (const key of ['stale', 'staleSince', 'staleReason']) {
+        if (!(key in merged)) merged[key] = status[key];
+      }
+      c.res = new Response(JSON.stringify(merged), {
+        status: c.res.status,
+        headers: c.res.headers,
+      });
+      return;
+    }
+
+    if (contentType.includes('text/markdown')) {
+      const body = await c.res.clone().text();
+      c.res = new Response(`> STALE: ${status.staleReason}\n\n${body}`, {
+        status: c.res.status,
+        headers: c.res.headers,
+      });
+    }
+    // Every other content type (PNG screenshots, plain text) is left untouched.
+  };
+}
+
+export default staleFlag;