Crate axess_core 

Core implementation for the Axess authentication and authorization library.

Re-export strategy

Public types have one canonical location (the module that defines or that owns the canonical re-export from a sibling crate) and may also be convenience-re-exported at the crate root. Adopters can use either path; the canonical path is what rustdoc displays. When in doubt, prefer the canonical path in import statements; it survives crate-root churn.

Concern	Canonical	Crate-root convenience
Session state	session::*	(none; depth-2 access only)
Authn service / state machine	authn::*	(none)
Authn factor configs	authn::factor::*	(none)
Authn errors	authn::error::*	(none)
Authz policy / decision	authz::*	(none)
Identity (principal, IDs)	principal::* (re-exports axess-identity)	(none)
Clock / RNG (DST foundation)	axess_clock::* / axess_rng::*	Clock, SecureRng, SystemClock, SystemRng
Health checks	health::*	HealthCheck, HealthStatus, CompositeHealthCheck
Authn metrics	metrics::*	AuthnMetrics, NoopMetrics
Middleware (CSRF, rate-limit, request-id, trace-id)	middleware::*	RateLimitLayer + helpers; RequestIdLayer (feature-gated); TraceIdLayer + TraceContext (feature-gated)
Test fixtures	testing::* (gated cfg(any(test, feature = "testing")))	MockClock, MockRng, MockIdentityStore, …

Why some types have crate-root convenience and others don’t: the ones promoted to the crate root are either DST primitives that every adopter touches (Clock, SecureRng) or framework integration points that read naturally as axess_core::RateLimitLayer. Authn / authz types stay at depth-2 so the import line reveals which layer the type belongs to. Useful when reading a route handler that mixes authn and authz concerns.

Feature flags

Feature	What it enables
authz	Cedar Policy authorization (RBAC + ABAC + ReBAC). On by default.
device	First-class device::Device identity with three-stage assurance ladder (Unknown → Seen → Trusted, plus terminal Revoked), per-tenant fingerprint pepper, refresh-family cascade, retention sweep, and CachedDeviceStore decorator. On by default. Pair with sqlite / postgres / mysql / valkey for persistent backends (SqliteDeviceStore, PostgresDeviceStore, MysqlDeviceStore, ValkeyDeviceStore). See device and docs/identity/device.md.
memory	In-memory session store and registry (MemorySessionStore, MemorySessionRegistry). Dev/test only, not in default features. Production builds without this flag cannot import these types.
sqlite	SQLite session store with AES-256-GCM encryption.
postgres	PostgreSQL session store with AES-256-GCM encryption.
valkey	Valkey/Redis session store and registry with optional encryption.
fido2	FIDO2/WebAuthn passkey authentication.
oauth	OAuth 2.0 / OIDC (AuthCode+PKCE, Client Credentials, Device Code).
ldap	LDAP bind authentication (Active Directory, OpenLDAP).
request-id	X-Request-Id middleware.
trace-id	W3C Trace Context (traceparent) middleware.
default-error-response	Built-in IntoResponse mapping for AuthnError (on by default). Disable to ship your own HTTP mapping; see authn::error for the recommended status-code table.
full	All of the above.

Internal features (used by the library, not intended for direct use): accept_client_id.

Re-exports

pub use session::AuthSession;

pub use session::AuthState;

pub use session::RefreshError;

pub use session::RefreshToken;

pub use session::RefreshTokenConfig;

pub use session::RefreshTokenStore;

pub use session::SessionBinding;

pub use session::SessionConfig;

pub use session::SessionConfigBuilder;

pub use session::SessionData;

pub use session::SessionLayer;

pub use session::SessionRegistry;

pub use session::SessionRegistryAdapter;

pub use session::SessionRegistryHandle;

pub use session::SessionRevoker;

pub use session::SessionStore;

pub use session::UserAgentBinding;

pub use session::MemorySessionRegistry;memory

pub use session::MemorySessionStore;memory

pub use authn::AuditContext;

pub use authn::AuditQuery;

pub use authn::AuthEvent;

pub use authn::AuthEventBuilder;

pub use authn::AuthEventStatus;

pub use authn::AuthEventType;

pub use authn::AuthMethod;

pub use authn::AuthnBackend;

pub use authn::AuthnError;

pub use authn::AuthnScope;

pub use authn::AuthnService;

pub use authn::EntityState;

pub use authn::EventQueryFilter;

pub use authn::FactorConfig;

pub use authn::FactorCredential;

pub use authn::FactorKind;

pub use authn::FactorOutcome;

pub use authn::FactorStep;

