authaction-python-sdk 0.1.0__tar.gz

authaction_python_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: authaction-python-sdk
+Version: 0.1.0
+Summary: AuthAction JWT verification SDK for Python — Django, Flask, and FastAPI
+License: MIT
+Keywords: oauth2,jwt,jwks,authentication,authaction,django,flask,fastapi
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: PyJWT[crypto]>=2.8.0
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == "django"
+Requires-Dist: djangorestframework>=3.14; extra == "django"
+Provides-Extra: flask
+Requires-Dist: flask>=2.3; extra == "flask"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == "fastapi"
+Requires-Dist: httpx>=0.24; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: django>=3.2; extra == "dev"
+Requires-Dist: djangorestframework>=3.14; extra == "dev"
+Requires-Dist: flask>=2.3; extra == "dev"
+Requires-Dist: fastapi>=0.100; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+
+# authaction-python-sdk
+
+JWT verification SDK for Python backends. Validates AuthAction access tokens via JWKS — handles key fetching, caching, and rotation automatically.
+
+Works with **Django REST Framework**, **Flask**, and **FastAPI**.
+
+## Installation
+
+```bash
+# Core only
+pip install authaction-python-sdk
+
+# With Django support
+pip install "authaction-python-sdk[django]"
+
+# With Flask support
+pip install "authaction-python-sdk[flask]"
+
+# With FastAPI support
+pip install "authaction-python-sdk[fastapi]"
+```
+
+---
+
+## Core
+
+```python
+from authaction import AuthAction
+
+aa = AuthAction(
+    domain=os.getenv("AUTHACTION_DOMAIN"),    # e.g. myapp.eu.authaction.com
+    audience=os.getenv("AUTHACTION_AUDIENCE"), # e.g. https://api.myapp.com
+)
+
+# Verify a raw token — raises TokenExpiredError / TokenInvalidError on failure
+payload = aa.verify_token(token)
+
+# Verify from Authorization header — returns None on missing/invalid, never raises
+payload = aa.verify_request(request.headers.get("Authorization"))
+
+print(payload["sub"])   # user identifier
+print(payload["email"]) # any JWT claim
+```
+
+---
+
+## Django REST Framework
+
+### 1. Configure settings
+
+```python
+# settings.py
+AUTHACTION = {
+    "DOMAIN":   os.getenv("AUTHACTION_DOMAIN"),
+    "AUDIENCE": os.getenv("AUTHACTION_AUDIENCE"),
+}
+
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "authaction.django.AuthActionAuthentication",
+    ],
+    "DEFAULT_PERMISSION_CLASSES": [
+        "rest_framework.permissions.IsAuthenticated",
+    ],
+}
+```
+
+### 2. Use in views
+
+```python
+from rest_framework.decorators import api_view, permission_classes
+from rest_framework.permissions import AllowAny, IsAuthenticated
+from rest_framework.response import Response
+
+@api_view(["GET"])
+@permission_classes([AllowAny])
+def public_view(request):
+    return Response({"message": "Public"})
+
+@api_view(["GET"])
+def protected_view(request):
+    return Response({"sub": request.user.sub, "email": request.user.email})
+```
+
+`request.user` is an `AuthenticatedToken` — access any JWT claim as an attribute:
+
+```python
+request.user.sub        # str
+request.user.email      # any claim
+request.user.payload    # dict — all raw claims
+```
+
+---
+
+## Flask
+
+```python
+from authaction import AuthAction
+from authaction.flask import make_require_auth
+
+aa = AuthAction(
+    domain=os.getenv("AUTHACTION_DOMAIN"),
+    audience=os.getenv("AUTHACTION_AUDIENCE"),
+)
+require_auth = make_require_auth(aa)
+
+@app.get("/public")
+def public_route():
+    return {"message": "Public"}
+
+@app.get("/protected")
+@require_auth
+def protected_route():
+    from flask import g
+    return {"sub": g.current_user["sub"]}
+```
+
+The decoded payload is available as `g.current_user` (a `dict`) inside decorated routes.
+
+---
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, Depends
+from authaction import AuthAction
+from authaction.fastapi import make_require_auth
+
+aa = AuthAction(
+    domain=os.getenv("AUTHACTION_DOMAIN"),
+    audience=os.getenv("AUTHACTION_AUDIENCE"),
+)
+require_auth = make_require_auth(aa)
+
+app = FastAPI()
+
+@app.get("/public")
+def public_route():
+    return {"message": "Public"}
+
+@app.get("/protected")
+def protected_route(user: dict = Depends(require_auth)):
+    return {"sub": user["sub"], "email": user.get("email")}
+```
+
+### Scope enforcement
+
+```python
+require_admin = make_require_auth(aa, scopes=["admin"])
+
+@app.delete("/users/{user_id}")
+def delete_user(user_id: str, user: dict = Depends(require_admin)):
+    ...  # raises HTTP 403 if token lacks 'admin' scope
+```
+
+---
+
+## Exceptions
+
+```python
+from authaction.exceptions import TokenExpiredError, TokenInvalidError
+
+try:
+    payload = aa.verify_token(token)
+except TokenExpiredError:
+    # token exp claim is in the past
+    ...
+except TokenInvalidError:
+    # bad signature, wrong issuer/audience, malformed JWT
+    ...
+```
+
+## Environment variables
+
+```bash
+AUTHACTION_DOMAIN=your-tenant.eu.authaction.com
+AUTHACTION_AUDIENCE=https://api.your-app.com
+```
+
+## How JWKS caching works
+
+Uses `PyJWT`'s `PyJWKClient` which:
+- Fetches public keys from `https://<domain>/.well-known/jwks.json` on first use
+- Caches up to 16 keys in-process (LRU, configurable via `jwks_cache_keys`)
+- Automatically re-fetches when an unknown `kid` is encountered (key rotation)
+
+## License
+
+MIT

