feat(security): introduce WorkspaceFileAccess — central workspace boundary authorization (#390)

Sub-issue 2 of #169, building on WorkspacePathResolver (#389/#428).

Adds src/core/workspace/WorkspaceFileAccess.ts. `authorizeRead`/`authorizeWrite`
return either `{ ok: true, resolvedPath }` or a structured
`{ ok: false, reason }` (outside_workspace | symlink_escapes_workspace |
realpath_failed | permission_denied), so tools can no longer perform a boolean
check and then act on a stale path — the missed `ApplyDiffTool` check in #241 is
exactly the failure mode this prevents.

Default behavior canonicalizes the requested path and every workspace folder via
`resolveRealPath` and fails closed; the `allowSymlinksOutsideWorkspace` opt-in
restores the pre-#169 lexical behavior. The setting is introduced here (its home)
in GlobalSettings and ExtensionState. No tool migrations, UI, or i18n in this PR.

Author: proyectoauraorg

packages/types/src/global-settings.ts

@@ -101,6 +101,7 @@ export const globalSettingsSchema = z.object({
 	alwaysAllowWrite: z.boolean().optional(),
 	alwaysAllowWriteOutsideWorkspace: z.boolean().optional(),
 	alwaysAllowWriteProtected: z.boolean().optional(),
+	allowSymlinksOutsideWorkspace: z.boolean().optional(),
 	writeDelayMs: z.number().min(0).optional(),
 	requestDelaySeconds: z.number().optional(),
 	alwaysAllowMcp: z.boolean().optional(),

packages/types/src/vscode-extension-host.ts

@@ -252,6 +252,7 @@ export type ExtensionState = Pick<
 	| "alwaysAllowWrite"
 	| "alwaysAllowWriteOutsideWorkspace"
 	| "alwaysAllowWriteProtected"
+	| "allowSymlinksOutsideWorkspace"
 	| "alwaysAllowMcp"
 	| "alwaysAllowModeSwitch"
 	| "alwaysAllowSubtasks"

src/core/workspace/WorkspaceFileAccess.ts

@@ -0,0 +1,166 @@
+import * as path from "path"
+
+import * as vscode from "vscode"
+
+import type { Task } from "../task/Task"
+import { resolveRealPath } from "../../utils/WorkspacePathResolver"
+
+/**
+ * Why an authorization was denied. Distinguishing `symlink_escapes_workspace` from
+ * `outside_workspace` lets callers (and telemetry) tell a deliberate out-of-tree path apart from a
+ * path that *looks* inside the workspace but resolves out of it via a symlink (#169).
+ */
+export type AuthorizeDenyReason =
+	| "outside_workspace"
+	| "symlink_escapes_workspace"
+	| "realpath_failed"
+	| "permission_denied"
+
+export type AuthorizeResult =
+	| { ok: true; resolvedPath: string }
+	| { ok: false; reason: AuthorizeDenyReason; message: string }
+
+export interface AuthorizeOptions {
+	/** Task whose provider state supplies the `allowSymlinksOutsideWorkspace` opt-in. */
+	task: Task
+	/** Absolute path as supplied by the tool. */
+	requestedPath: string
+	/** Tool name, used to prefix error messages. */
+	source: string
+}
+
+/** Lowercase on case-insensitive filesystems, matching {@link resolveRealPath}'s own normalization. */
+function normalizeCase(p: string): string {
+	return process.platform === "darwin" || process.platform === "win32" ? p.toLowerCase() : p
+}
+
+/** True when `child` is `parent` itself or nested under it. Both paths must already be normalized. */
+function isContained(parent: string, child: string): boolean {
+	return child === parent || child.startsWith(parent + path.sep)
+}
+
+/**
+ * Read the `allowSymlinksOutsideWorkspace` opt-in from provider state, defaulting to `false`
+ * (fail-closed). The provider may have been torn down mid-operation, in which case `getState()`
+ * rejects — that must not abort the file operation, so we swallow it and keep the safe default.
+ */
+async function readAllowSymlinksOutsideWorkspace(task: Task): Promise<boolean> {
+	try {
+		return (await task.providerRef.deref()?.getState())?.allowSymlinksOutsideWorkspace ?? false
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Central authorization for file access against the workspace boundary.
+ *
+ * Tools call this instead of doing a raw `isPathOutsideWorkspace()` boolean check followed by their
+ * own `fs` operation. The decoupled check-then-act pattern is structurally easy to get wrong — one
+ * missed call site (like `ApplyDiffTool` in #241) leaves a hole. Here a tool requests an authorized
+ * operation and gets back either a resolved path it may use, or a structured error it must surface.
+ *
+ * Default (fail-closed) behavior follows symlinks: the requested path and every workspace folder are
+ * canonicalized via {@link resolveRealPath}, and access is granted only when the real path lands
+ * inside a real workspace folder. When the user opts in via `allowSymlinksOutsideWorkspace`, the
+ * pre-#169 lexical behavior is restored (symlinks are not followed for the boundary decision).
+ *
+ * This layer owns policy only — it performs no `fs` read/write itself.
+ */
+async function authorize(options: AuthorizeOptions): Promise<AuthorizeResult> {
+	const { task, requestedPath, source } = options
+	const allowSymlinksOutsideWorkspace = await readAllowSymlinksOutsideWorkspace(task)
+
+	// Canonicalize the requested path (follows symlinks; walks up to the nearest existing ancestor
+	// for not-yet-created files). A non-ENOENT error here means we can't prove anything about the
+	// path, so we fail closed with a structured reason.
+	let resolvedPath: string
+	try {
+		resolvedPath = await resolveRealPath(requestedPath)
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException)?.code
+		const detail = err instanceof Error ? err.message : String(err)
+		if (code === "EACCES" || code === "EPERM") {
+			return {
+				ok: false,
+				reason: "permission_denied",
+				message: `[${source}] Permission denied resolving ${requestedPath}: ${detail}`,
+			}
+		}
+		return {
+			ok: false,
+			reason: "realpath_failed",
+			message: `[${source}] Could not resolve real path for ${requestedPath}: ${detail}`,
+		}
+	}
+
+	const folders = vscode.workspace.workspaceFolders ?? []
+
+	// Opt-in: restore pre-#169 lexical behavior — compare the literal path, never the symlink target.
+	if (allowSymlinksOutsideWorkspace) {
+		const lexicalPath = normalizeCase(path.resolve(requestedPath))
+		const insideLexically = folders.some((folder) =>
+			isContained(normalizeCase(path.resolve(folder.uri.fsPath)), lexicalPath),
+		)
+		if (insideLexically) {
+			return { ok: true, resolvedPath }
+		}
+		return {
+			ok: false,
+			reason: "outside_workspace",
+			message: `[${source}] ${requestedPath} is outside the workspace.`,
+		}
+	}
+
+	// Fail-closed: with no workspace open nothing can be proven inside.
+	if (folders.length === 0) {
+		return {
+			ok: false,
+			reason: "outside_workspace",
+			message: `[${source}] No workspace folder is open; ${requestedPath} cannot be authorized.`,
+		}
+	}
+
+	// Compare the resolved path against each *resolved* workspace folder. A folder we can't resolve
+	// (e.g. permissions) can't prove containment, so it's skipped rather than treated as a match.
+	for (const folder of folders) {
+		let resolvedFolder: string
+		try {
+			resolvedFolder = await resolveRealPath(folder.uri.fsPath)
+		} catch {
+			continue
+		}
+		if (isContained(resolvedFolder, resolvedPath)) {
+			return { ok: true, resolvedPath }
+		}
+	}
+
+	// Outside every folder. If the literal path looked inside but the resolved path escaped, a
+	// symlink is responsible — surface that distinctly from a plainly out-of-workspace path.
+	const lexicalPath = normalizeCase(path.resolve(requestedPath))
+	const lexicallyInside = folders.some((folder) =>
+		isContained(normalizeCase(path.resolve(folder.uri.fsPath)), lexicalPath),
+	)
+	if (lexicallyInside) {
+		return {
+			ok: false,
+			reason: "symlink_escapes_workspace",
+			message: `[${source}] ${requestedPath} resolves via symlink to ${resolvedPath}, which is outside the workspace.`,
+		}
+	}
+	return {
+		ok: false,
+		reason: "outside_workspace",
+		message: `[${source}] ${requestedPath} is outside the workspace.`,
+	}
+}
+
+/** Authorize a read against the workspace boundary. See {@link authorize}. */
+export function authorizeRead(options: AuthorizeOptions): Promise<AuthorizeResult> {
+	return authorize(options)
+}
+
+/** Authorize a write against the workspace boundary. See {@link authorize}. */
+export function authorizeWrite(options: AuthorizeOptions): Promise<AuthorizeResult> {
+	return authorize(options)
+}

src/core/workspace/__tests__/WorkspaceFileAccess.spec.ts

@@ -0,0 +1,193 @@
+import * as os from "os"
+import * as path from "path"
+import * as fs from "fs/promises"
+
+import * as vscode from "vscode"
+
+import type { Task } from "../../task/Task"
+import { authorizeRead, authorizeWrite } from "../WorkspaceFileAccess"
+
+vi.mock("vscode", () => ({
+	workspace: { workspaceFolders: [] as { uri: { fsPath: string } }[] },
+}))
+
+// Real symlinks in a real temp directory (no fs mocking, per #389/#390). Some scenarios can't be
+// reproduced everywhere: symlink creation needs privileges on Windows, and chmod-based EACCES is
+// meaningless as root. Such cases are skipped at runtime rather than mocked.
+const isWindows = process.platform === "win32"
+const isRoot = typeof process.getuid === "function" && process.getuid() === 0
+
+/** Lowercase on case-insensitive filesystems, matching the resolver's own normalization. */
+const expectCase = (p: string) => (process.platform === "darwin" || process.platform === "win32" ? p.toLowerCase() : p)
+
+/** Minimal Task stub exposing only what WorkspaceFileAccess reads. */
+function makeTask(opts: { allow?: boolean; providerGone?: boolean; getStateThrows?: boolean } = {}): Task {
+	const provider = {
+		getState: async () => {
+			if (opts.getStateThrows) {
+				throw new Error("provider torn down")
+			}
+			return { allowSymlinksOutsideWorkspace: opts.allow }
+		},
+	}
+	return {
+		providerRef: { deref: () => (opts.providerGone ? undefined : provider) },
+	} as unknown as Task
+}
+
+function setWorkspaceFolders(...paths: string[]) {
+	;(vscode.workspace as any).workspaceFolders = paths.map((p) => ({ uri: { fsPath: p } }))
+}
+
+describe("WorkspaceFileAccess", () => {
+	let tmpRoot: string
+	let workspace: string
+	let outside: string
+	let symlinksSupported = false
+
+	beforeEach(async () => {
+		// realpath the temp root so comparisons aren't tripped up by /var -> /private/var (macOS).
+		tmpRoot = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "zoo-wfa-")))
+		workspace = path.join(tmpRoot, "workspace")
+		outside = path.join(tmpRoot, "outside")
+		await fs.mkdir(workspace, { recursive: true })
+		await fs.mkdir(outside, { recursive: true })
+		setWorkspaceFolders(workspace)
+
+		const probeTarget = path.join(tmpRoot, "probe-target")
+		const probeLink = path.join(tmpRoot, "probe-link")
+		await fs.writeFile(probeTarget, "probe")
+		try {
+			await fs.symlink(probeTarget, probeLink)
+			symlinksSupported = true
+		} catch {
+			symlinksSupported = false
+		}
+	})
+
+	afterEach(async () => {
+		await fs.chmod(path.join(workspace, "restricted"), 0o755).catch(() => {})
+		await fs.rm(tmpRoot, { recursive: true, force: true }).catch(() => {})
+		;(vscode.workspace as any).workspaceFolders = []
+	})
+
+	it("authorizes a real file inside the workspace and returns its canonical path", async () => {
+		const file = path.join(workspace, "file.txt")
+		await fs.writeFile(file, "x")
+
+		const result = await authorizeRead({ task: makeTask(), requestedPath: file, source: "read_file" })
+
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.resolvedPath).toBe(expectCase(await fs.realpath(file)))
+		}
+	})
+
+	it("denies a symlink inside the workspace that escapes it (symlink_escapes_workspace)", async () => {
+		if (!symlinksSupported) return
+		const secret = path.join(outside, "secret.txt")
+		await fs.writeFile(secret, "x")
+		const link = path.join(workspace, "link.txt")
+		await fs.symlink(secret, link)
+
+		const result = await authorizeRead({ task: makeTask(), requestedPath: link, source: "read_file" })
+
+		expect(result).toMatchObject({ ok: false, reason: "symlink_escapes_workspace" })
+	})
+
+	it("allows an escaping symlink when allowSymlinksOutsideWorkspace is true", async () => {
+		if (!symlinksSupported) return
+		const secret = path.join(outside, "secret.txt")
+		await fs.writeFile(secret, "x")
+		const link = path.join(workspace, "link.txt")
+		await fs.symlink(secret, link)
+
+		const result = await authorizeRead({ task: makeTask({ allow: true }), requestedPath: link, source: "read_file" })
+
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.resolvedPath).toBe(expectCase(await fs.realpath(secret)))
+		}
+	})
+
+	it("denies a path that is plainly outside the workspace (outside_workspace)", async () => {
+		const file = path.join(outside, "file.txt")
+		await fs.writeFile(file, "x")
+
+		const result = await authorizeRead({ task: makeTask(), requestedPath: file, source: "read_file" })
+
+		expect(result).toMatchObject({ ok: false, reason: "outside_workspace" })
+	})
+
+	it("returns permission_denied when the path cannot be resolved due to EACCES", async () => {
+		if (isWindows || isRoot) return
+		const restricted = path.join(workspace, "restricted")
+		await fs.mkdir(restricted)
+		const target = path.join(restricted, "file.txt")
+		await fs.writeFile(target, "x")
+		await fs.chmod(restricted, 0o000)
+
+		const result = await authorizeRead({ task: makeTask(), requestedPath: target, source: "read_file" })
+
+		expect(result).toMatchObject({ ok: false, reason: "permission_denied" })
+	})
+
+	it("authorizes a not-yet-created file under a symlinked ancestor that stays inside the workspace", async () => {
+		if (!symlinksSupported) return
+		const realDir = path.join(workspace, "real-dir")
+		await fs.mkdir(realDir)
+		const linkDir = path.join(workspace, "link-dir")
+		await fs.symlink(realDir, linkDir)
+		const newFile = path.join(linkDir, "not-created-yet.txt")
+
+		const result = await authorizeWrite({ task: makeTask(), requestedPath: newFile, source: "write_to_file" })
+
+		expect(result.ok).toBe(true)
+		if (result.ok) {
+			expect(result.resolvedPath).toBe(expectCase(path.join(await fs.realpath(realDir), "not-created-yet.txt")))
+		}
+	})
+
+	it("fails closed when the provider has been torn down (deref returns undefined)", async () => {
+		if (!symlinksSupported) return
+		const secret = path.join(outside, "secret.txt")
+		await fs.writeFile(secret, "x")
+		const link = path.join(workspace, "link.txt")
+		await fs.symlink(secret, link)
+
+		// providerGone => allowSymlinksOutsideWorkspace defaults to false => symlink is followed and blocked.
+		const result = await authorizeRead({
+			task: makeTask({ providerGone: true }),
+			requestedPath: link,
+			source: "read_file",
+		})
+
+		expect(result).toMatchObject({ ok: false, reason: "symlink_escapes_workspace" })
+	})
+
+	it("fails closed when reading provider state throws", async () => {
+		if (!symlinksSupported) return
+		const secret = path.join(outside, "secret.txt")
+		await fs.writeFile(secret, "x")
+		const link = path.join(workspace, "link.txt")
+		await fs.symlink(secret, link)
+
+		const result = await authorizeRead({
+			task: makeTask({ getStateThrows: true }),
+			requestedPath: link,
+			source: "read_file",
+		})
+
+		expect(result).toMatchObject({ ok: false, reason: "symlink_escapes_workspace" })
+	})
+
+	it("fails closed when no workspace folder is open", async () => {
+		;(vscode.workspace as any).workspaceFolders = []
+		const file = path.join(workspace, "file.txt")
+		await fs.writeFile(file, "x")
+
+		const result = await authorizeWrite({ task: makeTask(), requestedPath: file, source: "write_to_file" })
+
+		expect(result).toMatchObject({ ok: false, reason: "outside_workspace" })
+	})
+})