README
¶
fileutil Package
Utility functions for security-conscious file path validation and common file operations.
Overview
The fileutil package focuses on security-conscious file handling: path validation, directory-boundary enforcement, and straightforward file and directory operations. It also provides a cross-platform tar extraction helper that guards against path-traversal payloads embedded in archives.
All functions emit debug output only when DEBUG=fileutil:* is active, and never write to stdout.
Public API
Functions
| Function | Signature | Description |
|---|---|---|
ValidateAbsolutePath |
func(path string) (string, error) |
Validates that a file path is absolute and safe; rejects empty paths, cleans with filepath.Clean, and verifies the result is absolute |
ValidatePathWithinBase |
func(base, candidate string) error |
Checks that candidate is located within the base directory tree; resolves symlinks before comparison to prevent traversal and symlink escapes |
FileExists |
func(path string) bool |
Returns true if path exists and is a regular file (not a directory) |
DirExists |
func(path string) bool |
Returns true if path exists and is a directory |
IsDirEmpty |
func(path string) bool |
Returns true if the directory at path contains no entries; also returns true if the directory cannot be read |
CopyFile |
func(src, dst string) error |
Copies the file at src to dst using buffered I/O; calls Sync on the destination before closing; removes the partial destination file on write error |
EnsureParentDir |
func(path string, perm os.FileMode) error |
Ensures the parent directory of path exists, creating it recursively with the given permissions; returns an error for empty paths |
ExtractFileFromTar |
func(data []byte, path string) ([]byte, error) |
Extracts a single file by path from a tar archive; rejects unsafe entry names (absolute or ..-containing paths) using filepath.IsLocal |
Behavioral contracts:
ValidateAbsolutePathMUST reject empty paths and MUST return an error for any path that is not absolute afterfilepath.Clean.ValidatePathWithinBaseMUST resolve symlinks viafilepath.EvalSymlinks(falling back tofilepath.Absfor non-existent paths) before comparing, so neither..components nor symlinks pointing outsidebasecan escape the boundary.IsDirEmptyMUST returntruewhen the directory cannot be read (treats unreadable as empty).CopyFileMUST callSyncon the destination before closing, and MUST remove the partial destination file if a write error occurs mid-copy.ExtractFileFromTarMUST reject the caller-suppliedpathand each tar entry name that does not satisfyfilepath.IsLocal; returns an error when the requested file is not present in the archive.
Usage Examples
import "github.com/github/gh-aw/pkg/fileutil"
// Validate and clean a user-supplied path
cleanPath, err := fileutil.ValidateAbsolutePath(userInput)
if err != nil {
return fmt.Errorf("invalid path: %w", err)
}
// Ensure output path stays within workspace
if err := fileutil.ValidatePathWithinBase("/workspace", outputPath); err != nil {
return fmt.Errorf("output path escapes workspace: %w", err)
}
// Copy a file (partial destination is removed on error)
if err := fileutil.CopyFile("source.txt", "destination.txt"); err != nil {
return fmt.Errorf("copy failed: %w", err)
}
// Extract a file from a tar archive in memory
content, err := fileutil.ExtractFileFromTar(tarBytes, "dist/binary")
if err != nil {
return fmt.Errorf("extraction failed: %w", err)
}
Thread Safety
All exported functions are safe for concurrent use. None of them share mutable package-level state; the package-level logger variables (fileutilLog, tarLog) are read-only after package initialization.
Dependencies
Internal:
github.com/github/gh-aw/pkg/logger— debug logging
Design Decisions
ValidatePathWithinBaseresolves symlinks before comparison, providing defence-in-depth against symlink attacks in addition to the..checking thatValidateAbsolutePathprovides.ExtractFileFromTaruses Go's standardarchive/tarinstead of an externaltarprocess, ensuring cross-platform compatibility in environments wheretarmay not be onPATH.CopyFileremoves the partial destination file on write error to prevent leaving corrupt files behind.- All debug output uses the
loggerpackage and is only emitted whenDEBUG=fileutil:*.
This specification is automatically maintained by the spec-extractor workflow.
Documentation
¶
Overview ¶
Package fileutil provides utility functions for working with file paths and file operations.
Index ¶
- func CopyFile(src, dst string) error
- func DirExists(path string) bool
- func EnsureParentDir(path string, perm os.FileMode) error
- func ExtractFileFromTar(data []byte, path string) ([]byte, error)
- func FileExists(path string) bool
- func IsDirEmpty(path string) bool
- func ResolveExecutablePath(name string) (string, error)
- func ValidateAbsolutePath(path string) (string, error)
- func ValidateExecutablePath(path string) (string, error)
- func ValidatePathWithinBase(base, candidate string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnsureParentDir ¶ added in v0.79.3
EnsureParentDir ensures the parent directory for path exists, creating it recursively when needed.
func ExtractFileFromTar ¶ added in v0.49.0
ExtractFileFromTar extracts a single file from a tar archive. Uses Go's standard archive/tar for cross-platform compatibility instead of spawning an external tar process which may not be available on all platforms.
path must be a local, relative path (no absolute paths or ".." components). filepath.IsLocal is used to enforce this for both the search target and each tar entry name, guarding against path-traversal payloads embedded in archives.
func FileExists ¶ added in v0.47.0
FileExists checks if a file exists and is not a directory.
func IsDirEmpty ¶ added in v0.47.0
IsDirEmpty checks if a directory is empty.
func ResolveExecutablePath ¶ added in v0.83.2
ResolveExecutablePath resolves an executable from PATH and validates the resulting path.
func ValidateAbsolutePath ¶
ValidateAbsolutePath validates that a file path is absolute and safe to use. It performs the following security checks:
- Cleans the path using filepath.Clean to normalize . and .. components
- Verifies the path is absolute to prevent relative path traversal attacks
Returns the cleaned absolute path if validation succeeds, or an error if:
- The path is empty
- The path is relative (not absolute)
This function should be used before any file operations (read, write, stat, etc.) to ensure defense-in-depth security against path traversal vulnerabilities.
Example:
cleanPath, err := fileutil.ValidateAbsolutePath(userInputPath)
if err != nil {
return fmt.Errorf("invalid path: %w", err)
}
content, err := os.ReadFile(cleanPath)
func ValidateExecutablePath ¶ added in v0.83.2
ValidateExecutablePath validates that an executable path is absolute, resolves symlinks when possible, points to a file, and is executable on non-Windows platforms.
func ValidatePathWithinBase ¶ added in v0.71.5
ValidatePathWithinBase checks that candidate is located within the base directory tree. Both paths are resolved via filepath.EvalSymlinks (with filepath.Abs as fallback when a path does not yet exist) before comparison, so neither ".." components nor symlinks pointing outside base can be used to escape.
For candidate paths that do not yet exist on disk, the longest existing ancestor is resolved through EvalSymlinks before the non-existing suffix is re-appended. This prevents an in-base symlinked directory from being used to write outside the base even when the final file does not exist yet.
Returns an error when:
- Either path cannot be resolved to an absolute form.
- The resolved candidate path starts outside the resolved base directory.
Types ¶
This section is empty.
Source Files