mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/domain/contracts/authorization.py

@@ -0,0 +1,229 @@
+"""Authorization contracts (ports) for the domain layer.
+
+These protocols define the interfaces for authorization components.
+Infrastructure layer provides concrete implementations.
+"""
+
+from abc import abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from ..value_objects import Permission, Principal, Role
+
+
+@dataclass
+class AuthorizationRequest:
+    """Request to check authorization.
+
+    Contains all information needed to make an authorization decision.
+
+    Attributes:
+        principal: The authenticated principal requesting access.
+        action: The action being requested (create, read, update, delete, invoke, etc.).
+        resource_type: Type of resource (provider, tool, config, audit, metrics).
+        resource_id: Specific resource identifier or '*' for any.
+        context: Additional context for policy evaluation (rate limits, time, etc.).
+    """
+
+    principal: Principal
+    action: str
+    resource_type: str
+    resource_id: str
+    context: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.action:
+            raise ValueError("AuthorizationRequest action cannot be empty")
+        if not self.resource_type:
+            raise ValueError("AuthorizationRequest resource_type cannot be empty")
+
+
+@dataclass
+class AuthorizationResult:
+    """Result of authorization check.
+
+    Attributes:
+        allowed: Whether the action is permitted.
+        reason: Human-readable reason for the decision.
+        matched_permission: The permission that granted access (if allowed).
+        matched_role: The role that provided the permission (if allowed).
+    """
+
+    allowed: bool
+    reason: str = ""
+    matched_permission: Permission | None = None
+    matched_role: str | None = None
+
+    @classmethod
+    def allow(
+        cls,
+        reason: str = "",
+        permission: Permission | None = None,
+        role: str | None = None,
+    ) -> "AuthorizationResult":
+        """Create an allow result."""
+        return cls(
+            allowed=True,
+            reason=reason,
+            matched_permission=permission,
+            matched_role=role,
+        )
+
+    @classmethod
+    def deny(cls, reason: str = "") -> "AuthorizationResult":
+        """Create a deny result."""
+        return cls(allowed=False, reason=reason)
+
+
+@runtime_checkable
+class IAuthorizer(Protocol):
+    """Checks if a principal is authorized for an action.
+
+    Authorizers make access control decisions based on:
+    - Principal identity and attributes
+    - Requested action
+    - Target resource
+    - Optional context (rate limits, time-based rules, etc.)
+    """
+
+    @abstractmethod
+    def authorize(self, request: AuthorizationRequest) -> AuthorizationResult:
+        """Check if the principal is authorized.
+
+        Args:
+            request: The authorization request with principal, action, and resource.
+
+        Returns:
+            AuthorizationResult with allowed status and reason.
+
+        Note:
+            This method should never raise exceptions for authorization failures.
+            Authorization denial is represented in the result, not via exceptions.
+        """
+        ...
+
+
+@runtime_checkable
+class IRoleStore(Protocol):
+    """Storage for roles and role assignments.
+
+    Handles:
+    - Role definitions (name -> permissions)
+    - Role assignments (principal -> roles, optionally scoped)
+
+    Roles can be assigned globally or scoped to a tenant/namespace.
+    """
+
+    @abstractmethod
+    def get_role(self, role_name: str) -> Role | None:
+        """Get role by name.
+
+        Args:
+            role_name: Name of the role to retrieve.
+
+        Returns:
+            Role if found, None otherwise.
+        """
+        ...
+
+    @abstractmethod
+    def get_roles_for_principal(
+        self,
+        principal_id: str,
+        scope: str = "*",
+    ) -> list[Role]:
+        """Get all roles assigned to a principal.
+
+        Args:
+            principal_id: ID of the principal.
+            scope: Filter by scope ('*' for all, 'global', 'tenant:X', etc.).
+
+        Returns:
+            List of roles assigned to the principal.
+        """
+        ...
+
+    @abstractmethod
+    def assign_role(
+        self,
+        principal_id: str,
+        role_name: str,
+        scope: str = "global",
+    ) -> None:
+        """Assign a role to a principal.
+
+        Args:
+            principal_id: ID of the principal receiving the role.
+            role_name: Name of the role to assign.
+            scope: Scope of the assignment (global, tenant:X, namespace:Y).
+
+        Raises:
+            ValueError: If role_name doesn't exist.
+        """
+        ...
+
+    @abstractmethod
+    def revoke_role(
+        self,
+        principal_id: str,
+        role_name: str,
+        scope: str = "global",
+    ) -> None:
+        """Revoke a role from a principal.
+
+        Args:
+            principal_id: ID of the principal losing the role.
+            role_name: Name of the role to revoke.
+            scope: Scope from which to revoke (global, tenant:X, namespace:Y).
+        """
+        ...
+
+
+@runtime_checkable
+class IPolicyEngine(Protocol):
+    """External policy engine (e.g., OPA) for complex authorization.
+
+    Used when built-in RBAC is insufficient and complex policies
+    are needed (multi-tenant isolation, time-based access, etc.).
+    """
+
+    @abstractmethod
+    def evaluate(self, input_data: dict[str, Any]) -> AuthorizationResult:
+        """Evaluate policy with given input.
+
+        Args:
+            input_data: Policy input including principal, action, resource, context.
+
+        Returns:
+            AuthorizationResult from policy evaluation.
+
+        Note:
+            Should fail closed (deny) on errors. Never raise exceptions
+            that would bypass authorization.
+        """
+        ...
+
+    @staticmethod
+    def build_input(request: AuthorizationRequest) -> dict[str, Any]:
+        """Build policy engine input from authorization request.
+
+        Args:
+            request: The authorization request.
+
+        Returns:
+            Dictionary formatted for policy engine input.
+        """
+        return {
+            "principal": {
+                "id": request.principal.id.value,
+                "type": request.principal.type.value,
+                "tenant_id": request.principal.tenant_id,
+                "groups": list(request.principal.groups),
+            },
+            "action": request.action,
+            "resource": {
+                "type": request.resource_type,
+                "id": request.resource_id,
+            },
+            "context": request.context,
+        }

