fraiseql_auth/oauth/

client.rs

//! OAuth2 and OIDC client implementations.

use std::{sync::Arc, time::Duration as StdDuration};

/// Timeout for all outbound OAuth2 / OIDC HTTP requests.
pub(crate) const OAUTH_REQUEST_TIMEOUT: StdDuration = StdDuration::from_secs(30);

use std::fmt::Write as _;

use serde::{Deserialize, Serialize};
use zeroize::Zeroizing;

use super::{
    super::jwks::{JwksCache, JwksError},
    pkce::{PKCEChallenge, gen_random_token},
    types::{IdTokenClaims, TokenResponse, UserInfo},
};

/// OIDC provider configuration
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct OIDCProviderConfig {
    /// Provider issuer URL
    pub issuer:                   String,
    /// Authorization endpoint
    pub authorization_endpoint:   String,
    /// Token endpoint
    pub token_endpoint:           String,
    /// Userinfo endpoint
    pub userinfo_endpoint:        Option<String>,
    /// JWKS URI for public keys
    pub jwks_uri:                 String,
    /// Scopes supported by provider
    pub scopes_supported:         Vec<String>,
    /// Response types supported
    pub response_types_supported: Vec<String>,
}

impl OIDCProviderConfig {
    /// Create new provider configuration
    #[must_use]
    pub fn new(
        issuer: String,
        authorization_endpoint: String,
        token_endpoint: String,
        jwks_uri: String,
    ) -> Self {
        Self {
            issuer,
            authorization_endpoint,
            token_endpoint,
            userinfo_endpoint: None,
            jwks_uri,
            scopes_supported: vec![
                "openid".to_string(),
                "profile".to_string(),
                "email".to_string(),
            ],
            response_types_supported: vec!["code".to_string()],
        }
    }
}

/// Result of [`OAuth2Client::authorization_url`].
///
/// The caller MUST store `state` (for CSRF verification at callback), when
/// present the PKCE `pkce.code_verifier` (for token exchange), and when
/// present the `nonce` value (must be verified against the ID token at
/// callback via [`OIDCClient::verify_id_token`]).
#[derive(Debug, Clone)]
pub struct AuthorizationRequest {
    /// The full authorization URL to redirect the user to.
    pub url:   String,
    /// CSRF state value — verify this matches the `state` query param at callback.
    pub state: String,
    /// PKCE challenge, present only when `use_pkce = true`.
    pub pkce:  Option<PKCEChallenge>,
    /// OIDC nonce for replay protection.
    ///
    /// Present only when the authorization URL was generated by
    /// [`OIDCClient::authorization_url`].  The caller must store this value
    /// and pass `Some(&nonce.nonce)` to [`OIDCClient::verify_id_token`] at
    /// callback time.
    pub nonce: Option<super::pkce::NonceParameter>,
}

/// OAuth2 client for authorization code flow.
#[derive(Clone)]
pub struct OAuth2Client {
    /// Client ID from provider.
    pub client_id:              String,
    /// Client secret from provider.
    /// Stored as `Zeroizing<String>` so the key material is wiped from memory
    /// when this struct is dropped.
    pub(crate) client_secret:   Zeroizing<String>,
    /// Authorization endpoint.
    pub authorization_endpoint: String,
    /// Token endpoint.
    token_endpoint:             String,
    /// Registered redirect URI.
    ///
    /// When set, `exchange_code` validates that the caller-supplied `redirect_uri`
    /// matches this value (exact match after trailing-`/` trim) before issuing
    /// the token request.  This prevents an attacker who can influence the
    /// `redirect_uri` parameter from steering the code exchange to an
    /// unregistered destination (open-redirect / code-interception attack).
    redirect_uri:               Option<String>,
    /// Scopes to request.
    pub scopes:                 Vec<String>,
    /// Use PKCE for additional security.
    pub use_pkce:               bool,
    /// HTTP client for token requests.
    http_client:                reqwest::Client,
}

