entropy-auth 2026.7.31

//! OAuth 2.0 Device Authorization Grant (RFC 8628).
//!
//! The device grant lets an input-constrained device (a TV, a console, a
//! first-run OS setup running in kiosk mode) obtain tokens without a
//! browser or keyboard on the device itself: the device shows a short
//! `user_code` and a `verification_uri`, the user visits that URL on a
//! phone or laptop and approves, and the device polls the token endpoint
//! until authorization completes.
//!
//! This module follows the same design as the rest of [`crate::oauth`]:
//! it **builds requests and parses responses only** — the caller supplies
//! the HTTP transport and drives the polling loop. This avoids coupling to
//! any particular HTTP library and keeps the crate `std`-only.
//!
//! # Client type
//!
//! These builders target **public clients** (native / desktop apps), which
//! per RFC 8628 §3.1 and RFC 6749 §2.1 have no client secret. Only
//! `client_id` is sent. The `device_authorization_endpoint` is typically
//! discovered from the provider's OIDC metadata
//! ([`crate::oidc`]), not statically configured, so it is passed in rather
//! than read from [`OAuthConfig`](super::OAuthConfig).
//!
//! # Flow
//!
//! 1. Build a [`DeviceAuthorizationRequest`] and POST it to the device
//!    authorization endpoint.
//! 2. Parse the JSON with [`DeviceAuthorizationResponse::parse`]; show the
//!    `user_code` + `verification_uri` (or `verification_uri_complete`) to
//!    the user.
//! 3. Poll: build a [`DeviceAccessTokenRequest`] and POST it to the token
//!    endpoint every [`DeviceAuthorizationResponse::interval`] seconds.
//! 4. Classify each poll with [`DeviceTokenOutcome::parse`]:
//!    - [`DeviceTokenOutcome::Pending`] — keep waiting.
//!    - [`DeviceTokenOutcome::SlowDown`] — increase the interval by 5s
//!      (RFC 8628 §3.5) and keep waiting.
//!    - [`DeviceTokenOutcome::Authorized`] — done; contains the tokens.
//!    - a terminal [`DeviceFlowError`] (`access_denied`, `expired_token`, …).
//!
//! # Security
//!
//! SECURITY: `device_code` is a bearer credential for the pending
//! authorization — it is wrapped in [`Zeroizing`] and redacted from
//! `Debug`. The poll request body (which contains it) is likewise wrapped
//! and redacted. `user_code` is user-facing and not secret.
//!
//! [`Zeroizing`]: crate::crypto::zeroize::Zeroizing

use std::fmt;

use crate::crypto::zeroize::Zeroizing;
use crate::encoding::url_encode_component;
use crate::json::JsonValue;
use crate::util::log::{debug, info, warn};

use super::{TokenResponse, TokenResponseError};

/// RFC 8628 §3.4 device-code grant type.
const DEVICE_GRANT_TYPE: &str = "urn:ietf:params:oauth:grant-type:device_code";

/// RFC 8628 §3.2 default polling interval (seconds) when the authorization
/// response omits `interval`.
pub const DEFAULT_POLL_INTERVAL_SECS: u64 = 5;

/// RFC 8628 §3.5 amount (seconds) to increase the polling interval by on a
/// `slow_down` error.
pub const SLOW_DOWN_INCREMENT_SECS: u64 = 5;

// ---------------------------------------------------------------------------
// Error type
// ---------------------------------------------------------------------------

