pargo-auth 0.1.2__py3-none-any.whl

pargo_auth/__init__.py

@@ -0,0 +1,17 @@
+"""PARGO Auth - Shared authentication middleware for PARGO backend services."""
+
+__version__ = "0.1.2"
+
+from .middleware import SupabaseAuth, get_current_user, require_auth
+from .models import AuthenticatedUser
+from .exceptions import AuthError, InvalidTokenError, ExpiredTokenError
+
+__all__ = [
+    "SupabaseAuth",
+    "get_current_user",
+    "require_auth",
+    "AuthenticatedUser",
+    "AuthError",
+    "InvalidTokenError",
+    "ExpiredTokenError",
+]

pargo_auth/exceptions.py

@@ -0,0 +1,31 @@
+"""Authentication exceptions."""
+
+
+class AuthError(Exception):
+    """Base authentication error."""
+    
+    def __init__(self, message: str = "Authentication failed", status_code: int = 401):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(self.message)
+
+
+class InvalidTokenError(AuthError):
+    """Token is malformed or signature is invalid."""
+    
+    def __init__(self, message: str = "Invalid token"):
+        super().__init__(message, status_code=401)
+
+
+class ExpiredTokenError(AuthError):
+    """Token has expired."""
+    
+    def __init__(self, message: str = "Token expired"):
+        super().__init__(message, status_code=401)
+
+
+class MissingTokenError(AuthError):
+    """No token provided."""
+    
+    def __init__(self, message: str = "Missing authorization header"):
+        super().__init__(message, status_code=401)

pargo_auth/middleware.py