/// Custom `Debug` that redacts the client secret.
#[allow(clippy::missing_fields_in_debug)] // Reason: http_client omitted intentionally (not useful in debug output)
impl std::fmt::Debug for OAuth2Client {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("OAuth2Client")
            .field("client_id", &self.client_id)
            .field("client_secret", &"[REDACTED]")
            .field("authorization_endpoint", &self.authorization_endpoint)
            .field("scopes", &self.scopes)
            .field("use_pkce", &self.use_pkce)
            .finish_non_exhaustive()
    }
}

impl OAuth2Client {
    /// Maximum byte size accepted from an OAuth token endpoint response.
    ///
    /// A well-formed token response (access_token, id_token, refresh_token) is a
    /// few kilobytes at most.  1 MiB prevents a malicious provider from sending a
    /// response large enough to exhaust server memory.
    pub(crate) const MAX_OAUTH_RESPONSE_BYTES: usize = 1024 * 1024;

    /// Create new OAuth2 client.
    pub fn new(
        client_id: impl Into<String>,
        client_secret: impl Into<String>,
        authorization_endpoint: impl Into<String>,
        token_endpoint: impl Into<String>,
    ) -> Self {
        Self {
            client_id:              client_id.into(),
            client_secret:          Zeroizing::new(client_secret.into()),
            authorization_endpoint: authorization_endpoint.into(),
            token_endpoint:         token_endpoint.into(),
            redirect_uri:           None,
            scopes:                 vec![
                "openid".to_string(),
                "profile".to_string(),
                "email".to_string(),
            ],
            use_pkce:               false,
            http_client:            reqwest::Client::builder()
                .timeout(OAUTH_REQUEST_TIMEOUT)
                .build()
                .unwrap_or_default(),
        }
    }

    /// Register the expected redirect URI.
    ///
    /// When set, [`Self::exchange_code`] validates that the caller-supplied
    /// `redirect_uri` exactly matches this value (after stripping trailing `/`)
    /// before issuing the token request.  This prevents open-redirect and
    /// authorization-code-interception attacks.
    ///
    /// Call this builder method immediately after construction for any client
    /// that will call `exchange_code` with a caller-supplied redirect URI.
    pub fn with_redirect_uri(mut self, uri: impl Into<String>) -> Self {
        self.redirect_uri = Some(uri.into());
        self
    }

    /// Set scopes for request.
    #[must_use]
    pub fn with_scopes(mut self, scopes: Vec<String>) -> Self {
        self.scopes = scopes;
        self
    }

    /// Enable PKCE protection.
    #[must_use]
    pub const fn with_pkce(mut self, enabled: bool) -> Self {
        self.use_pkce = enabled;
        self
    }

    /// Generate authorization URL.
    ///
    /// Returns an [`AuthorizationRequest`] containing the URL, the CSRF state
    /// value (must be stored and verified at callback), and an optional PKCE
    /// challenge (when `use_pkce = true`; the `code_verifier` must be stored
    /// and sent during token exchange).
    #[must_use]
    pub fn authorization_url(&self, redirect_uri: &str) -> AuthorizationRequest {
        // SECURITY: 32-byte OsRng → 43-char URL-safe base64 (~256-bit entropy, RFC 7636 §4.1)
        let state = gen_random_token();
        let scope = self.scopes.join(" ");

        let mut url = format!(
            "{}?client_id={}&redirect_uri={}&response_type=code&scope={}&state={}",
            self.authorization_endpoint,
            urlencoding::encode(&self.client_id),
            urlencoding::encode(redirect_uri),
            urlencoding::encode(&scope),
            urlencoding::encode(&state),
        );

        let pkce = if self.use_pkce {
            let challenge = PKCEChallenge::new();
            let _ = write!(
                url,
                "&code_challenge={}&code_challenge_method=S256",
                urlencoding::encode(&challenge.code_challenge),
            );
            Some(challenge)
        } else {
            None
        };

        AuthorizationRequest {
            url,
            state,
            pkce,
            nonce: None,
        }
    }

    // 1 MiB

