Gatehouse

An in-process authorization engine for Rust. Gatehouse keeps policy logic in Rust while giving each request an EvaluationSession for relationship and backend-loaded facts. Sessions batch, deduplicate, cache, and coalesce fact loads, so list endpoints can stay policy-correct without pushing authorization logic into the data layer.

Features

• Typed authorization domains: Define one PolicyDomain per authorization domain and keep subject, action, resource, and context types consistent.
• Request-bound evaluation: Bind session, subject, action, and context once, then call check, evaluate, evaluate_by, filter, filter_by, or lookup_page.
• RBAC, ReBAC, and predicate policies: Use RbacPolicy, RebacPolicy, or synchronous PolicyBuilder::when predicates.
• Deny-overrides semantics: PolicyBuilder::forbid() and custom forbid results veto grants, including through combinators and delegation.
• Batch-safe list endpoints: Authorize already-loaded resources or enumerate candidate IDs with LookupSource and Hydrator.
• Evaluation traces and telemetry: Inspect the policies and fact provenance that were actually evaluated.

Quick Start

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);

# tokio_test::block_on(async {
let session = EvaluationSession::empty();
let action = ReadAction;
let document = Document { owner_id: 7 };

let admin = User { id: 1, roles: vec!["admin"] };
let owner = User { id: 7, roles: vec!["user"] };
let guest = User { id: 2, roles: vec!["user"] };

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

Use EvaluationSession::empty() for fact-free checkers. When any policy reads facts through ctx.session.get(...), build a FactRegistry at application setup and create a fresh registry.session() for each request.

Core Flow

Most call sites bind request-wide inputs once and evaluate one or more resources through the bound evaluator:

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.filter(resources).await;
let authorized_rows = bound.filter_by(rows, |row| &row.authz_resource).await;
let page = bound.lookup_page(&lookup, &hydrator, cursor.as_deref(), limit).await?;

flowchart LR
    Request[request] --> Session[EvaluationSession]
    Request --> Bound[BoundEvaluator]
    Checker[PermissionChecker] --> Bound
    Bound --> Policies[policies]
    Policies --> Session
    Session --> Facts[FactSource::load_many]
    Facts --> Backend[(backend)]
    Policies --> Decision[AccessEvaluation + EvalTrace]

Loading

BoundEvaluator::evaluate preserves input order and returns one AccessEvaluation per resource. BoundEvaluator::filter keeps only granted resources. Use evaluate_by and filter_by when the caller owns wider rows and authorization should project each row to an embedded resource. The returned values are still the original rows. BoundEvaluator::lookup_page is for list endpoints where the application cannot load every possible candidate first; a LookupSource enumerates candidate IDs, a Hydrator resolves them, and the full policy stack authorizes the hydrated resources.

Decision Semantics

• PermissionChecker applies fixed deny-overrides semantics: any evaluated result containing PolicyEvalResult::Forbidden denies; otherwise the first grant wins.
• Policies declaring Effect::Forbid or Effect::AllowOrForbid are evaluated before allow-only policies, so a veto cannot be skipped by grant short-circuiting.
• If nothing grants, the checker denies with "All policies denied access".
• An empty checker denies with "No policies configured".
• PolicyEvalResult::NotApplicable means the policy did not grant. PolicyEvalResult::Forbidden means the policy actively vetoed.
• PolicyBuilder combines configured predicates with AND logic. PolicyBuilder::forbid() makes a matching policy forbid; a non-match remains not applicable and does not block.
• AndPolicy and OrPolicy evaluate veto-capable children before allow-only children, then short-circuit normally. NotPolicy inverts grants and non-grants, but never turns Forbidden into a grant.
• Forbidden propagates through AndPolicy, OrPolicy, NotPolicy, and DelegatingPolicy.
• not() does not neutralize a veto: admin.or(blocked.not()) still denies if blocked returns Forbidden. For "grant unless blocked", make blocked an allow-only predicate and wrap that in not(), or register a direct forbid policy when the block should be global.

Denials from AccessEvaluation are summary-level. Use AccessEvaluation::display_trace() or the attached EvalTrace to inspect individual policy reasons and fact provenance.

Policy Domains

A PolicyDomain names the four types involved in one authorization domain:

use gatehouse::PolicyDomain;

# struct User;
# struct DocAction;
# struct Document;
# struct RequestContext;
struct Documents;

impl PolicyDomain for Documents {
    type Subject = User;
    type Action = DocAction;
    type Resource = Document;
    type Context = RequestContext;
}

The generic parameter then stays short and consistent:

let policy = PolicyBuilder::<Documents>::new("Owner")
    .when(|user, _action, doc, _ctx| user.id == doc.owner_id)
    .build();

let checker = PermissionChecker::<Documents>::new();

PolicyBuilder

Use PolicyBuilder for synchronous predicate logic:

let suspended_account = PolicyBuilder::<Documents>::new("SuspendedAccount")
    .when(|user, _action, _doc, _ctx| user.is_suspended)
    .forbid()
    .build();

Reach for a direct Policy<D> implementation when a rule needs async work, custom batching, custom telemetry metadata, or hand-written forbid behavior.

use async_trait::async_trait;
use gatehouse::{EvalCtx, Policy, PolicyDomain, PolicyEvalResult};
use std::borrow::Cow;

# #[derive(Debug, Clone)]
# struct User { id: u64 }
# #[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 = ();
# }
struct OwnerPolicy;

#[async_trait]
impl Policy<Documents> for OwnerPolicy {
    async fn evaluate(&self, ctx: &EvalCtx<'_, Documents>) -> PolicyEvalResult {
        if ctx.subject.id == ctx.resource.owner_id {
            ctx.grant("subject owns the document")
        } else {
            ctx.not_applicable("subject does not own the document")
        }
    }

