altissimo-auth 1.1.0__py3-none-any.whl

altissimo/auth/__init__.py

@@ -0,0 +1,43 @@
+"""Altissimo Auth — reusable, framework-agnostic authentication library."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .core.exceptions import (
+    AuthError,
+    AuthForbiddenError,
+    AuthNotFoundError,
+    AuthUnauthorizedError,
+    GoogleTokenVerificationError,
+)
+from .core.models import (
+    APIKeyRecord,
+    AuthReasonCode,
+    AuthSource,
+    FirebaseUser,
+    GoogleTokenInfo,
+    GoogleUser,
+    IAPIdentity,
+)
+
+try:
+    __version__ = version("altissimo-auth")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = [
+    "APIKeyRecord",
+    "AuthError",
+    "AuthForbiddenError",
+    "AuthNotFoundError",
+    "AuthReasonCode",
+    "AuthSource",
+    "AuthUnauthorizedError",
+    "FirebaseUser",
+    "GoogleTokenInfo",
+    "GoogleTokenVerificationError",
+    "GoogleUser",
+    "IAPIdentity",
+    "__version__",
+]

altissimo/auth/cascade.py

@@ -0,0 +1,43 @@
+"""Auth Cascade — multi-method fallback for Django Ninja."""
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class AuthCascade:
+    """Try multiple auth methods sequentially, returning the first success.
+
+    This is useful for endpoints that accept multiple forms of authentication
+    (e.g., Firebase ID token, Google OAuth2 token, or API key) and need to
+    return the specific model for whichever method succeeded.
+
+    Usage with Django Ninja:
+        cascade = AuthCascade([
+            FirebaseAuth(),
+            GoogleAuth(),
+        ])
+
+        @api.get("/info", auth=cascade)
+        def info(request):
+            user = request.auth
+            ...
+    """
+
+    def __init__(self, auth_methods: list[Callable]) -> None:
+        """Initialize with a list of callable auth methods."""
+        self.auth_methods = auth_methods
+
+    def __call__(self, request: Any) -> Any | None:
+        """Try each method in sequence. Return the first non-None result."""
+        for method in self.auth_methods:
+            try:
+                result = method(request)
+                if result is not None:
+                    return result
+            except Exception as e:
+                logger.debug("AuthCascade method %s failed: %s", method.__class__.__name__, e)
+                continue
+        return None

altissimo/auth/core/__init__.py

@@ -0,0 +1 @@
+"""Core auth models, exceptions, and utilities."""

altissimo/auth/core/exceptions.py

@@ -0,0 +1,36 @@
+"""Auth exceptions.
+
+All exceptions carry a machine-readable `reason_code` that adapters can use
+for telemetry and structured error responses.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import AuthReasonCode
+
+
+class AuthError(Exception):
+    """Base auth exception."""
+
+    def __init__(self, message: str, *, reason_code: AuthReasonCode) -> None:
+        super().__init__(message)
+        self.reason_code = reason_code
+
+
+class AuthUnauthorizedError(AuthError):
+    """Authentication failure (HTTP 401)."""
+
+
+class AuthForbiddenError(AuthError):
+    """Authorization failure (HTTP 403)."""
+
+
+class AuthNotFoundError(AuthError):
+    """Authenticated subject cannot be mapped (HTTP 404)."""
+
+
+class GoogleTokenVerificationError(Exception):
+    """Raised when Google OAuth2 token verification fails."""

altissimo/auth/core/models.py

