mcp-eregistrations-bpa 0.8.5__py3-none-any.whl

mcp_eregistrations_bpa/audit/logger.py

@@ -0,0 +1,236 @@
+"""Audit logger for tracking BPA operations."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from mcp_eregistrations_bpa.audit.models import AuditEntry, AuditStatus
+from mcp_eregistrations_bpa.db import get_connection
+
+
+class AuditEntryNotFoundError(Exception):
+    """Raised when an audit entry is not found."""
+
+    pass
+
+
+class AuditEntryImmutableError(Exception):
+    """Raised when attempting to modify a finalized audit entry."""
+
+    pass
+
+
+class AuditLogger:
+    """Append-only audit logger for BPA operations.
+
+    This logger implements the audit-before-write pattern:
+    1. Call record_pending() BEFORE executing the BPA operation
+    2. Call mark_success() or mark_failed() AFTER the operation completes
+
+    The audit log is append-only (NFR5): entries can only be created and
+    their status updated, never deleted or modified otherwise.
+    """
+
+    def __init__(self, db_path: Path | None = None):
+        """Initialize the audit logger.
+
+        Args:
+            db_path: Optional path to SQLite database. If None, uses default.
+        """
+        self._db_path = db_path
+
+    async def record_pending(
+        self,
+        user_email: str,
+        operation_type: str,
+        object_type: str,
+        params: dict[str, Any],
+        object_id: str | None = None,
+    ) -> str:
+        """Record a pending operation BEFORE execution.
+
+        This method MUST be called before executing any BPA write operation.
+        It creates an audit entry with status='pending' that will be updated
+        after the operation completes.
+
+        Args:
+            user_email: Email of the user performing the operation
+            operation_type: Type (create, update, delete, link, unlink)
+            object_type: Type (service, registration, field, determinant, action)
+            params: Parameters passed to the operation
+            object_id: Optional ID of the object being operated on
+
+        Returns:
+            The audit entry ID (UUID string) for use with mark_success/mark_failed
+        """
+        entry = AuditEntry.create(
+            user_email=user_email,
+            operation_type=operation_type,
+            object_type=object_type,
+            params=params,
+            object_id=object_id,
+        )
+
+        async with get_connection(self._db_path) as conn:
+            await conn.execute(
+                """
+                INSERT INTO audit_logs (
+                    id, timestamp, user_email, operation_type, object_type,
+                    object_id, params, status, result, rollback_state_id
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    entry.id,
+                    entry.timestamp,
+                    entry.user_email,
+                    entry.operation_type,
+                    entry.object_type,
+                    entry.object_id,
+                    json.dumps(entry.params),
+                    entry.status.value,
+                    None,
+                    None,
+                ),
+            )
+            await conn.commit()
+
+        return entry.id
+
+    async def mark_success(self, audit_id: str, result: dict[str, Any]) -> None:
+        """Mark operation as successful with result summary.
+
+        Args:
+            audit_id: The audit entry ID returned by record_pending()
+            result: Summary of the operation result (e.g., created object ID)
+
+        Raises:
+            AuditEntryNotFoundError: If audit_id does not exist.
+            AuditEntryImmutableError: If entry is not in PENDING status.
+        """
+        async with get_connection(self._db_path) as conn:
+            # Check current status (append-only enforcement)
+            cursor = await conn.execute(
+                "SELECT status FROM audit_logs WHERE id = ?",
+                (audit_id,),
+            )
+            row = await cursor.fetchone()
+            if row is None:
+                raise AuditEntryNotFoundError(f"Audit entry '{audit_id}' not found")
+            if row["status"] != AuditStatus.PENDING.value:
+                raise AuditEntryImmutableError(
+                    f"Cannot modify audit entry with status '{row['status']}'. "
+                    "Only PENDING entries can be updated."
+                )
+
+            await conn.execute(
+                "UPDATE audit_logs SET status = ?, result = ? WHERE id = ?",
+                (AuditStatus.SUCCESS.value, json.dumps(result), audit_id),
+            )
+            await conn.commit()
+
+    async def mark_failed(self, audit_id: str, error_message: str) -> None:
+        """Mark operation as failed with error details.
+
+        Args:
+            audit_id: The audit entry ID returned by record_pending()
+            error_message: Description of the error that occurred
+
+        Raises:
+            AuditEntryNotFoundError: If audit_id does not exist.
+            AuditEntryImmutableError: If entry is not in PENDING status.
+        """
+        async with get_connection(self._db_path) as conn:
+            # Check current status (append-only enforcement)
+            cursor = await conn.execute(
+                "SELECT status FROM audit_logs WHERE id = ?",
+                (audit_id,),
+            )
+            row = await cursor.fetchone()
+            if row is None:
+                raise AuditEntryNotFoundError(f"Audit entry '{audit_id}' not found")
+            if row["status"] != AuditStatus.PENDING.value:
+                raise AuditEntryImmutableError(
+                    f"Cannot modify audit entry with status '{row['status']}'. "
+                    "Only PENDING entries can be updated."
+                )
+
+            await conn.execute(
+                "UPDATE audit_logs SET status = ?, result = ? WHERE id = ?",
+                (
+                    AuditStatus.FAILED.value,
+                    json.dumps({"error": error_message}),
+                    audit_id,
+                ),
+            )
+            await conn.commit()
+
+    async def save_rollback_state(
+        self,
+        audit_id: str,
+        object_type: str,
+        object_id: str,
+        previous_state: dict[str, Any],
+    ) -> str:
+        """Save rollback state for an audit entry.
+
+        This enables rollback capability for update/delete operations by
+        storing the previous state of the object before changes were made.
+
+        Args:
+            audit_id: The audit entry ID to associate the rollback state with.
+            object_type: Type of object (service, registration, etc.).
+            object_id: ID of the object.
+            previous_state: The object state before the operation.
+
+        Returns:
+            The rollback state ID (UUID string).
+        """
+        import uuid
+
+        rollback_state_id = str(uuid.uuid4())
+
+        async with get_connection(self._db_path) as conn:
+            # Insert rollback state
+            await conn.execute(
+                """
+                INSERT INTO rollback_states (
+                    id, audit_log_id, object_type, object_id, previous_state
+                ) VALUES (?, ?, ?, ?, ?)
+                """,
+                (
+                    rollback_state_id,
+                    audit_id,
+                    object_type,
+                    object_id,
+                    json.dumps(previous_state),
+                ),
+            )
+            # Update audit entry with rollback_state_id
+            await conn.execute(
+                "UPDATE audit_logs SET rollback_state_id = ? WHERE id = ?",
+                (rollback_state_id, audit_id),
+            )
+            await conn.commit()
+
+        return rollback_state_id
+
+    async def get_entry(self, audit_id: str) -> AuditEntry | None:
+        """Retrieve audit entry by ID.
+
+        Args:
+            audit_id: The audit entry ID to retrieve
+
+        Returns:
+            The AuditEntry if found, None otherwise
+        """
+        async with get_connection(self._db_path) as conn:
+            cursor = await conn.execute(
+                "SELECT * FROM audit_logs WHERE id = ?",
+                (audit_id,),
+            )
+            row = await cursor.fetchone()
+            if row is None:
+                return None
+            return AuditEntry.from_row(dict(row))

