io

Documentation

Overview

Package io provides secure input/output operations.

Index

• Variables
• func SecureCopyFile(src string, dest string, readOpts ReadOptions, writeOpts WriteOptions, ...) error
• func SecureMkdirAll(path string, opts DirOptions, log hyperlogger.Logger) error
• func SecureOpenFile(path string, opts ReadOptions, log hyperlogger.Logger) (*os.File, error)
• func SecurePath(path string, allowedRoots ...string) (string, error)
• func SecureReadDir(path string, log hyperlogger.Logger) ([]os.DirEntry, error)
• func SecureReadDirWithOptions(path string, opts ReadOptions, log hyperlogger.Logger) ([]os.DirEntry, error)
• func SecureReadFile(path string, log hyperlogger.Logger) ([]byte, error)
• func SecureReadFileWithOptions(path string, opts ReadOptions, log hyperlogger.Logger) ([]byte, error)
• func SecureReadFileWithSecureBuffer(path string, log hyperlogger.Logger) (*memory.SecureBuffer, error)
• func SecureReadFileWithSecureBufferOptions(path string, opts ReadOptions, log hyperlogger.Logger) (*memory.SecureBuffer, error)
• func SecureRemove(path string, opts RemoveOptions, log hyperlogger.Logger) error
• func SecureRemoveAll(path string, opts RemoveOptions, log hyperlogger.Logger) error
• func SecureTempDir(prefix string, opts DirOptions, log hyperlogger.Logger) (string, error)
• func SecureTempFile(prefix string, opts TempOptions, log hyperlogger.Logger) (*os.File, error)
• func SecureWriteFile(path string, data []byte, opts WriteOptions, log hyperlogger.Logger) error
• func SecureWriteFromReader(path string, reader io.Reader, opts WriteOptions, log hyperlogger.Logger) error
• type DirOptions
  • func NormalizeDirOptions(opts DirOptions) (DirOptions, error)
• type ReadOptions
  • func NormalizeReadOptions(opts ReadOptions) (ReadOptions, error)
• type RemoveOptions
  • func NormalizeRemoveOptions(opts RemoveOptions) (RemoveOptions, error)
• type TempOptions
  • func NormalizeTempOptions(opts TempOptions) (TempOptions, error)
• type WriteOptions
  • func NormalizeWriteOptions(opts WriteOptions) (WriteOptions, error)

Variables

var (
	// ErrEmptyPath indicates that a required path argument was empty.
	ErrEmptyPath = ewrap.New("path cannot be empty")
	// ErrInvalidPath indicates that a path failed validation.
	ErrInvalidPath = ewrap.New("invalid path")
	// ErrAbsolutePathNotAllowed indicates absolute paths are disallowed by policy.
	ErrAbsolutePathNotAllowed = ewrap.New("absolute paths are not allowed")
	// ErrPathEscapesRoot indicates the resolved path is outside the allowed roots.
	ErrPathEscapesRoot = ewrap.New("path escapes allowed root")
	// ErrSymlinkNotAllowed indicates a symlink was encountered when disallowed.
	ErrSymlinkNotAllowed = ewrap.New("symlinks are not allowed")
	// ErrFileTooLarge indicates a file exceeds the configured maximum size.
	ErrFileTooLarge = ewrap.New("file exceeds maximum size")
	// ErrNonRegularFile indicates a non-regular file was encountered when disallowed.
	ErrNonRegularFile = ewrap.New("non-regular files are not allowed")
	// ErrInvalidBaseDir indicates the base directory is invalid.
	ErrInvalidBaseDir = ewrap.New("invalid base directory")
	// ErrInvalidAllowedRoots indicates the allowed roots list is invalid.
	ErrInvalidAllowedRoots = ewrap.New("invalid allowed roots")
	// ErrMaxSizeInvalid indicates the configured max size is invalid.
	ErrMaxSizeInvalid = ewrap.New("max size cannot be negative")
	// ErrFileExists indicates a write target already exists when exclusive creation is requested.
	ErrFileExists = ewrap.New("file already exists")
	// ErrSyncDirUnsupported indicates directory sync is not supported on this platform or filesystem.
	ErrSyncDirUnsupported = ewrap.New("directory sync is not supported")
	// ErrNilReader indicates a nil reader was provided.
	ErrNilReader = ewrap.New("reader cannot be nil")
	// ErrNotDirectory indicates the target path is not a directory.
	ErrNotDirectory = ewrap.New("path is not a directory")
	// ErrInvalidPermissions indicates a permission mask was invalid.
	ErrInvalidPermissions = ewrap.New("invalid permissions")
	// ErrPermissionsNotAllowed indicates a path has disallowed permissions.
	ErrPermissionsNotAllowed = ewrap.New("permissions are not allowed")
	// ErrInvalidOwnership indicates ownership constraints are invalid.
	ErrInvalidOwnership = ewrap.New("invalid ownership")
	// ErrOwnershipNotAllowed indicates a path has unexpected ownership.
	ErrOwnershipNotAllowed = ewrap.New("ownership is not allowed")
	// ErrOwnershipUnsupported indicates ownership checks are not supported on this platform.
	ErrOwnershipUnsupported = ewrap.New("ownership checks are not supported")
	// ErrInvalidTempPrefix indicates a temp prefix was invalid.
	ErrInvalidTempPrefix = ewrap.New("invalid temp prefix")
	// ErrChecksumMismatch indicates a checksum verification failure.
	ErrChecksumMismatch = ewrap.New("checksum mismatch")
)

Functions

func SecureCopyFile

func SecureCopyFile(
	src string,
	dest string,
	readOpts ReadOptions,
	writeOpts WriteOptions,
	verifyChecksum bool,
	log hyperlogger.Logger,
) error

SecureCopyFile copies a file securely with configurable options.

