pkg-auth 3.0.0__py3-none-any.whl

pkg_auth/integrations/django/decorators.py

@@ -0,0 +1,74 @@
+"""``@require_permission`` function decorator for Django views."""
+from __future__ import annotations
+
+import functools
+from typing import Any, Awaitable, Callable
+
+from asgiref.sync import iscoroutinefunction
+from django.http import HttpRequest, HttpResponse, JsonResponse
+
+from ...authorization import MissingPermission
+
+
+def require_permission(
+    perm: str,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator: require ``perm`` on ``request.auth_context``.
+
+    Requires ``IdentityMiddleware`` and ``AuthContextMiddleware`` to be
+    installed in ``MIDDLEWARE``. The decorator does NOT do its own JWT
+    validation — that's the middleware's job.
+
+    Returns 401 if there's no identity, 403 if the perm is missing.
+
+    Works for both sync and async views.
+
+    Example::
+
+        @require_permission("course:edit")
+        async def edit_course(request, course_id):
+            ...
+    """
+
+    def decorator(view: Callable[..., Any]) -> Callable[..., Any]:
+        if iscoroutinefunction(view):
+
+            @functools.wraps(view)
+            async def async_wrapper(
+                request: HttpRequest, *args: Any, **kwargs: Any
+            ) -> HttpResponse:
+                err = _check(request, perm)
+                if err is not None:
+                    return err
+                return await view(request, *args, **kwargs)
+
+            return async_wrapper
+
+        @functools.wraps(view)
+        def sync_wrapper(
+            request: HttpRequest, *args: Any, **kwargs: Any
+        ) -> HttpResponse:
+            err = _check(request, perm)
+            if err is not None:
+                return err
+            return view(request, *args, **kwargs)
+
+        return sync_wrapper
+
+    return decorator
+
+
+def _check(request: HttpRequest, perm: str) -> HttpResponse | None:
+    auth_ctx = getattr(request, "auth_context", None)
+    if auth_ctx is None:
+        identity = getattr(request, "identity", None)
+        if identity is None:
+            return JsonResponse({"detail": "Not authenticated"}, status=401)
+        return JsonResponse(
+            {"detail": "Missing X-Organization-Id header"}, status=400,
+        )
+    try:
+        auth_ctx.require(perm)
+    except MissingPermission as exc:
+        return JsonResponse({"detail": str(exc)}, status=403)
+    return None

pkg_auth/integrations/django/install.py

@@ -0,0 +1,136 @@
+"""Process-wide wiring of pkg_auth dependencies for Django.
+
+Django middleware can't easily inject dependencies the way FastAPI's
+``Depends`` system can, so the package wires its use cases as
+process-globals during app startup. Call ``install_pkg_auth(...)`` once
+in your Django ``AppConfig.ready()`` (or settings) to register the
+authentication façade and the use case instances; the middlewares and
+decorators read them from this module.
+
+Exactly one of ``sync_user_use_case`` / ``resolve_user_use_case`` must
+be supplied — see the ``make_get_auth_context`` FastAPI docstring for
+the Mode A vs Mode B distinction.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...authentication import AuthenticateTokenUseCase
+from ...authentication.adapters.keycloak import JWTTokenDecoder
+from ...authorization.application.use_cases.resolve_auth_context import (
+    ResolveAuthContextUseCase,
+)
+from ...authorization.application.use_cases.resolve_user_from_jwt import (
+    ResolveUserFromJwtUseCase,
+)
+from ...authorization.application.use_cases.sync_user_from_jwt import (
+    SyncUserFromJwtUseCase,
+)
+from ...authorization.domain.ports import OrganizationRepository
+
+
+@dataclass(slots=True)
+class _PkgAuthRegistry:
+    authenticate: AuthenticateTokenUseCase
+    resolve_auth: ResolveAuthContextUseCase
+    organization_repo: OrganizationRepository
+    sync_user: SyncUserFromJwtUseCase | None = None
+    resolve_user: ResolveUserFromJwtUseCase | None = None
+    cookie_name: str = "access_token"
+    header_name: str = "X-Organization-Id"
+
+
+_REGISTRY: _PkgAuthRegistry | None = None
+
+
+def install_pkg_auth(
+    *,
+    keycloak_base_url: str,
+    realm: str,
+    audience: str,
+    resolve_use_case: ResolveAuthContextUseCase,
+    organization_repo: OrganizationRepository,
+    sync_user_use_case: SyncUserFromJwtUseCase | None = None,
+    resolve_user_use_case: ResolveUserFromJwtUseCase | None = None,
+    cookie_name: str = "access_token",
+    header_name: str = "X-Organization-Id",
+) -> None:
+    """Wire pkg_auth into the Django process.
+
+    Call this exactly once at startup, e.g. from your project's
+    ``AppConfig.ready()``. Pass exactly one of ``sync_user_use_case``
+    (Mode A — source-of-truth services) or ``resolve_user_use_case``
+    (Mode B — consuming services).
+
+    Mode B (most services)::
+
+        from pkg_auth.integrations.django import install_pkg_auth
+        from pkg_auth.authorization.adapters.django_orm.repositories import (
+            DjangoUserRepository, DjangoOrganizationRepository,
+            DjangoMembershipRepository,
+        )
+        from pkg_auth.authorization.application.use_cases.resolve_user_from_jwt import ResolveUserFromJwtUseCase
+        from pkg_auth.authorization.application.use_cases.resolve_auth_context import ResolveAuthContextUseCase
+
+        install_pkg_auth(
+            keycloak_base_url="https://auth.example.com",
+            realm="itqadem",
+            audience="courses-service",
+            resolve_user_use_case=ResolveUserFromJwtUseCase(
+                user_repo=DjangoUserRepository(),
+            ),
+            resolve_use_case=ResolveAuthContextUseCase(
+                membership_repo=DjangoMembershipRepository(),
+            ),
+            organization_repo=DjangoOrganizationRepository(),
+        )
+
+    Mode A (source-of-truth services like ``itq_users``)::
+
+        from pkg_auth.authorization.application.use_cases.sync_user_from_jwt import SyncUserFromJwtUseCase
+
+        install_pkg_auth(
+            ...,
+            sync_user_use_case=SyncUserFromJwtUseCase(
+                user_repo=MyServiceUserRepository(),
+            ),
+            ...,
+        )
+
+    Platform-admin detection is a service-level concern. Cache your
+    platform org id at startup (e.g. in this same ``ready()`` hook),
+    then call :func:`pkg_auth.authorization.is_platform_context` from
+    your views to compare against ``request.auth_context.organization_id``.
+    """
+    global _REGISTRY
+
+    if (sync_user_use_case is None) == (resolve_user_use_case is None):
+        raise ValueError(
+            "install_pkg_auth: pass exactly one of "
+            "sync_user_use_case (Mode A) or resolve_user_use_case (Mode B)."
+        )
+
+    issuer = f"{keycloak_base_url}/realms/{realm}"
+    jwks_uri = f"{issuer}/protocol/openid-connect/certs"
+    decoder = JWTTokenDecoder(
+        jwks_uri=jwks_uri, issuer=issuer, audience=audience,
+    )
+    _REGISTRY = _PkgAuthRegistry(
+        authenticate=AuthenticateTokenUseCase(token_decoder=decoder),
+        resolve_auth=resolve_use_case,
+        organization_repo=organization_repo,
+        sync_user=sync_user_use_case,
+        resolve_user=resolve_user_use_case,
+        cookie_name=cookie_name,
+        header_name=header_name,
+    )
+
+
+def get_registry() -> _PkgAuthRegistry:
+    if _REGISTRY is None:
+        raise RuntimeError(
+            "pkg_auth has not been installed. "
+            "Call pkg_auth.integrations.django.install_pkg_auth(...) "
+            "from your project's AppConfig.ready()."
+        )
+    return _REGISTRY

pkg_auth/integrations/django/middleware.py

@@ -0,0 +1,63 @@
+"""IdentityMiddleware — validates JWT, attaches ``request.identity``."""
+from __future__ import annotations
+
+from typing import Awaitable, Callable
+
+from asgiref.sync import iscoroutinefunction
+from django.http import HttpRequest, HttpResponse, JsonResponse
+
+from ...authentication import (
+    AuthenticationError,
+    InvalidTokenError,
+    TokenExpiredError,
+)
+from .install import get_registry
+
+
+def _extract_token(request: HttpRequest, cookie_name: str) -> str | None:
+    auth_header = request.headers.get("Authorization")
+    if auth_header and auth_header.startswith("Bearer "):
+        token = auth_header.removeprefix("Bearer ").strip()
+        if token:
+            return token
+    cookie_token = request.COOKIES.get(cookie_name)
+    if cookie_token:
+        return cookie_token
+    return None
+
+
+class IdentityMiddleware:
+    """Lazy JWT validation. Attaches ``request.identity`` (or ``None``).
+
+    On routes that don't require auth, this middleware is a no-op when
+    no token is present (``request.identity = None``). On routes that
+    DO require auth, the route's decorator / dependency raises 401
+    when ``request.identity`` is ``None``.
+
+    Token validation errors are NOT raised here — they set
+    ``request.identity = None`` and let the auth decorator decide. This
+    keeps the middleware out of the response path for anonymous routes.
+    """
+
+    sync_capable = True
+    async_capable = True
+
+    def __init__(
+        self,
+        get_response: Callable[
+            [HttpRequest], HttpResponse | Awaitable[HttpResponse]
+        ],
+    ) -> None:
+        self.get_response = get_response
+        self._async = iscoroutinefunction(get_response)
+
+    def __call__(self, request: HttpRequest) -> HttpResponse | Awaitable[HttpResponse]:
+        registry = get_registry()
+        token = _extract_token(request, registry.cookie_name)
+        request.identity = None  # type: ignore[attr-defined]
+        if token is not None:
+            try:
+                request.identity = registry.authenticate.execute(token)  # type: ignore[attr-defined]
+            except (TokenExpiredError, InvalidTokenError, AuthenticationError):
+                request.identity = None  # type: ignore[attr-defined]
+        return self.get_response(request)

pkg_auth/integrations/fastapi/__init__.py

@@ -0,0 +1,26 @@
+"""FastAPI integration for pkg_auth (identity + ACL)."""
+from __future__ import annotations
+
+try:
+    import fastapi  # noqa: F401
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "pkg_auth.integrations.fastapi requires fastapi. "
+        "Install with: pip install pkg-auth[fastapi]"
+    ) from exc
+
+from .auth_factory import Authentication, create_authentication
+from .auth_context_dep import make_get_auth_context
+from .decorators import require_permission
+from .errors import install_exception_handlers
+from .identity_dep import bearer_scheme, extract_token_from_request
+
+__all__ = [
+    "Authentication",
+    "create_authentication",
+    "make_get_auth_context",
+    "require_permission",
+    "install_exception_handlers",
+    "bearer_scheme",
+    "extract_token_from_request",
+]

