pas_external/oidc/

relying_party.rs

//! OIDC RP composition root.
//!
//! [`RelyingParty<S>`] is the deep-module entry point for OAuth + OIDC
//! integration. It hides ALL SDK-internal collaborators behind 3
//! lifecycle methods:
//!
//! - [`new`](RelyingParty::new) — discovery + JWKS bootstrap +
//!   internal `oauth::AuthClient` + [`PasIdTokenVerifier<S>`]
//!   composition. One call at consumer boot.
//! - [`start`](RelyingParty::start) — generate state + nonce + PKCE,
//!   persist in the [`StateStore`], return [`AuthorizationRedirect`].
//! - [`complete`](RelyingParty::complete) — atomic state-take + token
//!   exchange + id_token verify, return [`Completion<S>`].
//!
//! The consumer never directly imports `oauth::AuthClient` or
//! [`PasIdTokenVerifier<S>`]; the only port the consumer implements
//! is [`StateStore`] (the OIDC-specific atomic single-use invariant).
//! Discovery + JWKS + PKCE + nonce + URL building are all in-process
//! composition that earned its place inside this struct because the
//! caller cannot meaningfully customize them.
//!
//! ── 3 methods, 4 hidden collaborators ───────────────────────────────────
//!
//! | Hidden inside `RelyingParty<S>` | Surfaced to consumer |
//! |---------------------------------|----------------------|
//! | [`super::discovery::fetch_discovery`] (boot)         | none |
//! | [`PasIdTokenVerifier`] (boot + complete)             | none |
//! | `oauth::AuthClient` (boot + complete)                | none |
//! | [`crate::pkce`] (every `start`)                      | none |
//! | nonce generation (every `start`)                     | none |
//! | state generation (every `start`)                     | [`State`] (round-trip key only) |
//!
//! ── Scope contract ──────────────────────────────────────────────────────
//!
//! The marker `S` parameter does triple duty:
//!
//! 1. Determines the requested-scope string sent to PAS at `start`
//!    (via [`RequestedScope::SCOPE`]).
//! 2. Carries through to the verifier, narrowing the post-verify
//!    [`super::IdAssertion<S>`] PII surface (Phase 10's marker traits
//!    `HasEmail` / `HasProfile` / `HasPhone` / `HasAddress`).
//! 3. Propagates into [`Completion<S>`] so the consumer's typed
//!    handler signature mirrors the requested scope without runtime
//!    re-derivation.
//!
//! Asking for a scope at construction time and being unable to read
//! claims outside that scope is a single architectural decision
//! enforced at compile time.

use std::sync::Arc;

use ppoppo_clock::ArcClock;
use ppoppo_clock::native::WallClock;
use ppoppo_token::id_token::scopes::{
    Email, EmailProfile, EmailProfilePhone, EmailProfilePhoneAddress, Openid, Profile,
};
use ppoppo_token::id_token::Nonce;
use url::Url;

use super::{
    discovery::{fetch_discovery, Discovery, DiscoveryError},
    port::{IdTokenVerifier, IdVerifyError, ScopePiiReader},
    refresh_outcome::RefreshOutcome,
    state_store::{
        AuthorizationRedirect, CallbackParams, Completion, Config, PendingAuthRequest,
        RelativePath, State, StateStore, StateStoreError,
    },
    verifier::PasIdTokenVerifier,
};
use crate::oauth::{AuthClient, OAuthConfig};
use crate::pkce;
use crate::{EpochEnforcement, JwtVerifier, VerifyConfig};

// ────────────────────────────────────────────────────────────────────────
// RequestedScope — S → scope-string mapping
// ────────────────────────────────────────────────────────────────────────

/// Scope marker → scope-parameter mapping for the OIDC `scope` query
/// parameter sent to PAS at `start`.
///
/// Phase 10's [`ScopePiiReader`] gates which PII fields the verifier
/// hydrates (and therefore which accessors compile on the resulting
/// [`super::IdAssertion<S>`]). [`RequestedScope`] is the *strictly
/// stronger* trait the RP requires: every scope marker also has a
/// canonical string sent on the wire. The two ends meet —
/// `S = scopes::Email` causes both `scope=openid email` to be sent
/// AND `assertion.email()` to compile, with the same single type
/// parameter wiring the contract end-to-end.
///
/// **Adding a scope**: implement [`RequestedScope`] for the engine's
/// new marker type with the exact wire string. The RP does not
/// validate the string against any allowlist — PAS rejects unknown
/// scopes at the authorize endpoint.
pub trait RequestedScope: ScopePiiReader {
    /// The exact `scope` parameter value sent to PAS, space-separated
    /// per RFC 6749 §3.3.
    const SCOPE: &'static str;
}

