omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/validation/validator_localhandler.py

@@ -0,0 +1,261 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""LocalHandler Import Validator for ONEX Production Code Policy.
+
+This module provides validation to detect forbidden LocalHandler imports
+in production code. LocalHandler is a test-only handler that must NEVER
+be imported in src/omnibase_infra/.
+
+Policy:
+    - BLOCKED: Any import of LocalHandler in src/omnibase_infra/
+    - ALLOWED: Imports in tests/ directory for comparison tests
+
+The validator uses regex-based line scanning to detect import patterns.
+
+Import Patterns Detected:
+    - ``from omnibase_core.handlers import LocalHandler``
+    - ``from omnibase_core.handlers.handler_local import LocalHandler``
+    - ``from omnibase_core.handlers.local_handler import LocalHandler``
+    - ``import omnibase_core.handlers.LocalHandler``
+    - Any other pattern containing 'LocalHandler' in an import statement
+
+Usage:
+    >>> from omnibase_infra.validation.validator_localhandler import (
+    ...     validate_localhandler,
+    ...     validate_localhandler_ci,
+    ... )
+    >>> violations = validate_localhandler(Path("src/omnibase_infra"))
+    >>> result = validate_localhandler_ci(Path("src/omnibase_infra"))
+    >>> if not result.passed:
+    ...     print(result.format_summary())
+    ...     sys.exit(1)
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+
+from omnibase_infra.models.validation.model_localhandler_validation_result import (
+    ModelLocalHandlerValidationResult,
+)
+from omnibase_infra.models.validation.model_localhandler_violation import (
+    ModelLocalHandlerViolation,
+)
+
+logger = logging.getLogger(__name__)
+
+# Regex pattern to detect LocalHandler imports (line-by-line matching)
+# Matches both:
+#   - from ... import LocalHandler (with optional alias)
+#   - import statement with LocalHandler in path
+_PATTERN_LOCALHANDLER_IMPORT = re.compile(
+    r"^\s*(?:from\s+[\w.]+\s+import\s+.*\bLocalHandler\b|import\s+[\w.]*LocalHandler)"
+)
+
+# Maximum file size to process (in bytes).
+# Files larger than this are skipped to prevent hangs on auto-generated code.
+_MAX_FILE_SIZE_BYTES: int = 1_000_000  # 1MB
+
+# Directories to skip (exact name matching)
+_SKIP_DIRECTORIES: frozenset[str] = frozenset(
+    {
+        "tests",  # Test files are allowed to use LocalHandler
+        "__pycache__",  # Python bytecode cache
+        ".git",  # Git directory
+        ".venv",  # Virtual environment
+        "venv",  # Virtual environment
+        "node_modules",  # Node modules (unlikely but safe)
+    }
+)
+
+
+def _should_skip_file(filepath: Path) -> bool:
+    """Check if a file should be skipped based on directory matching.
+
+    Uses exact parent directory matching to prevent false positives.
+
+    Note:
+        __init__.py files are NOT skipped because they can contain
+        LocalHandler imports that must be validated.
+
+    Args:
+        filepath: Path to check.
+
+    Returns:
+        True if the file should be skipped.
+    """
+    parts = filepath.parts
+
+    # Check parent directories for exact matches (exclude filename)
+    for part in parts[:-1]:
+        if part in _SKIP_DIRECTORIES:
+            return True
+
+    # Skip private modules (underscore prefix) but NOT __init__.py
+    # __init__.py files CAN contain LocalHandler imports and must be validated
+    filename = filepath.name
+    if filename.startswith("_") and filename != "__init__.py":
+        return True
+
+    return False
+
+
+def validate_localhandler_in_file(filepath: Path) -> list[ModelLocalHandlerViolation]:
+    """Validate a single Python file for LocalHandler import violations.
+
+    Args:
+        filepath: Path to the Python file to validate.
+
+    Returns:
+        List of detected violations. Empty list if no violations found.
+    """
+    try:
+        content = filepath.read_text(encoding="utf-8")
+    except OSError as e:
+        logger.warning(
+            "Failed to read file",
+            extra={"file": str(filepath), "error": str(e)},
+        )
+        return []
+
+    violations: list[ModelLocalHandlerViolation] = []
+    lines = content.split("\n")
+
+    for line_number, line in enumerate(lines, start=1):
+        # Skip comment lines
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            continue
+
+        # Check if line contains LocalHandler import
+        if _PATTERN_LOCALHANDLER_IMPORT.match(stripped):
+            violations.append(
+                ModelLocalHandlerViolation(
+                    file_path=filepath,
+                    line_number=line_number,
+                    import_line=stripped,
+                )
+            )
+
+    return violations
+
+
+def _validate_localhandler_with_count(
+    directory: Path,
+    recursive: bool = True,
+) -> tuple[list[ModelLocalHandlerViolation], int]:
+    """Internal function to validate files and count them in a single traversal.
+
+    This avoids double traversal by combining file counting with validation.
+
+    Args:
+        directory: Path to the directory to validate.
+        recursive: If True, recursively validate subdirectories.
+
+    Returns:
+        Tuple of (violations list, files_checked count).
+    """
+    violations: list[ModelLocalHandlerViolation] = []
+    files_checked = 0
+    py_files = directory.rglob("*.py") if recursive else directory.glob("*.py")
+
+    for filepath in py_files:
+        if filepath.is_file() and not _should_skip_file(filepath):
+            # Skip very large files
+            try:
+                file_size = filepath.stat().st_size
+                if file_size > _MAX_FILE_SIZE_BYTES:
+                    logger.debug(
+                        "Skipping large file",
+                        extra={"file": str(filepath), "size_bytes": file_size},
+                    )
+                    continue
+            except OSError as e:
+                logger.warning(
+                    "Failed to stat file",
+                    extra={"file": str(filepath), "error": str(e)},
+                )
+                continue
+
+            # Count this file as checked
+            files_checked += 1
+
+            try:
+                file_violations = validate_localhandler_in_file(filepath)
+                violations.extend(file_violations)
+            except Exception as e:  # catch-all-ok: validation continues on file errors
+                logger.warning(
+                    "Failed to validate file",
+                    extra={
+                        "file": str(filepath),
+                        "error_type": type(e).__name__,
+                        "error": str(e),
+                    },
+                )
+                continue
+
+    return violations, files_checked
+
+
+def validate_localhandler(
+    directory: Path,
+    recursive: bool = True,
+) -> list[ModelLocalHandlerViolation]:
+    """Validate all Python files in a directory for LocalHandler import violations.
+
+    This is the main entry point for batch validation.
+
+    Args:
+        directory: Path to the directory to validate.
+        recursive: If True, recursively validate subdirectories.
+
+    Returns:
+        List of all detected violations across all files.
+
+    Example:
+        >>> violations = validate_localhandler(Path("src/omnibase_infra"))
+        >>> for v in violations:
+        ...     print(v.format_human_readable())
+    """
+    violations, _ = _validate_localhandler_with_count(directory, recursive)
+    return violations
+
+
+def validate_localhandler_ci(
+    directory: Path,
+    recursive: bool = True,
+) -> ModelLocalHandlerValidationResult:
+    """CI gate for LocalHandler validation.
+
+    This function is designed for CI pipeline integration. It returns a
+    structured result model containing the pass/fail status and all violations
+    for reporting.
+
+    Args:
+        directory: Path to the directory to validate.
+        recursive: If True, recursively validate subdirectories.
+
+    Returns:
+        ModelLocalHandlerValidationResult containing pass/fail status and violations.
+
+    Example:
+        >>> result = validate_localhandler_ci(Path("src/omnibase_infra"))
+        >>> if not result.passed:
+        ...     print(result.format_summary())
+        ...     for line in result.format_for_ci():
+        ...         print(line)
+        ...     sys.exit(1)
+    """
+    violations, files_checked = _validate_localhandler_with_count(directory, recursive)
+    return ModelLocalHandlerValidationResult.from_violations(violations, files_checked)
+
+
+__all__ = [
+    "ModelLocalHandlerValidationResult",
+    "ModelLocalHandlerViolation",
+    "validate_localhandler",
+    "validate_localhandler_ci",
+    "validate_localhandler_in_file",
+]

