pathsafe

Documentation

Overview

Package pathsafe normalizes repository-relative paths and proves that a materialization destination stays inside its root. Every path read from a repository, catalog, release, hook request, or persistent-path declaration passes through here before it touches the filesystem.

Rules (docs/security/threat-model.md, "path traversal"):

• repository paths use "/" separators, are relative, contain no empty, ".", or ".." segments, no NUL, no backslash, no drive letters, and no leading "/";
• segments are literal; "maps" is a directory name, never a glob;
• Windows reserved device names and trailing dots/spaces are rejected so a path cannot resolve differently across platforms;
• Join refuses to produce a filesystem path outside root even when a segment is later replaced by a symlink: callers must open with O_NOFOLLOW / verify realpath, and Materializer must never follow symlinks inside root.

Index

• Variables
• func IsBracketCategory(seg string) bool
• func Join(root, rel string) (string, error)
• func Normalize(p string) (string, error)
• func Overlaps(a, b string) bool
• func Within(root, path string) bool

Variables

var (
	ErrEmpty         = errors.New("pathsafe: empty path")
	ErrAbsolute      = errors.New("pathsafe: absolute path not allowed")
	ErrTraversal     = errors.New("pathsafe: path escapes root")
	ErrBadSegment    = errors.New("pathsafe: invalid path segment")
	ErrBadCharacter  = errors.New("pathsafe: invalid character in path")
	ErrReservedName  = errors.New("pathsafe: reserved or platform-ambiguous name")
	ErrNotNormalized = errors.New("pathsafe: path is not normalized")
)

Errors.

Functions

func IsBracketCategory

func IsBracketCategory(seg string) bool

IsBracketCategory reports whether the final segment is a FiveM bracketed category such as "maps". Brackets are literal directory names, never globs.

func Join

func Join(root, rel string) (string, error)

Join returns filepath.Join(root, rel) after proving the result stays inside root lexically. rel must already be normalized (Normalize is applied). root must be absolute and clean; the caller is responsible for resolving symlinks in root itself (filepath.EvalSymlinks) before calling Join.

func Normalize

func Normalize(p string) (string, error)

Normalize validates a repository-relative path and returns its normalized form. It rejects rather than repairs: "a//b", "./a", "a/../b" and "a\b" are errors so that stored paths are always byte-identical to their canonical form and can be compared without re-normalization.

func Overlaps

func Overlaps(a, b string) bool

Overlaps reports whether two normalized repository paths are equal or one is an ancestor of the other. Used for mount and persistent-path validation.

func Within

func Within(root, path string) bool

Within reports whether path is root or a lexical descendant of root. Both are expected to be absolute cleaned OS paths.