    /// Post a form request to the token endpoint and parse the response.
    async fn post_token_request(&self, params: &[(&str, &str)]) -> Result<TokenResponse, String> {
        let response = self
            .http_client
            .post(&self.token_endpoint)
            .form(params)
            .send()
            .await
            .map_err(|e| format!("Token request failed: {e}"))?;

        // Read the entire body once so we can apply a size cap regardless of
        // whether the response is a success or an error.
        let status = response.status();
        let body_bytes = response
            .bytes()
            .await
            .map_err(|e| format!("Failed to read token response body: {e}"))?;

        if !status.is_success() {
            let capped = &body_bytes[..body_bytes.len().min(Self::MAX_OAUTH_RESPONSE_BYTES)];
            let body = String::from_utf8_lossy(capped);
            return Err(format!("Token endpoint returned error: {body}"));
        }

        if body_bytes.len() > Self::MAX_OAUTH_RESPONSE_BYTES {
            return Err(format!(
                "Token response body too large ({} bytes, max {})",
                body_bytes.len(),
                Self::MAX_OAUTH_RESPONSE_BYTES
            ));
        }

        serde_json::from_slice::<TokenResponse>(&body_bytes)
            .map_err(|e| format!("Failed to parse token response: {e}"))
    }

    /// Exchange authorization code for tokens.
    ///
    /// # Errors
    ///
    /// Returns an error if the HTTP request to the token endpoint fails or the response
    /// cannot be parsed as a `TokenResponse`.
    pub async fn exchange_code(
        &self,
        code: &str,
        redirect_uri: &str,
    ) -> Result<TokenResponse, String> {
        // SECURITY: If a registered redirect URI was set via with_redirect_uri(),
        // validate the caller-supplied value before it reaches the token endpoint.
        // Exact match after trailing-slash trim — no prefix or scheme stripping.
        if let Some(registered) = &self.redirect_uri {
            if registered.trim_end_matches('/') != redirect_uri.trim_end_matches('/') {
                return Err(format!(
                    "redirect_uri mismatch: supplied '{}' does not match registered '{}'",
                    redirect_uri, registered
                ));
            }
        }
        let params = [
            ("grant_type", "authorization_code"),
            ("code", code),
            ("client_id", self.client_id.as_str()),
            ("client_secret", self.client_secret.as_str()),
            ("redirect_uri", redirect_uri),
        ];
        self.post_token_request(&params).await
    }

    /// Refresh access token using a refresh token.
    ///
    /// # Errors
    ///
    /// Propagates errors from the token endpoint request (network failure,
    /// non-2xx HTTP status, oversized response body, or JSON parse error).
    pub async fn refresh_token(&self, refresh_token: &str) -> Result<TokenResponse, String> {
        let params = [
            ("grant_type", "refresh_token"),
            ("refresh_token", refresh_token),
            ("client_id", self.client_id.as_str()),
            ("client_secret", self.client_secret.as_str()),
        ];
        self.post_token_request(&params).await
    }
}

/// Asymmetric signing algorithms permitted for OIDC ID tokens.
///
/// OIDC providers MUST use asymmetric signing so the relying party can verify
/// signatures without possessing key material that could forge tokens.
/// Symmetric algorithms (HS*) are forbidden on this path — see
/// [`FORBIDDEN_OIDC_ALGORITHMS`].
///
/// Reference: RFC 8725 §2.1, OpenID Connect Core §10.1.
pub const ALLOWED_OIDC_ALGORITHMS: &[jsonwebtoken::Algorithm] = &[
    jsonwebtoken::Algorithm::RS256,
    jsonwebtoken::Algorithm::RS384,
    jsonwebtoken::Algorithm::RS512,
    jsonwebtoken::Algorithm::ES256,
    jsonwebtoken::Algorithm::ES384,
];

/// Symmetric algorithms explicitly forbidden on the OIDC ID token path.
///
/// An OIDC provider that issues tokens with a symmetric algorithm is either
/// misconfigured or an attacker performing an algorithm-substitution attack
/// (RFC 8725 §2.1).  Any token header claiming one of these algorithms is
/// rejected with [`crate::error::AuthError::ForbiddenAlgorithm`] before
/// signature verification is attempted.
pub const FORBIDDEN_OIDC_ALGORITHMS: &[jsonwebtoken::Algorithm] = &[
    jsonwebtoken::Algorithm::HS256,
    jsonwebtoken::Algorithm::HS384,
    jsonwebtoken::Algorithm::HS512,
];

