riley_auth_api/routes/

oauth_provider.rs

use std::collections::BTreeSet;

use axum::extract::{Query, State};
use axum::http::{HeaderMap, StatusCode};
use axum::response::{IntoResponse, Response};
use axum::routing::{get, post};
use axum::{Form, Json, Router};
use axum_extra::extract::CookieJar;
use base64::{Engine, engine::general_purpose::URL_SAFE_NO_PAD};
use chrono::{Duration, Utc};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use subtle::ConstantTimeEq;

use riley_auth_core::db;
use riley_auth_core::error::{Error, ErrorBody, www_authenticate_value};
use riley_auth_core::jwt;

use crate::server::AppState;

/// OIDC protocol-level scopes that are always accepted without config definition
/// or client allowed_scopes check. These scopes control standard OIDC claim sets.
const PROTOCOL_SCOPES: &[&str] = &["openid", "profile", "email"];

// --- Request/Response types ---

#[derive(Deserialize)]
pub struct AuthorizeQuery {
    client_id: String,
    redirect_uri: String,
    response_type: String,
    scope: Option<String>,
    state: Option<String>,
    code_challenge: Option<String>,
    code_challenge_method: Option<String>,
    nonce: Option<String>,
    prompt: Option<String>,
}

#[derive(Deserialize, utoipa::ToSchema)]
pub struct TokenRequest {
    grant_type: String,
    code: Option<String>,
    redirect_uri: Option<String>,
    client_id: Option<String>,
    client_secret: Option<String>,
    code_verifier: Option<String>,
    refresh_token: Option<String>,
    scope: Option<String>,
}

#[derive(Serialize, utoipa::ToSchema)]
pub struct TokenResponse {
    access_token: String,
    token_type: &'static str,
    expires_in: u64,
    refresh_token: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    id_token: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    scope: Option<String>,
}

#[derive(Deserialize)]
pub struct ConsentQuery {
    consent_id: uuid::Uuid,
}

#[derive(Serialize, utoipa::ToSchema)]
pub struct ConsentResponse {
    client: ConsentClient,
    scopes: Vec<ConsentScope>,
    redirect_uri: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    state: Option<String>,
    expires_at: String,
}

#[derive(Serialize, utoipa::ToSchema)]
pub struct ConsentClient {
    name: String,
    client_id: String,
}

#[derive(Serialize, utoipa::ToSchema)]
pub struct ConsentScope {
    name: String,
    description: String,
}

#[derive(Deserialize, utoipa::ToSchema)]
pub struct ConsentDecision {
    approved: bool,
}

#[derive(Deserialize, utoipa::ToSchema)]
pub struct RevokeRequest {
    token: String,
    client_id: Option<String>,
    client_secret: Option<String>,
}

#[derive(Deserialize, utoipa::ToSchema)]
pub struct IntrospectRequest {
    token: String,
    // Client credentials via POST body (alternative to Basic auth)
    client_id: Option<String>,
    client_secret: Option<String>,
}

/// OAuth protocol routes — NOT CSRF-protected.
/// These are called by external OAuth clients (not browser requests with cookies).
pub fn router() -> Router<AppState> {
    Router::new()
        .route("/oauth/authorize", get(authorize))
        .route("/oauth/token", post(token))
        .route("/oauth/revoke", post(revoke))
        .route("/oauth/introspect", post(introspect))
        .route("/oauth/userinfo", get(userinfo).post(userinfo))
}

/// Consent routes — browser-facing, cookie-authenticated.
/// Should be wrapped with CSRF middleware.
pub fn consent_router() -> Router<AppState> {
    Router::new()
        .route("/oauth/consent", get(consent).post(consent_decision))
}

/// Build an OAuth error redirect per RFC 6749 §4.1.2.1.
///
/// Once `client_id` and `redirect_uri` are validated, all subsequent errors
/// must be communicated back to the client via redirect with query parameters.
fn redirect_error(
    redirect_uri: &str,
    error_code: &str,
    description: &str,
    state: Option<&str>,
) -> Response {
    // If the redirect_uri can't be parsed (shouldn't happen — already validated),
    // fall back to a plain HTTP error.
    let Ok(mut url) = url::Url::parse(redirect_uri) else {
        return Error::InvalidRedirectUri.into_response();
    };
    {
        let mut params = url.query_pairs_mut();
        params.append_pair("error", error_code);
        params.append_pair("error_description", description);
        if let Some(s) = state {
            params.append_pair("state", s);
        }
    }
    // RFC 6749 §4.1.2 specifies 302 Found for authorization redirects.
    // Redirect::temporary() produces 307, which preserves HTTP method.
    // Use explicit 302 for maximum interoperability.
    (StatusCode::FOUND, [("location", url.to_string())]).into_response()
}

