raxe 0.4.6__py3-none-any.whl

raxe/infrastructure/packs/registry.py

@@ -0,0 +1,381 @@
+"""Pack registry with precedence resolution.
+
+Manages multiple loaded packs and resolves rule conflicts based on precedence.
+Infrastructure layer - coordinates pack loading and rule resolution.
+"""
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from raxe.domain.packs.models import RulePack
+from raxe.domain.rules.models import Rule
+from raxe.infrastructure.packs.loader import PackLoader, PackLoadError
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RegistryConfig:
+    """Configuration for pack registry.
+
+    Attributes:
+        packs_root: Root directory containing pack type subdirectories
+                   (e.g., ~/.raxe/packs/)
+        precedence: Pack type precedence order (highest to lowest priority).
+                   Default: ["custom", "community", "core"]
+                   Custom rules override community, community overrides core.
+        strict: If True, fail on first error. If False, log warnings and continue.
+    """
+    packs_root: Path
+    precedence: list[str] = field(default_factory=lambda: ["custom", "community", "core"])
+    strict: bool = False
+
+    def __post_init__(self) -> None:
+        """Validate configuration after construction."""
+        if not self.precedence:
+            raise ValueError("Precedence list cannot be empty")
+
+        # Ensure packs_root is absolute path
+        if not self.packs_root.is_absolute():
+            self.packs_root = self.packs_root.resolve()
+
+
+class PackRegistry:
+    """Manages loaded rule packs with precedence.
+
+    Handles:
+    - Loading packs from filesystem (core, community, custom)
+    - Precedence resolution (custom > community > core by default)
+    - Rule deduplication (keeps highest precedence version)
+    - Version conflict handling
+
+    Example usage:
+        config = RegistryConfig(packs_root=Path("~/.raxe/packs"))
+        registry = PackRegistry(config)
+        registry.load_all_packs()
+
+        # Get rule (respects precedence)
+        rule = registry.get_rule("pi-001")
+
+        # Get all unique rules
+        all_rules = registry.get_all_rules()
+    """
+
+    def __init__(self, config: RegistryConfig):
+        """Initialize pack registry.
+
+        Args:
+            config: Registry configuration
+        """
+        self.config = config
+        self.loader = PackLoader(strict=config.strict)
+        self.packs: dict[str, RulePack] = {}
+
+    def load_all_packs(self) -> None:
+        """Load all packs from configured root directory.
+
+        Loads latest version from each pack type:
+        - packs_root/core/v*.*.*/pack.yaml
+        - packs_root/community/v*.*.*/pack.yaml
+        - packs_root/custom/*/pack.yaml (any subdirectory)
+
+        Logs summary of loaded packs.
+        """
+        if not self.config.packs_root.exists():
+            logger.warning(
+                f"Packs root directory does not exist: {self.config.packs_root}"
+            )
+            return
+
+        loaded_count = 0
+
+        # Load from each pack type in precedence order
+        for pack_type in self.config.precedence:
+            pack_type_dir = self.config.packs_root / pack_type
+
+            if not pack_type_dir.exists():
+                logger.debug(f"Pack type directory does not exist: {pack_type_dir}")
+                continue
+
+            try:
+                # Load latest version from this type
+                latest_pack = self.loader.load_latest_pack(pack_type_dir)
+
+                if latest_pack:
+                    self.packs[pack_type] = latest_pack
+                    loaded_count += 1
+                    logger.info(
+                        f"Loaded {pack_type} pack: {latest_pack.manifest.versioned_id} "
+                        f"with {len(latest_pack.rules)} rules"
+                    )
+                else:
+                    logger.debug(f"No valid pack found in {pack_type_dir}")
+
+            except PackLoadError as e:
+                logger.error(f"Failed to load {pack_type} pack: {e}")
+                if self.config.strict:
+                    raise
+
+        logger.info(
+            f"Pack registry loaded {loaded_count} packs from {self.config.packs_root}"
+        )
+
+    def load_pack_type(self, pack_type: str) -> RulePack | None:
+        """Load or reload a specific pack type.
+
+        Args:
+            pack_type: Pack type identifier ('core', 'community', 'custom')
+
+        Returns:
+            Loaded pack, or None if not found
+
+        Raises:
+            PackLoadError: If strict mode enabled and load fails
+        """
+        pack_type_dir = self.config.packs_root / pack_type
+
+        if not pack_type_dir.exists():
+            logger.warning(f"Pack type directory not found: {pack_type_dir}")
+            return None
+
+        try:
+            latest_pack = self.loader.load_latest_pack(pack_type_dir)
+
+            if latest_pack:
+                self.packs[pack_type] = latest_pack
+                logger.info(
+                    f"Loaded {pack_type} pack: {latest_pack.manifest.versioned_id}"
+                )
+                return latest_pack
+            else:
+                logger.warning(f"No valid pack found in {pack_type_dir}")
+                return None
+
+        except PackLoadError as e:
+            logger.error(f"Failed to load {pack_type} pack: {e}")
+            if self.config.strict:
+                raise
+            return None
+
+    def get_rule(self, rule_id: str) -> Rule | None:
+        """Get rule by ID, respecting precedence.
+
+        Returns the first matching rule found when searching packs
+        in precedence order. Higher precedence packs override lower.
+
+        Args:
+            rule_id: Rule identifier (e.g., 'pi-001')
+
+        Returns:
+            Rule from highest-precedence pack, or None if not found
+
+        Example:
+            # If custom pack has pi-001 v2.0.0 and core has pi-001 v1.0.0,
+            # returns custom pack's version (custom > core precedence)
+            rule = registry.get_rule("pi-001")
+        """
+        # Check packs in precedence order
+        for pack_type in self.config.precedence:
+            pack = self.packs.get(pack_type)
+            if not pack:
+                continue
+
+            rule = pack.get_rule(rule_id)
+            if rule:
+                logger.debug(
+                    f"Found rule {rule_id} in {pack_type} pack "
+                    f"(version {rule.version})"
+                )
+                return rule
+
+        logger.debug(f"Rule {rule_id} not found in any loaded pack")
+        return None
+
+    def get_rule_versioned(self, rule_id: str, version: str) -> Rule | None:
+        """Get rule by ID and specific version.
+
+        Searches all packs for exact rule_id@version match.
+        Does NOT respect precedence - returns first exact match found.
+
+        Args:
+            rule_id: Rule identifier (e.g., 'pi-001')
+            version: Semantic version (e.g., '0.0.1')
+
+        Returns:
+            Rule with exact version, or None if not found
+        """
+        for pack_type in self.config.precedence:
+            pack = self.packs.get(pack_type)
+            if not pack:
+                continue
+
+            rule = pack.get_rule_versioned(rule_id, version)
+            if rule:
+                logger.debug(
+                    f"Found rule {rule_id}@{version} in {pack_type} pack"
+                )
+                return rule
+
+        logger.debug(f"Rule {rule_id}@{version} not found in any loaded pack")
+        return None
+
+    def get_all_rules(self) -> list[Rule]:
+        """Get all unique rules from all packs.
+
+        Deduplicates by rule_id, keeping highest precedence version.
+        If custom pack has pi-001 and core pack has pi-001, only
+        custom version is returned.
+
+        Returns:
+            List of unique rules (deduplicated by rule_id)
+
+        Example:
+            all_rules = registry.get_all_rules()
+            # Returns: [pi-001 (custom), pi-002 (core), ...]
+        """
+        seen_ids = set()
+        rules = []
+
+        # Iterate in precedence order
+        for pack_type in self.config.precedence:
+            pack = self.packs.get(pack_type)
+            if not pack:
+                continue
+
+            for rule in pack.rules:
+                # Only add if we haven't seen this rule_id yet
+                if rule.rule_id not in seen_ids:
+                    rules.append(rule)
+                    seen_ids.add(rule.rule_id)
+                else:
+                    logger.debug(
+                        f"Skipping duplicate rule {rule.rule_id} from {pack_type} pack "
+                        f"(already loaded from higher precedence pack)"
+                    )
+
+        logger.debug(
+            f"Collected {len(rules)} unique rules from {len(self.packs)} packs"
+        )
+        return rules
+
+    def get_all_rules_with_versions(self) -> list[Rule]:
+        """Get all rules from all packs, including duplicates.
+
+        Does NOT deduplicate. Returns every rule from every pack,
+        so you may get multiple versions of the same rule_id.
+
+        Returns:
+            List of all rules from all packs (may contain duplicate rule_ids)
+
+        Example:
+            all_rules = registry.get_all_rules_with_versions()
+            # Returns: [pi-001@1.0.0 (core), pi-001@2.0.0 (custom), ...]
+        """
+        rules = []
+
+        for pack_type in self.config.precedence:
+            pack = self.packs.get(pack_type)
+            if not pack:
+                continue
+
+            rules.extend(pack.rules)
+
+        logger.debug(
+            f"Collected {len(rules)} rules (including duplicates) from {len(self.packs)} packs"
+        )
+        return rules
+
+    def get_rules_by_family(self, family: str) -> list[Rule]:
+        """Get all unique rules in a specific family.
+
+        Respects precedence - deduplicates by rule_id.
+
+        Args:
+            family: Rule family code (e.g., 'PI', 'JB', 'PII')
+
+        Returns:
+            List of unique rules in the specified family
+        """
+        all_rules = self.get_all_rules()
+        return [r for r in all_rules if r.family.value == family]
+
+    def get_rules_by_severity(self, severity: str) -> list[Rule]:
+        """Get all unique rules with a specific severity.
+
+        Respects precedence - deduplicates by rule_id.
+
+        Args:
+            severity: Severity level (e.g., 'critical', 'high', 'medium')
+
+        Returns:
+            List of unique rules with the specified severity
+        """
+        all_rules = self.get_all_rules()
+        return [r for r in all_rules if r.severity.value == severity]
+
+    def list_packs(self) -> list[RulePack]:
+        """List all loaded packs.
+
+        Returns:
+            List of loaded packs in precedence order
+        """
+        return [
+            self.packs[pack_type]
+            for pack_type in self.config.precedence
+            if pack_type in self.packs
+        ]
+
+    def get_pack(self, pack_type: str) -> RulePack | None:
+        """Get pack by type.
+
+        Args:
+            pack_type: Pack type identifier ('core', 'community', 'custom')
+
+        Returns:
+            Pack if loaded, None otherwise
+        """
+        return self.packs.get(pack_type)
+
+    def get_pack_info(self) -> dict[str, dict[str, any]]:
+        """Get summary information about all loaded packs.
+
+        Returns:
+            Dictionary mapping pack_type to pack metadata
+
+        Example:
+            {
+                'core': {
+                    'version': '0.0.1',
+                    'rule_count': 5,
+                    'pack_type': 'OFFICIAL',
+                },
+                'custom': {
+                    'version': '0.0.1',
+                    'rule_count': 2,
+                    'pack_type': 'CUSTOM',
+                }
+            }
+        """
+        info = {}
+
+        for pack_type, pack in self.packs.items():
+            info[pack_type] = {
+                'id': pack.manifest.id,
+                'version': pack.manifest.version,
+                'name': pack.manifest.name,
+                'pack_type': pack.manifest.pack_type.value,
+                'rule_count': len(pack.rules),
+                'schema_version': pack.manifest.schema_version,
+            }
+
+        return info
+
+    def reload_all_packs(self) -> None:
+        """Reload all packs from filesystem.
+
+        Clears current packs and loads fresh from disk.
+        Useful for picking up rule updates.
+        """
+        logger.info("Reloading all packs from filesystem")
+        self.packs.clear()
+        self.load_all_packs()

