From dd7449b92ead9a0da8bb9ffc6f0123bdbd8d1415 Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Tue, 1 Feb 2022 10:48:38 +0100 Subject: [PATCH] Deny missing docs in the config crates --- crates/config/src/lib.rs | 1 + crates/config/src/schema.rs | 4 +++ crates/config/src/sections/clients.rs | 37 ++++++++++++++++++++++++--- crates/config/src/sections/secrets.rs | 7 +++++ 4 files changed, 45 insertions(+), 4 deletions(-) diff --git a/crates/config/src/lib.rs b/crates/config/src/lib.rs index 1bbea804..50e7fe0f 100644 --- a/crates/config/src/lib.rs +++ b/crates/config/src/lib.rs @@ -14,6 +14,7 @@ #![forbid(unsafe_code)] #![deny(clippy::all)] +#![deny(missing_docs)] #![deny(rustdoc::broken_intra_doc_links)] #![warn(clippy::pedantic)] #![allow(clippy::module_name_repetitions)] diff --git a/crates/config/src/schema.rs b/crates/config/src/schema.rs index 554aeb6c..8e0c43b0 100644 --- a/crates/config/src/schema.rs +++ b/crates/config/src/schema.rs @@ -12,11 +12,14 @@ // See the License for the specific language governing permissions and // limitations under the License. +//! Useful JSON Schema definitions + use schemars::{ gen::SchemaGenerator, schema::{InstanceType, NumberValidation, Schema, SchemaObject}, }; +/// A network port pub fn port(_gen: &mut SchemaGenerator) -> Schema { Schema::Object(SchemaObject { instance_type: Some(InstanceType::Integer.into()), @@ -29,6 +32,7 @@ pub fn port(_gen: &mut SchemaGenerator) -> Schema { }) } +/// A network hostname pub fn hostname(_gen: &mut SchemaGenerator) -> Schema { Schema::Object(SchemaObject { instance_type: Some(InstanceType::String.into()), diff --git a/crates/config/src/sections/clients.rs b/crates/config/src/sections/clients.rs index 359eeafc..2ac393dd 100644 --- a/crates/config/src/sections/clients.rs +++ b/crates/config/src/sections/clients.rs @@ -48,24 +48,51 @@ impl From for JwksOrJwksUri { } } +/// Authentication method used by clients #[derive(JsonSchema, Serialize, Deserialize, Clone, Debug)] #[serde(tag = "client_auth_method", rename_all = "snake_case")] pub enum ClientAuthMethodConfig { + /// `none`: No authentication None, - ClientSecretBasic { client_secret: String }, - ClientSecretPost { client_secret: String }, - ClientSecretJwt { client_secret: String }, + + /// `client_secret_basic`: `client_id` and `client_secret` used as basic + /// authorization credentials + ClientSecretBasic { + /// The client secret + client_secret: String, + }, + + /// `client_secret_post`: `client_id` and `client_secret` sent in the + /// request body + ClientSecretPost { + /// The client secret + client_secret: String, + }, + + /// `client_secret_basic`: a `client_assertion` sent in the request body and + /// signed using the `client_secret` + ClientSecretJwt { + /// The client secret + client_secret: String, + }, + + /// `client_secret_basic`: a `client_assertion` sent in the request body and + /// signed by an asymetric key PrivateKeyJwt(JwksOrJwksUri), } +/// An OAuth 2.0 client configuration #[skip_serializing_none] #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] pub struct ClientConfig { + /// The client ID pub client_id: String, + /// Authentication method used for this client #[serde(flatten)] pub client_auth_method: ClientAuthMethodConfig, + /// List of allowed redirect URIs #[serde(default)] pub redirect_uris: Vec, } @@ -75,6 +102,7 @@ pub struct ClientConfig { pub struct InvalidRedirectUriError; impl ClientConfig { + #[doc(hidden)] pub fn resolve_redirect_uri<'a>( &'a self, suggested_uri: &'a Option, @@ -85,7 +113,7 @@ impl ClientConfig { ) } - pub fn check_redirect_uri<'a>( + fn check_redirect_uri<'a>( &self, redirect_uri: &'a Url, ) -> Result<&'a Url, InvalidRedirectUriError> { @@ -97,6 +125,7 @@ impl ClientConfig { } } +/// List of OAuth 2.0/OIDC clients config #[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)] #[serde(transparent)] pub struct ClientsConfig(Vec); diff --git a/crates/config/src/sections/secrets.rs b/crates/config/src/sections/secrets.rs index b482e5ff..4132864e 100644 --- a/crates/config/src/sections/secrets.rs +++ b/crates/config/src/sections/secrets.rs @@ -34,12 +34,14 @@ use tracing::info; use super::ConfigurationSection; +/// Helps encrypting and decrypting data #[derive(Clone)] pub struct Encrypter { aead: Arc, } impl Encrypter { + /// Creates an [`Encrypter`] out of an encryption key #[must_use] pub fn new(key: &[u8; 32]) -> Self { let key = GenericArray::from_slice(key); @@ -48,12 +50,14 @@ impl Encrypter { Self { aead } } + /// Encrypt a payload pub fn encrypt(&self, nonce: &[u8; 12], decrypted: &[u8]) -> anyhow::Result> { let nonce = GenericArray::from_slice(&nonce[..]); let encrypted = self.aead.encrypt(nonce, decrypted)?; Ok(encrypted) } + /// Decrypts a payload pub fn decrypt(&self, nonce: &[u8; 12], encrypted: &[u8]) -> anyhow::Result> { let nonce = GenericArray::from_slice(&nonce[..]); let encrypted = self.aead.decrypt(nonce, encrypted)?; @@ -86,6 +90,7 @@ pub struct KeyConfig { key: KeyOrPath, } +/// Application secrets #[serde_as] #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] pub struct SecretsConfig { @@ -104,6 +109,7 @@ pub struct SecretsConfig { } impl SecretsConfig { + /// Derive a signing and verifying keystore out of the config pub async fn key_store(&self) -> anyhow::Result { let mut store = StaticKeystore::new(); @@ -158,6 +164,7 @@ impl SecretsConfig { Ok(store) } + /// Derive an [`Encrypter`] out of the config #[must_use] pub fn encrypter(&self) -> Encrypter { Encrypter::new(&self.encryption)