Struct Capabilities 

pub struct Capabilities { /* private fields */ }

The capabilities a spec grants a job.

v1 has exactly one kind, filesystem reads under named roots. An empty set grants nothing — deny-by-default is the whole posture, so “no capabilities declared” must never read as “unrestricted”.

Implementations

impl Capabilities

pub fn new(read_roots: Vec<PathBuf>) -> Self

Grant read access beneath each of read_roots, and nothing else.

pub fn with_fetch(self, fetch_prefixes: Vec<String>) -> Self

Also grant fetching any URL beginning with one of fetch_prefixes.

pub fn allows_fetch(&self, url: &str) -> bool

Whether url may be fetched.

Prefix matching on the URL as written, deliberately: it is the rule a spec author can predict from reading their own capability line. No normalisation, no host-only matching — Fetch "https://x.org/docs/" grants that subtree and not https://x.org/other, and not http:// either, since the scheme is part of the prefix.

The one thing checked beyond the prefix is that the URL cannot climb out with .., which would otherwise let a granted prefix reach anywhere on the host.

pub fn fetch_prefixes(&self) -> &[String]

The granted fetch prefixes, as configured.

pub fn allows_read(&self, path: &Path) -> bool

Whether path may be read.

Both sides are canonicalized before comparison, and that is the entire substance of this function. The tempting implementation — path.starts_with(root) on the raw strings — admits two escapes:

• Traversal. /granted/inner/../../secret has /granted/inner as a string prefix while naming a file outside it.
• Symlinks. A path genuinely under the granted root can name a file anywhere on the system.

canonicalize resolves .. and follows symlinks, so the comparison is between the real locations rather than the spellings. Comparing with Path::starts_with rather than string prefixes additionally means /data-secret is not treated as nested inside /data.

A path that cannot be canonicalized — because it does not exist — is denied. That is deliberate on two counts: a nonexistent path cannot be proven inside the grant, and refusing it here means the decision cannot be made against a file that only appears afterwards.

Note the residual limitation: this resolves the path once, and the caller opens it separately. A sufficiently determined attacker who can swap a symlink between those two steps still has a window. Closing it properly needs the caller to pass an already-open descriptor; see the transport discussion in the cuttlefishd crate docs.

pub fn read_denial(&self, path: &Path) -> Option<ReadDenial>

Why a read was refused, when it was.

Self::allows_read answers yes-or-no, which is the right shape for the decision and the wrong shape for the message. Two very different situations reach it as false: a path the spec never granted, and a granted path that simply is not there. Reporting both as “read not permitted” sends somebody to re-read their capabilities line when what they actually have is a typo in a filename or a manifest listing a file that was moved.

Saying “does not exist” is only safe where the job could have found out anyway. So it is said only when the nearest existing ancestor of the path is itself inside a granted root — a directory the job may already open and read. For anything else the answer stays the undifferentiated refusal, because distinguishing “absent” from “forbidden” outside the grant is exactly the probe a capability list exists to prevent.

pub fn read_roots(&self) -> &[PathBuf]

The granted read roots, as configured.

Trait Implementations

impl Clone for Capabilities

fn clone(&self) -> Capabilities

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Capabilities

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Capabilities

fn default() -> Capabilities

Returns the “default value” for a type.