orcs_auth/lib.rs
1//! Permission primitives for ORCS.
2//!
3//! This crate provides the unified permission model for ORCS,
4//! sitting at the same level as `orcs-event` in the dependency graph.
5//!
6//! # Permission Model
7//!
8//! ```text
9//! Effective Permission =
10//! Capability(static WHAT)
11//! ∩ SandboxPolicy(WHERE)
12//! ∩ Session(WHO + WHEN)
13//! ∩ GrantPolicy(dynamic WHAT — modified by Grant/Revoke)
14//! ```
15//!
16//! | Layer | Type | Controls |
17//! |-------|------|----------|
18//! | [`Capability`] | Bitflags | What operations are allowed (static, inherited) |
19//! | [`SandboxPolicy`] | Trait | Where operations can target (filesystem boundary, etc.) |
20//! | [`Session`] | Struct | Who is acting, with what privilege level |
21//! | [`GrantPolicy`] | Trait | Dynamic command permissions (grant/revoke at runtime) |
22//! | [`PermissionPolicy`] | Trait | Combines all layers for permission decisions |
23//!
24//! # Crate Architecture
25//!
26//! ```text
27//! orcs-types (IDs, Principal)
28//! ↑ ↑
29//! orcs-event orcs-auth ◄── THIS CRATE
30//! (Signal) (Capability, SandboxPolicy, Session, GrantPolicy, PermissionPolicy)
31//! ↑ ↑
32//! orcs-component (Component, ChildContext — uses orcs-auth)
33//! ↑
34//! orcs-runtime (ProjectSandbox impl, DefaultGrantStore impl, DefaultPolicy impl)
35//! ```
36//!
37//! # Design Principles
38//!
39//! - **Trait definitions here, implementations in consumers** — orcs-runtime provides
40//! concrete implementations like `ProjectSandbox` and `DefaultPolicy`
41//! - **Resource-general** — `SandboxPolicy` abstracts filesystem today, but the model
42//! extends to Docker volumes, network scopes, etc.
43//! - **Deny wins** — A child can never exceed its parent's capabilities
44
45pub mod capability;
46pub mod error;
47pub mod grant;
48pub mod permission;
49pub mod policy;
50pub mod privilege;
51pub mod resource;
52pub mod session;
53
54// Re-export core types
55pub use capability::Capability;
56pub use error::AccessDenied;
57pub use grant::{CommandGrant, GrantError, GrantKind, GrantPolicy};
58pub use permission::CommandPermission;
59pub use policy::PermissionPolicy;
60pub use privilege::PrivilegeLevel;
61pub use resource::{SandboxError, SandboxPolicy};
62pub use session::Session;
63
64// Re-export Principal from orcs_types for convenience
65pub use orcs_types::Principal;