pkg-auth 3.0.0__py3-none-any.whl

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

@@ -0,0 +1,120 @@
+"""Django ORM implementation of RoleRepository."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Sequence
+
+from ....domain.entities import Role as DomainRole
+from ....domain.value_objects import (
+    OrgId,
+    PermissionKey,
+    RoleId,
+    RoleName,
+)
+from ..models import Permission as DefaultPermissionModel
+from ..models import Role as DefaultRoleModel
+
+
+async def _role_to_domain(row) -> DomainRole:
+    perm_keys = [
+        k async for k in row.permissions.all().values_list("key", flat=True)
+    ]
+    return DomainRole(
+        id=RoleId(row.id),
+        organization_id=OrgId(row.organization_id) if row.organization_id else None,
+        name=RoleName(row.name),
+        description=row.description,
+        permission_keys=frozenset(perm_keys),
+    )
+
+
+@dataclass(slots=True)
+class DjangoRoleRepository:
+    model: type = field(default=DefaultRoleModel)
+    permission_model: type = field(default=DefaultPermissionModel)
+
+    async def get(self, role_id: RoleId) -> DomainRole | None:
+        try:
+            row = await self.model.objects.aget(id=role_id.value)
+        except self.model.DoesNotExist:
+            return None
+        return await _role_to_domain(row)
+
+    async def get_by_name(
+        self, org_id: OrgId | None, name: RoleName
+    ) -> DomainRole | None:
+        qs = self.model.objects.filter(name=str(name))
+        qs = (
+            qs.filter(organization__isnull=True)
+            if org_id is None
+            else qs.filter(organization_id=org_id.value)
+        )
+        try:
+            row = await qs.aget()
+        except self.model.DoesNotExist:
+            return None
+        return await _role_to_domain(row)
+
+    async def create(
+        self,
+        *,
+        org_id: OrgId | None,
+        name: RoleName,
+        description: str | None,
+        permission_keys: Sequence[PermissionKey],
+    ) -> DomainRole:
+        now = datetime.now(timezone.utc)
+        row = await self.model.objects.acreate(
+            organization_id=org_id.value if org_id is not None else None,
+            name=str(name),
+            description=description,
+            created_at=now,
+            updated_at=now,
+        )
+        if permission_keys:
+            key_strs = [str(k) for k in permission_keys]
+            perm_ids = [
+                pid
+                async for pid in self.permission_model.objects.filter(
+                    key__in=key_strs
+                ).values_list("id", flat=True)
+            ]
+            await row.permissions.aset(perm_ids)
+        return await _role_to_domain(row)
+
+    async def update(
+        self,
+        role_id: RoleId,
+        *,
+        name: RoleName | None,
+        description: str | None,
+        permission_keys: Sequence[PermissionKey] | None,
+    ) -> DomainRole:
+        row = await self.model.objects.aget(id=role_id.value)
+        update_fields: list[str] = []
+        if name is not None:
+            row.name = str(name)
+            update_fields.append("name")
+        if description is not None:
+            row.description = description
+            update_fields.append("description")
+        if update_fields:
+            row.updated_at = datetime.now(timezone.utc)
+            update_fields.append("updated_at")
+            await row.asave(update_fields=update_fields)
+
+        if permission_keys is not None:
+            key_strs = [str(k) for k in permission_keys]
+            perm_ids = [
+                pid
+                async for pid in self.permission_model.objects.filter(
+                    key__in=key_strs
+                ).values_list("id", flat=True)
+            ]
+            await row.permissions.aset(perm_ids)
+
+        return await _role_to_domain(row)
+
+    async def delete(self, role_id: RoleId) -> None:
+        await self.model.objects.filter(id=role_id.value).adelete()

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

@@ -0,0 +1,60 @@
+"""Django ORM implementation of ServiceRepository."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable, Sequence
+
+from ....application.use_cases.sync_service_catalog import ServiceSpec
+from ....domain.entities import Service
+from ....domain.value_objects import LocalizedText, ServiceName
+from ..models import Service as DefaultServiceModel
+
+
+def _to_domain(row) -> Service:
+    return Service(
+        name=ServiceName(row.name),
+        display_label=LocalizedText(row.display_label or {}),
+        auto_provision=bool(row.auto_provision),
+        saas_available=bool(row.saas_available),
+        created_at=row.created_at,
+    )
+
+
+@dataclass(slots=True)
+class DjangoServiceRepository:
+    model: type = field(default=DefaultServiceModel)
+
+    async def upsert_many(self, services: Sequence[ServiceSpec]) -> None:
+        for s in services:
+            await self.model.objects.aupdate_or_create(
+                name=str(s.name),
+                defaults={
+                    "display_label": s.display_label.as_dict() or None,
+                    "auto_provision": s.auto_provision,
+                    "saas_available": s.saas_available,
+                },
+            )
+
+    async def ensure_exists(self, *, service_name: str) -> None:
+        await self.model.objects.aget_or_create(
+            name=service_name,
+            defaults={"auto_provision": False, "saas_available": False},
+        )
+
+    async def get(self, name: ServiceName) -> Service | None:
+        row = await self.model.objects.filter(name=str(name)).afirst()
+        return _to_domain(row) if row is not None else None
+
+    async def list_all(self) -> list[Service]:
+        return [
+            _to_domain(r)
+            async for r in self.model.objects.order_by("name")
+        ]
+
+    async def prune_absent(self, *, keep: Iterable[ServiceName]) -> int:
+        names = [str(n) for n in keep]
+        qs = self.model.objects.all()
+        if names:
+            qs = qs.exclude(name__in=names)
+        deleted, _ = await qs.adelete()
+        return int(deleted)

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