pkg_auth/integrations/fastapi/auth_context_dep.py

@@ -0,0 +1,150 @@
+"""``make_get_auth_context`` factory.
+
+Composes ``Authentication.get_identity`` (from the authentication
+module) with the authorization layer's ``ResolveAuthContextUseCase``,
+either ``SyncUserFromJwtUseCase`` (Mode A — writer) or
+``ResolveUserFromJwtUseCase`` (Mode B — reader), and
+``OrganizationRepository`` to produce a single FastAPI dependency that
+returns ``(IdentityContext, AuthContext)``.
+
+Exactly one of ``sync_user_use_case`` / ``resolve_user_use_case`` must
+be supplied:
+
+- **Mode A** (source-of-truth, extends the ACL schema): pass
+  ``sync_user_use_case=...`` — the dep will upsert the local user row
+  from JWT claims on every request.
+- **Mode B** (consumer, ACL DB is owned by a Mode A peer): pass
+  ``resolve_user_use_case=...`` — the dep will read-through and raise
+  ``UserNotProvisioned`` (→ HTTP 403) if the source-of-truth hasn't
+  mirrored the user yet.
+
+pkg_auth deliberately does NOT bake in a "platform admin fallback"
+here. Platform-admin detection is a *service-level* policy: services
+that want it call :func:`pkg_auth.authorization.is_platform_context`
+inside handlers, comparing the request's ``AuthContext.organization_id``
+against their own cached platform org id. Services that need
+elevated-privilege fallbacks (resolving the caller against a platform
+org when they aren't a member of the requested org) wrap this factory
+in their own dependency. See ``docs/FastAPI.md`` for the canonical
+pattern.
+"""
+from __future__ import annotations
+
+from typing import Awaitable, Callable
+from uuid import UUID
+
+from fastapi import Depends, HTTPException, Request, status
+
+from ...authentication import IdentityContext
+from ...authorization import (
+    AuthContext,
+    NotAMember,
+    OrgId,
+    UnknownOrganization,
+    UserNotProvisioned,
+)
+from ...authorization.application.use_cases.resolve_auth_context import (
+    ResolveAuthContextUseCase,
+)
+from ...authorization.application.use_cases.resolve_user_from_jwt import (
+    ResolveUserFromJwtUseCase,
+)
+from ...authorization.application.use_cases.sync_user_from_jwt import (
+    SyncUserFromJwtUseCase,
+)
+from ...authorization.domain.entities import User
+from ...authorization.domain.ports import OrganizationRepository
+
+DEFAULT_HEADER_NAME = "X-Organization-Id"
+
+
+def make_get_auth_context(
+    *,
+    get_identity: Callable[..., Awaitable[IdentityContext]],
+    resolve_use_case: ResolveAuthContextUseCase,
+    organization_repo: OrganizationRepository,
+    sync_user_use_case: SyncUserFromJwtUseCase | None = None,
+    resolve_user_use_case: ResolveUserFromJwtUseCase | None = None,
+    header_name: str = DEFAULT_HEADER_NAME,
+) -> Callable[..., Awaitable[tuple[IdentityContext, AuthContext]]]:
+    """Build a FastAPI dependency returning ``(IdentityContext, AuthContext)``.
+
+    Exactly one of ``sync_user_use_case`` or ``resolve_user_use_case``
+    must be supplied. See the module docstring for when to use each.
+
+    The dependency:
+        1. Resolves identity via the injected ``get_identity``.
+        2. Either lazily upserts the local user row from JWT claims
+           (Mode A) or reads it through and 403s if missing (Mode B).
+        3. Reads ``header_name`` from the request and parses it as a
+           UUID first, falling back to a slug lookup.
+        4. Resolves the user's auth context for that organization.
+
+    Errors map to:
+        - missing header                → 400
+        - unknown organization          → 404
+        - user not a member             → 403
+        - user not provisioned (Mode B) → 403
+    """
+    if (sync_user_use_case is None) == (resolve_user_use_case is None):
+        raise ValueError(
+            "make_get_auth_context: pass exactly one of "
+            "sync_user_use_case (Mode A) or resolve_user_use_case (Mode B)."
+        )
+
+    async def dependency(
+        request: Request,
+        identity: IdentityContext = Depends(get_identity),
+    ) -> tuple[IdentityContext, AuthContext]:
+        raw = request.headers.get(header_name)
+        if not raw:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Missing {header_name} header",
+            )
+
+        user: User
+        try:
+            if sync_user_use_case is not None:
+                user = await sync_user_use_case.execute(
+                    sub=identity.subject_str,
+                    email=identity.email_str or "",
+                    full_name=identity.full_name,
+                )
+            else:
+                assert resolve_user_use_case is not None
+                user = await resolve_user_use_case.execute(
+                    sub=identity.subject_str,
+                )
+        except UserNotProvisioned as exc:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=str(exc),
+            ) from exc
+
+        try:
+            org = await organization_repo.get(OrgId(UUID(raw)))
+        except (ValueError, AttributeError):
+            org = await organization_repo.get_by_slug(raw)
+        if org is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Organization {raw!r} not found",
+            )
+
+        try:
+            auth_ctx = await resolve_use_case.execute(user.id, org.id)
+        except NotAMember as exc:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=str(exc),
+            ) from exc
+        except UnknownOrganization as exc:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=str(exc),
+            ) from exc
+
+        return identity, auth_ctx
+
+    return dependency

