pkg-auth 3.0.0__py3-none-any.whl

pkg_auth/authorization/domain/exceptions.py

@@ -0,0 +1,68 @@
+"""Authorization (ACL) exceptions.
+
+These are deliberately a *separate* hierarchy from
+``pkg_auth.authentication.domain.exceptions``: authentication failures
+are 401, authorization failures are 403/404. Integration layers map
+each to the right HTTP status.
+"""
+from __future__ import annotations
+
+
+class AuthorizationError(Exception):
+    """Base for all authorization (ACL) failures."""
+
+
+class NotAMember(AuthorizationError):
+    """The user has no membership in the requested organization."""
+
+
+class MissingPermission(AuthorizationError):
+    """The user's role in the organization does not include the required permission."""
+
+
+class UnknownOrganization(AuthorizationError):
+    """The referenced organization does not exist."""
+
+
+class UnknownUser(AuthorizationError):
+    """The referenced user does not exist."""
+
+
+class UserNotProvisioned(AuthorizationError):
+    """JWT-authenticated user has no row in the local ACL ``users`` table.
+
+    Raised by :class:`ResolveUserFromJwtUseCase` in Mode B (consuming)
+    services: the caller is a valid Keycloak principal, but the
+    source-of-truth service (Mode A) hasn't mirrored them into the
+    shared ACL yet. Integration layers map this to HTTP 403.
+    """
+
+
+class UnknownRole(AuthorizationError):
+    """The referenced role does not exist."""
+
+
+class UnknownPermission(AuthorizationError):
+    """A referenced permission key is not registered in the catalog."""
+
+
+class PermissionVisibilityConflict(AuthorizationError):
+    """A role tried to use a permission whose visibility forbids it.
+
+    Raised when a platform-org role references a ``tenant_only`` permission,
+    or a normal-org role references a ``platform_only`` permission.
+    """
+
+
+class UnknownService(AuthorizationError):
+    """The referenced service is not registered in the ``services`` table."""
+
+
+class ServiceNotSaaSAvailable(AuthorizationError):
+    """A platform admin tried to enable a service the vendor has not marked
+    ``saas_available``. Integration layers map this to HTTP 403.
+    """
+
+
+class ServiceNotEnabled(AuthorizationError):
+    """The organization does not have the required service enabled."""

pkg_auth/authorization/domain/ports.py

