pkg-auth 3.0.0__py3-none-any.whl

pkg_auth/authorization/application/use_cases/update_role.py

@@ -0,0 +1,61 @@
+"""Update a role's name, description, or permission set."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+from ...domain.entities import Role
+from ...domain.exceptions import UnknownRole
+from ...domain.ports import PermissionCatalogRepository, RoleRepository
+from ...domain.value_objects import OrgId, PermissionKey, RoleId, RoleName
+from ._helpers import validate_permission_keys_for_role
+
+
+@dataclass(slots=True)
+class UpdateRoleUseCase:
+    """Update an existing role.
+
+    Pass ``None`` for any field to leave it unchanged. When
+    ``permission_keys`` is provided, every referenced key must already
+    exist in the permission catalog.
+
+    Note on cache invalidation: services that wrap their
+    ``MembershipRepository`` with ``CachedMembershipRepository`` should
+    invalidate the cache prefix after this call returns. The package
+    documents the convention but does not auto-invalidate.
+    """
+
+    role_repo: RoleRepository
+    catalog_repo: PermissionCatalogRepository
+    platform_org_id: OrgId | None = None
+
+    async def execute(
+        self,
+        role_id: RoleId,
+        *,
+        name: RoleName | None = None,
+        description: str | None = None,
+        permission_keys: Sequence[PermissionKey] | None = None,
+    ) -> Role:
+        existing = await self.role_repo.get(role_id)
+        if existing is None:
+            raise UnknownRole(f"role {role_id} not found")
+
+        if permission_keys is not None:
+            await validate_permission_keys_for_role(
+                self.catalog_repo,
+                permission_keys,
+                is_platform_org=self._is_platform_org(existing.organization_id),
+            )
+
+        return await self.role_repo.update(
+            role_id,
+            name=name,
+            description=description,
+            permission_keys=permission_keys,
+        )
+
+    def _is_platform_org(self, org_id: OrgId | None) -> bool | None:
+        if org_id is None or self.platform_org_id is None:
+            return None
+        return org_id == self.platform_org_id

pkg_auth/authorization/application/use_cases/upsert_membership.py

@@ -0,0 +1,54 @@
+"""Create or update a membership row."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...domain.entities import Membership
+from ...domain.exceptions import (
+    UnknownOrganization,
+    UnknownRole,
+    UnknownUser,
+)
+from ...domain.ports import (
+    MembershipRepository,
+    OrganizationRepository,
+    RoleRepository,
+    UserRepository,
+)
+from ...domain.value_objects import OrgId, RoleId, UserId
+
+
+@dataclass(slots=True)
+class UpsertMembershipUseCase:
+    """Idempotently grant a user a role in an organization.
+
+    Pre-flights the user, organization, and role to surface clean
+    domain exceptions instead of leaking adapter-level FK violations.
+    """
+
+    user_repo: UserRepository
+    organization_repo: OrganizationRepository
+    role_repo: RoleRepository
+    membership_repo: MembershipRepository
+
+    async def execute(
+        self,
+        *,
+        user_id: UserId,
+        org_id: OrgId,
+        role_id: RoleId,
+        status: str = "active",
+    ) -> Membership:
+        if await self.user_repo.get_by_id(user_id) is None:
+            raise UnknownUser(f"user {user_id} not found")
+        if await self.organization_repo.get(org_id) is None:
+            raise UnknownOrganization(f"organization {org_id} not found")
+        if await self.role_repo.get(role_id) is None:
+            raise UnknownRole(f"role {role_id} not found")
+
+        return await self.membership_repo.upsert(
+            user_id=user_id,
+            org_id=org_id,
+            role_id=role_id,
+            status=status,
+        )

