Crate capsec 

capsec — Compile-Time Capability-Based Security for Rust

capsec enforces the principle of least privilege at the type level. Functions declare their I/O capabilities via trait bounds, and the compiler ensures they cannot exceed them.

Quick Start

use capsec::prelude::*;

fn main() {
    let root = capsec::root();
    let fs_cap = root.grant::<FsRead>();
    let data = load_data("/tmp/data.csv", &fs_cap).unwrap();
}

fn load_data(path: &str, cap: &impl Has<FsRead>) -> Result<String, capsec::CapSecError> {
    capsec::fs::read_to_string(path, cap)
}

Architecture

This is a facade crate that re-exports from three internal crates:

• capsec-core — capability tokens, permission traits, composition
• capsec-macro — #[requires], #[deny], #[main], and #[context] proc macros
• capsec-std — capability-gated std wrappers

Modules

env

Capability-gated environment variable access. See capsec_std::env.

fs

Capability-gated filesystem operations. See capsec_std::fs.

net

Capability-gated network operations. See capsec_std::net.

prelude

Common imports for working with capsec.

process

Capability-gated subprocess execution. See capsec_std::process.

Structs

Ambient

Full ambient authority — grants every permission.

ApproverA

First approval handle for a DualKeyCap.

ApproverB

Second approval handle for a DualKeyCap.

Attenuated

A capability that has been narrowed to a specific scope.

Cap

A zero-sized capability token proving the holder has permission P.

CapRoot

The root of all capabilities. Only one can exist per process.

DirScope

Restricts filesystem operations to a directory subtree.

DualKeyCap

A dual-authorization capability requiring two independent approvals.

DualKeySendCap

A thread-safe dual-authorization capability token.

EnvRead

Permission to read environment variables.

EnvWrite

Permission to modify or remove environment variables.

FsAll

Permission for all filesystem operations. Subsumes FsRead and FsWrite.

FsRead

Permission to read files, list directories, and check metadata.

FsWrite

Permission to write, create, rename, and delete files and directories.

HostScope

Restricts network operations to a set of allowed host prefixes.

LogEntry

A record of a single capability exercise attempt.

LoggedCap

An audited capability token that logs every exercise attempt.

LoggedSendCap

A thread-safe audited capability token.

NetAll

Permission for all network operations. Subsumes NetConnect and NetBind.

NetBind

Permission to bind TCP listeners and UDP sockets to local ports.

NetConnect

Permission to open outbound TCP and UDP connections.

Revoker

A handle that can revoke its associated RuntimeCap (and all clones).

RuntimeCap

A revocable capability token proving the holder has permission P.

RuntimeSendCap

A thread-safe revocable capability token.

SendCap

A thread-safe capability token that can be sent across threads.

Spawn

Permission to spawn and execute subprocesses via std::process::Command.

TimedCap

A time-bounded capability token proving the holder has permission P.

TimedSendCap

A thread-safe time-bounded capability token.

Enums

CapSecError

Errors that can occur when using capsec capabilities.

Traits

Has

Proof that a capability token includes permission P.

Permission

Marker trait for all capability permissions.

Scope

A restriction that narrows the set of targets a capability can act on.

Subsumes

Indicates that Self implies permission P.

Functions

root

Creates the singleton capability root. Panics if called more than once.

run

Creates a CapRoot and passes it to the given closure.

test_root

Creates a capability root for testing. Bypasses the singleton check.

try_root

Creates the singleton capability root, returning None if already created.

Attribute Macros

context

Transforms a struct with permission-type fields into a capability context.

deny

Marks a function as capability-free.

main

Injects CapRoot creation into a function entry point.

permission

Defines a user-defined permission type for capability-based security.

requires

Declares the capability requirements of a function.