Enum AccessEvaluation 

#[non_exhaustive]
pub enum AccessEvaluation {
    Granted {
        policy_type: Cow<'static, str>,
        reason: Option<String>,
        trace: EvalTrace,
    },
    Denied {
        trace: EvalTrace,
        reason: String,
    },
}

The complete result of a permission evaluation. Contains both the final decision and a detailed trace for debugging.

Evaluation Tracing

The permission system provides detailed tracing of policy decisions:

let result = example().await;

match result {
    AccessEvaluation::Granted { policy_type, reason, trace } => {
        println!("Access granted by {}: {:?}", policy_type, reason);
        println!("Full evaluation trace:\n{}", trace.format());
    }
    AccessEvaluation::Denied { reason, trace } => {
        println!("Access denied: {}", reason);
        println!("Full evaluation trace:\n{}", trace.format());
    }
    _ => {
        println!("Access denied: unknown decision variant");
    }
}

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Granted

Access was granted.

Fields

policy_type: Cow<'static, str>

The policy that granted access. Cow<'static, str> for the same reason as on PolicyEvalResult: static names pass through with zero allocation.

reason: Option<String>

Optional reason for granting

trace: EvalTrace

Full evaluation trace including any rejected policies

Denied

Access was denied.

Fields

trace: EvalTrace

The complete evaluation trace showing all policy decisions

reason: String

Summary reason for denial

Implementations

impl AccessEvaluation

pub fn is_granted(&self) -> bool

Whether access was granted

Examples found in repository

examples/mfa_freshness_context.rs (line 250)

fn verdict(eval: &AccessEvaluation) -> &'static str {
    if eval.is_granted() {
        "GRANTED"
    } else {
        "DENIED"
    }
}

examples/axum.rs (line 401)

pub async fn view_invoice_handler(
    Path(invoice_id): Path<Uuid>,
    State(state): State<AppState>,
    AuthenticatedUser(user): AuthenticatedUser,
    overrides: InvoiceOverrides,
) -> impl IntoResponse {
    // Simulate a DB fetch.
    let invoice = overrides.build_invoice(invoice_id);
    let session = state.request_session();
    let context = RequestContext::now();

    if state
        .checker
        .bind(&session, &user, &Action::View, &context)
        .check(&invoice)
        .await
        .is_granted()
    {
        (StatusCode::OK, format!("{invoice:?}")).into_response()
    } else {
        (
            StatusCode::FORBIDDEN,
            "You are not authorized to view this invoice",
        )
            .into_response()
    }
}

pub async fn list_invoices_handler(
    State(state): State<AppState>,
    AuthenticatedUser(user): AuthenticatedUser,
) -> impl IntoResponse {
    let session = state.request_session();
    let candidates = state.invoices.as_ref().clone();
    let context = RequestContext::now();

    // The session is request-scoped: app state owns the source, this request
    // registers it, and the batch authorization call uses it for every invoice
    // — relationship loads are batched and deduplicated.
    let visible = state
        .checker
        .bind(&session, &user, &Action::View, &context)
        .filter(candidates)
        .await
        .into_iter()
        .map(InvoiceSummary::from)
        .collect::<Vec<_>>();

    Json(visible).into_response()
}

pub async fn edit_invoice_handler(
    Path(invoice_id): Path<Uuid>,
    State(state): State<AppState>,
    AuthenticatedUser(user): AuthenticatedUser,
    overrides: InvoiceOverrides,
) -> impl IntoResponse {
    let invoice = overrides.build_invoice(invoice_id);
    let session = state.request_session();
    let context = RequestContext::now();

    if state
        .checker
        .bind(&session, &user, &Action::Edit, &context)
        .check(&invoice)
        .await
        .is_granted()
    {
        (StatusCode::OK, "Invoice edited successfully").into_response()
    } else {
        (
            StatusCode::FORBIDDEN,
            "You are not authorized to edit this invoice",
        )
            .into_response()
    }
}

examples/delegating_policy.rs (line 185)

async fn main() {
    let owner_id = Uuid::new_v4();
    let author_id = Uuid::new_v4();

    let comment = Comment {
        author_id,
        document: Document { owner_id },
    };

    let author = Principal {
        user_id: author_id,
        is_admin: false,
    };
    let document_owner = Principal {
        user_id: owner_id,
        is_admin: false,
    };
    let admin = Principal {
        user_id: Uuid::new_v4(),
        is_admin: true,
    };
    let stranger = Principal {
        user_id: Uuid::new_v4(),
        is_admin: false,
    };

    let checker = comment_checker();
    let session = EvaluationSession::empty();
    let action = EditComment;
    let context = ();

    let cases = [
        ("author", &author),
        ("document owner (not author)", &document_owner),
        ("admin (not author/owner)", &admin),
        ("unrelated user", &stranger),
    ];
    for (who, principal) in cases {
        let granted = checker
            .bind(&session, principal, &action, &context)
            .check(&comment)
            .await
            .is_granted();
        println!(
            "{who:<28} can edit the comment? {}",
            if granted { "yes" } else { "no" }
        );
    }

    // The document owner is not the comment author, so the direct rule denies;
    // the delegating policy then asks the document checker, which grants. The
    // trace shows the decision crossing the domain boundary.
    println!("\nTrace — document owner (not the author) editing the comment:");
    let decision = checker
        .bind(&session, &document_owner, &action, &context)
        .check(&comment)
        .await;
    println!("{}", decision.display_trace());

    assert!(checker
        .bind(&session, &author, &action, &context)
        .check(&comment)
        .await
        .is_granted());
    assert!(checker
        .bind(&session, &document_owner, &action, &context)
        .check(&comment)
        .await
        .is_granted());
    assert!(checker
        .bind(&session, &admin, &action, &context)
        .check(&comment)
        .await
        .is_granted());
    assert!(!checker
        .bind(&session, &stranger, &action, &context)
        .check(&comment)
        .await
        .is_granted());
}

examples/rbac_policy.rs (line 115)

async fn main() {
    // The first resolver reads the requirement off the resource/action; the
    // second extracts the subject's roles. The role type (`Role`) is inferred
    // from the closures' return types.
    let rbac_policy = RbacPolicy::<DocumentDomain, _, _>::new(
        |_action: &ReadAction, doc: &Document| doc.required_roles.iter().copied().collect(),
        |user: &User| user.roles.iter().copied().collect(),
    );

    let mut checker = PermissionChecker::<DocumentDomain>::new();
    checker.add_policy(rbac_policy);

    let admin = user("admin", [Role::Admin]);
    let editor = user("editor", [Role::Editor]);
    let multi_role = user("editor+viewer", [Role::Editor, Role::Viewer]);
    let no_roles = user("no-roles", []);

    let admin_doc = document("admin handbook", [Role::Admin]);
    let editor_doc = document("style guide", [Role::Editor]);
    let shared_doc = document("team wiki", [Role::Editor, Role::Viewer]);

    // (user, document, expected outcome)
    let cases = [
        (&admin, &admin_doc, true),
        (&admin, &editor_doc, false), // admin role is not editor — no hierarchy here
        (&editor, &admin_doc, false),
        (&editor, &editor_doc, true),
        (&multi_role, &editor_doc, true),
        (&multi_role, &shared_doc, true),
        (&no_roles, &admin_doc, false),
        (&no_roles, &shared_doc, false),
    ];

    let session = EvaluationSession::empty();
    let action = ReadAction;
    let context = ();

    println!("{:<16} {:<16} verdict", "user", "document");
    println!("{}", "-".repeat(42));
    for (user, document, expected_granted) in cases {
        let decision = checker
            .bind(&session, user, &action, &context)
            .check(document)
            .await;
        println!(
            "{:<16} {:<16} {}",
            user.name,
            document.name,
            if decision.is_granted() {
                "GRANTED"
            } else {
                "DENIED"
            }
        );
        assert_eq!(decision.is_granted(), expected_granted);
    }

    // Note the admin/style-guide denial above: `RbacPolicy` is a flat
    // role-match with no built-in hierarchy. If admins should read
    // everything, either include `Role::Admin` in each document's required
    // set or add a separate admin-override policy to the checker.

    println!("\nWhy the editor is denied the admin handbook:");
    let decision = checker
        .bind(&session, &editor, &action, &context)
        .check(&admin_doc)
        .await;
    println!("{}", decision.display_trace());
}

examples/policy_builder.rs (line 140)

