pkg-auth 3.0.0__py3-none-any.whl

pkg_auth/authorization/__init__.py

@@ -0,0 +1,117 @@
+"""Authorization module: full ACL on top of pkg_auth.authentication.
+
+Public API:
+
+    Entities:        User, Organization, Permission, Role, Membership, AuthContext
+    Value objects:   UserId, OrgId, RoleId, PermissionId, RoleName, PermissionKey
+    Ports:           UserRepository, OrganizationRepository, RoleRepository,
+                     MembershipRepository, PermissionCatalogRepository
+    Exceptions:      AuthorizationError, NotAMember, MissingPermission,
+                     UnknownOrganization, UnknownUser, UnknownRole,
+                     UserNotProvisioned
+
+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.sync_service_catalog import ServiceSpec
+from .config import default_locale
+from .domain.entities import (
+    AuthContext,
+    Membership,
+    Organization,
+    OrganizationService,
+    Permission,
+    Role,
+    Service,
+    User,
+)
+from .platform import is_platform_context
+from .domain.exceptions import (
+    AuthorizationError,
+    MissingPermission,
+    NotAMember,
+    PermissionVisibilityConflict,
+    ServiceNotEnabled,
+    ServiceNotSaaSAvailable,
+    UnknownOrganization,
+    UnknownPermission,
+    UnknownRole,
+    UnknownService,
+    UnknownUser,
+    UserNotProvisioned,
+)
+from .domain.ports import (
+    MembershipRepository,
+    OrganizationRepository,
+    OrganizationServiceRepository,
+    PermissionCatalogRepository,
+    PermissionScope,
+    RoleRepository,
+    ServiceRepository,
+    UserRepository,
+)
+from .domain.value_objects import (
+    LocalizedText,
+    OrgId,
+    PermissionId,
+    PermissionKey,
+    PermissionVisibility,
+    RoleId,
+    RoleName,
+    ServiceName,
+    UserId,
+)
+
+__all__ = [
+    # Entities
+    "User",
+    "Organization",
+    "Permission",
+    "Role",
+    "Membership",
+    "AuthContext",
+    "Service",
+    "OrganizationService",
+    # Value objects
+    "UserId",
+    "OrgId",
+    "RoleId",
+    "PermissionId",
+    "RoleName",
+    "PermissionKey",
+    "PermissionVisibility",
+    "ServiceName",
+    "LocalizedText",
+    # Ports (Protocols)
+    "UserRepository",
+    "OrganizationRepository",
+    "RoleRepository",
+    "MembershipRepository",
+    "PermissionCatalogRepository",
+    "ServiceRepository",
+    "OrganizationServiceRepository",
+    # Application DTOs
+    "CatalogEntry",
+    "ServiceSpec",
+    "PermissionScope",
+    # Config
+    "default_locale",
+    # Platform helpers
+    "is_platform_context",
+    # Exceptions
+    "AuthorizationError",
+    "NotAMember",
+    "MissingPermission",
+    "UnknownOrganization",
+    "UnknownUser",
+    "UnknownRole",
+    "UnknownPermission",
+    "UnknownService",
+    "ServiceNotSaaSAvailable",
+    "ServiceNotEnabled",
+    "PermissionVisibilityConflict",
+    "UserNotProvisioned",
+]

pkg_auth/authorization/adapters/__init__.py

@@ -0,0 +1 @@
+"""Authorization adapter implementations (sqlalchemy, django_orm, cache)."""

pkg_auth/authorization/adapters/cache/__init__.py

@@ -0,0 +1,32 @@
+"""Pluggable cache layer for the ACL hot path.
+
+Public API:
+
+    Cache                       — Protocol port (bytes-in/bytes-out)
+    InMemoryTTLCache            — zero-deps in-process LRU + TTL cache
+    RedisCache                  — async redis backend (cache-redis extra)
+    CachedMembershipRepository  — decorator wrapping any MembershipRepository
+"""
+from __future__ import annotations
+
+from .decorators import (
+    CachedMembershipRepository,
+    CachedOrganizationServiceRepository,
+)
+from .memory import InMemoryTTLCache
+from .protocol import Cache
+
+__all__ = [
+    "Cache",
+    "InMemoryTTLCache",
+    "CachedMembershipRepository",
+    "CachedOrganizationServiceRepository",
+]
+
+# RedisCache is opt-in via the cache-redis extra. Don't import it
+# eagerly so users without redis installed don't see import errors.
+try:
+    from .redis import RedisCache  # noqa: F401
+    __all__.append("RedisCache")
+except ImportError:  # pragma: no cover
+    pass

pkg_auth/authorization/adapters/cache/decorators.py

@@ -0,0 +1,181 @@
+"""CachedMembershipRepository — decorator wrapping any MembershipRepository.
+
+Implements the same Protocol as the underlying repository, so it can be
+passed into use cases anywhere ``MembershipRepository`` is expected. The
+hot-path :meth:`load_auth_context` is the one that actually consults the
+cache; other methods proxy through and invalidate the affected key on
+writes.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from uuid import UUID
+
+from ...domain.entities import AuthContext, Membership, OrganizationService
+from ...domain.ports import (
+    MembershipRepository,
+    OrganizationServiceRepository,
+)
+from ...domain.value_objects import OrgId, RoleId, RoleName, ServiceName, UserId
+from .protocol import Cache
+
+DEFAULT_TTL_SECONDS = 30
+
+
+def _auth_context_key(user_id: UserId, org_id: OrgId) -> str:
+    return f"auth_ctx:{user_id}:{org_id}"
+
+
+def _org_services_key(org_id: OrgId) -> str:
+    return f"org_services:{org_id}"
+
+
+def _serialize_auth_context(ctx: AuthContext) -> bytes:
+    payload = {
+        "user_id": str(ctx.user_id.value),
+        "organization_id": str(ctx.organization_id.value),
+        "role_names": sorted(ctx.role_names),
+        "perms": sorted(ctx.perms),
+    }
+    return json.dumps(payload).encode("utf-8")
+
+
+def _deserialize_auth_context(blob: bytes) -> AuthContext:
+    payload = json.loads(blob.decode("utf-8"))
+    return AuthContext(
+        user_id=UserId(UUID(payload["user_id"])),
+        organization_id=OrgId(UUID(payload["organization_id"])),
+        role_names=frozenset(payload["role_names"]),
+        perms=frozenset(payload["perms"]),
+    )
+
+
+@dataclass(slots=True)
+class CachedMembershipRepository:
+    """Cache-decorating wrapper around a real ``MembershipRepository``.
+
+    Usage::
+
+        inner = SqlAlchemyMembershipRepository(session_factory=...)
+        cache = InMemoryTTLCache(max_entries=10_000)
+        membership_repo = CachedMembershipRepository(
+            inner=inner, cache=cache, ttl_seconds=30,
+        )
+
+    Cache invalidation:
+        - :meth:`upsert` and :meth:`delete` invalidate the affected
+          ``(user_id, org_id)`` key.
+        - **Role-level changes** (e.g. updating a role's permission set)
+          affect many cached entries and are NOT auto-invalidated. The
+          calling use case must call ``cache.invalidate_prefix("auth_ctx:")``
+          after the role mutation. The package documents this convention
+          in ``docs/Caching.md``; we deliberately don't hide it because
+          guessing wrong here would silently serve stale perms.
+    """
+
+    inner: MembershipRepository
+    cache: Cache
+    ttl_seconds: int = DEFAULT_TTL_SECONDS
+
+    async def get(
+        self, user_id: UserId, org_id: OrgId
+    ) -> Membership | None:
+        return await self.inner.get(user_id, org_id)
+
+    async def upsert(
+        self,
+        *,
+        user_id: UserId,
+        org_id: OrgId,
+        role_id: RoleId,
+        status: str,
+    ) -> Membership:
+        result = await self.inner.upsert(
+            user_id=user_id,
+            org_id=org_id,
+            role_id=role_id,
+            status=status,
+        )
+        await self.cache.delete(_auth_context_key(user_id, org_id))
+        return result
+
+    async def delete(self, user_id: UserId, org_id: OrgId) -> None:
+        await self.inner.delete(user_id, org_id)
+        await self.cache.delete(_auth_context_key(user_id, org_id))
+
+    async def load_auth_context(
+        self, user_id: UserId, org_id: OrgId
+    ) -> AuthContext | None:
+        cache_key = _auth_context_key(user_id, org_id)
+        blob = await self.cache.get(cache_key)
+        if blob is not None:
+            return _deserialize_auth_context(blob)
+        ctx = await self.inner.load_auth_context(user_id, org_id)
+        if ctx is not None:
+            await self.cache.set(
+                cache_key,
+                _serialize_auth_context(ctx),
+                ttl_seconds=self.ttl_seconds,
+            )
+        return ctx
+
+    async def list_for_user(self, user_id: UserId) -> list[Membership]:
+        return await self.inner.list_for_user(user_id)
+
+
+@dataclass(slots=True)
+class CachedOrganizationServiceRepository:
+    """Cache-decorating wrapper around an ``OrganizationServiceRepository``.
+
+    Caches the per-org enabled-service-name set — read on every protected
+    request by the service guard in ``ResolveAuthContextUseCase``. Writes
+    (``enable`` / ``disable`` / ``bulk_enable``) invalidate the org's key.
+    """
+
+    inner: OrganizationServiceRepository
+    cache: Cache
+    ttl_seconds: int = DEFAULT_TTL_SECONDS
+
+    async def list_enabled_service_names(self, org_id: OrgId) -> set[str]:
+        cache_key = _org_services_key(org_id)
+        blob = await self.cache.get(cache_key)
+        if blob is not None:
+            return set(json.loads(blob.decode("utf-8")))
+        names = await self.inner.list_enabled_service_names(org_id)
+        await self.cache.set(
+            cache_key,
+            json.dumps(sorted(names)).encode("utf-8"),
+            ttl_seconds=self.ttl_seconds,
+        )
+        return names
+
+    async def get(
+        self, org_id: OrgId, service_name: ServiceName
+    ) -> OrganizationService | None:
+        return await self.inner.get(org_id, service_name)
+
+    async def enable(
+        self, org_id: OrgId, service_name: ServiceName, *, source: str
+    ) -> OrganizationService:
+        result = await self.inner.enable(
+            org_id, service_name, source=source
+        )
+        await self.cache.delete(_org_services_key(org_id))
+        return result
+
+    async def disable(
+        self, org_id: OrgId, service_name: ServiceName
+    ) -> None:
+        await self.inner.disable(org_id, service_name)
+        await self.cache.delete(_org_services_key(org_id))
+
+    async def bulk_enable(
+        self,
+        org_id: OrgId,
+        service_names: "list[ServiceName] | tuple[ServiceName, ...]",
+        *,
+        source: str,
+    ) -> None:
+        await self.inner.bulk_enable(org_id, service_names, source=source)
+        await self.cache.delete(_org_services_key(org_id))

