authen 0.1.0

A robust, modular, high-level, and secure authentication crate for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

//! Token management module.
//!
//! This module provides the core abstractions and types for handling authentication tokens,
//! including creation, validation, and refreshing of access and refresh tokens. It defines
//! the `TokenPair` struct, the `TokenService` trait for token operations, and re-exports
//! submodules for claims and JWT handling.
//!
//! # Overview
//!
//! - **TokenPair**: Represents a pair of access and refresh tokens.
//! - **TokenService**: Trait for generating, validating, and refreshing tokens.
//! - **claims**: Submodule for token claims definitions.
//! - **jwt**: Submodule for JWT-specific logic.
//!
//! # Example
//!
//! ```rust
//! use crate::core::token::{TokenService, TokenPair};
//! # struct MyTokenService;
//! # #[async_trait::async_trait]
//! # impl TokenService for MyTokenService {
//! #     async fn generate_token_pair(&self, user_id: &str) -> Result<TokenPair, crate::error::AuthError> { todo!() }
//! #     async fn validate_access_token(&self, token: &str) -> Result<Box<dyn crate::core::token::claims::Claims + Send + Sync>, crate::error::AuthError> { todo!() }
//! #     async fn refresh_access_token(&self, refresh_token: &str) -> Result<TokenPair, crate::error::AuthError> { todo!() }
//! # }
//! # async fn example() {
//! let service = MyTokenService;
//! let tokens = service.generate_token_pair("user123").await.unwrap();
//! let claims = service.validate_access_token(&tokens.access_token).await.unwrap();
//! let refreshed = service.refresh_access_token(&tokens.refresh_token).await.unwrap();
//! # }
//! ```

use crate::error::AuthError;

/// Represents a pair of authentication tokens.
///
/// This struct contains both the access token and the refresh token as strings.
/// The access token is typically used for authenticating API requests, while the
/// refresh token is used to obtain new access tokens when the current one expires.
///
/// # Fields
///
/// - `access_token`: The short-lived token used for authenticating requests.
/// - `refresh_token`: The long-lived token used to refresh the access token.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct TokenPair {
    pub access_token: String,
    pub refresh_token: String,
}

/// Trait for token service operations.
///
/// This trait abstracts the main operations required for token-based authentication systems.
/// Implementors are responsible for generating, validating, and refreshing authentication tokens.
///
/// # Safety
///
/// All methods are asynchronous and must be thread-safe (`Send + Sync`).
///
/// # Example
///
/// ```rust
/// # use crate::core::token::{TokenService, TokenPair};
/// # struct MyTokenService;
/// # #[async_trait::async_trait]
/// # impl TokenService for MyTokenService {
/// #     async fn generate_token_pair(&self, user_id: &str) -> Result<TokenPair, crate::error::AuthError> { todo!() }
/// #     async fn validate_access_token(&self, token: &str) -> Result<Box<dyn crate::core::token::claims::Claims + Send + Sync>, crate::error::AuthError> { todo!() }
/// #     async fn refresh_access_token(&self, refresh_token: &str) -> Result<TokenPair, crate::error::AuthError> { todo!() }
/// # }
/// ```
#[async_trait::async_trait]
pub trait TokenService: Send + Sync {
    /// Generates a new token pair for a given user.
    ///
    /// # Arguments
    ///
    /// * `user_id` - The unique identifier of the user for whom the tokens are generated.
    ///
    /// # Returns
    ///
    /// * `Ok(TokenPair)` containing the access and refresh tokens if successful.
    /// * `Err(AuthError)` if token generation fails.
    async fn generate_token_pair(&self, user_id: &str) -> Result<TokenPair, AuthError>;

    /// Validates an access token and extracts its claims.
    ///
    /// # Arguments
    ///
    /// * `token` - The access token string to validate.
    ///
    /// # Returns
    ///
    /// * `Ok(Box<dyn Claims>)` containing the extracted claims if the token is valid.
    /// * `Err(AuthError)` if validation fails or the token is invalid/expired.
    async fn validate_access_token(
        &self,
        token: &str,
    ) -> Result<Box<dyn crate::core::token::claims::Claims + Send + Sync>, AuthError>;

    /// Refreshes an access token using a refresh token.
    ///
    /// # Arguments
    ///
    /// * `refresh_token` - The refresh token string used to obtain a new token pair.
    ///
    /// # Returns
    ///
    /// * `Ok(TokenPair)` containing the new access and refresh tokens if successful.
    /// * `Err(AuthError)` if the refresh token is invalid or expired.
    async fn refresh_access_token(&self, refresh_token: &str) -> Result<TokenPair, AuthError>;
}

/// Submodule for default claims for JWTs.
///
/// Contains traits and types for representing and validating claims in tokens.
pub mod claims;

/// Submodule for JWT implementation and utilities.
///
/// Contains logic for encoding, decoding, and verifying JWTs.
pub mod jwt;