oauthkit
A provider-registry-driven OAuth SDK for command-line tools. It gives any CLI the breadth of model-provider sign-in without hard-coding a single provider.
What it does
- Three flows, one token path. Authorization-code with PKCE (loopback redirect), device-code (RFC 8628), and API-key. Success and error parsing live in one shared token path.
- Data-driven provider registry. Providers are declared as data in
rules/providers.toml. Extend the set by merging your own TOML, not by editing the crate. - UI-agnostic. The SDK returns authorize URLs, device user codes, and
Credentials. Your CLI owns all rendering. - Pluggable storage. Persistence is a
CredentialStoreyou supply; aMemoryStoreships for tests. - No silent fallback. Every flow fails loud: a state mismatch, an OAuth
error, or a timeout returns an
Error, never a degraded success. Tokens are redacted inDebugoutput.
The built-in registry currently ships API-key and device-code providers. OAuth
providers must be added by merging your own TOML (see Extending the registry
below). The SDK still implements the authorization-code flow for any provider
that you configure.
Usage
use ;
use Duration;
# async
Extending the registry
Add providers or override built-ins as data:
use Registry;
# let my_toml = r#"
# [[provider]]
# id = "acme"
# display_name = "Acme"
# [[provider.methods]]
# flow = "api_key"
# "#;
let mut registry = builtin?;
registry.merge; // later id wins
# Ok::
Adding an OAuth provider
The built-ins are API-key and device-code because those work with a public,
non-secret identifier. Authorization-code OAuth needs a client_id you
register with the provider, so you supply it as data. Declare an oauth method in
your own TOML and merge it:
[[]]
= "acme"
= "Acme"
[[]]
= "oauth"
= "https://auth.acme.example/authorize"
= "https://auth.acme.example/oauth/token"
= "your-registered-client-id"
= ["openid", "profile", "offline_access"]
# Typed, well-known authorize parameters (merged into the authorize URL):
= "https://api.acme.example"
= "consent"
# Anything else the provider needs that has no typed field:
= [["custom_toggle", "1"]]
To build a config in code, use OAuthConfig::new (the type is #[non_exhaustive],
so set the optional fields on the returned value rather than a struct literal):
use OAuthConfig;
let mut oauth = new;
oauth.scopes = vec!;
oauth.audience = Some;
If the provider publishes an OpenID Connect discovery document, let oauthkit read the endpoints instead of hand-copying them:
use discover;
# async
Store credentials encrypted at rest with the optional encrypted-store feature
(pure-Rust ChaCha20-Poly1305 under a 32-byte key you supply):
= { = "0.2", = ["encrypted-store"] }
License
Apache-2.0.