huskarl-resource-server 0.9.1

OAuth2 resource server (JWT validation) support for the huskarl ecosystem.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

#![forbid(unsafe_code)]
#![deny(missing_docs)]
#![deny(rustdoc::broken_intra_doc_links)]
#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]
#![deny(clippy::panic)]
#![warn(clippy::pedantic)]
#![cfg_attr(docsrs, feature(doc_cfg))]
//! # `OAuth2` library for resource servers.
//!
//! A resource server has two jobs: validate the access token presented with a
//! request, and decide whether that token authorizes the request.
//!
//! This crate does the first. A [`validator`] verifies the token
//! (signature/introspection, expiry, audience, and any sender-constraint
//! binding) and returns a [`ValidatedRequest`]
//! carrying its claims — from which your application makes the second decision.
//! When validation fails, [`rejection`] turns the failure into the matching
//! response: status code, `WWW-Authenticate` challenges, and `DPoP-Nonce`.
//!
//! ## 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`](https://docs.rs/huskarl) — `OAuth2` **clients**: grants, token
//!   caching, and the request authorizer.
//! - **`huskarl-resource-server`** (this crate) — **resource servers**:
//!   access-token validation and request authorization.
//! - [`huskarl-core`](https://docs.rs/huskarl-core) — the shared **foundation**
//!   the other two build on.
//!
//! ## Example with RFC 9068 token validation:
//!
//! ```
//! use std::sync::Arc;
//!
//! use huskarl_resource_server::{
//!     core::{http::HttpClient, jwk::JwksSource},
//!     validator::rfc9068::Rfc9068Validator,
//! };
//!
//! # async fn setup_resource_server(
//! #     http_client: impl HttpClient + Clone + 'static,
//! # ) -> Result<(), huskarl_resource_server::core::Error> {
//! let validator = Rfc9068Validator::builder()
//!     .issuer("https://issuer")
//!     .audience("audience")
//!     .jws_verifier_factory(Arc::new(
//!         JwksSource::builder().http_client(http_client).build(),
//!     ))
//!     .build()
//!     .await?;
//! # let _ = validator;
//! # Ok(())
//! # }
//! ```
//!
//! ## Guides and explanation
//!
//! The API items here are the reference docs. For task-oriented how-to guides
//! (validating RFC 9068, custom, introspection, and multi-issuer tokens, plus
//! `DPoP` enforcement) and design explanation (choosing a validator, how
//! multi-issuer routing stays safe), see the [`_docs`] module.

#[cfg(any(doc, docsrs))]
pub mod _docs;

pub mod error;
pub mod introspection;
pub mod prelude;
pub mod rejection;
pub mod validator;

use std::sync::Arc;

#[doc(inline)]
pub use huskarl_core as core;
use validator::{AccessTokenValidator, ValidatedRequest, extract::TokenType};

/// The platform default [`core::crypto::verifier::JwsVerifierPlatform`] implementation.
///
/// On native platforms this wraps `huskarl-crypto-native`; on WebAssembly it wraps
/// `huskarl-crypto-webcrypto`. Enabled by the `default-jws-verifier-platform` feature.
#[derive(Debug, Clone)]
pub struct DefaultJwsVerifierPlatform(Arc<dyn core::crypto::verifier::JwsVerifierPlatform>);

impl From<DefaultJwsVerifierPlatform> for Arc<dyn core::crypto::verifier::JwsVerifierPlatform> {
    fn from(value: DefaultJwsVerifierPlatform) -> Self {
        value.0
    }
}

/// The platform default JWS verifier factory for native platforms.
#[cfg(all(
    feature = "default-jws-verifier-platform",
    not(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "none")))
))]
impl Default for DefaultJwsVerifierPlatform {
    fn default() -> Self {
        Self(Arc::new(huskarl_crypto_native::NativeVerifierPlatform))
    }
}

/// The platform default JWS verifier factory for WebAssembly/WebCrypto platforms.
#[cfg(all(
    feature = "default-jws-verifier-platform",
    all(target_arch = "wasm32", any(target_os = "unknown", target_os = "none"))
))]
impl Default for DefaultJwsVerifierPlatform {
    fn default() -> Self {
        Self(Arc::new(
            huskarl_crypto_webcrypto::WebCryptoVerifierPlatform::default(),
        ))
    }
}