entropy-auth 2026.7.31

//! Shared input validation for names, usernames, OAuth parameters, and other
//! external identifiers used throughout the auth crate.
//!
//! Centralises character allowlists and safety rules so that every untrusted
//! string passes through one code path before it reaches storage, logging, or
//! downstream services.
//!
//! # Name validation
//!
//! [`is_valid_name`] reuses the exact rules from `entropy-logging` so that
//! names accepted here are also safe for log file paths and command identifiers.
//!
//! # Auth-specific validators
//!
//! Additional validators enforce constraints appropriate for OAuth 2.0 /
//! `OpenID` Connect parameters:
//!
//! | Validator                   | Governed by          |
//! |-----------------------------|----------------------|
//! | [`is_valid_username`]       | Application policy   |
//! | [`is_valid_redirect_uri`]   | RFC 6749 §3.1.2     |
//! | [`is_valid_scope`]          | RFC 6749 §3.3       |
//! | [`is_valid_client_id`]      | RFC 6749 §2.2       |

// ---------------------------------------------------------------------------
// Name validation (mirrored from entropy-logging)
// ---------------------------------------------------------------------------

/// Maximum byte length for a validated name.
///
/// Names longer than this are rejected by [`is_valid_name`]. The limit
/// is deliberately generous — most names are under 30 bytes — but
/// bounded to prevent unbounded allocation in error messages and
/// log file paths.
pub const MAX_NAME_LEN: usize = 200;

/// Human-readable description of the validation rules enforced by
/// [`is_valid_name`]. Used by error types to avoid duplicating the
/// constraint list in multiple `Display` implementations.
///
/// The numeric limit is embedded directly in the string (rather than
/// referencing `MAX_NAME_LEN` by name) so that user-facing error
/// messages are self-contained and readable without consulting the docs.
pub const NAME_RULES: &str = "must be non-empty, not exceed 200 bytes, \
     start with an ASCII alphanumeric character, contain only [a-zA-Z0-9._-], \
     must not contain consecutive periods ('..') or end with a period, \
     and must not match a Windows reserved device name";

// Compile-time guard: the "200 bytes" literal in `NAME_RULES` must
// match `MAX_NAME_LEN`. If `MAX_NAME_LEN` changes, update the string
// above and this assertion will enforce the correspondence.
const _: () = assert!(
    MAX_NAME_LEN == 200,
    "MAX_NAME_LEN changed — update NAME_RULES string to match"
);

/// Returns `true` if `name` is safe to use as a filename or command
/// identifier.
///
/// The name must:
/// - Not be empty
/// - Not exceed 200 bytes
/// - Start with an ASCII alphanumeric character
/// - Contain only ASCII alphanumeric characters, hyphens (`-`), underscores
///   (`_`), or periods (`.`)
/// - Not contain consecutive periods (`..`)
/// - Not end with a period
/// - Not match a Windows reserved device name (`CON`, `PRN`, etc.)
///
/// # Security
///
/// This rejects path separators, null bytes, control characters, whitespace,
/// hidden-file prefixes, and shell metacharacters — preventing path traversal,
/// command injection, and filename collision attacks.
#[must_use]
#[inline]
#[doc(alias = "validate_name")]
pub fn is_valid_name(name: &str) -> bool {
    if name.is_empty() || name.len() > MAX_NAME_LEN {
        return false;
    }

    // Must start with alphanumeric.
    if !name.as_bytes()[0].is_ascii_alphanumeric() {
        return false;
    }

    // Only allow [a-zA-Z0-9._-].
    if !name
        .bytes()
        .all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_' || b == b'.')
    {
        return false;
    }

    // Reject consecutive periods (path traversal component) and trailing
    // periods (Windows silently strips them from filenames, which could
    // cause unexpected collisions).
    if name.contains("..") || name.ends_with('.') {
        return false;
    }

    // Reject Windows reserved device names (case-insensitive).
    // Check the stem (part before the first period) against reserved names.
    // Uses `eq_ignore_ascii_case` to avoid heap-allocating an uppercase copy.
    //
    // `split('.')` always yields at least one element (even for an empty
    // string), so the `unwrap_or` fallback is unreachable. We use
    // `unwrap_or(name)` instead of `unwrap()` to avoid a clippy
    // `missing_panics_doc` warning on this public function — adding a
    // `# Panics` section for an unreachable code path would be misleading.
    let stem = name.split('.').next().unwrap_or(name);
    if is_windows_reserved_name(stem) {
        return false;
    }

    true
}

/// Windows reserved device names used by [`is_windows_reserved_name`].
///
/// `CONIN$` and `CONOUT$` are also reserved on Windows but are not
/// listed here because the `$` character is already rejected by the
/// character allowlist in [`is_valid_name`].
const WINDOWS_RESERVED: &[&str] = &[
    // Standard device names.
    "CON", "PRN", "AUX", "NUL", // Serial ports.
    "COM0", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
    // Parallel ports.
    "LPT0", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
];

/// Returns `true` if `stem` matches a Windows reserved device name
/// (case-insensitive). Uses [`str::eq_ignore_ascii_case`] to avoid
/// heap allocation.
fn is_windows_reserved_name(stem: &str) -> bool {
    // Short-circuit on length: all reserved names are 3-4 characters.
    if stem.len() < 3 || stem.len() > 4 {
        return false;
    }

    WINDOWS_RESERVED
        .iter()
        .any(|reserved| stem.eq_ignore_ascii_case(reserved))
}

// ---------------------------------------------------------------------------
// Username validation
// ---------------------------------------------------------------------------

/// Maximum byte length for a validated username.
///
/// 256 bytes accommodates email-style usernames (`user@example.com`) and
/// federated identity providers that use long opaque identifiers, while
/// still bounding storage and display costs.
pub const MAX_USERNAME_LEN: usize = 256;

