neuronos-capabilities-lib 0.0.2__py3-none-any.whl

neuronos_capabilities/AuthManager/__init__.py

@@ -0,0 +1,42 @@
+"""
+AuthManager - Authentication & Authorization Capability for NeuronOS.
+
+A provider-agnostic auth capability following hexagonal architecture principles.
+Provides FastAPI decorators for JWT-based authentication and role-based access control.
+
+Example:
+    from neuronos_capabilities import AuthManager
+
+    auth = AuthManager({
+        "provider": "clerk",
+        "jwks_url": "https://your-app.clerk.accounts.dev/.well-known/jwks.json",
+    })
+
+    @app.get("/api/protected")
+    def protected(user: dict = Depends(auth.require_auth())):
+        return {"user_id": user["sub"]}
+
+    @app.get("/api/admin")
+    def admin(user: dict = Depends(auth.require_roles(["org:admin"]))):
+        return {"message": "Admin access granted"}
+"""
+
+from .auth_manager import AuthManager
+from .config.auth_config import AuthConfig
+from .exceptions.auth_exceptions import (
+    AuthManagerError,
+    ConfigurationError,
+    TokenError,
+    AuthorizationError,
+)
+
+__all__ = [
+    "AuthManager",
+    "AuthConfig",
+    "AuthManagerError",
+    "ConfigurationError",
+    "TokenError",
+    "AuthorizationError",
+]
+
+__version__ = "1.0.0"

neuronos_capabilities/AuthManager/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .clerk_adapter import ClerkAdapter
+
+__all__ = ["ClerkAdapter"]

neuronos_capabilities/AuthManager/adapters/clerk_adapter.py

@@ -0,0 +1,87 @@
+"""
+Clerk authentication adapter.
+
+Implements AuthPort using Clerk's JWKS endpoint for JWT verification.
+"""
+
+from typing import Any, Dict, List, Optional
+
+import jwt
+from jwt import PyJWKClient
+
+from ..config.auth_config import AuthConfig
+from ..ports.auth_port import AuthPort
+from ..exceptions.auth_exceptions import TokenError
+
+
+class ClerkAdapter(AuthPort):
+    """
+    Clerk-based authentication adapter.
+
+    Verifies JWTs against Clerk's JWKS endpoint and extracts
+    role/organization claims from the token payload.
+    """
+
+    def __init__(self, config: AuthConfig):
+        self._config = config
+        self._jwks_client = PyJWKClient(config.jwks_url)
+
+    def _decode_token(self, token: str) -> Dict[str, Any]:
+        """Shared decode logic for sync and async paths."""
+        try:
+            signing_key = self._jwks_client.get_signing_key_from_jwt(token)
+
+            decode_options = {"verify_audience": False}
+            kwargs: Dict[str, Any] = {
+                "jwt": token,
+                "key": signing_key.key,
+                "algorithms": self._config.algorithms,
+                "options": decode_options,
+                # Clock tolerance on exp/nbf/iat. Without it, PyJWT rejects a
+                # token whose `iat` is a single second ahead of this host
+                # ("The token is not yet valid (iat)", api_jwt.py: `iat > now +
+                # leeway`). Clerk stamps `iat` on its own servers, so a host
+                # running slightly behind fails EVERY request, and the client
+                # cannot compensate — re-minting yields a later `iat` still.
+                "leeway": self._config.leeway_seconds,
+            }
+
+            if self._config.issuer:
+                kwargs["issuer"] = self._config.issuer
+            if self._config.audience:
+                kwargs["audience"] = self._config.audience
+                decode_options["verify_audience"] = True
+
+            return jwt.decode(**kwargs)
+        except jwt.ExpiredSignatureError:
+            raise TokenError("Token has expired")
+        except jwt.InvalidTokenError as e:
+            raise TokenError(f"Invalid token: {str(e)}")
+        except Exception as e:
+            raise TokenError(f"Token verification failed: {str(e)}")
+
+    def verify_token(self, token: str) -> Dict[str, Any]:
+        return self._decode_token(token)
+
+    async def verify_token_async(self, token: str) -> Dict[str, Any]:
+        # PyJWKClient doesn't have native async; delegate to sync.
+        # For high-throughput, consider caching the JWKS keys.
+        return self._decode_token(token)
+
+    def has_role(self, payload: Dict[str, Any], roles: List[str]) -> bool:
+        # Clerk puts custom roles in public_metadata.rol when no org is configured,
+        # and in org_role when the user is scoped to an organization.
+        # Check both locations so the same decorator works either way.
+        org_role = payload.get("org_role")
+        if org_role and org_role in roles:
+            return True
+
+        metadata = payload.get("public_metadata") or payload.get("metadata") or {}
+        user_rol = metadata.get("rol", "")
+        return user_rol in roles
+
+    def get_org_id(self, payload: Dict[str, Any]) -> Optional[str]:
+        return payload.get("org_id")
+
+    def get_user_id(self, payload: Dict[str, Any]) -> Optional[str]:
+        return payload.get("sub")

