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

mcp_eregistrations_bpa/config.py

@@ -0,0 +1,349 @@
+"""Configuration management for MCP server.
+
+Loads configuration from environment variables only.
+
+Supports two authentication providers:
+- Keycloak: Standard OIDC with PKCE (default)
+- CAS: Legacy eRegistrations OAuth2 server (no PKCE, Basic Auth)
+
+Instance Isolation:
+Each BPA instance gets its own data directory based on hostname.
+This ensures tokens, audit logs, and rollback states are isolated.
+"""
+
+import hashlib
+import os
+import re
+from enum import Enum
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, Field, SecretStr, field_validator, model_validator
+
+from mcp_eregistrations_bpa.exceptions import ConfigurationError
+
+
+class AuthProvider(str, Enum):
+    """Authentication provider type."""
+
+    KEYCLOAK = "keycloak"  # Standard OIDC with PKCE
+    CAS = "cas"  # Legacy eRegistrations OAuth2 (no PKCE, Basic Auth)
+
+
+# XDG-compliant data directory
+CONFIG_DIR = Path.home() / ".config" / "mcp-eregistrations-bpa"
+
+
+def _generate_instance_slug(url: str) -> str:
+    """Generate a filesystem-safe slug from a BPA instance URL.
+
+    Creates a human-readable identifier from the hostname, plus a short hash
+    for uniqueness. Format: {sanitized_hostname}-{short_hash}
+
+    Examples:
+        https://bpa.dev.els.eregistrations.org -> els-dev-a1b2c3
+        https://bpa.test.cuba.eregistrations.org -> cuba-test-d4e5f6
+
+    Args:
+        url: The BPA instance URL.
+
+    Returns:
+        A filesystem-safe slug like "els-dev-a1b2c3".
+    """
+    parsed = urlparse(url)
+    hostname = parsed.netloc or parsed.path  # Handle edge cases
+
+    # Extract meaningful parts from hostname
+    # e.g., "bpa.dev.els.eregistrations.org" ->
+    # ["bpa", "dev", "els", "eregistrations", "org"]
+    parts = hostname.lower().split(".")
+
+    # Remove common prefixes/suffixes for cleaner slug
+    skip_parts = {"bpa", "eregistrations", "org", "com", "www"}
+    meaningful_parts = [p for p in parts if p not in skip_parts and p]
+
+    # Build readable slug (reversed to get country/env first: "els-dev")
+    if meaningful_parts:
+        slug_base = "-".join(reversed(meaningful_parts[:2]))  # Max 2 parts
+    else:
+        slug_base = "default"
+
+    # Add short hash for uniqueness (handles edge cases)
+    url_hash = hashlib.sha256(url.encode()).hexdigest()[:6]
+    slug = f"{slug_base}-{url_hash}"
+
+    # Sanitize: only allow alphanumeric and hyphens
+    slug = re.sub(r"[^a-z0-9-]", "-", slug)
+    slug = re.sub(r"-+", "-", slug).strip("-")
+
+    return slug
+
+
+def get_instance_data_dir(bpa_url: str | None = None) -> Path:
+    """Get the instance-specific data directory.
+
+    Each BPA instance gets its own subdirectory under CONFIG_DIR.
+    This isolates databases, tokens, and logs per instance.
+
+    Args:
+        bpa_url: BPA instance URL. If None, reads from environment.
+
+    Returns:
+        Path to instance-specific data directory.
+        Falls back to CONFIG_DIR if no URL configured.
+        Creates the directory if it doesn't exist.
+    """
+    if bpa_url is None:
+        bpa_url = os.environ.get("BPA_INSTANCE_URL")
+
+    if not bpa_url:
+        # Fallback to base config dir (backward compatible)
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        return CONFIG_DIR
+
+    slug = _generate_instance_slug(bpa_url)
+    instance_dir = CONFIG_DIR / "instances" / slug
+    instance_dir.mkdir(parents=True, exist_ok=True)
+    return instance_dir
+
+
+@lru_cache(maxsize=1)
+def get_current_instance_id() -> str | None:
+    """Get the instance ID for the current BPA instance (cached).
+
+    Returns:
+        Instance slug or None if not configured.
+    """
+    bpa_url = os.environ.get("BPA_INSTANCE_URL")
+    if not bpa_url:
+        return None
+    return _generate_instance_slug(bpa_url)
+
+
+class Config(BaseModel):
+    """MCP server configuration."""
+
+    bpa_instance_url: str
+
+    # Keycloak configuration (standard OIDC with PKCE)
+    keycloak_client_id: str = "mcp-eregistrations-bpa"
+    keycloak_url: str | None = None
+    keycloak_realm: str | None = None
+
+    # CAS configuration (legacy eRegistrations OAuth2)
+    cas_url: str | None = None
+    cas_client_id: str | None = None
+    cas_client_secret: SecretStr | None = Field(
+        default=None, repr=False
+    )  # Required for CAS (no PKCE)
+    cas_callback_port: int = 8914  # Fixed port for CAS redirect_uri
+    partc_url: str | None = None  # For fetching user roles
+
+    @field_validator("bpa_instance_url", "keycloak_url", "cas_url", "partc_url")
+    @classmethod
+    def validate_https(cls, v: str | None) -> str | None:
+        """Validate that URLs use HTTPS and have valid structure."""
+        if v is None:
+            return None
+        if not v:
+            raise ValueError("URL cannot be empty")
+        if v.startswith("http://"):
+            raise ValueError(
+                "URL must use HTTPS: "
+                "Security requires encrypted connections. "
+                "Update URL to use https:// scheme."
+            )
+        if not v.startswith("https://"):
+            raise ValueError("URL must start with https://")
+        # Validate URL structure
+        parsed = urlparse(v)
+        if not parsed.netloc:
+            raise ValueError("URL must have a valid host")
+        if parsed.query or parsed.fragment:
+            raise ValueError("URL must not contain query string or fragment")
+        return v.rstrip("/")  # Normalize: remove trailing slash
+
+    @model_validator(mode="after")
+    def validate_cas_config(self) -> "Config":
+        """Validate CAS configuration if CAS URL is provided."""
+        if self.cas_url:
+            if not self.cas_client_id:
+                raise ValueError(
+                    "CAS_CLIENT_ID required when CAS_URL is set. "
+                    "CAS authentication requires a client ID."
+                )
+            # Check SecretStr: must exist and have non-empty value
+            if (
+                not self.cas_client_secret
+                or not self.cas_client_secret.get_secret_value()
+            ):
+                raise ValueError(
+                    "CAS_CLIENT_SECRET required when CAS_URL is set. "
+                    "CAS uses Basic Auth instead of PKCE."
+                )
+        return self
+
+    @property
+    def auth_provider(self) -> AuthProvider:
+        """Detect authentication provider based on configuration.
+
+        Returns CAS if cas_url is configured, otherwise Keycloak.
+        """
+        if self.cas_url:
+            return AuthProvider.CAS
+        return AuthProvider.KEYCLOAK
+
+    @property
+    def oidc_discovery_url(self) -> str:
+        """Get the OIDC discovery URL (Keycloak only).
+
+        If keycloak_url and keycloak_realm are provided, constructs
+        the standard Keycloak realm discovery URL. Otherwise, falls
+        back to BPA instance URL for discovery.
+
+        Note: CAS does not support OIDC discovery.
+
+        Returns:
+            The URL for .well-known/openid-configuration discovery.
+        """
+        if self.keycloak_url and self.keycloak_realm:
+            # Standard Keycloak realm URL pattern
+            return f"{self.keycloak_url}/realms/{self.keycloak_realm}"
+        elif self.keycloak_url:
+            # Keycloak URL provided but no realm - use as base
+            return self.keycloak_url
+        else:
+            # Default: assume OIDC discovery at BPA URL
+            return self.bpa_instance_url
+
+    @property
+    def cas_authorization_url(self) -> str | None:
+        """Get the CAS authorization URL (CAS only).
+
+        Returns:
+            The CAS SPA authorization URL, or None if not using CAS.
+        """
+        if not self.cas_url:
+            return None
+        return f"{self.cas_url}/cas/spa.html"
+
+    @property
+    def cas_token_url(self) -> str | None:
+        """Get the CAS token endpoint URL (CAS only).
+
+        Returns:
+            The CAS token URL, or None if not using CAS.
+        """
+        if not self.cas_url:
+            return None
+        return f"{self.cas_url}/access_token"
+
+    @property
+    def cas_public_key_url(self) -> str | None:
+        """Get the CAS public key URL for JWT validation (CAS only).
+
+        Returns:
+            The CAS public key URL, or None if not using CAS.
+        """
+        if not self.cas_url:
+            return None
+        return f"{self.cas_url}/user/publicKey"
+
+    @property
+    def partc_user_attributes_url(self) -> str | None:
+        """Get the PARTC user attributes URL (CAS only).
+
+        Returns:
+            The PARTC URL for fetching user roles, or None if not configured.
+        """
+        if not self.partc_url:
+            return None
+        return f"{self.partc_url}/user/attributes"
+
+    @property
+    def instance_id(self) -> str:
+        """Get the unique instance ID for this BPA instance.
+
+        Used for data isolation (database, logs, etc.).
+
+        Returns:
+            A filesystem-safe slug like "els-dev-a1b2c3".
+        """
+        return _generate_instance_slug(self.bpa_instance_url)
+
+    @property
+    def instance_data_dir(self) -> Path:
+        """Get the instance-specific data directory.
+
+        Returns:
+            Path to the directory for this instance's data.
+        """
+        return get_instance_data_dir(self.bpa_instance_url)
+
+
+def load_config() -> Config:
+    """Load configuration from environment variables.
+
+    Required environment variables:
+        BPA_INSTANCE_URL: The BPA instance URL (required)
+
+    Optional environment variables:
+        KEYCLOAK_URL: Keycloak server URL
+        KEYCLOAK_REALM: Keycloak realm name
+        KEYCLOAK_CLIENT_ID: Keycloak client ID (default: mcp-eregistrations-bpa)
+        CAS_URL: CAS server URL (for legacy auth)
+        CAS_CLIENT_ID: CAS client ID
+        CAS_CLIENT_SECRET: CAS client secret
+        PARTC_URL: PARTC URL for user attributes
+
+    Returns:
+        Validated Config object.
+
+    Raises:
+        ConfigurationError: If required configuration is missing or invalid.
+    """
+    url = os.environ.get("BPA_INSTANCE_URL")
+
+    if not url:
+        raise ConfigurationError(
+            "BPA_INSTANCE_URL environment variable is required. "
+            "Set it in your MCP server configuration."
+        )
+
+    # Build config from environment variables
+    # Use Any because Pydantic handles type coercion (str -> SecretStr, etc.)
+    config_kwargs: dict[str, Any] = {"bpa_instance_url": url}
+
+    # Keycloak configuration
+    if keycloak_client_id := os.environ.get("KEYCLOAK_CLIENT_ID"):
+        config_kwargs["keycloak_client_id"] = keycloak_client_id
+
+    if keycloak_url := os.environ.get("KEYCLOAK_URL"):
+        config_kwargs["keycloak_url"] = keycloak_url
+
+    if keycloak_realm := os.environ.get("KEYCLOAK_REALM"):
+        config_kwargs["keycloak_realm"] = keycloak_realm
+
+    # CAS configuration
+    if cas_url := os.environ.get("CAS_URL"):
+        config_kwargs["cas_url"] = cas_url
+
+    if cas_client_id := os.environ.get("CAS_CLIENT_ID"):
+        config_kwargs["cas_client_id"] = cas_client_id
+
+    if cas_client_secret := os.environ.get("CAS_CLIENT_SECRET"):
+        config_kwargs["cas_client_secret"] = cas_client_secret
+
+    if partc_url := os.environ.get("PARTC_URL"):
+        config_kwargs["partc_url"] = partc_url
+
+    if cas_callback_port := os.environ.get("CAS_CALLBACK_PORT"):
+        config_kwargs["cas_callback_port"] = int(cas_callback_port)
+
+    # Validate and return config
+    try:
+        return Config(**config_kwargs)
+    except ValueError as e:
+        raise ConfigurationError(str(e)) from e