/// The category of device-flow failure.
#[derive(Debug, Clone, PartialEq, Eq)]
enum DeviceFlowErrorKind {
    /// The response body was not valid JSON.
    InvalidJson,
    /// The device authorization response was missing `device_code`.
    MissingDeviceCode,
    /// The device authorization response was missing `user_code`.
    MissingUserCode,
    /// The device authorization response was missing `verification_uri`.
    MissingVerificationUri,
    /// The device authorization response was missing `expires_in`.
    MissingExpiresIn,
    /// `expires_in` was present but not a non-negative integer.
    InvalidExpiresIn,
    /// `interval` was present but not a non-negative integer.
    InvalidInterval,
    /// Terminal poll error: the user denied the authorization
    /// (`access_denied`).
    AccessDenied,
    /// Terminal poll error: the `device_code` expired before the user
    /// approved (`expired_token`).
    ExpiredToken,
    /// Terminal poll error: some other OAuth error code from the endpoint.
    ServerError {
        /// The OAuth error code.
        error: String,
        /// Optional human-readable description.
        description: Option<String>,
    },
    /// The authorized poll response could not be parsed as a token response.
    TokenResponse(TokenResponseError),
}

/// Error returned by the device authorization grant.
///
/// Represents a malformed device authorization response, or a terminal
/// failure while polling the token endpoint. Non-terminal poll states
/// (`authorization_pending`, `slow_down`) are **not** errors — they are
/// returned as [`DeviceTokenOutcome`] variants so the caller can keep
/// polling.
///
/// Error messages never contain secret material (`device_code` and tokens
/// are excluded from all diagnostic output).
#[doc(alias = "device_error")]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DeviceFlowError {
    kind: DeviceFlowErrorKind,
}

impl DeviceFlowError {
    const fn new(kind: DeviceFlowErrorKind) -> Self {
        Self { kind }
    }

    /// Returns `true` if this is the terminal `access_denied` error — the
    /// user rejected the authorization request.
    #[must_use]
    #[inline]
    pub fn is_access_denied(&self) -> bool {
        matches!(self.kind, DeviceFlowErrorKind::AccessDenied)
    }

    /// Returns `true` if this is the terminal `expired_token` error — the
    /// `device_code` expired before the user approved. The caller should
    /// restart the flow to obtain a fresh code.
    #[must_use]
    #[inline]
    pub fn is_expired(&self) -> bool {
        matches!(self.kind, DeviceFlowErrorKind::ExpiredToken)
    }
}

impl fmt::Display for DeviceFlowError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match &self.kind {
            DeviceFlowErrorKind::InvalidJson => write!(f, "device flow: invalid JSON"),
            DeviceFlowErrorKind::MissingDeviceCode => {
                write!(f, "device flow: missing device_code")
            }
            DeviceFlowErrorKind::MissingUserCode => {
                write!(f, "device flow: missing user_code")
            }
            DeviceFlowErrorKind::MissingVerificationUri => {
                write!(f, "device flow: missing verification_uri")
            }
            DeviceFlowErrorKind::MissingExpiresIn => {
                write!(f, "device flow: missing expires_in")
            }
            DeviceFlowErrorKind::InvalidExpiresIn => {
                write!(f, "device flow: invalid expires_in value")
            }
            DeviceFlowErrorKind::InvalidInterval => {
                write!(f, "device flow: invalid interval value")
            }
            DeviceFlowErrorKind::AccessDenied => {
                write!(f, "device flow: authorization denied by user")
            }
            DeviceFlowErrorKind::ExpiredToken => {
                write!(f, "device flow: device_code expired")
            }
            DeviceFlowErrorKind::ServerError { error, description } => {
                write!(f, "device flow: OAuth error: {error}")?;
                if let Some(desc) = description {
                    write!(f, " ({desc})")?;
                }
                Ok(())
            }
            DeviceFlowErrorKind::TokenResponse(err) => {
                write!(f, "device flow: {err}")
            }
        }
    }
}

impl std::error::Error for DeviceFlowError {}

// ---------------------------------------------------------------------------
// DeviceAuthorizationRequest
// ---------------------------------------------------------------------------

/// A device authorization request (RFC 8628 §3.1).
///
/// Contains the pre-built `application/x-www-form-urlencoded` POST body and
/// the target endpoint URL. The caller POSTs the [`body`](Self::body) to the
/// [`endpoint`](Self::endpoint) using their HTTP transport.
#[doc(alias = "device_authorization")]
pub struct DeviceAuthorizationRequest {
    endpoint: String,
    body: String,
    content_type: &'static str,
}