/// GET /oauth/authorize — authorization endpoint (RFC 6749 §4.1)
///
/// Error handling follows RFC 6749 §4.1.2.1:
/// - Pre-redirect errors (invalid client_id or redirect_uri): HTTP 400
/// - Post-redirect errors (all others): redirect to redirect_uri with ?error=...
#[utoipa::path(
    get,
    path = "/oauth/authorize",
    tag = "oauth",
    params(
        ("client_id" = String, Query, description = "Client identifier"),
        ("redirect_uri" = String, Query, description = "Redirect URI"),
        ("response_type" = String, Query, description = "Must be 'code'"),
        ("scope" = Option<String>, Query, description = "Space-separated scopes"),
        ("state" = Option<String>, Query, description = "Client state parameter"),
        ("code_challenge" = Option<String>, Query, description = "PKCE code challenge"),
        ("code_challenge_method" = Option<String>, Query, description = "Must be 'S256'"),
        ("nonce" = Option<String>, Query, description = "OIDC nonce"),
        ("prompt" = Option<String>, Query, description = "OIDC prompt (none, login, consent)"),
    ),
    responses(
        (status = 302, description = "Redirect with authorization code or error"),
        (status = 400, description = "Invalid client or redirect URI", body = ErrorBody),
    )
)]
pub(crate) async fn authorize(
    State(state): State<AppState>,
    Query(query): Query<AuthorizeQuery>,
    jar: CookieJar,
) -> Result<Response, Error> {
    // --- Phase 1: Pre-redirect validation (HTTP errors) ---
    // client_id and redirect_uri must be validated FIRST. If either is invalid,
    // we cannot safely redirect and must return an HTTP error directly.

    let client = db::find_client_by_client_id(&state.db, &query.client_id)
        .await?
        .ok_or(Error::InvalidClient)?;

    if !client.redirect_uris.contains(&query.redirect_uri) {
        return Err(Error::InvalidRedirectUri);
    }

    // --- Phase 2: Post-redirect validation (error redirects) ---
    // From here on, all errors redirect back to the client with ?error=...
    let redirect_uri = &query.redirect_uri;
    let state_param = query.state.as_deref();

    // response_type
    if query.response_type != "code" {
        return Ok(redirect_error(
            redirect_uri,
            "unsupported_response_type",
            "response_type must be 'code'",
            state_param,
        ));
    }

    // PKCE is mandatory
    let code_challenge = match query.code_challenge.as_deref() {
        Some(c) => c,
        None => {
            return Ok(redirect_error(
                redirect_uri,
                "invalid_request",
                "code_challenge is required",
                state_param,
            ));
        }
    };
    let method = query.code_challenge_method.as_deref().unwrap_or("S256");
    if method != "S256" {
        return Ok(redirect_error(
            redirect_uri,
            "invalid_request",
            "code_challenge_method must be 'S256'",
            state_param,
        ));
    }

    // Validate and deduplicate requested scopes.
    // OIDC protocol-level scopes (openid, profile, email) are always accepted.
    // Custom/resource scopes must be defined in config and allowed for the client.
    let granted_scopes: Vec<String> = if let Some(ref scope_str) = query.scope {
        let requested: BTreeSet<&str> = scope_str.split_whitespace().collect();
        if requested.is_empty() {
            return Ok(redirect_error(
                redirect_uri,
                "invalid_scope",
                "scope parameter must not be empty",
                state_param,
            ));
        }
        let defined_names: Vec<&str> = state.config.scopes.definitions.iter()
            .map(|d| d.name.as_str())
            .collect();
        for s in &requested {
            if PROTOCOL_SCOPES.contains(s) {
                continue; // OIDC protocol-level, always accepted
            }
            if !defined_names.contains(s) {
                return Ok(redirect_error(
                    redirect_uri,
                    "invalid_scope",
                    &format!("unknown scope: {s}"),
                    state_param,
                ));
            }
            if !client.allowed_scopes.iter().any(|a| a == s) {
                return Ok(redirect_error(
                    redirect_uri,
                    "invalid_scope",
                    &format!("scope not allowed for this client: {s}"),
                    state_param,
                ));
            }
        }
        requested.into_iter().map(String::from).collect()
    } else {
        vec![]
    };

    // Parse and validate prompt parameter (OIDC Core 1.0 Section 3.1.2.1).
    let prompt_values: Vec<&str> = query.prompt.as_deref()
        .map(|p| p.split_whitespace().collect())
        .unwrap_or_default();

    for v in &prompt_values {
        if !["none", "login", "consent"].contains(v) {
            return Ok(redirect_error(
                redirect_uri,
                "invalid_request",
                &format!("unsupported prompt value: {v}"),
                state_param,
            ));
        }
    }
    // "none" must not be combined with other values per OIDC Core 1.0 Section 3.1.2.1.
    if prompt_values.contains(&"none") && prompt_values.len() > 1 {
        return Ok(redirect_error(
            redirect_uri,
            "invalid_request",
            "prompt=none must not be combined with other values",
            state_param,
        ));
    }

    let prompt_none = prompt_values.contains(&"none");
    let prompt_login = prompt_values.contains(&"login");

    // prompt=login: force re-authentication by redirecting to login_url.
    // The authorize request is encoded as a return_to URL so the user
    // returns here (without prompt=login) after re-authenticating.
    if prompt_login {
        match state.config.oauth.login_url.as_deref() {
            Some(login_url) => {
                let Ok(mut login_redirect) = url::Url::parse(login_url) else {
                    tracing::error!(login_url, "configured login_url is not a valid URL");
                    return Ok(redirect_error(
                        redirect_uri, "server_error", "internal error", state_param,
                    ));
                };
                // Build the return-to authorize URL without prompt=login to prevent loops
                let mut return_url = url::Url::parse(&format!(
                    "{}/oauth/authorize", state.config.server.public_url
                )).expect("public_url is a valid URL");
                {
                    let mut params = return_url.query_pairs_mut();
                    params.append_pair("client_id", &query.client_id);
                    params.append_pair("redirect_uri", &query.redirect_uri);
                    params.append_pair("response_type", &query.response_type);
                    if let Some(ref s) = query.scope {
                        params.append_pair("scope", s);
                    }
                    if let Some(ref s) = query.state {
                        params.append_pair("state", s);
                    }
                    if let Some(ref c) = query.code_challenge {
                        params.append_pair("code_challenge", c);
                    }
                    if let Some(ref m) = query.code_challenge_method {
                        params.append_pair("code_challenge_method", m);
                    }
                    if let Some(ref n) = query.nonce {
                        params.append_pair("nonce", n);
                    }
                }
                login_redirect.query_pairs_mut()
                    .append_pair("return_to", return_url.as_str());
                return Ok(
                    (StatusCode::FOUND, [("location", login_redirect.to_string())]).into_response()
                );
            }
            None => {
                return Ok(redirect_error(
                    redirect_uri,
                    "login_required",
                    "re-authentication required but no login_url is configured",
                    state_param,
                ));
            }
        }
    }

    // User must be authenticated (cookie-based) — check BEFORE consent,
    // because consent evaluation requires knowing who the user is.
    let access_token = match jar.get(&state.cookie_names.access) {
        Some(c) => c.value().to_string(),
        None => {
            return Ok(redirect_error(
                redirect_uri,
                "login_required",
                "user is not authenticated",
                state_param,
            ));
        }
    };

    let token_data = match state.keys.verify_session_token(&state.config.jwt, &access_token) {
        Ok(data) => data,
        Err(_) => {
            return Ok(redirect_error(
                redirect_uri,
                "login_required",
                "session is invalid or expired",
                state_param,
            ));
        }
    };

    let user_id: uuid::Uuid = match token_data.claims.sub.parse() {
        Ok(id) => id,
        Err(_) => {
            return Ok(redirect_error(
                redirect_uri,
                "server_error",
                "internal error",
                state_param,
            ));
        }
    };

    // Consent check — must come after authentication so the user is known.
    // For non-auto-approve clients, store the authorization request in the DB
    // and redirect to the deployer's consent URL.
    // prompt=none: must never show UI — return consent_required error redirect
    // instead of redirecting to consent_url.
    if !client.auto_approve {
        if prompt_none {
            return Ok(redirect_error(
                redirect_uri,
                "consent_required",
                "user consent is required",
                state_param,
            ));
        }
        let consent_url = match state.config.oauth.consent_url.as_deref() {
            Some(url) => url,
            None => {
                // No consent_url configured — cannot redirect to consent UI
                return Ok(redirect_error(
                    redirect_uri,
                    "consent_required",
                    "user consent is required but no consent_url is configured",
                    state_param,
                ));
            }
        };

        let expires_at = Utc::now() + Duration::seconds(600); // 10 minutes

        let consent_id = match db::store_consent_request(
            &state.db,
            client.id,
            user_id,
            &granted_scopes,
            &query.redirect_uri,
            query.state.as_deref(),
            query.code_challenge.as_deref(),
            query.code_challenge_method.as_deref(),
            query.nonce.as_deref(),
            expires_at,
        )
        .await
        {
            Ok(id) => id,
            Err(e) => {
                tracing::error!(error = %e, "failed to store consent request");
                return Ok(redirect_error(
                    redirect_uri,
                    "server_error",
                    "internal error",
                    state_param,
                ));
            }
        };

        // Redirect to deployer's consent page with consent_id
        let Ok(mut consent_redirect) = url::Url::parse(consent_url) else {
            tracing::error!(consent_url, "configured consent_url is not a valid URL");
            return Ok(redirect_error(
                redirect_uri,
                "server_error",
                "internal error",
                state_param,
            ));
        };
        consent_redirect
            .query_pairs_mut()
            .append_pair("consent_id", &consent_id.to_string());

        return Ok(
            (StatusCode::FOUND, [("location", consent_redirect.to_string())]).into_response()
        );
    }

    // --- Phase 3: Issue authorization code ---
    let mut code_bytes = [0u8; 32];
    rand::RngCore::fill_bytes(&mut rand::rng(), &mut code_bytes);
    let code = URL_SAFE_NO_PAD.encode(code_bytes);
    let code_hash = jwt::hash_token(&code);

    let expires_at = Utc::now() + Duration::seconds(
        state.config.jwt.authorization_code_ttl_secs as i64,
    );

    if let Err(e) = db::store_authorization_code(
        &state.db,
        &code_hash,
        user_id,
        client.id,
        &query.redirect_uri,
        &granted_scopes,
        Some(code_challenge),
        Some(method),
        query.nonce.as_deref(),
        expires_at,
    )
    .await
    {
        tracing::error!(error = %e, "failed to store authorization code");
        return Ok(redirect_error(
            redirect_uri,
            "server_error",
            "internal error",
            state_param,
        ));
    }

    // Redirect back to client with authorization code
    let mut redirect_url = match url::Url::parse(&query.redirect_uri) {
        Ok(url) => url,
        Err(_) => {
            return Ok(redirect_error(
                redirect_uri,
                "server_error",
                "internal error",
                state_param,
            ));
        }
    };

    {
        let mut params = redirect_url.query_pairs_mut();
        params.append_pair("code", &code);
        if let Some(s) = state_param {
            params.append_pair("state", s);
        }
    }

    Ok((StatusCode::FOUND, [("location", redirect_url.to_string())]).into_response())
}