@@ -0,0 +1,206 @@
+"""FastAPI authentication middleware for Supabase JWT verification."""
+
+import os
+import logging
+from typing import Optional
+from functools import lru_cache
+
+import httpx
+import jwt
+from fastapi import Request, HTTPException, Depends
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+from .models import AuthenticatedUser
+from .exceptions import AuthError, InvalidTokenError, ExpiredTokenError, MissingTokenError
+
+logger = logging.getLogger(__name__)
+
+# Security scheme for OpenAPI docs
+security = HTTPBearer(auto_error=False)
+
+
+class SupabaseAuth:
+    """
+    Supabase JWT verification using JWKS.
+    
+    Usage:
+        auth = SupabaseAuth(
+            supabase_url="https://xxx.supabase.co",
+            supabase_anon_key="your-anon-key",  # Optional, for audience validation
+        )
+        
+        @app.get("/protected")
+        async def protected(user: AuthenticatedUser = Depends(auth.get_user)):
+            return {"user_id": user.sub}
+    """
+    
+    def __init__(
+        self,
+        supabase_url: Optional[str] = None,
+        supabase_anon_key: Optional[str] = None,
+        skip_verification_in_dev: bool = True,
+    ):
+        self.supabase_url = supabase_url or os.getenv("SUPABASE_URL")
+        self.supabase_anon_key = supabase_anon_key or os.getenv("SUPABASE_ANON_KEY")
+        self.skip_verification_in_dev = skip_verification_in_dev
+        self._jwks_client: Optional[jwt.PyJWKClient] = None
+        
+        if not self.supabase_url:
+            raise ValueError("SUPABASE_URL must be set")
+    
+    @property
+    def jwks_url(self) -> str:
+        """JWKS endpoint for Supabase project."""
+        return f"{self.supabase_url}/auth/v1/.well-known/jwks.json"
+    
+    @property
+    def issuer(self) -> str:
+        """Expected JWT issuer."""
+        return f"{self.supabase_url}/auth/v1"
+    
+    def _get_jwks_client(self) -> jwt.PyJWKClient:
+        """Get or create JWKS client (cached)."""
+        if self._jwks_client is None:
+            self._jwks_client = jwt.PyJWKClient(
+                self.jwks_url,
+                cache_keys=True,
+                lifespan=3600,  # Cache keys for 1 hour
+            )
+        return self._jwks_client
+    
+    def verify_token(self, token: str) -> AuthenticatedUser:
+        """
+        Verify a Supabase JWT and return user info.
+        
+        Raises:
+            InvalidTokenError: Token is malformed or signature invalid
+            ExpiredTokenError: Token has expired
+        """
+        try:
+            # Get signing key from JWKS
+            jwks_client = self._get_jwks_client()
+            signing_key = jwks_client.get_signing_key_from_jwt(token)
+            
+            # Decode and verify
+            payload = jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=["RS256"],
+                issuer=self.issuer,
+                options={
+                    "verify_aud": False,  # Supabase doesn't always set aud
+                    "verify_iss": True,
+                    "verify_exp": True,
+                },
+            )
+            
+            return AuthenticatedUser(
+                sub=payload["sub"],
+                email=payload.get("email"),
+                email_verified=payload.get("email_verified", False),
+                raw_claims=payload,
+            )
+            
+        except jwt.ExpiredSignatureError:
+            raise ExpiredTokenError()
+        except jwt.InvalidTokenError as e:
+            logger.warning(f"Invalid token: {e}")
+            raise InvalidTokenError(str(e))
+        except Exception as e:
+            logger.error(f"Token verification failed: {e}")
+            raise InvalidTokenError("Token verification failed")
+    
+    async def get_user(
+        self,
+        request: Request,
+        credentials: Optional[HTTPAuthorizationCredentials] = Depends(security),
+    ) -> AuthenticatedUser:
+        """
+        FastAPI dependency to get authenticated user.
+        
+        Usage:
+            @app.get("/me")
+            async def get_me(user: AuthenticatedUser = Depends(auth.get_user)):
+                return {"id": user.sub}
+        """
+        # Skip auth in local development
+        if self.skip_verification_in_dev and os.getenv("ENV") == "local":
+            return AuthenticatedUser(
+                sub="local-dev-user",
+                email="dev@local",
+                email_verified=True,
+            )
+        
+        # Extract token
+        token = None
+        if credentials:
+            token = credentials.credentials
+        
+        # Fallback: check x-user-id header (legacy support)
+        if not token:
+            legacy_uid = request.headers.get("x-user-id")
+            if legacy_uid:
+                logger.warning("Using legacy x-user-id header - migrate to Bearer token")
+                return AuthenticatedUser(sub=legacy_uid)
+        
+        if not token:
+            raise HTTPException(status_code=401, detail="Missing authorization")
+        
+        try:
+            return self.verify_token(token)
+        except AuthError as e:
+            raise HTTPException(status_code=e.status_code, detail=e.message)
+    
+    async def get_user_optional(
+        self,
+        request: Request,
+        credentials: Optional[HTTPAuthorizationCredentials] = Depends(security),
+    ) -> Optional[AuthenticatedUser]:
+        """
+        FastAPI dependency that returns None instead of raising if not authenticated.
+        Useful for endpoints that work differently for logged-in vs anonymous users.
+        """
+        try:
+            return await self.get_user(request, credentials)
+        except HTTPException:
+            return None
+
+
+# Convenience: module-level instance using environment variables
+_default_auth: Optional[SupabaseAuth] = None
+
+
+def _get_default_auth() -> SupabaseAuth:
+    """Get or create default auth instance from environment."""
+    global _default_auth
+    if _default_auth is None:
+        _default_auth = SupabaseAuth()
+    return _default_auth
+
+
+async def get_current_user(
+    request: Request,
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security),
+) -> AuthenticatedUser:
+    """
+    Convenience dependency using environment-configured auth.
+    
+    Usage:
+        from pargo_auth import get_current_user, AuthenticatedUser
+        
+        @app.get("/me")
+        async def get_me(user: AuthenticatedUser = Depends(get_current_user)):
+            return {"id": user.sub}
+    """
+    auth = _get_default_auth()
+    return await auth.get_user(request, credentials)
+
+
+def require_auth():
+    """
+    Dependency that can be used in router dependencies list.
+    
+    Usage:
+        router = APIRouter(dependencies=[Depends(require_auth())])
+    """
+    return Depends(get_current_user)

pargo_auth/models.py

