PtcRunner.Kernel.ConfinedFile (PtcRunner v0.14.0)

Copy Markdown View Source

Reads one bounded UTF-8 file from a trusted root.

This is PtcRunner's own loading primitive for host configuration, manifests, PTC-Lisp components, contracts, and selected input. It is not a capability and is never reachable from a generated program: nothing here is exposed through Lisp discovery metadata or a provider callback.

Confinement is enforced before any content is read. A relative path is rejected outright when it is absolute, empty, oversized, contains a NUL byte, or carries an empty, ., or .. segment. Symbolic links are then resolved segment by segment; a link is followed only while its target stays inside the root, and the fully resolved path is re-checked against the root before it is opened. Traversal therefore fails as an explicit error rather than resolving to a path outside the grant.

The bounded read rejects a non-regular file, a file larger than the caller's ceiling, and invalid UTF-8. The target and every resolved parent directory are identity-checked around the open and read, so an ordinary path or parent replacement fails instead of redirecting trusted loading. This is a trusted host loader, not a hostile same-user filesystem sandbox: the configured hierarchy must not be concurrently swapped away and restored between those checks.

Trusted loading previously borrowed this behavior from the removed public file capability, freezing the entire root to return one manifest. This primitive now owns the trusted-loading contract independently; generated programs use explicitly installed MCP filesystem tools instead.

Summary

Types

error()

Functions

read(root, relative_path, max_bytes)

Reads relative_path beneath root, returning at most max_bytes of UTF-8 content.

resolve_absolute(path)

Resolves an absolute path, following only symbolic links that stay within the filesystem root, and returns the canonical absolute path.

Types

error()

@type error() ::
  :invalid_path
  | :symlink_escape
  | :symlink_depth_exceeded
  | :not_found
  | :not_regular
  | :unreadable
  | :too_large
  | :invalid_utf8
  | :changed_during_read

Functions

read(root, relative_path, max_bytes)

@spec read(binary(), binary(), pos_integer()) :: {:ok, binary()} | {:error, error()}

Reads relative_path beneath root, returning at most max_bytes of UTF-8 content.

root must be an existing directory. The path is confined to that root as described in the module documentation.

resolve_absolute(path)

@spec resolve_absolute(binary()) :: {:ok, binary()} | {:error, error()}

Resolves an absolute path, following only symbolic links that stay within the filesystem root, and returns the canonical absolute path.