atproto_oauth_aip/

workflow.rs

//! # OAuth 2.0 Workflow Implementation for AT Protocol Identity Providers
//!
//! This module provides a complete OAuth 2.0 authorization code flow implementation
//! specifically designed for AT Protocol Identity Providers (AIPs). It handles the
//! three main phases of OAuth authentication: initialization, completion, and session exchange.
//!
//! ## Workflow Overview
//!
//! The OAuth workflow consists of three main functions that handle different phases:
//!
//! 1. **Initialization (`oauth_init`)**: Creates a Pushed Authorization Request (PAR)
//!    and returns the authorization URL for user consent
//! 2. **Completion (`oauth_complete`)**: Exchanges the authorization code for access tokens
//! 3. **Session Exchange (`session_exchange`)**: Converts OAuth tokens to AT Protocol sessions
//!
//! ## Security Features
//!
//! - **Pushed Authorization Requests (PAR)**: Enhanced security by storing authorization
//!   parameters server-side rather than in redirect URLs
//! - **PKCE (Proof Key for Code Exchange)**: Protection against authorization code
//!   interception attacks
//! - **DPoP (Demonstration of Proof-of-Possession)**: Cryptographic binding of tokens
//!   to specific keys for enhanced security
//!
//! ## Usage Example
//!
//! ```rust,no_run
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! use atproto_oauth_aip::workflow::{oauth_init, oauth_complete, session_exchange, OAuthClient};
//! use atproto_oauth::resources::{AuthorizationServer, OAuthProtectedResource};
//! use atproto_oauth::workflow::{OAuthRequestState, OAuthRequest};
//!
//! let http_client = reqwest::Client::new();
//!
//! // 1. Initialize OAuth flow
//! let oauth_client = OAuthClient {
//!     redirect_uri: "https://myapp.com/callback".to_string(),
//!     client_id: "my_client_id".to_string(),
//!     client_secret: "my_client_secret".to_string(),
//! };
//!
//! # let authorization_server = AuthorizationServer {
//! #     issuer: "https://auth.example.com".to_string(),
//! #     authorization_endpoint: "https://auth.example.com/authorize".to_string(),
//! #     token_endpoint: "https://auth.example.com/token".to_string(),
//! #     pushed_authorization_request_endpoint: "https://auth.example.com/par".to_string(),
//! #     introspection_endpoint: "".to_string(),
//! #     scopes_supported: vec!["atproto".to_string(), "transition:generic".to_string()],
//! #     response_types_supported: vec!["code".to_string()],
//! #     grant_types_supported: vec!["authorization_code".to_string(), "refresh_token".to_string()],
//! #     token_endpoint_auth_methods_supported: vec!["none".to_string(), "private_key_jwt".to_string()],
//! #     token_endpoint_auth_signing_alg_values_supported: vec!["ES256".to_string()],
//! #     require_pushed_authorization_requests: true,
//! #     request_parameter_supported: false,
//! #     code_challenge_methods_supported: vec!["S256".to_string()],
//! #     authorization_response_iss_parameter_supported: true,
//! #     dpop_signing_alg_values_supported: vec!["ES256".to_string()],
//! #     client_id_metadata_document_supported: true,
//! # };
//!
//! let oauth_request_state = OAuthRequestState {
//!     state: "random-state".to_string(),
//!     nonce: "random-nonce".to_string(),
//!     code_challenge: "code-challenge".to_string(),
//!     scope: "atproto transition:generic".to_string(),
//! };
//!
//! let par_response = oauth_init(
//!     &http_client,
//!     &oauth_client,
//!     Some("user.bsky.social"),
//!     &authorization_server,
//!     &oauth_request_state
//! ).await?;
//!
//! // User visits auth_url and grants consent, returns with authorization code
//!
//! // 2. Complete OAuth flow
//! # let oauth_request = OAuthRequest {
//! #     oauth_state: "state".to_string(),
//! #     issuer: "https://auth.example.com".to_string(),
//! #     did: "did:plc:example".to_string(),
//! #     nonce: "nonce".to_string(),
//! #     signing_public_key: "public_key".to_string(),
//! #     pkce_verifier: "verifier".to_string(),
//! #     dpop_private_key: "private_key".to_string(),
//! #     created_at: chrono::Utc::now(),
//! #     expires_at: chrono::Utc::now() + chrono::Duration::hours(1),
//! # };
//! let token_response = oauth_complete(
//!     &http_client,
//!     &oauth_client,
//!     &authorization_server,
//!     "received_auth_code",
//!     &oauth_request
//! ).await?;
//!
//! // 3. Exchange for AT Protocol session
//! # let protected_resource = OAuthProtectedResource {
//! #     resource: "https://pds.example.com".to_string(),
//! #     scopes_supported: vec!["atproto".to_string()],
//! #     bearer_methods_supported: vec!["header".to_string()],
//! #     authorization_servers: vec!["https://auth.example.com".to_string()],
//! # };
//! let session = session_exchange(
//!     &http_client,
//!     &protected_resource,
//!     &token_response.access_token
//! ).await?;
//! # Ok(())
//! # }
//! ```
//!
//! ## Error Handling
//!
//! All functions return `Result<T, OAuthWorkflowError>` with detailed error information
//! for each phase of the OAuth flow including network failures, parsing errors,
//! and protocol violations.