/// GET /oauth/consent — returns consent context for the deployer's consent UI.
///
/// Requires session cookie + consent_id query parameter. The consent request
/// must exist, not be expired, and belong to the authenticated user.
#[utoipa::path(
    get,
    path = "/oauth/consent",
    tag = "oauth",
    params(("consent_id" = uuid::Uuid, Query, description = "Consent request ID")),
    responses(
        (status = 200, description = "Consent request details", body = ConsentResponse),
        (status = 400, description = "Invalid or expired consent request", body = ErrorBody),
        (status = 401, description = "Not authenticated", body = ErrorBody),
    )
)]
pub(crate) async fn consent(
    State(state): State<AppState>,
    Query(query): Query<ConsentQuery>,
    jar: CookieJar,
) -> Result<Json<ConsentResponse>, Error> {
    // User must be authenticated
    let access_token = jar
        .get(&state.cookie_names.access)
        .map(|c| c.value().to_string())
        .ok_or(Error::Unauthenticated)?;

    let token_data = state.keys.verify_session_token(&state.config.jwt, &access_token)?;

    let user_id: uuid::Uuid = token_data.claims.sub.parse().map_err(|_| Error::InvalidToken)?;

    // Look up the consent request
    let consent_req = db::find_consent_request(&state.db, query.consent_id)
        .await?
        .ok_or(Error::NotFound)?;

    // The consent request must belong to the authenticated user.
    // Return NotFound (not Forbidden) to avoid revealing that the consent_id
    // exists for a different user (oracle prevention).
    if consent_req.user_id != user_id {
        return Err(Error::NotFound);
    }

    // Look up the client (by internal id)
    let client = db::find_client_by_id(&state.db, consent_req.client_id)
        .await?
        .ok_or(Error::InvalidClient)?;

    // Resolve scopes to descriptions.
    // OIDC protocol-level scopes have hardcoded descriptions.
    let mut scopes = Vec::new();
    for s in &consent_req.scopes {
        if s == "openid" {
            continue; // protocol-level, no consent description needed
        }
        if s == "profile" {
            scopes.push(ConsentScope {
                name: "profile".to_string(),
                description: "Read your username, display name, and profile picture".to_string(),
            });
            continue;
        }
        if s == "email" {
            scopes.push(ConsentScope {
                name: "email".to_string(),
                description: "Read your email address".to_string(),
            });
            continue;
        }
        let description = state.config.scopes.definitions.iter()
            .find(|d| d.name == *s)
            .map(|d| d.description.clone())
            .unwrap_or_else(|| s.clone()); // Fallback: use scope name as description
        scopes.push(ConsentScope {
            name: s.clone(),
            description,
        });
    }

    Ok(Json(ConsentResponse {
        client: ConsentClient {
            name: client.name,
            client_id: client.client_id,
        },
        scopes,
        redirect_uri: consent_req.redirect_uri,
        state: consent_req.state,
        expires_at: consent_req.expires_at.to_rfc3339(),
    }))
}