neuronos_capabilities/AuthManager/auth_manager.py

@@ -0,0 +1,237 @@
+"""
+AuthManager - Public API for authentication and authorization.
+
+Provides FastAPI-compatible dependency decorators for protecting endpoints
+with JWT verification and role-based access control.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+from fastapi import Depends, HTTPException
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from .config.auth_config import AuthConfig
+from .ports.auth_port import AuthPort
+from .adapters.clerk_adapter import ClerkAdapter
+from .exceptions.auth_exceptions import (
+    AuthManagerError,
+    ConfigurationError,
+    TokenError,
+    AuthorizationError,
+)
+
+
+_security = HTTPBearer()
+
+
+class AuthManager:
+    """
+    Public API for authentication and authorization.
+
+    Provides FastAPI dependency functions that can be used with Depends()
+    to protect endpoints with JWT verification and role-based access control.
+
+    Example:
+        auth = AuthManager({"jwks_url": os.getenv("NEURONOS_AUTH_JWKS_URL")})
+
+        @app.get("/api/protected")
+        def protected(user: dict = Depends(auth.require_auth())):
+            return {"user_id": user["sub"]}
+
+        @app.get("/api/admin")
+        def admin_only(user: dict = Depends(auth.require_roles(["org:admin"]))):
+            return {"message": "Welcome admin"}
+
+        @app.get("/api/tenant")
+        def tenant_only(user: dict = Depends(auth.require_org("org_2abc123"))):
+            return {"message": "Org access granted"}
+
+        @app.get("/api/coordinator")
+        def coordinator(user: dict = Depends(auth.require_org_role("org_2abc123", ["org:coordinator"]))):
+            return {"message": "Org coordinator access"}
+    """
+
+    _ADAPTERS = {
+        "clerk": ClerkAdapter,
+    }
+
+    def __init__(self, config: Optional[Union[AuthConfig, Dict[str, Any]]] = None):
+        """
+        Initialize AuthManager with configuration.
+
+        Args:
+            config: AuthConfig object or dictionary with auth parameters.
+                    Sensitive values fall back to environment variables.
+
+        Raises:
+            ConfigurationError: If configuration is invalid or missing
+        """
+        if config is None:
+            # Attempt to build config entirely from env variables
+            config = AuthConfig()
+        elif isinstance(config, dict):
+            try:
+                config = AuthConfig(**config)
+            except Exception as e:
+                raise ConfigurationError(f"Invalid configuration: {str(e)}")
+
+        self.config = config
+        self._adapter: AuthPort = self._create_adapter(config)
+
+    def _create_adapter(self, config: AuthConfig) -> AuthPort:
+        adapter_cls = self._ADAPTERS.get(config.provider)
+        if not adapter_cls:
+            raise ConfigurationError(
+                f"Unsupported provider: {config.provider}. "
+                f"Supported: {', '.join(self._ADAPTERS.keys())}"
+            )
+        return adapter_cls(config)
+
+    # ===== FastAPI Dependency Factories =====
+
+    def require_auth(self):
+        """
+        FastAPI dependency that verifies the JWT and returns the decoded payload.
+
+        Returns 401 if token is missing or invalid.
+
+        Usage:
+            @app.get("/protected")
+            def endpoint(user: dict = Depends(auth.require_auth())):
+                ...
+        """
+        adapter = self._adapter
+
+        async def _dependency(
+            credentials: HTTPAuthorizationCredentials = Depends(_security),
+        ) -> Dict[str, Any]:
+            try:
+                return await adapter.verify_token_async(credentials.credentials)
+            except TokenError as e:
+                raise HTTPException(status_code=401, detail=str(e))
+
+        return _dependency
+
+    def require_roles(self, roles: List[str]):
+        """
+        FastAPI dependency that verifies JWT and checks the user has one of the given roles.
+
+        Returns 401 if token is invalid, 403 if role is not matched.
+
+        Args:
+            roles: List of acceptable roles (e.g., ["coordinador", "admin"])
+
+        Usage:
+            @app.get("/admin")
+            def endpoint(user: dict = Depends(auth.require_roles(["admin"]))):
+                ...
+        """
+        adapter = self._adapter
+
+        async def _dependency(
+            credentials: HTTPAuthorizationCredentials = Depends(_security),
+        ) -> Dict[str, Any]:
+            try:
+                payload = await adapter.verify_token_async(credentials.credentials)
+            except TokenError as e:
+                raise HTTPException(status_code=401, detail=str(e))
+
+            if not adapter.has_role(payload, roles):
+                raise HTTPException(
+                    status_code=403,
+                    detail=f"Requires one of roles: {', '.join(roles)}",
+                )
+            return payload
+
+        return _dependency
+
+    def require_org(self, org_id: str):
+        """
+        FastAPI dependency that verifies JWT and checks the user belongs to a specific org.
+
+        Returns 401 if token is invalid, 403 if org doesn't match.
+
+        Args:
+            org_id: Required organization ID (e.g., "org_2abc123")
+
+        Usage:
+            @app.get("/tenant")
+            def endpoint(user: dict = Depends(auth.require_org("org_2abc123"))):
+                ...
+        """
+        adapter = self._adapter
+
+        async def _dependency(
+            credentials: HTTPAuthorizationCredentials = Depends(_security),
+        ) -> Dict[str, Any]:
+            try:
+                payload = await adapter.verify_token_async(credentials.credentials)
+            except TokenError as e:
+                raise HTTPException(status_code=401, detail=str(e))
+
+            if adapter.get_org_id(payload) != org_id:
+                raise HTTPException(
+                    status_code=403,
+                    detail=f"Access restricted to organization '{org_id}'.",
+                )
+            return payload
+
+        return _dependency
+
+    def require_org_role(self, org_id: str, roles: List[str]):
+        """
+        FastAPI dependency that verifies JWT, org membership, AND role in one step.
+
+        Returns 401 if token is invalid, 403 if org or role doesn't match.
+
+        Args:
+            org_id: Required organization ID
+            roles: List of acceptable roles within that org
+
+        Usage:
+            @app.get("/org-coordinator")
+            def endpoint(user: dict = Depends(auth.require_org_role("org_2abc123", ["org:coordinator"]))):
+                ...
+        """
+        adapter = self._adapter
+
+        async def _dependency(
+            credentials: HTTPAuthorizationCredentials = Depends(_security),
+        ) -> Dict[str, Any]:
+            try:
+                payload = await adapter.verify_token_async(credentials.credentials)
+            except TokenError as e:
+                raise HTTPException(status_code=401, detail=str(e))
+
+            if adapter.get_org_id(payload) != org_id:
+                raise HTTPException(
+                    status_code=403,
+                    detail=f"Access restricted to organization '{org_id}'.",
+                )
+
+            if not adapter.has_role(payload, roles):
+                raise HTTPException(
+                    status_code=403,
+                    detail=f"Requires one of roles: {', '.join(roles)}",
+                )
+            return payload
+
+        return _dependency
+
+    # ===== Direct API (non-decorator usage) =====
+
+    def verify_token(self, token: str) -> Dict[str, Any]:
+        """Verify and decode a JWT token (synchronous)."""
+        return self._adapter.verify_token(token)
+
+    async def verify_token_async(self, token: str) -> Dict[str, Any]:
+        """Verify and decode a JWT token (asynchronous)."""
+        return await self._adapter.verify_token_async(token)
+
+    def get_user_id(self, payload: Dict[str, Any]) -> Optional[str]:
+        """Extract user ID from decoded payload."""
+        return self._adapter.get_user_id(payload)
+
+    def get_org_id(self, payload: Dict[str, Any]) -> Optional[str]:
+        """Extract organization ID from decoded payload."""
+        return self._adapter.get_org_id(payload)

neuronos_capabilities/AuthManager/config/__init__.py

@@ -0,0 +1,3 @@
+from .auth_config import AuthConfig
+
+__all__ = ["AuthConfig"]

neuronos_capabilities/AuthManager/config/auth_config.py

@@ -0,0 +1,106 @@
+"""
+Configuration module for AuthManager capability.
+
+Supports loading sensitive values from environment variables.
+"""
+
+import os
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from ..exceptions.auth_exceptions import ConfigurationError
+
+
+@dataclass
+class AuthConfig:
+    """
+    Configuration for authentication provider.
+
+    Sensitive values (jwks_url, issuer) can be set via environment variables:
+        - NEURONOS_AUTH_JWKS_URL
+        - NEURONOS_AUTH_ISSUER
+        - NEURONOS_AUTH_PROVIDER
+        - NEURONOS_AUTH_LEEWAY_SECONDS
+
+    Attributes:
+        provider: Auth provider name (e.g., "clerk")
+        jwks_url: URL to the JWKS endpoint for token verification
+        issuer: Expected token issuer (optional, for extra validation)
+        algorithms: Allowed JWT signing algorithms
+        audience: Expected audience claim (optional)
+        org_id: Lock to a specific organization ID (optional)
+        auto_error: If True, raise HTTPException on auth failure (default True)
+        leeway_seconds: Clock difference tolerated on the JWT time claims
+            (exp/nbf/iat). Defaults to 30.
+
+            Not merely a nicety: the provider stamps `iat` with ITS clock, so a
+            host running even ONE SECOND behind rejects every token with
+            "The token is not yet valid (iat)" — and no client can work around
+            it, because a freshly minted token carries a later `iat` still.
+            30s absorbs ordinary NTP drift without meaningfully extending a
+            token's life. Set to 0 to demand perfectly synchronized clocks.
+    """
+
+    DEFAULT_LEEWAY_SECONDS = 30
+
+    provider: str = ""
+    jwks_url: str = ""
+    issuer: Optional[str] = None
+    algorithms: List[str] = field(default_factory=lambda: ["RS256"])
+    audience: Optional[str] = None
+    org_id: Optional[str] = None
+    auto_error: bool = True
+    leeway_seconds: int = DEFAULT_LEEWAY_SECONDS
+
+    def __post_init__(self):
+        # Resolve from env variables if not provided directly
+        self.provider = self.provider or os.getenv("NEURONOS_AUTH_PROVIDER", "clerk")
+        self.jwks_url = self.jwks_url or os.getenv("NEURONOS_AUTH_JWKS_URL", "")
+        self.issuer = self.issuer or os.getenv("NEURONOS_AUTH_ISSUER") or None
+
+        # An explicit 0 is a real choice ("require synced clocks"), so the env
+        # var is only consulted when the caller left the default untouched.
+        if self.leeway_seconds == self.DEFAULT_LEEWAY_SECONDS:
+            env_leeway = os.getenv("NEURONOS_AUTH_LEEWAY_SECONDS")
+            if env_leeway:
+                try:
+                    self.leeway_seconds = int(env_leeway)
+                except ValueError:
+                    raise ConfigurationError(
+                        "NEURONOS_AUTH_LEEWAY_SECONDS must be an integer number of "
+                        f"seconds, got '{env_leeway}'."
+                    )
+
+        if self.leeway_seconds < 0:
+            raise ConfigurationError(
+                f"leeway_seconds must be >= 0, got {self.leeway_seconds}."
+            )
+
+        if not self.jwks_url:
+            raise ConfigurationError(
+                "jwks_url is required. Set it directly or via NEURONOS_AUTH_JWKS_URL env variable."
+            )
+
+        valid_providers = ["clerk"]
+        if self.provider.lower() not in valid_providers:
+            raise ConfigurationError(
+                f"Invalid provider '{self.provider}'. Supported: {', '.join(valid_providers)}"
+            )
+
+        self.provider = self.provider.lower()
+
+    def to_dict(self) -> dict:
+        return {
+            "provider": self.provider,
+            "jwks_url": self.jwks_url,
+            "issuer": self.issuer,
+            "algorithms": self.algorithms,
+            "audience": self.audience,
+            "org_id": self.org_id,
+            "auto_error": self.auto_error,
+            "leeway_seconds": self.leeway_seconds,
+        }
+
+    @classmethod
+    def from_dict(cls, config_dict: dict) -> "AuthConfig":
+        return cls(**config_dict)

neuronos_capabilities/AuthManager/examples/usage.py

@@ -0,0 +1,56 @@
+"""
+Example: Using AuthManager with FastAPI.
+
+Before running, set the environment variable:
+    export NEURONOS_AUTH_JWKS_URL="https://your-app.clerk.accounts.dev/.well-known/jwks.json"
+
+Three levels of protection:
+    1. auth.require_auth()                              → just verify the token
+    2. auth.require_roles(["coordinador"])               → verify token + check role
+    3. auth.require_org_role("org_2x", ["coordinador"])  → verify token + org + role
+"""
+
+from fastapi import FastAPI, Depends
+from fastapi.middleware.cors import CORSMiddleware
+
+from neuronos_capabilities import AuthManager
+
+app = FastAPI()
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:3000"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+auth = AuthManager()
+
+
+# --- Level 1: Auth only ---
+@app.get("/api/test-auth")
+async def test_auth(user: dict = Depends(auth.require_auth())):
+    """Any authenticated user."""
+    return {"status": "Token is valid", "user_id": user.get("sub")}
+
+
+# --- Level 2: Auth + Role ---
+@app.get("/api/coordinator-action")
+async def coordinator_action(
+    user: dict = Depends(auth.require_roles(["coordinador"])),
+):
+    """Requires 'coordinador' role from public_metadata.rol."""
+    return {"message": "Coordinator access granted", "user_id": user.get("sub")}
+
+
+# --- Level 3: Auth + Org + Role ---
+@app.get("/api/org-coordinator")
+async def org_coordinator(
+    user: dict = Depends(
+        auth.require_org_role("org_2abc123", ["coordinador"])
+    ),
+):
+    """Requires org membership AND 'coordinador' role."""
+    return {
+        "message": "Org Coordinator access granted",
+        "user_id": user.get("sub"),
+    }

neuronos_capabilities/AuthManager/exceptions/__init__.py

@@ -0,0 +1,13 @@
+from .auth_exceptions import (
+    AuthManagerError,
+    ConfigurationError,
+    TokenError,
+    AuthorizationError,
+)
+
+__all__ = [
+    "AuthManagerError",
+    "ConfigurationError",
+    "TokenError",
+    "AuthorizationError",
+]

neuronos_capabilities/AuthManager/exceptions/auth_exceptions.py

@@ -0,0 +1,23 @@
+"""
+Custom exceptions for AuthManager capability.
+"""
+
+
+class AuthManagerError(Exception):
+    """Base exception for all AuthManager errors."""
+    pass
+
+
+class ConfigurationError(AuthManagerError):
+    """Raised when configuration is invalid or incomplete."""
+    pass
+
+
+class TokenError(AuthManagerError):
+    """Raised when token verification fails (expired, malformed, invalid signature)."""
+    pass
+
+
+class AuthorizationError(AuthManagerError):
+    """Raised when the user lacks required roles or permissions."""
+    pass

neuronos_capabilities/AuthManager/ports/__init__.py

@@ -0,0 +1,3 @@
+from .auth_port import AuthPort
+
+__all__ = ["AuthPort"]

neuronos_capabilities/AuthManager/ports/auth_port.py

@@ -0,0 +1,92 @@
+"""
+Abstract port interface for authentication operations.
+
+Defines the provider-agnostic contract that all auth adapters must implement.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+
+class AuthPort(ABC):
+    """
+    Abstract interface for authentication providers.
+
+    All auth adapters must implement this interface.
+    """
+
+    @abstractmethod
+    def verify_token(self, token: str) -> Dict[str, Any]:
+        """
+        Verify and decode a JWT token (synchronous).
+
+        Args:
+            token: Raw JWT string
+
+        Returns:
+            Decoded token payload as dictionary
+
+        Raises:
+            TokenError: If token is invalid, expired, or malformed
+        """
+        pass
+
+    @abstractmethod
+    async def verify_token_async(self, token: str) -> Dict[str, Any]:
+        """
+        Verify and decode a JWT token (asynchronous).
+
+        Args:
+            token: Raw JWT string
+
+        Returns:
+            Decoded token payload as dictionary
+
+        Raises:
+            TokenError: If token is invalid, expired, or malformed
+        """
+        pass
+
+    @abstractmethod
+    def has_role(self, payload: Dict[str, Any], roles: List[str]) -> bool:
+        """
+        Check if the token payload contains any of the required roles.
+
+        The role can come from different locations depending on the provider
+        configuration (e.g., org_role for org-scoped tokens, or
+        public_metadata.rol for custom roles without orgs).
+
+        Args:
+            payload: Decoded JWT payload
+            roles: List of acceptable roles (e.g., ["coordinador", "admin"])
+
+        Returns:
+            True if user has at least one of the required roles
+        """
+        pass
+
+    @abstractmethod
+    def get_org_id(self, payload: Dict[str, Any]) -> Optional[str]:
+        """
+        Extract organization ID from token payload.
+
+        Args:
+            payload: Decoded JWT payload
+
+        Returns:
+            Organization ID string or None
+        """
+        pass
+
+    @abstractmethod
+    def get_user_id(self, payload: Dict[str, Any]) -> Optional[str]:
+        """
+        Extract user ID from token payload.
+
+        Args:
+            payload: Decoded JWT payload
+
+        Returns:
+            User ID string or None
+        """
+        pass

neuronos_capabilities/AuthManager/tests/__init__.py

@@ -0,0 +1 @@
+# AuthManager tests