Add Litestar docs and complete integration guide

Author: hg1g

docs/src/admin.md

@@ -82,6 +82,18 @@ urlpatterns += [
 
 Same endpoints as FastAPI. With `user_model` set, each mapping in the list response is enriched with the app's username and email alongside the Hanko data.
 
+### Litestar
+
+```python
+from hotosm_auth_litestar import create_admin_mappings_router, setup_auth
+
+admin_router = create_admin_mappings_router(get_db, app_name="my-app")
+deps, route_handlers = setup_auth()
+app = Litestar(route_handlers=[*route_handlers, admin_router], dependencies=deps)
+```
+
+Same endpoints as FastAPI.
+
 ---
 
 ## Custom Admin Endpoints
@@ -113,6 +125,18 @@ class MyAdminView(APIView):
         return Response({"ok": True})
 ```
 
+### Litestar
+
+```python
+from litestar import get
+from hotosm_auth_litestar import AdminUser
+
+@get("/api/admin/stats")
+async def get_stats(admin: AdminUser) -> dict:
+    # admin is a HankoUser — email already verified as admin
+    return {"requested_by": admin.email}
+```
+
 ---
 
 ## Login Backend Config

docs/src/index.md

@@ -56,33 +56,44 @@ flowchart TB
 ### FastAPI
 
 ```python
-# main.py
 from contextlib import asynccontextmanager
 from fastapi import FastAPI
 from hotosm_auth import AuthConfig
 from hotosm_auth_fastapi import init_auth, CurrentUser, osm_router
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    auth_config = AuthConfig.from_env()
-    init_auth(auth_config)
+    init_auth(AuthConfig.from_env())
     yield
 
 app = FastAPI(lifespan=lifespan)
-
 app.include_router(osm_router, prefix="/api")
 
 @app.get("/me")
 async def me(user: CurrentUser):
     return {"id": user.id, "email": user.email}
 ```
 
+### Litestar
+
+```python
+from litestar import Litestar, get
+from hotosm_auth_litestar import setup_auth, AuthContext
+
+deps, route_handlers = setup_auth()
+
+@get("/me")
+async def me(auth: AuthContext) -> dict:
+    return {"id": auth.user.id, "email": auth.user.email}
+
+app = Litestar(route_handlers=[*route_handlers, me], dependencies=deps)
+```
+
 ### Django
 
 ```python
 # settings.py
 INSTALLED_APPS = [..., 'hotosm_auth_django']
-
 MIDDLEWARE = [..., 'hotosm_auth_django.HankoAuthMiddleware']
 
 # views.py

docs/src/integration-guide.md

@@ -8,6 +8,7 @@ Step by step guide to integrate `hotosm-auth` in your project.
 |-----------|---------------------|------------------|
 | **FastAPI** | [Simple](#fastapi-simple-integration) | [With Mapping](#fastapi-integration-with-mapping) |
 | **Django** | [Simple](#django-simple-integration) | [With Mapping](#django-integration-with-mapping) |
+| **Litestar** | [Simple](#litestar-simple-integration) | [With Mapping](#litestar-integration-with-mapping) |
 | **Frontend** | [All](#frontend-all) | [All](#frontend-all) |
 
 ---
@@ -57,7 +58,8 @@ async def lifespan(app: FastAPI):
 app = FastAPI(lifespan=lifespan)
 
 # Mount OSM OAuth routes (optional)
-app.include_router(osm_router, prefix="/api/auth/osm")
+# router already has prefix="/auth/osm" → routes: /api/auth/osm/login, /api/auth/osm/callback
+app.include_router(osm_router, prefix="/api")
 ```
 
 ### Step 3: Protect routes
@@ -233,6 +235,102 @@ if getattr(settings, 'AUTH_PROVIDER', 'legacy') == 'hanko':
 
 ---
 
+## Litestar: Simple Integration
+
+For apps **without legacy auth** (e.g.: Field-TM).
+
+### Step 1: Dependency
+
+```toml
+# pyproject.toml
+dependencies = [
+    "hotosm-auth[litestar]==0.2.10",
+]
+```
+
+### Step 2: Initialization
+
+```python
+# main.py
+from litestar import Litestar
+from hotosm_auth_litestar import setup_auth
+
+# setup_auth() loads config from env, returns (deps, route_handlers)
+deps, route_handlers = setup_auth()
+
+app = Litestar(route_handlers=route_handlers, dependencies=deps)
+```
+
+### Step 3: Protect routes
+
+```python
+from litestar import get
+from hotosm_auth_litestar import AuthContext, OptionalAuthContext
+
+@get("/me")
+async def me(auth: AuthContext) -> dict:
+    """Requires authentication."""
+    return {"user_id": auth.user.id, "email": auth.user.email}
+
+@get("/public")
+async def public(optional_auth: OptionalAuthContext) -> dict:
+    """Optional auth."""
+    return {"user": optional_auth.user.email if optional_auth.user else "anonymous"}
+```
+
+### Step 4: Environment variables
+
+```bash
+HANKO_API_URL=https://login.hotosm.org
+COOKIE_SECRET=your-32-byte-secret
+
+# Only if using OSM OAuth
+OSM_CLIENT_ID=your-client-id
+OSM_CLIENT_SECRET=your-client-secret
+```
+
+---
+
+## Litestar: Integration with Mapping
+
+### Steps 1-2: Same as Simple
+
+### Step 3: Custom auth dependency
+
+```python
+# auth_deps.py
+from litestar import Request
+from hotosm_auth_litestar import get_current_user, get_mapped_user_id
+
+async def login_required(request: Request):
+    hanko_user = await get_current_user(request)
+    db = request.app.state.db
+    user_id = await get_mapped_user_id(
+        hanko_user=hanko_user,
+        db_conn=db,
+        app_name="my-app",
+        auto_create=True,
+        email_lookup_fn=lookup_user_by_email,
+        user_creator_fn=create_app_user,
+    )
+    return await get_user_by_id(db, user_id)
+```
+
+### Step 4: Admin routes (optional)
+
+```python
+# main.py
+from hotosm_auth_litestar import create_admin_mappings_router
+
+admin_router = create_admin_mappings_router(
+    get_db, app_name="my-app"
+)
+deps, route_handlers = setup_auth()
+app = Litestar(route_handlers=[*route_handlers, admin_router], dependencies=deps)
+```
+
+---
+
 ## Frontend (all)
 
 ```tsx
@@ -255,11 +353,11 @@ VITE_HANKO_URL=https://login.hotosm.org
 
 ## Checklist
 
-| Step | FastAPI Simple | FastAPI+Mapping | Django Simple | Django+Mapping |
-|------|----------------|-----------------|---------------|----------------|
-| Dependency | ✓ | ✓ | ✓ | ✓ |
-| init_auth / middleware | ✓ | ✓ | ✓ | ✓ |
-| Protect routes | CurrentUser | Override login_required | request.hotosm | request.hotosm |
-| Helper functions | - | ✓ | - | ✓ |
-| Admin routes | - | Optional | - | Optional |
-| AUTH_PROVIDER env | - | ✓ | - | ✓ |
+| Step | FastAPI Simple | FastAPI+Mapping | Django Simple | Django+Mapping | Litestar Simple | Litestar+Mapping |
+|------|----------------|-----------------|---------------|----------------|-----------------|------------------|
+| Dependency | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Init | init_auth | init_auth | middleware | middleware | setup_auth() | setup_auth() |
+| Protect routes | CurrentUser | Override login_required | request.hotosm | request.hotosm | AuthContext | Custom dep |
+| Helper functions | - | ✓ | - | ✓ | - | ✓ |
+| Admin routes | - | Optional | - | Optional | - | Optional |
+| AUTH_PROVIDER env | - | ✓ | - | ✓ | - | ✓ |

docs/src/overview.md

@@ -13,6 +13,7 @@
 | `hotosm_auth` | Core Python package (JWT, config, crypto) |
 | `hotosm_auth_fastapi` | FastAPI integration (dependencies, routes) |
 | `hotosm_auth_django` | Django integration (middleware, decorators) |
+| `hotosm_auth_litestar` | Litestar integration (dependencies, routes) |
 | `<hotosm-auth>` | Web component (Lit-based auth UI) |
 
 ---
@@ -36,10 +37,15 @@ auth-libs/
 │   │   ├── osm_routes.py             # /auth/osm/* endpoints
 │   │   └── admin_routes.py           # User mapping admin API
 │   │
-│   └── hotosm_auth_django/           # Django integration
-│       ├── middleware.py             # HankoAuthMiddleware
-│       ├── admin_routes.py           # Admin URL patterns
-│       └── models.py                 # HankoUserMapping model
+│   ├── hotosm_auth_django/           # Django integration
+│   │   ├── middleware.py             # HankoAuthMiddleware
+│   │   ├── admin_routes.py           # Admin URL patterns
+│   │   └── models.py                 # HankoUserMapping model
+│   │
+│   └── hotosm_auth_litestar/         # Litestar integration
+│       ├── dependencies.py           # AuthContext, setup_auth
+│       ├── osm_routes.py             # /auth/osm/* endpoints
+│       └── admin_routes.py           # User mapping admin API
 │
 └── web-component/                    # Frontend web component
     ├── src/hanko-auth.ts             # Lit web component
@@ -176,13 +182,19 @@ pip install "hotosm-auth[fastapi]==0.2.10"
 
 # With Django
 pip install "hotosm-auth[django]==0.2.10"
+
+# With Litestar
+pip install "hotosm-auth[litestar]==0.2.10"
 ```
 
 ### pyproject.toml
 
 ```toml
 dependencies = [
+    # Pick one:
     "hotosm-auth[fastapi]==0.2.10",
+    # "hotosm-auth[django]==0.2.10",
+    # "hotosm-auth[litestar]==0.2.10",
 ]
 ```
 

docs/src/python-libs.md

@@ -359,3 +359,101 @@ Run migrations:
 ```bash
 python manage.py migrate hotosm_auth_django
 ```
+
+---
+
+## Litestar: `hotosm_auth_litestar`
+
+### Setup
+
+```python
+# main.py
+from litestar import Litestar
+from hotosm_auth_litestar import setup_auth
+
+# setup_auth() loads config from env, returns (deps, route_handlers)
+deps, route_handlers = setup_auth()
+
+app = Litestar(route_handlers=route_handlers, dependencies=deps)
+```
+
+This automatically:
+
+- Loads `AuthConfig.from_env()`
+- Registers OSM OAuth routes (`/auth/osm/login`, `/auth/osm/callback`, etc.)
+- Sets up `AuthContext` and `OptionalAuthContext` dependencies
+
+### Usage
+
+```python
+from litestar import get
+from hotosm_auth_litestar import AuthContext, OptionalAuthContext
+
+@get("/me")
+async def me(auth: AuthContext) -> dict:
+    """Requires authentication."""
+    return {"user_id": auth.user.id, "email": auth.user.email}
+
+@get("/public")
+async def public(optional_auth: OptionalAuthContext) -> dict:
+    """Optional auth."""
+    return {"user": optional_auth.user.email if optional_auth.user else "anonymous"}
+```
+
+### Dependencies
+
+| Dependency | Type | Raises |
+|------------|------|--------|
+| `AuthContext` | `AuthContext` (`.user`, `.osm`) | 401 |
+| `OptionalAuthContext` | `OptionalAuthContext` | - |
+| `AdminUser` | `HankoUser` | 403 |
+
+### OSM Routes
+
+```
+GET  /auth/osm/login      → Redirect to OSM authorization
+GET  /auth/osm/callback   → Handle OAuth callback, set cookie
+GET  /auth/osm/status     → {"connected": true, "osm_username": "..."}
+POST /auth/osm/disconnect → Revoke tokens, clear cookie
+```
+
+### Admin Routes
+
+```python
+from hotosm_auth_litestar import create_admin_mappings_router, setup_auth
+
+admin_router = create_admin_mappings_router(get_db, app_name="my-app")
+deps, route_handlers = setup_auth()
+app = Litestar(route_handlers=[*route_handlers, admin_router], dependencies=deps)
+```
+
+Endpoints:
+
+```
+GET    /mappings              → List all mappings (paginated)
+POST   /mappings              → Create mapping
+GET    /mappings/{hanko_id}   → Get single mapping
+PUT    /mappings/{hanko_id}   → Update mapping
+DELETE /mappings/{hanko_id}   → Delete mapping
+```
+
+### Mapping Integration
+
+```python
+# auth_deps.py
+from litestar import Request
+from hotosm_auth_litestar import get_current_user, get_mapped_user_id
+
+async def login_required(request: Request):
+    hanko_user = await get_current_user(request)
+    db = request.app.state.db
+    user_id = await get_mapped_user_id(
+        hanko_user=hanko_user,
+        db_conn=db,
+        app_name="my-app",
+        auto_create=True,
+        email_lookup_fn=lookup_user_by_email,
+        user_creator_fn=create_app_user,
+    )
+    return await get_user_by_id(db, user_id)
+```