pkg_auth/authorization/adapters/cache/memory.py

@@ -0,0 +1,61 @@
+"""In-process LRU + TTL cache (zero new dependencies)."""
+from __future__ import annotations
+
+import asyncio
+import time
+from collections import OrderedDict
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class InMemoryTTLCache:
+    """Per-process LRU cache with per-entry TTL.
+
+    Suitable for single-replica services or when freshness can tolerate
+    per-pod divergence. For horizontally-scaled services that need
+    cache coherence, use :class:`RedisCache` instead.
+
+    The cache is async-safe via an internal :class:`asyncio.Lock` —
+    multiple coroutines can hit it concurrently without races.
+    """
+
+    max_entries: int = 10_000
+    _store: OrderedDict[str, tuple[bytes, float]] = field(
+        default_factory=OrderedDict
+    )
+    _lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+
+    async def get(self, key: str) -> bytes | None:
+        async with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            value, expires_at = entry
+            if expires_at < time.monotonic():
+                # Expired — drop and miss
+                self._store.pop(key, None)
+                return None
+            # LRU touch
+            self._store.move_to_end(key)
+            return value
+
+    async def set(
+        self, key: str, value: bytes, *, ttl_seconds: int
+    ) -> None:
+        async with self._lock:
+            expires_at = time.monotonic() + ttl_seconds
+            if key in self._store:
+                self._store.move_to_end(key)
+            self._store[key] = (value, expires_at)
+            while len(self._store) > self.max_entries:
+                self._store.popitem(last=False)
+
+    async def delete(self, key: str) -> None:
+        async with self._lock:
+            self._store.pop(key, None)
+
+    async def invalidate_prefix(self, prefix: str) -> None:
+        async with self._lock:
+            doomed = [k for k in self._store if k.startswith(prefix)]
+            for k in doomed:
+                self._store.pop(k, None)

