mcp-hangar 0.2.0__py3-none-any.whl

mcp_hangar/server/auth_cli.py

@@ -0,0 +1,335 @@
+"""CLI commands for authentication management.
+
+Provides commands for API key management and role assignment.
+
+Usage:
+    # Create an API key
+    mcp-hangar auth create-key --principal user:admin --name "Admin Key" --role admin
+
+    # List keys for a principal
+    mcp-hangar auth list-keys --principal user:admin
+
+    # Revoke a key
+    mcp-hangar auth revoke-key KEY_ID
+
+    # Assign a role
+    mcp-hangar auth assign-role --principal user:dev --role developer
+"""
+
+import argparse
+from datetime import datetime, timedelta, timezone
+import sys
+from typing import Optional
+
+from ..domain.security.roles import list_builtin_roles
+from ..infrastructure.auth.api_key_authenticator import InMemoryApiKeyStore
+from ..infrastructure.auth.rbac_authorizer import InMemoryRoleStore
+
+
+def create_auth_parser(subparsers) -> argparse.ArgumentParser:
+    """Create the auth subparser with all auth commands.
+
+    Args:
+        subparsers: The subparsers object from the main parser.
+
+    Returns:
+        The auth parser.
+    """
+    auth_parser = subparsers.add_parser(
+        "auth",
+        help="Authentication management commands",
+        description="Commands for managing API keys and role assignments.",
+    )
+
+    auth_subparsers = auth_parser.add_subparsers(dest="auth_command", help="Auth commands")
+
+    # create-key command
+    create_key_parser = auth_subparsers.add_parser(
+        "create-key",
+        help="Create a new API key",
+        description="Create a new API key for a principal. The key is only shown once!",
+    )
+    create_key_parser.add_argument(
+        "--principal",
+        required=True,
+        help="Principal ID for the key (e.g., 'user:admin', 'service:ci-pipeline')",
+    )
+    create_key_parser.add_argument(
+        "--name",
+        required=True,
+        help="Human-readable name for the key",
+    )
+    create_key_parser.add_argument(
+        "--role",
+        action="append",
+        default=[],
+        help="Roles to assign (can be repeated)",
+    )
+    create_key_parser.add_argument(
+        "--expires",
+        type=int,
+        help="Expiration in days",
+    )
+    create_key_parser.add_argument(
+        "--tenant",
+        help="Tenant ID for multi-tenancy",
+    )
+
+    # list-keys command
+    list_keys_parser = auth_subparsers.add_parser(
+        "list-keys",
+        help="List API keys for a principal",
+    )
+    list_keys_parser.add_argument(
+        "--principal",
+        required=True,
+        help="Principal ID",
+    )
+
+    # revoke-key command
+    revoke_key_parser = auth_subparsers.add_parser(
+        "revoke-key",
+        help="Revoke an API key",
+    )
+    revoke_key_parser.add_argument(
+        "key_id",
+        help="Key ID to revoke",
+    )
+    revoke_key_parser.add_argument(
+        "--yes",
+        "-y",
+        action="store_true",
+        help="Skip confirmation prompt",
+    )
+
+    # assign-role command
+    assign_role_parser = auth_subparsers.add_parser(
+        "assign-role",
+        help="Assign a role to a principal",
+    )
+    assign_role_parser.add_argument(
+        "--principal",
+        required=True,
+        help="Principal ID",
+    )
+    assign_role_parser.add_argument(
+        "--role",
+        required=True,
+        help="Role name",
+    )
+    assign_role_parser.add_argument(
+        "--scope",
+        default="global",
+        help="Scope (global, tenant:X, namespace:Y)",
+    )
+
+    # revoke-role command
+    revoke_role_parser = auth_subparsers.add_parser(
+        "revoke-role",
+        help="Revoke a role from a principal",
+    )
+    revoke_role_parser.add_argument(
+        "--principal",
+        required=True,
+        help="Principal ID",
+    )
+    revoke_role_parser.add_argument(
+        "--role",
+        required=True,
+        help="Role name",
+    )
+    revoke_role_parser.add_argument(
+        "--scope",
+        default="global",
+        help="Scope",
+    )
+
+    # list-roles command
+    _list_roles_parser = auth_subparsers.add_parser(  # noqa: F841 - used by argparse
+        "list-roles",
+        help="List available built-in roles",
+    )
+
+    return auth_parser
+
+
+def handle_auth_command(args, key_store: InMemoryApiKeyStore, role_store: InMemoryRoleStore) -> int:
+    """Handle auth CLI commands.
+
+    Args:
+        args: Parsed arguments.
+        key_store: API key store.
+        role_store: Role store.
+
+    Returns:
+        Exit code (0 for success, non-zero for errors).
+    """
+    if args.auth_command == "create-key":
+        return _handle_create_key(args, key_store, role_store)
+    elif args.auth_command == "list-keys":
+        return _handle_list_keys(args, key_store)
+    elif args.auth_command == "revoke-key":
+        return _handle_revoke_key(args, key_store)
+    elif args.auth_command == "assign-role":
+        return _handle_assign_role(args, role_store)
+    elif args.auth_command == "revoke-role":
+        return _handle_revoke_role(args, role_store)
+    elif args.auth_command == "list-roles":
+        return _handle_list_roles()
+    else:
+        print(f"Unknown auth command: {args.auth_command}", file=sys.stderr)
+        return 1
+
+
+def _handle_create_key(args, key_store: InMemoryApiKeyStore, role_store: InMemoryRoleStore) -> int:
+    """Handle create-key command."""
+    principal_id = args.principal
+    name = args.name
+    roles = args.role or []
+    expires_days = args.expires
+    tenant_id = args.tenant
+
+    # Calculate expiration
+    expires_at: Optional[datetime] = None
+    if expires_days:
+        expires_at = datetime.now(timezone.utc) + timedelta(days=expires_days)
+
+    # Validate roles exist
+    for role_name in roles:
+        if role_store.get_role(role_name) is None:
+            print(f"Error: Unknown role '{role_name}'", file=sys.stderr)
+            print(f"Available roles: {', '.join(list_builtin_roles())}", file=sys.stderr)
+            return 1
+
+    # Create the key
+    raw_key = key_store.create_key(
+        principal_id=principal_id,
+        name=name,
+        expires_at=expires_at,
+        tenant_id=tenant_id,
+    )
+
+    # Assign roles
+    for role_name in roles:
+        role_store.assign_role(principal_id, role_name)
+
+    # Output
+    print(f"API Key created for {principal_id}")
+    print(f"Key: {raw_key}")
+    print()
+    print("⚠️  Save this key now - it cannot be retrieved later!")
+    print()
+
+    if expires_at:
+        print(f"Expires: {expires_at.isoformat()}")
+
+    if roles:
+        print(f"Roles assigned: {', '.join(roles)}")
+
+    return 0
+
+
+def _handle_list_keys(args, key_store: InMemoryApiKeyStore) -> int:
+    """Handle list-keys command."""
+    principal_id = args.principal
+    keys = key_store.list_keys(principal_id)
+
+    if not keys:
+        print(f"No keys found for {principal_id}")
+        return 0
+
+    print(f"API Keys for {principal_id}:")
+    print()
+
+    for key in keys:
+        status = "🔴 REVOKED" if key.revoked else "🟢 ACTIVE"
+        if not key.revoked and key.is_expired:
+            status = "🟡 EXPIRED"
+
+        print(f"{status} {key.key_id}: {key.name}")
+        print(f"   Created: {key.created_at.isoformat()}")
+        if key.expires_at:
+            print(f"   Expires: {key.expires_at.isoformat()}")
+        if key.last_used_at:
+            print(f"   Last used: {key.last_used_at.isoformat()}")
+        print()
+
+    return 0
+
+
+def _handle_revoke_key(args, key_store: InMemoryApiKeyStore) -> int:
+    """Handle revoke-key command."""
+    key_id = args.key_id
+
+    # Check if key exists
+    key_metadata = key_store.get_key_by_id(key_id)
+    if key_metadata is None:
+        print(f"Error: Key {key_id} not found", file=sys.stderr)
+        return 1
+
+    if key_metadata.revoked:
+        print(f"Key {key_id} is already revoked")
+        return 0
+
+    # Confirm unless --yes flag
+    if not args.yes:
+        confirm = input(f"Are you sure you want to revoke key {key_id}? [y/N] ")
+        if confirm.lower() not in ("y", "yes"):
+            print("Cancelled")
+            return 0
+
+    # Revoke
+    if key_store.revoke_key(key_id):
+        print(f"Key {key_id} revoked")
+        return 0
+    else:
+        print(f"Error: Failed to revoke key {key_id}", file=sys.stderr)
+        return 1
+
+
+def _handle_assign_role(args, role_store: InMemoryRoleStore) -> int:
+    """Handle assign-role command."""
+    principal_id = args.principal
+    role_name = args.role
+    scope = args.scope
+
+    # Validate role exists
+    if role_store.get_role(role_name) is None:
+        print(f"Error: Unknown role '{role_name}'", file=sys.stderr)
+        print(f"Available roles: {', '.join(list_builtin_roles())}", file=sys.stderr)
+        return 1
+
+    try:
+        role_store.assign_role(principal_id, role_name, scope)
+        print(f"Assigned role '{role_name}' to {principal_id} (scope: {scope})")
+        return 0
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def _handle_revoke_role(args, role_store: InMemoryRoleStore) -> int:
+    """Handle revoke-role command."""
+    principal_id = args.principal
+    role_name = args.role
+    scope = args.scope
+
+    role_store.revoke_role(principal_id, role_name, scope)
+    print(f"Revoked role '{role_name}' from {principal_id} (scope: {scope})")
+    return 0
+
+
+def _handle_list_roles() -> int:
+    """Handle list-roles command."""
+    from ..domain.security.roles import BUILTIN_ROLES
+
+    print("Available built-in roles:")
+    print()
+
+    for name, role in BUILTIN_ROLES.items():
+        print(f"  {name}")
+        print(f"    {role.description}")
+        print(f"    Permissions: {len(role.permissions)}")
+        print()
+
+    return 0

