Docs: multi-realm current state

README quick start and configuration updated for init/serve split and
paskia.kantadb; API.md server-config endpoints replaced with admin realm
CRUD and the well-known webauthn endpoint; proxy guides point at the
realm auth-host setting; oidc.md documents per-realm issuers; MultiSite.md
rewritten from the implementation plan into documentation of the shipped
mechanics, policy model, and design rationale.

docs/API.md

@@ -72,8 +72,12 @@ E.g. Org admin cannot see anything of the other orgs that he has no admin access
 | PATCH | /auth/api/admin/oidc-clients/{uuid} | Update OIDC client | 200/401/403 |
 | PATCH | /auth/api/admin/oidc-clients/{uuid}/reset-secret | Reset client secret | 200/401/403 |
 | DELETE | /auth/api/admin/oidc-clients/{uuid} | Delete OIDC client | 200/401/403 |
-| GET | /auth/api/admin/server-config/ | Get server config | 200/401/403 |
-| PATCH | /auth/api/admin/server-config/ | Update server config | 200/401/403 |
+| GET | /auth/api/admin/realms/ | List realms (rp-ids) with derived URLs | 200/401/403 |
+| POST | /auth/api/admin/realms/ | Create realm `{rp_id, rp_name?, auth_host?, origins?}` | 200/400/401/403 |
+| PATCH | /auth/api/admin/realms/{rp_id} | Update realm rp_name/auth_host/origins | 200/400/401/403 |
+| DELETE | /auth/api/admin/realms/{rp_id} | Delete realm (refused while credentials remain) | 200/400/401/403 |
+
+Realm endpoints require the `auth:admin` permission; writes additionally require recent authentication (5 minutes). Changes are validated cross-realm and apply immediately.
 
 ### WebSockets: /auth/ws/*
 
@@ -86,7 +90,9 @@ E.g. Org admin cannot see anything of the other orgs that he has no admin access
 
 These are for internal use only, but are documented here because they are the core piece in all passkey operations.
 