omnibase_infra/validation/validator_registration_security.py

@@ -0,0 +1,410 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registration-time security validation for handlers.
+
+Validates handler security policies against environment constraints
+at registration time. Part of the two-layer security validation
+system (OMN-1098).
+
+Security Rules Enforced:
+    SECURITY-300: Secret scope not permitted by environment
+    SECURITY-301: Data classification exceeds environment maximum
+    SECURITY-302: Adapter handler requesting secrets
+    SECURITY-303: Adapter with non-EFFECT handler category
+    SECURITY-304: Adapter missing explicit domain allowlist
+
+Architecture:
+    This validator operates at registration time, before handlers are
+    permitted to execute. It validates handler-declared security policies
+    against environment-level constraints. Runtime enforcement (invocation-time
+    validation) is handled separately.
+
+    The validator is stateless for the convenience function pattern, but also
+    supports a stateful pattern where the environment policy is bound at
+    construction time.
+
+See Also:
+    - ModelHandlerSecurityPolicy: Handler-declared security requirements
+    - ModelEnvironmentPolicy: Environment-level security constraints
+    - EnumSecurityRuleId: Security validation rule identifiers
+
+"""
+
+from __future__ import annotations
+
+from omnibase_infra.enums import EnumHandlerTypeCategory, EnumSecurityRuleId
+from omnibase_infra.models.errors import ModelHandlerValidationError
+from omnibase_infra.models.handlers import ModelHandlerIdentifier
+from omnibase_infra.models.security import (
+    ModelEnvironmentPolicy,
+    ModelHandlerSecurityPolicy,
+    get_security_level,
+)
+
+
+class RegistrationSecurityValidator:
+    """Validates handler security policies at registration time.
+
+    This validator checks handler-declared security policies against
+    environment-level constraints. It can be used in two patterns:
+
+    1. Stateful pattern (bind environment policy at construction):
+        >>> validator = RegistrationSecurityValidator(env_policy)
+        >>> errors = validator.validate(handler_policy)
+        >>> if validator.is_valid(handler_policy): ...
+
+    2. Stateless pattern (use module-level convenience function):
+        >>> errors = validate_handler_registration(handler_policy, env_policy)
+
+    The validator is itself stateless (no mutable state), but binding the
+    environment policy at construction provides a convenient interface when
+    validating multiple handlers against the same environment.
+
+    Attributes:
+        environment_policy: The environment policy bound at construction.
+
+    Security Rules:
+        SECURITY-300: Secret scope not permitted by environment
+        SECURITY-301: Data classification exceeds environment maximum
+        SECURITY-302: Adapter handler requesting secrets
+        SECURITY-303: Adapter with non-EFFECT handler category
+        SECURITY-304: Adapter missing explicit domain allowlist
+
+    """
+
+    def __init__(self, environment_policy: ModelEnvironmentPolicy) -> None:
+        """Initialize the validator with environment policy.
+
+        Args:
+            environment_policy: Environment-level security constraints.
+        """
+        self._environment_policy = environment_policy
+
+    @property
+    def environment_policy(self) -> ModelEnvironmentPolicy:
+        """Get the environment policy bound to this validator."""
+        return self._environment_policy
+
+    def validate(
+        self,
+        handler_policy: ModelHandlerSecurityPolicy,
+        handler_identity: ModelHandlerIdentifier | None = None,
+    ) -> list[ModelHandlerValidationError]:
+        """Validate handler security policy against environment constraints.
+
+        Args:
+            handler_policy: Handler-declared security policy.
+            handler_identity: Optional handler identity for error context.
+                Defaults to "unknown" if not provided.
+
+        Returns:
+            List of validation errors (empty if valid).
+        """
+        return _validate_policies(
+            handler_policy, self._environment_policy, handler_identity
+        )
+
+    def is_valid(
+        self,
+        handler_policy: ModelHandlerSecurityPolicy,
+        handler_identity: ModelHandlerIdentifier | None = None,
+    ) -> bool:
+        """Check if handler security policy is valid for this environment.
+
+        Args:
+            handler_policy: Handler-declared security policy.
+            handler_identity: Optional handler identity for error context.
+                Defaults to "unknown" if not provided.
+
+        Returns:
+            True if valid (no errors), False otherwise.
+        """
+        return len(self.validate(handler_policy, handler_identity)) == 0
+
+
+def _validate_policies(
+    handler_policy: ModelHandlerSecurityPolicy,
+    env_policy: ModelEnvironmentPolicy,
+    handler_identity: ModelHandlerIdentifier | None = None,
+) -> list[ModelHandlerValidationError]:
+    """Core validation logic for handler security policy against environment.
+
+    This function implements all validation rules. It is used by both the
+    RegistrationSecurityValidator class and the convenience function.
+
+    Args:
+        handler_policy: Handler-declared security policy.
+        env_policy: Environment-level security constraints.
+        handler_identity: Optional handler identity for error context.
+            Defaults to "unknown" if not provided.
+
+    Returns:
+        List of validation errors (empty if valid).
+    """
+    # Use default "unknown" if no identity provided
+    identity = handler_identity or ModelHandlerIdentifier.from_handler_id("unknown")
+    errors: list[ModelHandlerValidationError] = []
+
+    # 1. Check secret scopes (SECURITY-300)
+    errors.extend(_validate_secret_scopes(handler_policy, env_policy, identity))
+
+    # 2. Check data classification (SECURITY-301)
+    errors.extend(_validate_classification(handler_policy, env_policy, identity))
+
+    # 3. Check adapter constraints (SECURITY-302, 303, 304)
+    if handler_policy.is_adapter:
+        errors.extend(
+            _validate_adapter_constraints(handler_policy, env_policy, identity)
+        )
+
+    return errors
+
+
+def _validate_secret_scopes(
+    handler_policy: ModelHandlerSecurityPolicy,
+    env_policy: ModelEnvironmentPolicy,
+    handler_identity: ModelHandlerIdentifier,
+) -> list[ModelHandlerValidationError]:
+    """Validate secret scopes against environment permissions.
+
+    SECURITY-300: Secret scope not permitted by environment.
+
+    Wildcard Support:
+        If permitted_secret_scopes contains "*", all secret scopes are allowed.
+        This is intended for development environments where secret isolation
+        is less critical.
+
+    Args:
+        handler_policy: Handler-declared security policy.
+        env_policy: Environment-level security constraints.
+        handler_identity: Handler identity for error context.
+
+    Returns:
+        List of errors for unpermitted secret scopes.
+    """
+    errors: list[ModelHandlerValidationError] = []
+
+    # If "*" is in permitted_secret_scopes, all scopes are allowed
+    if "*" in env_policy.permitted_secret_scopes:
+        return errors
+
+    # Find unpermitted scopes
+    unpermitted = handler_policy.secret_scopes - env_policy.permitted_secret_scopes
+
+    # Create error for each unpermitted scope
+    for scope in sorted(unpermitted):  # Sort for deterministic output
+        error = ModelHandlerValidationError.from_security_violation(
+            rule_id=EnumSecurityRuleId.SECRET_SCOPE_NOT_PERMITTED,
+            message=(
+                f"Secret scope '{scope}' not permitted in "
+                f"{env_policy.environment.value} environment"
+            ),
+            remediation_hint=(
+                f"Remove the '{scope}' secret scope from handler policy "
+                "or update environment policy to permit this scope"
+            ),
+            handler_identity=handler_identity,
+        )
+        errors.append(error)
+
+    return errors
+
+
+def _validate_classification(
+    handler_policy: ModelHandlerSecurityPolicy,
+    env_policy: ModelEnvironmentPolicy,
+    handler_identity: ModelHandlerIdentifier,
+) -> list[ModelHandlerValidationError]:
+    """Validate data classification against environment maximum.
+
+    SECURITY-301: Data classification exceeds environment maximum.
+
+    Args:
+        handler_policy: Handler-declared security policy.
+        env_policy: Environment-level security constraints.
+        handler_identity: Handler identity for error context.
+
+    Returns:
+        List containing error if classification exceeds max, else empty.
+    """
+    errors: list[ModelHandlerValidationError] = []
+
+    # Get security levels for comparison
+    handler_level = get_security_level(handler_policy.data_classification)
+    max_level = get_security_level(env_policy.max_data_classification)
+
+    # Check if handler classification exceeds environment maximum
+    if handler_level > max_level:
+        error = ModelHandlerValidationError.from_security_violation(
+            rule_id=EnumSecurityRuleId.CLASSIFICATION_EXCEEDS_MAX,
+            message=(
+                f"Handler data classification '{handler_policy.data_classification.value}' "
+                f"exceeds environment maximum '{env_policy.max_data_classification.value}' "
+                f"in {env_policy.environment.value} environment"
+            ),
+            remediation_hint=(
+                f"Reduce handler data classification to "
+                f"'{env_policy.max_data_classification.value}' or below, "
+                "or deploy to an environment with higher classification limits"
+            ),
+            handler_identity=handler_identity,
+        )
+        errors.append(error)
+
+    return errors
+
+
+def _validate_adapter_constraints(
+    handler_policy: ModelHandlerSecurityPolicy,
+    env_policy: ModelEnvironmentPolicy,
+    handler_identity: ModelHandlerIdentifier,
+) -> list[ModelHandlerValidationError]:
+    """Validate adapter-specific security constraints.
+
+    Adapters are special handlers that interact with external systems.
+    They have stricter security constraints:
+        SECURITY-302: Adapter requesting secrets (unless override allowed)
+        SECURITY-303: Adapter with non-EFFECT category
+        SECURITY-304: Adapter missing domain allowlist (if required)
+
+    Args:
+        handler_policy: Handler-declared security policy (must have is_adapter=True).
+        env_policy: Environment-level security constraints.
+        handler_identity: Handler identity for error context.
+
+    Returns:
+        List of errors for adapter constraint violations.
+    """
+    errors: list[ModelHandlerValidationError] = []
+
+    # SECURITY-302: Adapter requesting secrets
+    if handler_policy.secret_scopes and not env_policy.adapter_secrets_override_allowed:
+        error = ModelHandlerValidationError.from_security_violation(
+            rule_id=EnumSecurityRuleId.ADAPTER_REQUESTING_SECRETS,
+            message=(
+                "Adapter handler is requesting secret scopes "
+                f"({', '.join(sorted(handler_policy.secret_scopes))}) "
+                "but adapters should not have direct secret access"
+            ),
+            remediation_hint=(
+                "Remove secret scopes from adapter handler policy and use "
+                "platform secret management (Vault) instead, or enable "
+                "adapter_secrets_override_allowed in environment policy"
+            ),
+            handler_identity=handler_identity,
+        )
+        errors.append(error)
+
+    # SECURITY-303: Adapter with non-EFFECT category (or missing category)
+    # Adapters MUST explicitly set handler_type_category=EFFECT
+    if handler_policy.handler_type_category is None:
+        error = ModelHandlerValidationError.from_security_violation(
+            rule_id=EnumSecurityRuleId.ADAPTER_NON_EFFECT_CATEGORY,
+            message=(
+                "Invalid adapter handler configuration: "
+                "expected handler_type_category=EFFECT, got None"
+            ),
+            remediation_hint=(
+                "Set handler_type_category=EnumHandlerTypeCategory.EFFECT for adapter handlers, "
+                "or remove is_adapter=True if this is not an adapter"
+            ),
+            handler_identity=handler_identity,
+        )
+        errors.append(error)
+    elif handler_policy.handler_type_category != EnumHandlerTypeCategory.EFFECT:
+        error = ModelHandlerValidationError.from_security_violation(
+            rule_id=EnumSecurityRuleId.ADAPTER_NON_EFFECT_CATEGORY,
+            message=(
+                f"Adapter handler has category '{handler_policy.handler_type_category.value}' "
+                "but adapters must be EFFECT category (external I/O handlers)"
+            ),
+            remediation_hint=(
+                "Change handler_type_category to EFFECT for adapter handlers, "
+                "or remove is_adapter=True if this is not an adapter"
+            ),
+            handler_identity=handler_identity,
+        )
+        errors.append(error)
+
+    # SECURITY-304: Adapter missing domain allowlist
+    # Empty allowed_domains or containing "*" wildcard is treated as missing
+    # when explicit domain allowlist is required
+    has_explicit_domains = (
+        bool(handler_policy.allowed_domains)
+        and "*" not in handler_policy.allowed_domains
+    )
+    if env_policy.require_explicit_domain_allowlist and not has_explicit_domains:
+        # Determine appropriate message based on violation type
+        if not handler_policy.allowed_domains:
+            violation_detail = "missing explicit domain allowlist"
+        else:
+            violation_detail = (
+                "using wildcard '*' in domain allowlist (explicit domains required)"
+            )
+
+        error = ModelHandlerValidationError.from_security_violation(
+            rule_id=EnumSecurityRuleId.ADAPTER_MISSING_DOMAIN_ALLOWLIST,
+            message=(
+                f"Adapter handler {violation_detail} "
+                f"which is required in {env_policy.environment.value} environment"
+            ),
+            remediation_hint=(
+                "Add allowed_domains to handler policy specifying which "
+                "external domains the adapter may communicate with. "
+                "Wildcard '*' is not permitted when explicit domain allowlist is required."
+            ),
+            handler_identity=handler_identity,
+        )
+        errors.append(error)
+
+    return errors
+
+
+def validate_handler_registration(
+    handler_policy: ModelHandlerSecurityPolicy,
+    env_policy: ModelEnvironmentPolicy,
+    handler_identity: ModelHandlerIdentifier | None = None,
+) -> list[ModelHandlerValidationError]:
+    """Validate handler security policy against environment constraints.
+
+    Convenience function for one-shot validation without creating a
+    validator instance. For validating multiple handlers against the
+    same environment, consider using RegistrationSecurityValidator directly.
+
+    Args:
+        handler_policy: Handler-declared security policy.
+        env_policy: Environment-level security constraints.
+        handler_identity: Optional handler identity for error context.
+            Defaults to "unknown" if not provided.
+
+    Returns:
+        List of validation errors (empty if valid).
+
+    Example:
+        >>> from omnibase_infra.models.security import (
+        ...     ModelHandlerSecurityPolicy,
+        ...     ModelEnvironmentPolicy,
+        ... )
+        >>> from omnibase_core.enums import EnumDataClassification
+        >>> from omnibase_infra.enums import EnumEnvironment
+        >>>
+        >>> handler_policy = ModelHandlerSecurityPolicy(
+        ...     secret_scopes=frozenset({"database-creds"}),
+        ...     data_classification=EnumDataClassification.INTERNAL,
+        ... )
+        >>> env_policy = ModelEnvironmentPolicy(
+        ...     environment=EnumEnvironment.PRODUCTION,
+        ...     permitted_secret_scopes=frozenset({"api-keys"}),
+        ...     max_data_classification=EnumDataClassification.CONFIDENTIAL,
+        ... )
+        >>> errors = validate_handler_registration(handler_policy, env_policy)
+        >>> len(errors)  # 1 error for unpermitted secret scope
+        1
+    """
+    return _validate_policies(handler_policy, env_policy, handler_identity)
+
+
+__all__ = [
+    "RegistrationSecurityValidator",
+    "validate_handler_registration",
+]