yirifi-ops-auth-client 3.2.3__py3-none-any.whl

yirifi_ops_auth/deeplink/yaml_loader.py

@@ -0,0 +1,242 @@
+"""YAML configuration loader for deep linking.
+
+Allows microsites to define their entity configurations in YAML files
+instead of programmatic registration.
+
+Example YAML file (deeplinks.yaml):
+
+    schema_version: "1.0"
+    microsite:
+      id: risk
+      name: Risk Dashboard
+      urls:
+        dev: http://localhost:5012
+        uat: https://risk-uat.ops.yirifi.com
+        prd: https://risk.ops.yirifi.com
+
+    entities:
+      risk_item:
+        path: /risk-management/collections/risk_items/{id}
+        description: Risk management item
+      risk_hierarchy:
+        path: /risk-management/collections/risk_hierarchies/{id}
+
+Usage:
+    from yirifi_ops_auth.deeplink import load_from_yaml
+
+    # Load from file path
+    load_from_yaml("deeplinks.yaml")
+
+    # Or with Path object
+    from pathlib import Path
+    load_from_yaml(Path("config/deeplinks.yaml"))
+"""
+
+import logging
+from pathlib import Path
+from typing import Union, Optional
+
+logger = logging.getLogger(__name__)
+
+# Supported schema versions
+SUPPORTED_SCHEMA_VERSIONS = {"1.0"}
+
+
+class YamlLoadError(Exception):
+    """Raised when YAML loading or validation fails."""
+    pass
+
+
+def load_from_yaml(path: Union[str, Path]) -> None:
+    """Load entity definitions from a YAML file.
+
+    Args:
+        path: Path to the YAML configuration file
+
+    Raises:
+        YamlLoadError: If file not found, YAML invalid, or schema validation fails
+        ImportError: If PyYAML is not installed
+    """
+    try:
+        import yaml
+    except ImportError:
+        raise ImportError(
+            "PyYAML is required for YAML loading. Install with: pip install pyyaml"
+        )
+
+    path = Path(path)
+
+    if not path.exists():
+        raise YamlLoadError(f"Configuration file not found: {path}")
+
+    try:
+        with open(path) as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise YamlLoadError(f"Invalid YAML in {path}: {e}")
+
+    if not data:
+        raise YamlLoadError(f"Empty configuration file: {path}")
+
+    _validate_and_register(data, source=str(path))
+    logger.info(f"Loaded deep link configuration from {path}")
+
+
+def load_from_string(yaml_content: str, source: str = "<string>") -> None:
+    """Load entity definitions from a YAML string.
+
+    Useful for testing or when YAML is embedded/generated.
+
+    Args:
+        yaml_content: YAML content as a string
+        source: Description of source for error messages
+    """
+    try:
+        import yaml
+    except ImportError:
+        raise ImportError(
+            "PyYAML is required for YAML loading. Install with: pip install pyyaml"
+        )
+
+    try:
+        data = yaml.safe_load(yaml_content)
+    except yaml.YAMLError as e:
+        raise YamlLoadError(f"Invalid YAML from {source}: {e}")
+
+    if not data:
+        raise YamlLoadError(f"Empty configuration from {source}")
+
+    _validate_and_register(data, source=source)
+
+
+def _validate_and_register(data: dict, source: str) -> None:
+    """Validate YAML data and register with the registry.
+
+    Args:
+        data: Parsed YAML data
+        source: Source description for error messages
+    """
+    from .registry import register_entities
+
+    # Check schema version
+    schema_version = data.get("schema_version", "1.0")
+    if schema_version not in SUPPORTED_SCHEMA_VERSIONS:
+        raise YamlLoadError(
+            f"Unsupported schema_version '{schema_version}' in {source}. "
+            f"Supported: {SUPPORTED_SCHEMA_VERSIONS}"
+        )
+
+    # Validate microsite section
+    microsite = data.get("microsite")
+    if not microsite:
+        raise YamlLoadError(f"Missing 'microsite' section in {source}")
+
+    microsite_id = microsite.get("id")
+    if not microsite_id:
+        raise YamlLoadError(f"Missing 'microsite.id' in {source}")
+
+    microsite_name = microsite.get("name")
+    if not microsite_name:
+        raise YamlLoadError(f"Missing 'microsite.name' in {source}")
+
+    urls = microsite.get("urls")
+    if not urls:
+        raise YamlLoadError(f"Missing 'microsite.urls' in {source}")
+
+    # Validate required URLs
+    required_envs = {"dev", "uat", "prd"}
+    missing_envs = required_envs - set(urls.keys())
+    if missing_envs:
+        raise YamlLoadError(
+            f"Missing URLs for environments {missing_envs} in {source}"
+        )
+
+    # Validate entities section
+    entities_data = data.get("entities", {})
+    if not entities_data:
+        logger.warning(f"No entities defined in {source}")
+
+    # Convert to list format expected by register_entities
+    entities = []
+    for entity_type, entity_config in entities_data.items():
+        if not isinstance(entity_config, dict):
+            raise YamlLoadError(
+                f"Entity '{entity_type}' must be a dict in {source}"
+            )
+
+        path = entity_config.get("path")
+        if not path:
+            raise YamlLoadError(
+                f"Entity '{entity_type}' missing 'path' in {source}"
+            )
+
+        if "{id}" not in path:
+            raise YamlLoadError(
+                f"Entity '{entity_type}' path must contain {{id}}: {path}"
+            )
+
+        entities.append({
+            "type": entity_type,
+            "path": path,
+            "description": entity_config.get("description"),
+        })
+
+    # Register everything
+    register_entities(
+        microsite_id=microsite_id,
+        name=microsite_name,
+        urls=urls,
+        entities=entities,
+    )
+
+    logger.debug(
+        f"Registered {len(entities)} entities for '{microsite_id}' from {source}"
+    )
+
+
+def discover_and_load(
+    search_paths: Optional[list[Union[str, Path]]] = None,
+    filenames: Optional[list[str]] = None,
+) -> int:
+    """Discover and load YAML files from multiple locations.
+
+    Searches for configuration files in the given paths and loads them.
+
+    Args:
+        search_paths: Directories to search (default: current directory)
+        filenames: Filenames to look for (default: deeplinks.yaml, deeplinks.yml)
+
+    Returns:
+        Number of files loaded
+
+    Example:
+        # Load from current directory
+        discover_and_load()
+
+        # Load from specific directories
+        discover_and_load(search_paths=["config/", "deeplink_configs/"])
+    """
+    if search_paths is None:
+        search_paths = [Path.cwd()]
+
+    if filenames is None:
+        filenames = ["deeplinks.yaml", "deeplinks.yml"]
+
+    loaded_count = 0
+
+    for search_path in search_paths:
+        search_path = Path(search_path)
+        if not search_path.exists():
+            logger.debug(f"Search path does not exist: {search_path}")
+            continue
+
+        for filename in filenames:
+            filepath = search_path / filename
+            if filepath.exists():
+                try:
+                    load_from_yaml(filepath)
+                    loaded_count += 1
+                except YamlLoadError as e:
+                    logger.error(f"Failed to load {filepath}: {e}")
+
+    return loaded_count