use anyhow::Result;
use atproto_oauth::{
    resources::{AuthorizationServer, OAuthProtectedResource},
    workflow::{OAuthRequest, OAuthRequestState, ParResponse, TokenResponse},
};
use serde::Deserialize;

use crate::errors::OAuthWorkflowError;

#[cfg(feature = "zeroize")]
use zeroize::{Zeroize, ZeroizeOnDrop};

/// OAuth client configuration containing essential client credentials.
#[cfg_attr(feature = "zeroize", derive(Zeroize, ZeroizeOnDrop))]
pub struct OAuthClient {
    /// The redirect URI where the authorization server will send the user after authorization.
    #[cfg_attr(feature = "zeroize", zeroize(skip))]
    pub redirect_uri: String,

    /// The unique client identifier for this OAuth client.
    #[cfg_attr(feature = "zeroize", zeroize(skip))]
    pub client_id: String,

    /// The client secret used for authenticating with the authorization server.
    pub client_secret: String,
}

#[derive(Clone, Deserialize)]
#[serde(untagged)]
enum WrappedParResponse {
    ParResponse(ParResponse),
    Error {
        error: String,
        error_description: Option<String>,
    },
}

/// Represents an authenticated AT Protocol session.
///
/// This structure contains all the information needed to make authenticated
/// requests to AT Protocol services after a successful OAuth flow.
#[derive(Clone, Deserialize)]
#[cfg_attr(feature = "zeroize", derive(Zeroize, ZeroizeOnDrop))]
pub struct ATProtocolSession {
    /// The Decentralized Identifier (DID) of the authenticated user.
    #[cfg_attr(feature = "zeroize", zeroize(skip))]
    pub did: String,

    /// The handle (username) of the authenticated user.
    #[cfg_attr(feature = "zeroize", zeroize(skip))]
    pub handle: String,

    /// The OAuth access token for making authenticated requests.
    pub access_token: String,

    /// The type of token (typically "Bearer").
    pub token_type: String,

    /// The list of OAuth scopes granted to this session.
    #[cfg_attr(feature = "zeroize", zeroize(skip))]
    pub scopes: Vec<String>,

    /// The Personal Data Server (PDS) endpoint URL for this user.
    #[cfg_attr(feature = "zeroize", zeroize(skip))]
    pub pds_endpoint: String,

    /// The DPoP (Demonstration of Proof-of-Possession) key in JWK format.
    pub dpop_key: String,

    /// Unix timestamp indicating when this session expires.
    #[cfg_attr(feature = "zeroize", zeroize(skip))]
    pub expires_at: i64,
}