@@ -0,0 +1,217 @@
+"""Authorization domain ports (Protocol-based repositories).
+
+These Protocols are the contract between the application layer and the
+adapter layer. Adapters live under ``pkg_auth.authorization.adapters``
+(SQLAlchemy, Django ORM, cache decorator). The application layer imports
+only from this module; it must not import any concrete adapter.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterable, Literal, Protocol, Sequence
+
+from .entities import (
+    AuthContext,
+    Membership,
+    Organization,
+    OrganizationService,
+    Permission,
+    Role,
+    Service,
+    User,
+)
+from .value_objects import (
+    OrgId,
+    PermissionKey,
+    RoleId,
+    RoleName,
+    ServiceName,
+    UserId,
+)
+
+if TYPE_CHECKING:
+    from ..application.use_cases.register_permission_catalog import (
+        CatalogEntry,
+    )
+    from ..application.use_cases.sync_service_catalog import ServiceSpec
+
+# Role-builder visibility filter:
+#   - "platform"      → platform_only ∪ shared (what a platform-org role may use)
+#   - "tenant"/"org"  → shared ∪ tenant_only  (what a normal-org role may use)
+#   - "all"           → no filter
+# "org" is kept as a backward-compatible alias for "tenant".
+PermissionScope = Literal["org", "tenant", "platform", "all"]
+
+
+class UserRepository(Protocol):
+    """Read/write access to the ``users`` table.
+
+    The package lazily upserts users on first JWT sight via
+    :meth:`upsert_from_identity`; explicit creation is not exposed.
+    """
+
+    async def get_by_id(self, user_id: UserId) -> User | None: ...
+    async def get_by_keycloak_sub(self, sub: str) -> User | None: ...
+    async def upsert_from_identity(
+        self,
+        *,
+        sub: str,
+        email: str,
+        full_name: str | None,
+    ) -> User: ...
+
+
+class OrganizationRepository(Protocol):
+    """Read/write access to the ``organizations`` table."""
+
+    async def get(self, org_id: OrgId) -> Organization | None: ...
+    async def get_by_slug(self, slug: str) -> Organization | None: ...
+    async def create(self, *, slug: str, name: str) -> Organization: ...
+    async def update(
+        self, org_id: OrgId, *, name: str | None
+    ) -> Organization: ...
+    async def delete(self, org_id: OrgId) -> None: ...
+    async def list_for_user(self, user_id: UserId) -> list[Organization]: ...
+
+
+class RoleRepository(Protocol):
+    """Read/write access to the ``roles`` table (and the ``role_permissions`` join)."""
+
+    async def get(self, role_id: RoleId) -> Role | None: ...
+    async def get_by_name(
+        self, org_id: OrgId | None, name: RoleName
+    ) -> Role | None: ...
+    async def create(
+        self,
+        *,
+        org_id: OrgId | None,
+        name: RoleName,
+        description: str | None,
+        permission_keys: Sequence[PermissionKey],
+    ) -> Role: ...
+    async def update(
+        self,
+        role_id: RoleId,
+        *,
+        name: RoleName | None,
+        description: str | None,
+        permission_keys: Sequence[PermissionKey] | None,
+    ) -> Role: ...
+    async def delete(self, role_id: RoleId) -> None: ...
+
+
+class MembershipRepository(Protocol):
+    """Read/write access to the ``memberships`` table.
+
+    The hot path is :meth:`load_auth_context`, which the FastAPI / Django /
+    Strawberry deps call on every protected request. SQLAlchemy / Django
+    implementations should do this in one query (joined with the role and
+    its permissions) so the call site never round-trips for individual
+    perms.
+    """
+
+    async def get(
+        self, user_id: UserId, org_id: OrgId
+    ) -> Membership | None: ...
+    async def upsert(
+        self,
+        *,
+        user_id: UserId,
+        org_id: OrgId,
+        role_id: RoleId,
+        status: str,
+    ) -> Membership: ...
+    async def delete(self, user_id: UserId, org_id: OrgId) -> None: ...
+    async def load_auth_context(
+        self, user_id: UserId, org_id: OrgId
+    ) -> AuthContext | None: ...
+    async def list_for_user(self, user_id: UserId) -> list[Membership]: ...
+
+
+class PermissionCatalogRepository(Protocol):
+    """Read/write access to the ``permissions`` table (the global perm catalog).
+
+    The ``scope`` argument on the list methods filters by each row's
+    ``visibility``:
+
+    - ``"platform"``     → platform_only ∪ shared
+    - ``"tenant"``/``"org"`` → shared ∪ tenant_only
+    - ``"all"``          → no filter (default)
+    """
+
+    async def register_many(
+        self,
+        *,
+        service_name: str,
+        entries: Sequence["CatalogEntry"],
+    ) -> None: ...
+    async def list_all(
+        self, *, scope: PermissionScope = "all"
+    ) -> list[Permission]: ...
+    async def list_for_service(
+        self, service_name: str, *, scope: PermissionScope = "all"
+    ) -> list[Permission]: ...
+    async def get_service_map(self) -> dict[str, str]:
+        """Return a ``{permission_key: service_name}`` map for the whole
+        catalog. Used by the service guard in
+        :class:`ResolveAuthContextUseCase` to map a user's perm keys to the
+        services that own them. Small and slow-changing → cacheable.
+        """
+        ...
+    async def prune_absent(
+        self,
+        *,
+        service_name: str,
+        keep_keys: Iterable[PermissionKey],
+    ) -> int:
+        """Delete permissions owned by ``service_name`` whose key is NOT in
+        ``keep_keys``. Returns the number of rows deleted.
+
+        If ``keep_keys`` is empty, every row for ``service_name`` is deleted.
+        The FK ``role_permissions.permission_id`` is ``ON DELETE CASCADE``, so
+        role assignments referencing the pruned rows are silently dropped.
+        """
+        ...
+
+
+class ServiceRepository(Protocol):
+    """Read/write access to the ``services`` table (the service registry).
+
+    Vendor-controlled flags (``auto_provision``, ``saas_available``) are
+    written only via :meth:`upsert_many` (the ``pkg-auth-sync-services``
+    path). :meth:`ensure_exists` is called during permission-catalog
+    registration to create a bare row with safe defaults so the
+    default-deny guard does not strip a newly-registered service's perms
+    before the vendor configures it; it must NOT overwrite existing flags.
+    """
+
+    async def upsert_many(self, services: Sequence["ServiceSpec"]) -> None: ...
+    async def ensure_exists(self, *, service_name: str) -> None: ...
+    async def get(self, name: ServiceName) -> Service | None: ...
+    async def list_all(self) -> list[Service]: ...
+    async def prune_absent(
+        self, *, keep: Iterable[ServiceName]
+    ) -> int: ...
+
+
+class OrganizationServiceRepository(Protocol):
+    """Read/write access to the ``organization_services`` table (per-org
+    service entitlements that drive the service guard).
+    """
+
+    async def list_enabled_service_names(self, org_id: OrgId) -> set[str]: ...
+    async def get(
+        self, org_id: OrgId, service_name: ServiceName
+    ) -> OrganizationService | None: ...
+    async def enable(
+        self, org_id: OrgId, service_name: ServiceName, *, source: str
+    ) -> OrganizationService: ...
+    async def disable(
+        self, org_id: OrgId, service_name: ServiceName
+    ) -> None: ...
+    async def bulk_enable(
+        self,
+        org_id: OrgId,
+        service_names: Sequence[ServiceName],
+        *,
+        source: str,
+    ) -> None: ...

pkg_auth/authorization/domain/value_objects.py

@@ -0,0 +1,208 @@
+"""Authorization value objects (typed wrappers around DB IDs and string keys)."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from typing import Mapping
+from uuid import UUID
+
+# A service name / slug: lowercase letter first, then lowercase letters,
+# digits, ``_`` or ``-``. Matches the shape of the ``service_name`` strings
+# already stamped on permissions (e.g. ``"courses"``, ``"media-library"``).
+_SERVICE_NAME_PATTERN = re.compile(r"^[a-z][a-z0-9_-]*$")
+
+# Format:
+#   - one or more colon-separated segments
+#   - each segment must start with a lowercase letter
+#   - each segment may contain lowercase letters, digits, ``_``, ``-``
+#   - at least one colon (so single bare words like ``"admin"`` are rejected)
+#
+# Examples (valid):   "course:edit", "media-library:upload", "billing:invoice:refund"
+# Examples (invalid): "admin", "Course:edit", ":x", "x:", "1course:edit"
+_PERMISSION_KEY_PATTERN = re.compile(
+    r"^[a-z][a-z0-9_-]*(?::[a-z][a-z0-9_-]*)+$"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class UserId:
+    """Primary key of a row in the users table (UUID)."""
+
+    value: UUID
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+
+@dataclass(frozen=True, slots=True)
+class OrgId:
+    """Primary key of a row in the organizations table (UUID)."""
+
+    value: UUID
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+
+@dataclass(frozen=True, slots=True)
+class RoleId:
+    """Primary key of a row in the roles table (UUID)."""
+
+    value: UUID
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+
+@dataclass(frozen=True, slots=True)
+class PermissionId:
+    """Primary key of a row in the permissions table (UUID)."""
+
+    value: UUID
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+
+@dataclass(frozen=True, slots=True)
+class RoleName:
+    """Human-readable role name. Unique per ``(organization_id, name)``."""
+
+    value: str
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class PermissionKey:
+    """A permission key like ``"course:edit"`` or ``"billing:invoice:refund"``.
+
+    Format (validated in ``__post_init__``):
+
+        - one or more colon-separated segments
+        - each segment must start with a lowercase letter
+        - each segment may contain lowercase letters, digits, ``_``, ``-``
+        - at least one colon (so single bare words like ``"admin"`` are
+          rejected — they don't carry resource context)
+
+    Raises:
+        ValueError: when the value does not match the format.
+    """
+
+    value: str
+
+    def __post_init__(self) -> None:
+        if not _PERMISSION_KEY_PATTERN.match(self.value):
+            raise ValueError(
+                f"Invalid permission key {self.value!r}: "
+                f"must be 'resource:action' (lowercase, colon-separated)"
+            )
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class PermissionVisibility(str, Enum):
+    """Where a permission may be used / shown in role builders.
+
+    - ``PLATFORM_ONLY`` — only the platform org (cross-org admin perms,
+      e.g. ``organizations:create``). Hidden from normal-org role builders.
+    - ``SHARED`` — usable everywhere (the historical default).
+    - ``TENANT_ONLY`` — only normal organizations; **hidden from the
+      platform org**. Use for perms that make no sense for the vendor's
+      platform admins.
+
+    Replaces the old ``is_platform`` boolean: ``is_platform=True`` maps to
+    ``PLATFORM_ONLY`` and ``is_platform=False`` maps to ``SHARED``.
+    """
+
+    PLATFORM_ONLY = "platform_only"
+    SHARED = "shared"
+    TENANT_ONLY = "tenant_only"
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceName:
+    """A service identifier such as ``"courses"`` or ``"assessments"``.
+
+    Same shape as the ``service_name`` string already carried on
+    permissions; wrapping it as a value object lets the new services /
+    organization_services tables share validation.
+    """
+
+    value: str
+
+    def __post_init__(self) -> None:
+        if not _SERVICE_NAME_PATTERN.match(self.value):
+            raise ValueError(
+                f"Invalid service name {self.value!r}: must be a lowercase "
+                f"slug (letter first; letters, digits, '_' or '-')"
+            )
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class LocalizedText:
+    """A locale → text map for user-facing strings (permission descriptions,
+    service labels) that must support multiple languages.
+
+    Stored as JSONB in the ACL database, e.g.
+    ``{"en": "Edit course", "ar": "تعديل الدورة"}``. An empty map means
+    "no text provided". Values must be non-empty strings.
+    """
+
+    values: Mapping[str, str]
+
+    def __post_init__(self) -> None:
+        for locale, text in self.values.items():
+            if not isinstance(locale, str) or not locale:
+                raise ValueError(f"Invalid locale key {locale!r}")
+            if not isinstance(text, str) or not text:
+                raise ValueError(
+                    f"Invalid localized value for {locale!r}: must be a "
+                    f"non-empty string"
+                )
+        # Normalize to a plain immutable dict copy so callers can't mutate.
+        object.__setattr__(self, "values", dict(self.values))
+
+    @classmethod
+    def from_input(
+        cls,
+        value: "LocalizedText | Mapping[str, str] | str | None",
+        *,
+        default_locale: str,
+    ) -> "LocalizedText":
+        """Coerce a plain string, a dict, ``None``, or a ``LocalizedText``
+        into a ``LocalizedText``. A bare string is stored under
+        ``default_locale``; ``None`` becomes the empty map.
+        """
+        if value is None:
+            return cls({})
+        if isinstance(value, LocalizedText):
+            return value
+        if isinstance(value, str):
+            return cls({default_locale: value})
+        return cls(dict(value))
+
+    def get(self, locale: str, *, fallback: str | None = None) -> str | None:
+        """Return the text for ``locale`` or ``fallback`` if absent."""
+        return self.values.get(locale, fallback)
+
+    def resolve(self, locale: str, default_locale: str) -> str | None:
+        """Return ``locale``'s text, falling back to ``default_locale``, then
+        to any available value, then ``None``.
+        """
+        if locale in self.values:
+            return self.values[locale]
+        if default_locale in self.values:
+            return self.values[default_locale]
+        for text in self.values.values():
+            return text
+        return None
+
+    def as_dict(self) -> dict[str, str]:
+        return dict(self.values)

pkg_auth/authorization/platform.py

@@ -0,0 +1,47 @@
+"""Helpers for detecting platform-org context.
+
+A "platform" organization is one whose members are granted cross-org
+administrative privileges by the consuming service. There's nothing
+special about its DB row — it's just an organization that the service
+has designated as the platform org via configuration (slug, env var,
+settings module, etc.).
+
+The intended pattern:
+
+1. The service caches the platform org's id at startup, e.g. by looking
+   it up via slug from its ``OrganizationRepository`` in a lifespan or
+   ``AppConfig.ready()`` hook. Where the cache lives is up to the
+   service (module global, app config, request scope, …).
+2. Platform admins send their requests with
+   ``X-Organization-Id: <platform-org-slug>`` to surface their elevated
+   privileges. The auth dependency builds an :class:`AuthContext` whose
+   ``organization_id`` is the platform org id.
+3. Inside handlers, the service calls
+   :func:`is_platform_context` with the request's ``AuthContext`` and
+   the cached platform org id. When it returns ``True``, the handler
+   broadens its queryset filters (e.g. lists users from all orgs).
+
+This module is intentionally stateless — pkg_auth does not own the
+platform org id cache. Each consuming service decides where the cache
+lives and when to refresh it.
+"""
+from __future__ import annotations
+
+from .domain.entities import AuthContext
+from .domain.value_objects import OrgId
+
+
+def is_platform_context(
+    auth_ctx: AuthContext, platform_org_id: OrgId | None,
+) -> bool:
+    """Return True if the request is being made in the platform org.
+
+    ``platform_org_id`` is whatever the consuming service has cached
+    (typically resolved by slug at startup). When ``None`` — for
+    example before the cache is initialized, or in services that
+    don't have a designated platform org — this returns ``False``,
+    which is equivalent to "no platform-admin privileges available".
+    """
+    if platform_org_id is None:
+        return False
+    return auth_ctx.organization_id == platform_org_id

pkg_auth/integrations/django/__init__.py

@@ -0,0 +1,32 @@
+"""Django integration for pkg_auth (identity + ACL).
+
+Provides:
+    - ``IdentityMiddleware``     — validates JWT, attaches ``request.identity``
+    - ``AuthContextMiddleware``  — reads ``X-Organization-Id``, attaches ``request.auth_context``
+    - ``require_permission``     — function decorator for Django views
+    - ``install_pkg_auth``       — convenience wiring helper
+
+Add ``"pkg_auth.integrations.django"`` to ``INSTALLED_APPS`` and the
+two middlewares to ``MIDDLEWARE`` (in order — identity first).
+"""
+from __future__ import annotations
+
+try:
+    import django  # noqa: F401
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "pkg_auth.integrations.django requires Django. "
+        "Install with: pip install pkg-auth[django]"
+    ) from exc
+
+from .auth_context_middleware import AuthContextMiddleware
+from .decorators import require_permission
+from .install import install_pkg_auth
+from .middleware import IdentityMiddleware
+
+__all__ = [
+    "IdentityMiddleware",
+    "AuthContextMiddleware",
+    "require_permission",
+    "install_pkg_auth",
+]