impl RequestedScope for Openid {
    const SCOPE: &'static str = "openid";
}
impl RequestedScope for Email {
    const SCOPE: &'static str = "openid email";
}
impl RequestedScope for Profile {
    const SCOPE: &'static str = "openid profile";
}
impl RequestedScope for EmailProfile {
    const SCOPE: &'static str = "openid email profile";
}
impl RequestedScope for EmailProfilePhone {
    const SCOPE: &'static str = "openid email profile phone";
}
impl RequestedScope for EmailProfilePhoneAddress {
    const SCOPE: &'static str = "openid email profile phone address";
}

// ────────────────────────────────────────────────────────────────────────
// RelyingParty
// ────────────────────────────────────────────────────────────────────────

/// OAuth + OIDC Relying Party composition root.
///
/// `S: RequestedScope` propagates the scope contract from the
/// requested-scope wire parameter through Phase 10's
/// [`PasIdTokenVerifier<S>`] into the post-verify
/// [`Completion<S>`]. Constructing
/// `RelyingParty::<scopes::Email>` narrows the scope-bounded PII
/// available on the post-login assertion to the email scope claims.
///
/// Wrap in `Arc` for axum state — internals are mostly `Arc`-shared
/// (JWKS cache, reqwest client). The consumer typically constructs
/// once at boot and stores `Arc<RelyingParty<S>>` in app state.
pub struct RelyingParty<S: RequestedScope> {
    config: Config,
    state_store: Arc<dyn StateStore>,
    auth_client: AuthClient,
    verifier: Arc<dyn IdTokenVerifier<S>>,
    discovery: Discovery,
    clock: ArcClock,
}

// `Arc<dyn StateStore>` / `AuthClient` / `Arc<dyn IdTokenVerifier<S>>`
// don't trivially `Debug`. Manual impl shows only the non-sensitive
// boot-time configuration so consumers can log RP state without
// risking credential exposure.
impl<S: RequestedScope> std::fmt::Debug for RelyingParty<S> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("RelyingParty")
            .field("config", &self.config)
            .field("discovery", &self.discovery)
            .finish_non_exhaustive()
    }
}

/// Construction-time failure surface.
#[derive(Debug, thiserror::Error)]
pub enum RelyingPartyInitError {
    #[error("OIDC discovery fetch failed: {0}")]
    Discovery(#[from] DiscoveryError),
    #[error("JWKS fetch failed: {0}")]
    Jwks(IdVerifyError),
    #[error("OAuth client construction failed: {0}")]
    OAuthClient(String),
}

/// `start` failure surface.
#[derive(Debug, thiserror::Error)]
pub enum StartError {
    #[error("state store failure: {0}")]
    StateStore(#[from] StateStoreError),
    #[error("authorize URL construction failed: {0}")]
    UrlBuild(String),
}

/// `refresh` failure surface.
///
/// Mirrors [`CallbackError`]'s split between credential-rejection and
/// substrate-failure: 4xx responses indicate a dead refresh_token (the
/// consumer should clear the session cookies and force re-auth); 5xx
/// or transport failures are transient (the consumer may retry).
#[derive(Debug, thiserror::Error)]
pub enum RefreshError {
    /// PAS rejected the refresh_token (4xx). Dead credential — the
    /// consumer must clear the session and start a new authorization
    /// flow. Token rotation is a no-op when there is no live token to
    /// rotate.
    #[error("refresh_token rejected by PAS: {0}")]
    Rejected(String),

    /// PAS service is degraded (5xx) or transport-level failure
    /// (timeout, TLS, DNS). The session may still be live; the
    /// consumer should fail-soft (e.g., return 503 to the browser
    /// rather than clearing cookies).
    #[error("refresh transient failure: {0}")]
    Transient(String),
}

/// `complete` failure surface.
///
/// `StateNotFoundOrConsumed` is the load-bearing CSRF / state-replay
/// defense: state-store substrate atomicity guarantees that a second
/// `complete` call with the same `state` lands here regardless of
/// whether the first call succeeded or failed late.
#[derive(Debug, thiserror::Error)]
pub enum CallbackError {
    /// State key absent from substrate at callback. Indistinguishable
    /// across "never existed", "already consumed", "TTL-expired" — all
    /// three are CSRF-equivalent and intentionally collapse into one
    /// variant.
    #[error("state not found or already consumed (CSRF defense triggered)")]
    StateNotFoundOrConsumed,

