bookclerk_plugin_sdk.path_guard
Path containment helpers for authoring tools and sparse workerd launchers.
| Name | Kind | Summary |
|---|---|---|
resolve_under |
function | Join parts under root and require the result stay inside root. |
ensure_dir_under |
function | Create root / rel after resolve + startswith (check before mkdir). |
write_file_under |
function | Write contents to root / name after resolve + startswith. |
copy_file_under |
function | Copy src to root / name after resolve + startswith on dest. |
refuse_symlink_existing_components |
function | Like refuse_symlink_path, but any trailing missing components are OK. |
refuse_symlink_path |
function | Require path under trusted_root with no symlink suffix components. |
cli_user_path |
function | Accept a CLI path argument (any user-chosen location; no cwd jail). |
copy_tree_no_symlinks |
function | Copy a directory tree, refusing any symlink entries. |
def resolve_under(root: Path | str, *parts: str | Path) -> Path
Join parts under root and require the result stay inside root.
Lexical abspath / normpath + relpath / startswith barrier
(no realpath before the check — that is itself a path sink under local
threat modeling). Callers that write under a plugin tree must also use
refuse_symlink_path so a .bookclerk -> /outside link cannot
redirect generated output.
Args
root: Trusted directory (user-selected plugin/output root, or cache).*parts: Relative segments to join, or one absolute path to validate underroot.
Returns
Absolute normalized path under root.
Raises
ValueError: When a part contains../ NUL or the result escapesroot.
def ensure_dir_under(root: Path | str, rel: str | Path) -> Path
Create root / rel after resolve + startswith (check before mkdir).
def write_file_under(root: Path | str, name: str, contents: str | bytes) -> Path
Write contents to root / name after resolve + startswith.
Assumes root already exists (session/cache dirs are created first).
Refuses a symlink at the destination, including a leaf link out of root.
Filenames may contain .. (edition..2.js); . and .. components
are rejected.
def copy_file_under(root: Path | str, name: str, src: Path | str) -> Path
Copy src to root / name after resolve + startswith on dest.
def refuse_symlink_existing_components(trusted_root: Path | str, path: Path | str) -> Path
Like refuse_symlink_path, but any trailing missing components are OK.
Use before os.makedirs(..., exist_ok=True) so a symlink intermediate
cannot redirect recursive directory creation outside trusted_root.
def refuse_symlink_path(trusted_root: Path | str, path: Path | str) -> Path
Require path under trusted_root with no symlink suffix components.
Resolves the trusted root identity once (a symlinked operator/plugin root is allowed). Only components below that identity are inspected for symlinks. Missing final components are allowed (for create); intermediate missing parents raise.
Args
trusted_root: Original operator/plugin root (not a promoted child).path: Candidate path previously produced byresolve_under.
Returns
The validated path as a Path.
Raises
ValueError: When a suffix component is a symlink or escapestrusted_root.FileNotFoundError: When an intermediate parent is missing.
def cli_user_path(raw: str | Path) -> Path
Accept a CLI path argument (any user-chosen location; no cwd jail).
Authoring CLIs take absolute or relative paths without forcing containment
under Path.cwd(). Reject NUL only; callers apply
resolve_under for manifest-derived children beneath the opened
plugin/output root.
Args
raw: Operator-selected path (absolute, relative, or~-prefixed).
Returns
Normalized absolute path.
Raises
ValueError: When the path contains an interior NUL.
def copy_tree_no_symlinks(src: Path, dst: Path) -> None
Copy a directory tree, refusing any symlink entries.
Unlike shutil.copytree (which follows links by default), this never
embeds outside bytes through modules/leak -> /outside.
Args
src: Source directory (must not itself be a symlink).dst: Destination directory to create.
Raises
ValueError: When a symlink or unsupported file type is encountered.OSError: On filesystem failures.
Generated from packages/plugin-sdk-python at main · View as Markdown