usso 0.27.22__tar.gz → 0.28.1__tar.gz

usso-0.28.1/MANIFEST.in

@@ -0,0 +1 @@
+include pytest.ini

usso-0.28.1/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: usso
+Version: 0.28.1
+Summary: A plug-and-play client for integrating universal single sign-on (SSO) with Python frameworks, enabling secure and seamless authentication across microservices.
+Author-email: Mahdi Kiani <mahdikiany@gmail.com>
+Maintainer-email: Mahdi Kiani <mahdikiany@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ussoio/usso-python
+Project-URL: Bug Reports, https://github.com/ussoio/usso-python/issues
+Project-URL: Funding, https://github.com/ussoio/usso-python
+Project-URL: Say Thanks!, https://saythanks.io/to/mahdikiani
+Project-URL: Source, https://github.com/ussoio/usso-python
+Keywords: usso,sso,authentication,security,fastapi,django
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: pydantic>=2
+Requires-Dist: cryptography>=43.0.0
+Requires-Dist: cachetools
+Requires-Dist: singleton_package
+Requires-Dist: json-advanced
+Requires-Dist: httpx
+Requires-Dist: usso-jwt>=0.1.0
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.65.0; extra == "fastapi"
+Requires-Dist: uvicorn[standard]>=0.13.0; extra == "fastapi"
+Provides-Extra: django
+Requires-Dist: Django>=3.2; extra == "django"
+Provides-Extra: dev
+Requires-Dist: check-manifest; extra == "dev"
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Provides-Extra: all
+Requires-Dist: fastapi; extra == "all"
+Requires-Dist: uvicorn; extra == "all"
+Requires-Dist: django; extra == "all"
+Requires-Dist: dev; extra == "all"
+Requires-Dist: test; extra == "all"
+Dynamic: license-file
+
+# 🛡️ USSO Python Client SDK
+
+The **USSO Python Client SDK** (`usso`) provides a universal, secure JWT authentication layer for Python microservices and web frameworks.  
+It’s designed to integrate seamlessly with the [USSO Identity Platform](https://github.com/ussoio/usso) — or any standards-compliant token issuer.
+
+---
+
+## 🔗 Relationship to the USSO Platform
+
+This SDK is the official verification client for the **USSO** identity service, which provides multi-tenant authentication, RBAC, token flows, and more.  
+You can use the SDK with:
+- Self-hosted USSO via Docker
+- Any identity provider that issues signed JWTs (with proper config)
+
+---
+
+## ✨ Features
+
+- ✅ **Token verification** for EdDSA, RS256, HS256, and more
+- ✅ **Claim validation** (`exp`, `nbf`, `aud`, `iss`)
+- ✅ **Remote JWK support** for key rotation
+- ✅ **Typed payload parsing** via `UserData` (Pydantic)
+- ✅ **Token extraction** from:
+  - `Authorization` header
+  - Cookies
+  - Custom headers
+- ✅ **FastAPI integration** with dependency injection
+- ✅ **Django middleware** for request-based user resolution
+- 🧪 90% tested with `pytest` and `tox`
+
+---
+
+## 📦 Installation
+
+```bash
+pip install usso
+````
+
+With framework extras:
+
+```bash
+pip install "usso[fastapi]"     # for FastAPI integration
+pip install "usso[django]"      # for Django integration
+```
+
+---
+
+## 🚀 Quick Start (FastAPI)
+
+```python
+from usso.fastapi.integration import get_authenticator
+from usso.schemas import JWTConfig, JWTHeaderConfig, UserData
+from usso.jwt.enums import Algorithm
+
+config = JWTConfig(
+    key="your-ed25519-public-key",
+    issuer="https://sso.example.com",
+    audience="api.example.com",
+    type=Algorithm.EdDSA,
+    header=JWTHeaderConfig(type="Authorization")
+)
+
+authenticator = get_authenticator(config)
+
+@app.get("/me")
+def get_me(user: UserData = Depends(authenticator)):
+    return {"user_id": user.sub, "roles": user.roles}
+```
+
+---
+
+## 🧱 Project Structure
+
+```
+src/usso/
+├── fastapi/            # FastAPI adapter
+├── django/             # Django middleware
+├── jwt/                # Core JWT logic and algorithms
+├── session/            # Stateless session support
+├── models/             # JWTConfig, UserData, etc.
+├── exceptions/         # Shared exceptions
+├── authenticator.py    # High-level API (token + user resolution)
+```
+
+---
+
+## 🐳 Integrate with USSO (Docker)
+
+Run your own identity provider:
+
+```bash
+docker run -p 8000:8000 ghcr.io/ussoio/usso:latest
+```
+
+Then configure your app to verify tokens issued by this service, using its public JWKS endpoint:
+
+```python
+JWTConfig(
+    jwk_url="http://localhost:8000/.well-known/jwks.json",
+    ...
+)
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+pytest
+tox
+```
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! 
+
+---
+
+## 📝 License
+
+MIT License © \[mahdikiani]
+

usso-0.28.1/README.md

@@ -0,0 +1,124 @@
+# 🛡️ USSO Python Client SDK
+
+The **USSO Python Client SDK** (`usso`) provides a universal, secure JWT authentication layer for Python microservices and web frameworks.  
+It’s designed to integrate seamlessly with the [USSO Identity Platform](https://github.com/ussoio/usso) — or any standards-compliant token issuer.
+
+---
+
+## 🔗 Relationship to the USSO Platform
+
+This SDK is the official verification client for the **USSO** identity service, which provides multi-tenant authentication, RBAC, token flows, and more.  
+You can use the SDK with:
+- Self-hosted USSO via Docker
+- Any identity provider that issues signed JWTs (with proper config)
+
+---
+
+## ✨ Features
+
+- ✅ **Token verification** for EdDSA, RS256, HS256, and more
+- ✅ **Claim validation** (`exp`, `nbf`, `aud`, `iss`)
+- ✅ **Remote JWK support** for key rotation
+- ✅ **Typed payload parsing** via `UserData` (Pydantic)
+- ✅ **Token extraction** from:
+  - `Authorization` header
+  - Cookies
+  - Custom headers
+- ✅ **FastAPI integration** with dependency injection
+- ✅ **Django middleware** for request-based user resolution
+- 🧪 90% tested with `pytest` and `tox`
+
+---
+
+## 📦 Installation
+
+```bash
+pip install usso
+````
+
+With framework extras:
+
+```bash
+pip install "usso[fastapi]"     # for FastAPI integration
+pip install "usso[django]"      # for Django integration
+```
+
+---
+
+## 🚀 Quick Start (FastAPI)
+
+```python
+from usso.fastapi.integration import get_authenticator
+from usso.schemas import JWTConfig, JWTHeaderConfig, UserData
+from usso.jwt.enums import Algorithm
+
+config = JWTConfig(
+    key="your-ed25519-public-key",
+    issuer="https://sso.example.com",
+    audience="api.example.com",
+    type=Algorithm.EdDSA,
+    header=JWTHeaderConfig(type="Authorization")
+)
+
+authenticator = get_authenticator(config)
+
+@app.get("/me")
+def get_me(user: UserData = Depends(authenticator)):
+    return {"user_id": user.sub, "roles": user.roles}
+```
+
+---
+
+## 🧱 Project Structure
+
+```
+src/usso/
+├── fastapi/            # FastAPI adapter
+├── django/             # Django middleware
+├── jwt/                # Core JWT logic and algorithms
+├── session/            # Stateless session support
+├── models/             # JWTConfig, UserData, etc.
+├── exceptions/         # Shared exceptions
+├── authenticator.py    # High-level API (token + user resolution)
+```
+
+---
+
+## 🐳 Integrate with USSO (Docker)
+
+Run your own identity provider:
+
+```bash
+docker run -p 8000:8000 ghcr.io/ussoio/usso:latest
+```
+
+Then configure your app to verify tokens issued by this service, using its public JWKS endpoint:
+
+```python
+JWTConfig(
+    jwk_url="http://localhost:8000/.well-known/jwks.json",
+    ...
+)
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+pytest
+tox
+```
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! 
+
+---
+
+## 📝 License
+
+MIT License © \[mahdikiani]
+

{usso-0.27.22 → usso-0.28.1}/pyproject.toml

@@ -4,23 +4,19 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "usso"
-version = "0.27.22"
+version = "0.28.1"
 description = "A plug-and-play client for integrating universal single sign-on (SSO) with Python frameworks, enabling secure and seamless authentication across microservices."
 readme = "README.md"
 requires-python = ">=3.9"
-license = {file = "LICENSE.txt"}
+license = "MIT"
+license-files = ["LICENSE.txt"]
 keywords = ["usso", "sso", "authentication", "security", "fastapi", "django"]
-authors = [
-  {name = "Mahdi Kiani", email = "mahdikiany@gmail.com"}
-]
-maintainers = [
-  {name = "Mahdi Kiani", email = "mahdikiany@gmail.com"}
-]
+authors = [{ name = "Mahdi Kiani", email = "mahdikiany@gmail.com" }]
+maintainers = [{ name = "Mahdi Kiani", email = "mahdikiany@gmail.com" }]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
   "Topic :: Software Development :: Build Tools",
-  "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
@@ -29,13 +25,29 @@ classifiers = [
 ]
 dependencies = [
   "pydantic>=2",
-  "pyjwt[crypto]",
+  "cryptography>=43.0.0",
   "cachetools",
   "singleton_package",
   "json-advanced",
   "httpx",
+  "usso-jwt>=0.1.0",
 ]
-optional-dependencies = {"fastapi"=["fastapi>=0.65.0", "uvicorn[standard]>=0.13.0"], "django"=["Django>=3.2"], "httpx"=["httpx"], "dev"=["check-manifest"], "test" = ["coverage"], "all"=["fastapi", "uvicorn", "django", "httpx", "dev", "test"]}
+optional-dependencies = { "fastapi" = [
+  "fastapi>=0.65.0",
+  "uvicorn[standard]>=0.13.0",
+], "django" = [
+  "Django>=3.2",
+], "dev" = [
+  "check-manifest",
+], "test" = [
+  "coverage",
+], "all" = [
+  "fastapi",
+  "uvicorn",
+  "django",
+  "dev",
+  "test",
+] }
 
 [project.urls]
 "Homepage" = "https://github.com/ussoio/usso-python"
@@ -48,4 +60,17 @@ optional-dependencies = {"fastapi"=["fastapi>=0.65.0", "uvicorn[standard]>=0.13.
 usso = "usso:main"
 
 [tool.setuptools]
-package-data = {"usso" = ["*.dat"]}
+package-data = { "usso_jwt" = ["*.dat"] }
+
+[tool.ruff]
+line-length = 79
+target-version = "py313"
+fix = true
+unsafe-fixes = true
+preview = true
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+
+[tool.ruff.format]
+quote-style = "double"

usso-0.28.1/pytest.ini

@@ -0,0 +1,22 @@
+[pytest]
+pythonpath = .
+testpaths = tests
+
+asyncio_mode = auto
+asyncio_default_fixture_loop_scope = session
+
+
+addopts = 
+    --cov=src/usso/integrations/fastapi
+    --cov=src/usso/auth
+    --cov=src/usso/models
+    ; --cov=src/usso/session
+    --cov=src/usso/utils
+    ; --cov=src/usso
+    --cov-report=term-missing
+    --cov-report=html
+    --cov-fail-under=75
+
+filterwarnings =
+    ignore:.*pkg_resources.*:DeprecationWarning
+    

usso-0.28.1/src/usso/__init__.py

@@ -0,0 +1,25 @@
+"""USSO - Universal Single Sign-On Client
+
+A plug-and-play client for integrating universal single sign-on (SSO)
+with Python frameworks, enabling secure and seamless authentication
+across microservices.
+"""
+
+from .auth import APIHeaderConfig, AuthConfig, HeaderConfig, UssoAuth
+from .exceptions import USSOException
+from .models.user import UserData
+
+__version__ = "0.28.0"
+
+__all__ = [
+    # Main client
+    "UssoAuth",
+    # Configuration
+    "AuthConfig",
+    "HeaderConfig",
+    "APIHeaderConfig",
+    # Models
+    "UserData",
+    # Exceptions
+    "USSOException",
+]

usso-0.28.1/src/usso/auth/__init__.py

@@ -0,0 +1,9 @@
+"""USSO Authentication Module.
+
+This module provides the core authentication functionality for USSO.
+"""
+
+from .client import UssoAuth
+from .config import APIHeaderConfig, AuthConfig, HeaderConfig
+
+__all__ = ["UssoAuth", "AuthConfig", "HeaderConfig", "APIHeaderConfig"]

usso-0.28.1/src/usso/auth/api_key.py

@@ -0,0 +1,43 @@
+import logging
+from urllib.parse import urlparse
+
+import cachetools.func
+import httpx
+
+from ..exceptions import USSOException
+from ..models.user import UserData
+
+logger = logging.getLogger("usso")
+
+
+def _handle_exception(error_type: str, **kwargs):
+    """Handle API key related exceptions."""
+    if kwargs.get("raise_exception", True):
+        raise USSOException(
+            status_code=401, error=error_type, message=kwargs.get("message")
+        )
+    logger.error(kwargs.get("message") or error_type)
+
+
+@cachetools.func.ttl_cache(maxsize=128, ttl=10 * 60)
+def fetch_api_key_data(jwk_url: str, api_key: str):
+    """Fetch user data using an API key.
+
+    Args:
+        jwk_url: The JWK URL to use for verification
+        api_key: The API key to verify
+
+    Returns:
+        UserData: The user data associated with the API key
+
+    Raises:
+        USSOException: If the API key is invalid or verification fails
+    """
+    try:
+        parsed = urlparse(jwk_url)
+        url = f"{parsed.scheme}://{parsed.netloc}/api_key/verify"
+        response = httpx.post(url, json={"api_key": api_key})
+        response.raise_for_status()
+        return UserData(**response.json())
+    except Exception as e:
+        _handle_exception("error", message=str(e))

usso-0.28.1/src/usso/auth/client.py

@@ -0,0 +1,87 @@
+import logging
+
+import usso_jwt.exceptions
+import usso_jwt.schemas
+
+from ..exceptions import _handle_exception
+from ..models.user import UserData
+from .api_key import fetch_api_key_data
+from .config import AuthConfig, AvailableJwtConfigs
+
+logger = logging.getLogger("usso")
+
+
+class UssoAuth:
+    """Main authentication client for USSO.
+
+    This client handles token validation, user data retrieval,
+    and API key verification.
+    """
+
+    def __init__(
+        self,
+        *,
+        jwt_config: AvailableJwtConfigs | None = None,
+    ):
+        """Initialize the USSO authentication client.
+
+        Args:
+            jwt_config: JWT configuration(s) to use for token validation
+        """
+        if jwt_config is None:
+            jwt_config = AuthConfig()
+        self.jwt_configs = AuthConfig.validate_jwt_configs(jwt_config)
+
+    def user_data_from_token(
+        self,
+        token: str,
+        *,
+        expected_acr: str | None = "access",
+        raise_exception: bool = True,
+        **kwargs,
+    ) -> UserData | None:
+        """Get user data from a JWT token.
+
+        Args:
+            token: The JWT token to validate
+            expected_acr: Expected authentication context reference
+            raise_exception: Whether to raise exception on error
+            **kwargs: Additional arguments to pass to token verification
+
+        Returns:
+            UserData if token is valid, None otherwise
+
+        Raises:
+            USSOException: If token is invalid and raise_exception is True
+        """
+        exp = None
+        for jwk_config in self.jwt_configs:
+            try:
+                jwt_obj = usso_jwt.schemas.JWT(
+                    token=token, config=jwk_config, payload_class=UserData
+                )
+                if jwt_obj.verify(expected_acr=expected_acr, **kwargs):
+                    return jwt_obj.payload
+            except usso_jwt.exceptions.JWTError as e:
+                exp = e
+
+        _handle_exception(
+            "Unauthorized",
+            message=str(exp) if exp else None,
+            raise_exception=raise_exception,
+            **kwargs,
+        )
+
+    def user_data_from_api_key(self, api_key: str) -> UserData:
+        """Get user data from an API key.
+
+        Args:
+            api_key: The API key to verify
+
+        Returns:
+            UserData: The user data associated with the API key
+
+        Raises:
+            USSOException: If the API key is invalid
+        """
+        return fetch_api_key_data(self.jwt_configs[0].jwk_url, api_key)

usso-0.28.1/src/usso/auth/config.py

@@ -0,0 +1,115 @@
+import json
+from typing import Any, Literal, Union
+
+import usso_jwt.config
+from pydantic import BaseModel, model_validator
+
+from ..models.user import UserData
+from ..utils.string_utils import get_authorization_scheme_param
+
+
+class HeaderConfig(BaseModel):
+    type: Literal["Authorization", "Cookie", "CustomHeader"] = "Cookie"
+    name: str = "usso_access_token"
+
+    @model_validator(mode="before")
+    def validate_header(cls, data: dict):
+        if data.get("type") == "Authorization" and not data.get("name"):
+            data["name"] = "Bearer"
+        elif data.get("type") == "Cookie":
+            data["name"] = data.get("name", "usso_access_token")
+        elif data.get("type") == "CustomHeader":
+            data["name"] = data.get("name", "x-usso-access-token")
+        return data
+
+    def __hash__(self):
+        return hash(self.model_dump_json())
+
+    def get_key(self, request) -> str | None:
+        headers: dict[str, Any] = getattr(request, "headers", {})
+        cookies: dict[str, str] = getattr(
+            request, "cookies", headers.get("Cookie", {})
+        )
+        if self.type == "CustomHeader":
+            return headers.get(self.name)
+        elif self.type == "Cookie":
+            return cookies.get(self.name)
+        elif self.type == "Authorization":
+            authorization = headers.get("Authorization")
+        if self.type == "Authorization":
+            authorization = headers.get("Authorization")
+            scheme, credentials = get_authorization_scheme_param(authorization)
+            if scheme.lower() == self.name.lower():
+                return credentials
+
+
+class APIHeaderConfig(HeaderConfig):
+    verify_endpoint: str = "https://sso.usso.io/api_key/verify"
+
+
+class AuthConfig(usso_jwt.config.JWTConfig):
+    """Configuration for JWT processing."""
+
+    api_key_header: APIHeaderConfig | None = APIHeaderConfig(
+        type="CustomHeader", name="x-api-key"
+    )
+    jwt_header: HeaderConfig | None = HeaderConfig()
+    static_api_keys: list[str] | None = None
+
+    def get_api_key(self, request) -> str | None:
+        if self.api_key_header:
+            return self.api_key_header.get_key(request)
+        return None
+
+    def get_jwt(self, request) -> str | None:
+        if self.jwt_header:
+            return self.jwt_header.get_key(request)
+        return None
+
+    def verify_token(
+        self, token: str, *, raise_exception: bool = True, **kwargs
+    ) -> bool:
+        from usso_jwt import exceptions as jwt_exceptions
+        from usso_jwt import schemas
+
+        try:
+            return schemas.JWT(
+                token=token,
+                config=self,
+                payload_class=UserData,
+            ).verify(**kwargs)
+        except jwt_exceptions.JWTError as e:
+            if raise_exception:
+                raise e
+            return False
+
+    @classmethod
+    def _parse_config(
+        cls, config: Union[str, dict, "AuthConfig"]
+    ) -> "AuthConfig":
+        """Parse a single JWT configuration."""
+        if isinstance(config, str):
+            config = json.loads(config)
+        if isinstance(config, dict):
+            return cls(**config)
+        if isinstance(config, cls):
+            return config
+        raise ValueError("Invalid JWT configuration")
+
+    @classmethod
+    def validate_jwt_configs(
+        cls,
+        jwt_config: Union[
+            str, dict, "AuthConfig", list[str], list[dict], list["AuthConfig"]
+        ],
+    ) -> list["AuthConfig"]:
+        if isinstance(jwt_config, (str, dict, cls)):
+            return [cls._parse_config(jwt_config)]
+        if isinstance(jwt_config, list):
+            return [cls._parse_config(config) for config in jwt_config]
+        raise ValueError("Invalid jwt_config format")
+
+
+AvailableJwtConfigs = (
+    str | dict | AuthConfig | list[str] | list[dict] | list[AuthConfig]
+)