hotosm-auth 0.2.3__tar.gz

hotosm_auth-0.2.3/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json

hotosm_auth-0.2.3/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: hotosm-auth
+Version: 0.2.3
+Summary: HOTOSM SSO authentication library for Hanko + OSM OAuth
+Project-URL: Homepage, https://github.com/hotosm/login
+Project-URL: Documentation, https://hotosm.github.io/auth-docs
+Project-URL: Repository, https://github.com/hotosm/login/tree/main/auth-libs/python
+Project-URL: Issues, https://github.com/hotosm/login/issues
+Author-email: HOTOSM <tech@hotosm.org>
+License: AGPL-3.0
+Keywords: auth,django,fastapi,hanko,hotosm,oauth,osm,sso
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt[crypto]>=2.8.0
+Requires-Dist: python-dateutil>=2.8.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2.0; extra == 'django'
+Requires-Dist: djangorestframework>=3.14.0; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.104.0; extra == 'fastapi'
+Requires-Dist: sqlalchemy>=2.0.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# HOTOSM Auth Library - Python
+
+FastAPI/Django integration for Hanko authentication with OSM OAuth support.
+
+## Installation
+
+```bash
+pip install hotosm-auth
+```
+
+## Usage
+
+### FastAPI
+
+```python
+from fastapi import FastAPI, Depends
+from hotosm_auth.integrations.fastapi import CurrentUser
+
+app = FastAPI()
+
+@app.get("/me")
+async def get_me(user: CurrentUser):
+    return {"id": user.id, "email": user.email}
+```
+
+### Django
+
+```python
+from django.http import JsonResponse
+from hotosm_auth.integrations.django import require_auth
+
+@require_auth
+def my_view(request):
+    return JsonResponse({"user_id": request.user.id})
+```
+
+## Features
+
+- JWT validation for Hanko tokens
+- OSM OAuth 2.0 integration
+- User mapping between Hanko and application users
+- FastAPI and Django integrations
+
+## Configuration
+
+Set these environment variables:
+
+```bash
+HANKO_API_URL=https://login.hotosm.org
+OSM_CLIENT_ID=your_osm_client_id
+OSM_CLIENT_SECRET=your_osm_secret
+COOKIE_SECRET=your_secret_key
+```
+
+## License
+
+AGPL-3.0

hotosm_auth-0.2.3/README.md

@@ -0,0 +1,57 @@
+# HOTOSM Auth Library - Python
+
+FastAPI/Django integration for Hanko authentication with OSM OAuth support.
+
+## Installation
+
+```bash
+pip install hotosm-auth
+```
+
+## Usage
+
+### FastAPI
+
+```python
+from fastapi import FastAPI, Depends
+from hotosm_auth.integrations.fastapi import CurrentUser
+
+app = FastAPI()
+
+@app.get("/me")
+async def get_me(user: CurrentUser):
+    return {"id": user.id, "email": user.email}
+```
+
+### Django
+
+```python
+from django.http import JsonResponse
+from hotosm_auth.integrations.django import require_auth
+
+@require_auth
+def my_view(request):
+    return JsonResponse({"user_id": request.user.id})
+```
+
+## Features
+
+- JWT validation for Hanko tokens
+- OSM OAuth 2.0 integration
+- User mapping between Hanko and application users
+- FastAPI and Django integrations
+
+## Configuration
+
+Set these environment variables:
+
+```bash
+HANKO_API_URL=https://login.hotosm.org
+OSM_CLIENT_ID=your_osm_client_id
+OSM_CLIENT_SECRET=your_osm_secret
+COOKIE_SECRET=your_secret_key
+```
+
+## License
+
+AGPL-3.0

