grr_cli/core/auth/

device.rs

//! OAuth 2.0 Device Authorization Grant (RFC 8628).
//!
//! Headless fallback for the default PKCE loopback flow: the CLI shows a
//! URL plus a user code, the user approves in any browser (on any device),
//! and the CLI polls the token endpoint until approval lands.
//!
//! A configured client secret is sent when present; secretless PKCE
//! providers work with it absent.

use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};

use anyhow::anyhow;

use crate::core::error::{GrrError, Result, json_error_detail};
use tracing::warn;

use super::TokenStorage;

const DEVICE_CODE_URL: &str = "https://oauth2.googleapis.com/device/code";
const DEVICE_GRANT: &str = "urn:ietf:params:oauth:grant-type:device_code";

/// The scopes Google's device flow will actually grant.
///
/// The flow keeps its own allowlist: anything outside it comes back as
/// `invalid_scope: Invalid device flow scope: <scope>`, which fails the whole
/// request. It lives per flow, not in the Discovery index, so it cannot be
/// derived from the embedded data.
///
/// Verified against the live device endpoint on 2026-10-13 with a "TVs and
/// Limited Input devices" client — one scope at a time, because Google names
/// only the first offender. Google's own page (below) is *not* the endpoint's
/// truth: it lists `drive.appdata` and `drive.metadata.readonly`, which the
/// endpoint rejects, and omits the legacy GData scopes, which it accepts.
///
/// Source: <https://developers.google.com/identity/protocols/oauth2/limited-input-device>
const DEVICE_FLOW_SCOPES: &[&str] = &[
    "https://www.google.com/calendar/feeds",
    "https://www.google.com/m8/feeds",
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/calendar.readonly",
    "https://www.googleapis.com/auth/drive.file",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/userinfo.profile",
    "openid",
];

/// The consent set the device flow may send: `requested` — the flag-derived set
/// `grr auth login` would have used, `--service`/`--all-scopes` included —
/// filtered to what a TV/limited-input client can be granted. An
/// *intersection*, never a union: one scope outside Google's allowlist fails
/// the whole request with `invalid_scope`, granting nothing.
///
/// A device login is therefore a *narrower* credential than a browser login —
/// Gmail, Chat, Docs, Sheets, Slides, Tasks, Forms, Apps Script, Analytics and
/// the admin surfaces are all outside Google's allowlist. That is Google's
/// rule, not a choice here; asking anyway would grant nothing at all. What the
/// allowlist drops is logged, so the user learns the grant is narrower than the
/// flags asked for before they approve it, rather than after a 403.
pub(crate) fn device_flow_scopes(requested: &[String]) -> Vec<String> {
    let mut granted: Vec<String> = requested
        .iter()
        .filter(|scope| DEVICE_FLOW_SCOPES.contains(&scope.as_str()))
        .cloned()
        .collect();
    // Sorted so the consent string is byte-stable whatever order the flags
    // produced.
    granted.sort_unstable();
    granted.dedup();

    if granted.len() < requested.len() {
        warn!(
            "device flow: Google grants a TV/limited-input client {} of the {} scopes requested \
             (drive.file, calendar and legacy Calendar/Contacts, userinfo, openid); the {} it \
             drops — Gmail, Chat, Docs, Sheets, Slides, Tasks, Forms, Apps Script, Analytics and \
             the admin APIs — need the browser flow (`grr auth login`).",
            granted.len(),
            requested.len(),
            requested.len() - granted.len()
        );
    }
    granted
}

/// Pending device authorization: show `verification_url` + `user_code` to
/// the user, then poll with [`super::GoogleAuth::poll_device_code`] until done.
pub struct DeviceAuthChallenge {
    /// URL the user must open (e.g. <https://www.google.com/device>).
    pub verification_url: String,
    /// Short code the user types at `verification_url`.
    pub user_code: String,
    pub(crate) device_code: String,
    pub(crate) interval: Duration,
    pub(crate) deadline: Instant,
}

