ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/logic/adapters/api/dependencies/auth.py

@@ -0,0 +1,260 @@
+"""
+Authentication dependencies for FastAPI routes.
+
+Provides role-based access control through dependency injection.
+"""
+
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional, Set
+
+from fastapi import Depends, Header, HTTPException, Request, status
+
+from ciris_engine.schemas.api.auth import ROLE_PERMISSIONS, APIKeyInfo, AuthContext, UserInfo, UserRole
+
+from ..services.auth_service import APIAuthService
+
+__all__ = [
+    "AuthContext",
+    "get_auth_service",
+    "require_admin",
+    "require_observer",
+    "require_authenticated",
+]
+
+
+def get_auth_service(request: Request) -> APIAuthService:
+    """Get auth service from app state."""
+    if not hasattr(request.app.state, "auth_service"):
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Auth service not initialized")
+    auth_service = request.app.state.auth_service
+    if not isinstance(auth_service, APIAuthService):
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Invalid auth service type")
+    return auth_service
+
+
+def _extract_bearer_token(authorization: Optional[str]) -> str:
+    """Extract and validate bearer token from authorization header."""
+    if not authorization:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing authorization header",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    if not authorization.startswith("Bearer "):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid authorization format",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    return authorization[7:]  # Remove "Bearer " prefix
+
+
+def _handle_service_token_auth(request: Request, auth_service: APIAuthService, service_token: str) -> AuthContext:
+    """Handle service token authentication."""
+    service_user = auth_service.validate_service_token(service_token)
+    if not service_user:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid service token")
+
+    # Service token authentication successful
+    # NOTE: We do not audit successful service token auth to avoid log spam
+    # Service tokens are used frequently by the manager and other services
+    # Only failed attempts are audited for security monitoring
+
+    from ciris_engine.schemas.api.auth import UserRole as AuthUserRole
+
+    context = AuthContext(
+        user_id=service_user.wa_id,
+        role=AuthUserRole.SERVICE_ACCOUNT,
+        permissions=ROLE_PERMISSIONS.get(AuthUserRole.SERVICE_ACCOUNT, set()),
+        api_key_id=None,
+        authenticated_at=datetime.now(timezone.utc),
+    )
+    context.request = request
+    return context
+
+
+async def _handle_password_auth(request: Request, auth_service: APIAuthService, api_key: str) -> AuthContext:
+    """Handle username:password authentication."""
+    username, password = api_key.split(":", 1)
+    user = await auth_service.verify_user_password(username, password)
+    if not user:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid username or password")
+
+    from ciris_engine.schemas.api.auth import UserRole as AuthUserRole
+
+    # Map APIRole to UserRole
+    user_role = AuthUserRole[user.api_role.value]
+    context = AuthContext(
+        user_id=user.wa_id,
+        role=user_role,
+        permissions=ROLE_PERMISSIONS.get(user_role, set()),
+        api_key_id=None,
+        authenticated_at=datetime.now(timezone.utc),
+    )
+    context.request = request
+    return context
+
+
+def _build_permissions_set(key_info: Any, user: Any) -> Set[Any]:
+    """Build permissions set from role and custom permissions."""
+    permissions = set(ROLE_PERMISSIONS.get(key_info.role, set()))
+
+    # Add any custom permissions if user exists and has them
+    if user and hasattr(user, "custom_permissions") and user.custom_permissions:
+        from ciris_engine.schemas.api.auth import Permission
+
+        for perm in user.custom_permissions:
+            # Convert string to Permission enum if it's a valid permission
+            try:
+                permissions.add(Permission(perm))
+            except ValueError:
+                # Skip invalid permission strings
+                pass
+
+    return permissions
+
+
+def _handle_api_key_auth(request: Request, auth_service: APIAuthService, api_key: str) -> AuthContext:
+    """Handle regular API key authentication."""
+    key_info = auth_service.validate_api_key(api_key)
+    if not key_info:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid API key")
+
+    # Get user to check for custom permissions
+    user = auth_service.get_user(key_info.user_id)
+
+    # Build permissions set
+    permissions = _build_permissions_set(key_info, user)
+
+    # Create auth context with request reference
+    context = AuthContext(
+        user_id=key_info.user_id,
+        role=key_info.role,
+        permissions=permissions,
+        api_key_id=auth_service._get_key_id(api_key),
+        authenticated_at=datetime.now(timezone.utc),
+    )
+
+    # Attach request to context for service access in routes
+    context.request = request
+    return context
+
+
+async def get_auth_context(  # NOSONAR: FastAPI requires async for dependency injection
+    request: Request,
+    authorization: Optional[str] = Header(None),
+    auth_service: APIAuthService = Depends(get_auth_service),
+) -> AuthContext:
+    """Extract and validate authentication from request."""
+    api_key = _extract_bearer_token(authorization)
+
+    # Check if this is a service token
+    if api_key.startswith("service:"):
+        service_token = api_key[8:]  # Remove "service:" prefix
+        return _handle_service_token_auth(request, auth_service, service_token)
+
+    # Check if this is username:password format (for legacy support)
+    if ":" in api_key:
+        return await _handle_password_auth(request, auth_service, api_key)
+
+    # Otherwise, validate as regular API key
+    return _handle_api_key_auth(request, auth_service, api_key)
+
+
+async def optional_auth(
+    request: Request,
+    authorization: Optional[str] = Header(None),
+    auth_service: APIAuthService = Depends(get_auth_service),
+) -> Optional[AuthContext]:
+    """Optional authentication - returns None if no auth provided."""
+    if not authorization:
+        return None
+
+    try:
+        return await get_auth_context(request, authorization, auth_service)
+    except HTTPException:
+        return None
+
+
+def require_role(minimum_role: UserRole) -> Callable[..., AuthContext]:
+    """
+    Factory for role-based access control dependencies.
+
+    Args:
+        minimum_role: Minimum role required for access
+
+    Returns:
+        Dependency function that validates role
+    """
+
+    def check_role(auth: AuthContext = Depends(get_auth_context)) -> AuthContext:
+        """Validate user has required role."""
+        if not auth.role.has_permission(minimum_role):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Insufficient permissions. Requires {minimum_role.value} role or higher.",
+            )
+
+        return auth
+
+    # Set function name for better error messages
+    check_role.__name__ = f"require_{minimum_role.value.lower()}"
+    return check_role
+
+
+# Convenience dependencies for common roles
+require_authenticated = get_auth_context  # Alias for basic authentication
+require_observer = require_role(UserRole.OBSERVER)
+require_admin = require_role(UserRole.ADMIN)
+require_authority = require_role(UserRole.AUTHORITY)
+require_system_admin = require_role(UserRole.SYSTEM_ADMIN)
+require_service_account = require_role(UserRole.SERVICE_ACCOUNT)
+
+
+def check_permissions(permissions: list[str]) -> Callable[..., Any]:
+    """
+    Factory for permission-based access control dependencies.
+
+    Args:
+        permissions: List of required permissions
+
+    Returns:
+        Dependency function that validates permissions
+    """
+
+    async def check(  # NOSONAR: FastAPI requires async for dependency injection
+        auth: AuthContext = Depends(get_auth_context), auth_service: APIAuthService = Depends(get_auth_service)
+    ) -> None:
+        """Validate user has required permissions."""
+        from ciris_engine.schemas.runtime.api import APIRole
+        from ciris_engine.schemas.services.authority_core import WARole
+
+        # Get the user from auth service to get their API role
+        user = auth_service.get_user(auth.user_id)
+        if not user:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="User not found")
+
+        # Get permissions for user's API role
+        user_permissions = set(auth_service.get_permissions_for_role(user.api_role))
+
+        # ROOT WA role inherits AUTHORITY permissions (for deferral resolution, etc.)
+        # This is separate from API role - ROOT WAs get both SYSTEM_ADMIN + AUTHORITY perms
+        if hasattr(user, "wa_role") and user.wa_role == WARole.ROOT:
+            authority_perms = auth_service.get_permissions_for_role(APIRole.AUTHORITY)
+            user_permissions.update(authority_perms)
+
+        # Add any custom permissions
+        if hasattr(user, "custom_permissions") and user.custom_permissions:
+            for perm in user.custom_permissions:
+                user_permissions.add(perm)
+
+        # Check if user has all required permissions
+        missing = set(permissions) - user_permissions
+        if missing:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN, detail=f"Missing required permissions: {', '.join(missing)}"
+            )
+
+    return check