/// Human-readable description of the validation rules enforced by
/// [`is_valid_username`].
pub const USERNAME_RULES: &str = "must be non-empty, not exceed 256 bytes, \
     start with an ASCII alphanumeric character, contain only [a-zA-Z0-9._@-], \
     must not contain consecutive special characters, and must not contain null bytes";

// Compile-time guard: keep the embedded "256" in sync with the constant.
const _: () = assert!(
    MAX_USERNAME_LEN == 256,
    "MAX_USERNAME_LEN changed — update USERNAME_RULES string to match"
);

/// Returns `true` if `s` is a valid username.
///
/// The username must:
/// - Not be empty
/// - Not exceed 256 bytes
/// - Start with an ASCII alphanumeric character (`[a-zA-Z0-9]`)
/// - Contain only ASCII alphanumeric characters, periods (`.`), underscores
///   (`_`), hyphens (`-`), or at-signs (`@`)
/// - Not contain consecutive special (non-alphanumeric) characters
/// - Not contain null bytes
///
/// # Security
///
/// * Rejecting null bytes prevents truncation attacks in C-backed storage.
/// * Requiring an alphanumeric start prevents hidden-file or option-injection
///   attacks (`-flag`, `.hidden`).
/// * Forbidding consecutive special characters mitigates visual spoofing
///   (e.g. `user..name` vs `user.name`) and simplifies display rendering.
#[must_use]
#[inline]
#[doc(alias = "validate_username")]
pub fn is_valid_username(s: &str) -> bool {
    if s.is_empty() || s.len() > MAX_USERNAME_LEN {
        return false;
    }

    // Must start with alphanumeric.
    if !s.as_bytes()[0].is_ascii_alphanumeric() {
        return false;
    }

    // Track whether the previous character was a special (non-alphanumeric)
    // character so we can reject consecutive specials.
    let mut prev_special = false;

    for &b in s.as_bytes() {
        if b == 0 {
            // Null byte — reject unconditionally.
            return false;
        }

        let is_alnum = b.is_ascii_alphanumeric();
        let is_special = b == b'.' || b == b'_' || b == b'-' || b == b'@';

        if !is_alnum && !is_special {
            // Character outside the allowlist.
            return false;
        }

        if is_special {
            if prev_special {
                // Consecutive special characters.
                return false;
            }
            prev_special = true;
        } else {
            prev_special = false;
        }
    }

    true
}

// ---------------------------------------------------------------------------
// Redirect URI validation
// ---------------------------------------------------------------------------

/// Maximum byte length for a validated redirect URI.
///
/// 2048 bytes matches the de-facto limit in most browsers and reverse
/// proxies (e.g. Nginx `large_client_header_buffers`). Longer URIs
/// are almost certainly malformed or adversarial.
pub const MAX_REDIRECT_URI_LEN: usize = 2048;

/// Human-readable description of the validation rules enforced by
/// [`is_valid_redirect_uri`].
pub const REDIRECT_URI_RULES: &str = "must not be empty, not exceed 2048 bytes, \
     start with \"https://\" (or \"http://localhost\" / \"http://127.0.0.1\" for local \
     development), must not contain a fragment (#), and must not contain null bytes";

// Compile-time guard: keep the embedded "2048" in sync with the constant.
const _: () = assert!(
    MAX_REDIRECT_URI_LEN == 2048,
    "MAX_REDIRECT_URI_LEN changed — update REDIRECT_URI_RULES string to match"
);

/// Returns `true` if `s` is a valid OAuth 2.0 redirect URI.
///
/// Per RFC 6749 §3.1.2 the redirect URI must be an absolute URI. This
/// validator enforces:
///
/// - Non-empty
/// - At most 2048 bytes
/// - Scheme is `https://`, **or** `http://localhost` / `http://127.0.0.1`
///   (for local development per RFC 8252 §8.3)
/// - No fragment component (`#`) — RFC 6749 §3.1.2 explicitly forbids it
/// - No null bytes
///
/// # Security
///
/// * Requiring HTTPS (except for loopback) prevents token interception
///   via unencrypted transport.
/// * Rejecting fragments prevents client-side token leakage through
///   the URL hash, which is never sent to the server.
/// * Null byte rejection prevents truncation attacks in C-backed HTTP
///   stacks.
/// * Length bounding mitigates denial-of-service through oversized URIs.
#[must_use]
#[inline]
#[doc(alias = "validate_redirect_uri")]
pub fn is_valid_redirect_uri(s: &str) -> bool {
    if s.is_empty() || s.len() > MAX_REDIRECT_URI_LEN {
        return false;
    }

    // Null bytes could cause truncation in C-backed HTTP stacks.
    if s.bytes().any(|b| b == 0) {
        return false;
    }

    // Fragments are forbidden by RFC 6749 §3.1.2.
    if s.contains('#') {
        return false;
    }

    // Scheme check: HTTPS required, with loopback exceptions for local dev.
    let has_valid_scheme = s.starts_with("https://") || is_http_loopback(s);

    if !has_valid_scheme {
        return false;
    }

    true
}

/// Returns `true` if `s` is an `http://` URI targeting a loopback address.
///
/// RFC 8252 §8.3 permits `http` for loopback redirect URIs during local
/// development. We accept `http://localhost`, `http://127.0.0.1`, and
/// `http://[::1]` (with optional port and path).
fn is_http_loopback(s: &str) -> bool {
    if !s.starts_with("http://") {
        return false;
    }

    let after_scheme = &s["http://".len()..];

    // SECURITY: isolate the AUTHORITY and reject userinfo first. Matching the
    // loopback literal anywhere in `after_scheme` accepted
    // `http://127.0.0.1:8080@attacker.example/cb`, where the real host is
    // `attacker.example` and the loopback text is merely the userinfo — so a
    // plain-HTTP off-host redirect URI passed as a "loopback" exception.
    let authority = after_scheme
        .split(['/', '?', '#'])
        .next()
        .unwrap_or(after_scheme);
    if authority.contains('@') {
        return false;
    }

    // Match "localhost" or "127.0.0.1", optionally followed by `:port`,
    // `/path`, or `?query`. The host portion ends at the first `/`, `?`,
    // or `:` (port separator).
    for host in &["localhost", "127.0.0.1", "[::1]"] {
        if after_scheme.eq_ignore_ascii_case(host) {
            // Exact match with no trailing path/port.
            return true;
        }
        if let Some(rest) = after_scheme
            .get(..host.len())
            .filter(|prefix| prefix.eq_ignore_ascii_case(host))
            .and_then(|_| after_scheme.get(host.len()..))
        {
            // The character immediately after the host must be a delimiter.
            let next = rest.as_bytes().first().copied();
            if matches!(next, Some(b':' | b'/' | b'?')) {
                return true;
            }
        }
    }

    false
}