    fn policy_type(&self) -> Cow<'static, str> {
        Cow::Borrowed("OwnerPolicy")
    }
}

Built-In Policies

• RbacPolicy: role-based access control. Grants when at least one required role for (action, resource) is present in the subject's roles.
• RebacPolicy: relationship-based access control. Extracts subject/resource IDs, builds RelationshipQuery keys, and grants when the request session loads Found(true) from a registered FactSource.
• DelegatingPolicy: maps inputs into another PolicyDomain and delegates to a child PermissionChecker while preserving batching and trace shape.

Use PolicyBuilder::when for attribute-style predicates that compare subject, action, resource, and context in one closure.

Fluent Combinators

Policies can be composed with the PolicyExt helpers:

use gatehouse::PolicyExt;

let rule = is_editor.and(not_locked.not()).or(admin_override);
checker.add_policy(rule);

AndPolicy::try_new, OrPolicy::try_new, and NotPolicy::new remain available when constructing policies from dynamic collections.

forbid() creates a global veto, not a local negative predicate. In particular, grant.and(forbid_only) can never grant because the forbid-only child never satisfies AND's "all children grant" rule. For a local exclusion, build the blocked condition as an ordinary allow-style predicate and compose grant.and(blocked.not()).

Request-Scoped Facts

FactSource::load_many receives unique keys and must return exactly one result per key in the same order. EvaluationSession expands duplicate caller inputs, preserves caller order, caches results for the request, chunks loads according to FactSource::max_batch_size, and joins concurrent in-flight loads for the same key.

flowchart LR
    Policy[policy] --> Session[EvaluationSession]
    Session --> Cache{cached?}
    Cache -- yes --> Result[FactLoadResult]
    Cache -- no --> Source[FactSource::load_many]
    Source --> Backend[(backend)]
    Backend --> Result

Loading

RebacPolicy is the built-in fact-backed policy. Missing sources, missing facts, backend errors, and source contract violations fail closed to denied ReBAC decisions.

Use typed relation enums when the domain has a fixed relation set, even if the backing store uses strings. The FactSource owns the backend boundary and can convert Relation::Viewer to "viewer" when binding SQL parameters.

List Endpoints

For lists where the application already has candidate resources, use BoundEvaluator::filter:

let session = registry.session();
let visible_posts = checker
    .bind(&session, &user, &PostAction::View, &request_context)
    .filter(posts)
    .await;

If each item is a wide row and the authorization resource is a projection, use the extractor variants:

let visible_rows = checker
    .bind(&session, &user, &InvoiceAction::View, &request_context)
    .filter_by(rows, |row| &row.authz_resource)
    .await;

For lists where the candidate set is too large to load first, implement LookupSource<Domain> and Hydrator<Id>:

let page = checker
    .bind(&session, &user, &PostAction::View, &request_context)
    .lookup_page(&lookup, &hydrator, cursor.as_deref(), limit)
    .await?;

A LookupSource must enumerate a superset of every resource that any policy could grant for the bound subject/action/context. Lookup narrows candidates; it does not replace the policy stack.

Long-Lived Streams

EvaluationSession caches are scoped to one authorization pass. For SSE, WebSocket, and other long-lived streams, do not keep one fact-backed session for the stream lifetime.

If your product contract authorizes once at stream open, create a fresh session, compute the visible ID set with filter / filter_by, drop the session, and only emit frames for that set. If the stream must observe mid-stream permission revocation, run periodic reauthorization with a fresh registry.session() each tick and re-bind the checker for that pass.

Tracing And Telemetry

When trace-level events are enabled, checker evaluation records spans for single-resource and batch evaluation, and each evaluated policy records a trace! event on the gatehouse::security target. Batch evaluation records aggregate item counts and nested gatehouse.batch_policy spans with per-policy counts.

Reason strings are emitted verbatim. Keep credentials, tokens, raw PII, and other sensitive material out of policy reasons and fact provenance details. Enable the optional serde feature to serialize AccessEvaluation, EvalTrace, PolicyEvalResult, and fact provenance for audit logs.

Security event fields:

• security_rule.name
• security_rule.category
• security_rule.description
• security_rule.reference
• security_rule.ruleset.name
• security_rule.uuid
• security_rule.version
• security_rule.license
• event.outcome
• policy.type
• policy.result.reason

Examples

Run a self-contained example with:

cargo run --example rbac_policy

Run a server example with:

cargo run --example axum

Then send requests to http://127.0.0.1:8000; actix_web listens on http://127.0.0.1:8080.

Examples to start with:

• rbac_policy: basic role-based access control.
• policy_builder: attribute-style custom policies.
• combinator_policy: fluent and / or / not composition.
• deny_override: global veto policies with PolicyBuilder::forbid().
• delegating_policy: cross-domain checks with DelegatingPolicy.
• mfa_freshness_context: request-scoped context inputs.
• rebac_policy: relationship checks through FactSource.
• in_ram_rebac: in-memory relationship facts and session caching.
• lookup_in_ram: LookupSource plus Hydrator list authorization.
• factsource_n_plus_one: why request-scoped facts matter for list endpoints.
• axum and actix_web: web-framework integration.
• postgres_bulk_rebac: SQL-backed ReBAC fact loading.

Performance

Criterion benchmarks in benches/permission_checker.rs exercise bound checker evaluation, fact loading, batching, and policy-builder batch shortcuts. Run them with:

cargo bench

The postgres_bulk_rebac example demonstrates a SQL-backed ReBAC FactSource with one batched WITH ORDINALITY query per request. It expects a live PostgreSQL database and reads DATABASE_URL.