Security: WorkFolderTools.resolvePath ignores symlinks — escape via symlink possible

[mimeding]

Summary

Why this matters (business)

Work mode lets an agent read, edit, and run files inside a designated project folder. The whole safety story for "the agent can't accidentally rewrite my home directory" rests on WorkFolderToolHelpers.resolvePath — every file tool routes through it. If that helper accepts a path that escapes the work root, every downstream file operation inherits the escape.

The helper rejected ../etc/passwd-style escapes correctly (lexical .. is collapsed by .standardized before the prefix check). What it didn't reject was symlink-based escape: a symlink planted inside the work root that points to /etc, the user's ~/Documents, or any other path outside the project. An agent (or a malicious project template, or a routine git checkout of an attacker-controlled repo) could create such a symlink and then read/write through it while the containment check happily said "yes, that's inside the work root."

What's wrong (technical)

    static func resolvePath(_ relativePath: String, rootPath: URL) throws -> URL {
        let cleanPath = relativePath.hasPrefix("/") ? String(relativePath.dropFirst()) : relativePath
        let resolvedURL = rootPath.appendingPathComponent(cleanPath).standardized
        let rootPathString = rootPath.standardized.path

        guard resolvedURL.path.hasPrefix(rootPathString) else {
            throw WorkFolderToolError.pathOutsideRoot(relativePath)
        }
        return resolvedURL
    }

URL.standardized is purely lexical — it collapses .. and /./ but never reads the filesystem and never follows symbolic links. So a file named escape inside the work root that's actually a symlink to /some/private/dir lexically lives at <root>/escape, passes the prefix check, and the file tool then operates on /some/private/dir/....

Two additional pitfalls the audit's recommendation has to handle:

1. The prefix check uses hasPrefix(rootPathString) without a trailing separator. <root> = "/work/foo" would also match "/work/foo-evil/file" — a sibling directory with a name that happens to share a prefix.
2. On macOS, common roots like /var are themselves symlinks (/private/var). Naively resolving symlinks on the candidate path but not the root would cause every legitimate project whose path runs through a system symlink to fail containment.

Fix

Add a symlink-aware second pass:

let symlinkResolvedURL = resolvedURL.resolvingSymlinksInPath()
let symlinkResolvedRoot = rootPath.resolvingSymlinksInPath().standardized.path
let rootWithSeparator =
    symlinkResolvedRoot.hasSuffix("/") ? symlinkResolvedRoot : symlinkResolvedRoot + "/"

let resolvedPath = symlinkResolvedURL.path
let isInside =
    resolvedPath == symlinkResolvedRoot
    || resolvedPath.hasPrefix(rootWithSeparator)
guard isInside else {
    throw WorkFolderToolError.pathOutsideRoot(relativePath)
}
return resolvedURL

• Both sides are symlink-resolved, so macOS-typical roots via /var → /private/var work.
• Containment uses a trailing-/ prefix (or full-equality for the root itself), so sibling-directory false matches are impossible.
• The returned URL is intentionally the non-symlink-resolved one — callers that need an URL to hand to FileManager/Data(contentsOf:) get the same surface they always got; only the guard changed.

Scope decisions

This fixes WorkFolderTools.resolvePath. The same pattern (.standardized-only) exists elsewhere in the codebase (plugin static-asset serving in HTTPHandler.swift, sandbox setup URL handling). Those deserve their own focused PRs so each change can be reviewed against the constraints of its caller.

Changes

• Behavior change (file-tool path containment is now symlink-aware)
• UI change
• Refactor / chore
• Tests (new WorkFolderToolsResolvePathTests)
• Docs

Test Plan

cd Packages/OsaurusCore && swift test --filter WorkFolderToolsResolvePathTests

Manually: in a work folder, create escape -> /etc (e.g. ln -s /etc /work-root/escape). Ask the agent to read escape/passwd. Expected: the file-tool returns pathOutsideRoot. Previously: the agent could read /etc/passwd.

Checklist

• I have read CONTRIBUTING.md
• I added/updated tests where reasonable
• I updated docs/README as needed (n/a — internal helper)
• I verified build on macOS with Xcode 16.4+ (authored in a Linux sandbox; verified each touched file via swiftc -frontend -parse; the new tests use only Foundation FileManager APIs that work the same on both platforms)