Docs updates.

API.md

@@ -1,6 +1,6 @@
 # Paskia API
 
-For integrating Paskia with your app frontend, see [AuthFlow](AuthFlow.md).
+For integrating Paskia with your app frontend, see [integration](Integration.md).
 
 ## Web Interface
 

AuthFlow.md

@@ -1,43 +0,0 @@
-# Integrating Paskia with your App
-
-Protect API routes with forward-auth (see [Caddy](Caddy.md)). Optionally protect your app assets and not just the API.
-
-Catch response status 401/403 in fetch calls to protected endpoints and implement authentication flow in this case. The response is JSON and contains `detail` (an error message describing what is needed) and `auth.iframe` (a URL). Render that URL in an iframe and retry the request after authentication (see below).
-
-While the app is in (active) use, call `/auth/api/validate` occasionally to keep the session alive (session lifetime is 24h), otherwise the user will have to login every day. Max-age limits are unaffected by this and can be used on endpoints needing to reauthenticate with passkey more frequently.
-
-Fetch `/auth/api/user-info` to display user/session details, or link to `/auth/` if you prefer using the built-in profile UI and not having to do anything more.
-
-## Authentication Flow (iframe)
-
-```js
-// Show an authentication dialog
-const iframe = document.createElement('iframe')
-iframe.src = auth.url   // from 401/403 response JSON
-iframe.style.cssText = `
-  position: fixed;
-  inset: 0;
-  width: 100%;
-  height: 100%;
-  border: 0;
-  z-index: 9999;
-  background: transparent;
-  backdrop-filter: blur(0.1rem) brightness(0.7);
-`
-document.body.appendChild(iframe)
-
-// Wait until user is finished with the dialog
-const handler = ev => {
-  if (ev.origin !== location.origin) return
-  iframe.remove()
-  removeEventListener('message', handler)
-  if (ev.data?.type === 'auth-success') retry_original_fetch()
-}
-addEventListener('message', handler)
-```
-
-This describes the frontend flow for handling 401/403 responses from endpoints protected by Paskia forward-auth, without ever exiting your app.
-
-When a protected request fails, the backend returns 401 (needs auth / reauth) or 403 (missing permission). For API requests, the response is JSON that includes an iframe URL. Your app should render that URL in a full-screen iframe overlay, and retry the request after the iframe reports success. If it reports `auth-cancel`, don't try again. The backdrop for the dialog is a stylistic choice, and you can style the background shown with the dialog any way you wish, and consider using CSS file with the iframe rather than inline styles as used in the example.
-
-Following this flow the user gets authenticated properly and after that your app keeps running as if nothing ever happened.

Caddy.md

@@ -1,4 +1,4 @@
-# Paskia Caddy configuration
+# Paskia Caddy Configuration
 
 [Caddy](https://caddyserver.com/) is a modern web server that makes setting up web services easy. We provide a few Caddy snippets that make the configuration even easier, although the `forward_auth` directive of Caddy can be used directly as well. Place the [auth folder](caddy/auth) with the snippets `require` and `setup` where your config file is (e.g. `/etc/caddy/auth`)
 
@@ -7,7 +7,7 @@ What these snippets do
 - `require`: Use `/auth/api/forward` for access control
 - Render a login page or a permission denied page if needed (without changing URL)
 
-Your backend may not use authentication at all, or it can make use of the user information passed via `Remote-*` headers by the authentication system, see [Headers.md](Headers.md) for details.
+Your backend may not use authentication at all, or it can make use of the user information passed via `Remote-*` headers by the authentication system, see [trusted headers](Headers.md) for details.
 
 We assume the normal unprotected **Caddyfile** for your site looks like this:
 

Headers.md

@@ -1,5 +1,4 @@
-# Paskia
-## Trusted Headers for Apps
+# Paskia Trusted Headers for Apps
 
 | HTTP Header | Meaning | Example |
 |---|---|---|
@@ -20,3 +19,5 @@ When a request is allowed, the auth service adds these headers by the forward-au
 Only the UUID values should be used for identification needs, because they never change, even when things are renamed (display names change), and are never reused (created on authentication server). They are UUIDv7 so you can also extract the creation timestamp from them.
 
 Any `Remote-*` headers from clients are stripped by our [Caddy configuration](Caddy.md) to avoid dealing with any fake headers.
+
+Note: the headers are intended primarily for the backend, while either frontend or backend (passing the session cookie) can request `/auth/api/user-info` for more complete information, and that is the recommended way to do it in the frontend. See [integration](Integration.md) for more.

README.md

@@ -60,6 +60,10 @@ paskia serve [options]
 
 ## Further Documentation
 
-- [API reference](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/API.md)
-- [Caddy configuration](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/Caddy.md)
-- [Trusted Headers for Apps](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/Headers.md)
+#### Integrating with your app:
+- [Caddy configuration](Caddy.md)
+- [Trusted Headers](Headers.md)
+- [Frontend integration](Integration.md)
+
+#### API paths
+- [Paskia API](API.md)