pub use authn::FactorStore;

pub use authn::FactorTemplate;

pub use authn::FederatedProvider;

pub use authn::IdentityAdmin;

pub use authn::IdentityAuthnLog;

pub use authn::IdentityLookup;

pub use authn::IdentityStore;

pub use authn::IpPolicy;

pub use authn::LdapBindFactorConfig;

pub use authn::LockoutPolicy;

pub use authn::LoginOutcome;

pub use authn::NoSessionRegistryError;

pub use authn::NoopAuthnLog;

pub use authn::PrepareOutcome;

pub use authn::ProvisioningError;

pub use authn::SessionValidator;

pub use authn::SignupOutcome;

pub use authn::StatusDetail;

pub use authn::Tenant;

pub use authn::TenantBootstrap;

pub use authn::User;

pub use authn::create_tenant;

pub use authn::default_catalog;

pub use authn::extract_audit_context;

pub use authn::extract_audit_context_async;

pub use authn::require_valid_session;

pub use authz::AuthzDecision;authz

pub use authz::AuthzDenied;authz

pub use authz::AuthzEntityProvider;authz

pub use authz::AuthzError;authz

pub use authz::AuthzSession;authz

pub use authz::AuthzStore;authz

pub use authz::BuildRequestContext;authz

pub use authz::NoContext;authz

pub use authz::PolicyEvaluator;authz

pub use authz::PolicyStore;authz

pub use authz::StandardRequestContext;authz

pub use authz::ip_from_headers;authz

pub use authz::make_action_uid;authz

pub use authz::make_entity_uid;authz

pub use session::storage::in_memory_backend::InMemoryBackend;testing

pub use session::storage::sqlite::SqliteSessionStore;sqlite

pub use session::storage::postgres::PostgresSessionStore;postgres

pub use session::storage::postgres::PostgresStoreError;postgres

pub use session::storage::mysql::MysqlSessionStore;mysql

pub use session::storage::mysql::MysqlStoreError;mysql

pub use session::storage::valkey::ValkeySessionRegistry;valkey

pub use session::storage::valkey::ValkeySessionStore;valkey

pub use session::storage::valkey::ValkeyStoreError;valkey

pub use device::AttestationClass;device

pub use device::CachedDeviceStore;device

pub use device::DefaultFingerprintExtractor;device

pub use device::Device;device

pub use device::DeviceBinding;device

pub use device::DeviceEventSink;device

pub use device::DeviceFingerprintExtractor;device

pub use device::DeviceLifecycleService;device

pub use device::DevicePiiCategory;device

pub use device::DevicePiiMapping;device

pub use device::DevicePiiResolver;device

pub use device::DevicePiiStore;device

pub use device::DeviceResolver;device

pub use device::DeviceStore;device

pub use device::DeviceTrustLevel;device

pub use device::FingerprintHash;device

pub use device::LifecycleDeviceResolver;device

pub use device::MemoryDevicePiiStore;device

pub use device::MemoryDevicePiiStoreError;device

pub use device::MemoryDeviceStore;device

pub use device::MemoryDeviceStoreError;device

pub use device::NoopDeviceEventSink;device

pub use device::NoopDeviceResolver;device

pub use device::PiiToken;device

pub use device::REDACTED_PLACEHOLDER;device

pub use device::RedactedResolver;device

pub use device::SweepConfig;device

pub use device::SweepConfigBuilder;device

pub use device::SweepCounts;device

pub use device::TenantPepperResolver;device

pub use device::cascade_revoke_by_refresh_family;device

pub use device::cascade_revoke_devices;device

pub use authn::service::StepUpPolicy;device

pub use authn::service::StepUpPolicyBuilder;device

pub use authn::service::decide_step_up;device

pub use device::storage::SqlDeviceStoreError;device and (mysql or postgres or sqlite)

pub use device::storage::SqliteDeviceStore;device and sqlite

pub use device::storage::PostgresDeviceStore;device and postgres

pub use device::storage::MysqlDeviceStore;device and mysql

pub use device::storage::ValkeyDeviceStore;device and valkey

pub use device::storage::ValkeyDeviceStoreError;device and valkey

pub use principal::AuthHumanPrincipal;

pub use principal::AuthPrincipal;

pub use principal::AuthWorkloadPrincipal;

pub use principal::PrincipalRejection;

pub use principal::SessionResolver;

pub use principal::ToCedarEntity;authz

pub use session::cookies;

pub use session::hmac;

pub use health::CompositeHealthCheck;

pub use health::CompositeStatus;

pub use health::HealthCheck;

