pkg-auth 3.0.0__py3-none-any.whl

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

@@ -0,0 +1,127 @@
+"""SQLAlchemy implementation of PermissionCatalogRepository (UUID PKs, injectable model)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Sequence
+
+from sqlalchemy import delete, select
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from ....application.use_cases.register_permission_catalog import CatalogEntry
+from ....domain.entities import Permission
+from ....domain.ports import PermissionScope
+from ....domain.value_objects import (
+    LocalizedText,
+    PermissionId,
+    PermissionKey,
+    PermissionVisibility,
+)
+from ..models import PermissionORM as DefaultPermissionORM
+
+
+def _to_permission(row: Any) -> Permission:
+    return Permission(
+        id=PermissionId(row.id),
+        key=PermissionKey(row.key),
+        service_name=row.service_name,
+        description=LocalizedText(row.description or {}),
+        visibility=PermissionVisibility(row.visibility),
+    )
+
+
+def _scope_clause(model: type, scope: PermissionScope):
+    if scope in ("org", "tenant"):
+        return model.visibility.in_(
+            (PermissionVisibility.SHARED.value,
+             PermissionVisibility.TENANT_ONLY.value)
+        )
+    if scope == "platform":
+        return model.visibility.in_(
+            (PermissionVisibility.PLATFORM_ONLY.value,
+             PermissionVisibility.SHARED.value)
+        )
+    return None
+
+
+@dataclass(slots=True)
+class SqlAlchemyPermissionCatalogRepository:
+    session_factory: async_sessionmaker[AsyncSession]
+    model: type = field(default=DefaultPermissionORM)
+
+    async def register_many(
+        self,
+        *,
+        service_name: str,
+        entries: Sequence[CatalogEntry],
+    ) -> None:
+        if not entries:
+            return
+        rows = [
+            {
+                "key": str(entry.key),
+                "service_name": service_name,
+                "description": entry.description.as_dict() or None,
+                "visibility": entry.visibility.value,
+            }
+            for entry in entries
+        ]
+        stmt = pg_insert(self.model).values(rows)
+        stmt = stmt.on_conflict_do_update(
+            index_elements=["key"],
+            set_={
+                "service_name": stmt.excluded.service_name,
+                "description": stmt.excluded.description,
+                "visibility": stmt.excluded.visibility,
+            },
+        )
+        async with self.session_factory() as session:
+            await session.execute(stmt)
+            await session.commit()
+
+    async def list_all(
+        self, *, scope: PermissionScope = "all"
+    ) -> list[Permission]:
+        async with self.session_factory() as session:
+            stmt = select(self.model).order_by(self.model.id)
+            clause = _scope_clause(self.model, scope)
+            if clause is not None:
+                stmt = stmt.where(clause)
+            rows = (await session.execute(stmt)).scalars().all()
+            return [_to_permission(r) for r in rows]
+
+    async def list_for_service(
+        self, service_name: str, *, scope: PermissionScope = "all"
+    ) -> list[Permission]:
+        async with self.session_factory() as session:
+            stmt = (
+                select(self.model)
+                .where(self.model.service_name == service_name)
+                .order_by(self.model.id)
+            )
+            clause = _scope_clause(self.model, scope)
+            if clause is not None:
+                stmt = stmt.where(clause)
+            rows = (await session.execute(stmt)).scalars().all()
+            return [_to_permission(r) for r in rows]
+
+    async def get_service_map(self) -> dict[str, str]:
+        async with self.session_factory() as session:
+            stmt = select(self.model.key, self.model.service_name)
+            rows = (await session.execute(stmt)).all()
+            return {key: service_name for key, service_name in rows}
+
+    async def prune_absent(
+        self,
+        *,
+        service_name: str,
+        keep_keys: Iterable[PermissionKey],
+    ) -> int:
+        keys = [str(k) for k in keep_keys]
+        stmt = delete(self.model).where(self.model.service_name == service_name)
+        if keys:
+            stmt = stmt.where(self.model.key.notin_(keys))
+        async with self.session_factory() as session:
+            result = await session.execute(stmt)
+            await session.commit()
+            return int(result.rowcount or 0)

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

@@ -0,0 +1,171 @@
+"""SQLAlchemy implementation of RoleRepository (UUID PKs, injectable model)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+
+from sqlalchemy import delete, select, update
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from sqlalchemy.orm import selectinload
+
+from ....domain.entities import Role
+from ....domain.value_objects import (
+    OrgId,
+    PermissionKey,
+    RoleId,
+    RoleName,
+)
+from ..models import PermissionORM as DefaultPermissionORM
+from ..models import RoleORM as DefaultRoleORM
+
+
+def _to_role(row: Any) -> Role:
+    return Role(
+        id=RoleId(row.id),
+        organization_id=(
+            OrgId(row.organization_id) if row.organization_id is not None else None
+        ),
+        name=RoleName(row.name),
+        description=row.description,
+        permission_keys=frozenset(p.key for p in row.permissions),
+    )
+
+
+@dataclass(slots=True)
+class SqlAlchemyRoleRepository:
+    session_factory: async_sessionmaker[AsyncSession]
+    model: type = field(default=DefaultRoleORM)
+    permission_model: type = field(default=DefaultPermissionORM)
+
+    async def get(self, role_id: RoleId) -> Role | None:
+        async with self.session_factory() as session:
+            row = (
+                await session.execute(
+                    select(self.model)
+                    .options(selectinload(self.model.permissions))
+                    .where(self.model.id == role_id.value)
+                )
+            ).scalar_one_or_none()
+            return _to_role(row) if row is not None else None
+
+    async def get_by_name(
+        self, org_id: OrgId | None, name: RoleName
+    ) -> Role | None:
+        async with self.session_factory() as session:
+            cond = (
+                self.model.organization_id.is_(None)
+                if org_id is None
+                else self.model.organization_id == org_id.value
+            )
+            row = (
+                await session.execute(
+                    select(self.model)
+                    .options(selectinload(self.model.permissions))
+                    .where(cond, self.model.name == str(name))
+                )
+            ).scalar_one_or_none()
+            return _to_role(row) if row is not None else None
+
+    async def create(
+        self,
+        *,
+        org_id: OrgId | None,
+        name: RoleName,
+        description: str | None,
+        permission_keys: Sequence[PermissionKey],
+    ) -> Role:
+        async with self.session_factory() as session:
+            perm_rows: list[Any] = []
+            if permission_keys:
+                key_strs = [str(k) for k in permission_keys]
+                perm_rows = list(
+                    (
+                        await session.execute(
+                            select(self.permission_model).where(
+                                self.permission_model.key.in_(key_strs)
+                            )
+                        )
+                    )
+                    .scalars()
+                    .all()
+                )
+
+            row = self.model(
+                organization_id=org_id.value if org_id is not None else None,
+                name=str(name),
+                description=description,
+            )
+            row.permissions = perm_rows
+            session.add(row)
+            await session.commit()
+            row = (
+                await session.execute(
+                    select(self.model)
+                    .options(selectinload(self.model.permissions))
+                    .where(self.model.id == row.id)
+                )
+            ).scalar_one()
+            return _to_role(row)
+
+    async def update(
+        self,
+        role_id: RoleId,
+        *,
+        name: RoleName | None,
+        description: str | None,
+        permission_keys: Sequence[PermissionKey] | None,
+    ) -> Role:
+        async with self.session_factory() as session:
+            values: dict[str, object] = {}
+            if name is not None:
+                values["name"] = str(name)
+            if description is not None:
+                values["description"] = description
+            if values:
+                await session.execute(
+                    update(self.model)
+                    .where(self.model.id == role_id.value)
+                    .values(**values)
+                )
+
+            if permission_keys is not None:
+                row = (
+                    await session.execute(
+                        select(self.model)
+                        .options(selectinload(self.model.permissions))
+                        .where(self.model.id == role_id.value)
+                    )
+                ).scalar_one()
+                key_strs = [str(k) for k in permission_keys]
+                if key_strs:
+                    new_perms = list(
+                        (
+                            await session.execute(
+                                select(self.permission_model).where(
+                                    self.permission_model.key.in_(key_strs)
+                                )
+                            )
+                        )
+                        .scalars()
+                        .all()
+                    )
+                else:
+                    new_perms = []
+                row.permissions = new_perms
+
+            await session.commit()
+            row = (
+                await session.execute(
+                    select(self.model)
+                    .options(selectinload(self.model.permissions))
+                    .where(self.model.id == role_id.value)
+                )
+            ).scalar_one()
+            return _to_role(row)
+
+    async def delete(self, role_id: RoleId) -> None:
+        async with self.session_factory() as session:
+            await session.execute(
+                delete(self.model).where(self.model.id == role_id.value)
+            )
+            await session.commit()

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