yirifi_ops_auth/exceptions.py

@@ -0,0 +1,32 @@
+"""Custom exceptions for auth client."""
+
+
+class AuthClientError(Exception):
+    """Base exception for auth client errors."""
+
+    pass
+
+
+class AuthenticationError(AuthClientError):
+    """Authentication failed - user not logged in or invalid credentials."""
+
+    def __init__(self, message: str = 'Authentication required', redirect_url: str = None):
+        super().__init__(message)
+        self.message = message
+        self.redirect_url = redirect_url
+
+
+class AuthorizationError(AuthClientError):
+    """Authorization failed - user doesn't have required permissions."""
+
+    def __init__(self, message: str = 'Access denied'):
+        super().__init__(message)
+        self.message = message
+
+
+class AuthServiceError(AuthClientError):
+    """Error communicating with auth service."""
+
+    def __init__(self, message: str = 'Auth service unavailable'):
+        super().__init__(message)
+        self.message = message

yirifi_ops_auth/local_user.py

@@ -0,0 +1,124 @@
+"""
+Local User Helpers
+
+Provides utilities for microsites to manage local user tables that sync
+from the central auth service.
+
+Usage:
+    from yirifi_ops_auth.local_user import ensure_local_user, get_current_user_id
+
+    @app.before_request
+    def before_request():
+        ensure_local_user(db.session)
+
+    @app.route('/api/chat', methods=['POST'])
+    @require_auth
+    def create_chat():
+        chat = ChatHistory(user_id=get_current_user_id(), ...)
+"""
+
+from flask import g
+from sqlalchemy import text
+from datetime import datetime, timezone
+
+from yirifi_ops_auth.exceptions import AuthenticationError
+
+
+def get_current_user_id() -> str:
+    """
+    Get the current user's immutable ID for storage in domain tables.
+
+    Returns:
+        str: UUID string of the current user
+
+    Raises:
+        AuthenticationError: If no user is authenticated
+    """
+    if not hasattr(g, 'current_user') or not g.current_user:
+        raise AuthenticationError("No authenticated user")
+    return g.current_user.user_id
+
+
+def get_current_user_context() -> dict:
+    """
+    Get the current user's display info for API responses.
+
+    Returns:
+        dict: User info including user_id, display_name, email
+
+    Raises:
+        AuthenticationError: If no user is authenticated
+    """
+    if not hasattr(g, 'current_user') or not g.current_user:
+        raise AuthenticationError("No authenticated user")
+
+    user = g.current_user
+    return {
+        'user_id': user.user_id,
+        'display_name': user.display_name,
+        'email': user.email
+    }
+
+
+def ensure_local_user(db_session):
+    """
+    Ensure current user exists in local users table.
+
+    This should be called in a before_request hook after auth middleware
+    sets g.current_user. It handles the case where a new user logs in
+    before the daily sync has run.
+
+    The INSERT uses ON CONFLICT DO NOTHING because:
+    - If user exists, sync job keeps data fresh
+    - If user is new, this creates the record
+    - We don't update on login to avoid overwriting sync data
+
+    Args:
+        db_session: SQLAlchemy session (e.g., db.session)
+    """
+    if not hasattr(g, 'current_user') or not g.current_user:
+        return
+
+    user = g.current_user
+    try:
+        db_session.execute(text("""
+            INSERT INTO users (user_id, email, display_name, is_active, synced_at, created_at)
+            VALUES (:user_id, :email, :display_name, true, :synced_at, :created_at)
+            ON CONFLICT (user_id) DO NOTHING
+        """), {
+            'user_id': user.user_id,
+            'email': user.email,
+            'display_name': user.display_name,
+            'synced_at': datetime.now(timezone.utc),
+            'created_at': datetime.now(timezone.utc)
+        })
+        db_session.commit()
+    except Exception:
+        db_session.rollback()
+        # Silently fail - sync job will handle it
+        pass
+
+
+class LocalUserMixin:
+    """
+    Mixin for the local users table model.
+
+    Usage:
+        from yirifi_ops_auth.local_user import LocalUserMixin
+
+        class User(db.Model, LocalUserMixin):
+            __tablename__ = 'users'
+
+            # Additional fields specific to this microsite
+            preferences = db.Column(db.JSON, default={})
+    """
+    from sqlalchemy import Column, String, Boolean, DateTime
+    from sqlalchemy.dialects.postgresql import UUID
+    from sqlalchemy.sql import func
+
+    user_id = Column(UUID(as_uuid=True), primary_key=True)
+    email = Column(String(255), nullable=False)
+    display_name = Column(String(100))
+    is_active = Column(Boolean, default=True)
+    synced_at = Column(DateTime(timezone=True), default=func.now())
+    created_at = Column(DateTime(timezone=True), default=func.now())