// ---------------------------------------------------------------------------
// HTTPS URL validation
// ---------------------------------------------------------------------------

/// Returns `true` if `url` starts with `"https://"`.
///
/// This is a simple scheme check used by OIDC discovery and SAML
/// configuration to enforce transport-layer security on endpoint URLs.
/// It does **not** validate the URL structure beyond the scheme prefix.
#[must_use]
#[inline]
pub fn is_https_url(url: &str) -> bool {
    url.starts_with("https://")
}

// ---------------------------------------------------------------------------
// Scope validation
// ---------------------------------------------------------------------------

/// Maximum byte length for a validated scope string.
///
/// 1024 bytes is generous for space-delimited scope tokens. The bound
/// prevents abuse via extremely long scope lists that could bloat tokens
/// or logs.
pub const MAX_SCOPE_LEN: usize = 1024;

/// Human-readable description of the validation rules enforced by
/// [`is_valid_scope`].
pub const SCOPE_RULES: &str = "must be non-empty, not exceed 1024 bytes, \
     consist of space-delimited tokens where each token contains only NQCHAR \
     characters (0x21, 0x23-0x5B, 0x5D-0x7E) per RFC 6749 §3.3";

// Compile-time guard: keep the embedded "1024" in sync with the constant.
const _: () = assert!(
    MAX_SCOPE_LEN == 1024,
    "MAX_SCOPE_LEN changed — update SCOPE_RULES string to match"
);

/// Returns `true` if `s` is a valid OAuth 2.0 scope string.
///
/// Per RFC 6749 §3.3 the scope is a space-delimited list of scope tokens.
/// Each token consists of one or more NQCHAR characters, defined in
/// RFC 6749 Appendix A as:
///
/// ```text
/// NQCHAR = %x21 / %x23-5B / %x5D-7E
/// ```
///
/// This excludes space (`0x20`), double-quote (`0x22`, `"`), and backslash
/// (`0x5C`, `\`), as well as all control characters and non-ASCII bytes.
///
/// The full scope string must:
/// - Not be empty
/// - Not exceed 1024 bytes
/// - Consist of one or more tokens separated by single spaces (`0x20`)
///
/// # Security
///
/// * Strict NQCHAR enforcement prevents injection of control characters
///   or shell metacharacters into scope values that may appear in logs,
///   tokens, or HTTP headers.
/// * Length bounding prevents denial-of-service through oversized scope
///   parameters.
#[must_use]
#[inline]
#[doc(alias = "validate_scope")]
pub fn is_valid_scope(s: &str) -> bool {
    if s.is_empty() || s.len() > MAX_SCOPE_LEN {
        return false;
    }

    // Split on spaces; each segment must be a non-empty NQCHAR token.
    // This also implicitly rejects leading/trailing spaces and consecutive
    // spaces (they would produce empty segments).
    for token in s.split(' ') {
        if token.is_empty() {
            // Empty token means leading/trailing/consecutive spaces.
            return false;
        }
        if !token.bytes().all(is_nqchar) {
            return false;
        }
    }

    true
}

/// Returns `true` if `b` is an NQCHAR as defined by RFC 6749 Appendix A.
///
/// ```text
/// NQCHAR = %x21 / %x23-5B / %x5D-7E
/// ```
///
/// Excludes: space (0x20), double-quote (0x22), backslash (0x5C), control
/// characters (0x00-0x1F, 0x7F), and non-ASCII bytes (0x80-0xFF).
#[inline]
const fn is_nqchar(b: u8) -> bool {
    matches!(b, 0x21 | 0x23..=0x5B | 0x5D..=0x7E)
}

// ---------------------------------------------------------------------------
// Client ID validation
// ---------------------------------------------------------------------------

/// Maximum byte length for a validated client identifier.
///
/// 256 bytes accommodates UUIDs, URIs, and other provider-issued
/// identifiers while bounding storage costs.
pub const MAX_CLIENT_ID_LEN: usize = 256;

/// Human-readable description of the validation rules enforced by
/// [`is_valid_client_id`].
pub const CLIENT_ID_RULES: &str = "must be non-empty, not exceed 256 bytes, \
     contain only printable ASCII characters (0x20-0x7E), and must not contain \
     null bytes";

// Compile-time guard: keep the embedded "256" in sync with the constant.
const _: () = assert!(
    MAX_CLIENT_ID_LEN == 256,
    "MAX_CLIENT_ID_LEN changed — update CLIENT_ID_RULES string to match"
);

