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

yirifi_ops_auth/__init__.py

@@ -0,0 +1,58 @@
+"""Yirifi Ops Auth Client - Authentication library for Yirifi Ops microsites."""
+
+from yirifi_ops_auth.client import YirifiOpsAuthClient
+from yirifi_ops_auth.middleware import setup_auth_middleware, AuthMiddleware
+from yirifi_ops_auth.decorators import (
+    require_auth,
+    require_admin,
+    require_access,
+    # RBAC decorators
+    require_permission,
+    require_any_permission,
+    require_all_permissions,
+    require_role,
+    # Helpers
+    get_current_user,
+    is_authenticated,
+)
+from yirifi_ops_auth.models import AuthUser, VerifyResult
+from yirifi_ops_auth.exceptions import AuthenticationError, AuthorizationError
+from yirifi_ops_auth.local_user import (
+    ensure_local_user,
+    get_current_user_id,
+    get_current_user_context,
+    LocalUserMixin,
+)
+
+__version__ = '3.2.1'
+
+__all__ = [
+    # Client
+    'YirifiOpsAuthClient',
+    # Middleware
+    'setup_auth_middleware',
+    'AuthMiddleware',
+    # Auth decorators
+    'require_auth',
+    'require_admin',  # deprecated
+    'require_access',
+    # RBAC decorators
+    'require_permission',
+    'require_any_permission',
+    'require_all_permissions',
+    'require_role',
+    # Helpers
+    'get_current_user',
+    'is_authenticated',
+    # Local user helpers
+    'ensure_local_user',
+    'get_current_user_id',
+    'get_current_user_context',
+    'LocalUserMixin',
+    # Models
+    'AuthUser',
+    'VerifyResult',
+    # Exceptions
+    'AuthenticationError',
+    'AuthorizationError',
+]

yirifi_ops_auth/client.py

@@ -0,0 +1,154 @@
+"""HTTP client for auth service communication."""
+import httpx
+from typing import Optional
+
+from yirifi_ops_auth.models import AuthUser, VerifyResult
+from yirifi_ops_auth.exceptions import AuthServiceError
+
+
+class YirifiOpsAuthClient:
+    """Client for communicating with the Yirifi Ops Auth Service."""
+
+    def __init__(
+        self,
+        auth_service_url: str,
+        timeout: float = 5.0,
+        verify_ssl: bool = True
+    ):
+        """
+        Initialize the auth client.
+
+        Args:
+            auth_service_url: Base URL of the auth service (e.g., 'http://localhost:5100')
+            timeout: Request timeout in seconds
+            verify_ssl: Whether to verify SSL certificates
+        """
+        self.auth_service_url = auth_service_url.rstrip('/')
+        self.timeout = timeout
+        self._client = httpx.Client(
+            timeout=timeout,
+            verify=verify_ssl
+        )
+
+    def verify(
+        self,
+        session_cookie: Optional[str] = None,
+        api_key: Optional[str] = None,
+        microsite_id: Optional[str] = None,
+        app_id: Optional[str] = None,
+        permission: Optional[str] = None
+    ) -> VerifyResult:
+        """
+        Verify session cookie or API key with auth service.
+
+        Args:
+            session_cookie: Session cookie value (yirifi_ops_session)
+            api_key: API key for programmatic access
+            microsite_id: Optional microsite ID to check access for (deprecated, use app_id)
+            app_id: Application ID to get app-specific roles/permissions
+            permission: Specific permission to verify
+
+        Returns:
+            VerifyResult with validation status, user info, and permissions
+        """
+        if not session_cookie and not api_key:
+            return VerifyResult(
+                valid=False,
+                error='no_credentials',
+                redirect_url=f'{self.auth_service_url}/auth/login'
+            )
+
+        headers = {}
+        if session_cookie:
+            headers['Cookie'] = f'yirifi_ops_session={session_cookie}'
+        if api_key:
+            headers['X-API-Key'] = api_key
+
+        payload = {}
+        # Support both app_id (new) and microsite_id (legacy)
+        if app_id:
+            payload['app_id'] = app_id
+        elif microsite_id:
+            payload['app_id'] = microsite_id
+        if permission:
+            payload['permission'] = permission
+
+        try:
+            response = self._client.post(
+                f'{self.auth_service_url}/api/v1/auth/verify',
+                headers=headers,
+                json=payload if payload else None
+            )
+
+            data = response.json()
+
+            if data.get('valid'):
+                user_data = data['user']
+                access_data = data.get('access', {})
+
+                return VerifyResult(
+                    valid=True,
+                    user=AuthUser(
+                        user_id=user_data.get('user_id'),
+                        id=user_data['id'],
+                        email=user_data['email'],
+                        display_name=user_data['display_name'],
+                        is_admin=user_data.get('is_admin', False),
+                        microsites=access_data.get('microsites', user_data.get('microsites', [])),
+                        # RBAC fields
+                        roles=access_data.get('roles', []),
+                        permissions=access_data.get('permissions', []),
+                        effective_role=access_data.get('effective_role')
+                    ),
+                    has_access=access_data.get('has_access', True),
+                    role=access_data.get('effective_role', access_data.get('role'))
+                )
+            else:
+                # Ensure redirect_url is absolute (prepend auth_service_url if relative)
+                redirect_url = data.get('redirect_url', '/auth/login')
+                if redirect_url.startswith('/'):
+                    redirect_url = f'{self.auth_service_url}{redirect_url}'
+                return VerifyResult(
+                    valid=False,
+                    error=data.get('error'),
+                    redirect_url=redirect_url
+                )
+
+        except httpx.RequestError as e:
+            raise AuthServiceError(f'Failed to connect to auth service: {e}')
+        except Exception as e:
+            raise AuthServiceError(f'Auth verification failed: {e}')
+
+    def get_login_url(self, return_url: str = '') -> str:
+        """Get the login URL with optional return URL."""
+        if return_url:
+            return f'{self.auth_service_url}/auth/login?return_url={return_url}'
+        return f'{self.auth_service_url}/auth/login'
+
+    def get_access_denied_url(self, app_id: str = '', return_url: str = '') -> str:
+        """Get the access denied page URL with app context."""
+        from urllib.parse import urlencode
+        params = {}
+        if app_id:
+            params['app_id'] = app_id
+        if return_url:
+            params['return_url'] = return_url
+        if params:
+            return f'{self.auth_service_url}/auth/access-denied?{urlencode(params)}'
+        return f'{self.auth_service_url}/auth/access-denied'
+
+    def get_logout_url(self, return_url: str = '') -> str:
+        """Get the logout URL with optional return URL."""
+        if return_url:
+            return f'{self.auth_service_url}/auth/logout?return_url={return_url}'
+        return f'{self.auth_service_url}/auth/logout'
+
+    def close(self):
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

