Self-hosted AI workspace.
Python
"""The filesystem confinement boundary. One implementation, every call site.
"Is this path inside that root" is asked in twenty places in this tree, and
twenty times it is answered by a locally written ``realpath`` +
``os.path.commonpath`` pair. Each one is defensible on its own. Together they
are the problem: the boundary has no single definition, so a site that gets a
detail wrong is wrong *alone*, and a site added tomorrow starts from whichever
neighbour its author happened to copy.
The details that differ between those copies, and what this module settles:
**Both sides get canonicalized.** Comparing a ``realpath``-ed candidate against
a root that was only ``abspath``-ed is the bug class that has already cost this
project real time: on macOS ``/tmp`` is a symlink to ``/private/tmp``, so the
two sides disagree about a path neither of them is wrong about. It reads as an
escape and refuses a legitimate access. Canonicalizing one side is worse than
canonicalizing neither.
**``commonpath``, never ``startswith``.** ``/a/bc`` begins with ``/a/b`` and is
not inside it.
**Case folding is the filesystem's business, not the comparison's.**
``os.path.normcase`` lowercases on Windows and is the identity everywhere else
— including macOS, whose default filesystem is case-insensitive while its
``realpath`` preserves case. So normcase alone does not make the comparison
agree with the filesystem on macOS, and :func:`is_inside` does not pretend
otherwise: it answers about the canonical path, which is the question a
confinement check should be asking. Where a caller needs to match the
filesystem's own folding it must compare real paths of real files, not strings.
**A relative candidate joins the root, never the process cwd.** ``abspath`` of a
relative path silently uses ``os.getcwd()``, which is whatever the server
happens to be running in. A confinement helper that does that is resolving
against the wrong base before it even starts comparing.
**NUL and newline are rejected, not caught.** Several of the copies wrap the
whole comparison in ``except Exception: return False``, which turns a malformed
path into "outside" — the safe answer, reached by accident. Here it is a
``ValueError`` with a reason.
**``commonpath`` raising means outside.** It raises across Windows drive letters
and for mixed absolute/relative inputs. Both mean the candidate is not under the
root, so the refusal is deliberate rather than incidental.
What this module does *not* do: decide whether a path is sensitive (``.ssh``,
``id_rsa``, …). That is a separate deny list applied inside an allowed root, and
it lives with the callers that own it — ``src/tool_execution`` for the agent
tools. Confinement answers "inside the root"; it does not answer "allowed".
Relationship to :mod:`src.containment`: that module is the boundary for *where a
process runs*; this one is the boundary for *which paths a path check accepts*.
A contained process is restricted by a mount namespace, which this module cannot
express and does not try to; an in-process read of a model-supplied path is
restricted by this module, which a namespace does not see.
"""
from __future__ import annotations
import os
__all__ = [
"PathEscape",
"canonical_root",
"confine",
"is_inside",
]
class PathEscape(ValueError):
"""A candidate path does not resolve inside the root it was checked against.
A subclass of :class:`ValueError` so the call sites this replaces — which
raise ``ValueError`` and are caught as such by their callers and their
tests — keep behaving the way they did.
"""
def __init__(self, root: str, candidate: str, reason: str = "") -> None:
self.root = str(root)
self.candidate = str(candidate)
self.reason = str(reason or "outside the allowed root")
super().__init__(
f"path {self.candidate!r} is {self.reason} ({self.root})"
)
def _reject_unusable(value: str, *, label: str) -> str:
"""Normalize a path argument to ``str``, refusing the unusable shapes.
``\\x00`` is refused here because the OS layer raises on it much later and
from somewhere unhelpful, and because a broad ``except Exception`` around
the comparison would otherwise record it as an ordinary escape. Newlines
are refused for the same reason the workspace-mount parser refuses them:
a path carrying one has been built by splitting something that was not a
path list.
"""
if value is None:
raise ValueError(f"{label} is required")
if isinstance(value, os.PathLike):
value = os.fspath(value)
if not isinstance(value, str):
raise ValueError(f"{label} must be a path, got {type(value).__name__}")
text = value.strip()
if not text:
raise ValueError(f"{label} is required")
if "\x00" in text:
raise ValueError(f"{label} must not contain NUL")
if "\n" in text or "\r" in text:
raise ValueError(f"{label} must not contain a newline")
return text
def canonical_root(root) -> str:
"""The canonical form of a confinement root.
Exposed because a caller that holds a root across several checks should
canonicalize it once, and because a caller comparing two paths itself needs
the same canonical form this module compares against — a realpath-ed value
tested against a raw one is the asymmetry this module exists to remove.
"""
text = _reject_unusable(root, label="root")
return os.path.realpath(os.path.expanduser(text))
def _canonical_candidate(root: str, candidate) -> str:
"""Canonicalize ``candidate``, resolving a relative path under ``root``.
``realpath`` is deliberately the non-strict kind: a final component that
does not exist yet is normalized rather than refused, because a write target
is a legitimate thing to confine. Everything that *does* exist is resolved,
so a symlink anywhere in the chain — including the final component — is
followed before the comparison rather than after the open.
"""
text = _reject_unusable(candidate, label="path")
expanded = os.path.expanduser(text)
if not os.path.isabs(expanded):
expanded = os.path.join(root, expanded)
return os.path.realpath(expanded)
def is_inside(root, candidate, *, allow_root: bool = True) -> bool:
"""True when ``candidate`` resolves inside ``root``.
The boolean form, for call sites whose contract is a predicate. A malformed
argument is ``False`` here rather than a raise, because a predicate that
raises is the reason those call sites wrapped themselves in
``except Exception`` in the first place. Use :func:`confine` where the
caller wants the resolved path and a reason for the refusal.
``allow_root=False`` excludes the root itself, for a caller whose operation
is only meaningful on something *under* the root — deleting a file, say,
where the root is the directory it must not be.
"""
try:
confine(root, candidate, allow_root=allow_root)
return True
except (ValueError, OSError):
return False
def confine(root, candidate, *, allow_root: bool = True) -> str:
"""Resolve ``candidate`` inside ``root``, or raise.
Returns the canonical absolute path, which is what the caller should then
open: resolving and then opening the *original* string re-introduces the
symlink race the resolution just closed.
:raises ValueError: either argument is unusable as a path.
:raises PathEscape: the candidate resolves outside the root.
"""
base = canonical_root(root)
resolved = _canonical_candidate(base, candidate)
if resolved == base:
if allow_root:
return resolved
raise PathEscape(base, candidate, "the root itself, not a path inside it")
# normcase folds case on Windows and is the identity elsewhere; it is
# applied to both sides or to neither, which is the whole point.
try:
common = os.path.commonpath([os.path.normcase(resolved), os.path.normcase(base)])
except ValueError:
# Different Windows drives, or mixed absolute/relative. Both mean the
# candidate is not under the root.
raise PathEscape(base, candidate) from None
if common != os.path.normcase(base):
raise PathEscape(base, candidate)
return resolved