Merge pull request #153 from twitch-rs/dcf

implement DCF

Author: Emilgardis

CHANGELOG.md

@@ -10,10 +10,16 @@
 
 - MSRV bumped to `1.71.1`
 - Fixed a typo in `ModeratorManageGuestStart` (now: `ModeratorManageGuestStar`)
+- `RefreshToken::refresh_token` takes an optional secret to allow public clients to refresh tokens.
+
+### Added
+
+- Added support for Device Code Flow with `DeviceUserTokenBuilder`
 
 ### Fixed
 
 - `AppAccessToken` and `UserToken` now return the correct duration in `expires_in` after refreshing.
+- It's now possible to refresh a token without a client secret if the token supports it (e.g public client type).
 
 ## [v0.14.0] - 2024-09-23
 

Cargo.toml

@@ -87,6 +87,11 @@ name = "mock_user"
 path = "examples/mock_user.rs"
 required-features = ["reqwest", "mock_api"]
 
+[[example]]
+name = "device_code_flow"
+path = "examples/device_code_flow.rs"
+required-features = ["reqwest", "client"]
+
 [package.metadata.docs.rs]
 features = ["all", "mock_api"]
 rustc-args = ["--cfg", "nightly"]

examples/auth_flow.rs

@@ -1,6 +1,9 @@
 //! This is an example of the Authorization code grant flow using `twitch_oauth2`
 //!
 //! See https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#authorization-code-grant-flow
+//!
+//! See also the `device_code_flow` example for possibly easier integration.
+
 use anyhow::Context;
 use twitch_oauth2::tokens::UserTokenBuilder;
 

examples/device_code_flow.rs

@@ -0,0 +1,46 @@
+//! Example of how to create a user token using device code flow.
+//! The device code flow can be used on confidential and public clients.
+use twitch_oauth2::{DeviceUserTokenBuilder, TwitchToken, UserToken};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let _ = dotenv::dotenv(); // Eat error
+    let mut args = std::env::args().skip(1);
+
+    // Setup the http client to use with the library.
+    let reqwest = reqwest::Client::builder()
+        .redirect(reqwest::redirect::Policy::none())
+        .build()?;
+
+    // Grab the client id, convert to a `ClientId` with the `new` method.
+    let client_id = get_env_or_arg("TWITCH_CLIENT_ID", &mut args)
+        .map(twitch_oauth2::ClientId::new)
+        .expect("Please set env: TWITCH_CLIENT_ID or pass client id as an argument");
+
+    // Create the builder!
+    let mut builder = DeviceUserTokenBuilder::new(client_id, Default::default());
+
+    // Start the device code flow. This will return a code that the user must enter on Twitch
+    let code = builder.start(&reqwest).await?;
+
+    println!("Please go to {0}", code.verification_uri);
+    println!(
+        "Waiting for user to authorize, time left: {0}",
+        code.expires_in
+    );
+
+    // Finish the auth with wait_for_code, this will return a token if the user has authorized the app
+    let mut token = builder.wait_for_code(&reqwest, tokio::time::sleep).await?;
+
+    println!("token: {:?}\nTrying to refresh the token", token);
+    // we can also refresh this token, even without a client secret
+    // if the application was created as a public client type in the twitch dashboard this will work,
+    // if the application is a confidential client type, this refresh will fail because it needs the client secret.
+    token.refresh_token(&reqwest).await?;
+    println!("refreshed token: {:?}", token);
+    Ok(())
+}
+
+fn get_env_or_arg(env: &str, args: &mut impl Iterator<Item = String>) -> Option<String> {
+    std::env::var(env).ok().or_else(|| args.next())
+}

src/id.rs

@@ -33,6 +33,18 @@ impl TwitchTokenResponse {
     ) -> Result<TwitchTokenResponse, RequestParseError> {
         crate::parse_response(response)
     }
