omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/models/security/model_security_error.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Security validation error model.
+
+This module defines the ModelSecurityError model for capturing security
+validation failures. Errors indicate policy violations that must be addressed
+before handler registration or invocation can proceed.
+
+Example:
+    >>> from omnibase_infra.enums import EnumValidationSeverity
+    >>> error = ModelSecurityError(
+    ...     code="SECRET_SCOPE_NOT_PERMITTED",
+    ...     field="secret_scopes",
+    ...     message="Secret scope 'database-admin' not permitted in production",
+    ...     severity=EnumValidationSeverity.ERROR,
+    ... )
+
+See Also:
+    - ModelSecurityWarning: Advisory warnings that don't block validation
+    - ModelSecurityValidationResult: Complete validation result container
+    - EnumSecurityRuleId: Security validation rule identifiers
+    - EnumValidationSeverity: Validation severity levels
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumValidationSeverity
+
+
+class ModelSecurityError(BaseModel):
+    """A security validation error.
+
+    Represents a security validation failure that should prevent
+    handler registration or invocation. Errors indicate policy
+    violations that must be addressed.
+
+    Attributes:
+        code: Error code identifier (e.g., "MISSING_SECRET_SCOPE", "INVALID_DOMAIN").
+            Should be a stable identifier suitable for programmatic handling.
+        field: The field or policy attribute that caused the error.
+        message: Human-readable error description.
+        severity: Error severity level using EnumValidationSeverity.
+            Defaults to ERROR. Use CRITICAL for severe security issues
+            and WARNING for advisory issues.
+
+    Example:
+        >>> from omnibase_infra.enums import EnumValidationSeverity
+        >>> error = ModelSecurityError(
+        ...     code="SECRET_SCOPE_NOT_PERMITTED",
+        ...     field="secret_scopes",
+        ...     message="Secret scope 'database-admin' not permitted in production",
+        ...     severity=EnumValidationSeverity.ERROR,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    code: str = Field(
+        description="Error code identifier for programmatic handling",
+    )
+    field: str = Field(
+        description="The field or policy attribute that caused the error",
+    )
+    message: str = Field(
+        description="Human-readable error description",
+    )
+    severity: EnumValidationSeverity = Field(
+        default=EnumValidationSeverity.ERROR,
+        description="Error severity level (ERROR, CRITICAL, or WARNING)",
+    )
+
+
+__all__ = [
+    "ModelSecurityError",
+]

omnibase_infra/models/security/model_security_validation_result.py

@@ -0,0 +1,328 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Security validation result model for security validation.
+
+This module defines the ModelSecurityValidationResult model for capturing
+complete security validation outcomes, including all errors and warnings.
+This model is used by SecurityMetadataValidator (OMN-1137) to return
+structured validation outcomes.
+
+Example:
+    >>> from omnibase_infra.enums import EnumHandlerTypeCategory
+    >>> from omnibase_infra.models.security import (
+    ...     ModelSecurityError,
+    ...     ModelSecurityWarning,
+    ... )
+    >>> result = ModelSecurityValidationResult(
+    ...     valid=False,
+    ...     subject="my_component",
+    ...     handler_type=EnumHandlerTypeCategory.EFFECT,
+    ...     errors=[
+    ...         ModelSecurityError(
+    ...             code="MISSING_SECRET_SCOPE",
+    ...             field="secret_scopes",
+    ...             message="Required secret scope not declared",
+    ...             severity="error",
+    ...         )
+    ...     ],
+    ...     warnings=[],
+    ... )
+    >>> result.has_errors
+    True
+    >>> result.error_count
+    1
+
+See Also:
+    - ModelSecurityError: Security validation error model
+    - ModelSecurityWarning: Security validation warning model
+    - ModelHandlerSecurityPolicy: Handler-declared security requirements
+    - RegistrationSecurityValidator: Registration-time security validation
+    - EnumSecurityRuleId: Security validation rule identifiers
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumHandlerTypeCategory, EnumInfraTransportType
+from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
+from omnibase_infra.models.security.model_security_error import ModelSecurityError
+from omnibase_infra.models.security.model_security_warning import ModelSecurityWarning
+
+
+class ModelSecurityValidationResult(BaseModel):
+    """Result of security validation.
+
+    Captures the complete outcome of validating a component's security
+    policy, including all errors and warnings encountered. This model
+    provides a structured interface for validation consumers.
+
+    The ``valid`` attribute indicates whether the target passed security
+    validation. A target is valid only if there are no errors; warnings
+    do not affect validity.
+
+    Attributes:
+        valid: Whether the target passed security validation (no errors).
+        subject: Name of the validated component or target.
+        handler_type: Behavioral classification of the target.
+        errors: List of security validation errors.
+        warnings: List of security validation warnings.
+
+    Warning:
+        **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+        return ``True`` only when ``valid`` is True. This differs from typical
+        Pydantic model behavior where ``bool(model)`` always returns ``True`` for
+        any valid model instance. Use explicit attribute access if needed::
+
+            if result:  # Uses __bool__, True only if valid
+                proceed_with_registration()
+
+            if result is not None:  # Always True for constructed instance
+                inspect_result()
+
+    Example:
+        >>> from omnibase_infra.enums import EnumHandlerTypeCategory
+        >>> result = ModelSecurityValidationResult(
+        ...     valid=True,
+        ...     subject="safe_component",
+        ...     handler_type=EnumHandlerTypeCategory.COMPUTE,
+        ...     errors=[],
+        ...     warnings=[],
+        ... )
+        >>> bool(result)
+        True
+        >>> result.has_errors
+        False
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    valid: bool = Field(
+        description="Whether the target passed security validation",
+    )
+    subject: str = Field(
+        description="Identifier of the validated component (e.g., handler name)",
+    )
+    handler_type: EnumHandlerTypeCategory = Field(
+        description="Behavioral classification of the handler",
+    )
+    errors: tuple[ModelSecurityError, ...] = Field(
+        default_factory=tuple,
+        description="List of security validation errors",
+    )
+    warnings: tuple[ModelSecurityWarning, ...] = Field(
+        default_factory=tuple,
+        description="List of security validation warnings",
+    )
+
+    @property
+    def has_errors(self) -> bool:
+        """Check if any validation errors exist.
+
+        Returns:
+            True if there are one or more errors, False otherwise.
+
+        Example:
+            >>> result = ModelSecurityValidationResult(
+            ...     valid=False,
+            ...     subject="test",
+            ...     handler_type=EnumHandlerTypeCategory.EFFECT,
+            ...     errors=(ModelSecurityError(
+            ...         code="TEST", field="test", message="test", severity="error"
+            ...     ),),
+            ...     warnings=(),
+            ... )
+            >>> result.has_errors
+            True
+        """
+        return len(self.errors) > 0
+
+    @property
+    def has_warnings(self) -> bool:
+        """Check if any validation warnings exist.
+
+        Returns:
+            True if there are one or more warnings, False otherwise.
+
+        Example:
+            >>> result = ModelSecurityValidationResult(
+            ...     valid=True,
+            ...     subject="test",
+            ...     handler_type=EnumHandlerTypeCategory.COMPUTE,
+            ...     errors=(),
+            ...     warnings=(ModelSecurityWarning(
+            ...         code="TEST", field="test", message="test"
+            ...     ),),
+            ... )
+            >>> result.has_warnings
+            True
+        """
+        return len(self.warnings) > 0
+
+    @property
+    def error_count(self) -> int:
+        """Get the number of validation errors.
+
+        Returns:
+            Count of errors in this result.
+
+        Example:
+            >>> result = ModelSecurityValidationResult(
+            ...     valid=True,
+            ...     subject="test",
+            ...     handler_type=EnumHandlerTypeCategory.COMPUTE,
+            ...     errors=(),
+            ...     warnings=(),
+            ... )
+            >>> result.error_count
+            0
+        """
+        return len(self.errors)
+
+    @property
+    def warning_count(self) -> int:
+        """Get the number of validation warnings.
+
+        Returns:
+            Count of warnings in this result.
+
+        Example:
+            >>> result = ModelSecurityValidationResult(
+            ...     valid=True,
+            ...     subject="test",
+            ...     handler_type=EnumHandlerTypeCategory.COMPUTE,
+            ...     errors=(),
+            ...     warnings=(),
+            ... )
+            >>> result.warning_count
+            0
+        """
+        return len(self.warnings)
+
+    def __bool__(self) -> bool:
+        """Allow using result in boolean context.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when ``valid`` is True. This differs from typical
+            Pydantic model behavior where ``bool(model)`` always returns ``True`` for
+            any valid model instance.
+
+            This design enables idiomatic conditional checks::
+
+                if result:
+                    # Validation passed - proceed with registration
+                    register_handler()
+                else:
+                    # Validation failed - handle errors
+                    for error in result.errors:
+                        log_error(error)
+
+        Returns:
+            True if validation passed, False otherwise.
+        """
+        return self.valid
+
+    @classmethod
+    def success(
+        cls,
+        subject: str,
+        handler_type: EnumHandlerTypeCategory,
+        warnings: tuple[ModelSecurityWarning, ...] = (),
+    ) -> ModelSecurityValidationResult:
+        """Create a successful validation result.
+
+        Factory method for creating a valid result. May include warnings
+        but will have no errors.
+
+        Args:
+            subject: Name of the validated component or target.
+            handler_type: Behavioral classification of the target.
+            warnings: Optional warnings to include in the result.
+
+        Returns:
+            ModelSecurityValidationResult with valid=True and no errors.
+
+        Example:
+            >>> result = ModelSecurityValidationResult.success(
+            ...     subject="my_component",
+            ...     handler_type=EnumHandlerTypeCategory.COMPUTE,
+            ... )
+            >>> result.valid
+            True
+            >>> result.has_errors
+            False
+        """
+        return cls(
+            valid=True,
+            subject=subject,
+            handler_type=handler_type,
+            errors=(),
+            warnings=warnings,
+        )
+
+    @classmethod
+    def failure(
+        cls,
+        subject: str,
+        handler_type: EnumHandlerTypeCategory,
+        errors: tuple[ModelSecurityError, ...],
+        warnings: tuple[ModelSecurityWarning, ...] = (),
+    ) -> ModelSecurityValidationResult:
+        """Create a failed validation result.
+
+        Factory method for creating an invalid result with errors.
+
+        Args:
+            subject: Name of the validated component or target.
+            handler_type: Behavioral classification of the target.
+            errors: Validation errors (must be non-empty for failure).
+            warnings: Optional warnings to include in the result.
+
+        Returns:
+            ModelSecurityValidationResult with valid=False and errors.
+
+        Raises:
+            ProtocolConfigurationError: If errors is empty (failures must have errors).
+
+        Example:
+            >>> error = ModelSecurityError(
+            ...     code="TEST",
+            ...     field="test",
+            ...     message="Test error",
+            ...     severity="error",
+            ... )
+            >>> result = ModelSecurityValidationResult.failure(
+            ...     subject="bad_component",
+            ...     handler_type=EnumHandlerTypeCategory.EFFECT,
+            ...     errors=(error,),
+            ... )
+            >>> result.valid
+            False
+            >>> result.has_errors
+            True
+        """
+        if not errors:
+            context = ModelInfraErrorContext(
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="failure",
+            )
+            raise ProtocolConfigurationError(
+                "errors must be non-empty for failure results", context=context
+            )
+        return cls(
+            valid=False,
+            subject=subject,
+            handler_type=handler_type,
+            errors=errors,
+            warnings=warnings,
+        )
+
+
+__all__ = [
+    "ModelSecurityValidationResult",
+]

