Crate loopauth 

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 server to receive the redirect callback, exchanges the authorization code for tokens, and returns a TokenSet to the caller.

The callback server runs over plain HTTP by default. For providers that require HTTPS redirect URIs (e.g. Slack), call .use_https_with() with a TlsCertificate to serve over TLS instead. See the HTTPS callbacks section below.

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?;

HTTPS callbacks

Some providers require https:// redirect URIs, even for localhost. TlsCertificate::ensure_localhost handles certificate generation via mkcert automatically:

use loopauth::{CliTokenClient, TlsCertificate};
use std::path::PathBuf;

// First run: generates certs via mkcert. Later runs: loads existing.
let tls_dir = PathBuf::from("/home/user/.config/my-cli/tls");
let cert = TlsCertificate::ensure_localhost(&tls_dir)?;

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")?)
    .use_https_with(cert)
    .build();

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

End users need mkcert installed and its CA trusted (mkcert -install, one-time). See TlsCertificate::SETUP_GUIDE_MANAGED for end-user instructions tailored to this workflow, or TlsCertificate::SETUP_GUIDE for the full manual guide.

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.

ExtraAuthParams

Accumulates extra query parameters to append to the authorization URL.

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.

TlsCertificate

A validated TLS certificate and private key pair for HTTPS serving.

TokenResponseFields

The standard fields extracted from a token endpoint response.

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.

TlsCertificateError

Errors that can occur when constructing a TlsCertificate.

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.