async fn main() {
    let mut checker = PermissionChecker::<AdminDomain>::new();
    checker.add_policy(scoped_permission_policy());
    checker.add_policy(global_admin_policy());

    let org1 = Organization { id: "org-1".into() };
    let org2 = Organization { id: "org-2".into() };

    let org1_admin = StaffUser {
        name: "org1-admin",
        permissions: vec![GroupPermission {
            scope: "edit_user_settings",
            entity: "org-1".into(),
        }],
    };
    let org2_admin = StaffUser {
        name: "org2-admin",
        permissions: vec![GroupPermission {
            scope: "edit_user_settings",
            entity: "org-2".into(),
        }],
    };
    let no_grants = StaffUser {
        name: "no-grants",
        permissions: vec![],
    };
    let global_admin = StaffUser {
        name: "global-admin",
        permissions: vec![GroupPermission {
            scope: "global_admin",
            entity: String::new(),
        }],
    };

    // (user, action, organization, expected outcome)
    let cases = [
        // Scoped grant matches its own org…
        (&org1_admin, AdminAction::EditUserSettings, &org1, true),
        // …but not another org, and not another scope on the same org.
        (&org2_admin, AdminAction::EditUserSettings, &org1, false),
        (&org1_admin, AdminAction::EditOrgSettings, &org1, false),
        (&org2_admin, AdminAction::EditUserSettings, &org2, true),
        (&no_grants, AdminAction::EditUserSettings, &org1, false),
        // The global admin passes via the subject-axis policy on any org.
        (&global_admin, AdminAction::EditOrgSettings, &org1, true),
    ];

    for (user, action, org, expected_granted) in cases {
        let session = EvaluationSession::empty();
        let decision = checker.bind(&session, user, &action, &()).check(org).await;
        println!(
            "{:<12} {:?} on {}: {}",
            user.name,
            action,
            org.id,
            if decision.is_granted() {
                "GRANTED"
            } else {
                "DENIED"
            }
        );
        assert_eq!(decision.is_granted(), expected_granted);
    }

    // The trace names the policy that decided; for a denial it shows every
    // policy that was consulted and why each said no.
    println!("\nWhy org2-admin cannot edit user settings on org-1:");
    let session = EvaluationSession::empty();
    let decision = checker
        .bind(&session, &org2_admin, &AdminAction::EditUserSettings, &())
        .check(&org1)
        .await;
    println!("{}", decision.display_trace());
}

examples/in_ram_rebac.rs (line 152)

async fn main() {
    let user = User { id: Uuid::new_v4() };
    let documents = vec![
        Document {
            id: Uuid::new_v4(),
            title: "roadmap",
        },
        Document {
            id: Uuid::new_v4(),
            title: "incident report",
        },
        Document {
            id: Uuid::new_v4(),
            title: "finance plan",
        },
    ];

    let store = Arc::new(InRamRelationships::default());
    store.grant(user.id, documents[0].id, Relation::Viewer);
    store.grant(user.id, documents[1].id, Relation::Viewer);
    // The store can hold more relation types than any one policy consumes. This
    // editor grant is never matched below (the checker only asks about Viewer),
    // and is here to show the source and the policy stack are decoupled.
    store.grant(user.id, documents[1].id, Relation::Editor);
    let relationships: Arc<dyn FactSource<RelationshipKey>> = store;
    let registry = FactRegistry::builder()
        .with_arc::<RelationshipKey>(Arc::clone(&relationships))
        .build();

    let checker = build_checker();
    let context = ();

    let first_request = request_session(&registry);
    let visible = checker
        .bind(&first_request, &user, &View, &context)
        .filter(documents.clone())
        .await;
    println!(
        "batch list — visible documents: {:?}",
        visible
            .iter()
            .map(|document| document.title)
            .collect::<Vec<_>>()
    );

    // A fresh session for a single-resource check. The user has no viewer
    // relationship on the finance plan, so this denies.
    let second_request = request_session(&registry);
    let can_view_finance = checker
        .bind(&second_request, &user, &View, &context)
        .check(&documents[2])
        .await;
    println!(
        "single check — can view '{}'? {}",
        documents[2].title,
        if can_view_finance.is_granted() {
            "yes"
        } else {
            "no"
        }
    );
    assert!(!can_view_finance.is_granted());

    let shared = registry.clone();
    let concurrent_requests = (0..4)
        .map(|_| {
            let checker = checker.clone();
            let user = user.clone();
            let documents = documents.clone();
            let registry = shared.clone();
            tokio::spawn(async move {
                let session = request_session(&registry);
                let context = ();
                checker
                    .bind(&session, &user, &View, &context)
                    .filter(documents)
                    .await
                    .len()
            })
        })
        .collect::<Vec<_>>();

    println!("\n4 concurrent requests sharing one FactSource (each builds its own session):");
    for (index, request) in concurrent_requests.into_iter().enumerate() {
        let visible_count = request.await.unwrap();
        println!("  request {index}: {visible_count} visible document(s)");
        assert_eq!(visible_count, 2);
    }
}

Additional examples can be found in:

• examples/deny_override.rs
• examples/rebac_policy.rs
• examples/combinator_policy.rs
• examples/lookup_in_ram.rs
• examples/postgres_bulk_rebac.rs

pub fn trace(&self) -> &EvalTrace

Returns the evaluation trace regardless of outcome.

Both variants carry an EvalTrace; this accessor saves callers the match when they only need the trace — typically to render it with EvalTrace::format for logs or debugging output.

Examples found in repository

examples/mfa_freshness_context.rs (line 246)

fn report(label: &str, eval: &AccessEvaluation) {
    println!("{label} → {}\n{}", verdict(eval), eval.trace().format());
}

examples/combinator_policy.rs (line 121)

async fn main() {
    let user = User::new();
    let document = Document::new();
    let action = ViewAction;
    let context = ();
    // These policies have no fact sources, so each evaluation binds
    // `EvaluationSession::empty()`. The checker contributes its own `OR` root
    // to the trace; the combinator's short-circuit behaviour (what this example
    // measures) happens inside it regardless.

    println!("=== AND Policy Short-Circuit Example ===");
    {
        let counter = Arc::new(AtomicUsize::new(0));

        // Create an AND policy with a non-grant policy first
        let and_policy = CountingPolicy {
            allow: false,
            name: "DenyFirst".to_string(),
            counter: counter.clone(),
        }
        .and(CountingPolicy {
            allow: true,
            name: "AllowSecond".to_string(),
            counter: counter.clone(),
        });

        let mut checker = PermissionChecker::<DocumentDomain>::new();
        checker.add_policy(and_policy);

        println!("Evaluating AND(DenyFirst, AllowSecond):");
        let session = EvaluationSession::empty();
        let result = checker
            .bind(&session, &user, &action, &context)
            .check(&document)
            .await;
        println!(
            "Result: {}",
            if result.is_granted() {
                "Access granted"
            } else {
                "Access denied"
            }
        );
        println!("Policies evaluated: {}", counter.load(Ordering::SeqCst));
        println!("Trace:\n{}", result.trace().format());

        // The second policy should not be evaluated due to short-circuiting
        assert_eq!(counter.load(Ordering::SeqCst), 1);
    }

    println!("\n=== OR Policy Short-Circuit Example ===");
    {
        let counter = Arc::new(AtomicUsize::new(0));

        // Create an OR policy with an allow policy first
        let or_policy = CountingPolicy {
            allow: true,
            name: "AllowFirst".to_string(),
            counter: counter.clone(),
        }
        .or(CountingPolicy {
            allow: false,
            name: "DenySecond".to_string(),
            counter: counter.clone(),
        });

        let mut checker = PermissionChecker::<DocumentDomain>::new();
        checker.add_policy(or_policy);

        println!("Evaluating OR(AllowFirst, DenySecond):");
        let session = EvaluationSession::empty();
        let result = checker
            .bind(&session, &user, &action, &context)
            .check(&document)
            .await;
        println!(
            "Result: {}",
            if result.is_granted() {
                "Access granted"
            } else {
                "Access denied"
            }
        );
        println!("Policies evaluated: {}", counter.load(Ordering::SeqCst));
        println!("Trace:\n{}", result.trace().format());

        // The second policy should not be evaluated due to short-circuiting
        assert_eq!(counter.load(Ordering::SeqCst), 1);
    }

    println!("\n=== Complex Nested Policy Example ===");
    {
        let counter = Arc::new(AtomicUsize::new(0));

        // Create a complex nested policy: OR(AND(Deny, Allow), Allow)
        let inner_and = CountingPolicy {
            allow: false,
            name: "DenyInner".to_string(),
            counter: counter.clone(),
        }
        .and(CountingPolicy {
            allow: true,
            name: "AllowInner".to_string(),
            counter: counter.clone(),
        });

        let complex_policy = inner_and.or(CountingPolicy {
            allow: true,
            name: "AllowOuter".to_string(),
            counter: counter.clone(),
        });

        let mut checker = PermissionChecker::<DocumentDomain>::new();
        checker.add_policy(complex_policy);

        println!("Evaluating OR(AND(DenyInner, AllowInner), AllowOuter):");
        let session = EvaluationSession::empty();
        let result = checker
            .bind(&session, &user, &action, &context)
            .check(&document)
            .await;
        println!(
            "Result: {} for document with ID {} for user with ID {}",
            if result.is_granted() {
                "Access granted"
            } else {
                "Access denied"
            },
            document.id,
            user.id
        );
        println!("Policies evaluated: {}", counter.load(Ordering::SeqCst));
        println!("Trace:\n{}", result.trace().format());

        // The inner AND should evaluate only DenyInner (shorts-circuit),
        // then the OR continues to AllowOuter which grants access
        assert_eq!(counter.load(Ordering::SeqCst), 2);
    }
}

