oxideshield_guard/

licensed.rs

//! Licensed guard infrastructure for OxideShield.
//!
//! This module provides the infrastructure for license-gated guards,
//! including the `LicensedGuard` trait and guard registry system.
//!
//! ## Architecture
//!
//! Commercial guards implement `LicensedGuard` which adds license validation
//! on top of the base `Guard` trait. The `GuardRegistry` allows dynamic
//! registration of guards, enabling plugin-style commercial extensions.
//!
//! ## License Tiers
//!
//! - **Community**: Basic guards (Pattern, Length, Encoding, Perplexity, PII, Toxicity)
//! - **Professional**: + SemanticSimilarityGuard, MLClassifierGuard, Scanner, MultiLayerDefense
//! - **Enterprise**: + Custom guards, private models, dashboard access
//!
//! ## Usage
//!
//! ```rust,ignore
//! use oxideshield_guard::licensed::{LicensedGuard, GuardRegistry};
//! use oxide_license::{LicenseValidator, Feature};
//!
//! // Create a registry
//! let registry = GuardRegistry::new();
//!
//! // Register a licensed guard (from commercial module)
//! registry.register("semantic", SemanticGuardFactory::new());
//!
//! // Create guard with license validation
//! let validator = LicenseValidator::new()?;
//! let guard = registry.create("semantic", &validator).await?;
//! ```

use crate::guard::{Guard, GuardCheckResult};
use std::collections::HashMap;
use std::sync::Arc;

use oxide_license::{Feature, LicenseError, LicenseValidator};

/// Error types for licensed guard operations.
#[derive(Debug, thiserror::Error)]
pub enum LicensedGuardError {
    /// The required feature is not licensed.
    #[error("Feature '{feature}' requires {required_tier} license (current: {current_tier})")]
    FeatureNotLicensed {
        feature: String,
        required_tier: String,
        current_tier: String,
    },

    /// License validation failed.
    #[error("License validation failed: {0}")]
    ValidationFailed(String),

    /// Guard not found in registry.
    #[error("Guard '{0}' not found in registry")]
    GuardNotFound(String),

    /// Guard creation failed.
    #[error("Guard creation failed: {0}")]
    CreationFailed(String),

    /// Configuration error.
    #[error("Configuration error: {0}")]
    ConfigError(String),
}

impl From<LicenseError> for LicensedGuardError {
    fn from(err: LicenseError) -> Self {
        match err {
            LicenseError::FeatureNotLicensed {
                feature,
                required_tier,
                current_tier,
            } => LicensedGuardError::FeatureNotLicensed {
                feature,
                required_tier,
                current_tier,
            },
            _ => LicensedGuardError::ValidationFailed(err.to_string()),
        }
    }
}

/// Result type for licensed guard operations.
pub type LicensedGuardResult<T> = std::result::Result<T, LicensedGuardError>;

/// Guard that requires license validation.
///
/// This trait extends the base `Guard` trait with license requirements.
/// Commercial guards implement this trait to enable license-gated access.
pub trait LicensedGuard: Guard {
    /// Returns the feature required to use this guard.
    fn required_feature(&self) -> &str;

    /// Returns the license tier required for this guard.
    fn required_tier(&self) -> &str;

    /// Returns true if this guard is available in the Community tier.
    fn is_community(&self) -> bool {
        false
    }
}

/// Wrapper for a guard that performs license checks.
///
/// This wrapper validates the license before each guard check,
/// returning an error if the required feature is not licensed.
pub struct LicenseCheckedGuard<G: Guard> {
    inner: G,
    feature_name: String,
    tier_name: String,
    validator: Arc<LicenseValidator>,
}

impl<G: Guard> LicenseCheckedGuard<G> {
    /// Creates a new license-checked guard wrapper.
    pub fn new(
        inner: G,
        feature_name: impl Into<String>,
        tier_name: impl Into<String>,
        validator: Arc<LicenseValidator>,
    ) -> Self {
        Self {
            inner,
            feature_name: feature_name.into(),
            tier_name: tier_name.into(),
            validator,
        }
    }