    #[error("state store failure: {0}")]
    StateStore(#[from] StateStoreError),

    #[error("token exchange failed: {0}")]
    TokenExchange(String),

    #[error("id_token verification failed: {0}")]
    IdToken(#[from] IdVerifyError),
}

impl<S: RequestedScope> RelyingParty<S> {
    /// Construct a fully-composed RP.
    ///
    /// At boot:
    /// 1. Fetch the OIDC discovery document from
    ///    `<config.issuer>/.well-known/openid-configuration`.
    /// 2. Fetch the JWKS from the discovery's `jwks_uri` and seed
    ///    [`PasIdTokenVerifier<S>`] with it.
    /// 3. Construct the internal `oauth::AuthClient` using the
    ///    discovery's `authorization_endpoint` + `token_endpoint`.
    /// 4. Store all components for the lifetime of the RP.
    ///
    /// # Errors
    ///
    /// - [`RelyingPartyInitError::Discovery`] — discovery fetch failed
    /// - [`RelyingPartyInitError::Jwks`] — JWKS fetch failed
    /// - [`RelyingPartyInitError::OAuthClient`] — reqwest client build failed
    pub async fn new(
        config: Config,
        state_store: Arc<dyn StateStore>,
    ) -> Result<Self, RelyingPartyInitError> {
        let discovery = fetch_discovery(&config.issuer).await?;

        let expectations = VerifyConfig::new(
            // Trim the trailing slash the `url` crate re-adds to a host-only
            // `Url`: PAS signs id_tokens — like access tokens — under the
            // BARE issuer. id_token verify does not compare `iss` YET (Phase
            // 10.5-10.7), so this trim is a no-op today; doing it now keeps
            // the OAuth callback correct the moment iss-enforcement lands.
            // Mirror of the access-token perimeter trim in
            // `access_token_verifier` — same issuer, same reason.
            discovery.issuer.as_str().trim_end_matches('/'),
            config.client_id.clone(),
        );
        let verifier_concrete: PasIdTokenVerifier<S> =
            PasIdTokenVerifier::from_jwks_url(discovery.jwks_uri.to_string(), expectations)
                .await
                .map_err(RelyingPartyInitError::Jwks)?;
        let verifier: Arc<dyn IdTokenVerifier<S>> = Arc::new(verifier_concrete);

        let mut oauth_config = OAuthConfig::new(config.client_id.clone())
            // A web RP's redirect URI is a real absolute URL with a path, so
            // the `Url` normalization that bites host-only loopback URIs is a
            // no-op here; `as_str()` is what has always gone on the wire.
            .with_redirect_uri(config.redirect_uri.as_str())
            .with_auth_url(discovery.authorization_endpoint.clone())
        .with_token_url(discovery.token_endpoint.clone());
        // RFC 8707 (G2): a PCS-bound RP carries its resource indicator onto
        // the token + refresh legs so the minted `aud` clears the resource
        // perimeter. Threaded here so `exchange_code` / `refresh` need no
        // per-call argument. `start` (below) sends the same value on the
        // authorize leg.
        if let Some(resource) = &config.resource {
            oauth_config = oauth_config.with_resource(resource.clone());
        }
        let auth_client = AuthClient::try_new(oauth_config)
            .map_err(|e| RelyingPartyInitError::OAuthClient(e.to_string()))?;

        Ok(Self {
            config,
            state_store,
            auth_client,
            verifier,
            discovery,
            clock: Arc::new(WallClock),
        })
    }

    /// Begin an authorization flow.
    ///
    /// Generates fresh state + nonce + PKCE, persists the
    /// [`PendingAuthRequest`] under the state key (TTL =
    /// `config.state_ttl`), and returns the authorize URL the
    /// consumer should redirect the browser to.
    ///
    /// `after_login` is the post-login redirect target; the
    /// [`RelativePath`] newtype prevents open-redirect (RFC 9700
    /// §4.1.5) at the SDK boundary.
    ///
    /// # Errors
    ///
    /// - [`StartError::StateStore`] — substrate failure during `put`
    /// - [`StartError::UrlBuild`] — authorize URL serialization failed
    pub async fn start(
        &self,
        after_login: RelativePath,
    ) -> Result<AuthorizationRedirect, StartError> {
        let state_str = pkce::generate_state();
        let code_verifier = pkce::generate_code_verifier();
        let code_challenge = pkce::generate_code_challenge(&code_verifier);
        let nonce = pkce::generate_state();

        let state = State::from_string(state_str.clone());
        let pending = PendingAuthRequest {
            code_verifier: code_verifier.clone(),
            nonce: nonce.clone(),
            after_login,
            created_at: self.clock.now(),
        };
        self.state_store
            .put(&state, pending, self.config.state_ttl)
            .await?;

        let url = build_authorize_url(
            &self.discovery.authorization_endpoint,
            &self.config.client_id,
            &self.config.redirect_uri,
            &state_str,
            &code_challenge,
            S::SCOPE,
            &nonce,
            self.config.resource.as_deref(),
        );

        Ok(AuthorizationRedirect { url, state })
    }

    /// Complete a callback.
    ///
    /// Atomically `take`s the pending state, exchanges the
    /// authorization `code` for tokens, verifies the returned
    /// id_token against the stored nonce, and returns the verified
    /// [`Completion<S>`].
    ///
    /// ## Grant validation — deliberately absent here
    ///
    /// This method does **not** check the token response's RFC 6749 §5.1
    /// `scope` echo against `S`, while the native sibling
    /// ([`NativeAuthFlow::complete`](crate::native::NativeAuthFlow::complete))
    /// does. That asymmetry is a decision, not an oversight.
    ///
    /// The RP's grant validation **is the id_token**. `S` on this side
    /// selects a bundle of identity *claims*, and step 4 below verifies a
    /// signed assertion that either carries them or does not — a stronger
    /// check than a scope string, performed on cryptographic evidence rather
    /// than on the server's own summary of what it granted. The native flow
    /// has no id_token to lean on (it requests no `openid`), so the scope
    /// echo is the only grant evidence available to it.
    ///
    /// The two are also checking different things: a claim bundle that came
    /// back short is visible in the assertion, whereas a *resource* scope
    /// that came back short is invisible until the resource server refuses
    /// the call.
    ///
    /// # Errors
    ///
    /// - [`CallbackError::StateNotFoundOrConsumed`] — CSRF defense
    ///   (state absent or already consumed)
    /// - [`CallbackError::StateStore`] — substrate failure during
    ///   `take`
    /// - [`CallbackError::TokenExchange`] — PAS token endpoint
    ///   rejected
    /// - [`CallbackError::IdToken`] — id_token verification failed
    pub async fn complete(
        &self,
        params: CallbackParams,
    ) -> Result<Completion<S>, CallbackError> {
        // 1. Atomic state-take — single-use enforcement
        let pending = self
            .state_store
            .take(&params.state)
            .await?
            .ok_or(CallbackError::StateNotFoundOrConsumed)?;

        // 2. Token exchange
        let tokens = self
            .auth_client
            .exchange_code(&params.code, &pending.code_verifier)
            .await
            .map_err(|e| CallbackError::TokenExchange(e.to_string()))?;

        // 3. Read id_token from response (OIDC Core §3.1.3.3 — required
        //    when scope includes `openid`, which RequestedScope's
        //    `SCOPE` const always does)
        let id_token = tokens.id_token.as_deref().ok_or_else(|| {
            CallbackError::TokenExchange("token response missing id_token".to_owned())
        })?;

        // 4. Verify id_token against the stored nonce
        let nonce = Nonce::new(pending.nonce.as_str())
            .map_err(|_| CallbackError::IdToken(IdVerifyError::NonceMismatch))?;
        let id_assertion = self.verifier.verify(id_token, &nonce).await?;

        Ok(Completion {
            id_assertion,
            tokens,
            redirect_to: pending.after_login,
        })
    }

    /// Build the request-perimeter **access-token** verifier from this
    /// RP's own OIDC discovery metadata.
    ///
    /// The login flow ([`Self::complete`]) verifies *id_tokens*; a
    /// consumer's request perimeter must separately verify the *access
    /// tokens* PAS issues (RFC 9068). Both are signed by the same PAS
    /// keyset under the same issuer — values this RP already fetched at
    /// [`Self::new`]. This factory returns a ready [`JwtVerifier`] wired
    /// to the discovered `jwks_uri` and `issuer`, so the consumer never
    /// re-derives them.
    ///
    /// **Why it exists.** Before this method every integrator
    /// hand-assembled the perimeter verifier — string-formatting the
    /// JWKS URL and re-normalizing the issuer. [`Discovery::issuer`] is a
    /// [`Url`] whose `as_str()` carries the trailing slash the `url`
    /// crate normalizes onto a host-only URL, while PAS emits the *bare*
    /// issuer in the access-token `iss` claim and the engine matches it
    /// exactly. Getting that trim wrong produced a successful OAuth
    /// callback followed by a silent 401 on every subsequent request
    /// (RCW + CTW, 2026-05-27). Trimming **once here, in the SDK**, makes
    /// that bug class unrepresentable at the call site.
    ///
    /// The returned verifier owns a fresh, independent JWKS cache (the
    /// current per-verifier `ε1` invariant — see
    /// [`PasIdTokenVerifier`](super::verifier::PasIdTokenVerifier)); the
    /// `async fn` signature lets a future shared-cache optimization (ε2)
    /// swap the internals without a breaking change.
    ///
    /// **Required stance**: `epoch` is the sv-axis [`EpochEnforcement`]
    /// declaration (RFC_202607150428 Q3 — silence is unrepresentable).
    /// Consumers with no epoch substrate (RCW/CTW: no KVRocks, separate
    /// DB) pass a NAMED [`EpochEnforcement::Unenforced`], which WARNs at
    /// boot; the gap is bounded by the 1h access-token TTL plus PAS
    /// refresh-family revocation. Chain
    /// [`JwtVerifier::with_session_liveness`] /
    /// [`with_audit`](JwtVerifier::with_audit) on the result before
    /// storing it behind `Arc<dyn BearerVerifier>`.
    ///
    /// # Errors
    ///
    /// Returns [`crate::TokenVerifyError::KeysetUnavailable`] if the JWKS
    /// fetch fails — the perimeter cannot verify without at least one
    /// usable key snapshot.
    pub async fn access_token_verifier(
        &self,
        epoch: EpochEnforcement,
    ) -> Result<JwtVerifier, crate::TokenVerifyError> {
        JwtVerifier::from_jwks_url(
            self.discovery.jwks_uri.to_string(),
            VerifyConfig::new(
                // `discovery.issuer` is a `Url`; `.as_str()` re-adds the
                // trailing slash the `url` crate normalizes onto a
                // host-only URL. PAS emits the bare issuer on the
                // access-token `iss` claim and the engine matches it
                // exactly (M23) — so trim here, once, so no consumer has to.
                //
                // SYMMETRY (both configs trim): the sibling id_token
                // `VerifyConfig` in `new` above trims identically, and that
                // is deliberate — PAS signs both token classes' `iss` from
                // the same bare-issuer config (`ppoppo-token`'s
                // `engine::encode`); the matching no-trailing-slash invariant
                // on the published metadata is pinned in
                // `accounts-api::rest::well_known::discovery`. Access-token
                // verify does an exact `iss` match; id_token verify does not
                // check `iss` YET (Phase 10.5-10.7), so a slash-carrying
                // id_token config "works" today only by omission. Trimming
                // both keeps this perimeter correct now AND keeps the OAuth
                // callback correct the moment id_token iss-enforcement lands
                // — at which point a `…/` id_token config would reject every
                // real callback.
                self.discovery.issuer.as_str().trim_end_matches('/'),
                self.config.client_id.clone(),
            ),
            epoch,
        )
        .await
    }

    /// Refresh an existing PAS session.
    ///
    /// Exchanges a `refresh_token` for a fresh
    /// [`oauth::TokenResponse`] (new access_token, possibly rotated
    /// refresh_token, possibly new id_token). The consumer typically
    /// invokes this from a dedicated refresh endpoint — it is the
    /// SSOT for the OAuth refresh-grant exchange so that
    /// `chat-auth::rp` (and equivalent consumers) never reach into
    /// `oauth::AuthClient` directly.
    ///
    /// **No id_token verification is performed here.** Refresh
    /// responses MAY include an id_token (OIDC Core §12), but the
    /// consumer treats refresh as a session-extension mechanism, not a
    /// re-authentication event — the original
    /// [`Self::complete`] verified the user identity, and the cookie
    /// flow that calls this method already trusts the refresh_token
    /// it just decrypted.
    ///
    /// # Errors
    ///
    /// - [`RefreshError::Rejected`] — PAS returned 4xx; refresh_token
    ///   is dead, clear session and force re-auth.
    /// - [`RefreshError::Transient`] — 5xx or transport failure;
    ///   session may still be live, fail-soft.
    pub async fn refresh(
        &self,
        refresh_token: &str,
    ) -> Result<RefreshOutcome, RefreshError> {
        use crate::pas_port::{PasAuthPort, PasFailure};
        match self.auth_client.refresh(refresh_token).await {
            Ok(t) => Ok(RefreshOutcome::from(t)),
            Err(PasFailure::Rejected { detail, .. }) => Err(RefreshError::Rejected(detail)),
            Err(PasFailure::ServerError { detail, .. })
            | Err(PasFailure::Transport { detail }) => Err(RefreshError::Transient(detail)),
        }
    }

    /// Build the OIDC RP-Initiated Logout URL — the OP `end_session_endpoint`
    /// (OIDC RP-Initiated Logout 1.0 §2). The browser navigates here to end
    /// its OP session: pass the `id_token` the RP holds as the hint, the
    /// pre-registered `post_logout_redirect_uri` to land on afterward, and an
    /// optional opaque `state`. Pure — no IO; the caller performs the redirect.
    ///
    /// # Errors
    /// - [`EndSessionError::NotSupported`] — the OP's discovery document
    ///   advertises no `end_session_endpoint`.
    pub fn end_session_url(
        &self,
        id_token: &str,
        post_logout_redirect_uri: &Url,
        state: Option<&str>,
    ) -> Result<Url, EndSessionError> {
        let endpoint = self
            .discovery
            .end_session_endpoint
            .as_ref()
            .ok_or(EndSessionError::NotSupported)?;
        Ok(build_end_session_url(
            endpoint,
            id_token,
            post_logout_redirect_uri,
            &self.config.client_id,
            state,
        ))
    }
}

/// Error from [`RelyingParty::end_session_url`].
#[derive(Debug, thiserror::Error)]
pub enum EndSessionError {
    /// The OP's discovery document advertises no `end_session_endpoint`, so
    /// RP-Initiated Logout is unavailable against this provider.
    #[error("the OP advertises no end_session_endpoint (RP-Initiated Logout unsupported)")]
    NotSupported,
}

// ────────────────────────────────────────────────────────────────────────
// URL builder — extracted for boundary-test introspection
// ────────────────────────────────────────────────────────────────────────

/// Build the OIDC authorize URL.
///
/// Pulled out as a free function so the URL-shape boundary test can
/// re-derive the expected URL deterministically (given fixed inputs)
/// without round-tripping through `RelyingParty::start` (which
/// generates fresh randomness each call).
///
/// Order of query params is stable to ease test assertions, but
/// PAS does not depend on order (RFC 6749 §3.1).
#[allow(clippy::too_many_arguments)]
fn build_authorize_url(
    authorization_endpoint: &Url,
    client_id: &str,
    redirect_uri: &Url,
    state: &str,
    code_challenge: &str,
    scope: &str,
    nonce: &str,
    resource: Option<&str>,
) -> Url {
    let mut url = authorization_endpoint.clone();
    {
        let mut pairs = url.query_pairs_mut();
        pairs
            .append_pair("response_type", "code")
            .append_pair("client_id", client_id)
            .append_pair("redirect_uri", redirect_uri.as_str())
            .append_pair("state", state)
            .append_pair("code_challenge", code_challenge)
            .append_pair("code_challenge_method", "S256")
            .append_pair("scope", scope)
            .append_pair("nonce", nonce);
        // RFC 8707 §2: bind the resource at authorize so the code carries it
        // and the token-leg `aud` is minted against it. Omitted for identity
        // RPs (RCW/CTW), which keep `aud = client_id`.
        if let Some(r) = resource {
            pairs.append_pair("resource", r);
        }
    }
    url
}

/// Build the OIDC RP-Initiated Logout URL. Free function for the same
/// boundary-test reason as [`build_authorize_url`]. `query_pairs_mut`
/// percent-encodes every value (so `state` / the redirect URI are safe).
fn build_end_session_url(
    end_session_endpoint: &Url,
    id_token_hint: &str,
    post_logout_redirect_uri: &Url,
    client_id: &str,
    state: Option<&str>,
) -> Url {
    let mut url = end_session_endpoint.clone();
    {
        let mut pairs = url.query_pairs_mut();
        pairs
            .append_pair("id_token_hint", id_token_hint)
            .append_pair("post_logout_redirect_uri", post_logout_redirect_uri.as_str())
            .append_pair("client_id", client_id);
        if let Some(s) = state {
            pairs.append_pair("state", s);
        }
    }
    url
}

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used)]
    use super::*;

