From 535ac8558dae9e9597c903f68db250e7aaf277a8 Mon Sep 17 00:00:00 2001
From: Leo Vasanko <git@vasanko.com>
Date: Fri, 19 Dec 2025 20:59:16 +0000
Subject: [PATCH] Docs updates.

---
 README.md                     |  8 +++----
 API.md => docs/API.md         |  0
 Caddy.md => docs/Caddy.md     |  2 +-
 Headers.md => docs/Headers.md |  0
 docs/Integration.md           | 43 +++++++++++++++++++++++++++++++++++
 5 files changed, 48 insertions(+), 5 deletions(-)
 rename API.md => docs/API.md (100%)
 rename Caddy.md => docs/Caddy.md (96%)
 rename Headers.md => docs/Headers.md (100%)
 create mode 100644 docs/Integration.md

diff --git a/README.md b/README.md
index e272a69..6b52749 100644
--- a/README.md
+++ b/README.md
@@ -60,7 +60,7 @@ paskia serve [options]
 
 ## Further Documentation
 
-- [Caddy configuration](Caddy.md)
-- [Trusted Headers](Headers.md)
-- [Frontend integration](Integration.md)
-- [Paskia API](API.md)
+- [Caddy configuration](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/Caddy.md)
+- [Trusted Headers](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/Headers.md)
+- [Frontend integration](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/Integration.md)
+- [Paskia API](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/API.md)
diff --git a/API.md b/docs/API.md
similarity index 100%
rename from API.md
rename to docs/API.md
diff --git a/Caddy.md b/docs/Caddy.md
similarity index 96%
rename from Caddy.md
rename to docs/Caddy.md
index be50d8d..f3bb99d 100644
--- a/Caddy.md
+++ b/docs/Caddy.md
@@ -1,6 +1,6 @@
 # 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`)
+[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`)
 
 What these snippets do
 - `setup`: Mount the auth UI at `/auth/` proxying to `:4401`
diff --git a/Headers.md b/docs/Headers.md
similarity index 100%
rename from Headers.md
rename to docs/Headers.md
diff --git a/docs/Integration.md b/docs/Integration.md
new file mode 100644
index 0000000..56840d4
--- /dev/null
+++ b/docs/Integration.md
@@ -0,0 +1,43 @@
+# Integrating Paskia with your App
+
+Protect API routes with forward-auth (see [Caddy configuration](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.