@@ -0,0 +1,21 @@
+"""Data models for authentication."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class AuthenticatedUser:
+    """Represents an authenticated user from Supabase JWT."""
+    
+    sub: str  # Supabase user ID (stable, use as canonical identity)
+    email: Optional[str] = None
+    email_verified: bool = False
+    
+    # Raw claims for extensibility
+    raw_claims: Optional[dict] = None
+    
+    @property
+    def supabase_uid(self) -> str:
+        """Alias for sub - the Supabase user ID."""
+        return self.sub

pargo_auth-0.1.2.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: pargo-auth
+Version: 0.1.2
+Summary: Shared authentication middleware for PARGO backend services
+Project-URL: Homepage, https://github.com/pargoorg/pargo-auth
+Project-URL: Repository, https://github.com/pargoorg/pargo-auth
+Author-email: PARGO <dev@pargo.dk>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pyjwt>=2.8.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pargo-auth
+
+Shared authentication middleware for PARGO backend services. Verifies Supabase JWTs and provides FastAPI dependencies.
+
+## Installation
+
+```bash
+pip install pargo-auth
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI, Depends
+from pargo_auth import get_current_user, AuthenticatedUser
+
+app = FastAPI()
+
+@app.get("/me")
+async def get_me(user: AuthenticatedUser = Depends(get_current_user)):
+    return {
+        "id": user.sub,
+        "email": user.email,
+    }
+```
+
+## Configuration
+
+Set these environment variables:
+
+```bash
+SUPABASE_URL=https://your-project.supabase.co
+ENV=local  # Skip auth verification in local dev
+```
+
+## Usage Patterns
+
+### Basic: Protect individual endpoints
+
+```python
+from pargo_auth import get_current_user, AuthenticatedUser
+
+@app.get("/protected")
+async def protected(user: AuthenticatedUser = Depends(get_current_user)):
+    return {"user_id": user.sub}
+```
+
+### Protect entire router
+
+```python
+from fastapi import APIRouter, Depends
+from pargo_auth import require_auth
+
+router = APIRouter(dependencies=[require_auth()])
+
+@router.get("/data")
+async def get_data():  # Auth already required by router
+    return {"data": "secret"}
+```
+
+### Optional auth (different behavior for logged-in vs anonymous)
+
+```python
+from pargo_auth import SupabaseAuth, AuthenticatedUser
+
+auth = SupabaseAuth()
+
+@app.get("/content")
+async def get_content(user: AuthenticatedUser | None = Depends(auth.get_user_optional)):
+    if user:
+        return {"content": "personalized", "user": user.sub}
+    return {"content": "generic"}
+```
+
+### Custom instance (non-default config)
+
+```python
+from pargo_auth import SupabaseAuth
+
+auth = SupabaseAuth(
+    supabase_url="https://custom.supabase.co",
+    skip_verification_in_dev=False,  # Always verify, even locally
+)
+
+@app.get("/strict")
+async def strict_endpoint(user = Depends(auth.get_user)):
+    return {"user": user.sub}
+```
+
+## AuthenticatedUser
+
+The `AuthenticatedUser` object contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sub` | `str` | Supabase user ID (stable, use as canonical identity) |
+| `email` | `str \| None` | User's email (if available) |
+| `email_verified` | `bool` | Whether email is verified |
+| `raw_claims` | `dict \| None` | Full JWT payload for custom claims |
+
+## Legacy Support
+
+For backwards compatibility, the middleware also checks for `x-user-id` header if no Bearer token is present. This allows gradual migration from the old auth system.
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+```
+
+## License
+
+MIT

pargo_auth-0.1.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+pargo_auth/__init__.py,sha256=lWjCNYxegtjkGnnQu7mvjGs5iyLAuaSLFwnAmWqIPcM,454
+pargo_auth/exceptions.py,sha256=Qckee29SlPf8VS21s-1gT8j_gCoYKaJhYKet9DE28WE,879
+pargo_auth/middleware.py,sha256=fCh41HYMfNQbEieVFnUG6uCl-wr0SQ2KahGX297HCYE,6779
+pargo_auth/models.py,sha256=I_mb0PGPy7FHZbMHxs1tR4NekD-cv1Ea4ZSzjStDZo4,548
+pargo_auth-0.1.2.dist-info/METADATA,sha256=xXFakWjCY3MzTammApy2JUSnO8Myss86EA0x_LgIvg4,3612
+pargo_auth-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pargo_auth-0.1.2.dist-info/licenses/LICENSE,sha256=A-E9k545xbWsw-1DRhKLXcePHJ15tKx_bQl12OabqEY,1062
+pargo_auth-0.1.2.dist-info/RECORD,,

pargo_auth-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pargo_auth-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PARGO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.