    /// Returns the inner guard.
    pub fn inner(&self) -> &G {
        &self.inner
    }

    /// Returns the feature name.
    pub fn feature_name(&self) -> &str {
        &self.feature_name
    }

    /// Returns the tier name.
    pub fn tier_name(&self) -> &str {
        &self.tier_name
    }

    /// Validates the license for this guard.
    pub async fn validate_license(&self) -> LicensedGuardResult<()> {
        let feature = match self.feature_name.as_str() {
            "semantic_guard" => Feature::SemanticGuard,
            "ml_classifier" => Feature::MlClassifier,
            "scanner" | "advanced_probes" => Feature::Scanner,
            "multi_layer_defense" => Feature::MultiLayerDefense,
            "telemetry" => Feature::Telemetry,
            "bundled_embeddings" => Feature::BundledEmbeddings,
            "compliance_reports" => Feature::ComplianceReports,
            "threat_intel" => Feature::ThreatIntel,
            "dashboard" => Feature::Dashboard,
            "api_access" => Feature::ApiAccess,
            "proxy_basic" | "proxy_gateway" => Feature::ProxyBasic,
            "webhook_alerts" => Feature::WebhookAlerts,
            "rate_limiting" => Feature::RateLimiting,
            "streaming_guards" => Feature::StreamingGuards,
            "custom_guards" => Feature::CustomGuards,
            "private_models" => Feature::PrivateModels,
            "sso_saml" => Feature::SsoSaml,
            "embedding_privacy" => Feature::EmbeddingPrivacy,
            _ => {
                // Unknown feature - allow for community features
                return Ok(());
            }
        };

        self.validator.require_feature(feature).await?;
        Ok(())
    }
}

impl<G: Guard> Guard for LicenseCheckedGuard<G> {
    fn name(&self) -> &str {
        self.inner.name()
    }

    fn check(&self, content: &str) -> GuardCheckResult {
        // Note: License validation should be done async before calling check()
        // This sync method assumes validation was already performed
        self.inner.check(content)
    }

    fn action(&self) -> crate::guard::GuardAction {
        self.inner.action()
    }

    fn severity_threshold(&self) -> oxideshield_core::Severity {
        self.inner.severity_threshold()
    }
}

impl<G: Guard> LicensedGuard for LicenseCheckedGuard<G> {
    fn required_feature(&self) -> &str {
        &self.feature_name
    }

    fn required_tier(&self) -> &str {
        &self.tier_name
    }
}

/// Factory trait for creating guards.
///
/// This trait enables dynamic guard creation through the registry.
/// Each guard type provides a factory that can create instances.
#[async_trait::async_trait]
pub trait GuardFactory: Send + Sync {
    /// The type of guard this factory creates.
    type Guard: Guard + 'static;

    /// Creates a new guard instance.
    async fn create(&self, config: &GuardFactoryConfig) -> LicensedGuardResult<Self::Guard>;

    /// Returns the name of the guard type.
    fn guard_type(&self) -> &str;

    /// Returns the required feature for this guard.
    fn required_feature(&self) -> Option<&str>;

    /// Returns the required tier for this guard.
    fn required_tier(&self) -> &str;
}

/// Configuration for guard factory.
#[derive(Debug, Clone, Default)]
pub struct GuardFactoryConfig {
    /// Guard name.
    pub name: String,
    /// Additional configuration parameters.
    pub params: HashMap<String, String>,
    /// Whether to skip license validation.
    pub skip_license_check: bool,
}

impl GuardFactoryConfig {
    /// Creates a new factory config with a name.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            params: HashMap::new(),
            skip_license_check: false,
        }
    }

    /// Adds a parameter.
    pub fn with_param(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.params.insert(key.into(), value.into());
        self
    }

    /// Sets whether to skip license validation.
    pub fn skip_license_check(mut self, skip: bool) -> Self {
        self.skip_license_check = skip;
        self
    }
}