/// POST /oauth/consent — user approves or denies the consent request.
///
/// If approved: issues authorization code and redirects to the client's redirect_uri.
/// If denied: redirects with `?error=access_denied`.
/// Consumes the consent request in either case.
#[utoipa::path(
    post,
    path = "/oauth/consent",
    tag = "oauth",
    params(("consent_id" = uuid::Uuid, Query, description = "Consent request ID")),
    request_body = ConsentDecision,
    responses(
        (status = 302, description = "Redirect to client with code or error"),
        (status = 400, description = "Invalid or expired consent request", body = ErrorBody),
        (status = 401, description = "Not authenticated", body = ErrorBody),
    )
)]
pub(crate) async fn consent_decision(
    State(state): State<AppState>,
    Query(query): Query<ConsentQuery>,
    jar: CookieJar,
    Json(body): Json<ConsentDecision>,
) -> Result<Response, Error> {
    // User must be authenticated
    let access_token = jar
        .get(&state.cookie_names.access)
        .map(|c| c.value().to_string())
        .ok_or(Error::Unauthenticated)?;

    let token_data = state.keys.verify_session_token(&state.config.jwt, &access_token)?;

    let user_id: uuid::Uuid = token_data.claims.sub.parse().map_err(|_| Error::InvalidToken)?;

    // Atomically consume the consent request (one-time use, prevents TOCTOU race).
    // The user_id filter is part of the atomic DELETE so that a wrong user cannot
    // destroy another user's consent request.
    let consent_req = db::consume_consent_request(&state.db, query.consent_id, user_id)
        .await?
        .ok_or(Error::NotFound)?;

    let redirect_uri = &consent_req.redirect_uri;
    let state_param = consent_req.state.as_deref();

    if !body.approved {
        return Ok(redirect_error(
            redirect_uri,
            "access_denied",
            "user denied the authorization request",
            state_param,
        ));
    }

    // Issue authorization code (same logic as auto-approve path in authorize)
    let mut code_bytes = [0u8; 32];
    rand::RngCore::fill_bytes(&mut rand::rng(), &mut code_bytes);
    let code = URL_SAFE_NO_PAD.encode(code_bytes);
    let code_hash = jwt::hash_token(&code);

    let expires_at = Utc::now() + Duration::seconds(
        state.config.jwt.authorization_code_ttl_secs as i64,
    );

    // Look up the client to get the internal id
    let client = db::find_client_by_id(&state.db, consent_req.client_id)
        .await?
        .ok_or(Error::InvalidClient)?;

    // Re-validate redirect_uri against the client's current registered URIs.
    // The URI was validated at authorize time, but the client config may have
    // changed during the consent window (up to 10 minutes).
    if !client.redirect_uris.contains(&consent_req.redirect_uri) {
        return Ok(redirect_error(
            redirect_uri,
            "server_error",
            "redirect_uri no longer registered for this client",
            state_param,
        ));
    }

    if let Err(e) = db::store_authorization_code(
        &state.db,
        &code_hash,
        user_id,
        client.id,
        &consent_req.redirect_uri,
        &consent_req.scopes,
        consent_req.code_challenge.as_deref(),
        consent_req.code_challenge_method.as_deref(),
        consent_req.nonce.as_deref(),
        expires_at,
    )
    .await
    {
        tracing::error!(error = %e, "failed to store authorization code");
        return Ok(redirect_error(
            redirect_uri,
            "server_error",
            "internal error",
            state_param,
        ));
    }

    // Redirect back to client with authorization code
    let mut redirect_url = match url::Url::parse(&consent_req.redirect_uri) {
        Ok(url) => url,
        Err(_) => {
            return Ok(redirect_error(
                redirect_uri,
                "server_error",
                "internal error",
                state_param,
            ));
        }
    };

    {
        let mut params = redirect_url.query_pairs_mut();
        params.append_pair("code", &code);
        if let Some(s) = state_param {
            params.append_pair("state", s);
        }
    }

    Ok((StatusCode::FOUND, [("location", redirect_url.to_string())]).into_response())
}

