pkg-auth 3.1.0__tar.gz → 3.3.0__tar.gz

{pkg_auth-3.1.0 → pkg_auth-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pkg-auth
-Version: 3.1.0
+Version: 3.3.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"
@@ -123,6 +123,7 @@ See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complet
 ## Features
 
 - **Authentication** — Keycloak JWT validation producing an `IdentityContext`.
+- **Service token** — a service's own Keycloak token (client credentials), cached and refreshed, for calling other services.
 - **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`).
@@ -135,7 +136,7 @@ See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complet
 
 ```
 pkg_auth/
-  authentication/             JWT validation → IdentityContext (identity only)
+  authentication/             JWT validation → IdentityContext; the service's own token
   authorization/              Full ACL (users, orgs, roles, perms, memberships)
     domain/                   Pure entities, ports (Protocol), exceptions
     application/use_cases/    Business logic (use cases)
@@ -160,5 +161,6 @@ pkg_auth/
 - [FastAPI Integration](docs/FastAPI.md)
 - [Django Integration](docs/Django.md)
 - [Strawberry Integration](docs/Strawberry.md)
+- [Service Token](docs/Service-Token.md) — call another service as this service
 - [Keycloak Admin](docs/Keycloak-Admin.md)
 - [Migration v1](docs/MIGRATION_v1.md) · [Migration v2](docs/MIGRATION_v2.md)

{pkg_auth-3.1.0 → pkg_auth-3.3.0}/README.md

@@ -75,6 +75,7 @@ See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complet
 ## Features
 
 - **Authentication** — Keycloak JWT validation producing an `IdentityContext`.
+- **Service token** — a service's own Keycloak token (client credentials), cached and refreshed, for calling other services.
 - **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`).
@@ -87,7 +88,7 @@ See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complet
 
 ```
 pkg_auth/
-  authentication/             JWT validation → IdentityContext (identity only)
+  authentication/             JWT validation → IdentityContext; the service's own token
   authorization/              Full ACL (users, orgs, roles, perms, memberships)
     domain/                   Pure entities, ports (Protocol), exceptions
     application/use_cases/    Business logic (use cases)
@@ -112,5 +113,6 @@ pkg_auth/
 - [FastAPI Integration](docs/FastAPI.md)
 - [Django Integration](docs/Django.md)
 - [Strawberry Integration](docs/Strawberry.md)
+- [Service Token](docs/Service-Token.md) — call another service as this service
 - [Keycloak Admin](docs/Keycloak-Admin.md)
 - [Migration v1](docs/MIGRATION_v1.md) · [Migration v2](docs/MIGRATION_v2.md)

{pkg_auth-3.1.0 → pkg_auth-3.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pkg-auth"
-version = "3.1.0"
+version = "3.3.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.1.0 → pkg_auth-3.3.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.1.0 → pkg_auth-3.3.0}/src/pkg_auth/authentication/__init__.py

@@ -6,7 +6,7 @@ Public API:
     Subject, EmailAddress, RealmName  — identity value objects
     TokenDecoder                — Protocol port for token verification
     AuthenticateTokenUseCase    — token → IdentityContext
-    AuthenticationError, TokenExpiredError, InvalidTokenError
+    AuthenticationError, TokenExpiredError, InvalidTokenError, ServiceTokenError
 """
 from __future__ import annotations
 
@@ -15,6 +15,7 @@ from .domain.entities import IdentityContext
 from .domain.exceptions import (
     AuthenticationError,
     InvalidTokenError,
+    ServiceTokenError,
     TokenExpiredError,
 )
 from .domain.ports import TokenDecoder
@@ -30,4 +31,5 @@ __all__ = [
     "AuthenticationError",
     "TokenExpiredError",
     "InvalidTokenError",
+    "ServiceTokenError",
 ]

pkg_auth-3.3.0/src/pkg_auth/authentication/adapters/keycloak/__init__.py

@@ -0,0 +1,12 @@
+"""Keycloak adapters: JWT verification and this service's own token."""
+from __future__ import annotations
+
+from .jwt_decoder import JWTTokenDecoder
+from .service_token import ServiceCredentials, ServiceTokenAuth, ServiceTokenProvider
+
+__all__ = [
+    "JWTTokenDecoder",
+    "ServiceCredentials",
+    "ServiceTokenAuth",
+    "ServiceTokenProvider",
+]

pkg_auth-3.3.0/src/pkg_auth/authentication/adapters/keycloak/service_token.py

@@ -0,0 +1,210 @@
+"""This service's own Keycloak token (client-credentials grant), for calling other services."""
+from __future__ import annotations
+
+import asyncio
+import os
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, AsyncGenerator, Callable, Generator, Mapping, Optional, Tuple
+
+import httpx
+
+from ...domain.exceptions import ServiceTokenError
+
+_ENV_NAMES = (
+    "KEYCLOAK_BASE_URL",
+    "KEYCLOAK_REALM",
+    "KEYCLOAK_CLIENT_ID",
+    "KEYCLOAK_CLIENT_SECRET",
+)
+
+
+@dataclass(frozen=True)
+class ServiceCredentials:
+    """Where and as whom a service asks Keycloak for its own token."""
+
+    token_url: str
+    client_id: str
+    client_secret: str = field(repr=False)
+
+    @classmethod
+    def for_realm(
+        cls, *, base_url: str, realm: str, client_id: str, client_secret: str
+    ) -> "ServiceCredentials":
+        token_url = f"{base_url.rstrip('/')}/realms/{realm}/protocol/openid-connect/token"
+        return cls(token_url=token_url, client_id=client_id, client_secret=client_secret)
+
+    @classmethod
+    def from_env(cls, environ: Optional[Mapping[str, str]] = None) -> "ServiceCredentials":
+        """Read ``KEYCLOAK_BASE_URL``, ``KEYCLOAK_REALM``, ``KEYCLOAK_CLIENT_ID``
+        and ``KEYCLOAK_CLIENT_SECRET``; raise ``ValueError`` naming every one unset."""
+        env = os.environ if environ is None else environ
+        values = {name: (env.get(name) or "").strip() for name in _ENV_NAMES}
+        missing = [name for name, value in values.items() if not value]
+        if missing:
+            raise ValueError(f"service token needs {', '.join(missing)}")
+        return cls.for_realm(
+            base_url=values["KEYCLOAK_BASE_URL"],
+            realm=values["KEYCLOAK_REALM"],
+            client_id=values["KEYCLOAK_CLIENT_ID"],
+            client_secret=values["KEYCLOAK_CLIENT_SECRET"],
+        )
+
+
+class ServiceTokenProvider:
+    """Fetches, caches and refreshes this service's token.
+
+    One instance per process, shared by sync and async callers. A cached
+    token is reused until ``refresh_margin_seconds`` before it expires (or
+    half its lifetime, for tokens shorter than twice the margin), so a call
+    never goes out with a token that dies in flight.
+    """
+
+    def __init__(
+        self,
+        credentials: ServiceCredentials,
+        *,
+        refresh_margin_seconds: float = 30.0,
+        timeout_seconds: float = 10.0,
+        clock: Callable[[], float] = time.monotonic,
+        transport: Optional[httpx.BaseTransport] = None,
+        async_transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        self._credentials = credentials
+        self._margin = refresh_margin_seconds
+        self._timeout = timeout_seconds
+        self._clock = clock
+        self._transport = transport
+        self._async_transport = async_transport
+
+        self._token: Optional[str] = None
+        self._refresh_at = 0.0
+        self._sync_lock = threading.Lock()
+        self._async_lock: Optional[asyncio.Lock] = None
+
+    @classmethod
+    def from_env(
+        cls, environ: Optional[Mapping[str, str]] = None, **kwargs: Any
+    ) -> "ServiceTokenProvider":
+        return cls(ServiceCredentials.from_env(environ), **kwargs)
+
+    @property
+    def client_id(self) -> str:
+        return self._credentials.client_id
+
+    def get_token(self) -> str:
+        token = self._cached()
+        if token is not None:
+            return token
+        with self._sync_lock:
+            token = self._cached()
+            if token is not None:
+                return token
+            with httpx.Client(timeout=self._timeout, transport=self._transport) as client:
+                try:
+                    response = client.post(**self._request())
+                except httpx.HTTPError as exc:
+                    raise self._unreachable(exc) from exc
+            return self._store(response)
+
+    async def aget_token(self) -> str:
+        token = self._cached()
+        if token is not None:
+            return token
+        if self._async_lock is None:
+            self._async_lock = asyncio.Lock()
+        async with self._async_lock:
+            token = self._cached()
+            if token is not None:
+                return token
+            async with httpx.AsyncClient(
+                timeout=self._timeout, transport=self._async_transport
+            ) as client:
+                try:
+                    response = await client.post(**self._request())
+                except httpx.HTTPError as exc:
+                    raise self._unreachable(exc) from exc
+            return self._store(response)
+
+    def invalidate(self) -> None:
+        """Drop the cached token; the next call fetches a new one."""
+        self._token = None
+        self._refresh_at = 0.0
+
+    def _cached(self) -> Optional[str]:
+        token = self._token
+        if token is not None and self._clock() < self._refresh_at:
+            return token
+        return None
+
+    def _request(self) -> dict[str, Any]:
+        return {
+            "url": self._credentials.token_url,
+            "data": {
+                "grant_type": "client_credentials",
+                "client_id": self._credentials.client_id,
+                "client_secret": self._credentials.client_secret,
+            },
+        }
+
+    def _unreachable(self, exc: Exception) -> ServiceTokenError:
+        return ServiceTokenError(
+            f"could not reach Keycloak for client {self._credentials.client_id!r}: {exc}"
+        )
+
+    def _store(self, response: httpx.Response) -> str:
+        token, expires_in = self._parse(response)
+        lifetime = max(float(expires_in), 0.0)
+        self._token = token
+        self._refresh_at = self._clock() + lifetime - min(self._margin, lifetime / 2)
+        return token
+
+    def _parse(self, response: httpx.Response) -> Tuple[str, Any]:
+        client_id = self._credentials.client_id
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+        if not isinstance(body, dict):
+            body = {}
+        if response.status_code != 200:
+            reason = body.get("error_description") or body.get("error") or response.text[:200]
+            raise ServiceTokenError(
+                f"Keycloak refused a token for client {client_id!r}: "
+                f"HTTP {response.status_code} {reason}"
+            )
+        token = body.get("access_token")
+        if not isinstance(token, str) or not token:
+            raise ServiceTokenError(f"Keycloak returned no access_token for client {client_id!r}")
+        return token, body.get("expires_in", 60)
+
+
+class ServiceTokenAuth(httpx.Auth):
+    """``httpx`` auth that sends the service token and, on a 401, fetches a
+    fresh one and retries once (the cached token may have been revoked)."""
+
+    requires_request_body = True
+
+    def __init__(self, provider: ServiceTokenProvider) -> None:
+        self._provider = provider
+
+    def sync_auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        request.headers["Authorization"] = f"Bearer {self._provider.get_token()}"
+        response = yield request
+        if response.status_code == 401:
+            self._provider.invalidate()
+            request.headers["Authorization"] = f"Bearer {self._provider.get_token()}"
+            yield request
+
+    async def async_auth_flow(
+        self, request: httpx.Request
+    ) -> AsyncGenerator[httpx.Request, httpx.Response]:
+        request.headers["Authorization"] = f"Bearer {await self._provider.aget_token()}"
+        response = yield request
+        if response.status_code == 401:
+            self._provider.invalidate()
+            request.headers["Authorization"] = f"Bearer {await self._provider.aget_token()}"
+            yield request

{pkg_auth-3.1.0 → pkg_auth-3.3.0}/src/pkg_auth/authentication/domain/exceptions.py

@@ -16,3 +16,7 @@ class TokenExpiredError(AuthenticationError):
 
 class InvalidTokenError(AuthenticationError):
     """Token is malformed, has an invalid signature, or fails verification."""
+
+
+class ServiceTokenError(AuthenticationError):
+    """Keycloak did not issue this service's own (client-credentials) token."""

{pkg_auth-3.1.0 → pkg_auth-3.3.0}/src/pkg_auth/authorization/__init__.py

@@ -8,7 +8,7 @@ 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.
@@ -34,6 +34,8 @@ from .domain.entities import (
 from .platform import is_platform_context
 from .domain.exceptions import (
     AuthorizationError,
+    DelegationRefusal,
+    DelegationRefused,
     MissingPermission,
     NotAMember,
     PermissionVisibilityConflict,
@@ -118,4 +120,6 @@ __all__ = [
     "ServiceNotEnabled",
     "PermissionVisibilityConflict",
     "UserNotProvisioned",
+    "DelegationRefused",
+    "DelegationRefusal",
 ]

pkg_auth-3.3.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.1.0 → pkg_auth-3.3.0}/src/pkg_auth/authorization/domain/entities.py

@@ -163,12 +163,19 @@ class AuthContext:
     services cache their platform org's id at startup and call
     :func:`pkg_auth.authorization.is_platform_context` to compare against
     ``self.organization_id``. See the package docs for the pattern.
+
+    ``acted_by`` is **attribution only**. On a delegated (on-behalf-of)
+    request ``user_id`` is the target user — the acting principal for
+    authorization and ownership — and ``acted_by`` is the caller's ACL id;
+    it is ``None`` otherwise. It never grants or removes a permission, and
+    the cache serializer deliberately excludes it (``auth:AD-1``).
     """
 
     user_id: UserId
     organization_id: OrgId
     role_names: frozenset[str]
     perms: frozenset[str]
+    acted_by: UserId | None = None
 
     def has(self, perm: str) -> bool:
         """Return ``True`` if any of the user's roles grant ``perm``."""

{pkg_auth-3.1.0 → pkg_auth-3.3.0}/src/pkg_auth/authorization/domain/exceptions.py

@@ -7,6 +7,8 @@ each to the right HTTP status.
 """
 from __future__ import annotations
 
+from enum import Enum
+
 
 class AuthorizationError(Exception):
     """Base for all authorization (ACL) failures."""
@@ -66,3 +68,37 @@ class ServiceNotSaaSAvailable(AuthorizationError):
 
 class ServiceNotEnabled(AuthorizationError):
     """The organization does not have the required service enabled."""
+
+
+class DelegationRefusal(str, Enum):
+    """Why a delegated (on-behalf-of) request was refused.
+
+    One member per row 3–9 of ``auth:AD-1``'s order of checks. Integration
+    layers map ``REPEATED`` and ``EMPTY_TARGET`` to 400,
+    ``UNKNOWN_ORGANIZATION`` to 404, and every other reason to 403.
+    """
+
+    REPEATED = "repeated"
+    NOT_A_DELEGATOR = "not_a_delegator"
+    EMPTY_TARGET = "empty_target"
+    UNKNOWN_ORGANIZATION = "unknown_organization"
+    ORGANIZATION_NOT_ALLOWED = "organization_not_allowed"
+    TARGET_NOT_PROVISIONED = "target_not_provisioned"
+    TARGET_NOT_A_MEMBER = "target_not_a_member"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class DelegationRefused(AuthorizationError):
+    """A delegated request was refused; ``reason`` says which check failed.
+
+    The only error :class:`ResolveDelegatedAuthContextUseCase` raises for a
+    refusal — never :class:`NotAMember` or :class:`UserNotProvisioned`, so
+    no integration can mistake a refused delegation for the caller's own
+    failure and fall back to the caller's context.
+    """
+
+    def __init__(self, reason: DelegationRefusal, detail: str | None = None) -> None:
+        self.reason = reason
+        super().__init__(detail or f"delegation refused: {reason.value}")

{pkg_auth-3.1.0 → pkg_auth-3.3.0}/src/pkg_auth/integrations/django/auth_context_middleware.py

@@ -13,6 +13,9 @@ from ...authorization import (
     UnknownOrganization,
     UserNotProvisioned,
 )
+from ...authorization.application.use_cases.resolve_delegated_auth_context import (
+    ON_BEHALF_OF_HEADER,
+)
 from ...authorization.domain.entities import User
 from .install import get_registry
 
@@ -23,6 +26,9 @@ class AuthContextMiddleware:
     Requires ``IdentityMiddleware`` to run first so ``request.identity``
     is populated. Behavior:
 
+        - ``X-On-Behalf-Of`` present (any value, with or without the org
+          header or an identity) → 403; this middleware cannot delegate
+          (``auth:AD-1``)
         - no header → ``request.auth_context = None`` (route decides)
         - identity is None and header present → 401
         - org not found → 404
@@ -53,8 +59,14 @@ class AuthContextMiddleware:
             )
 
     async def __call__(self, request: HttpRequest) -> HttpResponse:
-        registry = get_registry()
         request.auth_context = None  # type: ignore[attr-defined]
+        if request.headers.get(ON_BEHALF_OF_HEADER) is not None:
+            return JsonResponse(
+                {"detail": f"{ON_BEHALF_OF_HEADER} is not accepted here"},
+                status=403,
+            )
+
+        registry = get_registry()
 
         raw = request.headers.get(registry.header_name)
         if raw is None: