omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/models/runtime/model_plugin_load_context.py

@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Plugin Load Context Model for Summary Logging.
+
+This module provides ModelPluginLoadContext which groups the parameters needed
+for logging a plugin load summary.
+
+See Also:
+    - PluginLoader: Uses this model to pass context to _log_load_summary
+    - ModelPluginLoadSummary: The summary model created from this context
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1132 Plugin Loader observability logging.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.runtime.model_failed_plugin_load import (
+    ModelFailedPluginLoad,
+)
+from omnibase_infra.models.runtime.model_loaded_handler import ModelLoadedHandler
+
+
+class ModelPluginLoadContext(BaseModel):
+    """Context for logging a plugin load summary.
+
+    Groups related parameters needed to create a load summary, reducing
+    the number of function parameters.
+
+    Attributes:
+        operation: The type of load operation (e.g., 'load_from_directory').
+        source: The source path or patterns used for discovery.
+        total_discovered: Total number of contract files discovered.
+        handlers: List of successfully loaded handlers.
+        failed_plugins: List of plugins that failed to load.
+        duration_seconds: Total operation time in seconds.
+        correlation_id: Correlation ID for distributed tracing (UUID for models).
+        original_correlation_id: Original correlation ID string for logging.
+            Preserves the exact string passed by the caller, even if it's not
+            a valid UUID format. Used in log extra fields for traceability.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    operation: str = Field(
+        ...,
+        min_length=1,
+        description="Type of load operation performed",
+    )
+    source: str = Field(
+        ...,
+        description="Source path or patterns used for discovery",
+    )
+    total_discovered: int = Field(
+        ...,
+        ge=0,
+        description="Total number of contract files discovered",
+    )
+    handlers: list[ModelLoadedHandler] = Field(
+        default_factory=list,
+        description="List of successfully loaded handlers",
+    )
+    failed_plugins: list[ModelFailedPluginLoad] = Field(
+        default_factory=list,
+        description="List of plugins that failed to load",
+    )
+    duration_seconds: float = Field(
+        ...,
+        ge=0.0,
+        description="Total operation time in seconds",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing (UUID for models)",
+    )
+    # NOTE: This field intentionally uses str (not UUID) to preserve the exact
+    # caller-provided value for logging. The caller may provide a non-UUID format
+    # correlation ID (e.g., 'test-correlation-12345' or OpenTelemetry trace IDs).
+    # The UUID-typed 'correlation_id' field is used for model validation.
+    caller_correlation_string: str = Field(
+        ...,
+        min_length=1,
+        description="Original correlation string from caller for logging (may be non-UUID)",
+    )
+
+
+__all__ = ["ModelPluginLoadContext"]

omnibase_infra/models/runtime/model_plugin_load_summary.py

@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Plugin Load Summary Model for Observability Logging.
+
+This module provides ModelPluginLoadSummary which tracks the results of batch
+plugin loading operations for observability purposes.
+
+The summary captures:
+- Total plugins discovered and loaded
+- Details of any failed loads
+- Load duration for performance monitoring
+- Correlation ID for distributed tracing
+
+See Also:
+    - PluginLoader: Uses this model for summary logging
+    - ModelLoadedHandler: Individual plugin metadata
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1132 Plugin Loader observability logging.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.runtime.model_failed_plugin_load import (
+    ModelFailedPluginLoad,
+)
+
+
+class ModelPluginLoadSummary(BaseModel):
+    """Summary of a batch plugin loading operation.
+
+    Captures comprehensive metrics about a batch loading operation for
+    observability, debugging, and performance monitoring.
+
+    Attributes:
+        operation: The type of load operation (e.g., 'load_from_directory',
+            'discover_and_load').
+        source: The source path or patterns used for discovery.
+        total_discovered: Total number of contract files discovered.
+        total_loaded: Number of plugins successfully loaded.
+        total_failed: Number of plugins that failed to load.
+        loaded_plugins: List of successfully loaded plugin details (name, class, module).
+        failed_plugins: List of failed plugin details with error information.
+        duration_seconds: Total time taken for the operation in seconds.
+        correlation_id: Correlation ID for distributed tracing.
+        completed_at: Timestamp when the operation completed.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> summary = ModelPluginLoadSummary(
+        ...     operation="load_from_directory",
+        ...     source="/app/plugins",
+        ...     total_discovered=5,
+        ...     total_loaded=4,
+        ...     total_failed=1,
+        ...     loaded_plugins=[
+        ...         {"name": "auth.plugin", "class": "AuthPlugin", "module": "app.plugins.auth"},
+        ...     ],
+        ...     failed_plugins=[ModelFailedPluginLoad(...)],
+        ...     duration_seconds=0.23,
+        ...     correlation_id=uuid4(),
+        ...     completed_at=datetime.now(UTC),
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    operation: str = Field(
+        ...,
+        min_length=1,
+        description="Type of load operation performed",
+    )
+    source: str = Field(
+        ...,
+        description="Source path or patterns used for discovery",
+    )
+    total_discovered: int = Field(
+        ...,
+        ge=0,
+        description="Total number of contract files discovered",
+    )
+    total_loaded: int = Field(
+        ...,
+        ge=0,
+        description="Number of plugins successfully loaded",
+    )
+    total_failed: int = Field(
+        ...,
+        ge=0,
+        description="Number of plugins that failed to load",
+    )
+    loaded_plugins: list[dict[str, str]] = Field(
+        default_factory=list,
+        description="List of loaded plugin details (name, class, module)",
+    )
+    failed_plugins: list[ModelFailedPluginLoad] = Field(
+        default_factory=list,
+        description="List of failed plugin details with error information",
+    )
+    duration_seconds: float = Field(
+        ...,
+        ge=0.0,
+        description="Total operation time in seconds",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for distributed tracing",
+    )
+    completed_at: datetime = Field(
+        ...,
+        description="Timestamp when the operation completed",
+    )
+
+
+__all__ = ["ModelPluginLoadSummary"]

omnibase_infra/models/security/__init__.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Security models for handler policy validation.
+
+This module exports security-related models for the two-layer handler
+security validation system (OMN-1098). These models define:
+
+1. Handler-declared security policies (what a handler needs)
+2. Environment-level constraints (what an environment permits)
+3. Validation results with errors and warnings (OMN-1137)
+
+The security validation system uses these models to:
+- Validate handler security requirements at registration time
+- Enforce security constraints at invocation time
+- Provide structured error reporting for violations
+
+See Also:
+    - EnumSecurityRuleId: Security validation rule identifiers
+    - docs/design/HANDLER_SECURITY_VALIDATION.md: Full design documentation
+"""
+
+from omnibase_infra.models.security.classification_levels import (
+    CLASSIFICATION_SECURITY_LEVELS,
+    get_security_level,
+)
+from omnibase_infra.models.security.model_environment_policy import (
+    ModelEnvironmentPolicy,
+)
+from omnibase_infra.models.security.model_handler_security_policy import (
+    ModelHandlerSecurityPolicy,
+)
+from omnibase_infra.models.security.model_security_error import (
+    ModelSecurityError,
+)
+from omnibase_infra.models.security.model_security_validation_result import (
+    ModelSecurityValidationResult,
+)
+from omnibase_infra.models.security.model_security_warning import (
+    ModelSecurityWarning,
+)
+
+__all__ = [
+    "CLASSIFICATION_SECURITY_LEVELS",
+    "ModelEnvironmentPolicy",
+    "ModelHandlerSecurityPolicy",
+    "ModelSecurityError",
+    "ModelSecurityValidationResult",
+    "ModelSecurityWarning",
+    "get_security_level",
+]

omnibase_infra/models/security/classification_levels.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Shared classification security level mapping.
+
+This module provides a single source of truth for data classification
+security level mappings. Both registration-time validation and
+invocation-time enforcement use this shared mapping to ensure
+consistent security decisions.
+
+Usage:
+    >>> from omnibase_infra.models.security.classification_levels import (
+    ...     CLASSIFICATION_SECURITY_LEVELS,
+    ...     get_security_level,
+    ... )
+    >>> from omnibase_core.enums import EnumDataClassification
+    >>>
+    >>> level = get_security_level(EnumDataClassification.INTERNAL)
+    >>> level
+    2
+
+Security Level Hierarchy (lowest to highest):
+    0: PUBLIC, OPEN (publicly accessible)
+    1: UNCLASSIFIED (not classified but not public)
+    2: INTERNAL, PRIVATE (organization internal)
+    3: SENSITIVE (requires extra handling)
+    4: CONFIDENTIAL (business confidential)
+    5: RESTRICTED, CLASSIFIED (restricted access)
+    6: SECRET (secret clearance required)
+    7: TOP_SECRET (highest classification)
+
+Note:
+    This module is intentionally simple with no external dependencies
+    beyond omnibase_core.enums to prevent circular imports.
+
+See Also:
+    - RegistrationSecurityValidator: Uses this for registration-time checks
+    - InvocationSecurityEnforcer: Uses this for runtime enforcement
+    - EnumDataClassification: The classification enum values
+"""
+
+from __future__ import annotations
+
+from omnibase_core.enums import EnumDataClassification
+
+# Security level mapping for data classification comparison.
+# Higher values indicate more sensitive/restricted data.
+# This ordering reflects standard data classification hierarchies.
+#
+# IMPORTANT: This is the SINGLE SOURCE OF TRUTH for classification levels.
+# Both registration_security_validator.py and invocation_security_enforcer.py
+# MUST use this mapping to ensure consistent security decisions.
+CLASSIFICATION_SECURITY_LEVELS: dict[EnumDataClassification, int] = {
+    EnumDataClassification.PUBLIC: 0,
+    EnumDataClassification.OPEN: 0,
+    EnumDataClassification.UNCLASSIFIED: 1,
+    EnumDataClassification.INTERNAL: 2,
+    EnumDataClassification.PRIVATE: 2,
+    EnumDataClassification.SENSITIVE: 3,
+    EnumDataClassification.CONFIDENTIAL: 4,
+    EnumDataClassification.RESTRICTED: 5,
+    EnumDataClassification.CLASSIFIED: 5,
+    EnumDataClassification.SECRET: 6,
+    EnumDataClassification.TOP_SECRET: 7,
+}
+
+
+def get_security_level(classification: EnumDataClassification) -> int:
+    """Get numeric security level for a data classification.
+
+    This function provides consistent security level lookups for both
+    registration-time validation and invocation-time enforcement.
+
+    Args:
+        classification: The data classification enum value.
+
+    Returns:
+        Integer security level (higher = more sensitive).
+        Range is 0 (PUBLIC) to 7 (TOP_SECRET).
+
+    Raises:
+        KeyError: If the classification is not in the mapping.
+            This should not happen with valid EnumDataClassification values.
+
+    Example:
+        >>> from omnibase_core.enums import EnumDataClassification
+        >>> get_security_level(EnumDataClassification.PUBLIC)
+        0
+        >>> get_security_level(EnumDataClassification.CONFIDENTIAL)
+        4
+        >>> get_security_level(EnumDataClassification.TOP_SECRET)
+        7
+    """
+    return CLASSIFICATION_SECURITY_LEVELS[classification]
+
+
+__all__ = [
+    "CLASSIFICATION_SECURITY_LEVELS",
+    "get_security_level",
+]

omnibase_infra/models/security/model_environment_policy.py

@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Environment-level security policy model.
+
+This module defines the security constraints that apply at the environment
+level. These constraints determine what security capabilities handlers
+are permitted to request in each deployment environment.
+
+Environment Policy Components:
+    - Permitted secret scopes: What secrets can be accessed
+    - Maximum data classification: Highest sensitivity level allowed
+    - Outbound domain constraints: Network access restrictions
+    - Adapter overrides: Special rules for adapter handlers
+
+Validation Flow:
+    1. Handler declares security policy (ModelHandlerSecurityPolicy)
+    2. Environment policy defines constraints (ModelEnvironmentPolicy)
+    3. Registration validates handler policy against environment constraints
+    4. Runtime enforces declared policy at invocation time
+
+See Also:
+    - ModelHandlerSecurityPolicy: Handler-declared security requirements
+    - EnumSecurityRuleId: Security validation rule identifiers
+    - EnumEnvironment: Deployment environment classification
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.enums import EnumDataClassification
+from omnibase_infra.enums import EnumEnvironment
+
+
+class ModelEnvironmentPolicy(BaseModel):
+    """Environment-level security constraints.
+
+    Defines what security capabilities are permitted in a given environment.
+    Used to validate handler security policies at registration time.
+
+    Environment Hierarchy (most to least permissive):
+        1. DEVELOPMENT - Most permissive, allows debugging features
+        2. CI - Automated testing, some elevated permissions
+        3. STAGING - Production-like with some relaxations
+        4. PRODUCTION - Most restrictive, full security enforcement
+
+    Constraint Types:
+        - Allowlists: Define what IS permitted (secret scopes, domains)
+        - Maximums: Define upper bounds (data classification)
+        - Requirements: Define what handlers MUST declare (domain allowlists)
+        - Overrides: Special rules for specific handler types (adapters)
+
+    Attributes:
+        environment: Target deployment environment.
+        permitted_secret_scopes: Secret scopes permitted in this environment.
+            Handlers requesting scopes not in this set will be rejected.
+        max_data_classification: Maximum data classification allowed.
+            Handlers declaring higher classification will be rejected.
+        allowed_outbound_domains: Reserved for future registration-time domain
+            enforcement. Currently NOT validated at registration time. This field
+            is intended for future validation where handlers requesting domains
+            not in this list would be rejected (unless None/unrestricted).
+            None means unrestricted, empty list would mean no outbound access.
+            Note: Handler-level domain allowlists (allowed_domains) ARE validated
+            via require_explicit_domain_allowlist constraint.
+        require_explicit_domain_allowlist: Whether handlers must declare
+            explicit domain allowlists. When True, handlers with empty
+            domain lists or ["*"] will be rejected.
+        adapter_secrets_override_allowed: Whether adapters can request
+            secrets. Usually False - adapters should use injected credentials.
+
+    Example:
+        >>> # Production environment with strict constraints
+        >>> prod_policy = ModelEnvironmentPolicy(
+        ...     environment=EnumEnvironment.PRODUCTION,
+        ...     permitted_secret_scopes=frozenset({
+        ...         "database/readonly",
+        ...         "api/service-account",
+        ...     }),
+        ...     max_data_classification=EnumDataClassification.CONFIDENTIAL,
+        ...     allowed_outbound_domains=[
+        ...         "api.internal.example.com",
+        ...         "metrics.internal.example.com",
+        ...     ],
+        ...     require_explicit_domain_allowlist=True,
+        ...     adapter_secrets_override_allowed=False,
+        ... )
+
+        >>> # Development environment with relaxed constraints
+        >>> dev_policy = ModelEnvironmentPolicy(
+        ...     environment=EnumEnvironment.DEVELOPMENT,
+        ...     permitted_secret_scopes=frozenset({"*"}),  # All scopes
+        ...     max_data_classification=EnumDataClassification.TOP_SECRET,
+        ...     allowed_outbound_domains=None,  # Unrestricted
+        ...     require_explicit_domain_allowlist=False,
+        ...     adapter_secrets_override_allowed=True,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+    )
+
+    environment: EnumEnvironment = Field(
+        description="Target environment",
+    )
+
+    permitted_secret_scopes: frozenset[str] = Field(
+        default_factory=frozenset,
+        description="Secret scopes permitted in this environment",
+    )
+
+    max_data_classification: EnumDataClassification = Field(
+        default=EnumDataClassification.INTERNAL,
+        description="Maximum data classification allowed",
+    )
+
+    allowed_outbound_domains: list[str] | None = Field(
+        default=None,
+        description=(
+            "Reserved for future registration-time domain enforcement. "
+            "Currently NOT validated - see require_explicit_domain_allowlist "
+            "for handler-level domain validation. None = unrestricted."
+        ),
+    )
+
+    require_explicit_domain_allowlist: bool = Field(
+        default=False,
+        description="Whether handlers must declare explicit domain allowlists",
+    )
+
+    adapter_secrets_override_allowed: bool = Field(
+        default=False,
+        description=(
+            "Whether adapters can request secrets directly (usually False). "
+            "SECURITY WARNING: Enabling in production violates least-privilege "
+            "principles. Adapters should use platform secret management (e.g., Vault) "
+            "rather than direct secret access. Only enable for development/testing "
+            "environments where secret isolation is less critical."
+        ),
+    )
+
+
+__all__ = ["ModelEnvironmentPolicy"]

omnibase_infra/models/security/model_handler_security_policy.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler-declared security policy model.
+
+This module defines the security policy that handlers declare at registration
+time. The policy specifies what security capabilities the handler requires,
+including secret access, network access, and data classification levels.
+
+Security Policy Components:
+    - Secret scopes: What secrets the handler needs access to
+    - Network access: What domains the handler may contact
+    - Data classification: Maximum data sensitivity level processed
+    - Adapter tag: Whether this is a platform adapter (stricter rules)
+
+Validation:
+    Security policies are validated against environment constraints at
+    registration time. See ModelEnvironmentPolicy for environment-level
+    constraints.
+
+See Also:
+    - ModelEnvironmentPolicy: Environment-level security constraints
+    - EnumSecurityRuleId: Security validation rule identifiers
+    - EnumHandlerTypeCategory: Handler behavioral classification
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.enums import EnumDataClassification
+from omnibase_infra.enums import EnumHandlerTypeCategory
+
+
+class ModelHandlerSecurityPolicy(BaseModel):
+    """Security policy declared by a handler in its contract.
+
+    This model captures the security requirements and constraints
+    that a handler declares at registration time. The policy is
+    validated against environment constraints before the handler
+    is permitted to register.
+
+    Security Requirements:
+        Handlers must declare ALL security capabilities they require.
+        Any undeclared capability will be denied at runtime.
+
+    Adapter Handlers:
+        Handlers marked as adapters (is_adapter=True) have stricter
+        security constraints:
+        - Cannot request secret scopes (must use injected credentials)
+        - Must be EFFECT category (adapters perform I/O)
+        - May require explicit domain allowlists in production
+
+    Attributes:
+        secret_scopes: Secret scopes this handler requires access to.
+            Empty set means no secret access needed.
+        allowed_domains: Outbound domains this handler may access.
+            Empty list means no outbound access. Use ["*"] for unrestricted
+            (only permitted in development).
+        data_classification: Maximum data classification this handler
+            processes. Cannot exceed environment maximum.
+        is_adapter: Whether this is an adapter handler (platform plumbing).
+            Adapters have stricter security rules applied.
+        handler_type_category: Behavioral classification of the handler.
+            Required when is_adapter=True (must be EFFECT).
+
+    Example:
+        >>> policy = ModelHandlerSecurityPolicy(
+        ...     secret_scopes=frozenset({"database/readonly"}),
+        ...     allowed_domains=["api.internal.example.com"],
+        ...     data_classification=EnumDataClassification.CONFIDENTIAL,
+        ...     is_adapter=False,
+        ...     handler_type_category=EnumHandlerTypeCategory.EFFECT,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+    )
+
+    secret_scopes: frozenset[str] = Field(
+        default_factory=frozenset,
+        description="Secret scopes this handler requires access to",
+    )
+
+    allowed_domains: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Outbound domains this handler may access (immutable tuple)",
+    )
+
+    data_classification: EnumDataClassification = Field(
+        default=EnumDataClassification.INTERNAL,
+        description="Maximum data classification this handler processes",
+    )
+
+    is_adapter: bool = Field(
+        default=False,
+        description="Whether this is an adapter handler (stricter security rules)",
+    )
+
+    handler_type_category: EnumHandlerTypeCategory | None = Field(
+        default=None,
+        description="Behavioral classification of the handler",
+    )
+
+
+__all__ = ["ModelHandlerSecurityPolicy"]