wisegate-core 0.13.0

//! Authentication module for HTTP Basic Authentication (RFC 7617) and Bearer Token (RFC 6750).
//!
//! Provides credential storage, verification, and HTTP header parsing for
//! implementing Basic Authentication and Bearer Token authentication in WiseGate.

pub mod hash;

use base64::{Engine, engine::general_purpose::STANDARD};
use std::sync::{Arc, LazyLock};
use tokio::sync::Semaphore;

// Process-wide: permissive requests without an attributable IP are also bounded.
static AUTH_SLOTS: LazyLock<Arc<Semaphore>> = LazyLock::new(|| Arc::new(Semaphore::new(4)));

#[derive(Debug)]
pub(crate) struct AuthCheckUnavailable;

/// Keep password hashing off the async executor, with no unbounded waiting queue.
pub(crate) async fn check_basic_auth_bounded(
    auth_header: Option<&str>,
    credentials: &Credentials,
) -> Result<bool, AuthCheckUnavailable> {
    check_basic_auth_with_slots(auth_header, credentials, &AUTH_SLOTS).await
}

async fn check_basic_auth_with_slots(
    auth_header: Option<&str>,
    credentials: &Credentials,
    slots: &Arc<Semaphore>,
) -> Result<bool, AuthCheckUnavailable> {
    if credentials.is_empty() {
        return Ok(true);
    }
    let Some(header) = auth_header.filter(|h| h.starts_with("Basic ")) else {
        return Ok(false);
    };
    let permit = slots
        .clone()
        .try_acquire_owned()
        .map_err(|_| AuthCheckUnavailable)?;
    let credentials = credentials.clone();
    let header = header.to_owned();
    run_auth_check(permit, move || credentials.verify(&header)).await
}

async fn run_auth_check(
    permit: tokio::sync::OwnedSemaphorePermit,
    check: impl FnOnce() -> bool + Send + 'static,
) -> Result<bool, AuthCheckUnavailable> {
    tokio::task::spawn_blocking(move || {
        // Cancellation of the requesting task must not release the slot while
        // a non-cancellable hash check is still running.
        let _permit = permit;
        check()
    })
    .await
    .map_err(|_| AuthCheckUnavailable)
}

/// A single credential entry (username and password/hash).
#[derive(Debug, Clone)]
pub struct Credential {
    username: String,
    password: String,
}

impl Credential {
    /// Creates a new credential from username and password/hash.
    pub fn new(username: String, password: String) -> Self {
        Self { username, password }
    }

    /// Parses a credential string in the format "username:password".
    ///
    /// # Errors
    ///
    /// Returns `None` if the string doesn't contain a colon or has an empty username.
    pub fn parse(value: &str) -> Option<Self> {
        let (user, pass) = value.split_once(':')?;
        if user.is_empty() {
            return None;
        }
        Some(Self::new(user.to_string(), pass.to_string()))
    }

    /// Returns the username.
    pub fn username(&self) -> &str {
        &self.username
    }

    /// Returns the password/hash.
    pub fn password(&self) -> &str {
        &self.password
    }
}

/// Stores credentials for authentication.
#[derive(Debug, Clone)]
pub struct Credentials {
    entries: Vec<Credential>,
}

impl Credentials {
    /// Creates a new empty credentials store.
    pub fn new() -> Self {
        Self {
            entries: Vec::new(),
        }
    }

    /// Creates credentials from a slice of credential entries.
    pub fn from_entries(entries: Vec<Credential>) -> Self {
        Self { entries }
    }

    /// Returns true if no credentials are stored.
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

    /// Returns the number of stored credentials.
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    /// Verifies credentials from an HTTP Authorization header.
    ///
    /// Expects the header value in the format `Basic {base64-encoded-credentials}`
    /// per RFC 7617.
    pub fn verify(&self, auth_header: &str) -> bool {
        let Some(encoded) = auth_header.strip_prefix("Basic ") else {
            return false;
        };

        let Ok(decoded) = STANDARD.decode(encoded.trim()) else {
            return false;
        };

        let Ok(decoded_str) = String::from_utf8(decoded) else {
            return false;
        };

        // RFC 7617: user-id cannot contain colons, password may contain colons
        let Some((user, password)) = decoded_str.split_once(':') else {
            return false;
        };

        self.check(user, password)
    }

