fsutil

Documentation

Overview

Package fsutil provides shared filesystem path safety helpers.

Index

• Variables
• func HasDotDotPathSegment(path string) bool
• func RejectSymlinkInRoot(root, path string) error
• func RejectSymlinkLeaf(path string) error
• func RejectSymlinkPathAndParent(path string) error
• func RejectSymlinkWalk(path string, opts WalkOptions) error
• func SafeID(id string) string
• type MissingMode
• type PathEscapesError
  • func (e *PathEscapesError) Error() string
  • func (e *PathEscapesError) Is(target error) bool
• type SymlinkError
  • func (e *SymlinkError) Error() string
  • func (e *SymlinkError) Is(target error) bool
• type WalkOptions

Variables

var ErrPathEscapes = errors.New("path escapes root")

ErrPathEscapes indicates a path escapes a required root directory.

var ErrSymlink = errors.New("symlink path component rejected")

ErrSymlink indicates a path component is a symbolic link.

Functions

func HasDotDotPathSegment

func HasDotDotPathSegment(path string) bool

HasDotDotPathSegment reports whether path contains a ".." segment.

func RejectSymlinkInRoot

func RejectSymlinkInRoot(root, path string) error

RejectSymlinkInRoot walks every path component from root to path (inclusive) and fails if any is a symlink. path must be under root.

func RejectSymlinkLeaf

func RejectSymlinkLeaf(path string) error

RejectSymlinkLeaf fails if path exists and is a symlink. A missing path is OK.

func RejectSymlinkPathAndParent

func RejectSymlinkPathAndParent(path string) error

RejectSymlinkPathAndParent ensures path (if it exists) is not a symlink, and that its immediate parent directory (if it exists) is not a symlink.

It does not walk all the way to the filesystem root: on macOS /var is a symlink to /private/var, which is a normal system layout and must not fail closed. Callers that manage a store root should additionally use RejectSymlinkInRoot so every component under the store root is checked.

func RejectSymlinkWalk

func RejectSymlinkWalk(path string, opts WalkOptions) error

RejectSymlinkWalk walks path components and rejects symlink components according to opts.

func SafeID

func SafeID(id string) string

SafeID sanitizes an ID for use as a single path component. Rejects empty, traversal, separators, and control characters by hashing unsafe input into a stable, safe component.

Types

type MissingMode

type MissingMode int

MissingMode controls how missing path components are treated during a walk.

const (
	// MissingFail rejects any missing component.
	MissingFail MissingMode = iota
	// MissingAllowLeaf allows only the final component to be missing.
	MissingAllowLeaf
	// MissingAllowAll allows any component to be missing.
	MissingAllowAll
)

type PathEscapesError

type PathEscapesError struct {
	Path string
	Root string
}

PathEscapesError carries path/root when a path escapes its root.

func (*PathEscapesError) Error

func (e *PathEscapesError) Error() string

func (*PathEscapesError) Is

func (e *PathEscapesError) Is(target error) bool

type SymlinkError

type SymlinkError struct {
	Path string
}

SymlinkError carries the offending symlink path.

func (*SymlinkError) Error

func (e *SymlinkError) Error() string

func (*SymlinkError) Is

func (e *SymlinkError) Is(target error) bool

type WalkOptions

type WalkOptions struct {
	// RequireAbsolute requires the cleaned path to be absolute.
	RequireAbsolute bool
	// RejectDotDot rejects a ".." path segment in the cleaned path.
	RejectDotDot bool
	// ResolveAbs runs filepath.Abs before walking.
	ResolveAbs bool
	// Missing controls missing-component policy.
	Missing MissingMode
	// SkipVolumeRootSymlinks skips symlink rejection for components whose
	// parent is the filesystem root (e.g. allow macOS /var -> /private/var).
	// Uses an upward walk matching historical pack.detect behavior.
	SkipVolumeRootSymlinks bool
}

WalkOptions configures RejectSymlinkWalk.