omnibase_infra/models/security/model_security_warning.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Security validation warning model.
+
+This module defines the ModelSecurityWarning model for capturing security
+validation advisories. Warnings do not block handler registration or invocation,
+but indicate potential issues that should be reviewed.
+
+Example:
+    >>> warning = ModelSecurityWarning(
+    ...     code="WILDCARD_DOMAIN_ACCESS",
+    ...     field="allowed_domains",
+    ...     message="Handler permits access to all domains - consider restricting",
+    ... )
+
+See Also:
+    - ModelSecurityError: Blocking errors that prevent validation
+    - ModelSecurityValidationResult: Complete validation result container
+    - EnumSecurityRuleId: Security validation rule identifiers
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelSecurityWarning(BaseModel):
+    """A security validation warning.
+
+    Represents a security advisory that does not block handler
+    registration or invocation, but indicates a potential issue
+    that should be reviewed.
+
+    Attributes:
+        code: Warning code identifier (e.g., "BROAD_DOMAIN_ACCESS").
+            Should be a stable identifier suitable for programmatic handling.
+        field: The field or policy attribute that triggered the warning.
+        message: Human-readable warning description.
+
+    Example:
+        >>> warning = ModelSecurityWarning(
+        ...     code="WILDCARD_DOMAIN_ACCESS",
+        ...     field="allowed_domains",
+        ...     message="Handler permits access to all domains - consider restricting",
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    code: str = Field(
+        description="Warning code identifier for programmatic handling",
+    )
+    field: str = Field(
+        description="The field or policy attribute that triggered the warning",
+    )
+    message: str = Field(
+        description="Human-readable warning description",
+    )
+
+
+__all__ = [
+    "ModelSecurityWarning",
+]

omnibase_infra/models/snapshot/__init__.py

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Generic Snapshot Models for Point-in-Time State Capture.
+
+This module provides infrastructure primitives for managing point-in-time
+snapshots of entity state. Snapshots support:
+
+- Subject-based grouping (ModelSubjectRef)
+- Structural diffing (ModelSnapshotDiff, ModelFieldChange)
+- Immutable state capture with content hashing (ModelSnapshot)
+- Lineage tracking for fork scenarios
+
+Related Tickets:
+    - OMN-1246: ServiceSnapshot Infrastructure Primitive
+"""
+
+from omnibase_infra.models.snapshot.model_field_change import ModelFieldChange
+from omnibase_infra.models.snapshot.model_snapshot import ModelSnapshot
+from omnibase_infra.models.snapshot.model_snapshot_diff import ModelSnapshotDiff
+from omnibase_infra.models.snapshot.model_subject_ref import ModelSubjectRef
+
+__all__: list[str] = [
+    "ModelFieldChange",
+    "ModelSnapshot",
+    "ModelSnapshotDiff",
+    "ModelSubjectRef",
+]

