feature: AIP client credentials token helper

crates/atproto-oauth-aip/src/errors.rs

···
 //!
 //! ## Error Categories
 //!
-//! - **`OAuthWorkflowError`** (workflow-1 to workflow-8): OAuth workflow operations including PAR, token exchange, and session management
+//! - **`OAuthWorkflowError`** (workflow-1 to workflow-9): OAuth workflow operations including PAR, token exchange, and session management
 //!
 //! ## Error Format
 //!
···
     #[error("error-atproto-oauth-aip-workflow-5 Token response json parsing failed: {0}")]
     TokenResponseParseFailed(#[source] reqwest::Error),
 
+    /// Token response contained an error.
+    #[error("error-atproto-oauth-aip-workflow-6 Token response invalid: {message}")]
+    TokenResponseInvalid {
+        /// Error message from the token response.
+        message: String,
+    },
+
     /// Failed to send session exchange HTTP request.
-    #[error("error-atproto-oauth-aip-workflow-6 Session request failed: {0}")]
+    #[error("error-atproto-oauth-aip-workflow-7 Session request failed: {0}")]
     SessionRequestFailed(#[source] reqwest::Error),
 
     /// Failed to parse session response JSON.
-    #[error("error-atproto-oauth-aip-workflow-7 Session json parsing failed: {0}")]
+    #[error("error-atproto-oauth-aip-workflow-8 Session json parsing failed: {0}")]
     SessionResponseParseFailed(#[source] reqwest::Error),
 
     /// Session response contained an error.
-    #[error("error-atproto-oauth-aip-workflow-8 Session response invalid: {message}")]
+    #[error("error-atproto-oauth-aip-workflow-9 Session response invalid: {message}")]
     SessionResponseInvalid {
         /// Error message from the session response.
         message: String,

crates/atproto-oauth-aip/src/workflow.rs

···
         }
     }
 }
+
+/// Obtains an access token using OAuth client credentials grant.
+///
+/// This function implements the OAuth 2.0 client credentials flow for obtaining
+/// service-to-service access tokens. This is typically used when a service needs
+/// to authenticate itself rather than acting on behalf of a user.
+///
+/// # Arguments
+///
+/// * `http_client` - The HTTP client to use for making requests
+/// * `aip_hostname` - The hostname of the AT Protocol Identity Provider (AIP)
+/// * `aip_client_id` - The client ID for authenticating with the AIP
+/// * `aip_client_secret` - The client secret for authenticating with the AIP
+///
+/// # Returns
+///
+/// Returns a `TokenResponse` containing the access token and metadata,
+/// or an error if the token request fails.
+///
+/// # Example
+///
+/// ```no_run
+/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+/// use atproto_oauth_aip::workflow::client_credentials_token;
+/// use atproto_oauth::workflow::TokenResponse;
+/// # let http_client = reqwest::Client::new();
+/// # let aip_hostname = "auth.example.com";
+/// # let client_id = "service-client-id";
+/// # let client_secret = "service-client-secret";
+///
+/// let token = client_credentials_token(
+///     &http_client,
+///     aip_hostname,
+///     client_id,
+///     client_secret,
+/// ).await?;
+///
+/// println!("Access token: {}", token.access_token);
+/// println!("Token type: {}", token.token_type);
+/// println!("Expires in: {} seconds", token.expires_in);
+/// # Ok(())
+/// # }
+/// ```
+pub async fn client_credentials_token(
+    http_client: &reqwest::Client,
+    aip_hostname: &str,
+    aip_client_id: &str,
+    aip_client_secret: &str,
+) -> Result<atproto_oauth::workflow::TokenResponse> {
+    // Construct the token endpoint URL
+    let token_url = format!("https://{}/oauth/token", aip_hostname);
+
+    // Prepare the form data for client credentials grant
+    let params = [("grant_type", "client_credentials")];
+
+    // Send the request with Basic authentication
+    let response = http_client
+        .post(&token_url)
+        .basic_auth(aip_client_id, Some(aip_client_secret))
+        .form(&params)
+        .send()
+        .await
+        .map_err(OAuthWorkflowError::TokenRequestFailed)?;
+
+    // Check if the request was successful
+    if !response.status().is_success() {
+        let status = response.status();
+        let error_text = response
+            .text()
+            .await
+            .unwrap_or_else(|_| "Unknown error".to_string());
+        return Err(OAuthWorkflowError::TokenResponseInvalid {
+            message: format!("Token request failed with status {}: {}", status, error_text),
+        }
+        .into());
+    }
+
+    // Parse the response
+    response
+        .json::<atproto_oauth::workflow::TokenResponse>()
+        .await
+        .map_err(|e| OAuthWorkflowError::TokenResponseParseFailed(e).into())
+}