pkg-auth 3.0.0__py3-none-any.whl

pkg_auth/authorization/application/use_cases/delete_membership.py

@@ -0,0 +1,21 @@
+"""Remove a membership row."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.ports import MembershipRepository
+from ...domain.value_objects import OrgId, UserId
+
+
+@dataclass(slots=True)
+class DeleteMembershipUseCase:
+    """Idempotently remove a user's membership in an organization.
+
+    Calling on a non-existent membership is a no-op (does not raise),
+    so this can be safely retried.
+    """
+
+    membership_repo: MembershipRepository
+
+    async def execute(self, *, user_id: UserId, org_id: OrgId) -> None:
+        await self.membership_repo.delete(user_id, org_id)

pkg_auth/authorization/application/use_cases/delete_organization.py

@@ -0,0 +1,21 @@
+"""Delete an organization (and cascade memberships, roles)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.ports import OrganizationRepository
+from ...domain.value_objects import OrgId
+
+
+@dataclass(slots=True)
+class DeleteOrganizationUseCase:
+    """Idempotently delete an organization.
+
+    Cascades to memberships and org-scoped roles via DB-level
+    ``ON DELETE CASCADE``. Calling on a non-existent org is a no-op.
+    """
+
+    organization_repo: OrganizationRepository
+
+    async def execute(self, org_id: OrgId) -> None:
+        await self.organization_repo.delete(org_id)

pkg_auth/authorization/application/use_cases/delete_role.py

@@ -0,0 +1,23 @@
+"""Delete a role (and cascade-detach any memberships)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.ports import RoleRepository
+from ...domain.value_objects import RoleId
+
+
+@dataclass(slots=True)
+class DeleteRoleUseCase:
+    """Idempotently delete a role.
+
+    The DB schema uses ``ON DELETE RESTRICT`` for membership FKs to the
+    role; if any memberships still reference this role, the repository
+    raises a conflict error which the integration layer can map to
+    HTTP 409. Callers must reassign or remove memberships first.
+    """
+
+    role_repo: RoleRepository
+
+    async def execute(self, role_id: RoleId) -> None:
+        await self.role_repo.delete(role_id)

pkg_auth/authorization/application/use_cases/list_user_organizations.py

@@ -0,0 +1,21 @@
+"""List the organizations a user belongs to."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.entities import Organization
+from ...domain.ports import OrganizationRepository
+from ...domain.value_objects import UserId
+
+
+@dataclass(slots=True)
+class ListUserOrganizationsUseCase:
+    """Return the organizations a user has any membership in.
+
+    Used by "switch organization" UIs in client apps.
+    """
+
+    organization_repo: OrganizationRepository
+
+    async def execute(self, user_id: UserId) -> list[Organization]:
+        return await self.organization_repo.list_for_user(user_id)

pkg_auth/authorization/application/use_cases/provision_default_services.py