pub fn granted_policy_type(&self) -> Option<&str>

Returns the granting policy’s name when the evaluation was a grant.

Useful for non-panicking inspection in tests and in production code that branches on which policy made the decision.

pub fn denied_reason(&self) -> Option<&str>

Returns the summary denial reason when the evaluation was a denial.

Mirrors Self::granted_policy_type for the denied case.

pub fn forbidden_by(&self) -> Option<&str>

Returns the name of the policy whose forbid caused this denial, if the denial was a deny-overrides veto rather than a plain “no policy granted” outcome.

Useful for distinguishing “actively blocked” (suspension, legal hold) from “no grant matched” — for example to map the former to a distinct HTTP status or audit event. Returns None for grants and for ordinary denials.

Examples found in repository

examples/deny_override.rs (line 178)

async fn main() {
    let owner_id = Uuid::new_v4();
    let admin = User {
        id: Uuid::new_v4(),
        is_admin: true,
        suspended: false,
    };
    let suspended_owner = User {
        id: owner_id,
        is_admin: false,
        suspended: true,
    };
    let owner = User {
        id: owner_id,
        is_admin: false,
        suspended: false,
    };
    let stranger = User {
        id: Uuid::new_v4(),
        is_admin: false,
        suspended: false,
    };

    let normal_doc = Document {
        owner_id,
        legal_hold: false,
    };
    let held_doc = Document {
        owner_id,
        legal_hold: true,
    };

    let checker = document_checker();
    let session = EvaluationSession::empty();
    let action = Access;
    let context = ();

    // (subject, resource, label)
    let cases = [
        (&admin, &normal_doc, "admin, normal doc"),
        (&owner, &normal_doc, "owner, own normal doc"),
        (&admin, &held_doc, "admin, LEGAL-HOLD doc"),
        (&suspended_owner, &normal_doc, "SUSPENDED owner, own doc"),
        (&stranger, &normal_doc, "stranger, someone else's doc"),
    ];

    println!("{:<32} {:>10} forbidden by", "case", "decision");
    println!("{}", "-".repeat(60));
    for (subject, document, label) in cases {
        let decision = checker
            .bind(&session, subject, &action, &context)
            .check(document)
            .await;
        println!(
            "{label:<32} {:>10} {}",
            verdict(decision.is_granted()),
            decision.forbidden_by().unwrap_or("-"),
        );
    }

    // The grants still work where nothing blocks them.
    checker
        .bind(&session, &admin, &action, &context)
        .check(&normal_doc)
        .await
        .assert_granted_by("AdminOverride");
    checker
        .bind(&session, &owner, &action, &context)
        .check(&normal_doc)
        .await
        .assert_granted_by("DocumentOwner");

    // The block rules override every grant — even the admin override.
    checker
        .bind(&session, &admin, &action, &context)
        .check(&held_doc)
        .await
        .assert_forbidden_by("LegalHold");
    checker
        .bind(&session, &suspended_owner, &action, &context)
        .check(&normal_doc)
        .await
        .assert_forbidden_by("AccountSuspended");

    // Default deny is untouched: no grant, no access — and no forbid
    // either, which `forbidden_by()` distinguishes for the caller.
    let stranger_decision = checker
        .bind(&session, &stranger, &action, &context)
        .check(&normal_doc)
        .await;
    stranger_decision.assert_denied();
    assert_eq!(stranger_decision.forbidden_by(), None);

    // Show the mechanism on the headline case: the forbid-effect policy is
    // evaluated first and ends the evaluation; the allow set is never
    // consulted.
    println!("\nWhy 'admin, LEGAL-HOLD doc' is blocked:");
    let decision = checker
        .bind(&session, &admin, &action, &context)
        .check(&held_doc)
        .await;
    println!("{}", decision.display_trace());

    scoped_exclusion_demo().await;
}

pub fn assert_granted_by(&self, expected: &str)

Test helper: panic unless the evaluation is Granted and the granting policy’s name matches expected.

Intended for policy unit tests that would otherwise hand-roll a pattern match over the evaluation. Prefer this over destructuring when the test’s only assertion is “policy X granted access.”

evaluation.assert_granted_by("AllowAll");

Examples found in repository

examples/mfa_freshness_context.rs (line 199)

async fn main() {
    let alice = User {
        id: Uuid::new_v4(),
        roles: vec!["finance".into()],
    };
    let small_refund = RefundRequest {
        id: Uuid::new_v4(),
        amount_cents: 5_000, // $50
    };
    let large_refund = RefundRequest {
        id: Uuid::new_v4(),
        amount_cents: 5_000_000, // $50,000
    };

    let now = SystemTime::now();
    let checker = build_checker();
    let session = EvaluationSession::empty();

    // Case 1: small refund, no MFA at all. Granted — the high-value
    // rule doesn't apply below the threshold, so the role grant decides.
    let small_no_mfa = ApprovalContext {
        current_time: now,
        mfa_verified_at: None,
    };
    let r = checker
        .bind(&session, &alice, &Approve, &small_no_mfa)
        .check(&small_refund)
        .await;
    report("small refund, no MFA", &r);
    r.assert_granted_by("FinanceCanApproveRefunds");

    // Case 2: large refund, no MFA. Forbidden by the freshness rule —
    // the veto overrides Alice's role grant.
    let r = checker
        .bind(&session, &alice, &Approve, &small_no_mfa)
        .check(&large_refund)
        .await;
    report("large refund, no MFA", &r);
    r.assert_forbidden_by("HighValueRequiresFreshMfa");

    // Case 3: large refund, MFA reasserted 8 minutes ago. Stale → forbidden.
    let stale = ApprovalContext {
        current_time: now,
        mfa_verified_at: Some(now - Duration::from_secs(8 * 60)),
    };
    let r = checker
        .bind(&session, &alice, &Approve, &stale)
        .check(&large_refund)
        .await;
    report("large refund, MFA 8m old", &r);
    r.assert_forbidden_by("HighValueRequiresFreshMfa");

    // Case 4: large refund, MFA reasserted 30 seconds ago. The deny rule
    // is not applicable, so the role grant decides.
    let fresh = ApprovalContext {
        current_time: now,
        mfa_verified_at: Some(now - Duration::from_secs(30)),
    };
    let r = checker
        .bind(&session, &alice, &Approve, &fresh)
        .check(&large_refund)
        .await;
    report("large refund, MFA 30s old", &r);
    r.assert_granted_by("FinanceCanApproveRefunds");

    // The point: cases 2-4 all use the same subject and resource. The
    // only thing that varies is `ApprovalContext`. That's exactly the
    // signal that the rule belongs in `Context`, not on User or
    // RefundRequest.
}

examples/deny_override.rs (line 187)

async fn main() {
    let owner_id = Uuid::new_v4();
    let admin = User {
        id: Uuid::new_v4(),
        is_admin: true,
        suspended: false,
    };
    let suspended_owner = User {
        id: owner_id,
        is_admin: false,
        suspended: true,
    };
    let owner = User {
        id: owner_id,
        is_admin: false,
        suspended: false,
    };
    let stranger = User {
        id: Uuid::new_v4(),
        is_admin: false,
        suspended: false,
    };

    let normal_doc = Document {
        owner_id,
        legal_hold: false,
    };
    let held_doc = Document {
        owner_id,
        legal_hold: true,
    };

    let checker = document_checker();
    let session = EvaluationSession::empty();
    let action = Access;
    let context = ();

    // (subject, resource, label)
    let cases = [
        (&admin, &normal_doc, "admin, normal doc"),
        (&owner, &normal_doc, "owner, own normal doc"),
        (&admin, &held_doc, "admin, LEGAL-HOLD doc"),
        (&suspended_owner, &normal_doc, "SUSPENDED owner, own doc"),
        (&stranger, &normal_doc, "stranger, someone else's doc"),
    ];

    println!("{:<32} {:>10} forbidden by", "case", "decision");
    println!("{}", "-".repeat(60));
    for (subject, document, label) in cases {
        let decision = checker
            .bind(&session, subject, &action, &context)
            .check(document)
            .await;
        println!(
            "{label:<32} {:>10} {}",
            verdict(decision.is_granted()),
            decision.forbidden_by().unwrap_or("-"),
        );
    }

    // The grants still work where nothing blocks them.
    checker
        .bind(&session, &admin, &action, &context)
        .check(&normal_doc)
        .await
        .assert_granted_by("AdminOverride");
    checker
        .bind(&session, &owner, &action, &context)
        .check(&normal_doc)
        .await
        .assert_granted_by("DocumentOwner");

    // The block rules override every grant — even the admin override.
    checker
        .bind(&session, &admin, &action, &context)
        .check(&held_doc)
        .await
        .assert_forbidden_by("LegalHold");
    checker
        .bind(&session, &suspended_owner, &action, &context)
        .check(&normal_doc)
        .await
        .assert_forbidden_by("AccountSuspended");

    // Default deny is untouched: no grant, no access — and no forbid
    // either, which `forbidden_by()` distinguishes for the caller.
    let stranger_decision = checker
        .bind(&session, &stranger, &action, &context)
        .check(&normal_doc)
        .await;
    stranger_decision.assert_denied();
    assert_eq!(stranger_decision.forbidden_by(), None);

    // Show the mechanism on the headline case: the forbid-effect policy is
    // evaluated first and ends the evaluation; the allow set is never
    // consulted.
    println!("\nWhy 'admin, LEGAL-HOLD doc' is blocked:");
    let decision = checker
        .bind(&session, &admin, &action, &context)
        .check(&held_doc)
        .await;
    println!("{}", decision.display_trace());

    scoped_exclusion_demo().await;
}

