typesec_agent/lib.rs
1//! # typesec-agent
2//!
3//! Agent executor: typestate + capability-based access control in action.
4//!
5//! This crate provides the high-level [`SecureAgent`] API that ties together:
6//! - The typestate machine from `typesec-core` (unauthenticated → authenticated).
7//! - Runtime policy checking via any [`PolicyEngine`].
8//! - Typed capability acquisition: the *only* way to get a `Capability<P, R>` is
9//! through a successful policy check.
10//! - Async task execution: the `execute` method requires a capability as proof.
11//!
12//! ## Usage Pattern
13//!
14//! ```rust,ignore
15//! // 1. Create agent with an engine — starts Unauthenticated.
16//! let agent = SecureAgent::new(Arc::new(rbac_engine));
17//!
18//! // 2. Authenticate — type transitions to Authenticated.
19//! let agent = agent.authenticate(Credentials::new("agent:bot", "token"))?;
20//!
21//! // 3. Request a capability — policy checked at runtime, cap minted on success.
22//! let report = Report::new("reports/q1");
23//! let cap: Capability<CanRead, Report> = agent.request_capability(&report).await?;
24//!
25//! // 4. Execute — cap is required proof. No cap? Won't compile.
26//! agent.execute(&cap, &report, |r| Box::pin(async move {
27//! println!("reading: {}", r.id);
28//! Ok(())
29//! })).await?;
30//! ```
31
32#![forbid(unsafe_code)]
33#![warn(missing_docs, clippy::all)]
34
35pub mod agent;
36pub mod executor;
37pub mod tool;
38
39pub use agent::{AgentBuilder, SecureAgent};
40pub use executor::TaskResult;
41pub use tool::{ProtectedTool, ToolFuture, ToolSpec};
42
43// Re-export core types for convenience.
44pub use typesec_core::{
45 CanDelete, CanExecute, CanRead, CanWrite, Capability, Credentials, Permission, Resource,
46};