feat: migrate public API from Has<P> to CapProvider<P> for transparent scope enforcement

Author: bordumb

CONTRIBUTING.md

@@ -164,7 +164,7 @@ capsec provides four macros that work together:
 
 | Macro | Purpose |
 |-------|---------|
-| `#[capsec::context]` | Generates `Has<P>` impls on a struct, turning it into a capability context |
+| `#[capsec::context]` | Generates `Has<P>` and `CapProvider<P>` impls on a struct, turning it into a capability context |
 | `#[capsec::main]` | Injects `CapRoot` creation into a function entry point |
 | `#[capsec::requires]` | Validates that a function's parameters satisfy declared permissions |
 | `#[capsec::deny]` | Marks a function as capability-free; violations are promoted to critical by the audit tool |

Cargo.toml

@@ -51,7 +51,7 @@ trybuild = "1"
 insta = { version = "1", features = ["yaml"] }
 
 # Internal crates
-capsec-core = { path = "crates/capsec-core", version = "0.1.0" }
-capsec-macro = { path = "crates/capsec-macro", version = "0.1.0" }
-capsec-std = { path = "crates/capsec-std", version = "0.1.0" }
-capsec-tokio = { path = "crates/capsec-tokio", version = "0.1.0" }
+capsec-core = { path = "crates/capsec-core", version = "0.1.9" }
+capsec-macro = { path = "crates/capsec-macro", version = "0.1.9" }
+capsec-std = { path = "crates/capsec-std", version = "0.1.9" }
+capsec-tokio = { path = "crates/capsec-tokio", version = "0.1.9" }

README.md

@@ -22,7 +22,7 @@ cargo capsec audit
 capsec fills that gap with three layers:
 
 1. **`cargo capsec audit`** — a static audit tool that scans your code and reports every I/O call. Drop it into CI and know exactly what your dependencies do.
-2. **Compile-time type system** — functions declare their I/O permissions via `Has<P>` trait bounds, and the compiler rejects anything that exceeds them. Zero runtime cost.
+2. **Compile-time type system** — functions declare their I/O permissions via `CapProvider<P>` trait bounds, and the compiler rejects anything that exceeds them. Zero runtime cost. Scoped capabilities (`Attenuated<P, S>`) enforce *where* a capability can act.
 3. **Runtime capability control** — `RuntimeCap` (revocable) and `TimedCap` (expiring) wrap static capabilities with runtime validity checks for dynamic scenarios like server init or migration windows.
 
 The audit tool finds the problems. The type system prevents them at compile time. Runtime caps handle the cases where permissions need to change dynamically.
@@ -120,15 +120,15 @@ Functions declare their I/O requirements in the type signature. The compiler enf
 use capsec::prelude::*;
 
 // Define a context with exactly the permissions your app needs.
-// The macro generates Cap fields, constructor, and Has<P> impls.
+// The macro generates Cap fields, constructor, Has<P> impls, and CapProvider<P> impls.
 #[capsec::context]
 struct AppCtx {
     fs: FsRead,
     net: NetConnect,
 }
 
