Documentation
¶
Overview ¶
Package hostfs opens trusted worker directories without following aliases.
Index ¶
- func MountIdentity(fd int) (unix.Statx_t, error)
- func OpenDirectory(directory string, owner uint32) (*os.File, error)
- func OpenPrivateState(name string, owner uint32, create bool) (*os.File, error)
- func PublishPin(ctx context.Context, pin Pin, owner uint32, data []byte, ...) (err error)
- func ReadOwned(ctx context.Context, name string, owner, mode uint32, maximum int64) ([]byte, error)
- func ReadPin(ctx context.Context, pin Pin, owner uint32) ([]byte, error)
- func ReadRegular(directory, name string, maximum int64) ([]byte, error)
- func StatPrivateState(name string, owner uint32) (unix.Stat_t, error)
- func VerifyPin(ctx context.Context, pin Pin, owner uint32) error
- type Pin
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MountIdentity ¶
MountIdentity returns inode and unique mount identity, failing on unsupported kernels.
func OpenDirectory ¶
OpenDirectory walks a canonical absolute path through no-follow descriptors. Ancestors must belong to root or owner and reject other writers, except for root-owned sticky directories. The final directory must belong to owner and reject group/world writes. Callers apply their own read/execute/privacy policy. The trusted owner must prevent changes during use; this is not a write lock.
func OpenPrivateState ¶
OpenPrivateState opens a mode-0600, single-link regular file in a private mode-0700 directory. Set create to permit creation without truncation. Paths must be canonical; the trusted owner must prevent replacement during use. The caller owns the descriptor and any required lifetime lock or sync.
func PublishPin ¶
func PublishPin(ctx context.Context, pin Pin, owner uint32, data []byte, beforePublish func() error) (err error)
PublishPin durably installs a mode-0400 snapshot in a private directory without replacing an existing name. An identical verified file is an idempotent retry. beforePublish must recheck current authority; it also runs for retries. An error after rename may leave the complete file installed. Retry with the same pin to resolve that ambiguity. A process crash may leave a private temporary file, never a partial destination. The trusted owner must protect paths during use. Filesystems without exclusive rename support fail without a fallback.
func ReadOwned ¶
ReadOwned reads at most one MiB from a single-link, owner-controlled file with an exact mode. Authority comes from the protected host path, not its content.
func ReadPin ¶
ReadPin returns an independently verified snapshot of at most 64 MiB. Callers must bound concurrent snapshots. Use a responsive local filesystem; context cancellation cannot forcibly interrupt a stalled kernel file call.
func ReadRegular ¶
ReadRegular reads a bounded regular file through no-follow descriptors. Every component is opened relative to its verified parent, so rename and symlink swaps cannot redirect traversal outside the host-selected export directory. Call this after the workload has stopped; a live writer cannot produce an immutable snapshot. Archives are not expanded and hard links are rejected.
func StatPrivateState ¶
StatPrivateState checks metadata without opening the file. This preserves process-owned SQLite locks, which closing another database descriptor can drop.
Types ¶
type Pin ¶
type Pin struct {
Path string `json:"path"`
SHA256 string `json:"sha256"`
Bytes int64 `json:"bytes"`
Mode uint32 `json:"mode"`
}
Pin identifies an owner-controlled regular file. The digest and mode come from approved host policy. Bytes is an exact length, or a bounded size hint when the independently trusted digest authenticates the complete content.
Source Files