authaction_python_sdk-0.1.0/README.md

@@ -0,0 +1,189 @@
+# authaction-python-sdk
+
+JWT verification SDK for Python backends. Validates AuthAction access tokens via JWKS — handles key fetching, caching, and rotation automatically.
+
+Works with **Django REST Framework**, **Flask**, and **FastAPI**.
+
+## Installation
+
+```bash
+# Core only
+pip install authaction-python-sdk
+
+# With Django support
+pip install "authaction-python-sdk[django]"
+
+# With Flask support
+pip install "authaction-python-sdk[flask]"
+
+# With FastAPI support
+pip install "authaction-python-sdk[fastapi]"
+```
+
+---
+
+## Core
+
+```python
+from authaction import AuthAction
+
+aa = AuthAction(
+    domain=os.getenv("AUTHACTION_DOMAIN"),    # e.g. myapp.eu.authaction.com
+    audience=os.getenv("AUTHACTION_AUDIENCE"), # e.g. https://api.myapp.com
+)
+
+# Verify a raw token — raises TokenExpiredError / TokenInvalidError on failure
+payload = aa.verify_token(token)
+
+# Verify from Authorization header — returns None on missing/invalid, never raises
+payload = aa.verify_request(request.headers.get("Authorization"))
+
+print(payload["sub"])   # user identifier
+print(payload["email"]) # any JWT claim
+```
+
+---
+
+## Django REST Framework
+
+### 1. Configure settings
+
+```python
+# settings.py
+AUTHACTION = {
+    "DOMAIN":   os.getenv("AUTHACTION_DOMAIN"),
+    "AUDIENCE": os.getenv("AUTHACTION_AUDIENCE"),
+}
+
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "authaction.django.AuthActionAuthentication",
+    ],
+    "DEFAULT_PERMISSION_CLASSES": [
+        "rest_framework.permissions.IsAuthenticated",
+    ],
+}
+```
+
+### 2. Use in views
+
+```python
+from rest_framework.decorators import api_view, permission_classes
+from rest_framework.permissions import AllowAny, IsAuthenticated
+from rest_framework.response import Response
+
+@api_view(["GET"])
+@permission_classes([AllowAny])
+def public_view(request):
+    return Response({"message": "Public"})
+
+@api_view(["GET"])
+def protected_view(request):
+    return Response({"sub": request.user.sub, "email": request.user.email})
+```
+
+`request.user` is an `AuthenticatedToken` — access any JWT claim as an attribute:
+
+```python
+request.user.sub        # str
+request.user.email      # any claim
+request.user.payload    # dict — all raw claims
+```
+
+---
+
+## Flask
+
+```python
+from authaction import AuthAction
+from authaction.flask import make_require_auth
+
+aa = AuthAction(
+    domain=os.getenv("AUTHACTION_DOMAIN"),
+    audience=os.getenv("AUTHACTION_AUDIENCE"),
+)
+require_auth = make_require_auth(aa)
+
+@app.get("/public")
+def public_route():
+    return {"message": "Public"}
+
+@app.get("/protected")
+@require_auth
+def protected_route():
+    from flask import g
+    return {"sub": g.current_user["sub"]}
+```
+
+The decoded payload is available as `g.current_user` (a `dict`) inside decorated routes.
+
+---
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, Depends
+from authaction import AuthAction
+from authaction.fastapi import make_require_auth
+
+aa = AuthAction(
+    domain=os.getenv("AUTHACTION_DOMAIN"),
+    audience=os.getenv("AUTHACTION_AUDIENCE"),
+)
+require_auth = make_require_auth(aa)
+
+app = FastAPI()
+
+@app.get("/public")
+def public_route():
+    return {"message": "Public"}
+
+@app.get("/protected")
+def protected_route(user: dict = Depends(require_auth)):
+    return {"sub": user["sub"], "email": user.get("email")}
+```
+
+### Scope enforcement
+
+```python
+require_admin = make_require_auth(aa, scopes=["admin"])
+
+@app.delete("/users/{user_id}")
+def delete_user(user_id: str, user: dict = Depends(require_admin)):
+    ...  # raises HTTP 403 if token lacks 'admin' scope
+```
+
+---
+
+## Exceptions
+
+```python
+from authaction.exceptions import TokenExpiredError, TokenInvalidError
+
+try:
+    payload = aa.verify_token(token)
+except TokenExpiredError:
+    # token exp claim is in the past
+    ...
+except TokenInvalidError:
+    # bad signature, wrong issuer/audience, malformed JWT
+    ...
+```
+
+## Environment variables
+
+```bash
+AUTHACTION_DOMAIN=your-tenant.eu.authaction.com
+AUTHACTION_AUDIENCE=https://api.your-app.com
+```
+
+## How JWKS caching works
+
+Uses `PyJWT`'s `PyJWKClient` which:
+- Fetches public keys from `https://<domain>/.well-known/jwks.json` on first use
+- Caches up to 16 keys in-process (LRU, configurable via `jwks_cache_keys`)
+- Automatically re-fetches when an unknown `kid` is encountered (key rotation)
+
+## License
+
+MIT