impl DeviceAuthChallenge {
    /// How long to wait before the next poll (grows on `slow_down`).
    pub fn retry_after(&self) -> Duration {
        self.interval
    }

    /// Whether the user code has expired and the flow must restart.
    pub fn is_expired(&self) -> bool {
        Instant::now() >= self.deadline
    }
}

impl super::GoogleAuth {
    /// The client the device flow must authenticate as, plus its secret.
    ///
    /// Google's device endpoint accepts one client type only — "TVs and
    /// Limited Input devices" — and answers the browser flow's Desktop
    /// client with `invalid_client: Invalid client type`, which tells a
    /// user nothing. Refusing locally, with the console steps, is the fix.
    fn device_client(&self) -> Result<(String, Option<String>)> {
        let id = self
            .config
            .device_client_id
            .as_deref()
            .map(str::trim)
            .filter(|id| !id.is_empty())
            .ok_or_else(|| {
                GrrError::Auth(
                    anyhow!(
                        "the device flow needs an OAuth client of type \"TVs and Limited Input \
                         devices\": Google rejects the Desktop client with `Invalid client type`.\n\
                         Create one in the Google Cloud console (APIs & Services → Credentials → \
                         Create credentials → OAuth client ID → TVs and Limited Input devices), \
                         then supply it as GRR_OAUTH__DEVICE_CLIENT_ID / \
                         GRR_OAUTH__DEVICE_CLIENT_SECRET, or as device-client-id / \
                         device-client-secret in the [oauth] block of ~/.grr/config.toml. \
                         Building from source can also bake it in: GRR_DEVICE_CLIENT_ID / \
                         GRR_DEVICE_CLIENT_SECRET (or a repo-root .env).\n\
                         The browser flow (`grr auth login`) needs none of this."
                    )
                    .into(),
                )
            })?;

        let secret = self
            .config
            .device_client_secret
            .as_deref()
            .map(str::trim)
            .filter(|secret| !secret.is_empty())
            .map(str::to_owned);
        Ok((id.to_owned(), secret))
    }

    /// Start a device flow asking for exactly `scopes` — the caller's
    /// flag-derived set, already intersected with Google's allowlist by
    /// [`device_flow_scopes`]. Returns the challenge to display to the user.
    pub async fn request_device_code(&self, scopes: &[String]) -> Result<DeviceAuthChallenge> {
        let (client_id, client_secret) = self.device_client()?;
        if scopes.is_empty() {
            return Err(GrrError::Auth(
                anyhow!(
                    "the requested scopes are all outside Google's device-flow allowlist, so the \
                     device endpoint would refuse the whole request; the browser flow \
                     (`grr auth login`) can ask for them"
                )
                .into(),
            ));
        }

        let form = vec![("client_id", client_id), ("scope", scopes.join(" "))];

        let (status, body) = self
            .token_request(DEVICE_CODE_URL, client_secret.as_deref(), form)
            .await?;

        if !status.is_success() {
            // `invalid_scope` here means Google's per-flow allowlist moved:
            // the scope is one this flow cannot show, so the whole request is
            // refused. Say that, rather than repeating a bare scope URL, and
            // point at the list that has to be updated.
            let detail = json_error_detail(&body);
            let hint = if body["error"].as_str() == Some("invalid_scope") {
                "\nGoogle's device flow keeps its own scope allowlist (DEVICE_FLOW_SCOPES in \
                 src/core/auth/device.rs, verified 2026-10-13). It has moved: update that list, \
                 or use the browser flow (`grr auth login`), which has no such ceiling."
            } else {
                ""
            };
            return Err(GrrError::Auth(
                anyhow!("device endpoint returned {status}: {detail}{hint}").into(),
            ));
        }

        let device_code = body["device_code"]
            .as_str()
            .ok_or_else(|| GrrError::Auth(anyhow!("device endpoint omitted device_code").into()))?;
        let user_code = body["user_code"]
            .as_str()
            .ok_or_else(|| GrrError::Auth(anyhow!("device endpoint omitted user_code").into()))?;
        let verification_url = body
            .get("verification_url")
            .or_else(|| body.get("verification_uri"))
            .and_then(serde_json::Value::as_str)
            .ok_or_else(|| {
                GrrError::Auth(anyhow!("device endpoint omitted verification_url").into())
            })?;

        let expires_in = body["expires_in"].as_u64().unwrap_or(1800);
        let interval = body["interval"]
            .as_u64()
            .map(Duration::from_secs)
            .filter(|d| !d.is_zero())
            .unwrap_or_else(|| Duration::from_secs(5));

        Ok(DeviceAuthChallenge {
            verification_url: verification_url.to_string(),
            user_code: user_code.to_string(),
            device_code: device_code.to_string(),
            interval,
            deadline: Instant::now() + Duration::from_secs(expires_in),
        })
    }

    /// Poll once. Returns `Ok(None)` while the user has not approved yet
    /// (caller sleeps `retry_after()` and retries), `Ok(Some)` with the
    /// stored token on approval, or `Err` on denial/expiry/failure.
    ///
    /// `scopes` is the same set [`Self::request_device_code`] was called with:
    /// it is what the credential records when Google's response omits `scope`,
    /// so the fallback is what was *requested*, never the index superset.
    pub async fn poll_device_code(
        &self,
        challenge: &mut DeviceAuthChallenge,
        scopes: &[String],
    ) -> Result<Option<TokenStorage>> {
        // Device polling reports status via 400 + JSON error codes, so the
        // body — not the HTTP status — drives the decision below.
        let (client_id, client_secret) = self.device_client()?;
        let (_, body) = self
            .token_request(
                &self.token_endpoint,
                client_secret.as_deref(),
                vec![
                    ("client_id", client_id),
                    ("device_code", challenge.device_code.clone()),
                    ("grant_type", DEVICE_GRANT.to_string()),
                ],
            )
            .await?;

        if let Some(code) = body["error"].as_str() {
            match code {
                "authorization_pending" => return Ok(None),
                "slow_down" => {
                    challenge.interval += Duration::from_secs(5);
                    return Ok(None);
                }
                _ => {
                    return Err(GrrError::Auth(
                        anyhow!("device poll failed: {}", json_error_detail(&body)).into(),
                    ));
                }
            }
        }

        let storage = token_storage_from_response(&body, scopes)?;
        *self.token_storage.write().await = Some(storage.clone());
        self.save_token(&storage).await?;
        Ok(Some(storage))
    }

    /// Fresh interactive login: drops any stored (possibly dead) token, runs
    /// the PKCE browser flow with exactly `scopes`, saves and returns the new
    /// token. The caller decides the set — see [`super::login_scopes`],
    /// [`super::scopes_for_service`] and [`super::scopes`].
    pub async fn login(&self, scopes: &[String]) -> Result<TokenStorage> {
        // Best effort: a dead on-disk token must never block fresh consent.
        let _ = self.revoke().await;
        let storage = self.run_oauth_flow(scopes).await?;
        *self.token_storage.write().await = Some(storage.clone());
        self.save_token(&storage).await?;
        Ok(storage)
    }
}

/// Build [`TokenStorage`] from a successful token-endpoint JSON body.
/// Shared by the PKCE exchange and the device poll.
///
/// `scopes` is what the caller wants stored when the response is silent:
/// the *requested* list on a fresh login, or the stored credential's own
/// scope on a refresh (which sends no scope list at all). Google's response
/// carries what was actually *granted* in `scope`, and the two genuinely
/// differ — the consent screen lets a user approve a subset, and a project
/// whose consent screen does not declare a scope (Google Auth Platform →
/// Data access) is granted nothing for it, silently. Storing the request as
/// if it were the grant makes a later 403 look like a stale token instead of
/// a scope the account never approved, so the response wins whenever it says
/// anything; this list is only the fallback for providers that omit it.
pub(crate) fn token_storage_from_response(
    token_data: &serde_json::Value,
    scopes: &[String],
) -> Result<TokenStorage> {
    let access_token = token_data["access_token"]
        .as_str()
        .ok_or_else(|| GrrError::Auth(anyhow!("No access token in response").into()))?
        .to_string();

    let expires_in = token_data["expires_in"].as_u64().unwrap_or(3600);
    let refresh_token = token_data["refresh_token"].as_str().map(str::to_string);

    let expires_at = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_secs())
        .unwrap_or(0)
        + expires_in;

    let granted = token_data["scope"]
        .as_str()
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .map(str::to_owned)
        .unwrap_or_else(|| scopes.join(" "));

    Ok(TokenStorage {
        access_token,
        refresh_token,
        expires_at,
        token_type: "Bearer".to_string(),
        scope: granted,
    })
}

#[cfg(test)]
mod tests {
    use super::super::{GoogleAuth, TokenStorage};
    use crate::core::config::OAuthConfig;

    async fn auth(device: Option<(&str, &str)>) -> crate::core::error::Result<GoogleAuth> {
        let config = OAuthConfig {
            client_id: "desktop-id.apps.googleusercontent.com".into(),
            client_secret: Some("desktop-secret".into()),
            device_client_id: device.map(|(id, _)| id.to_owned()),
            device_client_secret: device.map(|(_, secret)| secret.to_owned()),
        };
        let storage = TokenStorage {
            access_token: "test-token".into(),
            refresh_token: None,
            expires_at: u64::MAX,
            token_type: "Bearer".into(),
            scope: String::new(),
        };
        GoogleAuth::with_token(config, storage).await
    }

    /// The token response says what was granted; the request only says what
    /// was asked for. Google drops scopes a project has not declared (Data
    /// access), and the consent screen lets a user approve a subset — so the
    /// stored grant is what makes a later 403 diagnosable instead of looking
    /// like a stale token.
    #[test]
    fn the_stored_scope_is_the_grant_not_the_request() -> anyhow::Result<()> {
        let requested = vec!["https://www.googleapis.com/auth/gmail.readonly".to_owned()];

        let granted = super::token_storage_from_response(
            &serde_json::json!({
                "access_token": "t",
                "expires_in": 3600,
                "scope": "openid https://www.googleapis.com/auth/userinfo.email",
            }),
            &requested,
        )?;
        assert_eq!(
            granted.scope,
            "openid https://www.googleapis.com/auth/userinfo.email"
        );

        // A response that says nothing about scope falls back to the request.
        let silent = super::token_storage_from_response(
            &serde_json::json!({ "access_token": "t", "expires_in": 3600 }),
            &requested,
        )?;
        assert_eq!(silent.scope, requested.join(" "));

        // So does a blank one (a provider placeholder must not erase the set).
        let blank = super::token_storage_from_response(
            &serde_json::json!({ "access_token": "t", "scope": "   " }),
            &requested,
        )?;
        assert_eq!(blank.scope, requested.join(" "));

        Ok(())
    }

