alibi_core/utils/username/
policy.rs

1//! Configured username validation and normalization stages.
2
3use super::UsernameValidationError;
4use crate::{AuthError, AuthResult, utils::json::JsValue};
5use async_trait::async_trait;
6use std::{fmt, future::Future, sync::Arc};
7
8/// Awaited application validation of a username or display username.
9#[async_trait]
10pub trait UsernameValidator: Send + Sync {
11    async fn validate(&self, value: &str) -> AuthResult<bool>;
12}
13#[async_trait]
14impl<F, Fut> UsernameValidator for F
15where
16    F: Fn(String) -> Fut + Send + Sync,
17    Fut: Future<Output = AuthResult<bool>> + Send,
18{
19    async fn validate(&self, value: &str) -> AuthResult<bool> {
20        self(value.to_owned()).await
21    }
22}
23
24/// A synchronous normalization callback; errors propagate to its caller.
25pub trait UsernameNormalizer: Send + Sync {
26    fn normalize(&self, value: &str) -> AuthResult<String>;
27}
28impl<F> UsernameNormalizer for F
29where
30    F: Fn(&str) -> AuthResult<String> + Send + Sync,
31{
32    fn normalize(&self, value: &str) -> AuthResult<String> {
33        self(value)
34    }
35}
36
37#[derive(Clone, Default)]
38pub enum UsernameNormalization {
39    #[default]
40    Lowercase,
41    Preserve,
42    Custom(Arc<dyn UsernameNormalizer>),
43}
44impl fmt::Debug for UsernameNormalization {
45    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
46        f.write_str(match self {
47            Self::Lowercase => "Lowercase",
48            Self::Preserve => "Preserve",
49            Self::Custom(_) => "Custom",
50        })
51    }
52}
53
54/// The explicit upstream validation-order setting. An absent setting is
55/// distinct: sign-in validates raw input, while lookup always normalizes it.
56#[derive(Clone, Copy, Debug, PartialEq, Eq)]
57pub enum UsernameValidationOrder {
58    PreNormalization,
59    PostNormalization,
60}
61
62#[derive(Clone)]
63pub struct UsernameConfig {
64    /// UTF-16 lengths; zero uses the upstream defaults of 3 and 30.
65    pub min_length: usize,
66    pub max_length: usize,
67    pub normalization: UsernameNormalization,
68    pub validator: Option<Arc<dyn UsernameValidator>>,
69    pub include_display_username: bool,
70    pub display_normalizer: Option<Arc<dyn UsernameNormalizer>>,
71    pub display_validator: Option<Arc<dyn UsernameValidator>>,
72    pub validation_order: Option<UsernameValidationOrder>,
73    pub display_validation_order: Option<UsernameValidationOrder>,
74    pub immutable_username: bool,
75    /// Admit usernames supplied by endpoint callers.
76    pub input: bool,
77}
78impl Default for UsernameConfig {
79    fn default() -> Self {
80        Self {
81            min_length: 3,
82            max_length: 30,
83            normalization: UsernameNormalization::Lowercase,
84            validator: None,
85            include_display_username: true,
86            display_normalizer: None,
87            display_validator: None,
88            validation_order: None,
89            display_validation_order: None,
90            immutable_username: false,
91            input: true,
92        }
93    }
94}
95impl fmt::Debug for UsernameConfig {
96    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
97        f.debug_struct("UsernameConfig")
98            .field("min_length", &self.min_length)
99            .field("max_length", &self.max_length)
100            .field("normalization", &self.normalization)
101            .field("validator", &self.validator.as_ref().map(|_| "callback"))
102            .field("include_display_username", &self.include_display_username)
103            .field(
104                "display_normalizer",
105                &self.display_normalizer.as_ref().map(|_| "callback"),
106            )
107            .field(
108                "display_validator",
109                &self.display_validator.as_ref().map(|_| "callback"),
110            )
111            .field("validation_order", &self.validation_order)
112            .field("display_validation_order", &self.display_validation_order)
113            .field("immutable_username", &self.immutable_username)
114            .field("input", &self.input)
115            .finish()
116    }
117}
118impl UsernameConfig {
119    pub fn normalize(&self, value: &str) -> AuthResult<String> {
120        match &self.normalization {
121            UsernameNormalization::Lowercase => Ok(value.to_lowercase()),
122            UsernameNormalization::Preserve => Ok(value.to_owned()),
123            UsernameNormalization::Custom(normalizer) => normalizer
124                .normalize(value)
125                .map_err(AuthError::into_callback_failure),
126        }
127    }
128    pub fn normalize_display(&self, value: &str) -> AuthResult<String> {
129        self.display_normalizer.as_ref().map_or_else(
130            || Ok(value.to_owned()),
131            |normalizer| {
132                normalizer
133                    .normalize(value)
134                    .map_err(AuthError::into_callback_failure)
135            },
136        )
137    }
138    pub async fn value_error(&self, value: &str) -> AuthResult<Option<UsernameValidationError>> {
139        let length = value.encode_utf16().count();
140        let minimum = if self.min_length == 0 {
141            3
142        } else {
143            self.min_length
144        };
145        let maximum = if self.max_length == 0 {
146            30
147        } else {
148            self.max_length
149        };
150        if length < minimum {
151            return Ok(Some(UsernameValidationError::TooShort));
152        }
153        if length > maximum {
154            return Ok(Some(UsernameValidationError::TooLong));
155        }
156        let valid = if let Some(validator) = &self.validator {
157            validator
158                .validate(value)
159                .await
160                .map_err(AuthError::into_callback_failure)?
161        } else {
162            super::valid_default_characters(value)
163        };
164        Ok((!valid).then_some(UsernameValidationError::Invalid))
165    }
166    pub async fn validate_value(&self, value: &str, status: u16) -> AuthResult<()> {
167        if let Some(error) = self.value_error(value).await? {
168            return Err(error.auth_error(status));
169        }
170        Ok(())
171    }
172    pub async fn validate_hook_value(&self, value: &str) -> AuthResult<()> {
173        if self.validation_order == Some(UsernameValidationOrder::PostNormalization) {
174            self.validate_value(&self.normalize(value)?, 400).await
175        } else {
176            self.validate_value(value, 400).await
177        }
178    }
179    pub async fn validate_display(&self, value: &str) -> AuthResult<()> {
180        if !self.include_display_username {
181            return Ok(());
182        }
183        if let Some(validator) = &self.display_validator {
184            let normalized;
185            let input = if self.display_validation_order
186                == Some(UsernameValidationOrder::PostNormalization)
187            {
188                normalized = self.normalize_display(value)?;
189                &normalized
190            } else {
191                value
192            };
193            if !validator
194                .validate(input)
195                .await
196                .map_err(AuthError::into_callback_failure)?
197            {
198                return Err(AuthError::Upstream {
199                    status: 400,
200                    code: "INVALID_DISPLAY_USERNAME",
201                    message: "Display username is invalid",
202                });
203            }
204        }
205        Ok(())
206    }
207    /// Schema input transforms run both during endpoint parsing and storage.
208    pub fn fields(&self) -> crate::field_policy::FieldConfigs {
209        use crate::field_policy::FieldConfig;
210        let mut fields = crate::field_policy::FieldConfigs::new();
211        let policy = self.clone();
212        _ = fields.insert(
213            "username".into(),
214            FieldConfig::new(serde_json::json!({"type":"string"})).transform(move |value| {
215                match value {
216                    Some(JsValue::String(value)) => {
217                        Ok(Some(JsValue::String(policy.normalize(value)?)))
218                    }
219                    value => Ok(value.cloned()),
220                }
221            }),
222        );
223        if let Some(field) = fields.get_mut("username") {
224            field.input = self.input;
225        }
226        if self.include_display_username {
227            let policy = self.clone();
228            _ = fields.insert(
229                "displayUsername".into(),
230                FieldConfig::new(serde_json::json!({"type":"string"})).transform(move |value| {
231                    match value {
232                        Some(JsValue::String(value)) => {
233                            Ok(Some(JsValue::String(policy.normalize_display(value)?)))
234                        }
235                        value => Ok(value.cloned()),
236                    }
237                }),
238            );
239        } else {
240            let mut hidden = FieldConfig::new(serde_json::json!({"type":"string"}));
241            hidden.input = false;
242            hidden.returned = false;
243            _ = fields.insert("displayUsername".into(), hidden);
244        }
245        fields
246    }
247    /// Normalize the actual database-hook candidate before adapter transforms.
248    pub fn normalize_fields(
249        &self,
250        username: &mut Option<String>,
251        display: &mut Option<String>,
252        values: &mut crate::field_policy::FieldValues,
253        creation: bool,
254    ) -> AuthResult<()> {
255        let original_username = username.clone();
256        if let Some(value) = username.as_mut() {
257            if !value.is_empty() {
258                *value = self.normalize(value)?;
259            }
260            _ = values.insert("username".into(), JsValue::String(value.clone()));
261        }
262        if self.include_display_username {
263            if creation
264                && username.as_ref().is_some_and(|value| !value.is_empty())
265                && display.as_ref().is_none_or(String::is_empty)
266            {
267                display.clone_from(&original_username);
268                if let Some(value) = &display {
269                    _ = values.insert("displayUsername".into(), JsValue::String(value.clone()));
270                }
271            } else if let Some(value) = display.as_mut().filter(|value| !value.is_empty()) {
272                *value = self.normalize_display(value)?;
273                _ = values.insert("displayUsername".into(), JsValue::String(value.clone()));
274            }
275        } else {
276            *display = None;
277        }
278        Ok(())
279    }
280}
alibi_core/utils/username/policy.rs

alibi_core/utils/username/
policy.rs
