dsh-tiddlywiki 0.19.2 → 0.19.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-tiddlywiki",
   "description": "TiddlyWiki 5 as the DSH persistent knowledge base: fifteen tiddlywiki_* agent tools (filtered search/recent/tags/batch/rewrite/trash/lint + git sync & conflict resolve), a full TiddlyWiki editor embedded in the GUI center column (same-origin proxy, works over Tailscale/LAN/domain), a right-side wiki tab, a per-session summary tab, a quick-note card with draft auto-save behind a single knowledge FAB, an optional clip bookmarklet that also saves selected images as attachments, and git-based sync with auto-commit. Mounts via the official dsh plugin system — no DSH source changes.",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "type": "module",
   "keywords": [
     "dsh",
@@ -85,7 +85,7 @@
     "smoke:client": "node scripts/smoke-client.mjs",
     "selftest": "node scripts/selftest.mjs",
     "verify:static": "node scripts/verify-send-to-agent-bundle.mjs && node scripts/verify-render-bundle.mjs && node scripts/verify-package-contents.mjs && node scripts/verify-version-consistency.mjs",
-    "verify:unit": "node scripts/verify-clip-bridge.mjs && node scripts/verify-seed-error-policy.mjs && node scripts/verify-render-sanitizer.mjs",
+    "verify:unit": "node scripts/verify-clip-bridge.mjs && node scripts/verify-seed-error-policy.mjs && node scripts/verify-render-sanitizer.mjs && node scripts/verify-secret-masking.mjs",
     "verify:e2e": "node scripts/verify-auth.mjs && node scripts/verify-tools.mjs && node scripts/verify-git-resolve.mjs && node scripts/verify-resilience.mjs",
     "verify:large": "node scripts/verify-large-wiki.mjs",
     "verify": "npm run verify:static && npm run verify:unit && npm run verify:e2e",

package/src/client/settings-page.ts

@@ -267,13 +267,13 @@ function renderConfigSection(body: HTMLElement, config: Record<string, unknown>,
   const sendToAgent = (ui.sendToAgent ?? {}) as Record<string, unknown>
   checkField('ui.sendToAgent.enabled', '启用「发送给 Agent」（TW 笔记 → DSH 会话注入）', sendToAgent.enabled !== false)
   textField('ui.sendToAgent.endpoint', 'TW 端请求基址（空=自动取当前 DSH origin）', typeof sendToAgent.endpoint === 'string' ? sendToAgent.endpoint : '')
-  textField('ui.sendToAgent.token', '共享 token（非空时路由校验 x-send-to-agent-token 头）', typeof sendToAgent.token === 'string' ? sendToAgent.token : '')
+  textField('ui.sendToAgent.token', '共享 token（非空时路由校验 x-send-to-agent-token 头；已设置时显示为 ********，原样保存=不改，清空=删除）', typeof sendToAgent.token === 'string' ? sendToAgent.token : '')
   const allArticles = (ui.allArticles ?? {}) as Record<string, unknown>
   numField('ui.allArticles.pageSize', '「所有文章」每页条数', typeof allArticles.pageSize === 'number' ? allArticles.pageSize : 10)
   const bridge = (config.bridge ?? {}) as Record<string, unknown>
   checkField('bridge.enabled', '启用「本地剪藏桥」（书签小工具后端监听 127.0.0.1 端口，保存后立即生效）', bridge.enabled === true)
   numField('bridge.port', '剪藏桥端口（改端口需重启 dsh web 生效）', typeof bridge.port === 'number' && bridge.port > 0 ? bridge.port : 8618)
-  textField('bridge.token', '剪藏桥 token（非空时校验书签的 x-clip-token 头；强烈建议设置）', typeof bridge.token === 'string' ? bridge.token : '')
+  textField('bridge.token', '剪藏桥 token（非空时校验书签的 x-clip-token 头；强烈建议设置。已设置时显示为 ********，原样保存=不改，清空=删除）', typeof bridge.token === 'string' ? bridge.token : '')
   textField('bridge.tag', '剪藏笔记默认 tag', typeof bridge.tag === 'string' && bridge.tag.trim().length > 0 ? bridge.tag.trim() : 'clip')
   // 界面语言在下方「语言管理」区块设置（config 的 uiLanguage 仅供启动时自动应用）。
   // 注意：uiLanguage 目前只影响 TW 侧语言，客户端插件文案（FAB/快速笔记/侧边栏/本页）

package/src/host/admin.ts

@@ -24,7 +24,7 @@ import type { TiddlyWebClient } from './tw-api.ts'
 import type { WikiServer } from './wiki.ts'
 import { ROUTE_PREFIX, redactLogLines, redactRemoteUrl, type WebServerFace } from './routes.ts'
 import { CONFIG_TIDDLER, type ConfigStore, type PluginConfigShape } from './config.ts'
-import { readBody, json, rejectCrossSiteWrite, rejectNonRead } from './http.ts'
+import { readBody, json, guardHandler, errorStatus, rejectCrossSiteWrite, rejectNonRead } from './http.ts'
 import { waitForFileWrite, needsRestartAfterSeeds, flushPendingWrites } from './seeds.ts'
 import { RENDER_PLUGIN_FILE } from './seed-render.ts'
 import { GitFace } from './git.ts'
@@ -85,21 +85,28 @@ export async function readWikiInfo(wikiPath: string): Promise<WikiInfo> {
     }
     throw new Error(`读取 tiddlywiki.info 失败：${err instanceof Error ? err.message : String(err)}`)
   }
-  let parsed: Partial<WikiInfo>
+  let parsed: unknown
   try {
-    parsed = JSON.parse(raw) as Partial<WikiInfo>
+    parsed = JSON.parse(raw)
   } catch {
     throw new Error('tiddlywiki.info 不是合法 JSON；请先修复该文件再保存设置（已保留原文件）')
   }
+  // A top-level `null`/array/primitive is NOT a valid tiddlywiki.info; the old
+  // code spread it and crashed with "Cannot read properties of null" (a
+  // confusing 500 instead of the intended readable error).
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('tiddlywiki.info 顶层不是对象；请先修复该文件再保存设置（已保留原文件）')
+  }
+  const obj = parsed as Partial<WikiInfo>
   return {
     // Spread FIRST, then the normalized fields: the old order let a literal
     // `"plugins": null` (or a non-array) overwrite the `[]` default and crash
     // every consumer with `.includes is not a function`.
-    ...parsed,
-    description: parsed.description,
-    plugins: Array.isArray(parsed.plugins) ? parsed.plugins : [],
-    themes: Array.isArray(parsed.themes) ? parsed.themes : [],
-    languages: Array.isArray(parsed.languages) ? parsed.languages : [],
+    ...obj,
+    description: obj.description,
+    plugins: Array.isArray(obj.plugins) ? obj.plugins : [],
+    themes: Array.isArray(obj.themes) ? obj.themes : [],
+    languages: Array.isArray(obj.languages) ? obj.languages : [],
   }
 }
 
