Module private_fs 

Private filesystem helpers for sensitive application state.

Policy (spec §5.4): directories 0700, files and temp files 0600, symlink-safe opens, and atomic create-with-mode → write → rename so no interval exists where a fresh file is broader than policy. Pre-existing broader modes are repaired (chmod) on the next write. On non-Unix platforms the helpers fall back to default platform semantics (symlink refusal is still enforced via symlink_metadata).

Structs

ConfinedDir

A held O_DIRECTORY handle beneath a trusted root. Every operation is RELATIVE to this handle (openat/mkdirat/unlinkat), each component is opened O_NOFOLLOW, and no path is ever re-resolved after a check — the check IS the open, so ancestor-symlink plants and concurrent component swaps fail closed (ELOOP/ENOTDIR) instead of escaping.

ConfinedEntry

One entry discovered from a held directory handle. Discovery never re-resolves the directory by path; callers still perform the authoritative open relative to the same handle, so entry replacement races fail closed.

Enums

PrivateFsError

Typed failure for private filesystem operations.

Constants

DIR_MODE

Policy mode for private directories (Unix).

FILE_MODE

Policy mode for private files and temp files (Unix).

Functions

ensure_private_dir

Create dir (and missing parents) with mode 0700, and repair the leaf directory to 0700 if a pre-existing one is broader than policy.

open_private_append

Open path for appending, creating it with mode 0600 (O_NOFOLLOW on Unix). A symlink at the target yields PrivateFsError::SymlinkRefused. A pre-existing broader-mode file is repaired to 0600 via fchmod on the already-open handle (no path re-resolution).

validated_relative_components

Split and validate a RELATIVE multi-component path (a/b/c.jsonl). Rejects absolute paths, ./.., empty components, and backslashes.

write_atomic_private

Atomically replace path with data: the temp file is created in the same directory with create_new + mode 0600 (never create-then-chmod, so no interval is broader than policy), written, then renamed over the target. A symlink at the target or temp path yields a typed refusal.