ciris_engine/logic/adapters/api/endpoints/__init__.py

@@ -0,0 +1 @@
+"""API endpoints module."""

ciris_engine/logic/adapters/api/endpoints/emergency.py

@@ -0,0 +1,86 @@
+"""
+Emergency API endpoints.
+
+Provides WA-authorized emergency control endpoints including kill switch.
+"""
+
+import logging
+from typing import Any, Dict
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from ciris_engine.protocols.services import RuntimeControlService as RuntimeControlServiceProtocol
+from ciris_engine.schemas.services.shutdown import EmergencyShutdownStatus, WASignedCommand
+from ciris_engine.schemas.types import JSONDict
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/emergency", tags=["emergency"])
+
+
+def get_runtime_service() -> RuntimeControlServiceProtocol:
+    """Get runtime control service dependency."""
+    # This will be injected by the API adapter
+    # For now, return None - the actual service should be injected
+    return None  # type: ignore
+
+
+@router.post("/shutdown", response_model=EmergencyShutdownStatus)
+async def emergency_shutdown(
+    command: WASignedCommand, runtime_service: RuntimeControlServiceProtocol = Depends(get_runtime_service)
+) -> EmergencyShutdownStatus:
+    """
+    Execute WA-authorized emergency shutdown.
+
+    This endpoint accepts a signed SHUTDOWN_NOW command from a Wise Authority
+    and initiates immediate graceful shutdown, bypassing normal procedures.
+
+    The command must be signed by a ROOT WA authority or a WA in the trust tree.
+
+    Args:
+        command: Signed emergency shutdown command
+
+    Returns:
+        Status of the emergency shutdown process
+
+    Raises:
+        HTTPException: If command verification fails
+    """
+    logger.critical(f"Emergency shutdown endpoint called by WA {command.wa_id}")
+
+    try:
+        # Handle the emergency command
+        status = await runtime_service.handle_emergency_shutdown(command)
+
+        if not status.command_verified:
+            raise HTTPException(status_code=403, detail=f"Command verification failed: {status.verification_error}")
+
+        return status
+
+    except Exception as e:
+        logger.error(f"Emergency shutdown failed: {e}")
+        raise HTTPException(status_code=500, detail=f"Emergency shutdown failed: {str(e)}")
+
+
+@router.get("/kill-switch/status")
+async def get_kill_switch_status(
+    runtime_service: RuntimeControlServiceProtocol = Depends(get_runtime_service),
+) -> JSONDict:
+    """
+    Get current kill switch configuration status.
+
+    Returns:
+        Current kill switch configuration (without sensitive keys)
+    """
+    if hasattr(runtime_service, "_kill_switch_config"):
+        config = runtime_service._kill_switch_config
+        return {
+            "enabled": config.enabled,
+            "root_wa_count": len(config.root_wa_public_keys),  # ROOT WA authorities
+            "trust_tree_depth": config.trust_tree_depth,
+            "allow_relay": config.allow_relay,
+            "max_shutdown_time_ms": config.max_shutdown_time_ms,
+            "command_expiry_seconds": config.command_expiry_seconds,
+        }
+
+    return {"enabled": False, "error": "Kill switch not configured"}