    #[test]
    fn end_session_url_carries_hint_redirect_client_and_state() {
        let endpoint: Url = "https://accounts.ppoppo.com/oauth/logout".parse().unwrap();
        let redirect: Url = "https://ppoppo.com/".parse().unwrap();
        let url = build_end_session_url(&endpoint, "the.id.token", &redirect, "cwc", Some("a b"));
        let s = url.as_str();
        assert!(s.starts_with("https://accounts.ppoppo.com/oauth/logout?"), "{s}");
        assert!(s.contains("id_token_hint=the.id.token"), "{s}");
        // post_logout_redirect_uri is percent-encoded by query_pairs_mut.
        assert!(s.contains("post_logout_redirect_uri=https%3A%2F%2Fppoppo.com%2F"), "{s}");
        assert!(s.contains("client_id=cwc"), "{s}");
        // form-encoding: space → `+`.
        assert!(s.contains("state=a+b"), "{s}");
    }

    #[test]
    fn end_session_url_omits_state_when_absent() {
        let endpoint: Url = "https://accounts.ppoppo.com/oauth/logout".parse().unwrap();
        let redirect: Url = "https://ppoppo.com/".parse().unwrap();
        let url = build_end_session_url(&endpoint, "tok", &redirect, "cwc", None);
        assert!(!url.as_str().contains("state="), "{}", url.as_str());
    }