    /// Google rejects every scope outside its device-flow allowlist with
    /// `invalid_scope` — one bad scope fails the whole request — so the device
    /// consent set is the *intersection* of the flag-derived request with that
    /// allowlist: never a union, never the index superset, and the flags do
    /// govern (`--all-scopes` is the only way the allowlist's drive.file and
    /// calendar.readonly come along, because the default set does not ask for
    /// them).
    #[test]
    fn the_device_flow_requests_the_flags_intersected_with_the_allowlist() {
        let consent = crate::core::auth::scopes();
        let login = crate::core::auth::login_scopes();

        // `grr auth login --device` with no flags: the default set, filtered.
        let default = super::device_flow_scopes(&login);
        for granted in [
            "https://www.googleapis.com/auth/calendar",
            "https://www.googleapis.com/auth/userinfo.email",
            "openid",
        ] {
            assert!(
                default.contains(&granted.to_owned()),
                "{granted} was dropped"
            );
        }
        // Asked for by the default set, outside the allowlist: one of these
        // reaching Google fails the whole request.
        for rejected in [
            "https://mail.google.com/",
            "https://www.googleapis.com/auth/drive",
            "https://www.googleapis.com/auth/drive.appdata",
            "https://www.googleapis.com/auth/drive.metadata.readonly",
        ] {
            assert!(
                !default.contains(&rejected.to_owned()),
                "{rejected} must never reach the device endpoint"
            );
        }
        assert!(
            !default.iter().any(|s| s.contains("/auth/chat.")),
            "Chat is not a device-flow scope: {default:?}"
        );
        // The default set asks for `drive`, not drive.file: the device flow
        // stops being useful for the allowlist-only scopes until a flag asks.
        for allowlist_only in [
            "https://www.googleapis.com/auth/drive.file",
            "https://www.googleapis.com/auth/calendar.readonly",
        ] {
            assert!(!default.contains(&allowlist_only.to_owned()));
            assert!(
                login.iter().all(|scope| scope != allowlist_only),
                "{allowlist_only} unexpectedly entered the default login set"
            );
        }

        // `--all-scopes`: the whole index, still intersected.
        let all = super::device_flow_scopes(consent);
        for useful in [
            "https://www.googleapis.com/auth/drive.file",
            "https://www.googleapis.com/auth/calendar.readonly",
        ] {
            assert!(all.contains(&useful.to_owned()), "{useful} was dropped");
        }
        assert_eq!(
            all,
            consent
                .iter()
                .filter(|scope| super::DEVICE_FLOW_SCOPES.contains(&scope.as_str()))
                .cloned()
                .collect::<Vec<_>>(),
            "--all-scopes must be exactly the index intersected with the allowlist"
        );

        // Never wider than the request, never outside the allowlist, and
        // byte-stable however the request was ordered.
        for scope in all.iter().chain(default.iter()) {
            assert!(
                consent.iter().any(|known| known == scope),
                "{scope} is not in the consent set at all"
            );
            assert!(
                super::DEVICE_FLOW_SCOPES.contains(&scope.as_str()),
                "{scope} is not in Google's device-flow allowlist"
            );
        }
        let mut shuffled = login.clone();
        shuffled.reverse();
        assert_eq!(default, super::device_flow_scopes(&shuffled));
    }

    /// Google answers the Desktop client's device request with
    /// `invalid_client: Invalid client type` — a message that names neither
    /// the cause nor the fix. The flow refuses locally instead, naming the
    /// client type and every knob that supplies it.
    #[tokio::test]
    async fn a_missing_device_client_is_refused_locally_with_instructions() -> anyhow::Result<()> {
        let Err(err) = auth(None).await?.device_client() else {
            return Err(anyhow::anyhow!(
                "a build with no device client must refuse locally, not call Google"
            ));
        };
        let err = err.to_string();
        assert!(
            err.contains("TVs and Limited Input devices"),
            "does not name the client type: {err}"
        );
        assert!(
            err.contains("GRR_OAUTH__DEVICE_CLIENT_ID"),
            "the runtime env knob is not named: {err}"
        );
        assert!(
            err.contains("device-client-id"),
            "no config-file knob named: {err}"
        );
        Ok(())
    }

    /// The device flow authenticates as the device client, so the Desktop id
    /// never reaches Google's device endpoint (which would reject it).
    #[tokio::test]
    async fn the_configured_device_client_is_the_one_used() -> anyhow::Result<()> {
        let (id, secret) = auth(Some((
            "device-id.apps.googleusercontent.com",
            "device-secret",
        )))
        .await?
        .device_client()?;
        assert_eq!(id, "device-id.apps.googleusercontent.com");
        assert_eq!(secret.as_deref(), Some("device-secret"));
        assert_ne!(
            id, "desktop-id.apps.googleusercontent.com",
            "the browser client must not be sent to the device endpoint"
        );
        Ok(())
    }
}