pkg_auth/authorization/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI entrypoints for the authorization package."""

pkg_auth/authorization/cli/sync_catalog.py

@@ -0,0 +1,180 @@
+"""``pkg-auth-sync-catalog`` — deploy-time permission catalog sync.
+
+Intended for an init container that runs with a DB credential holding
+``INSERT, UPDATE, DELETE`` on ``permissions`` only. The long-running
+service should keep a separate SELECT-only credential and never call
+this CLI.
+
+Public surface is factored so services that want to customize something
+(extra flags, a different catalog loader, a pre-built session factory)
+can import the pieces and assemble their own entrypoint:
+
+    from pkg_auth.authorization.cli.sync_catalog import (
+        build_arg_parser, load_catalog, run,
+    )
+
+    def main() -> None:
+        parser = build_arg_parser()
+        parser.add_argument("--skip-legacy", action="store_true")
+        args = parser.parse_args()
+        asyncio.run(run(args, catalog_loader=my_loader))
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import os
+import sys
+from typing import Awaitable, Callable, Sequence
+
+from ..application.use_cases.register_permission_catalog import CatalogEntry
+from ..application.use_cases.sync_permission_catalog import (
+    SyncPermissionCatalogUseCase,
+    SyncResult,
+)
+from ..domain.ports import PermissionCatalogRepository, ServiceRepository
+
+CatalogLoader = Callable[[str], Sequence[CatalogEntry]]
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pkg-auth-sync-catalog",
+        description=(
+            "Sync a service's permission catalog against the ACL database: "
+            "UPSERT declared entries, DELETE anything for the service that "
+            "is no longer declared."
+        ),
+    )
+    parser.add_argument(
+        "--service",
+        required=True,
+        help="Service name whose catalog rows are managed by this run.",
+    )
+    parser.add_argument(
+        "--catalog",
+        required=True,
+        help=(
+            "Dotted path to the catalog iterable, e.g. "
+            "'courses.domain.permissions:CATALOG'."
+        ),
+    )
+    parser.add_argument(
+        "--db-url",
+        default=os.environ.get("ACL_DATABASE_URL"),
+        help=(
+            "SQLAlchemy async DB URL for the ACL database. "
+            "Falls back to the ACL_DATABASE_URL env var."
+        ),
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help=(
+            "Do not write. Print what would be upserted / pruned and exit 0."
+        ),
+    )
+    return parser
+
+
+def load_catalog(dotted: str) -> list[CatalogEntry]:
+    """Resolve ``module.path:ATTR`` to a list of :class:`CatalogEntry`."""
+    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
+    return list(value)
+
+
+async def run(
+    args: argparse.Namespace,
+    *,
+    repo: PermissionCatalogRepository | None = None,
+    service_repo: ServiceRepository | None = None,
+    session_factory: object | None = None,
+    catalog_loader: CatalogLoader = load_catalog,
+) -> SyncResult:
+    dispose: Callable[[], Awaitable[None]] | None = None
+    if repo is None:
+        from sqlalchemy.ext.asyncio import (  # noqa: PLC0415
+            async_sessionmaker,
+            create_async_engine,
+        )
+
+        from ..adapters.sqlalchemy.repositories.permission_catalog import (  # noqa: PLC0415
+            SqlAlchemyPermissionCatalogRepository,
+        )
+        from ..adapters.sqlalchemy.repositories.service import (  # noqa: PLC0415
+            SqlAlchemyServiceRepository,
+        )
+
+        if session_factory is None:
+            if not args.db_url:
+                raise SystemExit(
+                    "--db-url is required (or set ACL_DATABASE_URL)"
+                )
+            engine = create_async_engine(args.db_url, future=True)
+            session_factory = async_sessionmaker(engine, expire_on_commit=False)
+            dispose = engine.dispose
+        repo = SqlAlchemyPermissionCatalogRepository(
+            session_factory=session_factory
+        )
+        if service_repo is None:
+            service_repo = SqlAlchemyServiceRepository(
+                session_factory=session_factory
+            )
+
+    entries = catalog_loader(args.catalog)
+    use_case = SyncPermissionCatalogUseCase(
+        catalog_repo=repo, service_repo=service_repo
+    )
+
+    if args.dry_run:
+        existing = await repo.list_for_service(args.service, scope="all")
+        existing_keys = {str(p.key) for p in existing}
+        declared_keys = {str(e.key) for e in entries}
+        to_add = sorted(declared_keys - existing_keys)
+        to_prune = sorted(existing_keys - declared_keys)
+        print(f"[dry-run] service={args.service}")
+        print(f"[dry-run] to add:   {to_add}")
+        print(f"[dry-run] to prune: {to_prune}")
+
+    try:
+        result = await use_case.execute(
+            service_name=args.service,
+            entries=entries,
+            dry_run=args.dry_run,
+        )
+    finally:
+        if dispose is not None:
+            await dispose()
+    return result
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = build_arg_parser()
+    args = parser.parse_args(argv)
+    try:
+        result = asyncio.run(run(args))
+    except SystemExit:
+        raise
+    except Exception as exc:
+        print(f"pkg-auth-sync-catalog: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+    print(
+        f"sync: service={args.service} upserted={result.upserted} "
+        f"pruned={result.pruned} dry_run={result.dry_run}"
+    )
+
+
+if __name__ == "__main__":
+    main()