// ---- scoped exclusion: a deny that gates only one grant path --------

/// `Effect::Forbid` is a *global* veto: it blocks every grant path in the
/// checker. When a block rule should only gate one grant path — here,
/// muted users lose collaborator access but owners and admins keep
/// theirs — scope it with combinators instead:
/// `AndPolicy[ grant_arm, NotPolicy(block) ]`. The block policy in this local
/// shape should be an ordinary grant-style predicate, not `.forbid()`;
/// `Forbidden` is active and would still veto globally.
async fn scoped_exclusion_demo() {
    #[derive(Debug, Clone)]
    struct Member {
        is_owner: bool,
        is_collaborator: bool,
        muted: bool,
    }
    #[derive(Debug, Clone)]
    struct Thread;

    struct ThreadDomain;

    impl PolicyDomain for ThreadDomain {
        type Subject = Member;
        type Action = Access;
        type Resource = Thread;
        type Context = ();
    }

    let owner_policy = PolicyBuilder::<ThreadDomain>::new("ThreadOwner")
        .subjects(|member| member.is_owner)
        .build();
    let collaborator_policy: Arc<dyn Policy<ThreadDomain>> = Arc::from(
        PolicyBuilder::<ThreadDomain>::new("Collaborator")
            .subjects(|member| member.is_collaborator)
            .build(),
    );
    // The block rule for the scoped case *grants when it matches* so that
    // `NotPolicy` can invert it into a local gate. Compare with the
    // checker-level rules above, where `Effect::Forbid` keeps natural
    // polarity — this inversion is the price of scoping, which is why a
    // global block should prefer `Effect::Forbid`.
    let muted = PolicyBuilder::<ThreadDomain>::new("Muted")
        .subjects(|member| member.muted)
        .build();

    let collaborator_unless_muted = AndPolicy::try_new(vec![
        collaborator_policy,
        Arc::new(NotPolicy::new(muted)) as Arc<dyn Policy<ThreadDomain>>,
    ])
    .expect("gate has the grant arm and the guard");

    let mut checker = PermissionChecker::<ThreadDomain>::named("ThreadChecker");
    checker.add_policy(owner_policy);
    checker.add_policy(collaborator_unless_muted);

    let muted_collaborator = Member {
        is_owner: false,
        is_collaborator: true,
        muted: true,
    };
    let muted_owner = Member {
        is_owner: true,
        is_collaborator: false,
        muted: true,
    };

    let session = EvaluationSession::empty();
    let action = Access;
    let context = ();

    // The mute only gates the collaborator path...
    checker
        .bind(&session, &muted_collaborator, &action, &context)
        .check(&Thread)
        .await
        .assert_denied();
    // ...the owner path is untouched, which a global Effect::Forbid mute
    // could not express.
    checker
        .bind(&session, &muted_owner, &action, &context)
        .check(&Thread)
        .await
        .assert_granted_by("ThreadOwner");

    println!("\nScoped exclusion: muted collaborator blocked, muted owner unaffected.");
}

examples/lookup_in_ram.rs (line 309)

async fn main() {
    // Build a small population.
    let alice = User {
        id: Uuid::new_v4(),
        is_admin: false,
    };
    let admin = User {
        id: Uuid::new_v4(),
        is_admin: true,
    };
    let docs: Vec<Document> = (0..7)
        .map(|i| Document {
            id: Uuid::new_v4(),
            title: format!("doc-{i}"),
        })
        .collect();

    // Alice is a viewer of docs[1], docs[3], docs[5].
    let viewer_doc_ids: Vec<Uuid> = [&docs[1], &docs[3], &docs[5]]
        .into_iter()
        .map(|d| d.id)
        .collect();

    let viewers: HashMap<Uuid, Vec<Uuid>> = viewer_doc_ids
        .iter()
        .map(|doc_id| (*doc_id, vec![alice.id]))
        .collect();

    let viewer_lookup_index: HashMap<Uuid, Vec<Uuid>> =
        HashMap::from([(alice.id, viewer_doc_ids.clone())]);

    // Document catalog used by the hydrator. In production this is a
    // database call: `SELECT * FROM docs WHERE id = ANY($1)`.
    let catalog: Arc<HashMap<Uuid, Document>> =
        Arc::new(docs.iter().map(|d| (d.id, d.clone())).collect());

    let lookup = InMemoryViewerLookup {
        per_user: viewer_lookup_index,
    };

    // Hydrator closure: maps a slice of ids to `Vec<Option<Document>>`.
    // `None` would represent an id deleted between enumeration and the
    // catalog fetch; the in-memory catalog here always resolves.
    let hydrator = {
        let catalog = Arc::clone(&catalog);
        move |ids: &[Uuid]| {
            let catalog = Arc::clone(&catalog);
            let ids = ids.to_vec();
            async move {
                Ok::<_, std::convert::Infallible>(
                    ids.iter().map(|id| catalog.get(id).cloned()).collect(),
                )
            }
        }
    };

    // Compose policies: admin override OR viewer relation. The lookup
    // source only enumerates the viewer axis — admin overrides apply only
    // to point checks.
    let mut checker = PermissionChecker::<DocumentDomain>::new();
    checker.add_policy(AdminPolicy);
    checker.add_policy(ViewerPolicy { viewers });

    let session = EvaluationSession::empty();
    let page_size = NonZeroUsize::new(2).unwrap();

    // (1) Alice lists her visible documents by collecting lookup pages.
    let alice_visible =
        collect_authorized(&checker, &session, &alice, &lookup, page_size, &hydrator)
            .await
            .expect("lookup ok");
    println!("Alice sees {} document(s):", alice_visible.len());
    for doc in &alice_visible {
        println!("  - {} ({})", doc.title, doc.id);
    }
    let alice_visible_ids: Vec<Uuid> = alice_visible.iter().map(|doc| doc.id).collect();
    assert_eq!(
        alice_visible_ids, viewer_doc_ids,
        "the lookup + policy stack should authorize exactly the viewer-granted documents, in source order"
    );

    // (2) Admin lists "their visible documents" via the same lookup.
    // The viewer lookup does not enumerate documents for the admin (no
    // viewer relation), so this listing returns empty — correctly,
    // because lookup is bounded by what it enumerates. To enumerate
    // "everything an admin can see", the production code would either
    // route admin requests to a different source or simply skip the
    // lookup path and list directly.
    let admin_via_lookup =
        collect_authorized(&checker, &session, &admin, &lookup, page_size, &hydrator)
            .await
            .expect("lookup ok");
    println!(
        "\nAdmin via the viewer-lookup sees {} document(s) — this is bounded \
         by what the source enumerates; admin grants still apply at point checks.",
        admin_via_lookup.len()
    );
    assert!(
        admin_via_lookup.is_empty(),
        "the viewer lookup enumerates nothing for the admin, so the listing is empty"
    );

    // (3) Point check confirms the admin policy is alive: pick a document
    // the admin has no viewer relation on.
    let any_doc = &docs[0];
    let admin_point = checker
        .bind(&session, &admin, &View, &())
        .check(any_doc)
        .await;
    println!(
        "\nAdmin point check on '{}': {}",
        any_doc.title,
        if admin_point.is_granted() {
            "Granted"
        } else {
            "Denied"
        }
    );
    admin_point.assert_granted_by("AdminPolicy");

    // (4) Page-oriented streaming. Drive the lookup one candidate page at
    // a time — useful when you want to flush results to a response writer
    // as they are confirmed.
    println!("\nStreaming Alice's visible documents page-by-page:");
    let mut cursor: Option<Vec<u8>> = None;
    let mut page_index = 0;
    let mut streamed_total = 0;
    let alice_bound = checker.bind(&session, &alice, &View, &());
    loop {
        let page = alice_bound
            .lookup_page(&lookup, &hydrator, cursor.as_deref(), page_size)
            .await
            .expect("lookup_page ok");
        println!("  page {page_index}: {} authorized", page.resources.len());
        page_index += 1;
        streamed_total += page.resources.len();
        match page.next_cursor {
            None => break,
            Some(next) => cursor = Some(next),
        }
    }
    // 3 candidate ids paged 2-at-a-time: two candidate pages, same total as
    // the helper loop above.
    assert_eq!(page_index, 2);
    assert_eq!(streamed_total, viewer_doc_ids.len());
}