@@ -0,0 +1,146 @@
+"""Auth models.
+
+Framework-agnostic Pydantic models shared across all auth providers and adapters.
+"""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, field_validator
+
+
+class AuthSource(StrEnum):
+    """Supported auth sources."""
+
+    API_KEY = "api_key"
+    FIREBASE = "firebase"
+    GOOGLE = "google"
+    IAP = "iap"
+    SERVICE_ACCOUNT = "service_account"
+    WEBHOOK = "webhook"
+    JWT = "jwt"
+
+
+class AuthReasonCode(StrEnum):
+    """Stable reason codes for auth decisions."""
+
+    OK = "ok"
+
+    # API key
+    MISSING_API_KEY = "missing_api_key"
+    INVALID_API_KEY = "invalid_api_key"
+
+    # Google OAuth2
+    INVALID_GOOGLE_TOKEN = "invalid_google_token"
+
+    # Firebase
+    INVALID_FIREBASE_TOKEN = "invalid_firebase_token"
+    EXPIRED_FIREBASE_TOKEN = "expired_firebase_token"
+    USER_DISABLED = "user_disabled"
+
+    # Authorization
+    NOT_ADMIN = "not_admin"
+    INSUFFICIENT_CLAIMS = "insufficient_claims"
+
+    # OIDC service account
+    INVALID_OIDC_TOKEN = "invalid_oidc_token"
+    UNAUTHORIZED_CALLER = "unauthorized_caller"
+    AUTH_SERVICE_UNAVAILABLE = "auth_service_unavailable"
+
+    # Webhooks
+    INVALID_WEBHOOK_SIGNATURE = "invalid_webhook_signature"
+    INVALID_WEBHOOK_PAYLOAD = "invalid_webhook_payload"
+
+    # JWT
+    INVALID_JWT = "invalid_jwt"
+    EXPIRED_JWT = "expired_jwt"
+    INVALID_JWT_ISSUER = "invalid_jwt_issuer"
+
+
+class GoogleTokenInfo(BaseModel):
+    """Google OAuth2 ID token payload."""
+
+    iss: str
+    azp: str
+    aud: str
+    sub: str
+    hd: str | None = None
+    email: EmailStr
+    email_verified: bool
+    at_hash: str | None = None
+    nbf: datetime | None = None
+    iat: datetime
+    exp: datetime
+    jlt: str | None = None
+    alg: str | None = None
+    kid: str | None = None
+    typ: str | None = None
+
+    model_config = ConfigDict(extra="allow")
+
+    @field_validator("email", mode="before")
+    @classmethod
+    def lowercase_email(cls, value: Any) -> Any:
+        """Normalize email casing."""
+        return value.lower() if isinstance(value, str) else value
+
+
+class GoogleUser(BaseModel):
+    """Authenticated Google API user."""
+
+    id: str
+    email: EmailStr
+    hd: str | None = None
+    admin: bool = False
+
+    model_config = ConfigDict(extra="allow")
+
+    @field_validator("email", mode="before")
+    @classmethod
+    def lowercase_email(cls, value: Any) -> Any:
+        """Normalize email casing."""
+        return value.lower() if isinstance(value, str) else value
+
+
+class IAPIdentity(BaseModel):
+    """Identity extracted from Google IAP headers."""
+
+    email: str | None = None
+    user_id: str | None = None
+
+
+class FirebaseUser(BaseModel):
+    """Firebase user record.
+
+    Pydantic representation of a firebase_admin UserRecord, decoupled from
+    the firebase-admin SDK so consumers don't need to depend on it directly.
+    """
+
+    uid: str
+    email: str | None = None
+    email_verified: bool = False
+    disabled: bool = False
+    display_name: str | None = None
+    phone_number: str | None = None
+    photo_url: str | None = None
+    provider_id: str | None = None
+    tenant_id: str | None = None
+    tokens_valid_after_timestamp: int | str | None = None
+    custom_claims: dict[str, Any] | None = None
+    provider_data: list[dict[str, Any]] = Field(default_factory=list)
+
+    model_config = ConfigDict(extra="allow")
+
+
+class APIKeyRecord(BaseModel):
+    """Represents a validated API key.
+
+    Consumers should subclass or wrap this model to add project-specific fields
+    (e.g. scopes, rate limits, owner references).
+    """
+
+    id: str
+    """The API key identifier."""
+
+    model_config = ConfigDict(extra="allow")

altissimo/auth/core/policies.py

@@ -0,0 +1,46 @@
+"""Authorization policy checks.
+
+Stateless helpers that raise `AuthForbiddenError` when a principal does
+not satisfy the required authorization level.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .exceptions import AuthForbiddenError, AuthUnauthorizedError
+from .models import AuthReasonCode, FirebaseUser, GoogleUser
+
+
+class AuthPolicyService:
+    """Authorization policy checks."""
+
+    @staticmethod
+    def require_google_admin(user: GoogleUser) -> GoogleUser:
+        """Require Google user to be admin."""
+        if not user.admin:
+            raise AuthForbiddenError("Forbidden", reason_code=AuthReasonCode.NOT_ADMIN)
+        return user
+
+    @staticmethod
+    def require_firebase_admin(user: FirebaseUser) -> FirebaseUser:
+        """Require Firebase user to have admin custom claim."""
+        if not (user.custom_claims and user.custom_claims.get("admin")):
+            raise AuthForbiddenError("Forbidden", reason_code=AuthReasonCode.NOT_ADMIN)
+        return user
+
+    @staticmethod
+    def require_api_key_or_user(api_key_present: bool, user_present: bool) -> None:
+        """Require either API key or authenticated user."""
+        if not api_key_present and not user_present:
+            raise AuthUnauthorizedError(
+                "API Key or authenticated user required",
+                reason_code=AuthReasonCode.MISSING_API_KEY,
+            )
+
+    @staticmethod
+    def require_claim(user: FirebaseUser, claim: str, expected: Any = True) -> FirebaseUser:
+        """Require Firebase user to have a specific custom claim value."""
+        if not user.custom_claims or user.custom_claims.get(claim) != expected:
+            raise AuthForbiddenError("Forbidden", reason_code=AuthReasonCode.INSUFFICIENT_CLAIMS)
+        return user

altissimo/auth/core/telemetry.py

@@ -0,0 +1,42 @@
+"""Structured auth event logging.
+
+Provides a single `log_auth_event` helper that emits structured JSON log
+entries.  Consumers can replace the logger or add handlers as needed.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from .models import AuthReasonCode
+
+logger = logging.getLogger("altissimo.auth")
+
+
+def log_auth_event(
+    *,
+    event: str,
+    auth_source: str,
+    route: str,
+    method: str,
+    status_code: int,
+    reason_code: AuthReasonCode | str,
+    principal_id: str | None = None,
+) -> None:
+    """Emit a structured auth log event."""
+    normalized = reason_code.value if isinstance(reason_code, AuthReasonCode) else reason_code
+    logger.info(
+        "auth event: %s",
+        event,
+        extra={
+            "json_fields": {
+                "event": event,
+                "auth_source": auth_source,
+                "route": route,
+                "method": method,
+                "status_code": status_code,
+                "reason_code": normalized,
+                "principal_id": principal_id,
+            }
+        },
+    )