trekoon 0.4.0 → 0.4.2

package/src/board/server.ts

@@ -2,12 +2,12 @@ import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, extname, resolve } from "node:path";
 
+import { createBoardEventBus, type BoardEventBus } from "./event-bus";
 import { createBoardApiHandler } from "./routes";
-import { buildBoardSnapshot } from "./snapshot";
+import { startWalWatcher, type WalWatcher } from "./wal-watcher";
 
 import { openTrekoonDatabase, type TrekoonDatabase } from "../storage/database";
 import { resolveStoragePaths } from "../storage/path";
-import { TrackerDomain } from "../domain/tracker-domain";
 
 const CONTENT_TYPES: Record<string, string> = {
   ".css": "text/css; charset=utf-8",
@@ -93,6 +93,35 @@ function buildBoardSessionCookie(token: string): string {
   return `trekoon_board_session=${encodeURIComponent(token)}; Path=/; SameSite=Strict; HttpOnly`;
 }
 
+function readBoardSessionCookie(request: Request): string | null {
+  const rawCookie = request.headers.get("cookie");
+  if (!rawCookie) {
+    return null;
+  }
+
+  for (const part of rawCookie.split(";")) {
+    const [name, ...valueParts] = part.split("=");
+    if (name?.trim() !== "trekoon_board_session") {
+      continue;
+    }
+
+    const value = valueParts.join("=").trim();
+    return value.length > 0 ? decodeURIComponent(value) : null;
+  }
+
+  return null;
+}
+
+function isAuthenticatedBoardRequest(request: Request, url: URL, token: string): boolean {
+  const queryToken = url.searchParams.get("token");
+  if (queryToken && queryToken === token) {
+    return true;
+  }
+
+  const cookieToken = readBoardSessionCookie(request);
+  return cookieToken !== null && cookieToken === token;
+}
+
 function serializeInlineJson(value: unknown): string {
   return JSON.stringify(value)
     .replace(/</g, "\\u003c")
@@ -102,11 +131,12 @@ function serializeInlineJson(value: unknown): string {
     .replace(/\u2029/g, "\\u2029");
 }
 
-function buildBoardBootstrapPayload(database: TrekoonDatabase, token: string): string {
-  const domain = new TrackerDomain(database.db);
+function buildBoardBootstrapPayload(_database: TrekoonDatabase, token: string): string {
+  // Only the auth token is inlined; the snapshot is fetched client-side via
+  // /api/snapshot to keep index.html small and avoid disclosing data even
+  // briefly through the HTML response cache.
   return serializeInlineJson({
     token,
-    snapshot: buildBoardSnapshot(domain),
   });
 }
 
@@ -127,27 +157,56 @@ export function startBoardServer(options: StartBoardServerOptions = {}): BoardSe
   const boardRoot: string = paths.boardDir;
   const stateFile: string = resolve(paths.storageDir, BOARD_SERVER_STATE_FILENAME);
   const token: string = options.token ?? randomBytes(18).toString("hex");
+  const eventBus: BoardEventBus = createBoardEventBus();
+  const walWatcher: WalWatcher = startWalWatcher({
+    db: database.db,
+    databaseFile: database.paths.databaseFile,
+    eventBus,
+  });
   const apiHandler = createBoardApiHandler({
     db: database.db,
     cwd,
     token,
+    eventBus,
   });
 
   const serveBoard = (port: number) =>
     Bun.serve({
       hostname: "127.0.0.1",
       port,
+      idleTimeout: 0,
       fetch(request: Request): Promise<Response> | Response {
         const url = new URL(request.url);
         if (url.pathname.startsWith("/api/")) {
           return apiHandler(request);
         }
 
+        const isAuthenticated = isAuthenticatedBoardRequest(request, url, token);
         const responseHeaders: Record<string, string> = {
           "cache-control": "no-store",
         };
-        if ((url.searchParams.get("token") ?? "") === token) {
+        const queryTokenMatched = (url.searchParams.get("token") ?? "") === token;
+        if (isAuthenticated && queryTokenMatched) {
           responseHeaders["set-cookie"] = buildBoardSessionCookie(token);
+
+          // Token revoke on rotation (P1 finding 8): once we've installed the
+          // session cookie, redirect to the same URL with the `token=` query
+          // param stripped. This keeps the browser's address bar, history,
+          // and Referer headers free of the secret on the very first
+          // navigation, severing the leakage surface that an open URL bar
+          // would otherwise expose. The cookie carries auth from here on.
+          const redirectUrl = new URL(url);
+          redirectUrl.searchParams.delete("token");
+          // Preserve the relative location so the redirect works regardless
+          // of how the client reached us (loopback IP vs. localhost name).
+          const location = `${redirectUrl.pathname}${redirectUrl.search}${redirectUrl.hash}`;
+          return new Response(null, {
+            status: 302,
+            headers: {
+              ...responseHeaders,
+              location: location.length > 0 ? location : "/",
+            },
+          });
         }
 
         const assetPath = readAssetPath(boardRoot, url.pathname === "/" ? "/index.html" : url.pathname);
@@ -157,9 +216,13 @@ export function startBoardServer(options: StartBoardServerOptions = {}): BoardSe
             return new Response("Board assets are not installed", { status: 500 });
           }
 
-          const html = injectBoardBootstrap(readFileSync(fallbackPath, "utf8"), buildBoardBootstrapPayload(database, token));
+          const rawHtml = readFileSync(fallbackPath, "utf8");
+          const html = isAuthenticated
+            ? injectBoardBootstrap(rawHtml, buildBoardBootstrapPayload(database, token))
+            : rawHtml;
 
           return new Response(html, {
+            status: isAuthenticated ? 200 : 401,
             headers: {
               ...responseHeaders,
               "content-type": "text/html; charset=utf-8",
@@ -168,8 +231,12 @@ export function startBoardServer(options: StartBoardServerOptions = {}): BoardSe
         }
 
         if (assetPath.endsWith("/index.html")) {
-          const html = injectBoardBootstrap(readFileSync(assetPath, "utf8"), buildBoardBootstrapPayload(database, token));
+          const rawHtml = readFileSync(assetPath, "utf8");
+          const html = isAuthenticated
+            ? injectBoardBootstrap(rawHtml, buildBoardBootstrapPayload(database, token))
+            : rawHtml;
           return new Response(html, {
+            status: isAuthenticated ? 200 : 401,
             headers: {
               ...responseHeaders,
               "content-type": "text/html; charset=utf-8",
@@ -231,6 +298,8 @@ export function startBoardServer(options: StartBoardServerOptions = {}): BoardSe
     hostname: "127.0.0.1",
     port,
     stop(): void {
+      walWatcher.close();
+      eventBus.close();
       server.stop(true);
       database.close();
     },

package/src/board/wal-watcher.ts

@@ -0,0 +1,302 @@
+/**
+ * WAL watcher.
+ *
+ * Watches the SQLite WAL sidecar (`<dbfile>-wal`) for mtime changes so
+ * mutations issued by another process (e.g. `trekoon task update` running in
+ * a different shell) are picked up and pushed to SSE subscribers.
+ *
+ * The watcher is intentionally _decoupled_ from the in-process MutationService
+ * event path: in-process writes already publish their own deltas via the
+ * route handler, so we treat WAL mtime changes as a hint that "something
+ * changed somewhere" and reconcile by comparing a fresh snapshot against the
+ * last snapshot we broadcast. Only entities that actually differ end up in
+ * the published delta.
+ */
+
+import { existsSync, statSync, watch, type FSWatcher } from "node:fs";
+import { dirname, basename } from "node:path";
+
+import { type Database } from "bun:sqlite";
+
+import { TrackerDomain } from "../domain/tracker-domain";
+import { type BoardEventBus } from "./event-bus";
+import { buildBoardSnapshot, type BoardSnapshot } from "./snapshot";
+
+interface CollectionDiff {
+  readonly upserted: unknown[];
+  readonly deletedIds: string[];
+}
+
+function recordId(value: unknown): string | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const id = (value as { id?: unknown }).id;
+  return typeof id === "string" && id.length > 0 ? id : null;
+}
+
+/**
+ * Extract the (version, updatedAt) tuple used to detect content changes.
+ *
+ * `updatedAt` is bumped on every domain write; `version` is incremented in
+ * lockstep at the SQLite layer. Comparing the tuple lets us bail out cheaply
+ * when neither has moved, avoiding the JSON.stringify hot path that fires on
+ * every WAL tick — including ticks where only non-content shape changed
+ * (e.g. dependency reordering of an unrelated record produced an array
+ * identity change but no semantic delta for the entity in question).
+ */
+function recordChangeKey(value: unknown): { version: number | null; updatedAt: number | null } {
+  if (!value || typeof value !== "object") {
+    return { version: null, updatedAt: null };
+  }
+  const versionRaw = (value as { version?: unknown }).version;
+  const updatedAtRaw = (value as { updatedAt?: unknown }).updatedAt;
+  return {
+    version: typeof versionRaw === "number" ? versionRaw : null,
+    updatedAt: typeof updatedAtRaw === "number" ? updatedAtRaw : null,
+  };
+}
+
+function changeKeyEqual(
+  a: { version: number | null; updatedAt: number | null },
+  b: { version: number | null; updatedAt: number | null },
+): boolean {
+  return a.version === b.version && a.updatedAt === b.updatedAt;
+}
+
+function diffById(previous: readonly unknown[] | undefined, current: readonly unknown[] | undefined): CollectionDiff {
+  const previousIndex = new Map<string, unknown>();
+  for (const record of previous ?? []) {
+    const id = recordId(record);
+    if (id !== null) {
+      previousIndex.set(id, record);
+    }
+  }
+
+  const upserted: unknown[] = [];
+  const seen = new Set<string>();
+  for (const record of current ?? []) {
+    const id = recordId(record);
+    if (id === null) {
+      continue;
+    }
+
+    seen.add(id);
+    const previousRecord = previousIndex.get(id);
+    if (!previousRecord) {
+      upserted.push(record);
+      continue;
+    }
+    // Tuple compare on (version, updatedAt) — both move in lockstep on every
+    // domain write. Equal tuple → no content change → skip the upsert.
+    if (!changeKeyEqual(recordChangeKey(previousRecord), recordChangeKey(record))) {
+      upserted.push(record);
+    }
+  }
+
+  const deletedIds: string[] = [];
+  for (const id of previousIndex.keys()) {
+    if (!seen.has(id)) {
+      deletedIds.push(id);
+    }
+  }
+
+  return { upserted, deletedIds };
+}
+
+export interface WalWatcherOptions {
+  readonly db: Database;
+  readonly databaseFile: string;
+  readonly eventBus: BoardEventBus;
+  /**
+   * How long to coalesce successive mtime change events. Defaults to 150ms
+   * which is small enough to feel real-time and large enough to absorb the
+   * burst of write events that SQLite emits within a single transaction.
+   */
+  readonly debounceMs?: number;
+  /**
+   * Log every Nth reconcile failure at warn level. Defaults to 5.
+   */
+  readonly logEveryNthFailure?: number;
+  /**
+   * Optional logger override; defaults to `console.warn`. Used by tests to
+   * assert failure-counter behavior without polluting stderr.
+   */
+  readonly logger?: (message: string, error: unknown) => void;
+  /**
+   * Optional snapshot builder override. Defaults to {@link buildBoardSnapshot}.
+   * Tests inject a throwing or stubbed builder to exercise failure paths.
+   */
+  readonly buildSnapshot?: (domain: TrackerDomain) => BoardSnapshot;
+}
+
+export interface WalWatcher {
+  /**
+   * Force a reconciliation outside the normal mtime-driven path. Useful for
+   * tests and for kicking the watcher after a manual external change.
+   */
+  reconcile(): void;
+  /**
+   * Total number of reconcile failures since the watcher started. Exposed for
+   * tests and operators; the watcher itself never throws.
+   */
+  readonly failureCount: () => number;
+  close(): void;
+}
+
+export function startWalWatcher(options: WalWatcherOptions): WalWatcher {
+  const debounceMs = options.debounceMs ?? 150;
+  const logEveryNthFailure = Math.max(1, options.logEveryNthFailure ?? 5);
+  const logger = options.logger ?? ((message: string, error: unknown): void => {
+    // eslint-disable-next-line no-console
+    console.warn(message, error);
+  });
+  const walFile = `${options.databaseFile}-wal`;
+  const watchDir = dirname(options.databaseFile);
+  const dbBaseName = basename(options.databaseFile);
+
+  // Hoist TrackerDomain construction out of reconcile: build once and reuse
+  // across ticks. The domain is a thin wrapper over the bun:sqlite Database
+  // handle and holds prepared-statement caches — recreating it per tick burns
+  // CPU on large boards. The handle stays valid for the lifetime of the
+  // server, so re-binding is unnecessary.
+  const domain = new TrackerDomain(options.db);
+  const buildSnapshot = options.buildSnapshot ?? buildBoardSnapshot;
+
+  let lastSnapshot = buildSnapshot(domain);
+
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let closed = false;
+  let failures = 0;
+
+  function reconcile(): void {
+    if (closed) {
+      return;
+    }
+
+    try {
+      const fresh = buildSnapshot(domain);
+
+      const epicsDiff = diffById(lastSnapshot.epics, fresh.epics);
+      const tasksDiff = diffById(lastSnapshot.tasks, fresh.tasks);
+      const subtasksDiff = diffById(lastSnapshot.subtasks, fresh.subtasks);
+      const dependenciesDiff = diffById(lastSnapshot.dependencies, fresh.dependencies);
+
+      const hasChanges =
+        epicsDiff.upserted.length > 0 || epicsDiff.deletedIds.length > 0 ||
+        tasksDiff.upserted.length > 0 || tasksDiff.deletedIds.length > 0 ||
+        subtasksDiff.upserted.length > 0 || subtasksDiff.deletedIds.length > 0 ||
+        dependenciesDiff.upserted.length > 0 || dependenciesDiff.deletedIds.length > 0;
+
+      lastSnapshot = fresh;
+
+      if (!hasChanges) {
+        return;
+      }
+
+      options.eventBus.publishSnapshotDelta({
+        generatedAt: Date.now(),
+        source: "wal-watcher",
+        epics: epicsDiff.upserted,
+        tasks: tasksDiff.upserted,
+        subtasks: subtasksDiff.upserted,
+        dependencies: dependenciesDiff.upserted,
+        deletedEpicIds: epicsDiff.deletedIds,
+        deletedTaskIds: tasksDiff.deletedIds,
+        deletedSubtaskIds: subtasksDiff.deletedIds,
+        deletedDependencyIds: dependenciesDiff.deletedIds,
+      });
+    } catch (error) {
+      // Reconciliation must never crash the server. Errors here usually mean
+      // the database is mid-write or a downstream snapshot builder threw; the
+      // next mtime tick will retry. Log every Nth failure to keep operators
+      // informed without flooding stderr on persistent faults.
+      failures += 1;
+      if (failures % logEveryNthFailure === 0) {
+        logger(`wal-watcher: reconcile failed (${failures} total failures)`, error);
+      }
+    }
+  }
+
+  function scheduleReconcile(): void {
+    if (closed) {
+      return;
+    }
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      reconcile();
+    }, debounceMs);
+  }
+
+  // Track WAL mtime when available, so we only react to actual changes rather
+  // than spurious watcher fires (e.g. atime-only updates on some filesystems).
+  let lastWalMtime: number = readMtime(walFile);
+
+  function readMtime(path: string): number {
+    if (!existsSync(path)) {
+      return 0;
+    }
+    try {
+      return statSync(path).mtimeMs;
+    } catch {
+      return 0;
+    }
+  }
+
+  function maybeScheduleReconcile(): void {
+    const currentMtime = readMtime(walFile);
+    // mtime can equal 0 when the WAL was just checkpointed and removed; treat
+    // any change (including transitions to/from 0) as worth reconciling.
+    if (currentMtime !== lastWalMtime) {
+      lastWalMtime = currentMtime;
+      scheduleReconcile();
+    }
+  }
+
+  // We watch the directory rather than the WAL file directly because the WAL
+  // file can be unlinked (e.g. on checkpoint) which invalidates a direct
+  // file watch on some platforms.
+  let watcher: FSWatcher | null = null;
+  try {
+    watcher = watch(watchDir, (_eventType, filename) => {
+      if (closed) {
+        return;
+      }
+      if (typeof filename === "string" && filename !== `${dbBaseName}-wal` && filename !== dbBaseName) {
+        return;
+      }
+      maybeScheduleReconcile();
+    });
+    watcher.on("error", () => {
+      // Best-effort; ignore transient watcher errors.
+    });
+  } catch {
+    // Filesystem watch is best-effort. If it cannot be set up (e.g. read-only
+    // filesystem), the watcher silently degrades and only `reconcile()` calls
+    // will publish deltas.
+    watcher = null;
+  }
+
+  return {
+    reconcile,
+    failureCount: (): number => failures,
+    close(): void {
+      closed = true;
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+      }
+      if (watcher) {
+        try {
+          watcher.close();
+        } catch {
+          // Already closed.
+        }
+        watcher = null;
+      }
+    },
+  };
+}

package/src/commands/board.ts

@@ -7,6 +7,17 @@ import { BoardInstallError, type EnsureBoardInstalledOptions } from "../board/ty
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
 
+// Per-subcommand allow-lists. Mirrors the pattern used in epic/task/subtask
+// command modules: each subcommand declares the set of flags (and options)
+// it accepts; everything else is rejected up-front.
+const OPEN_FLAGS = ["reveal-token"] as const;
+const UPDATE_FLAGS: readonly string[] = [];
+
+const FLAGS_BY_SUBCOMMAND: Readonly<Record<string, readonly string[]>> = {
+  open: OPEN_FLAGS,
+  update: UPDATE_FLAGS,
+};
+
 type EnsureBoardInstalledFn = (options: EnsureBoardInstalledOptions) => ReturnType<typeof ensureBoardInstalled>;
 type StartBoardServerFn = (options: { cwd: string }) => BoardServerInfo;
 type OpenBoardInBrowserFn = (url: string) => Promise<OpenBrowserResult> | OpenBrowserResult;
@@ -67,7 +78,15 @@ export async function runBoard(context: CliContext): Promise<CliResult> {
   const parsed = parseArgs(context.args);
   const subcommand: string | undefined = parsed.positional[0];
 
-  if (parsed.options.size > 0 || parsed.flags.size > 0) {
+  const revealToken: boolean = parsed.flags.has("reveal-token");
+  const allowedFlags = new Set<string>(
+    subcommand !== undefined && subcommand in FLAGS_BY_SUBCOMMAND
+      ? FLAGS_BY_SUBCOMMAND[subcommand]
+      : [],
+  );
+  const disallowedFlags = [...parsed.flags].filter((flag) => !allowedFlags.has(flag));
+
+  if (parsed.options.size > 0 || disallowedFlags.length > 0) {
     return failResult({
       command: subcommand ? `board.${subcommand}` : "board",
       human: "Board commands do not accept options yet.",
@@ -118,30 +137,46 @@ export async function runBoard(context: CliContext): Promise<CliResult> {
         const install = ensureInstalledImpl(boardInstallOptions(context));
         const server = startBoardServerImpl({ cwd: context.cwd });
         const launch = await openBoardInBrowserImpl(server.url);
+        const humanLines: string[] = [
+          `Board ready at ${server.fallbackUrl}`,
+          launch.launched
+            ? `Browser launched with ${launch.command}`
+            : `Browser launch failed: ${launch.errorMessage ?? "unknown failure"}`,
+          `Open manually if needed: ${server.fallbackUrl}`,
+        ];
+        if (revealToken) {
+          humanLines.push(
+            `Tokenized URL (do not share, grants full board access): ${server.url}`,
+          );
+        }
+        const serverData: Record<string, unknown> = {
+          origin: server.origin,
+          fallbackUrl: server.fallbackUrl,
+          hostname: server.hostname,
+          port: server.port,
+        };
+        const launchData: Record<string, unknown> = {
+          launched: launch.launched,
+          command: launch.command,
+          errorMessage: launch.errorMessage,
+        };
+        if (revealToken) {
+          serverData.url = server.url;
+          serverData.token = server.token;
+          launchData.url = launch.url;
+          launchData.args = launch.args;
+        }
         return okResult({
           command: "board.open",
-          human: [
-            `Board ready at ${server.fallbackUrl}`,
-            launch.launched
-              ? `Browser launched with ${launch.command}`
-              : `Browser launch failed: ${launch.errorMessage ?? "unknown failure"}`,
-            `Open manually if needed: ${server.fallbackUrl}`,
-          ].join("\n"),
+          human: humanLines.join("\n"),
           data: {
             install: {
               action: install.action,
               paths: install.paths,
               manifest: install.manifest,
             },
-            server: {
-              origin: server.origin,
-              url: server.url,
-              fallbackUrl: server.fallbackUrl,
-              hostname: server.hostname,
-              port: server.port,
-              token: server.token,
-            },
-            launch,
+            server: serverData,
+            launch: launchData,
           },
         });
       }

package/src/commands/epic.ts

@@ -1357,10 +1357,9 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
 
           const targets = updateAll ? [...domain.listEpics()] : ids.map((id) => domain.getEpicOrThrow(id));
           const epics = targets.map((target) =>
-            mutations.updateEpic(target.id, {
-              status,
-              description: append === undefined ? undefined : appendLine(target.description, append),
-            }),
+            append !== undefined
+              ? mutations.appendToEpicDescription({ epicId: target.id, append, status })
+              : mutations.updateEpic(target.id, { status }),
           );
 
           return okResult({
@@ -1386,11 +1385,10 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           });
         }
 
-        const nextDescription =
-          append === undefined
-            ? description
-            : appendLine(domain.getEpicOrThrow(epicId).description, append);
-        const epic = mutations.updateEpic(epicId, { title, description: nextDescription, status });
+        const epic =
+          append !== undefined
+            ? mutations.appendToEpicDescription({ epicId, append, status })
+            : mutations.updateEpic(epicId, { title, description, status });
 
         return okResult({
           command: "epic.update",

package/src/commands/error-utils.ts

@@ -29,8 +29,46 @@ function readErrorMessage(error: unknown): string | null {
   return null;
 }
 
+// Keys whose values must never appear in surfaced error output.
+// Handles formats: key=val, key: val, key="val", 'key':'val', "key":"val",
+// Authorization: Bearer val, Authorization: Basic val.
+const SENSITIVE_KEY_PATTERN =
+  /(["']?)(token|secret|password|bearer|authorization|api[_-]?key|client[_-]?secret|private[_-]?key|cookie|session[_-]?id)(["']?\s*[:=]\s*(?:Bearer\s+|Basic\s+)?["']?)([^\s"',;&\]}{)<>]+)/giu;
+
+// Tag-style sensitive values: <key>value</key>.
+const SENSITIVE_TAG_PATTERN =
+  /(<\s*(token|secret|password|bearer|authorization|api[_-]?key|client[_-]?secret|private[_-]?key|cookie|session[_-]?id)\s*>)([^<]+)/giu;
+
+// Standalone "Bearer xyz" / "Basic xyz" anywhere in the message.
+// SENSITIVE_KEY_PATTERN runs first and consumes Authorization: Bearer/Basic forms; this
+// catches bare occurrences that remain (e.g. "got Bearer eyJ..." or "auth: Basic dXNl...").
+const STANDALONE_AUTH_SCHEME_PATTERN = /\b(Bearer|Basic)\s+([A-Za-z0-9._\-+/=]+)/giu;
+
+// JWT shape heuristic: three base64url segments separated by dots, each starting
+// with a base64url-encoded JSON header/payload/signature. The first two segments
+// of any JWT begin with "eyJ" because they encode JSON objects (`{"...`).
+// Catches bare JWTs that slip past the keyed and Bearer/Basic patterns above
+// (e.g. raw token pasted into an error message without an "Authorization:" prefix).
+const JWT_PATTERN = /\beyJ[A-Za-z0-9_\-]+\.eyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+/gu;
+
+export function redactSensitive(input: string): string {
+  const keyRedacted = input.replace(
+    SENSITIVE_KEY_PATTERN,
+    (_match, open, key, sep) => `${open}${key}${sep}REDACTED`,
+  );
+  const tagRedacted = keyRedacted.replace(
+    SENSITIVE_TAG_PATTERN,
+    (_match, openTag) => `${openTag}REDACTED`,
+  );
+  const authRedacted = tagRedacted.replace(
+    STANDALONE_AUTH_SCHEME_PATTERN,
+    (_match, scheme) => `${scheme} REDACTED`,
+  );
+  return authRedacted.replace(JWT_PATTERN, "REDACTED");
+}
+
 function sanitizeErrorMessage(message: string): string {
-  const normalized = message.replace(/\s+/gu, " ").trim();
+  const normalized = redactSensitive(message.replace(/\s+/gu, " ").trim());
   if (normalized.length <= 240) {
     return normalized;
   }
@@ -109,3 +147,18 @@ export function safeErrorMessage(error: unknown, fallback: string): string {
   const message = readErrorMessage(error);
   return message === null ? fallback : sanitizeErrorMessage(message);
 }
+
+/**
+ * Redact a stack trace before logging. Routes the input through
+ * `redactSensitive` (the canonical secret-stripping pass) so absolute paths
+ * and any inline credentials are scrubbed. The function is intentionally
+ * shallow — additional heuristics (e.g. JWT shape detection) live in
+ * `redactSensitive` itself so future contributors only need to extend that
+ * single regex pipeline.
+ */
+export function redactStack(stack: string | undefined): string {
+  if (typeof stack !== "string" || stack.length === 0) {
+    return "";
+  }
+  return redactSensitive(stack);
+}