@@ -297,6 +304,79 @@ export interface AdminDeps {
   }
 }
 
+/**
+ * Sentinel returned instead of a stored secret (`bridge.token` /
+ * `ui.sendToAgent.token`) by `GET /admin/state` and by `POST /admin/config`'s
+ * echo. `/admin/*` is an unauthenticated surface (only CSRF-hardened), and the
+ * config tiddler legitimately carries shared tokens — handing them to any
+ * caller of the loopback/LAN-reachable GUI is a real leak (v0.19.3). The
+ * settings page renders the sentinel verbatim; posting it back is a no-op
+ * (`stripMaskedSecrets` drops it), so the real value never leaves the host.
+ */
+export const MASKED_SECRET = '********'
+
+/** Mask secrets (and credentials inside the git remote URL) for an HTTP caller. */
+export function maskConfigSecrets(config: PluginConfigShape): PluginConfigShape {
+  const bridge = (config.bridge ?? {}) as Record<string, unknown>
+  const ui = (config.ui ?? {}) as Record<string, unknown>
+  const sendToAgent = (ui.sendToAgent ?? {}) as Record<string, unknown>
+  const git = (config.git ?? {}) as Record<string, unknown>
+  const maskToken = (value: unknown): string => (typeof value === 'string' && value.length > 0 ? MASKED_SECRET : '')
+  return {
+    ...config,
+    git: { ...git, remote: typeof git.remote === 'string' ? redactRemoteUrl(git.remote) : git.remote },
+    bridge: {
+      ...bridge,
+      token: maskToken(bridge.token),
+      tokenSet: typeof bridge.token === 'string' && bridge.token.length > 0,
+    },
+    ui: {
+      ...ui,
+      sendToAgent: {
+        ...sendToAgent,
+        token: maskToken(sendToAgent.token),
+        tokenSet: typeof sendToAgent.token === 'string' && sendToAgent.token.length > 0,
+      },
+    },
+  } as PluginConfigShape
+}
+
+/**
+ * Drop the masked placeholders from an incoming config patch so saving the
+ * settings page never overwrites a stored secret with `********` (or the
+ * redacted git remote with `https://***@…`). `bridge.token`/`ui.sendToAgent.token`
+ * are cleared only when the caller actually sends an empty string.
+ */
+export function stripMaskedSecrets<T extends Record<string, unknown>>(patch: T, current: PluginConfigShape): T {
+  const copy = { ...patch } as Record<string, unknown>
+  const cleanToken = (container: unknown): unknown => {
+    if (typeof container !== 'object' || container === null) return container
+    const obj = { ...(container as Record<string, unknown>) }
+    if (obj.token === MASKED_SECRET) delete obj.token
+    delete obj.tokenSet
+    return obj
+  }
+  if (copy.bridge !== undefined) copy.bridge = cleanToken(copy.bridge)
+  if (copy.ui !== undefined) {
+    const ui = typeof copy.ui === 'object' && copy.ui !== null
+      ? { ...(copy.ui as Record<string, unknown>) }
+      : copy.ui
+    if (typeof ui === 'object' && ui !== null && (ui as Record<string, unknown>).sendToAgent !== undefined) {
+      ;(ui as Record<string, unknown>).sendToAgent = cleanToken((ui as Record<string, unknown>).sendToAgent)
+    }
+    copy.ui = ui
+  }
+  if (copy.git !== undefined && typeof copy.git === 'object' && copy.git !== null) {
+    const git = { ...(copy.git as Record<string, unknown>) }
+    const storedRemote = typeof current.git?.remote === 'string' ? current.git.remote : ''
+    if (typeof git.remote === 'string' && storedRemote.length > 0 && git.remote === redactRemoteUrl(storedRemote)) {
+      delete git.remote
+    }
+    copy.git = git
+  }
+  return copy as T
+}
+
 export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: AdminDeps): () => void {
   const handleState = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     try {
@@ -317,7 +397,7 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
         server: { ...view, logs: redactLogLines(view.logs) },
         info: { plugins: info.plugins, themes: info.themes, languages: info.languages ?? [] },
         catalog,
-        config: deps.config.get(),
+        config: maskConfigSecrets(deps.config.get()),
         git,
       })
     } catch (err) {
@@ -343,6 +423,10 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
       const catalog = await bundledCatalog(deps.twRoot())
       const known = new Set([...catalog.plugins, ...catalog.themes].map((c) => c.name))
       const knownLangs = new Set(catalog.languages.map((c) => c.name))
+      /** Snapshot for the no-op guard below (JSON compare is enough here). */
+      const beforeInfo = JSON.stringify(info)
+      /** Set only when the request carried a themes array with a resolvable active pick. */
+      let activatedTheme: string | undefined
       const applyList = (field: 'plugins' | 'themes', raw: unknown): string[] => {
         if (!Array.isArray(raw)) return info[field]
         const next: string[] = []
@@ -367,45 +451,58 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
         }
         return next
       }