@@ -0,0 +1,93 @@
+"""SQLAlchemy implementation of ServiceRepository (UUID PKs, injectable model)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Sequence
+
+from sqlalchemy import delete, select
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from ....application.use_cases.sync_service_catalog import ServiceSpec
+from ....domain.entities import Service
+from ....domain.value_objects import LocalizedText, ServiceName
+from ..models import ServiceORM as DefaultServiceORM
+
+
+def _to_service(row: Any) -> 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 SqlAlchemyServiceRepository:
+    session_factory: async_sessionmaker[AsyncSession]
+    model: type = field(default=DefaultServiceORM)
+
+    async def upsert_many(self, services: Sequence[ServiceSpec]) -> None:
+        if not services:
+            return
+        rows = [
+            {
+                "name": str(s.name),
+                "display_label": s.display_label.as_dict() or None,
+                "auto_provision": s.auto_provision,
+                "saas_available": s.saas_available,
+            }
+            for s in services
+        ]
+        stmt = pg_insert(self.model).values(rows)
+        stmt = stmt.on_conflict_do_update(
+            index_elements=["name"],
+            set_={
+                "display_label": stmt.excluded.display_label,
+                "auto_provision": stmt.excluded.auto_provision,
+                "saas_available": stmt.excluded.saas_available,
+            },
+        )
+        async with self.session_factory() as session:
+            await session.execute(stmt)
+            await session.commit()
+
+    async def ensure_exists(self, *, service_name: str) -> None:
+        """Insert a bare service row if missing; never overwrite vendor flags."""
+        stmt = pg_insert(self.model).values(
+            name=service_name,
+            auto_provision=False,
+            saas_available=False,
+        )
+        stmt = stmt.on_conflict_do_nothing(index_elements=["name"])
+        async with self.session_factory() as session:
+            await session.execute(stmt)
+            await session.commit()
+
+    async def get(self, name: ServiceName) -> Service | None:
+        async with self.session_factory() as session:
+            row = (
+                await session.execute(
+                    select(self.model).where(self.model.name == str(name))
+                )
+            ).scalar_one_or_none()
+            return _to_service(row) if row is not None else None
+
+    async def list_all(self) -> list[Service]:
+        async with self.session_factory() as session:
+            rows = (
+                await session.execute(select(self.model).order_by(self.model.name))
+            ).scalars().all()
+            return [_to_service(r) for r in rows]
+
+    async def prune_absent(self, *, keep: Iterable[ServiceName]) -> int:
+        names = [str(n) for n in keep]
+        stmt = delete(self.model)
+        if names:
+            stmt = stmt.where(self.model.name.notin_(names))
+        async with self.session_factory() as session:
+            result = await session.execute(stmt)
+            await session.commit()
+            return int(result.rowcount or 0)

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

@@ -0,0 +1,74 @@
+"""SQLAlchemy implementation of UserRepository (UUID PKs, injectable model)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy import func, select
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from ....domain.entities import User
+from ....domain.value_objects import UserId
+from ..models import UserORM as DefaultUserORM
+
+
+def _to_user(row: Any) -> User:
+    return User(
+        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 SqlAlchemyUserRepository:
+    session_factory: async_sessionmaker[AsyncSession]
+    model: type = field(default=DefaultUserORM)
+
+    async def get_by_id(self, user_id: UserId) -> User | None:
+        async with self.session_factory() as session:
+            row = (
+                await session.execute(
+                    select(self.model).where(self.model.id == user_id.value)
+                )
+            ).scalar_one_or_none()
+            return _to_user(row) if row is not None else None
+
+    async def get_by_keycloak_sub(self, sub: str) -> User | None:
+        async with self.session_factory() as session:
+            row = (
+                await session.execute(
+                    select(self.model).where(self.model.keycloak_sub == sub)
+                )
+            ).scalar_one_or_none()
+            return _to_user(row) if row is not None else None
+
+    async def upsert_from_identity(
+        self,
+        *,
+        sub: str,
+        email: str,
+        full_name: str | None,
+    ) -> User:
+        stmt = (
+            pg_insert(self.model)
+            .values(keycloak_sub=sub, email=email, full_name=full_name)
+            .on_conflict_do_update(
+                index_elements=["keycloak_sub"],
+                set_={
+                    "email": email,
+                    "full_name": full_name,
+                    "last_seen_at": func.now(),
+                },
+            )
+            .returning(self.model)
+        )
+        async with self.session_factory() as session:
+            result = await session.execute(stmt)
+            await session.commit()
+            row = result.scalar_one()
+            return _to_user(row)

pkg_auth/authorization/application/__init__.py

@@ -0,0 +1 @@
+"""Authorization application layer (use cases)."""

pkg_auth/authorization/application/use_cases/__init__.py

@@ -0,0 +1 @@
+"""Authorization use cases."""

pkg_auth/authorization/application/use_cases/_helpers.py

@@ -0,0 +1,82 @@
+"""Internal helpers shared across authorization use cases.
+
+The leading underscore signals "internal" — these are not part of the
+public application API and may change between versions.
+"""
+from __future__ import annotations
+
+from typing import Sequence
+
+from ...domain.exceptions import (
+    PermissionVisibilityConflict,
+    UnknownPermission,
+)
+from ...domain.ports import PermissionCatalogRepository
+from ...domain.value_objects import PermissionKey, PermissionVisibility
+
+
+async def validate_permission_keys_exist(
+    catalog_repo: PermissionCatalogRepository,
+    keys: Sequence[PermissionKey],
+) -> None:
+    """Raise :class:`UnknownPermission` if any key is not in the catalog.
+
+    Used by :class:`CreateRoleUseCase` and :class:`UpdateRoleUseCase` to
+    enforce that role definitions only reference perms that some service
+    has actually registered.
+    """
+    if not keys:
+        return
+    all_perms = await catalog_repo.list_all()
+    known_keys = {str(p.key) for p in all_perms}
+    unknown = sorted(str(k) for k in keys if str(k) not in known_keys)
+    if unknown:
+        raise UnknownPermission(
+            f"unknown permission key(s): {unknown}"
+        )
+
+
+async def validate_permission_keys_for_role(
+    catalog_repo: PermissionCatalogRepository,
+    keys: Sequence[PermissionKey],
+    *,
+    is_platform_org: bool | None,
+) -> None:
+    """Validate permission keys for a role, enforcing visibility.
+
+    Always checks existence. When ``is_platform_org`` is not ``None`` (i.e.
+    a platform org id is configured and the role is org-scoped), it also
+    rejects cross-visibility assignment:
+
+    - a platform-org role may not use ``TENANT_ONLY`` perms;
+    - a normal-org role may not use ``PLATFORM_ONLY`` perms.
+
+    Pass ``is_platform_org=None`` for global role templates (org_id is None)
+    or when no platform org is configured — only existence is checked, which
+    preserves the pre-visibility behavior.
+    """
+    if not keys:
+        return
+    all_perms = await catalog_repo.list_all()
+    by_key = {str(p.key): p for p in all_perms}
+    unknown = sorted(str(k) for k in keys if str(k) not in by_key)
+    if unknown:
+        raise UnknownPermission(f"unknown permission key(s): {unknown}")
+
+    if is_platform_org is None:
+        return
+
+    forbidden = (
+        PermissionVisibility.TENANT_ONLY
+        if is_platform_org
+        else PermissionVisibility.PLATFORM_ONLY
+    )
+    violators = sorted(
+        str(k) for k in keys if by_key[str(k)].visibility == forbidden
+    )
+    if violators:
+        scope = "platform" if is_platform_org else "normal"
+        raise PermissionVisibilityConflict(
+            f"{forbidden.value} permission(s) {violators} cannot be assigned "
+            f"to a role in a {scope} organization"
+        )

pkg_auth/authorization/application/use_cases/check_permission.py

@@ -0,0 +1,21 @@
+"""Check that an :class:`AuthContext` grants a specific permission."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.entities import AuthContext
+
+
+@dataclass(slots=True)
+class CheckPermissionUseCase:
+    """Pure wrapper around :meth:`AuthContext.require`.
+
+    Exists as a use case mostly for symmetry with the rest of the
+    application layer — most call sites will use ``ctx.require(perm)``
+    directly. Provided here for services that prefer a use-case-shaped
+    API or want to add cross-cutting behavior (audit logging, metrics)
+    via decoration.
+    """
+
+    async def execute(self, ctx: AuthContext, perm: str) -> None:
+        ctx.require(perm)

pkg_auth/authorization/application/use_cases/create_organization.py

@@ -0,0 +1,41 @@
+"""Create an organization."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.entities import Organization
+from ...domain.ports import (
+    OrganizationRepository,
+    OrganizationServiceRepository,
+    ServiceRepository,
+)
+from .provision_default_services import ProvisionDefaultServicesUseCase
+
+
+@dataclass(slots=True)
+class CreateOrganizationUseCase:
+    """Create a new organization.
+
+    Slug uniqueness is enforced at the database level by a UNIQUE
+    constraint; the repository may raise a conflict error which the
+    integration layer can map to HTTP 409.
+
+    When ``service_repo`` and ``org_service_repo`` are wired, every
+    ``auto_provision`` service is enabled for the new org (so default-deny
+    members still get the default product surfaces). Leaving them unset
+    skips provisioning — Mode A services that own their own create flow call
+    :class:`ProvisionDefaultServicesUseCase` themselves instead.
+    """
+
+    organization_repo: OrganizationRepository
+    service_repo: ServiceRepository | None = None
+    org_service_repo: OrganizationServiceRepository | None = None
+
+    async def execute(self, *, slug: str, name: str) -> Organization:
+        org = await self.organization_repo.create(slug=slug, name=name)
+        if self.service_repo is not None and self.org_service_repo is not None:
+            await ProvisionDefaultServicesUseCase(
+                service_repo=self.service_repo,
+                org_service_repo=self.org_service_repo,
+            ).execute(org_id=org.id)
+        return org

pkg_auth/authorization/application/use_cases/create_role.py

@@ -0,0 +1,69 @@
+"""Create a role with a set of permissions."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+from ...domain.entities import Role
+from ...domain.exceptions import UnknownOrganization
+from ...domain.ports import (
+    OrganizationRepository,
+    PermissionCatalogRepository,
+    RoleRepository,
+)
+from ...domain.value_objects import OrgId, PermissionKey, RoleName
+from ._helpers import validate_permission_keys_for_role
+
+
+@dataclass(slots=True)
+class CreateRoleUseCase:
+    """Create a new role under an organization (or as a global template).
+
+    Validates:
+        - the organization exists (when ``org_id`` is not ``None``)
+        - every referenced permission key is registered in the catalog
+        - permission visibility matches the role's org (when
+          ``platform_org_id`` is configured): a platform-org role may not use
+          ``tenant_only`` perms; a normal-org role may not use
+          ``platform_only`` perms.
+    """
+
+    organization_repo: OrganizationRepository
+    role_repo: RoleRepository
+    catalog_repo: PermissionCatalogRepository
+    platform_org_id: OrgId | None = None
+
+    async def execute(
+        self,
+        *,
+        org_id: OrgId | None,
+        name: RoleName,
+        description: str | None,
+        permission_keys: Sequence[PermissionKey],
+    ) -> Role:
+        if org_id is not None:
+            if await self.organization_repo.get(org_id) is None:
+                raise UnknownOrganization(f"organization {org_id} not found")
+
+        await validate_permission_keys_for_role(
+            self.catalog_repo,
+            permission_keys,
+            is_platform_org=self._is_platform_org(org_id),
+        )
+
+        return await self.role_repo.create(
+            org_id=org_id,
+            name=name,
+            description=description,
+            permission_keys=permission_keys,
+        )
+
+    def _is_platform_org(self, org_id: OrgId | None) -> bool | None:
+        """``True``/``False`` when visibility should be enforced, else ``None``.
+
+        Returns ``None`` for global templates (org_id is None) or when no
+        platform org is configured, so only existence is checked.
+        """
+        if org_id is None or self.platform_org_id is None:
+            return None
+        return org_id == self.platform_org_id