/// Returns `true` if `s` is a valid OAuth 2.0 client identifier.
///
/// Per RFC 6749 §2.2 the client identifier is issued by the authorization
/// server and is not a secret. This validator enforces:
///
/// - Non-empty
/// - At most 256 bytes
/// - All bytes are printable ASCII (`0x20`–`0x7E`)
/// - No null bytes (implied by printable ASCII, but checked explicitly for
///   clarity)
///
/// # Security
///
/// * Printable-ASCII enforcement prevents control-character injection into
///   HTTP headers, logs, and database queries.
/// * Null byte rejection prevents C-string truncation attacks.
/// * Length bounding prevents denial-of-service through oversized identifiers.
#[must_use]
#[inline]
#[doc(alias = "validate_client_id")]
pub fn is_valid_client_id(s: &str) -> bool {
    if s.is_empty() || s.len() > MAX_CLIENT_ID_LEN {
        return false;
    }

    // Printable ASCII: 0x20 (space) through 0x7E (~). This range excludes
    // null (0x00), control characters (0x01-0x1F), and DEL (0x7F).
    s.bytes().all(|b| (0x20..=0x7E).contains(&b))
}

// ---------------------------------------------------------------------------
// Email validation
// ---------------------------------------------------------------------------

/// Maximum byte length for a validated email address.
///
/// RFC 5321 §4.5.3.1 limits the total length of a mailbox to 254 octets
/// (256 minus the angle brackets used in SMTP).
pub const MAX_EMAIL_LEN: usize = 254;

/// Human-readable description of the validation rules enforced by
/// [`is_valid_email`].
pub const EMAIL_RULES: &str = "must be non-empty, not exceed 254 bytes, \
     contain exactly one '@', have a non-empty local part (max 64 bytes) and \
     a non-empty domain with at least one '.', using only printable ASCII";

// Compile-time guard: keep the embedded "254" in sync with the constant.
const _: () = assert!(
    MAX_EMAIL_LEN == 254,
    "MAX_EMAIL_LEN changed — update EMAIL_RULES string to match"
);

/// Returns `true` if `email` is a structurally valid email address.
///
/// This is a practical validation suitable for registration forms, not a
/// full RFC 5322 parser. The address must:
///
/// - Not be empty
/// - Not exceed 254 bytes (RFC 5321 §4.5.3.1)
/// - Contain exactly one `@` character
/// - Have a non-empty local part (max 64 bytes, RFC 5321 §4.5.3.1.1)
/// - Have a non-empty domain containing at least one `.`
/// - Contain only printable ASCII characters (0x21–0x7E), excluding
///   control characters and spaces
/// - Not have consecutive dots in either local or domain part
/// - Not start or end with a dot in either local or domain part
///
/// # Security
///
/// * Printable-ASCII enforcement prevents control-character injection.
/// * Length bounding prevents denial-of-service through oversized values.
/// * Null bytes and spaces are rejected to prevent truncation attacks
///   and display spoofing.
#[must_use]
#[inline]
#[doc(alias = "validate_email")]
pub fn is_valid_email(email: &str) -> bool {
    if email.is_empty() || email.len() > MAX_EMAIL_LEN {
        return false;
    }

    // Must contain only printable ASCII (0x21-0x7E), no spaces.
    if !email.bytes().all(|b| (0x21..=0x7E).contains(&b)) {
        return false;
    }

    // Must contain exactly one '@'.
    let at_count = email.bytes().filter(|&b| b == b'@').count();
    if at_count != 1 {
        return false;
    }

    // `at_count == 1` above guarantees this is `Some`; the else is unreachable.
    let Some(at_pos) = email.find('@') else {
        return false;
    };
    let local = &email[..at_pos];
    let domain = &email[at_pos + 1..];

    // Local part: non-empty, max 64 bytes.
    if local.is_empty() || local.len() > 64 {
        return false;
    }

    // Local part must be an unquoted dot-atom (RFC 5321 §4.1.2): restrict to
    // the `atext` set plus '.'. This rejects specials that are illegal
    // outside a quoted string — `< > , ; : ( ) [ ] \ "` — which the
    // printable-ASCII gate above would otherwise admit. Quoted local parts
    // (`"foo bar"@example.com`) are deliberately unsupported.
    if !local.bytes().all(|b| {
        b.is_ascii_alphanumeric()
            || matches!(
                b,
                b'!' | b'#'
                    | b'$'
                    | b'%'
                    | b'&'
                    | b'\''
                    | b'*'
                    | b'+'
                    | b'-'
                    | b'/'
                    | b'='
                    | b'?'
                    | b'^'
                    | b'_'
                    | b'`'
                    | b'{'
                    | b'|'
                    | b'}'
                    | b'~'
                    | b'.'
            )
    }) {
        return false;
    }

    // Domain: non-empty, must contain at least one dot.
    if domain.is_empty() || !domain.contains('.') {
        return false;
    }

    // No consecutive dots, no leading/trailing dots in either part.
    for part in [local, domain] {
        if part.starts_with('.') || part.ends_with('.') || part.contains("..") {
            return false;
        }
    }

    // Domain labels: split on dots, each must be non-empty and alphanumeric
    // with hyphens allowed (but not at start/end).
    for label in domain.split('.') {
        if label.is_empty() {
            return false;
        }
        if label.starts_with('-') || label.ends_with('-') {
            return false;
        }
        if !label
            .bytes()
            .all(|b| b.is_ascii_alphanumeric() || b == b'-')
        {
            return false;
        }
    }

    true
}

// ---------------------------------------------------------------------------
// Password strength validation
// ---------------------------------------------------------------------------

/// Default set of special characters accepted for password complexity.
pub const DEFAULT_SPECIAL_CHARS: &str = "!@#$%^&*()_+-=[]{}|;:,.<>?";

/// Human-readable description of the default password rules.
pub const PASSWORD_RULES: &str = "must be at least 8 bytes, contain at least one \
     uppercase letter, one lowercase letter, one digit, and one special character";

/// Configuration for password strength validation rules.
///
/// Uses builder pattern with sensible defaults matching common security
/// policies.
// Each bool is an independent, user-facing policy toggle; collapsing them into
// a bitflag would hurt the builder API's readability.
#[allow(clippy::struct_excessive_bools)]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PasswordRules {
    /// Minimum password length. Default: 8.
    min_length: usize,
    /// Require at least one uppercase ASCII letter. Default: true.
    require_uppercase: bool,
    /// Require at least one lowercase ASCII letter. Default: true.
    require_lowercase: bool,
    /// Require at least one ASCII digit. Default: true.
    require_digit: bool,
    /// Require at least one special character. Default: true.
    require_special: bool,
    /// The set of characters considered "special". Default: [`DEFAULT_SPECIAL_CHARS`].
    special_chars: &'static str,
}