pub use health::HealthStatus;

pub use metrics::AuthnMetrics;

pub use metrics::NoopMetrics;

pub use testing::mock_tracing::TracingCapture;testing

pub use testing::MemoryRefreshStoreError;testing

pub use testing::MemoryRefreshTokenStore;testing

pub use testing::MockFactorStore;testing

pub use testing::MockIdentityStore;testing

pub use testing::mock_policy::MockEntityProvider;authz and (testing)

pub use testing::mock_policy::MockPolicyEvaluator;authz and (testing)

pub use middleware::request_id::RequestIdLayer;request-id

pub use middleware::trace_id::TraceContext;trace-id

pub use middleware::trace_id::TraceContextLayer;trace-id

pub use middleware::trace_id::TraceIdLayer;trace-id

pub use middleware::ratelimit::KeyExtractor;

pub use middleware::ratelimit::RateLimitConfig;

pub use middleware::ratelimit::RateLimitConfigBuilder;

pub use middleware::ratelimit::RateLimitLayer;

pub use middleware::ratelimit::RateLimitLoginIdentifier;

pub use middleware::ratelimit::RateLimitService;

pub use middleware::ratelimit::RateLimitTenantId;

pub use middleware::ratelimit::RateLimitUserId;

Modules

authn

Authentication service: identity lookup, factor verification, session management. Authentication layer: identity lookup, factor verification, session management.

authzauthz

Cedar Policy authorization for Axum applications.

delegateddelegated-exchange or delegated-stored

On-behalf-of (OBO) access: axess acts as a user at a downstream service. Two flow shapes share one conceptual abstraction; see delegated::stored and delegated::exchange for the per-flow contracts. On-behalf-of (OBO) access: axess acting as a user at a downstream service.

devicedevice

First-class typed Device aggregate + three-layer assurance ladder. Device identity. Typed Device aggregate, three-stage assurance ladder plus terminal Revoked state, fingerprint extraction, lifecycle service, PII tokenisation, in-process cache decorator, refresh-family cascade, retention sweep, and SQL / Valkey persistence backends. Implements the proposal in docs/identity/device.md. All types are gated on the device feature; storage backends are double-gated (device,sqlite, device,postgres, device,valkey).

federation

External-IdP federation adapters: per-protocol + per-issuer. Orchestrator-side external-IdP integration code.

health

Composite health-check primitives. Health-check abstraction for operational readiness probes.

local_idplocal-idp

Production-grade in-process IdP: mints workload-identity JWTs against an adopter-supplied local_idp::LocalIdpKeyStore and exposes JWKS for verifiers. Test counterpart lives at testing::local_idp. Gated on the local-idp feature. Production in-process IdP. Mints workload-identity JWTs against an adopter-supplied key store, serves the matching JWKS, and emits issuance events through the same audit hook the test fixture uses.

metrics

AuthnMetrics trait + NoopMetrics default implementation. Metrics hook trait for observability.

middleware

Optional axum/tower middleware: request ID, W3C trace context, rate limiting, CSRF. Renamed from extras in (the prior name was meant to signal “outside the core auth flow”; middleware is what these actually are). Optional axum/tower middleware that sits outside the core auth flow: request ID, W3C trace context, rate limiting, CSRF.

principal

Unified identity abstraction covering humans and workloads. See docs/workload-identity/README.md. Principal abstraction.

session

Custom tower session layer with HMAC-signed cookies and typed session data. Session layer: custom tower middleware providing signed cookies and typed session data.

store

Generic key/value-with-TTL store + codec, shared across backend implementations. Shared key/value-with-TTL store abstraction.

testingtesting

Mock authentication/identity stores, deterministic clocks/RNGs, fixture builders, and other test doubles. Gated behind cfg(any(test, feature = "testing")) so production builds cannot import them; in-crate tests get them via cfg(test). Deterministic-simulation-testing (DST) fixtures: mocks, fakes, and record builders that adopter test suites can use against axess-core’s production traits.

validation

Identifier / e-mail / URL validation helpers. Input validation helpers for Axess forms and factor flows.

workload

Workload identity hub: re-exports inbound resolvers and houses outbound primitives. See workload module docs. Outbound workload identity: axess presenting its own identity to a 3rd party (OAuth client_credentials / private_key_jwt, client-side mTLS, signed JWT assertions, cloud-STS exchanges). Each mechanism lives under crate::workload::outbound.

Structs

CliResolver

CLI / environment-sourced workload-identity resolver.

CliResolverBuilder

Builder for CliResolver. Every field except attributes is required; build() returns Err if any are missing.

