Skip to main content

Crate loopauth

Crate loopauth 

Source
Expand description

loopauth acquires OAuth 2.0 provider tokens for CLI applications via the Authorization Code + PKCE flow (RFC 6749, RFC 7636). It is provider token acquisition only, rather than app authentication or session management.

Given a client_id, auth_url, and token_url, CliTokenClient opens the user’s browser to the authorization URL, spins up a short-lived loopback HTTP server to receive the redirect callback, exchanges the authorization code for tokens, and returns a TokenSet to the caller.

Token storage and downstream identity consumption are intentionally out of scope; use the TokenStore trait to provide your own persistence.

§Two-Layer Pattern

loopauth returns provider tokens only. Your backend handles app identity:

  1. Call CliTokenClient::run_authorization_flow → provider returns a TokenSet
  2. Send TokenSet::id_token_raw to your backend → validate and issue your own session token

§Quick start

With explicit URLs:

use loopauth::{CliTokenClient, RequestScope};

let client = CliTokenClient::builder()
    .client_id("my-client-id")
    .auth_url(url::Url::parse("https://provider.example.com/authorize")?)
    .token_url(url::Url::parse("https://provider.example.com/token")?)
    .with_openid_scope()
    .add_scopes([RequestScope::Email])
    .without_jwks_validation() // or .jwks_validator(Box::new(my_validator))
    .build();

// let tokens = client.run_authorization_flow().await?;

With OIDC auto-discovery (provider URLs are fetched automatically):

use loopauth::{CliTokenClientBuilder, RequestScope, oidc::OpenIdConfiguration};
use url::Url;

let open_id_configuration = OpenIdConfiguration::fetch(
    Url::parse("https://provider.example.com")?,
).await?;

let client = CliTokenClientBuilder::from_open_id_configuration(&open_id_configuration)
    .client_id("my-client-id")
    .with_open_id_configuration_jwks_validator(&open_id_configuration)
    .add_scopes([RequestScope::Email])
    .build();

// let tokens = client.run_authorization_flow().await?;

Modules§

oidc
OpenID Connect support: discovery document fetching and ID token claims.

Structs§

AccessToken
An OAuth 2.0 access token.
CliTokenClient
Acquires OAuth 2.0 provider tokens for CLI applications via the Authorization Code + PKCE flow.
CliTokenClientBuilder
Builder for CliTokenClient.
ErrorPageContext
Context provided to ErrorPageRenderer implementations.
HasAuthUrl
Type-state: auth_url has been provided.
HasClientId
Type-state: client_id has been provided.
HasTokenUrl
Type-state: token_url has been provided.
JwksDisabled
Type-state: OIDC mode engaged with JWKS signature verification explicitly disabled.
JwksEnabled
Type-state: OIDC mode engaged with JWKS signature verification enabled.
JwksValidationError
An error returned by a JwksValidator when the id_token fails validation.
NoAuthUrl
Type-state: auth_url not yet provided.
NoClientId
Type-state: client_id not yet provided.
NoOidc
Type-state: OIDC mode not yet engaged; openid scope is not included.
NoTokenUrl
Type-state: token_url not yet provided.
OidcPending
Type-state: OIDC mode engaged but JWKS decision not yet made.
PageContext
Context provided to SuccessPageRenderer implementations.
RefreshToken
An OAuth 2.0 refresh token.
RemoteJwksValidator
Validates JWTs against a remote JWKS endpoint.
TokenSet
The set of tokens returned by a successful OAuth 2.0 authorization or refresh flow.
Unvalidated
Marker type: the id_token signature has not yet been verified.
Validated
Marker type: the id_token signature has been verified, or no id_token was present.

Enums§

AuthError
Errors that can occur during crate::CliTokenClient::run_authorization_flow.
CallbackError
Errors that can occur during OAuth 2.0 callback validation.
IdTokenError
Errors that can occur while validating an id_token after a successful token exchange.
OAuth2Scope
An OAuth 2.0 scope value.
RefreshError
Errors that can occur during crate::CliTokenClient::refresh or crate::CliTokenClient::refresh_if_expiring.
RefreshOutcome
Outcome of crate::CliTokenClient::refresh_if_expiring.
RequestScope
An OAuth 2.0 scope value for use with crate::CliTokenClientBuilder::add_scopes.
TokenStoreError
Errors that can occur in crate::TokenStore implementations.

Traits§

ErrorPageRenderer
Renders the error page HTML shown to the user when authentication fails.
JwksValidator
Validates the raw id_token string returned from the token endpoint.
SuccessPageRenderer
Renders the success page HTML shown to the user after authentication.
TokenStore
Persistent storage interface for TokenSet values.
ValidationState
Marker trait for crate::TokenSet validation state. Sealed — only Validated and Unvalidated implement it.