/// Required `typ` header value for OIDC ID tokens (RFC 7519 §5.1, RFC 8725 §3.11).
///
/// When the `typ` header is present it MUST equal `"JWT"` (case-insensitive).
/// A token with a different `typ` (e.g., `"at+JWT"` for access tokens) is
/// rejected to prevent token-type confusion attacks.
pub const REQUIRED_JWT_TYP: &str = "JWT";

/// JWT header parameters that must never appear in a legitimate OIDC ID token.
///
/// These fields (`jku`, `jwk`, `x5u`, `x5c`) could steer key resolution in a
/// vulnerable JWT library to an attacker-controlled endpoint (RFC 8725 §2.6).
/// The `jsonwebtoken` crate ignores them for key resolution, so this guard is
/// defence-in-depth: their presence in any token issued by a compliant OIDC
/// provider is anomalous and indicates a crafted or malicious token.
///
/// Note on `crit` (RFC 7515 §4.1.11): the `jsonwebtoken` v9 `Header` struct
/// does not expose a `crit` field.  The crate's decoder handles unknown
/// extensions at the decode level, so no explicit `crit` guard is required.
pub const FORBIDDEN_KEY_INJECTION_HEADERS: &[&str] = &["jku", "jwk", "x5u", "x5c"];

/// OIDC client for OpenID Connect flow.
pub struct OIDCClient {
    /// Provider configuration.
    pub config:               OIDCProviderConfig,
    /// Client ID.
    pub client_id:            String,
    /// Client secret — retained for token revocation and introspection endpoints.
    /// Stored as `Zeroizing<String>` so the key material is wiped from memory
    /// when this struct is dropped.
    #[allow(dead_code)] // Reason: retained for token revocation and introspection endpoints
    pub(crate) client_secret: Zeroizing<String>,
    /// JWKS key cache for ID token signature verification.
    pub jwks_cache:           Arc<JwksCache>,
    /// HTTP client for userinfo requests.
    http_client:              reqwest::Client,
}

/// Custom `Debug` that redacts the client secret.
#[allow(clippy::missing_fields_in_debug)] // Reason: http_client omitted intentionally (not useful in debug output)
impl std::fmt::Debug for OIDCClient {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("OIDCClient")
            .field("config", &self.config)
            .field("client_id", &self.client_id)
            .field("client_secret", &"[REDACTED]")
            .finish_non_exhaustive()
    }
}

impl OIDCClient {
    /// Maximum byte size for a userinfo endpoint response.
    ///
    /// Userinfo payloads carry a small set of JWT-derived claims.
    /// 1 `MiB` is generous while blocking allocation-bomb responses.
    pub(crate) const MAX_USERINFO_RESPONSE_BYTES: usize = 1024 * 1024;

    // 1 MiB

    /// Create new OIDC client with JWKS caching.
    ///
    /// The JWKS cache TTL defaults to 1 hour.
    ///
    /// # Errors
    ///
    /// Returns [`JwksError`] if `config.jwks_uri` is not a valid HTTPS URL
    /// (HTTP is allowed only for localhost).
    pub fn new(
        config: OIDCProviderConfig,
        client_id: impl Into<String>,
        client_secret: impl Into<String>,
    ) -> Result<Self, JwksError> {
        let jwks_cache = Arc::new(JwksCache::new(&config.jwks_uri, StdDuration::from_secs(3600))?);
        Ok(Self {
            config,
            client_id: client_id.into(),
            client_secret: Zeroizing::new(client_secret.into()),
            jwks_cache,
            http_client: reqwest::Client::builder()
                .timeout(OAUTH_REQUEST_TIMEOUT)
                .build()
                .unwrap_or_default(),
        })
    }

    /// Create OIDC client with a pre-built JWKS cache (for testing).
    pub fn with_jwks_cache(
        config: OIDCProviderConfig,
        client_id: impl Into<String>,
        client_secret: impl Into<String>,
        jwks_cache: Arc<JwksCache>,
    ) -> Self {
        Self {
            config,
            client_id: client_id.into(),
            client_secret: Zeroizing::new(client_secret.into()),
            jwks_cache,
            http_client: reqwest::Client::builder()
                .timeout(OAUTH_REQUEST_TIMEOUT)
                .build()
                .unwrap_or_default(),
        }
    }