-### Auth host mode (--auth-host)
+### Auth host mode (dedicated auth site)
+
+A realm may configure a dedicated authentication host (auth-host, a subdomain of the rp-id), either at bootstrap (`paskia init --auth-host`) or via the Realms admin panel.
 
 #### On the auth host:
 - The Web UI is served at site root instead of /auth/* (that redirects to root paths)
@@ -98,4 +104,12 @@ These are for internal use only, but are documented here because they are the co
 - /auth/api/* is served normally.
 - /auth/api/user/*, /auth/api/admin/*, and /auth/ws/* don't exist.
 
-The WebSocket connections are directed to auth host, and must have an allowed origin corresponding to the host where the user is logging in, that the session is tied with.
+The WebSocket connections are directed to the auth host, and must have an allowed origin corresponding to the host where the user is logging in, that the session is tied with.
+
+#### Shared auth host across realms
+
+When one realm has an auth host, other realms without their own use it as their *effective* auth host: their WebSocket and cross-device flows are directed there, but their own `/auth/` still serves the full profile (host mode is keyed off the realm's *own* auth host only). `/auth/api/settings` exposes both: `auth_host` (effective) and `own_auth_host` (this realm only, null when unset).
+
+### Related Origin Requests: /.well-known/webauthn
+
+`GET /.well-known/webauthn` returns `{"origins": [...]}` listing the realm's related origins (configured origins on domains unrelated to the rp-id), per WebAuthn Related Origin Requests. Browsers fetch this from the rp-id domain when an unrelated origin runs a ceremony with this realm's rp-id. Returns 404 when the realm has no related origins. If the rp-id's main site is hosted elsewhere, serve the JSON statically there (copy it from this instance).

docs/proxy/apisix.md

@@ -173,4 +173,4 @@ The auth check then always returns 204 (except reauth with `max_age`, which stil
 
 - The auth request is `GET` by default. Since the `forward-auth` plugin does not forward the request body unless `request_method` is set to `POST`, the default `GET` is the right choice for Paskia.
 - Hop-by-hop headers are handled by APISIX when it builds the auth request, so no extra configuration is needed for `Connection`/`Upgrade`.
-- If Paskia is running on a different host, replace `localhost:4401` with the Paskia service address. For a dedicated authentication host (`--auth-host`), route `auth.example.com` to Paskia instead of `/auth/`.
+- If Paskia is running on a different host, replace `localhost:4401` with the Paskia service address. For a dedicated authentication host (the realm's auth-host setting), route `auth.example.com` to Paskia instead of `/auth/`.

docs/proxy/caddy.md

@@ -81,7 +81,7 @@ auth.example.com {
 }
 ```
 
-Remember to specify `paskia serve --auth-host auth.example.com` to restrict the authentication services to this domain.
+Remember to set the auth host for the realm — either `paskia init --auth-host auth.example.com` at bootstrap or in the admin panel's Realms section — to restrict the authentication services to this domain.
 
 Note that we still reserve `/auth/` on each site for logout page and any APIs your application may require, while full user profile and global options are only available on the auth host.
 

docs/proxy/envoy.md

@@ -161,7 +161,7 @@ See [perm argument](../api/perm.md) and [max_age argument](../api/max-age.md) fo
 
 ## WebSocket support for `/auth/`
 
-If you use a dedicated authentication host (`--auth-host`), route `auth.example.com` to the Paskia cluster and you do not need the `/auth/` bypass above. Otherwise, make sure the `/auth/` route keeps the `Upgrade` and `Connection` headers so passkey WebSocket endpoints work. The default Envoy router handles `Upgrade` headers when the client requests them.
+If you use a dedicated authentication host (the realm's auth-host setting), route `auth.example.com` to the Paskia cluster and you do not need the `/auth/` bypass above. Otherwise, make sure the `/auth/` route keeps the `Upgrade` and `Connection` headers so passkey WebSocket endpoints work. The default Envoy router handles `Upgrade` headers when the client requests them.
 
 ## Public access
 

docs/proxy/haproxy.md

@@ -123,4 +123,4 @@ The `Remote-*` success-headers glob already copies the `Remote-Public` header th
 - The Lua script strips the request body from the auth subrequest, so Paskia's `/auth/api/forward` will only see the headers.
 - HAProxy variables are limited to alphanumeric characters, dots, and underscores, but the script already normalizes header names for you (e.g. `Remote-User` becomes `req.auth_response_header.remote_user`). The `Remote-*` glob pattern in the success-headers argument handles this automatically.
 - The auth backend must be reachable without TLS. If you need TLS to Paskia, run a local TCP forwarder or use HAProxy's Lua HTTP support directly (not covered by this script).
-- If you use a dedicated authentication host (`--auth-host`), route `auth.example.com` to the Paskia backend and start Paskia with `--auth-host auth.example.com` instead of exposing `/auth/` on every site.
+- If you use a dedicated authentication host (the realm's auth-host setting), route `auth.example.com` to the Paskia backend instead of exposing `/auth/` on every site.

docs/proxy/traefik.md

@@ -92,7 +92,7 @@ authResponseHeaders:
 
 The `/auth/` router above forwards all authentication UI, API, and WebSocket traffic to Paskia. Because this router does **not** use the `paskia-auth` middleware, users can reach the login page and profile UI without being authenticated first. Traefik handles WebSocket upgrades automatically when the client requests them.
 
-If you are using a dedicated authentication host instead of `/auth/`, create a separate router for `auth.example.com` pointing to the Paskia service and start Paskia with `--auth-host auth.example.com`.
+If you are using a dedicated authentication host instead of `/auth/`, create a separate router for `auth.example.com` pointing to the Paskia service and set the realm's auth host (`paskia init --auth-host auth.example.com` at bootstrap, or the admin panel's Realms section).
 
 ## Adjusting requirements