pub fn assert_denied(&self)

Test helper: panic unless the evaluation is Denied.

Use Self::assert_denied_with_reason_containing when you also need to assert on the denial reason.

Examples found in repository

examples/deny_override.rs (line 212)

async fn main() {
    let owner_id = Uuid::new_v4();
    let admin = User {
        id: Uuid::new_v4(),
        is_admin: true,
        suspended: false,
    };
    let suspended_owner = User {
        id: owner_id,
        is_admin: false,
        suspended: true,
    };
    let owner = User {
        id: owner_id,
        is_admin: false,
        suspended: false,
    };
    let stranger = User {
        id: Uuid::new_v4(),
        is_admin: false,
        suspended: false,
    };

    let normal_doc = Document {
        owner_id,
        legal_hold: false,
    };
    let held_doc = Document {
        owner_id,
        legal_hold: true,
    };

    let checker = document_checker();
    let session = EvaluationSession::empty();
    let action = Access;
    let context = ();

    // (subject, resource, label)
    let cases = [
        (&admin, &normal_doc, "admin, normal doc"),
        (&owner, &normal_doc, "owner, own normal doc"),
        (&admin, &held_doc, "admin, LEGAL-HOLD doc"),
        (&suspended_owner, &normal_doc, "SUSPENDED owner, own doc"),
        (&stranger, &normal_doc, "stranger, someone else's doc"),
    ];

    println!("{:<32} {:>10} forbidden by", "case", "decision");
    println!("{}", "-".repeat(60));
    for (subject, document, label) in cases {
        let decision = checker
            .bind(&session, subject, &action, &context)
            .check(document)
            .await;
        println!(
            "{label:<32} {:>10} {}",
            verdict(decision.is_granted()),
            decision.forbidden_by().unwrap_or("-"),
        );
    }

    // The grants still work where nothing blocks them.
    checker
        .bind(&session, &admin, &action, &context)
        .check(&normal_doc)
        .await
        .assert_granted_by("AdminOverride");
    checker
        .bind(&session, &owner, &action, &context)
        .check(&normal_doc)
        .await
        .assert_granted_by("DocumentOwner");

    // The block rules override every grant — even the admin override.
    checker
        .bind(&session, &admin, &action, &context)
        .check(&held_doc)
        .await
        .assert_forbidden_by("LegalHold");
    checker
        .bind(&session, &suspended_owner, &action, &context)
        .check(&normal_doc)
        .await
        .assert_forbidden_by("AccountSuspended");

    // Default deny is untouched: no grant, no access — and no forbid
    // either, which `forbidden_by()` distinguishes for the caller.
    let stranger_decision = checker
        .bind(&session, &stranger, &action, &context)
        .check(&normal_doc)
        .await;
    stranger_decision.assert_denied();
    assert_eq!(stranger_decision.forbidden_by(), None);

    // Show the mechanism on the headline case: the forbid-effect policy is
    // evaluated first and ends the evaluation; the allow set is never
    // consulted.
    println!("\nWhy 'admin, LEGAL-HOLD doc' is blocked:");
    let decision = checker
        .bind(&session, &admin, &action, &context)
        .check(&held_doc)
        .await;
    println!("{}", decision.display_trace());

    scoped_exclusion_demo().await;
}

// ---- scoped exclusion: a deny that gates only one grant path --------

/// `Effect::Forbid` is a *global* veto: it blocks every grant path in the
/// checker. When a block rule should only gate one grant path — here,
/// muted users lose collaborator access but owners and admins keep
/// theirs — scope it with combinators instead:
/// `AndPolicy[ grant_arm, NotPolicy(block) ]`. The block policy in this local
/// shape should be an ordinary grant-style predicate, not `.forbid()`;
/// `Forbidden` is active and would still veto globally.
async fn scoped_exclusion_demo() {
    #[derive(Debug, Clone)]
    struct Member {
        is_owner: bool,
        is_collaborator: bool,
        muted: bool,
    }
    #[derive(Debug, Clone)]
    struct Thread;

    struct ThreadDomain;

    impl PolicyDomain for ThreadDomain {
        type Subject = Member;
        type Action = Access;
        type Resource = Thread;
        type Context = ();
    }

    let owner_policy = PolicyBuilder::<ThreadDomain>::new("ThreadOwner")
        .subjects(|member| member.is_owner)
        .build();
    let collaborator_policy: Arc<dyn Policy<ThreadDomain>> = Arc::from(
        PolicyBuilder::<ThreadDomain>::new("Collaborator")
            .subjects(|member| member.is_collaborator)
            .build(),
    );
    // The block rule for the scoped case *grants when it matches* so that
    // `NotPolicy` can invert it into a local gate. Compare with the
    // checker-level rules above, where `Effect::Forbid` keeps natural
    // polarity — this inversion is the price of scoping, which is why a
    // global block should prefer `Effect::Forbid`.
    let muted = PolicyBuilder::<ThreadDomain>::new("Muted")
        .subjects(|member| member.muted)
        .build();

    let collaborator_unless_muted = AndPolicy::try_new(vec![
        collaborator_policy,
        Arc::new(NotPolicy::new(muted)) as Arc<dyn Policy<ThreadDomain>>,
    ])
    .expect("gate has the grant arm and the guard");

    let mut checker = PermissionChecker::<ThreadDomain>::named("ThreadChecker");
    checker.add_policy(owner_policy);
    checker.add_policy(collaborator_unless_muted);

    let muted_collaborator = Member {
        is_owner: false,
        is_collaborator: true,
        muted: true,
    };
    let muted_owner = Member {
        is_owner: true,
        is_collaborator: false,
        muted: true,
    };

    let session = EvaluationSession::empty();
    let action = Access;
    let context = ();

    // The mute only gates the collaborator path...
    checker
        .bind(&session, &muted_collaborator, &action, &context)
        .check(&Thread)
        .await
        .assert_denied();
    // ...the owner path is untouched, which a global Effect::Forbid mute
    // could not express.
    checker
        .bind(&session, &muted_owner, &action, &context)
        .check(&Thread)
        .await
        .assert_granted_by("ThreadOwner");

    println!("\nScoped exclusion: muted collaborator blocked, muted owner unaffected.");
}

examples/rebac_policy.rs (line 224)

async fn main() {
    println!("=== ReBAC Policy Example ===\n");

    let owner = User {
        id: Uuid::new_v4(),
        name: "Alice",
    };
    let contributor = User {
        id: Uuid::new_v4(),
        name: "Bob",
    };
    let viewer = User {
        id: Uuid::new_v4(),
        name: "Charlie",
    };
    let outsider = User {
        id: Uuid::new_v4(),
        name: "Dave",
    };
    let project = Project {
        id: Uuid::new_v4(),
        name: "Sample Project",
    };

    let relationships = HashSet::from([
        ProjectRelationship {
            subject_id: owner.id,
            resource_id: project.id,
            relation: Relation::Owner,
        },
        ProjectRelationship {
            subject_id: contributor.id,
            resource_id: project.id,
            relation: Relation::Contributor,
        },
        ProjectRelationship {
            subject_id: viewer.id,
            resource_id: project.id,
            relation: Relation::Viewer,
        },
    ]);

    let registry = FactRegistry::builder()
        .with::<ProjectRelationship, _>(ProjectRelationshipSource::new(relationships.clone()))
        .build();
    let session = registry.session();

    // Editing requires an owner OR contributor relationship; a viewer
    // relationship exists in the store but grants nothing here.
    let mut checker = PermissionChecker::<ProjectDomain>::new();
    checker.add_policy(RebacPolicy::<ProjectDomain, Uuid, Uuid, Relation>::new(
        |user: &User| user.id,
        |project: &Project| project.id,
        Relation::Owner,
    ));
    checker.add_policy(RebacPolicy::<ProjectDomain, Uuid, Uuid, Relation>::new(
        |user: &User| user.id,
        |project: &Project| project.id,
        Relation::Contributor,
    ));

    // (user, relationship held, expected outcome)
    let cases = [
        (&owner, "owner", true),
        (&contributor, "contributor", true),
        (&viewer, "viewer", false),
        (&outsider, "none", false),
    ];
    for (user, held, expected_granted) in cases {
        println!("Can {} ({held}) edit {}?", user.name, project.name);
        let decision = checker
            .bind(&session, user, &EditAction, &())
            .check(&project)
            .await;
        println!(
            "  -> {}\n",
            if decision.is_granted() {
                "GRANTED"
            } else {
                "DENIED"
            }
        );
        assert_eq!(decision.is_granted(), expected_granted);
    }

    // The trace records the facts each policy consulted (the `↳ fact` lines)
    // alongside its decision — here the viewer's denial shows both
    // relationship lookups coming back false. Note that no new "loading fact"
    // lines appear: this re-check runs in the same session, so the facts come
    // from the session cache.
    println!("Why {} is denied:", viewer.name);
    let decision = checker
        .bind(&session, &viewer, &EditAction, &())
        .check(&project)
        .await;
    println!("{}\n", decision.display_trace());

    println!("=== Error During Relationship Loading ===\n");

    // A failing store must never grant: the load error is carried into the
    // trace and the decision fails closed to denial — even for the owner.
    let error_registry = FactRegistry::builder()
        .with::<ProjectRelationship, _>(ProjectRelationshipSource::new(relationships).with_error())
        .build();
    let error_session = error_registry.session();
    let decision = checker
        .bind(&error_session, &owner, &EditAction, &())
        .check(&project)
        .await;
    println!("{}", decision.display_trace());
    decision.assert_denied();
    decision.assert_trace_contains("simulated relationship store error");
}

