Path confinement in Go belongs at the directory handle
An application that serves user-provided file names often begins with a simple check for .. or a call to filepath.Clean. Those checks miss the harder case: a path can stay syntactically inside a string while a symbolic link redirects the open operation somewhere else. Go 1.24 added os.Root to make that boundary part of the filesystem operation itself.
Why string validation is fragile
filepath.Join(root, userPath) can still produce a path whose final resolution escapes the intended directory. A local attacker may create or replace a symbolic link between validation and open. Cleaning the string before that race does not provide a reliable confinement property.
The Go project describes os.Root as a handle to one directory tree. Its methods refuse names that refer outside that tree, including through .. or symbolic links. This shifts the check to the operation that opens the file rather than leaving the application to reason about the filesystem state separately.
A smaller API boundary
Open the root once, then pass only the untrusted relative name to methods on that object.
root, err := os.OpenRoot("/srv/uploads") if err != nil { return err } defer root.Close() f, err := root.Open(userPath) if err != nil { return err } defer f.Close() The root handle should come from trusted configuration. Do not reopen a user-controlled absolute directory for each request. Also keep the policy around purpose and file type outside the path check. A confined file can still be a dangerous format, a huge input, or a special device exposed inside the tree.
What os.Root does not cover
The Go documentation is explicit about limits. os.Root does not prohibit traversal across filesystem boundaries, Linux bind mounts, /proc special files, or Unix device files. A mount point inside the root can expose another tree. A device node inside the root remains a device node.
That matters for multi-tenant upload directories and directories assembled from plugin-controlled mounts. Use a dedicated filesystem or mount namespace when the operating-system boundary has to be stronger than the application boundary. If uploads are stored beside executables or service credentials, move them to a separate path with restrictive ownership.
Tests that describe the boundary
A useful test suite should try ../outside, nested traversal, an absolute path, a symbolic link to an outside directory, a symbolic link that is replaced during a request, and a link whose target is a special file. The expected result is a refusal or an application-defined error. A test that only checks the cleaned string does not exercise the same condition.
Also test the trusted root itself. If the deployment accepts a symlink to / as its upload root, the application has granted the wrong directory before any user request arrives. Log the resolved root, owner, mount, and policy version at startup.
The operational review should ask who can create links or mount points below the root, which process owns the directory, whether every file read uses the same root object, and whether administrative tools bypass the application. os.Root is useful when those answers are known and the remaining path race is real.