/// POST /oauth/token — token endpoint
#[utoipa::path(
    post,
    path = "/oauth/token",
    tag = "oauth",
    request_body(content = TokenRequest, content_type = "application/x-www-form-urlencoded"),
    responses(
        (status = 200, description = "Token response", body = TokenResponse),
        (status = 400, description = "Invalid grant or request", body = ErrorBody),
        (status = 401, description = "Invalid client credentials", body = ErrorBody),
    )
)]
pub(crate) async fn token(
    State(state): State<AppState>,
    headers: HeaderMap,
    Form(body): Form<TokenRequest>,
) -> Result<Json<TokenResponse>, Error> {
    // Validate client credentials (Basic auth or POST body)
    let (client_id_str, client_secret) = extract_client_credentials(
        &headers,
        body.client_id.as_deref(),
        body.client_secret.as_deref(),
    )?;

    let client = db::find_client_by_client_id(&state.db, &client_id_str)
        .await?
        .ok_or(Error::InvalidClient)?;

    let secret_hash = jwt::hash_token(&client_secret);
    if secret_hash.as_bytes().ct_eq(client.client_secret_hash.as_bytes()).unwrap_u8() == 0 {
        return Err(Error::InvalidClient);
    }

    match body.grant_type.as_str() {
        "authorization_code" => {
            let code = body.code.as_deref().ok_or(Error::InvalidGrant)?;
            let redirect_uri = body.redirect_uri.as_deref().ok_or(Error::InvalidGrant)?;

            let code_hash = jwt::hash_token(code);

            // Atomically consume the authorization code (prevents TOCTOU race)
            let auth_code = db::consume_authorization_code(&state.db, &code_hash)
                .await?
                .ok_or(Error::InvalidAuthorizationCode)?;

            // Verify redirect_uri matches
            if auth_code.redirect_uri != redirect_uri {
                return Err(Error::InvalidGrant);
            }

            // Verify client matches
            if auth_code.client_id != client.id {
                return Err(Error::InvalidGrant);
            }

            // Verify PKCE (mandatory — code_challenge should always be present)
            let challenge = auth_code.code_challenge.as_deref()
                .ok_or(Error::InvalidGrant)?;
            let verifier = body.code_verifier.as_deref()
                .ok_or(Error::InvalidGrant)?;

            let computed = {
                let mut hasher = Sha256::new();
                hasher.update(verifier.as_bytes());
                URL_SAFE_NO_PAD.encode(hasher.finalize())
            };

            if computed.as_bytes().ct_eq(challenge.as_bytes()).unwrap_u8() == 0 {
                return Err(Error::InvalidGrant);
            }

            // Get user
            let user = db::find_user_by_id(&state.db, auth_code.user_id)
                .await?
                .ok_or(Error::UserNotFound)?;

            // Issue tokens with client_id as audience
            let scope_str = if auth_code.scopes.is_empty() {
                None
            } else {
                Some(auth_code.scopes.join(" "))
            };

            let access_token = state.keys.sign_access_token_with_scopes(
                &state.config.jwt,
                &user.id.to_string(),
                &user.username,
                &user.role,
                &client.client_id,
                scope_str.as_deref(),
            )?;

            let (refresh_raw, refresh_hash) = jwt::generate_refresh_token();
            let family_id = uuid::Uuid::now_v7();
            let expires_at = Utc::now() + Duration::seconds(
                state.config.jwt.refresh_token_ttl_secs as i64,
            );
            let auth_time = Some(auth_code.created_at.timestamp());
            db::store_refresh_token(
                &state.db,
                user.id,
                Some(client.id),
                &refresh_hash,
                expires_at,
                &auth_code.scopes,
                None,
                None,
                family_id,
                auth_code.nonce.as_deref(),
                auth_time,
            )
            .await?;

            // Only issue ID token when openid scope was granted (OIDC Core 1.0)
            let id_token = if auth_code.scopes.iter().any(|s| s == "openid") {
                // Include email claims when email scope is granted (OIDC Core 1.0 §5.4)
                let (email, email_verified) = if auth_code.scopes.iter().any(|s| s == "email") {
                    let links = db::find_oauth_links_by_user(&state.db, user.id).await?;
                    match links.iter().find(|l| l.provider_email.is_some()) {
                        Some(link) => (link.provider_email.clone(), Some(link.email_verified)),
                        None => (None, None),
                    }
                } else {
                    (None, None)
                };
                Some(state.keys.sign_id_token(
                    &state.config.jwt,
                    &user.id.to_string(),
                    &user.username,
                    user.display_name.as_deref(),
                    user.avatar_url.as_deref(),
                    &client.client_id,
                    auth_code.nonce.as_deref(),
                    auth_time,
                    email.as_deref(),
                    email_verified,
                    &auth_code.scopes,
                )?)
            } else {
                None
            };

            Ok(Json(TokenResponse {
                access_token,
                token_type: "Bearer",
                expires_in: state.config.jwt.access_token_ttl_secs,
                refresh_token: refresh_raw,
                id_token,
                scope: scope_str,
            }))
        }
        "refresh_token" => {
            let refresh_raw = body.refresh_token.as_deref()
                .ok_or(Error::InvalidGrant)?;

            let refresh_hash = jwt::hash_token(refresh_raw);

            // Check for token reuse — if this hash was already consumed, revoke the family
            if let Some(family_id) = db::check_token_reuse(&state.db, &refresh_hash).await? {
                db::revoke_token_family(&state.db, family_id).await?;
                return Err(Error::InvalidGrant);
            }

            // Atomically consume a client-bound refresh token (client_id = verified client).
            // This rejects session tokens or other clients' tokens without consuming them,
            // preventing cross-endpoint token destruction.
            let token_row = db::consume_client_refresh_token(&state.db, &refresh_hash, client.id)
                .await?
                .ok_or(Error::InvalidGrant)?;

            let user = db::find_user_by_id(&state.db, token_row.user_id)
                .await?
                .ok_or(Error::UserNotFound)?;

            // Intersect original scopes with client's current allowed_scopes.
            // OIDC protocol-level scopes pass through unconditionally.
            // If an admin revoked a resource scope from the client since the token
            // was issued, the refreshed token will no longer carry that scope.
            let mut effective_scopes: Vec<String> = token_row.scopes.iter()
                .filter(|s| PROTOCOL_SCOPES.contains(&s.as_str()) || client.allowed_scopes.contains(s))
                .cloned()
                .collect();

            // Scope downscoping (RFC 6749 §6): if the client requests a narrower
            // scope set, validate it's a subset of the effective scopes and narrow.
            if let Some(ref requested_scope) = body.scope {
                let requested: BTreeSet<&str> = requested_scope.split_whitespace().collect();
                let effective_set: BTreeSet<&str> = effective_scopes.iter().map(|s| s.as_str()).collect();
                for s in &requested {
                    if !effective_set.contains(s) {
                        return Err(Error::InvalidScope);
                    }
                }
                effective_scopes = requested.into_iter().map(String::from).collect();
            }

            let scope_str = if effective_scopes.is_empty() {
                None
            } else {
                Some(effective_scopes.join(" "))
            };

            let access_token = state.keys.sign_access_token_with_scopes(
                &state.config.jwt,
                &user.id.to_string(),
                &user.username,
                &user.role,
                &client.client_id,
                scope_str.as_deref(),
            )?;

            let (new_refresh_raw, new_refresh_hash) = jwt::generate_refresh_token();
            let expires_at = Utc::now() + Duration::seconds(
                state.config.jwt.refresh_token_ttl_secs as i64,
            );
            db::store_refresh_token(
                &state.db,
                user.id,
                Some(client.id),
                &new_refresh_hash,
                expires_at,
                &effective_scopes,
                None,
                None,
                token_row.family_id,
                token_row.nonce.as_deref(),
                token_row.auth_time,
            )
            .await?;

            // Only issue ID token when openid scope is in the effective scopes.
            // Nonce and auth_time are preserved from the original authorization
            // request across refresh rotations (OIDC Core 1.0 §12.2).
            let id_token = if effective_scopes.iter().any(|s| s == "openid") {
                // Include email claims when email scope is granted (OIDC Core 1.0 §5.4)
                let (email, email_verified) = if effective_scopes.iter().any(|s| s == "email") {
                    let links = db::find_oauth_links_by_user(&state.db, user.id).await?;
                    match links.iter().find(|l| l.provider_email.is_some()) {
                        Some(link) => (link.provider_email.clone(), Some(link.email_verified)),
                        None => (None, None),
                    }
                } else {
                    (None, None)
                };
                Some(state.keys.sign_id_token(
                    &state.config.jwt,
                    &user.id.to_string(),
                    &user.username,
                    user.display_name.as_deref(),
                    user.avatar_url.as_deref(),
                    &client.client_id,
                    token_row.nonce.as_deref(),
                    token_row.auth_time,
                    email.as_deref(),
                    email_verified,
                    &effective_scopes,
                )?)
            } else {
                None
            };

            Ok(Json(TokenResponse {
                access_token,
                token_type: "Bearer",
                expires_in: state.config.jwt.access_token_ttl_secs,
                refresh_token: new_refresh_raw,
                id_token,
                scope: scope_str,
            }))
        }
        _ => Err(Error::UnsupportedGrantType),
    }
}

