agentic-fabriq-sdk 0.1.3__py3-none-any.whl

af_sdk/__init__.py

@@ -0,0 +1,55 @@
+"""
+Agentic Fabric SDK
+
+Official Python SDK for building connectors and interacting with Agentic Fabric.
+"""
+
+from .auth.oauth import oauth_required
+from .connectors.base import AgentConnector, ConnectorContext, ToolConnector
+from .exceptions import (
+    AFError,
+    AuthenticationError,
+    AuthorizationError,
+    ConnectorError,
+    NotFoundError,
+    ValidationError,
+)
+from .models.types import (
+    AgentInvokeRequest,
+    AgentInvokeResult,
+    ToolInvokeRequest,
+    ToolInvokeResult,
+)
+from .transport.http import HTTPClient
+from .fabriq_client import FabriqClient
+from .models.audit import AuditEvent
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "oauth_required",
+    "ToolConnector",
+    "AgentConnector",
+    "ConnectorContext",
+    "AFError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ConnectorError",
+    "NotFoundError",
+    "ValidationError",
+    "AgentInvokeRequest",
+    "AgentInvokeResult",
+    "ToolInvokeRequest",
+    "ToolInvokeResult",
+    "HTTPClient",
+    "FabriqClient",
+    "AuditEvent",
+] 
+
+# Lazy expose dx submodule under af_sdk.dx
+from importlib import import_module as _import_module  # noqa: E402
+
+def __getattr__(name):
+    if name == "dx":
+        return _import_module("af_sdk.dx")
+    raise AttributeError(name)

af_sdk/auth/__init__.py

@@ -0,0 +1,31 @@
+"""
+Authentication and authorization utilities for Agentic Fabric SDK.
+"""
+
+from .oauth import (
+    api_key_required,
+    mtls_required,
+    no_auth_required,
+    oauth_required,
+    ScopeValidator,
+    TokenValidator,
+)
+from .token_cache import TokenManager, VaultClient
+
+# DPoP helper will be provided from af_sdk.auth.dpop
+try:
+    from .dpop import create_dpop_proof
+except Exception:  # pragma: no cover - optional import if file missing
+    create_dpop_proof = None  # type: ignore
+
+__all__ = [
+    "oauth_required",
+    "api_key_required",
+    "mtls_required",
+    "no_auth_required",
+    "ScopeValidator",
+    "TokenValidator",
+    "TokenManager",
+    "VaultClient",
+    "create_dpop_proof",
+] 

af_sdk/auth/dpop.py