raxe/infrastructure/policies/__init__.py

@@ -0,0 +1,16 @@
+"""Policy infrastructure layer.
+
+I/O implementations for loading and validating policies:
+- YAML file loader (local .raxe/policies.yaml)
+- API client (cloud-hosted policies)
+- Policy validator (signature verification)
+"""
+from raxe.infrastructure.policies.api_client import PolicyAPIClient
+from raxe.infrastructure.policies.validator import PolicyValidator
+from raxe.infrastructure.policies.yaml_loader import YAMLPolicyLoader
+
+__all__ = [
+    "PolicyAPIClient",
+    "PolicyValidator",
+    "YAMLPolicyLoader",
+]

raxe/infrastructure/policies/api_client.py

@@ -0,0 +1,256 @@
+"""Policy API client.
+
+Fetches policies from RAXE cloud API for cloud customers.
+Caches policies locally for offline operation.
+"""
+import json
+from pathlib import Path
+from typing import Protocol
+
+from raxe.domain.policies.models import Policy
+from raxe.infrastructure.policies.yaml_loader import YAMLPolicyLoader
+from raxe.infrastructure.security.auth import APIKey
+
+
+class HTTPClient(Protocol):
+    """HTTP client protocol for dependency injection.
+
+    Allows testing without real HTTP calls.
+    """
+
+    def get(self, url: str, headers: dict[str, str]) -> dict:
+        """Execute GET request.
+
+        Args:
+            url: URL to fetch
+            headers: HTTP headers
+
+        Returns:
+            Response data as dictionary
+
+        Raises:
+            Exception: On HTTP errors
+        """
+        ...
+
+
+class PolicyAPIError(Exception):
+    """Error fetching policies from API."""
+    pass
+
+
+def _get_default_api_base() -> str:
+    """Get default API base URL from centralized config."""
+    from raxe.infrastructure.config.endpoints import get_api_base
+    return get_api_base()
+
+
+class PolicyAPIClient:
+    """Fetch policies from RAXE cloud API.
+
+    Policies are cached locally for offline operation.
+    Cache is refreshed on each successful fetch.
+    """
+
+    def __init__(
+        self,
+        api_base_url: str = "",  # Will use centralized config if empty
+        cache_dir: Path | None = None,
+        http_client: HTTPClient | None = None,
+    ) -> None:
+        """Initialize API client.
+
+        Args:
+            api_base_url: Base URL for RAXE API (uses centralized config if empty)
+            cache_dir: Directory for policy cache (None = ~/.raxe/cache)
+            http_client: HTTP client implementation (None = use requests)
+        """
+        self.api_base_url = (api_base_url or _get_default_api_base()).rstrip("/")
+        self.cache_dir = cache_dir or Path.home() / ".raxe" / "cache"
+        self.http_client = http_client or self._default_http_client()
+        self.yaml_loader = YAMLPolicyLoader()
+
+        # Ensure cache directory exists
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def fetch_policies(
+        self,
+        api_key: APIKey,
+        *,
+        use_cache_on_error: bool = True,
+    ) -> list[Policy]:
+        """Fetch policies for customer from API.
+
+        Downloads policies, caches them locally, and returns as Policy objects.
+
+        Args:
+            api_key: Validated API key
+            use_cache_on_error: If True, return cached policies on API error
+
+        Returns:
+            List of Policy objects for customer
+
+        Raises:
+            PolicyAPIError: If API call fails and no cache available
+        """
+        try:
+            # Fetch from API
+            policies_data = self._fetch_from_api(api_key)
+
+            # Cache response
+            self._save_to_cache(api_key.customer_id, policies_data)
+
+            # Parse to domain models
+            return self._parse_response(policies_data)
+
+        except Exception as e:
+            if use_cache_on_error:
+                # Try to load from cache
+                try:
+                    return self.load_from_cache(api_key.customer_id)
+                except Exception:
+                    # Cache also failed, re-raise original error
+                    raise PolicyAPIError(
+                        f"Failed to fetch policies and no cache available: {e}"
+                    ) from e
+            else:
+                raise PolicyAPIError(f"Failed to fetch policies: {e}") from e
+
+    def load_from_cache(self, customer_id: str) -> list[Policy]:
+        """Load policies from local cache.
+
+        Args:
+            customer_id: Customer ID to load policies for
+
+        Returns:
+            List of cached policies
+
+        Raises:
+            PolicyAPIError: If cache doesn't exist or is invalid
+        """
+        cache_file = self._get_cache_path(customer_id)
+
+        if not cache_file.exists():
+            raise PolicyAPIError(f"No cached policies for {customer_id}")
+
+        try:
+            with open(cache_file) as f:
+                policies_data = json.load(f)
+            return self._parse_response(policies_data)
+        except (OSError, json.JSONDecodeError, ValueError) as e:
+            raise PolicyAPIError(f"Invalid policy cache: {e}") from e
+
+    def clear_cache(self, customer_id: str | None = None) -> None:
+        """Clear policy cache.
+
+        Args:
+            customer_id: Specific customer to clear (None = clear all)
+        """
+        if customer_id:
+            cache_file = self._get_cache_path(customer_id)
+            if cache_file.exists():
+                cache_file.unlink()
+        else:
+            # Clear all cache files
+            for cache_file in self.cache_dir.glob("policies_*.json"):
+                cache_file.unlink()
+
+    def _fetch_from_api(self, api_key: APIKey) -> dict:
+        """Fetch policies from API.
+
+        Args:
+            api_key: API key for authentication
+
+        Returns:
+            Response data as dictionary
+
+        Raises:
+            Exception: On HTTP errors
+        """
+        url = f"{self.api_base_url}/v1/policies"
+        headers = {
+            "Authorization": f"Bearer {api_key.raw_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "raxe-ce/1.0.0",
+        }
+
+        return self.http_client.get(url, headers)
+
+    def _parse_response(self, data: dict) -> list[Policy]:
+        """Parse API response to Policy objects.
+
+        Args:
+            data: Response data from API
+
+        Returns:
+            List of Policy objects
+
+        Raises:
+            ValueError: If response format invalid
+        """
+        # API returns same format as YAML for consistency
+        # Convert to YAML string and use existing parser
+        # (This avoids duplicating parsing logic)
+
+        if "policies" not in data:
+            raise ValueError("API response missing 'policies' field")
+
+        # Use YAML loader's parsing logic
+        return self.yaml_loader._parse_yaml_data(data, "<api>")
+
+    def _save_to_cache(self, customer_id: str, data: dict) -> None:
+        """Save policies to local cache.
+
+        Args:
+            customer_id: Customer ID
+            data: Policy data to cache
+        """
+        cache_file = self._get_cache_path(customer_id)
+
+        try:
+            with open(cache_file, "w") as f:
+                json.dump(data, f, indent=2)
+        except OSError:
+            # Cache write failed - not critical, just log and continue
+            # (Domain layer can't log, but application layer should)
+            pass
+
+    def _get_cache_path(self, customer_id: str) -> Path:
+        """Get cache file path for customer.
+
+        Args:
+            customer_id: Customer ID
+
+        Returns:
+            Path to cache file
+        """
+        # Sanitize customer_id for filename
+        safe_id = customer_id.replace("/", "_").replace("\\", "_")
+        return self.cache_dir / f"policies_{safe_id}.json"
+
+    def _default_http_client(self) -> HTTPClient:
+        """Create default HTTP client using requests.
+
+        Returns:
+            HTTP client implementation
+        """
+        try:
+            import requests
+
+            class RequestsHTTPClient:
+                def get(self, url: str, headers: dict[str, str]) -> dict:
+                    response = requests.get(url, headers=headers, timeout=10)
+                    response.raise_for_status()
+                    return response.json()
+
+            return RequestsHTTPClient()
+
+        except ImportError:
+            # requests not available - return stub that raises error
+            class NoHTTPClient:
+                def get(self, url: str, headers: dict[str, str]) -> dict:
+                    raise PolicyAPIError(
+                        "HTTP client not available. Install 'requests' package."
+                    )
+
+            return NoHTTPClient()