pi-crew 0.6.1 → 0.6.4

package/src/utils/env-filter.ts

@@ -1,10 +1,56 @@
 import { isSecretKey } from "./redaction.ts";
 
+// Well-known LLM provider API keys that are intentionally allowlisted in
+// child-pi.ts and async-runner.ts for pass-through to worker processes.
+// These are "secret" by pattern (contain KEY/API) but are safe to allowlist
+// because they are standard provider credentials, not arbitrary secrets.
+const KNOWN_PROVIDER_KEYS = new Set([
+	"MINIMAX_API_KEY", "MINIMAX_GROUP_ID",
+	"OPENAI_API_KEY", "OPENAI_ORG_ID",
+	"ANTHROPIC_API_KEY",
+	"GOOGLE_API_KEY", "GOOGLE_GENERATIVE_LANGUAGE_API_KEY",
+	"AZURE_OPENAI_API_KEY", "AZURE_OPENAI_ENDPOINT",
+	"AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION",
+	"ZEU_API_KEY", "ZERODEV_API_KEY",
+]);
+
+function isKnownProviderKey(key: string): boolean {
+	return KNOWN_PROVIDER_KEYS.has(key);
+}
+
 export interface SanitizeEnvOptions {
 	/** Allow-list of env var names to preserve. Supports trailing glob, e.g. `"PI_*"`. */
 	allowList?: string[];
 }
 