mcp_eregistrations_bpa/db/__init__.py

@@ -0,0 +1,21 @@
+"""SQLite database module for audit and rollback storage.
+
+This module provides:
+- Connection management with async context manager
+- Schema creation and migration system
+- XDG-compliant database path handling
+
+NFR Compliance:
+- NFR5: Tamper-evident audit logs (append-only design)
+- NFR11: Persist across restarts (SQLite file storage)
+- NFR13: No inconsistent state (transactions)
+"""
+
+from mcp_eregistrations_bpa.db.connection import get_connection, get_db_path
+from mcp_eregistrations_bpa.db.migrations import initialize_database
+
+__all__ = [
+    "get_connection",
+    "get_db_path",
+    "initialize_database",
+]

mcp_eregistrations_bpa/db/connection.py

@@ -0,0 +1,64 @@
+"""SQLite connection management.
+
+Provides instance-aware database path and async connection context manager.
+Each BPA instance gets its own isolated database.
+"""
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+import aiosqlite
+
+from mcp_eregistrations_bpa.config import get_instance_data_dir
+
+
+def get_db_path() -> Path:
+    """Get instance-specific database path.
+
+    Returns the path to the SQLite database file for the current BPA instance.
+    Each instance (El Salvador, Cuba, etc.) gets its own database.
+
+    Path pattern:
+        ~/.config/mcp-eregistrations-bpa/instances/{instance-slug}/data.db
+
+    Falls back to legacy path if no instance configured:
+        ~/.config/mcp-eregistrations-bpa/data.db
+
+    Creates the parent directory if it doesn't exist.
+
+    Returns:
+        Path to the instance-specific database file.
+    """
+    instance_dir = get_instance_data_dir()
+    return instance_dir / "data.db"
+
+
+@asynccontextmanager
+async def get_connection(
+    db_path: Path | None = None,
+) -> AsyncGenerator[aiosqlite.Connection, None]:
+    """Get async SQLite connection with WAL mode and foreign keys enabled.
+
+    Args:
+        db_path: Optional path to database. Defaults to get_db_path() if not provided.
+
+    Yields:
+        Configured aiosqlite connection with Row factory.
+
+    Example:
+        async with get_connection() as conn:
+            cursor = await conn.execute("SELECT * FROM audit_logs")
+            rows = await cursor.fetchall()
+    """
+    if db_path is None:
+        db_path = get_db_path()
+
+    async with aiosqlite.connect(db_path) as conn:
+        # Enable WAL mode for better concurrent access
+        await conn.execute("PRAGMA journal_mode=WAL")
+        # Enable foreign key enforcement
+        await conn.execute("PRAGMA foreign_keys=ON")
+        # Use Row factory for dict-like access
+        conn.row_factory = aiosqlite.Row
+        yield conn

