fraiseql_auth/
multi_provider.rs

1//! Multi-provider authentication — unified entry point for social login.
2//!
3//! Enables `GET /auth/v1/authorize?provider=github&redirect_uri=...` with
4//! automatic provider resolution and state-encoded provider tracking through
5//! the OAuth callback.
6
7use std::{collections::HashMap, sync::Arc};
8
9use axum::{
10    Json,
11    extract::{Query, State},
12    http::StatusCode,
13    response::{IntoResponse, Redirect, Response},
14};
15use serde::{Deserialize, Serialize};
16
17use crate::{
18    account_linking::AccountStore, handlers::generate_secure_state, provider::OAuthProvider,
19    session::SessionStore, state_store::StateStore,
20};
21
22/// Maximum length for the `redirect_uri` query parameter.
23const MAX_REDIRECT_URI_BYTES: usize = 2_048;
24
25/// Maximum length for the `provider` query parameter.
26const MAX_PROVIDER_NAME_BYTES: usize = 128;
27
28/// Shared state for the multi-provider auth endpoints.
29#[derive(Clone)]
30pub struct MultiProviderAuthState {
31    /// OAuth providers keyed by name (e.g., "github", "google").
32    providers:     HashMap<String, Arc<dyn OAuthProvider>>,
33    /// CSRF state store (in-memory or Redis).
34    state_store:   Arc<dyn StateStore>,
35    /// Session backend for creating sessions after successful auth.
36    session_store: Arc<dyn SessionStore>,
37    /// Optional user store for account linking (same email → same user).
38    user_store:    Option<Arc<dyn AccountStore>>,
39}
40
41impl MultiProviderAuthState {
42    /// Create a new multi-provider auth state.
43    pub fn new(state_store: Arc<dyn StateStore>, session_store: Arc<dyn SessionStore>) -> Self {
44        Self {
45            providers: HashMap::new(),
46            state_store,
47            session_store,
48            user_store: None,
49        }
50    }
51
52    /// Set the user store for account linking.
53    ///
54    /// When set, the callback handler uses [`AccountStore::link_or_create_user`] to
55    /// resolve provider identities to local users, enabling automatic account
56    /// linking when the same email appears across different providers.
57    pub fn with_user_store(mut self, user_store: Arc<dyn AccountStore>) -> Self {
58        self.user_store = Some(user_store);
59        self
60    }
61
62    /// Register an OAuth provider under the given name.
63    pub fn register_provider(&mut self, name: impl Into<String>, provider: Arc<dyn OAuthProvider>) {
64        self.providers.insert(name.into(), provider);
65    }
66
67    /// List the names of all registered providers.
68    #[must_use]
69    pub fn provider_names(&self) -> Vec<String> {
70        let mut names: Vec<String> = self.providers.keys().cloned().collect();
71        names.sort();
72        names
73    }
74
75    /// Look up a provider by name.
76    #[must_use]
77    pub fn get_provider(&self, name: &str) -> Option<&Arc<dyn OAuthProvider>> {
78        self.providers.get(name)
79    }
80}
81
82// ---------------------------------------------------------------------------
83// Query / response types
84// ---------------------------------------------------------------------------
85
86/// Query parameters for `GET /auth/v1/authorize`.
87#[derive(Debug, Deserialize)]
88pub struct AuthorizeQuery {
89    /// Provider name (e.g., "github", "google").
90    pub provider:     String,
91    /// Client application callback URI.
92    pub redirect_uri: String,
93}
94
95/// Query parameters for `GET /auth/v1/callback`.
96#[derive(Debug, Deserialize)]
97pub struct CallbackQuery {
98    /// Authorization code from the provider.
99    pub code:              Option<String>,
100    /// CSRF state token.
101    pub state:             Option<String>,
102    /// Provider error code.
103    pub error:             Option<String>,
104    /// Provider error description.
105    pub error_description: Option<String>,
106}
107
108/// Response for `GET /auth/v1/providers`.
109#[derive(Debug, Serialize)]
110pub struct ProvidersResponse {
111    /// Available provider names.
112    pub providers: Vec<String>,
113}
114
115/// Token response returned after a successful callback.
116#[derive(Debug, Serialize)]
117pub struct AuthTokenResponse {
118    /// Access token for API requests.
119    pub access_token:  String,
120    /// Refresh token (if available).
121    #[serde(skip_serializing_if = "Option::is_none")]
122    pub refresh_token: Option<String>,
123    /// Token type (always "Bearer").
124    pub token_type:    String,
125    /// Seconds until the access token expires.
126    pub expires_in:    u64,
127    /// Provider that authenticated the user.
128    pub provider:      String,
129}
130
131impl AuthTokenResponse {
132    /// Returns a builder for `AuthTokenResponse`.
133    #[must_use = "builder does nothing until .build() is called"]
134    pub fn builder() -> AuthTokenResponseBuilder {
135        AuthTokenResponseBuilder::default()
136    }
137}
138
139/// Builder for [`AuthTokenResponse`].
140#[derive(Debug, Default)]
141pub struct AuthTokenResponseBuilder {
142    access_token:  Option<String>,
143    refresh_token: Option<String>,
144    token_type:    Option<String>,
145    expires_in:    Option<u64>,
146    provider:      Option<String>,
147}
148
149impl AuthTokenResponseBuilder {
150    /// Sets the access token.
151    pub fn access_token(mut self, access_token: impl Into<String>) -> Self {
152        self.access_token = Some(access_token.into());
153        self
154    }
155
156    /// Sets the refresh token.
157    pub fn refresh_token(mut self, refresh_token: impl Into<String>) -> Self {
158        self.refresh_token = Some(refresh_token.into());
159        self
160    }
161
162    /// Sets the token type (typically `"Bearer"`).
163    pub fn token_type(mut self, token_type: impl Into<String>) -> Self {
164        self.token_type = Some(token_type.into());
165        self
166    }
167
168    /// Sets the number of seconds until the access token expires.
169    #[must_use = "builder method returns modified builder"]
170    pub const fn expires_in(mut self, expires_in: u64) -> Self {
171        self.expires_in = Some(expires_in);
172        self
173    }
174
175    /// Sets the provider that authenticated the user.
176    pub fn provider(mut self, provider: impl Into<String>) -> Self {
177        self.provider = Some(provider.into());
178        self
179    }
180
181    /// Builds the [`AuthTokenResponse`].
182    ///
183    /// # Errors
184    ///
185    /// Returns an error string if any required field (`access_token`, `token_type`,
186    /// `expires_in`, or `provider`) was not set.
187    pub fn build(self) -> Result<AuthTokenResponse, String> {
188        Ok(AuthTokenResponse {
189            access_token:  self
190                .access_token
191                .ok_or("AuthTokenResponse: access_token is required")?,
192            refresh_token: self.refresh_token,
193            token_type:    self.token_type.ok_or("AuthTokenResponse: token_type is required")?,
194            expires_in:    self.expires_in.ok_or("AuthTokenResponse: expires_in is required")?,
195            provider:      self.provider.ok_or("AuthTokenResponse: provider is required")?,
196        })
197    }
198}
199
200// ---------------------------------------------------------------------------
201// Helpers
202// ---------------------------------------------------------------------------
203
204fn json_error(status: StatusCode, message: &str) -> Response {
205    (status, Json(serde_json::json!({ "error": message }))).into_response()
206}
207
208// ---------------------------------------------------------------------------
209// GET /auth/v1/providers
210// ---------------------------------------------------------------------------
211
212/// List available authentication providers.
213///
214/// # Responses
215///
216/// - `200` JSON `{ providers: ["github", "google", ...] }`
217pub async fn list_providers(
218    State(state): State<Arc<MultiProviderAuthState>>,
219) -> Json<ProvidersResponse> {
220    Json(ProvidersResponse {
221        providers: state.provider_names(),
222    })
223}
224
225// ---------------------------------------------------------------------------
226// GET /auth/v1/authorize
227// ---------------------------------------------------------------------------
228
229/// Initiate the OAuth flow for a specific provider.
230///
231/// Generates a CSRF state token, stores it with the provider name, then
232/// redirects to the provider's authorization URL.
233///
234/// # Query parameters
235///
236/// - `provider` — **required**: provider name (must match a registered provider).
237/// - `redirect_uri` — **required**: client application callback URI.
238///
239/// # Responses
240///
241/// - `302` — redirect to the provider's authorization endpoint.
242/// - `400` — missing or invalid parameters, unknown provider.
243///
244/// # Errors
245///
246/// Returns a `400` JSON error if the provider is unknown, redirect_uri is empty/oversized,
247/// or the state store is at capacity.
248pub async fn authorize(
249    State(state): State<Arc<MultiProviderAuthState>>,
250    Query(q): Query<AuthorizeQuery>,
251) -> Response {
252    // Validate provider name length
253    if q.provider.len() > MAX_PROVIDER_NAME_BYTES {
254        return json_error(StatusCode::BAD_REQUEST, "provider name exceeds maximum length");
255    }
256
257    // Validate redirect_uri
258    if q.redirect_uri.is_empty() {
259        return json_error(StatusCode::BAD_REQUEST, "redirect_uri is required");
260    }
261    if q.redirect_uri.len() > MAX_REDIRECT_URI_BYTES {
262        return json_error(StatusCode::BAD_REQUEST, "redirect_uri exceeds maximum length");
263    }
264
265    // Look up provider
266    let Some(provider) = state.get_provider(&q.provider) else {
267        return json_error(StatusCode::BAD_REQUEST, &format!("unknown provider: {}", q.provider));
268    };
269
270    // Generate state and store with provider name
271    let state_value = generate_secure_state();
272
273    let Ok(now) = std::time::SystemTime::now()
274        .duration_since(std::time::UNIX_EPOCH)
275        .map(|d| d.as_secs())
276    else {
277        return json_error(StatusCode::INTERNAL_SERVER_ERROR, "system clock error");
278    };
279
280    let expiry = now + 600; // 10 minutes
281
282    if let Err(e) = state.state_store.store(state_value.clone(), q.provider.clone(), expiry).await {
283        tracing::error!("state store failed: {e}");
284        return json_error(
285            StatusCode::INTERNAL_SERVER_ERROR,
286            "authorization flow could not be started",
287        );
288    }
289
290    // Generate authorization URL
291    let authorization_url = provider.authorization_url(&state_value);
292
293    Redirect::to(&authorization_url).into_response()
294}
295
296// ---------------------------------------------------------------------------
297// GET /auth/v1/callback
298// ---------------------------------------------------------------------------
299
300/// Complete the OAuth flow after the provider redirects back.
301///
302/// Validates the state token, resolves the provider from the stored state,
303/// exchanges the authorization code for tokens, retrieves user info, and
304/// creates a session.
305///
306/// # Query parameters
307///
308/// - `code` — authorization code from the provider.
309/// - `state` — CSRF state token.
310///
311/// # Responses
312///
313/// - `200` JSON `{ access_token, refresh_token?, token_type, expires_in, provider }`
314/// - `400` — invalid state, missing parameters, or provider error.
315/// - `502` — token exchange with the provider failed.
316///
317/// # Errors
318///
319/// Returns `400` if the state is invalid/expired, code is missing, or the provider
320/// returned an error. Returns `502` if the token exchange or user info fetch fails.
321#[allow(clippy::cognitive_complexity)] // Reason: OAuth callback with state validation, token exchange, user info, and session creation
322pub async fn callback(
323    State(state): State<Arc<MultiProviderAuthState>>,
324    Query(q): Query<CallbackQuery>,
325) -> Response {
326    // Surface provider errors
327    if let Some(err) = q.error {
328        let desc = q.error_description.as_deref().unwrap_or("(no description)");
329        tracing::warn!(provider_error = %err, description = %desc, "OAuth provider returned error");
330        let client_message = match err.as_str() {
331            "access_denied" => "Access was denied",
332            "login_required" => "Authentication is required",
333            "invalid_request" | "invalid_scope" => "Invalid authorization request",
334            "server_error" | "temporarily_unavailable" => "Authorization server error",
335            _ => "Authorization failed",
336        };
337        return json_error(StatusCode::BAD_REQUEST, client_message);
338    }
339
340    // Validate required parameters
341    let (Some(code), Some(state_token)) = (q.code, q.state) else {
342        return json_error(StatusCode::BAD_REQUEST, "missing code or state parameter");
343    };
344
345    // Consume state (atomic remove) and get provider name
346    let Ok((provider_name, expiry)) = state.state_store.retrieve(&state_token).await else {
347        return json_error(StatusCode::BAD_REQUEST, "invalid or expired state token");
348    };
349
350    // Check state expiry
351    let now = std::time::SystemTime::now()
352        .duration_since(std::time::UNIX_EPOCH)
353        .unwrap_or_default()
354        .as_secs();
355
356    if now > expiry {
357        return json_error(StatusCode::BAD_REQUEST, "state token expired");
358    }
359
360    // Look up provider
361    let Some(provider) = state.get_provider(&provider_name) else {
362        tracing::error!(provider = %provider_name, "provider from state not found in registry");
363        return json_error(StatusCode::INTERNAL_SERVER_ERROR, "provider configuration error");
364    };
365
366    // Exchange code for tokens
367    let token_response = match provider.exchange_code(&code).await {
368        Ok(t) => t,
369        Err(e) => {
370            tracing::error!(error = %e, "token exchange failed");
371            return json_error(StatusCode::BAD_GATEWAY, "token exchange with provider failed");
372        },
373    };
374
375    // Get user info from provider
376    let user_info = match provider.user_info(&token_response.access_token).await {
377        Ok(u) => u,
378        Err(e) => {
379            tracing::error!(error = %e, "user info fetch failed");
380            return json_error(StatusCode::BAD_GATEWAY, "failed to retrieve user information");
381        },
382    };
383
384    // Resolve local user ID — use AccountStore for account linking when available,
385    // otherwise fall back to raw provider user ID.
386    let local_user_id = if let Some(account_store) = &state.user_store {
387        match account_store
388            .link_or_create_user(&user_info.email, &provider_name, &user_info.id)
389            .await
390        {
391            Ok(result) => result.user_id,
392            Err(e) => {
393                tracing::error!(error = %e, "account store lookup failed");
394                return json_error(StatusCode::INTERNAL_SERVER_ERROR, "user resolution failed");
395            },
396        }
397    } else {
398        user_info.id.clone()
399    };
400
401    // Create session (7-day expiry)
402    let session_expiry = now + (7 * 24 * 60 * 60);
403    let session_tokens = match state
404        .session_store
405        .create_session(&local_user_id, session_expiry)
406        .await
407    {
408        Ok(t) => t,
409        Err(e) => {
410            tracing::error!(error = %e, "session creation failed");
411            return json_error(StatusCode::INTERNAL_SERVER_ERROR, "session could not be created");
412        },
413    };
414
415    Json(AuthTokenResponse {
416        access_token:  session_tokens.access_token,
417        refresh_token: Some(session_tokens.refresh_token),
418        token_type:    "Bearer".to_string(),
419        expires_in:    session_tokens.expires_in,
420        provider:      provider_name,
421    })
422    .into_response()
423}
424
425// ---------------------------------------------------------------------------
426// Tests
427// ---------------------------------------------------------------------------
fraiseql_auth/multi_provider.rs

fraiseql_auth/
multi_provider.rs