    /// Generate an OIDC authorization URL with a fresh nonce for replay protection.
    ///
    /// This extends the standard OAuth2 flow by appending a `nonce` parameter to
    /// the authorization URL. The returned [`AuthorizationRequest::nonce`] **must**
    /// be stored (e.g. in the encrypted session state) and passed to
    /// [`verify_id_token`](Self::verify_id_token) at callback time.
    ///
    /// PKCE is always enabled for OIDC flows started via this method.
    #[must_use]
    pub fn authorization_url(&self, redirect_uri: &str) -> AuthorizationRequest {
        // SECURITY: 32-byte OsRng → 43-char URL-safe base64 (~256-bit entropy, RFC 7636 §4.1)
        let state = gen_random_token();
        let scope = self.config.scopes_supported.join(" ");
        let nonce = super::pkce::NonceParameter::new();
        let challenge = PKCEChallenge::new();

        let url = format!(
            "{}?client_id={}&redirect_uri={}&response_type=code&scope={}&state={}\
             &nonce={}&code_challenge={}&code_challenge_method=S256",
            self.config.authorization_endpoint,
            urlencoding::encode(&self.client_id),
            urlencoding::encode(redirect_uri),
            urlencoding::encode(&scope),
            urlencoding::encode(&state),
            urlencoding::encode(&nonce.nonce),
            urlencoding::encode(&challenge.code_challenge),
        );

        AuthorizationRequest {
            url,
            state,
            pkce: Some(challenge),
            nonce: Some(nonce),
        }
    }

