simple-module-users 0.0.10__tar.gz → 0.0.12__tar.gz

{simple_module_users-0.0.10 → simple_module_users-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_users
-Version: 0.0.10
+Version: 0.0.12
 Summary: Email + password user management, admin invites, RBAC-ready — replaces Keycloak for simple_module apps
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -23,12 +23,12 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: aiosmtplib>=3.0
 Requires-Dist: cachetools>=5.3
-Requires-Dist: fastapi-users[sqlalchemy]<16,>=15
-Requires-Dist: simple-module-auth==0.0.10
-Requires-Dist: simple-module-core==0.0.10
-Requires-Dist: simple-module-db==0.0.10
-Requires-Dist: simple-module-hosting==0.0.10
-Requires-Dist: simple-module-settings==0.0.10
+Requires-Dist: fastapi-users[oauth,sqlalchemy]<16,>=15
+Requires-Dist: simple-module-auth==0.0.12
+Requires-Dist: simple-module-core==0.0.12
+Requires-Dist: simple-module-db==0.0.12
+Requires-Dist: simple-module-hosting==0.0.12
+Requires-Dist: simple-module-settings==0.0.12
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
 
@@ -42,7 +42,7 @@ Email+password user management for [simple_module](https://github.com/antosubash
 pip install simple_module_users
 ```
 
-Pre-wired into any app scaffolded with `simple-module new`.
+Pre-wired into any app scaffolded with `smpy new`.
 
 ## What it provides
 
@@ -50,7 +50,7 @@ Pre-wired into any app scaffolded with `simple-module new`.
 - Admin invite flow — admin enters an email, recipient clicks a link, sets a password, is logged in.
 - Public signup toggle (`SM_USERS_ALLOW_SIGNUP`, default `false`).
 - Bootstrap admin via env vars (`SM_USERS_BOOTSTRAP_EMAIL` + `SM_USERS_BOOTSTRAP_PASSWORD`) — idempotent, only creates if the users table is empty.
-- `sm-users create-admin` CLI for ad-hoc admin creation.
+- `smpy users create-admin` CLI for ad-hoc admin creation.
 - Inertia pages for login/register/invite-accept/admin-invite.
 - Console mailer (logs to stdout) or SMTP mailer (`SM_USERS_MAILER=smtp`).
 
@@ -59,7 +59,7 @@ Pre-wired into any app scaffolded with `simple-module new`.
 CLI:
 
 ```bash
-uv run sm-users create-admin --email admin@example.com --password 'change-me'
+uv run smpy users create-admin --email admin@example.com --password 'change-me'
 ```
 
 Bootstrap-on-boot (`.env`):

{simple_module_users-0.0.10 → simple_module_users-0.0.12}/README.md

@@ -8,7 +8,7 @@ Email+password user management for [simple_module](https://github.com/antosubash
 pip install simple_module_users
 ```
 
-Pre-wired into any app scaffolded with `simple-module new`.
+Pre-wired into any app scaffolded with `smpy new`.
 
 ## What it provides
 
@@ -16,7 +16,7 @@ Pre-wired into any app scaffolded with `simple-module new`.
 - Admin invite flow — admin enters an email, recipient clicks a link, sets a password, is logged in.
 - Public signup toggle (`SM_USERS_ALLOW_SIGNUP`, default `false`).
 - Bootstrap admin via env vars (`SM_USERS_BOOTSTRAP_EMAIL` + `SM_USERS_BOOTSTRAP_PASSWORD`) — idempotent, only creates if the users table is empty.
-- `sm-users create-admin` CLI for ad-hoc admin creation.
+- `smpy users create-admin` CLI for ad-hoc admin creation.
 - Inertia pages for login/register/invite-accept/admin-invite.
 - Console mailer (logs to stdout) or SMTP mailer (`SM_USERS_MAILER=smtp`).
 
@@ -25,7 +25,7 @@ Pre-wired into any app scaffolded with `simple-module new`.
 CLI:
 
 ```bash
-uv run sm-users create-admin --email admin@example.com --password 'change-me'
+uv run smpy users create-admin --email admin@example.com --password 'change-me'
 ```
 
 Bootstrap-on-boot (`.env`):

{simple_module_users-0.0.10 → simple_module_users-0.0.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_users"
-version = "0.0.10"
+version = "0.0.12"
 description = "Email + password user management, admin invites, RBAC-ready — replaces Keycloak for simple_module apps"
 readme = "README.md"
 license = "MIT"
@@ -21,15 +21,15 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "simple_module_core==0.0.10",
-    "simple_module_db==0.0.10",
-    "simple_module_hosting==0.0.10",
-    "simple_module_settings==0.0.10",
-    "simple_module_auth==0.0.10",
+    "simple_module_core==0.0.12",
+    "simple_module_db==0.0.12",
+    "simple_module_hosting==0.0.12",
+    "simple_module_settings==0.0.12",
+    "simple_module_auth==0.0.12",
     # Pinned to a narrow range: `deps.py` relies on mutating CookieTransport
     # fields after construction (see reconfigure_cookie_transport in backend.py).
     # Bumping the major version requires re-checking those field names.
-    "fastapi-users[sqlalchemy]>=15,<16",
+    "fastapi-users[sqlalchemy,oauth]>=15,<16",
     "aiosmtplib>=3.0",
     "cachetools>=5.3",
     "typer>=0.12",

{simple_module_users-0.0.10 → simple_module_users-0.0.12}/tests/test_cli.py

@@ -1,4 +1,4 @@
-"""Tests for the sm-users CLI (users.cli).
+"""Tests for the smpy users CLI (users.cli).
 
 Strategy: monkeypatch ``users.bootstrap.create_admin`` so tests do not need
 a real database.  This avoids the complexity of standing up a schema-stamped
@@ -161,7 +161,7 @@ def test_create_admin_missing_email() -> None:
 
 
 def test_app_help() -> None:
-    """``sm-users --help`` shows the top-level help text and lists create-admin."""
+    """``smpy users --help`` shows the top-level help text and lists create-admin."""
     result = runner.invoke(app, ["--help"])
     assert result.exit_code == 0
     assert "create-admin" in result.output

simple_module_users-0.0.12/tests/test_oauth.py

@@ -0,0 +1,189 @@
+"""Unit + integration tests for the OAuth/OIDC plumbing.
+
+Provider client construction and the /authorize+/callback ASGI flow are not
+covered here because both depend on real httpx-oauth clients that hit the
+network (token exchange, profile fetch). Those are best validated in a manual
+QA pass against a dev IdP. What this file *does* cover:
+
+- ``enabled_provider_names`` correctly reflects settings.
+- ``build_clients`` instantiates the Google + GitHub clients when configured.
+- ``OAuthAccount`` persists and FK-cascades on user delete.
+- ``UserManager.oauth_callback`` (the find-or-create core fastapi-users helper
+  the route delegates to) creates a fresh user + linked OAuthAccount, and
+  associates by email when the user already exists.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+import pytest
+from fastapi_users.password import PasswordHelper
+from sqlalchemy import select
+from users.models import OAuthAccount, User
+from users.oauth import build_clients, enabled_provider_names
+from users.settings import UsersSettings
+
+_pw = PasswordHelper()
+
+
+# ---------------------------------------------------------------------------
+# Settings → provider list
+# ---------------------------------------------------------------------------
+
+
+def test_enabled_provider_names_empty_by_default():
+    assert enabled_provider_names(UsersSettings()) == []
+
+
+def test_enabled_provider_names_lists_configured_providers():
+    s = UsersSettings(
+        oauth_google_client_id="g-id",
+        oauth_google_client_secret="g-secret",
+        oauth_github_client_id="gh-id",
+        oauth_github_client_secret="gh-secret",
+    )
+    names = [p["name"] for p in enabled_provider_names(s)]
+    assert names == ["google", "github"]
+
+
+def test_enabled_provider_names_skips_provider_missing_secret():
+    s = UsersSettings(oauth_google_client_id="g-id")  # no secret
+    assert enabled_provider_names(s) == []
+
+
+def test_enabled_provider_names_oidc_requires_discovery_url():
+    s = UsersSettings(
+        oauth_oidc_client_id="x",
+        oauth_oidc_client_secret="y",
+        # discovery_url unset → not registered
+    )
+    assert enabled_provider_names(s) == []
+
+
+# ---------------------------------------------------------------------------
+# build_clients (no-network providers only)
+# ---------------------------------------------------------------------------
+
+
+def test_build_clients_google_and_github():
+    s = UsersSettings(
+        oauth_google_client_id="g-id",
+        oauth_google_client_secret="g-secret",
+        oauth_github_client_id="gh-id",
+        oauth_github_client_secret="gh-secret",
+    )
+    providers = build_clients(s)
+    assert [p.name for p in providers] == ["google", "github"]
+    # Sanity-check that the underlying httpx-oauth client carries our id.
+    assert providers[0].client.client_id == "g-id"
+    assert providers[1].client.client_id == "gh-id"
+
+
+# ---------------------------------------------------------------------------
+# OAuthAccount persistence + cascade
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.anyio
+async def test_oauth_account_round_trip_and_cascade(users_db):
+    user = User(
+        id=uuid.uuid4(),
+        email="oauth-rt@example.com",
+        hashed_password=_pw.hash("SecurePass1!"),
+        is_active=True,
+        is_verified=True,
+    )
+    users_db.add(user)
+    await users_db.commit()
+
+    account = OAuthAccount(
+        user_id=user.id,
+        oauth_name="google",
+        access_token="tok",
+        account_id="google-123",
+        account_email=user.email,
+    )
+    users_db.add(account)
+    await users_db.commit()
+
+    found = (
+        await users_db.execute(select(OAuthAccount).where(OAuthAccount.account_id == "google-123"))
+    ).scalar_one()
+    assert found.user_id == user.id
+
+    # FK cascade: deleting the user removes the linked account.
+    await users_db.delete(user)
+    await users_db.commit()
+    remaining = (
+        await users_db.execute(select(OAuthAccount).where(OAuthAccount.account_id == "google-123"))
+    ).scalar_one_or_none()
+    assert remaining is None
+
+
+# ---------------------------------------------------------------------------
+# UserManager.oauth_callback — the find-or-create flow the route delegates to
+# ---------------------------------------------------------------------------
+
+
+async def _build_user_manager(app):
+    """Construct a UserManager bound to the test app's DB session."""
+    from users.db_adapter import UserDatabaseWithRoles
+    from users.manager import UserManager
+    from users.models import OAuthAccount, User
+
+    session = app.state.sm.db.session_factory()
+    s = await session.__aenter__()
+    user_db = UserDatabaseWithRoles(s, User, OAuthAccount)
+    manager = UserManager(user_db, app.state.users.mailer, app.state.users.settings)
+    return manager, session, s
+
+
+@pytest.mark.anyio
+async def test_oauth_callback_creates_new_user_and_account(users_app):
+    manager, session, _ = await _build_user_manager(users_app)
+    try:
+        user = await manager.oauth_callback(
+            "google",
+            access_token="tok",
+            account_id="google-new-1",
+            account_email="newuser@example.com",
+            associate_by_email=True,
+            is_verified_by_default=True,
+        )
+        assert user.email == "newuser@example.com"
+        assert user.is_verified is True
+        assert len(user.oauth_accounts) == 1
+        assert user.oauth_accounts[0].oauth_name == "google"
+        assert user.oauth_accounts[0].account_id == "google-new-1"
+    finally:
+        await session.__aexit__(None, None, None)
+
+
+@pytest.mark.anyio
+async def test_oauth_callback_links_to_existing_email(users_app, users_db):
+    existing = User(
+        id=uuid.uuid4(),
+        email="existing@example.com",
+        hashed_password=_pw.hash("SecurePass1!"),
+        is_active=True,
+        is_verified=True,
+    )
+    users_db.add(existing)
+    await users_db.commit()
+
+    manager, session, _ = await _build_user_manager(users_app)
+    try:
+        linked = await manager.oauth_callback(
+            "github",
+            access_token="tok",
+            account_id="gh-42",
+            account_email="existing@example.com",
+            associate_by_email=True,
+            is_verified_by_default=True,
+        )
+        assert linked.id == existing.id
+        names = [a.oauth_name for a in linked.oauth_accounts]
+        assert names == ["github"]
+    finally:
+        await session.__aexit__(None, None, None)

{simple_module_users-0.0.10 → simple_module_users-0.0.12}/users/cli.py

@@ -1,9 +1,10 @@
 """Command-line entry points for the users module.
 
-Exposed via ``sm-users`` (see pyproject.toml [project.scripts]).
+Exposed via ``smpy users`` (see pyproject.toml
+[project.entry-points.simple_module_cli.cli_plugins]).
 
-    sm-users create-admin --email a@b.test --password sekret [--full-name Me]
-    sm-users create-admin --email a@b.test --password new --force
+    smpy users create-admin --email a@b.test --password sekret [--full-name Me]
+    smpy users create-admin --email a@b.test --password new --force
 """
 
 from __future__ import annotations

simple_module_users-0.0.12/users/components/RolesTab.tsx

@@ -0,0 +1,77 @@
+import { Link } from '@inertiajs/react';
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { Card, CardContent } from '@simple-module-py/ui/components/ui/card';
+import { TabsContent } from '@simple-module-py/ui/components/ui/tabs';
+import { Pencil, ShieldCheck, Users } from 'lucide-react';
+
+export interface RoleItem {
+  id: string;
+  name: string;
+  description?: string | null;
+  user_count: number;
+}
+
+const SYSTEM_ROLES = new Set(['Owner', 'Admin', 'Viewer']);
+
+export function RolesTab({ roles }: { roles: RoleItem[] }) {
+  return (
+    <TabsContent value="roles">
+      {roles.length === 0 ? (
+        <Card className="border-border">
+          <CardContent className="flex flex-col items-center gap-2 py-16 text-muted-foreground">
+            <ShieldCheck className="size-8" />
+            <p>No roles defined</p>
+          </CardContent>
+        </Card>
+      ) : (
+        <div className="grid gap-3 sm:grid-cols-2">
+          {roles.map((role) => {
+            const isSystem = SYSTEM_ROLES.has(role.name);
+            return (
+              <Card key={role.id} className="border-border">
+                <CardContent className="pt-5">
+                  <div className="flex items-start gap-3">
+                    <span className="inline-flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-primary-600/10 text-primary-700">
+                      {isSystem ? (
+                        <ShieldCheck className="h-[18px] w-[18px]" aria-hidden="true" />
+                      ) : (
+                        <Users className="h-[18px] w-[18px]" aria-hidden="true" />
+                      )}
+                    </span>
+                    <div className="flex-1 min-w-0">
+                      <div className="flex items-center gap-2">
+                        <h3 className="text-[15px] font-bold tracking-tight font-[var(--font-display)] text-foreground">
+                          {role.name}
+                        </h3>
+                        {isSystem && (
+                          <Badge
+                            variant="outline"
+                            className="border-border bg-secondary text-[10px] text-muted-foreground"
+                          >
+                            system
+                          </Badge>
+                        )}
+                      </div>
+                      <p className="mt-1 text-xs text-muted-foreground line-clamp-2">
+                        {role.description || 'No description.'}
+                      </p>
+                      <div className="mt-2 font-mono text-[11px] text-muted-foreground">
+                        {role.user_count} {role.user_count === 1 ? 'member' : 'members'}
+                      </div>
+                    </div>
+                    <Button asChild variant="ghost" size="icon-sm">
+                      <Link href={`/permissions/roles/${role.id}/edit`} aria-label="Edit role">
+                        <Pencil />
+                      </Link>
+                    </Button>
+                  </div>
+                </CardContent>
+              </Card>
+            );
+          })}
+        </div>
+      )}
+    </TabsContent>
+  );
+}

simple_module_users-0.0.12/users/components/UserRow.tsx

@@ -0,0 +1,80 @@
+import { Link } from '@inertiajs/react';
+import { Badge } from '@simple-module-py/ui/components/ui/badge';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { TableCell, TableRow } from '@simple-module-py/ui/components/ui/table';
+import { Pencil } from 'lucide-react';
+
+export interface UserListItem {
+  id: string;
+  email: string;
+  full_name: string | null;
+  is_active: boolean;
+  is_verified: boolean;
+  last_login_at: string | null;
+  created_at: string | null;
+  roles: string[];
+}
+
+function Avatar({ initial }: { initial: string }) {
+  return (
+    <span className="inline-flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-gradient-to-br from-primary-600 to-primary-800 text-[13px] font-bold text-white font-[var(--font-display)]">
+      {initial}
+    </span>
+  );
+}
+
+function StatusBadge({ user }: { user: UserListItem }) {
+  if (!user.is_active) {
+    return (
+      <Badge variant="outline" className="border-border bg-secondary text-muted-foreground">
+        disabled
+      </Badge>
+    );
+  }
+  if (!user.is_verified) {
+    return (
+      <Badge variant="outline" className="border-blue-200 bg-blue-50 text-blue-700">
+        invited
+      </Badge>
+    );
+  }
+  return (
+    <Badge variant="outline" className="border-primary-200 bg-primary-50 text-primary-700">
+      active
+    </Badge>
+  );
+}
+
+export function UserRow({ user }: { user: UserListItem }) {
+  return (
+    <TableRow className="hover:bg-secondary/40">
+      <TableCell className="py-3">
+        <div className="flex items-center gap-3">
+          <Avatar initial={(user.full_name || user.email).charAt(0).toUpperCase()} />
+          <div className="min-w-0">
+            <div className="truncate text-sm font-semibold text-foreground">
+              {user.full_name || user.email.split('@')[0]}
+            </div>
+            <div className="truncate text-[12px] text-muted-foreground">{user.email}</div>
+          </div>
+        </div>
+      </TableCell>
+      <TableCell className="hidden sm:table-cell text-sm text-muted-foreground">
+        {user.roles.length > 0 ? user.roles.join(', ') : '—'}
+      </TableCell>
+      <TableCell className="hidden sm:table-cell">
+        <StatusBadge user={user} />
+      </TableCell>
+      <TableCell className="hidden lg:table-cell text-sm text-muted-foreground">
+        {user.last_login_at ? new Date(user.last_login_at).toLocaleDateString() : '—'}
+      </TableCell>
+      <TableCell className="text-right">
+        <Button asChild variant="ghost" size="icon-sm">
+          <Link href={`/users/admin/${user.id}`}>
+            <Pencil />
+          </Link>
+        </Button>
+      </TableCell>
+    </TableRow>
+  );
+}

{simple_module_users-0.0.10 → simple_module_users-0.0.12}/users/db_adapter.py

@@ -12,7 +12,7 @@ from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 
-from users.models import User, UserAccessToken
+from users.models import OAuthAccount, User, UserAccessToken
 
 
 class UserDatabaseWithRoles(SQLAlchemyUserDatabase):
@@ -39,7 +39,10 @@ class UserDatabaseWithRoles(SQLAlchemyUserDatabase):
 async def get_user_db(
     session: AsyncSession = Depends(get_db),
 ) -> AsyncGenerator[UserDatabaseWithRoles, None]:
-    yield UserDatabaseWithRoles(session, User)
+    # OAuthAccount enables fastapi-users' OAuth router (get_by_oauth_account /
+    # add_oauth_account / update_oauth_account). Password-only flows are
+    # unaffected — those code paths never touch oauth_account_table.
+    yield UserDatabaseWithRoles(session, User, OAuthAccount)
 
 
 async def get_access_token_db(

{simple_module_users-0.0.10 → simple_module_users-0.0.12}/users/endpoints/api.py

@@ -30,8 +30,10 @@ from users.deps import (
     get_user_manager,
 )
 from users.endpoints.api_admin import admin_router
+from users.endpoints.api_oauth import register_oauth_routes
 from users.manager import UserManager
 from users.rate_limit import LoginRateLimiter, ThroughputLimiter
+from users.settings import UsersSettings
 
 logger = logging.getLogger(__name__)
 router = APIRouter()
@@ -125,7 +127,7 @@ auth_inner = fastapi_users.get_auth_router(auth_backend, requires_verification=T
 router.include_router(auth_inner, prefix="/auth-inner")
 
 
-def register_auth_routes(api_router: APIRouter) -> None:
+def register_auth_routes(api_router: APIRouter, settings: UsersSettings) -> None:
     """Mount all auth routes.
 
     The stock fastapi-users routers (reset/verify/register) ship POST endpoints
@@ -137,6 +139,9 @@ def register_auth_routes(api_router: APIRouter) -> None:
 
     The register router is always mounted; ``require_signup_enabled`` gates
     it at request time so ``allow_signup`` is hot-reloadable.
+
+    OAuth providers configured in ``settings`` are mounted under
+    ``/auth/<provider>/{login,callback}`` — see :mod:`users.endpoints.api_oauth`.
     """
     api_router.include_router(router)
     api_router.include_router(
@@ -160,6 +165,7 @@ def register_auth_routes(api_router: APIRouter) -> None:
             Depends(enforce_auth_throughput_limit),
         ],
     )
+    register_oauth_routes(api_router, settings)
 
 
 # ── Accept-invite (verify + set password + login, one shot) ─────────────────

simple_module_users-0.0.12/users/endpoints/api_oauth.py

@@ -0,0 +1,131 @@
+"""OAuth/OIDC login routes — one pair (``/login``, ``/callback``) per provider.
+
+Why a custom handler rather than ``fastapi_users.get_oauth_router``: the stock
+router's ``/callback`` returns a 204 No Content with the auth cookie set. That
+works for SPA flows that redirect on a successful AJAX response, but Inertia
+expects the user's browser to land on a real page. Here ``/callback`` returns
+a 303 redirect to ``settings.login_redirect_url`` instead, with the same
+cookie attached.
+
+Find-or-create + email-association logic still goes through
+``UserManager.oauth_callback`` — we don't reimplement it, only the transport
+around it. State CSRF uses Starlette's signed session cookie (already mounted
+by the framework) instead of fastapi-users' separate JWT-state cookie.
+"""
+
+from __future__ import annotations
+
+import logging
+import secrets
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi_users import exceptions as fu_exceptions
+from starlette.responses import RedirectResponse
+
+from users.deps import auth_backend, get_user_manager
+from users.oauth import OAuthProvider, build_clients
+
+if TYPE_CHECKING:
+    from users.manager import UserManager
+    from users.settings import UsersSettings
+
+logger = logging.getLogger(__name__)
+
+_SESSION_STATE_KEY_FMT = "oauth_state:{provider}"
+
+
+def _build_provider_router(provider: OAuthProvider, login_redirect_url: str) -> APIRouter:
+    """Mount /login + /callback for one provider."""
+    router = APIRouter()
+    state_key = _SESSION_STATE_KEY_FMT.format(provider=provider.name)
+
+    @router.get("/login")
+    async def begin(request: Request) -> RedirectResponse:
+        """Generate a state nonce, stash it in the session, redirect to the IdP."""
+        state = secrets.token_urlsafe(32)
+        request.session[state_key] = state
+        callback_url = str(request.url_for(f"oauth_{provider.name}_callback"))
+        authorization_url = await provider.client.get_authorization_url(callback_url, state)
+        return RedirectResponse(authorization_url, status_code=302)
+
+    @router.get("/callback", name=f"oauth_{provider.name}_callback")
+    async def callback(
+        request: Request,
+        code: str | None = None,
+        state: str | None = None,
+        user_manager: UserManager = Depends(get_user_manager),
+        strategy=Depends(auth_backend.get_strategy),
+    ) -> RedirectResponse:
+        """Verify state, exchange code, find-or-create user, set cookie, redirect."""
+        expected_state = request.session.pop(state_key, None)
+        if not state or not expected_state or not secrets.compare_digest(state, expected_state):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST, detail="OAUTH_INVALID_STATE"
+            )
+        if not code:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST, detail="OAUTH_MISSING_CODE"
+            )
+
+        callback_url = str(request.url_for(f"oauth_{provider.name}_callback"))
+        token = await provider.client.get_access_token(code, callback_url)
+        account_id, account_email = await provider.client.get_id_email(token["access_token"])
+        if account_email is None:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="OAUTH_NO_EMAIL")
+
+        try:
+            user = await user_manager.oauth_callback(
+                provider.name,
+                token["access_token"],
+                account_id,
+                account_email,
+                token.get("expires_at"),
+                token.get("refresh_token"),
+                request,
+                associate_by_email=True,
+                is_verified_by_default=True,
+            )
+        except fu_exceptions.UserAlreadyExists:
+            # Email exists but associate_by_email=False would forbid linking.
+            # We always pass True above, so this branch only fires if the
+            # provider returns ambiguous data.
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="OAUTH_USER_ALREADY_EXISTS",
+            ) from None
+
+        if not user.is_active:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST, detail="LOGIN_BAD_CREDENTIALS"
+            )
+
+        # Set the auth cookie via the existing backend, then bridge the
+        # session in on_after_login (sets session["user_id"] for AuthMiddleware).
+        login_response = await auth_backend.login(strategy, user)
+        await user_manager.on_after_login(user, request, login_response)
+
+        redirect = RedirectResponse(login_redirect_url, status_code=303)
+        for key, value in login_response.headers.items():
+            if key.lower() == "set-cookie":
+                redirect.raw_headers.append((b"set-cookie", value.encode("latin-1")))
+        return redirect
+
+    return router
+
+
+def register_oauth_routes(api_router: APIRouter, settings: UsersSettings) -> None:
+    """Mount /auth/<provider>/{login,callback} for every configured provider."""
+    providers = build_clients(settings)
+    for provider in providers:
+        api_router.include_router(
+            _build_provider_router(provider, settings.login_redirect_url),
+            prefix=f"/auth/{provider.name}",
+            tags=["users-auth"],
+        )
+    if providers:
+        logger.info(
+            "Registered %d OAuth provider(s): %s",
+            len(providers),
+            ", ".join(p.name for p in providers),
+        )