+// Keywords that indicate a secret env var
+const SECRET_SUFFIXES = ["token", "api", "key", "password", "passwd", "secret", "credential", "authorization", "private"];
+
+/**
+ * Check if a glob pattern could match secret env vars.
+ * A pattern like "PI_*" is dangerous because it could match PI_TOKEN, PI_API_KEY, etc.
+ *
+ * Exception: `PI_CREW_*` is a controlled namespace — the pi-crew codebase owns
+ * every PI_CREW_* env var (PI_CREW_PARENT_PID, PI_CREW_ADAPTIVE_REPAIR, etc.)
+ * and none of them are secrets. Allowing the glob here lets child Pi processes
+ * inherit our config without needing a per-var allowlist.
+ */
+function isDangerousGlob(pattern: string): boolean {
+	if (!pattern.endsWith("*")) return false;
+	const prefix = pattern.slice(0, -1); // Remove trailing *
+	if (prefix === "") return true; // Single "*" matches everything
+	// PI_CREW_* is the pi-crew controlled namespace — no secrets live here.
+	// This covers PI_CREW_*, PI_CREW_TEAMS_*, PI_CREW_AGENT_*, etc.
+	if (prefix.startsWith("PI_CREW_") || prefix === "PI_CREW") return false;
+	// Check if combining the prefix with any secret suffix would create a secret key
+	for (const suffix of SECRET_SUFFIXES) {
+		if (isSecretKey(prefix + suffix)) {
+			return true;
+		}
+	}
+	return false;
+}
+
 /**
  * Strip env vars whose keys look like secrets before passing to child processes.
  *
@@ -14,11 +60,31 @@ export interface SanitizeEnvOptions {
 export function sanitizeEnvSecrets(env: NodeJS.ProcessEnv, options?: SanitizeEnvOptions): Record<string, string> {
 	const filtered: Record<string, string> = {};
 	if (options?.allowList && options.allowList.length > 0) {
+		// Validate allowlist patterns don't match secrets
+		for (const pattern of options.allowList) {
+			if (isDangerousGlob(pattern)) {
+				throw new Error(`Allowlist pattern "${pattern}" could match secret env vars. Use a more specific pattern.`);
+			}
+			// Validate non-glob entries don't look like secret keys.
+			// Exception 1: if the key exists in env, it was intentionally set and
+			// should be allowed through (user knows what they're doing).
+			// Exception 2: known provider keys (MINIMAX_API_KEY, etc.) are always
+			// allowed because they are standard provider credentials explicitly
+			// listed in async-runner.ts / child-pi.ts allowlists.
+			if (!pattern.endsWith("*") && isSecretKey(pattern) && !(pattern in env) && !isKnownProviderKey(pattern)) {
+				throw new Error(`Allowlist entry "${pattern}" looks like a secret key. Use a more specific pattern.`);
+			}
+		}
 		const matchers = options.allowList.map((p) => {
 			if (p.endsWith("*")) {
+				// Glob pattern: matches keys that start with the prefix AND have
+				// at least one additional character (distinguishes "PI_CREW_*" from "PI_CREW_").
+				// For example, "PI_CREW_*" matches "PI_CREW_DEPTH" but not "PI_CREW_".
+				// This ensures trailing glob patterns require extra chars, not exact-prefix-only matches.
 				const prefix = p.slice(0, -1);
 				return (k: string) => k.startsWith(prefix) && k.length > prefix.length;
 			}
+			// Exact match is case-sensitive; Unix env vars are uppercase by convention.
 			return (k: string) => k === p;
 		});
 		for (const [key, value] of Object.entries(env)) {

package/src/utils/file-coalescer.ts

@@ -6,7 +6,15 @@ interface TimerApi {
 }
 
 const defaultTimerApi: TimerApi = {
-	setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
+	setTimeout: (handler, delayMs) => {
+		const t = setTimeout(handler, delayMs);
+		// Defense in depth: never let a coalescer timer block process exit.
+		// The timer may be cleared before it fires; .unref() is idempotent.
+		if (typeof t === "object" && t && "unref" in t && typeof t.unref === "function") {
+			t.unref();
+		}
+		return t;
+	},
 	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
 };
 

package/src/utils/guards.ts

@@ -0,0 +1,110 @@
+/**
+ * Centralized type guard library for pi-crew.
+ *
+ * Inspired by @ayulab/runtime-core — all unknown-to-narrowed checks
+ * go through these helpers instead of inline typeof/instanceof.
+ */
+
+// ── Primitive guards ──────────────────────────────────────────────────
+
+/** Narrow `unknown` to `Record<string, unknown>`. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Narrow `unknown` to `string`. */
+export function isString(value: unknown): value is string {
+	return typeof value === "string";
+}
+
+/** Narrow `unknown` to a non-empty string. */
+export function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+/** Narrow `unknown` to `number` (excludes NaN). */
+export function isNumber(value: unknown): value is number {
+	return typeof value === "number" && !Number.isNaN(value);
+}
+
+/** Narrow `unknown` to `boolean`. */
+export function isBoolean(value: unknown): value is boolean {
+	return typeof value === "boolean";
+}
+
+/** Narrow `unknown` to `readonly string[]`. */
+export function isStringArray(value: unknown): value is readonly string[] {
+	return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+
+/**
+ * Higher-order guard: build a guard that checks every element of an array.
+ *
+ * @example
+ * const isNumberArray = isArrayOf(isNumber);
+ */
+export function isArrayOf<T>(
+	guard: (item: unknown) => item is T,
+): (value: unknown) => value is readonly T[] {
+	return (value: unknown): value is readonly T[] =>
+		Array.isArray(value) && value.every(guard);
+}
+
+// ── Record field extractors ───────────────────────────────────────────
+
+/** Extract a string field from a record, returning `undefined` if absent. */
+export function getStringField(value: unknown, key: string): string | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return typeof field === "string" ? field : undefined;
+}
+
+/** Extract a number field from a record, returning `undefined` if absent. */
+export function getNumberField(value: unknown, key: string): number | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return typeof field === "number" && !Number.isNaN(field) ? field : undefined;
+}
+
+/** Extract a boolean field from a record, returning `undefined` if absent. */
+export function getBooleanField(value: unknown, key: string): boolean | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return typeof field === "boolean" ? field : undefined;
+}
+
+/** Extract a nested record field from a record, returning `undefined` if absent. */
+export function getRecordField(value: unknown, key: string): Record<string, unknown> | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return isRecord(field) ? field : undefined;
+}
+
+/** Extract an array field from a record, returning `undefined` if absent. */
+export function getArrayField(value: unknown, key: string): unknown[] | undefined {
+	if (!isRecord(value)) return undefined;
+	const field = value[key];
+	return Array.isArray(field) ? field : undefined;
+}
+
+// ── Error helpers ─────────────────────────────────────────────────────
+
+/**
+ * Extract a human-readable message from an unknown error value.
+ *
+ * Prefer this over manual `instanceof Error` checks to keep error
+ * handling uniform across the codebase.
+ */
+export function errorMessage(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}
+
+// ── Utility types ─────────────────────────────────────────────────────
+
+/** A non-empty readonly array type. */
+export type NonEmptyReadonlyArray<T> = readonly [T, ...T[]];
+
+/** Narrow a readonly array to a non-empty readonly array. */
+export function hasItems<T>(items: readonly T[]): items is NonEmptyReadonlyArray<T> {
+	return items.length > 0;
+}

