pargo-auth 0.1.2__tar.gz

pargo_auth-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,63 @@
+name: Deploy to PyPI
+
+on:
+  push:
+    branches: [master, main]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install hatch
+
+      - name: Bump version
+        id: bump
+        run: |
+          CURRENT=$(grep -Po '(?<=__version__ = ")[^"]+' src/pargo_auth/__init__.py)
+          echo "Current version: $CURRENT"
+          
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
+          NEW_PATCH=$((PATCH + 1))
+          NEW_VERSION="$MAJOR.$MINOR.$NEW_PATCH"
+          echo "New version: $NEW_VERSION"
+          
+          sed -i "s/__version__ = \"$CURRENT\"/__version__ = \"$NEW_VERSION\"/" src/pargo_auth/__init__.py
+          echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Commit version bump
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add src/pargo_auth/__init__.py
+          git commit -m "Bump version to ${{ steps.bump.outputs.version }}" || echo "No changes to commit"
+          git push
+
+      - name: Build package
+        run: hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Verify deployment
+        run: |
+          echo "=== Package built ==="
+          ls -la dist/
+          echo ""
+          echo "=== Version deployed ==="
+          echo "pargo-auth ${{ steps.bump.outputs.version }}"

pargo_auth-0.1.2/.gitignore

@@ -0,0 +1,62 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# macOS
+.DS_Store

pargo_auth-0.1.2/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.

pargo_auth-0.1.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,117 @@
+# 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/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pargo-auth"
+dynamic = ["version"]
+description = "Shared authentication middleware for PARGO backend services"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "PARGO", email = "dev@pargo.dk" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "fastapi>=0.100.0",
+    "httpx>=0.24.0",
+    "PyJWT>=2.8.0",
+    "cryptography>=41.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/pargoorg/pargo-auth"
+Repository = "https://github.com/pargoorg/pargo-auth"
+
+[tool.hatch.version]
+path = "src/pargo_auth/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pargo_auth"]

pargo_auth-0.1.2/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+testpaths = tests
+asyncio_mode = auto

pargo_auth-0.1.2/src/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-0.1.2/src/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-0.1.2/src/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-0.1.2/src/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/tests/test_middleware.py

@@ -0,0 +1,42 @@
+"""Tests for auth middleware."""
+
+import pytest
+from pargo_auth import AuthenticatedUser
+from pargo_auth.exceptions import InvalidTokenError, ExpiredTokenError
+
+
+def test_authenticated_user_creation():
+    """Test AuthenticatedUser dataclass."""
+    user = AuthenticatedUser(
+        sub="user-123",
+        email="test@example.com",
+        email_verified=True,
+    )
+    
+    assert user.sub == "user-123"
+    assert user.supabase_uid == "user-123"  # Alias
+    assert user.email == "test@example.com"
+    assert user.email_verified is True
+
+
+def test_authenticated_user_minimal():
+    """Test AuthenticatedUser with minimal fields."""
+    user = AuthenticatedUser(sub="user-456")
+    
+    assert user.sub == "user-456"
+    assert user.email is None
+    assert user.email_verified is False
+
+
+def test_invalid_token_error():
+    """Test InvalidTokenError."""
+    error = InvalidTokenError("bad token")
+    assert error.status_code == 401
+    assert error.message == "bad token"
+
+
+def test_expired_token_error():
+    """Test ExpiredTokenError."""
+    error = ExpiredTokenError()
+    assert error.status_code == 401
+    assert "expired" in error.message.lower()