pub fn assert_denied_with_reason_containing(&self, needle: &str)

Test helper: panic unless the evaluation is Denied and the top-level summary denial reason contains needle.

needle is matched against the single string on AccessEvaluation::Denied — a summary like "All policies denied access", not the per-policy reasons inside the trace tree. For a multi-policy checker, asserting on a specific policy’s reason needs Self::assert_trace_contains or Self::assert_not_applicable_by.

Substring match keeps tests resilient to minor reason-string rewording. For exact-match assertions, inspect Self::denied_reason directly.

pub fn assert_not_applicable_by(&self, expected: &str)

Test helper: panic unless the evaluation is Denied and some NotApplicable leaf in the trace tree was produced by a policy whose name matches expected.

Symmetric with Self::assert_granted_by but walks the trace rather than checking the top-level decision, because an ordinary final denial has no single denying policy: every policy in the checker declined to grant. Use this to assert that policy expected actually fired and was not applicable. Use Self::assert_forbidden_by for active vetoes.

evaluation.assert_not_applicable_by("StaffOnly");

pub fn assert_forbidden_by(&self, expected: &str)

Test helper: panic unless the evaluation is Denied because of a forbid by the policy named expected.

Stronger than Self::assert_not_applicable_by: this asserts the denial was a deny-overrides veto attributed to expected (via Self::forbidden_by), not merely that expected appears as a not-applicable leaf somewhere in the trace.

evaluation.assert_forbidden_by("GlobalFreeze");

Examples found in repository

examples/mfa_freshness_context.rs (line 208)

async fn main() {
    let alice = User {
        id: Uuid::new_v4(),
        roles: vec!["finance".into()],
    };
    let small_refund = RefundRequest {
        id: Uuid::new_v4(),
        amount_cents: 5_000, // $50
    };
    let large_refund = RefundRequest {
        id: Uuid::new_v4(),
        amount_cents: 5_000_000, // $50,000
    };

    let now = SystemTime::now();
    let checker = build_checker();
    let session = EvaluationSession::empty();

    // Case 1: small refund, no MFA at all. Granted — the high-value
    // rule doesn't apply below the threshold, so the role grant decides.
    let small_no_mfa = ApprovalContext {
        current_time: now,
        mfa_verified_at: None,
    };
    let r = checker
        .bind(&session, &alice, &Approve, &small_no_mfa)
        .check(&small_refund)
        .await;
    report("small refund, no MFA", &r);
    r.assert_granted_by("FinanceCanApproveRefunds");

    // Case 2: large refund, no MFA. Forbidden by the freshness rule —
    // the veto overrides Alice's role grant.
    let r = checker
        .bind(&session, &alice, &Approve, &small_no_mfa)
        .check(&large_refund)
        .await;
    report("large refund, no MFA", &r);
    r.assert_forbidden_by("HighValueRequiresFreshMfa");

    // Case 3: large refund, MFA reasserted 8 minutes ago. Stale → forbidden.
    let stale = ApprovalContext {
        current_time: now,
        mfa_verified_at: Some(now - Duration::from_secs(8 * 60)),
    };
    let r = checker
        .bind(&session, &alice, &Approve, &stale)
        .check(&large_refund)
        .await;
    report("large refund, MFA 8m old", &r);
    r.assert_forbidden_by("HighValueRequiresFreshMfa");

    // Case 4: large refund, MFA reasserted 30 seconds ago. The deny rule
    // is not applicable, so the role grant decides.
    let fresh = ApprovalContext {
        current_time: now,
        mfa_verified_at: Some(now - Duration::from_secs(30)),
    };
    let r = checker
        .bind(&session, &alice, &Approve, &fresh)
        .check(&large_refund)
        .await;
    report("large refund, MFA 30s old", &r);
    r.assert_granted_by("FinanceCanApproveRefunds");

    // The point: cases 2-4 all use the same subject and resource. The
    // only thing that varies is `ApprovalContext`. That's exactly the
    // signal that the rule belongs in `Context`, not on User or
    // RefundRequest.
}

examples/deny_override.rs (line 199)

async fn main() {
    let owner_id = Uuid::new_v4();
    let admin = User {
        id: Uuid::new_v4(),
        is_admin: true,
        suspended: false,
    };
    let suspended_owner = User {
        id: owner_id,
        is_admin: false,
        suspended: true,
    };
    let owner = User {
        id: owner_id,
        is_admin: false,
        suspended: false,
    };
    let stranger = User {
        id: Uuid::new_v4(),
        is_admin: false,
        suspended: false,
    };

    let normal_doc = Document {
        owner_id,
        legal_hold: false,
    };
    let held_doc = Document {
        owner_id,
        legal_hold: true,
    };

    let checker = document_checker();
    let session = EvaluationSession::empty();
    let action = Access;
    let context = ();

    // (subject, resource, label)
    let cases = [
        (&admin, &normal_doc, "admin, normal doc"),
        (&owner, &normal_doc, "owner, own normal doc"),
        (&admin, &held_doc, "admin, LEGAL-HOLD doc"),
        (&suspended_owner, &normal_doc, "SUSPENDED owner, own doc"),
        (&stranger, &normal_doc, "stranger, someone else's doc"),
    ];

    println!("{:<32} {:>10} forbidden by", "case", "decision");
    println!("{}", "-".repeat(60));
    for (subject, document, label) in cases {
        let decision = checker
            .bind(&session, subject, &action, &context)
            .check(document)
            .await;
        println!(
            "{label:<32} {:>10} {}",
            verdict(decision.is_granted()),
            decision.forbidden_by().unwrap_or("-"),
        );
    }

    // The grants still work where nothing blocks them.
    checker
        .bind(&session, &admin, &action, &context)
        .check(&normal_doc)
        .await
        .assert_granted_by("AdminOverride");
    checker
        .bind(&session, &owner, &action, &context)
        .check(&normal_doc)
        .await
        .assert_granted_by("DocumentOwner");

    // The block rules override every grant — even the admin override.
    checker
        .bind(&session, &admin, &action, &context)
        .check(&held_doc)
        .await
        .assert_forbidden_by("LegalHold");
    checker
        .bind(&session, &suspended_owner, &action, &context)
        .check(&normal_doc)
        .await
        .assert_forbidden_by("AccountSuspended");

    // Default deny is untouched: no grant, no access — and no forbid
    // either, which `forbidden_by()` distinguishes for the caller.
    let stranger_decision = checker
        .bind(&session, &stranger, &action, &context)
        .check(&normal_doc)
        .await;
    stranger_decision.assert_denied();
    assert_eq!(stranger_decision.forbidden_by(), None);

    // Show the mechanism on the headline case: the forbid-effect policy is
    // evaluated first and ends the evaluation; the allow set is never
    // consulted.
    println!("\nWhy 'admin, LEGAL-HOLD doc' is blocked:");
    let decision = checker
        .bind(&session, &admin, &action, &context)
        .check(&held_doc)
        .await;
    println!("{}", decision.display_trace());

    scoped_exclusion_demo().await;
}

pub fn assert_trace_contains(&self, needle: &str)

Test helper: panic unless needle appears anywhere in the formatted evaluation trace.

Substring match against the string produced by Self::display_trace, which includes every per-policy reason (granted and denied) the checker actually evaluated. Use this when the assertion is “some policy in the trace produced this specific reason” — the per-policy reasons live in the trace, not on the top-level summary that Self::assert_denied_with_reason_containing inspects.

Examples found in repository

examples/rebac_policy.rs (line 225)

