oauthkit 0.2.4

Provider-registry-driven OAuth SDK for CLIs: authorization-code+PKCE, device-code, and API-key sign-in across many model providers, with pluggable credential storage.
Documentation
# oauthkit — specification

`oauthkit` is a provider-registry-driven OAuth SDK for command-line tools. It
turns a declarative description of a provider's sign-in methods into working
authorization-code (with PKCE), device-code, and API-key flows, and stores the
resulting credentials behind a pluggable trait.

## Scope

- **In scope:** describing providers and their sign-in methods; executing the
  three sign-in flows; parsing and validating token/error responses; holding
  credentials behind a `CredentialStore`; redacting secrets in `Debug`.
- **Out of scope:** deciding *which* provider a user should use, refreshing on a
  schedule, and any UI. The crate is display/selection-agnostic. Persistence is a
  caller-supplied `CredentialStore`; the opt-in `encrypted-store` feature adds an
  `EncryptedStore` that seals credentials with ChaCha20-Poly1305 under a
  caller-supplied key (its `seal`/`open` bytes can be written to disk or a keyring).

## Data model

- `Registry` — a validated set of `Provider`s, loaded from TOML (`rules/`) or
  constructed programmatically. `Registry::validate` rejects malformed
  `authorize_url` / `token_url` / `device_authorization_url` / `redirect_uri`,
  a `loopback_port` that conflicts with an explicit `redirect_uri` port, and
  more than one `AuthMethod` of the same kind per provider.
- `Provider` — an id plus one or more `AuthMethod`s (`OAuthConfig`,
  `DeviceCodeConfig`, `ApiKeyConfig`). `oauth()`, `device()`, and `api_key()`
  return the first method of that kind; validation guarantees uniqueness, so
  first-match is deterministic.
- `OAuthConfig` — the authorization-code + PKCE parameters (`authorize_url`,
  `token_url`, `client_id`, `scopes`) plus typed optional authorize params
  (`audience`, `prompt`, `login_hint`), `redirect_uri` / `loopback_port`, and
  `extra_authorize_params` for provider-specific keys (a custom key that collides
  with one oauthkit already emits, including a typed field, is dropped). The type
  is `#[non_exhaustive]` and derives `Default`; construct it with
  `OAuthConfig::new(authorize_url, token_url, client_id)` and set the optional
  fields on the returned value so new knobs can be added as compatible releases.
- `Credential` — an enum with `OAuth { access_token, refresh_token?,
  token_type, .. }` and `ApiKey { key }` variants. The type enforces a valid
  shape; `secret()` returns the sensitive material and `Debug` is redacted.

## Flows

- **Authorization code + PKCE** (`AuthClient::begin_oauth` → `BeganAuthorization`):
  generates a PKCE verifier/challenge and `state`, opens a loopback redirect
  server bound to `loopback_port` (or an ephemeral port when `0`), rewrites port
  `0` in the authorize URL to the actually bound port, and matches the callback
  on the path taken from the configured `redirect_uri`. `state` mismatch is a
  hard error.
- **Device code** (`begin_device` → `complete_device`): requests a device code,
  then polls the token endpoint honoring `slow_down` (increase interval) and
  terminating on `access_denied` / `expired_token`. `complete_device` bounds the
  wait by `DEFAULT_SIGN_IN_TIMEOUT` (or a caller value).
- **API key** (`accept_api_key`, `api_key_from_env`): validates and wraps a
  caller-supplied key; no network call.
- **OIDC discovery** (`discover` → `OidcMetadata::to_oauth_config`): fetches
  `<issuer>/.well-known/openid-configuration`, validates it (non-2xx, malformed,
  or an issuer mismatch all fail loud), and turns the discovered endpoints plus a
  caller-supplied client id and scopes into an `OAuthConfig`.

## Guarantees

- **Fail closed / fail loud:** token and error responses parse into structured
  types; non-2xx bodies are parsed for `error` / `error_description`. Missing or
  malformed data is an `Error`, never a silently-empty `Credential`.
- **Secret hygiene:** no secret appears in `Debug`, `Display`, or (per row 15)
  tracing output. `secret()` is the single accessor.
- **Timeouts:** the HTTP client sets connect/read timeouts so a hung provider
  endpoint cannot block a flow indefinitely.
- **Deterministic dependencies:** every dependency is a concrete version; the
  crate compiles standalone (edition 2024, consumer MSRV Rust 1.86 set by the
  `icu`/`idna` dependency floor) with no workspace inheritance. The full test
  suite additionally needs Rust 1.88 (the `wiremock` dev-dependency uses
  let-chains); the pinned `rust-toolchain.toml` reflects that development floor.

## Public API

`Registry`, `Provider`, `AuthMethod`, `OAuthConfig`, `DeviceCodeConfig`,
`ApiKeyConfig`; `AuthClient<S: CredentialStore>` with `builtin` / `new`,
`begin_oauth`, `begin_device`, `complete_device`, `accept_api_key`,
`api_key_from_env`, `refresh_stored`, `logout`; `Credential`, `CredentialKind`,
`CredentialStore`, `MemoryStore`; `PkceCodes`, `generate_pkce`, `generate_state`, `constant_time_eq`;
`discover`, `OidcMetadata`; `Error`, `Result`; `DEFAULT_SIGN_IN_TIMEOUT`. Behind
the `encrypted-store` feature: `EncryptedStore`.

## Stability

Pre-1.0: the API may change between minor versions. Changes are recorded in
`CHANGELOG.md`. Credential serialization is tagged so stored credentials remain
readable across compatible versions.