Part 5 of 13 · 2 min read
Path confinement is what stops a file tool from reaching outside its own workspace
A tool that can write anywhere the operating system allows is not a workspace, it's the whole filesystem with extra steps.
Think of a guest room with a door that locks from the inside. A guest can rearrange everything inside the room. But the lock is what keeps "inside the room" and "the rest of the house" two different things, even if a window appears to lead somewhere else.
In plain words: path confinement means every path is resolved (following symlinks and removing .. segments) and checked to lie under the workspace root before any read or write happens. This is necessary because a naive check for the substring ".." misses real escapes. It misses a symlink inside the workspace that points outside it. It also misses a path like a/../../x that resolves outside even though it never contains a suspicious-looking standalone .. token in a simple string search.
A worked example. The workspace refuses ../x, /etc/passwd, a/../.., an empty path, a NUL-containing path, a symlinked file whose target is outside the root, and a symlinked directory that leads outside -- all seven attempts raise WorkspaceError before any file operation runs. A write is also atomic: forcing the rename step to fail during a test still leaves the previous version of the file intact, because the new content is written to a temporary file first and only swapped into place with os.replace if the write succeeds completely.
The key lines. From code/mini-workspace/workspace.py:
# from code/mini-workspace/workspace.py
def safe_path(self, name: str) -> Path:
if not name or "\x00" in name:
raise WorkspaceError("empty or invalid path")
p = (self.root / name).resolve() # resolve() follows symlinks and removes '..'
if p != self.root and self.root not in p.parents:
raise WorkspaceError(f"path escapes the workspace: {name}")
return p
Read it as: the check happens after .resolve(), not before. Resolving first is what makes the check correct: it converts a symlink or a ..-laden path into its real, final destination. Only then does it ask the one question that matters, "is this really under the root" — a check against the raw, unresolved string could never answer that correctly.
Path confinement, symlink escape, atomic write
Path confinement is resolving every path and checking the result lies under the workspace root. A symlink escape is a link inside the workspace whose target is outside it. An atomic write is writing to a temporary file and renaming it over the target, so a reader or a crash sees the old file or the new one, never half of one.
Example: all seven escape attempts failing with WorkspaceError, including the two symlink cases a plain string check would miss, is path confinement doing exactly the job its name promises -- the workspace is bounded by what resolve() says is true, not by what the path string looks like.