omnibase_infra/models/snapshot/model_field_change.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Field Change Model for Structural Diffs.
+
+Represents a single field change between two snapshots, capturing the
+before and after values for diff analysis.
+
+Thread Safety:
+    This model is frozen (immutable) for safe sharing across threads.
+
+Related Tickets:
+    - OMN-1246: ServiceSnapshot Infrastructure Primitive
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelFieldChange(BaseModel):
+    """Represents a single field change between snapshots.
+
+    Captures the transition from one value to another for a specific field
+    in a structural diff. Both values must be JSON-compatible.
+
+    Attributes:
+        from_value: The original value before the change.
+        to_value: The new value after the change.
+
+    Example:
+        >>> change = ModelFieldChange(
+        ...     from_value="pending",
+        ...     to_value="active",
+        ... )
+        >>> change.from_value
+        'pending'
+        >>> change.to_value
+        'active'
+
+        >>> # Complex nested changes
+        >>> change = ModelFieldChange(
+        ...     from_value={"count": 1, "items": ["a"]},
+        ...     to_value={"count": 2, "items": ["a", "b"]},
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    from_value: JsonType = Field(
+        ...,
+        description="The original value before the change",
+    )
+    to_value: JsonType = Field(
+        ...,
+        description="The new value after the change",
+    )
+
+
+__all__: list[str] = ["ModelFieldChange"]