#[derive(Deserialize, Clone)]
#[cfg_attr(feature = "zeroize", derive(Zeroize, ZeroizeOnDrop))]
#[serde(untagged)]
enum WrappedATProtocolSession {
    ATProtocolSession(ATProtocolSession),

    #[cfg_attr(feature = "zeroize", zeroize(skip))]
    Error {
        error: String,
        error_description: Option<String>,
    },
}

/// Initiates an OAuth authorization flow using Pushed Authorization Request (PAR).
///
/// This function starts the OAuth flow by sending a PAR request to the authorization
/// server. PAR allows the client to push the authorization request parameters to the
/// authorization server before redirecting the user, providing enhanced security.
///
/// # Arguments
///
/// * `http_client` - The HTTP client to use for making requests
/// * `oauth_client` - OAuth client configuration with credentials
/// * `handle` - Optional user handle to pre-fill in the login form
/// * `authorization_server` - Authorization server metadata
/// * `oauth_request_state` - OAuth request state including PKCE challenge and state
///
/// # Returns
///
/// Returns a `ParResponse` containing the request URI to redirect the user to,
/// or an error if the PAR request fails.
///
/// # Example
///
/// ```no_run
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// use atproto_oauth_aip::workflow::{oauth_init, OAuthClient};
/// use atproto_oauth::workflow::OAuthRequestState;
/// # let http_client = reqwest::Client::new();
/// let oauth_client = OAuthClient {
///     redirect_uri: "https://example.com/callback".to_string(),
///     client_id: "client123".to_string(),
///     client_secret: "secret456".to_string(),
/// };
/// # let authorization_server = todo!();
/// let oauth_request_state = OAuthRequestState {
///     state: "random-state".to_string(),
///     nonce: "random-nonce".to_string(),
///     code_challenge: "code-challenge".to_string(),
///     scope: "atproto transition:generic".to_string(),
/// };
/// let par_response = oauth_init(
///     &http_client,
///     &oauth_client,
///     Some("alice.bsky.social"),
///     &authorization_server,
///     &oauth_request_state,
/// ).await?;
/// # Ok(())
/// # }
/// ```
pub async fn oauth_init(
    http_client: &reqwest::Client,
    oauth_client: &OAuthClient,
    handle: Option<&str>,
    authorization_server: &AuthorizationServer,
    oauth_request_state: &OAuthRequestState,
) -> Result<ParResponse> {
    let par_url = authorization_server
        .pushed_authorization_request_endpoint
        .clone();

    let scope = &oauth_request_state.scope;

    let mut params = vec![
        ("client_id", oauth_client.client_id.as_str()),
        ("code_challenge_method", "S256"),
        ("code_challenge", &oauth_request_state.code_challenge),
        ("redirect_uri", oauth_client.redirect_uri.as_str()),
        ("response_type", "code"),
        ("scope", scope),
        ("state", oauth_request_state.state.as_str()),
    ];
    if let Some(value) = handle {
        params.push(("login_hint", value));
    }

    let response: WrappedParResponse = http_client
        .post(par_url)
        .form(&params)
        .basic_auth(
            oauth_client.client_id.as_str(),
            Some(oauth_client.client_secret.as_str()),
        )
        .send()
        .await
        .map_err(OAuthWorkflowError::ParRequestFailed)?
        .json()
        .await
        .map_err(OAuthWorkflowError::ParResponseParseFailed)?;

    match response {
        WrappedParResponse::ParResponse(value) => Ok(value),
        WrappedParResponse::Error {
            error,
            error_description,
        } => {
            let error_message = if let Some(value) = error_description {
                format!("{error}: {value}")
            } else {
                error.to_string()
            };
            Err(OAuthWorkflowError::ParResponseInvalid {
                message: error_message,
            }
            .into())
        }
    }
}