impl DeviceAuthorizationRequest {
    /// Builds a device authorization request for a public client.
    ///
    /// # Parameters
    ///
    /// * `device_authorization_endpoint` — the provider's device
    ///   authorization endpoint (typically from OIDC discovery).
    /// * `client_id` — the public client identifier.
    /// * `scope` — a space-delimited scope string (e.g. `"openid profile"`),
    ///   or empty to omit the `scope` parameter.
    #[must_use]
    pub fn new(device_authorization_endpoint: &str, client_id: &str, scope: &str) -> Self {
        let mut body = String::with_capacity(128);
        body.push_str("client_id=");
        body.push_str(&url_encode_component(client_id));
        if !scope.is_empty() {
            body.push_str("&scope=");
            body.push_str(&url_encode_component(scope));
        }

        debug!(
            endpoint = %device_authorization_endpoint,
            "oauth: device authorization request built"
        );

        Self {
            endpoint: device_authorization_endpoint.to_owned(),
            body,
            content_type: "application/x-www-form-urlencoded",
        }
    }

    /// Returns the endpoint URL to POST this request to.
    #[must_use]
    #[inline]
    pub fn endpoint(&self) -> &str {
        &self.endpoint
    }

    /// Returns the URL-encoded POST body.
    #[must_use]
    #[inline]
    pub fn body(&self) -> &str {
        &self.body
    }

    /// Returns the `Content-Type` header value for this request.
    #[must_use]
    #[inline]
    pub fn content_type(&self) -> &str {
        self.content_type
    }
}

impl fmt::Debug for DeviceAuthorizationRequest {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // The device authorization request body carries no secret (public
        // client, client_id only) but is redacted for consistency.
        f.debug_struct("DeviceAuthorizationRequest")
            .field("endpoint", &self.endpoint)
            .field("body", &"[REDACTED]")
            .field("content_type", &self.content_type)
            .finish()
    }
}

// ---------------------------------------------------------------------------
// DeviceAuthorizationResponse
// ---------------------------------------------------------------------------

/// A parsed device authorization response (RFC 8628 §3.2).
///
/// # Security
///
/// SECURITY: `device_code` is a bearer credential and is stored in a
/// [`Zeroizing`](crate::crypto::zeroize::Zeroizing) wrapper that clears
/// memory on drop; [`Debug`] redacts it. `user_code` is user-facing.
#[doc(alias = "device_authorization_response")]
pub struct DeviceAuthorizationResponse {
    device_code: Zeroizing<String>,
    user_code: String,
    verification_uri: String,
    verification_uri_complete: Option<String>,
    expires_in: u64,
    interval: u64,
}

impl DeviceAuthorizationResponse {
    /// Parses a JSON device authorization response body.
    ///
    /// # Errors
    ///
    /// Returns [`DeviceFlowError`] if the JSON is invalid, a required field
    /// (`device_code`, `user_code`, `verification_uri`, `expires_in`) is
    /// missing, or `expires_in` / `interval` is present but not a
    /// non-negative integer.
    #[must_use = "parsing may fail; handle the Result"]
    pub fn parse(json: &str) -> Result<Self, DeviceFlowError> {
        let value = JsonValue::parse(json).map_err(|_| {
            warn!("oauth: device authorization response parse failed: invalid JSON");
            DeviceFlowError::new(DeviceFlowErrorKind::InvalidJson)
        })?;

        // SECURITY: wrap device_code in Zeroizing immediately.
        let device_code = Zeroizing::new(
            value
                .get_str("device_code")
                .ok_or_else(|| DeviceFlowError::new(DeviceFlowErrorKind::MissingDeviceCode))?
                .to_owned(),
        );

        let user_code = value
            .get_str("user_code")
            .ok_or_else(|| DeviceFlowError::new(DeviceFlowErrorKind::MissingUserCode))?
            .to_owned();

        let verification_uri = value
            .get_str("verification_uri")
            .ok_or_else(|| DeviceFlowError::new(DeviceFlowErrorKind::MissingVerificationUri))?
            .to_owned();

        let verification_uri_complete =
            value.get_str("verification_uri_complete").map(String::from);

        let expires_in = match parse_non_negative(&value, "expires_in") {
            NumField::Value(v) => v,
            NumField::Absent => {
                return Err(DeviceFlowError::new(DeviceFlowErrorKind::MissingExpiresIn));
            }
            NumField::Invalid => {
                return Err(DeviceFlowError::new(DeviceFlowErrorKind::InvalidExpiresIn));
            }
        };

        // `interval` is optional; default to 5s per RFC 8628 §3.2.
        let interval = match parse_non_negative(&value, "interval") {
            NumField::Value(v) => v,
            NumField::Absent => DEFAULT_POLL_INTERVAL_SECS,
            NumField::Invalid => {
                return Err(DeviceFlowError::new(DeviceFlowErrorKind::InvalidInterval));
            }
        };

        info!(
            user_code = %user_code,
            expires_in,
            interval,
            "oauth: device authorization response parsed"
        );

        Ok(Self {
            device_code,
            user_code,
            verification_uri,
            verification_uri_complete,
            expires_in,
            interval,
        })
    }