/// Registry for dynamically registering and creating guards.
///
/// The registry enables a plugin architecture where commercial
/// guards can be registered at runtime.
pub struct GuardRegistry {
    factories: HashMap<String, Arc<dyn DynGuardFactory>>,
}

/// Type-erased guard factory for the registry.
#[async_trait::async_trait]
pub trait DynGuardFactory: Send + Sync {
    /// Creates a boxed guard.
    async fn create_boxed(
        &self,
        config: &GuardFactoryConfig,
    ) -> LicensedGuardResult<Box<dyn Guard>>;

    /// Returns the guard type name.
    fn guard_type(&self) -> &str;

    /// Returns the required feature.
    fn required_feature(&self) -> Option<&str>;

    /// Returns the required tier.
    fn required_tier(&self) -> &str;
}

#[async_trait::async_trait]
impl<F: GuardFactory> DynGuardFactory for F {
    async fn create_boxed(
        &self,
        config: &GuardFactoryConfig,
    ) -> LicensedGuardResult<Box<dyn Guard>> {
        let guard = self.create(config).await?;
        Ok(Box::new(guard))
    }

    fn guard_type(&self) -> &str {
        GuardFactory::guard_type(self)
    }

    fn required_feature(&self) -> Option<&str> {
        GuardFactory::required_feature(self)
    }

    fn required_tier(&self) -> &str {
        GuardFactory::required_tier(self)
    }
}

impl GuardRegistry {
    /// Creates a new empty registry.
    pub fn new() -> Self {
        Self {
            factories: HashMap::new(),
        }
    }

    /// Creates a registry with built-in community guards.
    pub fn with_builtins() -> Self {
        // Built-in guards are registered here
        // (Commercial guards would be registered by external modules)
        Self::new()
    }

    /// Registers a guard factory.
    pub fn register<F: DynGuardFactory + 'static>(&mut self, name: &str, factory: F) {
        self.factories.insert(name.to_string(), Arc::new(factory));
    }

    /// Returns true if a guard type is registered.
    pub fn has(&self, name: &str) -> bool {
        self.factories.contains_key(name)
    }

    /// Lists all registered guard types.
    pub fn list(&self) -> Vec<&str> {
        self.factories.keys().map(|s| s.as_str()).collect()
    }

    /// Gets information about a registered guard type.
    pub fn info(&self, name: &str) -> Option<GuardInfo> {
        self.factories.get(name).map(|f| GuardInfo {
            name: f.guard_type().to_string(),
            required_feature: f.required_feature().map(|s| s.to_string()),
            required_tier: f.required_tier().to_string(),
        })
    }

    /// Creates a guard instance.
    pub async fn create(
        &self,
        name: &str,
        config: &GuardFactoryConfig,
    ) -> LicensedGuardResult<Box<dyn Guard>> {
        let factory = self
            .factories
            .get(name)
            .ok_or_else(|| LicensedGuardError::GuardNotFound(name.to_string()))?;

        factory.create_boxed(config).await
    }

    /// Creates a guard instance with license validation.
    pub async fn create_licensed(
        &self,
        name: &str,
        config: &GuardFactoryConfig,
        validator: &LicenseValidator,
    ) -> LicensedGuardResult<Box<dyn Guard>> {
        let factory = self
            .factories
            .get(name)
            .ok_or_else(|| LicensedGuardError::GuardNotFound(name.to_string()))?;

        // Validate license if required
        if !config.skip_license_check {
            if let Some(feature_name) = factory.required_feature() {
                let feature = match feature_name {
                    "semantic_guard" => Feature::SemanticGuard,
                    "ml_classifier" => Feature::MlClassifier,
                    "scanner" | "advanced_probes" => Feature::Scanner,
                    "multi_layer_defense" => Feature::MultiLayerDefense,
                    "telemetry" => Feature::Telemetry,
                    "bundled_embeddings" => Feature::BundledEmbeddings,
                    "compliance_reports" => Feature::ComplianceReports,
                    "threat_intel" => Feature::ThreatIntel,
                    "dashboard" => Feature::Dashboard,
                    "api_access" => Feature::ApiAccess,
                    "proxy_basic" | "proxy_gateway" => Feature::ProxyBasic,
                    "embedding_privacy" => Feature::EmbeddingPrivacy,
                    _ => {
                        // Unknown feature - skip validation
                        return factory.create_boxed(config).await;
                    }
                };
                validator.require_feature(feature).await?;
            }
        }

        factory.create_boxed(config).await
    }
}

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

