pkg-auth 3.0.0__tar.gz

pkg_auth-3.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: pkg-auth
+Version: 3.0.0
+Summary: Clean-architecture auth core for multiple Python frameworks
+Author-email: Fritill <info@fritill.ae>
+License: MIT
+Project-URL: Homepage, https://github.com/fritill-team/fri_pkg_auth
+Project-URL: Repository, https://github.com/fritill-team/fri_pkg_auth
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pyjwt[crypto]>=2.10.1
+Requires-Dist: requests>=2.32.3
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio<1.0.0,>=0.23.0; extra == "dev"
+Requires-Dist: mypy<2.0.0,>=1.11.0; extra == "dev"
+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: asyncpg>=0.29; extra == "acl-sqlalchemy"
+Requires-Dist: alembic>=1.13; extra == "acl-sqlalchemy"
+Provides-Extra: acl-django
+Requires-Dist: django>=4.2; extra == "acl-django"
+Requires-Dist: psycopg[binary]>=3.1; extra == "acl-django"
+Provides-Extra: cache-redis
+Requires-Dist: redis>=5.0; extra == "cache-redis"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115; extra == "fastapi"
+Requires-Dist: starlette>=0.37; extra == "fastapi"
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: strawberry
+Requires-Dist: strawberry-graphql>=0.255; extra == "strawberry"
+Provides-Extra: all
+Requires-Dist: django>=6.0; extra == "all"
+Requires-Dist: fastapi>=0.115; extra == "all"
+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: asyncpg>=0.29; extra == "all"
+Requires-Dist: alembic>=1.13; extra == "all"
+Requires-Dist: redis>=5.0; extra == "all"
+
+# pkg-auth
+
+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.
+
+## Install
+
+```bash
+# 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 + Django
+pip install pkg-auth[acl-django,django]
+
+# With optional Redis cache
+pip install pkg-auth[cache-redis]
+```
+
+## Quickstart (FastAPI)
+
+```python
+from fastapi import Depends, FastAPI
+from pkg_auth.authentication import IdentityContext
+from pkg_auth.authorization import AuthContext
+from pkg_auth.integrations.fastapi import (
+    create_authentication,
+    make_get_auth_context,
+    require_permission,
+)
+
+# --- Wire authentication + authorization ---
+
+auth = create_authentication(
+    keycloak_base_url="https://auth.example.com",
+    realm="itqadem",
+    audience="courses-service",
+)
+
+# Mode B (consumer — the common case): pass resolve_user_use_case.
+# Mode A (source-of-truth): pass sync_user_use_case instead. Exactly
+# one of the two is required; passing both raises ValueError.
+get_auth_context = make_get_auth_context(
+    get_identity=auth.get_identity,
+    resolve_user_use_case=resolve_user,   # or: sync_user_use_case=sync_user (Mode A)
+    resolve_use_case=resolve,
+    organization_repo=org_repo,
+)
+
+app = FastAPI()
+
+# --- Use in routes ---
+
+@app.get("/courses/{id}")
+async def get_course(
+    id: str,
+    bundle: tuple[IdentityContext, AuthContext] = Depends(
+        require_permission("course:view", get_auth_context=get_auth_context)
+    ),
+):
+    identity, auth_ctx = bundle
+    return {"course_id": id, "role": str(auth_ctx.role_name)}
+```
+
+See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complete working example.
+
+## Architecture
+
+```
+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)
+    adapters/
+      sqlalchemy/             Canonical schema + Alembic migration + repos
+      django_orm/             Mirror models (managed=False) + repos
+      cache/                  InMemoryTTLCache / RedisCache + decorator
+  integrations/
+    fastapi/                  Deps + require_permission + exception handlers
+    django/                   Middleware + decorators
+    strawberry/               Context getter + permission classes
+  admin/                      Keycloak admin client (user provisioning)
+```
+
+**Layering rules**: domain has zero external imports; application imports only domain; adapters import their framework; integrations import everything.
+
+## Documentation
+
+- [Authorization model](docs/Authorization.md) — schema, permission catalog, roles, memberships
+- [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)

pkg_auth-3.0.0/README.md