pkg_auth/integrations/fastapi/auth_factory.py

@@ -0,0 +1,84 @@
+"""Authentication façade and factory for FastAPI services."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.security import HTTPAuthorizationCredentials
+
+from ...authentication import (
+    AuthenticateTokenUseCase,
+    AuthenticationError,
+    IdentityContext,
+    InvalidTokenError,
+    TokenExpiredError,
+)
+from ...authentication.adapters.keycloak import JWTTokenDecoder
+from .identity_dep import (
+    DEFAULT_COOKIE_NAME,
+    bearer_scheme,
+    extract_token_from_request,
+)
+
+
+@dataclass(slots=True)
+class Authentication:
+    """FastAPI-side façade over the pure ``AuthenticateTokenUseCase``.
+
+    Exposes a single dependency, :meth:`get_identity`, which validates
+    a JWT and returns an :class:`IdentityContext`. **Authorization is
+    handled separately** via the auth_context dependency from the
+    authorization module — this façade does identity only.
+    """
+
+    use_case: AuthenticateTokenUseCase
+    cookie_name: str = DEFAULT_COOKIE_NAME
+
+    async def get_identity(
+        self,
+        request: Request,
+        credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme),
+    ) -> IdentityContext:
+        """Dependency: require a valid Keycloak token, return ``IdentityContext``."""
+        try:
+            token = extract_token_from_request(
+                request, credentials, cookie_name=self.cookie_name,
+            )
+            return self.use_case.execute(token)
+        except TokenExpiredError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Token expired",
+            ) from exc
+        except (InvalidTokenError, AuthenticationError) as exc:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail=str(exc),
+            ) from exc
+
+
+def create_authentication(
+    *,
+    keycloak_base_url: str,
+    realm: str,
+    audience: str,
+    cookie_name: str = DEFAULT_COOKIE_NAME,
+) -> Authentication:
+    """High-level helper: build an :class:`Authentication` from Keycloak config.
+
+    The ``audience`` is the Keycloak client ID this service expects in
+    the ``aud`` claim. There is no longer a separate ``client_id``
+    parameter because authorization no longer reads claims —
+    authorization comes from the ACL database via the authorization
+    module.
+    """
+    issuer = f"{keycloak_base_url}/realms/{realm}"
+    jwks_uri = f"{issuer}/protocol/openid-connect/certs"
+
+    decoder = JWTTokenDecoder(
+        jwks_uri=jwks_uri,
+        issuer=issuer,
+        audience=audience,
+    )
+    use_case = AuthenticateTokenUseCase(token_decoder=decoder)
+    return Authentication(use_case=use_case, cookie_name=cookie_name)

pkg_auth/integrations/fastapi/decorators.py

@@ -0,0 +1,55 @@
+"""``require_permission`` Depends-wrapper for FastAPI routes."""
+from __future__ import annotations
+
+from typing import Awaitable, Callable
+
+from fastapi import Depends, HTTPException, status
+
+from ...authentication import IdentityContext
+from ...authorization import AuthContext, MissingPermission
+
+
+def require_permission(
+    perm: str,
+    *,
+    get_auth_context: Callable[
+        ..., Awaitable[tuple[IdentityContext, AuthContext]]
+    ],
+) -> Callable[..., Awaitable[tuple[IdentityContext, AuthContext]]]:
+    """Build a FastAPI dependency that enforces a single permission.
+
+    Usage on a single handler::
+
+        @router.post("/courses/{id}/publish")
+        async def publish(
+            id: str,
+            bundle = Depends(require_permission(
+                "course:publish", get_auth_context=get_auth_context,
+            )),
+        ): ...
+
+    Or as a route-level dependency (no kwarg in the handler signature)::
+
+        @router.post(
+            "/courses/{id}/publish",
+            dependencies=[Depends(require_permission(
+                "course:publish", get_auth_context=get_auth_context,
+            ))],
+        )
+        async def publish(id: str): ...
+    """
+
+    async def dependency(
+        bundle: tuple[IdentityContext, AuthContext] = Depends(get_auth_context),
+    ) -> tuple[IdentityContext, AuthContext]:
+        _, auth_ctx = bundle
+        try:
+            auth_ctx.require(perm)
+        except MissingPermission as exc:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=str(exc),
+            ) from exc
+        return bundle
+
+    return dependency

pkg_auth/integrations/fastapi/errors.py

@@ -0,0 +1,72 @@
+"""App-wide exception handlers for pkg_auth domain errors."""
+from __future__ import annotations
+
+from fastapi import FastAPI, Request, status
+from fastapi.responses import JSONResponse
+
+from ...authentication import (
+    AuthenticationError,
+    InvalidTokenError,
+    TokenExpiredError,
+)
+from ...authorization import (
+    AuthorizationError,
+    MissingPermission,
+    NotAMember,
+    UnknownOrganization,
+    UnknownPermission,
+    UnknownRole,
+    UnknownUser,
+)
+
+
+def install_exception_handlers(app: FastAPI) -> None:
+    """Register catch-all handlers for pkg_auth domain exceptions.
+
+    Mappings:
+        TokenExpiredError       → 401
+        InvalidTokenError       → 401
+        AuthenticationError     → 401
+        NotAMember              → 403
+        MissingPermission       → 403
+        AuthorizationError      → 403 (catch-all for the hierarchy)
+        UnknownOrganization     → 404
+        UnknownUser             → 404
+        UnknownRole             → 404
+        UnknownPermission       → 404
+
+    Services that prefer per-route ``try/except`` can simply not call
+    this. The deps and decorators in this package raise ``HTTPException``
+    directly so they work either way.
+    """
+
+    async def _401(_request: Request, exc: Exception) -> JSONResponse:
+        return JSONResponse(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            content={"detail": str(exc)},
+        )
+
+    async def _403(_request: Request, exc: Exception) -> JSONResponse:
+        return JSONResponse(
+            status_code=status.HTTP_403_FORBIDDEN,
+            content={"detail": str(exc)},
+        )
+
+    async def _404(_request: Request, exc: Exception) -> JSONResponse:
+        return JSONResponse(
+            status_code=status.HTTP_404_NOT_FOUND,
+            content={"detail": str(exc)},
+        )
+
+    app.add_exception_handler(TokenExpiredError, _401)
+    app.add_exception_handler(InvalidTokenError, _401)
+    app.add_exception_handler(AuthenticationError, _401)
+
+    app.add_exception_handler(NotAMember, _403)
+    app.add_exception_handler(MissingPermission, _403)
+    app.add_exception_handler(AuthorizationError, _403)
+
+    app.add_exception_handler(UnknownOrganization, _404)
+    app.add_exception_handler(UnknownUser, _404)
+    app.add_exception_handler(UnknownRole, _404)
+    app.add_exception_handler(UnknownPermission, _404)