proposal: os: add File.Root method to safely convert a File into a Root

[Jorropo]

Proposal Details

I have code which opens both files and directories as files to perform various actions such as fetching and comparing generations (I need to upstream to linux once I write tests) or other metadata with SyscallConn.

Trying to use #67002 to make it less conservative with some TOCTOU edge cases prove challenging since *os.Root does not provide needed SyscallConn to fetch the generation of directories and more architecturally the current codepath is to open everything as a *os.File and then use statx to decide what to do next.

---

package os

// AsRoot open the File as a Root if it is a directory otherwise it errors.
// The Root is returned with a new lifetime such that each need to be closed independently.
func (*File) AsRoot() (*Root, error)

// AsFile opens the Root as a File.
// The File is returned with a new lifetime such that each need to be closed independently.
func (*Root) AsFile() (*File, error)

[Jorropo]

I discussed this with @neild already and:
I think it might be possible to convert *os.File → *os.Root by using SyscallConn then calling os.OpenRoot with fmt.Sprintf("/proc/self/fd/%d") on Linux.
Not portable tho.

He pointed out *os.Root → *os.File should be possible by calling (*os.Root).Open(root, ".").

[Jorropo]

I am not sure if lifetimes should be independent or not.
I guess from a point of implementing in the std this is the easiest, but as a consumer I would sometime want the opposite.

[neild]

I would not want to try to have a Root and a File as two views of the same file descriptor. (In some cases, Roots don't even have a file descriptor.)

You can go from a Root to a File with root.Open("."), at the expense of creating a new FD.

Going from a File to a Root is not currently possible. I can imagine a method on File which lets you do so:

// Root returns a root rooted at the location of f, which must be a directory file.
func (f *File) Root() (*Root, error)

I don't know if there's a need for that operation; motivating use cases would be useful.

It might be reasonable to add a Root.SyscallConn method to give access to a root's FD, with the caveat that this method would return an error on platforms where a root doesn't have an FD (GOOS=js, GOOS=plan9). But perhaps that isn't necessary, and root.Open(".") is sufficient.

[shanduur]

@neild I didn't noticed that there was already a proposal for this, so I opened duplicate (#75084). I think, that I explained the rationale in the document above, but I will rewrite the most important part/rationale here:

What's most important for me, Linux's new mount API (kernel 5.2+) introduces powerful syscalls for filesystem management that work entirely with file descriptors.

1. fsopen() + fsmount() - Programmatic Filesystem Creation

// Create tmpfs entirely through syscalls
fsfd, _ := unix.Fsopen("tmpfs", unix.FSOPEN_CLOEXEC)
unix.FsconfigSetString(fsfd, "size", "100M")
unix.FsconfigSetString(fsfd, "mode", "0755")
unix.FsconfigCreate(fsfd)
mntfd, _ := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC, 0)

// Convert to Root for secure operations
file := os.NewFile(uintptr(mntfd), "tmpfs-mount")
root, err := file.AsRoot() // Proposed functionality

2. open_tree() - Filesystem Subtree Cloning

// Clone a filesystem subtree
mntfd, err := unix.OpenTree(unix.AT_FDCWD, "/some/directory", 
    unix.OPEN_TREE_CLONE|unix.OPEN_TREE_CLOEXEC)
if err != nil {
    return err
}

// Create Root from cloned mount
file := os.NewFile(uintptr(mntfd), "cloned-mount")
root, err := file.AsRoot() // Secure operations on cloned tree

3. Mount Namespace Operations

// Create overlay filesystem programmatically
fsfd, _ := unix.Fsopen("overlay", unix.FSOPEN_CLOEXEC)
unix.FsconfigSetString(fsfd, "lowerdir", "/base")
unix.FsconfigSetString(fsfd, "upperdir", "/changes")
unix.FsconfigSetString(fsfd, "workdir", "/work")
unix.FsconfigCreate(fsfd)
mntfd, _ := unix.Fsmount(fsfd, unix.FSMOUNT_CLOEXEC, 0)

// Convert to Root for namespace-aware operations
file := os.NewFile(uintptr(mntfd), "overlay-mount")
root, err := file.AsRoot()

4. File Descriptor-Based Mount Operations

// Work with existing directory fd
dirfd, _ := unix.Open("/base/directory", unix.O_RDONLY, 0)

// Clone subtree from fd (no path needed)
mntfd, _ := unix.OpenTree(dirfd, "", 
    unix.OPEN_TREE_CLONE|unix.AT_EMPTY_PATH|unix.OPEN_TREE_CLOEXEC)

// Convert to Root
file := os.NewFile(uintptr(mntfd), "fd-mount")
root, err := file.AsRoot()

Adding the new AsRoot() function converting *os.File to *os.Root would greatly simplify operations e.g. on anonymous filesystems, without mounting them, and allowing external actors to perform any operations on them.

[lVlayhem]

Motivating example could be a need to check that no symlinks where evaluated when accessing a path - while avoiding TOCTOU races.
AFAIK this can only be done when processing a chain of file descriptors (instead of file names).
And need to have ability to call stat/Lstat on the root, so convertion File <-> Root might help.

[neild]

To covert from a Root to a File, I think root.Open(".") suffices.

We don't have a good way to convert from a File to a Root without reevaluating the file's path, which is subject to TOCTOU races. There are a few reasonable motivating cases above for how one might end up with a File and be in need of a Root. In particular, there's no way to go from a file descriptor to a Root. Converting a File to a Root would address this, since os.NewFile creates a File from a file descriptor.

Bikeshedding a bit, I like File.Root a bit better than File.AsRoot. It's more consistent with method names like File.Fd. (Alternatively, File.OpenRoot would be consistent with os.OpenRoot.)

File.Root could return a root that shares the File's FD, or it could dup the FD. I think duplicating it is safer and clearer.

So:

package os

// Root returns a Root rooted at the directory associated with the file f.
// It returns an error if f is not a directory.
func (f *File) Root() (*Root, error)

We will need to add a caveat for platforms (GOOS=js, GOOS=plan9) where we will need to open the root by name rather than by reusing the File's FD.