+
+    /// Get the access token from this response
+    pub fn access_token(&self) -> &crate::AccessTokenRef { &self.access_token }
+
+    /// Get the expires in from this response
+    pub fn expires_in(&self) -> Option<Duration> { self.expires_in.map(Duration::from_secs) }
+
+    /// Get the refresh token from this response
+    pub fn refresh_token(&self) -> Option<&crate::RefreshTokenRef> { self.refresh_token.as_deref() }
+
+    /// Get the scopes from this response
+    pub fn scopes(&self) -> Option<&[crate::Scope]> { self.scopes.as_deref() }
 }
 
 /// Twitch's representation of the oauth flow for errors
@@ -60,6 +72,20 @@ impl std::fmt::Display for TwitchTokenErrorResponse {
         )
     }
 }
+/// Response from the device code flow
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct DeviceCodeResponse {
+    /// The identifier for a given user.
+    pub device_code: String,
+    /// Time until the code is no longer valid
+    pub expires_in: u64,
+    /// Time until another valid code can be requested
+    pub interval: u64,
+    /// The code that the user will use to authenticate
+    pub user_code: String,
+    /// The address you will send users to, to authenticate
+    pub verification_uri: String,
+}
 
 #[doc(hidden)]
 pub mod status_code {
@@ -105,17 +131,3 @@ pub mod scope {
         }
     }
 }
-
-impl TwitchTokenResponse {
-    /// Get the access token from this response
-    pub fn access_token(&self) -> &crate::AccessTokenRef { &self.access_token }
-
-    /// Get the expires in from this response
-    pub fn expires_in(&self) -> Option<Duration> { self.expires_in.map(Duration::from_secs) }
-
-    /// Get the refresh token from this response
-    pub fn refresh_token(&self) -> Option<&crate::RefreshTokenRef> { self.refresh_token.as_deref() }
-
-    /// Get the scopes from this response
-    pub fn scopes(&self) -> Option<&[crate::Scope]> { self.scopes.as_deref() }
-}

src/lib.rs

@@ -39,6 +39,7 @@
 //! to create user tokens in this library.
 //!
 //! Things like [`UserTokenBuilder`] can be used to create a token from scratch, via the [OAuth authorization code flow](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#authorization-code-grant-flow)
+//! You can also use the newer [OAuth device code flow](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#device-code-grant-flow) with [`DeviceUserTokenBuilder`].
 //!
 //! ## App access token
 //!
@@ -70,8 +71,8 @@ use tokens::errors::{RefreshTokenError, RevokeTokenError, ValidationError};
 pub use scopes::{Scope, Validator};
 #[doc(inline)]
 pub use tokens::{
-    AppAccessToken, ImplicitUserTokenBuilder, TwitchToken, UserToken, UserTokenBuilder,
-    ValidatedToken,
+    AppAccessToken, DeviceUserTokenBuilder, ImplicitUserTokenBuilder, TwitchToken, UserToken,
+    UserTokenBuilder, ValidatedToken,
 };
 
 pub use url;