pkg_auth/authorization/adapters/cache/protocol.py

@@ -0,0 +1,36 @@
+"""Cache port — abstract bytes-in/bytes-out cache."""
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class Cache(Protocol):
+    """Bytes-keyed cache abstraction.
+
+    Implementations are bytes-in / bytes-out: serialization is the
+    decorator's responsibility, not the cache's. This keeps the protocol
+    portable across in-memory, Redis, memcached, etc.
+    """
+
+    async def get(self, key: str) -> bytes | None:
+        """Return the cached value, or ``None`` if missing or expired."""
+        ...
+
+    async def set(
+        self, key: str, value: bytes, *, ttl_seconds: int
+    ) -> None:
+        """Store ``value`` at ``key`` with the given TTL in seconds."""
+        ...
+
+    async def delete(self, key: str) -> None:
+        """Remove ``key`` if present. No-op if missing."""
+        ...
+
+    async def invalidate_prefix(self, prefix: str) -> None:
+        """Remove every key starting with ``prefix``.
+
+        Used for bulk invalidation when role-level changes affect many
+        cached AuthContexts at once. Implementations may use SCAN+DEL
+        on Redis or a single dict comprehension in memory.
+        """
+        ...

pkg_auth/authorization/adapters/cache/redis.py

@@ -0,0 +1,60 @@
+"""Async Redis cache backend (cache-redis extra)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+try:
+    import redis.asyncio as redis_asyncio  # noqa: F401
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "pkg_auth.authorization.adapters.cache.redis requires the redis "
+        "package. Install with: pip install pkg-auth[cache-redis]"
+    ) from exc
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis
+
+
+@dataclass(slots=True)
+class RedisCache:
+    """Async Redis-backed :class:`Cache` implementation.
+
+    The Redis client is injected — services build their own
+    ``redis.asyncio.Redis`` (with auth, sentinel, etc.) and hand it to
+    the cache. The cache itself only knows how to ``GET`` / ``SET`` /
+    ``DEL`` / ``SCAN``.
+
+    All keys are namespaced by ``namespace`` so this cache can coexist
+    with other Redis users in the same database without collision.
+    """
+
+    client: "Redis"
+    namespace: str = "pkg_auth:acl"
+    scan_count: int = 500
+
+    def _k(self, key: str) -> str:
+        return f"{self.namespace}:{key}"
+
+    async def get(self, key: str) -> bytes | None:
+        return await self.client.get(self._k(key))
+
+    async def set(
+        self, key: str, value: bytes, *, ttl_seconds: int
+    ) -> None:
+        await self.client.set(self._k(key), value, ex=ttl_seconds)
+
+    async def delete(self, key: str) -> None:
+        await self.client.delete(self._k(key))
+
+    async def invalidate_prefix(self, prefix: str) -> None:
+        match = f"{self._k(prefix)}*"
+        cursor = 0
+        while True:
+            cursor, keys = await self.client.scan(
+                cursor=cursor, match=match, count=self.scan_count
+            )
+            if keys:
+                await self.client.delete(*keys)
+            if cursor == 0:
+                break

pkg_auth/authorization/adapters/django_orm/__init__.py

@@ -0,0 +1,37 @@
+"""Django ORM adapter for the ACL schema (managed=False mirror models).
+
+The schema is owned by the SQLAlchemy adapter's Alembic migrations.
+This module provides Django ORM models pointing at the *same* physical
+tables, with ``Meta.managed = False`` so Django's ``makemigrations`` will
+not try to manage them. Repositories implement the same Protocols as
+the SQLAlchemy adapter, using Django's async ORM API (``acreate``,
+``aget``, etc.).
+
+Importing this module requires Django to be installed:
+
+    pip install pkg-auth[acl-django]
+
+The Django app label is ``pkg_auth_acl``. Add
+``"pkg_auth.authorization.adapters.django_orm"`` to your service's
+``INSTALLED_APPS``.
+"""
+from __future__ import annotations
+
+try:
+    import django  # noqa: F401
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "pkg_auth.authorization.adapters.django_orm requires Django. "
+        "Install with: pip install pkg-auth[acl-django]"
+    ) from exc
+
+default_app_config = "pkg_auth.authorization.adapters.django_orm.apps.PkgAuthAclConfig"
+
+# NOTE: do NOT import .mixins or .models from this __init__. Django needs
+# the apps registry to be ready before any ``models.Model`` subclass can
+# be defined, and __init__.py runs during app loading. Consumers should
+# import the abstract mixins directly:
+#
+#     from pkg_auth.authorization.adapters.django_orm.mixins import UserMixin
+
+__all__ = ["default_app_config"]

pkg_auth/authorization/adapters/django_orm/apps.py

@@ -0,0 +1,24 @@
+"""Django AppConfig for the pkg_auth ACL ORM mirror models."""
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class PkgAuthAclConfig(AppConfig):
+    """Django app holding the ACL ORM mirror models.
+
+    Tables are owned by Alembic migrations from the SQLAlchemy adapter,
+    so all models in this app declare ``Meta.managed = False``. Adding
+    this app to ``INSTALLED_APPS`` lets Django code query the ACL
+    tables via the ORM without managing the schema.
+    """
+
+    name = "pkg_auth.authorization.adapters.django_orm"
+    label = "pkg_auth_acl"
+    verbose_name = "pkg_auth ACL"
+    # default_auto_field must be an AutoField subclass — Django uses it
+    # only for models that don't declare their own PK. Every concrete
+    # ACL model in models.py declares a UUIDField PK explicitly, so this
+    # value is effectively unused at runtime; we leave it as the Django
+    # default for compatibility.
+    default_auto_field = "django.db.models.BigAutoField"

pkg_auth/authorization/adapters/django_orm/mixins.py

@@ -0,0 +1,142 @@
+"""Abstract Django model mixins for the ACL schema.
+
+These are the Django analog of the SQLAlchemy mixins in
+``pkg_auth.authorization.adapters.sqlalchemy.mixins`` — they declare the
+ACL-essential columns without specifying ``id``, ``db_table``, FK columns,
+or relationships. Consuming services that want to extend an ACL table
+with their own columns subclass the mixin and provide their own concrete
+``Meta`` (``abstract = False``).
+
+Example (service extends UserMixin)::
+
+    from pkg_auth.authorization.adapters.django_orm.mixins import UserMixin
+
+    class User(UserMixin):
+        id = models.UUIDField(primary_key=True, default=uuid.uuid4)
+        username = models.CharField(max_length=255)
+
+        class Meta:
+            db_table = "users"
+            app_label = "accounts"
+
+Services that do NOT need to extend use the default concrete models in
+``models.py`` (managed=False mirrors) directly.
+"""
+from __future__ import annotations
+
+from django.db import models
+
+
+class UserMixin(models.Model):
+    """ACL columns for the users table."""
+
+    keycloak_sub = models.CharField(max_length=64, unique=True)
+    email = models.CharField(max_length=255)
+    full_name = models.CharField(max_length=255, null=True, blank=True)
+    first_seen_at = models.DateTimeField(auto_now_add=True)
+    last_seen_at = models.DateTimeField(auto_now=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        abstract = True
+        app_label = "pkg_auth_acl"
+
+
+class OrganizationMixin(models.Model):
+    """ACL columns for the organizations table."""
+
+    slug = models.CharField(max_length=255, unique=True)
+    name = models.CharField(max_length=255)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        abstract = True
+        app_label = "pkg_auth_acl"
+
+
+class PermissionMixin(models.Model):
+    """ACL columns for the permissions (catalog) table.
+
+    ``visibility`` controls which role builders may see/use the permission:
+    ``platform_only`` (platform org only), ``shared`` (everywhere, default),
+    or ``tenant_only`` (normal orgs only — hidden from the platform org).
+    ``description`` is a localized JSONB ``{locale: text}`` map.
+    """
+
+    key = models.CharField(max_length=255, unique=True)
+    service_name = models.CharField(max_length=64)
+    description = models.JSONField(null=True, blank=True)
+    visibility = models.CharField(max_length=32, default="shared")
+    registered_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        abstract = True
+        app_label = "pkg_auth_acl"
+
+
+class ServiceMixin(models.Model):
+    """ACL columns for the ``services`` table (the service registry).
+
+    ``auto_provision`` and ``saas_available`` are vendor-controlled and set
+    only via the ``pkg-auth-sync-services`` path. ``display_label`` is a
+    localized JSONB map.
+    """
+
+    name = models.CharField(max_length=64, unique=True)
+    display_label = models.JSONField(null=True, blank=True)
+    auto_provision = models.BooleanField(default=False)
+    saas_available = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        abstract = True
+        app_label = "pkg_auth_acl"
+
+
+class OrganizationServiceMixin(models.Model):
+    """ACL columns for the ``organization_services`` table (per-org service
+    entitlements). The FK to organizations lives on the concrete model.
+    """
+
+    service_name = models.CharField(max_length=64)
+    enabled = models.BooleanField(default=True)
+    source = models.CharField(max_length=16, default="manual")
+    granted_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        abstract = True
+        app_label = "pkg_auth_acl"
+
+
+class RoleMixin(models.Model):
+    """ACL columns for the roles table."""
+
+    name = models.CharField(max_length=128)
+    description = models.TextField(null=True, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        abstract = True
+        app_label = "pkg_auth_acl"
+
+
+class MembershipMixin(models.Model):
+    """ACL columns for the memberships table.
+
+    Does NOT include ``status`` — services define their own status type
+    (string, choices field, etc.). Does NOT include FK columns or
+    relationships — those depend on the concrete model's schema and
+    table names.
+    """
+
+    joined_at = models.DateTimeField(auto_now_add=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        abstract = True
+        app_label = "pkg_auth_acl"