yirifi_ops_auth/middleware.py

@@ -0,0 +1,281 @@
+"""Flask middleware for authentication."""
+from flask import Flask, request, redirect, g, current_app
+from typing import Optional, Callable
+
+from yirifi_ops_auth.client import YirifiOpsAuthClient
+from yirifi_ops_auth.exceptions import AuthenticationError, AuthorizationError, AuthServiceError
+
+
+class AuthMiddleware:
+    """Authentication middleware for Flask applications with RBAC support."""
+
+    def __init__(
+        self,
+        app: Flask,
+        auth_client: YirifiOpsAuthClient,
+        microsite_id: str = None,
+        app_id: str = None,
+        excluded_paths: Optional[list[str]] = None,
+        excluded_prefixes: Optional[list[str]] = None,
+        require_app_access: bool = True
+    ):
+        """
+        Initialize auth middleware.
+
+        Args:
+            app: Flask application
+            auth_client: YirifiOpsAuthClient instance
+            microsite_id: ID of this microsite (deprecated, use app_id)
+            app_id: Application ID for RBAC (e.g., 'sidebyside')
+            excluded_paths: Exact paths to exclude from auth (e.g., ['/health'])
+            excluded_prefixes: Path prefixes to exclude (e.g., ['/api/v1/health'])
+            require_app_access: If True (default), require user to have explicit role
+                              assignment in this app. Set to False only during RBAC
+                              migration to allow any authenticated user temporarily.
+        """
+        self.app = app
+        self.auth_client = auth_client
+        # Support both app_id (new) and microsite_id (legacy)
+        self.app_id = app_id or microsite_id
+        self.microsite_id = self.app_id  # Keep for backward compatibility
+        self.require_app_access = require_app_access
+        self.excluded_paths = excluded_paths or []
+        # Default exclusions - always included
+        default_prefixes = [
+            '/api/v1/health',
+            '/static',
+            '/favicon.ico',
+            # API documentation - allow public access for tooling
+            '/api/v1/swagger.json',
+            '/api/v1/openapi.json',
+            '/api/docs',
+            '/api/v1/docs',
+            '/swagger.json',
+            '/openapi.json',
+        ]
+        # Merge app-specific prefixes with defaults (app prefixes take priority)
+        if excluded_prefixes:
+            self.excluded_prefixes = list(set(default_prefixes + excluded_prefixes))
+        else:
+            self.excluded_prefixes = default_prefixes
+
+        # Store on app for access in routes
+        app.auth_client = auth_client
+        app.microsite_id = self.app_id  # Legacy
+        app.app_id = self.app_id  # New
+
+        # Register middleware
+        app.before_request(self._authenticate_request)
+
+        # Register error handlers
+        self._register_error_handlers()
+
+    def _is_excluded(self, path: str) -> bool:
+        """Check if path should be excluded from authentication."""
+        if path in self.excluded_paths:
+            return True
+        for prefix in self.excluded_prefixes:
+            if path.startswith(prefix):
+                return True
+        return False
+
+    def _authenticate_request(self):
+        """Authenticate incoming request.
+
+        Note: Returns responses directly instead of raising exceptions because
+        Flask's @errorhandler doesn't catch exceptions from before_request hooks.
+        """
+        # Skip excluded paths
+        if self._is_excluded(request.path):
+            return None
+
+        # Get credentials
+        session_cookie = request.cookies.get('yirifi_ops_session')
+        api_key = request.headers.get('X-API-Key')
+
+        # No credentials
+        if not session_cookie and not api_key:
+            return self._handle_unauthenticated()
+
+        # Verify with auth service (pass app_id for RBAC)
+        try:
+            result = self.auth_client.verify(
+                session_cookie=session_cookie,
+                api_key=api_key,
+                app_id=self.app_id
+            )
+        except AuthServiceError as e:
+            # Auth service unavailable - fail open or closed based on config
+            if current_app.config.get('AUTH_FAIL_OPEN', False):
+                g.current_user = None
+                g.auth_method = None
+                return None
+            # Return error response directly
+            return self._handle_auth_service_error(e.message)
+
+        # Invalid credentials
+        if not result.valid:
+            if api_key:
+                # API request - return 401 directly
+                return self._make_auth_error_response(result.error or 'Invalid API key')
+            else:
+                # Browser request - redirect to login
+                return self._handle_unauthenticated(result.redirect_url)
+
+        # Check app access (only if require_app_access is enabled)
+        if self.require_app_access and not result.has_access:
+            return self._handle_access_denied(f'Access denied to {self.app_id}')
+
+        # Store user in request context
+        g.current_user = result.user
+        g.auth_method = 'api_key' if api_key else 'session'
+        g.has_app_access = result.has_access  # Store for route-level checks
+
+        return None
+
+    def _is_api_request(self) -> bool:
+        """Detect if this is an API request (should get JSON errors, not redirects)."""
+        # Explicit API key header
+        if request.headers.get('X-API-Key'):
+            return True
+        # JSON content type
+        if request.is_json:
+            return True
+        # Accept header prefers JSON
+        accept = request.headers.get('Accept', '')
+        if 'application/json' in accept and 'text/html' not in accept:
+            return True
+        # API path patterns (swagger, openapi, etc.)
+        path = request.path.lower()
+        if any(pattern in path for pattern in ['/api/', 'swagger', 'openapi', '.json']):
+            return True
+        return False
+
+    def _handle_unauthenticated(self, redirect_url: str = None):
+        """Handle unauthenticated request."""
+        # Check if API request - return JSON error instead of redirect
+        if self._is_api_request():
+            return self._make_auth_error_response('Authentication required')
+
+        # Browser request - redirect to login
+        return_url = request.url
+        login_url = redirect_url or self.auth_client.get_login_url(return_url)
+        return redirect(login_url)
+
+    def _make_auth_error_response(self, message: str):
+        """Create a 401 JSON error response for API requests."""
+        from flask import jsonify, make_response
+        response = make_response(jsonify({
+            'success': False,
+            'error': {
+                'code': 'AUTHENTICATION_REQUIRED',
+                'message': message
+            }
+        }), 401)
+        return response
+
+    def _handle_access_denied(self, message: str):
+        """Handle access denied - user authenticated but lacks permission."""
+        if self._is_api_request():
+            from flask import jsonify, make_response
+            response = make_response(jsonify({
+                'success': False,
+                'error': {
+                    'code': 'ACCESS_DENIED',
+                    'message': message
+                }
+            }), 403)
+            return response
+        # Browser request - redirect to access denied page
+        access_denied_url = self.auth_client.get_access_denied_url(
+            app_id=self.app_id,
+            return_url=request.url
+        )
+        return redirect(access_denied_url)
+
+    def _handle_auth_service_error(self, message: str):
+        """Handle auth service unavailable error."""
+        from flask import jsonify, make_response, render_template_string
+        if self._is_api_request():
+            response = make_response(jsonify({
+                'success': False,
+                'error': {
+                    'code': 'AUTH_SERVICE_ERROR',
+                    'message': 'Authentication service unavailable'
+                }
+            }), 503)
+            return response
+        # Browser request - show error page
+        error_html = """
+        <!DOCTYPE html>
+        <html><head><title>Service Unavailable</title></head>
+        <body style="font-family: sans-serif; text-align: center; padding: 50px;">
+            <h1>Service Temporarily Unavailable</h1>
+            <p>The authentication service is currently unavailable. Please try again later.</p>
+        </body></html>
+        """
+        return make_response(render_template_string(error_html), 503)
+
+    def _register_error_handlers(self):
+        """Register error handlers for auth exceptions."""
+
+        @self.app.errorhandler(AuthenticationError)
+        def handle_auth_error(error):
+            if self._is_api_request():
+                return {
+                    'success': False,
+                    'error': {
+                        'code': 'AUTHENTICATION_REQUIRED',
+                        'message': error.message
+                    }
+                }, 401
+            return redirect(error.redirect_url or self.auth_client.get_login_url(request.url))
+
+        @self.app.errorhandler(AuthorizationError)
+        def handle_authz_error(error):
+            if self._is_api_request():
+                return {
+                    'success': False,
+                    'error': {
+                        'code': 'ACCESS_DENIED',
+                        'message': error.message
+                    }
+                }, 403
+            # Browser request - redirect to access denied page
+            access_denied_url = self.auth_client.get_access_denied_url(
+                app_id=self.app_id,
+                return_url=request.url
+            )
+            return redirect(access_denied_url)
+
+
+def setup_auth_middleware(
+    app: Flask,
+    auth_client: YirifiOpsAuthClient,
+    microsite_id: str,
+    **kwargs
+) -> AuthMiddleware:
+    """
+    Set up authentication middleware for a Flask app.
+
+    Args:
+        app: Flask application
+        auth_client: YirifiOpsAuthClient instance
+        microsite_id: ID of this microsite
+        **kwargs: Additional options passed to AuthMiddleware
+
+    Returns:
+        Configured AuthMiddleware instance
+
+    Example:
+        from yirifi_ops_auth import YirifiOpsAuthClient, setup_auth_middleware
+
+        def create_app():
+            app = Flask(__name__)
+
+            auth_client = YirifiOpsAuthClient(app.config['AUTH_SERVICE_URL'])
+            setup_auth_middleware(app, auth_client, microsite_id='sidebyside')
+
+            return app
+    """
+    return AuthMiddleware(app, auth_client, microsite_id, **kwargs)