authz_core/
lib.rs

1//! `authz-core` — Zanzibar-style Fine-Grained Authorization engine.
2//!
3//! This crate is the database- and transport-agnostic core of an authorization system.
4//! It provides everything needed to define, parse, and evaluate an authorization model
5//! without depending on any specific datastore or runtime.
6//!
7//! # Overview
8//!
9//! The main workflow:
10//!
11//! 1. **Write a model** in the built-in DSL (OpenFGA-inspired syntax).
12//! 2. **Parse** it with [`model_parser::parse_dsl`] into a [`model_ast::ModelFile`].
13//! 3. **Build** a [`type_system::TypeSystem`] from the parsed model.
14//! 4. **Implement** the [`traits::TupleReader`] trait for your datastore.
15//! 5. **Construct** a [`core_resolver::CoreResolver`] and call
16//!    [`resolver::CheckResolver::resolve_check`] to evaluate permissions.
17//!
18//! # Example
19//!
20//! ```rust,no_run
21//! use authz_core::model_parser::parse_dsl;
22//! use authz_core::type_system::TypeSystem;
23//! use authz_core::policy_provider::StaticPolicyProvider;
24//! use authz_core::core_resolver::CoreResolver;
25//! use authz_core::resolver::{CheckResolver, CheckResult, ResolveCheckRequest};
26//!
27//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
28//! let model = parse_dsl(r#"
29//!     type user {}
30//!     type document {
31//!         relations
32//!             define owner:  [user]
33//!             define viewer: [user]
34//!         permissions
35//!             define can_view = viewer + owner
36//!     }
37//! "#)?;
38//!
39//! let type_system = TypeSystem::new(model);
40//! let provider    = StaticPolicyProvider::new(type_system);
41//!
42//! // `MyStore` implements TupleReader — connect to your real datastore here.
43//! # use authz_core::traits::{Tuple, TupleFilter, TupleReader};
44//! # use authz_core::error::AuthzError;
45//! # #[derive(Clone)]
46//! # struct MyStore;
47//! # #[async_trait::async_trait]
48//! # impl TupleReader for MyStore {
49//! #     async fn read_tuples(&self, _: &TupleFilter) -> Result<Vec<Tuple>, AuthzError> { Ok(vec![]) }
50//! #     async fn read_user_tuple(&self, _: &str, _: &str, _: &str, _: &str, _: &str) -> Result<Option<Tuple>, AuthzError> { Ok(None) }
51//! #     async fn read_userset_tuples(&self, _: &str, _: &str, _: &str) -> Result<Vec<Tuple>, AuthzError> { Ok(vec![]) }
52//! #     async fn read_starting_with_user(&self, _: &str, _: &str) -> Result<Vec<Tuple>, AuthzError> { Ok(vec![]) }
53//! #     async fn read_user_tuple_batch(&self, _: &str, _: &str, _: &[String], _: &str, _: &str) -> Result<Option<Tuple>, AuthzError> { Ok(None) }
54//! # }
55//! let resolver = CoreResolver::new(MyStore, provider);
56//!
57//! let req = ResolveCheckRequest::new(
58//!     "document".into(), "doc-42".into(), "can_view".into(),
59//!     "user".into(),     "alice".into(),
60//! );
61//!
62//! match resolver.resolve_check(req).await? {
63//!     CheckResult::Allowed                   => println!("allowed"),
64//!     CheckResult::Denied                    => println!("denied"),
65//!     CheckResult::ConditionRequired(params) => println!("need: {:?}", params),
66//! }
67//! # Ok(())
68//! # }
69//! ```
70//!
71//! # Modules
72//!
73//! | Module | Purpose |
74//! |---|---|
75//! | [`model_ast`] | AST types produced by the parser |
76//! | [`model_parser`] | Parse the model DSL into a [`model_ast::ModelFile`] |
77//! | [`model_validator`] | Semantic validation of a parsed model |
78//! | [`type_system`] | In-memory model index; tuple validation |
79//! | [`traits`] | Core data types and async datastore traits |
80//! | [`resolver`] | [`resolver::CheckResolver`] trait and request/result types |
81//! | [`core_resolver`] | Built-in graph-walking resolver implementation |
82//! | [`policy_provider`] | Policy loading abstraction + [`policy_provider::StaticPolicyProvider`] |
83//! | [`dispatcher`] | Fan-out dispatcher trait + [`dispatcher::LocalDispatcher`] |
84//! | [`cache`] | Pluggable cache abstraction + [`cache::NoopCache`] |
85//! | [`cel`] | CEL (Common Expression Language) condition evaluation |
86//! | [`tenant_schema`] | [`tenant_schema::ChangelogReader`] for the Watch API |
87//! | [`error`] | [`error::AuthzError`] — all error variants |
88//!
89//! # Feature flags
90//!
91//! This crate has no optional feature flags. All components are always compiled.
92//!
93//! # MSRV
94//!
95//! Rust **1.85** or later (edition 2024).
96
97pub mod cache;
98pub mod cel;
99pub mod core_resolver;
100pub mod dispatcher;
101pub mod error;
102pub mod model_ast;
103pub mod model_parser;
104pub mod model_validator;
105pub mod policy_provider;
106pub mod resolver;
107pub mod tenant_schema;
108pub mod traits;
109pub mod type_system;
authz_core/lib.rs

authz_core/
lib.rs
