fix: resolve OIDC session loss and migration failures (#1023)

* fix: resolve OIDC session loss and migration failures

This commit fixes three critical issues affecting OIDC/SSO authentication:

1. Session Not Saved Before Redirect
   - Added explicit req.session.save() callback in OIDC callback handler
   - Ensures session is persisted before redirecting to /today
   - Prevents 401 errors after successful SSO authentication

2. Migration Resilience
   - Added DROP TABLE IF EXISTS users_new in migration
   - Prevents "table already exists" errors from failed migrations
   - Created cleanup script for orphaned migration tables

3. Trust Proxy Documentation
   - Documented TUDUDI_TRUST_PROXY requirement for reverse proxy deployments
   - Added troubleshooting guide for session loss issues
   - Updated .env.example with OIDC configuration examples

Fixes session loss when deployed behind reverse proxies (nginx, Traefik, etc.)

Changes:
- backend/modules/oidc/controller.js: Add session.save() before redirect
- backend/migrations/20260420000004-make-password-optional.js: Add DROP TABLE IF EXISTS
- backend/scripts/cleanup-failed-migration.js: New cleanup utility
- backend/.env.example: Add OIDC and trust proxy examples
- docs/10-oidc-sso.md: Add trust proxy configuration and troubleshooting
- docs/feature-plans/00-oidc-sso.md: Document required environment variables

* fix: prettier formatting in cleanup script

docs/10-oidc-sso.md

@@ -180,6 +180,23 @@ BASE_URL=http://localhost:3002  # Development
 BASE_URL=https://tududi.example.com  # Production
 ```
 
+**Trust Proxy Configuration (Required for Production):**
+
+If Tududi is deployed behind a reverse proxy (nginx, Traefik, Apache, etc.), you **must** configure Express to trust the proxy:
+
+```bash
+TUDUDI_TRUST_PROXY=true
+```
+
+This is required for:
+- Proper session handling after OIDC login
+- Rate limiting based on actual client IP addresses
+- Correct IP logging in audit trails
+
+Without this setting, you may experience:
+- Session loss after SSO login (401 errors)
+- Rate limiter errors: `ValidationError: The 'X-Forwarded-For' header is set but the Express 'trust proxy' setting is false`
+
 ---
 
 ## Provider Setup Guides
@@ -530,6 +547,37 @@ If a user was created via SSO and has no password:
 
 ## Troubleshooting
 
+### Session Lost After SSO Login (401 Errors)
+
+**Symptoms:**
+- Successfully authenticate with SSO provider
+- Redirected to `/today` page
+- Immediately see login screen again
+- API calls return 401 "Authentication required"
+- Browser logs show repeated 401 errors on `/api/profile`
+
+**Cause:** Express is not configured to trust the reverse proxy, causing session cookies to not be set properly.
+
+**Solution:**
+
+Add to your `.env` file:
+```bash
+TUDUDI_TRUST_PROXY=true
+```
+
+Then restart the Tududi server:
+```bash
+docker compose restart  # For Docker
+npm start              # For standalone
+```
+
+**Verification:**
+
+After restarting, the error log should no longer show:
+```
+ValidationError: The 'X-Forwarded-For' header is set but the Express 'trust proxy' setting is false
+```
+
 ### "Provider not found" Error
 
 **Cause:** The provider slug in the URL doesn't match any configured provider.

docs/feature-plans/00-oidc-sso.md

@@ -771,15 +771,27 @@ OIDC_PROVIDER_3_AUTO_PROVISION=true
 - **Azure AD:** `https://login.microsoftonline.com/{tenant-id}/v2.0`
 - **Generic:** Any OIDC-compliant provider with `.well-known/openid-configuration`
 
-### Required Environment Variable
+### Required Environment Variables
+
+The following environment variables must be set for OAuth redirects:
 
-The `BASE_URL` environment variable must be set for OAuth redirects:
 ```bash
+# Base URL for callback redirects
 BASE_URL=http://localhost:3002  # Development
 BASE_URL=https://tududi.example.com  # Production
+
+# Trust proxy (REQUIRED for production behind reverse proxy)
+TUDUDI_TRUST_PROXY=true
 ```
 
-This is used to construct the callback URL: `${BASE_URL}/api/oidc/callback/{slug}`
+**Why TUDUDI_TRUST_PROXY is Required:**
+
+When deployed behind a reverse proxy (nginx, Traefar, Apache), Express must be configured to trust the proxy headers. Without this:
+- Sessions may not be saved properly after OIDC callback
+- Rate limiting will fail with `X-Forwarded-For` errors
+- Users will experience 401 errors after successful SSO login
+
+The `BASE_URL` is used to construct the callback URL: `${BASE_URL}/api/oidc/callback/{slug}`
 
 ---