async fn main() {
    println!("=== ReBAC Policy Example ===\n");

    let owner = User {
        id: Uuid::new_v4(),
        name: "Alice",
    };
    let contributor = User {
        id: Uuid::new_v4(),
        name: "Bob",
    };
    let viewer = User {
        id: Uuid::new_v4(),
        name: "Charlie",
    };
    let outsider = User {
        id: Uuid::new_v4(),
        name: "Dave",
    };
    let project = Project {
        id: Uuid::new_v4(),
        name: "Sample Project",
    };

    let relationships = HashSet::from([
        ProjectRelationship {
            subject_id: owner.id,
            resource_id: project.id,
            relation: Relation::Owner,
        },
        ProjectRelationship {
            subject_id: contributor.id,
            resource_id: project.id,
            relation: Relation::Contributor,
        },
        ProjectRelationship {
            subject_id: viewer.id,
            resource_id: project.id,
            relation: Relation::Viewer,
        },
    ]);

    let registry = FactRegistry::builder()
        .with::<ProjectRelationship, _>(ProjectRelationshipSource::new(relationships.clone()))
        .build();
    let session = registry.session();

    // Editing requires an owner OR contributor relationship; a viewer
    // relationship exists in the store but grants nothing here.
    let mut checker = PermissionChecker::<ProjectDomain>::new();
    checker.add_policy(RebacPolicy::<ProjectDomain, Uuid, Uuid, Relation>::new(
        |user: &User| user.id,
        |project: &Project| project.id,
        Relation::Owner,
    ));
    checker.add_policy(RebacPolicy::<ProjectDomain, Uuid, Uuid, Relation>::new(
        |user: &User| user.id,
        |project: &Project| project.id,
        Relation::Contributor,
    ));

    // (user, relationship held, expected outcome)
    let cases = [
        (&owner, "owner", true),
        (&contributor, "contributor", true),
        (&viewer, "viewer", false),
        (&outsider, "none", false),
    ];
    for (user, held, expected_granted) in cases {
        println!("Can {} ({held}) edit {}?", user.name, project.name);
        let decision = checker
            .bind(&session, user, &EditAction, &())
            .check(&project)
            .await;
        println!(
            "  -> {}\n",
            if decision.is_granted() {
                "GRANTED"
            } else {
                "DENIED"
            }
        );
        assert_eq!(decision.is_granted(), expected_granted);
    }

    // The trace records the facts each policy consulted (the `↳ fact` lines)
    // alongside its decision — here the viewer's denial shows both
    // relationship lookups coming back false. Note that no new "loading fact"
    // lines appear: this re-check runs in the same session, so the facts come
    // from the session cache.
    println!("Why {} is denied:", viewer.name);
    let decision = checker
        .bind(&session, &viewer, &EditAction, &())
        .check(&project)
        .await;
    println!("{}\n", decision.display_trace());

    println!("=== Error During Relationship Loading ===\n");

    // A failing store must never grant: the load error is carried into the
    // trace and the decision fails closed to denial — even for the owner.
    let error_registry = FactRegistry::builder()
        .with::<ProjectRelationship, _>(ProjectRelationshipSource::new(relationships).with_error())
        .build();
    let error_session = error_registry.session();
    let decision = checker
        .bind(&error_session, &owner, &EditAction, &())
        .check(&project)
        .await;
    println!("{}", decision.display_trace());
    decision.assert_denied();
    decision.assert_trace_contains("simulated relationship store error");
}

pub fn to_result<E>(&self, error_fn: impl FnOnce(&str) -> E) -> Result<(), E>

Converts the evaluation into a Result, mapping a denial into an error.

error_fn receives the denial reason string and should return your application’s error type.

Note that this uses the summary denial reason stored on AccessEvaluation::Denied, not the individual child policy reasons from the trace tree. If you need the per-policy reasons, inspect EvalTrace first.

let checker = PermissionChecker::<Domain>::new();
let session = EvaluationSession::empty();
let result = checker.bind(&session, &User, &Action, &Ctx).check(&Resource).await;

// Map a denial into a standard error:
let outcome: Result<(), String> = result.to_result(|reason| reason.to_string());
assert!(outcome.is_err());

pub fn display_trace(&self) -> String

Returns a human-readable string containing both the decision headline and the full evaluation trace tree.

Useful for logging or debugging. The output includes the Display representation (e.g. [GRANTED] by AdminPolicy - User is admin) followed by the indented trace from EvalTrace::format.

Examples found in repository

examples/delegating_policy.rs (line 200)

async fn main() {
    let owner_id = Uuid::new_v4();
    let author_id = Uuid::new_v4();

    let comment = Comment {
        author_id,
        document: Document { owner_id },
    };

    let author = Principal {
        user_id: author_id,
        is_admin: false,
    };
    let document_owner = Principal {
        user_id: owner_id,
        is_admin: false,
    };
    let admin = Principal {
        user_id: Uuid::new_v4(),
        is_admin: true,
    };
    let stranger = Principal {
        user_id: Uuid::new_v4(),
        is_admin: false,
    };

    let checker = comment_checker();
    let session = EvaluationSession::empty();
    let action = EditComment;
    let context = ();

    let cases = [
        ("author", &author),
        ("document owner (not author)", &document_owner),
        ("admin (not author/owner)", &admin),
        ("unrelated user", &stranger),
    ];
    for (who, principal) in cases {
        let granted = checker
            .bind(&session, principal, &action, &context)
            .check(&comment)
            .await
            .is_granted();
        println!(
            "{who:<28} can edit the comment? {}",
            if granted { "yes" } else { "no" }
        );
    }

    // The document owner is not the comment author, so the direct rule denies;
    // the delegating policy then asks the document checker, which grants. The
    // trace shows the decision crossing the domain boundary.
    println!("\nTrace — document owner (not the author) editing the comment:");
    let decision = checker
        .bind(&session, &document_owner, &action, &context)
        .check(&comment)
        .await;
    println!("{}", decision.display_trace());

    assert!(checker
        .bind(&session, &author, &action, &context)
        .check(&comment)
        .await
        .is_granted());
    assert!(checker
        .bind(&session, &document_owner, &action, &context)
        .check(&comment)
        .await
        .is_granted());
    assert!(checker
        .bind(&session, &admin, &action, &context)
        .check(&comment)
        .await
        .is_granted());
    assert!(!checker
        .bind(&session, &stranger, &action, &context)
        .check(&comment)
        .await
        .is_granted());
}

examples/rbac_policy.rs (line 134)

async fn main() {
    // The first resolver reads the requirement off the resource/action; the
    // second extracts the subject's roles. The role type (`Role`) is inferred
    // from the closures' return types.
    let rbac_policy = RbacPolicy::<DocumentDomain, _, _>::new(
        |_action: &ReadAction, doc: &Document| doc.required_roles.iter().copied().collect(),
        |user: &User| user.roles.iter().copied().collect(),
    );

    let mut checker = PermissionChecker::<DocumentDomain>::new();
    checker.add_policy(rbac_policy);

    let admin = user("admin", [Role::Admin]);
    let editor = user("editor", [Role::Editor]);
    let multi_role = user("editor+viewer", [Role::Editor, Role::Viewer]);
    let no_roles = user("no-roles", []);

    let admin_doc = document("admin handbook", [Role::Admin]);
    let editor_doc = document("style guide", [Role::Editor]);
    let shared_doc = document("team wiki", [Role::Editor, Role::Viewer]);

    // (user, document, expected outcome)
    let cases = [
        (&admin, &admin_doc, true),
        (&admin, &editor_doc, false), // admin role is not editor — no hierarchy here
        (&editor, &admin_doc, false),
        (&editor, &editor_doc, true),
        (&multi_role, &editor_doc, true),
        (&multi_role, &shared_doc, true),
        (&no_roles, &admin_doc, false),
        (&no_roles, &shared_doc, false),
    ];

    let session = EvaluationSession::empty();
    let action = ReadAction;
    let context = ();

    println!("{:<16} {:<16} verdict", "user", "document");
    println!("{}", "-".repeat(42));
    for (user, document, expected_granted) in cases {
        let decision = checker
            .bind(&session, user, &action, &context)
            .check(document)
            .await;
        println!(
            "{:<16} {:<16} {}",
            user.name,
            document.name,
            if decision.is_granted() {
                "GRANTED"
            } else {
                "DENIED"
            }
        );
        assert_eq!(decision.is_granted(), expected_granted);
    }

    // Note the admin/style-guide denial above: `RbacPolicy` is a flat
    // role-match with no built-in hierarchy. If admins should read
    // everything, either include `Role::Admin` in each document's required
    // set or add a separate admin-override policy to the checker.

    println!("\nWhy the editor is denied the admin handbook:");
    let decision = checker
        .bind(&session, &editor, &action, &context)
        .check(&admin_doc)
        .await;
    println!("{}", decision.display_trace());
}

examples/policy_builder.rs (line 157)