/// Completes the OAuth authorization flow by exchanging the authorization code for tokens.
///
/// After the user has authorized the application and been redirected back with an
/// authorization code, this function exchanges that code for access tokens using
/// the token endpoint.
///
/// # Arguments
///
/// * `http_client` - The HTTP client to use for making requests
/// * `oauth_client` - OAuth client configuration with credentials
/// * `authorization_server` - Authorization server metadata
/// * `callback_code` - The authorization code received in the callback
/// * `oauth_request` - The original OAuth request containing the PKCE verifier
///
/// # Returns
///
/// Returns a `TokenResponse` containing the access token and other token information,
/// or an error if the token exchange fails.
///
/// # Example
///
/// ```no_run
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// use atproto_oauth_aip::workflow::oauth_complete;
/// # let http_client = reqwest::Client::new();
/// # let oauth_client = todo!();
/// # let authorization_server = todo!();
/// # let oauth_request = todo!();
/// let token_response = oauth_complete(
///     &http_client,
///     &oauth_client,
///     &authorization_server,
///     "auth_code_from_callback",
///     &oauth_request,
/// ).await?;
/// println!("Access token: {}", token_response.access_token);
/// # Ok(())
/// # }
/// ```
pub async fn oauth_complete(
    http_client: &reqwest::Client,
    oauth_client: &OAuthClient,
    authorization_server: &AuthorizationServer,
    callback_code: &str,
    oauth_request: &OAuthRequest,
) -> Result<TokenResponse> {
    let params = [
        ("client_id", oauth_client.client_id.as_str()),
        ("redirect_uri", oauth_client.redirect_uri.as_str()),
        ("grant_type", "authorization_code"),
        ("code", callback_code),
        ("code_verifier", &oauth_request.pkce_verifier),
    ];

    http_client
        .post(&authorization_server.token_endpoint)
        .basic_auth(
            oauth_client.client_id.as_str(),
            Some(oauth_client.client_secret.as_str()),
        )
        .form(&params)
        .send()
        .await
        .map_err(OAuthWorkflowError::TokenRequestFailed)?
        .json()
        .await
        .map_err(|e| OAuthWorkflowError::TokenResponseParseFailed(e).into())
}

/// Exchanges an OAuth access token for an AT Protocol session.
///
/// This function takes an OAuth access token and exchanges it for a full
/// AT Protocol session, which includes additional information like the user's
/// DID, handle, and PDS endpoint. This is specific to AT Protocol's OAuth
/// implementation.
///
/// # Arguments
///
/// * `http_client` - The HTTP client to use for making requests
/// * `protected_resource` - The protected resource metadata
/// * `access_token` - The OAuth access token to exchange
///
/// # Returns
///
/// Returns an `ATProtocolSession` with full session information,
/// or an error if the session exchange fails.
///
/// # Example
///
/// ```no_run
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// use atproto_oauth_aip::workflow::session_exchange;
/// # let http_client = reqwest::Client::new();
/// # let protected_resource = todo!();
/// # let access_token = "example_token";
/// let session = session_exchange(
///     &http_client,
///     &protected_resource,
///     access_token,
/// ).await?;
/// println!("Authenticated as {} ({})", session.handle, session.did);
/// println!("PDS endpoint: {}", session.pds_endpoint);
/// # Ok(())
/// # }
/// ```
pub async fn session_exchange(
    http_client: &reqwest::Client,
    protected_resource: &OAuthProtectedResource,
    access_token: &str,
) -> Result<ATProtocolSession> {
    let response = http_client
        .get(format!(
            "{}/api/atprotocol/session",
            protected_resource.resource
        ))
        .bearer_auth(access_token)
        .send()
        .await
        .map_err(OAuthWorkflowError::SessionRequestFailed)?
        .json()
        .await
        .map_err(OAuthWorkflowError::SessionResponseParseFailed)?;

    match response {
        WrappedATProtocolSession::ATProtocolSession(ref value) => Ok(value.clone()),
        WrappedATProtocolSession::Error {
            ref error,
            ref error_description,
        } => {
            let error_message = if let Some(value) = error_description {
                format!("{error}: {value}")
            } else {
                error.to_string()
            };
            Err(OAuthWorkflowError::SessionResponseInvalid {
                message: error_message,
            }
            .into())
        }
    }
}