DeviceId

Device identifier, sibling to UserId / TenantId. axess-minted: cryptographic opacity is the security contract, so prefer Self::new over Self::from_namespaced_str in production paths.

DpopProoffapi

A DPoP proof and its associated public key thumbprint.

EmailOtpConfig

Email OTP factor configuration.

FapiConfigfapi

FAPI 2.0 Baseline Profile configuration.

Fido2Config

FIDO2/WebAuthn factor configuration.

HotpConfig

HOTP factor configuration (RFC 4226).

HumanPrincipal

A human user authenticated through an interactive session.

LdapBindResultldap

Result of a successful LDAP bind.

LdapGroupSearchldap

Configuration for LDAP group membership searches after a successful bind.

LdapProviderConfigldap

Production LDAP provider wrapping the ldap3 crate.

MockClocktesting

A clock whose current time can be set from test code.

MockLdapProviderldap

Test double for LdapProvider. Configure accepted credentials via with_user; unconfigured users and wrong passwords are rejected.

MockOAuthProvideroauth

Mock OAuth/OIDC provider for deterministic simulation testing.

MockResolvertesting

Mock PrincipalResolver returning a canned Principal or IdentityError for tests.

MockRngtesting

Deterministic RNG for testing (NOT cryptographically secure).

OAuthClaimsoauth

OIDC claims extracted from a validated ID token.

OAuthLoginOptionsoauth

Options for a single OAuth login flow.

OAuthProviderConfigoauth

Configuration for an OAuth 2.0 / OIDC identity provider.

ParResponsefapi

Response from a Pushed Authorization Request (RFC 9126).

PasswordConfig

Password factor configuration.

PasswordRules

Complexity requirements for passwords.

SessionId

Session identifier. axess-minted; cryptographic opacity is the security contract. A session-id leak that revealed login time would be a vulnerability for forensic correlation against externally-observed events, so prefer Self::new (UUID v4 random) over time-prefixed variants.

SystemClock

Production Clock backed by chrono::Utc::now.

SystemRng

Production implementation using OS-provided cryptographically secure RNG.

TenantId

Tenant identifier. Scopes principals and events to a multi-tenant boundary. Adopter-supplied: see Self::from_uuid for direct UUID adoption, Self::from_namespaced_str for v5 mapping of non-UUID identifiers, Self::SYSTEM for the reserved platform-operator sentinel.

TotpConfig

TOTP factor configuration (RFC 6238).

TrustDomain

SPIFFE trust domain: the authority component of a SPIFFE-ID URI.

UserId

User (subject / principal) identifier. Adopter-supplied, same constructor surface as TenantId. Distinct Self::SYSTEM sentinel from the tenant so applications installing real rows for both don’t collapse them.

UserInfoClaimsoauth

Claims returned by the OIDC UserInfo endpoint.

WorkloadId

SPIFFE-ID-shaped workload identifier.

WorkloadPrincipal

A workload principal: a service, batch job, agent, or other non-human compute identity. Carries the SPIFFE-shaped workload id, its trust domain, the issuer that vouched for it, the tenant scope, and arbitrary attributes (empty today; populated from JWT claims when JWT-SVID resolution lands).

ZeroizedString

A String that is zeroed in memory on drop.

Enums

IdentityError

Errors from principal construction and identity parsing.

Issuer

How a principal’s identity was vouched for at resolution time.

LdapErrorldap

Errors returned by the LDAP provider during connect, bind, or search operations.

OAuthErroroauth

Errors returned by OAuth 2.0 / OIDC operations across discovery, token exchange, ID-token validation, and refresh.

OtpAlgorithm

The HMAC algorithm used for OTP generation.

Principal

An authenticated principal: either a human user or a workload.

ResponseModeoauth

OAuth 2.0 response mode: how the authorization server returns parameters.

SameSite

The SameSite cookie attribute.

SenderConstraintfapi

Sender-constraint mechanism for FAPI 2.0.

Traits

Clock

Clock trait to enable deterministic simulation/testing.

LdapProviderldap

Abstraction over LDAP bind operations.

OAuthProvideroauth

Abstraction over OAuth/OIDC token operations.

PrincipalResolver

Async resolver that produces a Principal from a context-specific identity source. See module-level docs for the dispatch model.

SecureRng

Trait for secure random number generation (DST-friendly).

Functions

spawn_jwks_refreshoauth

Spawn a background task that periodically calls OAuthProvider::refresh_jwks on provider.

Type Aliases

AuthUrlResultoauth

Result type for build_auth_url and build_auth_url_par.