pkg_auth/authorization/cli/sync_services.py

@@ -0,0 +1,151 @@
+"""``pkg-auth-sync-services`` — deploy-time service registry sync.
+
+The **vendor-only** path that declares which services exist and sets their
+``auto_provision`` / ``saas_available`` flags. Run from an init container
+with a DB credential that may write the ``services`` table. The runtime
+SaaS-toggle endpoint (:class:`SetOrganizationServiceUseCase`) can only
+enable services this CLI has marked ``saas_available``.
+
+The declared config is a dotted ``module:ATTR`` resolving to a sequence of
+:class:`ServiceSpec` (build them with ``ServiceSpec.make`` for ergonomic
+localized labels):
+
+    SERVICES = [
+        ServiceSpec.make("users", {"en": "Users"}, auto_provision=True),
+        ServiceSpec.make("assessments", {"en": "Assessments"},
+                         saas_available=True),
+    ]
+
+Composable pieces (``build_arg_parser``, ``load_services``, ``run``) mirror
+``sync_catalog`` so services can assemble custom entrypoints.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import os
+import sys
+from typing import Awaitable, Callable, Sequence
+
+from ..application.use_cases.sync_service_catalog import (
+    ServiceSpec,
+    ServiceSyncResult,
+    SyncServiceCatalogUseCase,
+)
+from ..domain.ports import ServiceRepository
+
+ServicesLoader = Callable[[str], Sequence[ServiceSpec]]
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pkg-auth-sync-services",
+        description=(
+            "Sync the vendor service registry against the ACL database: "
+            "UPSERT declared services (name, label, auto_provision, "
+            "saas_available), DELETE services no longer declared."
+        ),
+    )
+    parser.add_argument(
+        "--services",
+        required=True,
+        help=(
+            "Dotted path to the service-spec iterable, e.g. "
+            "'platform.services:SERVICES'."
+        ),
+    )
+    parser.add_argument(
+        "--db-url",
+        default=os.environ.get("ACL_DATABASE_URL"),
+        help=(
+            "SQLAlchemy async DB URL for the ACL database. "
+            "Falls back to the ACL_DATABASE_URL env var."
+        ),
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Do not write. Print what would be upserted / pruned and exit 0.",
+    )
+    return parser
+
+
+def load_services(dotted: str) -> list[ServiceSpec]:
+    """Resolve ``module.path:ATTR`` to a list of :class:`ServiceSpec`."""
+    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
+    return list(value)
+
+
+async def run(
+    args: argparse.Namespace,
+    *,
+    repo: ServiceRepository | None = None,
+    session_factory: object | None = None,
+    services_loader: ServicesLoader = load_services,
+) -> ServiceSyncResult:
+    dispose: Callable[[], Awaitable[None]] | None = None
+    if repo is None:
+        from sqlalchemy.ext.asyncio import (  # noqa: PLC0415
+            async_sessionmaker,
+            create_async_engine,
+        )
+
+        from ..adapters.sqlalchemy.repositories.service import (  # noqa: PLC0415
+            SqlAlchemyServiceRepository,
+        )
+
+        if session_factory is None:
+            if not args.db_url:
+                raise SystemExit(
+                    "--db-url is required (or set ACL_DATABASE_URL)"
+                )
+            engine = create_async_engine(args.db_url, future=True)
+            session_factory = async_sessionmaker(engine, expire_on_commit=False)
+            dispose = engine.dispose
+        repo = SqlAlchemyServiceRepository(session_factory=session_factory)
+
+    services = services_loader(args.services)
+    use_case = SyncServiceCatalogUseCase(service_repo=repo)
+
+    if args.dry_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)}")
+
+    try:
+        result = await use_case.execute(services=services, dry_run=args.dry_run)
+    finally:
+        if dispose is not None:
+            await dispose()
+    return result
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = build_arg_parser()
+    args = parser.parse_args(argv)
+    try:
+        result = asyncio.run(run(args))
+    except SystemExit:
+        raise
+    except Exception as exc:
+        print(f"pkg-auth-sync-services: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+    print(
+        f"sync-services: upserted={result.upserted} "
+        f"pruned={result.pruned} dry_run={result.dry_run}"
+    )
+
+
+if __name__ == "__main__":
+    main()

pkg_auth/authorization/config.py

@@ -0,0 +1,21 @@
+"""Process-level authorization config read from the environment.
+
+Kept out of the (pure) domain layer so value objects stay free of I/O.
+The application/adapter/CLI layers call :func:`default_locale` when they
+need to coerce a bare-string description into a :class:`LocalizedText`.
+"""
+from __future__ import annotations
+
+import os
+
+DEFAULT_LOCALE_ENV = "ACL_DEFAULT_LOCALE"
+FALLBACK_LOCALE = "en"
+
+
+def default_locale() -> str:
+    """Return the configured default/fallback locale.
+
+    Reads ``ACL_DEFAULT_LOCALE`` from the environment, falling back to
+    ``"en"`` when unset or empty.
+    """
+    return os.environ.get(DEFAULT_LOCALE_ENV) or FALLBACK_LOCALE

pkg_auth/authorization/domain/__init__.py

@@ -0,0 +1 @@
+"""Authorization domain layer (entities, value objects, ports, exceptions)."""

pkg_auth/authorization/domain/entities.py

@@ -0,0 +1,192 @@
+"""Authorization domain entities.
+
+All entities are frozen dataclasses with slots. They are loaded from the
+central ACL database by the SQLAlchemy / Django ORM repositories and
+treated as immutable snapshots. The entities are schema-agnostic — the
+concrete ``db_table`` / ``__tablename__`` values live in the adapter
+layer, and source-of-truth services that extend the ACL tables (Mode A)
+pick their own schema and table names via the mixin pattern.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from uuid import UUID
+
+from .exceptions import MissingPermission
+from .value_objects import (
+    LocalizedText,
+    OrgId,
+    PermissionId,
+    PermissionKey,
+    PermissionVisibility,
+    RoleId,
+    RoleName,
+    ServiceName,
+    UserId,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class User:
+    """A row from the ``users`` table.
+
+    The package owns the users table; rows are upserted lazily on the
+    first JWT seen by ``SyncUserFromJwtUseCase``. ``keycloak_sub`` is
+    the unique link to the IdP identity.
+    """
+
+    id: UserId
+    keycloak_sub: str
+    email: str
+    full_name: str | None
+    first_seen_at: datetime
+    last_seen_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class Organization:
+    """A row from the ``organizations`` table."""
+
+    id: OrgId
+    slug: str
+    name: str
+    created_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class Permission:
+    """A row from the ``permissions`` table (the global permission catalog).
+
+    Each downstream service registers its own permission keys on boot
+    via ``RegisterPermissionCatalogUseCase``. ``visibility`` controls
+    which role builders may see/use the permission (platform-only,
+    shared, or tenant-only — hidden from the platform org). ``description``
+    is a localized text map (``{"en": ..., "ar": ...}``) for the central
+    role-editor UI.
+    """
+
+    id: PermissionId
+    key: PermissionKey
+    service_name: str
+    description: LocalizedText
+    visibility: PermissionVisibility = PermissionVisibility.SHARED
+
+
+@dataclass(frozen=True, slots=True)
+class Service:
+    """A row from the ``services`` table — a deployable product surface
+    (e.g. ``assessments``, ``courses``) that an organization may be granted.
+
+    ``auto_provision`` services are enabled automatically for every new
+    organization. ``saas_available`` marks a service the **vendor** has
+    greenlit to be offered as SaaS; only those may be enabled for an org
+    through the runtime API. Both flags are vendor-controlled and set via
+    the ``pkg-auth-sync-services`` CLI / config — never a runtime endpoint.
+    """
+
+    name: ServiceName
+    display_label: LocalizedText
+    auto_provision: bool = False
+    saas_available: bool = False
+    created_at: datetime | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class OrganizationService:
+    """A row from the ``organization_services`` table — the entitlement
+    linking an organization to a service it may use.
+
+    ``source`` is ``"auto"`` (granted by default-service provisioning) or
+    ``"manual"`` (toggled by a platform admin). The service guard in
+    :class:`ResolveAuthContextUseCase` drops any permission whose
+    ``service_name`` is not enabled for the org.
+    """
+
+    organization_id: OrgId
+    service_name: ServiceName
+    enabled: bool = True
+    source: str = "manual"
+    granted_at: datetime | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Role:
+    """A row from the ``roles`` table.
+
+    ``organization_id`` is ``None`` for global role templates that can
+    be reused across organizations. ``permission_keys`` is the
+    denormalized set of permission strings the role grants — fast for
+    in-memory ``.has(perm)`` checks at the call site.
+    """
+
+    id: RoleId
+    organization_id: OrgId | None
+    name: RoleName
+    description: str | None
+    permission_keys: frozenset[str] = field(default_factory=frozenset)
+
+
+@dataclass(frozen=True, slots=True)
+class Membership:
+    """A row from the ``memberships`` table.
+
+    ``role_name`` is denormalized from the joined role for cheap
+    construction of an :class:`AuthContext` without re-querying. A user
+    can hold multiple memberships in the same organization — one row per
+    role — and the schema enforces uniqueness on
+    ``(user_id, organization_id, role_id)``.
+    """
+
+    id: UUID
+    user_id: UserId
+    organization_id: OrgId
+    role_id: RoleId
+    role_name: RoleName
+    status: str
+    joined_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class AuthContext:
+    """Hot-path authorization context for a (user, organization) request.
+
+    Built once per request by ``ResolveAuthContextUseCase`` and passed
+    through to handlers. A user can have **multiple roles** in an org;
+    ``perms`` is the **union** of all active roles' permissions.
+
+    Frozen because handler code must not mutate the perms set after the
+    dependency layer has built it.
+
+    pkg_auth deliberately does NOT carry a ``is_platform`` flag here.
+    Platform-admin detection is a *service-level* policy: consuming
+    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.
+    """
+
+    user_id: UserId
+    organization_id: OrgId
+    role_names: frozenset[str]
+    perms: frozenset[str]
+
+    def has(self, perm: str) -> bool:
+        """Return ``True`` if any of the user's roles grant ``perm``."""
+        return perm in self.perms
+
+    def require(self, perm: str) -> None:
+        """Raise :class:`MissingPermission` if ``perm`` is not granted.
+
+        Equivalent to ``if not ctx.has(perm): raise MissingPermission(...)``
+        but exported as a method for ergonomic ``ctx.require("course:edit")``
+        call sites.
+        """
+        if perm not in self.perms:
+            raise MissingPermission(
+                f"permission {perm!r} required on org {self.organization_id} "
+                f"(roles {sorted(self.role_names)})"
+            )
+
+    def has_role(self, role: str) -> bool:
+        """Return ``True`` if the user has the named role in this org."""
+        return role in self.role_names