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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_auth
-Version: 0.0.14
+Version: 0.0.16
 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.14
-Requires-Dist: simple-module-db==0.0.14
+Requires-Dist: simple-module-core==0.0.16
+Requires-Dist: simple-module-db==0.0.16
 Description-Content-Type: text/markdown
 
 # simple_module_auth

simple_module_auth-0.0.16/auth/__init__.py

@@ -0,0 +1,6 @@
+"""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/contracts/resolver.py

@@ -0,0 +1,41 @@
+"""Principal-resolver extension point — apps register additional auth sources here.
+
+A ``PrincipalResolver`` is an async callable that inspects an incoming
+``Request`` and returns a :class:`~auth.contracts.schemas.UserContext` if it
+can authenticate the caller, or ``None`` to fall through to the next resolver
+in the chain.
+
+The chain is consulted by ``users.middleware.AuthMiddleware`` *after* the
+session-cookie path has been tried, in registration order, and the first
+non-``None`` return wins.
+
+Invariants every resolver MUST satisfy:
+
+* **Async.** Resolvers are awaited.
+* **Cheap fast-path bail.** Resolvers run on every request; return ``None``
+  immediately when the credential type isn't present (e.g., no ``Authorization``
+  header, no matching scheme).
+* **Self-checks active/disabled state.** The middleware does NOT re-validate
+  the user after the resolver returns — return ``None`` for disabled,
+  unverified, or otherwise blocked users.
+* **Never raise on bad credentials.** Return ``None`` and let the chain
+  continue. The middleware wraps each resolver in ``try/except`` for
+  defense in depth, but resolver authors should not rely on it.
+* **Request-scoped — no session writes.** A PAT call must not silently
+  elevate to a long-lived session cookie. If the resolver needs to mint a
+  session, that's an entirely separate code path (the standard login flow).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from starlette.requests import Request
+
+from auth.contracts.schemas import UserContext
+
+PrincipalResolver = Callable[[Request], Awaitable[UserContext | None]]
+"""Async callable: ``(Request) -> UserContext | None``. See module docstring
+for the invariants resolver authors must uphold."""
+
+__all__ = ["PrincipalResolver"]

simple_module_auth-0.0.16/auth/module.py

@@ -0,0 +1,39 @@
+"""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"))}

simple_module_auth-0.0.16/auth/state.py

@@ -0,0 +1,24 @@
+"""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::
+
+    app.state.auth.principal_resolvers.append(my_pat_resolver)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from auth.contracts.resolver import PrincipalResolver
+
+
+@dataclass
+class AuthState:
+    """Per-app auth registry. Initialized empty; modules append resolvers."""
+
+    principal_resolvers: list[PrincipalResolver] = field(default_factory=list)
+
+
+__all__ = ["AuthState"]

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

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_auth"
-version = "0.0.14"
+version = "0.0.16"
 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.14",
-    "simple_module_db==0.0.14",
+    "simple_module_core==0.0.16",
+    "simple_module_db==0.0.16",
 ]
 
 [project.entry-points.simple_module]

simple_module_auth-0.0.16/tests/test_resolver_registry.py

@@ -0,0 +1,81 @@
+"""Tests for the auth.contracts.resolver type + AuthState registry."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable
+
+from auth.contracts.resolver import PrincipalResolver
+from auth.contracts.schemas import UserContext
+from starlette.requests import Request
+
+
+def test_principal_resolver_type_accepts_async_callable():
+    """A typical resolver signature should satisfy the type alias at runtime.
+
+    The alias is documentation + a checkable shape — we exercise the shape
+    by constructing one and asserting it's a Callable that returns an
+    awaitable.
+    """
+
+    async def fake_resolver(request: Request) -> UserContext | None:
+        return None
+
+    # Runtime — alias resolves to Callable[..., Awaitable[...]]
+    resolver: PrincipalResolver = fake_resolver
+    assert callable(resolver)
+    # Sanity: the function actually returns an awaitable when called.
+    from unittest.mock import MagicMock
+
+    result = resolver(MagicMock(spec=Request))
+    assert isinstance(result, Awaitable)
+    result.close()  # don't leave an unawaited coroutine
+
+
+def test_auth_state_initializes_with_empty_resolvers():
+    from auth.state import AuthState
+
+    state = AuthState()
+    assert state.principal_resolvers == []
+
+
+def test_auth_state_resolvers_is_mutable_list():
+    """Modules register resolvers by appending; the list must be a list, not a tuple."""
+    from auth.state import AuthState
+
+    state = AuthState()
+
+    async def resolver(request):  # pragma: no cover - registration smoke only
+        return None
+
+    state.principal_resolvers.append(resolver)
+    assert state.principal_resolvers == [resolver]
+
+
+def test_auth_module_register_settings_populates_app_state():
+    """``AuthModule.register_settings(app)`` must put an AuthState on ``app.state.auth``."""
+    from auth.module import AuthModule
+    from auth.state import AuthState
+    from fastapi import FastAPI
+
+    app = FastAPI()
+    AuthModule().register_settings(app)
+
+    assert isinstance(app.state.auth, AuthState)
+    assert app.state.auth.principal_resolvers == []
+
+
+def test_auth_package_reexports_public_surface():
+    """Downstream authors should be able to ``from auth import PrincipalResolver, UserContext``."""
+    import auth
+
+    assert hasattr(auth, "PrincipalResolver")
+    assert hasattr(auth, "UserContext")
+    assert "PrincipalResolver" in auth.__all__
+    assert "UserContext" in auth.__all__
+
+    # Identity check — re-exports point at the canonical definitions.
+    from auth.contracts.resolver import PrincipalResolver
+    from auth.contracts.schemas import UserContext
+
+    assert auth.PrincipalResolver is PrincipalResolver
+    assert auth.UserContext is UserContext

simple_module_auth-0.0.14/auth/__init__.py

@@ -1 +0,0 @@
-"""Auth module — shared contracts (UserContext, deps)."""

simple_module_auth-0.0.14/auth/module.py

@@ -1,26 +0,0 @@
-"""Auth module — shared contracts (UserContext, deps).
-
-Intentionally minimal: this module owns the PUBLIC interface (UserContext,
-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.
-"""
-
-from __future__ import annotations
-
-import importlib.resources
-from pathlib import Path
-
-from simple_module_core.module import ModuleBase, ModuleMeta
-
-
-class AuthModule(ModuleBase):
-    meta = ModuleMeta(
-        name="Auth",
-        route_prefix="/auth",
-    )
-
-    def locale_dirs(self) -> dict[str, Path]:
-        return {"auth": Path(str(importlib.resources.files(__package__) / "locales"))}