/// POST /oauth/revoke — revoke a refresh token (RFC 7009)
#[utoipa::path(
    post,
    path = "/oauth/revoke",
    tag = "oauth",
    request_body(content = RevokeRequest, content_type = "application/x-www-form-urlencoded"),
    responses(
        (status = 200, description = "Token revoked (or already invalid)"),
        (status = 401, description = "Invalid client credentials", body = ErrorBody),
    )
)]
pub(crate) async fn revoke(
    State(state): State<AppState>,
    headers: HeaderMap,
    Form(body): Form<RevokeRequest>,
) -> Result<StatusCode, Error> {
    // Validate client (Basic auth or POST body)
    let (client_id_str, client_secret) = extract_client_credentials(
        &headers,
        body.client_id.as_deref(),
        body.client_secret.as_deref(),
    )?;

    let client = db::find_client_by_client_id(&state.db, &client_id_str)
        .await?
        .ok_or(Error::InvalidClient)?;

    let secret_hash = jwt::hash_token(&client_secret);
    if secret_hash.as_bytes().ct_eq(client.client_secret_hash.as_bytes()).unwrap_u8() == 0 {
        return Err(Error::InvalidClient);
    }

    // Revoke the token, scoped to this client (RFC 7009 says always return 200)
    let token_hash = jwt::hash_token(&body.token);
    if let Err(e) = db::delete_refresh_token_for_client(&state.db, &token_hash, client.id).await {
        tracing::warn!(error = %e, client_id = %client_id_str, "token revocation failed");
    }

    Ok(StatusCode::OK)
}