    /// Checks if the given username and password match any stored credential.
    /// Uses constant-time comparison to prevent timing attacks.
    fn check(&self, username: &str, password: &str) -> bool {
        let mut found = false;
        for cred in &self.entries {
            // Use constant-time comparison for username to prevent enumeration
            let user_match = hash::constant_time_eq(cred.username.as_bytes(), username.as_bytes());
            // Always verify password to prevent timing leaks
            let pass_match = hash::verify(password, &cred.password);
            if user_match && pass_match {
                found = true;
            }
        }
        found
    }
}

impl Default for Credentials {
    fn default() -> Self {
        Self::new()
    }
}

/// Checks if the request has valid Basic authentication.
///
/// Returns `true` if authentication is successful or not required.
/// Returns `false` if authentication is required but failed.
///
/// # Arguments
///
/// * `auth_header` - The value of the Authorization header, if present.
/// * `credentials` - The credentials to check against.
pub fn check_basic_auth(auth_header: Option<&str>, credentials: &Credentials) -> bool {
    if credentials.is_empty() {
        // No credentials configured, authentication not required
        return true;
    }

    match auth_header {
        Some(header) => credentials.verify(header),
        None => false,
    }
}

/// Checks if the request has a valid Bearer token.
///
/// Returns `true` if authentication is successful or not required.
/// Returns `false` if authentication is required but failed.
///
/// # Arguments
///
/// * `auth_header` - The value of the Authorization header, if present.
/// * `expected_token` - The expected bearer token, if configured.
pub fn check_bearer_token(auth_header: Option<&str>, expected_token: Option<&str>) -> bool {
    let Some(expected) = expected_token else {
        // No token configured, authentication not required
        return true;
    };

    if expected.is_empty() {
        // Empty token means disabled
        return true;
    }

    let Some(header) = auth_header else {
        return false;
    };

    // RFC 6750: auth-scheme is case-insensitive
    let Some(token) = header
        .get(..7)
        .filter(|prefix| prefix.eq_ignore_ascii_case("bearer "))
        .map(|_| &header[7..])
    else {
        return false;
    };

    // Use constant-time comparison to prevent timing attacks
    hash::constant_time_eq(token.trim().as_bytes(), expected.as_bytes())
}

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

    #[tokio::test]
    async fn saturated_auth_rejects_without_waiting() {
        use futures::FutureExt;

        let slots = Arc::new(Semaphore::new(1));
        let _permit = slots.clone().try_acquire_owned().unwrap();
        let credentials = Credentials::from_entries(vec![Credential::new(
            "admin".to_string(),
            "secret".to_string(),
        )]);
        let header = format!("Basic {}", STANDARD.encode("admin:secret"));
        assert!(
            check_basic_auth_with_slots(Some(&header), &credentials, &slots)
                .now_or_never()
                .expect("saturated authentication must not queue")
                .is_err()
        );
    }

    #[tokio::test(flavor = "current_thread")]
    async fn blocking_auth_keeps_its_slot_after_request_cancellation() {
        let slots = Arc::new(Semaphore::new(1));
        let permit = slots.clone().try_acquire_owned().unwrap();
        let (started_tx, started_rx) = tokio::sync::oneshot::channel();
        let (finish_tx, finish_rx) = std::sync::mpsc::channel();
        let task = tokio::spawn(run_auth_check(permit, move || {
            started_tx.send(()).unwrap();
            // Bounded even if a regression makes the assertions below panic.
            finish_rx
                .recv_timeout(std::time::Duration::from_secs(2))
                .unwrap();
            true
        }));

        // A blocking call on this single-thread executor would prevent progress.
        started_rx.await.unwrap();
        task.abort();
        assert!(task.await.unwrap_err().is_cancelled());
        assert!(slots.clone().try_acquire_owned().is_err());
        finish_tx.send(()).unwrap();
        let released =
            tokio::time::timeout(std::time::Duration::from_secs(2), slots.acquire_owned())
                .await
                .expect("slot must be released when hashing finishes")
                .unwrap();
        drop(released);
    }

    #[tokio::test]
    async fn bounded_basic_auth_preserves_valid_and_invalid_credentials() {
        let credentials = Credentials::from_entries(vec![Credential::new(
            "admin".to_string(),
            "secret".to_string(),
        )]);
        let valid = format!("Basic {}", STANDARD.encode("admin:secret"));
        let invalid = format!("Basic {}", STANDARD.encode("admin:wrong"));
        assert!(
            check_basic_auth_bounded(Some(&valid), &credentials)
                .await
                .unwrap()
        );
        assert!(
            !check_basic_auth_bounded(Some(&invalid), &credentials)
                .await
                .unwrap()
        );
        assert!(!check_basic_auth_bounded(None, &credentials).await.unwrap());
    }

    #[test]
    fn test_credential_parse_valid() {
        let cred = Credential::parse("admin:secret").unwrap();
        assert_eq!(cred.username(), "admin");
        assert_eq!(cred.password(), "secret");
    }

    #[test]
    fn test_credential_parse_with_colon_in_password() {
        let cred = Credential::parse("admin:sec:ret").unwrap();
        assert_eq!(cred.username(), "admin");
        assert_eq!(cred.password(), "sec:ret");
    }

    #[test]
    fn test_credential_parse_no_colon() {
        assert!(Credential::parse("invalid").is_none());
    }

    #[test]
    fn test_credential_parse_empty_user() {
        assert!(Credential::parse(":password").is_none());
    }

    #[test]
    fn test_credentials_empty() {
        let creds = Credentials::new();
        assert!(creds.is_empty());
        assert_eq!(creds.len(), 0);
    }

    #[test]
    fn test_credentials_from_entries() {
        let entries = vec![
            Credential::new("admin".to_string(), "secret".to_string()),
            Credential::new("user".to_string(), "pass".to_string()),
        ];
        let creds = Credentials::from_entries(entries);
        assert!(!creds.is_empty());
        assert_eq!(creds.len(), 2);
    }

    #[test]
    fn test_verify_plain_text() {
        let creds = Credentials::from_entries(vec![Credential::new(
            "admin".to_string(),
            "secret".to_string(),
        )]);

        let header = format!("Basic {}", STANDARD.encode("admin:secret"));
        assert!(creds.verify(&header));
    }

    #[test]
    fn test_verify_wrong_password() {
        let creds = Credentials::from_entries(vec![Credential::new(
            "admin".to_string(),
            "secret".to_string(),
        )]);

        let header = format!("Basic {}", STANDARD.encode("admin:wrong"));
        assert!(!creds.verify(&header));
    }

    #[test]
    fn test_verify_wrong_user() {
        let creds = Credentials::from_entries(vec![Credential::new(
            "admin".to_string(),
            "secret".to_string(),
        )]);

        let header = format!("Basic {}", STANDARD.encode("wrong:secret"));
        assert!(!creds.verify(&header));
    }

    #[test]
    fn test_verify_bcrypt() {
        // bcrypt hash for "password"
        let hash = "$2y$05$bvIG6Nmid91Mu9RcmmWZfO5HJIMCT8riNW0hEp8f6/FuA2/mHZFpe";
        let creds =
            Credentials::from_entries(vec![Credential::new("user".to_string(), hash.to_string())]);

        let header = format!("Basic {}", STANDARD.encode("user:password"));
        assert!(creds.verify(&header));
    }

    #[test]
    fn test_verify_sha1() {
        // SHA1 hash for "password"
        let hash = "{SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g=";
        let creds =
            Credentials::from_entries(vec![Credential::new("user".to_string(), hash.to_string())]);

        let header = format!("Basic {}", STANDARD.encode("user:password"));
        assert!(creds.verify(&header));
    }

    #[test]
    fn test_verify_apr1() {
        // APR1 hash for "password"
        let hash = "$apr1$lZL6V/ci$eIMz/iKDkbtys/uU7LEK00";
        let creds =
            Credentials::from_entries(vec![Credential::new("user".to_string(), hash.to_string())]);

        let header = format!("Basic {}", STANDARD.encode("user:password"));
        assert!(creds.verify(&header));
    }

    #[test]
    fn test_verify_multiple_credentials() {
        let creds = Credentials::from_entries(vec![
            Credential::new("admin".to_string(), "admin123".to_string()),
            Credential::new("user1".to_string(), "pass1".to_string()),
            Credential::new("user2".to_string(), "pass2".to_string()),
        ]);

        assert!(creds.verify(&format!("Basic {}", STANDARD.encode("admin:admin123"))));
        assert!(creds.verify(&format!("Basic {}", STANDARD.encode("user1:pass1"))));
        assert!(creds.verify(&format!("Basic {}", STANDARD.encode("user2:pass2"))));
        assert!(!creds.verify(&format!("Basic {}", STANDARD.encode("unknown:pass"))));
    }

    #[test]
    fn test_verify_invalid_base64() {
        let creds = Credentials::from_entries(vec![Credential::new(
            "admin".to_string(),
            "secret".to_string(),
        )]);
        assert!(!creds.verify("Basic not-valid-base64!!!"));
    }

    #[test]
    fn test_verify_non_basic_auth() {
        let creds = Credentials::from_entries(vec![Credential::new(
            "admin".to_string(),
            "secret".to_string(),
        )]);
        assert!(!creds.verify("Bearer some-token"));
        assert!(!creds.verify("bearer some-token"));
    }

    #[test]
    fn test_verify_missing_colon_in_decoded() {
        let creds = Credentials::from_entries(vec![Credential::new(
            "admin".to_string(),
            "secret".to_string(),
        )]);
        let header = format!("Basic {}", STANDARD.encode("no-colon-here"));
        assert!(!creds.verify(&header));
    }

    #[test]
    fn test_check_basic_auth_no_credentials() {
        let creds = Credentials::new();
        // No credentials = authentication not required
        assert!(check_basic_auth(None, &creds));
        assert!(check_basic_auth(Some("Basic anything"), &creds));
    }

    #[test]
    fn test_check_basic_auth_with_credentials() {
        let creds = Credentials::from_entries(vec![Credential::new(
            "admin".to_string(),
            "secret".to_string(),
        )]);

        // No header = fail
        assert!(!check_basic_auth(None, &creds));

        // Valid header = success
        let valid_header = format!("Basic {}", STANDARD.encode("admin:secret"));
        assert!(check_basic_auth(Some(&valid_header), &creds));

        // Invalid header = fail
        let invalid_header = format!("Basic {}", STANDARD.encode("admin:wrong"));
        assert!(!check_basic_auth(Some(&invalid_header), &creds));
    }

    // ===========================================
    // Bearer token tests
    // ===========================================

    #[test]
    fn test_check_bearer_token_no_token_configured() {
        // No token configured = always pass
        assert!(check_bearer_token(None, None));
        assert!(check_bearer_token(Some("Bearer anything"), None));
    }

    #[test]
    fn test_check_bearer_token_empty_token() {
        // Empty token = disabled
        assert!(check_bearer_token(None, Some("")));
        assert!(check_bearer_token(Some("Bearer anything"), Some("")));
    }

    #[test]
    fn test_check_bearer_token_valid() {
        let token = "my-secret-token";
        let header = "Bearer my-secret-token";
        assert!(check_bearer_token(Some(header), Some(token)));
    }

    #[test]
    fn test_check_bearer_token_valid_with_whitespace() {
        let token = "my-secret-token";
        let header = "Bearer my-secret-token ";
        assert!(check_bearer_token(Some(header), Some(token)));
    }

    #[test]
    fn test_check_bearer_token_invalid() {
        let token = "my-secret-token";
        let header = "Bearer wrong-token";
        assert!(!check_bearer_token(Some(header), Some(token)));
    }

    #[test]
    fn test_check_bearer_token_no_header() {
        let token = "my-secret-token";
        assert!(!check_bearer_token(None, Some(token)));
    }

    #[test]
    fn test_check_bearer_token_basic_auth_header() {
        // Basic auth header should not work for bearer
        let token = "my-secret-token";
        let header = format!("Basic {}", STANDARD.encode("user:pass"));
        assert!(!check_bearer_token(Some(&header), Some(token)));
    }

    #[test]
    fn test_check_bearer_token_value_case_sensitive() {
        let token = "MySecretToken";
        assert!(check_bearer_token(
            Some("Bearer MySecretToken"),
            Some(token)
        ));
        assert!(!check_bearer_token(
            Some("Bearer mysecrettoken"),
            Some(token)
        ));
    }

    #[test]
    fn test_check_bearer_token_prefix_case_insensitive() {
        // RFC 6750: auth-scheme is case-insensitive
        let token = "my-secret-token";
        assert!(check_bearer_token(
            Some("bearer my-secret-token"),
            Some(token)
        ));
        assert!(check_bearer_token(
            Some("BEARER my-secret-token"),
            Some(token)
        ));
        assert!(check_bearer_token(
            Some("Bearer my-secret-token"),
            Some(token)
        ));
    }
}