async fn main() {
    let mut checker = PermissionChecker::<AdminDomain>::new();
    checker.add_policy(scoped_permission_policy());
    checker.add_policy(global_admin_policy());

    let org1 = Organization { id: "org-1".into() };
    let org2 = Organization { id: "org-2".into() };

    let org1_admin = StaffUser {
        name: "org1-admin",
        permissions: vec![GroupPermission {
            scope: "edit_user_settings",
            entity: "org-1".into(),
        }],
    };
    let org2_admin = StaffUser {
        name: "org2-admin",
        permissions: vec![GroupPermission {
            scope: "edit_user_settings",
            entity: "org-2".into(),
        }],
    };
    let no_grants = StaffUser {
        name: "no-grants",
        permissions: vec![],
    };
    let global_admin = StaffUser {
        name: "global-admin",
        permissions: vec![GroupPermission {
            scope: "global_admin",
            entity: String::new(),
        }],
    };

    // (user, action, organization, expected outcome)
    let cases = [
        // Scoped grant matches its own org…
        (&org1_admin, AdminAction::EditUserSettings, &org1, true),
        // …but not another org, and not another scope on the same org.
        (&org2_admin, AdminAction::EditUserSettings, &org1, false),
        (&org1_admin, AdminAction::EditOrgSettings, &org1, false),
        (&org2_admin, AdminAction::EditUserSettings, &org2, true),
        (&no_grants, AdminAction::EditUserSettings, &org1, false),
        // The global admin passes via the subject-axis policy on any org.
        (&global_admin, AdminAction::EditOrgSettings, &org1, true),
    ];

    for (user, action, org, expected_granted) in cases {
        let session = EvaluationSession::empty();
        let decision = checker.bind(&session, user, &action, &()).check(org).await;
        println!(
            "{:<12} {:?} on {}: {}",
            user.name,
            action,
            org.id,
            if decision.is_granted() {
                "GRANTED"
            } else {
                "DENIED"
            }
        );
        assert_eq!(decision.is_granted(), expected_granted);
    }

    // The trace names the policy that decided; for a denial it shows every
    // policy that was consulted and why each said no.
    println!("\nWhy org2-admin cannot edit user settings on org-1:");
    let session = EvaluationSession::empty();
    let decision = checker
        .bind(&session, &org2_admin, &AdminAction::EditUserSettings, &())
        .check(&org1)
        .await;
    println!("{}", decision.display_trace());
}

examples/deny_override.rs (line 223)

async fn main() {
    let owner_id = Uuid::new_v4();
    let admin = User {
        id: Uuid::new_v4(),
        is_admin: true,
        suspended: false,
    };
    let suspended_owner = User {
        id: owner_id,
        is_admin: false,
        suspended: true,
    };
    let owner = User {
        id: owner_id,
        is_admin: false,
        suspended: false,
    };
    let stranger = User {
        id: Uuid::new_v4(),
        is_admin: false,
        suspended: false,
    };

    let normal_doc = Document {
        owner_id,
        legal_hold: false,
    };
    let held_doc = Document {
        owner_id,
        legal_hold: true,
    };

    let checker = document_checker();
    let session = EvaluationSession::empty();
    let action = Access;
    let context = ();

    // (subject, resource, label)
    let cases = [
        (&admin, &normal_doc, "admin, normal doc"),
        (&owner, &normal_doc, "owner, own normal doc"),
        (&admin, &held_doc, "admin, LEGAL-HOLD doc"),
        (&suspended_owner, &normal_doc, "SUSPENDED owner, own doc"),
        (&stranger, &normal_doc, "stranger, someone else's doc"),
    ];

    println!("{:<32} {:>10} forbidden by", "case", "decision");
    println!("{}", "-".repeat(60));
    for (subject, document, label) in cases {
        let decision = checker
            .bind(&session, subject, &action, &context)
            .check(document)
            .await;
        println!(
            "{label:<32} {:>10} {}",
            verdict(decision.is_granted()),
            decision.forbidden_by().unwrap_or("-"),
        );
    }

    // The grants still work where nothing blocks them.
    checker
        .bind(&session, &admin, &action, &context)
        .check(&normal_doc)
        .await
        .assert_granted_by("AdminOverride");
    checker
        .bind(&session, &owner, &action, &context)
        .check(&normal_doc)
        .await
        .assert_granted_by("DocumentOwner");

    // The block rules override every grant — even the admin override.
    checker
        .bind(&session, &admin, &action, &context)
        .check(&held_doc)
        .await
        .assert_forbidden_by("LegalHold");
    checker
        .bind(&session, &suspended_owner, &action, &context)
        .check(&normal_doc)
        .await
        .assert_forbidden_by("AccountSuspended");

    // Default deny is untouched: no grant, no access — and no forbid
    // either, which `forbidden_by()` distinguishes for the caller.
    let stranger_decision = checker
        .bind(&session, &stranger, &action, &context)
        .check(&normal_doc)
        .await;
    stranger_decision.assert_denied();
    assert_eq!(stranger_decision.forbidden_by(), None);

    // Show the mechanism on the headline case: the forbid-effect policy is
    // evaluated first and ends the evaluation; the allow set is never
    // consulted.
    println!("\nWhy 'admin, LEGAL-HOLD doc' is blocked:");
    let decision = checker
        .bind(&session, &admin, &action, &context)
        .check(&held_doc)
        .await;
    println!("{}", decision.display_trace());

    scoped_exclusion_demo().await;
}

examples/rebac_policy.rs (line 209)

async fn main() {
    println!("=== ReBAC Policy Example ===\n");

    let owner = User {
        id: Uuid::new_v4(),
        name: "Alice",
    };
    let contributor = User {
        id: Uuid::new_v4(),
        name: "Bob",
    };
    let viewer = User {
        id: Uuid::new_v4(),
        name: "Charlie",
    };
    let outsider = User {
        id: Uuid::new_v4(),
        name: "Dave",
    };
    let project = Project {
        id: Uuid::new_v4(),
        name: "Sample Project",
    };

    let relationships = HashSet::from([
        ProjectRelationship {
            subject_id: owner.id,
            resource_id: project.id,
            relation: Relation::Owner,
        },
        ProjectRelationship {
            subject_id: contributor.id,
            resource_id: project.id,
            relation: Relation::Contributor,
        },
        ProjectRelationship {
            subject_id: viewer.id,
            resource_id: project.id,
            relation: Relation::Viewer,
        },
    ]);

    let registry = FactRegistry::builder()
        .with::<ProjectRelationship, _>(ProjectRelationshipSource::new(relationships.clone()))
        .build();
    let session = registry.session();

    // Editing requires an owner OR contributor relationship; a viewer
    // relationship exists in the store but grants nothing here.
    let mut checker = PermissionChecker::<ProjectDomain>::new();
    checker.add_policy(RebacPolicy::<ProjectDomain, Uuid, Uuid, Relation>::new(
        |user: &User| user.id,
        |project: &Project| project.id,
        Relation::Owner,
    ));
    checker.add_policy(RebacPolicy::<ProjectDomain, Uuid, Uuid, Relation>::new(
        |user: &User| user.id,
        |project: &Project| project.id,
        Relation::Contributor,
    ));

    // (user, relationship held, expected outcome)
    let cases = [
        (&owner, "owner", true),
        (&contributor, "contributor", true),
        (&viewer, "viewer", false),
        (&outsider, "none", false),
    ];
    for (user, held, expected_granted) in cases {
        println!("Can {} ({held}) edit {}?", user.name, project.name);
        let decision = checker
            .bind(&session, user, &EditAction, &())
            .check(&project)
            .await;
        println!(
            "  -> {}\n",
            if decision.is_granted() {
                "GRANTED"
            } else {
                "DENIED"
            }
        );
        assert_eq!(decision.is_granted(), expected_granted);
    }

    // The trace records the facts each policy consulted (the `↳ fact` lines)
    // alongside its decision — here the viewer's denial shows both
    // relationship lookups coming back false. Note that no new "loading fact"
    // lines appear: this re-check runs in the same session, so the facts come
    // from the session cache.
    println!("Why {} is denied:", viewer.name);
    let decision = checker
        .bind(&session, &viewer, &EditAction, &())
        .check(&project)
        .await;
    println!("{}\n", decision.display_trace());

    println!("=== Error During Relationship Loading ===\n");

    // A failing store must never grant: the load error is carried into the
    // trace and the decision fails closed to denial — even for the owner.
    let error_registry = FactRegistry::builder()
        .with::<ProjectRelationship, _>(ProjectRelationshipSource::new(relationships).with_error())
        .build();
    let error_session = error_registry.session();
    let decision = checker
        .bind(&error_session, &owner, &EditAction, &())
        .check(&project)
        .await;
    println!("{}", decision.display_trace());
    decision.assert_denied();
    decision.assert_trace_contains("simulated relationship store error");
}

Trait Implementations

impl Clone for AccessEvaluation

fn clone(&self) -> AccessEvaluation

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AccessEvaluation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for AccessEvaluation

A concise line about the final decision.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Serialize for AccessEvaluation

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.