Struct AuthClient 

pub struct AuthClient { /* private fields */ }

High-level auth client. Holds a shared reqwest::Client and the resolved client_id; provides device-code sign-in and access-token retrieval (with transparent refresh).

Implementations

impl AuthClient

pub fn from_env() -> Result<Self, ClientError>

Construct an AuthClient from compile-time/env configuration.

Errors with ClientError::NotProvisioned if no client_id is available.

pub fn from_env_with_backend( backend: Arc<dyn TokenBackend>, ) -> Result<Self, ClientError>

Like Self::from_env, but tokens are loaded from and saved to backend instead of the CLI’s config-resolved keychain/file store. This is the constructor for hosted consumers such as the MCP server.

pub fn with_backend(self, backend: Arc<dyn TokenBackend>) -> Self

Replace the token backend (builder style). Handy for tests that pair Self::for_test with an in-memory store.

pub fn scope(&self) -> &str

The space-separated Microsoft Graph scope string this client requests.

pub fn client_id(&self) -> &str

The Entra client_id this client authenticates as.

pub async fn store_tokens( &self, email: &str, tokens: &TokenSet, ) -> Result<(), ClientError>

Persist a freshly obtained TokenSet for email through the configured backend. Hosted sign-in flows call this after Self::exchange_code.

pub fn authorize_url( &self, redirect_uri: &str, code_challenge: &str, state: &str, ) -> String

Build the Microsoft /authorize URL for an auth-code + PKCE sign-in whose callback lands on redirect_uri (which must be registered on the Entra app). The caller owns state and the PKCE verifier behind code_challenge; pair with Self::exchange_code.

pub fn authorize_url_with_hint( &self, redirect_uri: &str, code_challenge: &str, state: &str, login_hint: Option<&str>, ) -> String

Self::authorize_url with a login_hint: the address Microsoft preselects in its account picker. The picker is still shown (prompt=select_account), so the user can pick another account; the hint only makes the expected one the obvious choice.

pub async fn exchange_code( &self, code: &str, code_verifier: &str, redirect_uri: &str, ) -> Result<AuthSuccess, ClientError>

Redeem an authorization code delivered to redirect_uri for tokens. Nothing is stored; call Self::store_tokens once the caller has decided which account the tokens belong to.

pub fn for_test( client_id: impl Into<String>, authority_base: impl Into<String>, ) -> Self

Construct an AuthClient against a specific authority, for tests with wiremock.

pub async fn run_browser_flow<F>( &self, on_authorize_url_ready: F, ) -> Result<AuthSuccess, ClientError>

where F: FnOnce(&str),

Run the OAuth 2.0 authorization-code + PKCE sign-in flow with a one-shot localhost HTTP server for the redirect callback.

on_authorize_url_ready receives the constructed /authorize URL once the local listener is bound and the URL is built. The caller is responsible for printing it to the user and (best-effort) opening the browser.

Works for both work/school (M365) and personal (live.com / outlook.com / hotmail.com) Microsoft accounts. Device-code is kept in tree for potential future headless use but no longer the default sign-in path.

pub async fn get_valid_token(&self, email: &str) -> Result<String, ClientError>

Get a valid (un-expired) access token for an email, refreshing if necessary. Returns ClientError::SessionExpired if the refresh fails; the caller should prompt the user to pidge auth login again for that account.

Tokens come from the configured TokenBackend. The default, LocalBackend, resolves the storage backend from the account’s config entry and falls back to the OS keychain if the email has no entry in config.yaml yet (e.g. mid-login).