fix(ui): thread doc-base through code-path validator

Out-of-tree linked docs (and annotate-mode files outside cwd) reference
files relative to themselves. The validator was resolving against cwd
only, so those paths got marked missing and the renderer demoted them
to plain text — even though clicks still resolved correctly via base.

Also tightens the suffix-match's leading-segment strip so `../foo.ts`
no longer silently misresolves to an unrelated `foo.ts` in cwd.

Cleanup: delete unused extract-code-paths import in reference-handlers,
add the export entry to packages/shared so consumers don't rely on
Bun's lenient subpath resolution. Add TODO(security) comments at both
handleDocExists sites flagging that absolute paths bypass project-root
containment.

223 tests pass (3 new resolver cases for baseDir + ../ regression).

Author: backnotprop

apps/pi-extension/server/reference.ts

@@ -201,6 +201,11 @@ export async function handleDocRequest(res: Res, url: URL): Promise<void> {
 /**
  * Batch existence check for code-file paths the renderer wants to linkify.
  * POST /api/doc/exists with { paths: string[] }.
+ *
+ * TODO(security): see packages/server/reference-handlers.ts handleDocExists —
+ * absolute paths are probed verbatim with no project-root containment check,
+ * leaking file existence back to the caller. Fix in lockstep with the Bun
+ * handler (reject absolute inputs or filter results via isWithinProjectRoot).
  */
 export async function handleDocExistsRequest(res: Res, req: IncomingMessage): Promise<void> {
 	const body = await parseBody(req);
@@ -213,6 +218,10 @@ export async function handleDocExistsRequest(res: Res, req: IncomingMessage): Pr
 		json(res, { error: "Too many paths (max 500)" }, 400);
 		return;
 	}
+	const baseRaw = (body as { base?: unknown }).base;
+	const baseDir = typeof baseRaw === "string" && baseRaw.length > 0
+		? resolveUserPath(baseRaw)
+		: undefined;
 
 	const projectRoot = process.cwd();
 	const results: Record<
@@ -225,7 +234,7 @@ export async function handleDocExistsRequest(res: Res, req: IncomingMessage): Pr
 
 	await Promise.all(
 		(paths as string[]).map(async (p) => {
-			const r = await resolveCodeFile(p, projectRoot);
+			const r = await resolveCodeFile(p, projectRoot, baseDir);
 			if (r.kind === "found") {
 				results[p] = { status: "found", resolved: r.path };
 			} else if (r.kind === "ambiguous") {

packages/editor/App.tsx

@@ -1933,6 +1933,9 @@ const App: React.FC = () => {
                   onOpenCodeFile={codeFilePopout.open}
                   linkedDocInfo={linkedDocHook.isActive ? { filepath: linkedDocHook.filepath!, onBack: handleLinkedDocBack, label: fileBrowser.dirs.find(d => d.path === fileBrowser.activeDirPath)?.isVault ? 'Vault File' : fileBrowser.activeFile ? 'File' : undefined, backLabel } : null}
                   imageBaseDir={imageBaseDir}
+                  codePathBaseDir={linkedDocHook.filepath
+                    ? linkedDocHook.filepath.replace(/\/[^/]+$/, '')
+                    : imageBaseDir}
                   copyLabel={annotateSource === 'message' ? 'Copy message' : annotateSource === 'file' || annotateSource === 'folder' ? 'Copy file' : undefined}
                   archiveInfo={archive.currentInfo}
                   sourceInfo={sourceInfo}

packages/server/reference-handlers.ts

@@ -18,7 +18,6 @@ import {
 	isWithinProjectRoot,
 	warmFileListCache,
 } from "@plannotator/shared/resolve-file";
-import { extractCandidateCodePaths } from "@plannotator/shared/extract-code-paths";
 import { htmlToMarkdown } from "@plannotator/shared/html-to-markdown";
 import { preloadFile } from "@pierre/diffs/ssr";
 
@@ -172,6 +171,14 @@ export async function handleDoc(req: Request): Promise<Response> {
  * Batch existence check for code-file paths the renderer wants to linkify.
  * POST /api/doc/exists with { paths: string[] } returns { results: { [path]: ValidationEntry } }.
  * Reads from the warm file-list cache populated at plan/annotate load.
+ *
+ * TODO(security): absolute paths sent here are probed verbatim against the
+ * filesystem — `resolveCodeFile` returns `{ kind: 'found', path: abs }` for any
+ * existing absolute file with no project-root containment check. A malicious
+ * shared plan with backtick-wrapped absolute paths (e.g. `/Users/x/.aws/…`)
+ * leaks file existence + canonical path back to the caller. Mitigation:
+ * reject absolute inputs (or `isWithinProjectRoot`-filter `r.path`) before
+ * recording a found result. Mirror in apps/pi-extension/server/reference.ts.
  */
 export async function handleDocExists(req: Request): Promise<Response> {
 	let body: unknown;
@@ -187,6 +194,10 @@ export async function handleDocExists(req: Request): Promise<Response> {
 	if (paths.length > 500) {
 		return Response.json({ error: "Too many paths (max 500)" }, { status: 400 });
 	}
+	const baseRaw = (body as { base?: unknown })?.base;
+	const baseDir = typeof baseRaw === "string" && baseRaw.length > 0
+		? resolveUserPath(baseRaw)
+		: undefined;
 
 	const projectRoot = process.cwd();
 	const results: Record<
@@ -199,7 +210,7 @@ export async function handleDocExists(req: Request): Promise<Response> {
 
 	await Promise.all(
 		(paths as string[]).map(async (p) => {
-			const r = await resolveCodeFile(p, projectRoot);
+			const r = await resolveCodeFile(p, projectRoot, baseDir);
 			if (r.kind === "found") {
 				results[p] = { status: "found", resolved: r.path };
 			} else if (r.kind === "ambiguous") {

packages/shared/package.json

@@ -21,6 +21,7 @@
     "./favicon": "./favicon.ts",
     "./code-file": "./code-file.ts",
     "./resolve-file": "./resolve-file.ts",
+    "./extract-code-paths": "./extract-code-paths.ts",
     "./external-annotation": "./external-annotation.ts",
     "./agent-jobs": "./agent-jobs.ts",
     "./config": "./config.ts",

packages/shared/resolve-file.test.ts

@@ -82,4 +82,32 @@ describe("resolveCodeFile", () => {
 			expect(r.path).toBe(join(root, "packages/editor/App.tsx"));
 		}
 	});
+
+	test("does NOT strip leading ../ — without baseDir, refuses to fabricate", async () => {
+		// `../foo.tsx` is meaningful (escape parent). With no baseDir context,
+		// we can't honor it, so we must fail rather than silently returning
+		// an unrelated file with the same basename from inside cwd.
+		const r = await resolveCodeFile("../editor/App.tsx", root);
+		expect(r.kind).toBe("not_found");
+	});
+
+	test("resolves via baseDir when input is relative to active doc", async () => {
+		// Linked doc at `<root>/packages/review-editor/...` references `../editor/App.tsx`
+		const baseDir = join(root, "packages/review-editor");
+		const r = await resolveCodeFile("../editor/App.tsx", root, baseDir);
+		expect(r.kind).toBe("found");
+		if (r.kind === "found") {
+			expect(r.path).toBe(join(root, "packages/editor/App.tsx"));
+		}
+	});
+
+	test("baseDir miss falls through to suffix walk", async () => {
+		// baseDir doesn't have the file, but cwd tree does — walk catches it.
+		const baseDir = join(root, "packages/review-editor");
+		const r = await resolveCodeFile("ui/components/Button.tsx", root, baseDir);
+		expect(r.kind).toBe("found");
+		if (r.kind === "found") {
+			expect(r.path).toBe(join(root, "packages/ui/components/Button.tsx"));
+		}
+	});
 });

packages/shared/resolve-file.ts

@@ -281,15 +281,23 @@ export function warmFileListCache(
  * Strategies:
  *   1. Absolute path → use as-is.
  *   2. Exact relative from project root.
- *   3. Case-insensitive suffix match against the cached file list:
+ *   3. If `baseDir` provided, literal `<baseDir>/<input>` existence check —
+ *      lets out-of-tree linked docs resolve their own relative references
+ *      (e.g. `../script.ts` in `~/notes/foo.md` finds `~/script.ts`).
+ *   4. Case-insensitive suffix match against the cached file list:
  *      - bare basename input → match any file with that basename;
  *      - input with `/` → match files whose path equals or ends with `/<input>`
  *        on a segment boundary (so `editor/App.tsx` matches `packages/editor/App.tsx`
  *        but not `myeditor/App.tsx`).
+ *
+ * `..` segments in the input are honored: only `./` is stripped before suffix
+ * matching. `../foo.ts` without a `baseDir` correctly falls through to
+ * not_found rather than fabricating a match against `foo.ts` somewhere in cwd.
  */
 export async function resolveCodeFile(
 	input: string,
 	projectRoot: string,
+	baseDir?: string,
 ): Promise<ResolveResult> {
 	const originalInput = input.trim();
 	const unquotedInput = stripWrappingQuotes(originalInput);
@@ -313,15 +321,25 @@ export async function resolveCodeFile(
 		return { kind: "found", path: fromRoot };
 	}
 
+	if (baseDir) {
+		const fromBase = resolve(baseDir, searchInput);
+		if (fileExists(fromBase)) {
+			return { kind: "found", path: fromBase };
+		}
+	}
+
 	const fileList = await warmFileListCache(projectRoot, "code");
 	if (fileList === null) {
 		return { kind: "unavailable", input: originalInput };
 	}
 
-	// Strip leading `./` or `../` so suffix matching works on inputs like
-	// `./editor/App.tsx` — file list entries never carry those segments.
-	const cleanedInput = searchInput.replace(/^(?:\.\.?\/)+/, "");
-	if (!cleanedInput) {
+	// Strip leading `./` so suffix matching works on inputs like
+	// `./editor/App.tsx` — file list entries never carry that segment.
+	// `../` is intentionally NOT stripped: `..` is meaningful (escape parent),
+	// not noise. If we can't honor it via baseDir, the input has no
+	// suffix-match equivalent in the in-tree file list.
+	const cleanedInput = searchInput.replace(/^(?:\.\/)+/, "");
+	if (!cleanedInput || cleanedInput.startsWith("../")) {
 		return { kind: "not_found", input: originalInput };
 	}
 	const target = cleanedInput.toLowerCase();

packages/ui/components/Viewer.tsx

@@ -68,6 +68,10 @@ interface ViewerProps {
   onOpenLinkedDoc?: (path: string) => void;
   onOpenCodeFile?: (path: string) => void;
   imageBaseDir?: string;
+  /** Directory the active document lives in — used by the code-path validator
+   *  so out-of-tree relative references (e.g. `../foo.ts` in a linked doc)
+   *  resolve against the doc's own directory rather than only cwd. */
+  codePathBaseDir?: string;
   linkedDocInfo?: { filepath: string; onBack: () => void; label?: string; backLabel?: string } | null;
   // Plan diff props
   planDiffStats?: { additions: number; deletions: number; modifications: number } | null;
@@ -159,6 +163,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   onOpenCodeFile,
   linkedDocInfo,
   imageBaseDir,
+  codePathBaseDir,
   copyLabel,
   actionsLabelMode = 'full',
   archiveInfo,
@@ -512,7 +517,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     setViewerCommentPopover(null);
   }, []);
 
-  const codePathValidation = useValidatedCodePaths(markdown);
+  const codePathValidation = useValidatedCodePaths(markdown, codePathBaseDir);
 
   return (
     <CodePathValidationContext.Provider value={codePathValidation}>

packages/ui/hooks/useValidatedCodePaths.ts

@@ -19,9 +19,16 @@ export type ValidatedMap = Map<string, ValidationEntry>;
  * renderer dispatches on status — see InlineMarkdown.
  *
  * Empty candidate set short-circuits — no fetch, ready: true immediately.
+ *
+ * `baseDir` is the directory the active document lives in (linked-doc parent
+ * or the annotate source file's parent). When set, the server tries
+ * `<baseDir>/<input>` literal-resolve before its cwd walk so out-of-tree
+ * relative references (e.g. `../script.ts` in `~/notes/foo.md`) don't get
+ * demoted to plain text.
  */
 export function useValidatedCodePaths(
 	markdown: string,
+	baseDir?: string,
 ): { validated: ValidatedMap; ready: boolean } {
 	const [validated, setValidated] = useState<ValidatedMap>(new Map());
 	const [ready, setReady] = useState<boolean>(false);
@@ -42,7 +49,9 @@ export function useValidatedCodePaths(
 				const res = await fetch("/api/doc/exists", {
 					method: "POST",
 					headers: { "Content-Type": "application/json" },
-					body: JSON.stringify({ paths: candidates }),
+					body: JSON.stringify(
+						baseDir ? { paths: candidates, base: baseDir } : { paths: candidates },
+					),
 				});
 				if (cancelled) return;
 				if (!res.ok) {
@@ -67,7 +76,7 @@ export function useValidatedCodePaths(
 		return () => {
 			cancelled = true;
 		};
-	}, [markdown]);
+	}, [markdown, baseDir]);
 
 	// Stable reference: only changes when validated/ready actually change.
 	// Without memoization, the parent provider's value is a fresh object every