mulmoclaude 0.5.2 → 0.6.0

package/server/api/routes/notifications.ts

@@ -23,12 +23,14 @@
 // For a one-shot "fire one of every target kind" run,
 // scripts/dev/fire-sample-notifications.sh drives this endpoint.
 //
-// The route is exported as a factory so the host wiring can inject
-// the pub-sub publisher and the chat-service push handle without
-// this file pulling in either module directly.
+// PR 4 of feat-encore made `publishNotification()` a thin wrapper
+// over the notifier engine, so this route no longer needs injected
+// pubsub / bridge deps — bridge push fans out via the legacy
+// adapter subscribed to the engine, and `scheduleTestNotification`
+// just calls the wrapper.
 
 import { Router, type Request, type Response } from "express";
-import { scheduleTestNotification, type NotificationDeps, type ScheduleNotificationOptions } from "../../events/notifications.js";
+import { scheduleTestNotification, type ScheduleNotificationOptions } from "../../events/notifications.js";
 import { log } from "../../system/logger/index.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
 import {
@@ -37,6 +39,7 @@ import {
   NOTIFICATION_VIEWS,
   type NotificationAction,
   type NotificationKind,
+  type NotificationTarget,
 } from "../../../src/types/notification.js";
 import { isRecord } from "../../utils/types.js";
 
@@ -45,7 +48,6 @@ interface TestRequestBody {
   body?: unknown;
   delaySeconds?: unknown;
   transportId?: unknown;
-  chatId?: unknown;
   kind?: unknown;
   action?: unknown;
 }
@@ -63,22 +65,94 @@ function parseKind(value: unknown): NotificationKind | undefined {
   return KIND_SET.has(value) ? (value as NotificationKind) : undefined;
 }
 
-// Loose validator — dev-facing so we prefer "pass through what looks
-// right" over strict type guards. Only checks that `type` is one of
-// the two known literals and, for navigates, that `target.view` is a
-// known view. The target's other fields are forwarded verbatim so
-// adding new optional fields doesn't require editing this file.
-function parseAction(value: unknown): NotificationAction | undefined {
+// `path` / `slug` / `anchor` / etc. arrive as `unknown` from the JSON
+// body. The URL builders in `legacyActionToNavigateTarget` assume each
+// field is `string | undefined`; passing a number through (e.g.
+// `path: 123`) would crash later inside `setTimeout` — after the 202
+// is sent — when `path.split("/")` runs. So validate per-view here:
+// any required field that isn't a non-empty string, or any optional
+// field that is present but isn't a string, drops the whole action.
+// The notification still fires; it just lands without a click target.
+function isOptionalString(value: unknown): boolean {
+  return value === undefined || typeof value === "string";
+}
+
+function asOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+// Per-view validators — split out so the dispatcher stays under the
+// cognitive-complexity threshold. Each validator returns either the
+// typed target or `undefined` for any field that doesn't match the
+// `src/types/notification.ts` discriminated union.
+
+function validateChatTarget(value: Record<string, unknown>): NotificationTarget | undefined {
+  // sessionId required: chat without it would bounce off the catch-all redirect.
+  if (typeof value.sessionId !== "string" || value.sessionId.length === 0) return undefined;
+  if (!isOptionalString(value.resultUuid)) return undefined;
+  return { view: NOTIFICATION_VIEWS.chat, sessionId: value.sessionId, resultUuid: asOptionalString(value.resultUuid) };
+}
+
+function validateTodosTarget(value: Record<string, unknown>): NotificationTarget | undefined {
+  if (!isOptionalString(value.itemId)) return undefined;
+  return { view: NOTIFICATION_VIEWS.todos, itemId: asOptionalString(value.itemId) };
+}
+
+function validateAutomationsTarget(value: Record<string, unknown>): NotificationTarget | undefined {
+  if (!isOptionalString(value.taskId)) return undefined;
+  return { view: NOTIFICATION_VIEWS.automations, taskId: asOptionalString(value.taskId) };
+}
+
+function validateSourcesTarget(value: Record<string, unknown>): NotificationTarget | undefined {
+  if (!isOptionalString(value.slug)) return undefined;
+  return { view: NOTIFICATION_VIEWS.sources, slug: asOptionalString(value.slug) };
+}
+
+function validateFilesTarget(value: Record<string, unknown>): NotificationTarget | undefined {
+  if (!isOptionalString(value.path)) return undefined;
+  return { view: NOTIFICATION_VIEWS.files, path: asOptionalString(value.path) };
+}
+
+function validateWikiTarget(value: Record<string, unknown>): NotificationTarget | undefined {
+  if (!isOptionalString(value.slug)) return undefined;
+  if (!isOptionalString(value.anchor)) return undefined;
+  return { view: NOTIFICATION_VIEWS.wiki, slug: asOptionalString(value.slug), anchor: asOptionalString(value.anchor) };
+}
+
+function validateNavigateTarget(value: unknown): NotificationTarget | undefined {
+  if (!isRecord(value)) return undefined;
+  if (typeof value.view !== "string" || !VIEW_SET.has(value.view)) return undefined;
+  switch (value.view) {
+    case NOTIFICATION_VIEWS.chat:
+      return validateChatTarget(value);
+    case NOTIFICATION_VIEWS.todos:
+      return validateTodosTarget(value);
+    case NOTIFICATION_VIEWS.calendar:
+      return { view: NOTIFICATION_VIEWS.calendar };
+    case NOTIFICATION_VIEWS.automations:
+      return validateAutomationsTarget(value);
+    case NOTIFICATION_VIEWS.sources:
+      return validateSourcesTarget(value);
+    case NOTIFICATION_VIEWS.files:
+      return validateFilesTarget(value);
+    case NOTIFICATION_VIEWS.wiki:
+      return validateWikiTarget(value);
+    default:
+      return undefined;
+  }
+}
+
+/** Exported for unit tests. Production callers go through
+ *  `createNotificationsRouter` and never see this function directly. */
+export function parseAction(value: unknown): NotificationAction | undefined {
   if (!isRecord(value)) return undefined;
   if (value.type === NOTIFICATION_ACTION_TYPES.none) {
     return { type: NOTIFICATION_ACTION_TYPES.none };
   }
   if (value.type !== NOTIFICATION_ACTION_TYPES.navigate) return undefined;
-  const target = value.target;
-  if (!isRecord(target) || typeof target.view !== "string" || !VIEW_SET.has(target.view)) {
-    return undefined;
-  }
-  return { type: NOTIFICATION_ACTION_TYPES.navigate, target: target as NotificationAction extends { target: infer T } ? T : never };
+  const target = validateNavigateTarget(value.target);
+  if (!target) return undefined;
+  return { type: NOTIFICATION_ACTION_TYPES.navigate, target };
 }
 
 function parseBody(body: TestRequestBody): ScheduleNotificationOptions {
@@ -95,9 +169,6 @@ function parseBody(body: TestRequestBody): ScheduleNotificationOptions {
   if (typeof body.transportId === "string" && body.transportId.length > 0) {
     opts.transportId = body.transportId;
   }
-  if (typeof body.chatId === "string" && body.chatId.length > 0) {
-    opts.chatId = body.chatId;
-  }
   const kind = parseKind(body.kind);
   if (kind) opts.kind = kind;
   const action = parseAction(body.action);
@@ -105,16 +176,15 @@ function parseBody(body: TestRequestBody): ScheduleNotificationOptions {
   return opts;
 }
 
-export function createNotificationsRouter(deps: NotificationDeps): Router {
+export function createNotificationsRouter(): Router {
   const router = Router();
   router.post(API_ROUTES.notifications.test, (req: Request<object, unknown, TestRequestBody>, res: Response<TestResponse>) => {
     const opts = parseBody(req.body ?? {});
-    const scheduled = scheduleTestNotification(opts, deps);
+    const scheduled = scheduleTestNotification(opts);
     log.info("notifications", "scheduled test push", {
       delaySeconds: scheduled.delaySeconds,
       firesAt: scheduled.firesAt,
       transportId: opts.transportId,
-      chatId: opts.chatId,
     });
     res.status(202).json({
       firesAt: scheduled.firesAt,

package/server/api/routes/notifier.ts

@@ -0,0 +1,98 @@
+// Single dispatch endpoint for the host UI's bell popup. Body shape:
+// `{ action: "clear" | "cancel" | "list" | "listHistory", ... }`.
+//
+// Trust boundary — `publish` is INTENTIONALLY not an HTTP action.
+// The only legitimate publishers are in-process: plugins go through
+// `runtime.notifier.publish` (auto-binds `pluginPkg` to the calling
+// plugin's pkg name in `server/plugins/runtime.ts:makeScopedNotifier`)
+// and host-internal modules call `engine.publish` directly. Exposing
+// `publish` over HTTP would let any holder of the bearer token
+// publish under any plugin's namespace, since the route layer cannot
+// authenticate which plugin (if any) made the request — bearer auth
+// only proves "the caller is on this machine and knows the token,"
+// not "the caller is plugin X." If a future feature genuinely needs
+// remote publish, it must arrive with caller-identity headers and a
+// per-pkg auth check; until then this surface is host-UI-only.
+//
+// `clear` / `cancel` are deliberately host-scoped (no `pluginPkg`):
+// the bell popup belongs to the host, sees every plugin's entries,
+// and must be able to dismiss any of them. Plugin-scoped clears (the
+// per-plugin isolation property) live on the in-process runtime API
+// only — `engine.clearForPlugin` is not reachable from this route.
+
+import { Router, type Request, type Response } from "express";
+import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import { cancel, clear, listAll, listHistory } from "../../notifier/engine.js";
+import type { NotifierEntry, NotifierHistoryEntry } from "../../notifier/types.js";
+import { log } from "../../system/logger/index.js";
+
+interface DispatchBody {
+  action?: unknown;
+  // clear / cancel
+  id?: unknown;
+}
+
+type DispatchResponse = { ok: true } | { entries: NotifierEntry[] } | { history: NotifierHistoryEntry[] } | { error: string };
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+const notifierRouter: Router = Router();
+
+notifierRouter.post(API_ROUTES.notifier.dispatch, async (req: Request<object, DispatchResponse, DispatchBody>, res: Response<DispatchResponse>) => {
+  const body = req.body ?? {};
+  const { action } = body;
+  try {
+    switch (action) {
+      case "clear": {
+        if (!isNonEmptyString(body.id)) {
+          res.status(400).json({ error: "id required" });
+          return;
+        }
+        await clear(body.id);
+        res.json({ ok: true });
+        return;
+      }
+      case "cancel": {
+        if (!isNonEmptyString(body.id)) {
+          res.status(400).json({ error: "id required" });
+          return;
+        }
+        await cancel(body.id);
+        res.json({ ok: true });
+        return;
+      }
+      case "list": {
+        const entries = await listAll();
+        res.json({ entries });
+        return;
+      }
+      case "listHistory": {
+        const history = await listHistory();
+        res.json({ history });
+        return;
+      }
+      // `publish` falls through to the default handler. See the
+      // trust-boundary note at the top of this file — exposing it
+      // over HTTP would let any bearer-token holder spoof an
+      // arbitrary `pluginPkg`. Use the in-process runtime API.
+      default:
+        res.status(400).json({ error: `unknown action: ${typeof action === "string" ? action : "<missing>"}` });
+    }
+  } catch (err) {
+    // Detailed error stays in the server log for triage; the HTTP
+    // response gets an opaque message so a parser-thrown filesystem
+    // path / internal stack frame can't leak to the client. Echoing
+    // `String(err)` would have given e.g. `Error: ENOENT, open
+    // '/Users/<...>/active.json'` to anyone holding the bearer token
+    // (CodeRabbit review on PR #1196).
+    log.error("notifier-route", "dispatch failed", {
+      action: typeof action === "string" ? action : "<unknown>",
+      error: String(err),
+    });
+    res.status(500).json({ error: "internal error" });
+  }
+});
+
+export default notifierRouter;

package/server/api/routes/pdf.ts

@@ -8,8 +8,10 @@ import { badRequest, serverError } from "../../utils/httpError.js";
 import { WORKSPACE_DIRS } from "../../workspace/paths.js";
 import { resolveWithinRoot, readBinarySafeSync } from "../../utils/files/safe.js";
 import { resolveWorkspacePath } from "../../utils/files/workspace-io.js";
+import { parseFrontmatter } from "../../utils/markdown/frontmatter.js";
 import { log } from "../../system/logger/index.js";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
+import { transformResolvableUrlsInHtml } from "../../../src/utils/image/htmlSrcAttrs.js";
 
 const router = Router();
 
@@ -58,54 +60,160 @@ const MIME_BY_EXT: Record<string, string> = {
 // inside the workspace after symlink resolution.
 const defaultWorkspaceRoot = realpathSync(resolveWorkspacePath(""));
 
+export interface InlineImagesOptions {
+  /** Workspace root absolute path. Defaults to the lazily-resolved
+   *  realpath of the configured workspace. */
+  workspaceRoot?: string;
+  /** Workspace-relative directory the markdown source lives in,
+   *  used to resolve `../foo.png`-style references. e.g.
+   *  `"data/wiki/pages"` for Wiki page PDFs. Defaults to
+   *  `WORKSPACE_DIRS.markdowns` for legacy callers. Inputs are
+   *  rejected if they're absolute or contain `..` segments — the
+   *  workspace boundary is enforced anyway by `resolveWithinRoot`,
+   *  but rejecting up-front gives a clearer log line than a
+   *  silently-broken image. */
+  sourceDir?: string;
+}
+
+// Tag scanning + attribute iteration live in the shared helper
+// (`src/utils/image/htmlSrcAttrs.ts`) so the Markdown surface
+// (`rewriteImgSrcAttrsInHtml`) and this PDF surface stay in lockstep.
+// Adding a tag / attribute (Stage B's `<source>` / `<video poster>`
+// / `<audio src>`) updates both surfaces with one diff (#1011 Stage B).
+
+function isSafeSourceDir(dir: string): boolean {
+  if (!dir) return true;
+  if (path.isAbsolute(dir)) return false;
+  return !dir.split(/[/\\]/).some((segment) => segment === "..");
+}
+
+// Resolve a workspace-rooted-or-relative `src` value to an absolute
+// path on disk, validated to stay inside the workspace root. Returns
+// null on any failure (escape attempt, missing file, malformed path).
+// Logs the reason so the developer can grep when a PDF image is
+// missing.
+function resolveImageAbsPath(src: string, workspaceRoot: string, baseDir: string): string | null {
+  // Strip query / fragment before any filesystem-level resolution —
+  // a `<img src="foo.png?v=123">` cache-bust must still find the
+  // file at `foo.png` on disk. Without this strip, `path.resolve`
+  // bakes the `?v=123` into the candidate path and the safe-resolve
+  // / readBinarySafeSync reject (codex review iter-2 #1028).
+  const pathPart = urlPathname(src);
+  // LLM-generated HTML often emits leading-slash workspace-rooted
+  // paths like "/artifacts/images/2026/04/foo.png" (web convention).
+  // Treat those as workspace-relative; otherwise path.resolve below
+  // sees the slash as host-absolute and the safe-resolve rejects.
+  const workspaceRooted = pathPart.startsWith("/");
+  const resolveBase = workspaceRooted ? workspaceRoot : baseDir;
+  const relSrc = workspaceRooted ? pathPart.slice(1) : pathPart;
+  const unsafeAbs = path.resolve(resolveBase, relSrc);
+  const relToWorkspace = path.relative(workspaceRoot, unsafeAbs);
+  if (relToWorkspace.startsWith("..") || path.isAbsolute(relToWorkspace)) {
+    log.warn("pdf", "image path escapes workspace", { src });
+    return null;
+  }
+  const abs = resolveWithinRoot(workspaceRoot, relToWorkspace);
+  if (!abs) {
+    log.warn("pdf", "image path rejected by safe-resolve", { src });
+    return null;
+  }
+  return abs;
+}
+
+function loadImageAsDataUri(abs: string): string | null {
+  const buf = readBinarySafeSync(abs);
+  if (!buf) {
+    log.warn("pdf", "could not read image", { abs });
+    return null;
+  }
+  const ext = path.extname(abs).toLowerCase();
+  const mime = MIME_BY_EXT[ext] ?? "application/octet-stream";
+  return `data:${mime};base64,${buf.toString("base64")}`;
+}
+
+// Video / audio extensions Stage B (#1011) added to the rewriter.
+// In PDF rendering puppeteer can't play them, so inlining a large
+// `.mp4` as base64 just blows up the HTML and times out the page
+// load (`Navigation timeout of 30000 ms exceeded`). The `<video
+// poster>` attribute IS an image and stays inlined — that's the
+// only thing the user actually sees in a PDF anyway. The `<video
+// src>` / `<source src>` (in a `<video>`) / `<audio src>` URL is
+// left as the original relative path; puppeteer's fetch will fail
+// quickly and `networkidle0` still resolves.
+//
+// Anchored at end-of-pathname (callers strip query / fragment first
+// via `urlPathname` below) so a query-string-only mention of the
+// extension doesn't false-positive — e.g. `foo.png?clip.mp4` must
+// inline the PNG, not be treated as an mp4 (codex review iter-1).
+const PDF_SKIP_MEDIA_EXT_RE = /\.(mp4|webm|mov|m4v|ogv|mp3|ogg|oga|wav|m4a|aac)$/i;
+
+function urlPathname(url: string): string {
+  const queryStart = url.indexOf("?");
+  const fragStart = url.indexOf("#");
+  const limit = [queryStart, fragStart].filter((idx) => idx >= 0).reduce((min, idx) => Math.min(min, idx), url.length);
+  return url.slice(0, limit);
+}
+
+/** Whether a URL points at a video / audio file that should NOT be
+ *  base64-inlined into a PDF. Exported for direct unit testing —
+ *  filesystem-level resolver checks (`resolveImageAbsPath`) can mask
+ *  the regex's behaviour because a missing file also returns null,
+ *  so the in-line callback's output looks identical for "skip" vs
+ *  "resolve-failed". */
+export function shouldSkipMediaForPdf(url: string): boolean {
+  return PDF_SKIP_MEDIA_EXT_RE.test(urlPathname(url));
+}
+
 /**
- * Inline local images as base64 data URIs so Puppeteer can render them.
- * Markdown files live in workspace/artifacts/documents/ and reference
- * images as "../images/xyz.png" → workspace/artifacts/images/xyz.png.
+ * Inline local images as base64 data URIs so Puppeteer can render
+ * them. Resolves URL-bearing attributes (currently `<img src>`,
+ * `<source src>`, `<video poster|src>`, `<audio src>`) against
+ * `sourceDir` (workspace-relative); for example, a Wiki page
+ * (`data/wiki/pages/X.md`) referencing
+ * `../../../artifacts/images/foo.png` resolves to
+ * `artifacts/images/foo.png`.
+ *
+ * Handles double-quoted, single-quoted, and unquoted values. Skips
+ * `data:` URIs and `http(s)` URLs. Refuses values that escape the
+ * workspace root after resolution — the workspace boundary is
+ * enforced by `resolveWithinRoot`, regardless of `sourceDir`.
  *
- * Paths are validated against the workspace root via resolveWithinRoot
- * so an attacker-controlled <img src="../../../etc/passwd"> can't read
- * files outside the workspace.
+ * Tag + attribute coverage is shared with the browser markdown
+ * surface (`rewriteImgSrcAttrsInHtml`) via `RESOLVABLE_TAG_ATTRS` in
+ * `src/utils/image/htmlSrcAttrs.ts`.
  */
-export function inlineImages(html: string, workspaceRoot: string = defaultWorkspaceRoot): string {
-  const baseDir = path.join(workspaceRoot, WORKSPACE_DIRS.markdowns);
-  return html.replace(/(<img\s[^>]*src=")([^"]+)(")/g, (_match, before: string, src: string, after: string) => {
-    if (src.startsWith("data:") || src.startsWith("http")) {
-      return _match;
-    }
-    // LLM-generated HTML often emits leading-slash workspace-rooted
-    // paths like "/artifacts/images/2026/04/foo.png" (web convention).
-    // Treat those as workspace-relative; otherwise path.resolve below
-    // sees the slash as host-absolute and the safe-resolve rejects.
-    const workspaceRooted = src.startsWith("/");
-    const resolveBase = workspaceRooted ? workspaceRoot : baseDir;
-    const relSrc = workspaceRooted ? src.slice(1) : src;
-    // Resolve the image path relative to markdowns/ (or workspace root
-    // for the leading-slash case) but require the final realpath to
-    // stay inside the workspace root. markdowns/ references like
-    // "../images/foo.png" are common so we can't restrict to markdowns/
-    // itself.
-    const unsafeAbs = path.resolve(resolveBase, relSrc);
-    // Make unsafeAbs relative to the workspace for the
-    // resolveWithinRoot check (it expects a relative path).
-    const relToWorkspace = path.relative(workspaceRoot, unsafeAbs);
-    if (relToWorkspace.startsWith("..") || path.isAbsolute(relToWorkspace)) {
-      log.warn("pdf", "image path escapes workspace", { src });
-      return _match;
-    }
-    const abs = resolveWithinRoot(workspaceRoot, relToWorkspace);
-    if (!abs) {
-      log.warn("pdf", "image path rejected by safe-resolve", { src });
-      return _match;
-    }
-    const buf = readBinarySafeSync(abs);
-    if (!buf) {
-      log.warn("pdf", "could not read image", { abs });
-      return _match;
-    }
-    const ext = path.extname(abs).toLowerCase();
-    const mime = MIME_BY_EXT[ext] ?? "application/octet-stream";
-    return `${before}data:${mime};base64,${buf.toString("base64")}${after}`;
+export function inlineImages(html: string, options: InlineImagesOptions = {}): string {
+  const workspaceRoot = options.workspaceRoot ?? defaultWorkspaceRoot;
+  // Defensive type guard: a malformed request body could send
+  // `baseDir: null` / `baseDir: 42` / etc. Coerce anything non-
+  // string to undefined so the legacy default kicks in instead of
+  // `path.join` throwing on a non-string.
+  const requestedDir = typeof options.sourceDir === "string" ? options.sourceDir : undefined;
+  // Distinguish "explicitly empty" (= workspace root, e.g. a top-
+  // level `README.md`) from "absent" (= legacy `markdowns/` default
+  // for chat callers). Without this, the `||` collapse would route
+  // every workspace-root file through the legacy default.
+  const hasRequestedDir = requestedDir !== undefined;
+  const dirIsSafe = !hasRequestedDir || isSafeSourceDir(requestedDir);
+  if (hasRequestedDir && !dirIsSafe) {
+    log.warn("pdf", "rejecting unsafe sourceDir, falling back to default", { sourceDir: requestedDir });
+  }
+  const sourceDir = dirIsSafe && hasRequestedDir ? requestedDir : WORKSPACE_DIRS.markdowns;
+  const baseDir = path.join(workspaceRoot, sourceDir);
+  return transformResolvableUrlsInHtml(html, (url) => {
+    // Narrow to exact `http://` / `https://` prefixes so a relative
+    // path like `http-assets/logo.png` isn't misclassified as
+    // external (CR follow-up on #1023).
+    if (url.startsWith("data:") || url.startsWith("http://") || url.startsWith("https://")) return null;
+    // Skip media (mp4 / mp3 / webm / ...) — see PDF_SKIP_MEDIA_EXT_RE
+    // comment. `<video poster="x.png">` still inlines because the
+    // poster value's pathname ends in an image extension. The
+    // pathname slice means `foo.png?cacheBust=clip.mp4` correctly
+    // routes through the PNG inline path (codex iter-1).
+    if (shouldSkipMediaForPdf(url)) return null;
+    const abs = resolveImageAbsPath(url, workspaceRoot, baseDir);
+    if (!abs) return null;
+    return loadImageAsDataUri(abs);
   });
 }
 
@@ -147,10 +255,41 @@ interface PdfMarkdownBody {
   markdown: string;
   filename?: string;
   format?: "Letter" | "A4";
+  /** Workspace-relative source directory of the markdown (e.g.
+   *  `"data/wiki/pages"` for Wiki pages). Used to resolve relative
+   *  `<img>` references against the right base. Omit for the legacy
+   *  `markdowns/` default. Validated server-side; absolute paths
+   *  and `..` segments are rejected. */
+  baseDir?: string;
+  /** When true, strip a leading YAML frontmatter envelope before
+   *  rendering so `title:` / `tags:` etc don't appear as plain text
+   *  on page 1 of the PDF. Wiki pages use this. Markdown / Text
+   *  Response callers omit (default false) so a chat-generated
+   *  document that *literally* starts with `---\n…\n---\n` is
+   *  preserved verbatim. */
+  stripFrontmatter?: boolean;
 }
 
 router.post(API_ROUTES.pdf.markdown, async (req: Request<object, unknown, PdfMarkdownBody>, res: Response) => {
-  const { markdown, filename = "document.pdf", format = "Letter" } = req.body;
+  const { body } = req;
+  // Express only sets `req.body` after `express.json()` parses a JSON
+  // payload. A client that sends raw JSON `null`, an array, or omits
+  // the body entirely would land here with body = null / [] / undefined,
+  // and the per-field guards below would throw on the first property
+  // dereference. Bail out cleanly with a 400 instead.
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    badRequest(res, "request body must be a JSON object");
+    return;
+  }
+  // Defensive type guards: a malformed JSON body could send
+  // `baseDir: null` / `stripFrontmatter: "yes"` / etc. Coerce
+  // anything off-shape to its safe default rather than letting a
+  // downstream `path.join` / boolean check throw.
+  const markdown = typeof body.markdown === "string" ? body.markdown : "";
+  const filename = typeof body.filename === "string" ? body.filename : "document.pdf";
+  const format: "Letter" | "A4" = body.format === "A4" ? "A4" : "Letter";
+  const baseDir = typeof body.baseDir === "string" ? body.baseDir : undefined;
+  const stripFrontmatter = body.stripFrontmatter === true;
 
   if (!markdown) {
     badRequest(res, "markdown is required");
@@ -158,8 +297,9 @@ router.post(API_ROUTES.pdf.markdown, async (req: Request<object, unknown, PdfMar
   }
 
   try {
-    log.info("pdf", "markdown", { filename, length: markdown.length });
-    const html = inlineImages(await marked.parse(markdown));
+    log.info("pdf", "markdown", { filename, length: markdown.length, baseDir, stripFrontmatter });
+    const source = stripFrontmatter ? parseFrontmatter(markdown).body : markdown;
+    const html = inlineImages(await marked.parse(source), { sourceDir: baseDir });
     const buffer = await renderPdf(wrapHtml(html, MARKDOWN_CSS), format);
     sendPdf(res, buffer, filename);
   } catch (err) {