omnibase_infra 0.2.6__py3-none-any.whl

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"]

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",
+]