/// POST /oauth/introspect — Token Introspection (RFC 7662)
///
/// Allows registered OAuth clients to validate tokens and retrieve their claims.
/// Accepts client authentication via HTTP Basic auth or POST body (client_id + client_secret).
/// Returns `{"active": false}` for any invalid, expired, or revoked token.
#[utoipa::path(
    post,
    path = "/oauth/introspect",
    tag = "oauth",
    request_body(content = IntrospectRequest, content_type = "application/x-www-form-urlencoded"),
    responses(
        (status = 200, description = "Introspection response (active: true/false)"),
        (status = 401, description = "Invalid client credentials", body = ErrorBody),
    )
)]
pub(crate) async fn introspect(
    State(state): State<AppState>,
    headers: HeaderMap,
    Form(body): Form<IntrospectRequest>,
) -> Result<impl IntoResponse, Error> {
    let no_cache_headers = || [
        (axum::http::header::CACHE_CONTROL, "no-store"),
        (axum::http::header::PRAGMA, "no-cache"),
    ];
    let inactive = || Ok((no_cache_headers(), Json(serde_json::json!({"active": false}))));

    // Authenticate the client via Basic auth or POST body credentials
    let (client_id_str, client_secret) = extract_client_credentials(
        &headers,
        body.client_id.as_deref(),
        body.client_secret.as_deref(),
    )?;

    let client = db::find_client_by_client_id(&state.db, &client_id_str)
        .await?
        .ok_or(Error::InvalidClient)?;

    let secret_hash = jwt::hash_token(&client_secret);
    if secret_hash.as_bytes().ct_eq(client.client_secret_hash.as_bytes()).unwrap_u8() == 0 {
        return Err(Error::InvalidClient);
    }

    // Decode and verify the token — any failure means inactive.
    // verify_client_token rejects session tokens (aud == issuer).
    let token_data = match state.keys.verify_client_token(&state.config.jwt, &body.token) {
        Ok(data) => data,
        Err(_) => return inactive(),
    };

    let claims = &token_data.claims;

    // Check the user still exists and is not soft-deleted
    let user_id: uuid::Uuid = match claims.sub.parse() {
        Ok(id) => id,
        Err(_) => return inactive(),
    };

    if db::find_user_by_id(&state.db, user_id).await?.is_none() {
        return inactive();
    }

    // Build RFC 7662 response
    let mut response = serde_json::json!({
        "active": true,
        "sub": claims.sub,
        "aud": claims.aud,
        "iss": claims.iss,
        "exp": claims.exp,
        "iat": claims.iat,
        "username": claims.username,
        "token_type": "Bearer",
        "client_id": claims.aud,
    });

    if let Some(ref scope) = claims.scope {
        response["scope"] = serde_json::Value::String(scope.clone());
    }

    Ok((no_cache_headers(), Json(response)))
}

/// Extract client credentials from Basic auth header or POST body.
///
/// Tries HTTP Basic auth first (RFC 6749 §2.3.1), then falls back to
/// POST body client_id/client_secret (RFC 6749 §2.3.1 alternative).
fn extract_client_credentials(
    headers: &HeaderMap,
    body_client_id: Option<&str>,
    body_client_secret: Option<&str>,
) -> Result<(String, String), Error> {
    // Try Basic auth first (RFC 7617)
    if let Some(auth_header) = headers.get("authorization").and_then(|v| v.to_str().ok()) {
        if auth_header.len() > 6 && auth_header[..6].eq_ignore_ascii_case("basic ") {
            let b64 = auth_header[6..].trim();
            let decoded = base64::engine::general_purpose::STANDARD
                .decode(b64)
                .or_else(|_| URL_SAFE_NO_PAD.decode(b64))
                .map_err(|_| Error::InvalidClient)?;
            let decoded_str = String::from_utf8(decoded).map_err(|_| Error::InvalidClient)?;
            let (id, secret) = decoded_str.split_once(':').ok_or(Error::InvalidClient)?;
            // RFC 6749 §2.3.1: credentials are application/x-www-form-urlencoded
            let id = percent_encoding::percent_decode_str(id)
                .decode_utf8()
                .map_err(|_| Error::InvalidClient)?
                .into_owned();
            let secret = percent_encoding::percent_decode_str(secret)
                .decode_utf8()
                .map_err(|_| Error::InvalidClient)?
                .into_owned();
            return Ok((id, secret));
        }
    }

    // Fall back to POST body credentials
    match (body_client_id, body_client_secret) {
        (Some(id), Some(secret)) => Ok((id.to_string(), secret.to_string())),
        _ => Err(Error::InvalidClient),
    }
}

