aura_authentication/lib.rs
1#![allow(clippy::disallowed_methods, clippy::disallowed_types)]
2//! # Aura Authenticate - Layer 5: Feature/Protocol Implementation
3//!
4//! **Purpose**: Authority, threshold, and guardian authentication protocols.
5//!
6//! Complete end-to-end authentication protocols using the guard chain pattern.
7//! Provides `AuthService` for authentication operations with pure guard evaluation
8//! and explicit effect execution.
9//!
10//! # Architecture Constraints
11//!
12//! **Layer 5 depends on aura-core, aura-effects, aura-composition, aura-protocol, aura-mpst, and domain crates**.
13//! - MUST build on orchestration layer (aura-protocol)
14//! - MUST compose effects from aura-effects and aura-composition
15//! - MUST implement end-to-end protocol logic
16//! - MUST NOT implement effect handlers (that's aura-effects)
17//! - MUST NOT implement orchestration primitives (that's aura-protocol)
18//! - MUST NOT do UI or CLI concerns (that's Layer 7)
19//!
20//! # Core Protocols
21//!
22//! - Challenge-Response Authentication: Request → Challenge → Proof → Session
23//! - Session Management: Time-limited capabilities with scope restrictions
24//! - Guardian Authentication: M-of-N guardian approval for recovery operations
25//! - Distributed Key Derivation: Multi-party key generation without revealing shares
26//!
27//! # Design Principles
28//!
29//! - **Guard Chain Pattern**: Pure evaluation over `GuardSnapshot` → `GuardOutcome` → `EffectCommand` execution
30//! - **Fact-Based State**: All state changes recorded as immutable `AuthFact` records
31//! - **View Derivation**: State derived from facts via `AuthViewReducer`
32//! - **Capability Verification**: Guard-based capability checking before operations
33//! - **Authority-Centric**: Uses `AuthorityId` as the primary identity type
34//!
35//! # Module Organization
36//!
37//! - [`guards`]: Pure guard types (`GuardSnapshot`, `GuardOutcome`, `EffectCommand`, `RecoveryContext`)
38//! - [`facts`]: Domain fact types (`AuthFact`, `AuthFactReducer`, `AuthFactDelta`)
39//! - [`service`]: Main `AuthService` with guard chain integration
40//! - [`view`]: View types (`AuthView`, `AuthViewReducer`) for deriving state from facts
41//! - [`guardian_auth_relational`]: Relational context-based guardian authentication
42//! - [`dkd`]: Distributed Key Derivation protocol
43//!
44//! See `docs/102_authority_and_identity.md` for the authority model documentation.
45
46#![allow(missing_docs)]
47#![forbid(unsafe_code)]
48
49/// Guard types for authentication operations
50///
51/// Provides `GuardSnapshot`, `GuardOutcome`, `EffectCommand`, and related types
52/// for guard chain integration following the pattern from `aura-invitation`.
53pub mod guards;
54
55/// Typed capability families owned by the authentication domain.
56pub mod capabilities;
57
58/// Domain fact types for authentication state changes
59pub mod facts;
60
61/// Authentication service coordinator
62///
63/// Main service for authentication operations with guard chain integration.
64/// All operations return `GuardOutcome` for the caller to execute.
65pub mod service;
66
67/// View delta and reducer for authentication facts
68///
69/// Provides `AuthView`, `AuthViewReducer`, and related view types
70/// for deriving authentication state from the fact log.
71pub mod view;
72
73/// Guardian authentication via relational contexts
74///
75/// Authority-centric guardian authentication using `RelationalContext`.
76pub mod guardian_auth_relational;
77
78/// Distributed Key Derivation (DKD) protocol implementation
79pub mod dkd;
80
81/// Operation category map (A/B/C) for protocol gating and review.
82///
83/// Note: Categories should be reviewed against `docs/109_operation_categories.md`.
84pub const OPERATION_CATEGORIES: &[(&str, &str)] = &[
85 ("auth:challenge", "A"),
86 ("auth:proof", "A"),
87 ("auth:session-issue", "A"),
88 ("auth:session-revoke", "A"),
89 ("auth:guardian-approval", "C"),
90 ("auth:recovery-complete", "C"),
91];
92
93/// Lookup the operation category (A/B/C) for a given operation.
94pub fn operation_category(operation: &str) -> Option<&'static str> {
95 OPERATION_CATEGORIES
96 .iter()
97 .find(|(op, _)| *op == operation)
98 .map(|(_, category)| *category)
99}
100
101// Re-export core types from aura-core (Layer 1)
102pub use aura_core::{AccountId, AuraError, AuraResult, Journal};
103
104// Re-export verification types from aura-signature (Layer 2)
105pub use aura_signature::session::{SessionScope, SessionTicket};
106pub use aura_signature::{
107 AuthenticationError, IdentityProof, KeyMaterial, Result as AuthenticationResult,
108 VerifiedIdentity,
109};
110
111// Re-export Biscuit authorization types
112pub use aura_authorization::{BiscuitTokenManager, ResourceScope, TokenAuthority};
113pub use aura_guards::{BiscuitGuardEvaluator, GuardError, GuardResult};
114
115// Re-export DKD types
116pub use dkd::{
117 create_test_config, execute_simple_dkd, DkdConfig, DkdError, DkdProtocol, DkdResult,
118 DkdSessionId, KeyDerivationContext, ParticipantContribution,
119};
120
121// Re-export guard types
122pub use guards::{
123 check_capability, check_flow_budget, costs, evaluate_request, EffectCommand, GuardDecision,
124 GuardOutcome, GuardRequest, GuardSnapshot, RecoveryContext, RecoveryOperationType,
125};
126
127// Re-export fact types
128pub use facts::{AuthFact, AuthFactDelta, AuthFactReducer, AUTH_FACT_TYPE_ID};
129
130// Re-export service types
131pub use service::{
132 AuthService, AuthServiceConfig, ChallengeResult, GuardianApprovalResult, SessionResult,
133};
134
135// Re-export view types
136pub use view::{
137 AuthView, AuthViewReducer, ChallengeInfo, FailureRecord, RecoveryInfo, SessionInfo,
138};
139
140/// Re-exports for DkdChoreography runners
141pub mod dkd_runners {
142 pub use crate::dkd::telltale_session_types_dkd_protocol::dkd_protocol::runners::{
143 execute_as, run_initiator, run_participant, InitiatorOutput, ParticipantOutput,
144 };
145 pub use crate::dkd::telltale_session_types_dkd_protocol::dkd_protocol::DkdChoreographyRole;
146}
147
148/// Re-exports for GuardianAuthRelational choreography runners
149pub mod guardian_auth_runners {
150 pub use crate::guardian_auth_relational::telltale_session_types_guardian_auth_relational::guardian_auth_relational::GuardianAuthRelationalRole;
151 pub use crate::guardian_auth_relational::telltale_session_types_guardian_auth_relational::guardian_auth_relational::runners::{
152 execute_as, run_account, run_coordinator, run_guardian,
153 AccountOutput, CoordinatorOutput, GuardianOutput,
154 };
155}