pkg-auth 3.0.0__py3-none-any.whl

pkg_auth/authorization/adapters/django_orm/models.py

@@ -0,0 +1,226 @@
+"""Default concrete Django ORM mirror models for the ACL (UUID PKs).
+
+.. warning::
+   **Mode B only.** These models declare ``Meta.managed = False`` and
+   map to the default ACL table names (``users``, ``organizations``,
+   …) so consuming services (Mode B) can read the shared ACL tables
+   via Django's ORM without owning the schema. The schema is owned
+   by the source-of-truth service.
+
+   **Do NOT import any class from this module into a Mode A service**
+   (one that extends the mixins to add service-specific columns, e.g.
+   a Django version of ``itq_users``). Mode A services own the ACL
+   schema, run their own migrations with ``Meta.managed = True``, and
+   define their own concrete models.
+
+   Mode A services must:
+
+   - Import the abstract column mixins from
+     ``pkg_auth.authorization.adapters.django_orm.mixins`` (NOT from
+     this module)
+   - Define their own concrete models with their own ``db_table`` and
+     ``Meta.managed = True``
+   - Run their own ``manage.py migrate`` (not ``alembic upgrade``)
+   - Inject their concrete model classes into the package repos via
+     ``DjangoUserRepository(model=MyUser)`` etc.
+
+   See ``docs/Django.md`` for the Mode A vs Mode B distinction.
+"""
+from __future__ import annotations
+
+import uuid
+
+from django.db import models
+
+from .mixins import (
+    MembershipMixin,
+    OrganizationMixin,
+    OrganizationServiceMixin,
+    PermissionMixin,
+    RoleMixin,
+    ServiceMixin,
+    UserMixin,
+)
+
+
+class User(UserMixin):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    class Meta:
+        managed = False
+        db_table = "users"
+        app_label = "pkg_auth_acl"
+
+
+class Organization(OrganizationMixin):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    class Meta:
+        managed = False
+        db_table = "organizations"
+        app_label = "pkg_auth_acl"
+
+
+class Permission(PermissionMixin):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    class Meta:
+        managed = False
+        db_table = "permissions"
+        app_label = "pkg_auth_acl"
+
+
+class Service(ServiceMixin):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+
+    class Meta:
+        managed = False
+        db_table = "services"
+        app_label = "pkg_auth_acl"
+
+
+class OrganizationService(OrganizationServiceMixin):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    organization = models.ForeignKey(
+        Organization,
+        on_delete=models.CASCADE,
+        db_column="organization_id",
+        related_name="services",
+    )
+
+    class Meta:
+        managed = False
+        db_table = "organization_services"
+        app_label = "pkg_auth_acl"
+        unique_together = (("organization", "service_name"),)
+
+
+class Role(RoleMixin):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    organization = models.ForeignKey(
+        Organization,
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        db_column="organization_id",
+        related_name="roles",
+    )
+    permissions = models.ManyToManyField(
+        Permission,
+        through="RolePermission",
+        related_name="roles",
+    )
+
+    class Meta:
+        managed = False
+        db_table = "roles"
+        app_label = "pkg_auth_acl"
+        unique_together = (("organization", "name"),)
+
+
+class RolePermission(models.Model):
+    role = models.ForeignKey(
+        Role,
+        on_delete=models.CASCADE,
+        db_column="role_id",
+        related_name="role_permissions",
+    )
+    permission = models.ForeignKey(
+        Permission,
+        on_delete=models.CASCADE,
+        db_column="permission_id",
+        related_name="role_permissions",
+    )
+
+    class Meta:
+        managed = False
+        db_table = "role_permissions"
+        app_label = "pkg_auth_acl"
+        unique_together = (("role", "permission"),)
+
+
+class Membership(MembershipMixin):
+    """Multi-role-aware: ``UNIQUE(user, organization, role)``.
+
+    A user can hold multiple memberships in the same organization (one row
+    per role); ``DjangoMembershipRepository.load_auth_context`` aggregates
+    them into the union of all active roles' permissions.
+    """
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    user = models.ForeignKey(
+        User,
+        on_delete=models.CASCADE,
+        db_column="user_id",
+        related_name="memberships",
+    )
+    organization = models.ForeignKey(
+        Organization,
+        on_delete=models.CASCADE,
+        db_column="organization_id",
+        related_name="memberships",
+    )
+    role = models.ForeignKey(
+        Role,
+        on_delete=models.PROTECT,
+        db_column="role_id",
+        related_name="memberships",
+    )
+    status = models.CharField(max_length=32, default="active")
+
+    class Meta:
+        managed = False
+        db_table = "memberships"
+        app_label = "pkg_auth_acl"
+        unique_together = (("user", "organization", "role"),)
+
+
+class MembershipInvitation(models.Model):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    organization = models.ForeignKey(
+        Organization,
+        on_delete=models.CASCADE,
+        db_column="organization_id",
+    )
+    email = models.CharField(max_length=255)
+    role = models.ForeignKey(
+        Role,
+        on_delete=models.PROTECT,
+        db_column="role_id",
+    )
+    token = models.CharField(max_length=64, unique=True)
+    invited_by_user = models.ForeignKey(
+        User,
+        on_delete=models.SET_NULL,
+        null=True,
+        db_column="invited_by_user_id",
+    )
+    expires_at = models.DateTimeField()
+    accepted_at = models.DateTimeField(null=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        managed = False
+        db_table = "membership_invitations"
+        app_label = "pkg_auth_acl"
+
+
+class AuthAuditLog(models.Model):
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    actor_user = models.ForeignKey(
+        User,
+        on_delete=models.SET_NULL,
+        null=True,
+        db_column="actor_user_id",
+    )
+    action = models.CharField(max_length=128)
+    target_type = models.CharField(max_length=64)
+    target_id = models.CharField(max_length=64)
+    payload = models.JSONField()
+    occurred_at = models.DateTimeField(auto_now_add=True)
+    request_id = models.CharField(max_length=64, null=True)
+
+    class Meta:
+        managed = False
+        db_table = "auth_audit_log"
+        app_label = "pkg_auth_acl"

pkg_auth/authorization/adapters/django_orm/repositories/__init__.py

@@ -0,0 +1,20 @@
+"""Django ORM repository implementations for the ACL ports."""
+from __future__ import annotations
+
+from .membership import DjangoMembershipRepository
+from .organization import DjangoOrganizationRepository
+from .organization_service import DjangoOrganizationServiceRepository
+from .permission_catalog import DjangoPermissionCatalogRepository
+from .role import DjangoRoleRepository
+from .service import DjangoServiceRepository
+from .user import DjangoUserRepository
+
+__all__ = [
+    "DjangoUserRepository",
+    "DjangoOrganizationRepository",
+    "DjangoRoleRepository",
+    "DjangoMembershipRepository",
+    "DjangoPermissionCatalogRepository",
+    "DjangoServiceRepository",
+    "DjangoOrganizationServiceRepository",
+]

pkg_auth/authorization/adapters/django_orm/repositories/membership.py

@@ -0,0 +1,118 @@
+"""Django ORM implementation of MembershipRepository (multi-role aware)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from ....domain.entities import AuthContext, Membership as DomainMembership
+from ....domain.value_objects import (
+    OrgId,
+    RoleId,
+    RoleName,
+    UserId,
+)
+from ..models import Membership as DefaultMembershipModel
+from ..models import Role as DefaultRoleModel
+
+
+def _to_domain(row, role_name: str) -> DomainMembership:
+    return DomainMembership(
+        id=row.id,
+        user_id=UserId(row.user_id),
+        organization_id=OrgId(row.organization_id),
+        role_id=RoleId(row.role_id),
+        role_name=RoleName(role_name),
+        status=row.status,
+        joined_at=row.joined_at,
+    )
+
+
+@dataclass(slots=True)
+class DjangoMembershipRepository:
+    """Multi-role per (user, org). Storage uniqueness is on
+    ``(user_id, organization_id, role_id)`` and ``load_auth_context``
+    aggregates the union of all active memberships."""
+
+    model: type = field(default=DefaultMembershipModel)
+    role_model: type = field(default=DefaultRoleModel)
+
+    async def get(
+        self, user_id: UserId, org_id: OrgId
+    ) -> DomainMembership | None:
+        row = await (
+            self.model.objects
+            .select_related("role")
+            .filter(user_id=user_id.value, organization_id=org_id.value)
+            .afirst()
+        )
+        if row is None:
+            return None
+        return _to_domain(row, row.role.name)
+
+    async def upsert(
+        self,
+        *,
+        user_id: UserId,
+        org_id: OrgId,
+        role_id: RoleId,
+        status: str,
+    ) -> DomainMembership:
+        now = datetime.now(timezone.utc)
+        row, created = await self.model.objects.aupdate_or_create(
+            user_id=user_id.value,
+            organization_id=org_id.value,
+            role_id=role_id.value,
+            defaults={
+                "status": status,
+                "updated_at": now,
+            },
+        )
+        if created:
+            row.joined_at = now
+            row.created_at = now
+            await row.asave(update_fields=["joined_at", "created_at"])
+        # Re-fetch with role for role_name
+        row = await self.model.objects.select_related("role").aget(id=row.id)
+        return _to_domain(row, row.role.name)
+
+    async def delete(self, user_id: UserId, org_id: OrgId) -> None:
+        # Multi-role: removes ALL memberships for (user, org).
+        await self.model.objects.filter(
+            user_id=user_id.value, organization_id=org_id.value,
+        ).adelete()
+
+    async def load_auth_context(
+        self, user_id: UserId, org_id: OrgId
+    ) -> AuthContext | None:
+        rows = (
+            self.model.objects
+            .select_related("role")
+            .prefetch_related("role__permissions")
+            .filter(
+                user_id=user_id.value,
+                organization_id=org_id.value,
+                status="active",
+            )
+        )
+        role_names: set[str] = set()
+        perms: set[str] = set()
+        any_active = False
+        async for row in rows:
+            any_active = True
+            role_names.add(row.role.name)
+            async for k in row.role.permissions.all().values_list("key", flat=True):
+                perms.add(k)
+        if not any_active:
+            return None
+        return AuthContext(
+            user_id=user_id,
+            organization_id=org_id,
+            role_names=frozenset(role_names),
+            perms=frozenset(perms),
+        )
+
+    async def list_for_user(self, user_id: UserId) -> list[DomainMembership]:
+        rows = self.model.objects.select_related("role").filter(
+            user_id=user_id.value
+        )
+        return [_to_domain(r, r.role.name) async for r in rows]

pkg_auth/authorization/adapters/django_orm/repositories/organization.py

@@ -0,0 +1,73 @@
+"""Django ORM implementation of OrganizationRepository."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from ....domain.entities import Organization as DomainOrganization
+from ....domain.value_objects import OrgId, UserId
+from ..models import Membership as DefaultMembershipModel
+from ..models import Organization as DefaultOrganizationModel
+
+
+def _to_domain(row) -> DomainOrganization:
+    return DomainOrganization(
+        id=OrgId(row.id),
+        slug=row.slug,
+        name=row.name,
+        created_at=row.created_at,
+    )
+
+
+@dataclass(slots=True)
+class DjangoOrganizationRepository:
+    """``model`` and ``membership_model`` are injectable so consuming
+    services can swap in their own concrete classes (extending the
+    abstract mixins). Defaults are the package's managed=False mirrors."""
+
+    model: type = field(default=DefaultOrganizationModel)
+    membership_model: type = field(default=DefaultMembershipModel)
+
+    async def get(self, org_id: OrgId) -> DomainOrganization | None:
+        try:
+            row = await self.model.objects.aget(id=org_id.value)
+        except self.model.DoesNotExist:
+            return None
+        return _to_domain(row)
+
+    async def get_by_slug(self, slug: str) -> DomainOrganization | None:
+        try:
+            row = await self.model.objects.aget(slug=slug)
+        except self.model.DoesNotExist:
+            return None
+        return _to_domain(row)
+
+    async def create(self, *, slug: str, name: str) -> DomainOrganization:
+        now = datetime.now(timezone.utc)
+        row = await self.model.objects.acreate(
+            slug=slug, name=name, created_at=now, updated_at=now,
+        )
+        return _to_domain(row)
+
+    async def update(
+        self, org_id: OrgId, *, name: str | None
+    ) -> DomainOrganization:
+        row = await self.model.objects.aget(id=org_id.value)
+        if name is not None:
+            row.name = name
+            row.updated_at = datetime.now(timezone.utc)
+            await row.asave(update_fields=["name", "updated_at"])
+        return _to_domain(row)
+
+    async def delete(self, org_id: OrgId) -> None:
+        await self.model.objects.filter(id=org_id.value).adelete()
+
+    async def list_for_user(self, user_id: UserId) -> list[DomainOrganization]:
+        # Distinct because a multi-role user has multiple membership rows per org.
+        rows = (
+            self.model.objects
+            .filter(memberships__user_id=user_id.value)
+            .distinct()
+            .order_by("id")
+        )
+        return [_to_domain(r) async for r in rows]

pkg_auth/authorization/adapters/django_orm/repositories/organization_service.py

@@ -0,0 +1,71 @@
+"""Django ORM implementation of OrganizationServiceRepository."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Sequence
+
+from ....domain.entities import OrganizationService
+from ....domain.value_objects import OrgId, ServiceName
+from ..models import OrganizationService as DefaultOrganizationServiceModel
+
+
+def _to_domain(row) -> OrganizationService:
+    return OrganizationService(
+        organization_id=OrgId(row.organization_id),
+        service_name=ServiceName(row.service_name),
+        enabled=bool(row.enabled),
+        source=row.source,
+        granted_at=row.granted_at,
+    )
+
+
+@dataclass(slots=True)
+class DjangoOrganizationServiceRepository:
+    model: type = field(default=DefaultOrganizationServiceModel)
+
+    async def list_enabled_service_names(self, org_id: OrgId) -> set[str]:
+        return {
+            row.service_name
+            async for row in self.model.objects.filter(
+                organization_id=org_id.value, enabled=True
+            ).only("service_name")
+        }
+
+    async def get(
+        self, org_id: OrgId, service_name: ServiceName
+    ) -> OrganizationService | None:
+        row = await self.model.objects.filter(
+            organization_id=org_id.value, service_name=str(service_name)
+        ).afirst()
+        return _to_domain(row) if row is not None else None
+
+    async def enable(
+        self, org_id: OrgId, service_name: ServiceName, *, source: str
+    ) -> OrganizationService:
+        row, _ = await self.model.objects.aupdate_or_create(
+            organization_id=org_id.value,
+            service_name=str(service_name),
+            defaults={"enabled": True, "source": source},
+        )
+        return _to_domain(row)
+
+    async def disable(
+        self, org_id: OrgId, service_name: ServiceName
+    ) -> None:
+        await self.model.objects.filter(
+            organization_id=org_id.value, service_name=str(service_name)
+        ).adelete()
+
+    async def bulk_enable(
+        self,
+        org_id: OrgId,
+        service_names: Sequence[ServiceName],
+        *,
+        source: str,
+    ) -> None:
+        for name in service_names:
+            await self.model.objects.aupdate_or_create(
+                organization_id=org_id.value,
+                service_name=str(name),
+                defaults={"enabled": True, "source": source},
+            )

pkg_auth/authorization/adapters/django_orm/repositories/permission_catalog.py

@@ -0,0 +1,102 @@
+"""Django ORM implementation of PermissionCatalogRepository (visibility + scope)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Iterable, Sequence
+
+from ....application.use_cases.register_permission_catalog import CatalogEntry
+from ....domain.entities import Permission as DomainPermission
+from ....domain.ports import PermissionScope
+from ....domain.value_objects import (
+    LocalizedText,
+    PermissionId,
+    PermissionKey,
+    PermissionVisibility,
+)
+from ..models import Permission as DefaultPermissionModel
+
+
+def _to_domain(row) -> DomainPermission:
+    return DomainPermission(
+        id=PermissionId(row.id),
+        key=PermissionKey(row.key),
+        service_name=row.service_name,
+        description=LocalizedText(row.description or {}),
+        visibility=PermissionVisibility(row.visibility),
+    )
+
+
+def _scope_filter(qs, scope: PermissionScope):
+    if scope in ("org", "tenant"):
+        return qs.filter(
+            visibility__in=(
+                PermissionVisibility.SHARED.value,
+                PermissionVisibility.TENANT_ONLY.value,
+            )
+        )
+    if scope == "platform":
+        return qs.filter(
+            visibility__in=(
+                PermissionVisibility.PLATFORM_ONLY.value,
+                PermissionVisibility.SHARED.value,
+            )
+        )
+    return qs
+
+
+@dataclass(slots=True)
+class DjangoPermissionCatalogRepository:
+    model: type = field(default=DefaultPermissionModel)
+
+    async def register_many(
+        self,
+        *,
+        service_name: str,
+        entries: Sequence[CatalogEntry],
+    ) -> None:
+        now = datetime.now(timezone.utc)
+        for entry in entries:
+            await self.model.objects.aupdate_or_create(
+                key=str(entry.key),
+                defaults={
+                    "service_name": service_name,
+                    "description": entry.description.as_dict() or None,
+                    "visibility": entry.visibility.value,
+                    "registered_at": now,
+                },
+            )
+
+    async def list_all(
+        self, *, scope: PermissionScope = "all"
+    ) -> list[DomainPermission]:
+        qs = _scope_filter(self.model.objects.order_by("id"), scope)
+        return [_to_domain(r) async for r in qs]
+
+    async def list_for_service(
+        self, service_name: str, *, scope: PermissionScope = "all"
+    ) -> list[DomainPermission]:
+        qs = _scope_filter(
+            self.model.objects.filter(service_name=service_name).order_by("id"),
+            scope,
+        )
+        return [_to_domain(r) async for r in qs]
+
+    async def get_service_map(self) -> dict[str, str]:
+        return {
+            row.key: row.service_name
+            async for row in self.model.objects.only("key", "service_name")
+        }
+
+    async def prune_absent(
+        self,
+        *,
+        service_name: str,
+        keep_keys: Iterable[PermissionKey],
+    ) -> int:
+        keys = [str(k) for k in keep_keys]
+        qs = self.model.objects.filter(service_name=service_name)
+        if keys:
+            qs = qs.exclude(key__in=keys)
+        deleted, _ = await qs.adelete()
+        return int(deleted)