@@ -125,6 +126,17 @@ pub static AUTH_URL: once_cell::sync::Lazy<url::Url> = mock_env_url!("TWITCH_OAU
 pub static TOKEN_URL: once_cell::sync::Lazy<url::Url> = mock_env_url!("TWITCH_OAUTH2_TOKEN_URL", {
     TWITCH_OAUTH2_URL.to_string() + "token"
 },);
+/// Device URL (`https://id.twitch.tv/oauth2/device`) for `id.twitch.tv`
+///
+/// Can be overridden when feature `mock_api` is enabled with environment variable `TWITCH_OAUTH2_URL` to set the root path, or with `TWITCH_OAUTH2_DEVICE_URL` to override the base (`https://id.twitch.tv/oauth2/`) url.
+///
+/// # Examples
+///
+/// Set the environment variable `TWITCH_OAUTH2_URL` to `http://localhost:8080/auth/` to use [`twitch-cli` mock](https://github.com/twitchdev/twitch-cli/blob/main/docs/mock-api.md) endpoints.
+pub static DEVICE_URL: once_cell::sync::Lazy<url::Url> =
+    mock_env_url!("TWITCH_OAUTH2_DEVICE_URL", {
+        TWITCH_OAUTH2_URL.to_string() + "device"
+    },);
 /// Validation URL (`https://id.twitch.tv/oauth2/validate`) for `id.twitch.tv`
 ///
 /// Can be overridden when feature `mock_api` is enabled with environment variable `TWITCH_OAUTH2_URL` to set the root path, or with `TWITCH_OAUTH2_VALIDATE_URL` to override the base (`https://id.twitch.tv/oauth2/`) url.
@@ -241,14 +253,16 @@ impl RefreshTokenRef {
     pub fn refresh_token_request(
         &self,
         client_id: &ClientId,
-        client_secret: &ClientSecret,
+        client_secret: Option<&ClientSecret>,
     ) -> http::Request<Vec<u8>> {
         use http::{HeaderMap, Method};
         use std::collections::HashMap;
 
         let mut params = HashMap::new();
         params.insert("client_id", client_id.as_str());
-        params.insert("client_secret", client_secret.secret());
+        if let Some(client_secret) = client_secret {
+            params.insert("client_secret", client_secret.secret());
+        }
         params.insert("grant_type", "refresh_token");
         params.insert("refresh_token", self.secret());
 
@@ -269,7 +283,7 @@ impl RefreshTokenRef {
         &self,
         http_client: &'a C,
         client_id: &ClientId,
-        client_secret: &ClientSecret,
+        client_secret: Option<&ClientSecret>,
     ) -> Result<
         (AccessToken, std::time::Duration, Option<RefreshToken>),
         RefreshTokenError<<C as Client>::Error>,

src/tokens.rs

@@ -6,7 +6,9 @@ mod user_token;
 
 pub use app_access_token::AppAccessToken;
 use twitch_types::{UserId, UserIdRef, UserName, UserNameRef};
-pub use user_token::{ImplicitUserTokenBuilder, UserToken, UserTokenBuilder};
+pub use user_token::{
+    DeviceUserTokenBuilder, ImplicitUserTokenBuilder, UserToken, UserTokenBuilder,
+};
 
 #[cfg(feature = "client")]
 use crate::client::Client;

src/tokens/app_access_token.rs

@@ -69,7 +69,7 @@ impl TwitchToken for AppAccessToken {
         let (access_token, expires_in, refresh_token) =
             if let Some(token) = self.refresh_token.take() {
                 token
-                    .refresh_token(http_client, &self.client_id, &self.client_secret)
+                    .refresh_token(http_client, &self.client_id, Some(&self.client_secret))
                     .await?
             } else {
                 return Err(RefreshTokenError::NoRefreshToken);

src/tokens/errors.rs

@@ -103,3 +103,36 @@ pub enum ImplicitUserTokenExchangeError<RE: std::error::Error + Send + Sync + 's
     /// could not get validation for token
     ValidationError(#[from] ValidationError<RE>),
 }
+/// Errors for [`DeviceUserTokenBuilder`][crate::tokens::DeviceUserTokenBuilder]
+#[derive(thiserror::Error, Debug, displaydoc::Display)]
+#[non_exhaustive]
+#[cfg(feature = "client")]
+pub enum DeviceUserTokenExchangeError<RE: std::error::Error + Send + Sync + 'static> {
+    /// request for exchange token failed
+    DeviceExchangeRequestError(#[source] RE),
+    /// could not parse response when getting exchange token
+    DeviceExchangeParseError(#[source] crate::RequestParseError),
+    /// request for user token failed
+    TokenRequestError(#[source] RE),
+    /// could not parse response when getting user token
+    TokenParseError(#[source] crate::RequestParseError),
+    /// could not get validation for token
+    ValidationError(#[from] ValidationError<RE>),
+    /// no device code found, exchange not started
+    NoDeviceCode,
+    /// the device code has expired
+    Expired,
+}
+
+#[cfg(feature = "client")]
+impl<RE: std::error::Error + Send + Sync + 'static> DeviceUserTokenExchangeError<RE> {
+    /// Check if the error is due to the authorization request being pending
+    pub fn is_pending(&self) -> bool {
+        matches!(self, DeviceUserTokenExchangeError::TokenParseError(
+                crate::RequestParseError::TwitchError(crate::id::TwitchTokenErrorResponse {
+                    message,
+                    ..
+                }),
+            ) if message == "authorization_pending")
+    }
+}