capsec_core/lib.rs
1//! # capsec-core
2//!
3//! Zero-cost capability tokens and permission traits for compile-time
4//! capability-based security in Rust.
5//!
6//! This crate provides the foundational types that the rest of the `capsec`
7//! ecosystem builds on:
8//!
9//! - [`Permission`](permission::Permission) — marker trait for capability categories
10//! - [`Cap<P>`](cap::Cap) — zero-sized proof token that the holder has permission `P`
11//! - [`Has<P>`](has::Has) — trait for checking and composing capabilities
12//! - [`CapRoot`](root::CapRoot) — the singleton root of all capability grants
13//! - [`Attenuated<P, S>`](attenuate::Attenuated) — scope-restricted capabilities
14//! - [`CapSecError`](error::CapSecError) — error types for scope violations and I/O
15//!
16//! All capability types are zero-sized at runtime. The security model is enforced
17//! entirely through the type system — no runtime overhead.
18//!
19//! # Quick start
20//!
21//! ```rust,ignore
22//! use capsec_core::root::test_root;
23//! use capsec_core::permission::{FsRead, NetConnect};
24//! use capsec_core::has::Has;
25//!
26//! // Create a capability root (use test_root in tests)
27//! let root = test_root();
28//!
29//! // Grant individual capabilities
30//! let fs_cap = root.grant::<FsRead>();
31//! let net_cap = root.grant::<NetConnect>();
32//!
33//! // Functions declare what they need via Has<P> bounds
34//! fn needs_both(fs: &impl Has<FsRead>, net: &impl Has<NetConnect>) {
35//! let _ = fs.cap_ref();
36//! let _ = net.cap_ref();
37//! }
38//!
39//! needs_both(&fs_cap, &net_cap);
40//! ```
41
42pub mod attenuate;
43pub mod cap;
44pub mod error;
45pub mod has;
46pub mod permission;
47pub mod root;
48pub mod runtime;
49
50/// Re-export of the seal token module for use by `#[capsec::permission]` macro.
51/// Do not use directly.
52#[doc(hidden)]
53pub use permission::__private;