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