mailledger_oauth/
lib.rs

1//! # mailledger-oauth
2//!
3//! `OAuth2` authentication library for email protocols (IMAP/SMTP).
4//!
5//! ## Features
6//!
7//! - **Authorization flows**: Authorization Code Flow (with PKCE) and Device Flow
8//! - **Token management**: Automatic refresh, expiration checking
9//! - **Provider configurations**: Pre-configured for Gmail, Outlook, Yahoo
10//! - **SASL mechanisms**: OAUTHBEARER (RFC 7628) and XOAUTH2 (proprietary)
11//!
12//! ## Quick Start
13//!
14//! ### Authorization Code Flow (Desktop/Web Apps)
15//!
16//! ```ignore
17//! use mailledger_oauth::{Provider, OAuthClient, AuthorizationCodeFlow};
18//!
19//! #[tokio::main]
20//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
21//!     // Configure for Gmail
22//!     let provider = Provider::google()?;
23//!     let client = OAuthClient::new("your_client_id", provider)
24//!         .with_client_secret("your_secret")
25//!         .with_redirect_uri("http://localhost:8080");
26//!
27//!     // Create flow with PKCE for security
28//!     let flow = AuthorizationCodeFlow::new(client).with_pkce();
29//!
30//!     // Generate authorization URL
31//!     let auth_url = flow.authorization_url(None, Some("random_state"))?;
32//!     println!("Visit: {}", auth_url);
33//!
34//!     // After user authorizes, exchange code for token
35//!     let code = "authorization_code_from_redirect";
36//!     let token = flow.exchange_code(code, None).await?;
37//!
38//!     println!("Access token: {}", token.access_token);
39//!     Ok(())
40//! }
41//! ```
42//!
43//! ### Device Flow (CLI/IoT Apps)
44//!
45//! ```ignore
46//! use mailledger_oauth::{Provider, OAuthClient, DeviceFlow};
47//!
48//! #[tokio::main]
49//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
50//!     let provider = Provider::google()?;
51//!     let client = OAuthClient::new("your_client_id", provider);
52//!     let flow = DeviceFlow::new(client);
53//!
54//!     // Request device authorization
55//!     let auth = flow.request_device_authorization(None).await?;
56//!
57//!     println!("Visit: {}", auth.verification_uri);
58//!     println!("Enter code: {}", auth.user_code);
59//!
60//!     // Poll for token (with automatic retry)
61//!     let (_, token) = flow.authorize(None, 120).await?;
62//!     println!("Authorized! Token: {}", token.access_token);
63//!     Ok(())
64//! }
65//! ```
66//!
67//! ### Using with IMAP/SMTP
68//!
69//! ```ignore
70//! use mailledger_oauth::sasl::{oauthbearer_response, xoauth2_response};
71//!
72//! // OAUTHBEARER (RFC 7628 standard)
73//! let auth_string = oauthbearer_response("user@gmail.com", &token.access_token);
74//! // Send: AUTHENTICATE OAUTHBEARER {auth_string}
75//!
76//! // XOAUTH2 (Google/Microsoft proprietary)
77//! let auth_string = xoauth2_response("user@gmail.com", &token.access_token);
78//! // Send: AUTHENTICATE XOAUTH2 {auth_string}
79//! ```
80//!
81//! ### Token Refresh
82//!
83//! ```ignore
84//! // Check if token needs refresh
85//! if token.is_expired() {
86//!     let new_token = client.refresh_token(&token).await?;
87//!     // Use new_token
88//! }
89//! ```
90//!
91//! ## Provider Support
92//!
93//! - **Gmail** - Full support with `https://mail.google.com/` scope
94//! - **Outlook/Microsoft** - Full support with IMAP/SMTP scopes
95//! - **Yahoo** - Full support with `mail-r` and `mail-w` scopes
96//! - **Custom** - Configure any `OAuth2` provider
97
98#![warn(missing_docs)]
99#![warn(clippy::all)]
100#![warn(clippy::pedantic)]
101#![forbid(unsafe_code)]
102
103mod error;
104pub mod flow;
105pub mod provider;
106pub mod sasl;
107pub mod token;
108
109pub use error::{Error, Result};
110pub use flow::{AuthorizationCodeFlow, DeviceFlow, OAuthClient, PkceChallenge};
111pub use provider::Provider;
112pub use token::Token;
mailledger_oauth/lib.rs

mailledger_oauth/
lib.rs
