simple-module-auth 0.0.16__tar.gz → 0.0.18__tar.gz

{simple_module_auth-0.0.16 → simple_module_auth-0.0.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_auth
-Version: 0.0.16
+Version: 0.0.18
 Summary: Session-cookie authentication primitives — middleware, login/logout, redirect helpers for simple_module
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -22,8 +22,8 @@ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: itsdangerous>=2.2
-Requires-Dist: simple-module-core==0.0.16
-Requires-Dist: simple-module-db==0.0.16
+Requires-Dist: simple-module-core==0.0.18
+Requires-Dist: simple-module-db==0.0.18
 Description-Content-Type: text/markdown
 
 # simple_module_auth

simple_module_auth-0.0.18/auth/__init__.py

@@ -0,0 +1,7 @@
+"""Auth module — shared contracts (UserContext, AuthProvider, PrincipalResolver, deps)."""
+
+from auth.contracts.provider import AuthProvider
+from auth.contracts.resolver import PrincipalResolver
+from auth.contracts.schemas import UserContext
+
+__all__ = ["AuthProvider", "PrincipalResolver", "UserContext"]

{simple_module_auth-0.0.16 → simple_module_auth-0.0.18}/auth/contracts/__init__.py

@@ -1,5 +1,6 @@
 """Auth contracts — public types for other modules."""
 
+from auth.contracts.provider import AuthProvider
 from auth.contracts.schemas import UserContext
 
-__all__ = ["UserContext"]
+__all__ = ["AuthProvider", "UserContext"]

simple_module_auth-0.0.18/auth/contracts/provider.py

@@ -0,0 +1,34 @@
+"""AuthProvider protocol — the contract both users and keycloak modules implement."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from starlette.requests import Request
+
+from auth.contracts.schemas import UserContext
+
+
+@runtime_checkable
+class AuthProvider(Protocol):
+    """Extension point for swappable authentication backends.
+
+    Exactly one module (``users`` or ``keycloak``) registers an implementation
+    on ``app.state.auth.auth_provider`` during ``register_settings``.
+    The ``AuthMiddleware`` delegates to it on every request.
+    """
+
+    name: str
+
+    async def resolve_user(self, request: Request) -> UserContext | None: ...
+
+    def get_login_url(self, request: Request, next_url: str | None = None) -> str: ...
+
+    def get_logout_url(self, request: Request) -> str: ...
+
+    def get_public_paths(self) -> tuple[tuple[str, ...], tuple[str, ...]]: ...
+
+    def is_bearer_request(self, request: Request) -> bool: ...
+
+
+__all__ = ["AuthProvider"]

simple_module_auth-0.0.18/auth/middleware.py

@@ -0,0 +1,113 @@
+"""Provider-agnostic authentication middleware.
+
+Delegates user resolution to the ``AuthProvider`` registered on
+``app.state.auth.auth_provider``, then falls through to the
+principal-resolver chain. Sets ``request.state.user`` and the
+``current_user_id`` ContextVar for audit listeners.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from simple_module_db.listeners import current_user_id
+from starlette.requests import Request
+from starlette.responses import JSONResponse, RedirectResponse
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+logger = logging.getLogger(__name__)
+
+_FRAMEWORK_PUBLIC_PREFIXES = (
+    "/health",
+    "/static/",
+    "/api/docs",
+    "/api/redoc",
+    "/openapi.json",
+    "/i18n/",
+)
+_FRAMEWORK_PUBLIC_EXACT = ("/",)
+_SESSION_NEXT_KEY = "next"
+
+
+class AuthMiddleware:
+    """Authenticate requests via the registered AuthProvider.
+
+    On cache miss (provider returns None), falls through to the
+    principal-resolver chain. Unauthenticated API requests get 401 JSON;
+    unauthenticated browser requests get a redirect to the provider's
+    login URL.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        path: str = scope["path"]
+        method: str = scope.get("method", "GET")
+        app_state = scope["app"].state
+        auth_state = app_state.auth
+        provider = auth_state.auth_provider
+
+        if provider is None:
+            await self.app(scope, receive, send)
+            return
+
+        is_public = (
+            any(path.startswith(p) for p in _FRAMEWORK_PUBLIC_PREFIXES)
+            or path in _FRAMEWORK_PUBLIC_EXACT
+        )
+        # Module-contributed public routes (register_public_routes hook). Method
+        # -aware, so a GET read route can be exempted without opening sibling
+        # POST/PATCH mutations under the same prefix.
+        if not is_public:
+            public_routes = getattr(app_state, "public_routes", None)
+            is_public = public_routes is not None and public_routes.matches(method, path)
+        # Legacy provider-declared paths (prefix-only, method-agnostic). Kept for
+        # back-compat with AuthProvider implementations.
+        if not is_public:
+            prefix_paths, exact_paths = provider.get_public_paths()
+            is_public = any(path.startswith(p) for p in prefix_paths) or path in exact_paths
+
+        request = Request(scope)
+        user_ctx = await provider.resolve_user(request)
+
+        if user_ctx is None:
+            for resolver in auth_state.principal_resolvers:
+                try:
+                    user_ctx = await resolver(request)
+                except Exception:
+                    logger.exception(
+                        "Principal resolver %r raised; treating as no-match",
+                        resolver,
+                    )
+                    continue
+                if user_ctx is not None:
+                    break
+
+        if user_ctx is None and not is_public:
+            if path.startswith("/api/") or provider.is_bearer_request(request):
+                response = JSONResponse({"detail": "Not authenticated"}, status_code=401)
+            else:
+                session = scope.get("session", {})
+                session[_SESSION_NEXT_KEY] = str(request.url)
+                response = RedirectResponse(provider.get_login_url(request), status_code=302)
+            await response(scope, receive, send)
+            return
+
+        if user_ctx is not None:
+            request.state.user = user_ctx
+            token = current_user_id.set(user_ctx.id)
+            try:
+                await self.app(scope, receive, send)
+            finally:
+                current_user_id.reset(token)
+            return
+
+        await self.app(scope, receive, send)
+
+
+__all__ = ["AuthMiddleware"]

simple_module_auth-0.0.18/auth/module.py

@@ -0,0 +1,55 @@
+"""Auth module — shared contracts (UserContext, AuthProvider, deps).
+
+Intentionally minimal: this module owns the PUBLIC interface (UserContext,
+AuthProvider, PrincipalResolver, get_current_user, CurrentUser, require_permission)
+that every other module imports. Keeping it stable prevents churn when auth
+internals change.
+
+The ``auth_provider`` slot on ``app.state.auth`` is the extension point
+auth-provider modules (``users``, ``keycloak``) use to register themselves.
+The ``principal_resolvers`` registry lets downstream modules add extra
+credential sources (PAT bearer tokens, API keys, etc.).
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.module import ModuleBase, ModuleMeta
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+    from auth.contracts.schemas import UserContext
+
+
+def _serialize_principal(user: UserContext) -> dict:
+    return {
+        "id": user.id,
+        "name": user.name,
+        "email": user.email,
+        "roles": user.roles,
+    }
+
+
+class AuthModule(ModuleBase):
+    meta = ModuleMeta(
+        name="Auth",
+        route_prefix="/auth",
+    )
+
+    def register_settings(self, app: FastAPI) -> None:
+        from auth.state import AuthState
+
+        app.state.auth = AuthState()
+        app.state.principal_serializer = _serialize_principal
+
+    def register_middleware(self, app: FastAPI) -> None:
+        from auth.middleware import AuthMiddleware
+
+        app.add_middleware(AuthMiddleware)
+
+    def locale_dirs(self) -> dict[str, Path]:
+        return {"auth": Path(str(importlib.resources.files(__package__) / "locales"))}

{simple_module_auth-0.0.16 → simple_module_auth-0.0.18}/auth/state.py

@@ -1,8 +1,8 @@
 """Module-owned state attached to ``app.state.auth`` by ``AuthModule.register_settings``.
 
-Holds the principal-resolver registry (see
-``auth.contracts.resolver.PrincipalResolver``). Apps register additional
-resolvers from their ``on_startup`` hook::
+Holds the auth provider (set by one of ``users`` or ``keycloak``) and the
+principal-resolver registry. Apps register additional resolvers from their
+``on_startup`` hook::
 
     app.state.auth.principal_resolvers.append(my_pat_resolver)
 """
@@ -10,14 +10,19 @@ resolvers from their ``on_startup`` hook::
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
 
 from auth.contracts.resolver import PrincipalResolver
 
+if TYPE_CHECKING:
+    from auth.contracts.provider import AuthProvider
+
 
 @dataclass
 class AuthState:
-    """Per-app auth registry. Initialized empty; modules append resolvers."""
+    """Per-app auth registry. Initialized empty; provider modules populate at boot."""
 
+    auth_provider: AuthProvider | None = None
     principal_resolvers: list[PrincipalResolver] = field(default_factory=list)
 
 

{simple_module_auth-0.0.16 → simple_module_auth-0.0.18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_auth"
-version = "0.0.16"
+version = "0.0.18"
 description = "Session-cookie authentication primitives — middleware, login/logout, redirect helpers for simple_module"
 readme = "README.md"
 license = "MIT"
@@ -22,8 +22,8 @@ classifiers = [
 ]
 dependencies = [
     "itsdangerous>=2.2",
-    "simple_module_core==0.0.16",
-    "simple_module_db==0.0.16",
+    "simple_module_core==0.0.18",
+    "simple_module_db==0.0.18",
 ]
 
 [project.entry-points.simple_module]

simple_module_auth-0.0.18/tests/test_auth_middleware.py

@@ -0,0 +1,205 @@
+"""Tests for the provider-agnostic AuthMiddleware."""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+from auth.contracts.schemas import UserContext
+from auth.middleware import AuthMiddleware
+from auth.state import AuthState
+from fastapi import FastAPI, Request
+from starlette.middleware.sessions import SessionMiddleware
+from starlette.responses import JSONResponse
+
+SECRET = "test-middleware-secret"
+
+_TEST_USER = UserContext(
+    id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+    email="test@example.com",
+    name="Test User",
+    roles=["admin"],
+)
+
+
+class _StubProvider:
+    name = "stub"
+
+    def __init__(self, *, user: UserContext | None = None):
+        self._user = user
+
+    async def resolve_user(self, request):
+        return self._user
+
+    def get_login_url(self, request, next_url=None):
+        return "/stub/login"
+
+    def get_logout_url(self, request):
+        return "/stub/logout"
+
+    def get_public_paths(self):
+        return (("/stub/login", "/stub/public/"), ())
+
+    def is_bearer_request(self, request):
+        auth = request.headers.get("authorization", "")
+        return auth.startswith("Bearer ")
+
+
+def _build_app(provider, *, principal_resolvers=None, public_routes=None):
+    app = FastAPI()
+    app.state.auth = AuthState(
+        auth_provider=provider,
+        principal_resolvers=list(principal_resolvers or []),
+    )
+    if public_routes is not None:
+        app.state.public_routes = public_routes
+
+    async def _handler(request: Request, path: str = ""):
+        user = getattr(request.state, "user", None)
+        return JSONResponse(
+            {
+                "user": user.to_session_dict() if user else None,
+            }
+        )
+
+    app.add_api_route("/{path:path}", _handler, methods=["GET", "POST", "PATCH"])
+
+    app.add_middleware(AuthMiddleware)
+    app.add_middleware(SessionMiddleware, secret_key=SECRET)
+    return app
+
+
+@pytest.fixture
+def authenticated_app():
+    return _build_app(_StubProvider(user=_TEST_USER))
+
+
+@pytest.fixture
+def unauthenticated_app():
+    return _build_app(_StubProvider(user=None))
+
+
+async def test_authenticated_request_sets_user(authenticated_app):
+    transport = httpx.ASGITransport(app=authenticated_app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
+        resp = await c.get("/some/page")
+    assert resp.status_code == 200
+    assert resp.json()["user"]["email"] == "test@example.com"
+
+
+async def test_unauthenticated_browser_redirects_to_login(unauthenticated_app):
+    transport = httpx.ASGITransport(app=unauthenticated_app)
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://test", follow_redirects=False
+    ) as c:
+        resp = await c.get("/protected/page")
+    assert resp.status_code == 302
+    assert resp.headers["location"] == "/stub/login"
+
+
+async def test_unauthenticated_api_returns_401(unauthenticated_app):
+    transport = httpx.ASGITransport(app=unauthenticated_app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
+        resp = await c.get("/api/protected")
+    assert resp.status_code == 401
+    assert resp.json()["detail"] == "Not authenticated"
+
+
+async def test_unauthenticated_bearer_returns_401(unauthenticated_app):
+    transport = httpx.ASGITransport(app=unauthenticated_app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
+        resp = await c.get("/some/page", headers={"Authorization": "Bearer bad"})
+    assert resp.status_code == 401
+
+
+async def test_public_paths_skip_auth(unauthenticated_app):
+    transport = httpx.ASGITransport(app=unauthenticated_app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
+        resp = await c.get("/stub/login")
+    assert resp.status_code == 200
+
+
+async def test_framework_public_paths_skip_auth(unauthenticated_app):
+    transport = httpx.ASGITransport(app=unauthenticated_app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
+        resp = await c.get("/health")
+    assert resp.status_code == 200
+
+
+async def test_root_is_public(unauthenticated_app):
+    transport = httpx.ASGITransport(app=unauthenticated_app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
+        resp = await c.get("/")
+    assert resp.status_code == 200
+
+
+async def test_registry_public_route_skips_auth():
+    """A module-contributed public route lets an unauthenticated GET through."""
+    from simple_module_core.public_routes import PublicRouteRegistry
+
+    registry = PublicRouteRegistry()
+    registry.add_prefix("/api/gis/stac")
+    app = _build_app(_StubProvider(user=None), public_routes=registry)
+
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
+        resp = await c.get("/api/gis/stac/collections")
+    assert resp.status_code == 200
+    assert resp.json()["user"] is None
+
+
+async def test_registry_method_scoping_gates_other_verbs():
+    """A GET-scoped public rule exempts GET but still gates PATCH on the same path."""
+    from simple_module_core.public_routes import PublicRouteRegistry
+
+    registry = PublicRouteRegistry()
+    registry.add_regex(r"/api/gis/datasets/[^/]+/tilejson$", methods={"GET"})
+    app = _build_app(_StubProvider(user=None), public_routes=registry)
+
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
+        ok = await c.get("/api/gis/datasets/42/tilejson")
+        gated = await c.patch("/api/gis/datasets/42/tilejson")
+    assert ok.status_code == 200
+    assert gated.status_code == 401
+
+
+async def test_no_registry_falls_back_to_provider_paths(unauthenticated_app):
+    """Apps built without a public-routes registry still honor provider paths."""
+    transport = httpx.ASGITransport(app=unauthenticated_app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
+        public = await c.get("/stub/public/data")
+        gated = await c.get("/api/protected")
+    assert public.status_code == 200
+    assert gated.status_code == 401
+
+
+async def test_resolver_chain_fallback():
+    """When provider returns None, fall through to principal resolvers."""
+
+    async def fake_resolver(request):
+        auth = request.headers.get("authorization", "")
+        if auth == "Bearer good-token":
+            return _TEST_USER
+        return None
+
+    app = _build_app(_StubProvider(user=None), principal_resolvers=[fake_resolver])
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
+        resp = await c.get("/protected", headers={"Authorization": "Bearer good-token"})
+    assert resp.status_code == 200
+    assert resp.json()["user"]["email"] == "test@example.com"
+
+
+async def test_resolver_exception_is_logged_and_skipped():
+    """A resolver that raises should be caught; middleware continues."""
+
+    async def bad_resolver(request):
+        raise RuntimeError("boom")
+
+    app = _build_app(_StubProvider(user=None), principal_resolvers=[bad_resolver])
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://test", follow_redirects=False
+    ) as c:
+        resp = await c.get("/protected/page")
+    assert resp.status_code == 302

simple_module_auth-0.0.18/tests/test_auth_provider_protocol.py

@@ -0,0 +1,56 @@
+"""Tests for the AuthProvider protocol."""
+
+from __future__ import annotations
+
+from auth.contracts.provider import AuthProvider
+from auth.contracts.schemas import UserContext
+from starlette.requests import Request
+
+
+class _FakeProvider:
+    """Minimal implementation to verify protocol conformance."""
+
+    name = "fake"
+
+    async def resolve_user(self, request: Request) -> UserContext | None:
+        return None
+
+    def get_login_url(self, request: Request, next_url: str | None = None) -> str:
+        return "/fake/login"
+
+    def get_logout_url(self, request: Request) -> str:
+        return "/fake/logout"
+
+    def get_public_paths(self) -> tuple[tuple[str, ...], tuple[str, ...]]:
+        return (("/fake/login",), ())
+
+    def is_bearer_request(self, request: Request) -> bool:
+        return False
+
+
+def test_fake_provider_satisfies_protocol():
+    provider = _FakeProvider()
+    assert isinstance(provider, AuthProvider)
+
+
+def test_protocol_rejects_incomplete_implementation():
+    class _Incomplete:
+        name = "broken"
+
+    assert not isinstance(_Incomplete(), AuthProvider)
+
+
+def test_auth_package_reexports_auth_provider():
+    import auth
+
+    assert hasattr(auth, "AuthProvider")
+    assert "AuthProvider" in auth.__all__
+    from auth.contracts.provider import AuthProvider as Canonical
+
+    assert auth.AuthProvider is Canonical
+
+
+def test_contracts_package_reexports_auth_provider():
+    from auth.contracts import AuthProvider
+
+    assert AuthProvider is not None

{simple_module_auth-0.0.16 → simple_module_auth-0.0.18}/tests/test_resolver_registry.py

@@ -79,3 +79,66 @@ def test_auth_package_reexports_public_surface():
 
     assert auth.PrincipalResolver is PrincipalResolver
     assert auth.UserContext is UserContext
+
+
+def test_auth_module_registers_middleware():
+    """AuthModule.register_middleware should add AuthMiddleware."""
+    from auth.module import AuthModule
+    from fastapi import FastAPI
+
+    app = FastAPI()
+    AuthModule().register_middleware(app)
+    middleware_classes = [m.cls.__name__ for m in app.user_middleware]
+    assert "AuthMiddleware" in middleware_classes
+
+
+def test_auth_module_registers_principal_serializer():
+    """AuthModule.register_settings should set principal_serializer on app.state."""
+    from auth.module import AuthModule
+    from fastapi import FastAPI
+
+    app = FastAPI()
+    AuthModule().register_settings(app)
+    serializer = getattr(app.state, "principal_serializer", None)
+    assert serializer is not None
+
+    from auth.contracts.schemas import UserContext
+
+    ctx = UserContext(id="123", email="a@b.com", name="Test", roles=["admin"])
+    result = serializer(ctx)
+    assert result == {"id": "123", "name": "Test", "email": "a@b.com", "roles": ["admin"]}
+
+
+def test_auth_state_has_auth_provider_field():
+    from auth.state import AuthState
+
+    state = AuthState()
+    assert state.auth_provider is None
+
+
+def test_auth_state_accepts_auth_provider():
+    from auth.contracts.provider import AuthProvider
+    from auth.state import AuthState
+
+    class FakeProvider:
+        name = "fake"
+
+        async def resolve_user(self, request):
+            return None
+
+        def get_login_url(self, request, next_url=None):
+            return "/login"
+
+        def get_logout_url(self, request):
+            return "/logout"
+
+        def get_public_paths(self):
+            return ((), ())
+
+        def is_bearer_request(self, request):
+            return False
+
+    provider = FakeProvider()
+    state = AuthState(auth_provider=provider)
+    assert state.auth_provider is provider
+    assert isinstance(state.auth_provider, AuthProvider)

simple_module_auth-0.0.16/auth/__init__.py

@@ -1,6 +0,0 @@
-"""Auth module — shared contracts (UserContext, PrincipalResolver, deps)."""
-
-from auth.contracts.resolver import PrincipalResolver
-from auth.contracts.schemas import UserContext
-
-__all__ = ["PrincipalResolver", "UserContext"]

simple_module_auth-0.0.16/auth/module.py

@@ -1,39 +0,0 @@
-"""Auth module — shared contracts (UserContext, deps).
-
-Intentionally minimal: this module owns the PUBLIC interface (UserContext,
-PrincipalResolver, get_current_user, CurrentUser, require_permission) that
-every other module imports. Keeping it stable prevents churn when auth
-internals change.
-
-All authentication logic (middleware, login, signup, OAuth) lives in the
-users module. The ``principal_resolvers`` registry on ``app.state.auth`` is
-the extension point downstream modules use to plug in additional credential
-sources (PAT bearer tokens, API keys, etc.) — see
-``docs/framework/principal-resolvers.md`` for the worked example.
-"""
-
-from __future__ import annotations
-
-import importlib.resources
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-from simple_module_core.module import ModuleBase, ModuleMeta
-
-if TYPE_CHECKING:
-    from fastapi import FastAPI
-
-
-class AuthModule(ModuleBase):
-    meta = ModuleMeta(
-        name="Auth",
-        route_prefix="/auth",
-    )
-
-    def register_settings(self, app: FastAPI) -> None:
-        from auth.state import AuthState
-
-        app.state.auth = AuthState()
-
-    def locale_dirs(self) -> dict[str, Path]:
-        return {"auth": Path(str(importlib.resources.files(__package__) / "locales"))}