huskarl-core 0.8.1

Base library for huskarl (OAuth2 client) ecosystem.
Documentation

The foundational traits and types for the huskarl OAuth2 ecosystem.

Most applications depend on the higher-level huskarl crate (grants, token cache, authorizer) rather than this crate directly. huskarl-core is the shared base they build on — the utilities below are also useful on their own, whether you are writing OAuth tooling or implementing a backend for the rest of the ecosystem.

The huskarl ecosystem

This crate is one of three that fit together. Each carries its own how-to guides and explanation in a _docs module:

  • huskarl — OAuth2 clients: grants, token caching, and the request authorizer.
  • huskarl-resource-server — resource servers: access-token validation and request authorization.
  • huskarl-core (this crate) — the shared foundation the other two build on.

What’s here

  • JOSE primitives — jwt builds, signs, and validates JWTs; jwk parses and produces JWK/JWKS wire types; crypto holds the signing, verification, and encryption traits plus a set of composable wrappers (multi-key, refreshable, retrying).
  • Secret handling — secrets retrieves credentials from environment variables, files, or your own provider, behind redacted wrappers that keep them out of logs, with optional decoding and caching.
  • Client authentication — client_auth carries the ways a client authenticates to an authorization server (client secret, private-key JWT, or none).
  • DPoP — dpop provides proof-of-possession binding for the authorization-server and resource-server flows.
  • HTTP — http defines the HttpClient seam that decouples the ecosystem from any specific HTTP implementation.
  • Authorization-server metadata — server_metadata models RFC 8414 / OIDC discovery documents.
  • Wire encoding — oauth_form serializes OAuth messages as application/x-www-form-urlencoded, including structured RFC 9396 values.
  • Errors — the flows return the one concrete Error/ErrorKind, which embeds cleanly in your own error type. A few subsystems return their own typed errors where the variants are the API — JWT validation (JwtValidationError), low-level verification (crypto::verifier), and wire encoding (oauth_form::Error) — design one From arm for Error plus arms for the subsystem errors you call directly.

Guides and explanation

The API items here are the reference documentation. For task-oriented how-to guides — building and validating JWTs, providing secrets, and implementing a backend — and design explanation — the error model, handling untrusted keys, and composing crypto strategies — see the _docs module.