func SecureMkdirAll

func SecureMkdirAll(path string, opts DirOptions, log hyperlogger.Logger) error

SecureMkdirAll creates a directory securely with configurable options.

func SecureOpenFile

func SecureOpenFile(path string, opts ReadOptions, log hyperlogger.Logger) (*os.File, error)

SecureOpenFile opens a file for streaming reads with configurable security options.

func SecurePath

func SecurePath(path string, allowedRoots ...string) (string, error)

SecurePath validates and sanitizes a file path using default read options. It returns a resolved path or an error if validation fails.

func SecureReadDir

func SecureReadDir(path string, log hyperlogger.Logger) ([]os.DirEntry, error)

SecureReadDir reads a directory securely with default options.

func SecureReadDirWithOptions

func SecureReadDirWithOptions(path string, opts ReadOptions, log hyperlogger.Logger) ([]os.DirEntry, error)

SecureReadDirWithOptions reads a directory securely with configurable options.

func SecureReadFile

func SecureReadFile(path string, log hyperlogger.Logger) ([]byte, error)

SecureReadFile reads a file into memory with default secure options. Use SecureReadFileWithOptions for custom behaviors.

func SecureReadFileWithOptions

func SecureReadFileWithOptions(path string, opts ReadOptions, log hyperlogger.Logger) ([]byte, error)

SecureReadFileWithOptions reads a file into memory with configurable security options.

func SecureReadFileWithSecureBuffer

func SecureReadFileWithSecureBuffer(path string, log hyperlogger.Logger) (*memory.SecureBuffer, error)

SecureReadFileWithSecureBuffer reads a file securely and returns its contents in a SecureBuffer.

func SecureReadFileWithSecureBufferOptions

func SecureReadFileWithSecureBufferOptions(path string, opts ReadOptions, log hyperlogger.Logger) (*memory.SecureBuffer, error)

SecureReadFileWithSecureBufferOptions reads a file securely with options and returns its contents in a SecureBuffer.

func SecureRemove

func SecureRemove(path string, opts RemoveOptions, log hyperlogger.Logger) error

SecureRemove removes a file or empty directory securely with configurable options.

func SecureRemoveAll

func SecureRemoveAll(path string, opts RemoveOptions, log hyperlogger.Logger) error

SecureRemoveAll removes a directory tree securely with configurable options.

func SecureTempDir

func SecureTempDir(prefix string, opts DirOptions, log hyperlogger.Logger) (string, error)

SecureTempDir creates a temp directory securely with configurable options.

func SecureTempFile

func SecureTempFile(prefix string, opts TempOptions, log hyperlogger.Logger) (*os.File, error)

SecureTempFile creates a temp file securely with configurable options.

func SecureWriteFile

func SecureWriteFile(path string, data []byte, opts WriteOptions, log hyperlogger.Logger) error

SecureWriteFile writes data to a file with configurable security options.

func SecureWriteFromReader

func SecureWriteFromReader(path string, reader io.Reader, opts WriteOptions, log hyperlogger.Logger) error

SecureWriteFromReader writes data from a reader to a file with configurable security options.

Types

type DirOptions

type DirOptions struct {
	BaseDir       string
	AllowedRoots  []string
	DirMode       os.FileMode
	AllowAbsolute bool
	AllowSymlinks bool
	EnforceMode   bool
	DisallowPerms os.FileMode
	OwnerUID      *int
	OwnerGID      *int
}

DirOptions configures secure directory behavior.

func NormalizeDirOptions

func NormalizeDirOptions(opts DirOptions) (DirOptions, error)

NormalizeDirOptions validates and normalizes directory options.

type ReadOptions

type ReadOptions struct {
	BaseDir         string
	AllowedRoots    []string
	MaxSizeBytes    int64
	AllowAbsolute   bool
	AllowSymlinks   bool
	AllowNonRegular bool
	DisallowPerms   os.FileMode
	OwnerUID        *int
	OwnerGID        *int
}

ReadOptions configures secure read behavior.

func NormalizeReadOptions

func NormalizeReadOptions(opts ReadOptions) (ReadOptions, error)

NormalizeReadOptions validates and normalizes read options.

type RemoveOptions

type RemoveOptions struct {
	BaseDir       string
	AllowedRoots  []string
	AllowAbsolute bool
	AllowSymlinks bool
	Wipe          bool
	OwnerUID      *int
	OwnerGID      *int
}

RemoveOptions configures secure remove behavior.

func NormalizeRemoveOptions

func NormalizeRemoveOptions(opts RemoveOptions) (RemoveOptions, error)

NormalizeRemoveOptions validates and normalizes remove options.

type TempOptions

type TempOptions struct {
	BaseDir         string
	AllowedRoots    []string
	FileMode        os.FileMode
	AllowAbsolute   bool
	AllowSymlinks   bool
	EnforceFileMode bool
	OwnerUID        *int
	OwnerGID        *int
}

TempOptions configures secure temp file behavior.

func NormalizeTempOptions

func NormalizeTempOptions(opts TempOptions) (TempOptions, error)

NormalizeTempOptions validates and normalizes temp file options.

type WriteOptions

type WriteOptions struct {
	BaseDir         string
	AllowedRoots    []string
	MaxSizeBytes    int64
	FileMode        os.FileMode
	CreateExclusive bool
	DisableAtomic   bool
	DisableSync     bool
	SyncDir         bool
	AllowAbsolute   bool
	AllowSymlinks   bool
	EnforceFileMode bool
	OwnerUID        *int
	OwnerGID        *int
}

WriteOptions configures secure write behavior.

func NormalizeWriteOptions

func NormalizeWriteOptions(opts WriteOptions) (WriteOptions, error)

NormalizeWriteOptions validates and normalizes write options.