impl Default for PasswordRules {
    fn default() -> Self {
        Self {
            min_length: 8,
            require_uppercase: true,
            require_lowercase: true,
            require_digit: true,
            require_special: true,
            special_chars: DEFAULT_SPECIAL_CHARS,
        }
    }
}

impl PasswordRules {
    /// Creates a new `PasswordRules` with default settings.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets the minimum password length in bytes (not characters).
    ///
    /// Because the check uses `str::len()`, multi-byte UTF-8 characters
    /// count as more than one toward the minimum. For ASCII-only passwords
    /// the byte length equals the character count.
    #[must_use]
    pub fn with_min_length(mut self, min_length: usize) -> Self {
        self.min_length = min_length;
        self
    }

    /// Sets whether an uppercase letter is required.
    #[must_use]
    pub fn with_require_uppercase(mut self, required: bool) -> Self {
        self.require_uppercase = required;
        self
    }

    /// Sets whether a lowercase letter is required.
    #[must_use]
    pub fn with_require_lowercase(mut self, required: bool) -> Self {
        self.require_lowercase = required;
        self
    }

    /// Sets whether a digit is required.
    #[must_use]
    pub fn with_require_digit(mut self, required: bool) -> Self {
        self.require_digit = required;
        self
    }

    /// Sets whether a special character is required.
    #[must_use]
    pub fn with_require_special(mut self, required: bool) -> Self {
        self.require_special = required;
        self
    }

    /// Sets the special character set.
    #[must_use]
    pub fn with_special_chars(mut self, chars: &'static str) -> Self {
        self.special_chars = chars;
        self
    }

    /// Returns the minimum password length in bytes (not characters).
    #[must_use]
    #[inline]
    pub fn min_length(&self) -> usize {
        self.min_length
    }
}

/// Validates a password against the given rules.
///
/// Returns `Ok(())` if the password satisfies all rules.
///
/// # Errors
///
/// Returns `Err` with a list of human-readable descriptions of the unmet
/// rules when the password fails one or more checks.
///
/// # Security
///
/// This function never logs or includes the password in error output.
/// The returned error strings describe which *rules* are unmet, not
/// what the password contains.
pub fn validate_password_strength(
    password: &str,
    rules: &PasswordRules,
) -> Result<(), Vec<&'static str>> {
    let mut errors = Vec::new();

    if password.len() < rules.min_length {
        errors.push("must meet the minimum length requirement");
    }
    if rules.require_uppercase && !password.chars().any(|c| c.is_ascii_uppercase()) {
        errors.push("must contain at least one uppercase letter");
    }
    if rules.require_lowercase && !password.chars().any(|c| c.is_ascii_lowercase()) {
        errors.push("must contain at least one lowercase letter");
    }
    if rules.require_digit && !password.chars().any(|c| c.is_ascii_digit()) {
        errors.push("must contain at least one digit");
    }
    if rules.require_special && !password.chars().any(|c| rules.special_chars.contains(c)) {
        errors.push("must contain at least one special character");
    }

    if errors.is_empty() {
        Ok(())
    } else {
        Err(errors)
    }
}

// ===========================================================================
// Tests
// ===========================================================================

#[cfg(test)]
mod tests {
    use super::*;

    // --- Name Validation ---

    #[test]
    fn name_empty() {
        assert!(!is_valid_name(""));
    }

    #[test]
    fn name_exceeds_max_length() {
        let long = "a".repeat(MAX_NAME_LEN + 1);
        assert!(!is_valid_name(&long));
    }

    #[test]
    fn name_max_length_accepted() {
        let name = "a".repeat(MAX_NAME_LEN);
        assert!(is_valid_name(&name));
    }

    #[test]
    fn name_starts_with_hyphen() {
        assert!(!is_valid_name("-myapp"));
    }

    #[test]
    fn name_starts_with_underscore() {
        assert!(!is_valid_name("_myapp"));
    }

    #[test]
    fn name_starts_with_period() {
        assert!(!is_valid_name(".hidden"));
    }

    #[test]
    fn name_contains_slash() {
        assert!(!is_valid_name("foo/bar"));
    }

    #[test]
    fn name_contains_backslash() {
        assert!(!is_valid_name("foo\\bar"));
    }

    #[test]
    fn name_contains_space() {
        assert!(!is_valid_name("foo bar"));
    }

    #[test]
    fn name_contains_null() {
        assert!(!is_valid_name("foo\0bar"));
    }

    #[test]
    fn name_contains_newline() {
        assert!(!is_valid_name("foo\nbar"));
    }

    #[test]
    fn name_contains_tab() {
        assert!(!is_valid_name("foo\tbar"));
    }

    #[test]
    fn name_consecutive_periods() {
        assert!(!is_valid_name("foo..bar"));
    }

    #[test]
    fn name_dot_dot() {
        assert!(!is_valid_name(".."));
    }

    #[test]
    fn name_single_dot() {
        assert!(!is_valid_name("."));
    }

    #[test]
    fn name_trailing_period() {
        assert!(!is_valid_name("app."));
    }

    #[test]
    fn name_shell_metacharacters() {
        assert!(!is_valid_name("git;echo"));
        assert!(!is_valid_name("git|cat"));
        assert!(!is_valid_name("$(cmd)"));
    }

    #[test]
    fn name_windows_reserved() {
        for name in ["CON", "con", "PRN", "AUX", "NUL", "COM1", "LPT1"] {
            assert!(!is_valid_name(name), "{name} should be rejected");
        }
    }

