pkg-auth 3.0.0__tar.gz → 3.2.0__tar.gz

{pkg_auth-3.0.0 → pkg_auth-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pkg-auth
-Version: 3.0.0
+Version: 3.2.0
 Summary: Clean-architecture auth core for multiple Python frameworks
 Author-email: Fritill <info@fritill.ae>
 License: MIT
@@ -19,7 +19,7 @@ Requires-Dist: types-requests<3.0.0.0,>=2.32.0.0; extra == "dev"
 Requires-Dist: types-PyJWT<2.0.0,>=1.7.0; extra == "dev"
 Requires-Dist: testcontainers[postgres,redis]>=4.0; extra == "dev"
 Provides-Extra: acl-sqlalchemy
-Requires-Dist: sqlalchemy<3.0,>=2.0; extra == "acl-sqlalchemy"
+Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0; extra == "acl-sqlalchemy"
 Requires-Dist: asyncpg>=0.29; extra == "acl-sqlalchemy"
 Requires-Dist: alembic>=1.13; extra == "acl-sqlalchemy"
 Provides-Extra: acl-django
@@ -41,7 +41,7 @@ Requires-Dist: starlette>=0.37; extra == "all"
 Requires-Dist: django>=4.2; extra == "all"
 Requires-Dist: psycopg[binary]>=3.1; extra == "all"
 Requires-Dist: strawberry-graphql>=0.255; extra == "all"
-Requires-Dist: sqlalchemy<3.0,>=2.0; extra == "all"
+Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0; extra == "all"
 Requires-Dist: asyncpg>=0.29; extra == "all"
 Requires-Dist: alembic>=1.13; extra == "all"
 Requires-Dist: redis>=5.0; extra == "all"
@@ -50,7 +50,7 @@ Requires-Dist: redis>=5.0; extra == "all"
 
 Clean-architecture **identity + ACL** for multi-framework Python services. Handles JWT authentication (via Keycloak) and database-backed authorization (users, organizations, roles, permissions, memberships) in a single package with first-class support for **FastAPI**, **Django**, and **Strawberry GraphQL**.
 
-> **v1.0 is a breaking change from v0.x.** The old claim-based authorization model (`AccessContext`, `AccessRights`, `require_permissions`) is replaced by a real ACL database. See [`docs/MIGRATION_v1.md`](docs/MIGRATION_v1.md) for the upgrade guide.
+> **v3.0.0 is a breaking change.** The `permissions.is_platform` flag is replaced by a tri-state `visibility` enum (`platform_only`/`shared`/`tenant_only`); permission `description` is now a localized JSONB map; and a first-class **Service** model with a **default-deny service guard** is added. See [`docs/Upgrade-Service-Guard.md`](docs/Upgrade-Service-Guard.md) for the 3.0.0 upgrade guide. Earlier migrations: [`docs/MIGRATION_v1.md`](docs/MIGRATION_v1.md), [`docs/MIGRATION_v2.md`](docs/MIGRATION_v2.md).
 
 ## Install
 
@@ -58,16 +58,21 @@ Clean-architecture **identity + ACL** for multi-framework Python services. Handl
 # Core (identity only — no DB deps)
 pip install pkg-auth
 
-# With ACL + FastAPI (most common for itqadem services)
-pip install pkg-auth[acl-sqlalchemy,fastapi]
+# With ACL + FastAPI (most common for fritill services)
+pip install "pkg-auth[acl-sqlalchemy,fastapi]"
 
 # With ACL + Django
-pip install pkg-auth[acl-django,django]
+pip install "pkg-auth[acl-django,django]"
 
 # With optional Redis cache
-pip install pkg-auth[cache-redis]
+pip install "pkg-auth[cache-redis]"
+
+# Everything
+pip install "pkg-auth[all]"
 ```
 
+Available extras: `acl-sqlalchemy`, `acl-django`, `cache-redis`, `fastapi`, `django`, `strawberry`, `all`.
+
 ## Quickstart (FastAPI)
 
 ```python
@@ -84,7 +89,7 @@ from pkg_auth.integrations.fastapi import (
 
 auth = create_authentication(
     keycloak_base_url="https://auth.example.com",
-    realm="itqadem",
+    realm="fritill",
     audience="courses-service",
 )
 
@@ -110,11 +115,22 @@ async def get_course(
     ),
 ):
     identity, auth_ctx = bundle
-    return {"course_id": id, "role": str(auth_ctx.role_name)}
+    return {"course_id": id, "roles": sorted(auth_ctx.role_names)}
 ```
 
 See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complete working example.
 
+## Features
+
+- **Authentication** — Keycloak JWT validation producing an `IdentityContext`.
+- **Authorization (ACL)** — database-backed users, organizations, roles, permissions, and memberships, resolved into a hot-path `AuthContext` (`role_names`, `perms`).
+- **Permission visibility** — tri-state catalog visibility (`platform_only` / `shared` / `tenant_only`).
+- **Localized descriptions** — permission descriptions stored as localized JSONB (`LocalizedText`, `ACL_DEFAULT_LOCALE`).
+- **Services & service guard** — first-class `Service` / `OrganizationService` model with a **default-deny** service guard; the platform org bypasses it.
+- **Mode A / Mode B** — be the source of truth for the `users` table, or consume a shared ACL read-only.
+- **Integrations** — FastAPI, Django, and Strawberry GraphQL.
+- **CLIs** — `keycloak-init-client`, `pkg-auth-sync-catalog`, `pkg-auth-sync-services`.
+
 ## Architecture
 
 ```
@@ -122,9 +138,9 @@ pkg_auth/
   authentication/             JWT validation → IdentityContext (identity only)
   authorization/              Full ACL (users, orgs, roles, perms, memberships)
     domain/                   Pure entities, ports (Protocol), exceptions
-    application/use_cases/    Business logic (13 use cases)
+    application/use_cases/    Business logic (use cases)
     adapters/
-      sqlalchemy/             Canonical schema + Alembic migration + repos
+      sqlalchemy/             Canonical schema + Alembic migrations (0001–0005) + repos
       django_orm/             Mirror models (managed=False) + repos
       cache/                  InMemoryTTLCache / RedisCache + decorator
   integrations/
@@ -138,10 +154,11 @@ pkg_auth/
 
 ## Documentation
 
-- [Authorization model](docs/Authorization.md) — schema, permission catalog, roles, memberships
+- [Authorization model](docs/Authorization.md) — schema, permission catalog, roles, memberships, service guard
+- [Upgrade to the Service Guard (3.0.0)](docs/Upgrade-Service-Guard.md)
 - [Caching](docs/Caching.md) — InMemoryTTLCache, RedisCache, invalidation contract
 - [FastAPI Integration](docs/FastAPI.md)
 - [Django Integration](docs/Django.md)
 - [Strawberry Integration](docs/Strawberry.md)
 - [Keycloak Admin](docs/Keycloak-Admin.md)
-- [Migration from v0.x](docs/MIGRATION_v1.md)
+- [Migration v1](docs/MIGRATION_v1.md) · [Migration v2](docs/MIGRATION_v2.md)

{pkg_auth-3.0.0 → pkg_auth-3.2.0}/README.md

@@ -2,7 +2,7 @@
 
 Clean-architecture **identity + ACL** for multi-framework Python services. Handles JWT authentication (via Keycloak) and database-backed authorization (users, organizations, roles, permissions, memberships) in a single package with first-class support for **FastAPI**, **Django**, and **Strawberry GraphQL**.
 
-> **v1.0 is a breaking change from v0.x.** The old claim-based authorization model (`AccessContext`, `AccessRights`, `require_permissions`) is replaced by a real ACL database. See [`docs/MIGRATION_v1.md`](docs/MIGRATION_v1.md) for the upgrade guide.
+> **v3.0.0 is a breaking change.** The `permissions.is_platform` flag is replaced by a tri-state `visibility` enum (`platform_only`/`shared`/`tenant_only`); permission `description` is now a localized JSONB map; and a first-class **Service** model with a **default-deny service guard** is added. See [`docs/Upgrade-Service-Guard.md`](docs/Upgrade-Service-Guard.md) for the 3.0.0 upgrade guide. Earlier migrations: [`docs/MIGRATION_v1.md`](docs/MIGRATION_v1.md), [`docs/MIGRATION_v2.md`](docs/MIGRATION_v2.md).
 
 ## Install
 
@@ -10,16 +10,21 @@ Clean-architecture **identity + ACL** for multi-framework Python services. Handl
 # Core (identity only — no DB deps)
 pip install pkg-auth
 
-# With ACL + FastAPI (most common for itqadem services)
-pip install pkg-auth[acl-sqlalchemy,fastapi]
+# With ACL + FastAPI (most common for fritill services)
+pip install "pkg-auth[acl-sqlalchemy,fastapi]"
 
 # With ACL + Django
-pip install pkg-auth[acl-django,django]
+pip install "pkg-auth[acl-django,django]"
 
 # With optional Redis cache
-pip install pkg-auth[cache-redis]
+pip install "pkg-auth[cache-redis]"
+
+# Everything
+pip install "pkg-auth[all]"
 ```
 
+Available extras: `acl-sqlalchemy`, `acl-django`, `cache-redis`, `fastapi`, `django`, `strawberry`, `all`.
+
 ## Quickstart (FastAPI)
 
 ```python
@@ -36,7 +41,7 @@ from pkg_auth.integrations.fastapi import (
 
 auth = create_authentication(
     keycloak_base_url="https://auth.example.com",
-    realm="itqadem",
+    realm="fritill",
     audience="courses-service",
 )
 
@@ -62,11 +67,22 @@ async def get_course(
     ),
 ):
     identity, auth_ctx = bundle
-    return {"course_id": id, "role": str(auth_ctx.role_name)}
+    return {"course_id": id, "roles": sorted(auth_ctx.role_names)}
 ```
 
 See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complete working example.
 
+## Features
+
+- **Authentication** — Keycloak JWT validation producing an `IdentityContext`.
+- **Authorization (ACL)** — database-backed users, organizations, roles, permissions, and memberships, resolved into a hot-path `AuthContext` (`role_names`, `perms`).
+- **Permission visibility** — tri-state catalog visibility (`platform_only` / `shared` / `tenant_only`).
+- **Localized descriptions** — permission descriptions stored as localized JSONB (`LocalizedText`, `ACL_DEFAULT_LOCALE`).
+- **Services & service guard** — first-class `Service` / `OrganizationService` model with a **default-deny** service guard; the platform org bypasses it.
+- **Mode A / Mode B** — be the source of truth for the `users` table, or consume a shared ACL read-only.
+- **Integrations** — FastAPI, Django, and Strawberry GraphQL.
+- **CLIs** — `keycloak-init-client`, `pkg-auth-sync-catalog`, `pkg-auth-sync-services`.
+
 ## Architecture
 
 ```
@@ -74,9 +90,9 @@ pkg_auth/
   authentication/             JWT validation → IdentityContext (identity only)
   authorization/              Full ACL (users, orgs, roles, perms, memberships)
     domain/                   Pure entities, ports (Protocol), exceptions
-    application/use_cases/    Business logic (13 use cases)
+    application/use_cases/    Business logic (use cases)
     adapters/
-      sqlalchemy/             Canonical schema + Alembic migration + repos
+      sqlalchemy/             Canonical schema + Alembic migrations (0001–0005) + repos
       django_orm/             Mirror models (managed=False) + repos
       cache/                  InMemoryTTLCache / RedisCache + decorator
   integrations/
@@ -90,10 +106,11 @@ pkg_auth/
 
 ## Documentation
 
-- [Authorization model](docs/Authorization.md) — schema, permission catalog, roles, memberships
+- [Authorization model](docs/Authorization.md) — schema, permission catalog, roles, memberships, service guard
+- [Upgrade to the Service Guard (3.0.0)](docs/Upgrade-Service-Guard.md)
 - [Caching](docs/Caching.md) — InMemoryTTLCache, RedisCache, invalidation contract
 - [FastAPI Integration](docs/FastAPI.md)
 - [Django Integration](docs/Django.md)
 - [Strawberry Integration](docs/Strawberry.md)
 - [Keycloak Admin](docs/Keycloak-Admin.md)
-- [Migration from v0.x](docs/MIGRATION_v1.md)
+- [Migration v1](docs/MIGRATION_v1.md) · [Migration v2](docs/MIGRATION_v2.md)

{pkg_auth-3.0.0 → pkg_auth-3.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pkg-auth"
-version = "3.0.0"
+version = "3.2.0"
 description = "Clean-architecture auth core for multiple Python frameworks"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -33,7 +33,7 @@ dev = [
 
 # ACL storage backends (v1.0)
 acl-sqlalchemy = [
-    "sqlalchemy>=2.0,<3.0",
+    "sqlalchemy[asyncio]>=2.0,<3.0",
     "asyncpg>=0.29",
     "alembic>=1.13",
 ]
@@ -67,7 +67,7 @@ all = [
     "django>=4.2",
     "psycopg[binary]>=3.1",
     "strawberry-graphql>=0.255",
-    "sqlalchemy>=2.0,<3.0",
+    "sqlalchemy[asyncio]>=2.0,<3.0",
     "asyncpg>=0.29",
     "alembic>=1.13",
     "redis>=5.0",

{pkg_auth-3.0.0 → pkg_auth-3.2.0}/src/pkg_auth/__init__.py

@@ -10,6 +10,6 @@ Authorization (ACL) and framework integrations (FastAPI, Django,
 Strawberry) are available via sub-packages.
 """
 
-__version__ = "2.1.0"
+__version__ = "3.2.0"
 
 __all__ = ["__version__"]

{pkg_auth-3.0.0 → pkg_auth-3.2.0}/src/pkg_auth/authorization/__init__.py

@@ -8,14 +8,17 @@ Public API:
                      MembershipRepository, PermissionCatalogRepository
     Exceptions:      AuthorizationError, NotAMember, MissingPermission,
                      UnknownOrganization, UnknownUser, UnknownRole,
-                     UserNotProvisioned
+                     UserNotProvisioned, DelegationRefused, DelegationRefusal
 
 The application layer (use cases) is added in M3; SQLAlchemy / Django ORM
 adapters in M4 / M6; cache layer in M5; framework integrations in M7-M9.
 """
 from __future__ import annotations
 
-from .application.use_cases.register_permission_catalog import CatalogEntry
+from .application.use_cases.register_permission_catalog import (
+    CatalogEntry,
+    ServiceManifest,
+)
 from .application.use_cases.sync_service_catalog import ServiceSpec
 from .config import default_locale
 from .domain.entities import (
@@ -31,6 +34,8 @@ from .domain.entities import (
 from .platform import is_platform_context
 from .domain.exceptions import (
     AuthorizationError,
+    DelegationRefusal,
+    DelegationRefused,
     MissingPermission,
     NotAMember,
     PermissionVisibilityConflict,
@@ -96,6 +101,7 @@ __all__ = [
     # Application DTOs
     "CatalogEntry",
     "ServiceSpec",
+    "ServiceManifest",
     "PermissionScope",
     # Config
     "default_locale",
@@ -114,4 +120,6 @@ __all__ = [
     "ServiceNotEnabled",
     "PermissionVisibilityConflict",
     "UserNotProvisioned",
+    "DelegationRefused",
+    "DelegationRefusal",
 ]

{pkg_auth-3.0.0 → pkg_auth-3.2.0}/src/pkg_auth/authorization/adapters/django_orm/repositories/service.py

@@ -25,8 +25,14 @@ class DjangoServiceRepository:
     model: type = field(default=DefaultServiceModel)
 
     async def upsert_many(self, services: Sequence[ServiceSpec]) -> None:
+        """Vendor flag overlay: set flags, seed label only on create.
+
+        On conflict the existing (service-owned) ``display_label`` is preserved
+        — only the vendor flags update. Written without ``create_defaults`` so
+        it works on Django 4.2.
+        """
         for s in services:
-            await self.model.objects.aupdate_or_create(
+            obj, created = await self.model.objects.aget_or_create(
                 name=str(s.name),
                 defaults={
                     "display_label": s.display_label.as_dict() or None,
@@ -34,12 +40,29 @@ class DjangoServiceRepository:
                     "saas_available": s.saas_available,
                 },
             )
+            if not created:
+                obj.auto_provision = s.auto_provision
+                obj.saas_available = s.saas_available
+                await obj.asave(
+                    update_fields=["auto_provision", "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 register_identity(
+        self, *, name: str, display_label: LocalizedText | None = None
+    ) -> None:
+        """Self-register identity; never overwrite vendor flags."""
+        label = display_label.as_dict() if display_label is not None else None
+        obj, created = await self.model.objects.aget_or_create(
+            name=name,
+            defaults={
+                "display_label": label or None,
+                "auto_provision": False,
+                "saas_available": False,
+            },
         )
+        if not created and label:
+            obj.display_label = label
+            await obj.asave(update_fields=["display_label"])
 
     async def get(self, name: ServiceName) -> Service | None:
         row = await self.model.objects.filter(name=str(name)).afirst()

{pkg_auth-3.0.0 → pkg_auth-3.2.0}/src/pkg_auth/authorization/adapters/sqlalchemy/repositories/service.py

@@ -30,6 +30,11 @@ class SqlAlchemyServiceRepository:
     model: type = field(default=DefaultServiceORM)
 
     async def upsert_many(self, services: Sequence[ServiceSpec]) -> None:
+        """Vendor flag overlay: set ``auto_provision`` / ``saas_available``.
+
+        On insert the spec's ``display_label`` seeds the row; on conflict the
+        existing (service-owned) label is preserved — only the flags update.
+        """
         if not services:
             return
         rows = [
@@ -45,7 +50,6 @@ class SqlAlchemyServiceRepository:
         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,
             },
@@ -54,14 +58,29 @@ class SqlAlchemyServiceRepository:
             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."""
+    async def register_identity(
+        self, *, name: str, display_label: LocalizedText | None = None
+    ) -> None:
+        """Self-register a service's identity; never overwrite vendor flags.
+
+        Inserts a row with safe default flags if absent. If a non-empty
+        ``display_label`` is given, it is set on insert and on conflict
+        (identity is service-owned); the flags are left untouched.
+        """
+        label = display_label.as_dict() if display_label is not None else None
         stmt = pg_insert(self.model).values(
-            name=service_name,
+            name=name,
+            display_label=label or None,
             auto_provision=False,
             saas_available=False,
         )
-        stmt = stmt.on_conflict_do_nothing(index_elements=["name"])
+        if label:
+            stmt = stmt.on_conflict_do_update(
+                index_elements=["name"],
+                set_={"display_label": stmt.excluded.display_label},
+            )
+        else:
+            stmt = stmt.on_conflict_do_nothing(index_elements=["name"])
         async with self.session_factory() as session:
             await session.execute(stmt)
             await session.commit()

{pkg_auth-3.0.0 → pkg_auth-3.2.0}/src/pkg_auth/authorization/application/use_cases/register_permission_catalog.py

@@ -10,9 +10,40 @@ from ...domain.value_objects import (
     LocalizedText,
     PermissionKey,
     PermissionVisibility,
+    ServiceName,
 )
 
 
+@dataclass(frozen=True, slots=True)
+class ServiceManifest:
+    """A service's self-declared identity for the service registry.
+
+    A service ships this alongside its permission catalog so it registers
+    *itself* (name + localized ``display_label``) when ``pkg-auth-sync-catalog``
+    runs. It deliberately carries no vendor flags (``auto_provision`` /
+    ``saas_available``) — those stay vendor-owned via ``pkg-auth-sync-services``.
+    """
+
+    name: ServiceName
+    display_label: LocalizedText = field(default_factory=lambda: LocalizedText({}))
+
+    @classmethod
+    def make(
+        cls,
+        name: ServiceName | str,
+        display_label: "LocalizedText | Mapping[str, str] | str | None" = None,
+        *,
+        default_locale_: str | None = None,
+    ) -> "ServiceManifest":
+        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
+            ),
+        )
+
+
 @dataclass(frozen=True, slots=True)
 class CatalogEntry:
     """One row a service registers into the central permission catalog.
@@ -98,10 +129,10 @@ class RegisterPermissionCatalogUseCase:
     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.
+    When a ``service_repo`` is wired, the service registers its own identity
+    row (``name`` + optional ``display_label``) with safe default flags, 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
@@ -112,10 +143,13 @@ class RegisterPermissionCatalogUseCase:
         *,
         service_name: str,
         entries: Sequence[CatalogEntryInput],
+        display_label: LocalizedText | None = None,
     ) -> 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.service_repo.register_identity(
+                name=service_name, display_label=display_label
+            )
         await self.catalog_repo.register_many(
             service_name=service_name,
             entries=normalized,

pkg_auth-3.2.0/src/pkg_auth/authorization/application/use_cases/resolve_delegated_auth_context.py

@@ -0,0 +1,169 @@
+"""Resolve a delegated (on-behalf-of) :class:`AuthContext` (``auth:AD-1``)."""
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field, replace
+from types import MappingProxyType
+from typing import Any
+from uuid import UUID
+
+from ...domain.entities import AuthContext, Organization, User
+from ...domain.exceptions import (
+    DelegationRefusal,
+    DelegationRefused,
+    NotAMember,
+)
+from ...domain.ports import OrganizationRepository, UserRepository
+from ...domain.value_objects import OrgId
+from .resolve_auth_context import ResolveAuthContextUseCase
+
+Delegators = Mapping[str, frozenset[OrgId]]
+
+ON_BEHALF_OF_HEADER = "X-On-Behalf-Of"
+
+
+async def find_organization(
+    repo: OrganizationRepository, raw: str
+) -> Organization | None:
+    """Look up an org from a raw ``X-Organization-Id`` value.
+
+    Tries ``raw`` as a UUID first and falls back to a slug lookup. The one
+    lookup rule shared by the FastAPI dependency and the delegated use case,
+    so the two cannot drift.
+    """
+    try:
+        org_id = OrgId(UUID(raw))
+    except ValueError:
+        return await repo.get_by_slug(raw)
+    return await repo.get(org_id)
+
+
+def _to_org_id(raw: Any, sub: str) -> OrgId:
+    if isinstance(raw, OrgId):
+        return raw
+    if isinstance(raw, UUID):
+        return OrgId(raw)
+    if isinstance(raw, str):
+        try:
+            return OrgId(UUID(raw))
+        except ValueError:
+            pass
+    raise ValueError(
+        f"delegators[{sub!r}]: organization {raw!r} is not a UUID"
+    )
+
+
+def normalize_delegators(
+    raw: Mapping[str, Iterable[Any]] | None,
+) -> MappingProxyType[str, frozenset[OrgId]]:
+    """Normalize a ``delegators`` config into an immutable allowlist.
+
+    Keys are Keycloak service-account ``sub`` strings, kept exactly as
+    given. Values are iterables of org ids (``OrgId``, ``UUID`` or UUID
+    strings). ``None`` or an empty mapping yields an empty map, so nobody
+    delegates (fail closed); a ``sub`` with no orgs is dropped, so it is
+    refused as not a delegator before any lookup.
+
+    Raises :class:`ValueError` when ``raw`` is a bare ``str`` or not a
+    mapping, a ``sub`` is not a non-blank, unpadded ``str``, a value is a bare
+    ``str`` or not iterable, or an org is not a UUID.
+    """
+    if raw is None:
+        return MappingProxyType({})
+    if isinstance(raw, (str, bytes)) or not isinstance(raw, Mapping):
+        raise ValueError(
+            f"delegators must be a mapping of sub -> org ids, got {type(raw).__name__}"
+        )
+    normalized: dict[str, frozenset[OrgId]] = {}
+    for sub, orgs in raw.items():
+        if not isinstance(sub, str) or not sub.strip() or sub != sub.strip():
+            raise ValueError(f"delegators: blank, padded or non-string sub {sub!r}")
+        if isinstance(orgs, (str, bytes)):
+            raise ValueError(
+                f"delegators[{sub!r}] must be a collection of org ids, not a bare string"
+            )
+        try:
+            items = list(orgs)
+        except TypeError as exc:
+            raise ValueError(
+                f"delegators[{sub!r}] must be a collection of org ids"
+            ) from exc
+        org_ids = frozenset(_to_org_id(o, sub) for o in items)
+        if org_ids:  # an agent with no orgs is not a delegator at all
+            normalized[sub] = org_ids
+    return MappingProxyType(normalized)
+
+
+@dataclass(slots=True)
+class ResolveDelegatedAuthContextUseCase:
+    """Decide a delegated request and return the target's :class:`AuthContext`.
+
+    The single framework-free place that holds ``delegators`` (``auth:AD-1``
+    Placement). Integrations pass the raw ``X-On-Behalf-Of`` values and the
+    raw ``X-Organization-Id`` value; they never see the allowlist.
+
+    Checks run in ``auth:AD-1``'s order (rows 3–9), first match wins, and
+    every refusal is a :class:`DelegationRefused`. The target is looked up
+    read-only through ``UserRepository.get_by_keycloak_sub`` — delegation
+    never creates a user. On success the result is the target's own
+    context from ``resolve_use_case`` (same service guard, same cache
+    entry) with ``acted_by`` attached afterwards; the caller's perms are
+    never used.
+    """
+
+    resolve_use_case: ResolveAuthContextUseCase
+    user_repo: UserRepository
+    organization_repo: OrganizationRepository
+    delegators: Delegators | None = field(default=None)
+
+    def __post_init__(self) -> None:
+        self.delegators = normalize_delegators(self.delegators)
+
+    async def execute(
+        self,
+        *,
+        caller: User,
+        on_behalf_of: Sequence[str],
+        organization: str,
+    ) -> AuthContext:
+        if isinstance(on_behalf_of, (str, bytes)):
+            raise TypeError("on_behalf_of must be the header's list of values")
+        if len(on_behalf_of) == 0:
+            raise ValueError("on_behalf_of is empty; only call when the header is present")
+
+        # Row 3: repeated header.
+        if len(on_behalf_of) > 1:
+            raise DelegationRefused(DelegationRefusal.REPEATED)
+
+        # Row 4: caller not a delegator — before any lookup.
+        assert self.delegators is not None
+        allowed_orgs = self.delegators.get(caller.keycloak_sub)
+        if allowed_orgs is None:
+            raise DelegationRefused(DelegationRefusal.NOT_A_DELEGATOR)
+
+        # Row 5: empty value.
+        target_sub = on_behalf_of[0]
+        if not target_sub.strip():
+            raise DelegationRefused(DelegationRefusal.EMPTY_TARGET)
+
+        # Row 6: unknown org (UUID first, then slug).
+        org = await find_organization(self.organization_repo, organization)
+        if org is None:
+            raise DelegationRefused(DelegationRefusal.UNKNOWN_ORGANIZATION)
+
+        # Row 7: org not on this agent's list (no platform-org bypass).
+        if org.id not in allowed_orgs:
+            raise DelegationRefused(DelegationRefusal.ORGANIZATION_NOT_ALLOWED)
+
+        # Row 8: target not provisioned — read-only lookup, never upsert.
+        target = await self.user_repo.get_by_keycloak_sub(target_sub)
+        if target is None:
+            raise DelegationRefused(DelegationRefusal.TARGET_NOT_PROVISIONED)
+
+        # Row 9: target not a member.
+        try:
+            ctx = await self.resolve_use_case.execute(target.id, org.id)
+        except NotAMember as exc:
+            raise DelegationRefused(DelegationRefusal.TARGET_NOT_A_MEMBER) from exc
+
+        return replace(ctx, acted_by=caller.id)

{pkg_auth-3.0.0 → pkg_auth-3.2.0}/src/pkg_auth/authorization/application/use_cases/sync_permission_catalog.py

@@ -11,6 +11,7 @@ from dataclasses import dataclass
 from typing import Sequence
 
 from ...domain.ports import PermissionCatalogRepository, ServiceRepository
+from ...domain.value_objects import LocalizedText
 from .register_permission_catalog import (
     CatalogEntry,
     CatalogEntryInput,
@@ -51,6 +52,7 @@ class SyncPermissionCatalogUseCase:
         *,
         service_name: str,
         entries: Sequence[CatalogEntryInput],
+        display_label: LocalizedText | None = None,
         dry_run: bool = False,
     ) -> SyncResult:
         normalized: list[CatalogEntry] = [_normalize_entry(e) for e in entries]
@@ -70,7 +72,9 @@ class SyncPermissionCatalogUseCase:
             )
 
         if self.service_repo is not None:
-            await self.service_repo.ensure_exists(service_name=service_name)
+            await self.service_repo.register_identity(
+                name=service_name, display_label=display_label
+            )
         await self.catalog_repo.register_many(
             service_name=service_name,
             entries=normalized,