pkg_auth/integrations/django/apps.py

@@ -0,0 +1,10 @@
+"""Django AppConfig for pkg_auth's framework integration."""
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class PkgAuthDjangoConfig(AppConfig):
+    name = "pkg_auth.integrations.django"
+    label = "pkg_auth_django"
+    verbose_name = "pkg_auth Django integration"

pkg_auth/integrations/django/auth_context_middleware.py

@@ -0,0 +1,105 @@
+"""AuthContextMiddleware — reads X-Organization-Id, attaches ``request.auth_context``."""
+from __future__ import annotations
+
+from typing import Awaitable, Callable
+from uuid import UUID
+
+from asgiref.sync import iscoroutinefunction
+from django.http import HttpRequest, HttpResponse, JsonResponse
+
+from ...authorization import (
+    NotAMember,
+    OrgId,
+    UnknownOrganization,
+    UserNotProvisioned,
+)
+from ...authorization.domain.entities import User
+from .install import get_registry
+
+
+class AuthContextMiddleware:
+    """Resolve and attach ``request.auth_context`` for protected routes.
+
+    Requires ``IdentityMiddleware`` to run first so ``request.identity``
+    is populated. Behavior:
+
+        - no header → ``request.auth_context = None`` (route decides)
+        - identity is None and header present → 401
+        - org not found → 404
+        - user not a member → 403
+
+    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 views, comparing the request's ``AuthContext.organization_id``
+    against their own cached platform org id. Services that need to
+    *resolve* the caller against a platform org when they aren't a
+    member of the requested org can subclass this middleware and
+    intercept the ``NotAMember`` branch themselves.
+    """
+
+    sync_capable = False
+    async_capable = True
+
+    def __init__(
+        self,
+        get_response: Callable[[HttpRequest], Awaitable[HttpResponse]],
+    ) -> None:
+        self.get_response = get_response
+        if not iscoroutinefunction(get_response):
+            raise RuntimeError(
+                "AuthContextMiddleware requires async middleware chain "
+                "(use ASGI / runserver)."
+            )
+
+    async def __call__(self, request: HttpRequest) -> HttpResponse:
+        registry = get_registry()
+        request.auth_context = None  # type: ignore[attr-defined]
+
+        raw = request.headers.get(registry.header_name)
+        if raw is None:
+            return await self.get_response(request)
+
+        identity = getattr(request, "identity", None)
+        if identity is None:
+            return JsonResponse(
+                {"detail": "Not authenticated"}, status=401,
+            )
+
+        user: User
+        try:
+            if registry.sync_user is not None:
+                user = await registry.sync_user.execute(
+                    sub=identity.subject_str,
+                    email=identity.email_str or "",
+                    full_name=identity.full_name,
+                )
+            else:
+                assert registry.resolve_user is not None
+                user = await registry.resolve_user.execute(
+                    sub=identity.subject_str,
+                )
+        except UserNotProvisioned as exc:
+            return JsonResponse({"detail": str(exc)}, status=403)
+
+        # Accept UUID or slug. The package switched to UUID PKs in v1.2;
+        # the legacy isdigit() fast-path is gone.
+        try:
+            org = await registry.organization_repo.get(OrgId(UUID(raw)))
+        except (ValueError, AttributeError):
+            org = await registry.organization_repo.get_by_slug(raw)
+        if org is None:
+            return JsonResponse(
+                {"detail": f"Organization {raw!r} not found"}, status=404,
+            )
+
+        try:
+            request.auth_context = await registry.resolve_auth.execute(  # type: ignore[attr-defined]
+                user.id, org.id,
+            )
+        except NotAMember as exc:
+            return JsonResponse({"detail": str(exc)}, status=403)
+        except UnknownOrganization as exc:
+            return JsonResponse({"detail": str(exc)}, status=404)
+
+        return await self.get_response(request)