mcp_hangar/domain/contracts/event_store.py

@@ -0,0 +1,178 @@
+"""Event Store contract - interface for domain event persistence.
+
+The Event Store provides append-only persistence for domain events,
+enabling Event Sourcing pattern with optimistic concurrency control.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Iterator
+
+from ..events import DomainEvent
+
+
+class ConcurrencyError(Exception):
+    """Raised when optimistic concurrency check fails.
+
+    This occurs when attempting to append events to a stream with
+    an expected version that doesn't match the actual stream version.
+    """
+
+    def __init__(self, stream_id: str, expected: int, actual: int):
+        """Initialize concurrency error.
+
+        Args:
+            stream_id: The stream that had the conflict.
+            expected: Expected version at time of append.
+            actual: Actual version found in store.
+        """
+        self.stream_id = stream_id
+        self.expected = expected
+        self.actual = actual
+        super().__init__(f"Concurrency conflict on stream '{stream_id}': expected version {expected}, actual {actual}")
+
+
+class StreamNotFoundError(Exception):
+    """Raised when attempting to read a non-existent stream."""
+
+    def __init__(self, stream_id: str):
+        self.stream_id = stream_id
+        super().__init__(f"Stream not found: {stream_id}")
+
+
+class IEventStore(ABC):
+    """Interface for domain event persistence.
+
+    Event Store is an append-only log of domain events organized into streams.
+    Each stream represents an aggregate's event history.
+
+    Stream IDs follow convention: "{aggregate_type}:{aggregate_id}"
+    Example: "provider:math", "provider_group:default"
+
+    Version numbers:
+    - -1 means "no stream exists" (for new aggregates)
+    - 0+ is the actual version (count of events - 1)
+    """
+
+    @abstractmethod
+    def append(
+        self,
+        stream_id: str,
+        events: list[DomainEvent],
+        expected_version: int,
+    ) -> int:
+        """Append events to a stream with optimistic concurrency control.
+
+        Events are appended atomically. Either all events are persisted
+        or none are (in case of concurrency conflict).
+
+        Args:
+            stream_id: Identifier of the event stream.
+            events: List of domain events to append.
+            expected_version: Expected current version of stream.
+                Use -1 for new streams (no events yet).
+
+        Returns:
+            New version of the stream after append.
+
+        Raises:
+            ConcurrencyError: When expected_version doesn't match actual.
+        """
+
+    @abstractmethod
+    def read_stream(
+        self,
+        stream_id: str,
+        from_version: int = 0,
+    ) -> list[DomainEvent]:
+        """Read all events from a stream.
+
+        Args:
+            stream_id: Identifier of the event stream.
+            from_version: Start reading from this version (inclusive).
+                Defaults to 0 (read all events).
+
+        Returns:
+            List of domain events in order of occurrence.
+            Empty list if stream doesn't exist.
+        """
+
+    @abstractmethod
+    def read_all(
+        self,
+        from_position: int = 0,
+        limit: int = 1000,
+    ) -> Iterator[tuple[int, str, DomainEvent]]:
+        """Read all events across all streams (for projections).
+
+        Used to build read models by processing all events in order.
+
+        Args:
+            from_position: Global position to start from (exclusive).
+                Use 0 to read from beginning.
+            limit: Maximum number of events to return.
+
+        Yields:
+            Tuples of (global_position, stream_id, event).
+        """
+
+    @abstractmethod
+    def get_stream_version(self, stream_id: str) -> int:
+        """Get current version of a stream.
+
+        Args:
+            stream_id: Identifier of the event stream.
+
+        Returns:
+            Current version number, or -1 if stream doesn't exist.
+        """
+
+    @abstractmethod
+    def list_streams(self, prefix: str = "") -> list[str]:
+        """List all stream IDs, optionally filtered by prefix.
+
+        Args:
+            prefix: Optional prefix to filter streams.
+
+        Returns:
+            List of stream IDs matching the prefix.
+        """
+
+
+class NullEventStore(IEventStore):
+    """Null object implementation - discards all events.
+
+    Use when event persistence is disabled or for testing.
+    """
+
+    def append(
+        self,
+        stream_id: str,
+        events: list[DomainEvent],
+        expected_version: int,
+    ) -> int:
+        """Accept events but don't persist them."""
+        return expected_version + len(events)
+
+    def read_stream(
+        self,
+        stream_id: str,
+        from_version: int = 0,
+    ) -> list[DomainEvent]:
+        """Return empty list (no events persisted)."""
+        return []
+
+    def read_all(
+        self,
+        from_position: int = 0,
+        limit: int = 1000,
+    ) -> Iterator[tuple[int, str, DomainEvent]]:
+        """Yield nothing (no events persisted)."""
+        return iter([])
+
+    def get_stream_version(self, stream_id: str) -> int:
+        """Return -1 (stream doesn't exist)."""
+        return -1
+
+    def list_streams(self, prefix: str = "") -> list[str]:
+        """Return empty list (no streams)."""
+        return []