@@ -0,0 +1,38 @@
+"""Provision the default (auto-provision) services for an organization."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.ports import (
+    OrganizationServiceRepository,
+    ServiceRepository,
+)
+from ...domain.value_objects import OrgId
+
+
+@dataclass(slots=True)
+class ProvisionDefaultServicesUseCase:
+    """Enable every ``auto_provision`` service for an organization.
+
+    Called on organization creation (wired into pkg_auth's own
+    :class:`CreateOrganizationUseCase`; Mode A services call it from their
+    own org-creation flow). Idempotent — re-running only re-enables the same
+    default set with ``source="auto"``.
+
+    Under the default-deny service guard, an org that never runs this (and is
+    never granted services manually) resolves to zero permissions for normal
+    members. Mark core services (e.g. ``users``) ``auto_provision=True`` so
+    every org gets them.
+    """
+
+    service_repo: ServiceRepository
+    org_service_repo: OrganizationServiceRepository
+
+    async def execute(self, *, org_id: OrgId) -> list[str]:
+        services = await self.service_repo.list_all()
+        names = [s.name for s in services if s.auto_provision]
+        if names:
+            await self.org_service_repo.bulk_enable(
+                org_id, names, source="auto"
+            )
+        return [str(n) for n in names]

pkg_auth/authorization/application/use_cases/register_permission_catalog.py

@@ -0,0 +1,122 @@
+"""Register a service's permission catalog at startup."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping, Sequence, Union
+
+from ...config import default_locale
+from ...domain.ports import PermissionCatalogRepository, ServiceRepository
+from ...domain.value_objects import (
+    LocalizedText,
+    PermissionKey,
+    PermissionVisibility,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogEntry:
+    """One row a service registers into the central permission catalog.
+
+    ``visibility`` controls which role builders may see/use the permission:
+
+    - ``SHARED`` (default) — usable everywhere.
+    - ``PLATFORM_ONLY`` — only the platform org (e.g. ``organizations:create``).
+    - ``TENANT_ONLY`` — only normal orgs; hidden from the platform org.
+
+    ``description`` is a :class:`LocalizedText` locale→text map. Build entries
+    with :meth:`make` to accept a plain string (stored under the configured
+    default locale) or a ``{locale: text}`` dict.
+    """
+
+    key: PermissionKey
+    description: LocalizedText = field(default_factory=lambda: LocalizedText({}))
+    visibility: PermissionVisibility = PermissionVisibility.SHARED
+
+    def __post_init__(self) -> None:
+        # Coerce a plain string / dict / None description into LocalizedText
+        # so positional ``CatalogEntry(key, "text")`` stays ergonomic.
+        if not isinstance(self.description, LocalizedText):
+            object.__setattr__(
+                self,
+                "description",
+                LocalizedText.from_input(
+                    self.description, default_locale=default_locale()
+                ),
+            )
+
+    @classmethod
+    def make(
+        cls,
+        key: PermissionKey,
+        description: "LocalizedText | Mapping[str, str] | str | None" = None,
+        visibility: PermissionVisibility = PermissionVisibility.SHARED,
+        *,
+        default_locale_: str | None = None,
+    ) -> "CatalogEntry":
+        """Ergonomic constructor that coerces ``description`` into a
+        :class:`LocalizedText` using the configured default locale.
+        """
+        loc = default_locale_ or default_locale()
+        return cls(
+            key=key,
+            description=LocalizedText.from_input(description, default_locale=loc),
+            visibility=visibility,
+        )
+
+
+CatalogEntryInput = Union[
+    CatalogEntry,
+    tuple[PermissionKey, "LocalizedText | Mapping[str, str] | str | None"],
+    tuple[
+        PermissionKey,
+        "LocalizedText | Mapping[str, str] | str | None",
+        PermissionVisibility,
+    ],
+]
+
+
+def _normalize_entry(entry: CatalogEntryInput) -> CatalogEntry:
+    if isinstance(entry, CatalogEntry):
+        return entry
+    if isinstance(entry, tuple):
+        if len(entry) == 2:
+            key, description = entry
+            return CatalogEntry.make(key, description)
+        if len(entry) == 3:
+            key, description, visibility = entry
+            return CatalogEntry.make(key, description, visibility)
+        raise ValueError(f"Invalid catalog entry tuple length: {len(entry)}")
+    raise TypeError(f"Unsupported catalog entry type: {type(entry).__name__}")
+
+
+@dataclass(slots=True)
+class RegisterPermissionCatalogUseCase:
+    """Idempotently register the permission keys a service knows about.
+
+    Each consuming service calls this on boot with its static perm
+    list. The repository upserts by ``key`` so calling it on every
+    restart is safe and converges. Re-registering the same key with a
+    different ``visibility`` flips it.
+
+    When a ``service_repo`` is wired, a bare ``services`` row is ensured for
+    ``service_name`` (safe defaults, never overwriting vendor flags) so the
+    default-deny service guard does not strip the service's perms before the
+    vendor configures it.
+    """
+
+    catalog_repo: PermissionCatalogRepository
+    service_repo: ServiceRepository | None = None
+
+    async def execute(
+        self,
+        *,
+        service_name: str,
+        entries: Sequence[CatalogEntryInput],
+    ) -> None:
+        normalized = [_normalize_entry(e) for e in entries]
+        if self.service_repo is not None:
+            await self.service_repo.ensure_exists(service_name=service_name)
+        await self.catalog_repo.register_many(
+            service_name=service_name,
+            entries=normalized,
+        )

pkg_auth/authorization/application/use_cases/resolve_auth_context.py

@@ -0,0 +1,70 @@
+"""Resolve an :class:`AuthContext` for a (user, organization) pair."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.entities import AuthContext
+from ...domain.exceptions import NotAMember
+from ...domain.ports import (
+    MembershipRepository,
+    OrganizationServiceRepository,
+    PermissionCatalogRepository,
+)
+from ...domain.value_objects import OrgId, UserId
+
+
+@dataclass(slots=True)
+class ResolveAuthContextUseCase:
+    """Hot-path use case: load the AuthContext for a request.
+
+    Called once per protected request by the FastAPI / Django / Strawberry
+    deps. The membership repository is responsible for joining the role
+    and its permissions in a single query so this is a single network
+    round-trip to Postgres (or a hit on the cache decorator).
+
+    **Service guard.** When ``org_service_repo`` and ``catalog_repo`` are
+    wired, the resolved permissions are filtered down to the services the
+    organization actually has enabled (**default-deny**: a perm whose owning
+    service is not enabled for the org is dropped). The platform org — when
+    its id is passed as ``platform_org_id`` — bypasses the guard entirely so
+    platform admins keep all permissions. Leaving the guard repos unset
+    preserves the pre-guard behavior (no filtering), which lets services
+    adopt the guard incrementally.
+    """
+
+    membership_repo: MembershipRepository
+    org_service_repo: OrganizationServiceRepository | None = None
+    catalog_repo: PermissionCatalogRepository | None = None
+    platform_org_id: OrgId | None = None
+
+    async def execute(self, user_id: UserId, org_id: OrgId) -> AuthContext:
+        ctx = await self.membership_repo.load_auth_context(user_id, org_id)
+        if ctx is None:
+            raise NotAMember(
+                f"user {user_id} is not a member of org {org_id}"
+            )
+        return await self._apply_service_guard(ctx, org_id)
+
+    async def _apply_service_guard(
+        self, ctx: AuthContext, org_id: OrgId
+    ) -> AuthContext:
+        if self.org_service_repo is None or self.catalog_repo is None:
+            return ctx  # guard not wired
+        if self.platform_org_id is not None and org_id == self.platform_org_id:
+            return ctx  # platform admins bypass the guard
+        if not ctx.perms:
+            return ctx
+
+        enabled = await self.org_service_repo.list_enabled_service_names(org_id)
+        service_map = await self.catalog_repo.get_service_map()
+        allowed = frozenset(
+            perm for perm in ctx.perms if service_map.get(perm) in enabled
+        )
+        if allowed == ctx.perms:
+            return ctx
+        return AuthContext(
+            user_id=ctx.user_id,
+            organization_id=ctx.organization_id,
+            role_names=ctx.role_names,
+            perms=allowed,
+        )

pkg_auth/authorization/application/use_cases/resolve_user_from_jwt.py

@@ -0,0 +1,34 @@
+"""Resolve a local user from a Keycloak JWT identity (read-only, Mode B)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.entities import User
+from ...domain.exceptions import UserNotProvisioned
+from ...domain.ports import UserRepository
+
+
+@dataclass(slots=True)
+class ResolveUserFromJwtUseCase:
+    """Look up a local ``users`` row by Keycloak ``sub`` without writing.
+
+    Use this in Mode B (consuming) services whose ``ACL_DATABASE_URL``
+    points at a Mode A-owned database. Writing the ``users`` table is
+    the source-of-truth service's job; a Mode B consumer that has never
+    seen a given ``sub`` means the SoT hasn't provisioned them yet —
+    which is a 403, not a signal to insert.
+
+    Raises :class:`UserNotProvisioned` when no row exists for ``sub``.
+    Integration layers map that to HTTP 403.
+    """
+
+    user_repo: UserRepository
+
+    async def execute(self, *, sub: str) -> User:
+        user = await self.user_repo.get_by_keycloak_sub(sub)
+        if user is None:
+            raise UserNotProvisioned(
+                f"No local user for Keycloak sub {sub!r}; "
+                "source-of-truth service has not provisioned this user yet."
+            )
+        return user

pkg_auth/authorization/application/use_cases/set_organization_service.py

@@ -0,0 +1,50 @@
+"""Enable/disable a service for an organization (SaaS governance)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.entities import OrganizationService
+from ...domain.exceptions import ServiceNotSaaSAvailable, UnknownService
+from ...domain.ports import (
+    OrganizationServiceRepository,
+    ServiceRepository,
+)
+from ...domain.value_objects import OrgId, ServiceName
+
+
+@dataclass(slots=True)
+class SetOrganizationServiceUseCase:
+    """Toggle a service for an organization, enforcing vendor SaaS policy.
+
+    This is what a platform-admin API endpoint calls. Enabling is rejected
+    with :class:`ServiceNotSaaSAvailable` unless the service is marked
+    ``saas_available`` by the vendor (via ``pkg-auth-sync-services``), which
+    is how the package owner keeps the client from offering arbitrary
+    services as SaaS. Disabling is always allowed.
+    """
+
+    service_repo: ServiceRepository
+    org_service_repo: OrganizationServiceRepository
+
+    async def execute(
+        self,
+        *,
+        org_id: OrgId,
+        service_name: ServiceName,
+        enabled: bool,
+    ) -> OrganizationService | None:
+        service = await self.service_repo.get(service_name)
+        if service is None:
+            raise UnknownService(f"service {service_name} is not registered")
+
+        if not enabled:
+            await self.org_service_repo.disable(org_id, service_name)
+            return None
+
+        if not service.saas_available:
+            raise ServiceNotSaaSAvailable(
+                f"service {service_name} is not available to offer as SaaS"
+            )
+        return await self.org_service_repo.enable(
+            org_id, service_name, source="manual"
+        )

pkg_auth/authorization/application/use_cases/sync_permission_catalog.py

@@ -0,0 +1,86 @@
+"""Sync a service's permission catalog — upsert declared keys, prune absent ones.
+
+Use from a deploy-time init container with a DB credential that has
+``INSERT, UPDATE, DELETE`` on ``permissions``. Runtime service credentials
+should remain SELECT-only and use :class:`RegisterPermissionCatalogUseCase`
+(or nothing at all) instead.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+from ...domain.ports import PermissionCatalogRepository, ServiceRepository
+from .register_permission_catalog import (
+    CatalogEntry,
+    CatalogEntryInput,
+    _normalize_entry,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class SyncResult:
+    """Outcome of a catalog sync run.
+
+    For non-dry-runs, ``upserted`` is the number of declared entries
+    (all of them are UPSERTed unconditionally by ``register_many``) and
+    ``pruned`` is the number of DB rows deleted. For dry-runs, both
+    numbers are the *would-be* counts computed from a diff against the
+    current DB state; no writes happen.
+    """
+
+    upserted: int
+    pruned: int
+    dry_run: bool
+
+
+@dataclass(slots=True)
+class SyncPermissionCatalogUseCase:
+    """Upsert declared entries then delete anything for the service that is
+    no longer declared.
+
+    Scoped by ``service_name`` so running sync for ``courses`` will never
+    touch permissions owned by other services (e.g. ``users:*``).
+    """
+
+    catalog_repo: PermissionCatalogRepository
+    service_repo: ServiceRepository | None = None
+
+    async def execute(
+        self,
+        *,
+        service_name: str,
+        entries: Sequence[CatalogEntryInput],
+        dry_run: bool = False,
+    ) -> SyncResult:
+        normalized: list[CatalogEntry] = [_normalize_entry(e) for e in entries]
+        keep_keys = [e.key for e in normalized]
+
+        if dry_run:
+            existing = await self.catalog_repo.list_for_service(
+                service_name, scope="all"
+            )
+            existing_keys = {str(p.key) for p in existing}
+            declared_keys = {str(k) for k in keep_keys}
+            would_prune = existing_keys - declared_keys
+            return SyncResult(
+                upserted=len(normalized),
+                pruned=len(would_prune),
+                dry_run=True,
+            )
+
+        if self.service_repo is not None:
+            await self.service_repo.ensure_exists(service_name=service_name)
+        await self.catalog_repo.register_many(
+            service_name=service_name,
+            entries=normalized,
+        )
+        pruned = await self.catalog_repo.prune_absent(
+            service_name=service_name,
+            keep_keys=keep_keys,
+        )
+        return SyncResult(
+            upserted=len(normalized),
+            pruned=pruned,
+            dry_run=False,
+        )

pkg_auth/authorization/application/use_cases/sync_service_catalog.py

@@ -0,0 +1,91 @@
+"""Sync the vendor-declared service registry.
+
+This is the **only** path that sets the vendor-controlled flags
+``auto_provision`` and ``saas_available`` on a service. Run it from a
+deploy-time init container / CLI (``pkg-auth-sync-services``) with a DB
+credential that may write the ``services`` table — never from a runtime
+API. Runtime service enablement for an org goes through
+:class:`SetOrganizationServiceUseCase`, which can only toggle services
+already marked ``saas_available`` here.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping, Sequence, Union
+
+from ...config import default_locale
+from ...domain.ports import ServiceRepository
+from ...domain.value_objects import LocalizedText, ServiceName
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceSpec:
+    """One row the vendor declares into the service registry."""
+
+    name: ServiceName
+    display_label: LocalizedText = field(
+        default_factory=lambda: LocalizedText({})
+    )
+    auto_provision: bool = False
+    saas_available: bool = False
+
+    @classmethod
+    def make(
+        cls,
+        name: ServiceName | str,
+        display_label: "LocalizedText | Mapping[str, str] | str | None" = None,
+        *,
+        auto_provision: bool = False,
+        saas_available: bool = False,
+        default_locale_: str | None = None,
+    ) -> "ServiceSpec":
+        loc = default_locale_ or default_locale()
+        return cls(
+            name=name if isinstance(name, ServiceName) else ServiceName(name),
+            display_label=LocalizedText.from_input(
+                display_label, default_locale=loc
+            ),
+            auto_provision=auto_provision,
+            saas_available=saas_available,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceSyncResult:
+    upserted: int
+    pruned: int
+    dry_run: bool
+
+
+@dataclass(slots=True)
+class SyncServiceCatalogUseCase:
+    """Upsert declared services then prune services no longer declared."""
+
+    service_repo: ServiceRepository
+
+    async def execute(
+        self,
+        *,
+        services: Sequence[ServiceSpec],
+        dry_run: bool = False,
+    ) -> ServiceSyncResult:
+        keep = [s.name for s in services]
+
+        if dry_run:
+            existing = await self.service_repo.list_all()
+            existing_names = {str(s.name) for s in existing}
+            declared_names = {str(n) for n in keep}
+            would_prune = existing_names - declared_names
+            return ServiceSyncResult(
+                upserted=len(services),
+                pruned=len(would_prune),
+                dry_run=True,
+            )
+
+        await self.service_repo.upsert_many(services)
+        pruned = await self.service_repo.prune_absent(keep=keep)
+        return ServiceSyncResult(
+            upserted=len(services),
+            pruned=pruned,
+            dry_run=False,
+        )

pkg_auth/authorization/application/use_cases/sync_user_from_jwt.py

@@ -0,0 +1,32 @@
+"""Sync a user record from a Keycloak JWT identity (lazy upsert)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.entities import User
+from ...domain.ports import UserRepository
+
+
+@dataclass(slots=True)
+class SyncUserFromJwtUseCase:
+    """Upsert a row in ``acl.users`` from JWT identity claims.
+
+    Called by integration deps the first time they see a JWT for a given
+    Keycloak ``sub``. Idempotent: subsequent calls update ``email`` /
+    ``full_name`` / ``last_seen_at`` but never change the user ``id``.
+    """
+
+    user_repo: UserRepository
+
+    async def execute(
+        self,
+        *,
+        sub: str,
+        email: str,
+        full_name: str | None,
+    ) -> User:
+        return await self.user_repo.upsert_from_identity(
+            sub=sub,
+            email=email,
+            full_name=full_name,
+        )

pkg_auth/authorization/application/use_cases/update_organization.py

@@ -0,0 +1,31 @@
+"""Update an organization's metadata."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.entities import Organization
+from ...domain.exceptions import UnknownOrganization
+from ...domain.ports import OrganizationRepository
+from ...domain.value_objects import OrgId
+
+
+@dataclass(slots=True)
+class UpdateOrganizationUseCase:
+    """Update an organization's display name.
+
+    The slug is intentionally immutable (changing it would break URLs
+    and ``X-Organization-Id`` headers in flight). Pass ``name=None`` to
+    leave the name unchanged.
+    """
+
+    organization_repo: OrganizationRepository
+
+    async def execute(
+        self,
+        org_id: OrgId,
+        *,
+        name: str | None = None,
+    ) -> Organization:
+        if await self.organization_repo.get(org_id) is None:
+            raise UnknownOrganization(f"organization {org_id} not found")
+        return await self.organization_repo.update(org_id, name=name)