Fix and complete integration guide

Author: hg1g

docs/mkdocs.yml

@@ -42,12 +42,6 @@ theme:
   icon:
     repo: fontawesome/brands/github
 
-extra_css:
-  - stylesheets/extra.css
-
-extra_javascript:
-  - javascripts/mermaid-zoom.js
-
 plugins:
   - search
   - offline

docs/src/integration-guide.md

@@ -18,7 +18,7 @@ Step by step guide to integrate `hotosm-auth` in your project.
 ```
 Does your app have an existing auth system (legacy)?
 │
-├─ NO → Simple Integration (Portal, OAM)
+├─ NO → Simple Integration (Portal)
 │       You only need to validate Hanko JWT
 │
 └─ YES → Integration with Mapping (Drone-TM, fAIr)
@@ -29,7 +29,7 @@ Does your app have an existing auth system (legacy)?
 
 ## FastAPI: Simple Integration
 
-For apps **without legacy auth** (e.g.: Portal, OAM).
+For apps **without legacy auth** (e.g.: Portal).
 
 ### Step 1: Dependency
 
@@ -196,6 +196,14 @@ MIDDLEWARE = [
 
 ```python
 # views.py
+from hotosm_auth_django import login_required
+
+# Decorator approach
+@login_required
+def my_view(request):
+    return JsonResponse({"email": request.hotosm.user.email})
+
+# Class-based view — check manually
 class ProtectedView(APIView):
     def get(self, request):
         if not request.hotosm.user:
@@ -207,9 +215,12 @@ class ProtectedView(APIView):
 
 ## Django: Integration with Mapping
 
+### Steps 1-2: Same as Simple
+
 ### Step 3: Settings with dual-mode
 
 ```python
+# settings.py
 AUTH_PROVIDER = env("AUTH_PROVIDER", default="legacy")
 
 if AUTH_PROVIDER == "hanko":
@@ -220,14 +231,59 @@ if AUTH_PROVIDER == "hanko":
     )
 ```
 
-### Step 4: Admin routes
+### Step 4: DRF authentication backend
+
+The middleware populates `request.hotosm.user`. Create a DRF `BaseAuthentication` class that maps that Hanko user to your app user:
+
+```python
+# authentication.py
+from rest_framework import authentication
+from hotosm_auth_django import get_mapped_user_id
+from myapp.models import AppUser
+
+class HankoAuthentication(authentication.BaseAuthentication):
+    def authenticate(self, request):
+        hanko_user = getattr(request, 'hotosm', None) and request.hotosm.user
+        if not hanko_user:
+            return None, None
+
+        app_user_id = get_mapped_user_id(hanko_user, app_name="my-app")
+
+        if app_user_id:
+            user = AppUser.objects.get(id=app_user_id)
+            return user, None
+
+        # No mapping yet → send to onboarding
+        request.needs_onboarding = True
+        return None, None
+
+
+# Select auth class based on provider
+if settings.AUTH_PROVIDER == "hanko":
+    MyAuthentication = HankoAuthentication
+else:
+    MyAuthentication = LegacyAuthentication  # your existing class
+```
+
+Register it in settings:
+
+```python
+# settings.py
+REST_FRAMEWORK = {
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "myapp.authentication.MyAuthentication",
+    ]
+}
+```
+
+### Step 5: Admin routes
 
 ```python
 # urls.py
-if getattr(settings, 'AUTH_PROVIDER', 'legacy') == 'hanko':
+if settings.AUTH_PROVIDER == "hanko":
     from hotosm_auth_django.admin_routes import create_admin_urlpatterns
     admin_patterns = create_admin_urlpatterns(
-        app_name="my-app", user_model="myapp.User",
+        app_name="my-app", user_model="myapp.AppUser",
         user_id_column="id", user_name_column="username", user_email_column="email",
     )
     urlpatterns += [path("api/admin/", include(admin_patterns))]
@@ -237,7 +293,7 @@ if getattr(settings, 'AUTH_PROVIDER', 'legacy') == 'hanko':
 
 ## Litestar: Simple Integration
 
-For apps **without legacy auth** (e.g.: Field-TM).
+For apps **without legacy auth**.
 
 ### Step 1: Dependency
 
@@ -256,9 +312,10 @@ from litestar import Litestar
 from hotosm_auth_litestar import setup_auth
 
 # setup_auth() loads config from env, returns (deps, route_handlers)
+# route_handlers includes the OSM OAuth routes — spread alongside your own handlers
 deps, route_handlers = setup_auth()
 
-app = Litestar(route_handlers=route_handlers, dependencies=deps)
+app = Litestar(route_handlers=[*route_handlers, me, ...], dependencies=deps)
 ```
 
 ### Step 3: Protect routes
