pkg-auth 3.0.0__py3-none-any.whl

pkg_auth/authorization/adapters/sqlalchemy/models.py

@@ -0,0 +1,268 @@
+"""Default concrete ORM models for the bundled ACL (UUID PKs).
+
+.. warning::
+   **Mode B only.** These concrete ``*ORM`` classes inherit from
+   ``AclBase`` — the bundled declarative base whose ``MetaData``
+   emits unqualified table names (resolving via the database
+   ``search_path``). They are ready to use out of the box for
+   *consuming* services (Mode B) that point their own sessionmaker
+   at the shared ACL database.
+
+   **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.
+   ``itq_users``). Mode A services own the ACL schema and define
+   their own concrete models against their own ``DeclarativeBase``.
+   Accidentally importing ``UserORM`` / ``OrganizationORM`` / … into
+   a Mode A service splits its models across two metadata objects
+   and breaks ``metadata.create_all`` / migration tooling.
+
+   Mode A services must:
+
+   - Import the abstract column mixins from
+     ``pkg_auth.authorization.adapters.sqlalchemy.mixins`` (NOT from
+     this module or ``base.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 datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import (
+    DateTime,
+    ForeignKey,
+    String,
+    Text,
+    UniqueConstraint,
+    Uuid,
+    func,
+    text,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from .base import AclBase
+from .mixins import (
+    MembershipMixin,
+    OrganizationMixin,
+    OrganizationServiceMixin,
+    PermissionMixin,
+    RoleMixin,
+    ServiceMixin,
+    UserMixin,
+)
+
+
+class UserORM(AclBase, UserMixin):
+    __tablename__ = "users"
+
+    id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+
+    memberships: Mapped[list["MembershipORM"]] = relationship(
+        back_populates="user",
+        cascade="all, delete-orphan",
+    )
+
+
+class OrganizationORM(AclBase, OrganizationMixin):
+    __tablename__ = "organizations"
+
+    id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+
+    memberships: Mapped[list["MembershipORM"]] = relationship(
+        back_populates="organization",
+        cascade="all, delete-orphan",
+    )
+    roles: Mapped[list["RoleORM"]] = relationship(
+        back_populates="organization",
+        cascade="all, delete-orphan",
+    )
+
+
+class PermissionORM(AclBase, PermissionMixin):
+    __tablename__ = "permissions"
+
+    id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+
+
+class ServiceORM(AclBase, ServiceMixin):
+    __tablename__ = "services"
+
+    id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+
+
+class OrganizationServiceORM(AclBase, OrganizationServiceMixin):
+    __tablename__ = "organization_services"
+    __table_args__ = (
+        UniqueConstraint(
+            "organization_id", "service_name",
+            name="uq_org_services_org_service",
+        ),
+    )
+
+    id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+    organization_id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("organizations.id", ondelete="CASCADE"),
+        index=True,
+    )
+
+
+class RoleORM(AclBase, RoleMixin):
+    __tablename__ = "roles"
+    __table_args__ = (
+        UniqueConstraint("organization_id", "name", name="uq_roles_org_name"),
+    )
+
+    id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+    organization_id: Mapped[UUID | None] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("organizations.id", ondelete="CASCADE"),
+        index=True,
+    )
+
+    organization: Mapped[OrganizationORM | None] = relationship(
+        back_populates="roles"
+    )
+    permissions: Mapped[list[PermissionORM]] = relationship(
+        secondary="role_permissions"
+    )
+    memberships: Mapped[list["MembershipORM"]] = relationship(
+        back_populates="role"
+    )
+
+
+class RolePermissionORM(AclBase):
+    __tablename__ = "role_permissions"
+
+    role_id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("roles.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    permission_id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("permissions.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+
+
+class MembershipORM(AclBase, MembershipMixin):
+    __tablename__ = "memberships"
+    __table_args__ = (
+        UniqueConstraint(
+            "user_id", "organization_id", "role_id",
+            name="uq_memberships_user_org_role",
+        ),
+    )
+
+    id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+    user_id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        index=True,
+    )
+    organization_id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("organizations.id", ondelete="CASCADE"),
+        index=True,
+    )
+    role_id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("roles.id", ondelete="RESTRICT"),
+        index=True,
+    )
+    status: Mapped[str] = mapped_column(String(32), server_default="active")
+
+    user: Mapped[UserORM] = relationship(back_populates="memberships")
+    organization: Mapped[OrganizationORM] = relationship(
+        back_populates="memberships"
+    )
+    role: Mapped[RoleORM] = relationship(back_populates="memberships")
+
+
+class MembershipInvitationORM(AclBase):
+    __tablename__ = "membership_invitations"
+
+    id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+    organization_id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("organizations.id", ondelete="CASCADE"),
+    )
+    email: Mapped[str] = mapped_column(String(255), index=True)
+    role_id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("roles.id", ondelete="RESTRICT"),
+    )
+    token: Mapped[str] = mapped_column(String(64), unique=True)
+    invited_by_user_id: Mapped[UUID | None] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+    )
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    accepted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+
+
+class AuthAuditLogORM(AclBase):
+    __tablename__ = "auth_audit_log"
+
+    id: Mapped[UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        primary_key=True,
+        server_default=text("gen_random_uuid()"),
+    )
+    actor_user_id: Mapped[UUID | None] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        index=True,
+    )
+    action: Mapped[str] = mapped_column(String(128), index=True)
+    target_type: Mapped[str] = mapped_column(String(64))
+    target_id: Mapped[str] = mapped_column(String(64))
+    payload: Mapped[dict[str, Any]] = mapped_column(JSONB)
+    occurred_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        index=True,
+    )
+    request_id: Mapped[str | None] = mapped_column(String(64))

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

@@ -0,0 +1,16 @@
+"""SQLAlchemy repository implementations for the ACL ports."""
+from __future__ import annotations
+
+from .membership import SqlAlchemyMembershipRepository
+from .organization import SqlAlchemyOrganizationRepository
+from .permission_catalog import SqlAlchemyPermissionCatalogRepository
+from .role import SqlAlchemyRoleRepository
+from .user import SqlAlchemyUserRepository
+
+__all__ = [
+    "SqlAlchemyUserRepository",
+    "SqlAlchemyOrganizationRepository",
+    "SqlAlchemyRoleRepository",
+    "SqlAlchemyMembershipRepository",
+    "SqlAlchemyPermissionCatalogRepository",
+]

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

@@ -0,0 +1,146 @@
+"""SQLAlchemy implementation of MembershipRepository (UUID PKs, injectable model)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy import delete, select
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from sqlalchemy.orm import selectinload
+
+from ....domain.entities import AuthContext, Membership
+from ....domain.value_objects import (
+    OrgId,
+    RoleId,
+    RoleName,
+    UserId,
+)
+from ..models import MembershipORM as DefaultMembershipORM
+from ..models import RoleORM as DefaultRoleORM
+
+
+def _to_membership(row: Any, role_name: str) -> Membership:
+    return Membership(
+        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 SqlAlchemyMembershipRepository:
+    session_factory: async_sessionmaker[AsyncSession]
+    model: type = field(default=DefaultMembershipORM)
+    role_model: type = field(default=DefaultRoleORM)
+
+    async def get(
+        self, user_id: UserId, org_id: OrgId
+    ) -> Membership | None:
+        async with self.session_factory() as session:
+            row = (
+                await session.execute(
+                    select(self.model)
+                    .options(selectinload(self.model.role))
+                    .where(
+                        self.model.user_id == user_id.value,
+                        self.model.organization_id == org_id.value,
+                    )
+                )
+            ).scalar_one_or_none()
+            return _to_membership(row, row.role.name) if row is not None else None
+
+    async def upsert(
+        self,
+        *,
+        user_id: UserId,
+        org_id: OrgId,
+        role_id: RoleId,
+        status: str,
+    ) -> Membership:
+        stmt = (
+            pg_insert(self.model)
+            .values(
+                user_id=user_id.value,
+                organization_id=org_id.value,
+                role_id=role_id.value,
+                status=status,
+            )
+            .on_conflict_do_update(
+                index_elements=["user_id", "organization_id"],
+                set_={"role_id": role_id.value, "status": status},
+            )
+            .returning(self.model)
+        )
+        async with self.session_factory() as session:
+            result = await session.execute(stmt)
+            await session.commit()
+            row = result.scalar_one()
+            role = (
+                await session.execute(
+                    select(self.role_model).where(
+                        self.role_model.id == row.role_id
+                    )
+                )
+            ).scalar_one()
+            return _to_membership(row, role.name)
+
+    async def delete(self, user_id: UserId, org_id: OrgId) -> None:
+        async with self.session_factory() as session:
+            await session.execute(
+                delete(self.model).where(
+                    self.model.user_id == user_id.value,
+                    self.model.organization_id == org_id.value,
+                )
+            )
+            await session.commit()
+
+    async def load_auth_context(
+        self, user_id: UserId, org_id: OrgId
+    ) -> AuthContext | None:
+        """Multi-role: fetch ALL active memberships for (user, org),
+        merge their roles' permissions into a single AuthContext.
+        """
+        async with self.session_factory() as session:
+            stmt = (
+                select(self.model)
+                .options(
+                    selectinload(self.model.role).selectinload(
+                        self.role_model.permissions
+                    )
+                )
+                .where(
+                    self.model.user_id == user_id.value,
+                    self.model.organization_id == org_id.value,
+                    self.model.status == "active",
+                )
+            )
+            rows = (await session.execute(stmt)).scalars().all()
+            if not rows:
+                return None
+            role_names: set[str] = set()
+            all_perms: set[str] = set()
+            for row in rows:
+                role_names.add(row.role.name)
+                all_perms.update(p.key for p in row.role.permissions)
+            return AuthContext(
+                user_id=UserId(rows[0].user_id),
+                organization_id=OrgId(rows[0].organization_id),
+                role_names=frozenset(role_names),
+                perms=frozenset(all_perms),
+            )
+
+    async def list_for_user(self, user_id: UserId) -> list[Membership]:
+        async with self.session_factory() as session:
+            rows = (
+                await session.execute(
+                    select(self.model)
+                    .options(selectinload(self.model.role))
+                    .where(self.model.user_id == user_id.value)
+                )
+            ).scalars().all()
+            return [_to_membership(r, r.role.name) for r in rows]

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

@@ -0,0 +1,97 @@
+"""SQLAlchemy implementation of OrganizationRepository (UUID PKs, injectable model)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy import delete, select, update
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from ....domain.entities import Organization
+from ....domain.value_objects import OrgId, UserId
+from ..models import MembershipORM as DefaultMembershipORM
+from ..models import OrganizationORM as DefaultOrganizationORM
+
+
+def _to_org(row: Any) -> Organization:
+    return Organization(
+        id=OrgId(row.id),
+        slug=row.slug,
+        name=row.name,
+        created_at=row.created_at,
+    )
+
+
+@dataclass(slots=True)
+class SqlAlchemyOrganizationRepository:
+    session_factory: async_sessionmaker[AsyncSession]
+    model: type = field(default=DefaultOrganizationORM)
+    membership_model: type = field(default=DefaultMembershipORM)
+
+    async def get(self, org_id: OrgId) -> Organization | None:
+        async with self.session_factory() as session:
+            row = (
+                await session.execute(
+                    select(self.model).where(self.model.id == org_id.value)
+                )
+            ).scalar_one_or_none()
+            return _to_org(row) if row is not None else None
+
+    async def get_by_slug(self, slug: str) -> Organization | None:
+        async with self.session_factory() as session:
+            row = (
+                await session.execute(
+                    select(self.model).where(self.model.slug == slug)
+                )
+            ).scalar_one_or_none()
+            return _to_org(row) if row is not None else None
+
+    async def create(self, *, slug: str, name: str) -> Organization:
+        async with self.session_factory() as session:
+            row = self.model(slug=slug, name=name)
+            session.add(row)
+            await session.commit()
+            await session.refresh(row)
+            return _to_org(row)
+
+    async def update(
+        self, org_id: OrgId, *, name: str | None
+    ) -> Organization:
+        async with self.session_factory() as session:
+            values: dict[str, object] = {}
+            if name is not None:
+                values["name"] = name
+            if values:
+                await session.execute(
+                    update(self.model)
+                    .where(self.model.id == org_id.value)
+                    .values(**values)
+                )
+                await session.commit()
+            row = (
+                await session.execute(
+                    select(self.model).where(self.model.id == org_id.value)
+                )
+            ).scalar_one()
+            return _to_org(row)
+
+    async def delete(self, org_id: OrgId) -> None:
+        async with self.session_factory() as session:
+            await session.execute(
+                delete(self.model).where(self.model.id == org_id.value)
+            )
+            await session.commit()
+
+    async def list_for_user(self, user_id: UserId) -> list[Organization]:
+        async with self.session_factory() as session:
+            stmt = (
+                select(self.model)
+                .join(
+                    self.membership_model,
+                    self.membership_model.organization_id == self.model.id,
+                )
+                .where(self.membership_model.user_id == user_id.value)
+                .order_by(self.model.id)
+            )
+            rows = (await session.execute(stmt)).scalars().all()
+            return [_to_org(r) for r in rows]

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

@@ -0,0 +1,106 @@
+"""SQLAlchemy implementation of OrganizationServiceRepository."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+
+from sqlalchemy import delete, select
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from ....domain.entities import OrganizationService
+from ....domain.value_objects import OrgId, ServiceName
+from ..models import OrganizationServiceORM as DefaultOrganizationServiceORM
+
+
+def _to_entitlement(row: Any) -> 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 SqlAlchemyOrganizationServiceRepository:
+    session_factory: async_sessionmaker[AsyncSession]
+    model: type = field(default=DefaultOrganizationServiceORM)
+
+    async def list_enabled_service_names(self, org_id: OrgId) -> set[str]:
+        async with self.session_factory() as session:
+            stmt = select(self.model.service_name).where(
+                self.model.organization_id == org_id.value,
+                self.model.enabled.is_(True),
+            )
+            rows = (await session.execute(stmt)).scalars().all()
+            return set(rows)
+
+    async def get(
+        self, org_id: OrgId, service_name: ServiceName
+    ) -> OrganizationService | None:
+        async with self.session_factory() as session:
+            row = (
+                await session.execute(
+                    select(self.model).where(
+                        self.model.organization_id == org_id.value,
+                        self.model.service_name == str(service_name),
+                    )
+                )
+            ).scalar_one_or_none()
+            return _to_entitlement(row) if row is not None else None
+
+    async def enable(
+        self, org_id: OrgId, service_name: ServiceName, *, source: str
+    ) -> OrganizationService:
+        await self._upsert(org_id, [str(service_name)], source=source)
+        result = await self.get(org_id, service_name)
+        assert result is not None  # just upserted
+        return result
+
+    async def disable(
+        self, org_id: OrgId, service_name: ServiceName
+    ) -> None:
+        async with self.session_factory() as session:
+            await session.execute(
+                delete(self.model).where(
+                    self.model.organization_id == org_id.value,
+                    self.model.service_name == str(service_name),
+                )
+            )
+            await session.commit()
+
+    async def bulk_enable(
+        self,
+        org_id: OrgId,
+        service_names: Sequence[ServiceName],
+        *,
+        source: str,
+    ) -> None:
+        if not service_names:
+            return
+        await self._upsert(
+            org_id, [str(n) for n in service_names], source=source
+        )
+
+    async def _upsert(
+        self, org_id: OrgId, names: list[str], *, source: str
+    ) -> None:
+        rows = [
+            {
+                "organization_id": org_id.value,
+                "service_name": name,
+                "enabled": True,
+                "source": source,
+            }
+            for name in names
+        ]
+        stmt = pg_insert(self.model).values(rows)
+        stmt = stmt.on_conflict_do_update(
+            index_elements=["organization_id", "service_name"],
+            set_={"enabled": True, "source": stmt.excluded.source},
+        )
+        async with self.session_factory() as session:
+            await session.execute(stmt)
+            await session.commit()