package/src/utils/paths.ts

@@ -9,7 +9,49 @@ export function packageRoot(): string {
 
 export function userPiRoot(): string {
 	const home = process.env.PI_TEAMS_HOME?.trim() || os.homedir();
-	return path.join(home, ".pi", "agent");
+	const resolved = path.join(home, ".pi", "agent");
+
+	// Reject symlinks to prevent confusion attacks where PI_TEAMS_HOME points to
+	// an attacker-controlled target via a user-owned symlink.
+	// We use lstatSync (does NOT follow) to detect symlinks before they are resolved.
+	// ENOENT is acceptable — the directory may not exist yet (caller will create it).
+	let isSymlink = false;
+	try {
+		const lstats = fs.lstatSync(resolved);
+		isSymlink = lstats.isSymbolicLink();
+	} catch (err: unknown) {
+		if (err instanceof Error && "code" in err && err.code !== "ENOENT") throw err;
+		// Path doesn't exist yet — caller will create it. Skip further validation.
+		return resolved;
+	}
+	if (isSymlink) {
+		throw new Error(
+			`userPiRoot: PI_TEAMS_HOME path "${resolved}" is a symlink. ` +
+			"Symlinks are not supported for PI_TEAMS_HOME to prevent confusion attacks. " +
+			"Set PI_TEAMS_HOME to a direct path owned by the current user.",
+		);
+	}
+
+	// Validate that the resolved path is owned by the current user
+	// to ensure security assumptions about file permissions (0o600/0o700) hold.
+	// Skip check if the directory does not exist yet.
+	try {
+		const stats = fs.statSync(resolved);
+		if (stats.uid !== os.userInfo().uid) {
+			throw new Error(
+				`userPiRoot: PI_TEAMS_HOME path "${resolved}" is not owned by the current user (uid=${os.userInfo().uid}, found uid=${stats.uid}). ` +
+				"This violates security assumptions about file permissions. Set PI_TEAMS_HOME to a path owned by the current user, or unset it to use the default.",
+			);
+		}
+	} catch (err: unknown) {
+		if (err instanceof Error && "code" in err && err.code !== "ENOENT") {
+			throw err;
+		}
+		// ENOENT from statSync means the directory was deleted between lstat and stat
+		// (race condition). This is acceptable — caller will handle.
+	}
+
+	return resolved;
 }
 
 const PROJECT_DIR_MARKERS = [".git", ".pi", ".crew", ".hg", ".svn", ".factory", ".omc"];
@@ -48,8 +90,34 @@ function hasProjectMarker(dir: string): boolean {
 	return false;
 }
 
+/** On Windows, resolve a path to its canonical long-name form.
+ *  Uses realpathSync.native to get the \\?\ long-name path, then strips
+ *  the prefix for path.relative compatibility. */
+function canonicalizePath(p: string): string {
+	try {
+		const r = fs.realpathSync.native(p);
+		return r.startsWith("\\\\?\\") ? r.slice(4) : r;
+	} catch {
+		try { return fs.realpathSync(p); } catch { return p; }
+	}
+}
+
 export function findRepoRoot(cwd: string): string | undefined {
-	const startKey = path.resolve(cwd);
+	// Resolve symlinks before walking to prevent malicious symlinks from bypassing
+	// home/temp boundary checks. If the path doesn't exist (e.g., caller passed
+	// a non-existent CWD like /tmp/no-such-dir), fall back to the lexical path
+	// and let computeRepoRoot handle the rest. ENOENT here is common for
+	// newly-created test directories and shouldn't propagate as a crash.
+	let startKey: string;
+	try {
+		startKey = fs.realpathSync(cwd);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			startKey = path.resolve(cwd);
+		} else {
+			throw error;
+		}
+	}
 	const cached = projectRootCache.get(startKey);
 	if (cached && Date.now() - cached.cachedAt < PROJECT_ROOT_CACHE_TTL_MS) {
 		// Re-insert to refresh LRU position.
@@ -82,18 +150,25 @@ function computeRepoRoot(start: string): string | undefined {
 }
 
 export function projectPiRoot(cwd: string): string {
-	return path.join(findRepoRoot(cwd) ?? cwd, ".pi");
+	const repoRoot = findRepoRoot(cwd) ?? cwd;
+	const piDir = path.join(repoRoot, ".pi");
+	// Use realpathSync to resolve any symlinks before returning to prevent
+	// config from being read from unexpected locations.
+	if (fs.existsSync(piDir)) return fs.realpathSync(piDir);
+	return piDir;
 }
 
 export function projectCrewRoot(cwd: string): string {
 	const repoRoot = findRepoRoot(cwd) ?? cwd;
 	const crewDir = path.join(repoRoot, ".crew");
 	// Keep an existing .crew/ stable even when .pi/ exists for project config.
-	if (fs.existsSync(crewDir)) return crewDir;
+	// Use canonicalizePath to get long-name form on Windows, matching
+	// what worktree operations and resolveRealContainedPath expect.
+	if (fs.existsSync(crewDir)) return canonicalizePath(crewDir);
 	// Legacy reuse: if .pi/ already exists for the project, namespace under .pi/teams/
 	// to avoid creating a parallel .crew/ alongside an existing pi project layout.
 	const piDir = path.join(repoRoot, ".pi");
-	if (fs.existsSync(piDir)) return path.join(piDir, "teams");
+	if (fs.existsSync(piDir)) return path.join(canonicalizePath(piDir), "teams");
 	return crewDir;
 }
 

package/src/utils/redaction.ts

@@ -7,8 +7,13 @@
 export const PEM_PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]+?-----END [A-Z ]+PRIVATE KEY-----/g;
 
 // Linear-time secret key detection
+// IMPORTANT: This function must maintain linear-time guarantees.
+// The fast-path regex uses simple string alternatives with anchors only (no quantifiers),
+// and the linear scan iterates through characters once. If either path is replaced with
+// a more complex regex, catastrophic backtracking (ReDoS) could result.
+// Any modifications must preserve O(n) complexity where n = keyName.length.
 export function isSecretKey(keyName: string): boolean {
-	// Fast path: common secret key names
+	// Fast path: common secret key names (safe anchored regex, no backtracking)
 	const lower = keyName.toLowerCase();
 	if (/^(token|apikey|api_key|password|secret|credential|authorization|privatekey|private_key)$/.test(lower)) {
 		return true;

package/src/utils/safe-paths.ts

@@ -16,30 +16,299 @@ export function resolveContainedPath(baseDir: string, targetPath: string): strin
 	}
 	const base = path.resolve(baseDir);
 	const resolved = path.isAbsolute(targetPath) ? path.resolve(targetPath) : path.resolve(base, targetPath);
-	const relative = path.relative(base, resolved);
+	// On Windows, paths are case-insensitive and short-name (8.3) aliases may
+	// differ from long-name forms (e.g. C:\Users\RUNNER~1 vs C:\Users\runneradmin).
+	// We normalize both paths to their canonical form by resolving through
+	// realpathSync, walking up ancestors for non-existent paths.
+	const baseNorm = process.platform === "win32" ? resolveWindowsCanonical(base) : base;
+	const resolvedNorm = process.platform === "win32" ? resolveWindowsCanonical(resolved) : resolved;
+	const relative = process.platform === "win32"
+		? path.relative(baseNorm.toLowerCase(), resolvedNorm.toLowerCase())
+		: path.relative(base, resolved);
 	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
 	return resolved;
 }
 
+/**
+ * On Windows, resolve a path to its canonical (long-name) form.
+ * Walks up ancestors until finding one that exists, then joins back down.
+ * This handles paths where intermediate directories don't exist yet but
+ * their ancestors do (and may use short-name aliases).
+ */
+function resolveWindowsCanonical(p: string): string {
+	try {
+		// Use regular realpathSync (not .native) to preserve the input path form.
+		// On Windows CI, .native always returns long-name (runneradmin) while
+		// non-native preserves short-name (RUNNER~1). Using non-native ensures
+		// the returned form matches what os.tmpdir() and mkdtempSync produce.
+		let real = fs.realpathSync(p);
+		// Guard against NTFS internal paths (e.g. C:\$Extend\$Deleted)
+		if (real.includes("$Extend") || real.includes("$Deleted")) throw new Error("NTFS internal path");
+		return real;
+	} catch {
+		// Fallback: try realpathSync (non-native) which may succeed where .native fails
+		try {
+			const real = fs.realpathSync(p);
+			return real;
+		} catch { /* proceed to ancestor walk */ }
+		// Walk up to find the deepest existing ancestor
+		const parts: string[] = [];
+		let current = p;
+		while (current !== path.dirname(current)) {
+			try {
+				// Use non-native to preserve input path form
+				let real = fs.realpathSync(current);
+				// Guard against NTFS internal paths
+				if (real.includes("$Extend") || real.includes("$Deleted")) throw new Error("NTFS internal path");
+				// Found existing ancestor — join with remaining parts in reverse order
+				// (parts were pushed bottom-up, so iterate from last to first)
+				for (let i = parts.length - 1; i >= 0; i--) {
+					real = path.join(real, parts[i]);
+				}
+				return real;
+			} catch { /* keep walking */ }
+			parts.push(path.basename(current));
+			current = path.dirname(current);
+		}
+		// Couldn't resolve any ancestor — return original
+		return p;
+	}
+}
+
+/**
+ * Resolve a target path to its real (symlink-resolved) absolute path while
+ * guaranteeing the result stays inside `baseDir`.
+ *
+ * ## Security model — asymmetric ancestor handling
+ *
+ * `baseDir` and `targetPath` are validated with different policies because
+ * they play different roles:
+ *
+ * - **baseDir** (the container): all ancestors MUST exist and MUST NOT be
+ *   symlinks. We refuse to operate if any component is missing or symlinked,
+ *   because a symlinked container could point the caller outside the
+ *   intended trust boundary (e.g. `/var/run -> /run` resolving into an
+ *   attacker-controlled directory).
+ *
+ * - **targetPath** (the contained file): the FINAL component may be
+ *   non-existent (for write operations creating a new file) and EXISTING
+ *   ancestors of the target may also be missing. We DO require that any
+ *   ancestor that DOES exist must not be a symlink — an attacker who can
+ *   create a directory in the container must not be able to redirect the
+ *   file being created.
+ *
+ * This asymmetry is intentional: callers that need to create a new file
+ * pass a non-existent targetPath. Callers that operate on an existing file
+ * get full symlink protection. Callers MUST NOT pass a symlinked
+ * intermediate component; if you need to, use `resolveContainedPath`
+ * instead (which only checks the resolved path, not the chain).
+ *
+ * Throws on:
+ *   - null byte in targetPath
+ *   - targetPath resolves outside baseDir
+ *   - any existing ancestor (base or target) is a symlink
+ *   - baseDir itself does not exist
+ *
+ * Returns the resolved real path on success, or the resolved (but not
+ * realpathed) path when the target does not exist yet.
+ *
+ * NOTE: There is a race condition window between validation and use where an
+ * attacker could create a directory component after validation but before the
+ * file is created. Callers MUST create parent directories atomically
+ * (e.g., mkdirSync with { recursive: true }) and use O_CREAT | O_NOFOLLOW | O_EXCL
+ * for atomic file creation, as atomicWriteFile does. This ensures the entire
+ * operation is atomic and prevents TOCTOU attacks.
+ */
 export function resolveRealContainedPath(baseDir: string, targetPath: string): string {
+	if (targetPath.includes('\0')) {
+		throw new Error(`Security: path contains null byte`);
+	}
 	const resolved = resolveContainedPath(baseDir, targetPath);
+
+	// Open baseDir with O_NOFOLLOW to atomically validate no symlinks in the path.
+	// O_NOFOLLOW makes the open fail with ELOOP if any path component is a symlink.
+	let baseFd: number | undefined;
+	try {
+		baseFd = fs.openSync(baseDir, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+	} catch (error) {
+		const errCode = (error as NodeJS.ErrnoException).code;
+		if (errCode === "ENOENT") {
+			// baseDir doesn't exist yet — create it and retry
+			try {
+				fs.mkdirSync(baseDir, { recursive: true });
+				baseFd = fs.openSync(baseDir, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+			} catch (retryError) {
+				throw new Error(`Cannot open base directory ${baseDir}: ${retryError instanceof Error ? retryError.message : String(retryError)}`);
+			}
+		} else if (errCode === "ELOOP") {
+			// On macOS, system directories like /var → /private/var contain symlinks.
+			// If baseDir is under such a path, resolve through realpath and retry.
+			if (process.platform === "darwin") {
+				try {
+					const realBaseDir = fs.realpathSync(baseDir);
+					if (realBaseDir !== baseDir) {
+						baseFd = fs.openSync(realBaseDir, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+						baseDir = realBaseDir; // update for later use
+						// Fall through to fstatSync below
+					}
+				} catch { /* throw original */ }
+			}
+			if (baseFd === undefined) throw new Error("Refusing to resolve: baseDir path contains a symlink: " + baseDir);
+		} else {
+			throw new Error(`Cannot open base directory ${baseDir}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
 	let realBase: string;
-	let realTarget: string;
 	try {
-		realBase = fs.realpathSync.native(baseDir);
-	} catch (baseError) {
-		throw new Error(`Cannot resolve real path of base directory ${baseDir}: ${baseError instanceof Error ? baseError.message : String(baseError)}`);
+		const stat = fs.fstatSync(baseFd);
+		if (!stat.isDirectory()) throw new Error(`baseDir ${baseDir} is not a directory`);
+		// Use regular realpathSync (not .native) to preserve input path form.
+		// On Windows CI, .native always returns long-name form (runneradmin)
+		// while non-native preserves short-name (RUNNER~1). Using non-native
+		// ensures the result matches what the caller passed in.
+		realBase = fs.realpathSync(baseDir);
+	} catch (error) {
+		// baseDir MUST exist and be resolvable for the containment guarantee to hold.
+		// Callers creating new directories must create baseDir atomically (e.g.,
+		// mkdirSync with { recursive: true }) BEFORE calling this function, and use
+		// O_NOFOLLOW|O_CREAT|O_EXCL for the actual file creation to ensure atomicity.
+		// The safe-paths validation and the file creation are two separate operations
+		// with a gap between them — callers must close this gap with atomic primitives.
+		throw new Error(`Cannot resolve real path of base directory ${baseDir}: ${error instanceof Error ? error.message : String(error)}`);
+	} finally {
+		fs.closeSync(baseFd);
+	}
+
+	// Walk the ancestor chain of the resolved target path, using O_NOFOLLOW
+	// on each ancestor to atomically validate none are symlinks.
+	const O_NOFOLLOW = fs.constants.O_NOFOLLOW;
+	const O_RDONLY = fs.constants.O_RDONLY;
+	const resolvedParts = resolved.split(path.sep);
+	let resolvedAccumulated = "";
+	if (resolvedParts[0] === "") resolvedAccumulated = "/"; // Unix root
+	for (let i = 1; i < resolvedParts.length; i++) {
+		if (resolvedParts[i] === "") continue;
+		resolvedAccumulated = path.join(resolvedAccumulated, resolvedParts[i]);
+		try {
+			const fd = fs.openSync(resolvedAccumulated, O_RDONLY | O_NOFOLLOW);
+			fs.closeSync(fd);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ELOOP") {
+			// On macOS, /var → /private/var, /tmp → /private/tmp, /etc → /private/etc
+			// are system symlinks managed by the OS. Allow them.
+			if (process.platform === "darwin") {
+				const resolvedSymlink = resolvedAccumulated;
+				const knownDarwinSymlinks = ["/var", "/tmp", "/etc", "/private/var", "/private/tmp", "/private/etc"];
+				if (knownDarwinSymlinks.includes(resolvedSymlink)) continue;
+			}
+			throw new Error("Refusing to resolve: target path ancestor is a symlink: " + resolvedAccumulated);
+		}
+			// EPERM on Windows when opening a directory — skip validation
+			if ((error as NodeJS.ErrnoException).code === "EPERM" && process.platform === "win32") continue;
+			// ENOENT means component doesn't exist — that's OK. Only existing symlinks
+			// are a security risk (symlinks to attacker-controlled targets). Non-existent
+			// paths can be created by the caller and don't pose a symlink risk.
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			// For the final component (target itself), ENOENT is expected for non-existent targets.
+			if (i === resolvedParts.length - 1) continue;
+			// For non-final components (parent directories), ENOENT is also acceptable —
+			// the caller will create them before the write operation if needed.
+			// We only need to ensure no existing path component is a symlink.
+			continue;
+		}
+	}
+
+	// Open the target with O_NOFOLLOW to catch any symlinks.
+	// ENOENT is acceptable for write operations — the file may not exist yet.
+	let targetFd: number;
+	try {
+		targetFd = fs.openSync(resolved, O_RDONLY | O_NOFOLLOW);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ELOOP") throw new Error("Refusing to resolve: target path is a symlink: " + resolved);
+		// EPERM on Windows when opening a directory — treat as non-existent
+		if ((error as NodeJS.ErrnoException).code === "EPERM" && process.platform === "win32") return resolved;
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			// Target doesn't exist yet — that's OK for write operations.
+			// All ancestors have been validated above (no symlinks).
+			// The caller will create the file with atomic primitives.
+			return resolved;
+		}
+		throw new Error(`Cannot open ${resolved}: ${error instanceof Error ? error.message : String(error)}`);
 	}
+
+	let realTarget: string;
 	try {
-		realTarget = fs.realpathSync.native(resolved);
+		// Use regular realpathSync (not .native) to preserve input path form.
+		realTarget = fs.realpathSync(resolved);
 	} catch (targetError) {
 		if ((targetError as NodeJS.ErrnoException).code === "ENOENT") {
-			throw new Error(`Path does not exist: ${resolved}`);
+			// Target doesn't exist yet — this is OK for write operations.
+			// Return the resolved path so the caller can create the file.
+			// We already validated all ancestors are not symlinks above.
+			return resolved;
 		}
 		throw new Error(`Cannot resolve real path of ${resolved}: ${targetError instanceof Error ? targetError.message : String(targetError)}`);
+	} finally {
+		fs.closeSync(targetFd);
+	}
+
+	// Re-validate the ancestor chain of the resolved path to catch any TOCTOU
+	// races that occurred between the initial O_NOFOLLOW validation and the
+	// realpathSync call. An attacker could have replaced a validated ancestor
+	// with a symlink during this window.
+	//
+	// Skip the final path component (realTarget itself) — we just successfully
+	// realpathSync'd it, so it exists. Re-validating it can spuriously fail on
+	// Windows where the resolved path uses short-name (8.3) form that
+	// openSync cannot reopen, or where the realpathSync result differs in
+	// case/separator form from the original.
+	//
+	// Walk via path.dirname which is portable across all platforms and
+	// correctly handles extended-length (\\?\), UNC (\\server\share), and
+	// short-name paths on Windows without manual parsing.
+	let ancestor = path.dirname(realTarget);
+	while (ancestor && ancestor !== path.dirname(ancestor)) {
+		try {
+			const fd = fs.openSync(ancestor, O_RDONLY | O_NOFOLLOW);
+			fs.closeSync(fd);
+		} catch (error) {
+			const errCode = (error as NodeJS.ErrnoException).code;
+			if (errCode === "ELOOP") throw new Error("Refusing to resolve: TOCTOU race detected, path became a symlink: " + ancestor);
+			// Windows: EPERM can occur when opening system directories (e.g. C:\)
+			// or NTFS internal paths ($Extend/$Deleted). Skip and continue walking.
+			if (process.platform === "win32" && errCode === "EPERM") {
+				if (ancestor.includes("$Extend") || ancestor.includes("$Deleted")) {
+					// NTFS internal path — stop walking, we've reached the filesystem root
+					break;
+				}
+				// System directory — continue walking up
+				ancestor = path.dirname(ancestor);
+				continue;
+			}
+			if (errCode !== "ENOENT") throw error;
+			// ENOENT on an ancestor of realTarget after realpathSync is concerning
+			// — the path existed when we validated it but now doesn't. This could
+			// indicate a race or attack. For safety, treat this as an error.
+			throw new Error(`Cannot validate resolved path: ${ancestor} disappeared after realpathSync: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		ancestor = path.dirname(ancestor);
+	}
+
+	// Verify the resolved real path is still within baseDir.
+	// On Windows, realpathSync.native may return different short/long-name forms
+	// for the same physical directory depending on how the path was opened.
+	// Use resolveWindowsCanonical (same as resolveContainedPath) to normalize
+	// both paths consistently before comparison.
+	if (process.platform === "win32") {
+		const normBase = resolveWindowsCanonical(realBase).replace(/\\/g, "/").toLowerCase();
+		const normTarget = resolveWindowsCanonical(realTarget).replace(/\\/g, "/").toLowerCase();
+		if (!normTarget.startsWith(normBase + "/") && normBase !== normTarget) {
+			throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
+		}
+	} else {
+		const relative = path.relative(realBase, realTarget);
+		if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
 	}
-	const relative = path.relative(realBase, realTarget);
-	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
 	return realTarget;
 }
 
@@ -47,7 +316,9 @@ export function resolveContainedRelativePath(baseDir: string, relativePath: stri
 	if (relativePath.includes('\0')) {
 		throw new Error(`Security: path contains null byte: ${kind}`);
 	}
-	const normalized = relativePath.replaceAll("\\", "/").replace(/^\.\/+/, "");
+	const normalized = relativePath.replace(/\\/g, "/").replace(/^\.\/+/, "");
+	// Detect Windows absolute paths (C:\, \\server\share) that path.isAbsolute may miss after normalization
+	if (/^[A-Za-z]:/.test(normalized)) throw new Error(`Invalid ${kind}: ${relativePath}`);
 	if (!normalized || normalized.split("/").some((segment) => segment === "..") || path.isAbsolute(normalized)) throw new Error(`Invalid ${kind}: ${relativePath}`);
 	return resolveContainedPath(baseDir, path.resolve(baseDir, normalized));
 }