authaction_python_sdk-0.1.0/authaction/__init__.py

@@ -0,0 +1,70 @@
+"""
+AuthAction Python SDK — JWT verification for Django and Flask APIs.
+
+Quick start::
+
+    from authaction import AuthAction
+
+    aa = AuthAction(domain="myapp.eu.authaction.com", audience="https://api.myapp.com")
+
+    # Verify a raw token (raises TokenExpiredError / TokenInvalidError on failure)
+    payload = aa.verify_token(token)
+
+    # Verify from an Authorization header value (returns None on missing/invalid)
+    payload = aa.verify_request(request.headers.get("Authorization"))
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._verifier import JwtVerifier
+from .exceptions import AuthActionError, TokenExpiredError, TokenInvalidError
+
+__all__ = [
+    "AuthAction",
+    "JwtVerifier",
+    "AuthActionError",
+    "TokenExpiredError",
+    "TokenInvalidError",
+]
+
+__version__ = "0.1.0"
+
+
+class AuthAction:
+    """
+    Top-level AuthAction client.
+
+    :param domain: AuthAction tenant domain (e.g. ``myapp.eu.authaction.com``).
+    :param audience: API identifier registered in AuthAction.
+    :param jwks_cache_keys: Maximum number of public keys to cache (default 16).
+
+    Example::
+
+        aa = AuthAction(
+            domain=os.getenv("AUTHACTION_DOMAIN"),
+            audience=os.getenv("AUTHACTION_AUDIENCE"),
+        )
+        payload = aa.verify_token(token)
+    """
+
+    def __init__(
+        self,
+        domain: str,
+        audience: str,
+        jwks_cache_keys: int = 16,
+    ) -> None:
+        self._verifier = JwtVerifier(
+            domain=domain,
+            audience=audience,
+            jwks_cache_keys=jwks_cache_keys,
+        )
+
+    def verify_token(self, token: str) -> dict[str, Any]:
+        """Verify a raw JWT string and return the decoded claims."""
+        return self._verifier.verify_token(token)
+
+    def verify_request(self, authorization_header: str | None) -> dict[str, Any] | None:
+        """Verify a Bearer token from an Authorization header value."""
+        return self._verifier.verify_request(authorization_header)

authaction_python_sdk-0.1.0/authaction/_verifier.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Any
+
+import jwt
+from jwt import PyJWKClient, PyJWKClientError
+
+from .exceptions import TokenExpiredError, TokenInvalidError
+
+
+class JwtVerifier:
+    """
+    Core JWT verifier.
+
+    Wraps PyJWT's PyJWKClient which already handles:
+    - JWKS fetching from /.well-known/jwks.json
+    - In-memory key caching (LRU, configurable size)
+    - Automatic key rotation (re-fetches when an unknown kid is seen)
+
+    Always validates: RS256 algorithm, issuer, audience, and expiry.
+    """
+
+    def __init__(
+        self,
+        domain: str,
+        audience: str,
+        jwks_cache_keys: int = 16,
+    ) -> None:
+        self._domain = domain
+        self._audience = audience
+        self._issuer = f"https://{domain}"
+        self._client = PyJWKClient(
+            f"https://{domain}/.well-known/jwks.json",
+            cache_keys=True,
+            max_cached_keys=jwks_cache_keys,
+        )
+
+    def verify_token(self, token: str) -> dict[str, Any]:
+        """
+        Verify a raw JWT string and return the decoded claims.
+
+        Raises:
+            TokenExpiredError: The token's ``exp`` claim is in the past.
+            TokenInvalidError: Signature, issuer, audience, or structure is invalid.
+        """
+        try:
+            signing_key = self._client.get_signing_key_from_jwt(token)
+        except PyJWKClientError as exc:
+            raise TokenInvalidError(f"JWKS key lookup failed: {exc}") from exc
+
+        try:
+            return jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=["RS256"],
+                audience=self._audience,
+                issuer=self._issuer,
+            )
+        except jwt.ExpiredSignatureError as exc:
+            raise TokenExpiredError("Token has expired") from exc
+        except jwt.InvalidTokenError as exc:
+            raise TokenInvalidError(str(exc)) from exc
+
+    def verify_request(self, authorization_header: str | None) -> dict[str, Any] | None:
+        """
+        Extract the Bearer token from an Authorization header value and verify it.
+
+        Returns ``None`` when the header is absent or not a Bearer scheme.
+        Never raises — returns ``None`` on invalid tokens.
+        """
+        if not authorization_header or not authorization_header.startswith("Bearer "):
+            return None
+        token = authorization_header[7:].strip()
+        try:
+            return self.verify_token(token)
+        except (TokenExpiredError, TokenInvalidError):
+            return None

authaction_python_sdk-0.1.0/authaction/django/__init__.py

@@ -0,0 +1,29 @@
+"""
+Django REST Framework integration for AuthAction.
+
+Configure once in ``settings.py``::
+
+    AUTHACTION = {
+        "DOMAIN": "myapp.eu.authaction.com",
+        "AUDIENCE": "https://api.myapp.com",
+    }
+
+    REST_FRAMEWORK = {
+        "DEFAULT_AUTHENTICATION_CLASSES": [
+            "authaction.django.AuthActionAuthentication",
+        ],
+        "DEFAULT_PERMISSION_CLASSES": [
+            "rest_framework.permissions.IsAuthenticated",
+        ],
+    }
+
+Access the decoded payload in views::
+
+    @api_view(["GET"])
+    def protected(request):
+        return Response({"sub": request.user.sub})
+"""
+
+from .authentication import AuthActionAuthentication, AuthenticatedToken
+
+__all__ = ["AuthActionAuthentication", "AuthenticatedToken"]

authaction_python_sdk-0.1.0/authaction/django/authentication.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Any
+
+from rest_framework.authentication import BaseAuthentication
+from rest_framework.exceptions import AuthenticationFailed
+from rest_framework.request import Request
+
+from .._verifier import JwtVerifier
+from ..exceptions import TokenExpiredError, TokenInvalidError
+
+
+class AuthenticatedToken:
+    """
+    Minimal user-like object that wraps the decoded JWT claims.
+    Assigned to ``request.user`` after successful authentication.
+    """
+
+    is_authenticated = True
+
+    def __init__(self, payload: dict[str, Any]) -> None:
+        self.payload = payload
+
+    @property
+    def sub(self) -> str:
+        return str(self.payload.get("sub", ""))
+
+    def __getattr__(self, item: str) -> Any:
+        try:
+            return self.payload[item]
+        except KeyError:
+            raise AttributeError(item) from None
+
+
+def _get_verifier() -> JwtVerifier:
+    """Lazily construct the verifier from Django settings."""
+    from django.conf import settings  # imported lazily to avoid Django startup order issues
+
+    config: dict[str, Any] = getattr(settings, "AUTHACTION", {})
+    domain = config.get("DOMAIN") or ""
+    audience = config.get("AUDIENCE") or ""
+    if not domain or not audience:
+        raise ImproperlyConfigured(  # noqa: F821
+            "AUTHACTION settings must include 'DOMAIN' and 'AUDIENCE'. "
+            "Add AUTHACTION = {'DOMAIN': '...', 'AUDIENCE': '...'} to settings.py."
+        )
+    return JwtVerifier(domain=domain, audience=audience)
+
+
+try:
+    from django.core.exceptions import ImproperlyConfigured  # noqa: F401
+except ImportError:
+    ImproperlyConfigured = RuntimeError  # type: ignore[misc,assignment]
+
+
+class AuthActionAuthentication(BaseAuthentication):
+    """
+    Django REST Framework authentication class that validates AuthAction JWTs.
+
+    Read the token from ``Authorization: Bearer <token>`` and return
+    ``(AuthenticatedToken(payload), raw_token)`` on success, or ``None``
+    when the header is absent (to allow other authenticators to run).
+
+    Raises ``AuthenticationFailed`` (HTTP 401) when the header is present
+    but the token is invalid or expired.
+
+    Usage::
+
+        REST_FRAMEWORK = {
+            "DEFAULT_AUTHENTICATION_CLASSES": [
+                "authaction.django.AuthActionAuthentication",
+            ],
+        }
+    """
+
+    _verifier: JwtVerifier | None = None
+
+    @classmethod
+    def get_verifier(cls) -> JwtVerifier:
+        if cls._verifier is None:
+            cls._verifier = _get_verifier()
+        return cls._verifier
+
+    def authenticate(self, request: Request) -> tuple[AuthenticatedToken, str] | None:
+        auth_header: str = request.headers.get("Authorization", "")
+
+        if not auth_header.startswith("Bearer "):
+            return None  # Not a Bearer request — let other authenticators try
+
+        token = auth_header[7:].strip()
+        if not token:
+            raise AuthenticationFailed("Empty Bearer token")
+
+        try:
+            payload = self.get_verifier().verify_token(token)
+        except TokenExpiredError:
+            raise AuthenticationFailed("Token has expired")
+        except TokenInvalidError as exc:
+            raise AuthenticationFailed(str(exc))
+
+        return AuthenticatedToken(payload), token
+
+    def authenticate_header(self, request: Request) -> str:
+        return "Bearer"

authaction_python_sdk-0.1.0/authaction/exceptions.py

@@ -0,0 +1,10 @@
+class AuthActionError(Exception):
+    """Base exception for all AuthAction SDK errors."""
+
+
+class TokenExpiredError(AuthActionError):
+    """The JWT's ``exp`` claim is in the past."""
+
+
+class TokenInvalidError(AuthActionError):
+    """The JWT signature, issuer, audience, or structure is invalid."""