    #[test]
    fn name_windows_reserved_with_extension() {
        // "CON.txt" should still be rejected — the stem is "CON".
        assert!(!is_valid_name("CON.txt"));
        assert!(!is_valid_name("nul.log"));
    }

    #[test]
    fn name_simple() {
        assert!(is_valid_name("my_app"));
    }

    #[test]
    fn name_with_hyphens() {
        assert!(is_valid_name("cargo-deny"));
    }

    #[test]
    fn name_with_periods() {
        assert!(is_valid_name("app.v2.1"));
    }

    #[test]
    fn name_with_mixed_characters() {
        assert!(is_valid_name("my-app_v2.1"));
    }

    #[test]
    fn name_single_character() {
        assert!(is_valid_name("a"));
    }

    #[test]
    fn name_numeric_start() {
        assert!(is_valid_name("7zip"));
    }

    // --- Username Validation ---

    #[test]
    fn username_empty() {
        assert!(!is_valid_username(""));
    }

    #[test]
    fn username_exceeds_max_length() {
        let long = "a".repeat(MAX_USERNAME_LEN + 1);
        assert!(!is_valid_username(&long));
    }

    #[test]
    fn username_max_length_accepted() {
        let name = "a".repeat(MAX_USERNAME_LEN);
        assert!(is_valid_username(&name));
    }

    #[test]
    fn username_simple() {
        assert!(is_valid_username("alice"));
    }

    #[test]
    fn username_with_at_sign() {
        assert!(is_valid_username("alice@example.com"));
    }

    #[test]
    fn username_with_all_special_chars() {
        assert!(is_valid_username("a.b-c_d@e"));
    }

    #[test]
    fn username_numeric_start() {
        assert!(is_valid_username("42user"));
    }

    #[test]
    fn username_single_character() {
        assert!(is_valid_username("a"));
    }

    #[test]
    fn username_starts_with_hyphen() {
        assert!(!is_valid_username("-alice"));
    }

    #[test]
    fn username_starts_with_period() {
        assert!(!is_valid_username(".alice"));
    }

    #[test]
    fn username_starts_with_underscore() {
        assert!(!is_valid_username("_alice"));
    }

    #[test]
    fn username_starts_with_at() {
        assert!(!is_valid_username("@alice"));
    }

    #[test]
    fn username_consecutive_specials() {
        assert!(!is_valid_username("alice..bob"));
        assert!(!is_valid_username("alice.-bob"));
        assert!(!is_valid_username("alice._bob"));
        assert!(!is_valid_username("alice@-bob"));
        assert!(!is_valid_username("alice-.bob"));
    }

    #[test]
    fn username_contains_space() {
        assert!(!is_valid_username("alice bob"));
    }

    #[test]
    fn username_contains_null() {
        assert!(!is_valid_username("alice\0bob"));
    }

    #[test]
    fn username_contains_slash() {
        assert!(!is_valid_username("alice/bob"));
    }

    #[test]
    fn username_contains_hash() {
        assert!(!is_valid_username("alice#1"));
    }

    #[test]
    fn username_trailing_special_allowed() {
        // Trailing special is allowed (only consecutive specials are rejected).
        // e.g. an email ending in a domain is fine.
        assert!(is_valid_username("alice@example.com"));
    }

    // --- Redirect URI Validation ---

    #[test]
    fn redirect_uri_empty() {
        assert!(!is_valid_redirect_uri(""));
    }

    #[test]
    fn redirect_uri_exceeds_max_length() {
        let long = format!("https://example.com/{}", "a".repeat(MAX_REDIRECT_URI_LEN));
        assert!(!is_valid_redirect_uri(&long));
    }

    #[test]
    fn redirect_uri_max_length_accepted() {
        let padding = "a".repeat(MAX_REDIRECT_URI_LEN - "https://x.co/".len());
        let uri = format!("https://x.co/{padding}");
        assert_eq!(uri.len(), MAX_REDIRECT_URI_LEN);
        assert!(is_valid_redirect_uri(&uri));
    }

    #[test]
    fn redirect_uri_https() {
        assert!(is_valid_redirect_uri("https://example.com/callback"));
    }

    #[test]
    fn redirect_uri_https_with_port() {
        assert!(is_valid_redirect_uri("https://example.com:8443/callback"));
    }

    #[test]
    fn redirect_uri_https_with_query() {
        assert!(is_valid_redirect_uri("https://example.com/cb?state=abc"));
    }

    #[test]
    fn redirect_uri_http_localhost() {
        assert!(is_valid_redirect_uri("http://localhost/callback"));
    }

    #[test]
    fn redirect_uri_http_localhost_with_port() {
        assert!(is_valid_redirect_uri("http://localhost:8080/callback"));
    }

    #[test]
    fn redirect_uri_http_localhost_bare() {
        assert!(is_valid_redirect_uri("http://localhost"));
    }

    #[test]
    fn redirect_uri_http_127_0_0_1() {
        assert!(is_valid_redirect_uri("http://127.0.0.1/callback"));
    }

    #[test]
    fn redirect_uri_http_127_0_0_1_with_port() {
        assert!(is_valid_redirect_uri("http://127.0.0.1:3000"));
    }

    #[test]
    fn redirect_uri_http_non_loopback_rejected() {
        assert!(!is_valid_redirect_uri("http://example.com/callback"));
    }

    #[test]
    fn redirect_uri_http_localhost_like_rejected() {
        // "localhostevil.com" should not match the loopback exception.
        assert!(!is_valid_redirect_uri("http://localhostevil.com/callback"));
    }

    #[test]
    fn redirect_uri_http_127_0_0_1_like_rejected() {
        // "127.0.0.1evil.com" should not match the loopback exception.
        assert!(!is_valid_redirect_uri("http://127.0.0.1evil.com"));
    }

    #[test]
    fn redirect_uri_http_ipv6_loopback() {
        assert!(is_valid_redirect_uri("http://[::1]/callback"));
    }