@@ -0,0 +1,99 @@
+# pkg-auth
+
+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.
+
+## Install
+
+```bash
+# 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 + Django
+pip install pkg-auth[acl-django,django]
+
+# With optional Redis cache
+pip install pkg-auth[cache-redis]
+```
+
+## Quickstart (FastAPI)
+
+```python
+from fastapi import Depends, FastAPI
+from pkg_auth.authentication import IdentityContext
+from pkg_auth.authorization import AuthContext
+from pkg_auth.integrations.fastapi import (
+    create_authentication,
+    make_get_auth_context,
+    require_permission,
+)
+
+# --- Wire authentication + authorization ---
+
+auth = create_authentication(
+    keycloak_base_url="https://auth.example.com",
+    realm="itqadem",
+    audience="courses-service",
+)
+
+# Mode B (consumer — the common case): pass resolve_user_use_case.
+# Mode A (source-of-truth): pass sync_user_use_case instead. Exactly
+# one of the two is required; passing both raises ValueError.
+get_auth_context = make_get_auth_context(
+    get_identity=auth.get_identity,
+    resolve_user_use_case=resolve_user,   # or: sync_user_use_case=sync_user (Mode A)
+    resolve_use_case=resolve,
+    organization_repo=org_repo,
+)
+
+app = FastAPI()
+
+# --- Use in routes ---
+
+@app.get("/courses/{id}")
+async def get_course(
+    id: str,
+    bundle: tuple[IdentityContext, AuthContext] = Depends(
+        require_permission("course:view", get_auth_context=get_auth_context)
+    ),
+):
+    identity, auth_ctx = bundle
+    return {"course_id": id, "role": str(auth_ctx.role_name)}
+```
+
+See [`examples/itqadem_courses_app`](examples/itqadem_courses_app) for a complete working example.
+
+## Architecture
+
+```
+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)
+    adapters/
+      sqlalchemy/             Canonical schema + Alembic migration + repos
+      django_orm/             Mirror models (managed=False) + repos
+      cache/                  InMemoryTTLCache / RedisCache + decorator
+  integrations/
+    fastapi/                  Deps + require_permission + exception handlers
+    django/                   Middleware + decorators
+    strawberry/               Context getter + permission classes
+  admin/                      Keycloak admin client (user provisioning)
+```
+
+**Layering rules**: domain has zero external imports; application imports only domain; adapters import their framework; integrations import everything.
+
+## Documentation
+
+- [Authorization model](docs/Authorization.md) — schema, permission catalog, roles, memberships
+- [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)

pkg_auth-3.0.0/pyproject.toml

@@ -0,0 +1,133 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pkg-auth"
+version = "3.0.0"
+description = "Clean-architecture auth core for multiple Python frameworks"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+
+authors = [
+    { name = "Fritill", email = "info@fritill.ae" }
+]
+
+# Runtime dependencies
+dependencies = [
+    "httpx>=0.28.1",
+    "pyjwt[crypto]>=2.10.1",
+    "requests>=2.32.3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0,<9.0.0",
+    "pytest-asyncio>=0.23.0,<1.0.0",
+    "mypy>=1.11.0,<2.0.0",
+    "types-requests>=2.32.0.0,<3.0.0.0",
+    "types-PyJWT>=1.7.0,<2.0.0",
+    "testcontainers[postgres,redis]>=4.0",
+]
+
+# ACL storage backends (v1.0)
+acl-sqlalchemy = [
+    "sqlalchemy>=2.0,<3.0",
+    "asyncpg>=0.29",
+    "alembic>=1.13",
+]
+acl-django = [
+    "django>=4.2",
+    "psycopg[binary]>=3.1",
+]
+
+# Cache backends (v1.0)
+cache-redis = [
+    "redis>=5.0",
+]
+
+# Framework integrations
+fastapi = [
+    "fastapi>=0.115",
+    "starlette>=0.37",
+]
+django = [
+    "django>=4.2",
+]
+strawberry = [
+    "strawberry-graphql>=0.255",
+]
+
+# Convenience meta-extra
+all = [
+    "django>=6.0",
+    "fastapi>=0.115",
+    "starlette>=0.37",
+    "django>=4.2",
+    "psycopg[binary]>=3.1",
+    "strawberry-graphql>=0.255",
+    "sqlalchemy>=2.0,<3.0",
+    "asyncpg>=0.29",
+    "alembic>=1.13",
+    "redis>=5.0",
+]
+
+
+[project.urls]
+Homepage = "https://github.com/fritill-team/fri_pkg_auth"
+Repository = "https://github.com/fritill-team/fri_pkg_auth"
+
+[project.scripts]
+keycloak-init-client = "pkg_auth.admin.cli:main"
+pkg-auth-sync-catalog = "pkg_auth.authorization.cli.sync_catalog:main"
+pkg-auth-sync-services = "pkg_auth.authorization.cli.sync_services:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "pkg_auth.authentication.*"
+strict = true
+disallow_any_generics = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+no_implicit_reexport = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "pkg_auth.authorization.*"
+strict = true
+disallow_any_generics = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+no_implicit_reexport = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "pkg_auth.integrations.*"
+strict = true
+# Slightly relaxed: framework decorators (Django/Strawberry) sometimes need Any
+disallow_any_expr = false
+warn_return_any = false
+
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "-m 'not integration'"
+markers = [
+    "integration: tests requiring real Postgres or Redis (testcontainers)",
+]

pkg_auth-3.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pkg_auth-3.0.0/src/pkg_auth/__init__.py

@@ -0,0 +1,15 @@
+"""pkg_auth: clean-architecture identity + ACL for Python services.
+
+Importing this top-level package gives you only the version. Reach for
+specific surfaces via the sub-packages:
+
+    from pkg_auth.authentication import IdentityContext, AuthenticateTokenUseCase
+    from pkg_auth.authentication.adapters.keycloak import JWTTokenDecoder
+
+Authorization (ACL) and framework integrations (FastAPI, Django,
+Strawberry) are available via sub-packages.
+"""
+
+__version__ = "2.1.0"
+
+__all__ = ["__version__"]

pkg_auth-3.0.0/src/pkg_auth/admin/__init__.py

@@ -0,0 +1,35 @@
+"""
+pkg_auth.admin.keycloak
+
+Async Keycloak admin utilities:
+
+- KCAdminSettings: configuration for Keycloak admin connection.
+- KeycloakAdminClient: minimal async admin client (httpx-based).
+- provision_keycloak_client: high-level async helper to:
+    * ensure API client exists (bearer-only)
+    * ensure client roles match your permission list
+    * ensure audience + roles mappers on frontend clients
+- settings_from_env / ensure_keycloak_client_from_env:
+    convenience wrappers for env-driven CLI / initContainers.
+"""
+
+from __future__ import annotations
+
+from .client import KeycloakAdminClient
+from .env import settings_from_env, ensure_keycloak_client_from_env
+from .helpers import (
+    _ensure_api_client,
+    _ensure_roles,
+    _ensure_frontend_mappers,
+    _remove_frontend_mappers,
+)
+from .provision_client import provision_keycloak_client
+from .settings import KCAdminSettings
+
+__all__ = [
+    "KCAdminSettings",
+    "KeycloakAdminClient",
+    "settings_from_env",
+    "ensure_keycloak_client_from_env",
+    "provision_keycloak_client"
+]

pkg_auth-3.0.0/src/pkg_auth/admin/cli.py

@@ -0,0 +1,87 @@
+# src/pkg_auth/keycloak_admin/__main__.py
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from typing import Any, Sequence
+
+from .env import settings_from_env
+from .provision_client import provision_keycloak_client
+
+
+def _parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Provision Keycloak API client, roles and audience mappers",
+    )
+
+    parser.add_argument(
+        "--client-id",
+        help="Override API clientId (default: {APP_NAME|SERVICE_NAME}-api)",
+    )
+    parser.add_argument(
+        "--permissions",
+        "-P",
+        nargs="*",
+        help="Explicit list of permission/role names "
+             "(if omitted, your caller can pass them programmatically).",
+    )
+    parser.add_argument(
+        "--frontend-client-ids",
+        "-F",
+        nargs="*",
+        help="Frontend clientIds to grant audience and client-roles mappers to "
+             "(defaults from env KEYCLOAK_FRONTEND_CLIENT_IDS).",
+    )
+    parser.add_argument(
+        "--remove-frontend-client-ids",
+        "-R",
+        nargs="*",
+        help="Frontend clientIds to remove audience + roles mappers from "
+             "(effective only with --strict-audience).",
+    )
+    parser.add_argument(
+        "--strict-roles",
+        action="store_true",
+        help="Reconcile roles strictly: create missing and delete extra roles.",
+    )
+    parser.add_argument(
+        "--strict-audience",
+        action="store_true",
+        help="Reconcile audience + roles mappers strictly and remove mappers "
+             "from --remove-frontend-client-ids.",
+    )
+
+    return parser.parse_args(args=argv)
+
+
+async def _run(args: argparse.Namespace) -> dict[str, Any]:
+    settings = settings_from_env()
+    return await provision_keycloak_client(
+        settings=settings,
+        client_id=args.client_id,
+        permissions=list(args.permissions or []),
+        frontend_client_ids=list(args.frontend_client_ids or []),
+        remove_frontend_client_ids=list(args.remove_frontend_client_ids or []),
+        strict_roles=bool(args.strict_roles),
+        strict_audience=bool(args.strict_audience),
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    args = _parse_args(argv)
+
+    try:
+        summary = asyncio.run(_run(args))
+        json.dump({"ok": True, **summary}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+    except Exception as exc:  # noqa: BLE001
+        json.dump({"ok": False, "error": str(exc)}, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+        raise
+
+
+if __name__ == "__main__":
+    main()