-      info.plugins = applyList('plugins', body.plugins)
-      // Activate the chosen theme: load its full dependency chain AND set
-      // `$:/theme` so the browser's themeManager actually applies it (the
-      // `themes` array alone only makes the plugin available).
-      let activatedTheme: string | undefined
-      if (Array.isArray(body.themes)) {
-        const themeDeps: Record<string, string[]> = {}
-        for (const theme of catalog.themes) {
-          if (theme.dependents && theme.dependents.length > 0) themeDeps[theme.name] = theme.dependents
-        }
-        let selected = applyList('themes', body.themes)
-        // Explicit active-theme pick (new two-layer UI): validate and auto-add
-        // it to the loaded set so its dependency closure is loaded. Without an
-        // explicit pick, activate the deepest loaded overlay (old single-radio).
-        const explicitActive = typeof body.themeActive === 'string' && body.themeActive.length > 0
-        if (explicitActive) {
-          const activeName = body.themeActive as string
-          if (known.has(activeName) || info.themes.includes(activeName)) {
-            if (!selected.includes(activeName)) selected.push(activeName)
-            activatedTheme = activeName
+      // Validation + in-memory mutation only: a rejected name must NOT touch
+      // tiddlywiki.info (400 straight out), while a failure of the write/restart
+      // below is an internal error (500) — the old code reported both as 400.
+      try {
+        info.plugins = applyList('plugins', body.plugins)
+        // Activate the chosen theme: load its full dependency chain AND set
+        // `$:/theme` so the browser's themeManager actually applies it (the
+        // `themes` array alone only makes the plugin available).
+        if (Array.isArray(body.themes)) {
+          const themeDeps: Record<string, string[]> = {}
+          for (const theme of catalog.themes) {
+            if (theme.dependents && theme.dependents.length > 0) themeDeps[theme.name] = theme.dependents
           }
+          const selected = applyList('themes', body.themes)
+          // Explicit active-theme pick (new two-layer UI): validate and auto-add
+          // it to the loaded set so its dependency closure is loaded. Without an
+          // explicit pick, activate the deepest loaded overlay (old single-radio).
+          const explicitActive = typeof body.themeActive === 'string' && body.themeActive.length > 0
+          if (explicitActive) {
+            const activeName = body.themeActive as string
+            if (known.has(activeName) || info.themes.includes(activeName)) {
+              if (!selected.includes(activeName)) selected.push(activeName)
+              activatedTheme = activeName
+            }
+          }
+          info.themes = normalizeThemes(selected, themeDeps)
+          if (activatedTheme === undefined && info.themes.length > 0) {
+            activatedTheme = info.themes[info.themes.length - 1]
+          }
+        } else {
+          info.themes = applyList('themes', body.themes)
         }
-        info.themes = normalizeThemes(selected, themeDeps)
-        if (activatedTheme === undefined && info.themes.length > 0) {
-          activatedTheme = info.themes[info.themes.length - 1]
-        }
-      } else {
-        info.themes = applyList('themes', body.themes)
+        if (Array.isArray(body.languages)) info.languages = applyLanguages(body.languages)
+      } catch (err) {
+        json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 400)
+        return
+      }
+      // NO-OP GUARD (v0.19.3): a body that changes nothing (e.g. `{}`, or the
+      // same lists re-sent) used to rewrite tiddlywiki.info + restart TW — a
+      // visible TW interruption for a request that asked for nothing.
+      const changed = JSON.stringify(info) !== beforeInfo
+      if (changed) {
+        await writeWikiInfo(wikiPath, info)
+        await deps.server.restart()
       }
-      if (Array.isArray(body.languages)) info.languages = applyLanguages(body.languages)
-      await writeWikiInfo(wikiPath, info)
-      await deps.server.restart()
       // Activate the chosen theme tiddler (mirrors TW's own Control Panel).
-      if (activatedTheme !== undefined) {
+      if (Array.isArray(body.themes) && activatedTheme !== undefined) {
         const client = deps.getClient()
         if (client !== undefined) {
           await client
             .put({ title: '$:/theme', text: `$:/themes/${activatedTheme}`, type: 'text/vnd.tiddlywiki', tags: [] })
-            .catch(() => undefined)
+            .catch((err) => { console.warn('[dsh-tiddlywiki] activating theme failed:', err) })
         }
       }
       // After a languages change, pin the active language tiddler: first
@@ -416,7 +513,8 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
         if (client !== undefined) {
           const langs = info.languages ?? []
           const active = langs.length > 0 ? `$:/languages/${langs[0]}` : '$:/languages/en-GB'
-          await client.put({ title: '$:/language', text: active, type: 'text/plain', tags: [] }).catch(() => undefined)
+          await client.put({ title: '$:/language', text: active, type: 'text/plain', tags: [] })
+            .catch((err) => { console.warn('[dsh-tiddlywiki] pinning $:/language failed:', err) })
           // Keep the startup auto-apply hint (config uiLanguage) consistent with
           // the active language, so a later dsh-web restart doesn't re-enable
           // a language the user just disabled here.
@@ -426,9 +524,9 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
           }
         }
       }
-      json(res, { ok: true, info: { plugins: info.plugins, themes: info.themes, languages: info.languages ?? [] } })
+      json(res, { ok: true, changed, info: { plugins: info.plugins, themes: info.themes, languages: info.languages ?? [] } })
     } catch (err) {
-      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 400)
+      json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 500)
     }
   }
 
