Documentation
¶
Overview ¶
Package privatefiles owns private file creation, access checks, and bounded record I/O.
Index ¶
- Constants
- func CheckEntry(root *os.Root, name string, directory bool, want EntryReceipt) error
- func CheckRecord(root *os.Root, name string, want RecordReceipt) error
- func CreateChild(root *os.Root, name string) error
- func CreateDirectory(directory string) error
- func CreateFile(root *os.Root, name string) (*os.File, error)
- func InspectRetainedPublications(ctx context.Context, files map[string]RetainedFile, read RetainedRecordReader, ...) ([]string, error)
- func ReadFile(root *os.Root, name string, limit int64) ([]byte, error)
- func ReadServiceConfiguration(root *os.Root, name string, limit int64) ([]byte, error)
- func ValidateACL(_ *os.Root, _ string, _ fs.FileInfo, _ string) error
- func ValidateAncestors(path string) error
- func ValidateMetadata(info fs.FileInfo, field string) error
- type Directory
- func (d *Directory) CheckNoPendingPublications(ctx context.Context) error
- func (d *Directory) Child(name string) (*Directory, error)
- func (d *Directory) CompareAndPublishFileContext(ctx context.Context, name string, previous, data []byte, prefix string) error
- func (d *Directory) CompareAndRemoveFileContext(ctx context.Context, name string, previous []byte) (bool, error)
- func (d *Directory) CompletePublication(ctx context.Context, name string, previous, data []byte, prefix string, ...) error
- func (d *Directory) CopyFile(ctx context.Context, name string, output io.Writer, limit int64) (copied int64, resultErr error)
- func (d *Directory) CreateChild(name string) (*Directory, error)
- func (d *Directory) ExistingChild(name string) (*Directory, error)
- func (d *Directory) InspectPublication(ctx context.Context, name string, previous, data []byte, prefix string) ([]string, error)
- func (d *Directory) Open() (*os.Root, error)
- func (d *Directory) PublishFileContext(ctx context.Context, name string, data []byte, prefix string) error
- func (d *Directory) ReadDir() ([]fs.DirEntry, error)
- func (d *Directory) ReadFile(name string, limit int64) ([]byte, error)
- func (d *Directory) RecoverPublications(ctx context.Context) error
- func (d *Directory) WriteFile(name string, data []byte, prefix string) error
- func (d *Directory) WriteFileContext(ctx context.Context, name string, data []byte, prefix string) error
- func (d *Directory) WriteFileContextWithSync(ctx context.Context, name string, data []byte, prefix string, ...) error
- func (d *Directory) WriteFileIfAbsentContext(ctx context.Context, name string, data []byte, prefix string) error
- type EntryReceipt
- type RecordReceipt
- type RetainedFile
- type RetainedPublication
- type RetainedRecordReader
Constants ¶
const ( // DirectoryMode excludes group and other access on POSIX. DirectoryMode fs.FileMode = 0o700 // FileMode excludes group and other access on POSIX. FileMode fs.FileMode = 0o600 )
const (
// PublicationDirectoryName identifies the reserved metadata child for private record publication.
PublicationDirectoryName = ".record-publications"
)
const RetainedPublicationMaxBytes = publicationJournalMaxBytes
RetainedPublicationMaxBytes bounds one captured publication journal.
Variables ¶
This section is empty.
Functions ¶
func CheckEntry ¶
CheckEntry rejects a different native identity or access policy.
func CheckRecord ¶
func CheckRecord(root *os.Root, name string, want RecordReceipt) error
CheckRecord rejects changed ownership, metadata, identity, or contents.
func CreateChild ¶
CreateChild exclusively creates one private child directory.
func CreateDirectory ¶
CreateDirectory creates private children through verified directory handles. Existing directories retain their permissions. Every parent must pass the ancestor policy.
func CreateFile ¶
CreateFile exclusively creates one private regular file.
func InspectRetainedPublications ¶
func InspectRetainedPublications(ctx context.Context, files map[string]RetainedFile, read RetainedRecordReader, accepts func(parent, destination, prefix string) bool) ([]string, error)
InspectRetainedPublications selects native journals and matching staging files to keep inactive. The caller supplies a complete verified inventory and a destination owner check. It must preserve every selected file in inactive recovery evidence. Destination records remain active and require separate owner validation. This check never promotes staging files. This result does not authorize native cleanup or admission.
func ReadFile ¶
ReadFile reads one bounded private regular file under an open root. The caller owns directory access policy and closes the root.
func ReadServiceConfiguration ¶
ReadServiceConfiguration reads a bounded primary input with trusted ownership and protected writes. The caller must explicitly select this policy and validate the selected path's ancestors. This exception does not change private state or dotenv readers and never changes permissions.
func ValidateACL ¶
ValidateACL checks native grants on the expected file without changing its ACL.
func ValidateAncestors ¶
ValidateAncestors checks existing parents and selected symlink routes without creating paths. Linux and macOS require root or effective-user ownership and protected directory entries. Trusted sticky directories permit shared creation. macOS also checks native ACL grants.
Types ¶
type Directory ¶
type Directory struct {
// contains filtered or unexported fields
}
Directory binds a private directory to its original filesystem identity. Each operation reopens and validates it. No open handle survives the operation.
func ExistingDirectory ¶
ExistingDirectory binds an existing private directory without creating any paths.
func NewDirectory ¶
NewDirectory validates or creates one private directory without changing existing permissions. Linux, macOS, and Windows also validate ancestor ownership and access.
func NewExclusiveDirectory ¶
NewExclusiveDirectory creates one private directory beneath an existing trusted parent. An existing target causes an existence error. Failures preserve uncertain filesystem entries.
func (*Directory) CheckNoPendingPublications ¶
CheckNoPendingPublications inspects existing receipts without deleting files or creating metadata. Migration must recover pending publications before recording a source inventory.
func (*Directory) Child ¶
Child validates or privately creates one child under the bound directory handle.
func (*Directory) CompareAndPublishFileContext ¶
func (d *Directory) CompareAndPublishFileContext(ctx context.Context, name string, previous, data []byte, prefix string) error
CompareAndPublishFileContext requires the previously read bytes to remain current. A nil previous value requires an absent destination. An empty non-nil value requires an empty file.
func (*Directory) CompareAndRemoveFileContext ¶
func (d *Directory) CompareAndRemoveFileContext(ctx context.Context, name string, previous []byte) (bool, error)
CompareAndRemoveFileContext removes a private record whose bytes match previous. It shares the PublishFileContext writer lock and verifies identity and access before removal. A missing file permits an idempotent retry. A nil previous value is invalid. The result reports visible removal even when directory synchronization fails.
func (*Directory) CompletePublication ¶
func (d *Directory) CompletePublication(ctx context.Context, name string, previous, data []byte, prefix string, check func(context.Context) error) error
CompletePublication finishes only an exact record after a host-owned completion check. It refuses foreign journals, changed staging identities, and incomplete staging evidence.
func (*Directory) CopyFile ¶
func (d *Directory) CopyFile(ctx context.Context, name string, output io.Writer, limit int64) (copied int64, resultErr error)
CopyFile streams one private regular file into a caller-owned writer. A failure can follow partial output. The caller must discard that output. The operation verifies native access, file identity, size, and directory identity.
func (*Directory) CreateChild ¶
CreateChild exclusively creates one private child directory.
func (*Directory) ExistingChild ¶
ExistingChild binds an existing child without creating any paths.
func (*Directory) InspectPublication ¶
func (d *Directory) InspectPublication(ctx context.Context, name string, previous, data []byte, prefix string) ([]string, error)
InspectPublication checks only one exact publication without changing records. Returned stage names permit a host to inspect its original decision before completion.
func (*Directory) Open ¶
Open verifies directory identity, ownership, and private access before returning a confined root. The caller must close the root.
func (*Directory) PublishFileContext ¶
func (d *Directory) PublishFileContext(ctx context.Context, name string, data []byte, prefix string) error
PublishFileContext publishes a private record with durable staging ownership. Recovery never treats an unrecorded temporary filename as proof of ownership. The method excludes concurrent publishers and recovers their complete abandoned receipts.
func (*Directory) ReadDir ¶
ReadDir lists the bound directory without following another directory at its original path.
func (*Directory) ReadFile ¶
ReadFile reads a bounded private regular file from the bound directory. Missing files return the filesystem absence error.
func (*Directory) RecoverPublications ¶
RecoverPublications removes unchanged staging records under an exclusive writer lock. It preserves unknown files and incomplete receipts. A missing metadata directory requires no recovery.
func (*Directory) WriteFile ¶
WriteFile publishes complete private bytes through an exclusively created temporary file. Existing destinations must remain private regular files. The caller serializes writers.
func (*Directory) WriteFileContext ¶
func (d *Directory) WriteFileContext(ctx context.Context, name string, data []byte, prefix string) error
WriteFileContext checks cancellation before access and immediately before destination publication. The caller serializes writers. Cancellation before publication preserves the previous destination. PublicationError identifies a visible record with unconfirmed durability.
func (*Directory) WriteFileContextWithSync ¶
func (d *Directory) WriteFileContextWithSync(ctx context.Context, name string, data []byte, prefix string, syncDirectory func(*os.Root) error) error
WriteFileContextWithSync uses the supplied directory synchronizer after publication. A nil synchronizer selects the native filesystem operation. The caller serializes writers.
func (*Directory) WriteFileIfAbsentContext ¶
func (d *Directory) WriteFileIfAbsentContext(ctx context.Context, name string, data []byte, prefix string) error
WriteFileIfAbsentContext publishes private bytes only when no destination exists. The write preserves a competing destination, including one created during publication.
type EntryReceipt ¶
type EntryReceipt = publicationEntry
EntryReceipt binds a directory or regular file to its native identity and access policy. Directory receipts do not bind child contents or modification times.
func CaptureEntry ¶
CaptureEntry records one private direct child under an open root.
type RecordReceipt ¶
type RecordReceipt = publicationRecord
RecordReceipt also binds regular-file contents, size, mode, and modification time.
func CaptureRecord ¶
CaptureRecord records one bounded private regular file under an open root.
type RetainedFile ¶
RetainedFile identifies bytes in a verified backup. Names are slash-separated relative paths.
type RetainedPublication ¶
type RetainedPublication struct {
Destination string
Prefix string
Stage string
HasRecord bool
Size int64
SHA256 string
}
RetainedPublication describes staging evidence in a captured publication journal. Native identities remain historical. This result cannot authorize native cleanup.
func InspectRetainedPublication ¶
func InspectRetainedPublication(name string, raw []byte) (RetainedPublication, error)
InspectRetainedPublication validates a captured journal without accessing files. The caller must verify the backup, destination ownership, and any retained staging bytes. It must preserve the evidence and never promote staging bytes from this result.
Source Files
¶
- acl_other.go
- ancestors_linux.go
- ancestors_posix.go
- copy.go
- creation_posix.go
- directory.go
- directory_exclusive.go
- metadata_posix.go
- open_posix.go
- receipt.go
- record_access.go
- record_access_limits.go
- record_access_linux.go
- record_access_posix.go
- record_completion.go
- record_completion_inspection.go
- record_journal.go
- record_publication.go
- record_receipt.go
- record_recovery.go
- record_removal.go
- record_restore.go
- record_retained.go
- record_writer.go
- records.go
- service_acl_linux.go
- service_configuration.go
- service_metadata_posix.go