    /// Returns the device verification code (bearer credential for polling).
    ///
    /// # Security
    ///
    /// SECURITY: The caller must not log this value.
    #[must_use]
    #[inline]
    pub fn device_code(&self) -> &str {
        &self.device_code
    }

    /// Returns the end-user code to display (e.g. `"WDJB-MJHT"`).
    #[must_use]
    #[inline]
    pub fn user_code(&self) -> &str {
        &self.user_code
    }

    /// Returns the verification URI the user visits to approve.
    #[must_use]
    #[inline]
    pub fn verification_uri(&self) -> &str {
        &self.verification_uri
    }

    /// Returns the verification URI with the `user_code` pre-filled, if the
    /// provider supplied one (RFC 8628 §3.2). Ideal for a QR code.
    #[must_use]
    #[inline]
    pub fn verification_uri_complete(&self) -> Option<&str> {
        self.verification_uri_complete.as_deref()
    }

    /// Returns the lifetime in seconds of the `device_code` / `user_code`.
    #[must_use]
    #[inline]
    pub fn expires_in(&self) -> u64 {
        self.expires_in
    }

    /// Returns the minimum polling interval in seconds (defaults to
    /// [`DEFAULT_POLL_INTERVAL_SECS`] when the provider omits it).
    #[must_use]
    #[inline]
    pub fn interval(&self) -> u64 {
        self.interval
    }
}

impl fmt::Debug for DeviceAuthorizationResponse {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // SECURITY: redact device_code.
        f.debug_struct("DeviceAuthorizationResponse")
            .field("device_code", &"[REDACTED]")
            .field("user_code", &self.user_code)
            .field("verification_uri", &self.verification_uri)
            .field("verification_uri_complete", &self.verification_uri_complete)
            .field("expires_in", &self.expires_in)
            .field("interval", &self.interval)
            .finish()
    }
}

/// The three outcomes of reading a non-negative integer field, letting
/// callers distinguish a missing field from a malformed one.
enum NumField {
    /// The field was absent or JSON `null`.
    Absent,
    /// The field was present but not a non-negative integer.
    Invalid,
    /// A valid non-negative value.
    Value(u64),
}

/// Reads a non-negative integer field from a JSON object.
fn parse_non_negative(value: &JsonValue, key: &str) -> NumField {
    match value.get(key) {
        None => NumField::Absent,
        Some(v) if v.is_null() => NumField::Absent,
        Some(v) => match v.as_i64() {
            Some(n) if n >= 0 =>
            {
                #[allow(clippy::cast_sign_loss)]
                NumField::Value(n as u64)
            }
            _ => NumField::Invalid,
        },
    }
}

// ---------------------------------------------------------------------------
// DeviceAccessTokenRequest
// ---------------------------------------------------------------------------