-// Leaf functions take &impl Has<P> — works with raw caps AND context structs.
-pub fn load_config(path: &str, cap: &impl Has<FsRead>) -> Result<String, CapSecError> {
+// Leaf functions take &impl CapProvider<P> — works with raw caps, context structs, AND scoped caps.
+pub fn load_config(path: &str, cap: &impl CapProvider<FsRead>) -> Result<String, CapSecError> {
     capsec::fs::read_to_string(path, cap)
 }
 
@@ -157,11 +157,11 @@ let _ = capsec::fs::read_to_string("/etc/passwd", &net_cap);
 ```
 
 ```
-error[E0277]: the trait bound `Cap<NetConnect>: Has<FsRead>` is not satisfied
+error[E0277]: the trait bound `Cap<NetConnect>: CapProvider<FsRead>` is not satisfied
  --> src/main.rs:4:55
   |
 4 |     let _ = capsec::fs::read_to_string("/etc/passwd", &net_cap);
-  |             --------------------------                ^^^^^^^^ the trait `Has<FsRead>` is not implemented for `Cap<NetConnect>`
+  |             --------------------------                ^^^^^^^^ the trait `CapProvider<FsRead>` is not implemented for `Cap<NetConnect>`
   |             |
   |             required by a bound introduced by this call
 ```
@@ -189,15 +189,15 @@ help: provide the argument
 
 ```rust
 let fs_all = root.grant::<FsAll>();
-needs_net(&fs_all);  // fn needs_net(_: &impl Has<NetConnect>) {}
+needs_net(&fs_all);  // fn needs_net(_: &impl CapProvider<NetConnect>) {}
 ```
 
 ```
-error[E0277]: the trait bound `Cap<FsAll>: Has<NetConnect>` is not satisfied
+error[E0277]: the trait bound `Cap<FsAll>: CapProvider<NetConnect>` is not satisfied
  --> src/main.rs:3:15
   |
 3 |     needs_net(&fs_all);
-  |     --------- ^^^^^^^ the trait `Has<NetConnect>` is not implemented for `Cap<FsAll>`
+  |     --------- ^^^^^^^ the trait `CapProvider<NetConnect>` is not implemented for `Cap<FsAll>`
   |     |
   |     required by a bound introduced by this call
 ```
@@ -210,7 +210,7 @@ These are real `rustc` errors — no custom error framework, no runtime panics.
 |--|--------|-------|
 | Can any function read files? | Yes | Only if it has `Cap<FsRead>` |
 | Can any function open sockets? | Yes | Only if it has `Cap<NetConnect>` |
-| Can you audit who has what access? | Grep and pray | Grep for `Has<FsRead>` |
+| Can you audit who has what access? | Grep and pray | Grep for `CapProvider<FsRead>` |
 | Runtime cost? | N/A | Zero — all types are erased at compile time |
 
 ### Security model
@@ -347,7 +347,7 @@ fn main(root: CapRoot) -> Result<(), Box<dyn std::error::Error>> {
 
 ### Key properties
 
-- `RuntimeCap`, `TimedCap`, `LoggedCap`, and `DualKeyCap` do **not** implement `Has<P>` — fallibility is explicit via `try_cap()` at every call site
+- `RuntimeCap`, `TimedCap`, `LoggedCap`, and `DualKeyCap` do **not** implement `Has<P>` but they do implement `CapProvider<P>` — so they can be passed directly to capsec-std/tokio functions. Fallibility is handled transparently by `provide_cap()`
 - All are `!Send` by default — use `make_send()` to opt into cross-thread transfer
 - Cloning a `RuntimeCap` shares the revocation flag — revoking one revokes all clones
 - Cloning a `LoggedCap` shares the audit log — entries from any clone appear in the same log
@@ -379,7 +379,7 @@ capsec's design draws from three foundational papers in capability-based securit
 
 - **Saltzer & Schroeder (1975)** — [The Protection of Information in Computer Systems](https://www.cs.virginia.edu/~evans/cs551/saltzer/). Defined the eight design principles for protection mechanisms. capsec implements six: economy of mechanism (zero-sized types), fail-safe defaults (no cap = no access), least privilege (the core mission), open design (open source + adversarial test suite), separation of privilege (`DualKeyCap`), and compromise recording (`LoggedCap`). The two partially met — complete mediation and least common mechanism — are inherent limitations of a library-level approach.
 
-- **Melicher et al. (2017)** — [A Capability-Based Module System for Authority Control](https://www.cs.cmu.edu/~aldrich/papers/ecoop17modules.pdf) (ECOOP 2017). Formalized non-transitive authority in the Wyvern language, proving that a module's authority can be determined by inspecting only its interface. capsec achieves the same property: `Has<P>` bounds make a function's authority visible in its signature, and `Attenuated<P, S>` / runtime cap types that don't implement `Has<P>` enforce non-transitivity.
+- **Melicher et al. (2017)** — [A Capability-Based Module System for Authority Control](https://www.cs.cmu.edu/~aldrich/papers/ecoop17modules.pdf) (ECOOP 2017). Formalized non-transitive authority in the Wyvern language, proving that a module's authority can be determined by inspecting only its interface. capsec achieves the same property: `CapProvider<P>` bounds make a function's authority visible in its signature, and `Attenuated<P, S>` enforces non-transitivity through scope checks embedded in `provide_cap()`.
 
 ---
 

crates/capsec-core/src/attenuate.rs

@@ -58,6 +58,7 @@ impl<P: Permission> Cap<P> {
 
 impl<P: Permission, S: Scope> Attenuated<P, S> {
     /// Checks whether `target` is within this capability's scope.
+    #[must_use = "ignoring a scope check silently discards scope violations"]
     pub fn check(&self, target: &str) -> Result<(), CapSecError> {
         self.scope.check(target)
     }

crates/capsec-core/src/cap.rs

@@ -30,6 +30,7 @@ use std::marker::PhantomData;
 /// // cap is a proof token — zero bytes at runtime
 /// assert_eq!(std::mem::size_of_val(&cap), 0);
 /// ```
+#[must_use = "capability tokens are proof of permission — discarding one wastes a grant"]
 pub struct Cap<P: Permission> {
     _phantom: PhantomData<P>,
     // PhantomData<*const ()> makes Cap !Send + !Sync
@@ -68,6 +69,7 @@ impl<P: Permission> Cap<P> {
     ///
     /// This is an explicit opt-in — you're acknowledging that this capability
     /// will be used in a multi-threaded context (e.g., passed into `tokio::spawn`).
+    #[must_use = "make_send consumes the original Cap and returns a SendCap"]
     pub fn make_send(self) -> SendCap<P> {
         SendCap {
             _phantom: PhantomData,
@@ -100,6 +102,7 @@ impl<P: Permission> Clone for Cap<P> {
 ///     // use cap in this thread
 /// }).join().unwrap();
 /// ```
+#[must_use = "capability tokens are proof of permission — discarding one wastes a grant"]
 pub struct SendCap<P: Permission> {
     _phantom: PhantomData<P>,
 }

crates/capsec-core/src/cap_provider.rs

@@ -14,6 +14,7 @@ use crate::permission::Permission;
 pub trait CapProvider<P: Permission> {
     /// Provides a `Cap<P>` for the given target, or returns an error if the
     /// target is outside the capability's scope.
+    #[must_use = "ignoring a capability check silently discards scope violations"]
     fn provide_cap(&self, target: &str) -> Result<Cap<P>, CapSecError>;
 }
 
@@ -63,7 +64,7 @@ impl<P: Permission> CapProvider<P> for crate::cap::SendCap<P> {
     }
 }
 
-// ── Subsumption ─────────────────────────────────────────────────────
+// ── Subsumption (Cap) ────────────────────────────────────────────────
 
 macro_rules! impl_cap_provider_subsumes {
     ($super:ty => $($sub:ty),+) => {
@@ -82,7 +83,24 @@ use crate::permission::*;
 impl_cap_provider_subsumes!(FsAll => FsRead, FsWrite);
 impl_cap_provider_subsumes!(NetAll => NetConnect, NetBind);
 
-// ── Ambient ─────────────────────────────────────────────────────────
+// ── Subsumption (SendCap) ───────────────────────────────────────────
+
+macro_rules! impl_cap_provider_sendcap_subsumes {
+    ($super:ty => $($sub:ty),+) => {
+        $(
+            impl CapProvider<$sub> for crate::cap::SendCap<$super> {
+                fn provide_cap(&self, _target: &str) -> Result<Cap<$sub>, CapSecError> {
+                    Ok(Cap::new())
+                }
+            }
+        )+
+    }
+}
+
+impl_cap_provider_sendcap_subsumes!(FsAll => FsRead, FsWrite);
+impl_cap_provider_sendcap_subsumes!(NetAll => NetConnect, NetBind);
+
+// ── Ambient (Cap) ───────────────────────────────────────────────────
 
 macro_rules! impl_cap_provider_ambient {
     ($($perm:ty),+) => {
@@ -100,7 +118,25 @@ impl_cap_provider_ambient!(
     FsRead, FsWrite, FsAll, NetConnect, NetBind, NetAll, EnvRead, EnvWrite, Spawn
 );
 
-// ── Tuples ──────────────────────────────────────────────────────────
+// ── Ambient (SendCap) ───────────────────────────────────────────────
+
+macro_rules! impl_cap_provider_sendcap_ambient {
+    ($($perm:ty),+) => {
+        $(
+            impl CapProvider<$perm> for crate::cap::SendCap<Ambient> {
+                fn provide_cap(&self, _target: &str) -> Result<Cap<$perm>, CapSecError> {
+                    Ok(Cap::new())
+                }
+            }
+        )+
+    }
+}
+
+impl_cap_provider_sendcap_ambient!(
+    FsRead, FsWrite, FsAll, NetConnect, NetBind, NetAll, EnvRead, EnvWrite, Spawn
+);
+
+// ── Tuples (Cap) ────────────────────────────────────────────────────
 
 macro_rules! impl_cap_provider_tuple_first {
     ([$($a:ident),+]; $all:tt) => {
@@ -145,6 +181,101 @@ impl_cap_provider_tuple_second!(
     FsRead, FsWrite, FsAll, NetConnect, NetBind, NetAll, EnvRead, EnvWrite, Spawn, Ambient
 );
 
+// ── Tuples (SendCap) ────────────────────────────────────────────────
+
+macro_rules! impl_cap_provider_sendcap_tuple_first {
+    ([$($a:ident),+]; $all:tt) => {
+        $( impl_cap_provider_sendcap_tuple_first!(@inner $a; $all); )+
+    };
+    (@inner $a:ident; [$($b:ident),+]) => {
+        $(
+            impl CapProvider<$a> for crate::cap::SendCap<($a, $b)> {
+                fn provide_cap(&self, _target: &str) -> Result<Cap<$a>, CapSecError> {
+                    Ok(Cap::new())
+                }
+            }
+        )+
+    };
+}
+
+macro_rules! impl_cap_provider_sendcap_tuple_second {
+    ($first:ident $(, $rest:ident)+) => {
+        $(
+            impl CapProvider<$first> for crate::cap::SendCap<($rest, $first)> {
+                fn provide_cap(&self, _target: &str) -> Result<Cap<$first>, CapSecError> {
+                    Ok(Cap::new())
+                }
+            }
+            impl CapProvider<$rest> for crate::cap::SendCap<($first, $rest)> {
+                fn provide_cap(&self, _target: &str) -> Result<Cap<$rest>, CapSecError> {
+                    Ok(Cap::new())
+                }
+            }
+        )+
+        impl_cap_provider_sendcap_tuple_second!($($rest),+);
+    };
+    ($single:ident) => {};
+}
+
+impl_cap_provider_sendcap_tuple_first!(
+    [FsRead, FsWrite, FsAll, NetConnect, NetBind, NetAll, EnvRead, EnvWrite, Spawn, Ambient];
+    [FsRead, FsWrite, FsAll, NetConnect, NetBind, NetAll, EnvRead, EnvWrite, Spawn, Ambient]
+);
+
+impl_cap_provider_sendcap_tuple_second!(
+    FsRead, FsWrite, FsAll, NetConnect, NetBind, NetAll, EnvRead, EnvWrite, Spawn, Ambient
+);
+
+// ── Runtime / Prescript types ───────────────────────────────────────
+
+impl<P: Permission> CapProvider<P> for crate::runtime::RuntimeCap<P> {
+    fn provide_cap(&self, _target: &str) -> Result<Cap<P>, CapSecError> {
+        self.try_cap()
+    }
+}
+
+impl<P: Permission> CapProvider<P> for crate::runtime::RuntimeSendCap<P> {
+    fn provide_cap(&self, _target: &str) -> Result<Cap<P>, CapSecError> {
+        self.try_cap()
+    }
+}
+
+impl<P: Permission> CapProvider<P> for crate::runtime::TimedCap<P> {
+    fn provide_cap(&self, _target: &str) -> Result<Cap<P>, CapSecError> {
+        self.try_cap()
+    }
+}
+
+impl<P: Permission> CapProvider<P> for crate::runtime::TimedSendCap<P> {
+    fn provide_cap(&self, _target: &str) -> Result<Cap<P>, CapSecError> {
+        self.try_cap()
+    }
+}
+
+impl<P: Permission> CapProvider<P> for crate::prescript::LoggedCap<P> {
+    fn provide_cap(&self, _target: &str) -> Result<Cap<P>, CapSecError> {
+        self.try_cap()
+    }
+}
+
+impl<P: Permission> CapProvider<P> for crate::prescript::LoggedSendCap<P> {
+    fn provide_cap(&self, _target: &str) -> Result<Cap<P>, CapSecError> {
+        self.try_cap()
+    }
+}
+
+impl<P: Permission> CapProvider<P> for crate::prescript::DualKeyCap<P> {
+    fn provide_cap(&self, _target: &str) -> Result<Cap<P>, CapSecError> {
+        self.try_cap()
+    }
+}
+
+impl<P: Permission> CapProvider<P> for crate::prescript::DualKeySendCap<P> {
+    fn provide_cap(&self, _target: &str) -> Result<Cap<P>, CapSecError> {
+        self.try_cap()
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -186,4 +317,79 @@ mod tests {
         assert!(CapProvider::<FsRead>::provide_cap(&cap, "/any").is_ok());
         assert!(CapProvider::<NetConnect>::provide_cap(&cap, "host").is_ok());
     }
+
+    #[test]
+    fn sendcap_subsumption_provides() {
+        let root = crate::root::test_root();
+        let cap = root.grant::<FsAll>().make_send();
+        let result: Result<Cap<FsRead>, _> = cap.provide_cap("/any");
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn sendcap_ambient_provides() {
+        let root = crate::root::test_root();
+        let cap = root.grant::<Ambient>().make_send();
+        let result: Result<Cap<FsRead>, _> = cap.provide_cap("/any");
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn sendcap_tuple_provides() {
+        let root = crate::root::test_root();
+        let cap = root.grant::<(FsRead, NetConnect)>().make_send();
+        assert!(CapProvider::<FsRead>::provide_cap(&cap, "/any").is_ok());
+        assert!(CapProvider::<NetConnect>::provide_cap(&cap, "host").is_ok());
+    }
+
+    #[test]
+    fn runtime_cap_provides() {
+        let root = crate::root::test_root();
+        let cap = root.grant::<FsRead>();
+        let (rcap, _revoker) = crate::runtime::RuntimeCap::new(cap);
+        assert!(rcap.provide_cap("/any").is_ok());
+    }
+
+    #[test]
+    fn runtime_cap_provides_fails_after_revocation() {
+        let root = crate::root::test_root();
+        let cap = root.grant::<FsRead>();
+        let (rcap, revoker) = crate::runtime::RuntimeCap::new(cap);
+        revoker.revoke();
+        assert!(rcap.provide_cap("/any").is_err());
+    }
+
+    #[test]
+    fn timed_cap_provides() {
+        let root = crate::root::test_root();
+        let cap = root.grant::<FsRead>();
+        let tcap = crate::runtime::TimedCap::new(cap, std::time::Duration::from_secs(60));
+        assert!(tcap.provide_cap("/any").is_ok());
+    }
+
+    #[test]
+    fn logged_cap_provides() {
+        let root = crate::root::test_root();
+        let cap = root.grant::<FsRead>();
+        let lcap = crate::prescript::LoggedCap::new(cap);
+        assert!(lcap.provide_cap("/any").is_ok());
+    }
+
+    #[test]
+    fn dual_key_cap_provides() {
+        let root = crate::root::test_root();
+        let cap = root.grant::<FsRead>();
+        let (dcap, a, b) = crate::prescript::DualKeyCap::new(cap);
+        a.approve();
+        b.approve();
+        assert!(dcap.provide_cap("/any").is_ok());
+    }
+
+    #[test]
+    fn dual_key_cap_provides_fails_without_approvals() {
+        let root = crate::root::test_root();
+        let cap = root.grant::<FsRead>();
+        let (dcap, _a, _b) = crate::prescript::DualKeyCap::new(cap);
+        assert!(dcap.provide_cap("/any").is_err());
+    }
 }