@@ -301,6 +358,7 @@ OSM_CLIENT_SECRET=your-client-secret
 # auth_deps.py
 from litestar import Request
 from hotosm_auth_litestar import get_current_user, get_mapped_user_id
+from app.hanko_helpers import lookup_user_by_email, create_app_user
 
 async def login_required(request: Request):
     hanko_user = await get_current_user(request)
@@ -316,7 +374,29 @@ async def login_required(request: Request):
     return await get_user_by_id(db, user_id)
 ```
 
-### Step 4: Admin routes (optional)
+### Step 4: Helper functions
+
+```python
+# hanko_helpers.py
+async def lookup_user_by_email(db, email: str) -> Optional[str]:
+    """Look up user by email. Returns user_id or None."""
+    async with db.cursor() as cur:
+        await cur.execute("SELECT id FROM users WHERE email = %s", [email])
+        row = await cur.fetchone()
+    return str(row[0]) if row else None
+
+async def create_app_user(db, hanko_user: HankoUser) -> str:
+    """Create new user. Returns user_id."""
+    async with db.cursor() as cur:
+        await cur.execute(
+            "INSERT INTO users (email, name) VALUES (%s, %s) RETURNING id",
+            [hanko_user.email, hanko_user.username or hanko_user.email.split("@")[0]]
+        )
+        row = await cur.fetchone()
+    return str(row[0])
+```
+
+### Step 5: Admin routes (optional)
 
 ```python
 # main.py
@@ -357,7 +437,7 @@ VITE_HANKO_URL=https://login.hotosm.org
 |------|----------------|-----------------|---------------|----------------|-----------------|------------------|
 | 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 |
+| Protect routes | CurrentUser | Override login_required | request.hotosm | BaseAuthentication | AuthContext | Custom dep |
+| Helper functions | - | ✓ | - | - | - | ✓ |
+| Admin routes | - | Step 5 | - | Step 5 | - | Step 5 |
 | AUTH_PROVIDER env | - | ✓ | - | ✓ | - | ✓ |

frontend/public/docs/404.html

@@ -49,8 +49,6 @@
 
 
 
-      <link rel="stylesheet" href="/app/docs/stylesheets/extra.css">
-    
     <script>__md_scope=new URL("/app/docs/",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
 
 
@@ -911,8 +909,6 @@ <h1>404 - Not found</h1>
 
       <script src="/app/docs/assets/javascripts/bundle.79ae519e.min.js"></script>
 
-        <script src="/app/docs/javascripts/mermaid-zoom.js"></script>
-      
 
   </body>
 </html>

frontend/public/docs/admin.html

@@ -55,8 +55,6 @@
 
 
 
-      <link rel="stylesheet" href="stylesheets/extra.css">
-    
     <script>__md_scope=new URL(".",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
 
 
@@ -1318,8 +1316,6 @@ <h2 id="proxy-endpoints-login-backend">Proxy Endpoints (Login Backend)<a class="
 
       <script src="assets/javascripts/bundle.79ae519e.min.js"></script>
 
-        <script src="javascripts/mermaid-zoom.js"></script>
-      
 
   </body>
 </html>

frontend/public/docs/index.html

@@ -53,8 +53,6 @@
 
 
 
-      <link rel="stylesheet" href="stylesheets/extra.css">
-    
     <script>__md_scope=new URL(".",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
 
 
@@ -1266,8 +1264,6 @@ <h2 id="implementations">Implementations<a class="headerlink" href="#implementat
 
       <script src="assets/javascripts/bundle.79ae519e.min.js"></script>
 
-        <script src="javascripts/mermaid-zoom.js"></script>
-      
 
   </body>
 </html>