/// A device access token (poll) request (RFC 8628 §3.4).
///
/// Built once per poll and sent to the token endpoint via POST. Contains
/// the device-code grant body.
///
/// # Security
///
/// SECURITY: The body contains the `device_code` bearer credential; it is
/// wrapped in [`Zeroizing`](crate::crypto::zeroize::Zeroizing) and redacted
/// from [`Debug`].
#[doc(alias = "device_token_request")]
pub struct DeviceAccessTokenRequest {
    endpoint: String,
    body: Zeroizing<String>,
    content_type: &'static str,
}

impl DeviceAccessTokenRequest {
    /// Builds a device access token poll request for a public client.
    ///
    /// # Parameters
    ///
    /// * `token_endpoint` — the provider's token endpoint.
    /// * `client_id` — the public client identifier.
    /// * `device_code` — the `device_code` from the authorization response.
    #[must_use]
    pub fn new(token_endpoint: &str, client_id: &str, device_code: &str) -> Self {
        let mut body = String::with_capacity(256);
        body.push_str("grant_type=");
        body.push_str(&url_encode_component(DEVICE_GRANT_TYPE));
        body.push_str("&device_code=");
        body.push_str(&url_encode_component(device_code));
        body.push_str("&client_id=");
        body.push_str(&url_encode_component(client_id));

        // SECURITY: never log the device_code.
        debug!(endpoint = %token_endpoint, "oauth: device token poll request built");

        Self {
            endpoint: token_endpoint.to_owned(),
            body: Zeroizing::new(body),
            content_type: "application/x-www-form-urlencoded",
        }
    }

    /// Returns the endpoint URL to POST this request to.
    #[must_use]
    #[inline]
    pub fn endpoint(&self) -> &str {
        &self.endpoint
    }

    /// Returns the URL-encoded POST body.
    #[must_use]
    #[inline]
    pub fn body(&self) -> &str {
        &self.body
    }

    /// Returns the `Content-Type` header value for this request.
    #[must_use]
    #[inline]
    pub fn content_type(&self) -> &str {
        self.content_type
    }
}

impl fmt::Debug for DeviceAccessTokenRequest {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // SECURITY: redact body which contains the device_code.
        f.debug_struct("DeviceAccessTokenRequest")
            .field("endpoint", &self.endpoint)
            .field("body", &"[REDACTED]")
            .field("content_type", &self.content_type)
            .finish()
    }
}

// ---------------------------------------------------------------------------
// DeviceTokenOutcome
// ---------------------------------------------------------------------------

/// The classified result of a single device-token poll (RFC 8628 §3.5).
///
/// The non-terminal states ([`Pending`](Self::Pending),
/// [`SlowDown`](Self::SlowDown)) are returned as `Ok` so the caller keeps
/// polling; terminal failures (`access_denied`, `expired_token`, other
/// server errors, malformed tokens) are returned as [`DeviceFlowError`].
#[derive(Debug)]
#[non_exhaustive]
pub enum DeviceTokenOutcome {
    /// Authorization complete — carries the issued tokens.
    Authorized(TokenResponse),
    /// The user has not yet approved. Wait `interval` seconds and poll again.
    Pending,
    /// Polling too fast. Increase the interval by
    /// [`SLOW_DOWN_INCREMENT_SECS`] and poll again.
    SlowDown,
}