/// GET /oauth/userinfo — OIDC UserInfo endpoint (OpenID Connect Core 1.0 §5.3)
///
/// Accepts a Bearer access token via the Authorization header. The token must
/// have been issued to an OAuth client (aud != issuer). Returns profile claims
/// filtered by the scopes granted in the access token.
///
/// **Note:** POST is also supported on this endpoint per OIDC Core 1.0 §5.3.
#[utoipa::path(
    get,
    path = "/oauth/userinfo",
    tag = "oauth",
    description = "OIDC UserInfo endpoint. Both GET and POST are supported per OIDC Core 1.0 §5.3.",
    responses(
        (status = 200, description = "User identity claims (filtered by token scopes)"),
        (status = 401, description = "Invalid or missing bearer token", body = ErrorBody),
    ),
    security(("bearer" = []))
)]
pub(crate) async fn userinfo(
    State(state): State<AppState>,
    headers: HeaderMap,
) -> Response {
    match userinfo_inner(&state, &headers).await {
        Ok(json) => Json(json).into_response(),
        Err(err) => bearer_error_response(&state.config.jwt.issuer, err),
    }
}

/// Attach `WWW-Authenticate: Bearer` to an error response per RFC 6750 §3.1.
fn bearer_error_response(issuer: &str, err: Error) -> Response {
    let header_value = www_authenticate_value(issuer, &err);
    let mut resp = err.into_response();
    if let Some(value) = header_value {
        resp.headers_mut().insert(
            axum::http::header::WWW_AUTHENTICATE,
            value.parse().unwrap(),
        );
    }
    resp
}

async fn userinfo_inner(
    state: &AppState,
    headers: &HeaderMap,
) -> Result<serde_json::Value, Error> {
    // Extract Bearer token from Authorization header (case-insensitive prefix per RFC 6750 §2.1)
    let auth_header = headers
        .get("authorization")
        .and_then(|v| v.to_str().ok())
        .ok_or(Error::Unauthenticated)?;

    let bearer_token = if auth_header.len() > 7 && auth_header[..7].eq_ignore_ascii_case("bearer ") {
        &auth_header[7..]
    } else {
        return Err(Error::Unauthenticated);
    };

    // Validate the JWT — verify_client_token rejects session tokens (aud == issuer).
    // Session tokens are not valid for UserInfo — use /auth/me instead.
    let token_data = state
        .keys
        .verify_client_token(&state.config.jwt, bearer_token)?;

    let claims = &token_data.claims;

    // Verify the audience matches a registered client
    db::find_client_by_client_id(&state.db, &claims.aud)
        .await?
        .ok_or(Error::InvalidToken)?;

    // Parse user ID
    let user_id: uuid::Uuid = claims.sub.parse().map_err(|_| Error::InvalidToken)?;

    // Fetch user profile — return 401 (not 404) if user was deleted,
    // since the token is no longer valid for any resource endpoint.
    let user = db::find_user_by_id(&state.db, user_id)
        .await?
        .ok_or(Error::InvalidToken)?;

    // Parse granted scopes from the token
    let scopes: BTreeSet<&str> = claims
        .scope
        .as_deref()
        .map(|s| s.split_whitespace().collect())
        .unwrap_or_default();

    // UserInfo requires the "openid" scope (OIDC Core 1.0 §5.3)
    if !scopes.contains("openid") {
        return Err(Error::Forbidden);
    }

    // Build response based on granted scopes (OIDC Core 1.0 §5.4)
    let mut response = serde_json::Map::new();

    // "sub" is always returned per OIDC Core 1.0 §5.3.2
    response.insert("sub".to_string(), serde_json::json!(user.id.to_string()));

    if scopes.contains("profile") {
        response.insert(
            "preferred_username".to_string(),
            serde_json::json!(user.username),
        );
        if let Some(ref name) = user.display_name {
            response.insert("name".to_string(), serde_json::json!(name));
        }
        if let Some(ref picture) = user.avatar_url {
            response.insert("picture".to_string(), serde_json::json!(picture));
        }
        response.insert(
            "updated_at".to_string(),
            serde_json::json!(user.updated_at.timestamp()),
        );
    }

    if scopes.contains("email") {
        // Fetch email from the user's oldest oauth_link that has an email (deterministic ordering)
        let links = db::find_oauth_links_by_user(&state.db, user_id).await?;
        if let Some(link) = links.iter().find(|l| l.provider_email.is_some()) {
            response.insert("email".to_string(), serde_json::json!(link.provider_email.as_deref().unwrap()));
            response.insert("email_verified".to_string(), serde_json::json!(link.email_verified));
        }
    }

    Ok(serde_json::Value::Object(response))
}