mcp_eregistrations_bpa/audit/models.py

@@ -0,0 +1,131 @@
+"""Audit models for tracking BPA operations."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+
+class AuditStatus(str, Enum):
+    """Status of an audit log entry."""
+
+    PENDING = "pending"
+    SUCCESS = "success"
+    FAILED = "failed"
+
+
+class OperationType(str, Enum):
+    """Type of operation being audited."""
+
+    CREATE = "create"
+    UPDATE = "update"
+    DELETE = "delete"
+    LINK = "link"
+    UNLINK = "unlink"
+
+
+class ObjectType(str, Enum):
+    """Type of object being operated on."""
+
+    SERVICE = "service"
+    REGISTRATION = "registration"
+    FIELD = "field"
+    DETERMINANT = "determinant"
+    ACTION = "action"
+
+
+@dataclass
+class AuditEntry:
+    """Represents a single audit log entry for a BPA operation.
+
+    Audit entries are created BEFORE operations execute (with status='pending')
+    and updated AFTER completion (with status='success' or 'failed').
+    """
+
+    id: str
+    timestamp: str
+    user_email: str
+    operation_type: str
+    object_type: str
+    params: dict[str, Any]
+    status: AuditStatus = AuditStatus.PENDING
+    object_id: str | None = None
+    result: dict[str, Any] | None = None
+    rollback_state_id: str | None = None
+
+    @classmethod
+    def create(
+        cls,
+        user_email: str,
+        operation_type: str,
+        object_type: str,
+        params: dict[str, Any],
+        object_id: str | None = None,
+    ) -> AuditEntry:
+        """Factory method for creating new audit entries.
+
+        Args:
+            user_email: Email of the user performing the operation
+            operation_type: Type (create, update, delete, link, unlink)
+            object_type: Type (service, registration, field, determinant, action)
+            params: Parameters passed to the operation
+            object_id: Optional ID of the object being operated on
+
+        Returns:
+            A new AuditEntry with generated UUID and timestamp
+        """
+        return cls(
+            id=str(uuid.uuid4()),
+            timestamp=datetime.now(UTC).isoformat(),
+            user_email=user_email,
+            operation_type=operation_type,
+            object_type=object_type,
+            params=params,
+            object_id=object_id,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dict for database storage.
+
+        Returns:
+            Dictionary with all fields, params/result serialized as JSON strings
+        """
+        return {
+            "id": self.id,
+            "timestamp": self.timestamp,
+            "user_email": self.user_email,
+            "operation_type": self.operation_type,
+            "object_type": self.object_type,
+            "object_id": self.object_id,
+            "params": json.dumps(self.params),
+            "status": self.status.value,
+            "result": json.dumps(self.result) if self.result else None,
+            "rollback_state_id": self.rollback_state_id,
+        }
+
+    @classmethod
+    def from_row(cls, row: dict[str, Any]) -> AuditEntry:
+        """Create from database row.
+
+        Args:
+            row: Dictionary with database column values
+
+        Returns:
+            AuditEntry instance with deserialized data
+        """
+        return cls(
+            id=row["id"],
+            timestamp=row["timestamp"],
+            user_email=row["user_email"],
+            operation_type=row["operation_type"],
+            object_type=row["object_type"],
+            object_id=row["object_id"],
+            params=json.loads(row["params"]),
+            status=AuditStatus(row["status"]),
+            result=json.loads(row["result"]) if row["result"] else None,
+            rollback_state_id=row["rollback_state_id"],
+        )

