sfs

Documentation

Overview

The sfs package providing a secure file system, with access limitations.

Index

• func EquivalentPaths(p1, p2 string) (bool, error)
• func HasFilepathPrefix(path, prefix string) (bool, error)
• func IsCaseSensitiveFilesystem(dir string) (bool, error)
• func IsDir(name string) (bool, error)
• func IsRegular(name string) (bool, error)
• func IsSymlink(path string) (bool, error)
• type FS
  • func (fs *FS) Accessible(path string, flags Flags) error
  • func (fs *FS) AddRoot(path string) error
  • func (fs *FS) Create(name string) (*os.File, error)
  • func (fs *FS) Mkdir(name string, perm os.FileMode) error
  • func (fs *FS) MkdirAll(name string, perm os.FileMode) error
  • func (fs *FS) Open(name string) (*os.File, error)
  • func (fs *FS) ReadDir(dirname string) ([]os.DirEntry, error)
  • func (fs *FS) Remove(name string) error
  • func (fs *FS) RemoveAll(path string) error
  • func (fs *FS) RemoveRoot(path string) error
  • func (fs *FS) Rename(oldpath, newpath string) error
  • func (fs *FS) Roots() []string
  • func (fs *FS) Secured() bool
  • func (fs *FS) SetSecured(secured bool)
  • func (fs *FS) Stat(name string) (os.FileInfo, error)
• type Flags

Functions

func EquivalentPaths

func EquivalentPaths(p1, p2 string) (bool, error)

EquivalentPaths compares the paths passed to check if they are equivalent. It respects the case-sensitivity of the underlying filesysyems.

func HasFilepathPrefix

func HasFilepathPrefix(path, prefix string) (bool, error)

HasFilepathPrefix will determine if "path" starts with "prefix" from the point of view of a filesystem.

Unlike filepath.HasPrefix, this function is path-aware, meaning that it knows that two directories /foo and /foobar are not the same thing, and therefore HasFilepathPrefix("/foobar", "/foo") will return false.

This function also handles the case where the involved filesystems are case-insensitive, meaning /foo/bar and /Foo/Bar correspond to the same file. In that situation HasFilepathPrefix("/Foo/Bar", "/foo") will return true. The implementation is *not* OS-specific, so a FAT32 filesystem mounted on Linux will be handled correctly.

func IsCaseSensitiveFilesystem

func IsCaseSensitiveFilesystem(dir string) (bool, error)

IsCaseSensitiveFilesystem determines if the filesystem where dir exists is case sensitive or not.

CAVEAT: this function works by taking the last component of the given path and flipping the case of the first letter for which case flipping is a reversible operation (/foo/Bar → /foo/bar), then testing for the existence of the new filename. There are two possibilities:

1. The alternate filename does not exist. We can conclude that the filesystem is case sensitive.

2. The filename happens to exist. We have to test if the two files are the same file (case insensitive file system) or different ones (case sensitive filesystem).

If the input directory is such that the last component is composed exclusively of case-less codepoints (e.g. numbers), this function will return false.

func IsDir

func IsDir(name string) (bool, error)

IsDir determines is the path given is a directory or not.

func IsRegular

func IsRegular(name string) (bool, error)

IsRegular determines if the path given is a regular file or not.

func IsSymlink

func IsSymlink(path string) (bool, error)

IsSymlink determines if the given path is a symbolic link.

Types

type FS

type FS struct {
	// contains filtered or unexported fields
}

FS contains wrappers for common file system functions that also check whether a given path can be accessed. The zero value of an FS is ready for use.

A path is accessible if it is a descendant of a root in FS. A root is not accessible unless the Root flag is specified.

func (*FS) Accessible

func (fs *FS) Accessible(path string, flags Flags) error

Accessible returns an error if path cannot be accessed.

func (*FS) AddRoot

func (fs *FS) AddRoot(path string) error

AddRoot adds path as a root. Returns an error if the path could not be converted to an absolute path. Does nothing if the path is an empty string or is already a root.

func (*FS) Create

func (fs *FS) Create(name string) (*os.File, error)

Create wraps os.Create, returning an error if name cannot be accessed.

func (*FS) Mkdir

func (fs *FS) Mkdir(name string, perm os.FileMode) error

Create wraps os.Mkdir, returning an error if name cannot be accessed.

func (*FS) MkdirAll

func (fs *FS) MkdirAll(name string, perm os.FileMode) error

Create wraps os.MkdirAll, returning an error if name cannot be accessed.

func (*FS) Open

func (fs *FS) Open(name string) (*os.File, error)

Create wraps os.Open, returning an error if name cannot be accessed.

func (*FS) ReadDir

func (fs *FS) ReadDir(dirname string) ([]os.DirEntry, error)

Create wraps os.ReadDir, returning an error if dirname cannot be accessed. dirname is allowed to be a root.

func (*FS) Remove

func (fs *FS) Remove(name string) error

Create wraps os.Remove, returning an error if name cannot be accessed.

func (*FS) RemoveAll

func (fs *FS) RemoveAll(path string) error

Create wraps os.RemoveAll, returning an error if name cannot be accessed.

func (*FS) RemoveRoot

func (fs *FS) RemoveRoot(path string) error

RemoveRoot removes path as a root. Returns an error if the path could not be converted to an absolute path. Does nothing if the path is an empty string or is not a root.

func (*FS) Rename

func (fs *FS) Rename(oldpath, newpath string) error

Create wraps os.Rename, returning an error if oldpath or newpath cannot be accessed.

func (*FS) Roots

func (fs *FS) Roots() []string

Roots returns a list of roots in the FS.

func (*FS) Secured

func (fs *FS) Secured() bool

Secured returns whether paths are secured. If false, then any path can be accessed.

func (*FS) SetSecured

func (fs *FS) SetSecured(secured bool)

SetSecured sets whether paths are secured. If false, then any path can be accessed.

func (*FS) Stat

func (fs *FS) Stat(name string) (os.FileInfo, error)

Create wraps os.Stat, returning an error if name cannot be accessed.

type Flags

type Flags int

Flags alter how access checks are made.

const (
	Root Flags // Path is accessible if it is a root directory.
)