@@ -441,8 +539,10 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
         json(res, { ok: false, error: 'wiki service is not running' }, 503)
         return
       }
-      await deps.config.set(client, body)
-      json(res, { ok: true, config: deps.config.get() })
+      // Never persist the masked placeholders the page read back from /state
+      // (v0.19.3): saving an untouched form must not clobber a real token.
+      await deps.config.set(client, stripMaskedSecrets(body as Record<string, unknown>, deps.config.get()) as PluginConfigShape)
+      json(res, { ok: true, config: maskConfigSecrets(deps.config.get()) })
     } catch (err) {
       json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, 400)
     }
@@ -552,14 +652,15 @@ export function registerAdminRoutes(ctx: { webServer: WebServerFace }, deps: Adm
     }
   }
 
+  // Same rejection safety net as routes.ts (v0.19.3).
   const disposers = [
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/state`, handler: (req, res) => { void handleState(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/info`, handler: (req, res) => { void handleInfo(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/config`, handler: (req, res) => { void handleConfig(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/restart`, handler: (req, res) => { void handleRestart(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/seeds`, handler: (req, res) => { void handleSeeds(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/seeds/run`, handler: (req, res) => { void handleSeedsRun(req, res) } }),
-    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/seeds/remove`, handler: (req, res) => { void handleSeedsRemove(req, res) } }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/state`, handler: guardHandler(handleState) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/info`, handler: guardHandler(handleInfo) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/config`, handler: guardHandler(handleConfig) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/restart`, handler: guardHandler(handleRestart) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/seeds`, handler: guardHandler(handleSeeds) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/seeds/run`, handler: guardHandler(handleSeedsRun) }),
+    ctx.webServer.register({ kind: 'exact', path: `${ROUTE_PREFIX}/admin/seeds/remove`, handler: guardHandler(handleSeedsRemove) }),
   ]
   return () => {
     for (const dispose of disposers) dispose()

package/src/host/clip-bridge.ts

@@ -137,8 +137,14 @@ const PRIVATE_V4_PATTERNS = [
   /^169\.254\./, // link-local (cloud metadata 169.254.169.254)
   /^172\.(1[6-9]|2\d|3[01])\./, // private
   /^192\.0\.0\./, // IETF protocol assignments
+  /^192\.0\.2\./, // TEST-NET-1
+  /^192\.88\.99\./, // 6to4 relay anycast
   /^192\.168\./, // private
-  /^198\.1[89]\./, // benchmarking
+  /^198\.1[89]\./, // benchmarking 198.18/15
+  /^198\.51\.100\./, // TEST-NET-2
+  /^203\.0\.113\./, // TEST-NET-3
+  /^22[4-9]\./, /^23\d\./, // multicast 224/4
+  /^24\d\./, /^25[0-5]\./, // reserved 240/4 (incl. 255.255.255.255 broadcast)
 ]
 
 /** Parse a dotted-quad IPv4 into 4 bytes, or null. */
@@ -659,6 +665,13 @@ export class ClipBridge {
       }
       const onListening = (): void => {
         server.removeListener('error', onError)
+        // Replace the bind-time handler with a PERMANENT one (v0.19.3): without
+        // any 'error' listener a later server error (e.g. EMFILE/ECONNRESET on a
+        // accept) is an unhandled 'error' event → Node throws → the whole dsh
+        // web process dies. Log and keep serving.
+        server.on('error', (err: Error) => {
+          this.deps.log?.(`server error after listen: ${err.message}`)
+        })
         const addr = server.address() as AddressInfo
         this.boundPort = addr.port
         resolve()
@@ -675,8 +688,22 @@ export class ClipBridge {
     this.server = undefined
     this.boundPort = 0
     if (server === undefined) return Promise.resolve()
+    // `server.close()` only resolves once every open connection ends, and the
+    // bookmarklet's keep-alive socket can hold it open forever — the effect
+    // disposer (plugin unload) would then hang (v0.19.3). Force-close the
+    // connections and cap the wait.
     return new Promise<void>((resolve) => {
-      server.close(() => resolve())
+      let done = false
+      const finish = (): void => {
+        if (done) return
+        done = true
+        resolve()
+      }
+      try {
+        ;(server as unknown as { closeAllConnections?: () => void }).closeAllConnections?.()
+      } catch { /* not available on this Node */ }
+      server.close(() => finish())
+      setTimeout(finish, 1_000).unref?.()
     })
   }
 

package/src/host/http.ts

@@ -75,6 +75,41 @@ export function json(res: ServerResponse, payload: unknown, status = 200): void
   res.end(JSON.stringify(payload))
 }
 
+/**
+ * Map a thrown error to an HTTP status. Oversized bodies are a client problem
+ * (413), everything else is ours (500) — the routes used to answer 500 for
+ * `/note` and `/admin/*` but 413 for `/upload` for the identical condition.
+ */
+export function errorStatus(err: unknown): number {
+  const message = err instanceof Error ? err.message : String(err)
+  return /body too large/i.test(message) ? 413 : 500
+}
+
+/** The route-handler shape the registries take. */
+export type RouteHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>
+
+/**
+ * Wrap an async route handler so a rejected promise can never become an
+ * unhandled rejection (v0.19.3).
+ *
+ * WHY: every registration used to be `void handleX(req, res)`, and the host
+ * installs no `unhandledRejection` handler — Node's default policy then EXITS
+ * the whole dsh web process, while the client request hangs with no response.
+ * A handler that throws (including a sync throw before its own try block, e.g.
+ * `new URL(req.url)` outside the try in the proxies) now always ends in a
+ * response: 413/500 JSON, or a bare `end()` when headers are already sent.
+ */
+export function guardHandler(handler: RouteHandler): (req: IncomingMessage, res: ServerResponse) => void {
+  return (req, res) => {
+    void handler(req, res).catch((err) => {
+      try {
+        if (!res.headersSent) json(res, { ok: false, error: err instanceof Error ? err.message : String(err) }, errorStatus(err))
+        else res.end()
+      } catch { /* response already gone */ }
+    })
+  }
+}
+
 /**
  * True when a NON-GET/HEAD/OPTIONS request is a cross-site (CSRF) request.
  *