mcp_eregistrations_bpa/auth/__init__.py

@@ -0,0 +1,64 @@
+"""Authentication module for Keycloak OIDC and CAS.
+
+This module provides authentication for both:
+- Keycloak: OIDC/PKCE authentication (modern BPA systems)
+- CAS: OAuth2 Basic Auth authentication (legacy BPA systems)
+
+Both flows include browser-based login, token management, automatic refresh,
+and permission enforcement.
+
+Permission enforcement usage in MCP tools:
+    @mcp.tool()
+    async def service_create(name: str) -> dict[str, object]:
+        # Ensure write permission before proceeding
+        access_token = await ensure_write_permission()
+        # ... use access_token for BPA API call
+"""
+
+from mcp_eregistrations_bpa.auth.callback import CallbackServer
+from mcp_eregistrations_bpa.auth.cas import perform_cas_browser_login
+from mcp_eregistrations_bpa.auth.oidc import (
+    OIDCConfig,
+    build_authorization_url,
+    discover_oidc_config,
+    generate_pkce_pair,
+    generate_state,
+    perform_browser_login,
+)
+from mcp_eregistrations_bpa.auth.permissions import (
+    PERMISSION_SERVICE_DESIGNER,
+    PERMISSION_VIEWER,
+    WRITE_PERMISSIONS,
+    check_permission,
+    ensure_authenticated,
+    ensure_write_permission,
+)
+from mcp_eregistrations_bpa.auth.token_manager import (
+    TokenManager,
+    TokenResponse,
+    exchange_code_for_tokens,
+)
+
+__all__ = [
+    # OIDC (Keycloak)
+    "OIDCConfig",
+    "discover_oidc_config",
+    "generate_pkce_pair",
+    "generate_state",
+    "build_authorization_url",
+    "perform_browser_login",
+    "CallbackServer",
+    # CAS (Legacy)
+    "perform_cas_browser_login",
+    # Token management
+    "TokenManager",
+    "TokenResponse",
+    "exchange_code_for_tokens",
+    # Permissions
+    "PERMISSION_VIEWER",
+    "PERMISSION_SERVICE_DESIGNER",
+    "WRITE_PERMISSIONS",
+    "ensure_authenticated",
+    "ensure_write_permission",
+    "check_permission",
+]