Module safe_path 

Path-safety helpers for confining ceremony-derived names and paths.

Ceremony files are authored by third parties and may be downloaded and run by an operator who never inspected them. Any string from a ceremony that ends up on the filesystem — an artifact id used as an output filename, a material’s path: value — is therefore untrusted and must not be allowed to escape the directory it is meant to live in.

Two primitives cover the cases that occur in practice:

• validate_component / safe_join for a value that must be a single path component (a bare file or directory name). This is the right tool for identifiers that become filenames. Because these names are created by the runtime and a ceremony is portable across operating systems, the rules are the intersection of what every platform accepts (see validate_component for the full list).
• confine for a value that may legitimately be a multi-segment relative path but must stay within a known root (e.g. keys/root.pem under the ceremony directory). This is used for reading files that already exist on the host, so it only enforces containment, not name portability.

Both are purely lexical: they never touch the filesystem, so they are safe to call on paths that do not exist yet and cannot be confused by the current working directory. Lexical checks do not defend against symlinks placed at the destination — call sites that create files should additionally open with create_new (no-follow, no-clobber) so a pre-planted symlink cannot redirect the write.

Enums

PathSafetyError

Why a ceremony-supplied name or path was rejected as unsafe.

Functions

confine

Resolve an untrusted relative candidate against root, guaranteeing the result stays within root.

is_safe_component

Returns true if name is a safe single path component.

safe_join

Join a single untrusted name onto base, guaranteeing the result is a direct child of base.

validate_component

Validate that name is a safe, portable single path component: a non-empty plain file or directory name that every supported platform accepts and that cannot leave its directory.