ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/api/auth.py

@@ -0,0 +1,351 @@
+"""
+Authentication and authorization schemas for CIRIS API v2.0.
+
+Implements role-based access control with clear hierarchy:
+OBSERVER < ADMIN < AUTHORITY < ROOT
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional, Set
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class UserRole(str, Enum):
+    """User roles in order of increasing privilege."""
+
+    OBSERVER = "OBSERVER"
+    ADMIN = "ADMIN"
+    AUTHORITY = "AUTHORITY"
+    SYSTEM_ADMIN = "SYSTEM_ADMIN"  # Renamed from ROOT to avoid confusion with WA ROOT
+    SERVICE_ACCOUNT = "SERVICE_ACCOUNT"  # For service-to-service authentication
+
+    @property
+    def level(self) -> int:
+        """Numeric privilege level for comparison."""
+        return {
+            "OBSERVER": 1,
+            "ADMIN": 2,
+            "AUTHORITY": 3,
+            "SYSTEM_ADMIN": 4,
+            "SERVICE_ACCOUNT": 2,  # Same level as ADMIN for shutdown operations
+        }[self.value]
+
+    def has_permission(self, required_role: "UserRole") -> bool:
+        """Check if this role meets or exceeds required role."""
+        return self.level >= required_role.level
+
+
+class Permission(str, Enum):
+    """Granular permissions for fine-grained access control."""
+
+    # Observer permissions
+    VIEW_MESSAGES = "view_messages"
+    VIEW_TELEMETRY = "view_telemetry"
+    VIEW_REASONING = "view_reasoning"
+    VIEW_CONFIG = "view_config"
+    VIEW_MEMORY = "view_memory"
+    VIEW_AUDIT = "view_audit"
+    VIEW_TOOLS = "view_tools"
+    VIEW_LOGS = "view_logs"
+    SEND_MESSAGES = "send_messages"  # Permission to send messages via API
+
+    # Admin permissions
+    MANAGE_CONFIG = "manage_config"
+    RUNTIME_CONTROL = "runtime_control"
+    MANAGE_INCIDENTS = "manage_incidents"
+    MANAGE_TASKS = "manage_tasks"
+    MANAGE_FILTERS = "manage_filters"
+    TRIGGER_ANALYSIS = "trigger_analysis"
+
+    # Authority permissions
+    RESOLVE_DEFERRALS = "resolve_deferrals"
+    PROVIDE_GUIDANCE = "provide_guidance"
+    GRANT_PERMISSIONS = "grant_permissions"
+    MANAGE_USER_PERMISSIONS = "manage_user_permissions"
+
+    # System Admin permissions
+    FULL_ACCESS = "full_access"
+    EMERGENCY_SHUTDOWN = "emergency_shutdown"
+    MANAGE_SENSITIVE_CONFIG = "manage_sensitive_config"
+
+
+# Role to permissions mapping
+ROLE_PERMISSIONS: Dict[UserRole, Set[Permission]] = {
+    UserRole.OBSERVER: {
+        Permission.VIEW_MESSAGES,
+        Permission.VIEW_TELEMETRY,
+        Permission.VIEW_REASONING,
+        Permission.VIEW_CONFIG,
+        Permission.VIEW_MEMORY,
+        Permission.VIEW_AUDIT,
+        Permission.VIEW_TOOLS,
+        Permission.VIEW_LOGS,
+        Permission.SEND_MESSAGES,  # OBSERVER can send messages (gated by billing/credit system)
+    },
+    UserRole.ADMIN: {
+        # Includes all OBSERVER permissions
+        Permission.VIEW_MESSAGES,
+        Permission.VIEW_TELEMETRY,
+        Permission.VIEW_REASONING,
+        Permission.VIEW_CONFIG,
+        Permission.VIEW_MEMORY,
+        Permission.VIEW_AUDIT,
+        Permission.VIEW_TOOLS,
+        Permission.VIEW_LOGS,
+        Permission.SEND_MESSAGES,  # ADMIN can send messages
+        # Plus admin permissions
+        Permission.MANAGE_CONFIG,
+        Permission.RUNTIME_CONTROL,
+        Permission.MANAGE_INCIDENTS,
+        Permission.MANAGE_TASKS,
+        Permission.MANAGE_FILTERS,
+        Permission.TRIGGER_ANALYSIS,
+    },
+    UserRole.AUTHORITY: {
+        # Includes all ADMIN permissions
+        Permission.VIEW_MESSAGES,
+        Permission.VIEW_TELEMETRY,
+        Permission.VIEW_REASONING,
+        Permission.VIEW_CONFIG,
+        Permission.VIEW_MEMORY,
+        Permission.VIEW_AUDIT,
+        Permission.VIEW_TOOLS,
+        Permission.VIEW_LOGS,
+        Permission.SEND_MESSAGES,  # AUTHORITY can send messages
+        Permission.MANAGE_CONFIG,
+        Permission.RUNTIME_CONTROL,
+        Permission.MANAGE_INCIDENTS,
+        Permission.MANAGE_TASKS,
+        Permission.MANAGE_FILTERS,
+        Permission.TRIGGER_ANALYSIS,
+        # Plus authority permissions
+        Permission.RESOLVE_DEFERRALS,
+        Permission.PROVIDE_GUIDANCE,
+        Permission.GRANT_PERMISSIONS,
+        Permission.MANAGE_USER_PERMISSIONS,
+    },
+    UserRole.SYSTEM_ADMIN: {
+        # System admin has all permissions explicitly
+        # (includes all lower role permissions plus system-level permissions)
+        Permission.VIEW_MESSAGES,
+        Permission.VIEW_TELEMETRY,
+        Permission.VIEW_REASONING,
+        Permission.VIEW_CONFIG,
+        Permission.VIEW_MEMORY,
+        Permission.VIEW_AUDIT,
+        Permission.VIEW_TOOLS,
+        Permission.VIEW_LOGS,
+        Permission.SEND_MESSAGES,
+        Permission.MANAGE_CONFIG,
+        Permission.RUNTIME_CONTROL,
+        Permission.MANAGE_INCIDENTS,
+        Permission.MANAGE_TASKS,
+        Permission.MANAGE_FILTERS,
+        Permission.TRIGGER_ANALYSIS,
+        Permission.RESOLVE_DEFERRALS,  # SYSTEM_ADMIN can resolve deferrals
+        Permission.PROVIDE_GUIDANCE,
+        Permission.GRANT_PERMISSIONS,
+        Permission.MANAGE_USER_PERMISSIONS,
+        Permission.FULL_ACCESS,
+        Permission.EMERGENCY_SHUTDOWN,
+        Permission.MANAGE_SENSITIVE_CONFIG,
+    },
+    UserRole.SERVICE_ACCOUNT: {
+        # Permissions for service-to-service operations and system administration
+        Permission.VIEW_TELEMETRY,
+        Permission.VIEW_CONFIG,
+        Permission.RUNTIME_CONTROL,  # For shutdown operations
+        Permission.VIEW_TOOLS,
+        Permission.VIEW_LOGS,
+        Permission.SEND_MESSAGES,  # For system admin agent interaction and testing
+    },
+}
+
+
+class AuthContext(BaseModel):
+    """Authentication context for API requests."""
+
+    user_id: str = Field(..., description="Unique user identifier")
+    role: UserRole = Field(..., description="User's role")
+    permissions: Set[Permission] = Field(..., description="Granted permissions")
+    api_key_id: Optional[str] = Field(None, description="API key ID if using key auth")
+    session_id: Optional[str] = Field(None, description="Session ID if using session auth")
+    authenticated_at: datetime = Field(..., description="When authentication occurred")
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    # Request object (not serialized)
+    request: Optional[Any] = Field(None, exclude=True)
+
+    @classmethod
+    def from_api_key(cls, api_key: "APIKey") -> "AuthContext":
+        """Create context from API key."""
+        return cls(
+            user_id=api_key.user_id,
+            role=api_key.role,
+            permissions=ROLE_PERMISSIONS.get(api_key.role, set()),
+            api_key_id=api_key.id,
+            session_id=None,
+            authenticated_at=datetime.now(timezone.utc),
+            request=None,
+        )
+
+    def has_permission(self, permission: Permission) -> bool:
+        """Check if user has specific permission."""
+        if self.role == UserRole.SYSTEM_ADMIN:
+            return True  # SYSTEM_ADMIN has all permissions
+        return permission in self.permissions
+
+
+class APIKey(BaseModel):
+    """API key model for authentication."""
+
+    id: str = Field(..., description="Unique key identifier")
+    key_hash: str = Field(..., description="Hashed API key")
+    user_id: str = Field(..., description="User who owns this key")
+    role: UserRole = Field(..., description="Role granted by this key")
+    description: str = Field("", description="Human-readable description")
+    created_at: datetime = Field(..., description="When key was created")
+    last_used: Optional[datetime] = Field(None, description="Last time key was used")
+    expires_at: Optional[datetime] = Field(None, description="When key expires")
+    is_active: bool = Field(True, description="Whether key is active")
+
+    def is_valid(self) -> bool:
+        """Check if key is currently valid."""
+        if not self.is_active:
+            return False
+
+        if self.expires_at and self.expires_at < datetime.now(timezone.utc):
+            return False
+
+        return True
+
+
+class LoginRequest(BaseModel):
+    """Request to authenticate with username/password."""
+
+    username: str = Field(..., description="Username")
+    password: str = Field(..., description="Password")
+
+
+class LoginResponse(BaseModel):
+    """Response after successful login."""
+
+    access_token: str = Field(..., description="JWT access token")
+    token_type: str = Field("bearer", description="Token type")
+    expires_in: int = Field(..., description="Token lifetime in seconds")
+    user_id: str = Field(..., description="Authenticated user ID")
+    role: UserRole = Field(..., description="User's role")
+
+
+class TokenRefreshRequest(BaseModel):
+    """Request to refresh access token."""
+
+    refresh_token: str = Field(..., description="Refresh token")
+
+
+class UserInfo(BaseModel):
+    """Current user information."""
+
+    user_id: str = Field(..., description="User ID")
+    username: str = Field(..., description="Username")
+    role: UserRole = Field(..., description="User's role")
+    permissions: List[str] = Field(..., description="List of permissions")
+    created_at: datetime = Field(..., description="Account creation time")
+    last_login: Optional[datetime] = Field(None, description="Last login time")
+
+
+class TokenResponse(BaseModel):
+    """Token information response."""
+
+    user_id: str
+    role: UserRole
+    scopes: List[str]
+    expires_at: Optional[datetime] = None
+
+
+class OAuth2StartRequest(BaseModel):
+    """OAuth2 flow start request."""
+
+    redirect_uri: Optional[str] = Field(None, description="Custom redirect URI after authentication")
+
+
+class OAuth2CallbackResponse(BaseModel):
+    """OAuth2 callback response with API key."""
+
+    access_token: str = Field(..., description="API key for accessing CIRIS API")
+    token_type: str = Field("Bearer", description="Token type")
+    expires_in: int = Field(..., description="Token expiration in seconds")
+    role: UserRole = Field(..., description="User role")
+    user_id: str = Field(..., description="User identifier")
+    provider: str = Field(..., description="OAuth provider used")
+    email: Optional[str] = Field(None, description="User email from OAuth provider")
+    name: Optional[str] = Field(None, description="User name from OAuth provider")
+
+
+class APIKeyCreateRequest(BaseModel):
+    """Request to create a new API key."""
+
+    description: Optional[str] = Field(None, description="Description of the key's purpose")
+    expires_in_minutes: int = Field(
+        ...,
+        ge=30,
+        le=10080,
+        description="Expiry time in minutes (30 minutes to 7 days). 30min=30, 1day=1440, 7days=10080",
+    )
+
+
+class APIKeyResponse(BaseModel):
+    """Response with created API key."""
+
+    api_key: str = Field(..., description="The generated API key (show only once!)")
+    role: UserRole = Field(..., description="Role assigned to the key")
+    expires_at: Optional[datetime] = Field(None, description="When the key expires")
+    description: Optional[str] = Field(None, description="Key description")
+    created_at: datetime = Field(..., description="When the key was created")
+    created_by: str = Field(..., description="User who created the key")
+
+
+class APIKeyInfo(BaseModel):
+    """API key information (without the actual key)."""
+
+    key_id: str = Field(..., description="Key identifier (partial)")
+    role: UserRole = Field(..., description="Role assigned to the key")
+    expires_at: Optional[datetime] = Field(None, description="When the key expires")
+    description: Optional[str] = Field(None, description="Key description")
+    created_at: datetime = Field(..., description="When the key was created")
+    created_by: str = Field(..., description="User who created the key")
+    last_used: Optional[datetime] = Field(None, description="Last time the key was used")
+    is_active: bool = Field(..., description="Whether the key is active")
+
+
+class APIKeyListResponse(BaseModel):
+    """List of API keys."""
+
+    api_keys: List[APIKeyInfo] = Field(..., description="List of API keys")
+    total: int = Field(..., description="Total number of keys")
+
+
+class PermissionRequestResponse(BaseModel):
+    """Response for permission request operation."""
+
+    success: bool = Field(..., description="Whether the request was successful")
+    status: str = Field(
+        ..., description="Status of the request (already_granted, already_requested, request_submitted)"
+    )
+    message: str = Field(..., description="Human-readable message")
+    requested_at: Optional[datetime] = Field(None, description="When the permission was requested")
+
+
+class PermissionRequestUser(BaseModel):
+    """User with permission request information."""
+
+    id: str = Field(..., description="User ID")
+    email: Optional[str] = Field(None, description="User email")
+    oauth_name: Optional[str] = Field(None, description="Name from OAuth provider")
+    oauth_picture: Optional[str] = Field(None, description="Profile picture URL from OAuth provider")
+    role: UserRole = Field(..., description="Current role")
+    permission_requested_at: datetime = Field(..., description="When permissions were requested")
+    has_send_messages: bool = Field(..., description="Whether user already has SEND_MESSAGES permission")

ciris_engine/schemas/api/config_security.py

@@ -0,0 +1,242 @@
+"""
+Configuration security and filtering for CIRIS API v2.0.
+
+Automatically detects and filters sensitive configuration values
+based on user role to prevent information leakage.
+"""
+
+import re
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field, field_serializer
+
+from ciris_engine.schemas.types import ConfigDict, ConfigValue
+
+from .auth import UserRole
+
+
+class ConfigSecurity:
+    """Configuration security and filtering rules."""
+
+    # Patterns for sensitive keys (case-insensitive)
+    SENSITIVE_PATTERNS = [
+        re.compile(r".*_(key|secret|token|password|auth|credential)$", re.IGNORECASE),
+        re.compile(r"^(api|oauth|jwt|encryption|private)_.*", re.IGNORECASE),
+        re.compile(r".*(credential|certificate|private|password).*", re.IGNORECASE),
+        re.compile(r"^(aws|azure|gcp|github|gitlab)_.*", re.IGNORECASE),
+    ]
+
+    # Exact sensitive keys
+    SENSITIVE_KEYS = {
+        # Authentication & Security
+        "wa_root_key",
+        "wa_authority_keys",
+        "admin_users",
+        "api_keys",
+        "oauth_client_secret",
+        "oauth_client_id",
+        "jwt_secret",
+        "encryption_key",
+        "signing_key",
+        # Database & Infrastructure
+        "database_url",
+        "redis_url",
+        "mongodb_uri",
+        "elasticsearch_url",
+        # External Services
+        "openai_api_key",
+        "anthropic_api_key",
+        "huggingface_token",
+        "discord_bot_token",
+        "slack_bot_token",
+        "telegram_bot_token",
+        # Cloud Providers
+        "aws_access_key_id",
+        "aws_secret_access_key",
+        "azure_client_secret",
+        "gcp_service_account",
+        # Other Sensitive
+        "smtp_password",
+        "webhook_secret",
+        "payment_api_key",
+    }
+
+    @classmethod
+    def is_sensitive(cls, key: str) -> bool:
+        """
+        Check if a configuration key is sensitive.
+
+        Args:
+            key: Configuration key to check
+
+        Returns:
+            True if key contains sensitive data
+        """
+        # Check exact matches first (faster)
+        if key in cls.SENSITIVE_KEYS:
+            return True
+
+        # Check patterns
+        for pattern in cls.SENSITIVE_PATTERNS:
+            if pattern.match(key):
+                return True
+
+        return False
+
+    @classmethod
+    def filter_value(cls, key: str, value: Any, role: UserRole) -> Any:
+        """
+        Filter a single configuration value based on role.
+
+        Args:
+            key: Configuration key
+            value: Configuration value
+            role: User's role
+
+        Returns:
+            Filtered value (may be "[REDACTED]")
+        """
+        if not cls.is_sensitive(key):
+            return value
+
+        # SYSTEM_ADMIN sees everything
+        if role == UserRole.SYSTEM_ADMIN:
+            return value
+
+        # Special cases for certain roles
+        if role == UserRole.ADMIN and key == "admin_users":
+            return value  # Admins can see admin list
+
+        if role == UserRole.AUTHORITY and key == "wa_authority_keys":
+            return value  # Authorities can see authority keys
+
+        # Everyone else gets redacted
+        return "[REDACTED]"
+
+    @classmethod
+    def filter_config(cls, config: ConfigDict, role: UserRole) -> ConfigDict:
+        """
+        Filter entire configuration dictionary based on role.
+
+        Args:
+            config: Configuration dictionary
+            role: User's role
+
+        Returns:
+            Filtered configuration
+        """
+        if role == UserRole.SYSTEM_ADMIN:
+            return config  # SYSTEM_ADMIN sees everything
+
+        filtered = {}
+        for key, value in config.items():
+            filtered[key] = cls.filter_value(key, value, role)
+
+        return filtered
+
+    @classmethod
+    def get_visible_keys(cls, all_keys: List[str], role: UserRole) -> Dict[str, bool]:
+        """
+        Get visibility status for a list of keys.
+
+        Args:
+            all_keys: List of configuration keys
+            role: User's role
+
+        Returns:
+            Dict mapping key -> is_visible
+        """
+        visibility = {}
+
+        for key in all_keys:
+            if not cls.is_sensitive(key):
+                visibility[key] = True
+            elif role == UserRole.SYSTEM_ADMIN:
+                visibility[key] = True
+            elif role == UserRole.ADMIN and key == "admin_users":
+                visibility[key] = True
+            elif role == UserRole.AUTHORITY and key == "wa_authority_keys":
+                visibility[key] = True
+            else:
+                visibility[key] = False
+
+        return visibility
+
+
+class ConfigValueResponse(BaseModel):
+    """Response for a single configuration value."""
+
+    key: str = Field(..., description="Configuration key")
+    value: ConfigValue = Field(..., description="Configuration value (may be redacted)")
+    is_sensitive: bool = Field(..., description="Whether this is a sensitive key")
+    is_redacted: bool = Field(..., description="Whether value was redacted")
+    last_updated: Optional[datetime] = Field(None, description="When value was last updated")
+    updated_by: Optional[str] = Field(None, description="Who last updated this value")
+
+    @field_serializer("last_updated")
+    def serialize_last_updated(self, last_updated: Optional[datetime], _info: Any) -> Optional[str]:
+        return last_updated.isoformat() if last_updated else None
+
+
+class ConfigListResponse(BaseModel):
+    """Response for configuration list."""
+
+    configs: ConfigDict = Field(..., description="Configuration values")
+    metadata: Dict[str, Union[str, int, float, bool]] = Field(..., description="Response metadata")
+
+
+def filter_config_for_role(config: ConfigDict, role: UserRole) -> ConfigDict:
+    """
+    Filter configuration values based on user role.
+
+    Args:
+        config: Configuration dictionary
+        role: User's role
+
+    Returns:
+        Filtered configuration with sensitive values redacted
+    """
+    return ConfigSecurity.filter_config(config, role)
+
+
+class ConfigUpdateRequest(BaseModel):
+    """Request to update configuration value."""
+
+    value: ConfigValue = Field(..., description="New configuration value")
+    comment: Optional[str] = Field(None, description="Optional comment about change")
+
+
+class ConfigUpdateResponse(BaseModel):
+    """Response after configuration update."""
+
+    success: bool = Field(..., description="Whether update succeeded")
+    key: str = Field(..., description="Configuration key")
+    message: str = Field(..., description="Status message")
+    requires_restart: bool = Field(False, description="Whether change requires restart")
+
+
+class ConfigHistoryEntry(BaseModel):
+    """Configuration change history entry."""
+
+    key: str = Field(..., description="Configuration key")
+    old_value: ConfigValue = Field(..., description="Previous value (may be redacted)")
+    new_value: ConfigValue = Field(..., description="New value (may be redacted)")
+    changed_at: datetime = Field(..., description="When change occurred")
+    changed_by: str = Field(..., description="Who made the change")
+    comment: Optional[str] = Field(None, description="Change comment")
+
+
+class ConfigValidationRequest(BaseModel):
+    """Request to validate configuration changes."""
+
+    changes: ConfigDict = Field(..., description="Proposed changes")
+
+
+class ConfigValidationResponse(BaseModel):
+    """Response from configuration validation."""
+
+    valid: bool = Field(..., description="Whether all changes are valid")
+    errors: Dict[str, str] = Field(default_factory=dict, description="Validation errors by key")
+    warnings: Dict[str, str] = Field(default_factory=dict, description="Validation warnings by key")
+    requires_restart: List[str] = Field(default_factory=list, description="Keys that require restart")