@@ -0,0 +1,43 @@
+"""
+Client-side DPoP (Proof of Possession) helper for AF SDK.
+
+This provides a simple HMAC-signed JWT for development that matches the
+Gateway's mock PoP verifier semantics. In production, replace with a
+DPoP JWT signed using a private key corresponding to the client cert
+thumbprint per RFC 9449.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Dict, Optional
+
+import jwt
+
+
+def create_dpop_proof(*, method: str, url: str, thumbprint: str = "dev-thumbprint", lifetime_s: int = 60, secret: Optional[str] = None) -> str:
+    """Create a development DPoP-like JWT for AF mock endpoints.
+
+    Args:
+        method: HTTP method, e.g., "POST".
+        url: Full request URL.
+        thumbprint: x5t#S256 thumbprint string (dev default).
+        lifetime_s: Token lifetime in seconds.
+        secret: HMAC secret for signing (dev only). If not provided, uses a default.
+
+    Returns:
+        A compact JWT string to send in the DPoP header.
+    """
+    now = int(time.time())
+    payload: Dict = {
+        "htm": method.upper(),
+        "htu": url,
+        "iat": now,
+        "exp": now + lifetime_s,
+        "cnf": {"x5t#S256": thumbprint},
+        "typ": "pop",
+    }
+    key = secret or "af-dev-pop-secret"
+    return jwt.encode(payload, key, algorithm="HS256")
+
+

af_sdk/auth/oauth.py

@@ -0,0 +1,247 @@
+"""
+OAuth authentication decorator and helpers.
+"""
+
+import time
+from functools import wraps
+from typing import Any, Awaitable, Callable, List, Optional
+
+from ..exceptions import AuthenticationError, TokenRefreshError
+
+
+def oauth_required(*, scopes: List[str], refresh_if_expired: bool = True):
+    """
+    Decorator that injects a valid OAuth2 Bearer token for the current user.
+
+    Automatically:
+    1. Pulls access token from TokenManager (refreshes if expired)
+    2. Populates `Authorization` header
+    3. Enforces that requested scopes ⊆ granted scopes
+
+    Args:
+        scopes: List of required OAuth scopes
+        refresh_if_expired: Whether to attempt token refresh if expired
+
+    Raises:
+        AuthenticationError: If token is invalid or missing
+        TokenRefreshError: If token refresh fails
+    """
+
+    def decorator(fn: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
+        @wraps(fn)
+        async def wrapper(self, *args, **kwargs):
+            ctx = getattr(self, "ctx", None)
+            if not ctx:
+                raise AuthenticationError("Connector context not available")
+
+            tool_id = getattr(self, "TOOL_ID", None)
+            if not tool_id:
+                raise AuthenticationError("TOOL_ID not set in connector")
+
+            try:
+                # Get OAuth token from token manager
+                token = await ctx.token_manager.get_oauth_token(
+                    tool_id=tool_id,
+                    user_id=ctx.user_id,
+                    scopes=scopes,
+                    refresh_if_expired=refresh_if_expired,
+                )
+
+                # Inject Authorization header
+                headers = kwargs.setdefault("headers", {})
+                headers.setdefault("Authorization", f"Bearer {token}")
+
+                # Log the request (without token)
+                ctx.logger.info(
+                    f"Making OAuth request to {tool_id}",
+                    extra={"scopes": scopes, "user_id": ctx.user_id},
+                )
+
+                return await fn(self, *args, **kwargs)
+
+            except Exception as e:
+                ctx.logger.error(f"OAuth authentication failed: {e}")
+                if isinstance(e, (AuthenticationError, TokenRefreshError)):
+                    raise
+                raise AuthenticationError(f"OAuth authentication failed: {e}")
+
+        return wrapper
+
+    return decorator
+
+
+def api_key_required(*, key_name: str = "api_key", header_name: str = "X-API-Key"):
+    """
+    Decorator that injects an API key for the current user.
+
+    Args:
+        key_name: Name of the API key in the vault
+        header_name: HTTP header name for the API key
+
+    Raises:
+        AuthenticationError: If API key is missing or invalid
+    """
+
+    def decorator(fn: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
+        @wraps(fn)
+        async def wrapper(self, *args, **kwargs):
+            ctx = getattr(self, "ctx", None)
+            if not ctx:
+                raise AuthenticationError("Connector context not available")
+
+            tool_id = getattr(self, "TOOL_ID", None)
+            if not tool_id:
+                raise AuthenticationError("TOOL_ID not set in connector")
+
+            try:
+                # Get API key from vault
+                secret_path = f"af/{ctx.tenant_id}/{ctx.user_id}/api_keys/{tool_id}/{key_name}"
+                secret = await ctx.token_manager.vault_client.read_secret(secret_path)
+                
+                if not secret or "value" not in secret:
+                    raise AuthenticationError(f"API key not found: {key_name}")
+
+                api_key = secret["value"]
+
+                # Inject API key header
+                headers = kwargs.setdefault("headers", {})
+                headers.setdefault(header_name, api_key)
+
+                # Log the request
+                ctx.logger.info(
+                    f"Making API key request to {tool_id}",
+                    extra={"key_name": key_name, "user_id": ctx.user_id},
+                )
+
+                return await fn(self, *args, **kwargs)
+
+            except Exception as e:
+                ctx.logger.error(f"API key authentication failed: {e}")
+                if isinstance(e, AuthenticationError):
+                    raise
+                raise AuthenticationError(f"API key authentication failed: {e}")
+
+        return wrapper
+
+    return decorator
+
+
+def mtls_required(*, cert_path: Optional[str] = None, key_path: Optional[str] = None):
+    """
+    Decorator that configures mutual TLS authentication.
+
+    Args:
+        cert_path: Path to client certificate (optional, uses default if not provided)
+        key_path: Path to client private key (optional, uses default if not provided)
+
+    Raises:
+        AuthenticationError: If mTLS configuration fails
+    """
+
+    def decorator(fn: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
+        @wraps(fn)
+        async def wrapper(self, *args, **kwargs):
+            ctx = getattr(self, "ctx", None)
+            if not ctx:
+                raise AuthenticationError("Connector context not available")
+
+            try:
+                # Configure mTLS for the HTTP client
+                # This would typically be done at the session level
+                # For now, we'll add it to the kwargs
+                cert_config = (cert_path, key_path) if cert_path and key_path else None
+                kwargs.setdefault("cert", cert_config)
+
+                ctx.logger.info(
+                    "Making mTLS request",
+                    extra={"cert_path": cert_path, "user_id": ctx.user_id},
+                )
+
+                return await fn(self, *args, **kwargs)
+
+            except Exception as e:
+                ctx.logger.error(f"mTLS authentication failed: {e}")
+                raise AuthenticationError(f"mTLS authentication failed: {e}")
+
+        return wrapper
+
+    return decorator
+
+
+def no_auth_required(fn: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
+    """
+    Decorator that marks a method as not requiring authentication.
+    Useful for public endpoints or health checks.
+    """
+
+    @wraps(fn)
+    async def wrapper(self, *args, **kwargs):
+        ctx = getattr(self, "ctx", None)
+        if ctx:
+            ctx.logger.info("Making unauthenticated request")
+        return await fn(self, *args, **kwargs)
+
+    return wrapper
+
+
+class ScopeValidator:
+    """Helper class for validating OAuth scopes."""
+
+    @staticmethod
+    def validate_scopes(required_scopes: List[str], granted_scopes: List[str]) -> bool:
+        """
+        Validate that all required scopes are granted.
+
+        Args:
+            required_scopes: List of required scopes
+            granted_scopes: List of granted scopes
+
+        Returns:
+            True if all required scopes are granted, False otherwise
+        """
+        return set(required_scopes).issubset(set(granted_scopes))
+
+    @staticmethod
+    def missing_scopes(required_scopes: List[str], granted_scopes: List[str]) -> List[str]:
+        """
+        Get list of missing scopes.
+
+        Args:
+            required_scopes: List of required scopes
+            granted_scopes: List of granted scopes
+
+        Returns:
+            List of missing scopes
+        """
+        return list(set(required_scopes) - set(granted_scopes))
+
+
+class TokenValidator:
+    """Helper class for validating OAuth tokens."""
+
+    @staticmethod
+    def is_expired(expires_at: float) -> bool:
+        """
+        Check if a token is expired.
+
+        Args:
+            expires_at: Expiration timestamp
+
+        Returns:
+            True if token is expired, False otherwise
+        """
+        return time.time() >= expires_at
+
+    @staticmethod
+    def expires_soon(expires_at: float, buffer_seconds: int = 300) -> bool:
+        """
+        Check if a token expires soon.
+
+        Args:
+            expires_at: Expiration timestamp
+            buffer_seconds: Buffer time in seconds
+
+        Returns:
+            True if token expires within buffer time, False otherwise
+        """
+        return time.time() + buffer_seconds >= expires_at 

af_sdk/auth/token_cache.py

@@ -0,0 +1,318 @@
+"""
+Token cache manager for OAuth tokens.
+"""
+
+import asyncio
+from typing import Dict, List, Optional
+
+from ..exceptions import AuthenticationError, TokenRefreshError
+from ..models.types import OAuthToken
+from .oauth import ScopeValidator, TokenValidator
+
+
+class VaultClient:
+    """Client for interacting with the vault service."""
+
+    def __init__(self, base_url: str, http_client, logger):
+        self.base_url = base_url
+        self.http_client = http_client
+        self.logger = logger
+
+    async def read_secret(self, path: str) -> Optional[Dict]:
+        """Read a secret from the vault."""
+        try:
+            response = await self.http_client.get(f"{self.base_url}/api/secrets/{path}")
+            if response.status_code == 200:
+                return response.json()
+            elif response.status_code == 404:
+                return None
+            else:
+                response.raise_for_status()
+        except Exception as e:
+            self.logger.error(f"Failed to read secret from vault: {e}")
+            raise
+
+    async def write_secret(self, path: str, data: Dict) -> None:
+        """Write a secret to the vault."""
+        try:
+            response = await self.http_client.post(
+                f"{self.base_url}/api/secrets",
+                json={"path": path, "data": data}
+            )
+            response.raise_for_status()
+        except Exception as e:
+            self.logger.error(f"Failed to write secret to vault: {e}")
+            raise
+
+    async def delete_secret(self, path: str) -> None:
+        """Delete a secret from the vault."""
+        try:
+            response = await self.http_client.delete(f"{self.base_url}/api/secrets/{path}")
+            response.raise_for_status()
+        except Exception as e:
+            self.logger.error(f"Failed to delete secret from vault: {e}")
+            raise
+
+
+class TokenManager:
+    """Handles per-user OAuth token lifecycle."""
+
+    def __init__(self, tenant_id: str, vault_client: VaultClient, gateway_client=None):
+        self.tenant_id = tenant_id
+        self.vault_client = vault_client
+        self.gateway_client = gateway_client
+        self.cache: Dict[str, OAuthToken] = {}
+        self.lock = asyncio.Lock()
+        self.refresh_locks: Dict[str, asyncio.Lock] = {}
+
+    async def get_oauth_token(
+        self,
+        tool_id: str,
+        user_id: Optional[str],
+        scopes: List[str],
+        refresh_if_expired: bool = True,
+    ) -> str:
+        """
+        Get a valid OAuth token for the specified tool and user.
+
+        Args:
+            tool_id: ID of the tool requiring authentication
+            user_id: ID of the user (None for service accounts)
+            scopes: Required OAuth scopes
+            refresh_if_expired: Whether to refresh expired tokens
+
+        Returns:
+            Valid access token
+
+        Raises:
+            AuthenticationError: If token is not available or invalid
+            TokenRefreshError: If token refresh fails
+        """
+        cache_key = f"{tool_id}:{user_id or 'service'}"
+        
+        # Check cache first
+        token = self.cache.get(cache_key)
+        if token and not TokenValidator.is_expired(token.expires_at.timestamp()):
+            # Validate scopes
+            if ScopeValidator.validate_scopes(scopes, token.scopes):
+                return token.access_token
+            else:
+                missing = ScopeValidator.missing_scopes(scopes, token.scopes)
+                raise AuthenticationError(f"Insufficient scopes. Missing: {missing}")
+
+        # Get or create refresh lock for this token
+        if cache_key not in self.refresh_locks:
+            self.refresh_locks[cache_key] = asyncio.Lock()
+        
+        refresh_lock = self.refresh_locks[cache_key]
+
+        async with refresh_lock:
+            # Double-check after acquiring lock
+            token = self.cache.get(cache_key)
+            if token and not TokenValidator.is_expired(token.expires_at.timestamp()):
+                if ScopeValidator.validate_scopes(scopes, token.scopes):
+                    return token.access_token
+
+            # Load token from vault
+            secret_path = self._get_token_path(tool_id, user_id)
+            try:
+                secret_data = await self.vault_client.read_secret(secret_path)
+                if not secret_data:
+                    raise AuthenticationError(f"No OAuth token found for {tool_id}")
+
+                token = OAuthToken(**secret_data)
+                
+                # Check if token is expired
+                if TokenValidator.is_expired(token.expires_at.timestamp()):
+                    if refresh_if_expired and token.refresh_token:
+                        token = await self._refresh_token(tool_id, user_id, token)
+                    else:
+                        raise AuthenticationError(f"OAuth token expired for {tool_id}")
+
+                # Validate scopes
+                if not ScopeValidator.validate_scopes(scopes, token.scopes):
+                    missing = ScopeValidator.missing_scopes(scopes, token.scopes)
+                    raise AuthenticationError(f"Insufficient scopes. Missing: {missing}")
+
+                # Cache the token
+                self.cache[cache_key] = token
+                return token.access_token
+
+            except Exception as e:
+                if isinstance(e, (AuthenticationError, TokenRefreshError)):
+                    raise
+                raise AuthenticationError(f"Failed to get OAuth token: {e}")
+
+    async def _refresh_token(
+        self, tool_id: str, user_id: Optional[str], token: OAuthToken
+    ) -> OAuthToken:
+        """
+        Refresh an OAuth token using the refresh token.
+
+        Args:
+            tool_id: ID of the tool
+            user_id: ID of the user
+            token: Current token with refresh_token
+
+        Returns:
+            New token with updated access_token and expires_at
+
+        Raises:
+            TokenRefreshError: If refresh fails
+        """
+        if not self.gateway_client:
+            raise TokenRefreshError("Gateway client not configured")
+
+        if not token.refresh_token:
+            raise TokenRefreshError("No refresh token available")
+
+        try:
+            # Call gateway to refresh token
+            response = await self.gateway_client.post(
+                "/token/refresh",
+                json={
+                    "refresh_token": token.refresh_token,
+                    "tool_id": tool_id,
+                    "user_id": user_id,
+                }
+            )
+            response.raise_for_status()
+            
+            refresh_data = response.json()
+            
+            # Create new token
+            new_token = OAuthToken(
+                access_token=refresh_data["access_token"],
+                refresh_token=refresh_data.get("refresh_token", token.refresh_token),
+                token_type=refresh_data.get("token_type", "Bearer"),
+                expires_at=refresh_data["expires_at"],
+                scopes=refresh_data.get("scopes", token.scopes),
+            )
+
+            # Store in vault
+            secret_path = self._get_token_path(tool_id, user_id)
+            await self.vault_client.write_secret(secret_path, new_token.dict())
+
+            return new_token
+
+        except Exception as e:
+            raise TokenRefreshError(f"Failed to refresh token: {e}")
+
+    async def store_oauth_token(
+        self, tool_id: str, user_id: Optional[str], token: OAuthToken
+    ) -> None:
+        """
+        Store an OAuth token in the vault and cache.
+
+        Args:
+            tool_id: ID of the tool
+            user_id: ID of the user
+            token: OAuth token to store
+        """
+        secret_path = self._get_token_path(tool_id, user_id)
+        await self.vault_client.write_secret(secret_path, token.dict())
+
+        # Update cache
+        cache_key = f"{tool_id}:{user_id or 'service'}"
+        self.cache[cache_key] = token
+
+    async def revoke_oauth_token(self, tool_id: str, user_id: Optional[str]) -> None:
+        """
+        Revoke an OAuth token (remove from vault and cache).
+
+        Args:
+            tool_id: ID of the tool
+            user_id: ID of the user
+        """
+        secret_path = self._get_token_path(tool_id, user_id)
+        await self.vault_client.delete_secret(secret_path)
+
+        # Remove from cache
+        cache_key = f"{tool_id}:{user_id or 'service'}"
+        self.cache.pop(cache_key, None)
+
+    async def list_tokens(self, user_id: Optional[str]) -> List[Dict]:
+        """
+        List all tokens for a user.
+
+        Args:
+            user_id: ID of the user
+
+        Returns:
+            List of token metadata
+        """
+        # This would need to be implemented based on vault capabilities
+        # For now, return cached tokens
+        result = []
+        user_key = user_id or 'service'
+        
+        for cache_key, token in self.cache.items():
+            if cache_key.endswith(f":{user_key}"):
+                tool_id = cache_key.split(":")[0]
+                result.append({
+                    "tool_id": tool_id,
+                    "user_id": user_id,
+                    "scopes": token.scopes,
+                    "expires_at": token.expires_at.isoformat(),
+                    "is_expired": TokenValidator.is_expired(token.expires_at.timestamp()),
+                })
+        
+        return result
+
+    def _get_token_path(self, tool_id: str, user_id: Optional[str]) -> str:
+        """
+        Get the vault path for a token.
+
+        Args:
+            tool_id: ID of the tool
+            user_id: ID of the user
+
+        Returns:
+            Vault path for the token
+        """
+        user_part = user_id or "service"
+        return f"af/{self.tenant_id}/{user_part}/oauth/{tool_id}/token"
+
+    async def cleanup_expired_tokens(self) -> None:
+        """Remove expired tokens from cache."""
+        expired_keys = []
+        
+        for cache_key, token in self.cache.items():
+            if TokenValidator.is_expired(token.expires_at.timestamp()):
+                expired_keys.append(cache_key)
+        
+        for key in expired_keys:
+            del self.cache[key]
+
+    async def get_token_info(self, tool_id: str, user_id: Optional[str]) -> Optional[Dict]:
+        """
+        Get information about a token without returning the actual token.
+
+        Args:
+            tool_id: ID of the tool
+            user_id: ID of the user
+
+        Returns:
+            Token information or None if not found
+        """
+        cache_key = f"{tool_id}:{user_id or 'service'}"
+        token = self.cache.get(cache_key)
+        
+        if not token:
+            # Try to load from vault
+            secret_path = self._get_token_path(tool_id, user_id)
+            secret_data = await self.vault_client.read_secret(secret_path)
+            if secret_data:
+                token = OAuthToken(**secret_data)
+        
+        if token:
+            return {
+                "tool_id": tool_id,
+                "user_id": user_id,
+                "scopes": token.scopes,
+                "expires_at": token.expires_at.isoformat(),
+                "is_expired": TokenValidator.is_expired(token.expires_at.timestamp()),
+                "expires_soon": TokenValidator.expires_soon(token.expires_at.timestamp()),
+            }
+        
+        return None