mcp_hangar/server/auth_config.py

@@ -0,0 +1,305 @@
+"""Authentication and Authorization configuration.
+
+Defines dataclasses for auth configuration and functions to load
+auth settings from YAML configuration files.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ApiKeyAuthConfig:
+    """API Key authentication configuration.
+
+    Attributes:
+        enabled: Whether API key authentication is enabled.
+        header_name: Name of the HTTP header containing the API key.
+    """
+
+    enabled: bool = True
+    header_name: str = "X-API-Key"
+
+
+@dataclass
+class OIDCAuthConfig:
+    """OIDC/JWT authentication configuration.
+
+    Attributes:
+        enabled: Whether OIDC/JWT authentication is enabled.
+        issuer: OIDC issuer URL (e.g., https://auth.company.com).
+        audience: Expected audience claim value.
+        jwks_uri: JWKS endpoint URL (auto-discovered from issuer if None).
+        client_id: Optional client ID for additional validation.
+        subject_claim: JWT claim for subject identifier.
+        groups_claim: JWT claim for group memberships.
+        tenant_claim: JWT claim for tenant identifier.
+        email_claim: JWT claim for email address.
+    """
+
+    enabled: bool = False
+    issuer: str = ""
+    audience: str = ""
+    jwks_uri: str | None = None
+    client_id: str | None = None
+
+    # Claim mappings
+    subject_claim: str = "sub"
+    groups_claim: str = "groups"
+    tenant_claim: str = "tenant_id"
+    email_claim: str = "email"
+
+
+@dataclass
+class OPAConfig:
+    """OPA (Open Policy Agent) configuration.
+
+    Attributes:
+        enabled: Whether OPA policy engine is enabled.
+        url: URL of the OPA server.
+        policy_path: Path to the policy decision endpoint.
+        timeout: HTTP request timeout in seconds.
+    """
+
+    enabled: bool = False
+    url: str = "http://localhost:8181"
+    policy_path: str = "v1/data/mcp/authz/allow"
+    timeout: float = 5.0
+
+
+@dataclass
+class RoleAssignment:
+    """A single role assignment configuration.
+
+    Attributes:
+        principal: Principal ID (e.g., "user:admin@company.com", "group:platform-engineering").
+        role: Role name (e.g., "admin", "developer").
+        scope: Scope of the assignment (e.g., "global", "tenant:data-team").
+    """
+
+    principal: str
+    role: str
+    scope: str = "global"
+
+
+@dataclass
+class StorageConfig:
+    """Storage backend configuration for auth data.
+
+    Attributes:
+        driver: Storage driver ("memory", "sqlite", "postgresql").
+        path: Path for SQLite database file (only for sqlite driver).
+        host: Database host (only for postgresql driver).
+        port: Database port (only for postgresql driver).
+        database: Database name (only for postgresql driver).
+        user: Database user (only for postgresql driver).
+        password: Database password (only for postgresql driver).
+        min_connections: Minimum pool connections (only for postgresql driver).
+        max_connections: Maximum pool connections (only for postgresql driver).
+    """
+
+    driver: str = "memory"  # memory, sqlite, postgresql
+
+    # SQLite options
+    path: str = "data/auth.db"
+
+    # PostgreSQL options
+    host: str = "localhost"
+    port: int = 5432
+    database: str = "mcp_hangar"
+    user: str = "mcp_hangar"
+    password: str = ""
+    min_connections: int = 2
+    max_connections: int = 10
+
+
+@dataclass
+class RateLimitConfig:
+    """Rate limiting configuration for auth attempts.
+
+    Attributes:
+        enabled: Whether rate limiting is enabled.
+        max_attempts: Maximum failed attempts per window.
+        window_seconds: Time window for counting attempts.
+        lockout_seconds: How long to lock out after exceeding limit.
+    """
+
+    enabled: bool = True
+    max_attempts: int = 10
+    window_seconds: int = 60
+    lockout_seconds: int = 300
+
+
+@dataclass
+class AuthConfig:
+    """Authentication and authorization configuration.
+
+    This is the main configuration container for all auth settings.
+
+    Authentication is OPT-IN by default (enabled=False). Set enabled=True
+    in your configuration to activate authentication.
+
+    Attributes:
+        enabled: Master switch for auth (if False, all requests are allowed). Default: False (opt-in).
+        allow_anonymous: If True, allow unauthenticated requests as anonymous.
+        storage: Storage backend configuration.
+        rate_limit: Rate limiting configuration.
+        api_key: API key authentication configuration.
+        oidc: OIDC/JWT authentication configuration.
+        opa: OPA policy engine configuration.
+        role_assignments: Static role assignments from configuration.
+    """
+
+    enabled: bool = False  # OPT-IN: auth disabled by default
+    allow_anonymous: bool = False
+
+    storage: StorageConfig = field(default_factory=StorageConfig)
+    rate_limit: RateLimitConfig = field(default_factory=RateLimitConfig)
+
+    api_key: ApiKeyAuthConfig = field(default_factory=ApiKeyAuthConfig)
+    oidc: OIDCAuthConfig = field(default_factory=OIDCAuthConfig)
+    opa: OPAConfig = field(default_factory=OPAConfig)
+
+    role_assignments: list[RoleAssignment] = field(default_factory=list)
+
+
+def parse_auth_config(config_dict: dict[str, Any] | None) -> AuthConfig:
+    """Parse auth configuration from dictionary.
+
+    Args:
+        config_dict: The 'auth' section of the configuration file.
+
+    Returns:
+        Parsed AuthConfig object with defaults for missing values.
+    """
+    if config_dict is None:
+        return AuthConfig()
+
+    # Parse storage config
+    storage_dict = config_dict.get("storage", {})
+    storage_config = StorageConfig(
+        driver=storage_dict.get("driver", "memory"),
+        path=storage_dict.get("path", "data/auth.db"),
+        host=storage_dict.get("host", "localhost"),
+        port=storage_dict.get("port", 5432),
+        database=storage_dict.get("database", "mcp_hangar"),
+        user=storage_dict.get("user", "mcp_hangar"),
+        password=storage_dict.get("password", ""),
+        min_connections=storage_dict.get("min_connections", 2),
+        max_connections=storage_dict.get("max_connections", 10),
+    )
+
+    # Parse rate limit config
+    rate_limit_dict = config_dict.get("rate_limit", {})
+    rate_limit_config = RateLimitConfig(
+        enabled=rate_limit_dict.get("enabled", True),
+        max_attempts=rate_limit_dict.get("max_attempts", 10),
+        window_seconds=rate_limit_dict.get("window_seconds", 60),
+        lockout_seconds=rate_limit_dict.get("lockout_seconds", 300),
+    )
+
+    # Parse API key config
+    api_key_dict = config_dict.get("api_key", {})
+    api_key_config = ApiKeyAuthConfig(
+        enabled=api_key_dict.get("enabled", True),
+        header_name=api_key_dict.get("header_name", "X-API-Key"),
+    )
+
+    # Parse OIDC config
+    oidc_dict = config_dict.get("oidc", {})
+    oidc_config = OIDCAuthConfig(
+        enabled=oidc_dict.get("enabled", False),
+        issuer=oidc_dict.get("issuer", ""),
+        audience=oidc_dict.get("audience", ""),
+        jwks_uri=oidc_dict.get("jwks_uri"),
+        client_id=oidc_dict.get("client_id"),
+        subject_claim=oidc_dict.get("subject_claim", "sub"),
+        groups_claim=oidc_dict.get("groups_claim", "groups"),
+        tenant_claim=oidc_dict.get("tenant_claim", "tenant_id"),
+        email_claim=oidc_dict.get("email_claim", "email"),
+    )
+
+    # Parse OPA config
+    opa_dict = config_dict.get("opa", {})
+    opa_config = OPAConfig(
+        enabled=opa_dict.get("enabled", False),
+        url=opa_dict.get("url", "http://localhost:8181"),
+        policy_path=opa_dict.get("policy_path", "v1/data/mcp/authz/allow"),
+        timeout=opa_dict.get("timeout", 5.0),
+    )
+
+    # Parse role assignments
+    role_assignments: list[RoleAssignment] = []
+    for assignment_dict in config_dict.get("role_assignments", []):
+        if isinstance(assignment_dict, dict):
+            role_assignments.append(
+                RoleAssignment(
+                    principal=assignment_dict.get("principal", ""),
+                    role=assignment_dict.get("role", ""),
+                    scope=assignment_dict.get("scope", "global"),
+                )
+            )
+
+    return AuthConfig(
+        enabled=config_dict.get("enabled", False),  # OPT-IN: default to disabled
+        allow_anonymous=config_dict.get("allow_anonymous", False),
+        storage=storage_config,
+        rate_limit=rate_limit_config,
+        api_key=api_key_config,
+        oidc=oidc_config,
+        opa=opa_config,
+        role_assignments=role_assignments,
+    )
+
+
+def get_default_auth_config() -> AuthConfig:
+    """Get default auth configuration.
+
+    Returns a disabled auth configuration suitable for development
+    where authentication is not required.
+
+    Returns:
+        AuthConfig with auth disabled.
+    """
+    return AuthConfig(enabled=False, allow_anonymous=True)
+
+
+# Example configuration (for documentation):
+EXAMPLE_AUTH_CONFIG = """
+auth:
+  enabled: true
+  allow_anonymous: false
+
+  api_key:
+    enabled: true
+    header_name: X-API-Key
+
+  oidc:
+    enabled: true
+    issuer: https://auth.company.com
+    audience: mcp-hangar
+    # jwks_uri auto-discovered from issuer if not specified
+    groups_claim: groups
+    tenant_claim: org_id
+
+  opa:
+    enabled: false  # Use built-in RBAC by default
+    url: http://opa:8181
+    policy_path: v1/data/mcp/authz/allow
+
+  role_assignments:
+    # Bootstrap admin
+    - principal: "user:admin@company.com"
+      role: admin
+      scope: global
+
+    # Platform team
+    - principal: "group:platform-engineering"
+      role: provider-admin
+      scope: global
+
+    # Data team - scoped to their tenant
+    - principal: "group:data-science"
+      role: developer
+      scope: "tenant:data-team"
+"""