yirifi_ops_auth/decorators.py

@@ -0,0 +1,213 @@
+"""Authentication decorators for Flask routes."""
+from functools import wraps
+from flask import g
+
+from yirifi_ops_auth.exceptions import AuthenticationError, AuthorizationError
+
+
+def require_auth(f):
+    """
+    Decorator to require authentication on a route.
+
+    The middleware already handles authentication, but this decorator
+    provides an explicit check for routes that must have a user.
+
+    Example:
+        @app.route('/profile')
+        @require_auth
+        def profile():
+            return f"Hello {g.current_user.display_name}"
+    """
+    @wraps(f)
+    def decorated(*args, **kwargs):
+        if not hasattr(g, 'current_user') or g.current_user is None:
+            raise AuthenticationError('Authentication required')
+        return f(*args, **kwargs)
+    return decorated
+
+
+def require_admin(f):
+    """
+    Decorator to require admin privileges.
+
+    DEPRECATED: Use @require_permission('admin:access') or @require_role('super_admin') instead.
+
+    Example:
+        @app.route('/admin')
+        @require_admin
+        def admin_panel():
+            return "Admin only content"
+    """
+    @wraps(f)
+    def decorated(*args, **kwargs):
+        if not hasattr(g, 'current_user') or g.current_user is None:
+            raise AuthenticationError('Authentication required')
+        # Use role check instead of deprecated is_admin field
+        if not g.current_user.has_role('super_admin'):
+            raise AuthorizationError('Admin access required')
+        return f(*args, **kwargs)
+    return decorated
+
+
+def require_permission(permission: str):
+    """
+    Decorator factory to require a specific permission.
+
+    Args:
+        permission: Permission code to require (e.g., 'report:create')
+
+    Example:
+        @app.route('/reports', methods=['POST'])
+        @require_permission('report:create')
+        def create_report():
+            # User has report:create permission
+            return create_new_report(request.json)
+    """
+    def decorator(f):
+        @wraps(f)
+        def decorated(*args, **kwargs):
+            if not hasattr(g, 'current_user') or g.current_user is None:
+                raise AuthenticationError('Authentication required')
+
+            if not g.current_user.has_permission(permission):
+                raise AuthorizationError(f'Permission denied: {permission}')
+
+            return f(*args, **kwargs)
+        return decorated
+    return decorator
+
+
+def require_any_permission(*permissions: str):
+    """
+    Decorator factory to require at least one of the specified permissions.
+
+    Args:
+        *permissions: Permission codes to check
+
+    Example:
+        @require_any_permission('report:read', 'report:create')
+        def view_reports():
+            return get_reports()
+    """
+    def decorator(f):
+        @wraps(f)
+        def decorated(*args, **kwargs):
+            if not hasattr(g, 'current_user') or g.current_user is None:
+                raise AuthenticationError('Authentication required')
+
+            if not g.current_user.has_any_permission(*permissions):
+                raise AuthorizationError(
+                    f'Permission denied. Required one of: {", ".join(permissions)}'
+                )
+
+            return f(*args, **kwargs)
+        return decorated
+    return decorator
+
+
+def require_all_permissions(*permissions: str):
+    """
+    Decorator factory to require all of the specified permissions.
+
+    Args:
+        *permissions: Permission codes to check
+
+    Example:
+        @require_all_permissions('report:read', 'data:export')
+        def export_report():
+            return generate_export()
+    """
+    def decorator(f):
+        @wraps(f)
+        def decorated(*args, **kwargs):
+            if not hasattr(g, 'current_user') or g.current_user is None:
+                raise AuthenticationError('Authentication required')
+
+            if not g.current_user.has_all_permissions(*permissions):
+                missing = [p for p in permissions if not g.current_user.has_permission(p)]
+                raise AuthorizationError(
+                    f'Permission denied. Missing: {", ".join(missing)}'
+                )
+
+            return f(*args, **kwargs)
+        return decorated
+    return decorator
+
+
+def require_role(role: str):
+    """
+    Decorator factory to require a specific role.
+
+    Note: Prefer using @require_permission() over @require_role() as it
+    provides more granular access control.
+
+    Args:
+        role: Role code to require (e.g., 'admin', 'editor')
+
+    Example:
+        @require_role('admin')
+        def admin_dashboard():
+            return render_template('admin/dashboard.html')
+    """
+    def decorator(f):
+        @wraps(f)
+        def decorated(*args, **kwargs):
+            if not hasattr(g, 'current_user') or g.current_user is None:
+                raise AuthenticationError('Authentication required')
+
+            if not g.current_user.has_role(role):
+                raise AuthorizationError(f'Role required: {role}')
+
+            return f(*args, **kwargs)
+        return decorated
+    return decorator
+
+
+def require_access(microsite_id: str):
+    """
+    Decorator factory to require access to a specific microsite.
+
+    This is useful when a route needs access to a different microsite
+    than the one the app is registered under.
+
+    Example:
+        @app.route('/cross-site-data')
+        @require_access('other-microsite')
+        def cross_site():
+            return "Data from other microsite"
+    """
+    def decorator(f):
+        @wraps(f)
+        def decorated(*args, **kwargs):
+            if not hasattr(g, 'current_user') or g.current_user is None:
+                raise AuthenticationError('Authentication required')
+            if not g.current_user.has_access_to(microsite_id):
+                raise AuthorizationError(f'Access denied to {microsite_id}')
+            return f(*args, **kwargs)
+        return decorated
+    return decorator
+
+
+def get_current_user():
+    """
+    Get the current authenticated user.
+
+    Returns:
+        AuthUser or None if not authenticated
+
+    Example:
+        user = get_current_user()
+        if user:
+            print(f"Logged in as {user.email}")
+    """
+    return getattr(g, 'current_user', None)
+
+
+def is_authenticated() -> bool:
+    """
+    Check if the current request is authenticated.
+
+    Returns:
+        True if user is authenticated
+    """
+    return hasattr(g, 'current_user') and g.current_user is not None

