Capabilities
Context-Generic Programming can declare dependencies and carry capability values, but it does not enforce a security boundary. CGP extends Rust with pluggable trait implementations, chosen per context and resolved at compile time, as a library on stable Rust whose consumer traits are ordinary Rust traits. This page separates object capabilities, effects as capabilities, and other uses of the term, then explains which properties CGP shares and which must come from another system.
In your termsβ
A context is the type a CGP method runs on, supplying data through fields and implementations through wiring. In these examples it represents an application. A context field can hold an object-capability value, while a provider's declared dependencies describe what it needs from that context.
| In capability-oriented code | In CGP |
|---|---|
| A requirement on a computation's environment | An impl-side dependency, declared with #[uses] or #[implicit] |
| An environment supplying a required value | A context value with the required field |
| A capability value passed to an operation | A context field borrowed by a provider |
| Checking that requirements are supplied | check_components! verifies declared dependencies |
| An unforgeable authority-bearing reference | Must be supplied by the field's value type; a trait bound alone does not provide it |
| Excluding ambient authority | Not enforced by CGP; ordinary Rust APIs and globals remain accessible |
The idea, brieflyβ
The word capability describes several different mechanisms. Object capabilities concern authority over resources; effect capabilities concern operations available in a scope; other uses concern privileges, ownership, or implicit dependencies. Their different guarantees determine how each relates to CGP.
The object-capability modelβ
An object capability combines a reference to a resource with authority to use it. Code obtains access through references it is given or can derive from existing authority. This makes the reference graph relevant to the principle of least authority: give each component only the access it needs. Miller's account and Capability Myths Demolished explain the model and its security properties.
A capability-safe environment excludes ambient authority that would bypass those references. An unrestricted global file-opening function would violate that rule. Passing a reference delegates authority; a wrapper can expose fewer operations or mediate access so it can later revoke it. These are properties of the supplied objects and their environment, rather than of a dependency annotation alone.
Pony gives its main actor an environment from which it obtains authority. The following fragment
uses env.root to create file access, following the
Pony tutorial:
use "files"
actor Main
new create(env: Env) =>
// `env.root` is the only source of authority; it is passed in, never global.
let auth: FileAuth = FileAuth(env.root)
let path = FilePath(auth, "/var/app/config.txt")
match OpenFile(path)
| let file: File => env.out.print(file.read_string(100))
else env.out.print("could not open")
end
Capability-based security in systemsβ
Capability systems can enforce authority below the language level. Examples include kernel-object handles in seL4, hardware support in CHERI, and the handles supplied through WASI. Their enforcement mechanisms differ, so a library that accepts handles should not be assumed to provide the same isolation as an operating system or sandbox.
Rust's cap-std exposes resource access through explicit handles. Its Dir API limits file
operations to a directory, while opening a directory through ambient authority requires an explicit
marker. This fragment illustrates the distinction:
use cap_std::ambient_authority;
use cap_std::fs::Dir;
fn read_config(dir: &Dir) -> std::io::Result<String> {
// File access through `dir` stays within the directory it represents.
let mut text = String::new();
std::io::Read::read_to_string(&mut dir.open("config.txt")?, &mut text)?;
Ok(text)
}
// Ambient authority is exercised once, and the call marks it.
let dir = Dir::open_ambient_dir("/var/app", ambient_authority())?;
read_config(&dir)?;
dir.open("../secret.txt") // Err: a path led outside of the filesystem
The confinement applies to operations performed through dir. Arbitrary Rust code can still call
std::fs directly if its execution environment permits it. The
cap-std README explains both the handle-based APIs and
the limit of a library-level discipline.
Privilege bits and reference qualifiersβ
Linux capabilities divide superuser privileges into units such as CAP_NET_BIND_SERVICE.
They are per-thread privilege attributes, rather than references to individual resources. The
capabilities manual describes that model.
Pony's reference capabilities describe aliasing and access to values. Qualifiers such as iso,
val, and ref support safe sharing and data-race prevention. Rust ownership and borrowing address
related concerns through different rules. The
Pony reference-capability tutorial
explains these qualifiers. Neither these qualifiers nor Linux privilege bits are mechanisms CGP adds.
Effects as capabilitiesβ
Effect-capability systems make an operation depend on access to a handler-provided capability. Effekt expresses the capabilities a computation requires through its effect types and controls how they can escape their scope. The paper Effects as Capabilities develops this approach.
Scala's capture checking tracks references to capabilities in types, while its safer-exceptions
feature uses CanThrow to express permission to throw a checked exception. The following example
uses the experimental safer-exceptions feature in Scala 3.8.4:
import language.experimental.saferExceptions
class LimitExceeded extends Exception
val limit = 10e9
def f(x: Double): Double throws LimitExceeded =
if x < limit then x * x else throw LimitExceeded()
try println(List(1.0, 2.0, 3.0).map(f).sum) // the try supplies the CanThrow capability
catch case ex: LimitExceeded => println("too large")
The surrounding try supplies the CanThrow evidence needed by f. This illustrates static
permission to perform an operation, rather than a runtime operating-system privilege. See Scala's
CanThrow documentation
and capture-checking reference.
CGP's declared requirements resemble part of this structure, but CGP does not supply capture checking.
Capabilities in Rust discussionsβ
Rust discussions use capability terminology for implicit dependencies, sandboxed resources, and ownership tokens. The intended guarantee matters more than the shared word:
- Implicit dependencies: the contexts-and-capabilities proposal supplies values such as an arena through a context, reducing parameter forwarding. See Mandry's proposal.
- Sandboxed resources:
cap-stdand WASI express access through handles, with different enforcement boundaries. - Ownership tokens: a value with a controlled constructor represents access to a resource, such as a peripheral. The Embedded Rust Book explains the singleton pattern, and PermRust explores token-based permissions.
A request for capabilities in Rust can therefore mean either a more convenient API or a stronger restriction on what code may do. CGP addresses dependency declaration and selection; its wiring alone does not impose the latter restriction.
The properties that distinguish the modelsβ
The following properties help identify which mechanism a program needs:
| Mechanism | What it represents | Where its guarantee comes from |
|---|---|---|
| Object capability | Authority carried by a reference | Controlled references and an environment that excludes bypasses |
| Effect capability | Access to an operation or handler | The language's effect, scope, or capture rules |
| Rust contexts proposal | An implicitly supplied dependency | The proposed context-binding and type-checking rules |
| Ownership token | Access represented by a value | Controlled construction and ownership or borrowing |
| CGP dependency | A trait or field an implementation requires | Rust trait checking against the selected context |
How CGP expresses itβ
CGP declares what a provider needs from its context and checks that the context supplies it. Those requirements may include authority-bearing values, but CGP does not make every dependency an authority token. It also does not restrict access to globals or check the escape of capability references beyond Rust's ordinary type and lifetime rules.
Providers declare requirements on a contextβ
A provider uses #[uses] for trait dependencies and #[implicit] for field dependencies.
This fragment assumes a CanGreet component whose method returns a String:
#[cgp_impl(new GreetHello)]
impl Greeter {
fn greet(&self, #[implicit] name: &str) -> String {
format!("Hello, {name}!")
}
}
#[derive(HasField)]
pub struct App {
pub name: String,
}
delegate_components! {
App {
GreeterComponent: GreetHello,
}
}
check_components! { App { GreeterComponent } }
GreetHello needs a name field, and App supplies it. check_components! verifies the field
requirement for the selected provider; constructing App { name } supplies its runtime value.
App is an environmental context representing an application, and the component is self-targeted.
This is a dependency relationship: the String does not confer protected authority.
Contexts can also determine abstract types, such as the error type shared by their providers. Selecting such a type is separate from supplying an authority-bearing value of that type. A type choice alone does not grant access to a resource.
An object capability can live in the contextβ
A context can carry a cap-std directory handle to a provider that declares it as a dependency.
This example reads configuration using that handle:
use cap_std::fs::Dir;
#[cgp_component(ConfigReader)]
pub trait CanReadConfig {
fn read_config(&self) -> std::io::Result<String>;
}
#[cgp_impl(new ReadConfigFromDir)]
impl ConfigReader {
fn read_config(&self, #[implicit] config_dir: &Dir) -> std::io::Result<String> {
let mut text = String::new();
std::io::Read::read_to_string(&mut config_dir.open("config.txt")?, &mut text)?;
Ok(text)
}
}
#[derive(HasField)]
pub struct App {
pub config_dir: Dir,
}
delegate_components! {
App {
ConfigReaderComponent: ReadConfigFromDir,
}
}
check_components! { App { ConfigReaderComponent } }
cap-std constrains file access performed through config_dir, while CGP verifies that App
supplies the required field. App is again an environmental context with a self-targeted component.
The mechanisms compose: the value type supplies resource-access behavior, and CGP supplies the
dependency declaration and static wiring check. An allocator or arena can be passed through a context
field in the same way, as discussed in Rust's own proposals.
CGP does not remove ambient authorityβ
A provider can access ordinary Rust APIs beyond its context dependencies. ReadConfigFromDir
could call std::fs::File::open(...) directly if the execution environment allows it, and CGP
would not reject the call. Its declared bounds describe requirements on the context, not a complete
list of effects or authority exercised by the body.
A trait bound does not create an authority tokenβ
A HasField bound establishes access to a field of a particular name and type. It does not
establish who may create the field's value. When the field contains a capability, the relevant
construction and access restrictions come from that value's type and execution environment.
Rust types with private constructors can implement controlled tokens; CGP can carry those tokens
without changing their guarantees.
Wiring is static; capability values can vary at runtimeβ
A concrete context type fixes its provider selections and field types. Its values can still hold
different handles: two App instances can refer to different directories, including a temporary
directory used by a test. Their filesystem authority therefore differs even though their wiring
is identical.
Delegation, attenuation, and revocation must come from the capability implementation. A context can hold a wrapper that limits access or checks whether access has been revoked. A higher-order provider can also wrap behavior, but wrapping alone is not proof of attenuation if other access paths remain available. CGP does not add these security properties or prevent runtime capability values from implementing them.
What each approach costsβ
Object capabilities support reasoning about authority through references, but that reasoning needs an enforcement boundary. Retrofitting a handle-based API into an unrestricted language does not remove other APIs that exercise ambient authority. Applications must account for those bypasses or use an environment that excludes them. The cap-std documentation makes this library-level limit explicit.
Effect-capability systems add scope and escape rules that programmers must understand. Effekt's second-class treatment restricts where capabilities can be stored or returned, while Scala's capture checking tracks their use through types. These rules support guarantees that a plain dependency declaration does not provide. The Effekt paper and Scala reference explain the respective designs.
CGP adds declarations, wiring, and compile-time work without supplying confinement or capture
checking. Programs that need those properties must obtain them elsewhere. Its generated trait
machinery also affects diagnostics: cargo cgp check leads with the root
cause for the classes it recognizes, and the tool does not yet reshape every class. The
Modularity Hierarchy compares this machinery
with simpler Rust abstractions.
Where a capability system is the better choiceβ
Use an enforcing capability system when the requirement is to limit what code may access.
A capability-safe language or sandbox can exclude ambient access paths. Within Rust, cap-std
helps express handle-based access, while an appropriate sandbox is needed to constrain code that
could otherwise bypass those handles. Ownership tokens address controlled access to resources
through Rust's construction and borrowing rules.
CGP fits the separate requirement of reusable implementations with declared dependencies and choices per context. It can carry capability values from those systems, but a wiring check is not a security audit or proof of confinement.
What to expect that differsβ
CGP checks declared context requirements rather than all authority used by a body. Ordinary Rust globals and APIs remain available unless another mechanism restricts them.
A field dependency identifies a value the implementation needs. Whether that value grants
protected authority depends on its type and how it was obtained. A String and a directory handle
can both be dependencies without having the same security meaning.
The context type fixes wiring, while runtime values determine which resources its handles reach. Any delegation or revocation behavior belongs to those handles and wrappers, not to the wiring macro.
CGP does not add an escape checker. Rust's ownership, borrowing, and lifetime rules still apply, and a value can be cloned or moved only when its type and the surrounding code permit it. CGP adds neither Effekt's second-class restriction nor Scala's capture sets.
CGP terminology keeps these distinctions visible. A component defines a trait, a provider requires traits and reads fields, and a context supplies those requirements. The term capability is reserved for the external mechanisms and values whose properties justify it.
Where to go nextβ
These pages explain the dependencies and related language proposals:
- Impl-side dependencies: requirements declared by providers.
- Implicit arguments: reading values from context fields.
- Algebraic effects: operations, handlers, and the continuation boundary.
- Rust's own proposals: the contexts-and-capabilities proposal.
Sourcesβ
The cap-std snippets were compiled with cap-std 3 and the CGP snippet against cgp 0.8.0
with a check_components! assertion per wired context; the Scala snippet was compiled with Scala
3.8.4. The Pony snippet was checked against the standard library's documented signatures for
FileAuth, FilePath, and OpenFile rather than compiled.
- Dennis & Van Horn, Programming Semantics for Multiprogrammed Computations (CACM 1966): the origin of the capability.
- Miller, Robust Composition (PhD thesis, 2006) and Miller, Yee & Shapiro, Capability Myths Demolished (2003): the object-capability model, its defining properties, delegation, attenuation, revocation, and the myths.
- Wikipedia, Object-capability model and Capability-based security: the definitions and the systems implementing the model.
- Pony tutorial, Object Capabilities and Reference Capabilities: the unforgeable-token definition,
env.root, and the aliasing qualifiers that share the word. - Austral specification, CHERI, and WASI design principles: linear capability values, architectural capabilities, and unforgeable handles without ambient authority.
- Gohman, Introducing cap-std and the cap-std README: capability-oriented APIs,
ambient_authority(), and the limit that a library cannot sandbox arbitrary Rust code. - capabilities(7): Linux capabilities as privilege units.
- BrachthΓ€user, Schuster & Ostermann, Effects as Capabilities (OOPSLA 2020), Odersky et al., Scoped Capabilities for Polymorphic Effects (2022), Scala 3 Reference, Capture Checking, and CanThrow Capabilities: effect types as capabilities a computation requires, capture sets, and the erased
CanThrow. - Mandry, Contexts and capabilities in Rust and Wuyts, Nesting Allocators: the implicit-value sense and the global allocator as ambient authority.
- Embedded Rust Book, Peripherals as singletons and Gehring, Rehms & Tschorsch, PermRust: ownership tokens as static capabilities.
An AI agent wrote this page using the CGP knowledge base. Its CGP code was verified against the library's source and its other snippets against the toolchains named in Sources. See How AI is used in this project.