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 jwt;
38pub mod password;
39pub mod permissions;
40pub mod middleware;
41pub mod token_generator;
42pub mod traits;
43pub mod resource_policy;
44#[cfg(feature = "axum")]
45pub mod audience;
46#[cfg(feature = "axum")]
47pub mod company;
48#[cfg(feature = "axum")]
49pub mod idempotency;
50#[cfg(feature = "axum")]
51pub mod org;
52
53// Re-export commonly used types
54pub use audit::AuditEvent;
55pub use auth_service::*;
56pub use jwt::*;
57pub use password::*;
58// `AuthContext` here is the IDENTITY context (`user_id` / `roles` / `permissions`) — the one
59// `ResourcePolicy` and every generated `*_auth.rs` checks against. `traits` has a same-named struct
60// carrying request forensics; it is re-exported below as `RequestAuthContext` so `AuthContext`
61// resolves to exactly one type at this crate's root.
62pub use middleware::{AuthMiddleware, AuthExtractor, AuthContext};
63pub use token_generator::TokenGenerator;
64
65/// The HTTP company guard (feature `axum`): derive `company_id` from a signed token, never a request body.
66#[cfg(feature = "axum")]
67pub use company::{company_auth, CompanyClaims, CompanyContext, CompanyVerifier};
68/// The org-tree session guard and its issuer (feature `axum`, ADR-0028): acting unit +
69/// entitlements from a signed token; the issuer mints the pair the guard trusts.
70#[cfg(feature = "axum")]
71pub use org::{
72 org_auth, OrgClaims, OrgContext, OrgIssuer, OrgVerifier, TOKEN_TYPE_ACCESS,
73 TOKEN_TYPE_REFRESH,
74};
75/// Tenant binding of session tokens (feature `axum`): the `aud` claim against the request's tenant.
76#[cfg(feature = "axum")]
77pub use audience::AudienceSource;
78#[cfg(feature = "axum")]
79pub use idempotency::{IdempotencyState, idempotency_middleware, migrate as migrate_idempotency};
80
81// ── Backward-compatibility aliases (deprecated) ──
82//
83// These were `Tenant*` until ADR-0005 established that `company_id` is a legal-entity/books boundary,
84// not the tenant (the tenant is the database). The rename is a breaking change for downstream
85// consumers pinned to `main` — e.g. serpa-posman-service references `TenantVerifier`. These aliases
86// keep such consumers compiling on sync, with a deprecation warning and a migration path. Remove them
87// once no consumer references the old names.
88#[cfg(feature = "axum")]
89#[deprecated(note = "renamed to CompanyContext (ADR-0005: company_id is a legal-entity boundary, not the tenant)")]
90pub use company::CompanyContext as TenantContext;
91#[cfg(feature = "axum")]
92#[deprecated(note = "renamed to CompanyVerifier (ADR-0005)")]
93pub use company::CompanyVerifier as TenantVerifier;
94#[cfg(feature = "axum")]
95#[deprecated(note = "renamed to CompanyClaims (ADR-0005)")]
96pub use company::CompanyClaims as TenantClaims;
97#[cfg(feature = "axum")]
98#[deprecated(note = "renamed to company_auth (ADR-0005)")]
99pub use company::company_auth as tenant_auth;
100
101// Re-export generic traits
102pub use permissions::{
103 PermissionLike, RoleLike, PermissionChecker,
104 SimplePermission, SimpleRole, InMemoryPermissionService,
105 // Backwards compatibility
106 Permission, Role, PermissionService,
107};
108
109pub use traits::{
110 AuthenticatableUser, SimpleUser,
111 UserRepository, SecurityService,
112 // Backwards compatibility
113 User,
114 // Other types
115 RefreshTokenClaims, DeviceInfo, SecurityFlags, SecurityAlertType,
116 PasswordPolicy, TwoFactorMethod, TwoFactorChallenge,
117 PasswordResetRequest, PasswordResetConfirmation, AuthRequest, AuthResultEnhanced,
118};
119
120/// Request forensics (IP, user agent, device fingerprint, session) captured at authentication time.
121///
122/// Renamed on re-export: this used to be exported as `AuthContext`, which collided with the identity
123/// context of the same name in `middleware` and silently shadowed it at the crate root — code that
124/// wrote `use backbone_auth::AuthContext` and then read `.permissions` did not compile. Reach for
125/// `AuthContext` for *who the caller is*, and this for *where the request came from*.
126pub use traits::AuthContext as RequestAuthContext;
127
128pub use resource_policy::{
129 ResourceAction, ResourcePolicy, AccessDenied,
130 // Simple policy-only guard (used in tests and simple scenarios)
131 PermissionGuard,
132 // Generic service-integrated guard (used in generated module code)
133 ServicePermissionGuard, AuthContextProvider,
134 PermitAllResourcePolicy, DenyAllResourcePolicy, RoleRequiredPolicy,
135};
136
137/// Auth version
138pub const VERSION: &str = env!("CARGO_PKG_VERSION");