yirifi_ops_auth/deeplink/__init__.py

@@ -0,0 +1,210 @@
+"""Deep linking module for cross-microsite navigation.
+
+This module provides tools to generate URLs to entities across different
+Yirifi Ops microsites with permission-aware rendering.
+
+Quick Start:
+    1. Register your microsite's entities:
+        from yirifi_ops_auth.deeplink import register_entities
+
+        register_entities(
+            microsite_id="risk",
+            name="Risk Dashboard",
+            urls={"dev": "http://localhost:5012", "uat": "...", "prd": "..."},
+            entities=[
+                {"type": "risk_item", "path": "/items/{id}"},
+            ]
+        )
+
+    2. Set up in your Flask app:
+        from yirifi_ops_auth.deeplink import setup_deeplinks
+        setup_deeplinks(app, env='dev')
+
+    3. Use in templates:
+        {{ cross_link('risk_item', item.r_yid, 'Open in Risk Dashboard') }}
+
+    4. Or use in Python:
+        from yirifi_ops_auth.deeplink import resolve_link
+        url = resolve_link('risk_item', 'r_yid_123')
+
+Federation (v3.1.0+):
+    Enable cross-microsite entity discovery without manual registration:
+
+        setup_deeplinks(
+            app,
+            env='dev',
+            enable_federation=True,  # Queries auth service + microsites
+            expose_references=True,  # Exposes /api/v1/references
+        )
+
+    Now templates can use entities from ANY microsite:
+        {{ cross_link('reg_link', link.id) }}  # Works without registering!
+
+Registration Functions:
+    - register_entities: Register a microsite and its entities (bulk)
+    - register_microsite: Register a microsite configuration
+    - register_entity: Register a single entity definition
+    - load_from_yaml: Load entity definitions from YAML file
+    - clear_registry: Clear all registrations (for testing)
+
+Resolution Functions:
+    - setup_deeplinks: Initialize deep linking for a Flask app
+    - resolve_link: Generate a URL for an entity
+    - deep_link_info: Get URL + accessibility info
+    - can_link_to: Check if user can access an entity's microsite
+
+Template Helpers (available after setup_deeplinks):
+    - {{ deep_link(entity_type, entity_id) }} - Returns URL string
+    - {{ deep_link_info(entity_type, entity_id) }} - Returns DeepLinkInfo object
+    - {{ cross_link(entity_type, entity_id, label) }} - Renders permission-aware link
+    - {{ cross_link_button(entity_type, entity_id, label) }} - Renders styled button
+
+Registry Query Functions:
+    - get_entity_definition: Get definition for an entity type
+    - list_entity_types: List all registered entity types
+    - list_entity_types_for_microsite: List entity types for a microsite
+    - list_microsites: List all registered microsites
+
+Federation Functions:
+    - configure_federation: Configure and start federation client
+    - get_federation_client: Get the federation client singleton
+    - stop_federation: Stop the federation client
+    - FederationConfig: Configuration dataclass for federation
+
+Environment:
+    - Environment: Thread-safe environment class with get/set/override
+    - get_environment: Get current environment (dev/uat/prd)
+    - set_environment: Explicitly set environment
+"""
+
+# Flask integration
+from .jinja import setup_deeplinks
+
+# Core resolution
+from .resolver import (
+    resolve_link,
+    deep_link_info,
+    can_link_to,
+    get_entity_microsite_name,
+    DeepLinkInfo,
+    DeepLinkError,
+    UnknownEntityTypeError,
+    UnknownMicrositeError,
+)
+
+# Registry - registration functions
+from .registry import (
+    register_entities,
+    register_microsite,
+    register_entity,
+    clear_registry,
+    get_registry,
+    # Query functions
+    get_entity_definition,
+    get_microsite_for_entity,
+    get_microsite_config,
+    get_microsite_name,
+    get_microsite_base_url,
+    list_entity_types,
+    list_entity_types_for_microsite,
+    list_microsites,
+    # Types
+    EntityDefinition,
+    MicrositeConfig,
+    RegistrationError,
+    DeepLinkRegistry,
+)
+
+# YAML loading
+from .yaml_loader import (
+    load_from_yaml,
+    load_from_string,
+    discover_and_load,
+    YamlLoadError,
+)
+
+# Environment
+from .environment import (
+    Environment,
+    get_environment,
+    set_environment,
+    VALID_ENVIRONMENTS,
+)
+
+# Federation
+from .federation import (
+    configure_federation,
+    get_federation_client,
+    stop_federation,
+    clear_federation_cache,
+    FederationConfig,
+    FederationClient,
+    FederationError,
+    FederationTimeoutError,
+    FederationConnectionError,
+)
+
+# Blueprint for /api/v1/references
+from .blueprint import references_bp
+
+__all__ = [
+    # Flask integration
+    'setup_deeplinks',
+
+    # Core resolution
+    'resolve_link',
+    'deep_link_info',
+    'can_link_to',
+    'get_entity_microsite_name',
+    'DeepLinkInfo',
+    'DeepLinkError',
+    'UnknownEntityTypeError',
+    'UnknownMicrositeError',
+
+    # Registration
+    'register_entities',
+    'register_microsite',
+    'register_entity',
+    'clear_registry',
+    'get_registry',
+    'load_from_yaml',
+    'load_from_string',
+    'discover_and_load',
+    'RegistrationError',
+    'YamlLoadError',
+
+    # Registry queries
+    'get_entity_definition',
+    'get_microsite_for_entity',
+    'get_microsite_config',
+    'get_microsite_name',
+    'get_microsite_base_url',
+    'list_entity_types',
+    'list_entity_types_for_microsite',
+    'list_microsites',
+
+    # Types
+    'EntityDefinition',
+    'MicrositeConfig',
+    'DeepLinkRegistry',
+
+    # Environment
+    'Environment',
+    'get_environment',
+    'set_environment',
+    'VALID_ENVIRONMENTS',
+
+    # Federation
+    'configure_federation',
+    'get_federation_client',
+    'stop_federation',
+    'clear_federation_cache',
+    'FederationConfig',
+    'FederationClient',
+    'FederationError',
+    'FederationTimeoutError',
+    'FederationConnectionError',
+
+    # Blueprint
+    'references_bp',
+]