    fn authorize(resource: Option<&str>) -> String {
        let endpoint: Url = "https://accounts.ppoppo.com/oauth/authorize".parse().unwrap();
        let redirect: Url = "https://ppoppo.com/callback".parse().unwrap();
        build_authorize_url(
            &endpoint, "cwc", &redirect, "st", "chal", "openid profile", "nc", resource,
        )
        .into()
    }

    #[test]
    fn authorize_url_binds_resource_when_present() {
        // Value is percent-encoded by query_pairs_mut (`:` → %3A, `/` → %2F).
        assert!(
            authorize(Some("https://api.ppoppo.com/grpc"))
                .contains("resource=https%3A%2F%2Fapi.ppoppo.com%2Fgrpc"),
            "PCS-bound RP binds its resource at authorize (RFC 8707 §2)"
        );
    }

    #[test]
    fn authorize_url_omits_resource_for_identity_rps() {
        assert!(
            !authorize(None).contains("resource="),
            "RCW/CTW send no resource → aud stays client_id"
        );
    }

    /// `complete` reads `tokens.id_token` and errors when it is absent,
    /// justified by "OIDC Core §3.1.3.3 — required when scope includes
    /// `openid`, which `RequestedScope`'s `SCOPE` const always does".
    ///
    /// That justification is an invariant over an open trait, held today
    /// only by the six impls above all happening to start with `openid`.
    /// Nothing enforced it. An impl added without the prefix would compile,
    /// request a non-OIDC scope, receive no id_token, and turn every login
    /// into `TokenExchange("token response missing id_token")` — a message
    /// pointing at the token endpoint for a fault that is in the scope
    /// marker.
    ///
    /// The native flow now exists precisely for markers that do NOT request
    /// `openid`, which makes the temptation to add one here concrete.
    #[test]
    fn every_requested_scope_asks_for_openid() {
        // Enumerated by hand because Rust offers no reflection over a
        // trait's impls; the count guard below is what stops this list from
        // silently falling behind.
        let scopes: [(&str, &str); 6] = [
            ("Openid", Openid::SCOPE),
            ("Email", Email::SCOPE),
            ("Profile", Profile::SCOPE),
            ("EmailProfile", EmailProfile::SCOPE),
            ("EmailProfilePhone", EmailProfilePhone::SCOPE),
            ("EmailProfilePhoneAddress", EmailProfilePhoneAddress::SCOPE),
        ];

        for (name, scope) in scopes {
            assert!(
                scope.split(' ').any(|atom| atom == "openid"),
                "{name}'s SCOPE (`{scope}`) must request `openid` — \
                 `RelyingParty::complete` requires an id_token. A marker \
                 requesting resource scopes belongs on `NativeAuthFlow`."
            );
        }
    }
}