    #[test]
    fn redirect_uri_http_ipv6_loopback_with_port() {
        assert!(is_valid_redirect_uri("http://[::1]:8080/callback"));
    }

    #[test]
    fn redirect_uri_fragment_rejected() {
        assert!(!is_valid_redirect_uri("https://example.com/cb#frag"));
    }

    #[test]
    fn redirect_uri_null_byte_rejected() {
        assert!(!is_valid_redirect_uri("https://example.com/\0"));
    }

    #[test]
    fn redirect_uri_plain_http_rejected() {
        assert!(!is_valid_redirect_uri("http://remote-host.com/callback"));
    }

    #[test]
    fn redirect_uri_ftp_rejected() {
        assert!(!is_valid_redirect_uri("ftp://example.com/callback"));
    }

    #[test]
    fn redirect_uri_no_scheme() {
        assert!(!is_valid_redirect_uri("example.com/callback"));
    }

    #[test]
    fn redirect_uri_localhost_with_query() {
        assert!(is_valid_redirect_uri("http://localhost?code=abc"));
    }

    // --- Scope Validation ---

    #[test]
    fn scope_empty() {
        assert!(!is_valid_scope(""));
    }

    #[test]
    fn scope_exceeds_max_length() {
        let long = "a".repeat(MAX_SCOPE_LEN + 1);
        assert!(!is_valid_scope(&long));
    }

    #[test]
    fn scope_max_length_accepted() {
        let s = "a".repeat(MAX_SCOPE_LEN);
        assert!(is_valid_scope(&s));
    }

    #[test]
    fn scope_single_token() {
        assert!(is_valid_scope("openid"));
    }

    #[test]
    fn scope_multiple_tokens() {
        assert!(is_valid_scope("openid profile email"));
    }

    #[test]
    fn scope_with_special_nqchar() {
        // 0x21 is '!', 0x23 is '#', 0x7E is '~'
        assert!(is_valid_scope("read!write"));
        assert!(is_valid_scope("scope#1"));
        assert!(is_valid_scope("a~b"));
    }

    #[test]
    fn scope_leading_space_rejected() {
        assert!(!is_valid_scope(" openid"));
    }

    #[test]
    fn scope_trailing_space_rejected() {
        assert!(!is_valid_scope("openid "));
    }

    #[test]
    fn scope_consecutive_spaces_rejected() {
        assert!(!is_valid_scope("openid  profile"));
    }

    #[test]
    fn scope_double_quote_rejected() {
        // 0x22 is `"` — excluded from NQCHAR.
        assert!(!is_valid_scope("open\"id"));
    }

    #[test]
    fn scope_backslash_rejected() {
        // 0x5C is `\` — excluded from NQCHAR.
        assert!(!is_valid_scope("open\\id"));
    }

    #[test]
    fn scope_control_char_rejected() {
        assert!(!is_valid_scope("open\x01id"));
    }

    #[test]
    fn scope_null_byte_rejected() {
        assert!(!is_valid_scope("open\x00id"));
    }

    #[test]
    fn scope_non_ascii_rejected() {
        assert!(!is_valid_scope("öpenid"));
    }

    #[test]
    fn scope_space_only_rejected() {
        assert!(!is_valid_scope(" "));
    }

    #[test]
    fn scope_nqchar_boundary_0x21() {
        // 0x21 ('!') is the lowest valid NQCHAR.
        assert!(is_valid_scope("!"));
    }

    #[test]
    fn scope_nqchar_boundary_0x20_rejected() {
        // 0x20 is space — only valid as a token delimiter, not within a token.
        // A single space produces two empty tokens, which fails.
        assert!(!is_valid_scope(" "));
    }

    #[test]
    fn scope_nqchar_boundary_0x7e() {
        // 0x7E ('~') is the highest valid NQCHAR.
        assert!(is_valid_scope("~"));
    }

    #[test]
    fn scope_nqchar_boundary_0x7f_rejected() {
        // 0x7F is DEL — not valid NQCHAR.
        assert!(!is_valid_scope("\x7F"));
    }

    // --- Client ID Validation ---

    #[test]
    fn client_id_empty() {
        assert!(!is_valid_client_id(""));
    }

    #[test]
    fn client_id_exceeds_max_length() {
        let long = "a".repeat(MAX_CLIENT_ID_LEN + 1);
        assert!(!is_valid_client_id(&long));
    }

    #[test]
    fn client_id_max_length_accepted() {
        let id = "a".repeat(MAX_CLIENT_ID_LEN);
        assert!(is_valid_client_id(&id));
    }

    #[test]
    fn client_id_simple() {
        assert!(is_valid_client_id("my-client-123"));
    }

    #[test]
    fn client_id_uuid() {
        assert!(is_valid_client_id("550e8400-e29b-41d4-a716-446655440000"));
    }

    #[test]
    fn client_id_with_spaces() {
        // Spaces (0x20) are printable ASCII and allowed.
        assert!(is_valid_client_id("my client"));
    }

    #[test]
    fn client_id_all_printable_ascii() {
        // Every printable ASCII character from 0x20 to 0x7E.
        let all_printable: String = (0x20u8..=0x7Eu8).map(|b| b as char).collect();
        assert!(is_valid_client_id(&all_printable));
    }

    #[test]
    fn client_id_null_byte_rejected() {
        assert!(!is_valid_client_id("client\0id"));
    }

    #[test]
    fn client_id_control_char_rejected() {
        assert!(!is_valid_client_id("client\x01id"));
        assert!(!is_valid_client_id("client\nid"));
        assert!(!is_valid_client_id("client\tid"));
    }

    #[test]
    fn client_id_del_rejected() {
        // 0x7F (DEL) is not printable ASCII.
        assert!(!is_valid_client_id("client\x7Fid"));
    }

    #[test]
    fn client_id_non_ascii_rejected() {
        assert!(!is_valid_client_id("clïent"));
    }

