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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pkg-auth
-Version: 3.0.0
+Version: 3.1.0
 Summary: Clean-architecture auth core for multiple Python frameworks
 Author-email: Fritill <info@fritill.ae>
 License: MIT
@@ -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.1.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.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pkg-auth"
-version = "3.0.0"
+version = "3.1.0"
 description = "Clean-architecture auth core for multiple Python frameworks"
 readme = "README.md"
 requires-python = ">=3.10"

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

@@ -15,7 +15,10 @@ 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 (
@@ -96,6 +99,7 @@ __all__ = [
     # Application DTOs
     "CatalogEntry",
     "ServiceSpec",
+    "ServiceManifest",
     "PermissionScope",
     # Config
     "default_locale",

{pkg_auth-3.0.0 → pkg_auth-3.1.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.1.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.1.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.0.0 → pkg_auth-3.1.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,

{pkg_auth-3.0.0 → pkg_auth-3.1.0}/src/pkg_auth/authorization/application/use_cases/sync_service_catalog.py

@@ -59,7 +59,16 @@ class ServiceSyncResult:
 
 @dataclass(slots=True)
 class SyncServiceCatalogUseCase:
-    """Upsert declared services then prune services no longer declared."""
+    """Apply vendor flags to declared services (the overlay model).
+
+    Upserts each declared service's vendor flags (``auto_provision`` /
+    ``saas_available``) without clobbering a service-owned ``display_label``.
+    Because each service registers its own identity row (via
+    ``pkg-auth-sync-catalog``), this does **not** prune by default — a service
+    the vendor list omits is simply left ungoverned, not deleted. Pass
+    ``prune=True`` for an explicit, central cleanup of services no longer
+    declared anywhere.
+    """
 
     service_repo: ServiceRepository
 
@@ -67,23 +76,28 @@ class SyncServiceCatalogUseCase:
         self,
         *,
         services: Sequence[ServiceSpec],
+        prune: bool = False,
         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
+            would_prune = 0
+            if prune:
+                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 = len(existing_names - declared_names)
             return ServiceSyncResult(
                 upserted=len(services),
-                pruned=len(would_prune),
+                pruned=would_prune,
                 dry_run=True,
             )
 
         await self.service_repo.upsert_many(services)
-        pruned = await self.service_repo.prune_absent(keep=keep)
+        pruned = 0
+        if prune:
+            pruned = await self.service_repo.prune_absent(keep=keep)
         return ServiceSyncResult(
             upserted=len(services),
             pruned=pruned,

{pkg_auth-3.0.0 → pkg_auth-3.1.0}/src/pkg_auth/authorization/cli/sync_catalog.py

@@ -28,7 +28,10 @@ import os
 import sys
 from typing import Awaitable, Callable, Sequence
 
-from ..application.use_cases.register_permission_catalog import CatalogEntry
+from ..application.use_cases.register_permission_catalog import (
+    CatalogEntry,
+    ServiceManifest,
+)
 from ..application.use_cases.sync_permission_catalog import (
     SyncPermissionCatalogUseCase,
     SyncResult,
@@ -36,6 +39,7 @@ from ..application.use_cases.sync_permission_catalog import (
 from ..domain.ports import PermissionCatalogRepository, ServiceRepository
 
 CatalogLoader = Callable[[str], Sequence[CatalogEntry]]
+ManifestLoader = Callable[[str], ServiceManifest]
 
 
 def build_arg_parser() -> argparse.ArgumentParser:
@@ -60,6 +64,17 @@ def build_arg_parser() -> argparse.ArgumentParser:
             "'courses.domain.permissions:CATALOG'."
         ),
     )
+    parser.add_argument(
+        "--service-manifest",
+        default=None,
+        help=(
+            "Optional dotted path to a ServiceManifest the service registers "
+            "for itself, e.g. 'courses.domain.permissions:SERVICE'. Its name "
+            "must match --service; its display_label seeds/updates the "
+            "service's identity row. Vendor flags stay owned by "
+            "pkg-auth-sync-services."
+        ),
+    )
     parser.add_argument(
         "--db-url",
         default=os.environ.get("ACL_DATABASE_URL"),
@@ -95,6 +110,26 @@ def load_catalog(dotted: str) -> list[CatalogEntry]:
     return list(value)
 
 
+def load_manifest(dotted: str) -> ServiceManifest:
+    """Resolve ``module.path:ATTR`` to a :class:`ServiceManifest`."""
+    if ":" not in dotted:
+        raise ValueError(f"Expected 'module.path:ATTR', got {dotted!r}")
+    module_path, attr = dotted.split(":", 1)
+    module = importlib.import_module(module_path)
+    try:
+        value = getattr(module, attr)
+    except AttributeError as exc:
+        raise ValueError(
+            f"Module {module_path!r} has no attribute {attr!r}"
+        ) from exc
+    if not isinstance(value, ServiceManifest):
+        raise ValueError(
+            f"{dotted!r} is not a ServiceManifest (got "
+            f"{type(value).__name__})"
+        )
+    return value
+
+
 async def run(
     args: argparse.Namespace,
     *,
@@ -102,6 +137,7 @@ async def run(
     service_repo: ServiceRepository | None = None,
     session_factory: object | None = None,
     catalog_loader: CatalogLoader = load_catalog,
+    manifest_loader: ManifestLoader = load_manifest,
 ) -> SyncResult:
     dispose: Callable[[], Awaitable[None]] | None = None
     if repo is None:
@@ -134,6 +170,17 @@ async def run(
             )
 
     entries = catalog_loader(args.catalog)
+
+    display_label = None
+    if args.service_manifest:
+        manifest = manifest_loader(args.service_manifest)
+        if str(manifest.name) != args.service:
+            raise SystemExit(
+                f"manifest name {str(manifest.name)!r} does not match "
+                f"--service {args.service!r}"
+            )
+        display_label = manifest.display_label
+
     use_case = SyncPermissionCatalogUseCase(
         catalog_repo=repo, service_repo=service_repo
     )
@@ -152,6 +199,7 @@ async def run(
         result = await use_case.execute(
             service_name=args.service,
             entries=entries,
+            display_label=display_label,
             dry_run=args.dry_run,
         )
     finally:

{pkg_auth-3.0.0 → pkg_auth-3.1.0}/src/pkg_auth/authorization/cli/sync_services.py

@@ -63,6 +63,15 @@ def build_arg_parser() -> argparse.ArgumentParser:
             "Falls back to the ACL_DATABASE_URL env var."
         ),
     )
+    parser.add_argument(
+        "--prune",
+        action="store_true",
+        help=(
+            "Also DELETE services not in this list. Off by default (overlay "
+            "model: services own their own identity rows). Use only for an "
+            "explicit central cleanup."
+        ),
+    )
     parser.add_argument(
         "--dry-run",
         action="store_true",
@@ -121,10 +130,13 @@ async def run(
         existing = {str(s.name) for s in await repo.list_all()}
         declared = {str(s.name) for s in services}
         print(f"[dry-run] to add:   {sorted(declared - existing)}")
-        print(f"[dry-run] to prune: {sorted(existing - declared)}")
+        if args.prune:
+            print(f"[dry-run] to prune: {sorted(existing - declared)}")
 
     try:
-        result = await use_case.execute(services=services, dry_run=args.dry_run)
+        result = await use_case.execute(
+            services=services, prune=args.prune, dry_run=args.dry_run
+        )
     finally:
         if dispose is not None:
             await dispose()

{pkg_auth-3.0.0 → pkg_auth-3.1.0}/src/pkg_auth/authorization/domain/ports.py

@@ -20,6 +20,7 @@ from .entities import (
     User,
 )
 from .value_objects import (
+    LocalizedText,
     OrgId,
     PermissionKey,
     RoleId,
@@ -176,16 +177,34 @@ class PermissionCatalogRepository(Protocol):
 class ServiceRepository(Protocol):
     """Read/write access to the ``services`` table (the service registry).
 
-    Vendor-controlled flags (``auto_provision``, ``saas_available``) are
-    written only via :meth:`upsert_many` (the ``pkg-auth-sync-services``
-    path). :meth:`ensure_exists` is called during permission-catalog
-    registration to create a bare row with safe defaults so the
-    default-deny guard does not strip a newly-registered service's perms
-    before the vendor configures it; it must NOT overwrite existing flags.
+    Ownership is split into two non-overlapping concerns so services can be
+    rolled out independently (the *overlay* model):
+
+    - **Identity** (``name`` + ``display_label``) is owned by each service and
+      written via :meth:`register_identity` from its own catalog sync
+      (``pkg-auth-sync-catalog``). A service registers itself.
+    - **Vendor flags** (``auto_provision``, ``saas_available``) are owned by the
+      vendor and written via :meth:`upsert_many` (``pkg-auth-sync-services``).
+
+    Neither path clobbers the other's fields: :meth:`register_identity` never
+    touches the flags, and :meth:`upsert_many` never overwrites an existing
+    row's ``display_label``. Because each service owns its own row,
+    ``pkg-auth-sync-services`` does NOT prune by default; :meth:`prune_absent`
+    remains available for an explicit, opt-in cleanup.
     """
 
     async def upsert_many(self, services: Sequence["ServiceSpec"]) -> None: ...
-    async def ensure_exists(self, *, service_name: str) -> None: ...
+    async def register_identity(
+        self, *, name: str, display_label: LocalizedText | None = None
+    ) -> None:
+        """Self-register a service's identity (idempotent).
+
+        Insert a row for ``name`` if absent (flags default ``False`` so the
+        default-deny guard does not strip the service's perms before the vendor
+        configures it). If the row exists, update ``display_label`` only when a
+        non-empty label is given; never touch the vendor flags.
+        """
+        ...
     async def get(self, name: ServiceName) -> Service | None: ...
     async def list_all(self) -> list[Service]: ...
     async def prune_absent(

{pkg_auth-3.0.0 → pkg_auth-3.1.0}/src/pkg_auth.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pkg-auth
-Version: 3.0.0
+Version: 3.1.0
 Summary: Clean-architecture auth core for multiple Python frameworks
 Author-email: Fritill <info@fritill.ae>
 License: MIT
@@ -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)