footing 0.1.3

Feature-gated foundations for Rust backend services
Documentation
//! Validated local role and scope requirements.

use serde::{Deserialize, Deserializer, Serialize};

use super::{
    error::PermissionError,
    model::{Principal, normalize_policy_authorities},
};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
/// Kind of principal authority evaluated by a local requirement.
pub enum AuthorityKind {
    /// Principal role.
    Role,
    /// Principal scope, including wildcard scope matching.
    Scope,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
/// Match mode used by a principal authority requirement.
pub enum RequirementMatch {
    /// At least one configured authority must match.
    Any,
    /// Every configured authority must match.
    All,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[non_exhaustive]
/// A validated local role or scope requirement.
pub struct PrincipalRequirement {
    authority_kind: AuthorityKind,
    match_mode: RequirementMatch,
    authorities: Vec<String>,
}

impl PrincipalRequirement {
    /// Creates a validated requirement.
    pub fn new(
        authority_kind: AuthorityKind,
        match_mode: RequirementMatch,
        authorities: impl IntoIterator<Item = impl Into<String>>,
    ) -> Result<Self, PermissionError> {
        let name = match authority_kind {
            AuthorityKind::Role => "role requirement",
            AuthorityKind::Scope => "scope requirement",
        };
        Ok(Self {
            authority_kind,
            match_mode,
            authorities: normalize_policy_authorities(authorities, name)?,
        })
    }

    /// Requires one role.
    pub fn role(role: impl Into<String>) -> Result<Self, PermissionError> {
        Self::new(AuthorityKind::Role, RequirementMatch::All, [role])
    }

    /// Requires at least one role.
    pub fn any_roles(
        roles: impl IntoIterator<Item = impl Into<String>>,
    ) -> Result<Self, PermissionError> {
        Self::new(AuthorityKind::Role, RequirementMatch::Any, roles)
    }

    /// Requires every role.
    pub fn all_roles(
        roles: impl IntoIterator<Item = impl Into<String>>,
    ) -> Result<Self, PermissionError> {
        Self::new(AuthorityKind::Role, RequirementMatch::All, roles)
    }

    /// Requires one scope.
    pub fn scope(scope: impl Into<String>) -> Result<Self, PermissionError> {
        Self::new(AuthorityKind::Scope, RequirementMatch::All, [scope])
    }

    /// Requires at least one scope.
    pub fn any_scopes(
        scopes: impl IntoIterator<Item = impl Into<String>>,
    ) -> Result<Self, PermissionError> {
        Self::new(AuthorityKind::Scope, RequirementMatch::Any, scopes)
    }

    /// Requires every scope.
    pub fn all_scopes(
        scopes: impl IntoIterator<Item = impl Into<String>>,
    ) -> Result<Self, PermissionError> {
        Self::new(AuthorityKind::Scope, RequirementMatch::All, scopes)
    }

    #[must_use]
    /// Returns the authority kind.
    pub const fn authority_kind(&self) -> AuthorityKind {
        self.authority_kind
    }

    #[must_use]
    /// Returns the match mode.
    pub const fn match_mode(&self) -> RequirementMatch {
        self.match_mode
    }

    #[must_use]
    /// Returns the normalized authorities.
    pub fn authorities(&self) -> &[String] {
        &self.authorities
    }

    /// Evaluates the requirement against a principal.
    pub fn check(&self, principal: &Principal) -> Result<(), PermissionError> {
        let matches = match (self.authority_kind, self.match_mode) {
            (AuthorityKind::Role, RequirementMatch::Any) => {
                principal.has_any_role(self.authorities.iter().map(String::as_str))
            }
            (AuthorityKind::Role, RequirementMatch::All) => {
                principal.has_all_roles(self.authorities.iter().map(String::as_str))
            }
            (AuthorityKind::Scope, RequirementMatch::Any) => {
                principal.has_any_scope(self.authorities.iter().map(String::as_str))
            }
            (AuthorityKind::Scope, RequirementMatch::All) => {
                principal.has_all_scopes(self.authorities.iter().map(String::as_str))
            }
        };
        if matches {
            Ok(())
        } else {
            Err(PermissionError::Denied)
        }
    }
}

impl<'de> Deserialize<'de> for PrincipalRequirement {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        #[derive(Deserialize)]
        struct RequirementWire {
            authority_kind: AuthorityKind,
            match_mode: RequirementMatch,
            authorities: Vec<String>,
        }

        let wire = RequirementWire::deserialize(deserializer)?;
        Self::new(wire.authority_kind, wire.match_mode, wire.authorities)
            .map_err(serde::de::Error::custom)
    }
}