    #[test]
    fn client_id_single_char() {
        assert!(is_valid_client_id("x"));
    }

    #[test]
    fn client_id_single_space() {
        assert!(is_valid_client_id(" "));
    }

    // --- HTTPS URL Validation ---

    #[test]
    fn https_url_valid() {
        assert!(is_https_url("https://example.com"));
        assert!(is_https_url("https://example.com/path?query=1"));
    }

    #[test]
    fn https_url_rejects_http() {
        assert!(!is_https_url("http://example.com"));
    }

    #[test]
    fn https_url_rejects_empty() {
        assert!(!is_https_url(""));
    }

    #[test]
    fn https_url_rejects_no_scheme() {
        assert!(!is_https_url("example.com"));
    }

    // --- Email Validation ---

    #[test]
    fn email_valid_simple() {
        assert!(is_valid_email("user@example.com"));
    }

    #[test]
    fn email_valid_with_subdomain() {
        assert!(is_valid_email("user@mail.example.com"));
    }

    #[test]
    fn email_valid_with_plus() {
        assert!(is_valid_email("user+tag@example.com"));
    }

    #[test]
    fn email_valid_with_dots_in_local() {
        assert!(is_valid_email("first.last@example.com"));
    }

    #[test]
    fn email_empty() {
        assert!(!is_valid_email(""));
    }

    #[test]
    fn email_no_at() {
        assert!(!is_valid_email("userexample.com"));
    }

    #[test]
    fn email_double_at() {
        assert!(!is_valid_email("user@@example.com"));
    }

    #[test]
    fn email_no_domain() {
        assert!(!is_valid_email("user@"));
    }

    #[test]
    fn email_no_local() {
        assert!(!is_valid_email("@example.com"));
    }

    #[test]
    fn email_no_tld_dot() {
        assert!(!is_valid_email("user@localhost"));
    }

    #[test]
    fn email_consecutive_dots_local() {
        assert!(!is_valid_email("user..name@example.com"));
    }

    #[test]
    fn email_consecutive_dots_domain() {
        assert!(!is_valid_email("user@example..com"));
    }

    #[test]
    fn email_leading_dot_local() {
        assert!(!is_valid_email(".user@example.com"));
    }

    #[test]
    fn email_trailing_dot_local() {
        assert!(!is_valid_email("user.@example.com"));
    }

    #[test]
    fn email_leading_dot_domain() {
        assert!(!is_valid_email("user@.example.com"));
    }

    #[test]
    fn email_domain_label_leading_hyphen() {
        assert!(!is_valid_email("user@-example.com"));
    }

    #[test]
    fn email_domain_label_trailing_hyphen() {
        assert!(!is_valid_email("user@example-.com"));
    }

    #[test]
    fn email_with_space() {
        assert!(!is_valid_email("user @example.com"));
    }

    #[test]
    fn email_with_null() {
        assert!(!is_valid_email("user\0@example.com"));
    }

    #[test]
    fn email_exceeds_max_length() {
        let local = "a".repeat(64);
        let domain = format!("{}.com", "b".repeat(MAX_EMAIL_LEN));
        let email = format!("{local}@{domain}");
        assert!(!is_valid_email(&email));
    }

    #[test]
    fn email_local_exceeds_64_bytes() {
        let local = "a".repeat(65);
        let email = format!("{local}@example.com");
        assert!(!is_valid_email(&email));
    }

    #[test]
    fn email_non_ascii_rejected() {
        assert!(!is_valid_email("üser@example.com"));
    }

    // --- Password Strength Validation ---

    #[test]
    fn password_strength_valid() {
        let rules = PasswordRules::default();
        assert!(validate_password_strength("MyP@ssw0rd", &rules).is_ok());
    }

    #[test]
    fn password_strength_too_short() {
        let rules = PasswordRules::default();
        let errors = validate_password_strength("Ab1!", &rules).unwrap_err();
        assert!(errors.iter().any(|e| e.contains("minimum length")));
    }

    #[test]
    fn password_strength_no_uppercase() {
        let rules = PasswordRules::default();
        let errors = validate_password_strength("myp@ssw0rd", &rules).unwrap_err();
        assert!(errors.iter().any(|e| e.contains("uppercase")));
    }

    #[test]
    fn password_strength_no_lowercase() {
        let rules = PasswordRules::default();
        let errors = validate_password_strength("MYP@SSW0RD", &rules).unwrap_err();
        assert!(errors.iter().any(|e| e.contains("lowercase")));
    }

    #[test]
    fn password_strength_no_digit() {
        let rules = PasswordRules::default();
        let errors = validate_password_strength("MyP@ssword", &rules).unwrap_err();
        assert!(errors.iter().any(|e| e.contains("digit")));
    }

    #[test]
    fn password_strength_no_special() {
        let rules = PasswordRules::default();
        let errors = validate_password_strength("MyPassw0rd", &rules).unwrap_err();
        assert!(errors.iter().any(|e| e.contains("special")));
    }

    #[test]
    fn password_strength_multiple_failures() {
        let rules = PasswordRules::default();
        let errors = validate_password_strength("short", &rules).unwrap_err();
        assert!(errors.len() >= 3);
    }

    #[test]
    fn password_strength_custom_min_length() {
        let rules = PasswordRules::new().with_min_length(12);
        let errors = validate_password_strength("MyP@ssw0rd", &rules).unwrap_err();
        assert!(errors.iter().any(|e| e.contains("minimum length")));
    }

    #[test]
    fn password_strength_relaxed_rules() {
        let rules = PasswordRules::new()
            .with_require_uppercase(false)
            .with_require_special(false);
        assert!(validate_password_strength("password1", &rules).is_ok());
    }

    #[test]
    fn password_rules_builder() {
        let rules = PasswordRules::new().with_min_length(16);
        assert_eq!(rules.min_length(), 16);
    }
}