hotosm_auth-0.2.3/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hotosm-auth"
+version = "0.2.3"
+description = "HOTOSM SSO authentication library for Hanko + OSM OAuth"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "AGPL-3.0" }
+authors = [
+    { name = "HOTOSM", email = "tech@hotosm.org" },
+]
+keywords = ["hotosm", "auth", "hanko", "osm", "oauth", "sso", "fastapi", "django"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Framework :: FastAPI",
+    "Framework :: Django",
+]
+
+dependencies = [
+    "pyjwt[crypto]>=2.8.0",
+    "httpx>=0.25.0",
+    "cryptography>=41.0.0",
+    "pydantic>=2.0.0",
+    "python-dateutil>=2.8.0",
+]
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.104.0",
+    "sqlalchemy>=2.0.0",
+]
+django = [
+    "django>=4.2.0",
+    "djangorestframework>=3.14.0",
+]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.1.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/hotosm/login"
+Documentation = "https://hotosm.github.io/auth-docs"
+Repository = "https://github.com/hotosm/login/tree/main/auth-libs/python"
+Issues = "https://github.com/hotosm/login/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hotosm_auth", "src/hotosm_auth_fastapi", "src/hotosm_auth_django"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+select = ["E", "F", "I", "N", "W"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

hotosm_auth-0.2.3/src/hotosm_auth/__init__.py

@@ -0,0 +1,87 @@
+"""
+hotosm-auth: HOTOSM SSO Authentication Library
+
+This library provides authentication for HOTOSM applications using:
+- Hanko v2.1.0 for base SSO (Google, GitHub, Email/Password)
+- OpenStreetMap OAuth 2.0 for OSM authorization
+
+Core Package Structure:
+    - hotosm_auth: Core functionality (this package)
+    - hotosm_auth_fastapi: FastAPI integration
+    - hotosm_auth_django: Django integration
+
+Quick Start (FastAPI):
+    from hotosm_auth_fastapi import setup_auth, Auth
+
+    app = FastAPI()
+    setup_auth(app)
+
+    @app.get("/me")
+    async def me(auth: Auth):
+        return {"user": auth.user.email}
+
+Quick Start (Django):
+    # settings.py
+    MIDDLEWARE = ['hotosm_auth_django.HankoAuthMiddleware']
+
+    # views.py
+    from hotosm_auth_django import login_required
+
+    @login_required
+    def my_view(request):
+        return JsonResponse({"email": request.hotosm.user.email})
+"""
+
+__version__ = "0.2.0"
+
+# Core models and configuration
+from hotosm_auth.models import HankoUser, OSMConnection, OSMScope
+from hotosm_auth.config import AuthConfig
+from hotosm_auth.exceptions import (
+    AuthenticationError,
+    TokenExpiredError,
+    TokenInvalidError,
+    CookieDecryptionError,
+    OSMOAuthError,
+)
+from hotosm_auth.jwt_validator import JWTValidator
+from hotosm_auth.crypto import CookieCrypto
+from hotosm_auth.osm_oauth import OSMOAuthClient
+from hotosm_auth.logger import get_logger, log_auth_event
+
+# Admin schemas (used by both FastAPI and Django)
+from hotosm_auth.schemas.admin import (
+    MappingResponse,
+    MappingListResponse,
+    MappingCreate,
+    MappingUpdate,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Models
+    "HankoUser",
+    "OSMConnection",
+    "OSMScope",
+    # Configuration
+    "AuthConfig",
+    # Exceptions
+    "AuthenticationError",
+    "TokenExpiredError",
+    "TokenInvalidError",
+    "CookieDecryptionError",
+    "OSMOAuthError",
+    # Core classes
+    "JWTValidator",
+    "CookieCrypto",
+    "OSMOAuthClient",
+    # Logging
+    "get_logger",
+    "log_auth_event",
+    # Admin schemas
+    "MappingResponse",
+    "MappingListResponse",
+    "MappingCreate",
+    "MappingUpdate",
+]

hotosm_auth-0.2.3/src/hotosm_auth/config.py

@@ -0,0 +1,279 @@
+"""
+Configuration for HOTOSM authentication.
+
+Apps should create one AuthConfig instance at startup with their settings.
+"""
+
+import os
+from typing import Optional
+from pydantic import BaseModel, Field, HttpUrl
+from hotosm_auth.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class AuthConfig(BaseModel):
+    """Configuration for hotosm-auth library.
+
+    Example usage:
+        config = AuthConfig(
+            hanko_api_url="https://login.hotosm.org",
+            cookie_secret="your-secret-key-32-bytes-min",
+            cookie_domain=".hotosm.org",
+            osm_enabled=True,
+        )
+    """
+
+    # Hanko configuration
+    hanko_api_url: HttpUrl = Field(
+        ...,
+        description="Hanko API URL (e.g., https://login.hotosm.org)",
+    )
+
+    # Cookie configuration
+    cookie_secret: str = Field(
+        ...,
+        min_length=32,
+        description="Secret key for encrypting OSM cookies (min 32 bytes)",
+    )
+    cookie_domain: Optional[str] = Field(
+        None,
+        description="Domain for cookies (e.g., '.hotosm.org' for all subdomains)",
+    )
+    cookie_secure: bool = Field(
+        True,
+        description="Use secure cookies (HTTPS only). Set False for local dev.",
+    )
+    cookie_samesite: str = Field(
+        "lax",
+        description="SameSite cookie policy: 'lax', 'strict', or 'none'",
+    )
+
+    # OSM OAuth configuration
+    osm_enabled: bool = Field(
+        False,
+        description="Enable OSM OAuth integration",
+    )
+    osm_client_id: Optional[str] = Field(
+        None,
+        description="OSM OAuth client ID (required if osm_enabled=True)",
+    )
+    osm_client_secret: Optional[str] = Field(
+        None,
+        description="OSM OAuth client secret (required if osm_enabled=True)",
+    )
+    osm_redirect_uri: Optional[str] = Field(
+        None,
+        description="OSM OAuth redirect URI (e.g., https://app.hotosm.org/auth/osm/callback)",
+    )
+    osm_scopes: list[str] = Field(
+        default_factory=lambda: ["read_prefs"],
+        description="Default OSM OAuth scopes to request",
+    )
+    osm_api_url: HttpUrl = Field(
+        default="https://www.openstreetmap.org",
+        description="OSM API base URL (use https://master.apis.dev.openstreetmap.org for dev)",
+    )
+
+    # JWT validation
+    jwt_audience: Optional[str] = Field(
+        None,
+        description="Expected JWT audience claim (optional)",
+    )
+    jwt_issuer: Optional[str] = Field(
+        "auto",
+        description="Expected JWT issuer claim (optional, 'auto' defaults to hanko_api_url, None skips validation)",
+    )
+
+    # JWKS caching
+    jwks_cache_ttl: int = Field(
+        3600,
+        description="JWKS cache TTL in seconds (default 1 hour)",
+    )
+
+    # Admin configuration
+    admin_emails: str = Field(
+        "",
+        description="Comma-separated list of admin email addresses",
+    )
+
+    @property
+    def admin_email_list(self) -> list[str]:
+        """Parse admin_emails into a list of lowercase email addresses."""
+        return [e.strip().lower() for e in self.admin_emails.split(",") if e.strip()]
+
+    def model_post_init(self, __context) -> None:
+        """Validate configuration after initialization."""
+        # If OSM is enabled, require client credentials
+        if self.osm_enabled:
+            if not self.osm_client_id:
+                raise ValueError("osm_client_id is required when osm_enabled=True")
+            if not self.osm_client_secret:
+                raise ValueError("osm_client_secret is required when osm_enabled=True")
+
+            # Auto-generate osm_redirect_uri if not provided
+            if not self.osm_redirect_uri:
+                # Default pattern: {HANKO_API_URL}/auth/osm/callback
+                auto_uri = f"{str(self.hanko_api_url).rstrip('/')}/auth/osm/callback"
+                logger.info(f"OSM_REDIRECT_URI not set, auto-generating: {auto_uri}")
+                logger.info("If this doesn't match your app's path, set OSM_REDIRECT_URI explicitly.")
+                object.__setattr__(self, 'osm_redirect_uri', auto_uri)
+
+        # Default JWT issuer to Hanko API URL if set to "auto"
+        # Use object.__setattr__ because model is frozen
+        if self.jwt_issuer == "auto":
+            # Strip trailing slash from HttpUrl (Pydantic adds it automatically)
+            issuer_url = str(self.hanko_api_url).rstrip('/')
+            object.__setattr__(self, 'jwt_issuer', issuer_url)
+            logger.info(f"JWT issuer set to: {issuer_url} (from hanko_api_url)")
+        elif self.jwt_issuer:
+            logger.info(f"JWT issuer explicitly set to: {self.jwt_issuer}")
+        else:
+            logger.warning("JWT issuer validation is DISABLED (jwt_issuer=None)")
+        # If None, issuer validation is skipped
+
+    @classmethod
+    def from_env(cls) -> "AuthConfig":
+        """
+        Load configuration from environment variables.
+
+        This is the recommended way to configure hotosm-auth in production.
+
+        Required environment variables:
+            HANKO_API_URL: Hanko API URL (e.g., https://login.hotosm.org)
+            COOKIE_SECRET: Secret key for encrypting cookies (min 32 bytes)
+
+        Optional environment variables:
+            COOKIE_DOMAIN: Cookie domain (e.g., ".hotosm.org")
+            COOKIE_SECURE: Use secure cookies (default: "true")
+            COOKIE_SAMESITE: SameSite policy (default: "lax")
+            JWT_AUDIENCE: Expected JWT audience
+            JWT_ISSUER: Expected JWT issuer (default: "auto")
+            OSM_CLIENT_ID: OSM OAuth client ID
+            OSM_CLIENT_SECRET: OSM OAuth client secret
+            OSM_REDIRECT_URI: OSM OAuth redirect URI (optional, auto-generated from HANKO_API_URL if not set)
+            OSM_SCOPES: Space-separated OSM scopes (default: "read_prefs")
+            OSM_API_URL: OSM API URL (default: https://www.openstreetmap.org)
+            ADMIN_EMAILS: Comma-separated list of admin email addresses
+
+        Example:
+            # .env file
+            HANKO_API_URL=https://login.hotosm.org
+            COOKIE_SECRET=your-secret-key-min-32-bytes
+            OSM_CLIENT_ID=your-osm-client-id
+            OSM_CLIENT_SECRET=your-osm-client-secret
+
+            # Python code
+            config = AuthConfig.from_env()
+
+        Returns:
+            AuthConfig: Configuration loaded from environment
+
+        Raises:
+            ValueError: If required environment variables are missing
+        """
+        # Try to load .env file from current working directory
+        try:
+            from dotenv import load_dotenv
+            import os as _os
+            # Load from current directory and walk up parent directories
+            load_dotenv(dotenv_path=_os.path.join(_os.getcwd(), '.env'), verbose=False)
+            # Also try parent directories
+            load_dotenv(verbose=False)
+        except ImportError:
+            # dotenv not installed, rely on environment variables being set
+            pass
+
+        # Required variables
+        hanko_api_url = os.getenv("HANKO_API_URL")
+        if not hanko_api_url:
+            raise ValueError(
+                "HANKO_API_URL environment variable is required. "
+                "Set it to your Hanko API URL (e.g., https://login.hotosm.org)"
+            )
+
+        cookie_secret = os.getenv("COOKIE_SECRET")
+        if not cookie_secret:
+            raise ValueError(
+                "COOKIE_SECRET environment variable is required. "
+                "Generate a secure secret with: python -c \"import secrets; print(secrets.token_urlsafe(32))\""
+            )
+
+        # Optional variables with smart defaults
+        cookie_domain = os.getenv("COOKIE_DOMAIN")
+        cookie_secure_env = os.getenv("COOKIE_SECURE")
+        cookie_samesite = os.getenv("COOKIE_SAMESITE", "lax")
+
+        # Smart default for COOKIE_DOMAIN (based on HANKO_API_URL)
+        if not cookie_domain:
+            from urllib.parse import urlparse
+            parsed = urlparse(hanko_api_url)
+            hostname = parsed.hostname or "localhost"
+
+            if hostname in ["localhost", "127.0.0.1"]:
+                cookie_domain = "localhost"
+                logger.info("COOKIE_DOMAIN not set, auto-detected: localhost")
+            else:
+                # Production: extract root domain with dot prefix
+                # e.g., "login.hotosm.org" → ".hotosm.org"
+                parts = hostname.split(".")
+                if len(parts) >= 2:
+                    cookie_domain = f".{'.'.join(parts[-2:])}"
+                    logger.info(f"COOKIE_DOMAIN not set, auto-detected: {cookie_domain}")
+                else:
+                    cookie_domain = None  # No domain restriction
+                    logger.info("COOKIE_DOMAIN not set, using no domain restriction")
+
+        # Smart default for COOKIE_SECURE (based on HANKO_API_URL scheme)
+        if cookie_secure_env is None:
+            cookie_secure = hanko_api_url.startswith("https://")
+            logger.info(f"COOKIE_SECURE not set, auto-detected: {cookie_secure} (from {hanko_api_url})")
+        else:
+            cookie_secure = cookie_secure_env.lower() == "true"
+
+        # JWT configuration
+        jwt_audience = os.getenv("JWT_AUDIENCE") or None
+        # If JWT_ISSUER is not set or empty, default to "auto"
+        # This ensures issuer validation is enabled by default
+        jwt_issuer_env = os.getenv("JWT_ISSUER")
+        if jwt_issuer_env and jwt_issuer_env.strip():
+            jwt_issuer = jwt_issuer_env
+            logger.info(f"JWT_ISSUER from env: {jwt_issuer}")
+        else:
+            jwt_issuer = "auto"  # Default to auto instead of None
+            logger.info("JWT_ISSUER not set, defaulting to 'auto'")
+
+        # OSM configuration
+        osm_client_id = os.getenv("OSM_CLIENT_ID")
+        osm_client_secret = os.getenv("OSM_CLIENT_SECRET")
+        osm_redirect_uri = os.getenv("OSM_REDIRECT_URI")
+        osm_scopes_str = os.getenv("OSM_SCOPES", "read_prefs")
+        osm_scopes = osm_scopes_str.split() if osm_scopes_str else ["read_prefs"]
+        osm_api_url = os.getenv("OSM_API_URL", "https://www.openstreetmap.org")
+
+        # Determine if OSM is enabled
+        osm_enabled = bool(osm_client_id and osm_client_secret)
+
+        # Admin configuration
+        admin_emails = os.getenv("ADMIN_EMAILS", "")
+
+        return cls(
+            hanko_api_url=hanko_api_url,
+            cookie_secret=cookie_secret,
+            cookie_domain=cookie_domain,
+            cookie_secure=cookie_secure,
+            cookie_samesite=cookie_samesite,
+            jwt_audience=jwt_audience,
+            jwt_issuer=jwt_issuer,
+            osm_enabled=osm_enabled,
+            osm_client_id=osm_client_id if osm_enabled else None,
+            osm_client_secret=osm_client_secret if osm_enabled else None,
+            osm_redirect_uri=osm_redirect_uri if osm_enabled else None,
+            osm_scopes=osm_scopes if osm_enabled else [],
+            osm_api_url=osm_api_url,
+            admin_emails=admin_emails,
+        )
+
+    class Config:
+        """Pydantic configuration."""
+        frozen = True  # Make config immutable after creation