@@ -0,0 +1,77 @@
+"""Django ORM implementation of UserRepository."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from django.db import IntegrityError
+
+from ....domain.entities import User as DomainUser
+from ....domain.value_objects import UserId
+from ..models import User as DefaultUserModel
+
+
+def _to_domain(row) -> DomainUser:
+    return DomainUser(
+        id=UserId(row.id),
+        keycloak_sub=row.keycloak_sub,
+        email=row.email,
+        full_name=row.full_name,
+        first_seen_at=row.first_seen_at,
+        last_seen_at=row.last_seen_at,
+    )
+
+
+@dataclass(slots=True)
+class DjangoUserRepository:
+    """Django ORM implementation of UserRepository.
+
+    The ``model`` field accepts any concrete Django model class that
+    inherits from :class:`pkg_auth.authorization.adapters.django_orm.UserMixin`.
+    Defaults to the package's managed=False mirror model.
+    """
+
+    model: type = field(default=DefaultUserModel)
+
+    async def get_by_id(self, user_id: UserId) -> DomainUser | None:
+        try:
+            row = await self.model.objects.aget(id=user_id.value)
+        except self.model.DoesNotExist:
+            return None
+        return _to_domain(row)
+
+    async def get_by_keycloak_sub(self, sub: str) -> DomainUser | None:
+        try:
+            row = await self.model.objects.aget(keycloak_sub=sub)
+        except self.model.DoesNotExist:
+            return None
+        return _to_domain(row)
+
+    async def upsert_from_identity(
+        self,
+        *,
+        sub: str,
+        email: str,
+        full_name: str | None,
+    ) -> DomainUser:
+        now = datetime.now(timezone.utc)
+        try:
+            row = await self.model.objects.aget(keycloak_sub=sub)
+            row.email = email
+            row.full_name = full_name
+            row.last_seen_at = now
+            await row.asave(update_fields=["email", "full_name", "last_seen_at"])
+        except self.model.DoesNotExist:
+            try:
+                row = await self.model.objects.acreate(
+                    keycloak_sub=sub,
+                    email=email,
+                    full_name=full_name,
+                    first_seen_at=now,
+                    last_seen_at=now,
+                    created_at=now,
+                    updated_at=now,
+                )
+            except IntegrityError:
+                row = await self.model.objects.aget(keycloak_sub=sub)
+        return _to_domain(row)

pkg_auth/authorization/adapters/sqlalchemy/__init__.py

@@ -0,0 +1,90 @@
+"""SQLAlchemy adapter for the ACL tables.
+
+Importing this module requires SQLAlchemy and asyncpg to be installed:
+
+    pip install pkg-auth[acl-sqlalchemy]
+
+The module exposes ``MIGRATIONS_DIR`` so the source-of-truth service
+can register the bundled version files via Alembic's
+``version_locations`` mechanism as a starting point — Mode A services
+typically evolve the schema further via their own migrations from
+that point on. See ``docs/Authorization.md`` for the wiring pattern.
+"""
+from __future__ import annotations
+
+try:
+    import sqlalchemy  # noqa: F401
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "pkg_auth.authorization.adapters.sqlalchemy requires SQLAlchemy. "
+        "Install with: pip install pkg-auth[acl-sqlalchemy]"
+    ) from exc
+
+from pathlib import Path
+
+from .base import AclBase, create_acl_base
+from .mixins import (
+    MembershipMixin,
+    OrganizationMixin,
+    OrganizationServiceMixin,
+    PermissionMixin,
+    RoleMixin,
+    ServiceMixin,
+    UserMixin,
+)
+from .models import (
+    AuthAuditLogORM,
+    MembershipInvitationORM,
+    MembershipORM,
+    OrganizationORM,
+    OrganizationServiceORM,
+    PermissionORM,
+    RoleORM,
+    RolePermissionORM,
+    ServiceORM,
+    UserORM,
+)
+from .repositories.membership import SqlAlchemyMembershipRepository
+from .repositories.organization import SqlAlchemyOrganizationRepository
+from .repositories.organization_service import (
+    SqlAlchemyOrganizationServiceRepository,
+)
+from .repositories.permission_catalog import SqlAlchemyPermissionCatalogRepository
+from .repositories.role import SqlAlchemyRoleRepository
+from .repositories.service import SqlAlchemyServiceRepository
+from .repositories.user import SqlAlchemyUserRepository
+
+MIGRATIONS_DIR: str = str(Path(__file__).parent / "migrations" / "versions")
+
+__all__ = [
+    "AclBase",
+    "create_acl_base",
+    "MIGRATIONS_DIR",
+    # Mixins (for services that extend)
+    "UserMixin",
+    "OrganizationMixin",
+    "PermissionMixin",
+    "RoleMixin",
+    "MembershipMixin",
+    "ServiceMixin",
+    "OrganizationServiceMixin",
+    # ORM models
+    "UserORM",
+    "OrganizationORM",
+    "PermissionORM",
+    "RoleORM",
+    "RolePermissionORM",
+    "MembershipORM",
+    "MembershipInvitationORM",
+    "AuthAuditLogORM",
+    "ServiceORM",
+    "OrganizationServiceORM",
+    # Repositories
+    "SqlAlchemyUserRepository",
+    "SqlAlchemyOrganizationRepository",
+    "SqlAlchemyRoleRepository",
+    "SqlAlchemyMembershipRepository",
+    "SqlAlchemyPermissionCatalogRepository",
+    "SqlAlchemyServiceRepository",
+    "SqlAlchemyOrganizationServiceRepository",
+]

pkg_auth/authorization/adapters/sqlalchemy/base.py

@@ -0,0 +1,55 @@
+"""SQLAlchemy declarative base for the bundled ACL ORM.
+
+.. warning::
+   **Mode B only.** This module is part of pkg_auth's *default
+   concrete ORM* — used by consuming services (Mode B) that point
+   their own sessionmaker at the shared ACL database and read the
+   tables via the bundled ``*ORM`` classes.
+
+   **Do NOT import ``AclBase`` from a Mode A service** (one that
+   extends the mixins to add service-specific columns, e.g.
+   ``itq_users``). Mode A services own the ACL schema — they bring
+   their own ``DeclarativeBase`` and their own concrete ORM classes,
+   and run their own Alembic migrations. Importing ``AclBase`` into
+   a Mode A service splits the service's models across two metadata
+   objects and causes ``metadata.create_all`` / migration tooling to
+   misbehave.
+
+   Mode A services must:
+
+   - Import the abstract column mixins from
+     ``pkg_auth.authorization.adapters.sqlalchemy.mixins`` (NOT from
+     this module or ``models.py``)
+   - Define their own concrete ``*ORM`` classes against their own
+     ``DeclarativeBase``
+   - Write their own Alembic migrations
+
+   See ``docs/Django.md`` for the Mode A vs Mode B distinction.
+"""
+from __future__ import annotations
+
+from sqlalchemy import MetaData
+from sqlalchemy.orm import DeclarativeBase
+
+
+def create_acl_base(schema: str | None = None) -> type[DeclarativeBase]:
+    """Build a ``DeclarativeBase`` for the bundled ACL ORM.
+
+    By default (``schema=None``), tables are emitted unqualified and
+    resolve via the database ``search_path`` — which means ``public``
+    on a standard Postgres setup. This matches where source-of-truth
+    services like ``itq_users`` put the ACL tables.
+
+    Pass an explicit schema name (``create_acl_base("custom")``) if
+    your source-of-truth service placed the tables in a non-default
+    Postgres schema.
+    """
+    md = MetaData(schema=schema)
+
+    class _AclBase(DeclarativeBase):
+        metadata = md
+
+    return _AclBase
+
+
+AclBase = create_acl_base()

pkg_auth/authorization/adapters/sqlalchemy/migrations/__init__.py

@@ -0,0 +1 @@
+"""Alembic migrations for the ACL schema."""

pkg_auth/authorization/adapters/sqlalchemy/migrations/versions/20260410_0001_initial_schema.py

@@ -0,0 +1,293 @@
+"""Initial ACL tables.
+
+Revision ID: pkg_auth_acl_0001
+Revises:
+Create Date: 2026-04-10 00:00:00.000000
+
+Creates the bundled ACL tables in the connection's default schema
+(typically ``public``): ``users``, ``organizations``, ``permissions``,
+``roles``, ``role_permissions``, ``memberships``,
+``membership_invitations``, ``auth_audit_log``.
+
+Uses an explicit, deterministic revision id (``pkg_auth_acl_0001``)
+and a branch label (``pkg_auth_acl``) so source-of-truth services
+can register this directory via Alembic ``version_locations`` and
+run ``alembic upgrade pkg_auth_acl@head`` as a starting point.
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "pkg_auth_acl_0001"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = ("pkg_auth_acl",)
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ----- users ---------------------------------------------------------- #
+    op.create_table(
+        "users",
+        sa.Column("id", sa.Uuid(as_uuid=True), primary_key=True),
+        sa.Column("keycloak_sub", sa.String(64), nullable=False),
+        sa.Column("email", sa.String(255), nullable=False),
+        sa.Column("full_name", sa.String(255), nullable=True),
+        sa.Column(
+            "first_seen_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "last_seen_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.UniqueConstraint("keycloak_sub", name="uq_users_keycloak_sub"),
+    )
+    op.create_index("ix_users_keycloak_sub", "users", ["keycloak_sub"])
+    op.create_index("ix_users_email", "users", ["email"])
+
+    # ----- organizations -------------------------------------------------- #
+    op.create_table(
+        "organizations",
+        sa.Column("id", sa.Uuid(as_uuid=True), primary_key=True),
+        sa.Column("slug", sa.String(255), nullable=False),
+        sa.Column("name", sa.String(255), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.UniqueConstraint("slug", name="uq_organizations_slug"),
+    )
+    op.create_index("ix_organizations_slug", "organizations", ["slug"])
+
+    # ----- permissions ---------------------------------------------------- #
+    op.create_table(
+        "permissions",
+        sa.Column("id", sa.Uuid(as_uuid=True), primary_key=True),
+        sa.Column("key", sa.String(255), nullable=False),
+        sa.Column("service_name", sa.String(64), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column(
+            "registered_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.UniqueConstraint("key", name="uq_permissions_key"),
+    )
+    op.create_index("ix_permissions_key", "permissions", ["key"])
+    op.create_index(
+        "ix_permissions_service_name", "permissions", ["service_name"]
+    )
+
+    # ----- roles ---------------------------------------------------------- #
+    op.create_table(
+        "roles",
+        sa.Column("id", sa.Uuid(as_uuid=True), primary_key=True),
+        sa.Column(
+            "organization_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("organizations.id", ondelete="CASCADE"),
+            nullable=True,
+        ),
+        sa.Column("name", sa.String(128), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.UniqueConstraint("organization_id", "name", name="uq_roles_org_name"),
+    )
+    op.create_index("ix_roles_organization_id", "roles", ["organization_id"])
+
+    # ----- role_permissions ---------------------------------------------- #
+    op.create_table(
+        "role_permissions",
+        sa.Column(
+            "role_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("roles.id", ondelete="CASCADE"),
+            primary_key=True,
+        ),
+        sa.Column(
+            "permission_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("permissions.id", ondelete="CASCADE"),
+            primary_key=True,
+        ),
+    )
+
+    # ----- memberships --------------------------------------------------- #
+    op.create_table(
+        "memberships",
+        sa.Column("id", sa.Uuid(as_uuid=True), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "organization_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("organizations.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "role_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("roles.id", ondelete="RESTRICT"),
+            nullable=False,
+        ),
+        sa.Column(
+            "status",
+            sa.String(32),
+            nullable=False,
+            server_default="active",
+        ),
+        sa.Column(
+            "joined_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.UniqueConstraint(
+            "user_id", "organization_id", "role_id", name="uq_memberships_user_org_role"
+        ),
+    )
+    op.create_index("ix_memberships_user_id", "memberships", ["user_id"])
+    op.create_index(
+        "ix_memberships_organization_id", "memberships", ["organization_id"]
+    )
+    op.create_index("ix_memberships_role_id", "memberships", ["role_id"])
+
+    # ----- membership_invitations ---------------------------------------- #
+    op.create_table(
+        "membership_invitations",
+        sa.Column("id", sa.Uuid(as_uuid=True), primary_key=True),
+        sa.Column(
+            "organization_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("organizations.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("email", sa.String(255), nullable=False),
+        sa.Column(
+            "role_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("roles.id", ondelete="RESTRICT"),
+            nullable=False,
+        ),
+        sa.Column("token", sa.String(64), nullable=False),
+        sa.Column(
+            "invited_by_user_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("accepted_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.UniqueConstraint("token", name="uq_membership_invitations_token"),
+    )
+    op.create_index(
+        "ix_membership_invitations_email", "membership_invitations", ["email"]
+    )
+
+    # ----- auth_audit_log ------------------------------------------------ #
+    op.create_table(
+        "auth_audit_log",
+        sa.Column("id", sa.Uuid(as_uuid=True), primary_key=True),
+        sa.Column(
+            "actor_user_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("action", sa.String(128), nullable=False),
+        sa.Column("target_type", sa.String(64), nullable=False),
+        sa.Column("target_id", sa.String(64), nullable=False),
+        sa.Column(
+            "payload",
+            postgresql.JSONB(astext_type=sa.Text()),
+            nullable=False,
+        ),
+        sa.Column(
+            "occurred_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column("request_id", sa.String(64), nullable=True),
+    )
+    op.create_index(
+        "ix_auth_audit_log_actor", "auth_audit_log", ["actor_user_id"]
+    )
+    op.create_index("ix_auth_audit_log_action", "auth_audit_log", ["action"])
+    op.create_index(
+        "ix_auth_audit_log_occurred_at", "auth_audit_log", ["occurred_at"]
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("auth_audit_log")
+    op.drop_table("membership_invitations")
+    op.drop_table("memberships")
+    op.drop_table("role_permissions")
+    op.drop_table("roles")
+    op.drop_table("permissions")
+    op.drop_table("organizations")
+    op.drop_table("users")