Gatehouse Authorization Engine

Gatehouse uses EvaluationSession to manage the lifecycle of facts during an authorization pass. When a policy requires external data (facts), the FactSource::load_many method is called to fetch them.

Key behaviors of EvaluationSession:

• Caching: Results are cached for the duration of a single request/session to prevent redundant loads.
• Deduplication & Ordering: It expands duplicate caller inputs and preserves the original caller order.
• Batching: It chunks loads according to the FactSource::max_batch_size to optimize backend calls.
• Concurrency: It joins concurrent in-flight loads for the same key.

FactSource Contract: FactSource::load_many must receive unique keys and return exactly one result per key in the same order as requested.

Policy Behavior: RebacPolicy is the built-in fact-backed policy. Decisions follow these rules:

• Found(false) and Missing result in an abstention.
• Missing sources, backend errors, or contract violations produce indeterminate decisions.

Gatehouse distinguishes between Grant Policies and Veto Policies to ensure clear authority separation.

Grant Policies (Policy<D>)

Return a GrantResult: grant, abstention, or indeterminate.

Veto Policies (VetoPolicy<D>)

Return a VetoResult: veto, pass, or indeterminate.

Decision Logic

1. Vetoes are resolved first: A definite veto denies access immediately. Unresolved veto uncertainty (indeterminate) also blocks grants.
2. Grants are evaluated: If vetoes pass, any grant authorizes access. A failed grant policy does not defeat an independent grant.
3. Final Outcome: If nothing grants, access is Denied. If there is uncertainty (e.g., from an indeterminate veto or failed fact load), access is Indeterminate. An empty checker denies access.

Mapping to Application Boundaries

Use evaluation.into_result() to convert an AccessEvaluation into a standard Rust Result.

• Ok(()) $\rightarrow$ Access Granted.
• Err(AccessError::Denied { .. }) $\rightarrow$ Map to a 403 Forbidden response.
• Err(AccessError::Indeterminate { .. }) $\rightarrow$ Map to a 503 Service Unavailable or similar error.

use gatehouse::{AccessError, AccessEvaluation, EvalTrace};

fn http_status(evaluation: AccessEvaluation) -> u16 {
    match evaluation.into_result() {
        Ok(()) => 200,
        Err(AccessError::Denied { .. }) => 403,
        Err(_) => 503,
    }
}

The typical authorization workflow involves binding request-wide inputs (session, subject, action, and context) to a PermissionChecker to create a BoundEvaluator. This evaluator is then used to check individual resources or perform batch operations like filtering or paging.

Common operations on a BoundEvaluator:

• check(&resource): Evaluates a single resource.
• evaluate(resources): Returns decisions for a collection of resources, preserving input order.
• try_filter(resources): Returns only the granted items and fails if any decision is indeterminate.
• try_filter_by(rows, |row| &row.authz_resource): Filters a collection of rows based on an extracted resource.
• try_lookup_page(...): Handles paginated lookups using a LookupSource and Hydrator.

let session = registry.session();
let bound = checker.bind(&session, &subject, &action, &request_context);

let decision = bound.check(&resource).await;
let decisions = bound.evaluate(resources.clone()).await;
let authorized = bound.try_filter(resources).await?;
let authorized_rows = bound.try_filter_by(rows, |row| &row.authz_resource).await?;
let page = bound.try_lookup_page(&lookup, &hydrator, cursor.as_deref(), limit).await?;

Upgrading from version 0.4 to 0.5 involves significant API changes designed to reduce the authorization surface and prevent misuse. Key changes include moving from four generic parameters to a single PolicyDomain, requiring all checker calls to go through a session-bound evaluator, and changing how non-grants are handled.

Migration Checklist

1. Define one PolicyDomain marker per authorization domain.
2. Change Policy<S, A, R, C> implementations to Policy<Domain>.
3. Change EvalCtx<'_, S, A, R, C> to EvalCtx<'_, Domain>.
4. Replace ctx.deny(...) with ctx.not_applicable(...).
5. Replace PolicyEvalResult::Denied with PolicyEvalResult::NotApplicable.
6. Replace PolicyBuilder::<S, A, R, C> with PolicyBuilder::<Domain>.
7. Replace direct checker methods (e.g., check, evaluate_in_session) with the new binding pattern: checker.bind(...).check(...), .evaluate(...), .filter(...), or .lookup_page(...).
8. Build request sessions through FactRegistry for fact-backed policies.
9. Replace AbacPolicy with PolicyBuilder::when or a hand-written Policy.
10. Update direct BatchEvalCtx / PolicyBatchItem construction in tests.
11. Add wildcard arms to matches on public gatehouse enums (they are now #[non_exhaustive]).

Gatehouse is an in-process authorization engine for Rust. To get started, define your authorization domain by implementing the PolicyDomain trait for a marker struct, then use PolicyBuilder to define rules and PermissionChecker to evaluate them.

Key steps:

1. Define your Subject, Action, Resource, and Context types.
2. Implement PolicyDomain for a struct representing your domain.
3. Create policies using PolicyBuilder (for synchronous predicates) or by implementing the Policy trait (for asynchronous logic).
4. Add policies to a PermissionChecker.
5. Bind the checker to a session and inputs to perform checks.

use gatehouse::*;

#[derive(Debug, Clone)]
struct User {
    id: u64,
    roles: Vec<&'static str>,
}

#[derive(Debug, Clone)]
struct Document {
    owner_id: u64,
}

#[derive(Debug, Clone)]
struct ReadAction;

struct Documents;
impl PolicyDomain for Documents {
    type Subject = User;
    type Action = ReadAction;
    type Resource = Document;
    type Context = ();
}

let admin_policy = PolicyBuilder::<Documents>::new("AdminOnly")
    .subjects(|user: &User| user.roles.contains(&"admin")),
    .build();

let owner_policy = PolicyBuilder::<Documents>::new("OwnerOnly")
    .when(|user: &User, _action: &ReadAction, doc: &Document, _ctx: &()| {
        user.id == doc.owner_id
    })
    .build();

let mut checker = PermissionChecker::<Documents>::new();
checker.add_policy(admin_policy);
checker.add_policy(owner_policy);

let session = EvaluationSession::empty();
let action = ReadAction;
let document = Document { owner_id: 7 };
let admin = User { id: 1, roles: vec!["admin"] };

assert!(checker.bind(&session, &admin, &action, &()).check(&document).await.is_granted());