    /// Verify an ID token's JWT signature and claims.
    ///
    /// Decodes the JWT header to extract the `kid`, fetches the matching public
    /// key from the JWKS cache, then validates signature, issuer, audience, and
    /// required claims.
    ///
    /// **Nonce**: when `expected_nonce` is `Some`, the token's `nonce` claim must
    /// match exactly.  When it is `None` but the token *contains* a `nonce` claim,
    /// validation still succeeds — callers that generated the authorization URL
    /// via [`authorization_url`](Self::authorization_url) MUST pass the stored
    /// nonce here.
    ///
    /// **`max_age`**: when `max_age_secs` is `Some`, the token's `auth_time` claim
    /// is required and must be within `max_age_secs` seconds of the current time.
    /// This prevents accepting tokens from sessions that were authenticated too
    /// long ago (RFC 6749 §3.1.2.1 / OIDC Core §3.1.2.1).
    ///
    /// # Errors
    ///
    /// Returns an error if the token is malformed, the signature is invalid,
    /// claims validation fails, the nonce doesn't match, or the `auth_time` /
    /// `max_age` constraint is violated.
    pub async fn verify_id_token(
        &self,
        id_token: &str,
        expected_nonce: Option<&str>,
        max_age_secs: Option<u64>,
    ) -> Result<IdTokenClaims, String> {
        // 1. Decode header to get kid
        let header = jsonwebtoken::decode_header(id_token)
            .map_err(|e| format!("Invalid JWT header: {e}"))?;

        // 1a. Algorithm whitelist (S41 — RFC 8725 §2.1): reject forbidden symmetric algorithms
        //     and any algorithm not in the OIDC allowlist before touching the JWKS cache.
        if FORBIDDEN_OIDC_ALGORITHMS.contains(&header.alg) {
            let alg_str = format!("{:?}", header.alg);
            return Err(format!("Forbidden OIDC algorithm: {alg_str}"));
        }
        if !ALLOWED_OIDC_ALGORITHMS.contains(&header.alg) {
            let alg_str = format!("{:?}", header.alg);
            return Err(format!("OIDC algorithm not in allowlist: {alg_str}"));
        }

        // 1b. typ header assertion (S41 — RFC 8725 §3.11 / RFC 7519 §5.1): when present,
        //     `typ` must equal "JWT" (case-insensitive) to prevent token-type confusion.
        if let Some(ref typ) = header.typ {
            if typ.to_uppercase() != REQUIRED_JWT_TYP {
                return Err(format!(
                    "Unexpected JWT typ header '{typ}': expected '{REQUIRED_JWT_TYP}'"
                ));
            }
        }

        // 1c. Key-injection header rejection (S42 — RFC 8725 §2.6): reject tokens that
        //     carry jku, jwk, x5u, or x5c headers.  In a vulnerable JWT library these
        //     fields can steer key resolution to an attacker-controlled endpoint.  The
        //     `jsonwebtoken` crate ignores them for key resolution (defence-in-depth),
        //     but their presence in an OIDC ID token is anomalous — no compliant provider
        //     sets them — and the only correct response is rejection.
        //     See also: FORBIDDEN_KEY_INJECTION_HEADERS constant.
        if header.jku.is_some()
            || header.jwk.is_some()
            || header.x5u.is_some()
            || header.x5c.is_some()
        {
            return Err("JWT header contains forbidden key-injection parameter".to_string());
        }

        let kid = header.kid.ok_or("JWT missing 'kid' in header")?;

        // 2. Get key from JWKS cache
        let key = self
            .jwks_cache
            .get_key(&kid)
            .await
            .map_err(|e| format!("JWKS fetch error: {e}"))?
            .ok_or_else(|| format!("No key found for kid '{kid}'"))?;

        // 3. Build validation criteria
        let mut validation = jsonwebtoken::Validation::new(header.alg);
        validation.set_issuer(&[&self.config.issuer]);
        validation.set_audience(&[&self.client_id]);
        validation.set_required_spec_claims(&["exp", "iat", "iss", "aud", "sub"]);

        // 4. Decode and validate
        let token_data = jsonwebtoken::decode::<IdTokenClaims>(id_token, &key, &validation)
            .map_err(|e| format!("ID token validation failed: {e}"))?;
        let claims = token_data.claims;

        // 4.5. Validate temporal claims: iat staleness/skew and nbf not-before (S40).
        claims
            .validate_temporal_claims()
            .map_err(|e| format!("ID token temporal validation failed: {e}"))?;

        // 5. Verify nonce using constant-time comparison (replay protection — RFC 6749 §10.12 /
        //    OIDC Core §3.1.3.7).
        if let Some(expected) = expected_nonce {
            super::claims_validator::validate_nonce_claim(&claims, expected)
                .map_err(|e| e.to_string())?;
        }

        // 6. Validate auth_time against max_age (OIDC Core §3.1.2.1).
        if let Some(max_age) = max_age_secs {
            let now_secs = std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map_or(i64::MAX, |d| i64::try_from(d.as_secs()).unwrap_or(i64::MAX));
            super::claims_validator::validate_auth_time_claim(&claims, max_age, now_secs)
                .map_err(|e| e.to_string())?;
        }

        Ok(claims)
    }

    /// Fetch user information from the provider's userinfo endpoint.
    ///
    /// # Errors
    ///
    /// Returns an error if no userinfo endpoint is configured, the HTTP request
    /// fails, or the response cannot be parsed.
    pub async fn get_userinfo(&self, access_token: &str) -> Result<UserInfo, String> {
        let endpoint = self
            .config
            .userinfo_endpoint
            .as_ref()
            .ok_or("No userinfo endpoint configured for this provider")?;

        let response = self
            .http_client
            .get(endpoint)
            .bearer_auth(access_token)
            .send()
            .await
            .map_err(|e| format!("Userinfo request failed: {e}"))?;

        if !response.status().is_success() {
            return Err(format!("Userinfo endpoint returned {}", response.status()));
        }

        let body = response
            .bytes()
            .await
            .map_err(|e| format!("Failed to read userinfo response: {e}"))?;
        if body.len() > Self::MAX_USERINFO_RESPONSE_BYTES {
            return Err(format!(
                "Userinfo response too large ({} bytes, max {})",
                body.len(),
                Self::MAX_USERINFO_RESPONSE_BYTES
            ));
        }
        serde_json::from_slice::<UserInfo>(&body)
            .map_err(|e| format!("Failed to parse userinfo response: {e}"))
    }
}