/// Information about a registered guard type.
#[derive(Debug, Clone)]
pub struct GuardInfo {
    /// Guard type name.
    pub name: String,
    /// Required feature (None for community guards).
    pub required_feature: Option<String>,
    /// Required license tier.
    pub required_tier: String,
}

/// List of guards and their license requirements.
///
/// This is used for documentation and license validation.
pub const GUARD_LICENSE_REQUIREMENTS: &[(&str, &str, &str)] = &[
    // (Guard name, Required feature, Required tier)
    // Community guards (no feature required)
    ("PatternGuard", "", "Community"),
    ("LengthGuard", "", "Community"),
    ("EncodingGuard", "", "Community"),
    ("PerplexityGuard", "", "Community"),
    ("PIIGuard", "", "Community"),
    ("ToxicityGuard", "", "Community"),
    ("StructuredOutputGuard", "", "Community"),
    // Professional guards
    ("SemanticSimilarityGuard", "semantic_guard", "Professional"),
    ("MLClassifierGuard", "ml_classifier", "Professional"),
    ("AgenticGuard", "agentic_guard", "Professional"),
    ("SwarmGuard", "swarm_guard", "Professional"),
    ("ContainmentPolicy", "containment_policy", "Professional"),
    ("EmbeddingPIIFilter", "embedding_privacy", "Professional"),
    // Enterprise guards (future)
    ("CustomGuard", "custom_guards", "Enterprise"),
];

/// Returns the license requirement for a guard type.
pub fn guard_license_requirement(guard_name: &str) -> Option<(&'static str, &'static str)> {
    GUARD_LICENSE_REQUIREMENTS
        .iter()
        .find(|(name, _, _)| *name == guard_name)
        .map(|(_, feature, tier)| (*feature, *tier))
}

/// Returns true if a guard is available in the Community tier.
pub fn is_community_guard(guard_name: &str) -> bool {
    guard_license_requirement(guard_name)
        .map(|(_, tier)| tier == "Community")
        .unwrap_or(false)
}

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

    #[test]
    fn test_guard_license_requirements() {
        // Community guards
        assert!(is_community_guard("PatternGuard"));
        assert!(is_community_guard("PIIGuard"));
        assert!(is_community_guard("ToxicityGuard"));

        // Professional guards
        assert!(!is_community_guard("SemanticSimilarityGuard"));
        assert!(!is_community_guard("MLClassifierGuard"));

        // Unknown guards
        assert!(!is_community_guard("UnknownGuard"));
    }

    #[test]
    fn test_guard_factory_config() {
        let config = GuardFactoryConfig::new("test")
            .with_param("threshold", "0.8")
            .with_param("action", "block")
            .skip_license_check(true);

        assert_eq!(config.name, "test");
        assert_eq!(config.params.get("threshold"), Some(&"0.8".to_string()));
        assert!(config.skip_license_check);
    }

    #[test]
    fn test_guard_registry() {
        let registry = GuardRegistry::new();
        assert!(!registry.has("semantic"));
        assert!(registry.list().is_empty());
    }

    #[test]
    fn test_licensed_guard_error_display() {
        let err = LicensedGuardError::FeatureNotLicensed {
            feature: "semantic_guard".to_string(),
            required_tier: "Professional".to_string(),
            current_tier: "Community".to_string(),
        };
        assert!(err.to_string().contains("semantic_guard"));
        assert!(err.to_string().contains("Professional"));
    }
}