feat: expose detection error types

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ambient-id"
-version = "0.0.4"
+version = "0.0.5"
 authors = ["William Woodruff <william@astral.sh>"]
 edition = "2024"
 description = "Detects ambient OIDC credentials in a variety of environments"

src/github.rs

@@ -1,27 +1,21 @@
+//! GitHub Actions OIDC token detection.
+
 use reqwest_middleware::ClientWithMiddleware;
 
 use crate::{DetectionState, DetectionStrategy};
 
+/// Possible errors during GitHub Actions OIDC token detection.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
     /// The GitHub Actions environment lacks necessary permissions.
+    ///
+    /// This is typically resolved by adding `id-token: write` to the
+    /// job's `permissions` block.
+    #[error("insufficient permissions: {0}")]
     InsufficientPermissions(&'static str),
-    /// The HTTP request to fetch the ID token failed (in middleware).
-    Middleware(#[from] reqwest_middleware::Error),
-    /// The HTTP request to fetch the ID token failed (in reqwest).
-    Request(#[from] reqwest::Error),
-}
-
-impl std::fmt::Display for Error {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            Error::InsufficientPermissions(what) => {
-                write!(f, "insufficient permissions: {what}")
-            }
-            Error::Middleware(err) => write!(f, "HTTP request failed: {err}"),
-            Error::Request(err) => write!(f, "HTTP request failed: {err}"),
-        }
-    }
+    /// The HTTP request to fetch the ID token failed.
+    #[error("HTTP request failed: {0}")]
+    Request(#[from] reqwest_middleware::Error),
 }
 
 /// The JSON payload returned by GitHub's ID token endpoint.
@@ -68,9 +62,11 @@ impl DetectionStrategy for GitHubActions {
             .query(&[("audience", audience)])
             .send()
             .await?
-            .error_for_status()?
+            .error_for_status()
+            .map_err(reqwest_middleware::Error::Reqwest)?
             .json::<TokenRequestResponse>()
-            .await?;
+            .await
+            .map_err(reqwest_middleware::Error::Reqwest)?;
 
         Ok(crate::IdToken(resp.value.into()))
     }

src/gitlab.rs

@@ -1,18 +1,15 @@
+//! GitLab CI OIDC token detection.
+
 use crate::{DetectionState, DetectionStrategy};
 
+/// Possible errors during GitLab CI OIDC token detection.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// The expected environment variable for the ID token was not found.
+    #[error("ID token variable not found: {0}")]
     Missing(String),
 }
 
-impl std::fmt::Display for Error {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            Error::Missing(what) => write!(f, "ID token variable not found: {what}"),
-        }
-    }
-}
-
 pub(crate) struct GitLabCI;
 
 impl GitLabCI {

src/lib.rs

@@ -26,6 +26,9 @@ use secrecy::{ExposeSecret, SecretString};
 mod github;
 mod gitlab;
 
+pub use github::Error as GitHubError;
+pub use gitlab::Error as GitLabError;
+
 /// A detected ID token.
 ///
 /// This is a newtype around a [`SecretString`] that ensures zero-on-drop
@@ -49,10 +52,10 @@ impl IdToken {
 pub enum Error {
     /// An error occurred while detecting GitHub Actions credentials.
     #[error("GitHub Actions detection error")]
-    GitHubActions(#[from] github::Error),
+    GitHubActions(#[from] GitHubError),
     /// An error occurred while detecting GitLab CI credentials.
     #[error("GitLab CI detection error")]
-    GitLabCI(#[from] gitlab::Error),
+    GitLabCI(#[from] GitLabError),
 }
 
 #[derive(Default)]