capsec 0.2.2

Compile-time capability-based security for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

//! # 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
//!
//! ```rust,ignore
//! 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 CapProvider<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

//  Re-exports from capsec-core

pub use capsec_core::cap::{Cap, SendCap};
pub use capsec_core::error::CapSecError;
pub use capsec_core::has::Has;
pub use capsec_core::permission::{
    Ambient, EnvRead, EnvWrite, FsAll, FsRead, FsWrite, NetAll, NetBind, NetConnect, Permission,
    Spawn, Subsumes,
};
pub use capsec_core::root::{CapRoot, root, try_root};

#[cfg(debug_assertions)]
pub use capsec_core::root::test_root;

pub use capsec_core::attenuate::{Attenuated, DirScope, HostScope, Scope};

pub use capsec_core::cap_provider::CapProvider;

pub use capsec_core::runtime::{Revoker, RuntimeCap, RuntimeSendCap, TimedCap, TimedSendCap};

pub use capsec_core::prescript::{
    ApproverA, ApproverB, DualKeyCap, DualKeySendCap, LogEntry, LoggedCap, LoggedSendCap,
};

/// Creates a `CapRoot` and passes it to the given closure.
///
/// This is a convenience entry point. Panics if `root()` has already been called.
pub fn run<T>(f: impl FnOnce(CapRoot) -> T) -> T {
    let root = root();
    f(root)
}

//  Re-exports from capsec-macro

pub use capsec_macro::{context, deny, main, permission, requires};

//  Capability-gated std wrappers

/// Capability-gated filesystem operations. See [`capsec_std::fs`].
pub mod fs {
    pub use capsec_std::file::{ReadFile, WriteFile};
    pub use capsec_std::fs::*;
}

/// Capability-gated network operations. See [`capsec_std::net`].
pub mod net {
    pub use capsec_std::net::*;
}

/// Capability-gated environment variable access. See [`capsec_std::env`].
pub mod env {
    pub use capsec_std::env::*;
}

/// Capability-gated subprocess execution. See [`capsec_std::process`].
pub mod process {
    pub use capsec_std::process::*;
}

//  Async capability-gated tokio wrappers (optional)

/// Async capability-gated wrappers for tokio. Requires the `tokio` feature.
///
/// ```toml
/// capsec = { version = "0.1", features = ["tokio"] }
/// ```
#[cfg(feature = "tokio")]
pub mod tokio {
    /// Task spawning with capability transfer.
    pub mod task {
        pub use capsec_tokio::task::*;
    }
    /// Async capability-gated filesystem operations.
    pub mod fs {
        pub use capsec_tokio::file::{AsyncReadFile, AsyncWriteFile};
        pub use capsec_tokio::fs::*;
    }
    /// Async capability-gated network operations.
    pub mod net {
        pub use capsec_tokio::net::*;
    }
    /// Async capability-gated subprocess execution.
    pub mod process {
        pub use capsec_tokio::process::*;
    }
}

/// Common imports for working with capsec.
///
/// ```
/// use capsec::prelude::*;
/// ```
pub mod prelude {
    pub use crate::{
        Ambient, ApproverA, ApproverB, Attenuated, Cap, CapProvider, CapRoot, CapSecError,
        DirScope, DualKeyCap, DualKeySendCap, EnvRead, EnvWrite, FsAll, FsRead, FsWrite, Has,
        HostScope, LoggedCap, LoggedSendCap, NetAll, NetBind, NetConnect, Permission, Revoker,
        RuntimeCap, RuntimeSendCap, Scope, SendCap, Spawn, Subsumes, TimedCap, TimedSendCap,
    };
}