backbone_auth/
lib.rs

1//! Backbone Framework Auth
2//!
3//! Authentication and authorization system with JWT, password hashing, and RBAC.
4//!
5//! ## Generic Design
6//!
7//! This crate provides **generic traits** that modules can implement with their
8//! own domain entities. This follows the framework rule: "Backbone is a GENERIC
9//! library and must NEVER contain entity-specific code."
10//!
11//! ### Core Traits
12//!
13//! - `AuthenticatableUser` - Trait for user entities that can be authenticated
14//! - `PermissionLike` - Trait for permission entities
15//! - `RoleLike` - Trait for role entities with permissions
16//! - `PermissionChecker` - Trait for permission checking services
17//! - `UserRepository` - Generic repository trait for user operations
18//!
19//! ### Default Implementations
20//!
21//! For testing and simple use cases, default implementations are provided:
22//! - `SimpleUser` - Default user struct implementing `AuthenticatableUser`
23//! - `SimplePermission` - Default permission struct implementing `PermissionLike`
24//! - `SimpleRole` - Default role struct implementing `RoleLike`
25//! - `InMemoryPermissionService` - In-memory RBAC service
26//!
27//! ### Backwards Compatibility
28//!
29//! Type aliases are provided for backwards compatibility:
30//! - `User` = `SimpleUser`
31//! - `Permission` = `SimplePermission`
32//! - `Role` = `SimpleRole`
33//! - `PermissionService` = `InMemoryPermissionService<SimpleRole>`
34
35pub mod audit;
36pub mod auth_service;
37pub mod grants;
38pub mod jwt;
39pub mod password;
40pub mod permissions;
41pub mod middleware;
42pub mod token_generator;
43pub mod traits;
44pub mod resource_policy;
45#[cfg(feature = "axum")]
46pub mod audience;
47#[cfg(feature = "axum")]
48pub mod company;
49#[cfg(feature = "axum")]
50pub mod idempotency;
51#[cfg(feature = "axum")]
52pub mod org;
53#[cfg(feature = "axum")]
54pub mod resolver;
55
56// Re-export commonly used types
57pub use audit::AuditEvent;
58pub use auth_service::*;
59pub use jwt::*;
60pub use password::*;
61// `AuthContext` here is the IDENTITY context (`user_id` / `roles` / `permissions`) — the one
62// `ResourcePolicy` and every generated `*_auth.rs` checks against. `traits` has a same-named struct
63// carrying request forensics; it is re-exported below as `RequestAuthContext` so `AuthContext`
64// resolves to exactly one type at this crate's root.
65pub use middleware::{AuthMiddleware, AuthExtractor, AuthContext};
66pub use token_generator::TokenGenerator;
67
68/// Permissions as data: canonical names, matching, the grants a person holds and where they are read
69/// from (`grants`); the request layer that fills `AuthContext.permissions` from a source (feature
70/// `axum`, `resolver`).
71pub use grants::{
72    GrantError, GrantSource, Grants, LegacySpelling, PermissionRequired, PermissionWaiver,
73    GOD_PERMISSION, PERMISSION_REQUIRED,
74};
75#[cfg(feature = "axum")]
76pub use resolver::{resolve_grants, GrantResolver};
77#[cfg(feature = "identity-grants")]
78pub use resolver::IdentityGrantSource;
79
80/// The HTTP company guard (feature `axum`): derive `company_id` from a signed token, never a request body.
81#[cfg(feature = "axum")]
82pub use company::{company_auth, CompanyClaims, CompanyContext, CompanyVerifier};
83/// The org-tree session guard and its issuer (feature `axum`, ADR-0028): acting unit +
84/// entitlements from a signed token; the issuer mints the pair the guard trusts.
85#[cfg(feature = "axum")]
86pub use org::{
87    org_auth, OrgClaims, OrgContext, OrgIssuer, OrgVerifier, TOKEN_TYPE_ACCESS,
88    TOKEN_TYPE_REFRESH,
89};
90/// Tenant binding of session tokens (feature `axum`): the `aud` claim against the request's tenant.
91#[cfg(feature = "axum")]
92pub use audience::AudienceSource;
93#[cfg(feature = "axum")]
94pub use idempotency::{IdempotencyState, idempotency_middleware, migrate as migrate_idempotency};
95
96// ── Backward-compatibility aliases (deprecated) ──
97//
98// These were `Tenant*` until ADR-0005 established that `company_id` is a legal-entity/books boundary,
99// not the tenant (the tenant is the database). The rename is a breaking change for downstream
100// consumers pinned to `main` — e.g. serpa-posman-service references `TenantVerifier`. These aliases
101// keep such consumers compiling on sync, with a deprecation warning and a migration path. Remove them
102// once no consumer references the old names.
103#[cfg(feature = "axum")]
104#[deprecated(note = "renamed to CompanyContext (ADR-0005: company_id is a legal-entity boundary, not the tenant)")]
105pub use company::CompanyContext as TenantContext;
106#[cfg(feature = "axum")]
107#[deprecated(note = "renamed to CompanyVerifier (ADR-0005)")]
108pub use company::CompanyVerifier as TenantVerifier;
109#[cfg(feature = "axum")]
110#[deprecated(note = "renamed to CompanyClaims (ADR-0005)")]
111pub use company::CompanyClaims as TenantClaims;
112#[cfg(feature = "axum")]
113#[deprecated(note = "renamed to company_auth (ADR-0005)")]
114pub use company::company_auth as tenant_auth;
115
116// Re-export generic traits
117pub use permissions::{
118    PermissionLike, RoleLike, PermissionChecker,
119    SimplePermission, SimpleRole, InMemoryPermissionService,
120    // Backwards compatibility
121    Permission, Role, PermissionService,
122};
123
124pub use traits::{
125    AuthenticatableUser, SimpleUser,
126    UserRepository, SecurityService,
127    // Backwards compatibility
128    User,
129    // Other types
130    RefreshTokenClaims, DeviceInfo, SecurityFlags, SecurityAlertType,
131    PasswordPolicy, TwoFactorMethod, TwoFactorChallenge,
132    PasswordResetRequest, PasswordResetConfirmation, AuthRequest, AuthResultEnhanced,
133};
134
135/// Request forensics (IP, user agent, device fingerprint, session) captured at authentication time.
136///
137/// Renamed on re-export: this used to be exported as `AuthContext`, which collided with the identity
138/// context of the same name in `middleware` and silently shadowed it at the crate root — code that
139/// wrote `use backbone_auth::AuthContext` and then read `.permissions` did not compile. Reach for
140/// `AuthContext` for *who the caller is*, and this for *where the request came from*.
141pub use traits::AuthContext as RequestAuthContext;
142
143pub use resource_policy::{
144    ResourceAction, ResourcePolicy, AccessDenied,
145    // Simple policy-only guard (used in tests and simple scenarios)
146    PermissionGuard,
147    // Generic service-integrated guard (used in generated module code)
148    ServicePermissionGuard, AuthContextProvider,
149    PermitAllResourcePolicy, DenyAllResourcePolicy, RoleRequiredPolicy,
150};
151
152/// Auth version
153pub const VERSION: &str = env!("CARGO_PKG_VERSION");
backbone_auth/lib.rs

backbone_auth/
lib.rs