mcp_eregistrations_bpa/db/migrations.py

@@ -0,0 +1,168 @@
+"""Database schema creation and migration system.
+
+Provides versioned schema migrations for audit_logs and rollback_states tables.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import aiosqlite
+
+from mcp_eregistrations_bpa.db.connection import get_connection, get_db_path
+
+# Migration definitions: (version, sql_statements)
+# Each migration is a tuple of (version_number, sql_script)
+# Migrations are applied in order, only if version > current_version
+MIGRATIONS: list[tuple[int, str]] = [
+    (
+        1,
+        """
+        -- Version tracking table
+        CREATE TABLE IF NOT EXISTS schema_version (
+            version INTEGER PRIMARY KEY,
+            applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+
+        -- Audit logs table (NFR5: tamper-evident, append-only)
+        CREATE TABLE IF NOT EXISTS audit_logs (
+            id TEXT PRIMARY KEY,
+            timestamp TEXT NOT NULL,
+            user_email TEXT NOT NULL,
+            operation_type TEXT NOT NULL,
+            object_type TEXT NOT NULL,
+            object_id TEXT,
+            params TEXT NOT NULL,
+            status TEXT NOT NULL DEFAULT 'pending',
+            result TEXT,
+            rollback_state_id TEXT
+        );
+
+        -- Rollback states table
+        CREATE TABLE IF NOT EXISTS rollback_states (
+            id TEXT PRIMARY KEY,
+            audit_log_id TEXT NOT NULL REFERENCES audit_logs(id),
+            object_type TEXT NOT NULL,
+            object_id TEXT NOT NULL,
+            previous_state TEXT NOT NULL,
+            created_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+
+        -- Indexes for common queries
+        CREATE INDEX IF NOT EXISTS idx_audit_logs_timestamp
+            ON audit_logs(timestamp);
+        CREATE INDEX IF NOT EXISTS idx_audit_logs_status
+            ON audit_logs(status);
+        CREATE INDEX IF NOT EXISTS idx_audit_logs_object_type
+            ON audit_logs(object_type);
+        CREATE INDEX IF NOT EXISTS idx_audit_logs_object_id
+            ON audit_logs(object_id);
+        CREATE INDEX IF NOT EXISTS idx_rollback_states_audit_log_id
+            ON rollback_states(audit_log_id);
+        CREATE INDEX IF NOT EXISTS idx_rollback_states_object
+            ON rollback_states(object_type, object_id);
+        """,
+    ),
+    (
+        2,
+        """
+        -- Add index on user_email for filtering by user
+        CREATE INDEX IF NOT EXISTS idx_audit_logs_user_email
+            ON audit_logs(user_email);
+        """,
+    ),
+    # Future migrations go here as (version, sql) tuples
+]
+
+
+async def get_schema_version(conn: aiosqlite.Connection) -> int:
+    """Get the current schema version from the database.
+
+    Args:
+        conn: Active database connection.
+
+    Returns:
+        Current schema version number, or 0 if no version table exists.
+    """
+    try:
+        cursor = await conn.execute("SELECT MAX(version) FROM schema_version")
+        row = await cursor.fetchone()
+        if row and row[0] is not None:
+            version: int = row[0]
+            return version
+        return 0
+    except aiosqlite.OperationalError:
+        # Table doesn't exist yet
+        return 0
+
+
+async def apply_migrations(conn: aiosqlite.Connection) -> int:
+    """Apply pending migrations in order.
+
+    Args:
+        conn: Active database connection.
+
+    Returns:
+        Number of migrations applied.
+
+    Raises:
+        aiosqlite.Error: If migration fails.
+    """
+    current_version = await get_schema_version(conn)
+    migrations_applied = 0
+
+    for version, sql in MIGRATIONS:
+        if version > current_version:
+            # Execute the migration script
+            await conn.executescript(sql)
+            # Record the applied migration
+            await conn.execute(
+                "INSERT INTO schema_version (version) VALUES (?)",
+                (version,),
+            )
+            await conn.commit()
+            migrations_applied += 1
+
+    return migrations_applied
+
+
+async def initialize_database(db_path: Path | None = None) -> dict[str, Any]:
+    """Initialize the database with all required tables and indexes.
+
+    This is the main entry point for database setup. It should be called
+    during MCP server startup.
+
+    Args:
+        db_path: Optional path to database. Defaults to get_db_path() if not provided.
+
+    Returns:
+        Dictionary with initialization results:
+        - db_path: Path to the database file
+        - schema_version: Current schema version after initialization
+        - migrations_applied: Number of migrations applied
+        - tables_created: List of tables in the database
+
+    Example:
+        result = await initialize_database()
+        print(f"Database at {result['db_path']}")
+        print(f"Schema version: {result['schema_version']}")
+    """
+    if db_path is None:
+        db_path = get_db_path()
+
+    async with get_connection(db_path) as conn:
+        migrations_applied = await apply_migrations(conn)
+        schema_version = await get_schema_version(conn)
+
+        # Get list of tables
+        cursor = await conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
+        )
+        rows = await cursor.fetchall()
+        tables = [row[0] for row in rows]
+
+    return {
+        "db_path": str(db_path),
+        "schema_version": schema_version,
+        "migrations_applied": migrations_applied,
+        "tables_created": tables,
+    }

mcp_eregistrations_bpa/exceptions.py

@@ -0,0 +1,39 @@
+"""Custom exception hierarchy for MCP server."""
+
+
+class MCPError(Exception):
+    """Base exception for all MCP server errors."""
+
+    pass
+
+
+class ConfigurationError(MCPError):
+    """Raised when configuration is invalid or missing."""
+
+    pass
+
+
+class AuthenticationError(MCPError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class BPAClientError(MCPError):
+    """Raised when BPA API client encounters an error."""
+
+    pass
+
+
+class PermissionDeniedError(MCPError):
+    """Raised when user lacks required permission.
+
+    This is distinct from AuthenticationError which indicates
+    the user is not authenticated at all. PermissionDeniedError means
+    the user is authenticated but lacks specific permissions.
+
+    Note: Named PermissionDeniedError to avoid shadowing Python's
+    built-in PermissionError (an OSError subclass).
+    """
+
+    pass

mcp_eregistrations_bpa/rollback/__init__.py

@@ -0,0 +1,19 @@
+"""Rollback capability module.
+
+This module provides rollback functionality for BPA write operations,
+allowing users to undo changes by restoring objects to their previous state.
+"""
+
+from mcp_eregistrations_bpa.rollback.manager import (
+    ROLLBACK_ENDPOINTS,
+    RollbackError,
+    RollbackManager,
+    RollbackNotPossibleError,
+)
+
+__all__ = [
+    "RollbackManager",
+    "RollbackError",
+    "RollbackNotPossibleError",
+    "ROLLBACK_ENDPOINTS",
+]