impl DeviceTokenOutcome {
    /// Classifies a JSON token-endpoint response received while polling.
    ///
    /// # Errors
    ///
    /// Returns [`DeviceFlowError`] for terminal conditions: `access_denied`,
    /// `expired_token`, any other OAuth error code, invalid JSON, or an
    /// authorized response whose token payload fails to parse. The
    /// non-terminal `authorization_pending` and `slow_down` states are
    /// returned as `Ok` variants.
    #[must_use = "the poll outcome determines whether to keep waiting"]
    pub fn parse(json: &str) -> Result<Self, DeviceFlowError> {
        let value = JsonValue::parse(json).map_err(|_| {
            warn!("oauth: device token poll parse failed: invalid JSON");
            DeviceFlowError::new(DeviceFlowErrorKind::InvalidJson)
        })?;

        // RFC 6749 §5.2 / RFC 8628 §3.5: an error response is identified by
        // the presence of `error`. Gate on presence (not on it being a
        // string) so a hostile non-string `error` can't slip through as a
        // success alongside a forged `access_token`.
        if value.get("error").is_some() {
            let error = value.get_str("error").unwrap_or("invalid_error");
            return match error {
                "authorization_pending" => Ok(Self::Pending),
                "slow_down" => Ok(Self::SlowDown),
                "access_denied" => Err(DeviceFlowError::new(DeviceFlowErrorKind::AccessDenied)),
                "expired_token" => Err(DeviceFlowError::new(DeviceFlowErrorKind::ExpiredToken)),
                other => {
                    let description = value.get_str("error_description").map(String::from);
                    warn!(code = %other, "oauth: device token poll error");
                    Err(DeviceFlowError::new(DeviceFlowErrorKind::ServerError {
                        error: other.to_owned(),
                        description,
                    }))
                }
            };
        }

        // No error field: this should be a successful token response. Reuse
        // the shared token-response parser.
        let token = TokenResponse::parse(json)
            .map_err(|e| DeviceFlowError::new(DeviceFlowErrorKind::TokenResponse(e)))?;
        Ok(Self::Authorized(token))
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    // --- DeviceAuthorizationRequest ---

    #[test]
    fn auth_request_contains_client_id_and_scope() {
        let req = DeviceAuthorizationRequest::new(
            "https://idp.example.com/device",
            "my-client",
            "openid profile",
        );
        assert_eq!(req.endpoint(), "https://idp.example.com/device");
        assert!(req.body().contains("client_id=my-client"));
        // space in scope is URL-encoded
        assert!(
            req.body().contains("scope=openid%20profile"),
            "{}",
            req.body()
        );
        assert_eq!(req.content_type(), "application/x-www-form-urlencoded");
    }

    #[test]
    fn auth_request_omits_empty_scope() {
        let req = DeviceAuthorizationRequest::new("https://idp.example.com/device", "c", "");
        assert!(!req.body().contains("scope="));
    }

    #[test]
    fn auth_request_debug_redacts_body() {
        let req = DeviceAuthorizationRequest::new("https://idp.example.com/device", "c", "openid");
        assert!(format!("{req:?}").contains("[REDACTED]"));
    }

    // --- DeviceAuthorizationResponse::parse ---

    fn full_auth_response() -> &'static str {
        r#"{
            "device_code": "dev-code-abc",
            "user_code": "WDJB-MJHT",
            "verification_uri": "https://idp.example.com/activate",
            "verification_uri_complete": "https://idp.example.com/activate?user_code=WDJB-MJHT",
            "expires_in": 1800,
            "interval": 5
        }"#
    }

    #[test]
    fn parses_full_authorization_response() {
        let r = DeviceAuthorizationResponse::parse(full_auth_response()).unwrap();
        assert_eq!(r.device_code(), "dev-code-abc");
        assert_eq!(r.user_code(), "WDJB-MJHT");
        assert_eq!(r.verification_uri(), "https://idp.example.com/activate");
        assert_eq!(
            r.verification_uri_complete(),
            Some("https://idp.example.com/activate?user_code=WDJB-MJHT")
        );
        assert_eq!(r.expires_in(), 1800);
        assert_eq!(r.interval(), 5);
    }

    #[test]
    fn interval_defaults_to_five_when_absent() {
        let json = r#"{"device_code":"d","user_code":"U","verification_uri":"https://x/a","expires_in":900}"#;
        let r = DeviceAuthorizationResponse::parse(json).unwrap();
        assert_eq!(r.interval(), DEFAULT_POLL_INTERVAL_SECS);
        assert_eq!(r.verification_uri_complete(), None);
    }

    #[test]
    fn missing_device_code_is_error() {
        let json = r#"{"user_code":"U","verification_uri":"https://x/a","expires_in":900}"#;
        assert!(DeviceAuthorizationResponse::parse(json).is_err());
    }

    #[test]
    fn missing_expires_in_is_error() {
        let json = r#"{"device_code":"d","user_code":"U","verification_uri":"https://x/a"}"#;
        assert!(DeviceAuthorizationResponse::parse(json).is_err());
    }

    #[test]
    fn negative_expires_in_is_error() {
        let json = r#"{"device_code":"d","user_code":"U","verification_uri":"https://x/a","expires_in":-1}"#;
        assert!(DeviceAuthorizationResponse::parse(json).is_err());
    }

    #[test]
    fn invalid_json_is_error() {
        assert!(DeviceAuthorizationResponse::parse("not json").is_err());
    }

    #[test]
    fn auth_response_debug_redacts_device_code() {
        let r = DeviceAuthorizationResponse::parse(full_auth_response()).unwrap();
        let dbg = format!("{r:?}");
        assert!(dbg.contains("[REDACTED]"));
        assert!(!dbg.contains("dev-code-abc"));
    }

    // --- DeviceAccessTokenRequest ---

    #[test]
    fn token_request_has_device_grant_and_encoded_fields() {
        let req = DeviceAccessTokenRequest::new(
            "https://idp.example.com/token",
            "my-client",
            "dev-code-abc",
        );
        assert_eq!(req.endpoint(), "https://idp.example.com/token");
        // grant_type urn is URL-encoded (colons -> %3A)
        assert!(
            req.body()
                .contains("grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code"),
            "{}",
            req.body()
        );
        assert!(req.body().contains("device_code=dev-code-abc"));
        assert!(req.body().contains("client_id=my-client"));
    }

    #[test]
    fn token_request_debug_redacts_body() {
        let req =
            DeviceAccessTokenRequest::new("https://idp.example.com/token", "c", "secret-code");
        let dbg = format!("{req:?}");
        assert!(dbg.contains("[REDACTED]"));
        assert!(!dbg.contains("secret-code"));
    }

    // --- DeviceTokenOutcome::parse ---

    #[test]
    fn poll_authorization_pending_is_pending() {
        let out = DeviceTokenOutcome::parse(r#"{"error":"authorization_pending"}"#).unwrap();
        assert!(matches!(out, DeviceTokenOutcome::Pending));
    }

    #[test]
    fn poll_slow_down_is_slow_down() {
        let out = DeviceTokenOutcome::parse(r#"{"error":"slow_down"}"#).unwrap();
        assert!(matches!(out, DeviceTokenOutcome::SlowDown));
    }

    #[test]
    fn poll_access_denied_is_terminal_error() {
        let err = DeviceTokenOutcome::parse(r#"{"error":"access_denied"}"#).unwrap_err();
        assert!(err.is_access_denied());
    }

    #[test]
    fn poll_expired_token_is_terminal_error() {
        let err = DeviceTokenOutcome::parse(r#"{"error":"expired_token"}"#).unwrap_err();
        assert!(err.is_expired());
    }

    #[test]
    fn poll_unknown_error_is_server_error() {
        let err = DeviceTokenOutcome::parse(r#"{"error":"invalid_client"}"#).unwrap_err();
        assert!(!err.is_access_denied() && !err.is_expired());
    }

    #[test]
    fn poll_success_is_authorized() {
        let json = r#"{"access_token":"at-123","token_type":"Bearer","expires_in":3600}"#;
        let out = DeviceTokenOutcome::parse(json).unwrap();
        match out {
            DeviceTokenOutcome::Authorized(t) => {
                assert_eq!(t.access_token(), "at-123");
                assert_eq!(t.token_type(), "Bearer");
            }
            _ => panic!("expected Authorized"),
        }
    }

    #[test]
    fn poll_invalid_json_is_error() {
        assert!(DeviceTokenOutcome::parse("nope").is_err());
    }
}