mcp_hangar/domain/contracts/metrics_publisher.py

@@ -0,0 +1,59 @@
+"""Metrics Publisher contract for domain layer.
+
+This interface allows the domain to publish metrics without depending
+on concrete metrics implementation (Prometheus, statsd, etc.).
+"""
+
+from abc import ABC, abstractmethod
+
+
+class IMetricsPublisher(ABC):
+    """Contract for publishing metrics from domain layer."""
+
+    @abstractmethod
+    def record_cold_start(self, provider_id: str, duration_s: float, mode: str) -> None:
+        """
+        Record a cold start event.
+
+        Args:
+            provider_id: Provider identifier
+            duration_s: Duration of cold start in seconds
+            mode: Provider mode (subprocess, docker, etc.)
+        """
+        pass
+
+    @abstractmethod
+    def begin_cold_start(self, provider_id: str) -> None:
+        """
+        Mark the beginning of a cold start.
+
+        Args:
+            provider_id: Provider identifier
+        """
+        pass
+
+    @abstractmethod
+    def end_cold_start(self, provider_id: str) -> None:
+        """
+        Mark the end of a cold start.
+
+        Args:
+            provider_id: Provider identifier
+        """
+        pass
+
+
+class NullMetricsPublisher(IMetricsPublisher):
+    """Null object pattern implementation that does nothing."""
+
+    def record_cold_start(self, provider_id: str, duration_s: float, mode: str) -> None:
+        """No-op implementation."""
+        pass
+
+    def begin_cold_start(self, provider_id: str) -> None:
+        """No-op implementation."""
+        pass
+
+    def end_cold_start(self, provider_id: str) -> None:
+        """No-op implementation."""
+        pass