ciris_engine/logic/adapters/api/middleware/__init__.py

@@ -0,0 +1 @@
+"""API middleware components."""

ciris_engine/logic/adapters/api/middleware/rate_limiter.py

@@ -0,0 +1,302 @@
+"""
+Simple rate limiting middleware for CIRIS API.
+
+Implements a basic in-memory rate limiter using token bucket algorithm.
+"""
+
+import asyncio
+import logging
+from datetime import datetime, timedelta
+from typing import Any, Callable, Dict, Optional, Tuple, cast
+
+import jwt
+from fastapi import Request, Response
+from fastapi.responses import JSONResponse
+
+logger = logging.getLogger(__name__)
+
+
+class RateLimiter:
+    """Simple in-memory rate limiter using token bucket algorithm.
+
+    IMPORTANT: This implementation is in-memory only and not suitable for
+    multi-instance deployments. For production with multiple API pods,
+    consider using Redis or another distributed backend.
+    """
+
+    def __init__(self, requests_per_minute: int = 60, max_clients: int = 10000):
+        """
+        Initialize rate limiter.
+
+        Args:
+            requests_per_minute: Number of requests allowed per minute
+            max_clients: Maximum number of client buckets to track (prevents memory exhaustion)
+        """
+        self.rate = requests_per_minute
+        self.max_clients = max_clients
+        self.buckets: Dict[str, Tuple[float, datetime]] = {}
+        self._lock = asyncio.Lock()
+        self._cleanup_interval = 300  # Cleanup old entries every 5 minutes
+        self._last_cleanup = datetime.now()
+
+    async def check_rate_limit(self, client_id: str) -> bool:
+        """
+        Check if request is within rate limit.
+
+        Args:
+            client_id: Unique identifier for client (IP or user)
+
+        Returns:
+            True if allowed, False if rate limited
+        """
+        async with self._lock:
+            now = datetime.now()
+
+            # Cleanup old entries periodically
+            if (now - self._last_cleanup).total_seconds() > self._cleanup_interval:
+                self._cleanup_old_entries()
+                self._last_cleanup = now
+
+            # Get or create bucket
+            if client_id not in self.buckets:
+                # Enforce max bucket count to prevent memory exhaustion
+                if len(self.buckets) >= self.max_clients:
+                    # Remove oldest bucket to make room (LRU-like behavior)
+                    oldest_client = min(self.buckets.items(), key=lambda x: x[1][1])[0]
+                    del self.buckets[oldest_client]
+
+                # New client starts with full tokens minus the one consumed by this request
+                self.buckets[client_id] = (float(self.rate - 1), now)
+                return True
+
+            tokens, last_update = self.buckets[client_id]
+
+            # Calculate time elapsed and refill tokens
+            elapsed = (now - last_update).total_seconds()
+            tokens = min(self.rate, tokens + elapsed * (self.rate / 60.0))
+
+            # Check if we have tokens available
+            if tokens >= 1:
+                tokens -= 1
+                self.buckets[client_id] = (tokens, now)
+                return True
+
+            # No tokens available - update timestamp but don't consume
+            self.buckets[client_id] = (tokens, now)
+            return False
+
+    def _cleanup_old_entries(self) -> None:
+        """Remove entries that haven't been used in over an hour."""
+        now = datetime.now()
+        cutoff = now - timedelta(hours=1)
+
+        to_remove = []
+        for client_id, (_, last_update) in self.buckets.items():
+            if last_update < cutoff:
+                to_remove.append(client_id)
+
+        for client_id in to_remove:
+            del self.buckets[client_id]
+
+    def get_retry_after(self, client_id: str) -> int:
+        """
+        Get seconds until next request is allowed.
+
+        Args:
+            client_id: Unique identifier for client
+
+        Returns:
+            Seconds to wait before retry
+        """
+        if client_id not in self.buckets:
+            return 0
+
+        tokens, _ = self.buckets[client_id]
+        if tokens >= 1:
+            return 0
+
+        # Calculate time needed to get 1 token
+        tokens_needed = 1 - tokens
+        seconds_per_token = 60.0 / self.rate
+        return int(tokens_needed * seconds_per_token) + 1
+
+
+class RateLimitMiddleware:
+    """FastAPI middleware for rate limiting."""
+
+    def __init__(self, requests_per_minute: int = 60, gateway_secret: Optional[bytes] = None):
+        """
+        Initialize middleware.
+
+        Args:
+            requests_per_minute: Rate limit per minute
+            gateway_secret: Secret for verifying JWT tokens (required for user-based rate limiting)
+        """
+        self.limiter = RateLimiter(requests_per_minute)
+        self.gateway_secret = gateway_secret
+        # Exempt paths that should not be rate limited
+        self.exempt_paths = {
+            "/openapi.json",
+            "/docs",
+            "/redoc",
+            "/emergency/shutdown",  # Emergency endpoints bypass rate limiting
+            "/v1/system/health",  # Health checks should not be rate limited
+        }
+        # Static file extensions that should be exempt from rate limiting
+        self.exempt_extensions = {
+            ".js",
+            ".css",
+            ".map",
+            ".woff",
+            ".woff2",
+            ".ttf",
+            ".otf",
+            ".eot",
+            ".png",
+            ".jpg",
+            ".jpeg",
+            ".gif",
+            ".svg",
+            ".ico",
+            ".webp",
+            ".mp4",
+            ".webm",
+            ".txt",
+            ".html",  # Static HTML pages from Next.js export
+        }
+
+    def _get_gateway_secret(self, request: Request) -> Optional[bytes]:
+        """
+        Get gateway secret from the authentication service.
+
+        Args:
+            request: FastAPI request object with app state
+
+        Returns:
+            Gateway secret bytes, or None if not available
+        """
+        # Try to get from explicitly set gateway_secret first
+        if self.gateway_secret:
+            return self.gateway_secret
+
+        # Lazy-load from authentication service if available
+        if hasattr(request.app.state, "authentication_service"):
+            auth_service = request.app.state.authentication_service
+            if auth_service and hasattr(auth_service, "gateway_secret"):
+                secret = auth_service.gateway_secret
+                # Type guard: ensure it's bytes
+                if isinstance(secret, bytes):
+                    return secret
+
+        return None
+
+    def _extract_user_id_from_jwt(self, token: str, request: Request) -> Optional[str]:
+        """
+        Extract user ID from JWT token WITH proper signature verification.
+
+        SECURITY: This method verifies the JWT signature before trusting the contents.
+        Prevents attackers from forging tokens with arbitrary user IDs to bypass rate limiting.
+
+        Args:
+            token: JWT token string
+            request: FastAPI request object (for accessing authentication service)
+
+        Returns:
+            User ID (wa_id) from verified token's 'sub' claim, or None if verification fails
+        """
+        gateway_secret = self._get_gateway_secret(request)
+        if not gateway_secret:
+            # No gateway secret available - cannot verify tokens, fallback to IP-based rate limiting
+            logger.debug("No gateway_secret available - cannot verify JWT tokens")
+            return None
+
+        try:
+            # SECURITY FIX: Verify signature with gateway secret before trusting token contents
+            decoded = jwt.decode(token, gateway_secret, algorithms=["HS256"])
+
+            # Extract and validate the 'sub' field
+            sub = decoded.get("sub")
+            if isinstance(sub, str):
+                return sub
+            return None
+        except jwt.InvalidTokenError as e:
+            # Token verification failed - fallback to IP-based rate limiting
+            logger.debug(f"JWT verification failed in rate limiter: {type(e).__name__}: {e}")
+            return None
+        except Exception as e:
+            # Unexpected error during verification
+            logger.debug(f"Failed to verify JWT in rate limiter: {type(e).__name__}: {e}")
+            return None
+
+    async def __call__(self, request: Request, call_next: Callable[..., Any]) -> Response:
+        """Process request through rate limiter."""
+        # Check if path is exempt
+        if request.url.path in self.exempt_paths:
+            response = await call_next(request)
+            return cast(Response, response)
+
+        # Check if request is for a static file (by extension or path prefix)
+        path = request.url.path
+        if path.startswith("/_next/") or any(path.endswith(ext) for ext in self.exempt_extensions):
+            response = await call_next(request)
+            return cast(Response, response)
+
+        # Extract client identifier (prefer authenticated user, fallback to IP)
+        client_host = request.client.host if request.client else "unknown"
+        client_id = None
+
+        # Try to extract user ID from authentication
+        auth_header = request.headers.get("Authorization", "")
+        if auth_header.startswith("Bearer "):
+            token = auth_header[7:]  # Remove "Bearer " prefix
+
+            # Check for service token format: "service:TOKEN"
+            if token.startswith("service:"):
+                # Service tokens use IP-based rate limiting
+                client_id = f"service_{client_host}"
+            else:
+                # JWT tokens: verify and extract user_id for per-user rate limiting
+                user_id = self._extract_user_id_from_jwt(token, request)
+                if user_id:
+                    # Use user ID from verified JWT for per-user rate limiting
+                    client_id = f"user_{user_id}"
+                else:
+                    # Failed to verify JWT, fall back to IP-based
+                    client_id = f"auth_{client_host}"
+        else:
+            # No authentication - use IP-based rate limiting
+            client_id = f"ip_{client_host}"
+
+        # Check rate limit
+        allowed = await self.limiter.check_rate_limit(client_id)
+
+        if not allowed:
+            retry_after = self.limiter.get_retry_after(client_id)
+            return JSONResponse(
+                status_code=429,
+                content={
+                    "detail": f"Too many requests. Please wait {retry_after} seconds before trying again.",
+                    "error": "rate_limit_exceeded",
+                    "retry_after": retry_after,
+                    "message": "You're sending requests too quickly. The system will be ready again shortly.",
+                },
+                headers={
+                    "Retry-After": str(retry_after),
+                    "X-RateLimit-Limit": str(self.limiter.rate),
+                    "X-RateLimit-Remaining": "0",
+                    "X-RateLimit-Window": "60",
+                },
+            )
+
+        # Process request
+        processed_response = await call_next(request)
+        typed_response: Response = cast(Response, processed_response)
+
+        # Add rate limit headers to response
+        if client_id in self.limiter.buckets:
+            tokens, _ = self.limiter.buckets[client_id]
+            typed_response.headers["X-RateLimit-Limit"] = str(self.limiter.rate)
+            typed_response.headers["X-RateLimit-Remaining"] = str(int(tokens))
+            typed_response.headers["X-RateLimit-Window"] = "60"
+
+        return typed_response

ciris_engine/logic/adapters/api/models.py

@@ -0,0 +1,29 @@
+"""
+Shared models for API responses.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+from ciris_engine.schemas.types import JSONDict
+
+
+class StandardResponse(BaseModel):
+    """Standard API response format."""
+
+    success: bool = Field(..., description="Whether the request was successful")
+    data: Optional[Any] = Field(None, description="Response data")
+    message: Optional[str] = Field(None, description="Human-readable message")
+    error: Optional[str] = Field(None, description="Error message if success is False")
+    metadata: Optional[JSONDict] = Field(default_factory=lambda: {}, description="Additional metadata")
+
+
+class TokenData(BaseModel):
+    """Token data for authenticated users."""
+
+    username: str = Field(..., description="Username")
+    email: Optional[str] = Field(None, description="User email")
+    role: str = Field("OBSERVER", description="User role (OBSERVER, ADMIN, AUTHORITY, SYSTEM_ADMIN)")
+    exp: Optional[datetime] = Field(None, description="Token expiration")