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

backbone_auth/
lib.rs
