Update fastapi-vue-setup 1.6.1 with major changes.

The restricted entry validates the session before rendering anything
(no load-time flash): 401/403 switches to the existing login component
in place of the profile, success renders the panel fully populated via
props, other failures show a minimal card with Back only. The dialog
drops the standalone page's heading and help text.

.gitignore

@@ -6,6 +6,9 @@ dist/
 package-lock.json
 paskia.sqlite
 *.paskiadb
+*.converted-bak
+*.kantadb
+*.data
 /paskia/frontend-build
 /paskia/_version.py
 coverage-html/

README.md

@@ -20,7 +20,7 @@ An easy to install passkey-based authentication service that protects any web ap
 ## Authenticate to get to your app, or in your app
 
 - API fetch: auth checks and login without leaving your app
-- Forward-auth proxy: protect any unprotected site or service (Caddy, Nginx)
+- Forward-auth proxy: protect any unprotected site or service ([Caddy](docs/proxy/caddy.md), [Nginx](docs/proxy/nginx.md), and [others](docs/proxy/index.md))
 
 The API mode is useful for applications that can be customized to run with Paskia. Forward auth can also protect your javascript and other assets. Each provides fine-grained permission control and reauthentication requests where needed, and both can be mixed where needed.
 
@@ -35,64 +35,58 @@ Paskia includes set of login, reauthentication and forbidden dialogs that it can
 
 Install [UV](https://docs.astral.sh/uv/getting-started/installation/) and run:
 
-```fish
+```sh
-uvx paskia --rp-id example.com
+uvx paskia init example.com
+uvx paskia
 ```
 
-On the first run it downloads the software and prints a registration link for the Admin. The server starts on [localhost:4401](http://localhost:4401), serving authentication for `*.example.com`. For local testing, leave out `--rp-id`.
+The first command bootstraps the database and prints a registration link for the Admin. The second starts the server on [localhost:4401](http://localhost:4401), serving authentication for `*.example.com`. For local testing, leave out the rp-id (defaults to `localhost`).
 
 For production you need a web server such as [Caddy](https://caddyserver.com/) to serve HTTPS on your actual domain names and proxy requests to Paskia and your backend apps (see documentation below).
 
 For a permanent install of `paskia` CLI command, not needing `uvx`:
 
-```fish
+```sh
 uv tool install paskia
 ```
 
 ## Configuration
 
-You will need to specify your main domain to which all passkeys will be tied as rp-id. Use your main domain even if Paskia is not running there. All other options are optional.
+Bootstrapping is done once with `paskia init`; after that, `paskia` serves all configured domains from the database `paskia.kantadb` in the current directory. Domain configuration (rp-name, auth host, origins) is managed via the admin web interface, including adding further domains (rp-ids).
 
 ```text
-paskia [options]
+paskia init [rp-id] [rp-name] [options]  # one-time bootstrap; with an existing
+                                         # database, adds the rp-id (or renames it)
+paskia migrate [rp-id]                   # convert a legacy {rp-id}.paskiadb database
+paskia [-l endpoint]                     # serve
 ```
 
-| Option | Description | Default |
+| init option | Description | Default |
 |--------|-------------|---------|
-| -l, --listen *endpoint* | Listen address: *host*:*port*, :*port* (all interfaces), or */path.sock* | **localhost:4401** |
+| -l, --listen *endpoint* | Listen address: *host*:*port*, :*port* (all interfaces), or */path.sock* (stored in the database) | **localhost:4401** |
-| --rp-id *domain* | Main/top domain for passkeys | **localhost** |
+| *rp-id* (positional) | Main/top domain for passkeys | **localhost** |
-| --rp-name *"text"* | Branding name for the entire system (passkey auth, login dialog). | Same as rp-id |
+| *rp-name* (positional) | Branding name of the domain (passkey auth, login dialog) | Same as rp-id |
-| --origin *url* | Only sites listed can login (repeatable) | rp-id and all subdomains |
-| --auth-host *url* | Dedicated authentication site, e.g. **auth.example.com** | Use **/auth/** path on each site |
-| --save | Save current options to database | (only --rp-id required on further invocations) |
 
-To clear a stored setting, pass an empty value like `--auth-host=`. The database is stored in `{rp-id}.paskiadb` in current directory. This can be overridden by environment `PASKIA_DB` if needed.
+Origins, auth hosts and related domains are configured afterwards in the admin panel's Domains section.
+
+The `paskia` serve command accepts only `--listen` (overriding the stored value) and never converts databases: with no `paskia.kantadb` it tells you to run `paskia init`, or `paskia migrate` when a legacy `{rp-id}.paskiadb` database is present. `paskia migrate` converts the legacy database; with several candidates, the positional rp-id selects one by name and the rest are left in place.
 
 ## Tutorial: From Local Testing to Production
 
 This section walks you through a complete example, from running Paskia locally to protecting a real site in production.
 
-### Step 1: Local Testing
+### Step 1: Production Configuration
 
-For development and testing, run Paskia without any arguments:
+For a real deployment, bootstrap Paskia with your domain name (rp-id). This enables SSO setup for that domain and any subdomains.
 
-```fish
+```sh
-paskia
+uvx paskia init example.com "Example Corp"
+uvx paskia
 ```
 
-This starts the server on [localhost:4401](http://localhost:4401) with passkeys bound to `localhost`. On first run, Paskia prints a registration link for the Master Admin—click it to register your first passkey.
+This binds passkeys to the rp-id, allowing them to be used there or on any subdomain of it. The rp-name is the branding shown in UI and registered with passkeys for everything on your domain (rp id). Init prints a registration link—use it to create your Admin account. You may enter your real name here for a more suitable account name.
 
-### Step 2: Production Configuration
+### Step 2: Set Up Caddy
-
-For a real deployment, configure Paskia with your domain name (rp-id). This enables SSO setup for that domain and any subdomains.
-
-```fish
-paskia --rp-id=example.com --rp-name="Example Corp" --save
-```
-
-This binds passkeys to the rp-id, allowing them to be used there or on any subdomain of it. The `--rp-name` is the branding shown in UI and registered with passkeys for everything on your domain (rp id). The `--save` option stores these settings in the database, so future runs only need `paskia --rp-id example.com`, of which we will make use of with the systemd config later on.
-
-### Step 3: Set Up Caddy
 
 Install [Caddy](https://caddyserver.com/) and copy the [auth folder](caddy/auth) to `/etc/caddy/auth`. Say your current unprotected Caddyfile looks like this:
 
@@ -116,7 +110,7 @@ app.example.com {
 
 Run `systemctl reload caddy`. Now `app.example.com` requires the `myapp:login` permission. Try accessing it and you'll land on a login dialog.
 
-### Step 4: Assign Permissions via Admin Panel
+### Step 3: Assign Permissions via Admin Panel
 
 ![Admin panel permissions](https://git.zi.fi/leovasanko/paskia/raw/main/docs/screenshots/master-permissions.webp)
 
@@ -129,7 +123,7 @@ Now you have granted yourself the new permission.
 
 Permission scopes are text identifiers with colons as separators that we can use for permission checks. The `myapp:` prefix is a convention to namespace permissions per application—you but you can use other forms as you see fit (urlsafe characters, no spaces allowed).
 
-### Step 5: Add API Authentication to Your App
+### Step 4: Add API Authentication to Your App
 
 Your backend already receives `Remote-*` headers from Caddy's forward-auth. For frontend API calls, we provide a [JS paskia module](https://www.npmjs.com/package/paskia):
 
@@ -170,48 +164,51 @@ You may also remove the `myapp:login` protection from the rest of your site path
     }
 ```
 
-### Step 6: Run Paskia as a Service
+### Step 5: Run Paskia as a Service
 
 Create a system user paskia, install UV on the system, and create a systemd unit:
 
-```fish
+```sh
 sudo useradd --system --home-dir /srv/paskia --create-home paskia
+```
+
+Install UV on the system (or arch btw `pacman -S uv`):
+
+```sh
 curl -LsSf https://astral.sh/uv/install.sh | sudo env UV_INSTALL_DIR=/usr/local/bin sh
-sudo systemctl edit --force --full paskia@.service
+```
+
+Create a systemd unit:
+
+```sh
+sudo systemctl edit --force --full paskia.service
 ```
 
 Paste the following and save:
 
 ```ini
 [Unit]
-Description=Paskia for %i
+Description=Paskia authentication system
 
 [Service]
 Type=simple
 User=paskia
+SyslogIdentifier=paskia
 WorkingDirectory=/srv/paskia
-ExecStart=uvx paskia --rp-id=%i
+ExecStart=uvx paskia@latest
 
 [Install]
 WantedBy=multi-user.target
 ```
 
-Then enable and start, view output for registration link:
+Run the service and view log:
 
-```fish
+```sh
-sudo systemctl enable --now paskia@example.com && sudo journalctl -u paskia@example.com -f -n 30 -o cat
+sudo systemctl enable --now paskia && sudo journalctl -n30 -ocat -fu paskia
 ```
 
 ### Optional: Dedicated Authentication Site
 
-By default, Paskia serves login dialogs and admin interface at the `/auth/` path on each protected site. For a cleaner setup, you can use a dedicated authentication subdomain instead. We assume you have your DNS setup for that domain or a wildcard of all subdomains to current machine.
-
-Configure Paskia with the authentication host:
-
-```fish
-paskia --rp-id example.com --auth-host=auth.example.com --save
-```
-
 Add a Caddy configuration for the authentication domain:
 
 ```caddyfile
@@ -220,13 +217,22 @@ auth.example.com {
 }
 ```
 
-Now all authentication happens at `auth.example.com` instead of `/auth/` paths on your apps. No other changes are needed. Your existing protected sites continue to work as before but they just forward to the dedicated site for user profile and other such functionality.
+Now all authentication happens at `auth.example.com` instead of `/auth/` paths on your apps. Your existing protected sites continue to work as before but they just forward to the dedicated site for user profile and other such functionality.
 
+Set the auth host in the admin panel's Domains section.
+
+## Multiple Domains and Related Origins
+
+One Paskia instance can serve several domains (rp-ids) from the same database: users, orgs and permissions are shared, while passkeys are registered per domain. The master admin adds domains in the admin panel's Domains section; no restart is needed.
+
+A domain can also let *other* domain names use its passkeys via WebAuthn [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) — list them in the domain's allowed origins (they show as related domains), and paskia serves the required `/.well-known/webauthn` declaration on the domain's main site. In-domain entries of the same list restrict which sites of the domain's own name may authenticate (a new domain defaults to `**.{domain}` — the apex and all subdomains over https).
+
+See [Multi-Site documentation](docs/MultiSite.md) for details.
 
 
 ## Further Documentation
 
-- [Caddy configuration](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/Caddy.md)
+- [Forward-Auth Guides](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/proxy/index.md) (Caddy, Nginx, ...)
 - [Trusted Headers for Backend Apps](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)

caddy/Caddyfile.dev

@@ -1,9 +1,12 @@
 localhost {
-	# Forwards API by caddy, bypassing the Vite dev proxy
+	# WebSockets bypass directly to backend (workaround for bun proxy bug)
 	# Avoids bug https://github.com/oven-sh/bun/issues/9882
-	handle /api/* {
+	handle /auth/ws/* {
 		reverse_proxy :4402   # directly to backend
 	}
+	# Everything else goes to or via Vite
+	# (Vite proxies /auth/api, /.well-known/openid-configuration and
+	# /.well-known/webauthn to the backend)
 	handle {
 		reverse_proxy :4403   # vite dev server
 	}

caddy/auth/require

@@ -2,11 +2,13 @@
 # Argument is mandatory and provides a query string to /auth/api/forward
 #   "" means just authentication
 #   perm=yourservice:login to require specific permission
+#   public=1 to allow public access (backend must check Remote-Public)
 forward_auth {$AUTH_UPSTREAM:localhost:4401} {
     uri /auth/api/forward?{args[0]}
     header_up Connection keep-alive  # Much higher performance
     header_up -Upgrade  # Disable Upgrade: WebSocket
     copy_headers {
+        Remote-Public
         Remote-User
         Remote-Name
         Remote-Groups

caddy/auth/setup

@@ -4,3 +4,10 @@ header -Remote-*
 handle @auth_api {
     reverse_proxy {$AUTH_UPSTREAM::4401}
 }
+# Paskia-served well-known endpoints: OIDC discovery and WebAuthn Related
+# Origin Requests (must reach paskia even when other /.well-known/* files
+# are served statically)
+@auth_wellknown path /.well-known/openid-configuration /.well-known/webauthn
+handle @auth_wellknown {
+    reverse_proxy {$AUTH_UPSTREAM::4401}
+}

docs/API.md

@@ -1,64 +1,117 @@
 # Paskia API
 
+[Integration](Integration.md) · [Proxy guides](proxy/index.md)
+
 For integrating Paskia with your app frontend, see [integration](Integration.md).
 
 ## Web Interface
 
-| Method | Path | What it is for | Notes |
+| Method | Path | What it is for | Responses |
 |---:|---|---|---|
-| GET | `/auth/` | User profile page | |
+| GET | /auth/ | User profile page | HTML 200/401 |
-| GET | `/auth/admin/` | Admin panel | Requires auth:admin (master) or org admin permissions. |
+| GET | /auth/admin/ | Admin panel, requires auth:admin or org admin permissions | HTML 200/401/403 |
-| GET | `/auth/{token}` | Reset / add credential URL (QR code link) | E.g. `/auth/fun.cotton.fresh.xray.lava` |
+| GET | /auth/{token} | Reset / add credential URL (QR code link), e.g. /auth/fun.cotton.fresh.xray.lava | HTML 200 |
 
-### Public JSON API: `/auth/api/*`
+### Public JSON API: /auth/api/*
 
-| Method | Path | Used for | Notes |
+| Method | Path | Used for | Expected responses |
 |---:|---|---|---|
-| GET | `/auth/api/settings` | Paskia configuration | Returns RP info + base paths + session cookie name |
+| GET | /auth/api/settings | Paskia configuration: RP info, base paths, session cookie name | 200 |
-| GET | `/auth/api/user-info` | Full user profile | Basic information, credentials, sessions, permissions |
+| GET | /auth/api/user-info | Full user profile: info, credentials, sessions, permissions | 200/401 |
-| POST | `/auth/api/logout` | Terminate session and delete session cookie | Signs out of the current site |
+| POST | /auth/api/logout | Terminate session and delete session cookie on the current host | 200 |
-| POST | `/auth/api/validate` | Validate and renew session cookie | Optional query: `perm=` (repeatable), `max_age=` |
+| POST | [/auth/api/validate](api/validate.md) | Validate and renew the session cookie; query [perm](api/perm.md), [max_age](api/max-age.md), [renew](api/validate.md#query-parameters) | 200/401/403 |
-| GET | `/auth/api/forward` | Validate access (Caddy/Nginx) | 204 on success; 401/403 otherwise (HTML if requested) |
+| GET | [/auth/api/forward](api/forward.md) | Forward-auth with reverse proxies; see [proxy guides](proxy/index.md), query [perm](api/perm.md), [max_age](api/max-age.md) | 204/401/403 empty, json or html|
 
-The `validate` and `forward` endpoints take query arguments `perm=` and `max_age=` for specific requirements on the validation of the current session.
+### User JSON API: /auth/api/user/*
 
-### User JSON API: `/auth/api/user/*`
+| Method | Path | Used for | Responses |
-
-| Method | Path | Used for | Notes |
 |---:|---|---|---|
-| PUT | `/auth/api/user/display-name` | Update the user’s display name | Body: JSON `{ "display_name": "..." }` |
+| PATCH | /auth/api/user/display-name | Update the user's display name | 200/401 |
-| POST | `/auth/api/user/logout-all` | Terminate all user sessions | Clears current host cookie |
+| POST | /auth/api/user/logout-all | Terminate all user sessions | 200/401 |
-| DELETE | `/auth/api/user/session/{session_id}` | Terminate one session | Session IDs are server-issued |
+| DELETE | /auth/api/user/session/{session_id} | Terminate one session | 200/401 |
-| DELETE | `/auth/api/user/credential/{uuid}` | Delete a credential | Requires recent authentication |
+| DELETE | /auth/api/user/credential/{uuid} | Delete a credential; requires recent authentication | 200/401/403 |
-| POST | `/auth/api/user/create-link` | Create a device-add link | Requires recent authentication |
+| POST | /auth/api/user/create-link | Create a device-add link; requires recent authentication | 200/401/403 |
+| GET | /auth/api/user/{uuid}/profile.webp | Canonical avatar image URL, public on the auth host | 200/304/404 |
+| PUT | /auth/api/user/{uuid}/profile.webp | Upload or replace an avatar; square WebP prepared in the browser | 200/401/403 |
+| DELETE | /auth/api/user/{uuid}/profile.webp | Remove an avatar; allowed for the user or an admin | 200/401/403 |
 
-These are used mostly from the user profile panel and modify the current user.
+These are used mostly from the user profile panel by the user himself, but the profile pictures are public for all to read.
 
-### Admin API: `/auth/api/admin/*`
+### Admin API: /auth/api/admin/*
 
 Normally only used via admin panel, requires auth admin permissions and can modify any users, orgs and permissions the session has access to.
 
-E.g. Org admin cannot see anything of the other orgs that he has no admin access to. Master admin `auth:admin` can see everything and create and manage orgs.
+E.g. Org admin cannot see anything of the other orgs that he has no admin access to. Master admin auth:admin can see everything and create and manage orgs.
 
-### WebSockets: `/auth/ws/*`
+| Method | Path | Used for | Responses |
+|---:|---|---|---|
+| GET | /auth/api/admin/info | Admin overview: orgs, permissions, OIDC clients | 200/401/403 |
+| POST | /auth/api/admin/permissions/ | Create permission | 200/401/403 |
+| PATCH | /auth/api/admin/permissions/{uuid} | Update permission | 200/401/403 |
+| DELETE | /auth/api/admin/permissions/{uuid} | Delete permission | 200/401/403 |
+| POST | /auth/api/admin/orgs/ | Create organization | 200/401/403 |
+| GET | /auth/api/admin/orgs/{uuid} | Get organization details | 200/401/403 |
+| PATCH | /auth/api/admin/orgs/{uuid} | Update organization | 200/401/403 |
+| DELETE | /auth/api/admin/orgs/{uuid} | Delete organization | 200/401/403 |
+| POST | /auth/api/admin/orgs/{uuid}/users | Create user in org | 200/401/403 |
+| POST | /auth/api/admin/orgs/{uuid}/roles | Create role in org | 200/401/403 |
+| POST | /auth/api/admin/orgs/{uuid}/permission | Grant permission to org | 200/401/403 |
+| DELETE | /auth/api/admin/orgs/{uuid}/permission | Revoke permission from org | 200/401/403 |
+| PATCH | /auth/api/admin/roles/{uuid} | Update role | 200/401/403 |
+| POST | /auth/api/admin/roles/{uuid}/permissions/{uuid} | Add permission to role | 200/401/403 |
+| DELETE | /auth/api/admin/roles/{uuid}/permissions/{uuid} | Remove permission from role | 200/401/403 |
+| DELETE | /auth/api/admin/roles/{uuid} | Delete role | 200/401/403 |
+| PATCH | /auth/api/admin/users/{uuid}/role | Update user role | 200/401/403 |
+| PATCH | /auth/api/admin/users/{uuid}/info | Update user info | 200/401/403 |
+| GET | /auth/api/admin/users/{uuid} | Get user details | 200/401/403 |
+| DELETE | /auth/api/admin/users/{uuid} | Delete user | 200/401/403 |
+| POST | /auth/api/admin/users/{uuid}/create-link | Create device add link | 200/401/403 |
+| DELETE | /auth/api/admin/users/{uuid}/credentials/{uuid} | Delete user credential | 200/401/403 |
+| DELETE | /auth/api/admin/users/{uuid}/sessions/{key} | Delete user session | 200/401/403 |
+| POST | /auth/api/admin/oidc-clients/ | Create OIDC client | 200/401/403 |
+| 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/domains/ | List domains (rp-ids) with derived URLs | 200/401/403 |
+| POST | /auth/api/admin/domains/ | Create domain `{rp_id, rp_name?, origins?, related?}` | 200/400/401/403 |
+| PATCH | /auth/api/admin/domains/{rp_id} | Update domain rp_name/origins/related | 200/400/401/403 |
+| DELETE | /auth/api/admin/domains/{rp_id} | Delete domain (refused while credentials remain) | 200/400/401/403 |
+
+Domain endpoints require the `auth:admin` permission; writes additionally require recent authentication (5 minutes). Changes are validated cross-domain and apply immediately.
+
+`origins` is a single object keyed by all of the domain's sign-in sites. Entries *within* the rp-id domain are in-domain sites: bare hosts, wildcards under the rp-id following the shell-glob convention (`**.example.com` covers the apex and subdomains at any depth, `*.example.com` exactly one subdomain level — https only, any scheme and port under localhost; plain `*` is not accepted), or full origins when not https. Entries *outside* the rp-id domain are related origins that may assert this domain's rp-id (WebAuthn Related Origin Requests, max 5, no wildcards); those are published at `/.well-known/webauthn` on the rp-id host. An empty object allows nothing of the domain itself. A value of `true` marks presence; `{"auth_host": true}` additionally marks an in-domain entry as the domain's authentication host.
+
+### WebSockets: /auth/ws/*
 
 | Path | Used for | Notes |
 |---|---|---|
-| `WS /auth/ws/authenticate` | Passkey authentication | Returns a session token |
+| WS /auth/ws/authenticate | Passkey authentication | Returns a session token |
-| `WS /auth/ws/register` | Register a new credential | Adding another passkey to current user or via reset token |
+| WS /auth/ws/register | Register a new credential | Adding another passkey to current user or via reset token |
-| `WS /auth/ws/remote-auth/request` | Start a cross-device login/registration request | Used from unauthenticated client |
+| WS /auth/ws/remote-auth/request | Start a cross-device login/registration request | Used from unauthenticated client |
-| `WS /auth/ws/remote-auth/permit` | Approve/deny a pairing code | Used to accept the request, if same words are entered |
+| WS /auth/ws/remote-auth/permit | Approve/deny a pairing code | Used to accept the request, if same words are entered |
 
 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 domain may configure a dedicated authentication host (auth-host, a subdomain of the rp-id) via the Domains admin panel.
 
 #### On the auth host:
-- The Web UI is served at site root (e.g. admin UI at `/admin/`), and the `/auth/...` equivalents (e.g. `/auth/admin/`) redirect to the root paths.
+- The Web UI is served at site root instead of /auth/* (that redirects to root paths)
-- All of the API stays under `/auth/api/*`
+- All of the API stays under /auth/api/*
-- Auth WebSockets remain at `/auth/ws/*` but take connections from other hosts to issue sessions for each of those.
+- Auth WebSockets remain at /auth/ws/* but take connections from other hosts to issue sessions for each of those.
 
 #### On non-auth hosts:
-- `/auth/` shows only minimal profile and allows logging out of the current site
+- /auth/ shows only minimal profile and allows logging out of the current site, link to full profile on auth host
-- `/auth/api/*` is served normally.
+- /auth/api/* is served normally.
-- `/auth/api/user/*`, `/auth/api/admin/*`, and `/auth/ws/*` don't exist.
+- /auth/api/user/*, /auth/api/admin/*, and /auth/ws/* don't exist.
+
+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.
+
+#### Auth hosts and other domains
+
+Auth hosts are strictly per-domain: a domain without its own auth host uses its own hosts for the WebSocket flows, and `/auth/api/settings` reports `auth_host` (and the identical `own_auth_host`) as null. One domain's auth host never serves another domain implicitly. To consolidate logins on one host, mark that host as the auth host on each domain that should use it (possible when the host lies under each domain's rp-id, i.e. nested rp-ids); dispatch resolves a shared host to the best-matching (longest rp-id suffix) domain.
+
+### Related Origin Requests: /.well-known/webauthn
+
+`GET /.well-known/webauthn` returns `{"origins": [...]}` listing the domain'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 domain's rp-id. Returns 404 when the domain 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/Headers.md

@@ -1,16 +1,29 @@
 # Paskia Trusted Headers for Backend Apps
 
+[Proxy guides](proxy/index.md) · [`/auth/api/forward`](api/forward.md)
+
 | HTTP Header | Meaning | Example |
 |---|---|---|
-| `Remote-User` | Authenticated user UUID | **01c03276-b8f0-**… (string) |
+| Remote-User | Authenticated user UUID | **01c03276-b8f0-**… (string) |
-| `Remote-Name` | User display name | **John Doe** |
+| Remote-Name | User display name | **John Doe** |
-| `Remote-Org` | Organization UUID | Identifier for user's org (string) |
+| Remote-Org | Organization UUID | Identifier for user's org (string) |
-| `Remote-Org-Name` | Organization display name | **The Company Ltd.** |
+| Remote-Org-Name | Organization display name | **The Company Ltd.** |
-| `Remote-Role` | Role UUID | Identifier for user's role (string) |
+| Remote-Role | Role UUID | Identifier for user's role (string) |
-| `Remote-Role-Name` | Role display name | **Employee** |
+| Remote-Role-Name | Role display name | **Employee** |
-| `Remote-Groups` | Permissions the user has, comma separated | **auth:admin,yourapp:reports** |
+| Remote-Groups | Permissions the user has, comma separated | **auth:admin,yourapp:reports** |
-| `Remote-Session-Expires` | Session expiry timestamp (ISO 8601 UTC) | **2030-12-31T23:59:59Z** |
+| Remote-Session-Expires | Session expiry timestamp (ISO 8601 UTC) | **2030-12-31T23:59:59Z** |
-| `Remote-Credential` | Credential UUID | Identifier for the sign-in passkey (string) |
+| Remote-Credential | Credential UUID | Identifier for the sign-in passkey (string) |
+| Remote-Public | Public-access marker, only present on routes using [`public=1`](api/forward.md#public-access) | **authenticated**, **forbidden** or **anonymous** |
+
+### Public access
+
+On routes configured with `public=1`, every forwarded request carries `Remote-Public` and the backend must check it before treating the request as authorized:
+
+- `authenticated` — the user has everything the route asked for; full `Remote-*` headers.
+- `forbidden` — the user is logged in but the route's `perm` check failed. Full identity headers are sent, including `Remote-Groups` — it is trustworthy, it just lacks the requested permission.
+- `anonymous` — no valid session; no identity headers are sent.
+
+Without `public=1` the header is absent and every request reaching the backend is fully authorized.
 
 Similar headers are also used by other authentication systems like [Authelia](https://www.authelia.com/integration/trusted-header-sso/introduction/) to signal the backend application information about the signed in user.
 
@@ -18,6 +31,6 @@ 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.
+Any `Remote-*` headers from clients are stripped by the proxy configuration (see our [Caddy configuration](proxy/caddy.md) and [Forward-Auth Proxy Guides](proxy/index.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.

docs/Integration.md

@@ -1,6 +1,8 @@
 # Integrating Paskia with your App
 
-This guide covers frontend and backend integration with Paskia. For Caddy forward-auth setup, see [Caddy configuration](Caddy.md).
+[API overview](API.md) · [Proxy guides](proxy/index.md)
+
+This guide covers frontend and backend integration with Paskia. For forward-auth setup, see the [Forward-Auth Proxy Guides](proxy/index.md); Caddy users can also start from the dedicated [Caddy configuration](proxy/caddy.md).
 
 ## Frontend Integration
 
@@ -58,7 +60,7 @@ validator.start()  // start polling (pauses on idle)
 validator.stop()   // stop polling
 ```
 
-The validator calls `/auth/api/validate` periodically to:
+The validator calls `/auth/api/validate` (see below) periodically to:
 - Renew the session cookie (24h lifetime)
 - Detect if the user logged out or switched accounts
 - Pause polling when the page is idle, allowing sessions to expire when not used
@@ -101,7 +103,7 @@ Or link to the built-in profile page: `/auth/`
 
 ### Using Forward-Auth Headers
 
-When using Caddy forward-auth, your backend receives `Remote-*` headers on authenticated requests. See [Headers](Headers.md) for the full list.
+When using forward-auth, your backend receives `Remote-*` headers on authenticated requests. See [Headers](Headers.md) for the full list and [Forward-Auth Proxy Guides](proxy/index.md) for proxy configuration.
 
 ```python
 # Example: Python/FastAPI
@@ -115,47 +117,45 @@ def get_data(request: Request):
 
 ### Direct Validation from Backend
 
-Your backend can validate sessions directly by calling Paskia's validate endpoint:
+This is useful for:
+- Apps/APIs not behind proxy Forward-Auth protection
+- Background jobs that need to verify a stored session
+- Check extra permissions, get user context or renew session
+
+Your backend can validate sessions directly by calling Paskia's validate endpoint [`/auth/api/validate`](api/validate.md). It generally expects client headers proxied as is, while on the URL you can specify exact requirements. To verify a session without extending its lifetime or updating its IP / user-agent, pass `renew=0`.
+
+Usually it is sufficient to simply forward the headers the client sent, assuming your proxy already preserved `Host` and set `X-Forwarded-For` (otherwise set them here with original host and IP). `User-Agent` should also be forwarded if available, omitted if not: do not let your backend HTTP client add its own header.
+
+Be sure to REMOVE connection hop-by-hop headers (these will break WebSockets among other things):
 
 ```python
-import httpx
+"Connection", "Keep-Alive", "Proxy-Connection", "TE", "Transfer-Encoding", "Upgrade"
-
-async def validate_session(request) -> dict:
-    """Validate a session cookie and check permissions."""
-    authcookie = request.get("__Host-paskia")
-    response = await httpx.post(
-        "http://localhost:4401/auth/api/validate?perm=myapp:login+myapp:api",
-        headers={
-            "Host": request.headers["host"]
-            "X-Forwarded-For": request.client.host,
-            "Cookie": f"__Host-paskia={}",
-        },
-    )
-    if response.status_code != 200:
-        return response.json()  # Return to client
-    # User authenticated... We are good to go!
-    ctx = response.json()  # User and session information
 ```
 
-This is useful for:
+## Public access
-- WebSocket connections where headers aren't available after handshake
-- Background jobs that need to verify a stored session
-- APIs not behind forward-auth (auth/restrict)
 
-### Validate Endpoint Parameters
+For apps where authentication is optional, configure the proxy route with `public=1` (see your [proxy guide](proxy/index.md)). The auth check then always lets the request through, and your backend branches on the `Remote-Public` header:
 
-`POST /auth/api/validate` accepts query parameters:
+- `anonymous` — no valid session; no `Remote-*` identity headers are present.
+- `forbidden` — the user is logged in (identity headers are present and trustworthy) but the route's `perm` was not granted.
+- `authenticated` — session valid and all requested permissions met.
 
-| Parameter | Description |
+```python
-|-----------|-------------|
+# Example: Python/FastAPI
-| `perm=scope:name` | Require this permission (repeatable) |
+@app.get("/api/reports")
-| `max_age=5min` | Require recent passkey use |
+def reports(request: Request):
+    public = request.headers.get("Remote-Public")
+    if public != "authenticated":
+        raise HTTPException(401)  # or serve a limited public view
+    user_id = request.headers.get("Remote-User")
+    # ...
+```
 
-Returns 200 with user info on success, 401/403 on failure.
+Login-on-demand still works unchanged: any 401 your app itself returns for privileged operations carries the `auth.iframe` URL that the [paskia](https://www.npmjs.com/package/paskia) module handles automatically (see [API Fetch with Automatic Auth](#api-fetch-with-automatic-auth)). A `max_age` reauth requirement on the route still returns the 401 auth flow directly from the proxy. See [public access](api/forward.md#public-access) and [Headers](Headers.md#public-access).
 
 ## Proxying /auth/ to Paskia
 
-Your app server needs to proxy `/auth/` paths to Paskia. This can be done by your application but is much easier done by Caddy or Nginx.
+Your app server needs to proxy `/auth/` paths to Paskia. This can be done by your application but is much easier done by a reverse proxy. The [Forward-Auth Proxy Guides](proxy/index.md) cover Caddy, Nginx, Traefik, Apache APISIX, Envoy and HAProxy.
 
 ### Caddy
 

docs/MultiSite.md

@@ -0,0 +1,205 @@
+# Multiple Domains (Multi-Site)
+
+One Paskia instance on one port serves several domains from a single
+database. Typical uses:
+
+- `app1.company.com` and `app2.com` cannot share passkeys, but user
+  management should stay under one roof.
+- A few alternative brand names should accept the _same_ passkeys.
+
+## Shared vs. per-domain
+
+**Shared across all domains:** user accounts, organizations, roles,
+permissions, and OIDC clients. A user account exists once and can sign in
+on every domain.
+
+**Per domain:** passkeys and sessions.
+
+- A passkey is registered to one domain name (enforced by the browser): a
+  passkey created for `company.com` works on `company.com` and its
+  subdomains, never on an unrelated name — unless that name is configured
+  as a [related origin](#related-origins-sharing-passkeys-across-domain-names).
+  A user active on two domains simply holds one passkey per domain.
+- A session is bound to the exact host that issued it.
+
+## The simplest case: several sites on one domain
+
+Multi-site does not require several domains. Sites under one name —
+`app1.company.com`, `app2.company.com` and so on — share the domain
+`company.com`: one passkey works on all of them (WebAuthn natively allows
+the domain and its subdomains), and the default `**.company.com` origin
+entry already lets every one of them sign in. Add explicit entries only
+to restrict which sites may sign in, and mark an auth host (see below)
+if you want sign-in centralized on one site.
+
+## Managing domains
+
+The admin panel's **Domains** section (master admins only) lists every
+domain with its allowed origins. There you can add, edit and delete
+domains; changes apply immediately without a restart and require a recent
+sign-in (within 5 minutes). The 🔑 and 🔗 markers in the origins column
+identify the auth host and related origins (below).
+
+A domain consists of:
+
+- **Domain (rp-id)** — the domain name passkeys belong to, e.g.
+  `company.com`. ("rp-id" is the WebAuthn term; read it as "domain name".)
+  It cannot be changed after creation, because existing passkeys are bound
+  to it — delete and re-create the domain instead.
+- **Display name (rp-name)** — branding shown in sign-in dialogs and
+  registered with passkeys.
+- **Allowed origins** — the sites where this domain's passkeys may sign
+  in, plus any related origins.
+
+Deleting a domain is refused while any passkey is still registered to it,
+when it is the last remaining domain, or when it is the domain you are
+currently using. Users and organizations are never deleted with a domain
+— they are shared. An edit that would lock you out (your current site
+could no longer run passkey ceremonies for that domain) is refused as
+well.
+
+## Allowed origins (sign-in sites)
+
+This list controls which sites may sign in with the domain's passkeys.
+Everything is explicit: an empty list allows nothing of the domain itself
+(related origins, below, still work — a domain can in principle run
+entirely on related origins). A new domain starts with one entry,
+`**.{domain}`, which suits most deployments.
+
+Entry forms:
+
+- `**.company.com` — the domain itself and its subdomains at any depth,
+  https only. The default entry of a new domain.
+- `*.company.com` — exactly one subdomain level: `app.company.com` yes,
+  but neither the apex `company.com` nor `a.b.company.com`. Use this when
+  the apex or deeper subdomains should not serve sign-ins.
+- `app.company.com` — exactly this host, https only.
+- `http://localhost:8080` — a full origin with scheme, for non-https
+  exceptions.
+
+Under `localhost`, both wildcard forms match any scheme and any port, as
+a development convenience. An entry on a different domain name
+automatically becomes a related origin (🔗) instead — see below.
+
+### Wildcard syntax
+
+Wildcards follow the shell-glob convention — the same one permission
+scopes use (`*` within a segment, `**` across segments, see
+[the perm argument](api/perm.md)): `**` spans any number of hostname
+labels including none, `*` spans exactly one. Wildcards must stay within
+the domain, and plain `*` is not accepted — it would suggest "anything
+goes".
+
+Conventions elsewhere differ: DNS, TLS and nginx take `*.example.com` to
+mean subdomains only (TLS: exactly one level), while browser-extension
+match patterns take it as apex plus any depth. The `*`/`**` split
+sidesteps that ambiguity, and the less obvious forms `*example.com` and
+`.example.com` remain unsupported on purpose.
+
+## The auth host (🔑)
+
+Marking one allowed origin as the **auth host** (row menu ⋮ → "Set as
+auth host") centralizes the account and admin interface on that site,
+e.g. `auth.company.com`:
+
+- On the auth host the web UI is served at the site root (`/` instead of
+  `/auth/`), and all passkey operations for the domain happen there.
+- The domain's other sites show only a minimal profile page at `/auth/`
+  with logout and a link to the full profile; their sign-in dialogs talk
+  to the auth host behind the scenes. Every sign-in site still needs to
+  be listed in (or covered by) the allowed origins.
+
+The auth host is strictly per-domain — domains never borrow each other's
+auth host. To consolidate several domains on one sign-in site, that site
+must lie under each domain's name (nested domains, e.g. domains
+`company.com` and `auth.company.com`) and be marked on each of them.
+
+## Related origins: sharing passkeys across domain names
+
+Sometimes a few different domain names should accept the _same_ passkeys
+— for example after a rebrand, when `app2.com` should keep working with
+existing `company.com` passkeys. Adding `app2.com` to `company.com`'s
+allowed origins makes it a **related origin**: browsers then let
+`app2.com` use `company.com` passkeys directly — no redirects, no
+cross-domain cookies. (This uses the WebAuthn "Related Origin Requests"
+mechanism, which is why the UI also says ROR.)
+
+Rules:
+
+- At most **5 related origins per domain** — a browser limit. This is for
+  a small family of equally trusted sites, not for hundreds of customer
+  domains; use separate domains for those.
+- Exact hosts only — no wildcards — and always outside the domain's own
+  name.
+- The browser verifies the setup against
+  `https://<domain>/.well-known/webauthn`. Paskia serves that document
+  automatically when it hosts the domain's main site; if the main site is
+  hosted elsewhere, copy the JSON document shown in the domain dialog and
+  publish it there. The dialog also checks the published document for
+  you.
+- A related origin shares the domain's security boundary completely — do
+  not mix trust levels within one domain.
+- When several domains could claim a host: a host that _is_ a configured
+  domain name always serves its own domain; otherwise an explicit related
+  origin listing wins over merely falling under another domain's name.
+
+Passkeys never move between domains. If you later consolidate separate
+domains onto one, users re-enroll: sign in once via remote authorization
+(below), then register a new passkey for the common domain from the
+profile page.
+
+## Signing in across domains
+
+Users exist once, but need a passkey per domain. Two mechanisms smooth
+this over:
+
+- **Remote authorization:** a user without a passkey for the current
+  domain can start a login request and approve it from any device already
+  signed in — on _any_ domain of the instance. The approval screen shows
+  which site is requesting access.
+- **Enroll on the spot:** when the signed-in user has no passkey for the
+  current domain, the profile page offers "Add Passkey for {domain}", so
+  everyday sign-in stays local from then on.
+
+## OIDC with multiple domains
+
+OIDC clients are shared by the whole instance: register a client once and
+it works through every domain. Each domain serves its own discovery URL
+(`https://<host>/.well-known/openid-configuration`), listed in the admin
+OIDC client view. Have each app pick **one** discovery URL and use it
+consistently, so its tokens always validate against the same issuer.
+
+## Command line
+
+The admin panel covers all domain management after bootstrap. On the
+command line:
+
+- `paskia init [domain] [name]` — creates the database `paskia.kantadb`
+  with the first domain. Run again with an existing database to add
+  another domain (or update a display name).
+- `paskia migrate [domain]` — converts a legacy 1.x `{domain}.paskiadb`
+  database to `paskia.kantadb`; see below.
+- `paskia` — serves all configured domains; takes no domain options, only
+  `--listen` as a per-run override.
+
+## Upgrading from 1.x
+
+2.0 intentionally changes the on-disk layout and the domain configuration
+model:
+
+- The database is the single file **`paskia.kantadb`** in the working
+  directory; user files (avatars) live in **`paskia.data/users/`**.
+  `paskia migrate` performs the conversion and renames the old database
+  aside to `{domain}.paskiadb.converted-bak`. With several legacy
+  databases, the positional argument selects one by name. Legacy wildcard
+  origins convert as-is (https only, except any scheme and port under
+  `localhost`); a legacy database without configured origins — where that
+  meant the whole domain was allowed — gets an explicit `**.{domain}`
+  entry.
+- Origins, auth hosts and related origins are no longer environment
+  settings — they live in the database and are managed in the admin
+  panel's Domains section. `PASKIA_AUTH_HOST` remains only as a
+  development-server (vite) setting.
+- OIDC becomes instance-global: one signing key and one client set,
+  reachable through every domain's discovery URL (previously each rp-id
+  had its own). Existing clients keep working through any domain.

docs/api/forward.md

@@ -0,0 +1,84 @@
+# GET /auth/api/forward
+
+[API overview](../API.md) · [Proxy guides](../proxy/index.md)
+
+Forward-auth validation for reverse proxies. The proxy calls this endpoint for every incoming request; Paskia validates the session and either authorizes the request by returning 204 with `Remote-*` headers, or rejects it with 401/403 error responses with an HTML login page if `text/html` was requested (i.e. it's a browser viewing the page), or otherwise JSON with details on the error and a URL to initiate API authentication flow.
+
+The proxy server follows the 204 response with the original request to protected service, adding those remote headers to original user request, sent to the service. Any error response is sent directly back to client, never connecting to the protected service.
+
+See [Forward-Auth Proxy Guides](../proxy/index.md) for Caddy, Nginx, Traefik, Apache APISIX, Envoy and HAProxy configuration examples. Caddy users can also start from the dedicated [Caddy configuration guide](../proxy/caddy.md).
+
+
+## Query parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| perm | Required permissions. See the [perm argument](perm.md). |
+| max_age | Require recent passkey use. See the [max_age argument](max-age.md). |
+| public | `public=1` allows public access: instead of 401 (no/expired session) or 403 (permission denied), the request passes with a `Remote-Public` header marking the bypass. Reauth (`max_age`) still requires the auth flow. |
+
+## Public access
+
+With `public=1` the endpoint returns 204 in every case except reauth and malformed arguments, and always sets `Remote-Public`:
+
+| Value | Meaning | Identity headers |
+|---|---|---|
+| `authenticated` | Session valid, all requested permissions met | Full `Remote-*` set |
+| `forbidden` | Session valid, but the `perm` check failed | Full `Remote-*` set (including `Remote-Groups` — it is trustworthy, it just lacks the requested permission) |
+| `anonymous` | No valid session | None |
+
+The backend must check `Remote-Public` before treating the request as authorized. See [Trusted Headers](../Headers.md) and the "Public access" section in the [proxy guides](../proxy/index.md).
+
+## Request headers
+
+| Header | Expected value / note | How Paskia uses it |
+|---|---|---|
+| Host | Forwarded directly from the client | Verifying the session's bound host |
+| Cookie | Forwarded directly or just cookie `__Host-paskia` | Session ID |
+| X-Forwarded-Method | The HTTP method, e.g. POST | Logging of original request |
+| X-Forwarded-Uri | Request path and query, e.g. /reports?foo=bar | Logging of original request |
+| Accept | text/html or anything else | Determines whether failures return an HTML page or JSON |
+
+Connection hop-by-hop headers (Connection, Upgrade, Transfer-Encoding, etc.) must not be forwarded.
+
+## Response
+
+### Success (204)
+
+No response body. Only [Remote headers](../Headers.md) are set on the response and your proxy should forward them to the backend request. The headers, not a response body, are the whole point of this endpoint: they are how the authenticated identity reaches the protected service, which can trust them because it is only reachable through the proxy.
+
+### Failure (400 / 401 / 403)
+
+| Status | Meaning |
+|---|---|
+| 400 | Malformed perm argument (see [perm](perm.md#syntax-errors)). The error detail names `/auth/api/forward` as the origin and never echoes query arguments. |
+| 401 | Session missing or expired, or max_age not satisfied — the user needs to (re)authenticate. |
+| 403 | Requested permissions are missing — the forbidden flow allows signing in with another account. |
+
+Failure responses come in two flavors, chosen by the Accept header, because the audience differs:
+
+- A browser asking for a page (Accept includes text/html) gets a full authentication page it can show directly — the proxy simply passes the response through and the user can sign in without any application involvement.
+- Any other request (fetch, img, ...) gets JSON intended for programmatic handling. Besides the error detail, it carries an auth section whose iframe URL points to a ready-made authentication dialog your frontend can embed, so the user can sign in without leaving your app:
+
+```json
+{
+  "detail": "Additional authentication required",
+  "auth": {
+    "mode": "reauth",
+    "iframe": "/auth/restricted/iframe#mode=reauth&theme=dark"
+  }
+}
+```
+
+The mode field:
+- login: no valid session, need to sign in
+- reauth: additional authentication required (using same passkey)
+- forbidden: lacking required permissions
+
+Extra metadata such as the user's theme override may appear as additional fields and iframe fragment parameters.
+
+Note: we provide a JavaScript package [paskia](https://www.npmjs.com/package/paskia) with helpers for the embedding, fetch 401/403 handling, session renewals and more.
+
+## Session renewal
+
+The forward endpoint **does not renew** the session because in the forward-auth mechanism it could not send the client a renewed session cookie. It only validates the current cookie and returns the trusted headers. Use [/auth/api/validate](validate.md) when you need to refresh the session lifetime. Otherwise the user will have to sign in again every 24h even if they are actively using the service.

docs/api/max-age.md

@@ -0,0 +1,47 @@
+# The max_age argument
+
+[API overview](../API.md) · [`/auth/api/validate`](validate.md) · [`/auth/api/forward`](../forward.md)
+
+The max_age argument is used by endpoints that validate sessions to require a recent passkey use. It is supported by:
+
+- [POST /auth/api/validate](validate.md)
+- [GET /auth/api/forward](forward.md)
+
+## What it checks
+
+max_age limits how long ago the user last authenticated with their passkey. It is intended for high-risk actions where you want to be sure the user recently proved possession of their credential, not just that they still have a valid session cookie.
+
+The check compares the elapsed time since the credential was last used against the given limit:
+
+- If the credential has a last_used timestamp, that time is used.
+- Otherwise, the session's validated timestamp is used as a fallback.
+
+If the authentication is older than max_age, the endpoint returns 401 with mode reauth, prompting the user to re-authenticate.
+
+## Time units
+
+max_age accepts a number followed by one of these units:
+
+| Unit | Meaning |
+|---|---|
+| s | seconds |
+| m / min | minutes |
+| h | hours |
+| d | days |
+
+Examples:
+
+```text
+?max_age=30s
+?max_age=5m
+?max_age=5min
+?max_age=1h
+?max_age=1d
+```
+
+An invalid format is logged as a warning but does not cause the request to fail; the requirement is simply ignored in that case.
+
+## Important notes
+
+- Session renewal by /auth/api/validate does **not** count as fresh authentication. The check is based on the credential's last_used time, not on how recently the session cookie was renewed.
+- max_age is independent of perm. You can use either or both at the same time.

docs/api/perm.md

@@ -0,0 +1,96 @@
+# The perm argument
+
+[API overview](../API.md) · [`/auth/api/validate`](validate.md) · [`/auth/api/forward`](../forward.md)
+
+The perm argument is used by endpoints that validate sessions to require one or more permission scopes. It is supported by:
+
+- [POST /auth/api/validate](validate.md)
+- [GET /auth/api/forward](forward.md)
+
+## Passing the argument
+
+Repeat the query parameter for each required scope:
+
+```text
+?perm=myapp:read&perm=myapp:write
+```
+
+You can also pass multiple scopes in one parameter by separating them with whitespace (a literal space, i.e. `+` or `%20` in the query string):
+
+```text
+?perm=myapp:read%20myapp:write
+```
+
+Both forms produce the same result.
+
+## Semantics
+
+The perm argument uses **AND** semantics between groups: **every** listed scope group must be satisfied by the effective permissions for the request to succeed. If any required group is not satisfied, the endpoint returns 403.
+
+Within a single group, use `|` to list alternatives with **OR** semantics — the group is satisfied when **any one** of the alternatives is present:
+
+```text
+?perm=myapp:read|myapp:write+myapp:login
+```
+
+This requires `myapp:login` **and** (`myapp:read` **or** `myapp:write`). No whitespace is allowed around the `|` operator.
+
+## Syntax errors
+
+Parsing is strict: anything out of spec is rejected with **400 Bad Request** rather than guessed at. This includes:
+
+- Empty values or alternatives (`?perm=`, `?perm=a||b`, `?perm=|a`, `?perm=a|`)
+- Whitespace around `|` (`?perm=a+|+b`)
+- Characters not allowed in scopes other than the operators (space and `|`); scopes match `^[A-Za-z0-9:._~/-]+$` plus the `*` wildcard. In particular a literal `+` in the decoded value (from a `%2B` in the query string) is rejected — use `+` or `%20` to encode a space, never `%2B`.
+
+Extra spaces between groups (leading, trailing, or repeated) are tolerated, since they can easily result from URL formatting and carry no ambiguity — they only ever add required permissions, never remove them. The `|` operator is parsed strictly: `?perm=foo&perm=|bar` is an error, never a way to make `foo` optional.
+
+## Wildcards
+
+Wildcards work like filenames, with `:` and `/` acting as path separators:
+
+- `*` matches any sequence of characters **within a single segment** (it never crosses a `:` or `/`)
+- `**` matches any sequence of characters, **across separators**
+- Part of a segment can be wildcarded, with required text on either or both sides
+
+```text
+?perm=myapp:*
+```
+
+This matches myapp:read and myapp:write, but **not** myapp:read:all — use `myapp:**` for that. Partial wildcards like `myapp:re*` or `myapp:r*d` match myapp:read. The same applies to path-based scopes: `myapp:path:/api/*` matches myapp:path:/api/clients but not myapp:path:/api/v2/clients — use `myapp:path:/api/**` to span path segments.
+
+## Effective permissions
+
+The permissions available to a session are determined as follows:
+
+1. **Role permissions** — the role assigned to the user contains a set of permission UUIDs.
+2. **Org grantable permissions** — only permissions that the user's organization is allowed to grant are effective.
+3. **Domain filtering** — a permission can be restricted to a specific domain via its domain field. If the request's Host header does not match that domain, the permission is excluded.
+
+The result is the set of effective permission scopes used for the perm check. Domain-restricted permissions let you grant a scope only for a specific site or subdomain without making it global.
+
+## Examples
+
+Require a single permission:
+
+```text
+?perm=myapp:login
+```
+
+Require two permissions:
+
+```text
+?perm=myapp:login&perm=myapp:api
+```
+
+Require any scope under myapp:
+
+```text
+?perm=myapp:*
+```
+
+Require myapp:login and either myapp:read or myapp:write:
+
+```text
+?perm=myapp:login&perm=myapp:read|myapp:write
+```

docs/api/validate.md

@@ -0,0 +1,67 @@
+# POST /auth/api/validate
+
+[API overview](../API.md) · [`/auth/api/forward`](../forward.md) · [max_age](max-age.md) · [perm](perm.md)
+
+Validate a session and renew its lifetime when needed. This endpoint is normally called by the browser/session validator, but backends may also call it directly when not behind a forward-auth proxy.
+
+See also the [API overview](../API.md) and the [integration guide](../Integration.md).
+
+## Query parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| perm | Required permissions. See the [perm argument](perm.md). |
+| max_age | Require recent passkey use. See the [max_age argument](max-age.md). |
+| renew | Pass `renew=0` to skip renewal: does no session updates, auth check only. |
+
+## Request headers
+
+| Header | Expected value / note | How Paskia uses it |
+|---|---|---|
+| Host | Forwarded directly from the client | Verifying the session's bound host |
+| Cookie | Forwarded directly or just cookie `__Host-paskia` | Session ID |
+| X-Forwarded-For | Real client IP | Recorded in logs and session data instead of the backend/proxy IP; requires FORWARDED_ALLOW_IPS to trust the immediate peer |
+| User-Agent | Forward the original client UA if available; do not let your backend client add its own default | Recorded in session data only when the header is present; omitting it preserves the existing value |
+
+See [integration documentation for backend validate requests](../Integration.md) for more detailed instructions, in particular for forwarding of client-provided headers.
+
+## Response
+
+The endpoint always responds with JSON.
+
+### Success (200)
+
+```json
+{
+  "valid": true,
+  "renewed": false,
+  "ctx": {
+    "user": {
+      "uuid": "...",
+      "display_name": "John Smith",
+      "theme": "dark"
+    },
+    "org": {
+      "uuid": "...",
+      "display_name": "The Company Ltd."
+    },
+    "role": {
+      "uuid": "...",
+      "display_name": "Employee"
+    },
+    "permissions": ["auth:admin", "myapp:login"]
+  }
+}
+```
+
+If the response includes a Set-Cookie header, the session has been renewed (renewed is true) and you should forward that cookie to the client so the browser updates its expiry. Not forwarding it means the session lifetime is not extended, so the user may need to re-authenticate sooner. Renewals are throttled, so frequent calls usually return renewed: false with no Set-Cookie.
+
+### Failure (400 / 401 / 403)
+
+| Status | Meaning |
+|---|---|
+| 400 | Malformed perm argument (see [perm](perm.md#syntax-errors)). |
+| 401 | Session missing, expired, or max_age not satisfied. The response body includes auth metadata for the login/reauth iframe. |
+| 403 | Session is valid but one or more requested permissions are missing. |
+
+A failure response never contains a refreshed Set-Cookie.

docs/proxy/apisix.md

@@ -0,0 +1,176 @@
+# Apache APISIX Forward-Auth
+
+[`/auth/api/forward`](../api/forward.md) · [Proxy guides](index.md)
+
+This guide uses the Apache APISIX [`forward-auth`](https://apisix.apache.org/docs/apisix/plugins/forward-auth/) plugin to ask Paskia whether each request is allowed.
+
+## Overview
+
+APISIX adds the standard `X-Forwarded-*` headers automatically, but we still tell the plugin to forward `Host`, `Cookie`, and `Accept` from the client request. On a `204` response from Paskia we copy the `Remote-*` headers to the backend request.
+
+## Admin API example
+
+```sh
+# Route that proxies /auth/ to Paskia without forward-auth.
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "id": "paskia-auth-ui",
+    "uri": "/auth/*",
+    "upstream": {
+      "nodes": { "localhost:4401": 1 },
+      "type": "roundrobin"
+    }
+  }'
+
+# Protected route that uses Paskia forward-auth.
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "id": "app-protected",
+    "uri": "/*",
+    "priority": 10,
+    "plugins": {
+      "forward-auth": {
+        "uri": "http://localhost:4401/auth/api/forward?perm=myapp:login",
+        "request_headers": [
+          "Host",
+          "Cookie",
+          "Accept",
+          "X-Forwarded-Method",
+          "X-Forwarded-Uri",
+          "X-Forwarded-Host",
+          "X-Forwarded-Proto",
+          "X-Forwarded-For"
+        ],
+        "upstream_headers": [
+          "Remote-User",
+          "Remote-Name",
+          "Remote-Groups",
+          "Remote-Org",
+          "Remote-Org-Name",
+          "Remote-Role",
+          "Remote-Role-Name",
+          "Remote-Session-Expires",
+          "Remote-Credential",
+          "Remote-Public"
+        ]
+      }
+    },
+    "upstream": {
+      "nodes": { "localhost:3000": 1 },
+      "type": "roundrobin"
+    }
+  }'
+```
+
+The `paskia-auth-ui` route has a higher priority (`priority` defaults to the same value for both routes; you can also rely on the more specific `/auth/*` URI matching first). Because it does not use the `forward-auth` plugin, users can reach the login/profile pages without already being authenticated.
+
+## ADC / declarative example
+
+```yaml
+services:
+  - name: paskia-auth-ui
+    routes:
+      - name: auth-route
+        uris:
+          - /auth/*
+        upstream:
+          type: roundrobin
+          nodes:
+            - host: localhost
+              port: 4401
+              weight: 1
+
+  - name: app-protected
+    routes:
+      - name: app-route
+        uris:
+          - /*
+        plugins:
+          forward-auth:
+            uri: http://localhost:4401/auth/api/forward?perm=myapp:login
+            request_headers:
+              - Host
+              - Cookie
+              - Accept
+              - X-Forwarded-Method
+              - X-Forwarded-Uri
+              - X-Forwarded-Host
+              - X-Forwarded-Proto
+              - X-Forwarded-For
+            upstream_headers:
+              - Remote-User
+              - Remote-Name
+              - Remote-Groups
+              - Remote-Org
+              - Remote-Org-Name
+              - Remote-Role
+              - Remote-Role-Name
+              - Remote-Session-Expires
+              - Remote-Credential
+              - Remote-Public
+        upstream:
+          type: roundrobin
+          nodes:
+            - host: localhost
+              port: 3000
+              weight: 1
+```
+
+Apply it with:
+
+```sh
+adc sync -f paskia.yaml
+```
+
+## What APISIX sends to Paskia
+
+APISIX automatically adds these headers to the auth request:
+
+| Header | Value |
+|---|---|
+| `X-Forwarded-Method` | Original HTTP method |
+| `X-Forwarded-Proto` | Request scheme (`http`/`https`) |
+| `X-Forwarded-Host` | Original host |
+| `X-Forwarded-Uri` | Original request URI |
+| `X-Forwarded-For` | Client IP address |
+
+We list them again in `request_headers` to make sure they are not accidentally filtered out when the list is explicit.
+
+## Response headers
+
+`upstream_headers` lists the `Remote-*` headers that APISIX copies from the auth response to the backend request. The plugin does not support a wildcard here, so each header must be named.
+
+If you want Paskia's failure-response headers (such as `Content-Type` or `Set-Cookie`) to reach the client, list them in `client_headers`. For Paskia this is usually not needed; the response body already contains the JSON auth URL or the HTML login page.
+
+## Adjusting requirements
+
+Change the `uri` query string to require different permissions or recent authentication:
+
+```yaml
+uri: http://localhost:4401/auth/api/forward?perm=myapp:login
+uri: http://localhost:4401/auth/api/forward?perm=myapp:admin&max_age=5min
+uri: http://localhost:4401/auth/api/forward
+```
+
+The last form requires only authentication. See [perm argument](../api/perm.md) and [max_age argument](../api/max-age.md).
+
+## Public access
+
+For routes where anonymous visitors are allowed but logged-in users should still be identified, add `public=1` to the `forward-auth` URI:
+
+```yaml
+uri: http://localhost:4401/auth/api/forward?public=1
+uri: http://localhost:4401/auth/api/forward?public=1&perm=myapp:reports
+```
+
+The auth check then always returns 204 (except reauth with `max_age`, which still returns the 401 auth flow), and the `Remote-Public` header — included in the `upstream_headers` lists above — marks each request as `anonymous`, `forbidden` or `authenticated`. The backend always runs and must check `Remote-Public` before treating the request as authorized. See [public access](../api/forward.md#public-access) and [trusted headers](../Headers.md#public-access).
+
+## Notes
+
+- 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 (the domain's auth-host setting), route `auth.example.com` to Paskia instead of `/auth/`.

docs/proxy/caddy.md

@@ -1,13 +1,15 @@
 # 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`)
+[`/auth/api/forward`](../api/forward.md) · [Proxy guides](index.md)
+
+[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`
 - `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 [trusted headers](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:
 
@@ -56,6 +58,19 @@ app.example.com {
 
 The above setup allows unauthenticated access to certain files, then implements two different access controls for your backend app depending on which path is accessed. Note that the perm and max-age options may be combined, e.g. `perm=myapp:admin&max-age=5min` on a very sensitive endpoint. This will require additional authentication if the passkey hasn't been used in the last 5 minutes (automatic session renewals don't affect this). Use `""` if you only want the user to be authenticated with no time or perm requirements.
 
+### Public access (public=1)
+
+For routes where anonymous visitors are allowed but logged-in users should still be identified, add `public=1` to the same snippet:
+
+```caddyfile
+handle {
+    import auth/require "public=1"
+    reverse_proxy :3000
+}
+```
+
+The auth check then always passes (204): anonymous requests and users lacking a requested `perm` reach your backend marked with a `Remote-Public` header (`anonymous`, `forbidden` or `authenticated`) instead of getting a 401/403. Your backend must check `Remote-Public` before treating the request as authorized — see [trusted headers](../Headers.md#public-access). A `max_age` reauth requirement still renders the authentication page, even on public routes.
+
 ### Dedicated Authentication Site
 
 When you setup a separate subdomain for the authentication site, just add to your config another section for the auth host:
@@ -66,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 domain in the admin panel's Domains 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

@@ -0,0 +1,181 @@
+# Envoy External Authorization (ext_authz)
+
+[`/auth/api/forward`](../api/forward.md) · [Proxy guides](index.md)
+
+This guide uses Envoy's [external authorization filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter) (`ext_authz`) to ask Paskia whether each request is allowed.
+
+## Overview
+
+Envoy's `ext_authz` HTTP filter calls an external HTTP service before forwarding a request to the upstream. The filter needs to know which headers from the original request to send to Paskia, and which headers from Paskia's response to add to the upstream request or to the client response.
+
+A minimal static configuration looks like this:
+
+```yaml
+static_resources:
+  listeners:
+    - name: app_listener
+      address:
+        socket_address:
+          address: 0.0.0.0
+          port_value: 8080
+      filter_chains:
+        - filters:
+            - name: envoy.filters.network.http_connection_manager
+              typed_config:
+                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+                stat_prefix: ingress_http
+                use_remote_address: true
+                route_config:
+                  name: local_route
+                  virtual_hosts:
+                    - name: app
+                      domains: ["*"]
+                      routes:
+                        # Pass /auth/ straight to Paskia, bypassing ext_authz.
+                        - match:
+                            prefix: "/auth/"
+                          route:
+                            cluster: paskia
+                          typed_per_filter_config:
+                            envoy.filters.http.ext_authz:
+                              "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
+                              disabled: true
+
+                        # Protect everything else.
+                        - match:
+                            prefix: "/"
+                          route:
+                            cluster: app_backend
+                http_filters:
+                  - name: envoy.filters.http.ext_authz
+                    typed_config:
+                      "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz
+                      transport_api_version: v3
+                      http_service:
+                        server_uri:
+                          uri: localhost:4401
+                          cluster: paskia
+                          timeout: 0.5s
+                        # Send every auth check to /auth/api/forward with the
+                        # required permission, regardless of the original path.
+                        path_override: "/auth/api/forward?perm=myapp:login"
+                        authorization_request:
+                          allowed_headers:
+                            patterns:
+                              - exact: Host
+                              - exact: Cookie
+                              - exact: Accept
+                          # Add the headers Paskia logs / expects.
+                          headers_to_add:
+                            - key: X-Forwarded-Method
+                              value: "%REQ(:METHOD)%"
+                            - key: X-Forwarded-Uri
+                              value: "%REQ(:PATH)%"
+                            - key: X-Forwarded-Proto
+                              value: "%REQ(:SCHEME)%"
+                            - key: X-Forwarded-For
+                              value: "%REQ(X-Forwarded-For)%"
+                        authorization_response:
+                          # Forward every Remote-* header to the backend.
+                          allowed_upstream_headers:
+                            patterns:
+                              - prefix: Remote-
+                          # Forward the response Content-Type to the client on 401/403.
+                          allowed_client_headers:
+                            patterns:
+                              - exact: Content-Type
+                      failure_mode_allow: false
+                  - name: envoy.filters.http.router
+                    typed_config:
+                      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+
+  clusters:
+    - name: app_backend
+      connect_timeout: 0.25s
+      type: logical_dns
+      lb_policy: round_robin
+      load_assignment:
+        cluster_name: app_backend
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address:
+                    socket_address:
+                      address: localhost
+                      port_value: 3000
+
+    - name: paskia
+      connect_timeout: 0.25s
+      type: logical_dns
+      lb_policy: round_robin
+      load_assignment:
+        cluster_name: paskia
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address:
+                    socket_address:
+                      address: localhost
+                      port_value: 4401
+```
+
+## Important configuration details
+
+- **`path_override`** — the auth request always goes to `/auth/api/forward?perm=myapp:login`, no matter which path the client requested. The original path is sent in `X-Forwarded-Uri` for Paskia to log.
+- **`authorization_request.allowed_headers`** — Envoy only forwards the headers you explicitly allow. We allow `Host`, `Cookie`, and `Accept`. The `X-Forwarded-*` headers are added via `headers_to_add` so they are based on Envoy's view of the request, not spoofed client values.
+- **`headers_to_add`** — Envoy supports substitution format strings such as `%REQ(:METHOD)%` and `%REQ(:PATH)%`. These set the headers Paskia uses for logging and host validation.
+- **`authorization_response.allowed_upstream_headers`** — `prefix: Remote-` tells Envoy to copy every response header starting with `Remote-` to the upstream request. This also removes any client-supplied `Remote-*` headers, so the backend can trust them.
+- **`authorization_response.allowed_client_headers`** — on a 401/403 response, Envoy forwards only the allowed response headers to the client. Paskia returns HTML or JSON with a `Content-Type` header, so we allow that. (Paskia does not set cookies on the forward-auth response.)
+- **`typed_per_filter_config`** on the `/auth/` route disables `ext_authz` so users can reach the login/profile pages without already being authenticated.
+
+## Per-route requirements
+
+Different routes often need different permissions or `max_age` values. Use `typed_per_filter_config` on each route to override the `http_service.path_override`:
+
+```yaml
+routes:
+  - match:
+      prefix: "/reports"
+    route:
+      cluster: app_backend
+    typed_per_filter_config:
+      envoy.filters.http.ext_authz:
+        "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
+        check_settings:
+          http_service:
+            path_override: "/auth/api/forward?perm=myapp:reports&max_age=5min"
+
+  - match:
+      prefix: "/"
+    route:
+      cluster: app_backend
+    typed_per_filter_config:
+      envoy.filters.http.ext_authz:
+        "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
+        check_settings:
+          http_service:
+            path_override: "/auth/api/forward?perm=myapp:login"
+```
+
+See [perm argument](../api/perm.md) and [max_age argument](../api/max-age.md) for query parameter syntax.
+
+## WebSocket support for `/auth/`
+
+If you use a dedicated authentication host (the domain'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
+
+For routes where anonymous visitors are allowed but logged-in users should still be identified, add `public=1` to `path_override` (globally or per route):
+
+```yaml
+path_override: "/auth/api/forward?public=1"
+path_override: "/auth/api/forward?public=1&perm=myapp:reports"
+```
+
+The auth check then always returns 204 (except reauth with `max_age`, which still returns the 401 auth flow), and the `Remote-Public` header — matched by the `prefix: Remote-` rule in `allowed_upstream_headers` — marks each request as `anonymous`, `forbidden` or `authenticated`. The backend always runs and must check `Remote-Public` before treating the request as authorized. See [public access](../api/forward.md#public-access) and [trusted headers](../Headers.md#public-access).
+
+## Notes
+
+- Envoy's `ext_authz` filter does not send the request body to the auth server by default. For Paskia this is fine.
+- If Paskia is running behind TLS, use `https://` in `server_uri.uri` and configure the cluster's transport socket.
+- The `failure_mode_allow: false` setting means that if Paskia cannot be reached, Envoy will reject the request. In testing you may prefer `true`, but use `false` in production so a failed auth service cannot accidentally allow traffic.

docs/proxy/haproxy.md

@@ -0,0 +1,126 @@
+# HAProxy Forward-Auth
+
+[`/auth/api/forward`](../api/forward.md) · [Proxy guides](index.md)
+
+HAProxy does not have a built-in forward-auth primitive, but the community [`haproxy-auth-request`](https://github.com/TimWolla/haproxy-auth-request) Lua script provides an `auth-intercept` action that works very similarly to Nginx's `auth_request`. It makes an internal HTTP request to Paskia and copies the response headers to the backend request.
+
+## Requirements
+
+- HAProxy 2.2 or newer (2.0+ may work but 2.2+ supports all features shown here).
+- Compiled with `USE_LUA=1`.
+- The [`haproxy-auth-request`](https://github.com/TimWolla/haproxy-auth-request) Lua script loaded.
+- The [`haproxy-lua-http`](https://github.com/haproxytech/haproxy-lua-http) dependency in the Lua path.
+
+## Overview
+
+```haproxy
+global
+    lua-load /usr/share/haproxy/auth-request.lua
+
+defaults
+    mode http
+    timeout connect 5s
+    timeout client 30s
+    timeout server 30s
+
+# Backend that runs the Paskia auth check.
+backend paskia_auth
+    server paskia 127.0.0.1:4401
+
+# Backend that runs the Paskia UI / WebSocket / API.
+backend paskia_ui
+    server paskia 127.0.0.1:4401
+
+# Your protected application.
+backend app_backend
+    server app 127.0.0.1:3000
+
+frontend app
+    bind *:80
+
+    # 1. Route /auth/ straight to Paskia, bypassing the auth check.
+    acl is_auth path_beg /auth/
+    use_backend paskia_ui if is_auth
+
+    # 2. Add the headers Paskia logs / expects. These are then copied to the
+    #    auth subrequest by auth-intercept.
+    http-request set-header X-Forwarded-Method %[method]
+    http-request set-header X-Forwarded-Uri %[url]
+
+    # 3. Run the auth check. The parameters are:
+    #    backend       path                                   method
+    #    req-headers   success-headers                        failure-headers
+    #
+    #    - req-headers:   headers copied from client to Paskia.
+    #    - success-headers: headers copied from Paskia response to backend request.
+    #    - failure-headers: headers copied from Paskia response to client response.
+    http-request lua.auth-intercept paskia_auth /auth/api/forward?perm=myapp:login GET Host,Cookie,Accept,X-Forwarded-Method,X-Forwarded-Uri Remote-* *
+
+    # 4. If the subrequest was not successful, deny the request.
+    http-request deny if ! { var(txn.auth_response_successful) -m bool }
+
+    default_backend app_backend
+```
+
+## What the configuration does
+
+1. **Route `/auth/` to Paskia** — users must be able to reach the login/profile UI without already being authenticated. HAProxy will proxy WebSocket upgrade headers automatically for this backend when the client requests them.
+2. **Set `X-Forwarded-Method` and `X-Forwarded-Uri`** — HAProxy adds these headers to the incoming request so the Lua script can copy them to the auth subrequest. `%[method]` returns the HTTP method and `%[url]` returns the path and query string.
+3. **`lua.auth-intercept`** — sends a `GET` request to `/auth/api/forward?perm=myapp:login` on the `paskia_auth` backend. It copies the listed request headers (including the dynamic ones we just set) to the auth subrequest.
+4. **On success (`2xx`)** — copies every response header matching `Remote-*` from Paskia to the backend request. This overrides any client-supplied `Remote-*` headers, so the backend can trust them.
+5. **On failure (`4xx`)** — copies all response headers (`*`) to the client response and uses Paskia's response body, so the browser gets the login HTML or the JSON auth URL.
+6. **Deny if auth failed** — the final `http-request deny` rule is a safety net. In practice, `auth-intercept` with `*` as the failure-headers already terminates the transaction with Paskia's response.
+
+## Backend definition for the auth subrequest
+
+The `paskia_auth` backend can be the same physical server as `paskia_ui`, but using a separate backend is convenient because the Lua script will use the first available server in the backend. The auth subrequest is a plain HTTP request, so no special WebSocket options are needed here.
+
+```haproxy
+backend paskia_auth
+    server paskia 127.0.0.1:4401
+```
+
+## Per-route permissions
+
+You can run different auth checks for different paths by using HAProxy ACLs. Place the more specific rules before the generic one:
+
+```haproxy
+frontend app
+    bind *:80
+
+    acl is_auth path_beg /auth/
+    use_backend paskia_ui if is_auth
+
+    acl is_reports path_beg /reports
+    http-request set-header X-Forwarded-Method %[method] if is_reports
+    http-request set-header X-Forwarded-Uri %[url] if is_reports
+    http-request lua.auth-intercept paskia_auth /auth/api/forward?perm=myapp:reports&max_age=5min GET Host,Cookie,Accept,X-Forwarded-Method,X-Forwarded-Uri Remote-* * if is_reports
+
+    http-request set-header X-Forwarded-Method %[method]
+    http-request set-header X-Forwarded-Uri %[url]
+    http-request lua.auth-intercept paskia_auth /auth/api/forward?perm=myapp:login GET Host,Cookie,Accept,X-Forwarded-Method,X-Forwarded-Uri Remote-* *
+
+    http-request deny if ! { var(txn.auth_response_successful) -m bool }
+    default_backend app_backend
+```
+
+See [perm argument](../api/perm.md) and [max_age argument](../api/max-age.md) for query parameter syntax.
+
+## Public access
+
+For routes where anonymous visitors are allowed but logged-in users should still be identified, add `public=1` to the auth subrequest path:
+
+```haproxy
+http-request lua.auth-intercept paskia_auth /auth/api/forward?public=1 GET Host,Cookie,Accept,X-Forwarded-Method,X-Forwarded-Uri Remote-* *
+# or with a permission the backend will check itself:
+http-request lua.auth-intercept paskia_auth /auth/api/forward?public=1&perm=myapp:reports GET Host,Cookie,Accept,X-Forwarded-Method,X-Forwarded-Uri Remote-* *
+```
+
+The `Remote-*` success-headers glob already copies the `Remote-Public` header that marks each request as `anonymous`, `forbidden` or `authenticated`. With `public=1` the backend always runs and must check `Remote-Public` before treating the request as authorized; only reauth (`max_age`) still returns the 401 auth flow, so the `http-request deny` safety net simply never triggers on public routes. See [public access](../api/forward.md#public-access) and [trusted headers](../Headers.md#public-access).
+
+## Notes
+
+- 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 (the domain's auth-host setting), route `auth.example.com` to the Paskia backend instead of exposing `/auth/` on every site.

docs/proxy/index.md

@@ -0,0 +1,48 @@
+# Forward-Auth Proxy Guides
+
+[`/auth/api/forward`](../api/forward.md) · [Trusted headers](../Headers.md)
+
+These guides show how to protect a backend application with Paskia using the forward-auth (also called "external authentication") mechanism. The reverse proxy asks Paskia whether a request is allowed before forwarding it to the protected service.
+
+For details about the endpoint the proxy calls, see [`/auth/api/forward`](../api/forward.md). For the headers your backend receives on successful requests, see [Trusted Headers](../Headers.md).
+
+## Available guides
+
+- [Caddy](caddy.md) — fully supported with ready-to-use snippets (`auth/setup` and `auth/require`).
+- [Nginx](nginx.md) — using the `auth_request` module.
+- [Traefik](traefik.md) — using the `ForwardAuth` middleware.
+- [Apache APISIX](apisix.md) — using the `forward-auth` plugin.
+- [Envoy](envoy.md) — using the `ext_authz` HTTP filter.
+- [HAProxy](haproxy.md) — using a Lua auth request.
+
+## Common requirements
+
+No matter which proxy you use, the auth subrequest must:
+
+1. Be sent to `GET /auth/api/forward` on the Paskia backend. By default Paskia listens on `localhost:4401`; set the `AUTH_UPSTREAM` environment variable in our Caddy snippets, or point your proxy at wherever Paskia is running.
+2. Include the query parameters Paskia needs for access control:
+   - `perm` — required permission scope, repeatable (e.g. `perm=myapp:login`). See [perm argument](../api/perm.md).
+   - `max_age` — how recently the user must have authenticated (e.g. `max_age=5min`). See [max_age argument](../api/max-age.md).
+   - `public=1` — optional; allow public access (anonymous visitors and users missing `perm` pass through, marked with a `Remote-Public` header instead of a 401/403). See [public access](../api/forward.md#public-access).
+3. Forward these request headers from the original client request:
+   - `Host` — the site the user is visiting.
+   - `Cookie` — the session cookie, normally `__Host-paskia`.
+   - `X-Forwarded-Method` — the original HTTP method (e.g. `GET`, `POST`).
+   - `X-Forwarded-Uri` — the original path and query string (e.g. `/reports?foo=bar`).
+   - `Accept` — decides whether a 401/403 response should be HTML (browser) or JSON (API/fetch).
+4. Strip hop-by-hop headers (`Connection`, `Upgrade`, `Transfer-Encoding`, `Keep-Alive`, `Proxy-Connection`, `TE`) from the auth subrequest. The auth check is a plain HTTP request and must not carry WebSocket/body framing headers.
+5. On a `204 No Content` response, copy the `Remote-*` response headers to the request that is forwarded to the protected backend. The headers are the whole point of the auth check. With `public=1`, also copy `Remote-Public` — it marks whether the request is `authenticated`, `forbidden` or `anonymous`, and the backend must check it.
+6. On a 401/403 response, send Paskia's response back to the client without contacting the protected backend. (With `public=1` these only occur for reauth requirements.)
+7. Also proxy the `/auth/` path prefix to Paskia so the login/profile UI, API endpoints, and WebSockets are reachable. Paskia's WebSocket endpoints need `Upgrade` and `Connection` headers passed through for that path.
+
+## Backend usage
+
+After the proxy forwards the request, your backend can read the trusted headers. For example, in Python/FastAPI:
+
+```python
+user_id = request.headers.get("Remote-User")
+org_id = request.headers.get("Remote-Org")
+permissions = request.headers.get("Remote-Groups", "").split(",")
+```
+
+Only trust headers that come from the proxy; never trust `Remote-*` headers that arrive directly from the internet. Your proxy configuration should strip any client-supplied `Remote-*` headers before the auth check.

docs/proxy/nginx.md

@@ -0,0 +1,143 @@
+# Nginx Forward-Auth
+
+[`/auth/api/forward`](../api/forward.md) · [Proxy guides](index.md)
+
+This guide uses the [Nginx `auth_request`](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) module to ask Paskia whether each request is allowed before proxying it to your backend.
+
+## Overview
+
+```nginx
+server {
+    listen 80;
+    server_name app.example.com;
+
+    # 1. Proxy /auth/ to Paskia (HTTP + WebSocket).
+    location /auth/ {
+        proxy_pass http://localhost:4401;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+    }
+
+    # 2. All other paths are protected.
+    location / {
+        auth_request /auth-internal;
+
+        # 3. Capture the Remote-* headers from the auth response and
+        #    pass them to the backend request.
+        auth_request_set $remote_user        $upstream_http_remote_user;
+        auth_request_set $remote_name        $upstream_http_remote_name;
+        auth_request_set $remote_groups      $upstream_http_remote_groups;
+        auth_request_set $remote_org         $upstream_http_remote_org;
+        auth_request_set $remote_org_name    $upstream_http_remote_org_name;
+        auth_request_set $remote_role        $upstream_http_remote_role;
+        auth_request_set $remote_role_name   $upstream_http_remote_role_name;
+        auth_request_set $remote_session_exp $upstream_http_remote_session_expires;
+        auth_request_set $remote_credential  $upstream_http_remote_credential;
+        auth_request_set $remote_public      $upstream_http_remote_public;
+
+        proxy_set_header Remote-User             $remote_user;
+        proxy_set_header Remote-Name             $remote_name;
+        proxy_set_header Remote-Groups           $remote_groups;
+        proxy_set_header Remote-Org              $remote_org;
+        proxy_set_header Remote-Org-Name         $remote_org_name;
+        proxy_set_header Remote-Role             $remote_role;
+        proxy_set_header Remote-Role-Name        $remote_role_name;
+        proxy_set_header Remote-Session-Expires  $remote_session_exp;
+        proxy_set_header Remote-Credential       $remote_credential;
+        proxy_set_header Remote-Public           $remote_public;
+
+        # 4. The proxy_set_header lines above override any client-supplied
+        #    Remote-* headers, so the backend receives only the values from
+        #    Paskia's auth response.
+
+        proxy_pass http://localhost:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+
+    # 5. Internal endpoint used by auth_request.
+    location = /auth-internal {
+        internal;
+        proxy_pass http://localhost:4401/auth/api/forward?perm=myapp:login;
+        proxy_http_version 1.1;
+        proxy_pass_request_body off;
+        proxy_set_header Content-Length "";
+        proxy_set_header X-Forwarded-Method $request_method;
+        proxy_set_header X-Forwarded-Uri $request_uri;
+        proxy_set_header Host $host;
+        proxy_set_header Cookie $http_cookie;
+        proxy_set_header Accept $http_accept;
+        # Drop hop-by-hop headers that must not reach the auth subrequest.
+        proxy_set_header Connection "";
+        proxy_set_header Upgrade "";
+        proxy_set_header Transfer-Encoding "";
+        proxy_set_header Keep-Alive "";
+        proxy_set_header Proxy-Connection "";
+        proxy_set_header TE "";
+    }
+}
+
+# WebSocket upgrade map.
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+```
+
+## What the configuration does
+
+1. **`/auth/`** is proxied straight to Paskia. The `Upgrade` and `Connection` headers are passed through so WebSocket endpoints such as `/auth/ws/authenticate` work.
+2. **`/`** is protected by `auth_request /auth-internal`. Nginx makes an internal subrequest to that location before proxying the original request to the app.
+3. **`auth_request_set`** captures each `Remote-*` header from the Paskia response. Nginx does not have wildcard capture, so every header must be listed explicitly. The captured values are then attached to the backend request with `proxy_set_header`.
+4. The `proxy_set_header` lines override any `Remote-*` headers the client might have sent, so the backend can trust the headers that come from Paskia.
+5. **`/auth-internal`** is the actual forward-auth call. It must:
+   - point to `/auth/api/forward`,
+   - not forward the request body (`proxy_pass_request_body off;`),
+   - pass `Host`, `Cookie`, `Accept`, `X-Forwarded-Method`, and `X-Forwarded-Uri`,
+   - strip hop-by-hop headers.
+
+## Adjusting requirements
+
+Change the query string on the `proxy_pass` line inside `/auth-internal` to require different permissions or recent authentication:
+
+```nginx
+proxy_pass http://localhost:4401/auth/api/forward?perm=myapp:login;
+proxy_pass http://localhost:4401/auth/api/forward?perm=myapp:admin&max_age=5min;
+proxy_pass http://localhost:4401/auth/api/forward?"";
+```
+
+The last form (`?""`) requires only authentication and no specific permission. See [perm argument](../api/perm.md) and [max_age argument](../api/max-age.md) for details.
+
+## Public paths
+
+To leave some paths unprotected (for example `/.well-known/` or `/static/`), add `location` blocks before the protected `location /` block:
+
+```nginx
+location /.well-known/ {
+    root /var/www;
+}
+
+location /static/ {
+    root /var/www;
+}
+```
+
+## Public access
+
+For routes where anonymous visitors are allowed but logged-in users should still be identified, add `public=1` to the auth subrequest URI inside `/auth-internal`:
+
+```nginx
+proxy_pass http://localhost:4401/auth/api/forward?public=1;
+proxy_pass http://localhost:4401/auth/api/forward?public=1&perm=myapp:reports;
+```
+
+The auth check then always returns 204 (except reauth with `max_age`, which still returns the 401 auth flow), and `Remote-Public` marks each request as `anonymous`, `forbidden` or `authenticated`. It is captured and forwarded by the `auth_request_set $remote_public` / `proxy_set_header Remote-Public` lines added in the overview above — the backend always runs and must check `Remote-Public` before treating the request as authorized. See [public access](../api/forward.md#public-access) and [trusted headers](../Headers.md#public-access).
+
+## Notes
+
+- Nginx `auth_request` always makes the auth subrequest with the same HTTP method as the original request, but the body is suppressed by the configuration above. Paskia uses the `X-Forwarded-Method` and `X-Forwarded-Uri` headers for logging.
+- The `auth_request_set` variables are empty when the auth request fails, so on 401/403 the backend is never contacted; Nginx returns Paskia's response directly.
+- For HTTPS, add `listen 443 ssl;` and your certificate configuration as usual.

docs/proxy/traefik.md

@@ -0,0 +1,138 @@
+# Traefik ForwardAuth
+
+[`/auth/api/forward`](../api/forward.md) · [Proxy guides](index.md)
+
+This guide uses Traefik's [ForwardAuth middleware](https://doc.traefik.io/traefik/reference/routing-configuration/http/middlewares/forwardauth/) to ask Paskia whether each request is allowed.
+
+## Overview
+
+A typical dynamic (YAML) configuration looks like this:
+
+```yaml
+http:
+  routers:
+    app:
+      rule: "Host(`app.example.com`)"
+      service: app-backend
+      middlewares:
+        - paskia-auth
+
+    # Route /auth/ straight to Paskia, bypassing the auth middleware.
+    auth:
+      rule: "Host(`app.example.com`) && PathPrefix(`/auth/`)"
+      service: paskia
+      middlewares: []
+
+  middlewares:
+    paskia-auth:
+      forwardAuth:
+        address: "http://localhost:4401/auth/api/forward?perm=myapp:login"
+        # Forward every Remote-* header from the auth response to the backend.
+        authResponseHeadersRegex: "^Remote-"
+        # Explicitly pass the headers Paskia needs. If left empty, all headers
+        # are forwarded; being explicit avoids accidentally leaking hop-by-hop
+        # headers to the auth server.
+        authRequestHeaders:
+          - Host
+          - Cookie
+          - Accept
+          - X-Forwarded-Method
+          - X-Forwarded-Uri
+          - X-Forwarded-Host
+          - X-Forwarded-Proto
+          - X-Forwarded-For
+
+  services:
+    app-backend:
+      loadBalancer:
+        servers:
+          - url: "http://localhost:3000"
+
+    paskia:
+      loadBalancer:
+        servers:
+          - url: "http://localhost:4401"
+```
+
+## What Traefik sends automatically
+
+Traefik's ForwardAuth middleware sends the auth request to the configured `address` and includes the following headers derived from the original request:
+
+| Header | Value |
+|---|---|
+| `X-Forwarded-Method` | Original HTTP method |
+| `X-Forwarded-Proto` | Original protocol (`http`/`https`) |
+| `X-Forwarded-Host` | Original host |
+| `X-Forwarded-Uri` | Original request URI (path and query) |
+| `X-Forwarded-For` | Client IP address |
+
+These are exactly the headers Paskia logs. You should still include them in `authRequestHeaders` if you set that list explicitly, to make sure they are not filtered out.
+
+## Response headers
+
+`authResponseHeadersRegex: "^Remote-"` tells Traefik to copy every response header starting with `Remote-` from Paskia's `204` response and add it to the request that is forwarded to your backend. It also strips any `Remote-*` headers that the client may have sent, so the backend can trust the values.
+
+For stricter control, you can list the headers explicitly instead of using the regex:
+
+```yaml
+authResponseHeaders:
+  - Remote-User
+  - Remote-Name
+  - Remote-Groups
+  - Remote-Org
+  - Remote-Org-Name
+  - Remote-Role
+  - Remote-Role-Name
+  - Remote-Session-Expires
+  - Remote-Credential
+  - Remote-Public
+```
+
+## Proxying `/auth/` to Paskia
+
+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 set the domain's auth host in the admin panel's Domains section.
+
+## Adjusting requirements
+
+Change the `address` query string to require different permissions or recent authentication:
+
+```yaml
+address: "http://localhost:4401/auth/api/forward?perm=myapp:login"
+address: "http://localhost:4401/auth/api/forward?perm=myapp:admin&max_age=5min"
+address: "http://localhost:4401/auth/api/forward"
+```
+
+The last form requires only authentication, no specific permission. See [perm argument](../api/perm.md) and [max_age argument](../api/max-age.md).
+
+## Docker labels example
+
+When using Traefik with Docker Compose, you can define the middleware with labels:
+
+```yaml
+labels:
+  - "traefik.enable=true"
+  - "traefik.http.routers.myapp.rule=Host(`app.example.com`)"
+  - "traefik.http.routers.myapp.middlewares=paskia-auth"
+  - "traefik.http.middlewares.paskia-auth.forwardauth.address=http://localhost:4401/auth/api/forward?perm=myapp:login"
+  - "traefik.http.middlewares.paskia-auth.forwardauth.authResponseHeadersRegex=^Remote-"
+  - "traefik.http.middlewares.paskia-auth.forwardauth.authRequestHeaders=Host,Cookie,Accept,X-Forwarded-Method,X-Forwarded-Uri"
+```
+
+## Public access
+
+For routes where anonymous visitors are allowed but logged-in users should still be identified, add `public=1` to the middleware `address`:
+
+```yaml
+address: "http://localhost:4401/auth/api/forward?public=1"
+address: "http://localhost:4401/auth/api/forward?public=1&perm=myapp:reports"
+```
+
+The auth check then always returns 204 (except reauth with `max_age`, which still returns the 401 auth flow), and the `Remote-Public` header — copied by `authResponseHeadersRegex: "^Remote-"` — marks each request as `anonymous`, `forbidden` or `authenticated`. The backend always runs and must check `Remote-Public` before treating the request as authorized. See [public access](../api/forward.md#public-access) and [trusted headers](../Headers.md#public-access).
+
+## Notes
+
+- By default ForwardAuth sends a request without the original body. If you need to forward the body for logging/validation, set `forwardBody: true` and a sensible `maxBodySize`, but for Paskia this is not required.
+- Paskia does not set cookies on the forward-auth response; it only returns `Remote-*` headers. Use the JavaScript helpers from the [paskia](https://www.npmjs.com/package/paskia) package for session renewal in the frontend.
+- For HTTPS, use `https://` in the `address` and configure TLS options (`tls.insecureSkipVerify: true` only for testing).

e2e/README.md

@@ -75,18 +75,22 @@ Runs tests with Playwright Inspector for step-by-step debugging.
 
 ```
 e2e/
-├── playwright.config.ts      # Playwright configuration
+├── playwright.config.js      # Playwright configuration
 ├── package.json
 ├── tsconfig.json
 ├── test-data/                # Test database (created at runtime)
-│   └── test.sqlite
+│   └── paskia.kantadb
 └── tests/
-    ├── global-setup.ts       # Creates fresh DB, captures reset token
+    ├── global-setup.ts       # Creates fresh DB (localhost + test.localhost domains), captures reset token
     ├── global-teardown.ts    # Cleanup
-    ├── passkey.spec.ts       # Main E2E tests
+    ├── 10-passkey.spec.ts    # Registration, authentication, session tests
+    ├── 20-api-auth.spec.ts   # API-mode iframe flows (401/403/reauth)
+    ├── 50-multidomain.spec.ts# Multi-domain dispatch, related origins, auth hosts, remote login
+    ├── 99-logout.spec.ts     # Logout (runs last)
     └── fixtures/
         ├── virtual-authenticator.ts  # Virtual authenticator setup
-        └── passkey-helpers.ts        # WebSocket helpers
+        ├── passkey-helpers.ts        # WebSocket helpers
+        └── remote-auth.ts            # Pairing-code remote auth helpers
 ```
 
 ## What's Tested
@@ -107,6 +111,13 @@ e2e/
 - Logout (`/auth/api/logout`)
 - Invalid/missing token rejection
 
+### Multi-Domain
+- Host-based domain dispatch (`localhost` vs `test.localhost`, 421 for unknown hosts)
+- Related Origin Requests well-known endpoint and admin domain API
+- Per-domain auth hosts (UI at the site root)
+- WebSocket cross-domain rules
+- Cross-domain remote login via pairing code
+
 ## How Virtual Authenticator Works
 
 The tests use Chrome DevTools Protocol (CDP) to create a virtual authenticator:
@@ -142,12 +153,12 @@ This creates an in-browser authenticator that:
 ## Limitations
 
 1. **Chromium only**: Virtual authenticator is a Chrome DevTools feature
-2. **No cross-origin**: Tests run on localhost; production-like origins need additional setup
+2. **Multi-domain via `*.localhost`**: Chrome resolves any `*.localhost` hostname to loopback, which the tests use for cross-domain scenarios; non-localhost domains are exercised only via explicit Host headers (Node-side requests)
 3. **Single user per run**: Bootstrap creates one admin user; additional users need admin API
 
 ## Debugging Tips
 
-1. **Check test database**: `e2e/test-data/test.sqlite` persists after tests
+1. **Check test database**: `e2e/test-data/paskia.kantadb` is removed during teardown; comment out the cleanup in `global-teardown.ts` to inspect it after a run
 2. **View server output**: Global setup echoes server bootstrap to console
 3. **Use trace viewer**: `npx playwright show-trace` on failure traces
 

e2e/tests/50-multidomain.spec.ts

@@ -0,0 +1,258 @@
+import { test, expect } from './fixtures/virtual-authenticator'
+import {
+  registerPasskey,
+  getSessionCookieName,
+  popDeviceToken,
+} from './fixtures/passkey-helpers'
+import {
+  startRemoteAuthRequest,
+  awaitRemoteAuthSession,
+  permitRemoteAuth,
+} from './fixtures/remote-auth'
+
+/**
+ * Multi-domain E2E tests.
+ *
+ * The server is bootstrapped with two domains: localhost (default) and
+ * test.localhost. Chrome resolves any *.localhost hostname to loopback, so
+ * both domains are reachable over real HTTP from the browser.
+ *
+ * Covers:
+ * - Host-based domain dispatch (settings, 421 for unknown hosts)
+ * - Related Origin Requests well-known endpoint + admin domain API,
+ *   including HTTP dispatch to a related hostname
+ * - Per-domain auth hosts: settings, UI at the site root, /auth/ redirect
+ * - WebSocket cross-domain rule: rejected unless the Host is the origin
+ *   domain's own auth host
+ * - Cross-domain remote login: a passkey registered on localhost permits a
+ *   session on test.localhost via pairing code
+ * - The profile enrollment prompt on a domain where the user has no passkey
+ */
+
+test.describe('Multi-domain E2E', () => {
+  test.describe.configure({ mode: 'serial' })
+
+  const baseUrl = process.env.BASE_URL || 'http://localhost:4404'
+  const domainUrl = 'http://test.localhost:4404'
+
+  test('dispatches domains by host header', async ({ page }) => {
+    // Browser navigation: Chrome maps *.localhost to loopback
+    const domainResp = await page.goto(`${domainUrl}/auth/api/settings`)
+    expect(domainResp?.status()).toBe(200)
+    const domainSettings = await domainResp?.json()
+    expect(domainSettings.rp_id).toBe('test.localhost')
+    expect(domainSettings.own_auth_host).toBeNull()
+    expect(domainSettings.auth_host).toBeNull()
+    expect(domainSettings.ui_base_path).toBe('/auth/')
+
+    const defaultResp = await page.goto(`${baseUrl}/auth/api/settings`)
+    expect(defaultResp?.status()).toBe(200)
+    const defaultSettings = await defaultResp?.json()
+    expect(defaultSettings.rp_id).toBe('localhost')
+    expect(defaultSettings.auth_host).toBeNull()
+    expect(defaultSettings.ui_base_path).toBe('/auth/')
+
+    // Unknown host is rejected with 421 Misdirected Request.
+    // page.request is Node-side, so target loopback with an explicit Host.
+    const unknownResp = await page.request.get(`${baseUrl}/auth/api/settings`, {
+      headers: { Host: 'unknown.example.org' },
+    })
+    expect(unknownResp.status()).toBe(421)
+  })
+
+  test('well-known webauthn endpoint reflects related origins', async ({ page }) => {
+    // No related origins configured initially → 404
+    const before = await page.request.get(`${baseUrl}/.well-known/webauthn`)
+    expect(before.status()).toBe(404)
+  })
+
+  test('master admin manages domains and related origins via API', async ({ page, virtualAuthenticator }) => {
+    // Fresh session via device token (domain writes require recent auth)
+    const deviceToken = popDeviceToken()
+    test.skip(!deviceToken, 'No device tokens available')
+    await page.goto('/auth/')
+    const reg = await registerPasskey(page, baseUrl, { resetToken: deviceToken })
+    expect(reg.session_token).toBeTruthy()
+
+    const headers = { Cookie: `${getSessionCookieName()}=${reg.session_token}` }
+
+    // List domains
+    const list = await page.request.get(`${baseUrl}/auth/api/admin/domains/`, { headers })
+    expect(list.ok()).toBeTruthy()
+    const domains = await list.json()
+    expect(domains.map((r: any) => r.rp_id).sort()).toEqual(['localhost', 'test.localhost'])
+    const localhostDomain = domains.find((r: any) => r.rp_id === 'localhost')
+    expect(localhostDomain.origins).toEqual({ '**.localhost': true })
+
+    // Add a related origin (unrelated domain) to the localhost domain —
+    // same origins table; classification is derived from the rp-id
+    const patch = await page.request.patch(`${baseUrl}/auth/api/admin/domains/localhost`, {
+      headers,
+      data: { rp_name: '', origins: { '**.localhost': true, 'app.example.com': true } },
+    })
+    expect(patch.ok()).toBeTruthy()
+
+    // The well-known endpoint now lists it
+    const wk = await page.request.get(`${baseUrl}/.well-known/webauthn`)
+    expect(wk.ok()).toBeTruthy()
+    const wkJson = await wk.json()
+    expect(wkJson.origins).toContain('https://app.example.com')
+
+    // The related hostname now dispatches to the listing domain (HTTP).
+    // page.request is Node-side, so target loopback with an explicit Host.
+    const relResp = await page.request.get(`${baseUrl}/auth/api/settings`, {
+      headers: { Host: 'app.example.com' },
+    })
+    expect(relResp.ok()).toBeTruthy()
+    expect((await relResp.json()).rp_id).toBe('localhost')
+
+    // Restore: back to the pristine seeded state for later tests
+    const restore = await page.request.patch(`${baseUrl}/auth/api/admin/domains/localhost`, {
+      headers,
+      data: { rp_name: '', origins: { '**.localhost': true } },
+    })
+    expect(restore.ok()).toBeTruthy()
+    const after = await page.request.get(`${baseUrl}/.well-known/webauthn`)
+    expect(after.status()).toBe(404)
+
+    // ...and the related hostname is unknown again
+    const relGone = await page.request.get(`${baseUrl}/auth/api/settings`, {
+      headers: { Host: 'app.example.com' },
+    })
+    expect(relGone.status()).toBe(421)
+  })
+
+  test('per-domain auth host serves the domain UI at its site root', async ({ page, virtualAuthenticator }) => {
+    // Fresh session via device token (domain writes require recent auth)
+    const deviceToken = popDeviceToken()
+    test.skip(!deviceToken, 'No device tokens available')
+    await page.goto('/auth/')
+    const reg = await registerPasskey(page, baseUrl, { resetToken: deviceToken })
+    expect(reg.session_token).toBeTruthy()
+
+    const headers = { Cookie: `${getSessionCookieName()}=${reg.session_token}` }
+    const authHost = 'auth.test.localhost:4404'
+
+    try {
+      // Mark an auth host on the test.localhost domain. Chrome resolves any
+      // *.localhost hostname to loopback, so the auth host is reachable.
+      const patch = await page.request.patch(`${baseUrl}/auth/api/admin/domains/test.localhost`, {
+        headers,
+        data: { rp_name: '', origins: { [`http://${authHost}`]: { auth_host: true }, '**.test.localhost': true } },
+      })
+      expect(patch.ok()).toBeTruthy()
+
+      // The auth host dispatches to its domain and reports itself in settings
+      const settingsResp = await page.goto(`http://${authHost}/auth/api/settings`)
+      expect(settingsResp?.status()).toBe(200)
+      const settings = await settingsResp?.json()
+      expect(settings.rp_id).toBe('test.localhost')
+      expect(settings.auth_host).toBe(authHost)
+      expect(settings.own_auth_host).toBe(authHost)
+      expect(settings.ui_base_path).toBe('/')
+
+      // The UI lives at the site root on the auth host
+      const rootResp = await page.goto(`http://${authHost}/`)
+      expect(rootResp?.status()).toBe(200)
+      expect(rootResp?.headers()['content-type']).toContain('text/html')
+
+      // /auth/ on the auth host redirects to the root
+      const redir = await page.request.get(`${baseUrl}/auth/`, {
+        headers: { Host: authHost },
+        maxRedirects: 0,
+      })
+      expect(redir.status()).toBe(307)
+      expect(redir.headers()['location']).toMatch(/^http:\/\/auth\.test\.localhost(:\d+)?\/$/)
+    } finally {
+      // Restore: back to the pristine seeded state (later tests sign in on
+      // test.localhost, and an empty table would allow nothing)
+      const restore = await page.request.patch(`${baseUrl}/auth/api/admin/domains/test.localhost`, {
+        headers,
+        data: { rp_name: '', origins: { '**.test.localhost': true } },
+      })
+      expect(restore.ok()).toBeTruthy()
+    }
+
+    const after = await page.request.get(`${baseUrl}/auth/api/settings`, {
+      headers: { Host: 'test.localhost:4404' },
+    })
+    expect((await after.json()).auth_host).toBeNull()
+  })
+
+  test('WebSocket cross-domain connections require the origin domain\'s own auth host', async ({ page }) => {
+    await page.goto(`${domainUrl}/auth/`)
+
+    // Same-domain WebSocket receives authentication options...
+    const sameDomain: any = await page.evaluate(async () => {
+      return new Promise((resolve) => {
+        const ws = new WebSocket(`ws://${location.host}/auth/ws/authenticate`)
+        const timer = setTimeout(() => { ws.close(); resolve({ message: false }) }, 5000)
+        ws.onmessage = () => { clearTimeout(timer); ws.close(); resolve({ message: true }) }
+        ws.onerror = () => { clearTimeout(timer); resolve({ message: false }) }
+      })
+    })
+    expect(sameDomain.message).toBe(true)
+
+    // ...but a cross-domain connection is closed pre-accept: test.localhost
+    // has no auth host of its own, so no other host may serve its logins
+    const crossDomain: any = await page.evaluate(async (host) => {
+      return new Promise((resolve) => {
+        const ws = new WebSocket(`ws://${host}/auth/ws/authenticate`)
+        let message = false
+        const timer = setTimeout(() => { ws.close(); resolve({ message, code: -1 }) }, 5000)
+        ws.onmessage = () => { message = true }
+        ws.onclose = (event) => {
+          clearTimeout(timer)
+          resolve({ message, code: event.code, wasClean: event.wasClean })
+        }
+      })
+    }, new URL(baseUrl).host)
+    expect(crossDomain.message).toBe(false)
+    expect(crossDomain.wasClean).toBe(false)
+  })
+
+  test('cross-domain remote login via pairing code', async ({ page, virtualAuthenticator }) => {
+    // Register a fresh passkey on localhost (this test's virtual authenticator)
+    const deviceToken = popDeviceToken()
+    test.skip(!deviceToken, 'No device tokens available')
+    await page.goto('/auth/')
+    const reg = await registerPasskey(page, baseUrl, { resetToken: deviceToken })
+    expect(reg.session_token).toBeTruthy()
+
+    // Requester page on the other domain (no session there)
+    const reqPage = await page.context().newPage()
+    await reqPage.goto(`${domainUrl}/auth/`)
+
+    const pairingCode = await startRemoteAuthRequest(reqPage)
+    expect(pairingCode.split('.')).toHaveLength(3)
+
+    // Approver permits with the localhost passkey; the "found" message names
+    // the requesting domain
+    const found = await permitRemoteAuth(page, pairingCode)
+    expect(found.rp_id).toBe('test.localhost')
+
+    // The requester redeems the exchange code on its own domain and the
+    // session validates there for the same user
+    const validation = await awaitRemoteAuthSession(reqPage)
+    expect(validation.ctx.user.uuid).toBe(reg.user)
+
+    // The session is recorded with the requesting host
+    const userInfo = await reqPage.evaluate(async () => {
+      const resp = await fetch('/auth/api/user-info')
+      if (!resp.ok) throw new Error(`user-info failed: ${resp.status}`)
+      return resp.json()
+    })
+    const current = Object.values(userInfo.sessions as any[]).find((s: any) => s.is_current) as any
+    expect(current.host).toContain('test.localhost')
+
+    // The profile on test.localhost prompts adding a passkey for this domain,
+    // and the existing localhost passkey carries a domain badge
+    await reqPage.goto(`${domainUrl}/auth/`)
+    const notice = reqPage.locator('.domain-enroll-notice')
+    await expect(notice).toBeVisible({ timeout: 15000 })
+    await expect(notice).toContainText('test.localhost')
+    await expect(reqPage.locator('.badge-domain').first()).toHaveText('localhost')
+
+    await reqPage.close()
+  })
+})

e2e/tests/fixtures/remote-auth.ts

@@ -0,0 +1,187 @@
+import { type Page } from '@playwright/test'
+
+/**
+ * Remote authentication (pairing code) helpers for E2E tests.
+ * These drive the /auth/ws/remote-auth/* protocol directly in browser context,
+ * so requests carry the page origin's cookies and Chrome's host resolution.
+ */
+
+// PBKDF2-SHA512 PoW solver; must match frontend/src/utils/pow.js.
+// Passed as source into page.evaluate and instantiated with eval there.
+const solvePoWSource = `async (challengeBytes, work) => {
+  const baseKey = await crypto.subtle.importKey('raw', challengeBytes, 'PBKDF2', false, ['deriveBits'])
+  const solution = new Uint8Array(8 * work)
+  const nonce = new Uint32Array(2)
+  const mask = 0x7FF
+  for (let i = 0; i < work; i++) {
+    let result
+    do {
+      if (++nonce[0] === 0x100000000) ++nonce[1]
+      result = new Uint32Array(await crypto.subtle.deriveBits(
+        { name: 'PBKDF2', salt: nonce, iterations: 128, hash: 'SHA-512' }, baseKey, 32))
+    } while (result[0] & mask)
+    solution.set(new Uint8Array(nonce.buffer), i * 8)
+  }
+  return solution
+}`
+
+const b64helpersSource = `
+  const b64dec = (s) => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0))
+  const b64enc = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf))).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '')
+`
+
+/**
+ * Start a remote auth request on the given page (the device wanting to log in).
+ * The page must already be navigated to the requesting domain's origin.
+ * Keeps the WebSocket open on window.__raWs and collects later messages into
+ * window.__raMsgs; resolves with the pairing code.
+ */
+export async function startRemoteAuthRequest(page: Page): Promise<string> {
+  return page.evaluate(async ({ powSrc, b64src }) => {
+    const solvePoW = eval(`(${powSrc})`)
+    const { b64dec, b64enc } = eval(`(() => { ${b64src}; return { b64dec, b64enc } })()`)
+    const w = window as any
+    w.__raMsgs = []
+    return new Promise<string>((resolve, reject) => {
+      const ws = new WebSocket(`ws://${location.host}/auth/ws/remote-auth/request`)
+      w.__raWs = ws
+      ws.onmessage = async (event) => {
+        const data = JSON.parse(event.data)
+        w.__raMsgs.push(data)
+        if (typeof data.status === 'number' && data.status >= 400) {
+          ws.close()
+          reject(new Error(data.detail || `request failed: ${data.status}`))
+          return
+        }
+        if (data.pow && !data.pairing_code) {
+          const solution = await solvePoW(b64dec(data.pow.challenge), data.pow.work)
+          ws.send(JSON.stringify({ pow: b64enc(solution), action: 'login' }))
+          return
+        }
+        if (data.pairing_code) {
+          resolve(data.pairing_code)
+        }
+      }
+      ws.onerror = () => reject(new Error('WebSocket error during remote auth request'))
+      ws.onclose = (event) => {
+        if (!event.wasClean && event.code !== 1000) reject(new Error(`WebSocket closed unexpectedly: ${event.code}`))
+      }
+    })
+  }, { powSrc: solvePoWSource, b64src: b64helpersSource })
+}
+
+/**
+ * Wait for the remote auth request on the page to complete, redeem the
+ * exchange code via set-session, and return the /auth/api/validate response.
+ */
+export async function awaitRemoteAuthSession(page: Page, timeoutMs = 90000): Promise<any> {
+  return page.evaluate(async ({ timeoutMs }) => {
+    const w = window as any
+    const msgs: any[] = w.__raMsgs
+    if (!msgs) throw new Error('No remote auth request started on this page')
+    const exchangeCode: string = await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('Timed out waiting for remote auth completion')), timeoutMs)
+      const iv = setInterval(() => {
+        const done = msgs.find(m => m.status === 'authenticated' && m.exchange_code)
+        const failed = msgs.find(m => ['denied', 'expired', 'timeout', 'cancelled'].includes(m.status) || (typeof m.status === 'number' && m.status >= 400))
+        if (done) {
+          clearTimeout(timer); clearInterval(iv)
+          resolve(done.exchange_code)
+        } else if (failed) {
+          clearTimeout(timer); clearInterval(iv)
+          reject(new Error(failed.detail || `Remote auth ${failed.status}`))
+        }
+      }, 50)
+    })
+    const resp = await fetch('/auth/api/set-session', {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${exchangeCode}` },
+    })
+    if (!resp.ok) throw new Error(`set-session failed: ${resp.status}`)
+    const validate = await fetch('/auth/api/validate', { method: 'POST' })
+    if (!validate.ok) throw new Error(`validate failed: ${validate.status}`)
+    return await validate.json()
+  }, { timeoutMs })
+}
+
+/**
+ * Permit a remote auth request from the given page (the authenticating device).
+ * The page must be on the approver's origin with a valid session cookie and a
+ * virtual authenticator holding a credential for that domain.
+ * Resolves with the "found" message (includes the requesting domain's rp_id).
+ */
+export async function permitRemoteAuth(page: Page, code: string): Promise<any> {
+  return page.evaluate(async ({ code, powSrc, b64src }) => {
+    const solvePoW = eval(`(${powSrc})`)
+    const { b64dec, b64enc } = eval(`(() => { ${b64src}; return { b64dec, b64enc } })()`)
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(`ws://${location.host}/auth/ws/remote-auth/permit`)
+      let stage = 0
+      let foundMsg: any = null
+      ws.onmessage = async (event) => {
+        const data = JSON.parse(event.data)
+        try {
+          if (typeof data.status === 'number' && data.status >= 400) {
+            ws.close()
+            reject(new Error(data.detail || `permit failed: ${data.status}`))
+            return
+          }
+          if (data.pow && stage === 0) {
+            const solution = await solvePoW(b64dec(data.pow.challenge), data.pow.work)
+            stage = 1
+            ws.send(JSON.stringify({ code, pow: b64enc(solution) }))
+            return
+          }
+          if (data.status === 'found') {
+            foundMsg = data
+            const solution = await solvePoW(b64dec(data.pow.challenge), data.pow.work)
+            stage = 2
+            ws.send(JSON.stringify({ authenticate: true, pow: b64enc(solution) }))
+            return
+          }
+          if (data.optionsJSON) {
+            const opts = data.optionsJSON
+            const credential = await navigator.credentials.get({
+              publicKey: {
+                challenge: b64dec(opts.challenge),
+                rpId: opts.rpId,
+                timeout: opts.timeout,
+                userVerification: opts.userVerification,
+                allowCredentials: opts.allowCredentials?.map((cred: any) => ({
+                  type: cred.type,
+                  id: b64dec(cred.id),
+                  transports: cred.transports,
+                })) || [],
+              }
+            }) as PublicKeyCredential | null
+            if (!credential) throw new Error('Failed to get credential')
+            const response = credential.response as AuthenticatorAssertionResponse
+            ws.send(JSON.stringify({
+              id: credential.id,
+              rawId: b64enc(credential.rawId),
+              response: {
+                clientDataJSON: b64enc(response.clientDataJSON),
+                authenticatorData: b64enc(response.authenticatorData),
+                signature: b64enc(response.signature),
+                userHandle: response.userHandle ? b64enc(response.userHandle) : null,
+              },
+              type: credential.type,
+              clientExtensionResults: credential.getClientExtensionResults(),
+              authenticatorAttachment: (credential as any).authenticatorAttachment,
+            }))
+            return
+          }
+          if (data.status === 'success') {
+            ws.close()
+            resolve(foundMsg)
+            return
+          }
+        } catch (err: any) {
+          ws.close()
+          reject(new Error(err.message || 'Permit failed'))
+        }
+      }
+      ws.onerror = () => reject(new Error('WebSocket error during permit'))
+    })
+  }, { code, powSrc: solvePoWSource, b64src: b64helpersSource })
+}

e2e/tests/global-setup.ts

@@ -1,6 +1,6 @@
-import { execSync, spawn } from 'child_process'
+import { execFileSync, spawn, spawnSync } from 'child_process'
 import { join, dirname } from 'path'
-import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs'
 import { fileURLToPath } from 'url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -20,50 +20,81 @@ interface TestState {
 /**
  * Global setup for E2E tests.
  *
- * Uses in-memory SQLite database for fast, isolated tests.
+ * Bootstraps a fresh combined database (paskia.kantadb) with two domains —
- * Captures the bootstrap reset token for initial user registration.
+ * localhost (default) and test.localhost — then starts the server with the
+ * test data directory as its working directory. Captures the bootstrap reset
+ * token from 'paskia init' output for initial user registration.
  */
 export default async function globalSetup() {
   console.log('\n🔧 Setting up E2E test environment...\n')
 
-  // Create test data directory for state file
+  // Start from a clean slate: the test data directory doubles as the server
-  if (!existsSync(testDataDir)) {
+  // working directory, so paskia.kantadb and paskia.data/ are created here
+  rmSync(testDataDir, { recursive: true, force: true })
   mkdirSync(testDataDir, { recursive: true })
-  }
 
   // Build the package first
   console.log('  Building package with uv build...')
-  execSync('uv build', { cwd: projectRoot, stdio: 'inherit' })
+  execFileSync('uv', ['build'], { cwd: projectRoot, stdio: 'inherit' })
   console.log('  ✅ Build complete\n')
 
-  console.log('  Starting server with in-memory database...')
   if (COLLECT_COVERAGE) {
     console.log('  📊 Coverage collection enabled for Python backend')
   }
 
   const state: TestState = {}
 
-  // Build server command - with or without coverage
+  // Bootstrap the database: two domains, localhost and test.localhost
+  console.log('  Bootstrapping database with paskia init...')
+  const initResult = spawnSync(
+    'uv',
+    [
+      'run', '--project', projectRoot,
+      'paskia', 'init', '-l', 'localhost:4404', 'localhost',
+    ],
+    { cwd: testDataDir, encoding: 'utf-8' }
+  )
+  const initOutput = `${initResult.stdout}${initResult.stderr}`
+  process.stdout.write(initOutput)
+  if (initResult.status !== 0) {
+    throw new Error(`paskia init failed with exit code ${initResult.status}`)
+  }
+  const addResult = spawnSync(
+    'uv',
+    ['run', '--project', projectRoot, 'paskia', 'init', 'test.localhost'],
+    { cwd: testDataDir, encoding: 'utf-8' }
+  )
+  process.stdout.write(`${addResult.stdout}${addResult.stderr}`)
+  if (addResult.status !== 0) {
+    throw new Error(`paskia init test.localhost failed with exit code ${addResult.status}`)
+  }
+
+  // Parse the reset token from init output
+  // Format: http://localhost:4404/auth/{token} where token is dot-separated words
+  const match = initOutput.match(/https?:\/\/localhost(?::\d+)?\/auth\/([a-z]+(?:\.[a-z]+)+)/)
+  if (!match) {
+    throw new Error('Failed to capture reset token from paskia init output')
+  }
+  state.resetToken = match[1]
+  console.log(`\n  ✅ Captured reset token: ${state.resetToken}\n`)
+
+  // Start the server (serve mode: all configuration comes from the database)
+  console.log('  Starting server...')
   const serverArgs = COLLECT_COVERAGE
     ? [
-        'run', 'coverage', 'run', '--parallel-mode',
+        'run', '--project', projectRoot,
-        '-m', 'paskia', '-l', 'localhost:4404',
+        'coverage', 'run', '--parallel-mode',
-        '--rp-id', 'localhost'
+        '-m', 'paskia', '-l', 'localhost:4404'
       ]
     : [
-        'run', 'paskia', '-l', 'localhost:4404',
+        'run', '--project', projectRoot,
-        '--rp-id', 'localhost'
+        'paskia', '-l', 'localhost:4404'
       ]
 
-  // Use a fresh database file for tests
-  const testDbFile = join(testDataDir, 'test.paskiadb')
-
-  // Start the server using Node's spawn
   const serverProcess = spawn('uv', serverArgs, {
-    cwd: projectRoot,
+    cwd: testDataDir,
     env: {
       ...process.env,
-      PASKIA_DB: testDbFile,
       COVERAGE_FILE: join(projectRoot, '.coverage'),
     },
     stdio: ['ignore', 'pipe', 'pipe'],
@@ -71,66 +102,38 @@ export default async function globalSetup() {
 
   state.serverPid = serverProcess.pid
 
-  // Capture output to find reset token
+  serverProcess.stdout?.on('data', (data: Buffer) => process.stdout.write(data))
-  const resetTokenPromise = new Promise<string>((resolve, reject) => {
+  serverProcess.stderr?.on('data', (data: Buffer) => process.stderr.write(data))
-    const timeout = setTimeout(() => {
-      reject(new Error('Timed out waiting for server bootstrap (30s)'))
-    }, 30000)
-
-    let output = ''
-
-    const handleData = (data: Buffer) => {
-      const text = data.toString()
-      output += text
-      process.stdout.write(text) // Echo to console
-
-      // Look for the reset token URL in the output
-      // Format: https://localhost/auth/{token} or http://localhost:4404/auth/{token}
-      // where token is word.word.word.word.word (dot separated)
-      const match = output.match(/https?:\/\/localhost(?::\d+)?\/auth\/([a-z]+(?:\.[a-z]+)+)/)
-      if (match) {
-        clearTimeout(timeout)
-        // Wait a bit for server to fully start
-        setTimeout(() => resolve(match[1]), 1000)
-      }
-    }
-
-    serverProcess.stdout?.on('data', handleData)
-    serverProcess.stderr?.on('data', handleData)
-
-    serverProcess.on('error', (err) => {
-      clearTimeout(timeout)
-      reject(err)
-    })
 
   serverProcess.on('exit', (code) => {
     if (code !== 0 && code !== null) {
-        clearTimeout(timeout)
+      console.error(`Server exited unexpectedly with code ${code}`)
-        reject(new Error(`Server exited with code ${code}`))
     }
   })
-  })
 
-  try {
+  // Wait for the server to become ready and fetch the session cookie name
-    state.resetToken = await resetTokenPromise
+  console.log('  Waiting for server readiness...')
-    console.log(`\n  ✅ Captured reset token: ${state.resetToken}\n`)
+  const deadline = Date.now() + 30000
-  } catch (err) {
+  let settings: any = null
-    console.error('Failed to capture reset token:', err)
+  while (Date.now() < deadline) {
-    serverProcess.kill()
-    throw err
-  }
-
-  // Fetch session cookie name from server settings
     try {
       const response = await fetch('http://localhost:4404/auth/api/settings')
-    const settings = await response.json()
+      if (response.ok) {
-    state.sessionCookie = settings.session_cookie
+        settings = await response.json()
-    console.log(`  ✅ Session cookie name: ${state.sessionCookie}\n`)
+        break
-  } catch (err) {
-    console.error('Failed to fetch settings:', err)
-    serverProcess.kill()
-    throw err
       }
+    } catch {
+      // Not up yet
+    }
+    await new Promise(r => setTimeout(r, 250))
+  }
+  if (!settings) {
+    serverProcess.kill()
+    throw new Error('Server did not become ready in time (30s)')
+  }
+  state.sessionCookie = settings.session_cookie
+  console.log(`  ✅ Session cookie name: ${state.sessionCookie}`)
+  console.log(`  ✅ Domain: ${settings.rp_id} (${settings.rp_name})\n`)
 
   // Save state for tests
   writeFileSync(stateFile, JSON.stringify(state, null, 2))

e2e/tests/global-teardown.ts

@@ -59,11 +59,13 @@ export default async function globalTeardown() {
     rmSync(stateFile, { force: true })
   }
 
-  // Clean up test database
+  // Clean up test database and auxiliary data
-  const testDbFile = join(testDataDir, 'test.paskiadb')
+  for (const name of ['paskia.kantadb', 'paskia.data']) {
-  if (existsSync(testDbFile)) {
+    const p = join(testDataDir, name)
-    console.log('  Removing test database...')
+    if (existsSync(p)) {
-    rmSync(testDbFile)
+      console.log(`  Removing ${name}...`)
+      rmSync(p, { force: true, recursive: true })
+    }
   }
 
   // Generate Python coverage report if coverage was collected

examples/index.html

@@ -8,6 +8,17 @@
         :root {
             color-scheme: light dark;  /* Automatic themes by browser */
         }
+        .section a, .section button {
+            display: inline-block;
+            padding: 0.4em;
+            margin-right: 0.3em;
+            border: none;
+            background: #aaa2;
+            color: inherit;
+            font: inherit;
+            text-decoration: none;
+            cursor: pointer;
+        }
     </style>
 </head>
 <body>
@@ -20,13 +31,14 @@
         <div class="content">
             <div class="section">
                 <h2>Management Site</h2>
-                <button onclick="window.open('/auth/', '_blank')">👤 User Profile</button>
+                <a href="/auth/">👤 User Profile</a>
-                <button onclick="window.open('/auth/admin/', '_blank')">⚙️ Admin Panel</button>
+                <a href="/auth/admin/">⚙️ Admin Panel</a>
             </div>
 
             <div class="section">
                 <h2>API Mode (not leaving the page)</h2>
                 <p>For SPAs and fetch() calls - shows auth in an iframe overlay:</p>
+                <button onclick="profileDemo()">👤 Login/Profile</button>
                 <button onclick="apiCall('/auth/api/user-info', 'GET')">📋 Get User Info</button>
                 <button onclick="apiCall('/auth/api/forward?max_age=10s')">🔄 Reauth (max_age=10s)</button>
                 <button onclick="apiCall('/auth/api/forward?perm=auth:admin')">🛡️ Admin Only</button>
@@ -35,10 +47,10 @@
 
             <div class="section">
                 <h2>Browser Mode (full page)</h2>
-                <p>Block access to otherwise open site - intended for forward-auth mechanism (Caddy, Nginx):</p>
+                <p>Block access to otherwise open site - intended for forward-auth mechanism (Caddy, Nginx). If not authenticated, you'll see the login page; after auth, a 204 response (blank page = success). Back returns here:</p>
-                <button onclick="browserNav('/auth/api/forward')">🔐 Basic Auth</button>
+                <a href="/auth/api/forward">🔐 Basic Auth</a>
-                <button onclick="browserNav('/auth/api/forward?max_age=10s')">🔄 Reauth (max_age=10s)</button>
+                <a href="/auth/api/forward?max_age=10s">🔄 Reauth (max_age=10s)</a>
-                <button onclick="browserNav('/auth/api/forward?perm=auth:admin')">🛡️ Admin Only</button>
+                <a href="/auth/api/forward?perm=auth:admin">🛡️ Admin Only</a>
             </div>
 
             <pre id="output">Click a button to test...</pre>
@@ -46,52 +58,51 @@
     </div>
 
     <script type="module">
-        import { apiFetch, apiJson, AuthCancelledError } from '/paskia-js/dist/paskia.js'
+        import { apiFetch, apiJson, AuthCancelledError, profile } from '/paskia-js/dist/paskia.js'
-
-        const output = document.getElementById('output');
 
         function log(msg) {
-            output.textContent = msg;
+            console.log(msg)
+            document.getElementById('output').textContent = msg
         }
 
         // Make an API call using paskia module (handles 401/403 automatically)
         window.apiCall = async function(url, method = 'GET') {
-            log(`${method} ${url}...`);
+            log(`${method} ${url}...`)
             try {
-                const response = await apiFetch(url, { method });
+                const response = await apiFetch(url, { method })
 
                 // Forward endpoint returns 204 on success
                 if (response.status === 204) {
-                    log('✓ Success (204 No Content)');
+                    log('✓ Success (204 No Content)')
-                    return;
+                    return
                 }
 
                 if (!response.ok) {
-                    log(`Error: ${response.status} ${response.statusText}`);
+                    log(`Error: ${response.status} ${response.statusText}`)
-                    return;
+                    return
                 }
 
-                const data = await response.json();
+                const data = await response.json()
-                log('✓ Response:\n' + JSON.stringify(data, null, 2));
+                log('✓ Response:\n' + JSON.stringify(data, null, 2))
             } catch (e) {
                 if (e instanceof AuthCancelledError) {
-                    log('Authentication cancelled');
+                    log('Authentication cancelled')
                 } else {
-                    log(`Error: ${e.message}`);
+                    log(`Error: ${e.message}`)
                 }
             }
         }
 
         window.logout = async function() {
-            await fetch('/auth/api/logout', { method: 'POST' });
+            await fetch('/auth/api/logout', { method: 'POST' })
-            log('Logged out');
+            log('Logged out')
         }
 
-        // Browser mode: open the forward endpoint directly in a new window.
+        // Profile dialog: resolves 'login' / 'logout' / 'back'
-        window.browserNav = function(url) {
+        window.profileDemo = async function() {
-            log('Opening in new window...\nIf not authenticated, you\'ll see the login page.\nAfter auth, you\'ll see a 204 response (blank page = success).');
+            log(`Profile return: ${await profile()}`)
-            window.open(url, '_blank');
         }
+
     </script>
 </body>
 </html>

frontend/auth/App.vue

@@ -2,7 +2,14 @@
   <div class="app-shell">
     <StatusMessage />
     <main class="app-main">
-      <HostProfileView v-if="viewState === 'profile' && isHostMode" />
+      <HostProfileView
+        v-if="viewState === 'profile' && isHostMode"
+        :ctx="store.ctx"
+        :user-info="store.userInfo"
+        :settings="store.settings"
+        @back="goBack"
+        @logout="onHostLogout"
+      />
       <ProfileView v-else-if="viewState === 'profile'" />
       <LoadingView v-else-if="viewState === 'loading'" :message="loadingMessage" />
       <AccessDenied v-else-if="viewState === 'terminal'" />
@@ -13,8 +20,9 @@
 <script setup>
 import { computed, onMounted, onUnmounted, ref } from 'vue'
 import { useAuthStore } from '@/stores/auth'
-import { apiJson, SessionValidator } from 'paskia'
+import { apiJson, SessionValidator, settings as paskiaSettings } from 'paskia'
 import { updateThemeFromSession } from '@/utils/theme'
+import { goBack } from '@/utils/helpers'
 import StatusMessage from '@/components/StatusMessage.vue'
 import ProfileView from '@/components/ProfileView.vue'
 import HostProfileView from '@/components/HostProfileView.vue'
@@ -37,17 +45,23 @@ function normalizeHost(raw) {
 }
 
 /**
- * Host mode is active when an auth_host is configured AND the current host differs from it.
+ * Host mode is active when an own_auth_host is configured AND the current host differs from it.
  * In host mode, we show a limited profile view with logout and link to full profile.
  */
 const isHostMode = computed(() => {
-  const authHost = store.settings?.auth_host
+  const authHost = store.settings?.own_auth_host
   if (!authHost) return false
   const currentHost = normalizeHost(window.location.host)
   const configuredHost = normalizeHost(authHost)
   return currentHost !== configuredHost
 })
 
+// HostProfileView already posted /auth/api/logout; clear local state and reload.
+function onHostLogout() {
+  sessionStorage.clear()
+  window.location.reload()
+}
+
 function onSessionLost(e) {
   store.userInfo = null
   store.ctx = null
@@ -72,8 +86,8 @@ async function loadUserInfo() {
     // apiJson handles 401/403 with auth.iframe automatically:
     // shows overlay iframe, waits for auth, retries the request.
     const [validateData, userInfoData] = await Promise.all([
-      apiJson('/auth/api/validate', { method: 'POST' }),
+      apiJson('/auth/api/validate', { method: 'POST', timeout: paskiaSettings.auth_ms }),
-      apiJson('/auth/api/user-info', { method: 'GET' })
+      apiJson('/auth/api/user-info', { method: 'GET', timeout: paskiaSettings.auth_ms })
     ])
     store.userInfo = userInfoData
     store.ctx = validateData.ctx
@@ -99,7 +113,7 @@ onMounted(async () => {
   if (rpName) {
     // In host mode, show "account summary" style title
     // Settings are loaded but isHostMode depends on them, so check here
-    const authHost = store.settings?.auth_host
+    const authHost = store.settings?.own_auth_host
     const inHostMode = authHost && normalizeHost(window.location.host) !== normalizeHost(authHost)
     document.title = inHostMode ? `${rpName} · Account summary` : rpName
   }

frontend/auth/admin/AdminApp.vue

@@ -13,11 +13,11 @@ import AdminOidcDetail from '@/admin/AdminOidcDetail.vue'
 import AdminDialogs from '@/admin/AdminDialogs.vue'
 import { useAuthStore } from '@/stores/auth'
 import { adminUiPath, makeUiHref } from '@/utils/settings'
-import { apiJson, SessionValidator } from 'paskia'
+import { apiJson, SessionValidator, settings as paskiaSettings } from 'paskia'
 import { updateThemeFromSession } from '@/utils/theme'
 import { uuidv7 } from 'uuidv7'
 import { getDirection } from '@/utils/keynav'
-import { goBack } from '@/utils/helpers'
+import { originDisplayEntries } from '@/utils/helpers'
 
 const info = ref(null)
 const loading = ref(true)
@@ -28,6 +28,7 @@ const error = ref(null)
 const orgs = ref([])
 const permissions = ref([])
 const oidcClients = ref([])
+const domains = ref([])
 const currentOrgId = ref(null) // UUID of selected org for detail view
 const currentUserId = ref(null) // UUID for user detail view
 const currentOidcId = ref(null) // UUID for OIDC client detail view
@@ -174,6 +175,16 @@ async function loadAdminData() {
   oidcClients.value = Object.entries(data.oidc_clients).map(([uuid, c]) => ({ uuid, ...c }))
 }
 
+// Domain list is master-admin only; callers guard on isMasterAdmin
+async function loadDomains() {
+  try {
+    domains.value = await apiJson('/auth/api/admin/domains/')
+  } catch (e) {
+    console.warn('Unable to load domains', e)
+    domains.value = []
+  }
+}
+
 // Helper to get users for a role as sorted array of [uuid, user]
 function roleUsers(org, roleUuid) {
   return Object.entries(org.users)
@@ -196,7 +207,7 @@ function orgUserCount(org) {
 }
 
 async function loadUserInfo() {
-  const data = await apiJson('/auth/api/validate', { method: 'POST' })
+  const data = await apiJson('/auth/api/validate', { method: 'POST', timeout: paskiaSettings.auth_ms })
   info.value = data
   updateThemeFromSession(data.ctx)
   authenticated.value = true
@@ -207,6 +218,7 @@ function clearSensitiveState() {
   orgs.value = []
   permissions.value = []
   oidcClients.value = []
+  domains.value = []
   userDetail.value = null
   editingOidcClient.value = null
   authenticated.value = false
@@ -236,6 +248,7 @@ async function load() {
     await loadAdminData()
     // If we get here, user has admin access - now fetch user info for display
     await loadUserInfo()
+    if (isMasterAdmin.value) await loadDomains()
 
     if (!isMasterAdmin.value && isOrgAdmin.value && orgs.value.length === 1) {
       if (!window.location.hash || window.location.hash === '#overview') {
@@ -452,16 +465,50 @@ function resetOidcSecret(clientId) {
   if (editingOidcClient.value?.client_id === clientId) {
     editingOidcClient.value = { ...editingOidcClient.value, client_secret }
   }
-  // Also update dialog if open (for backwards compatibility)
-  if (dialog.value.type === 'oidc-edit' && dialog.value.data?.client_id === clientId) {
-    dialog.value.data.client_secret = client_secret
-  }
 }
 
 function createPermissionForClient(clientId) {
   openDialog('perm-create', { display_name: '', scope: '', domain: clientId })
 }
 
+function createDomain() {
+  openDialog('domain-edit', {
+    isNew: true,
+    rp_id: '',
+    rp_name: '',
+    auth_host: '',
+    origins: [],
+    originValidation: [],
+    wellKnownCheck: null,
+  })
+}
+
+function openDomain(domain) {
+  // One combined list for editing, in display order: in-domain sites and
+  // related origins, classified by hostname against the rp-id.
+  const rows = originDisplayEntries(domain)
+  openDialog('domain-edit', {
+    isNew: false,
+    rp_id: domain.rp_id,
+    rp_name: domain.rp_name || '',
+    auth_host: rows.find(r => r.auth)?.key || '',
+    origins: rows.map(r => r.key),
+    originValidation: rows.map(() => null),
+    wellKnownCheck: null,
+  })
+}
+
+function deleteDomain(domain) {
+  openDialog('confirm', {
+    message: `Delete domain "${domain.rp_id}"? This is refused while any passkeys remain registered for it.`,
+    action: async () => {
+      await apiJson(`/auth/api/admin/domains/${domain.rp_id}`, { method: 'DELETE' })
+      authStore.showMessage(`Domain "${domain.rp_id}" deleted.`, 'success', 2500)
+      await loadDomains()
+    }
+  })
+}
+
 function deleteOidcClient(client) {
   openDialog('confirm', {
     message: `Delete OIDC client "${client.name}"? This will break any applications using this client.`,
@@ -719,10 +766,7 @@ async function refreshUserDetail() {
   }
 }
 
-async function onUserNameSaved() {
+
-  await refreshUserDetail()
-  authStore.showMessage('User renamed', 'success', 1500)
-}
 
 async function submitDialog() {
   if (!dialog.value.type || dialog.value.busy) return
@@ -779,7 +823,7 @@ async function submitDialog() {
       apiJson(`/auth/api/admin/roles/${role.uuid}`, { method: 'PATCH', body: { display_name: name } })
         .then(() => {
           authStore.showMessage(`Role renamed to "${name}".`, 'success', 2500)
-          loadOrgs()
+          loadAdminData()
         })
         .catch(e => {
           authStore.showMessage(e.message || 'Failed to update role', 'error')
@@ -807,7 +851,7 @@ async function submitDialog() {
       apiJson(`/auth/api/admin/users/${user.uuid}/info`, { method: 'PATCH', body: { display_name: name } })
         .then(() => {
           authStore.showMessage(`User renamed to "${name}".`, 'success', 2500)
-          onUserNameSaved()
+          refreshUserDetail()
         })
         .catch(e => {
           authStore.showMessage(e.message || 'Failed to update user name', 'error')
@@ -861,29 +905,38 @@ async function submitDialog() {
           authStore.showMessage(e.message || 'Failed to create permission', 'error')
         })
       return // Don't call closeDialog() again
-    } else if (t === 'oidc-edit') {
+    } else if (t === 'domain-edit') {
-      const { client_id, client_secret, isNew } = dialog.value.data
+      const d = dialog.value.data
-      const name = dialog.value.data.name?.trim()
+      const rp_id = d.rp_id?.trim().toLowerCase()
-      const uris = dialog.value.data.redirect_uris?.trim()
+      if (!rp_id) throw new Error('Domain (rp-id) required')
-      if (!name) throw new Error('Client name required')
+      const rp_name = d.rp_name?.trim() || ''
+      const auth_host = d.auth_host?.trim().toLowerCase() || ''
+      // One origins object holds in-domain sites and related origins
+      // (ROR) together; the server classifies each key against the rp-id.
+      // Keys are stored lowercased, without the https:// scheme.
+      const keyOf = o => o.replace(/^https:\/\//i, '').replace(/\/+$/, '').toLowerCase()
+      const origins = {}
+      for (const o of d.origins || []) {
+        const key = keyOf(o.trim())
+        if (!key) continue
+        origins[key] = key === auth_host ? { auth_host: true } : true
+      }
 
-      const redirect_uris = uris ? uris.split('\n').map(u => u.trim()).filter(u => u) : []
-
-      // Close dialog immediately, then perform async operation
       closeDialog()
-
+      const req = d.isNew
-      const req = client_secret
+        ? apiJson('/auth/api/admin/domains/', { method: 'POST', body: { rp_id, rp_name, origins } })
-        ? sha256Hex(client_secret).then(secret_hash => isNew
+        : apiJson(`/auth/api/admin/domains/${rp_id}`, { method: 'PATCH', body: { rp_name, origins } })
-            ? apiJson('/auth/api/admin/oidc-clients', { method: 'POST', body: { client_id, secret_hash, name, redirect_uris } })
-            : apiJson(`/auth/api/admin/oidc-clients/${client_id}`, { method: 'PATCH', body: { name, redirect_uris, secret_hash } }))
-        : apiJson(`/auth/api/admin/oidc-clients/${client_id}`, { method: 'PATCH', body: { name, redirect_uris } })
       req
         .then(() => {
-          authStore.showMessage(`OIDC client "${name}" ${isNew ? 'created' : 'updated'}.`, 'success', 2500)
+          authStore.showMessage(`Domain "${rp_id}" ${d.isNew ? 'created' : 'updated'}.`, 'success', 2500)
-          loadAdminData()
+          loadDomains()
+          // Reload settings to reflect rp_name changes
+          authStore.loadSettings(true).then(() => {
+            if (authStore.settings?.rp_name) document.title = authStore.settings.rp_name + ' Admin'
+          })
         })
         .catch(e => {
-          authStore.showMessage(e.message || `Failed to ${isNew ? 'create' : 'update'} OIDC client`, 'error')
+          authStore.showMessage(e.message || 'Failed to save domain', 'error')
         })
       return // Don't call closeDialog() again
     } else if (t === 'confirm') {
@@ -938,6 +991,8 @@ async function submitDialog() {
                   :orgs="orgs"
                   :permissions="permissions"
                   :oidc-clients="oidcClients"
+                  :domains="domains"
+                  :current-rp-id="authStore.settings?.rp_id || ''"
                   :navigation-disabled="hasActiveModal"
                   :permission-summary="permissionSummary"
                   @create-org="createOrg"
@@ -951,6 +1006,9 @@ async function submitDialog() {
                   @create-oidc-client="createOidcClient"
                   @open-oidc-client="openOidcClient"
                   @delete-oidc-client="deleteOidcClient"
+                  @create-domain="createDomain"
+                  @open-domain="openDomain"
+                  @delete-domain="deleteDomain"
                   @navigate-out="handlePanelNavigateOut"
                 />
 
@@ -964,9 +1022,7 @@ async function submitDialog() {
                   :show-reg-modal="showRegModal"
                   :navigation-disabled="hasActiveModal"
                   @generate-user-registration-link="generateUserRegistrationLink"
-                  @go-overview="goOverview"
                   @open-org="openOrg"
-                  @on-user-name-saved="onUserNameSaved"
                   @refresh-user-detail="refreshUserDetail"
                   @edit-user-name="editUserName"
                   @close-reg-modal="showRegModal = false"
@@ -995,6 +1051,7 @@ async function submitDialog() {
                   ref="adminOidcDetailRef"
                   :client="editingOidcClient"
                   :permissions="permissions"
+                  :domains="domains"
                   :is-new="editingOidcClient.isNew"
                   :navigation-disabled="hasActiveModal"
                   @save="handleOidcSave"
@@ -1013,11 +1070,8 @@ async function submitDialog() {
     <AdminDialogs
       :dialog="dialog"
       :permission-id-pattern="PERMISSION_ID_PATTERN"
-      :settings="authStore.settings"
       @submit-dialog="submitDialog"
       @close-dialog="closeDialog"
-      @reset-oidc-secret="resetOidcSecret"
-      @create-permission-for-client="createPermissionForClient"
     />
   </div>
 </template>

frontend/auth/restricted/RestrictedApi.vue

@@ -1,5 +1,36 @@
 <template>
+  <template v-if="authMode === 'profile'">
+    <!--
+      Profile mode: render nothing until the session check completes (avoids
+      a load-time flash of the wrong view). Without a session, the login flow
+      runs in place of the profile; on success auth-success is posted and the
+      host resolves profile() with 'login'.
+    -->
     <RestrictedAuth
+      v-if="profileState === 'login'"
+      mode="login"
+      @authenticated="handleAuthenticated"
+      @back="handleBack"
+    />
+    <HostProfileView
+      v-else-if="profileState === 'ready'"
+      :ctx="profileCtx"
+      :user-info="profileInfo"
+      :settings="profileSettings"
+      @back="handleBack"
+      @logout="handleLogout"
+    />
+    <div v-else class="view-root profile-pending">
+      <div class="surface surface--tight">
+        <p class="view-lede">{{ profileState === 'error' ? 'Could not load your account.' : 'Loading your account…' }}</p>
+        <div class="button-row">
+          <button type="button" class="btn-secondary" @click="handleBack">Back</button>
+        </div>
+      </div>
+    </div>
+  </template>
+  <RestrictedAuth
+    v-else
     :mode="authMode"
     :remote-auth-token="remoteAuthToken"
     :oidc-query-string="oidcQueryString"
@@ -11,6 +42,10 @@
 <script setup>
 import { onMounted, ref } from 'vue'
 import RestrictedAuth from '@/components/RestrictedAuth.vue'
+import HostProfileView from '@/components/HostProfileView.vue'
+import { fetchJson, settings as paskiaSettings } from 'paskia'
+import { getSettings } from '@/utils/settings'
+import { updateThemeFromSession } from '@/utils/theme'
 
 // Check if this is a remote auth URL: /auth/{token}
 // The token is a 5-word passphrase like "word1.word2.word3.word4.word5"
@@ -45,8 +80,32 @@ let authMode
 if (window.location.pathname === '/auth/restricted/oidc') {
   authMode = 'oidc'
 } else {
-  // Both iframe and forward auth use hash params for mode (forbidden/login/reauth)
+  // Both iframe and forward auth use hash params for mode (forbidden/login/reauth/profile)
-  authMode = ['reauth', 'forbidden'].includes(hashParams.get('mode')) ? hashParams.get('mode') : 'login'
+  authMode = ['reauth', 'forbidden', 'profile'].includes(hashParams.get('mode')) ? hashParams.get('mode') : 'login'
+}
+
+// Profile mode state: 'loading' | 'login' | 'ready' | 'error'
+const profileState = ref('loading')
+const profileCtx = ref(null)
+const profileInfo = ref(null)
+const profileSettings = ref(null)
+
+async function loadProfile() {
+  try {
+    const [validateData, infoData, settingsData] = await Promise.all([
+      fetchJson('/auth/api/validate', { method: 'POST', timeout: paskiaSettings.auth_ms }),
+      fetchJson('/auth/api/user-info', { method: 'GET', timeout: paskiaSettings.auth_ms }),
+      getSettings()
+    ])
+    profileCtx.value = validateData.ctx
+    profileInfo.value = infoData
+    profileSettings.value = settingsData
+    updateThemeFromSession(validateData.ctx)
+    profileState.value = 'ready'
+  } catch (error) {
+    // No/expired session: run the login flow in place of the profile
+    profileState.value = error.status === 401 || error.status === 403 ? 'login' : 'error'
+  }
 }
 
 function postToParent(message) {
@@ -74,10 +133,18 @@ function handleBack() {
   })
 }
 
+function handleLogout() {
+  postToParent({
+    type: 'auth-logout'
+  })
+}
+
 onMounted(() => {
   // Check for remote auth token in URL
   remoteAuthToken.value = extractRemoteToken()
 
+  if (authMode === 'profile') loadProfile()
+
   postToParent({
     type: 'auth-ready'
   })
@@ -89,3 +156,15 @@ onMounted(() => {
   })
 })
 </script>
+
+<style scoped>
+.view-root.profile-pending { min-height: 100vh; align-items: center; justify-content: center; padding: 2rem 1rem; }
+.profile-pending .surface {
+  max-width: 520px;
+  margin: 0 auto;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 1.75rem;
+}
+</style>

frontend/auth/restricted/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <script>{let t=localStorage.getItem('paskia-theme');if(!t){let p=new URLSearchParams(location.hash.slice(1)).get('theme');if(p==='light'||p==='dark')t=p}(t==='dark'||t!=='light'&&matchMedia('(prefers-color-scheme:dark)').matches)&&document.documentElement.classList.add('dark');if(window.location.pathname==='/auth/restricted/iframe')document.documentElement.style.background='transparent'}</script>
+    <script>{let t=new URLSearchParams(location.hash.slice(1)).get('theme');if(t!=='light'&&t!=='dark')t=localStorage.getItem('paskia-theme');(t==='dark'||t!=='light'&&matchMedia('(prefers-color-scheme:dark)').matches)&&document.documentElement.classList.add('dark');if(window.location.pathname==='/auth/restricted/iframe')document.documentElement.style.background='transparent'}</script>
     <link rel="stylesheet" href="/src/assets/style.css">
   </head>
   <body>

frontend/int/reset/ResetApp.vue

@@ -59,7 +59,7 @@
 import { computed, onMounted, reactive, ref } from 'vue'
 import passkey from '@/utils/passkey'
 import { getSettings, uiBasePath } from '@/utils/settings'
-import { apiJson, ApiError, getUserFriendlyErrorMessage } from 'paskia'
+import { apiJson, ApiError, getUserFriendlyErrorMessage, settings as paskiaSettings } from 'paskia'
 import { updateThemeFromSession } from '@/utils/theme'
 
 const status = reactive({
@@ -164,7 +164,8 @@ async function exchangeCode(result) {
   }
   return await apiJson('/auth/api/set-session', {
     method: 'POST',
-    headers: { 'Authorization': `Bearer ${result.exchange_code}` }
+    headers: { 'Authorization': `Bearer ${result.exchange_code}` },
+    timeout: paskiaSettings.auth_ms,
   })
 }
 

frontend/src/admin/AdminDialogs.vue

@@ -1,144 +1,78 @@
 <script setup>
-import { computed } from 'vue'
+// Dispatcher: renders the dialog component matching dialog.type. Each
-import Modal from '@/components/Modal.vue'
+// dialog component carries its own title and content.
-import NameEditForm from '@/components/NameEditForm.vue'
+import OrgCreateDialog from './dialogs/OrgCreateDialog.vue'
-import { useAuthStore } from '@/stores/auth'
+import OrgUpdateDialog from './dialogs/OrgUpdateDialog.vue'
+import RoleCreateDialog from './dialogs/RoleCreateDialog.vue'
+import RoleUpdateDialog from './dialogs/RoleUpdateDialog.vue'
+import UserCreateDialog from './dialogs/UserCreateDialog.vue'
+import UserUpdateNameDialog from './dialogs/UserUpdateNameDialog.vue'
+import PermissionDialog from './dialogs/PermissionDialog.vue'
+import DomainEditDialog from './dialogs/DomainEditDialog.vue'
+import ConfirmDialog from './dialogs/ConfirmDialog.vue'
 
-const props = defineProps({
+defineProps({
   dialog: Object,
-  PERMISSION_ID_PATTERN: String,
+  PERMISSION_ID_PATTERN: String
-  settings: Object
 })
 
-const emit = defineEmits(['submitDialog', 'closeDialog', 'resetOidcSecret', 'createPermissionForClient'])
+defineEmits(['submitDialog', 'closeDialog'])
-
-const NAME_EDIT_TYPES = new Set(['org-update', 'role-update', 'user-update-name'])
-const NO_SUBMIT_TYPES = new Set([])
-const rpId = computed(() => props.settings?.rp_id || 'the configured domain')
-const discoveryUrl = computed(() => `${window.location.origin}/.well-known/openid-configuration`)
-
-// Copy-to-clipboard helper
-const authStore = useAuthStore()
-function copyText(value, label) {
-  navigator.clipboard.writeText(value).then(() => {
-    authStore.showMessage(`${label} copied to clipboard`, 'success', 1500)
-  })
-}
 </script>
 
 <template>
-  <Modal v-if="dialog.type" @close="$emit('closeDialog')">
+  <OrgCreateDialog
-      <h3 class="modal-title">
+    v-if="dialog.type === 'org-create'"
-        <template v-if="dialog.type==='org-create'">Create Organization</template>
+    :dialog="dialog"
-        <template v-else-if="dialog.type==='org-update'">Rename Organization</template>
+    @submit="$emit('submitDialog')"
-        <template v-else-if="dialog.type==='role-create'">Create Role</template>
+    @close="$emit('closeDialog')"
-        <template v-else-if="dialog.type==='role-update'">Edit Role</template>
+  />
-        <template v-else-if="dialog.type==='user-create'">Add User To Role</template>
+  <OrgUpdateDialog
-        <template v-else-if="dialog.type==='user-update-name'">Edit User Name</template>
+    v-else-if="dialog.type === 'org-update'"
-        <template v-else-if="dialog.type==='perm-create' || dialog.type==='perm-display'">{{ dialog.type === 'perm-create' ? 'Create Permission' : 'Edit Permission' }}</template>
+    :dialog="dialog"
-        <template v-else-if="dialog.type==='oidc-edit'">{{ dialog.data?.isNew ? 'New OIDC Client' : 'OIDC Client' }}</template>
+    @submit="$emit('submitDialog')"
-        <template v-else-if="dialog.type==='confirm'">Confirm</template>
+    @close="$emit('closeDialog')"
-      </h3>
+  />
-      <form @submit.prevent="$emit('submitDialog')" class="modal-form">
+  <RoleCreateDialog
-        <template v-if="dialog.type==='org-create'">
+    v-else-if="dialog.type === 'role-create'"
-          <label>Name
+    :dialog="dialog"
-            <input ref="nameInput" v-model="dialog.data.name" required />
+    @submit="$emit('submitDialog')"
-          </label>
+    @close="$emit('closeDialog')"
-        </template>
+  />
-        <template v-else-if="dialog.type==='org-update'">
+  <RoleUpdateDialog
-          <NameEditForm
+    v-else-if="dialog.type === 'role-update'"
-            label="Organization Name"
+    :dialog="dialog"
-            v-model="dialog.data.name"
+    @submit="$emit('submitDialog')"
-            :busy="dialog.busy"
+    @close="$emit('closeDialog')"
-            :error="dialog.error"
+  />
-            @cancel="$emit('closeDialog')"
+  <UserCreateDialog
+    v-else-if="dialog.type === 'user-create'"
+    :dialog="dialog"
+    @submit="$emit('submitDialog')"
+    @close="$emit('closeDialog')"
+  />
+  <UserUpdateNameDialog
+    v-else-if="dialog.type === 'user-update-name'"
+    :dialog="dialog"
+    @submit="$emit('submitDialog')"
+    @close="$emit('closeDialog')"
+  />
+  <PermissionDialog
+    v-else-if="dialog.type === 'perm-create' || dialog.type === 'perm-display'"
+    :dialog="dialog"
+    :permission-id-pattern="PERMISSION_ID_PATTERN"
+    @submit="$emit('submitDialog')"
+    @close="$emit('closeDialog')"
+  />
+  <DomainEditDialog
+    v-else-if="dialog.type === 'domain-edit'"
+    :dialog="dialog"
+    @submit="$emit('submitDialog')"
+    @close="$emit('closeDialog')"
+  />
+  <ConfirmDialog
+    v-else-if="dialog.type === 'confirm'"
+    :dialog="dialog"
+    @submit="$emit('submitDialog')"
+    @close="$emit('closeDialog')"
   />
 </template>
-        <template v-else-if="dialog.type==='role-create'">
-          <label>Role Name
-            <input v-model="dialog.data.name" placeholder="Role name" required />
-          </label>
-        </template>
-        <template v-else-if="dialog.type==='role-update'">
-          <NameEditForm
-            label="Role Name"
-            v-model="dialog.data.name"
-            :busy="dialog.busy"
-            :error="dialog.error"
-            @cancel="$emit('closeDialog')"
-          />
-        </template>
-        <template v-else-if="dialog.type==='user-create'">
-          <p class="small muted">Role: {{ dialog.data.role.display_name }}</p>
-          <label>Display Name
-            <input v-model="dialog.data.name" placeholder="User display name" required />
-          </label>
-        </template>
-        <template v-else-if="dialog.type==='user-update-name'">
-          <NameEditForm
-            label="Display Name"
-            v-model="dialog.data.name"
-            :busy="dialog.busy"
-            :error="dialog.error"
-            @cancel="$emit('closeDialog')"
-          />
-        </template>
-        <template v-else-if="dialog.type==='perm-create' || dialog.type==='perm-display'">
-          <label>Display Name
-            <input ref="displayNameInput" v-model="dialog.data.display_name" required />
-          </label>
-          <label>Permission Scope
-            <input v-model="dialog.data.scope" required :pattern="PERMISSION_ID_PATTERN" title="Allowed: A-Za-z0-9:._~-" data-form-type="other" />
-          </label>
-          <p class="small muted">E.g. yourapp:reports. Changing the scope name may break deployed applications.</p>
-          <label>Domain Scope
-            <input v-model="dialog.data.domain" data-form-type="other" />
-          </label>
-          <p class="small muted">A domain ({{ rpId }} or subdomain) restricts this permission to that host. An OIDC client UUID sends it as a <em>groups</em> claim to that client.</p>
-        </template>
-        <template v-else-if="dialog.type==='confirm'">
-          <p>{{ dialog.data.message }}</p>
-        </template>
-        <div v-if="dialog.error && !NAME_EDIT_TYPES.has(dialog.type)" class="error small">{{ dialog.error }}</div>
-        <div v-if="!NAME_EDIT_TYPES.has(dialog.type) && !NO_SUBMIT_TYPES.has(dialog.type)" class="modal-actions">
-          <button
-            type="button"
-            class="btn-secondary"
-            @click="$emit('closeDialog')"
-            :disabled="dialog.busy"
-          >
-            Cancel
-          </button>
-          <button
-            type="submit"
-            class="btn-primary"
-            :disabled="dialog.busy"
-          >
-            {{ dialog.type==='confirm' ? 'OK' : 'Save' }}
-          </button>
-        </div>
-        <div v-else-if="NO_SUBMIT_TYPES.has(dialog.type)" class="modal-actions">
-          <button
-            type="button"
-            class="btn-primary"
-            @click="$emit('closeDialog')"
-          >
-            Close
-          </button>
-        </div>
-      </form>
-  </Modal>
-</template>
-
-<style scoped>
-.optional { font-weight: normal; color: var(--color-text-muted); font-size: 0.85em; }
-.oidc-divider { border: none; border-top: 1px solid var(--color-border); margin: var(--space-sm) 0; }
-.oidc-dl { display: grid; grid-template-columns: auto 1fr; gap: 0.2rem 1rem; align-items: baseline; margin: 0; }
-.oidc-dl dt { font-size: 0.85rem; color: var(--color-text-muted); white-space: nowrap; }
-.oidc-dl dd { margin: 0; cursor: pointer; overflow: hidden; }
-.oidc-dl output { font-family: var(--font-mono, monospace); font-size: 0.85rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; display: block; }
-.oidc-reset-row { display: flex; align-items: center; gap: var(--space-sm); flex-wrap: wrap; }
-.oidc-groups { cursor: default; }
-.oidc-group { cursor: pointer; }
-.oidc-group output { white-space: normal; word-break: break-all; }
-</style>

frontend/src/admin/AdminOidcDetail.vue

@@ -6,6 +6,7 @@ import { useAuthStore } from '@/stores/auth'
 const props = defineProps({
   client: Object,
   permissions: Array,
+  domains: Array,
   isNew: { type: Boolean, default: false },
   navigationDisabled: { type: Boolean, default: false }
 })
@@ -29,7 +30,17 @@ const clientSecret = ref(null)
 
 // Computed
 const clientId = computed(() => props.client?.client_id || props.client?.uuid || '')
-const discoveryUrl = computed(() => authSitePath('/.well-known/openid-configuration'))
+// One discovery URL per domain (the OIDC provider is instance-global;
+// any configured host works — the RP must use its chosen one consistently)
+const discoveryUrls = computed(() => {
+  const origins = new Set()
+  for (const d of props.domains || []) {
+    const url = d.site_url && new URL(d.site_url)
+    if (url) origins.add(url.origin)
+  }
+  if (!origins.size) origins.add(new URL(authStore.settings.auth_site_url).origin)
+  return [...origins].sort().map(o => `${o}/.well-known/openid-configuration`)
+})
 const iconUrl = computed(() => authSitePath('/favicon.ico'))
 
 // Groups (permissions) scoped to this client
@@ -147,8 +158,14 @@ defineExpose({ focusFirstElement })
             <span v-else class="small muted">(only stored in hashed form)</span>
           </dd>
 
-          <dt>Auto Discovery URL</dt>
+          <dt class="discovery-dt">Auto Discovery URL
-          <dd><output @click="copyText(discoveryUrl, 'OpenID Connect Auto Discovery URL')" title="Click to copy">{{ discoveryUrl }}</output></dd>
+            <span v-if="discoveryUrls.length > 1" class="small muted">Any one — pick the site your users should log in on, and use it consistently.</span>
+          </dt>
+          <dd class="discovery-dd">
+            <span class="discovery-urls">
+              <output v-for="url in discoveryUrls" :key="url" @click="copyText(url, 'OpenID Connect Auto Discovery URL')" title="Click to copy">{{ url }}</output>
+            </span>
+          </dd>
 
           <dt>Icon URL</dt>
           <dd>
@@ -258,6 +275,29 @@ defineExpose({ focusFirstElement })
   min-width: 0;
 }
 
+.discovery-dt {
+  white-space: normal;
+  max-width: 20em;
+}
+
+.discovery-dt .small {
+  display: block;
+  font-weight: normal;
+}
+
+.discovery-dd {
+  flex-direction: column;
+  align-items: stretch;
+  gap: 0.25rem;
+}
+
+.discovery-urls {
+  display: flex;
+  flex-direction: column;
+  gap: 0.15rem;
+  min-width: 0;
+}
+
 .warning-text {
   display: block;
   font-size: 0.9rem;

frontend/src/admin/AdminOrgDetail.vue

@@ -1,6 +1,7 @@
 <script setup>
 import { computed, ref } from 'vue'
 import draggable from 'vuedraggable'
+import ProfilePicture from '@/components/ProfilePicture.vue'
 import { getDirection, navigateButtonRow, focusPreferred } from '@/utils/keynav'
 
 const props = defineProps({
@@ -36,14 +37,26 @@ const orgPermissions = computed(() => {
 })
 
 // Get users for a role as sorted array of { uuid, ...user }
+function getNormalizedName(name) {
+  let cleaned = name.replace(/\([^)]*\)/g, '').trim();
+  if (cleaned.includes(',')) {
+    return cleaned.toLowerCase();
+  } else {
+    const parts = cleaned.split(/\s+/);
+    const last = parts.pop();
+    const first = parts.join(' ');
+    return `${last}, ${first}`.toLowerCase();
+  }
+}
+
 function roleUsers(roleUuid) {
   return Object.entries(props.selectedOrg.users)
     .filter(([_, u]) => u.role === roleUuid)
     .map(([uuid, u]) => ({ uuid, ...u }))
     .sort((a, b) => {
-      const nameA = a.display_name.toLowerCase()
+      const normA = getNormalizedName(a.display_name);
-      const nameB = b.display_name.toLowerCase()
+      const normB = getNormalizedName(b.display_name);
-      return nameA.localeCompare(nameB)
+      return normA.localeCompare(normB);
     })
 }
 
@@ -59,10 +72,6 @@ function onUserChange(evt, targetRoleUuid) {
   }
 }
 
-function permissionDisplayName(scope) {
-  return props.permissions.find(p => p.scope === scope)?.display_name || scope
-}
-
 function toggleRolePermission(role, pid, checked) {
   emit('toggleRolePermission', role, pid, checked)
 }
@@ -388,8 +397,19 @@ defineExpose({ focusFirstElement })
                 @keydown.enter="$emit('openUser', u)"
                 :title="u.uuid"
               >
+                <ProfilePicture
+                  class="user-chip-picture"
+                  :src="u.avatar_url"
+                  :title="u.display_name"
+                  width="3.25rem"
+                  height="100%"
+                  radius="0"
+                  fallback-size="1.3rem"
+                />
+                <span class="user-chip-body">
                   <span class="name">{{ u.display_name }}</span>
-                <span class="meta">{{ u.last_seen ? new Date(u.last_seen).toLocaleDateString() : '—' }}</span>
+                  <span class="meta">{{ u.last_seen ? new Date(u.last_seen).toLocaleDateString(undefined, { month: 'short', day: 'numeric', year: 'numeric' }) : '—' }}</span>
+                </span>
               </li>
             </template>
           </draggable>
@@ -409,8 +429,8 @@ defineExpose({ focusFirstElement })
 .perm-matrix-grid .role-head { display: flex; align-items: flex-end; justify-content: center; }
 .perm-matrix-grid .role-head span { writing-mode: vertical-rl; transform: rotate(180deg); font-size: 0.65rem; }
 .perm-matrix-grid .add-role-head { cursor: pointer; }
-.roles-grid { display: flex; flex-wrap: wrap; gap: var(--space-lg); margin-top: var(--space-lg); justify-content: flex-start; align-items: stretch; }
+.roles-grid { display: flex; flex-wrap: wrap; gap: 0; margin-top: var(--space-lg); justify-content: flex-start; align-items: stretch; }
-.role-column { flex: 0 0 240px; border-radius: var(--radius-md); padding: var(--space-md); display: flex; flex-direction: column; }
+.role-column { flex: 0 0 17em; border-radius: var(--radius-md); padding: var(--space-md); display: flex; flex-direction: column; }
 .role-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: var(--space-md); }
 .role-name { display: flex; align-items: center; gap: var(--space-xs); font-size: 1.1rem; color: var(--color-heading); }
 .role-actions { display: flex; gap: var(--space-xs); }
@@ -418,9 +438,12 @@ defineExpose({ focusFirstElement })
 .plus-btn:hover { background: rgba(37, 99, 235, 0.18); }
 .user-list-wrapper { position: relative; flex: 1; display: flex; flex-direction: column; min-height: 5.5rem; }
 .user-list { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: var(--space-xs); flex: 1; }
-.user-chip { background: var(--color-accent-strong); color: white; border: none; border-radius: var(--radius-md); padding: 0.45rem 0.6rem; display: flex; justify-content: space-between; gap: var(--space-sm); cursor: grab; }
+.user-chip { background: var(--color-accent-strong); color: var(--color-accent-contrast); border: none; border-radius: var(--radius-md); padding: 0; display: grid; grid-template-columns: 3.25rem minmax(0, 1fr); align-items: stretch; gap: 0; cursor: grab; overflow: hidden; min-height: 3.25rem; }
 .user-chip:focus { outline: 2px solid var(--color-accent); outline-offset: 1px; }
-.user-chip .meta { font-size: 0.7rem; color: rgba(255, 255, 255, 0.8); }
+.user-chip-picture { align-self: stretch; }
+.user-chip-body { display: flex; min-width: 0; flex-direction: column; justify-content: center; gap: 0.1rem; padding: 0.45rem 0.6rem; }
+.user-chip .name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.user-chip .meta { font-size: 0.7rem; opacity: 0.85; }
 .user-chip.sortable-ghost { opacity: 0.5; }
 .user-chip.sortable-chosen { box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2); }
 .empty-role { position: absolute; inset: 0; border: 1px dashed var(--color-border-strong); border-radius: var(--radius-md); display: flex; align-items: center; justify-content: center; pointer-events: none; }

frontend/src/admin/AdminOverview.vue

@@ -1,28 +1,27 @@
 <script setup>
 import { computed, ref } from 'vue'
 import { getDirection, navigateButtonRow, focusPreferred, focusAtIndex } from '@/utils/keynav'
-import { formatDate } from '@/utils/helpers'
+import { formatDate, originDisplayEntries } from '@/utils/helpers'
 
 const props = defineProps({
   info: Object,
   orgs: Array,
   permissions: Array,
   oidcClients: Array,
+  domains: Array,
+  currentRpId: { type: String, default: '' },
   permissionSummary: Object,
   navigationDisabled: { type: Boolean, default: false }
 })
 
-const emit = defineEmits(['createOrg', 'openOrg', 'updateOrg', 'deleteOrg', 'toggleOrgPermission', 'openDialog', 'deletePermission', 'renamePermissionDisplay', 'createOidcClient', 'openOidcClient', 'deleteOidcClient', 'navigateOut'])
+const emit = defineEmits(['createOrg', 'openOrg', 'updateOrg', 'deleteOrg', 'toggleOrgPermission', 'openDialog', 'deletePermission', 'renamePermissionDisplay', 'createOidcClient', 'openOidcClient', 'deleteOidcClient', 'createDomain', 'openDomain', 'deleteDomain', 'navigateOut'])
 
 // Template refs for navigation
-const orgSection = ref(null)
 const orgActionsRef = ref(null)
 const orgTableRef = ref(null)
 const permMatrixRef = ref(null)
 const permActionsRef = ref(null)
 const permTableRef = ref(null)
-const oidcActionsRef = ref(null)
-const oidcTableRef = ref(null)
 
 const sortedOrgs = computed(() => [...props.orgs].sort((a,b)=> {
   const nameCompare = a.org.display_name.localeCompare(b.org.display_name)
@@ -40,6 +39,11 @@ function domainDisplay(domain) {
   return oidcClientNames.value[domain] || domain
 }
 
+// Domains display in alphabetical rp-id order.
+const sortedDomains = computed(() =>
+  [...(props.domains || [])].sort((a, b) => a.rp_id.localeCompare(b.rp_id))
+)
+
 // Map OIDC client UUIDs to their group permissions (sorted by scope)
 const clientGroups = computed(() => {
   const map = {}
@@ -62,10 +66,6 @@ const sortedPermissions = computed(() => [...props.permissions].sort((a,b)=> a.s
 const isMasterAdmin = computed(() => props.info?.ctx.permissions.includes('auth:admin'))
 const isOrgAdmin = computed(() => props.info?.ctx.permissions.includes('auth:org:admin'))
 
-function permissionDisplayName(scope) {
-  return props.permissions.find(p => p.scope === scope)?.display_name || scope
-}
-
 function getRoleNames(org) {
   // org.roles is dict[UUID, Role]
   return Object.values(org.roles)
@@ -431,6 +431,49 @@ defineExpose({ focusFirstElement })
       </tbody>
     </table>
   </div>
+
+  <div v-if="isMasterAdmin" class="domains-section">
+    <div class="section-header">
+      <h2>Domains</h2>
+      <p class="section-description">
+        The domain names (rp-ids) served, along with hosts belonging to them. Each domain has its own passkeys, and each host will only accept passkeys from its own domain. To let several <em>different</em> domain names share the same passkeys, open the domain and configure related domains (WebAuthn Related Origins). Alternatively create entirely separate domains, or combine the two modes. Each domain's own origins may use wildcards; related origins are individual hosts only, at most five per domain.
+      </p>
+      <p class="section-description">
+        Related origins are your choice when you wish to keep existing credentials working on a few alternative domains. Configure separate domains only when there is more separation, or a need for wildcard hosts. Note that users are shared and remote logins remain possible across domains.
+      </p>
+    </div>
+    <div>
+      <button @click="$emit('createDomain')">+ Add Domain</button>
+    </div>
+    <table class="org-table">
+      <thead>
+        <tr>
+          <th>Domain (rp-id)</th>
+          <th>Allowed Origins</th>
+          <th class="center"></th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr v-if="!domains || domains.length === 0">
+          <td colspan="3" class="center muted">No domains configured</td>
+        </tr>
+        <tr v-for="domain in sortedDomains" :key="domain.rp_id">
+          <td class="perm-name-cell">
+            <div class="perm-title">
+              <a :href="'#domain:' + domain.rp_id" @click.prevent="$emit('openDomain', domain)">{{ domain.rp_name || domain.rp_id }}</a>
+            </div>
+            <div class="perm-id-info">
+              <span class="id-text">{{ domain.rp_id }}</span>
+            </div>
+          </td>
+          <td class="domain-origins"><span v-for="(e, i) in originDisplayEntries(domain)" :key="e.key">{{ i ? ', ' : '' }}{{ e.key }}{{ e.auth ? '🔑' : '' }}{{ e.related ? '🔗' : '' }}</span></td>
+          <td class="center">
+            <button v-if="domain.rp_id !== currentRpId" @click="$emit('deleteDomain', domain)" class="icon-btn delete-icon" aria-label="Delete domain" title="Delete domain">❌</button>
+          </td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
 </template>
 
 <style scoped>
@@ -455,4 +498,10 @@ defineExpose({ focusFirstElement })
 .oidc-clients-section { margin-bottom: var(--space-xl); margin-top: var(--space-2xl); }
 .oidc-clients-section .section-header { display: flex; flex-direction: column; gap: 0.4rem; margin-bottom: var(--space-md); }
 .client-groups { font-size: 0.85rem; color: var(--color-text-muted); max-width: 200px; font-family: var(--font-mono, monospace); }
+
+/* Domains Section */
+.domains-section { margin-top: var(--space-2xl); }
+.domains-section .section-header { display: flex; flex-direction: column; gap: 0.4rem; margin-bottom: var(--space-md); }
+.domain-origins { font-family: var(--font-mono, monospace); font-size: 0.85rem; }
+.domains-section .perm-title { display: flex; align-items: center; gap: 0.5rem; }
 </style>

frontend/src/admin/AdminUserDetail.vue

@@ -2,6 +2,7 @@
 import { ref, computed } from 'vue'
 import UserBasicInfo from '@/components/UserBasicInfo.vue'
 import CredentialList from '@/components/CredentialList.vue'
+import ProfilePictureEditorModal from '@/components/ProfilePictureEditorModal.vue'
 import RegistrationLinkModal from '@/components/RegistrationLinkModal.vue'
 import SessionList from '@/components/SessionList.vue'
 import { useAuthStore } from '@/stores/auth'
@@ -17,12 +18,14 @@ const props = defineProps({
   navigationDisabled: { type: Boolean, default: false }
 })
 
-const emit = defineEmits(['generateUserRegistrationLink', 'goOverview', 'openOrg', 'onUserNameSaved', 'closeRegModal', 'editUserName', 'refreshUserDetail', 'navigateOut', 'deleteUser'])
+const emit = defineEmits(['generateUserRegistrationLink', 'openOrg', 'closeRegModal', 'editUserName', 'refreshUserDetail', 'navigateOut', 'deleteUser'])
 
 const authStore = useAuthStore()
 const terminatingSessions = ref({})
 const hoveredCredentialUuid = ref(null)
 const hoveredSession = ref(null)
+const showPictureDialog = ref(false)
+const avatarRenderVersion = ref(0)
 
 // Convert credentials dict to array with uuid attached as 'credential'
 const credentials = computed(() =>
@@ -48,15 +51,31 @@ function handleEditName() {
   emit('editUserName', props.selectedUser)
 }
 
+function openPictureDialog() {
+  if (!props.userDetail || props.userDetail.error) return
+  showPictureDialog.value = true
+}
+
+function closePictureDialog() {
+  showPictureDialog.value = false
+}
+
+function handlePictureUpdated() {
+  avatarRenderVersion.value += 1
+  emit('refreshUserDetail')
+}
+
 async function handleDelete(credential) {
   try {
     const data = await apiJson(`/auth/api/admin/users/${props.selectedUser.uuid}/credentials/${credential.credential}`, { method: 'DELETE' })
     if (data.status === 'ok') {
-      emit('onUserNameSaved') // Reuse to refresh user detail
+      emit('refreshUserDetail')
+      authStore.showMessage('Passkey removed', 'success', 2500)
     } else {
-      console.error('Failed to delete credential', data)
+      authStore.showMessage(data.detail || 'Failed to remove passkey', 'error')
     }
   } catch (err) {
+    authStore.showMessage(err.message || 'Failed to remove passkey', 'error')
     console.error('Delete credential error', err)
   }
 }
@@ -73,7 +92,7 @@ async function handleTerminateSession(session) {
         location.reload()
         return
       }
-      emit('refreshUserDetail') // Refresh without showing rename message
+      emit('refreshUserDetail')
       authStore.showMessage('Session terminated', 'success', 2500)
     } else {
       authStore.showMessage(data.detail || 'Failed to terminate session', 'error')
@@ -102,7 +121,7 @@ function handleUserInfoKeydown(event) {
   event.preventDefault()
 
   if (direction === 'left' || direction === 'right') {
-    navigateButtonRow(userInfoRef.value, event.target, direction, { itemSelector: '.mini-btn' })
+    navigateButtonRow(userInfoRef.value, event.target, direction, { itemSelector: '.user-picture-btn, .mini-btn' })
   } else if (direction === 'up') {
     emit('navigateOut', 'up')
   } else if (direction === 'down') {
@@ -124,7 +143,7 @@ function handleRegActionsKeydown(event) {
     navigateButtonRow(regActionsRef.value, event.target, direction, { itemSelector: 'button' })
   } else if (direction === 'up') {
     // Move to user info edit button
-    focusPreferred(userInfoRef.value, { itemSelector: '.mini-btn' })
+    focusPreferred(userInfoRef.value, { itemSelector: '.user-picture-btn, .mini-btn' })
   } else if (direction === 'down') {
     // Move to credential list
     credentialListRef.value?.$el?.focus()
@@ -174,10 +193,22 @@ function handleBackButtonKeydown(event) {
 
 // Focus helper for external navigation
 function focusFirstElement() {
-  focusPreferred(userInfoRef.value, { itemSelector: '.mini-btn' })
+  focusPreferred(userInfoRef.value, { itemSelector: '.user-picture-btn, .mini-btn' })
 }
 
 defineExpose({ focusFirstElement })
+
+const currentPictureEndpoint = computed(() => {
+  if (!props.selectedUser?.uuid) return null
+  return `/auth/api/user/${props.selectedUser.uuid}/profile.webp`
+})
+
+const adminPictureTitle = computed(() => {
+  const username = props.userDetail?.user?.preferred_username || props.selectedUser?.preferred_username
+  const displayName = props.userDetail?.user?.display_name || props.selectedUser?.display_name
+  const label = username || displayName || 'User'
+  return `Profile Picture for ${label}`
+})
 </script>
 
 <template>
@@ -186,6 +217,9 @@ defineExpose({ focusFirstElement })
       <UserBasicInfo
         v-if="userDetail && !userDetail.error"
         :name="userDetail.user.display_name || selectedUser.display_name"
+        :avatar-url="userDetail.user.avatar_url"
+        :avatar-render-version="avatarRenderVersion"
+        avatar-clickable
         :visits="userDetail.user.visits"
         :created-at="userDetail.user.created_at"
         :last-seen="userDetail.user.last_seen"
@@ -195,7 +229,7 @@ defineExpose({ focusFirstElement })
         :org-display-name="userDetail.org.display_name"
         :role-name="userDetail.role.display_name"
         :update-endpoint="`/auth/api/admin/users/${selectedUser.uuid}/info`"
-        @saved="$emit('onUserNameSaved')"
+        @avatar-click="openPictureDialog"
         @edit="handleEditName"
       >
         <div class="admin-actions">
@@ -254,10 +288,19 @@ defineExpose({ focusFirstElement })
     <RegistrationLinkModal
       v-if="showRegModal"
       :endpoint="`/auth/api/admin/users/${selectedUser.uuid}/create-link`"
-      :user-name="userDetail?.display_name || selectedUser.display_name"
+      :user-name="userDetail?.user?.display_name || selectedUser.display_name"
       @close="$emit('closeRegModal')"
       @copied="onLinkCopied"
     />
+    <ProfilePictureEditorModal
+      v-if="showPictureDialog && currentPictureEndpoint"
+      :endpoint="currentPictureEndpoint"
+      :picture-url="userDetail?.user?.avatar_url"
+      :render-version="avatarRenderVersion"
+      :title="adminPictureTitle"
+      @close="closePictureDialog"
+      @updated="handlePictureUpdated"
+    />
   </div>
 </template>
 

frontend/src/admin/dialogs/AdminDialog.vue

@@ -0,0 +1,51 @@
+<script setup>
+import Modal from '@/components/Modal.vue'
+
+// Shared frame for the admin dialogs: Modal wrapper, title, form with
+// error display and Cancel/Save actions. The dialog's fields go in the
+// default slot; optional extra content attached next to the modal panel
+// (e.g. the domain origins diagnostics) goes in the 'attached' slot.
+defineProps({
+  title: { type: String, required: true },
+  busy: Boolean,
+  error: { type: String, default: '' },
+  submitLabel: { type: String, default: 'Save' },
+  // Block submit (e.g. while domain-origin validation has hard errors)
+  submitDisabled: Boolean,
+  // Name-edit dialogs render their own error message and action buttons
+  // — the frame then only provides the title and the form element
+  bare: Boolean
+})
+
+defineEmits(['submit', 'close'])
+</script>
+
+<template>
+  <Modal @close="$emit('close')">
+    <template #attached>
+      <slot name="attached" />
+    </template>
+    <h3 class="modal-title">{{ title }}</h3>
+    <form @submit.prevent="$emit('submit')" class="modal-form">
+      <slot />
+      <div v-if="error && !bare" class="error small">{{ error }}</div>
+      <div v-if="!bare" class="modal-actions">
+        <button
+          type="button"
+          class="btn-secondary"
+          @click="$emit('close')"
+          :disabled="busy"
+        >
+          Cancel
+        </button>
+        <button
+          type="submit"
+          class="btn-primary"
+          :disabled="busy || submitDisabled"
+        >
+          {{ submitLabel }}
+        </button>
+      </div>
+    </form>
+  </Modal>
+</template>

frontend/src/admin/dialogs/ConfirmDialog.vue

@@ -0,0 +1,22 @@
+<script setup>
+import AdminDialog from './AdminDialog.vue'
+
+defineProps({
+  dialog: { type: Object, required: true }
+})
+
+defineEmits(['submit', 'close'])
+</script>
+
+<template>
+  <AdminDialog
+    title="Confirm"
+    submit-label="OK"
+    :busy="dialog.busy"
+    :error="dialog.error"
+    @submit="$emit('submit')"
+    @close="$emit('close')"
+  >
+    <p>{{ dialog.data.message }}</p>
+  </AdminDialog>
+</template>

frontend/src/admin/dialogs/DomainEditDialog.vue

@@ -0,0 +1,543 @@
+<script setup>
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import AdminDialog from './AdminDialog.vue'
+import { useAuthStore } from '@/stores/auth'
+import { compareOrigins } from '@/utils/helpers'
+
+const props = defineProps({
+  dialog: { type: Object, required: true }
+})
+
+defineEmits(['submit', 'close'])
+
+const title = computed(() =>
+  props.dialog.data?.isNew ? 'Add Domain' : `Edit Domain: ${props.dialog.data?.rp_id}`
+)
+
+// The rp-id of the domain being edited (lowercased: classification
+// compares against it, and hosts are case-insensitive)
+const dialogRpId = computed(() => (props.dialog.data?.rp_id || '').trim().toLowerCase())
+
+// Block submit on hard errors: malformed entries, an over-cap related
+// list (the server rejects the save), a save that would lock the admin
+// out of the domain they are using, or validation still in flight.
+// Connectivity and rp-id mismatch results are warnings only (entries may
+// be hosted elsewhere, or a new domain whose DNS is not routed to this
+// instance yet).
+const isValidationInvalid = computed(() => {
+  const d = props.dialog.data
+  const bad = v => v === 'invalid' || v === 'validating'
+  if (d.originValidation?.some(bad)) return true
+  if (relatedEntries.value.length > 5) return true
+  if (d.isNew && !isWellFormedDomain(d.rp_id || '')) return true
+  if (lockoutWarning.value) return true
+  return false
+})
+
+// A single origins list holds two kinds of entries: sites on the rp-id
+// domain form the in-domain sign-in allow-list; entries on other domain
+// names are related origins (WebAuthn ROR). Classification is automatic
+// from the hostname. A bare '*' or '**' is invalid (wildcards must sit
+// under the rp-id) and never a related origin.
+function isRelatedEntry(origin) {
+  if (isWildcardEntry(origin)) return false // wildcards are never related
+  const h = originHostname(origin)
+  return !!(h && dialogRpId.value && !isWithinDomain(origin, dialogRpId.value))
+}
+const relatedEntries = computed(() => {
+  const d = props.dialog.data
+  if (!d?.origins) return []
+  return d.origins.filter(isRelatedEntry)
+})
+
+// Well-known document browsers fetch from the rp-id domain to verify the
+// related-origin list (never from the auth host).
+const wellKnownUrl = computed(() => {
+  const host = (props.dialog.data?.rp_id || '').replace(/^https:\/\//, '').replace(/\/+$/, '')
+  return host ? `https://${host}/.well-known/webauthn` : ''
+})
+
+// ROR origins must be absolute https URLs in the well-known document.
+function asHttpsOrigin(origin) {
+  const o = origin.trim().replace(/\/+$/, '')
+  return o.startsWith('http') ? o : `https://${o}`
+}
+const wellKnownJson = computed(() =>
+  JSON.stringify({ origins: relatedEntries.value.map(asHttpsOrigin) })
+)
+
+// Copy-to-clipboard helper
+const authStore = useAuthStore()
+function copyText(value, label) {
+  navigator.clipboard.writeText(value).then(() => {
+    authStore.showMessage(`${label} copied to clipboard`, 'success', 1500)
+  })
+}
+
+// --- Lockout prevention (editing the domain in use) ---
+
+// When the admin edits the domain they are currently signed in on and no
+// auth host is marked (with one, ceremonies move there and saving is
+// always allowed), their current page origin must stay allowed to run
+// passkey ceremonies — otherwise saving locks them out. Mirrors the
+// backend check (Passkey.validate_origin): an in-domain origin matches a
+// row exactly (scheme+host+port) or a wildcard row — '**.base' covers
+// the apex and subdomains at any depth, '*.base' exactly one subdomain
+// level — over https, except under localhost (any scheme and port);
+// a related row matches only on exact equality (https://host).
+const lockoutWarning = computed(() => {
+  const d = props.dialog.data
+  if (d?.isNew || d?.auth_host) return null
+  const rpId = dialogRpId.value
+  if (!rpId || rpId !== authStore.settings?.rp_id) return null
+  return pageOriginAllowed(d.origins || [], rpId) ? null : window.location.host
+})
+
+// Whether any origin diagnostic is present
+const hasOriginDiagnostics = computed(() => {
+  const d = props.dialog.data
+  if (!d) return false
+  if (d.originValidation?.some(v => v === 'invalid' || v === 'unreachable' || v === 'mismatch')) return true
+  return relatedEntries.value.length > 5 || !!lockoutWarning.value
+})
+
+// Any runtime diagnostic to show in the dialog's attached feedback panel
+const hasDiagnostics = computed(
+  () => hasOriginDiagnostics.value || !!props.dialog.data?.wellKnownCheck
+)
+
+function pageOriginAllowed(rows, rpId) {
+  const toUrl = key => (isWildcardEntry(key) || key.includes('://')) ? key : 'https://' + key
+  const inDomain = []
+  const related = []
+  for (const row of rows) {
+    if (!originHostname(row)) continue
+    const key = entryKey(row).toLowerCase()
+    if (!key) continue
+    const bucket = isRelatedEntry(row) ? related : inDomain
+    bucket.push(toUrl(key))
+  }
+  const probe = origin => {
+    let hostname
+    try { hostname = new URL(origin).hostname } catch { return false }
+    if (hostname === rpId || hostname.endsWith('.' + rpId)) {
+      if (inDomain.includes(origin)) return true
+      return inDomain.some(e => {
+        const base = wildcardBase(e)
+        if (!base) return false
+        const matched = e.startsWith('**.')
+          ? hostname === base || hostname.endsWith('.' + base)
+          : hostname.endsWith('.' + base) && !hostname.slice(0, -base.length - 1).includes('.')
+        if (!matched) return false
+        // Under localhost a wildcard matches any scheme and port
+        return base === 'localhost' || base.endsWith('.localhost') || origin.startsWith('https://')
+      })
+    }
+    return related.includes(origin)
+  }
+  // The page scheme may be http (e.g. on localhost) — probe both
+  return probe(`https://${window.location.host}`) || probe(`http://${window.location.host}`)
+}
+
+const originInputs = ref([])
+
+async function addOrigin() {
+  const d = props.dialog.data
+  if (!d) return
+  d.origins.push('')
+  d.originValidation.push(null)
+  await nextTick()
+  originInputs.value[originInputs.value.length - 1]?.focus()
+}
+
+// Row validation runs after a short typing pause and immediately on
+// blur, so no error indication appears mid-edit. Empty rows are ignored.
+const originValidateTimers = new Map()
+
+function scheduleValidateOrigin(i) {
+  clearTimeout(originValidateTimers.get(i))
+  originValidateTimers.set(i, setTimeout(() => {
+    originValidateTimers.delete(i)
+    validateOrigin(i)
+  }, 600))
+}
+
+function onOriginBlur(i) {
+  clearTimeout(originValidateTimers.get(i))
+  originValidateTimers.delete(i)
+  validateOrigin(i)
+}
+
+function removeOrigin(i) {
+  const d = props.dialog.data
+  if (d) {
+    // Row indices shift on removal — drop all pending validations
+    for (const t of originValidateTimers.values()) clearTimeout(t)
+    originValidateTimers.clear()
+    d.origins.splice(i, 1)
+    d.originValidation.splice(i, 1)
+  }
+}
+
+function isWellFormedDomain(value) {
+  if (!value.trim()) return false
+  try {
+    const url = value.startsWith('http') ? new URL(value) : new URL('https://' + value)
+    // Any DNS label sequence (matching backend validate_rp_id): labels of
+    // 1-63 alnum/hyphen chars, no leading/trailing hyphen, dot-separated
+    return /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/i.test(url.hostname)
+  } catch {
+    return false
+  }
+}
+
+// Wildcard entries follow the shell-glob convention: '*.base' covers
+// exactly one subdomain level, '**.base' the apex and any depth.
+const isWildcardEntry = value => {
+  const v = value.trim()
+  return v.startsWith('*.') || v.startsWith('**.')
+}
+
+// Base domain of a wildcard entry (lowercased); null when the value is
+// not a wildcard pattern or has no base.
+function wildcardBase(value) {
+  const v = value.trim()
+  if (v.startsWith('**.')) return v.slice(3).replace(/\.+$/, '').toLowerCase() || null
+  if (v.startsWith('*.')) return v.slice(2).replace(/\.+$/, '').toLowerCase() || null
+  return null
+}
+
+function originHostname(origin) {
+  const v = origin.trim()
+  if (!v || v === '*' || v === '**') return null // a bare '*' or '**' is not a valid entry
+  if (isWildcardEntry(v)) {
+    const base = wildcardBase(v)
+    return base && isWellFormedDomain(base) ? base : null
+  }
+  try {
+    const url = v.startsWith('http') ? new URL(v) : new URL('https://' + v)
+    // The URL parser keeps malformed hostnames like '.localhost' or
+    // 'a..b.com' — reject anything that is not clean dot-separated labels
+    return url.hostname && isWellFormedDomain(url.hostname) ? url.hostname : null
+  } catch {
+    return null
+  }
+}
+
+function isWithinDomain(origin, rpId) {
+  const hostname = originHostname(origin)
+  if (!hostname) return false
+  return hostname === rpId || hostname.endsWith('.' + rpId)
+}
+
+async function validateOriginConnectivity(i) {
+  const d = props.dialog.data
+  if (!d) return
+  const value = d.origins[i]
+
+  d.originValidation[i] = 'validating'
+  try {
+    const cleanValue = value.replace(/\/+$/, '')
+    const testUrl = cleanValue.startsWith('http') ? cleanValue : 'https://' + cleanValue
+    const response = await fetch(testUrl + '/auth/api/settings', {
+      method: 'GET',
+      headers: { 'Accept': 'application/json' }
+    })
+    if (d.origins[i] !== value) return // entry changed while validating
+    if (response.ok) {
+      const data = await response.json()
+      // Valid when the entry is served by this instance for the edited domain
+      d.originValidation[i] = (data.rp_id && data.rp_id === dialogRpId.value) ? 'valid' : 'mismatch'
+    } else {
+      d.originValidation[i] = 'unreachable'
+    }
+  } catch (e) {
+    if (d.origins[i] === value) {
+      d.originValidation[i] = 'unreachable'
+    }
+  }
+}
+
+// A '*' typed into an empty field expands to '**.<rp-id>' with the second
+// asterisk selected: typing on (e.g. '.') replaces the selection —
+// yielding '*.<rp-id>' — while the rp-id stays at the end; Backspace
+// deletes the second asterisk; doing nothing keeps the any-depth form.
+// Only typed input into an empty field triggers this — never pasting or
+// deleting (e.g. backspacing '**' down to '*' must not re-expand).
+function onOriginInput(i, e) {
+  const d = props.dialog.data
+  if (!d) return
+  const el = e.target
+  const oldKey = entryKey(d.origins[i])
+  let value = el.value
+  if (value === '*' && dialogRpId.value && (e.inputType === 'insertText' || e.inputType === 'insertCompositionText')) {
+    value = '**.' + dialogRpId.value
+    el.value = value
+    el.setSelectionRange(1, 2)
+  }
+  d.origins[i] = value
+  // Keep the auth-host mark on a renamed entry, unless it no longer
+  // qualifies (wildcards and related origins cannot be the auth host)
+  if (d.auth_host && oldKey === d.auth_host) {
+    const key = entryKey(value)
+    d.auth_host = key && !key.startsWith('*') && !isRelatedEntry(value) ? key : ''
+  }
+  d.originValidation[i] = null
+  scheduleValidateOrigin(i)
+}
+
+function validateOrigin(i) {
+  const d = props.dialog.data
+  if (!d) return
+  const value = d.origins[i]
+  // Empty rows are ignored — never errors, and skipped on save
+  if (!value || !value.trim()) {
+    d.originValidation[i] = null
+    return
+  }
+  if (!originHostname(value)) {
+    d.originValidation[i] = 'invalid'
+    return
+  }
+  if (isWildcardEntry(value)) {
+    // Wildcards have no concrete site to probe, and are only allowed
+    // within the domain (related origins are individual hosts)
+    d.originValidation[i] = isWithinDomain(value, dialogRpId.value) ? null : 'invalid'
+    return
+  }
+  validateOriginConnectivity(i)
+}
+
+// Fetch the well-known document and check it lists every related origin.
+// Runs automatically whenever the related set changes; result is a
+// warning only, never a submit blocker (the rp-id site may be hosted
+// elsewhere, and cross-origin fetches can fail for unrelated reasons).
+async function testWellKnown() {
+  const d = props.dialog.data
+  if (!d) return
+  const related = relatedEntries.value.map(asHttpsOrigin)
+  if (!related.length) {
+    d.wellKnownCheck = null
+    return
+  }
+  const key = related.join('|')
+  d.wellKnownCheck = 'validating'
+  try {
+    const response = await fetch(wellKnownUrl.value, { headers: { 'Accept': 'application/json' } })
+    if (!response.ok) throw new Error('not ok')
+    const doc = await response.json()
+    if (related.join('|') !== key) return // list changed while fetching
+    const listed = new Set((doc.origins || []).map(o => String(o).replace(/\/+$/, '')))
+    const missing = related.filter(o => !listed.has(o))
+    d.wellKnownCheck = missing.length ? 'missing' : 'valid'
+    d.wellKnownMissing = missing
+  } catch {
+    if (related.join('|') === key) d.wellKnownCheck = 'unreachable'
+  }
+}
+watch(() => relatedEntries.value.map(asHttpsOrigin).join('|'), testWellKnown, { immediate: true })
+
+// Prefill a new domain's list with the real '**.<rp-id>' row once its
+// rp-id is known ('**.x' = the domain apex and all its subdomains over
+// https, any scheme and port under localhost). The row follows rp-id
+// edits while it is still the untouched prefilled row; once the admin
+// edits it, it is left alone. Seeding waits for a complete-looking rp-id
+// (letters after the final dot) so mid-typing states like 'something.'
+// don't prefill a broken '**.something'.
+function looksCompleteDomain(value) {
+  const host = (value || '').trim().replace(/\.$/, '')
+  return host === 'localhost' || /\.[a-z]{2,}$/i.test(host)
+}
+// Tracks the prefilled row so rp-id edits can keep updating it.
+let seededOrigin = null
+watch(dialogRpId, rp => {
+  const d = props.dialog.data
+  if (!d?.isNew) return
+  if (!looksCompleteDomain(rp) || !isWellFormedDomain(rp)) return
+  const seed = '**.' + rp.trim().replace(/\.$/, '')
+  if (!d.origins.length) {
+    d.origins.push(seed)
+    d.originValidation.push(null)
+    seededOrigin = seed
+  } else if (d.origins.length === 1 && d.origins[0] === seededOrigin && seed !== seededOrigin) {
+    d.origins[0] = seed
+    seededOrigin = seed
+  }
+})
+
+// --- Row menu: auth host assignment and entry removal ---
+
+const openMenu = ref(null)
+
+// Close the popup on any click outside it (the toggle button stops
+// propagation, so it never reaches this listener).
+function onDocumentClick(e) {
+  if (openMenu.value !== null && !e.target.closest('.row-menu')) openMenu.value = null
+}
+onMounted(() => document.addEventListener('click', onDocumentClick))
+onBeforeUnmount(() => {
+  document.removeEventListener('click', onDocumentClick)
+  for (const t of originValidateTimers.values()) clearTimeout(t)
+  originValidateTimers.clear()
+})
+
+// Origins-dict key form of an entry (https:// omitted), also used for the
+// auth_host value.
+function entryKey(value) {
+  return value?.trim().replace(/^https:\/\//, '').replace(/\/+$/, '') || ''
+}
+
+function isAuthHostEntry(origin) {
+  const d = props.dialog.data
+  const key = entryKey(origin)
+  return !!(key && d?.auth_host && key === d.auth_host)
+}
+
+function setAuthHost(i) {
+  const d = props.dialog.data
+  if (!d) return
+  let key = entryKey(d.origins[i])
+  let added = false
+  const wbase = wildcardBase(key)
+  if (wbase) {
+    // A wildcard cannot be the auth host — create a concrete auth.<base> entry
+    key = 'auth.' + wbase
+    if (!d.origins.some(o => entryKey(o) === key)) {
+      d.origins.push(key)
+      d.originValidation.push(null)
+      added = true
+    }
+  }
+  d.auth_host = key
+  openMenu.value = null
+  resortOrigins()
+  if (added) validateOrigin(d.origins.findIndex(o => entryKey(o) === key))
+}
+
+function clearAuthHost() {
+  const d = props.dialog.data
+  if (d) d.auth_host = ''
+  openMenu.value = null
+  resortOrigins()
+}
+
+// Display order, applied after row-menu actions (never while typing in an
+// input, to avoid focus loss): auth host first, then the rp-id, then
+// in-domain entries hierarchically, then related origins.
+function resortOrigins() {
+  const d = props.dialog.data
+  if (!d) return
+  const rank = o => isAuthHostEntry(o) ? 0 : o === dialogRpId.value ? 1 : isRelatedEntry(o) ? 3 : 2
+  const pairs = d.origins.map((o, i) => [o, d.originValidation[i]])
+  pairs.sort((a, b) => rank(a[0]) - rank(b[0]) || compareOrigins(a[0], b[0]))
+  d.origins = pairs.map(p => p[0])
+  d.originValidation = pairs.map(p => p[1])
+}
+
+function onRemoveOrigin(i) {
+  const d = props.dialog.data
+  if (!d) return
+  if (isAuthHostEntry(d.origins[i])) d.auth_host = ''
+  removeOrigin(i)
+  openMenu.value = null
+  resortOrigins()
+}
+</script>
+
+<template>
+  <AdminDialog
+    :title="title"
+    :busy="dialog.busy"
+    :error="dialog.error"
+    :submit-disabled="isValidationInvalid"
+    @submit="$emit('submit')"
+    @close="$emit('close')"
+  >
+    <template #attached>
+      <div v-if="relatedEntries.length || hasDiagnostics" class="attach-panel" @click.stop>
+        <template v-if="relatedEntries.length">
+          <p class="small muted">
+            Related origins are verified by browsers against
+            <a :href="wellKnownUrl" target="_blank" rel="noopener noreferrer">{{ wellKnownUrl }}</a>
+            — served automatically when this instance hosts {{ dialog.data.rp_id }}; otherwise publish this document there:
+          </p>
+          <pre class="wellknown-doc" title="Click to copy" tabindex="0" @click="copyText(wellKnownJson, 'Well-known document')" @keydown.enter.prevent="copyText(wellKnownJson, 'Well-known document')">{{ wellKnownJson }}</pre>
+        </template>
+        <ul v-if="hasDiagnostics" class="diag-list">
+          <li v-if="dialog.data.originValidation.some(v => v === 'invalid')" class="small error">Some entries are invalid — check for typos in the hostname; a bare '*' or '**' is not allowed, and wildcards only within the domain.</li>
+          <li v-if="dialog.data.originValidation.some(v => v === 'unreachable')" class="small">Some sites are unreachable — make sure they are routed to this instance.</li>
+          <li v-else-if="dialog.data.originValidation.some(v => v === 'mismatch')" class="small">Some sites are reachable but do not serve this domain.</li>
+          <li v-if="relatedEntries.length > 5" class="small error">At most 5 related origins are allowed ({{ relatedEntries.length }} listed) — the save is rejected.</li>
+          <li v-if="lockoutWarning" class="small error">Saving would lock you out: {{ lockoutWarning }} could no longer run sign-in ceremonies for this domain. Keep it listed, or mark an auth host.</li>
+          <li v-if="dialog.data.wellKnownCheck === 'validating'" class="small">Checking the published document…</li>
+          <li v-else-if="dialog.data.wellKnownCheck === 'valid'" class="small">✓ The published document lists all related origins.</li>
+          <li v-else-if="dialog.data.wellKnownCheck === 'missing'" class="small error">The published document does not list: {{ (dialog.data.wellKnownMissing || []).join(', ') }}</li>
+          <li v-else-if="dialog.data.wellKnownCheck === 'unreachable'" class="small">Could not fetch the published document to verify it.</li>
+        </ul>
+      </div>
+    </template>
+    <template v-if="dialog.data.isNew">
+      <label>Domain (rp-id)
+        <input v-model="dialog.data.rp_id" placeholder="example.com" data-form-type="other" required />
+      </label>
+      <p class="small muted">The domain name passkeys belong to — they work on this domain and its subdomains, and related domains. Cannot be changed later.</p>
+    </template>
+    <label>Display Name (rp-name)
+      <input v-model="dialog.data.rp_name" :placeholder="dialog.data.rp_id" />
+    </label>
+
+    <div class="origin-label">
+      Allowed Origins
+      <button type="button" class="icon-btn origin-add-btn" @click="addOrigin()" aria-label="Add origin" title="Add origin">➕</button>
+    </div>
+    <div v-if="dialog.data.origins.length" class="origin-list">
+      <div v-for="(_, i) in dialog.data.origins" :key="i" class="origin-row">
+        <input
+          ref="originInputs"
+          :value="dialog.data.origins[i]"
+          @input="e => onOriginInput(i, e)"
+          @blur="onOriginBlur(i)"
+          class="origin-input"
+          :class="{ 'input-error': dialog.data.originValidation[i] === 'invalid' }"
+        />
+        <span v-if="isAuthHostEntry(dialog.data.origins[i])" class="key-badge" title="Authentication site — the account and admin interface live here">🔑</span>
+        <span v-else-if="isRelatedEntry(dialog.data.origins[i])" class="key-badge" title="Related origin (WebAuthn ROR) — shares this domain's passkeys">🔗</span>
+        <div class="row-menu">
+          <button type="button" class="icon-btn" @click.stop="openMenu = openMenu === i ? null : i" aria-label="Origin actions" title="Actions">⋮</button>
+          <div v-if="openMenu === i" class="row-menu-popup">
+            <button v-if="isAuthHostEntry(dialog.data.origins[i])" type="button" @click="clearAuthHost()"><span class="menu-icon">🔑</span>Remove auth host</button>
+            <button v-else-if="!isRelatedEntry(dialog.data.origins[i]) && originHostname(dialog.data.origins[i])" type="button" @click="setAuthHost(i)"><span class="menu-icon">🔑</span>Set as auth host</button>
+            <button type="button" @click="onRemoveOrigin(i)"><span class="menu-icon delete-menu-icon">❌</span>Delete</button>
+          </div>
+        </div>
+      </div>
+    </div>
+    <p class="small muted">
+      Only the listed sites may sign in with {{ dialog.data.rp_id }} passkeys. Wildcards may be used: <strong>**.{{ dialog.data.rp_id }}</strong> allows the whole domain, <strong>*.{{ dialog.data.rp_id }}</strong> only a single subdomain level.<template v-if="relatedEntries.length"> 🔗 means related host requiring WebAuthn ROR setup.</template><template v-if="dialog.data.auth_host"> 🔑 is the dedicated Paskia host for all account management.</template>
+    </p>
+  </AdminDialog>
+</template>
+
+<style scoped>
+/* Domain origins */
+.origin-label { font-weight: 600; font-size: 0.95rem; margin-top: var(--space-sm); display: flex; align-items: center; gap: var(--space-sm); }
+.origin-list { display: flex; flex-direction: column; gap: 0.4rem; }
+.origin-row { display: flex; align-items: center; gap: var(--space-xs); }
+.origin-input { flex: 1; min-width: 8rem; font-family: var(--font-mono, monospace); }
+.origin-add-btn { font-size: 1.2rem; }
+.key-badge { flex-shrink: 0; }
+.row-menu { position: relative; flex-shrink: 0; }
+.row-menu-popup { position: absolute; right: 0; top: 100%; z-index: 10; display: flex; flex-direction: column; min-width: 9rem; background: var(--color-bg, #fff); border: 1px solid var(--color-border, #ccc); border-radius: 4px; box-shadow: 0 2px 8px rgba(0,0,0,0.15); }
+.row-menu-popup button { display: flex; align-items: center; justify-content: flex-start; gap: 0.45em; text-align: left; padding: var(--space-xs) var(--space-sm); background: none; border: none; cursor: pointer; white-space: nowrap; }
+.row-menu-popup button:hover:not(:disabled) { background: var(--color-bg-soft, rgba(127,127,127,0.12)); }
+.row-menu-popup button:disabled { opacity: 0.5; cursor: default; }
+.row-menu-popup .menu-icon { flex-shrink: 0; width: 1.1em; text-align: center; }
+.row-menu-popup .delete-menu-icon { filter: saturate(1.4); }
+
+.wellknown-doc { margin: 0; padding: var(--space-xs) var(--space-sm); font-size: 0.8rem; background: var(--color-bg-soft, rgba(127,127,127,0.08)); border-radius: 4px; white-space: pre; overflow: hidden; text-overflow: ellipsis; cursor: pointer; }
+
+.input-error {
+  border-color: var(--color-error);
+  background: var(--color-error-bg, rgba(239, 68, 68, 0.05));
+}
+</style>

frontend/src/admin/dialogs/OrgCreateDialog.vue

@@ -0,0 +1,23 @@
+<script setup>
+import AdminDialog from './AdminDialog.vue'
+
+defineProps({
+  dialog: { type: Object, required: true }
+})
+
+defineEmits(['submit', 'close'])
+</script>
+
+<template>
+  <AdminDialog
+    title="Create Organization"
+    :busy="dialog.busy"
+    :error="dialog.error"
+    @submit="$emit('submit')"
+    @close="$emit('close')"
+  >
+    <label>Name
+      <input v-model="dialog.data.name" required />
+    </label>
+  </AdminDialog>
+</template>

frontend/src/admin/dialogs/OrgUpdateDialog.vue

@@ -0,0 +1,28 @@
+<script setup>
+import AdminDialog from './AdminDialog.vue'
+import NameEditForm from '@/components/NameEditForm.vue'
+
+defineProps({
+  dialog: { type: Object, required: true }
+})
+
+defineEmits(['submit', 'close'])
+</script>
+
+<template>
+  <AdminDialog
+    title="Rename Organization"
+    :busy="dialog.busy"
+    bare
+    @submit="$emit('submit')"
+    @close="$emit('close')"
+  >
+    <NameEditForm
+      label="Organization Name"
+      v-model="dialog.data.name"
+      :busy="dialog.busy"
+      :error="dialog.error"
+      @cancel="$emit('close')"
+    />
+  </AdminDialog>
+</template>

frontend/src/admin/dialogs/PermissionDialog.vue

@@ -0,0 +1,37 @@
+<script setup>
+import { computed } from 'vue'
+import AdminDialog from './AdminDialog.vue'
+
+const props = defineProps({
+  dialog: { type: Object, required: true },
+  permissionIdPattern: { type: String, required: true }
+})
+
+defineEmits(['submit', 'close'])
+
+const title = computed(() =>
+  props.dialog.type === 'perm-create' ? 'Create Permission' : 'Edit Permission'
+)
+</script>
+
+<template>
+  <AdminDialog
+    :title="title"
+    :busy="dialog.busy"
+    :error="dialog.error"
+    @submit="$emit('submit')"
+    @close="$emit('close')"
+  >
+    <label>Display Name
+      <input v-model="dialog.data.display_name" required />
+    </label>
+    <label>Permission Scope
+      <input v-model="dialog.data.scope" required :pattern="permissionIdPattern" title="Allowed: A-Za-z0-9:._~-" data-form-type="other" />
+    </label>
+    <p class="small muted">E.g. yourapp:reports. Changing the scope name may break deployed applications.</p>
+    <label>Domain Scope
+      <input v-model="dialog.data.domain" data-form-type="other" />
+    </label>
+    <p class="small muted">A domain restricts this permission to that host (any configured domain's rp-id or a subdomain of it). An OIDC client UUID sends it as a <em>groups</em> claim to that client.</p>
+  </AdminDialog>
+</template>

frontend/src/admin/dialogs/RoleCreateDialog.vue

@@ -0,0 +1,23 @@
+<script setup>
+import AdminDialog from './AdminDialog.vue'
+
+defineProps({
+  dialog: { type: Object, required: true }
+})
+
+defineEmits(['submit', 'close'])
+</script>
+
+<template>
+  <AdminDialog
+    title="Create Role"
+    :busy="dialog.busy"
+    :error="dialog.error"
+    @submit="$emit('submit')"
+    @close="$emit('close')"
+  >
+    <label>Role Name
+      <input v-model="dialog.data.name" placeholder="Role name" required />
+    </label>
+  </AdminDialog>
+</template>

frontend/src/admin/dialogs/RoleUpdateDialog.vue

@@ -0,0 +1,28 @@
+<script setup>
+import AdminDialog from './AdminDialog.vue'
+import NameEditForm from '@/components/NameEditForm.vue'
+
+defineProps({
+  dialog: { type: Object, required: true }
+})
+
+defineEmits(['submit', 'close'])
+</script>
+
+<template>
+  <AdminDialog
+    title="Edit Role"
+    :busy="dialog.busy"
+    bare
+    @submit="$emit('submit')"
+    @close="$emit('close')"
+  >
+    <NameEditForm
+      label="Role Name"
+      v-model="dialog.data.name"
+      :busy="dialog.busy"
+      :error="dialog.error"
+      @cancel="$emit('close')"
+    />
+  </AdminDialog>
+</template>

frontend/src/admin/dialogs/UserCreateDialog.vue

@@ -0,0 +1,24 @@
+<script setup>
+import AdminDialog from './AdminDialog.vue'
+
+defineProps({
+  dialog: { type: Object, required: true }
+})
+
+defineEmits(['submit', 'close'])
+</script>
+
+<template>
+  <AdminDialog
+    title="Add User To Role"
+    :busy="dialog.busy"
+    :error="dialog.error"
+    @submit="$emit('submit')"
+    @close="$emit('close')"
+  >
+    <p class="small muted">Role: {{ dialog.data.role.display_name }}</p>
+    <label>Display Name
+      <input v-model="dialog.data.name" placeholder="User display name" required />
+    </label>
+  </AdminDialog>
+</template>

frontend/src/admin/dialogs/UserUpdateNameDialog.vue

@@ -0,0 +1,28 @@
+<script setup>
+import AdminDialog from './AdminDialog.vue'
+import NameEditForm from '@/components/NameEditForm.vue'
+
+defineProps({
+  dialog: { type: Object, required: true }
+})
+
+defineEmits(['submit', 'close'])
+</script>
+
+<template>
+  <AdminDialog
+    title="Edit User Name"
+    :busy="dialog.busy"
+    bare
+    @submit="$emit('submit')"
+    @close="$emit('close')"
+  >
+    <NameEditForm
+      label="Display Name"
+      v-model="dialog.data.name"
+      :busy="dialog.busy"
+      :error="dialog.error"
+      @cancel="$emit('close')"
+    />
+  </AdminDialog>
+</template>

frontend/src/assets/profile-generic.svg

@@ -0,0 +1,5 @@
+<?xml version="1.0"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="340" height="340">
+<path fill="#DDD" d="m169,.5a169,169 0 1,0 2,0zm0,86a76,76 0 1
+1-2,0zM57,287q27-35 67-35h92q40,0 67,35a164,164 0 0,1-226,0"/>
+</svg>

frontend/src/assets/style.css

@@ -9,8 +9,8 @@
   --font-sans: "Inter", "Inter var", "Segoe UI", system-ui, -apple-system, "Helvetica Neue", sans-serif;
   --font-mono: "DM Mono", "JetBrains Mono", "SFMono-Regular", Menlo, Monaco, Consolas, "Liberation Mono", monospace;
   --color-canvas: white;
-  --color-surface: white;
+  --color-surface: #def;
-  --color-surface-subtle: white;
+  --color-surface-subtle: #bcf;
   --color-surface-hover: oklab(0.97 -0.01 -0.02);
   --color-dialog: oklab(0.96 -0.01 -0.03);
   --color-border: oklab(0.82 -0.02 -0.06);
@@ -21,7 +21,7 @@
   --color-link: oklab(0.5 -0.06 -0.17);
   --color-link-hover: oklab(0.45 -0.06 -0.19);
   --color-accent: oklab(0.55 -0.06 -0.19);
-  --color-accent-strong: oklab(0.45 -0.06 -0.19);
+  --color-accent-strong: #46f;
   --color-accent-contrast: white;
   --color-secondary: oklab(0.55 -0.02 -0.05);
   --color-secondary-strong: oklab(0.45 -0.02 -0.05);
@@ -467,6 +467,61 @@ th {
   font-size: 0.9rem;
 }
 
+/* Runtime diagnostics list: 🔸 markers with a hanging indent, so wrapped
+   lines align with the text rather than under the marker */
+.diag-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.diag-list li {
+  position: relative;
+  padding-left: 1.4em;
+}
+
+.diag-list li + li {
+  margin-top: 0.3em;
+}
+
+.diag-list li::before {
+  content: "🔸";
+  position: absolute;
+  left: 0;
+}
+
+/* Dialog attachment panel (runtime diagnostics, related-origin setup):
+   docked on the right of the dialog, so appearing or disappearing never
+   shifts the dialog itself. On narrow screens it hangs below instead. */
+.attach-panel {
+  position: absolute;
+  top: calc(100% + 0.5rem);
+  left: 0;
+  right: 0;
+  background: var(--color-dialog);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-xl);
+  padding: var(--space-md) var(--space-lg);
+  max-height: 30vh;
+  overflow-y: auto;
+}
+
+.attach-panel > * + * {
+  margin-top: var(--space-md);
+}
+
+@media (min-width: 1200px) {
+  .attach-panel {
+    top: 0;
+    left: calc(100% + 0.75rem);
+    right: auto;
+    /* Never wider than the space right of the centered 500px dialog */
+    width: min(340px, calc(50vw - 286px));
+    max-height: calc(100vh - 3rem);
+  }
+}
+
 .icon-btn {
   background: none;
   border: none;
@@ -576,6 +631,12 @@ th {
   padding: 1.5rem;
 }
 
+/* Positions attachments (e.g. the diagnostics panel) relative to the
+   dialog; shrink-wraps the panel in the overlay's flex layout */
+.modal-wrap {
+  position: relative;
+}
+
 .device-dialog,
 .modal {
   background: var(--color-dialog);
@@ -804,6 +865,28 @@ th {
   border: 1px solid var(--color-border);
 }
 
+.badge-domain {
+  font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;
+  font-size: 0.75rem;
+}
+
+.domain-enroll-notice {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding: 0.75rem 1rem;
+  margin-bottom: 1rem;
+  border: 1px solid var(--color-accent);
+  border-radius: var(--radius-sm);
+  background: var(--color-surface-subtle);
+}
+
+.domain-enroll-notice p {
+  margin: 0;
+}
+
 
 .session-meta-info {
   font-size: 0.75rem;

frontend/src/components/CredentialList.vue

@@ -32,6 +32,7 @@
           </div>
           <h4 class="item-title">{{ getCredentialAuthName(credential) }}</h4>
           <div class="item-actions">
+            <span v-if="credential.rp_id && settings?.rp_id && credential.rp_id !== settings.rp_id" class="badge badge-domain" :title="`Passkey registered for ${credential.rp_id}`">{{ credential.rp_id }}</span>
             <span v-if="credential.is_current_session && !hoveredCredentialUuid && !hoveredSessionCredentialUuid" class="badge badge-current">Current</span>
             <span v-else-if="hoveredCredentialUuid === credential.credential" class="badge badge-current">Selected</span>
             <span v-else-if="hoveredSessionCredentialUuid === credential.credential" class="badge badge-current">Linked</span>
@@ -61,8 +62,13 @@
 </template>
 
 <script setup>
+import { onMounted, ref } from 'vue'
 import { formatDate } from '@/utils/helpers'
 import { navigateGrid, handleEscape, handleDeleteKey, getDirection } from '@/utils/keynav'
+import { getSettings } from '@/utils/settings'
+
+const settings = ref(null)
+onMounted(async () => { settings.value = await getSettings() })
 
 const props = defineProps({
   credentials: { type: Array, default: () => [] },

frontend/src/components/HostProfileView.vue

@@ -1,26 +1,30 @@
 <template>
-  <section class="view-root view-root--wide host-view" data-view="host-profile">
+  <div class="view-root host-profile" data-view="host-profile">
-    <header class="view-header">
+    <div class="surface surface--tight">
+      <!-- Heading/lede belong to the standalone page; in the dialog the host
+           page already provides the surrounding context. -->
+      <header v-if="!inIframe" class="view-header center">
         <h1>{{ headingTitle }}</h1>
         <p class="view-lede">{{ subheading }}</p>
       </header>
 
-    <section class="section-block" ref="userInfoSection">
+      <section class="section-block">
         <div class="section-body">
           <UserBasicInfo
-          v-if="ctx"
+            v-if="sessionCtx && info"
-          :name="ctx.user.display_name"
+            :name="sessionCtx.user.display_name"
-          :visits="authStore.userInfo.user.visits"
+            :avatar-url="info.user.avatar_url"
-          :created-at="authStore.userInfo.user.created_at"
+            :visits="info.user.visits"
-          :last-seen="authStore.userInfo.user.last_seen"
+            :created-at="info.user.created_at"
-          :email="ctx.user.email"
+            :last-seen="info.user.last_seen"
-          :telephone="ctx.user.telephone"
+            :email="sessionCtx.user.email"
+            :telephone="sessionCtx.user.telephone"
             :org-display-name="orgDisplayName"
             :role-name="roleDisplayName"
             :can-edit="false"
           />
           <p v-else class="empty-state">
-          {{ initializing ? 'Loading your account…' : 'No active session found.' }}
+            {{ loading ? 'Loading your account…' : 'No active session found.' }}
           </p>
         </div>
       </section>
@@ -31,61 +35,82 @@
             <button
               type="button"
               class="btn-secondary"
-            @click="goBack"
+              @click="$emit('back')"
             >
               Back
             </button>
             <button
+              v-if="sessionCtx"
               type="button"
               class="btn-danger"
-            :disabled="authStore.isLoading"
+              :disabled="busy"
               @click="logout"
             >
-            {{ authStore.isLoading ? 'Signing out…' : 'Logout' }}
+              {{ busy ? 'Signing out…' : 'Logout' }}
             </button>
             <button
-            v-if="authSiteUrl"
               type="button"
               class="btn-primary"
-            :disabled="authStore.isLoading"
+              :disabled="busy"
               @click="goToAuthSite"
             >
               Full Profile
             </button>
           </div>
-        <p class="note"><strong>Logout</strong> from {{ currentHost }}, or access your <strong>Full Profile</strong> at {{ authSiteHost }} (you may need to sign in again).</p>
+          <p v-if="!inIframe" class="note"><strong>Logout</strong> from {{ currentHost }}, or view your <strong>Full Profile</strong> at {{ authSiteHost }} (you may need to sign in again).</p>
         </div>
       </section>
-  </section>
+    </div>
+  </div>
 </template>
 
 <script setup>
-import { computed, ref } from 'vue'
+import { computed, onMounted, ref } from 'vue'
 import UserBasicInfo from '@/components/UserBasicInfo.vue'
-import { useAuthStore } from '@/stores/auth'
+import { getSettings } from '@/utils/settings'
-import { goBack } from '@/utils/helpers'
+import { fetchJson, settings as paskiaSettings } from 'paskia'
+import { updateThemeFromSession } from '@/utils/theme'
 import { getDirection, navigateButtonRow } from '@/utils/keynav'
 
-defineProps({
+// Data may be provided by the parent (full-page /auth/ app already loaded it
-  initializing: {
+// into the store); otherwise the component fetches it itself (restricted iframe).
-    type: Boolean,
+const props = defineProps({
-    default: false
+  ctx: {
+    type: Object,
+    default: null
+  },
+  userInfo: {
+    type: Object,
+    default: null
+  },
+  settings: {
+    type: Object,
+    default: null
   }
 })
 
-const authStore = useAuthStore()
+const emit = defineEmits(['back', 'logout'])
+
+const inIframe = window.parent !== window
 const currentHost = window.location.host
 
+const fetchedCtx = ref(null)
+const fetchedInfo = ref(null)
+const fetchedSettings = ref(null)
+const loading = ref(!(props.ctx && props.userInfo))
+const busy = ref(false)
+
 // Template refs for navigation
-const userInfoSection = ref(null)
 const buttonRow = ref(null)
 
-const ctx = computed(() => authStore.userInfo || null)
+const sessionCtx = computed(() => props.ctx || fetchedCtx.value)
-const orgDisplayName = computed(() => ctx.value?.org?.display_name ?? '')
+const info = computed(() => props.userInfo || fetchedInfo.value)
-const roleDisplayName = computed(() => ctx.value?.role?.display_name ?? '')
+const settingsData = computed(() => props.settings || fetchedSettings.value)
+const orgDisplayName = computed(() => sessionCtx.value?.org?.display_name ?? '')
+const roleDisplayName = computed(() => sessionCtx.value?.role?.display_name ?? '')
 
 const headingTitle = computed(() => {
-  const service = authStore.settings?.rp_name
+  const service = settingsData.value?.rp_name
   return service ? `${service} account` : 'Account overview'
 })
 
@@ -93,11 +118,12 @@ const subheading = computed(() => {
   return `You're signed in to ${currentHost}.`
 })
 
-const authSiteHost = computed(() => authStore.settings?.auth_host || '')
+const authSiteHost = computed(() => settingsData.value?.auth_host || '')
 const authSiteUrl = computed(() => {
-  const host = authSiteHost.value
+  // Fall back to the current host when no separate auth host is configured;
-  if (!host) return ''
+  // the full profile is at ui_base_path either way.
-  let path = authStore.settings?.ui_base_path ?? '/auth/'
+  const host = authSiteHost.value || currentHost
+  let path = settingsData.value?.ui_base_path ?? '/auth/'
   if (!path.startsWith('/')) path = `/${path}`
   if (!path.endsWith('/')) path = `${path}/`
   const protocol = window.location.protocol || 'https:'
@@ -106,11 +132,27 @@ const authSiteUrl = computed(() => {
 
 const goToAuthSite = () => {
   if (!authSiteUrl.value) return
+  // Inside an iframe, open the full profile in a new window and close the
+  // frame (auth-back) so the host page regains focus.
+  if (inIframe) {
+    window.open(authSiteUrl.value, '_blank')
+    emit('back')
+  } else {
     window.location.href = authSiteUrl.value
   }
+}
 
 const logout = async () => {
-  await authStore.logout()
+  if (busy.value) return
+  busy.value = true
+  try {
+    await fetchJson('/auth/api/logout', { method: 'POST', timeout: paskiaSettings.auth_ms })
+  } catch (error) {
+    console.error('Logout error:', error)
+  }
+  // The parent decides how to react: the full-page app reloads, the iframe
+  // host receives auth-logout and closes the frame.
+  emit('logout')
 }
 
 // Keyboard navigation for button row
@@ -123,7 +165,39 @@ const handleButtonRowKeydown = (event) => {
   if (direction === 'left' || direction === 'right') {
     navigateButtonRow(buttonRow.value, event.target, direction, { itemSelector: 'button' })
   }
-  // Up does nothing (no elements above to navigate to)
-  // Down does nothing (no elements below to navigate to)
 }
+
+onMounted(async () => {
+  if (!props.settings) {
+    getSettings().then((data) => { fetchedSettings.value = data })
+  }
+  if (props.ctx && props.userInfo) return
+  try {
+    const [validateData, infoData] = await Promise.all([
+      fetchJson('/auth/api/validate', { method: 'POST', timeout: paskiaSettings.auth_ms }),
+      fetchJson('/auth/api/user-info', { method: 'GET', timeout: paskiaSettings.auth_ms })
+    ])
+    fetchedCtx.value = validateData.ctx
+    fetchedInfo.value = infoData
+    updateThemeFromSession(validateData.ctx)
+  } catch (error) {
+    if (error.status !== 401 && error.status !== 403) {
+      console.error('Failed to load account summary:', error)
+    }
+  } finally {
+    loading.value = false
+  }
+})
 </script>
+
+<style scoped>
+.view-root.host-profile { min-height: 100vh; align-items: center; justify-content: center; padding: 2rem 1rem; }
+.surface.surface--tight {
+  max-width: 520px;
+  margin: 0 auto;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 1.75rem;
+}
+</style>

frontend/src/components/Modal.vue

@@ -1,8 +1,11 @@
 <template>
   <div class="dialog-overlay" @click="$emit('close')">
-    <div ref="dialog" class="modal-panel" @keydown="handleDialogKeydown" @click.stop>
+    <div class="modal-wrap">
+      <div ref="dialog" :class="['modal-panel', panelClass]" @keydown="handleDialogKeydown" @click.stop>
         <slot />
       </div>
+      <slot name="attached" />
+    </div>
   </div>
 </template>
 
@@ -17,7 +20,9 @@ const props = defineProps({
   // Optional: index to help find next sibling when item is deleted
   focusIndex: { type: Number, default: -1 },
   // Optional: selector for finding siblings when restoring focus
-  focusSiblingSelector: { type: String, default: '' }
+  focusSiblingSelector: { type: String, default: '' },
+  // Optional: extra class name(s) for the modal panel
+  panelClass: { type: [String, Array, Object], default: '' }
 })
 
 const emit = defineEmits(['close'])

frontend/src/components/ProfilePicture.vue

@@ -0,0 +1,126 @@
+<template>
+  <component
+    :is="rootTag"
+    v-bind="rootAttrs"
+    class="profile-picture"
+    :class="{ 'profile-picture-btn': clickable }"
+    :style="pictureStyle"
+    @click="handleClick"
+  >
+    <img
+      v-if="showPicture"
+      :key="`${src || 'none'}:${renderVersion}`"
+      :src="src"
+      alt=""
+      class="profile-picture-image"
+      @error="handleError"
+    />
+    <img
+      v-else
+      :src="profileGeneric"
+      alt=""
+      class="profile-picture-fallback"
+    />
+  </component>
+</template>
+
+<script setup>
+import profileGeneric from '@/assets/profile-generic.svg'
+import { computed, ref, watch } from 'vue'
+
+const props = defineProps({
+  src: { type: String, default: null },
+  clickable: { type: Boolean, default: false },
+  loading: { type: Boolean, default: false },
+  title: { type: String, default: '' },
+  renderVersion: { type: [Number, String], default: 0 },
+  width: { type: String, default: '3rem' },
+  height: { type: String, default: '3rem' },
+  radius: { type: String, default: '0.9rem' },
+  fit: { type: String, default: 'cover' },
+  filter: { type: String, default: 'none' },
+  fallbackSize: { type: String, default: '2em' }
+})
+
+const emit = defineEmits(['click'])
+const pictureAvailable = ref(true)
+
+const rootTag = computed(() => (props.clickable ? 'button' : 'div'))
+const showPicture = computed(() => !!props.src && pictureAvailable.value)
+const pictureStyle = computed(() => ({
+  '--profile-picture-width': props.width,
+  '--profile-picture-height': props.height,
+  '--profile-picture-radius': props.radius,
+  '--profile-picture-fit': props.fit,
+  '--profile-picture-filter': props.filter,
+  '--profile-picture-fallback-size': props.fallbackSize
+}))
+const rootAttrs = computed(() => {
+  if (!props.clickable) return { title: props.title || undefined }
+  return {
+    type: 'button',
+    disabled: props.loading,
+    title: props.title || undefined
+  }
+})
+
+watch(() => props.src, () => {
+  pictureAvailable.value = true
+})
+
+const handleError = () => {
+  pictureAvailable.value = false
+}
+
+const handleClick = () => {
+  if (!props.clickable || props.loading) return
+  emit('click')
+}
+</script>
+
+<style scoped>
+.profile-picture {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--profile-picture-width);
+  height: var(--profile-picture-height);
+  font-size: var(--profile-picture-fallback-size);
+  line-height: 1;
+  overflow: hidden;
+  border-radius: var(--profile-picture-radius);
+  background: transparent;
+  flex-shrink: 0;
+}
+
+.profile-picture-btn {
+  padding: 0;
+  border: 0;
+  transition: transform 0.12s ease, box-shadow 0.12s ease;
+  cursor: pointer;
+}
+
+.profile-picture-btn:hover:not(:disabled) {
+  transform: translateY(-1px);
+  box-shadow: inset 0 0 0 1px var(--color-accent);
+}
+
+.profile-picture-btn:disabled {
+  cursor: progress;
+}
+
+.profile-picture-image {
+  width: 100%;
+  height: 100%;
+  object-fit: var(--profile-picture-fit);
+  display: block;
+  filter: var(--profile-picture-filter);
+}
+
+.profile-picture-fallback {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+  display: block;
+}
+</style>

frontend/src/components/ProfilePictureEditorModal.vue

@@ -0,0 +1,489 @@
+<template>
+  <Modal panel-class="modal-panel--avatar" @close="closeEditor">
+    <h3>{{ title }}</h3>
+    <input
+      ref="pictureInput"
+      type="file"
+      accept="image/*"
+      class="profile-picture-editor-input"
+      :disabled="saving"
+      @change="handlePictureSelected"
+    />
+    <div ref="picturePreview" class="profile-picture-editor-preview" :style="previewStyle">
+      <img
+        v-if="editorImageUrl && displayMetrics"
+        :src="editorImageUrl"
+        alt=""
+        class="profile-picture-editor-image"
+        :style="editorImageStyle"
+      />
+      <img
+        v-if="editorImageUrl && displayMetrics"
+        :src="editorImageUrl"
+        alt=""
+        class="profile-picture-editor-image profile-picture-editor-image--overlay"
+        :style="editorOverlayStyle"
+      />
+      <div
+        v-if="editorImageUrl && displayMetrics"
+        class="profile-picture-editor-crop"
+        :style="cropBoxStyle"
+        @pointerdown="startMove"
+      >
+        <div class="profile-picture-editor-guides" aria-hidden="true">
+          <div class="profile-picture-editor-guide profile-picture-editor-guide--circle"></div>
+          <div class="profile-picture-editor-guide profile-picture-editor-guide--eyes"></div>
+          <div class="profile-picture-editor-guide profile-picture-editor-guide--cheek-left"></div>
+          <div class="profile-picture-editor-guide profile-picture-editor-guide--cheek-right"></div>
+        </div>
+        <button
+          type="button"
+          class="profile-picture-editor-handle profile-picture-editor-handle--nw"
+          @pointerdown.stop="startResize($event, 'nw')"
+        ></button>
+        <button
+          type="button"
+          class="profile-picture-editor-handle profile-picture-editor-handle--ne"
+          @pointerdown.stop="startResize($event, 'ne')"
+        ></button>
+        <button
+          type="button"
+          class="profile-picture-editor-handle profile-picture-editor-handle--sw"
+          @pointerdown.stop="startResize($event, 'sw')"
+        ></button>
+        <button
+          type="button"
+          class="profile-picture-editor-handle profile-picture-editor-handle--se"
+          @pointerdown.stop="startResize($event, 'se')"
+        ></button>
+      </div>
+      <ProfilePicture
+        v-else
+        class="profile-picture-editor-trigger"
+        :src="pictureUrl"
+        :render-version="renderVersion"
+        clickable
+        :loading="saving"
+        title="Choose profile picture"
+        width="100%"
+        height="100%"
+        radius="0"
+        fit="contain"
+        fallback-size="5rem"
+        @click="triggerPictureSelect"
+      />
+    </div>
+    <div v-if="errorMessage" class="error small">{{ errorMessage }}</div>
+    <div class="modal-actions">
+      <button type="button" class="btn-secondary" :disabled="saving" @click="closeEditor">Back</button>
+      <button
+        v-if="!editorImageUrl && pictureUrl"
+        type="button"
+        class="btn-danger"
+        :disabled="saving"
+        @click="removePicture"
+      >Delete</button>
+      <button
+        v-if="editorImageUrl"
+        type="button"
+        class="btn-primary"
+        :disabled="saving"
+        @click="savePicture"
+      >Save</button>
+    </div>
+  </Modal>
+</template>
+
+<script setup>
+import { computed, nextTick, onMounted, onUnmounted, reactive, ref, watch } from 'vue'
+import { apiJson } from 'paskia'
+import { useAuthStore } from '@/stores/auth'
+import Modal from '@/components/Modal.vue'
+import ProfilePicture from '@/components/ProfilePicture.vue'
+
+const AVATAR_UPLOAD_SIZE = 720
+const MIN_CROP_SIZE = 36
+
+const props = defineProps({
+  endpoint: { type: String, required: true },
+  pictureUrl: { type: String, default: null },
+  renderVersion: { type: [Number, String], default: 0 },
+  title: { type: String, default: 'Profile Picture' }
+})
+
+const emit = defineEmits(['close', 'updated'])
+const authStore = useAuthStore()
+
+const pictureInput = ref(null)
+const picturePreview = ref(null)
+const editorImage = ref(null)
+const editorImageUrl = ref('')
+const previewObjectUrl = ref(null)
+const saving = ref(false)
+const errorMessage = ref('')
+const cropRect = reactive({ x: 0, y: 0, size: 0 })
+const previewRect = reactive({ width: 0, height: 0 })
+const viewportSize = reactive({ width: 0, height: 0 })
+let dragState = null
+let previewObserver = null
+
+onMounted(async () => {
+  viewportSize.width = window.innerWidth
+  viewportSize.height = window.innerHeight
+  window.addEventListener('pointermove', handlePointerMove)
+  window.addEventListener('pointerup', endPointerInteraction)
+  window.addEventListener('resize', syncPreviewRect)
+  await nextTick()
+  syncPreviewRect()
+  if (picturePreview.value && typeof ResizeObserver !== 'undefined') {
+    previewObserver = new ResizeObserver(() => syncPreviewRect())
+    previewObserver.observe(picturePreview.value)
+  }
+})
+
+onUnmounted(() => {
+  window.removeEventListener('pointermove', handlePointerMove)
+  window.removeEventListener('pointerup', endPointerInteraction)
+  window.removeEventListener('resize', syncPreviewRect)
+  previewObserver?.disconnect()
+  clearPreviewObjectUrl()
+})
+
+watch(editorImage, async (image) => {
+  if (!image) return
+  await nextTick()
+  syncPreviewRect()
+  initializeCrop()
+})
+
+const clearPreviewObjectUrl = () => {
+  if (!previewObjectUrl.value) return
+  URL.revokeObjectURL(previewObjectUrl.value)
+  previewObjectUrl.value = null
+}
+
+const resetEditor = () => {
+  clearPreviewObjectUrl()
+  editorImage.value = null
+  editorImageUrl.value = ''
+  cropRect.x = 0
+  cropRect.y = 0
+  cropRect.size = 0
+  errorMessage.value = ''
+  if (pictureInput.value) pictureInput.value.value = ''
+}
+
+const syncPreviewRect = () => {
+  viewportSize.width = window.innerWidth
+  viewportSize.height = window.innerHeight
+  const element = picturePreview.value
+  if (!element) return
+  previewRect.width = element.clientWidth
+  previewRect.height = element.clientHeight
+}
+
+const previewStyle = computed(() => {
+  const image = editorImage.value
+  if (!image) {
+    const size = Math.min(viewportSize.width * 0.72, viewportSize.height * 0.42, 352)
+    return {
+      width: `${Math.max(160, Math.round(size))}px`,
+      height: `${Math.max(160, Math.round(size))}px`
+    }
+  }
+
+  const maxWidth = Math.min(viewportSize.width * 0.88, 928)
+  const maxHeight = Math.min(viewportSize.height * 0.62, 620)
+  const scale = Math.min(maxWidth / image.naturalWidth, maxHeight / image.naturalHeight)
+
+  return {
+    width: `${Math.max(1, Math.round(image.naturalWidth * scale))}px`,
+    height: `${Math.max(1, Math.round(image.naturalHeight * scale))}px`
+  }
+})
+
+const displayMetrics = computed(() => {
+  const image = editorImage.value
+  if (!image || !previewRect.width || !previewRect.height) return null
+  const scale = Math.min(previewRect.width / image.naturalWidth, previewRect.height / image.naturalHeight)
+  const width = image.naturalWidth * scale
+  const height = image.naturalHeight * scale
+  return {
+    x: (previewRect.width - width) / 2,
+    y: (previewRect.height - height) / 2,
+    width,
+    height
+  }
+})
+
+const editorImageStyle = computed(() => {
+  const metrics = displayMetrics.value
+  if (!metrics) return null
+  return {
+    width: `${metrics.width}px`,
+    height: `${metrics.height}px`,
+    left: `${metrics.x}px`,
+    top: `${metrics.y}px`
+  }
+})
+
+const editorOverlayStyle = computed(() => {
+  const metrics = displayMetrics.value
+  if (!metrics || !cropRect.size) return editorImageStyle.value
+
+  const left = cropRect.x
+  const top = cropRect.y
+  const right = cropRect.x + cropRect.size
+  const bottom = cropRect.y + cropRect.size
+
+  return {
+    ...editorImageStyle.value,
+    clipPath: `polygon(evenodd, 0 0, 100% 0, 100% 100%, 0 100%, 0 0, ${left}px ${top}px, ${left}px ${bottom}px, ${right}px ${bottom}px, ${right}px ${top}px, ${left}px ${top}px)`
+  }
+})
+
+const cropBoxStyle = computed(() => {
+  const metrics = displayMetrics.value
+  if (!metrics || !cropRect.size) return null
+  return {
+    left: `${metrics.x + cropRect.x}px`,
+    top: `${metrics.y + cropRect.y}px`,
+    width: `${cropRect.size}px`,
+    height: `${cropRect.size}px`
+  }
+})
+
+const initializeCrop = () => {
+  const metrics = displayMetrics.value
+  if (!metrics) return
+  const size = Math.min(metrics.width, metrics.height)
+  cropRect.size = size
+  cropRect.x = (metrics.width - size) / 2
+  cropRect.y = (metrics.height - size) / 2
+}
+
+const triggerPictureSelect = () => {
+  pictureInput.value?.click()
+}
+
+const handlePictureSelected = async (event) => {
+  const nextFile = event.target.files?.[0] || null
+  resetEditor()
+  if (!nextFile) return
+
+  previewObjectUrl.value = URL.createObjectURL(nextFile)
+  editorImageUrl.value = previewObjectUrl.value
+  const image = new Image()
+  image.decoding = 'async'
+  image.src = editorImageUrl.value
+  try {
+    await image.decode()
+    editorImage.value = image
+  } catch {
+    errorMessage.value = 'Failed to load image'
+    resetEditor()
+  }
+}
+
+const startMove = (event) => {
+  if (!displayMetrics.value || saving.value) return
+  event.preventDefault()
+  dragState = {
+    mode: 'move',
+    startX: event.clientX,
+    startY: event.clientY,
+    initialX: cropRect.x,
+    initialY: cropRect.y,
+    initialSize: cropRect.size
+  }
+}
+
+const startResize = (event, handle) => {
+  if (!displayMetrics.value || saving.value) return
+  event.preventDefault()
+  dragState = {
+    mode: 'resize',
+    handle,
+    startX: event.clientX,
+    startY: event.clientY,
+    initialX: cropRect.x,
+    initialY: cropRect.y,
+    initialSize: cropRect.size
+  }
+}
+
+const handlePointerMove = (event) => {
+  if (!dragState) return
+  const metrics = displayMetrics.value
+  if (!metrics) return
+
+  const dx = event.clientX - dragState.startX
+  const dy = event.clientY - dragState.startY
+
+  if (dragState.mode === 'move') {
+    cropRect.x = Math.max(0, Math.min(metrics.width - dragState.initialSize, dragState.initialX + dx))
+    cropRect.y = Math.max(0, Math.min(metrics.height - dragState.initialSize, dragState.initialY + dy))
+    return
+  }
+
+  const directionMap = {
+    nw: { deltaX: -1, deltaY: -1 },
+    ne: { deltaX: 1, deltaY: -1 },
+    sw: { deltaX: -1, deltaY: 1 },
+    se: { deltaX: 1, deltaY: 1 }
+  }
+  const direction = directionMap[dragState.handle]
+  if (!direction) return
+
+  const delta = Math.max(dx * direction.deltaX, dy * direction.deltaY)
+  const nextSize = Math.max(
+    MIN_CROP_SIZE,
+    Math.min(getResizeLimit(metrics, dragState), dragState.initialSize + delta)
+  )
+
+  applyResize(dragState, nextSize)
+}
+
+const endPointerInteraction = () => {
+  dragState = null
+}
+
+const getResizeLimit = (metrics, state) => {
+  const { initialX, initialY, initialSize, handle } = state
+
+  if (handle === 'nw') return Math.min(initialX + initialSize, initialY + initialSize)
+  if (handle === 'ne') return Math.min(metrics.width - initialX, initialY + initialSize)
+  if (handle === 'sw') return Math.min(initialX + initialSize, metrics.height - initialY)
+  return Math.min(metrics.width - initialX, metrics.height - initialY)
+}
+
+const applyResize = (state, size) => {
+  const { initialX, initialY, initialSize, handle } = state
+
+  if (handle === 'nw') {
+    cropRect.x = initialX + initialSize - size
+    cropRect.y = initialY + initialSize - size
+    cropRect.size = size
+    return
+  }
+
+  if (handle === 'ne') {
+    cropRect.x = initialX
+    cropRect.y = initialY + initialSize - size
+    cropRect.size = size
+    return
+  }
+
+  if (handle === 'sw') {
+    cropRect.x = initialX + initialSize - size
+    cropRect.y = initialY
+    cropRect.size = size
+    return
+  }
+
+  cropRect.x = initialX
+  cropRect.y = initialY
+  cropRect.size = size
+}
+
+const renderPictureBlob = async () => {
+  const image = editorImage.value
+  if (!image) throw new Error('No image selected')
+  const metrics = displayMetrics.value
+  if (!metrics || !cropRect.size) throw new Error('Crop selection unavailable')
+
+  const canvas = document.createElement('canvas')
+  canvas.width = AVATAR_UPLOAD_SIZE
+  canvas.height = AVATAR_UPLOAD_SIZE
+  const context = canvas.getContext('2d')
+  if (!context) throw new Error('Canvas unavailable')
+
+  const sourceScale = image.naturalWidth / metrics.width
+  const sourceX = cropRect.x * sourceScale
+  const sourceY = cropRect.y * sourceScale
+  const sourceSize = cropRect.size * sourceScale
+  context.drawImage(image, sourceX, sourceY, sourceSize, sourceSize, 0, 0, AVATAR_UPLOAD_SIZE, AVATAR_UPLOAD_SIZE)
+
+  return await new Promise((resolve, reject) => {
+    canvas.toBlob((blob) => {
+      if (!blob) {
+        reject(new Error('Failed to export cropped picture'))
+        return
+      }
+      resolve(blob)
+    }, 'image/webp', 0.9)
+  })
+}
+
+const reloadPictureFromCache = async () => {
+  const response = await fetch(props.endpoint, {
+    method: 'GET',
+    credentials: 'same-origin',
+    cache: 'reload'
+  })
+  if (!response.ok) throw new Error('Failed to refresh profile picture')
+}
+
+const savePicture = async () => {
+  try {
+    saving.value = true
+    errorMessage.value = ''
+    const blob = await renderPictureBlob()
+    const formData = new FormData()
+    formData.append('file', blob, 'profile.webp')
+    await apiJson(props.endpoint, { method: 'PUT', body: formData })
+    await reloadPictureFromCache()
+    authStore.showMessage('Profile picture updated.', 'success', 3000)
+    emit('updated')
+    closeEditor()
+  } catch (error) {
+    errorMessage.value = error.message || 'Failed to update profile picture'
+  } finally {
+    saving.value = false
+  }
+}
+
+const removePicture = async () => {
+  try {
+    saving.value = true
+    errorMessage.value = ''
+    await apiJson(props.endpoint, { method: 'DELETE' })
+    authStore.showMessage('Profile picture removed.', 'success', 3000)
+    emit('updated')
+    closeEditor()
+  } catch (error) {
+    errorMessage.value = error.message || 'Failed to remove profile picture'
+  } finally {
+    saving.value = false
+  }
+}
+
+const closeEditor = () => {
+  resetEditor()
+  emit('close')
+}
+</script>
+
+<style scoped>
+.profile-picture-editor-input { display: none; }
+.profile-picture-editor-preview { position: relative; display: flex; justify-content: center; align-items: center; width: auto; max-width: min(58rem, 88vw); min-height: 0; margin: 0 auto; overflow: visible; }
+.profile-picture-editor-trigger { min-width: 0; }
+.profile-picture-editor-image { position: absolute; user-select: none; pointer-events: none; object-fit: contain; }
+.profile-picture-editor-image--overlay { filter: grayscale(0.45) saturate(0.7) brightness(0.68); }
+.profile-picture-editor-crop { position: absolute; border: 2px solid white; cursor: move; touch-action: none; }
+.profile-picture-editor-guides { position: absolute; inset: 0; pointer-events: none; }
+.profile-picture-editor-guide { position: absolute; border-color: rgba(255, 255, 255, 0.52); }
+.profile-picture-editor-guide--circle { inset: 0; border: 1.5px solid rgba(255, 255, 255, 0.62); border-radius: 999px; box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.18); }
+.profile-picture-editor-guide--eyes { left: 18%; right: 18%; top: 38%; border-top: 1.5px solid rgba(255, 255, 255, 0.56); }
+.profile-picture-editor-guide--cheek-left { top: 24%; bottom: 18%; left: 24%; border-left: 1.5px solid rgba(255, 255, 255, 0.48); }
+.profile-picture-editor-guide--cheek-right { top: 24%; bottom: 18%; right: 24%; border-right: 1.5px solid rgba(255, 255, 255, 0.48); }
+.profile-picture-editor-handle { position: absolute; width: 1.1rem; height: 1.1rem; border-radius: 999px; border: 2px solid white; background: var(--color-accent); padding: 0; }
+.profile-picture-editor-handle--nw { left: -0.55rem; top: -0.55rem; cursor: nwse-resize; }
+.profile-picture-editor-handle--ne { right: -0.55rem; top: -0.55rem; cursor: nesw-resize; }
+.profile-picture-editor-handle--sw { left: -0.55rem; bottom: -0.55rem; cursor: nesw-resize; }
+.profile-picture-editor-handle--se { right: -0.55rem; bottom: -0.55rem; cursor: nwse-resize; }
+:deep(.modal-panel--avatar) { width: fit-content; max-width: min(58rem, 94vw); }
+@media (max-width: 720px) {
+  .profile-picture-editor-preview { max-width: 100%; }
+}
+</style>

frontend/src/components/ProfileView.vue

@@ -15,6 +15,9 @@
         v-if="authStore.userInfo?.user"
         ref="userBasicInfo"
         :name="authStore.userInfo.user.display_name"
+        :avatar-url="authStore.userInfo.user.avatar_url"
+        :avatar-render-version="avatarRenderVersion"
+        avatar-clickable
         :email="authStore.userInfo.user.email"
         :preferred_username="authStore.userInfo.user.preferred_username"
         :telephone="authStore.userInfo.user.telephone"
@@ -26,6 +29,7 @@
         :role-name="authStore.userInfo.role.display_name"
         update-endpoint="/auth/api/user/info"
         @saved="authStore.loadUserInfo()"
+        @avatar-click="openAvatarDialog"
         @edit="openEditDialog"
         @keydown="handleUserInfoKeydown"
       >
@@ -50,6 +54,10 @@
         <p class="section-description">Ideally have at least two passkeys in case you lose one. More than one user can be registered on the same device, giving you a choice at login. <a href="https://bitwarden.com/pricing/" target="_blank" rel="noopener noreferrer">Bitwarden</a> can sync one passkey to all your devices. Other secure options include <b>local passkeys</b>, as well as hardware keys such as <a href="https://www.yubico.com" target="_blank" rel="noopener noreferrer">YubiKey</a>. Cloud sync via Google, Microsoft or iCloud is discouraged.</p>
       </div>
       <div class="section-body">
+        <div v-if="missingDomainPasskey" class="domain-enroll-notice">
+          <p>You don't have a passkey for <strong>{{ rpName }}</strong> ({{ authStore.settings.rp_id }}) yet. Add one to log in here directly.</p>
+          <button @click="addNewCredential" class="btn-primary">Add Passkey for {{ authStore.settings.rp_id }}</button>
+        </div>
         <CredentialList
           ref="credentialList"
           :credentials="credentials"
@@ -131,6 +139,15 @@
       </form>
     </Modal>
 
+    <ProfilePictureEditorModal
+      v-if="showAvatarDialog && currentAvatarEndpoint"
+      :endpoint="currentAvatarEndpoint"
+      :picture-url="authStore.userInfo?.user?.avatar_url"
+      :render-version="avatarRenderVersion"
+      @close="closeAvatarDialog"
+      @updated="handleProfilePictureUpdated"
+    />
+
     <RegistrationLinkModal
       v-if="showRegLink"
       endpoint="/auth/api/user/create-link"
@@ -144,6 +161,7 @@
 import { ref, onMounted, onUnmounted, computed, watch } from 'vue'
 import Breadcrumbs from '@/components/Breadcrumbs.vue'
 import CredentialList from '@/components/CredentialList.vue'
+import ProfilePictureEditorModal from '@/components/ProfilePictureEditorModal.vue'
 import ThemeSelector from '@/components/ThemeSelector.vue'
 import UserBasicInfo from '@/components/UserBasicInfo.vue'
 import Modal from '@/components/Modal.vue'
@@ -160,11 +178,13 @@ import { navigateButtonRow, focusPreferred, focusAtIndex, getDirection } from '@
 const authStore = useAuthStore()
 const updateInterval = ref(null)
 const showEditDialog = ref(false)
+const showAvatarDialog = ref(false)
 const showRegLink = ref(false)
 const editName = ref('')
 const editEmail = ref('')
 const editUsername = ref('')
 const editTelephone = ref('')
+const avatarRenderVersion = ref(0)
 const saving = ref(false)
 const editError = ref('')
 const hoveredCredentialUuid = ref(null)
@@ -176,14 +196,15 @@ const credentialButtons = ref(null)
 const sessionList = ref(null)
 const logoutButtons = ref(null)
 const breadcrumbs = ref(null)
-const userBasicInfo = ref(null)
 const userInfoSection = ref(null)
 
 // Check if any modal/dialog is open (blocks arrow key navigation)
-const hasActiveModal = computed(() => showEditDialog.value || showRegLink.value)
+const hasActiveModal = computed(() => showEditDialog.value || showAvatarDialog.value || showRegLink.value)
 
 watch(showEditDialog, (open) => {
-  if (!open) return
+  if (!open) {
+    return
+  }
   const user = authStore.userInfo.user
   editName.value = user.display_name ?? ''
   editEmail.value = user.email ?? ''
@@ -196,7 +217,28 @@ onMounted(() => {
   updateInterval.value = setInterval(() => { if (authStore.userInfo) authStore.userInfo = { ...authStore.userInfo } }, 60000)
 })
 
-onUnmounted(() => { if (updateInterval.value) clearInterval(updateInterval.value) })
+onUnmounted(() => {
+  if (updateInterval.value) clearInterval(updateInterval.value)
+})
+
+const currentAvatarEndpoint = computed(() => {
+  const userUuid = authStore.userInfo?.user?.uuid
+  if (!userUuid) return null
+  return `/auth/api/user/${userUuid}/profile.webp`
+})
+
+const openAvatarDialog = () => {
+  showAvatarDialog.value = true
+}
+
+const closeAvatarDialog = () => {
+  showAvatarDialog.value = false
+}
+
+const handleProfilePictureUpdated = async () => {
+  await authStore.loadUserInfo()
+  avatarRenderVersion.value += 1
+}
 
 const addNewCredential = async () => {
   try {
@@ -245,7 +287,7 @@ const handleBreadcrumbKeydown = (event) => {
   if (direction === 'down') {
     event.preventDefault()
     // Move to user info section - always focus edit button first
-    focusPreferred(userInfoSection.value, { primarySelector: '.mini-btn', itemSelector: '.mini-btn, .pairing-input' })
+    focusPreferred(userInfoSection.value, { primarySelector: '.mini-btn', itemSelector: '.user-picture-btn, .mini-btn, .pairing-input' })
   }
   // ArrowUp at the top does nothing
 }
@@ -257,7 +299,7 @@ const handleUserInfoKeydown = (event) => {
   if (!direction) return
 
   event.preventDefault()
-  const itemSelector = '.mini-btn, .pairing-input'
+  const itemSelector = '.user-picture-btn, .mini-btn, .pairing-input'
 
   if (direction === 'left' || direction === 'right') {
     navigateButtonRow(userInfoSection.value, event.target, direction, { itemSelector })
@@ -278,7 +320,7 @@ const handleCredentialNavigateOut = (direction) => {
     focusPreferredButton(credentialButtons.value)
   } else if (direction === 'up' || direction === 'left') {
     // Focus user info section - always focus edit button first
-    focusPreferred(userInfoSection.value, { primarySelector: '.mini-btn', itemSelector: '.mini-btn, .pairing-input' })
+    focusPreferred(userInfoSection.value, { primarySelector: '.mini-btn', itemSelector: '.user-picture-btn, .mini-btn, .pairing-input' })
   }
 }
 
@@ -372,6 +414,11 @@ const hasMultipleSessions = computed(() => Object.keys(sessions.value).length >
 const credentials = computed(() =>
   Object.entries(authStore.userInfo.credentials).map(([uuid, c]) => ({ ...c, credential: uuid }))
 )
+const missingDomainPasskey = computed(() => {
+  const rpId = authStore.settings?.rp_id
+  if (!rpId) return false
+  return !credentials.value.some(c => c.rp_id === rpId)
+})
 const useWideLayout = computed(() => {
   // Check if any single site has more than 8 sessions
   const groups = {}
@@ -399,6 +446,7 @@ const saveProfile = async () => {
   try {
     editError.value = ''
     saving.value = true
+    let changed = false
     const body = {}
     if (name !== user.display_name) body.display_name = name
     if (emailVal !== (user.email || null)) body.email = emailVal
@@ -406,6 +454,9 @@ const saveProfile = async () => {
     if (telephoneVal !== (user.telephone || null)) body.telephone = telephoneVal
     if (Object.keys(body).length) {
       await apiJson('/auth/api/user/info', { method: 'PATCH', body })
+      changed = true
+    }
+    if (changed) {
       await authStore.loadUserInfo()
       authStore.showMessage('Profile updated!', 'success', 3000)
     }

frontend/src/components/RemoteAuthPermit.vue

@@ -53,6 +53,7 @@
       <!-- Device info display (shown when 3 words match a request) -->
       <div v-else-if="deviceInfo" class="device-info">
         <p class="device-permit-text">Permit {{ deviceInfo.action === 'register' ? 'registration' : 'login' }} to <strong>{{ deviceInfo.host }}</strong></p>
+        <p v-if="crossDomainNotice" class="device-meta domain-notice">on <strong>{{ deviceInfo.rp_name || deviceInfo.rp_id }}</strong><template v-if="deviceInfo.rp_name"> ({{ deviceInfo.rp_id }})</template></p>
         <p class="device-meta">{{ deviceInfo.user_agent_pretty || '—' }}</p>
 
         <p v-if="error" class="error-message">{{ error }}</p>
@@ -122,6 +123,13 @@ watch(deviceInfo, (newVal) => {
   emit('deviceInfoVisible', !!newVal)
 })
 
+const crossDomainNotice = computed(() => {
+  const info = deviceInfo.value
+  if (!info?.rp_id) return false
+  const ownRpId = settings.value?.rp_id
+  return ownRpId ? info.rp_id !== ownRpId : true
+})
+
 const hasInvalidWord = ref(false)
 const serverError = ref(false)
 const cursorPos = ref(0)
@@ -613,7 +621,9 @@ async function lookupDeviceInfo() {
         host: res.host,
         user_agent_pretty: res.user_agent_pretty,
         client_ip: res.client_ip,
-        action: res.action || 'login'
+        action: res.action || 'login',
+        rp_id: res.rp_id || null,
+        rp_name: res.rp_name || null
       }
       lastLookedUpCode = currentCode
       nextTick(() => { submitBtnRef.value?.focus() })
@@ -937,6 +947,12 @@ defineExpose({ reset, deny, code, handleInput, loading, error })
   font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;
 }
 
+.domain-notice {
+  color: var(--color-text);
+  font-family: inherit;
+  font-size: 0.9rem;
+}
+
 .error-message {
   margin: 0.5rem 0 0;
   font-size: 0.875rem;

frontend/src/components/RestrictedAuth.vue

@@ -58,7 +58,7 @@
 import { computed, nextTick, onMounted, onUnmounted, reactive, ref, watch } from 'vue'
 import passkey from '@/utils/passkey'
 import { getSettings, uiBasePath } from '@/utils/settings'
-import { fetchJson, getUserFriendlyErrorMessage } from 'paskia'
+import { fetchJson, getUserFriendlyErrorMessage, settings as paskiaSettings } from 'paskia'
 import RemoteAuthRequest from '@/components/RemoteAuthRequest.vue'
 import { focusDialogButton } from '@/utils/keynav'
 import { updateThemeFromSession } from '@/utils/theme'
@@ -147,7 +147,7 @@ async function fetchSettings() {
 
 async function validateSession() {
   try {
-    session.value = await fetchJson('/auth/api/validate', { method: 'POST' })
+    session.value = await fetchJson('/auth/api/validate', { method: 'POST', timeout: paskiaSettings.auth_ms })
     updateThemeFromSession(session.value?.ctx)
     if (isAuthenticated.value && props.mode !== 'reauth') {
       currentView.value = 'forbidden'
@@ -198,7 +198,7 @@ async function logoutUser() {
   if (loading.value) return
   loading.value = true
   try {
-    await fetchJson('/auth/api/logout', { method: 'POST' })
+    await fetchJson('/auth/api/logout', { method: 'POST', timeout: paskiaSettings.auth_ms })
     session.value = null
     currentView.value = 'login'
     showMessage('Logged out. You can sign in with a different account.', 'info', 3000)
@@ -220,7 +220,7 @@ async function exchangeCode(result) {
     throw new Error('Authentication response missing exchange_code')
   }
   return await fetchJson('/auth/api/set-session', {
-    method: 'POST', headers: { 'Authorization': `Bearer ${result.exchange_code}` }
+    method: 'POST', headers: { 'Authorization': `Bearer ${result.exchange_code}` }, timeout: paskiaSettings.auth_ms
   })
 }
 

frontend/src/components/UserBasicInfo.vue

@@ -1,9 +1,20 @@
 <template>
   <div v-if="userLoaded" class="user-info" :class="{ 'has-extra': $slots.default }">
     <div class="user-info-content">
-      <div class="user-picture">
+      <ProfilePicture
-        <span>👤</span>
+        :src="avatarUrl"
-      </div>
+        :render-version="avatarRenderVersion"
+        :clickable="avatarClickable"
+        :loading="loading"
+        :title="avatarClickable ? 'Change profile picture' : ''"
+        width="5.25rem"
+        height="5.25rem"
+        radius="var(--radius-sm)"
+        fallback-size="2.8em"
+        class="user-picture"
+        :class="avatarClickable ? 'user-picture-btn' : ''"
+        @click="emit('avatar-click')"
+      />
       <h3 class="user-name-heading">
         <span class="user-name-row">
           <span class="display-name" :title="name">{{ name }}</span>
@@ -42,11 +53,13 @@
 
 <script setup>
 import { computed } from 'vue'
-import { useAuthStore } from '@/stores/auth'
+import ProfilePicture from '@/components/ProfilePicture.vue'
 import { formatDate } from '@/utils/helpers'
 
 const props = defineProps({
   name: { type: String, required: true },
+  avatarUrl: { type: String, default: null },
+  avatarRenderVersion: { type: [Number, String], default: 0 },
   email: { type: String, default: null },
   preferred_username: { type: String, default: null },
   telephone: { type: String, default: null },
@@ -55,14 +68,13 @@ const props = defineProps({
   lastSeen: { type: [String, Number, Date], default: null },
   updateEndpoint: { type: String, default: null },
   canEdit: { type: Boolean, default: true },
+  avatarClickable: { type: Boolean, default: false },
   loading: { type: Boolean, default: false },
   orgDisplayName: { type: String, default: '' },
   roleName: { type: String, default: '' }
 })
 
-const emit = defineEmits(['saved', 'edit'])
+const emit = defineEmits(['saved', 'edit', 'avatar-click'])
-const authStore = useAuthStore()
-
 const userLoaded = computed(() => !!props.name)
 </script>
 
@@ -96,12 +108,12 @@ const userLoaded = computed(() => !!props.name)
   grid-template-areas:
     "picture heading fields"
     "picture org fields"
-    ". info info";
+    "picture info info";
   gap: 0 1rem;
   min-width: 0;
 }
 
-.user-picture { grid-area: picture; display: flex; align-items: flex-start; font-size: 2em; line-height: 1; }
+:deep(.user-picture) { grid-area: picture; align-self: stretch; }
 .user-name-heading { grid-area: heading; display: flex; align-items: center; flex-wrap: wrap; margin: 0 0 0.25rem 0; min-width: 0; }
 .org-role-sub { grid-area: org; display: flex; flex-direction: column; min-width: 0; }
 .org-line { font-size: .7rem; font-weight: 600; line-height: 1.1; color: var(--color-text-muted); text-transform: uppercase; letter-spacing: 0.05em; }

frontend/src/stores/auth.js

@@ -1,7 +1,7 @@
 import { defineStore } from 'pinia'
 import { register, authenticate } from '@/utils/passkey'
 import { getSettings } from '@/utils/settings'
-import { apiJson } from 'paskia'
+import { apiJson, settings as paskiaSettings } from 'paskia'
 import { updateThemeFromSession } from '@/utils/theme'
 
 export const useAuthStore = defineStore('auth', {
@@ -50,6 +50,7 @@ export const useAuthStore = defineStore('auth', {
       return await apiJson('/auth/api/set-session', {
         method: 'POST',
         headers: {'Authorization': `Bearer ${result.session_token}`},
+        timeout: paskiaSettings.auth_ms,
       })
     },
     async register() {
@@ -82,12 +83,12 @@ export const useAuthStore = defineStore('auth', {
       if (!this.userInfo) this.currentView = 'login'
       else this.currentView = 'profile'
     },
-    async loadSettings() {
+    async loadSettings(force = false) {
-      this.settings = await getSettings()
+      this.settings = await getSettings(force)
     },
     async loadUserInfo() {
       try {
-        this.userInfo = await apiJson('/auth/api/user-info', { method: 'GET' })
+        this.userInfo = await apiJson('/auth/api/user-info', { method: 'GET', timeout: paskiaSettings.auth_ms })
         updateThemeFromSession(this.userInfo)
         console.log('User info loaded:', this.userInfo)
       } catch (error) {
@@ -121,7 +122,7 @@ export const useAuthStore = defineStore('auth', {
     },
     async logout() {
       try {
-        await apiJson('/auth/api/logout', {method: 'POST'})
+        await apiJson('/auth/api/logout', {method: 'POST', timeout: paskiaSettings.auth_ms})
         sessionStorage.clear()
         location.reload()
       } catch (error) {
@@ -134,7 +135,7 @@ export const useAuthStore = defineStore('auth', {
     },
     async logoutEverywhere() {
       try {
-        await apiJson('/auth/api/user/logout-all', {method: 'POST'})
+        await apiJson('/auth/api/user/logout-all', {method: 'POST', timeout: paskiaSettings.auth_ms})
         sessionStorage.clear()
         location.reload()
       } catch (error) {

frontend/src/utils/helpers.js

@@ -41,3 +41,87 @@ export const hostIP = ip => {
     return ip
   }
 }
+
+// Display-time ordering of a domain's configured origins (the stored
+// object is unordered): the auth host first (flagged), then in-domain
+// entries (exact rp-id, then hierarchical), then related origins — hosts
+// outside the rp-id domain — hierarchically. An empty origins object
+// allows nothing and shows as an empty list.
+
+// Hierarchical origin comparison: split off scheme/port, compare hostnames
+// label by label from the TLD down, parents before their subdomains and a
+// wildcard label ('**' any depth, '*' one level — in that order) after all
+// concrete labels at the same level. Entries on the same host tie-break by
+// scheme (https first) and numeric port.
+function originParts(key) {
+  let s = key.toLowerCase().replace(/\/+$/, '')
+  let scheme = ''
+  const sm = s.match(/^([a-z][a-z0-9+.-]*):\/\//)
+  if (sm) { scheme = sm[1]; s = s.slice(sm[0].length) }
+  let port = ''
+  const pm = s.match(/:(\d+)$/)
+  if (pm) { port = pm[1]; s = s.slice(0, -pm[0].length) }
+  const labels = s.split('.').reverse()
+  return { labels, scheme, port }
+}
+
+export function compareOrigins(a, b) {
+  const A = originParts(a), B = originParts(b)
+  for (let i = 0; i < Math.max(A.labels.length, B.labels.length); i++) {
+    const la = A.labels[i], lb = B.labels[i]
+    if (la === undefined) return -1
+    if (lb === undefined) return 1
+    if (la === lb) continue
+    const wa = la === '*' || la === '**'
+    const wb = lb === '*' || lb === '**'
+    if (wa && wb) return la === '**' ? -1 : 1
+    if (wa) return 1
+    if (wb) return -1
+    const c = la.localeCompare(lb)
+    if (c) return c
+  }
+  if (A.scheme !== B.scheme) {
+    if (A.scheme === 'https') return -1
+    if (B.scheme === 'https') return 1
+    return A.scheme.localeCompare(B.scheme)
+  }
+  if (A.port && B.port) return Number(A.port) - Number(B.port)
+  return A.port.localeCompare(B.port)
+}
+
+// An origins-table entry outside the rp-id domain is a related origin
+// (WebAuthn ROR). Wildcards ('*.' or '**.') are never related — they are
+// only valid under the rp-id.
+function isRelatedKey(rpId, key) {
+  if (key.startsWith('*.') || key.startsWith('**.')) return false
+  try {
+    const hostname = new URL(key.includes('://') ? key : 'https://' + key).hostname
+    return !!hostname && hostname !== rpId && !hostname.endsWith('.' + rpId)
+  } catch {
+    return false
+  }
+}
+
+export function originDisplayEntries(domain) {
+  const origins = domain.origins || {}
+  const keys = Object.keys(origins)
+  const authKey = keys.find(k => origins[k] !== true && origins[k]?.auth_host)
+  const inDomain = []
+  const related = []
+  for (const k of keys) {
+    if (k === authKey) continue
+    const bucket = isRelatedKey(domain.rp_id, k) ? related : inDomain
+    bucket.push(k)
+  }
+  inDomain.sort((a, b) => {
+    if (a === domain.rp_id) return -1
+    if (b === domain.rp_id) return 1
+    return compareOrigins(a, b)
+  })
+  related.sort(compareOrigins)
+  const rows = []
+  if (authKey) rows.push({ key: authKey, auth: true })
+  for (const k of inDomain) rows.push({ key: k, auth: false })
+  for (const k of related) rows.push({ key: k, auth: false, related: true })
+  return rows
+}

frontend/src/utils/settings.js

@@ -1,15 +1,19 @@
 let _settingsPromise = null
 let _settings = null
+let _requestGen = 0
 
 export function getSettingsCached() { return _settings }
 
-export async function getSettings() {
+export async function getSettings(force = false) {
+  if (force) { _settings = null; _settingsPromise = null; _requestGen++ }
   if (_settings) return _settings
   if (_settingsPromise) return _settingsPromise
+  const gen = _requestGen
+  const stale = () => getSettings() // superseded by a force reset: defer to the fresh state
   _settingsPromise = fetch('/auth/api/settings')
     .then(r => (r.ok ? r.json() : {}))
-    .then(obj => { _settings = obj || {}; return _settings })
+    .then(obj => gen === _requestGen ? (_settings = obj || {}) : stale())
-    .catch(() => { _settings = {}; return _settings })
+    .catch(() => gen === _requestGen ? (_settings = {}) : stale())
   return _settingsPromise
 }
 

frontend/src/utils/theme.js

@@ -38,9 +38,20 @@ export function initThemeFromCache() {
   applyTheme(getCachedTheme())
 }
 
+/** Theme default from the URL hash (restricted iframe/forward pages only) */
+function getHashTheme() {
+  const theme = new URLSearchParams(window.location.hash.slice(1)).get('theme')
+  return theme === 'light' || theme === 'dark' ? theme : ''
+}
+
 /** Update theme from session context (call after login/session load) */
 export function updateThemeFromSession(ctx, animate = false) {
   const theme = ctx?.user?.theme || ''
+  // Always keep the cache in sync with the profile: empty override clears it
+  // so stale values never mask future server-provided themes.
   setCachedTheme(theme)
-  applyTheme(theme, document.documentElement, animate)
+  // Without a profile override, stay consistent with the initial paint: a
+  // theme parameter on the URL (e.g. host page color scheme injected by
+  // paskia-js) remains in effect before the browser/desktop default.
+  applyTheme(theme || getHashTheme(), document.documentElement, animate)
 }

frontend/vite-plugin-fastapi.js

@@ -5,13 +5,14 @@
  * Configures Vite for FastAPI backend integration:
  * - Proxies /api/* requests to the FastAPI backend
  * - Builds to the Python module's frontend-build directory
+ * - Disables Vite's screen clearing on startup
  *
  * Options:
- *   paths - Array of paths to proxy (default: ["/api"])
+ *   paths - Array of paths to proxy (default: ['/api'])
  */
 
-export default function fastapiVue({ paths = ["/api"] } = {}) {
+export default function fastapiVue({ paths = ['/api'] } = {}) {
-  const backendUrl = process.env.PASKIA_BACKEND_URL || "http://localhost:4402"
+  const backendUrl = process.env.PASKIA_BACKEND_URL || 'http://localhost:4402'
 
   // Build proxy configuration for each path
   const proxy = {}
@@ -24,11 +25,12 @@ export default function fastapiVue({ paths = ["/api"] } = {}) {
   }
 
   return {
-    name: "vite-plugin-fastapi-paskia",
+    name: 'vite-plugin-fastapi-paskia',
     config: () => ({
+      clearScreen: false,
       server: { proxy },
       build: {
-        outDir: "../paskia/frontend-build",
+        outDir: '../paskia/frontend-build',
         emptyOutDir: true,
       },
     }),

frontend/vite.config.js

@@ -6,8 +6,12 @@ import { existsSync, renameSync, mkdirSync } from 'node:fs'
 import sirv from 'sirv'
 import fastapiVue from './vite-plugin-fastapi.js'
 
-// Auth host mode: when set, clients accessing the auth host get /auth/ at / and /auth/admin/ at /admin/
+// Auth host mode: when set, clients accessing an auth host get /auth/ at / and /auth/admin/ at /admin/
-const authHost = process.env.PASKIA_AUTH_HOST
+// Comma-separated list of bare hostnames (one per domain with a dedicated auth host)
+const authHosts = (process.env.PASKIA_AUTH_HOST || '')
+  .split(',')
+  .map(h => h.trim().replace(/^https?:\/\//, '').split(':')[0].split('/')[0])
+  .filter(Boolean)
 
 export default defineConfig(({ command }) => ({
   appType: 'mpa',
@@ -17,6 +21,7 @@ export default defineConfig(({ command }) => ({
       "/auth/api",
       "/auth/ws",
       "/.well-known/openid-configuration",
+      "/.well-known/webauthn",
       // Passphrase links: /auth/word1.word2.word3.word4.word5
       "^/auth/[a-z]+\\.[a-z]+\\.[a-z]+\\.[a-z]+\\.[a-z]+$",
       // Passphrase links: /word1.word2.word3.word4.word5
@@ -25,13 +30,13 @@ export default defineConfig(({ command }) => ({
     vue(),
     // Auth host routing: rewrite paths when accessing dedicated auth host
     // Must run before serve-examples to handle / correctly
-    authHost && {
+    authHosts.length && {
       name: 'auth-host-routing',
       configureServer(server) {
         server.middlewares.use((req, _res, next) => {
           const host = req.headers.host?.split(':')[0]
           // Check if request is coming to the auth host
-          if (host === authHost) {
+          if (authHosts.includes(host)) {
             // Only rewrite specific paths that should map to /auth/*
             // Rewrite / and /index.html to /auth/
             if (req.url === '/' || req.url === '/index.html') {
@@ -59,6 +64,14 @@ export default defineConfig(({ command }) => ({
         })
       }
     },
+    {
+      name: 'serve-paskia-js',
+      configureServer(server) {
+        // Serve the locally built paskia-js module for the examples page
+        const serve = sirv(resolve(__dirname, '../paskia-js'), { dev: true })
+        server.middlewares.use('/paskia-js', serve)
+      }
+    },
     {
       name: 'serve-examples',
       configureServer(server) {
@@ -67,7 +80,7 @@ export default defineConfig(({ command }) => ({
         server.middlewares.use((req, _res, next) => {
           // Skip redirect to examples on auth host (handled by auth-host-routing)
           const host = req.headers.host?.split(':')[0]
-          if (authHost && host === authHost) {
+          if (authHosts.includes(host)) {
             next()
             return
           }

oidc.md

@@ -2,11 +2,15 @@
 
 OpenID Connect 1.0 provider enabling third-party apps to authenticate users via passkey. Also supports native cookie-based authentication.
 
+## Domains (multi rp-id)
+
+The OIDC provider is instance-global: one signing key (`oidc.key` in the transaction log) and one client set for the whole instance, usable through every configured domain. Discovery, keys, token and userinfo endpoints resolve the issuer from the request host (domain dispatch), so every configured host is an issuer alias sharing the one key. `Session.issuer` records the issuing origin (scheme included, stamped from the WS Origin) so refresh and back-channel logout produce the right `iss`; `Session.rp_id` records the owning domain for display. `CookieCode` is stamped with the session's rp-id and verified at redemption; `OIDCCode` is not, since the provider is instance-global.
+
 ## Data Models
 
 **User** — Added: `email`, `preferred_username`
 
-**Session** — Added: `client_uuid` (None = native, set = OIDC)
+**Session** — Added: `client_uuid` (None = native, set = OIDC), `issuer` (origin that issued the session), `rp_id` (owning domain, display only)
 - `key: bytes` — hashed DB key, never stored raw
 - `secret` → `hash_secret("session", secret)` → DB lookup
 - OIDC `sid` → `base64url.encode(hash_secret("oidc", session.key))`
@@ -15,21 +19,24 @@ OpenID Connect 1.0 provider enabling third-party apps to authenticate users via
 
 ## Auth Codes (In-Memory Only)
 
-60-second lifetime, auto-cleaned:
+60-second lifetime, auto-cleaned. Two separate stores keep the OIDC and cookie flows isolated:
 
 ```python
-from paskia.authcode import AuthCode, OIDC, codes
+from paskia.authcode import CookieCode, OIDCCode, store_cookie, store_oidc
 
-class AuthCode(msgspec.Struct):
+class OIDCCode(msgspec.Struct):
     session_key: str       # Session DB key
     created: datetime
-    oidc: OIDC | None      # Only for OIDC mode
+    redirect_uri, scope: str
+    nonce, code_challenge: str | None   # PKCE S256 when provided
 
-class OIDC(msgspec.Struct):
+class CookieCode(msgspec.Struct):
-    redirect_uri, scope, nonce, code_challenge, code_challenge_method: str
+    session_key: str
+    created: datetime
+    rp_id: str             # domain the code was issued in; checked at redemption
 ```
 
-Usage: `code = authcode.store(AuthCode(...))` → later `codes.pop(code, None)`
+Usage: `code = store_oidc(OIDCCode(...))` → later popped from `oidc_codes` / `cookie_codes`.
 
 ## Authorization Flows
 
@@ -75,12 +82,18 @@ Discovery: `backchannel_logout_supported: true`
 - `GET /.well-known/openid-configuration` — Discovery
 - `GET /auth/oidc/keys` — Keys (EdDSA)
 - `POST /auth/oidc/token` — Exchange/refresh
-- `GET /auth/oidc/userinfo` — User (bearer token)
+- `GET /auth/oidc/userinfo` — User (bearer token, includes `picture` when `profile` scope is granted and avatar exists)
 - `POST /auth/oidc/backchannel-logout` — Logout
 - `POST /auth/api/exchange` — Native auth code → cookie
 
+## Claims
+
+- `profile` scope may include `name`, `preferred_username`, and `picture`
+- `email` scope may include `email`
+- `groups` is emitted from client-scoped permissions
+
 ## Files
 
 **Created:** [paskia/authcode.py](paskia/authcode.py), [paskia/util/crypto.py](paskia/util/crypto.py), [paskia/fastapi/oid.py](paskia/fastapi/oid.py)
 
-**Modified:** [paskia/db/structs.py](paskia/db/structs.py), [paskia/db/operations.py](paskia/db/operations.py), [paskia/fastapi/ws.py](paskia/fastapi/ws.py), [paskia/fastapi/api.py](paskia/fastapi/api.py), [paskia/globals.py](paskia/globals.py), [paskia/fastapi/mainapp.py](paskia/fastapi/mainapp.py)
+**Modified:** [paskia/db/structs.py](paskia/db/structs.py), [paskia/db/operations.py](paskia/db/operations.py), [paskia/fastapi/ws.py](paskia/fastapi/ws.py), [paskia/fastapi/api.py](paskia/fastapi/api.py), [paskia/domains.py](paskia/domains.py), [paskia/fastapi/mainapp.py](paskia/fastapi/mainapp.py)

paskia-js/README.md

@@ -1,14 +1,14 @@
-# Paskia
-
 ![Screenshot](https://git.zi.fi/leovasanko/paskia/raw/main/docs/screenshots/forbidden-light.webp)
 
-JavaScript utilities for [Paskia authentication system](https://git.zi.fi/leovasanko/paskia) integration into web apps.
+# Paskia
+
+JavaScript utilities for integrating the [Paskia authentication system](https://git.zi.fi/leovasanko/paskia) into web apps.
 
 ## Installation
 
-### NPM
+### npm
 
-No framework dependencies. Works with any framework (Vue, React, Svelte, etc.) or vanilla JS. Typescript typing included.
+No framework dependencies. Works with Vue, React, Svelte, vanilla JavaScript and other frontend stacks. TypeScript types are included.
 
 ```sh
 npm install paskia
@@ -20,7 +20,7 @@ import { ... } from 'paskia'
 
 ### Plain JavaScript
 
-Fetch the module directly from a CDN, or [download](https://cdn.jsdelivr.net/npm/paskia@latest/dist/paskia.js) first and host yourself. No Node needed.
+Import directly from a CDN, or [download](https://cdn.jsdelivr.net/npm/paskia@latest/dist/paskia.js) and host it yourself. No Node.js is required.
 
 ```html
 <script type="module">
@@ -28,67 +28,102 @@ Fetch the module directly from a CDN, or [download](https://cdn.jsdelivr.net/npm
 </script>
 ```
 
-## Features
+## Authentication
 
-### Session Validation
+### API requests
 
-Refresh session and track its validity with automatic polling. Pauses on lack of user activity to avoid useless traffic and to allow session expiry even when the page is left open but idle. This monitors that the same account stays logged in but doesn't do any permission checks.
+`apiFetch` wraps `fetch` with Paskia authentication handling, while `apiJson` adds automatic JSON request/response handling. Both support request timeouts. For the same JSON and timeout handling without prompting the user for authentication, use `fetchJson`.
+
+```js
+import { apiJson, apiFetch } from 'paskia'
+
+const data = await apiJson('/api/endpoint', {
+  method: 'POST',
+  body: { key: 'value' }
+})
+
+const response = await apiFetch('/api/endpoint')
+```
+
+With `apiJson`, a provided `body` is JSON-encoded with the appropriate content type and the response is parsed as JSON.
+
+When the server requests authentication, the API call pauses while the appropriate Paskia dialog is shown and retries after successful authentication.
+
+> Paskia uses `401` and `403` responses to trigger the appropriate **login**, **reauthentication** or **access denied** flow. The backend supplies the authentication URL and context; see the main Paskia documentation for the full response protocol.
+
+### Account and Profile
+
+`profile()` provides a single dialog for an application's login/profile button that allows the user to sign in, view who they are and sign out without ever leaving the page.
+
+```js
+import { profile } from 'paskia'
+
+const result = await profile()
+if (result !== 'back')  // Refresh application state
+```
+
+When signed out, it presents the login flow and returns `'login'` on success. When signed in, it shows the profile and returns `'logout'` after logout. `'back'` is returned when the dialog is closed without an expected session change.
+
+Authentication and profile dialogs follow the user's theme override when set in profile, otherwise the host page's light/dark `color-scheme` to remain in the application's color scheme, then the browser/OS preference.
+
+### Lower-level Authentication
+
+`apiFetch` and `apiJson` call `showAuthIframe()` internally. Applications using plain `fetch` or `fetchJson` can call it directly with an authentication URL returned by the backend:
+
+```js
+import { showAuthIframe } from 'paskia'
+
+await showAuthIframe(data.auth.iframe)
+```
+
+## Session Validation
+
+`SessionValidator` periodically checks that the active Paskia session is still valid and still belongs to the user your application currently has loaded. Validation also refreshes the session to avoid expiry during use.
 
 ```js
 import { SessionValidator } from 'paskia'
 
 const validator = new SessionValidator(
-  () => currentUser?.uuid,  // getter for current user ID that we track
+  () => currentUser?.uuid,  // User ID currently known by your app
-  (error) => handleSessionLost(error)  // callback when session is lost
+  error => handleSessionLost(error)
 )
 
-validator.start()  // call at your app startup/login
+validator.start()
-validator.stop()   // stop the system (optional)
+validator.stop()
 ```
 
-### API Fetch Utilities
+The first callback is read on each check, so a logout, expired session or switch to another account invalidates the session your app is currently using. Polling pauses while the user is inactive, avoiding unnecessary traffic and allowing idle sessions to expire.
 
-Enhanced fetch functions with automatic error handling and authentication retry:
+## Timeout Settings
+
+Paskia exports mutable defaults for network and session timers:
 
 ```js
-import { apiJson, apiFetch } from 'paskia'
+import { settings } from 'paskia'
 
-// JSON API calls with automatic auth handling
+settings.fetch_ms = 10000   // apiFetch, apiJson and fetchJson timeout
-const data = await apiJson('/api/endpoint', { method: 'POST', body: { key: 'value' } })
+settings.auth_ms = 1000     // Session validation request timeout
-
+settings.poll_ms = 60000    // Session validation interval
-// Raw fetch with auth handling
+settings.idle_ms = 300000   // Inactivity before validation pauses
-const response = await apiFetch('/api/endpoint')
 ```
 
-When a 401/403 response includes an auth iframe URL, the request automatically pauses, displays the authentication UI, and retries upon success. In case this is not needed, use standard `fetch` or our `fetchJson`.
+Request timeout can also be overridden per call:
-
-The JSON variants set headers automatically, with body and response in JSON.
-
-### Authentication Overlay
-
-Normally you use apiJson/apiFetch and they handle this automatically. If you need to wire it yourself, on a 401/403 response that includes `auth.iframe`, call `showAuthIframe(...)` and then retry the original request.
-
-The backend returns 401/403 responses with the correct URL for proper user feedback. Alternatively you may use `/auth/restricted/iframe#mode=login`, `mode=reauth` or `mode=forbidden` to trigger the UX flow you need.
 
 ```js
-import { showAuthIframe, AuthCancelledError } from 'paskia'
+await apiJson('/api/upload', {
-
+  method: 'POST',
-const response = await fetch('/api/protected')
+  body: data,
-if (response.status === 401 || response.status === 403) {
+  timeout: 30000
-  const data = await response.json()
+})
-  if (data.auth?.iframe) {
-    await showAuthIframe(data.auth.iframe)  // Raises AuthCancelledError if the user cancels
-  }
-}
 ```
 
-This resolves after the user authenticates (possibly with another account than previously), and you should usually retry the original API request. Note that successful authentication doesn't guarantee that the user still has rights to what originally failed.
+## Shared Blur Backdrop
 
-### Shared Blur Backdrop
+A shared backdrop provides consistent UX across your application, avoiding different things stacking with their own backdrops and dialogs in unexpected manner.
 
-The authentication dialog displays with a blur backdrop (z-index 1099). The auth iframe uses z-index 9999. Your app dialogs should use z-index 1100–9998 to appear above the backdrop but below authentication.
+Paskia dialogs use a shared blurred backdrop at z-index `1099` and the authentication iframe at `9999`. Application dialogs can use `1100`–`9998` to appear between them.
 
-The backdrop is also reusable/refcounted, so you can keep consistent visuals for your own dialogs:
+The same refcounted backdrop can be used by application UI:
 
 ```js
 import { holdGlobalBackdrop, releaseGlobalBackdrop } from 'paskia'
@@ -101,31 +136,26 @@ try {
 }
 ```
 
-The backdrop only disappears after all holders have released it.
+It disappears after all holders release it, also avoiding awkward fade/appear animations when changing between multiple dialogs.
 
 ## Error Handling
 
-### AuthCancelledError (apiFetch, apiJson, showAuthIframe)
+### `AuthCancelledError`
 
-If the user clicks Back in the authentication dialog, refusing to authenticate, `AuthCancelledError` is risen (as a response to postMessage from the iframe). The dialog closes as expected and it is up to the app how to continue from there.
+`apiFetch`, `apiJson` and `showAuthIframe` raise `AuthCancelledError` when the user cancels required authentication with Back or Escape. This means the user does not wish to authenticate, and should not be asked again.
 
-- Do nothing if the app can continue despite the failed operation (no UI notification needed)
+Continue without the failed operation when possible, or show an appropriate terminal view when authentication is required to continue.
-- Display a simple Access Denied page with suggestion/button to reload the page to try again
 
-Do not retry automatically.
+When the error is a direct result of a user action, we don't want to show an additional message for that, while in other situations we should. Helpers determine whether an error needs user notification and provide a suitable message:
-
-### UI feedback
-
-A set of small utilities are available for determining whether the user needs a notification and to format the error message.
 
 ```js
 import { getUserFriendlyErrorMessage, shouldShowErrorToast } from 'paskia'
 
 try {
   await apiJson('/api/action')
-} catch (e) {
+} catch (error) {
-  if (shouldShowErrorToast(e)) {
+  if (shouldShowErrorToast(error)) {
-    your.message.display(getUserFriendlyErrorMessage(e))
+    your.message.display(getUserFriendlyErrorMessage(error))
   }
 }
 ```

paskia-js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paskia",
-  "version": "1.1.0",
+  "version": "2.1.0",
   "description": "Paskia authentication utilities for JavaScript",
   "author": "Leo Vasanko",
   "license": "Unlicense",

paskia-js/src/fetch.ts

@@ -1,9 +1,8 @@
 import { showAuthIframe, AuthCancelledError } from './overlay'
+import settings from './settings'
 
 export { AuthCancelledError }
 
-const DEFAULT_TIMEOUT_MS = 1000
-
 export interface ApiFetchOptions extends RequestInit {
   timeout?: number
 }
@@ -40,7 +39,7 @@ export class NetworkError extends Error {
 }
 
 export async function apiFetch(url: string, options: ApiFetchOptions = {}): Promise<Response> {
-  const { timeout = DEFAULT_TIMEOUT_MS, ...fetchOptions } = options
+  const { timeout = settings.fetch_ms, ...fetchOptions } = options
   fetchOptions.credentials = fetchOptions.credentials || 'include'
 
   while (true) {

paskia-js/src/index.ts

@@ -12,12 +12,15 @@ export {
 
 export type { ApiFetchOptions, FetchJsonOptions } from './fetch'
 
+export { default as settings } from './settings'
+
 export {
   holdGlobalBackdrop,
   releaseGlobalBackdrop,
   isAuthIframeOpen,
   hideAuthIframe,
   showAuthIframe,
+  profile,
 } from './overlay'
 
 export { SessionValidator } from './validate'

paskia-js/src/overlay.ts

@@ -32,12 +32,27 @@ body.paskia-backdrop {
   color-scheme: auto;
   background: transparent;
 }
+#${AUTH_IFRAME_ID}.paskia-dialog {
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: min(36rem, 100%);
+  height: min(42rem, 100%);
+}
 `
 
+type DialogResult = 'login' | 'logout' | 'back'
+type DialogKind = 'auth' | 'profile'
+
 let authIframe: HTMLIFrameElement | null = null
-let authPromise: Promise<void> | null = null
+let authPromise: Promise<DialogResult | undefined> | null = null
-let authResolve: (() => void) | null = null
+let authResolve: ((result?: DialogResult) => void) | null = null
 let authReject: ((error: Error) => void) | null = null
+// Auth flows reject AuthCancelledError on auth-back (callers rely on it to
+// abort request retries) and resolve void on auth-success. The profile dialog
+// never rejects: auth-back resolves 'back', and auth-success (the user logged
+// in while the profile dialog was open) resolves 'login'.
+let dialogKind: DialogKind = 'auth'
 let messageListenerInstalled = false
 let backdropHolders = 0
 
@@ -89,7 +104,7 @@ function handleAuthMessage(event: MessageEvent): void {
     case 'auth-success':
       hideAuthIframe()
       if (authResolve) {
-        authResolve()
+        authResolve(dialogKind === 'profile' ? 'login' : undefined)
         authPromise = null
         authResolve = null
         authReject = null
@@ -98,8 +113,20 @@ function handleAuthMessage(event: MessageEvent): void {
 
     case 'auth-back':
       hideAuthIframe()
-      if (authReject) {
+      if (dialogKind === 'auth' && authReject) {
         authReject(new AuthCancelledError())
+      } else if (authResolve) {
+        authResolve('back')
+      }
+      authPromise = null
+      authResolve = null
+      authReject = null
+      break
+
+    case 'auth-logout':
+      hideAuthIframe()
+      if (authResolve) {
+        authResolve('logout')
         authPromise = null
         authResolve = null
         authReject = null
@@ -116,12 +143,15 @@ function ensureMessageListener(): void {
   }
 }
 
-export function showAuthIframe(iframeUrl: string, title = 'Authentication'): Promise<void> {
+function openIframe(iframeUrl: string, title: string, kind: DialogKind): Promise<DialogResult | undefined> {
   injectStyles()
   ensureMessageListener()
 
   if (authPromise) return authPromise
 
+  dialogKind = kind
+  iframeUrl = withAppTheme(iframeUrl)
+
   if (document.getElementById(AUTH_IFRAME_ID)) {
     authPromise = new Promise((resolve, reject) => {
       authResolve = resolve
@@ -140,6 +170,7 @@ export function showAuthIframe(iframeUrl: string, title = 'Authentication'): Pro
 
   authIframe = document.createElement('iframe')
   authIframe.id = AUTH_IFRAME_ID
+  if (kind === 'profile') authIframe.classList.add('paskia-dialog')
   authIframe.title = title
   authIframe.src = iframeUrl
   document.body.appendChild(authIframe)
@@ -147,6 +178,49 @@ export function showAuthIframe(iframeUrl: string, title = 'Authentication'): Pro
   return authPromise
 }
 
+// Detect the host page's own color scheme (CSS color-scheme on body) as an
+// implicit app-level default. Only an unambiguous 'light' or 'dark' counts;
+// 'normal', 'light dark' etc. mean the page adapts, so no override is needed.
+function detectColorScheme(): string {
+  if (typeof window === 'undefined' || !document.body) return ''
+  const scheme = getComputedStyle(document.body).colorScheme
+  return scheme === 'light' || scheme === 'dark' ? scheme : ''
+}
+
+// Apply the host page's own color scheme to the iframe URL hash — only when
+// the URL has no theme parameter yet (a server-provided user theme override
+// is authoritative). The restricted UI's precedence is: URL parameter (user
+// override from the server, else host color scheme) > cached profile theme
+// (localStorage) > browser/desktop default.
+function withAppTheme(iframeUrl: string): string {
+  const theme = detectColorScheme()
+  if (!theme) return iframeUrl
+  const hashIndex = iframeUrl.indexOf('#')
+  const base = hashIndex === -1 ? iframeUrl : iframeUrl.slice(0, hashIndex)
+  const params = new URLSearchParams(hashIndex === -1 ? '' : iframeUrl.slice(hashIndex + 1))
+  if (params.has('theme')) return iframeUrl
+  params.set('theme', theme)
+  return `${base}#${params}`
+}
+
+export function showAuthIframe(iframeUrl: string, title = 'Authentication'): Promise<void> {
+  return openIframe(iframeUrl, title, 'auth').then(() => undefined)
+}
+
+/**
+ * Show the minimal profile of the logged-in user in a compact dialog iframe.
+ *
+ * Unlike the auth flows, this always resolves — 'login' when the user was
+ * signed out and completed the login flow inside the frame, 'logout' when
+ * they signed out inside the frame, 'back' when they closed it otherwise.
+ * The caller decides from context how to react to each (e.g. whether to
+ * start a new login attempt with showAuthIframe).
+ */
+export function profile(): Promise<DialogResult> {
+  return openIframe('/auth/restricted/iframe#mode=profile', 'Profile', 'profile')
+    .then((result) => result ?? 'back')
+}
+
 export function createAuthIframe(iframeUrl: string, title = 'Authentication'): HTMLIFrameElement {
   injectStyles()
   const existing = document.getElementById(AUTH_IFRAME_ID)

paskia-js/src/settings.ts

@@ -0,0 +1,6 @@
+export default {
+  fetch_ms: 10000,
+  auth_ms: 1000,
+  poll_ms: 60000,
+  idle_ms: 300000,
+}

paskia-js/src/validate.ts

@@ -1,7 +1,5 @@
 import { apiJson } from './fetch'
-
+import settings from './settings'
-const POLL_INTERVAL = 60 * 1000
-const IDLE_TIMEOUT = 5 * 60 * 1000
 
 export class SessionValidator {
   private userUuidGetter: () => string | undefined
@@ -19,12 +17,12 @@ export class SessionValidator {
   resetIdleTimer(): void {
     if (this.idleTimer) clearTimeout(this.idleTimer)
     if (!this.active) this.startPolling()
-    this.idleTimer = setTimeout(() => this.stopPolling(), IDLE_TIMEOUT)
+    this.idleTimer = setTimeout(() => this.stopPolling(), settings.idle_ms)
   }
 
   async validate(): Promise<void> {
     try {
-      const data = await apiJson<{ ctx?: { user?: { uuid?: string } } }>('/auth/api/validate', { method: 'POST' })
+      const data = await apiJson<{ ctx?: { user?: { uuid?: string } } }>('/auth/api/validate', { method: 'POST', timeout: settings.auth_ms })
       const newUuid = data.ctx?.user?.uuid
       if (newUuid !== this.userUuidGetter()) {
         window.location.reload()
@@ -40,7 +38,7 @@ export class SessionValidator {
   startPolling(): void {
     if (this.active) return
     this.active = true
-    this.pollTimer = setInterval(() => this.validate(), POLL_INTERVAL)
+    this.pollTimer = setInterval(() => this.validate(), settings.poll_ms)
   }
 
   stopPolling(): void {

paskia/__main__.py

@@ -1,83 +1,48 @@
 import argparse
-import json
+import asyncio
 import logging
 import os
-from urllib.parse import urlparse
+import sys
+from pathlib import Path
 
-from fastapi_vue import server
+from fastapi_vue import env, server, teleport
-from fastapi_vue.hostutil import parse_endpoints
+from fastapi_vue.logging import setup_logging
+from kanta import Kanta
 
-from paskia.config import PaskiaConfig
+from paskia.db import legacy
-from paskia.db.jsonl import load_readonly
+from paskia.db.bootstrap import bootstrap, log_reset_link
-from paskia.util import startupbox
+from paskia.db.paths import db_file_path
-from paskia.util.hostutil import normalize_origin
+from paskia.db.structs import DB, Config, DomainConfig
+from paskia.domains import build as build_registry
+from paskia.domains import configure as configure_domains
+from paskia.domains import validate_config
+from paskia.util import hostutil, startupbox
+from paskia.util.runtime import serve_config
 
+# Keep the literal value here: fastapi-vue-setup reads DEFAULT_PORT from
+# this module on upgrades. The app-side shared copy is paskia.util.constants.
 DEFAULT_PORT = 4401
-DEVMODE = os.getenv("PASKIA_DEV") == "1"
+os.environ["FASTAPI_VUE"] = "PASKIA"
 
 EPILOG = """\
-Example:
+Examples:
-  paskia --rp-id example.com --rp-name "Example Corporation" --auth-host auth.example.com
+  paskia init example.com "Example Corporation"
+  paskia migrate example.com
+  paskia --listen 4402 --save
+  paskia
 """
 
 
-def is_subdomain(sub: str, domain: str) -> bool:
+def _split_multi(values: list[str] | None) -> list[str]:
-    """Check if sub is a subdomain of domain (or equal)."""
+    """Split repeatable/comma-separated CLI values into a flat list."""
-    sub_parts = sub.lower().split(".")
+    result = []
-    domain_parts = domain.lower().split(".")
+    for value in values or []:
-    if len(sub_parts) < len(domain_parts):
+        result.extend(part.strip() for part in value.split(",") if part.strip())
-        return False
+    return result
-    return sub_parts[-len(domain_parts) :] == domain_parts
 
 
-def validate_auth_host(auth_host: str, rp_id: str) -> None:
+def _add_listen_option(p: argparse.ArgumentParser, help_extra: str = "") -> None:
-    """Validate that auth_host is a subdomain of rp_id."""
-    parsed = urlparse(auth_host if "://" in auth_host else f"//{auth_host}")
-    host = parsed.hostname or parsed.path
-    if not host:
-        raise SystemExit(f"Invalid auth-host: '{auth_host}'")
-    if not is_subdomain(host, rp_id):
-        raise SystemExit(
-            f"auth-host '{auth_host}' is not a subdomain of rp-id '{rp_id}'"
-        )
-
-
-def add_common_options(p: argparse.ArgumentParser) -> None:
     p.add_argument(
-        "--rp-id", default="localhost", help="Relying Party ID (default: localhost)"
-    )
-    p.add_argument("--rp-name", help="Relying Party name (default: same as rp-id)")
-    p.add_argument(
-        "--origin",
-        action="append",
-        dest="origins",
-        default=[],
-        metavar="URL",
-        help="Allowed origin URL(s). May be specified multiple times. If any are specified, only those origins are permitted for WebSocket authentication.",
-    )
-    p.add_argument(
-        "--auth-host",
-        help=("Dedicated authentication site (optionally with scheme/port)"),
-    )
-    p.add_argument(
-        "--save",
-        action="store_true",
-        help="Save the CLI options to database for future runs.",
-    )
-
-
-def main():
-    # Configure logging to remove the "ERROR:root:" prefix
-    logging.basicConfig(level=logging.INFO, format="%(message)s", force=True)
-
-    parser = argparse.ArgumentParser(
-        prog="paskia",
-        description="Paskia authentication server",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog=EPILOG,
-    )
-
-    parser.add_argument(
         "-l",
         "--listen",
         action="append",
@@ -85,118 +50,269 @@ def main():
         help=(
             "Endpoint to listen on (default: localhost:4401). "
             "Forms: host:port  port  :port  [ipv6]:port  unix:path  /path.sock"
-        ),
         )
-    add_common_options(parser)
+        + help_extra,
-
-    args = parser.parse_args()
-
-    # Handle clearing options
-    if getattr(args, "auth_host", None) == "":
-        args.auth_host = None
-    if getattr(args, "rp_name", None) == "":
-        args.rp_name = None
-    if getattr(args, "listen", None) == "":
-        args.listen = None
-
-    # Read-only load to get stored config (no writes, no global state)
-    db_path = os.environ.get("PASKIA_DB", f"{args.rp_id}.paskiadb")
-    stored_db = load_readonly(db_path, rp_id=args.rp_id)
-    stored_config = stored_db.config
-
-    # Apply defaults from stored config
-    if args.rp_name is None and stored_config.rp_name is not None:
-        args.rp_name = stored_config.rp_name
-    if args.origins is None and stored_config.origins is not None:
-        args.origins = stored_config.origins
-    if args.auth_host is None and stored_config.auth_host is not None:
-        args.auth_host = stored_config.auth_host
-    if args.listen is None and stored_config.listen is not None:
-        args.listen = stored_config.listen
-
-    # Parse first endpoint for config display and site_url
-    ep = next(iter(parse_endpoints(args.listen, DEFAULT_PORT)), {})
-    host, port, uds = ep.get("host"), ep.get("port"), ep.get("uds")
-
-    # Process and normalize auth_host
-    if args.auth_host:
-        if "://" not in args.auth_host:
-            args.auth_host = f"https://{args.auth_host}"
-        args.auth_host = args.auth_host.rstrip("/")
-        validate_auth_host(args.auth_host, args.rp_id)
-        if args.origins:
-            args.origins.insert(0, args.auth_host)  # Ensure first in origins
-
-    # Normalize, strip trailing slashes, and deduplicate while preserving order
-    origins = list({normalize_origin(o).rstrip("/"): ... for o in (args.origins)})
-
-    # Compute site_url and site_path for reset links
-    # Priority: auth_host > first configured origin > PASKIA_VITE_URL (devserver) > http://localhost:port > https://rp_id
-    site_path = "/auth/"
-    if args.auth_host:
-        site_url = args.auth_host
-        site_path = "/"
-    elif origins:
-        # Find localhost origin if rp_id is localhost, else use first origin
-        localhost_origin = (
-            next((o for o in origins if "://localhost" in o), None)
-            if args.rp_id == "localhost"
-            else None
-        )
-        site_url = localhost_origin or origins[0]
-    elif vite_url := os.environ.get("PASKIA_VITE_URL"):
-        site_url = vite_url.rstrip("/")  # Devserver
-    elif args.rp_id == "localhost" and port:
-        site_url = f"http://localhost:{port}"  # Backend directly if we can
-    else:
-        site_url = f"https://{args.rp_id}"  # Assume external reverse proxy
-
-    # Build runtime configuration
-    config = PaskiaConfig(
-        rp_id=args.rp_id,
-        rp_name=args.rp_name or None,
-        origins=origins or None,
-        auth_host=args.auth_host or None,
-        site_url=site_url,
-        site_path=site_path,
-        host=host,
-        port=port,
-        uds=uds,
     )
 
-    # Export configuration via single JSON env variable for worker processes
-    # Include cli_config and save flag so lifespan can handle bootstrap/persistence
-    cli_config = {
-        "rp_id": args.rp_id,
-        "rp_name": args.rp_name,
-        "origins": args.origins,
-        "auth_host": args.auth_host,
-        "listen": args.listen,
-    }
-    config_json = {
-        "rp_id": config.rp_id,
-        "rp_name": config.rp_name,
-        "origins": config.origins,
-        "auth_host": config.auth_host,
-        "site_url": config.site_url,
-        "site_path": config.site_path,
-        "save": args.save,
-        "cli_config": cli_config,
-    }
-    os.environ["PASKIA_CONFIG"] = json.dumps(config_json)
 
-    startupbox.print_startup_config(config)
+def _load_stored_config(db_path: Path) -> Config:
+    """Load the stored Config from disk using Kanta in read-only mode.
 
-    dev = {"reload": True, "reload_dirs": ["paskia"]} if DEVMODE else {}
+    This must not depend on PASKIA_CONFIG or the global lifecycle Kanta.
+    Read-only opens never write or migrate the file.
+    """
+    kanta = Kanta(str(db_path), DB())
+
+    async def _read() -> Config:
+        await kanta.open(readonly=True)
+        try:
+            return kanta.data.config
+        finally:
+            await kanta.close()
+
+    try:
+        return asyncio.run(_read())
+    except Exception as e:
+        logging.exception("Failed to load database")
+        raise SystemExit(f"{e}") from e
+
+
+def _init_add_domain(db_path: Path, rp_id: str, rp_name: str | None, listen) -> None:
+    """Add a domain to an existing database, or update an existing one's
+    rp-name."""
+    new_db = DB()
+    kanta = Kanta(str(db_path), new_db)
+
+    async def _update() -> str:
+        await kanta.open()
+        try:
+            data = kanta.data
+            if rp_id in data.config.domains:
+                if rp_name is None and listen is None:
+                    raise SystemExit(f"Domain {rp_id} is already configured.")
+                with kanta.transaction("init:update_domain"):
+                    if rp_name is not None:
+                        data.config.domains[rp_id].rp_name = rp_name
+                    if listen is not None:
+                        data.config.listen = listen
+                return f"Updated domain {rp_id}"
+            new = DomainConfig(rp_name=rp_name, origins={f"**.{rp_id}": True})
+            try:
+                validate_config(
+                    Config(
+                        domains={**data.config.domains, rp_id: new},
+                        listen=data.config.listen,
+                    )
+                )
+            except ValueError as e:
+                raise SystemExit(str(e)) from e
+            with kanta.transaction("init:add_domain"):
+                data.config.domains[rp_id] = new
+                if listen is not None:
+                    data.config.listen = listen
+            return f"Added domain {rp_id}"
+        finally:
+            await kanta.close()
+
+    print(f"✅ {asyncio.run(_update())}")
+
+
+def cmd_init(args: argparse.Namespace) -> None:
+    """Bootstrap a new paskia.kantadb, or add a domain to an existing one."""
+    rp_id = (args.rp_id or "localhost").strip().lower()
+    rp_name = args.rp_name or None
+    listen = _split_multi(args.listen) or None
+    try:
+        hostutil.validate_rp_id(rp_id)
+    except ValueError as e:
+        raise SystemExit(str(e)) from e
+
+    db_path = db_file_path()
+    if db_path.exists():
+        _init_add_domain(db_path, rp_id, rp_name, listen)
+        return
+    if found := legacy.find_legacy_databases():
+        names = ", ".join(str(p) for p in found)
+        raise SystemExit(
+            f"Legacy database(s) found ({names}) — run 'paskia migrate' to "
+            "convert, not 'paskia init'."
+        )
+
+    # Only rp-id and rp-name are bootstrap-time configuration; the new
+    # domain starts with its whole subtree allowed ('**.{rp-id}') and
+    # everything else (origin allow-list, auth host, related domains) is
+    # set up afterwards via the admin interface. The bootstrap rp-name
+    # exists so the very first admin registration ceremony already shows
+    # the correct name.
+    config = Config(
+        domains={rp_id: DomainConfig(rp_name=rp_name, origins={f"**.{rp_id}": True})},
+        listen=listen,
+    )
+    try:
+        validate_config(config)
+    except ValueError as e:
+        raise SystemExit(str(e)) from e
+
+    # Create the database; the kanta bootstrap callback seeds it (admin
+    # user, org, permissions, reset token, the OIDC signing key).
+    new_db = DB()
+    kanta = Kanta(str(db_path), new_db)
+    result = {}
+
+    @kanta.bootstrap
+    def _bootstrap(data: DB) -> None:
+        result["passphrase"] = bootstrap(data, config=config)
+
+    async def _create() -> None:
+        async with kanta:
+            pass
+
+    try:
+        asyncio.run(_create())
+    except Exception as e:
+        logging.exception("Failed to create database")
+        db_path.unlink(missing_ok=True)
+        raise SystemExit(f"{e}") from e
+
+    configure_domains(listen=config.listen)
+    registry = build_registry(config)
+    log_reset_link(
+        registry.get(rp_id).reset_link_url(result["passphrase"]),
+        "✅ Bootstrap completed!",
+    )
+
+
+def cmd_migrate(args: argparse.Namespace) -> None:
+    """Convert or merge a legacy/current database into paskia.kantadb."""
+    merging = db_file_path().exists()
+    rp_ids = legacy.migrate_database(args.source)
+    action = "Merged into existing" if merging else "Converted to"
+    print(f"✅ {action} {db_file_path()} (domains: {', '.join(rp_ids)})")
+
+
+def _save_listen(db_path: Path, listen: list[str] | None) -> None:
+    """Persist the listen endpoints to the stored configuration."""
+    kanta = Kanta(str(db_path), DB())
+
+    async def _write() -> None:
+        async with kanta:
+            with kanta.transaction("serve:save_listen"):
+                kanta.data.config.listen = listen
+
+    asyncio.run(_write())
+
+
+def cmd_serve(args: argparse.Namespace) -> None:
+    """Open the combined database and serve all configured domains."""
+    db_path = db_file_path()
+    if not db_path.exists():
+        if found := legacy.find_legacy_databases():
+            names = ", ".join(str(p) for p in found)
+            raise SystemExit(
+                f"Database {db_path} not found, but legacy database(s) exist "
+                f"({names}) — run 'paskia migrate' to convert."
+            )
+        raise SystemExit(f"Database {db_path} not found — run 'paskia init' first.")
+
+    if args.save and args.listen is not None:
+        # '--listen ""' clears the stored endpoints (back to the default)
+        _save_listen(db_path, _split_multi(args.listen) or None)
+
+    config = _load_stored_config(db_path)
+
+    listen = _split_multi(args.listen) or config.listen
+    configure_domains(listen=listen)
+    try:
+        registry = build_registry(config)
+    except ValueError as e:
+        raise SystemExit(f"Invalid stored configuration: {e}") from e
+    # Sanitization warnings (serving is best-effort; fixing the stored config
+    # is the admin's job via the admin interface) are logged by build().
+
+    # Pass process-global serve parameters to the server process(es)
+    serve_config().listen = listen
+    teleport()  # Serialize bound config before spawning workers
+
+    startupbox.print_startup_config(registry, listen=listen, default_port=DEFAULT_PORT)
+
+    # Run the server (spawns processes in dev mode)
+    # tracerite, access logging and log config are handled by fastapi_vue.server;
+    # we print our own startup config box, so disable the built-in one.
     server.run(
         "paskia.fastapi.mainapp:app",
-        listen=args.listen,
+        listen=listen,
         default_port=DEFAULT_PORT,
-        log_level="warning",
+        server_header=False,
-        access_log=False,
+        startup_box=None,
-        **dev,
+        reload=Path(__file__).parent if env.dev else False,
     )
 
 
+def main():
+    # Full logging setup (tracerite, formatting) before any CLI output
+    setup_logging()
+
+    parser = argparse.ArgumentParser(
+        prog="paskia",
+        description="Paskia authentication server",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=EPILOG,
+    )
+    _add_listen_option(parser)
+    parser.add_argument(
+        "--save",
+        action="store_true",
+        help="Save --listen to the database for future runs. "
+        "Use --listen \"\" to clear the stored endpoints.",
+    )
+
+    init_parser = argparse.ArgumentParser(
+        prog="paskia init",
+        description="Bootstrap a new paskia.kantadb database in the current "
+        "directory. With an existing database, adds the domain to it instead "
+        "(or updates its rp-name).",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=EPILOG,
+    )
+    init_parser.add_argument(
+        "rp_id",
+        nargs="?",
+        help="Relying Party ID of the initial domain (default: localhost). "
+        "Further domains, origins and auth hosts are added via the admin "
+        "interface — or with another 'paskia init <rp-id>'.",
+    )
+    init_parser.add_argument(
+        "rp_name",
+        nargs="?",
+        help="Relying Party name of the domain (default: same as rp-id). "
+        "Used by the initial admin registration; editable later via admin UI.",
+    )
+    _add_listen_option(init_parser, help_extra=" (stored in the database)")
+
+    migrate_parser = argparse.ArgumentParser(
+        prog="paskia migrate",
+        description="Convert a legacy <rp-id>.paskiadb database to paskia.kantadb, "
+        "or merge a legacy database / another paskia.kantadb into an existing one",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    migrate_parser.add_argument(
+        "source",
+        nargs="?",
+        help="rp-id of the legacy database to convert, or path to a legacy "
+        "<rp-id>.paskiadb directory/file or a current-format paskia.kantadb "
+        "file. When paskia.kantadb already exists, the source data is merged "
+        "into it. Without an argument, a single legacy *.paskiadb candidate "
+        "in the current directory is selected automatically.",
+    )
+
+    argv = sys.argv[1:]
+    if argv and argv[0] == "init":
+        cmd_init(init_parser.parse_args(argv[1:]))
+    elif argv and argv[0] == "migrate":
+        cmd_migrate(migrate_parser.parse_args(argv[1:]))
+    else:
+        cmd_serve(parser.parse_args(argv))
+
+
 if __name__ == "__main__":
     main()

paskia/authcode.py

@@ -24,6 +24,8 @@ class OIDCCode(msgspec.Struct):
     """An OIDC authorization code pending token exchange.
 
     PKCE uses S256 only when provided (verified at token exchange).
+    Codes are redeemable at any host of the instance — the OIDC provider
+    is instance-global.
     """
 
     session_key: str
@@ -35,10 +37,17 @@ class OIDCCode(msgspec.Struct):
 
 
 class CookieCode(msgspec.Struct):
-    """A cookie exchange code for setting session cookie after WebSocket auth."""
+    """A cookie exchange code for setting session cookie after WebSocket auth.
+
+    rp_id binds the code to the domain it was issued in; the redemption
+    endpoint (dispatched by Host) must match. This is what allows a
+    remote-auth approver on one domain to mint a code for the requesting
+    device's domain without the code being usable on the wrong domain.
+    """
 
     session_key: str
     created: datetime
+    rp_id: str
 
 
 # Separate stores for each code type

paskia/authsession.py

@@ -23,6 +23,11 @@ if TYPE_CHECKING:
 EXPIRES = SESSION_LIFETIME
 
 
+def session_ctx(auth: str, host: str | None = None):
+    """Get session context with normalized host."""
+    return db.data().session_ctx(auth, hostutil.normalize_host(host))
+
+
 def expires() -> datetime:
     return datetime.now(UTC) + EXPIRES
 
@@ -31,7 +36,7 @@ def reset_expires() -> datetime:
     return datetime.now(UTC) + RESET_LIFETIME
 
 
-def get_reset(token: str) -> "ResetToken":
+def get_reset(token: str) -> ResetToken:
     """Validate a credential reset token."""
 
     record = ResetToken.by_passphrase(token)
@@ -42,7 +47,7 @@ def get_reset(token: str) -> "ResetToken":
 
 def delete_credential(credential_uuid: UUID, auth: str, host: str | None = None):
     """Delete a specific credential for the current user."""
-    ctx = db.data().session_ctx(auth, hostutil.normalize_host(host))
+    ctx = session_ctx(auth, host)
     if not ctx:
         raise ValueError("Session expired")
     db.delete_credential(credential_uuid, ctx.user.uuid)

paskia/bootstrap.py

@@ -1,56 +1,43 @@
 """
 Bootstrap module for passkey authentication system.
 
-This module handles initial system setup when a new database is created,
+The initial database seeding (admin user, organization, permissions,
-including creating default admin user, organization, permissions, and
+registration reset token) is performed by ``paskia init`` via
-generating a reset link for initial admin setup.
+:func:`paskia.db.bootstrap.bootstrap`. This module provides the serve-time
+check that re-prints a registration link when the admin user still has no
+passkey on any configured domain.
 """
 
 import logging
 
-from paskia import authsession, db
+from paskia import authsession, db, domains
-from paskia.db.structs import Config
+from paskia.db.bootstrap import log_reset_link
-from paskia.util import hostutil
 
 logger = logging.getLogger(__name__)
 
-# Shared log message template for admin reset links
+
-ADMIN_RESET_MESSAGE = """
+def _configure_logger() -> None:
-👤 Admin  %s
+    if logger.handlers:
-   - Use this link to register a Passkey for the admin user!
+        return
-"""
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    logger.propagate = False
 
 
-def _log_reset_link(passphrase: str, message: str | None = None) -> str:
+_configure_logger()
-    """Log a reset link message and return the URL."""
-    reset_link = hostutil.reset_link_url(passphrase)
-    if message:
-        logger.info(message)
-    logger.info(ADMIN_RESET_MESSAGE, reset_link)
-    return reset_link
-
-
-async def bootstrap_system(config: Config | None = None) -> None:
-    """
-    Bootstrap the entire system with default data.
-
-    Uses db.bootstrap() which performs all operations in a single transaction.
-    The transaction log will show a single "bootstrap" action with all changes.
-
-    Args:
-        config: Configuration to store (rp_id, rp_name, origins, etc.)
-    """
-    # Call the single-transaction bootstrap function
-    reset_passphrase = db.bootstrap(config=config)
-
-    # Log the reset link (this is separate from the transaction log)
-    _log_reset_link(reset_passphrase, "✅ Bootstrap completed!")
 
 
 async def check_admin_credentials() -> bool:
     """
     Check if the admin user needs credentials and create a reset link if needed.
 
+    With global users, the admin may hold passkeys under any configured
+    domain — the check passes if the admin has a credential for at least
+    one of them. Otherwise a reset link is printed for the first domain
+    (sorted by rp-id).
+
     Returns:
         bool: True if a reset link was created, False if admin already has credentials
     """
@@ -77,12 +64,15 @@ async def check_admin_credentials() -> bool:
         if not admin_users:
             return False
 
-        # Check first admin user for credentials
+        # Check first admin user for credentials on any configured domain
         admin_user = admin_users[0]
+        reg = domains.registry()
+        configured = sorted(d.rp_id for d in reg.domains)
 
-        if not admin_user.credential_ids:
+        if not any(admin_user.credential_ids_for(rp_id) for rp_id in configured):
-            # Admin exists but has no credentials, create reset link
+            # Admin exists but has no credential on any domain
-            logger.info("⚠️  Admin user has no credentials!")
+            target = reg.get(configured[0])
+            logger.info("⚠️  Admin user has no credentials on %s!", target.rp_id)
 
             expiry = authsession.reset_expires()
             token = db.create_reset_token(
@@ -90,7 +80,7 @@ async def check_admin_credentials() -> bool:
                 expiry=expiry,
                 token_type="admin registration",
             )
-            _log_reset_link(token)
+            log_reset_link(target.reset_link_url(token))
             return True
 
         return False
@@ -99,24 +89,11 @@ async def check_admin_credentials() -> bool:
         return False
 
 
-async def bootstrap_if_needed(config: Config | None = None) -> bool:
+async def bootstrap_if_needed() -> bool:
-    """
+    """Run the serve-time admin credential check.
-    Check if system needs bootstrapping and perform it if necessary.
-
-    Args:
-        config: Configuration to store during bootstrap (rp_id, rp_name, origins, etc.)
 
     Returns:
-        bool: True if bootstrapping was performed, False if system was already set up
+        bool: Always returns False (bootstrapping is performed by ``paskia init``).
     """
-    # Check if the admin permission exists - if it does, system is already bootstrapped
-    if any(p.scope == "auth:admin" for p in db.data().permissions.values()):
-        # Permission exists, system is already bootstrapped
-        # Check if admin needs credentials (only for already-bootstrapped systems)
     await check_admin_credentials()
     return False
-
-    # No admin permission found, need to bootstrap
-    # Bootstrap creates the admin user AND the reset link, so no need to check credentials after
-    await bootstrap_system(config=config)
-    return True

paskia/config.py

@@ -1,4 +1,3 @@
-from dataclasses import dataclass
 from datetime import timedelta
 
 # Shared configuration constants for session management.
@@ -6,19 +5,3 @@ SESSION_LIFETIME = timedelta(hours=24)
 
 # Lifetime for reset links created by admins
 RESET_LIFETIME = timedelta(days=14)
-
-
-@dataclass
-class PaskiaConfig:
-    """Runtime configuration for the Paskia authentication server."""
-
-    rp_id: str
-    rp_name: str | None
-    origins: list[str] | None
-    auth_host: str | None
-    site_url: str  # Base URL without trailing path (e.g. https://example.com)
-    site_path: str  # Path to auth UI: "/" if auth_host, else "/auth/"
-    # Listen address (one of host:port or uds)
-    host: str | None = None
-    port: int | None = None
-    uds: str | None = None

paskia/db/__init__.py

@@ -19,20 +19,13 @@ Usage:
 """
 
 import paskia.db.operations as operations
-from paskia.db.background import (
-    start_background,
-    start_cleanup,
-    stop_background,
-    stop_cleanup,
-)
 from paskia.db.bootstrap import bootstrap
-from paskia.db.jsonl import load_readonly
-from paskia.db.lifecycle import cleanup_expired, init
 from paskia.db.operations import (
     add_permission_to_org,
     add_permission_to_role,
     create_credential,
     create_credential_session,
+    create_domain,
     create_oid_client,
     create_org,
     create_permission,
@@ -40,10 +33,10 @@ from paskia.db.operations import (
     create_role,
     create_user,
     delete_credential,
+    delete_domain,
     delete_oid_client,
     delete_org,
     delete_permission,
-    delete_reset_token,
     delete_role,
     delete_session,
     delete_sessions_for_user,
@@ -54,9 +47,8 @@ from paskia.db.operations import (
     remove_permission_from_org,
     remove_permission_from_role,
     reset_oid_client_secret,
-    set_session_host,
-    update_config,
     update_credential_sign_count,
+    update_domain,
     update_oid_client,
     update_org_name,
     update_permission,
@@ -68,9 +60,11 @@ from paskia.db.operations import (
 )
 from paskia.db.structs import (
     DB,
+    OIDC,
     Client,
     Config,
     Credential,
+    DomainConfig,
     Org,
     Permission,
     ResetToken,
@@ -92,8 +86,10 @@ __all__ = [
     "Credential",
     "DB",
     "Client",
+    "OIDC",
     "Org",
     "Permission",
+    "DomainConfig",
     "ResetToken",
     "Role",
     "Session",
@@ -101,30 +97,23 @@ __all__ = [
     "User",
     # Instance
     "data",
-    "init",
-    "load_readonly",
-    # Background
-    "start_background",
-    "stop_background",
-    "start_cleanup",
-    "stop_cleanup",
     # Read ops
     # Write ops
     "add_permission_to_org",
     "add_permission_to_role",
     "bootstrap",
-    "cleanup_expired",
     "create_credential",
     "create_credential_session",
     "create_org",
     "create_permission",
+    "create_domain",
     "create_reset_token",
     "create_role",
     "create_user",
     "delete_credential",
     "delete_org",
     "delete_permission",
-    "delete_reset_token",
+    "delete_domain",
     "delete_role",
     "delete_session",
     "delete_sessions_for_user",
@@ -133,11 +122,10 @@ __all__ = [
     "oidc_login",
     "remove_permission_from_org",
     "remove_permission_from_role",
-    "set_session_host",
-    "update_config",
     "update_credential_sign_count",
     "update_org_name",
     "update_permission",
+    "update_domain",
     "update_role_name",
     "update_session",
     "update_user_display_name",

paskia/db/background.py

@@ -1,63 +1,38 @@
 """
 Background task for database maintenance.
 
-Periodically flushes pending changes to disk and cleans up expired items.
+Kanta handles periodic flushing to disk.  This module keeps a small
+companion task that periodically cleans up expired sessions/tokens.
 """
 
 import asyncio
 import logging
-from datetime import UTC, datetime
 
-import paskia.db.operations as _ops
 from paskia.db.lifecycle import cleanup_expired
 
-FLUSH_INTERVAL = 0.1  # Flush to disk
 CLEANUP_INTERVAL = 1  # Expired item cleanup
 
-
 _logger = logging.getLogger(__name__)
 _background_task: asyncio.Task | None = None
 
 
-async def flush() -> None:
-    """Write all pending database changes to disk."""
-    store = _ops._store
-    if store is None:
-        _logger.warning("flush() called but _store is None")
-        return
-    await store.flush()
-
-
 async def _background_loop():
-    """Background task that periodically flushes changes and cleans up."""
+    """Background task that periodically cleans up expired items."""
     # Run cleanup immediately on startup to clear old expired items
     cleanup_expired()
-    await flush()
-
-    last_cleanup = datetime.now(UTC)
 
     while True:
         try:
-            await asyncio.sleep(FLUSH_INTERVAL)
+            await asyncio.sleep(CLEANUP_INTERVAL)
-            # Flush pending changes to disk
-            await flush()
-
-            # Run cleanup periodically
-            now = datetime.now(UTC)
-            if (now - last_cleanup).total_seconds() >= CLEANUP_INTERVAL:
             cleanup_expired()
-                await flush()  # Flush cleanup changes
-                last_cleanup = now
         except asyncio.CancelledError:
-            # Final flush before exit
-            await flush()
             break
         except Exception:
             _logger.debug("Error in database background loop", exc_info=True)
 
 
 async def start_background():
-    """Start the background flush/cleanup task."""
+    """Start the background cleanup task."""
     global _background_task
 
     # Check if task exists but is no longer running (e.g., after uvicorn reload)
@@ -71,16 +46,15 @@ async def start_background():
                 # Check if task is in current event loop
                 loop = asyncio.get_running_loop()
                 task_loop = _background_task.get_loop()
-                if loop is not task_loop:
+                if loop is task_loop:
-                    _logger.debug("Background task in different event loop, restarting")
-                    _background_task = None
-                else:
                     # Task is already running in same loop - idempotent, just return
                     # This happens with dual IPv4+IPv6 endpoints sharing the same process
                     _logger.debug(
                         "Background task already running in same loop, skipping"
                     )
                     return
+                _logger.debug("Background task in different event loop, restarting")
+                _background_task = None
             except Exception as e:
                 _logger.debug("Error checking background task loop: %s, restarting", e)
                 _background_task = None
@@ -90,7 +64,7 @@ async def start_background():
 
 
 async def stop_background():
-    """Stop the background task, flush pending changes, and release the file lock."""
+    """Stop the background cleanup task."""
     global _background_task
     if _background_task:
         _background_task.cancel()
@@ -99,9 +73,3 @@ async def stop_background():
         except asyncio.CancelledError:
             pass
         _background_task = None
-    _ops._store.close()
-
-
-# Aliases for backwards compatibility
-start_cleanup = start_background
-stop_cleanup = stop_background

paskia/db/bootstrap.py

@@ -2,24 +2,58 @@
 Bootstrap operations for initial system setup.
 """
 
+import logging
+import sys
 from datetime import UTC, datetime
 
 import uuid7
 
-import paskia.db.operations as _ops
 from paskia.authsession import reset_expires
-from paskia.db.structs import Config, Org, Permission, ResetToken, Role, User
+from paskia.db.structs import DB, OIDC, Config, Org, Permission, ResetToken, Role, User
 from paskia.util.crypto import secret_key
 
+_reset_link_logger = logging.getLogger("paskia.reset_link")
+
+
+def _configure_reset_link_logger() -> None:
+    if _reset_link_logger.handlers:
+        return
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    _reset_link_logger.addHandler(handler)
+    _reset_link_logger.setLevel(logging.INFO)
+    _reset_link_logger.propagate = False
+
+
+_configure_reset_link_logger()
+
+ADMIN_RESET_MESSAGE = """
+👤 Admin  %s
+   - Use this link to register a Passkey for the admin user!
+"""
+
+
+def log_reset_link(url: str, message: str | None = None) -> str:
+    """Log a reset link message and return the URL."""
+    if message:
+        _reset_link_logger.info(message)
+    _reset_link_logger.info(ADMIN_RESET_MESSAGE, url)
+    return url
+
 
 def bootstrap(
+    data: DB,
     org_name: str = "Organization",
     admin_name: str = "Admin",
     reset_passphrase: str | None = None,
     reset_expiry: datetime | None = None,
     config: Config | None = None,
 ) -> str:
-    """Bootstrap the entire system in a single transaction.
+    """Bootstrap the entire system by seeding an empty database.
+
+    This is intended to be called from a ``@kanta.bootstrap`` callback during
+    ``kanta.open()``. It mutates the provided root ``data`` object directly;
+    kanta queues the resulting state as the initial "bootstrap" change record.
 
     Creates:
     - auth:admin permission (Master Admin)
@@ -29,10 +63,8 @@ def bootstrap(
     - Reset token for admin registration
     - Config (if provided)
 
-    This is the only way to create a new database file.
-    All data is created atomically - if any step fails, nothing is written.
-
     Args:
+        data: The live root database object (usually a ``DB`` instance).
         org_name: Display name for the organization (default: "Organization")
         admin_name: Display name for the admin user (default: "Admin")
         reset_passphrase: Passphrase for the reset token (generated if not provided)
@@ -44,7 +76,7 @@ def bootstrap(
     """
 
     # Check if system is already bootstrapped
-    for p in _ops._db.permissions.values():
+    for p in data.permissions.values():
         if p.scope == "auth:admin":
             raise ValueError(
                 "System already bootstrapped (auth:admin permission exists)"
@@ -62,7 +94,6 @@ def bootstrap(
     if reset_expiry is None:
         reset_expiry = reset_expires()
 
-    with _ops._db.transaction("bootstrap"):
     # Create auth:admin permission
     perm_admin = Permission(
         scope="auth:admin",
@@ -70,7 +101,6 @@ def bootstrap(
         orgs={org_uuid: True},  # Grant to org
     )
     perm_admin.uuid = perm_admin_uuid
-        perm_admin.store()
 
     # Create auth:org:admin permission
     perm_org_admin = Permission(
@@ -79,12 +109,10 @@ def bootstrap(
         orgs={org_uuid: True},  # Grant to org
     )
     perm_org_admin.uuid = perm_org_admin_uuid
-        perm_org_admin.store()
 
     # Create organization
     new_org = Org.create(display_name=org_name)
     new_org.uuid = org_uuid
-        new_org.store()
 
     # Create Administration role with both permissions
     admin_role = Role(
@@ -93,7 +121,6 @@ def bootstrap(
         permissions={perm_admin_uuid: True, perm_org_admin_uuid: True},
     )
     admin_role.uuid = role_uuid
-        admin_role.store()
 
     # Create admin user
     admin_user = User(
@@ -105,7 +132,6 @@ def bootstrap(
         theme="",
     )
     admin_user.uuid = user_uuid
-        admin_user.store()
 
     # Create reset token
     reset_token, reset_passphrase = ResetToken.create(
@@ -114,13 +140,20 @@ def bootstrap(
         token_type="admin bootstrap",
         passphrase=reset_passphrase,
     )
-        reset_token.store()
 
     # Set config if provided
     if config is not None:
-            _ops._db.config = config
+        data.config = config
 
-        # Generate OIDC signing key
+    # Generate the instance-global OIDC signing key
-        _ops._db.oidc.key = secret_key()
+    data.oidc = OIDC(key=secret_key())
+
+    # Store all bootstrapped objects in the live data object
+    data.permissions[perm_admin_uuid] = perm_admin
+    data.permissions[perm_org_admin_uuid] = perm_org_admin
+    data.orgs[org_uuid] = new_org
+    data.roles[role_uuid] = admin_role
+    data.users[user_uuid] = admin_user
+    data.reset_tokens[reset_token.key] = reset_token
 
     return reset_passphrase

paskia/db/filelock.py

@@ -1,247 +0,0 @@
-"""Cross-platform locked file for the database (no separate .lock files).
-
-Unix:    open() + fcntl.flock (advisory, cooperative among processes that flock).
-Windows: CreateFileW with FILE_SHARE_READ (OS-enforced, allows readers, blocks writers).
-
-A single file descriptor is opened once for both reading and writing.
-The lock is acquired atomically (on Windows) or immediately after open (on Unix),
-and the same descriptor is used for the lifetime of the process: first to read
-the existing content, then to append new writes.
-"""
-
-import logging
-import os
-import sys
-from pathlib import Path
-
-_logger = logging.getLogger(__name__)
-
-
-def _fatal(msg: str) -> None:
-    """Log a fatal error and exit immediately, bypassing exception handlers."""
-    _logger.critical(msg)
-    os._exit(1)
-
-
-if sys.platform == "win32":
-    import ctypes
-    from ctypes import wintypes
-
-    _kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
-
-    _GENERIC_READ = 0x80000000
-    _GENERIC_WRITE = 0x40000000
-    _FILE_SHARE_READ = 0x00000001
-    _OPEN_EXISTING = 3
-    _OPEN_ALWAYS = 4
-    _FILE_ATTRIBUTE_NORMAL = 0x80
-    _FILE_BEGIN = 0
-    _FILE_END = 2
-    _ERROR_SHARING_VIOLATION = 32
-    _INVALID_FILE_SIZE = 0xFFFFFFFF
-
-    _kernel32.CreateFileW.restype = wintypes.HANDLE
-    _kernel32.CreateFileW.argtypes = [
-        wintypes.LPCWSTR,
-        wintypes.DWORD,
-        wintypes.DWORD,
-        ctypes.c_void_p,
-        wintypes.DWORD,
-        wintypes.DWORD,
-        wintypes.HANDLE,
-    ]
-    _kernel32.ReadFile.restype = wintypes.BOOL
-    _kernel32.ReadFile.argtypes = [
-        wintypes.HANDLE,
-        ctypes.c_void_p,
-        wintypes.DWORD,
-        ctypes.POINTER(wintypes.DWORD),
-        ctypes.c_void_p,
-    ]
-    _kernel32.WriteFile.restype = wintypes.BOOL
-    _kernel32.WriteFile.argtypes = [
-        wintypes.HANDLE,
-        ctypes.c_void_p,
-        wintypes.DWORD,
-        ctypes.POINTER(wintypes.DWORD),
-        ctypes.c_void_p,
-    ]
-    _kernel32.GetFileSize.restype = wintypes.DWORD
-    _kernel32.GetFileSize.argtypes = [
-        wintypes.HANDLE,
-        ctypes.POINTER(wintypes.DWORD),
-    ]
-    _kernel32.SetFilePointer.restype = wintypes.DWORD
-    _kernel32.SetFilePointer.argtypes = [
-        wintypes.HANDLE,
-        wintypes.LONG,
-        ctypes.POINTER(wintypes.LONG),
-        wintypes.DWORD,
-    ]
-    _kernel32.CloseHandle.restype = wintypes.BOOL
-    _kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
-
-    def _is_invalid_handle(handle) -> bool:
-        return ctypes.c_void_p(handle).value == ctypes.c_void_p(-1).value
-
-else:
-    import fcntl
-
-
-class LockedFile:
-    """A file opened with an exclusive write lock.
-
-    Usage::
-
-        f = LockedFile()
-        f.open(path)          # open + lock (read+write)
-        content = f.read()    # read entire content
-        f.write(data)         # append data (seeks to end first)
-        f.close()             # release lock + close fd
-
-    Unix:    fcntl.flock (advisory) — read-only callers that don't flock are unaffected.
-    Windows: CreateFileW with FILE_SHARE_READ — OS blocks other writers.
-    """
-
-    def __init__(self) -> None:
-        self._fd: int | None = None  # Unix fd or Windows HANDLE
-
-    def open(self, path: Path, *, create: bool = False) -> None:
-        """Open *path* for read+write with an exclusive lock.
-
-        Args:
-            path:   File to open and lock.
-            create: If True, create the file if it doesn't exist (bootstrap).
-
-        Raises:
-            SystemExit: If the file is locked by another process or not found.
-        """
-        if self._fd is not None:
-            return  # Already open (idempotent)
-
-        if sys.platform == "win32":
-            self._open_win32(path, create)
-        else:
-            self._open_unix(path, create)
-
-    def open_and_read(self, path: Path) -> bytes:
-        """Open *path* with exclusive lock and read all content.
-
-        Combined operation for efficient use with asyncio.to_thread().
-        """
-        self.open(path)
-        return self.read()
-
-    def read(self) -> bytes:
-        """Read the entire file content from the beginning."""
-        if self._fd is None:
-            raise RuntimeError("LockedFile.read() called on a closed file")
-
-        if sys.platform == "win32":
-            return self._read_win32()
-        else:
-            return self._read_unix()
-
-    def write(self, data: bytes) -> None:
-        """Append *data* to the end of the file."""
-        if self._fd is None:
-            raise RuntimeError("LockedFile.write() called on a closed file")
-
-        if sys.platform == "win32":
-            self._write_win32(data)
-        else:
-            self._write_unix(data)
-
-    def close(self) -> None:
-        """Release the lock and close the file."""
-        if self._fd is None:
-            return
-        if sys.platform == "win32":
-            _kernel32.CloseHandle(self._fd)
-        else:
-            os.close(self._fd)
-        self._fd = None
-
-    @property
-    def is_open(self) -> bool:
-        return self._fd is not None
-
-    # -- Unix ----------------------------------------------------------------
-
-    def _open_unix(self, path: Path, create: bool) -> None:
-        flags = os.O_RDWR | (os.O_CREAT if create else 0)
-        try:
-            fd = os.open(path, flags, 0o666)
-        except FileNotFoundError:
-            _fatal(f"Database file not found: {path.resolve()}")
-        try:
-            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
-        except OSError:
-            os.close(fd)
-            _fatal(f"🛑 {path.resolve()}: database already locked by another instance")
-        self._fd = fd
-
-    def _read_unix(self) -> bytes:
-        os.lseek(self._fd, 0, os.SEEK_SET)
-        chunks = []
-        while True:
-            chunk = os.read(self._fd, 1 << 20)  # 1 MiB
-            if not chunk:
-                break
-            chunks.append(chunk)
-        return b"".join(chunks)
-
-    def _write_unix(self, data: bytes) -> None:
-        os.lseek(self._fd, 0, os.SEEK_END)
-        os.write(self._fd, data)
-
-    # -- Windows -------------------------------------------------------------
-
-    def _open_win32(self, path: Path, create: bool) -> None:
-        disposition = _OPEN_ALWAYS if create else _OPEN_EXISTING
-        handle = _kernel32.CreateFileW(
-            str(path),
-            _GENERIC_READ | _GENERIC_WRITE,
-            _FILE_SHARE_READ,
-            None,
-            disposition,
-            _FILE_ATTRIBUTE_NORMAL,
-            None,
-        )
-        if _is_invalid_handle(handle):
-            err = ctypes.get_last_error()
-            if err == _ERROR_SHARING_VIOLATION:
-                _fatal(
-                    f"🛑 {path.resolve()}: database already locked by another instance"
-                )
-            _fatal(f"Failed to open database {path.resolve()}: Windows error {err}")
-        self._fd = handle
-
-    def _read_win32(self) -> bytes:
-        _kernel32.SetFilePointer(self._fd, 0, None, _FILE_BEGIN)
-        size = _kernel32.GetFileSize(self._fd, None)
-        if size == _INVALID_FILE_SIZE:
-            raise OSError(
-                f"GetFileSize failed: Windows error {ctypes.get_last_error()}"
-            )
-        if size == 0:
-            return b""
-        buf = ctypes.create_string_buffer(size)
-        bytes_read = wintypes.DWORD()
-        ok = _kernel32.ReadFile(self._fd, buf, size, ctypes.byref(bytes_read), None)
-        if not ok:
-            raise OSError(f"ReadFile failed: Windows error {ctypes.get_last_error()}")
-        return buf.raw[: bytes_read.value]
-
-    def _write_win32(self, data: bytes) -> None:
-        _kernel32.SetFilePointer(self._fd, 0, None, _FILE_END)
-        written = wintypes.DWORD()
-        ok = _kernel32.WriteFile(
-            self._fd,
-            data,
-            len(data),
-            ctypes.byref(written),
-            None,
-        )
-        if not ok:
-            raise OSError(f"WriteFile failed: Windows error {ctypes.get_last_error()}")

paskia/db/jsonl.py

@@ -1,335 +0,0 @@
-"""
-JSONL persistence layer for the database.
-"""
-
-import asyncio
-import copy
-import logging
-import os
-import signal
-from collections import deque
-from contextlib import contextmanager
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import Any
-from uuid import UUID
-
-import jsondiff
-import msgspec
-
-from paskia.db.filelock import LockedFile
-from paskia.db.logging import log_change
-from paskia.db.migrations import (
-    DBVER,
-    MigrationCtx,
-    apply_all_migrations,
-    apply_migrations_readonly,
-)
-from paskia.db.structs import DB, Config, SessionContext
-
-_logger = logging.getLogger(__name__)
-
-# Default database path
-DB_PATH_DEFAULT = "paskia.jsonl"
-
-
-def load_readonly(db_path: str, *, rp_id: str = "localhost") -> DB:
-    """Replay JSONL and apply migrations to produce a DB, without writing anything.
-
-    This is suitable for reading settings before the server starts.
-    Migrations are applied in-memory only; nothing is queued or flushed.
-    """
-    path = Path(db_path)
-    if not path.exists():
-        return DB(config=Config(rp_id=rp_id))
-
-    data_dict: dict = {}
-    version = 0
-    try:
-        with open(path, "rb") as f:
-            content = f.read()
-        for line_num, line in enumerate(content.split(b"\n"), 1):
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                change = msgspec.json.decode(line)
-                data_dict = jsondiff.patch(data_dict, change["diff"], marshal=True)
-                version = change.get("v", 0)
-            except Exception as e:
-                raise ValueError(f"Error parsing line {line_num}: {e}")
-    except OSError as e:
-        raise SystemExit(f"Failed to load database: {e}")
-    except (ValueError, msgspec.DecodeError) as e:
-        raise SystemExit(f"Failed to load database: {e}")
-
-    if not data_dict:
-        return DB(config=Config(rp_id=rp_id))
-
-    # Apply migrations in-memory (no persistence)
-    apply_migrations_readonly(data_dict, version, MigrationCtx(rp_id=rp_id))
-
-    # Decode to msgspec struct
-    db = msgspec.json.decode(msgspec.json.encode(data_dict), type=DB)
-    return db
-
-
-class _ChangeRecord(msgspec.Struct, omit_defaults=True):
-    """A single change record in the JSONL file."""
-
-    ts: datetime
-    a: str  # action - describes the operation (e.g., "migrate", "login", "create_user")
-    v: int  # schema version after this change
-    u: str | None = None  # user UUID who performed the action (None for system)
-    diff: dict = {}
-
-
-# msgspec encoder for change records
-_change_encoder = msgspec.json.Encoder()
-
-
-def compute_diff(previous: dict, current: dict) -> dict | None:
-    """Compute JSON diff between two states.
-
-    Args:
-        previous: Previous state (JSON-compatible dict)
-        current: Current state (JSON-compatible dict)
-
-    Returns:
-        The diff, or None if no changes
-    """
-    diff = jsondiff.diff(previous, current, marshal=True)
-    return diff if diff else None
-
-
-def create_change_record(
-    action: str, version: int, diff: dict, user: str | None = None
-) -> _ChangeRecord:
-    """Create a change record for persistence."""
-    return _ChangeRecord(
-        ts=datetime.now(UTC),
-        a=action,
-        v=version,
-        u=user,
-        diff=diff,
-    )
-
-
-# Actions that are allowed to create a new database file
-_BOOTSTRAP_ACTIONS = frozenset({"bootstrap"})
-
-
-class JsonlStore:
-    """JSONL persistence layer for a DB instance."""
-
-    def __init__(self, db: DB, db_path: str = DB_PATH_DEFAULT):
-        self.db: DB = db
-        self.db_path = Path(db_path)
-        self._file = LockedFile()
-        self._flush_failed = False
-        self._previous_builtins: dict[str, Any] = {}
-        self._pending_changes: deque[_ChangeRecord] = deque()
-        self._current_action: str = "system"
-        self._current_user: str | None = None
-        self._in_transaction: bool = False
-        self._transaction_snapshot: dict[str, Any] | None = None
-        self._current_version: int = DBVER  # Schema version for new databases
-
-    async def load(
-        self, db_path: str | None = None, *, rp_id: str = "localhost"
-    ) -> None:
-        """Load data from JSONL change log."""
-        if db_path is not None:
-            self.db_path = Path(db_path)
-        self._rp_id = rp_id
-        if not self.db_path.exists():
-            return
-
-        # Open with exclusive write lock and read contents — single threadpool call
-        content = await asyncio.to_thread(self._file.open_and_read, self.db_path)
-
-        # Replay change log to reconstruct state
-        data_dict: dict = {}
-        try:
-            for line_num, line in enumerate(content.split(b"\n"), 1):
-                line = line.strip()
-                if not line:
-                    continue
-                try:
-                    change = msgspec.json.decode(line)
-                    data_dict = jsondiff.patch(data_dict, change["diff"], marshal=True)
-                    self._current_version = change.get("v", 0)
-                except Exception as e:
-                    raise ValueError(f"Error parsing line {line_num}: {e}")
-        except OSError as e:
-            raise SystemExit(f"Failed to load database: {e}")
-        except (ValueError, msgspec.DecodeError) as e:
-            raise SystemExit(f"Failed to load database: {e}")
-
-        if not data_dict:
-            return
-
-        # Set previous state for diffing (will be updated by _queue_change)
-        self._previous_builtins = copy.deepcopy(data_dict)
-
-        # Callback to persist each migration
-        async def persist_migration(
-            action: str, new_version: int, current: dict
-        ) -> None:
-            self._current_version = new_version
-            self._queue_change(action, new_version, current)
-
-        # Apply schema migrations one at a time
-        await apply_all_migrations(
-            data_dict,
-            self._current_version,
-            persist_migration,
-            MigrationCtx(rp_id=rp_id),
-        )
-
-        # Decode to msgspec struct
-        decoder = msgspec.json.Decoder(DB)
-        self.db = decoder.decode(msgspec.json.encode(data_dict))
-        self.db._store = self
-
-        # Normalize via msgspec round-trip (handles omit_defaults etc.)
-        # This ensures _previous_builtins matches what msgspec would produce
-        normalized_dict = msgspec.to_builtins(self.db)
-        await persist_migration(
-            "migrate:msgspec", self._current_version, normalized_dict
-        )
-
-    def _queue_change(
-        self, action: str, version: int, current: dict, user: str | None = None
-    ) -> None:
-        """Queue a change record and log it.
-
-        Args:
-            action: The action name for the change record
-            version: The schema version for the change record
-            current: The current state as a plain dict
-            user: Optional user UUID who performed the action
-        """
-        diff = compute_diff(self._previous_builtins, current)
-        if not diff:
-            return
-        self._pending_changes.append(create_change_record(action, version, diff, user))
-
-        # Log the change with user display name if available
-        user_display = None
-        if user:
-            try:
-                user_uuid = UUID(user)
-                if user_uuid in self.db.users:
-                    user_display = self.db.users[user_uuid].display_name
-            except (ValueError, KeyError):
-                user_display = user
-
-        log_change(action, diff, user_display, self._previous_builtins, self.db)
-        self._previous_builtins = copy.deepcopy(current)
-
-    @contextmanager
-    def transaction(
-        self,
-        action: str,
-        ctx: SessionContext | None = None,
-        *,
-        user: str | None = None,
-    ):
-        """Wrap writes in transaction. Queues change on successful exit.
-
-        Args:
-            action: Describes the operation (e.g., "Created user", "Login")
-            ctx: Session context of user performing the action (None for system operations)
-            user: User UUID string (alternative to ctx when full context unavailable)
-        """
-        if self._in_transaction:
-            raise RuntimeError("Nested transactions are not supported")
-
-        # Check for out-of-transaction modifications
-        current_state = msgspec.to_builtins(self.db)
-        if current_state != self._previous_builtins:
-            # Allow bootstrap to create a new database from empty state
-            is_bootstrap = action in _BOOTSTRAP_ACTIONS
-            if is_bootstrap and not self._previous_builtins:
-                pass  # Expected: creating database from scratch
-            else:
-                diff = compute_diff(self._previous_builtins, current_state)
-                diff_json = msgspec.json.encode(diff).decode()
-                _logger.critical(
-                    "Database state modified outside of transaction! "
-                    "This indicates a bug where DB changes occurred without a transaction wrapper.\n"
-                    f"Changes detected:\n{diff_json}"
-                )
-                raise SystemExit(1)
-
-        old_action = self._current_action
-        old_user = self._current_user
-        self._current_action = action
-        # Prefer ctx.user.uuid if ctx provided, otherwise use user param
-        self._current_user = str(ctx.user.uuid) if ctx else user
-        self._in_transaction = True
-        self._transaction_snapshot = current_state
-
-        try:
-            yield
-            current = msgspec.to_builtins(self.db)
-            self._queue_change(
-                self._current_action, self._current_version, current, self._current_user
-            )
-        except Exception:
-            # Rollback on error: restore from snapshot
-            _logger.warning("Transaction '%s' failed, rolling back changes", action)
-            if self._transaction_snapshot is not None:
-                decoder = msgspec.json.Decoder(DB)
-                self.db = decoder.decode(
-                    msgspec.json.encode(self._transaction_snapshot)
-                )
-                self.db._store = self
-            raise
-        finally:
-            self._current_action = old_action
-            self._current_user = old_user
-            self._in_transaction = False
-            self._transaction_snapshot = None
-
-    async def flush(self) -> None:
-        """Write all pending changes to disk.
-
-        On failure, logs an error and sends SIGTERM to trigger graceful shutdown.
-        """
-        if self._flush_failed or not self._pending_changes:
-            return
-
-        if not self._file.is_open:
-            first_action = self._pending_changes[0].a
-            if first_action not in _BOOTSTRAP_ACTIONS:
-                _logger.error(
-                    "Refusing to create database file with action '%s' - "
-                    "only bootstrap can create a new database",
-                    first_action,
-                )
-                self._flush_failed = True
-                os.kill(os.getpid(), signal.SIGTERM)
-                return
-            # Bootstrap: create and open the file with lock
-            await asyncio.to_thread(self._file.open, self.db_path, create=True)
-
-        changes_to_write = list(self._pending_changes)
-
-        try:
-            lines = [_change_encoder.encode(change) for change in changes_to_write]
-            if not lines:
-                self._pending_changes.clear()
-                return
-
-            await asyncio.to_thread(self._file.write, b"\n".join(lines) + b"\n")
-            self._pending_changes.clear()
-        except OSError as e:
-            _logger.error("Failed to flush database: %s", e)
-            self._flush_failed = True
-            os.kill(os.getpid(), signal.SIGTERM)
-
-    def close(self) -> None:
-        """Release the file lock and close the file."""
-        self._file.close()

paskia/db/legacy.py

@@ -0,0 +1,386 @@
+"""Legacy database format reader, converter and database merging.
+
+Retains the msgspec structs used by the old ``<rp-id>.paskiadb/main.db``
+format so existing databases can be opened and converted to the combined
+``paskia.kantadb`` format, and implements the merge of incoming data
+(legacy or current format) into an existing ``paskia.kantadb``. Only the
+structs whose shape differs from the current schema are redefined here;
+unchanged structs are imported from ``paskia.db.structs``.
+
+Assumes the on-disk records are in the latest legacy format (schema
+migrations were discarded together with the old format). The legacy
+structs will be deleted once legacy conversion is no longer supported.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+from datetime import datetime
+from pathlib import Path
+from uuid import UUID
+
+import msgspec
+from kanta import Kanta
+
+from paskia.db.paths import db_file_path, users_root_path
+from paskia.db.structs import (
+    DB,
+    OIDC,
+    Config,
+    Credential,
+    DomainConfig,
+    Org,
+    OriginEntry,
+    Permission,
+    ResetToken,
+    Role,
+    Session,
+    User,
+)
+
+
+class LegacyConfig(msgspec.Struct, omit_defaults=True):
+    """Pre-domains stored configuration (single rp-id per database)."""
+
+    rp_id: str
+    rp_name: str | None = None
+    auth_host: str | None = None
+    origins: list[str] | None = None
+    listen: list[str] | None = None
+
+
+class LegacyCredential(msgspec.Struct, dict=True):
+    """Credential without the rp_id stamp."""
+
+    credential_id: bytes
+    user_uuid: UUID = msgspec.field(name="user")
+    aaguid: UUID
+    public_key: bytes
+    sign_count: int
+    created_at: datetime
+    last_used: datetime | None = None
+    last_verified: datetime | None = None
+
+
+class LegacySession(msgspec.Struct, dict=True, omit_defaults=True):
+    """Session without the rp_id/issuer stamps."""
+
+    user_uuid: UUID = msgspec.field(name="user")
+    credential_uuid: UUID = msgspec.field(name="credential")
+    host: str
+    ip: str
+    user_agent: str
+    validated: datetime
+    client_uuid: UUID | None = msgspec.field(name="client", default=None)
+
+
+class LegacyDB(msgspec.Struct, dict=True, omit_defaults=False):
+    """Root structure of a legacy single-rp-id database."""
+
+    config: LegacyConfig = msgspec.field(
+        default_factory=lambda: LegacyConfig(rp_id="localhost")
+    )
+    permissions: dict[UUID, Permission] = {}
+    orgs: dict[UUID, Org] = {}
+    roles: dict[UUID, Role] = {}
+    users: dict[UUID, User] = {}
+    credentials: dict[UUID, LegacyCredential] = {}
+    sessions: dict[str, LegacySession] = {}
+    reset_tokens: dict[str, ResetToken] = {}
+    oidc: OIDC = msgspec.field(default_factory=OIDC)
+
+
+def _read_legacy(path: Path) -> LegacyDB:
+    """Open a legacy database read-only and return its contents."""
+    kanta = Kanta(str(path), LegacyDB())
+
+    async def _read() -> LegacyDB:
+        await kanta.open(readonly=True)
+        return kanta.data
+
+    return asyncio.run(_read())
+
+
+def _read_kantadb(path: Path) -> DB:
+    """Open a current-format database read-only and return its contents."""
+    kanta = Kanta(str(path), DB())
+
+    async def _read() -> DB:
+        await kanta.open(readonly=True)
+        return kanta.data
+
+    return asyncio.run(_read())
+
+
+def _legacy_to_db(old: LegacyDB) -> DB:
+    """Convert legacy database contents to the combined kantadb format.
+
+    All credentials and sessions are stamped with the legacy database's
+    rp-id; the OIDC provider carries over as-is (it is instance-global).
+    """
+    rp_id = old.config.rp_id
+
+    from paskia.domains import origin_key  # noqa: PLC0415  (import cycle)
+
+    origins: dict[str, bool | OriginEntry] = {}
+    for origin in old.config.origins or []:
+        origins[origin_key(origin)] = True
+    if old.config.auth_host:
+        origins[origin_key(old.config.auth_host)] = OriginEntry(auth_host=True)
+    if not old.config.origins:
+        # Legacy semantics: no origins configured = the whole rp-id domain
+        # allowed, regardless of a dedicated auth host. The new format
+        # requires explicit entries.
+        origins[f"**.{rp_id}"] = True
+
+    new_config = Config(
+        domains={rp_id: DomainConfig(rp_name=old.config.rp_name, origins=origins)},
+        listen=old.config.listen,
+    )
+
+    credentials = {
+        uuid: Credential(
+            credential_id=c.credential_id,
+            user_uuid=c.user_uuid,
+            aaguid=c.aaguid,
+            public_key=c.public_key,
+            sign_count=c.sign_count,
+            created_at=c.created_at,
+            rp_id=rp_id,
+            last_used=c.last_used,
+            last_verified=c.last_verified,
+        )
+        for uuid, c in old.credentials.items()
+    }
+    sessions = {
+        key: Session(
+            user_uuid=s.user_uuid,
+            credential_uuid=s.credential_uuid,
+            host=s.host,
+            ip=s.ip,
+            user_agent=s.user_agent,
+            validated=s.validated,
+            client_uuid=s.client_uuid,
+            rp_id=rp_id,
+        )
+        for key, s in old.sessions.items()
+    }
+
+    converted = DB(
+        config=new_config,
+        permissions=old.permissions,
+        orgs=old.orgs,
+        roles=old.roles,
+        users=old.users,
+        credentials=credentials,
+        sessions=sessions,
+        reset_tokens=old.reset_tokens,
+        oidc=old.oidc,
+    )
+    return converted
+
+
+def _migration_label(incoming: DB) -> str:
+    """Transaction label for a migration; multiple rp-ids join with slashes."""
+    return f"migrate:cli:{'/'.join(incoming.config.domains)}"
+
+
+def _write_fresh(data: DB, dst: Path, label: str) -> None:
+    """Write a fresh database at ``dst`` with the given contents."""
+    new_db = DB()
+    kanta = Kanta(str(dst), new_db)
+
+    @kanta.bootstrap(action=label)
+    def _seed(target: DB) -> None:
+        target.config = data.config
+        target.permissions = data.permissions
+        target.orgs = data.orgs
+        target.roles = data.roles
+        target.users = data.users
+        target.credentials = data.credentials
+        target.sessions = data.sessions
+        target.reset_tokens = data.reset_tokens
+        target.oidc = data.oidc
+
+    async def _write() -> None:
+        async with kanta:
+            pass
+
+    asyncio.run(_write())
+
+
+def convert_legacy_database(src: Path, dst: Path) -> Config:
+    """Convert a legacy main.db file into the combined kantadb format.
+
+    Reads the legacy database at ``src`` and writes a fresh database at
+    ``dst``. Returns the converted (new-format) configuration.
+    """
+    converted = _legacy_to_db(_read_legacy(src))
+    _write_fresh(converted, dst, _migration_label(converted))
+    return converted.config
+
+
+def _merge_data(data: DB, incoming: DB) -> None:
+    """Merge ``incoming`` contents into the live ``data`` object.
+
+    Records are uuid-keyed (or hash-keyed for sessions/reset tokens), so
+    identical keys denote the same item: existing entries win, new entries
+    are added. Domains merge per rp-id with a union of allowed origins;
+    the existing instance's listen endpoints and OIDC signing key win.
+    """
+    for rp_id, domain in incoming.config.domains.items():
+        existing = data.config.domains.get(rp_id)
+        if existing is None:
+            data.config.domains[rp_id] = domain
+            continue
+        for origin, entry in domain.origins.items():
+            existing.origins.setdefault(origin, entry)
+        if existing.rp_name is None:
+            existing.rp_name = domain.rp_name
+    for bucket in (
+        "permissions",
+        "orgs",
+        "roles",
+        "users",
+        "credentials",
+        "sessions",
+        "reset_tokens",
+    ):
+        target_map = getattr(data, bucket)
+        for key, value in getattr(incoming, bucket).items():
+            target_map.setdefault(key, value)
+    for uuid, client in incoming.oidc.clients.items():
+        data.oidc.clients.setdefault(uuid, client)
+    if data.oidc.key is None:
+        data.oidc.key = incoming.oidc.key
+
+
+def merge_database(dst: Path, incoming: DB) -> None:
+    """Merge ``incoming`` contents into the existing database at ``dst``."""
+    kanta = Kanta(str(dst), DB())
+
+    async def _merge() -> None:
+        async with kanta:
+            with kanta.transaction(_migration_label(incoming)):
+                _merge_data(kanta.data, incoming)
+
+    asyncio.run(_merge())
+
+
+def find_legacy_databases(cwd: Path | None = None) -> list[Path]:
+    """Find legacy ``*.paskiadb`` databases in a directory.
+
+    A candidate is either a directory containing ``main.db`` or a legacy
+    single-file database. Empty directories and non-matching files are
+    ignored.
+    """
+    cwd = cwd or Path.cwd()
+    candidates = []
+    for entry in sorted(cwd.glob("*.paskiadb")):
+        if entry.is_dir():
+            if (entry / "main.db").is_file():
+                candidates.append(entry)
+        elif entry.is_file():
+            candidates.append(entry)
+    return candidates
+
+
+def _resolve_source(source: str | None) -> tuple[Path, bool, Path, Path | None]:
+    """Resolve the migrate source.
+
+    ``source`` may be an rp-id (selecting ``<rp-id>.paskiadb`` in the
+    current directory), a path to a legacy ``*.paskiadb`` directory or
+    file, or a path to a current-format ``*.kantadb`` file. Without
+    ``source``, exactly one legacy candidate must exist in the current
+    directory.
+
+    Returns ``(db_file, is_legacy, users_dir, rename_target)`` where
+    ``users_dir`` holds auxiliary user files (avatars) and
+    ``rename_target`` is the legacy directory/file to rename aside after
+    a successful migration (None for current-format sources).
+    """
+
+    def legacy(src: Path) -> tuple[Path, bool, Path, Path]:
+        return (
+            src / "main.db" if src.is_dir() else src,
+            True,
+            src / "users" if src.is_dir() else src.parent / "users",
+            src,
+        )
+
+    if source is not None:
+        path = Path(source)
+        if path.is_dir():
+            if (path / "main.db").is_file():
+                return legacy(path)
+            raise SystemExit(f"No legacy main.db found in directory {path}.")
+        if path.is_file():
+            if path.suffix == ".paskiadb":
+                return legacy(path)
+            return path, False, path.parent / "paskia.data" / "users", None
+        # Not a path: treat as rp-id selecting a legacy candidate by name
+        name = f"{source}.paskiadb"
+        matches = [c for c in find_legacy_databases() if c.name == name]
+        if not matches:
+            found = ", ".join(str(c) for c in find_legacy_databases()) or "none"
+            raise SystemExit(
+                f"No legacy database {name} in this directory (candidates: {found})."
+            )
+        return legacy(matches[0])
+    candidates = find_legacy_databases()
+    if not candidates:
+        raise SystemExit("No legacy *.paskiadb database found — nothing to migrate.")
+    if len(candidates) > 1:
+        names = ", ".join(str(c) for c in candidates)
+        raise SystemExit(
+            f"Multiple legacy databases found ({names}) — select one with "
+            "'paskia migrate <rp-id>'."
+        )
+    return legacy(candidates[0])
+
+
+def _move_user_files(src_users: Path) -> None:
+    """Move persisted user files (avatars) to the new data root."""
+    if not src_users.is_dir():
+        return
+    target_users = users_root_path(create_root=True)
+    for child in src_users.iterdir():
+        if (target_users / child.name).exists():
+            continue
+        shutil.move(str(child), str(target_users / child.name))
+
+
+def migrate_database(source: str | None = None) -> list[str]:
+    """Convert or merge a database into ``paskia.kantadb``.
+
+    The source may be a legacy ``<rp-id>.paskiadb`` database (selected by
+    rp-id or path) or a current-format ``*.kantadb`` file given by path.
+    When ``paskia.kantadb`` already exists, the incoming data is merged
+    into it (uuid-keyed records make conflicts a non-issue); otherwise a
+    fresh database is written. Returns the migrated domains' rp-ids. A
+    migrated legacy source is renamed aside to ``<name>.converted-bak``
+    rather than deleted; a merged kantadb source is left in place.
+    """
+    target = db_file_path()
+    db_file, is_legacy, users_dir, rename_target = _resolve_source(source)
+    if db_file.resolve() == target.resolve():
+        raise SystemExit(f"{db_file} is the active database — nothing to migrate.")
+
+    incoming = (
+        _legacy_to_db(_read_legacy(db_file)) if is_legacy else _read_kantadb(db_file)
+    )
+    rp_ids = list(incoming.config.domains)
+
+    if target.exists():
+        merge_database(target, incoming)
+    else:
+        _write_fresh(incoming, target, _migration_label(incoming))
+
+    _move_user_files(users_dir)
+    if rename_target is not None and rename_target.exists():
+        shutil.move(
+            str(rename_target),
+            str(rename_target.with_name(rename_target.name + ".converted-bak")),
+        )
+    return rp_ids

paskia/db/lifecycle.py

@@ -2,43 +2,148 @@
 Database lifecycle: initialization and maintenance.
 """
 
+import asyncio
 import logging
 import os
+import re
+import signal
 from datetime import UTC, datetime
+from pathlib import Path
+from typing import Annotated, Any, Optional
+from uuid import UUID
+
+from kanta import Kanta
+from kanta.exceptions import DatabaseError
 
 import paskia.db.operations as _ops
 from paskia import oidc_notify
 from paskia.authsession import EXPIRES
+from paskia.db.paths import db_file_path
 
-_logger = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
+
+# The combined database lives at a fixed CWD-relative path; no runtime
+# configuration is needed to locate it.
+kanta = Kanta(str(db_file_path()), _ops._db)
+_ops._db._store = kanta
 
 
-async def init(rp_id: str = "localhost", *args, **kwargs):
+def _lookup_uuid_in_state(state: dict | None, uuid_str: str) -> str | None:
-    """Load database from JSONL file."""
+    """Resolve UUID to label from serialized state dict."""
-    if _ops._initialized:
+    if not state:
-        _logger.debug("Database already initialized, skipping reload")
+        return None
-        return
+
-    default_path = f"{rp_id}.paskiadb"
+    # Display-name based entities.
-    db_path = os.environ.get("PASKIA_DB", default_path)
+    for bucket in ("users", "orgs", "roles", "permissions"):
-    await _ops._store.load(db_path, rp_id=rp_id)
+        entity = state.get(bucket, {}).get(uuid_str)
-    _ops._db = _ops._store.db
+        if isinstance(entity, dict):
-    _ops._initialized = True
+            display_name = entity.get("display_name")
+            if isinstance(display_name, str) and display_name:
+                return display_name
+
+    # OIDC clients use "name" instead of "display_name".
+    oidc_state = state.get("oidc", {})
+    if isinstance(oidc_state, dict):
+        client = oidc_state.get("clients", {}).get(uuid_str)
+        if isinstance(client, dict):
+            name = client.get("name")
+            if isinstance(name, str) and name:
+                return name
+
+    return None
+
+
+def _resolve_uuid_label(
+    uuid_str: str,
+    *,
+    previous: dict | None = None,
+    current: dict | None = None,
+) -> str | None:
+    """Resolve known entity UUIDs to human-readable labels."""
+    # Prefer previous state so deletions/renames still show a useful label.
+    label = _lookup_uuid_in_state(previous, uuid_str)
+    if label:
+        return label
+    label = _lookup_uuid_in_state(current, uuid_str)
+    if label:
+        return label
+
+    try:
+        uid = UUID(uuid_str)
+    except ValueError:
+        return None
+
+    if uid in _ops._db.users:
+        return _ops._db.users[uid].display_name
+    if uid in _ops._db.orgs:
+        return _ops._db.orgs[uid].display_name
+    if uid in _ops._db.roles:
+        return _ops._db.roles[uid].display_name
+    if uid in _ops._db.permissions:
+        return _ops._db.permissions[uid].display_name
+    if uid in _ops._db.oidc.clients:
+        return _ops._db.oidc.clients[uid].name
+    return None
+
+
+# The OIDC signing key is stored at oidc.key.
+_OIDC_KEY_PATH = re.compile(r"^oidc\.key$")
+
+
+@kanta.logfmt
+def format_log_uuid(
+    value: Any,
+    path: str,
+    previous: Annotated[dict, "pre"] | None = None,
+    current: Annotated[dict, "post"] | None = None,
+) -> Optional[str]:  # noqa: UP045
+    """Format UUID values/keys/actor labels and censor secrets in transaction logs."""
+    # Censor sensitive OIDC key material regardless of value type, but only
+    # when formatting the value: path components are passed with the component
+    # itself as value and must stay visible ("oidc.key = <hidden>").
+    if _OIDC_KEY_PATH.fullmatch(path) and value != "key":
+        return "<hidden>"
+
+    if not isinstance(value, str):
+        return None
+
+    # Works for transaction actor metadata ($user), values, and path components.
+    return _resolve_uuid_label(value, previous=previous, current=current)
+
+
+@kanta.fatal_error
+def terminate(error: DatabaseError) -> None:
+    """Fatal error callback: terminate the process on background write failures."""
+    logger.error("Fatal database error: %s", error)
+    os.kill(os.getpid(), signal.SIGTERM)
+
+
+async def init():
+    """Load database from JSONL file using kanta.
+
+    The database must already exist and be initialized (see ``paskia
+    init``); the serve command's startup checks guarantee this before the
+    lifespan runs.
+    """
+    rootpath = Path(kanta.filename).parent
+    try:
+        await asyncio.to_thread(rootpath.mkdir, parents=True, exist_ok=True)
+        await kanta.open()
+    except Exception as e:
+        raise SystemExit(f"{e}") from e
 
 
 def cleanup_expired() -> int:
     """Remove expired sessions and reset tokens. Returns count removed."""
     now = datetime.now(UTC)
-    count = 0
     limit = now - EXPIRES
     expired_sessions = [k for k, s in _ops._db.sessions.items() if s.validated < limit]
     if expired_sessions:
         oidc_notify.schedule_notifications(expired_sessions)
-    with _ops._db.transaction("expiry"):
+    with kanta.transaction("expiry"):
         for k in expired_sessions:
             del _ops._db.sessions[k]
-            count += 1
         expired_tokens = [k for k, t in _ops._db.reset_tokens.items() if t.expiry < now]
         for k in expired_tokens:
             del _ops._db.reset_tokens[k]
-            count += 1
+    return len(expired_sessions) + len(expired_tokens)
-    return count

paskia/db/logging.py

@@ -1,466 +0,0 @@
-"""
-Database change logging with pretty-printed diffs.
-
-Provides a logger for JSONL database changes that formats diffs
-in a human-readable path.notation style with color coding.
-
-UUIDs are replaced with display names where available, or the full UUID string
-for types without display names.
-"""
-
-import logging
-import re
-import sys
-from typing import TYPE_CHECKING, Any
-from uuid import UUID
-
-if TYPE_CHECKING:
-    from paskia.db.structs import DB
-
-logger = logging.getLogger("paskia.db")
-
-# UUID regex pattern (8-4-4-4-12 hex format)
-_UUID_PATTERN = re.compile(
-    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
-)
-
-# Pattern to match control characters and bidirectional overrides
-_UNSAFE_CHARS = re.compile(
-    r"[\x00-\x1f\x7f-\x9f"  # C0 and C1 control characters
-    r"\u200e\u200f"  # LRM, RLM
-    r"\u202a-\u202e"  # LRE, RLE, PDF, LRO, RLO
-    r"\u2066-\u2069"  # LRI, RLI, FSI, PDI
-    r"]"
-)
-
-# ANSI color codes (matching FastAPI logging style)
-_RESET = "\033[0m"
-_DIM = "\033[2m"
-_PATH_PREFIX = "\033[1;30m"  # Dark grey for path prefix (like host in access log)
-_PATH_FINAL = "\033[0m"  # Default for final element (like path in access log)
-_DELETE = "\033[1;31m"  # Red for deletions
-_ADD = "\033[0;32m"  # Green for additions
-_ACTION = "\033[1;34m"  # Bold blue for action name
-_USER = "\033[0;34m"  # Blue for user display
-
-
-def _is_uuid(value: str) -> bool:
-    """Check if a string is a UUID."""
-    return bool(_UUID_PATTERN.match(value))
-
-
-class UuidResolver:
-    """Resolve UUIDs to display names or short suffixes.
-
-    Uses the previous state for lookups to show the name before any changes.
-    """
-
-    def __init__(self, db: "DB | None" = None, previous: dict | None = None):
-        self._db = db
-        self._previous = previous
-
-    def resolve(self, uuid_str: str) -> str:
-        """Resolve a UUID to its display name or the full UUID string."""
-        display = self._get_display_name(uuid_str)
-        if display:
-            return display
-        return uuid_str
-
-    def _get_display_name(self, uuid_str: str) -> str | None:
-        """Look up display name for a UUID.
-
-        First checks the previous state (to show names before changes),
-        then falls back to the current database.
-        """
-        # Try previous state first (for showing name before a change)
-        name = self._lookup_in_previous(uuid_str)
-        if name:
-            return name
-
-        # Fall back to current database
-        return self._lookup_in_db(uuid_str)
-
-    def _lookup_in_previous(self, uuid_str: str) -> str | None:
-        """Look up display name in the previous state dict."""
-        if not self._previous:
-            return None
-
-        # Check users
-        if "users" in self._previous and uuid_str in self._previous["users"]:
-            user_data = self._previous["users"][uuid_str]
-            if isinstance(user_data, dict) and "display_name" in user_data:
-                return user_data["display_name"]
-
-        # Check orgs
-        if "orgs" in self._previous and uuid_str in self._previous["orgs"]:
-            org_data = self._previous["orgs"][uuid_str]
-            if isinstance(org_data, dict) and "display_name" in org_data:
-                return org_data["display_name"]
-
-        # Check roles
-        if "roles" in self._previous and uuid_str in self._previous["roles"]:
-            role_data = self._previous["roles"][uuid_str]
-            if isinstance(role_data, dict) and "display_name" in role_data:
-                return role_data["display_name"]
-
-        # Check permissions
-        if (
-            "permissions" in self._previous
-            and uuid_str in self._previous["permissions"]
-        ):
-            perm_data = self._previous["permissions"][uuid_str]
-            if isinstance(perm_data, dict) and "display_name" in perm_data:
-                return perm_data["display_name"]
-
-        return None
-
-    def _lookup_in_db(self, uuid_str: str) -> str | None:
-        """Look up display name in the current database."""
-        if not self._db:
-            return None
-
-        try:
-            uuid_obj = UUID(uuid_str)
-        except ValueError:
-            return None
-
-        # Check users
-        if uuid_obj in self._db.users:
-            return self._db.users[uuid_obj].display_name
-
-        # Check orgs
-        if uuid_obj in self._db.orgs:
-            return self._db.orgs[uuid_obj].display_name
-
-        # Check roles
-        if uuid_obj in self._db.roles:
-            return self._db.roles[uuid_obj].display_name
-
-        # Check permissions
-        if uuid_obj in self._db.permissions:
-            return self._db.permissions[uuid_obj].display_name
-
-        return None
-
-
-def _format_value(
-    value: Any,
-    max_len: int = 60,
-    resolver: UuidResolver | None = None,
-) -> str:
-    """Format a value for display, truncating if needed.
-
-    If resolver is provided, UUIDs are replaced with display names or short suffixes.
-    """
-    if value is None:
-        return "null"
-
-    if isinstance(value, bool):
-        return "true" if value else "false"
-
-    if isinstance(value, (int, float)):
-        return str(value)
-
-    if isinstance(value, str):
-        # Check if it's a UUID and resolve to display name
-        if resolver and _is_uuid(value):
-            return resolver.resolve(value)
-        # Filter out control characters and bidirectional overrides
-        value = _UNSAFE_CHARS.sub("", value)
-        # Truncate long strings
-        if len(value) > max_len:
-            return value[: max_len - 3] + "..."
-        return value
-
-    if isinstance(value, dict):
-        if not value:
-            return "{}"
-        # Check if all values are True - render as set-like {key1, key2}
-        all_true = all(v is True for v in value.values())
-        parts = []
-        for k, v in value.items():
-            # Replace UUID keys with display names
-            key_display = resolver.resolve(k) if resolver and _is_uuid(k) else k
-            if all_true:
-                parts.append(key_display)
-            else:
-                val_display = _format_value(v, max_len=30, resolver=resolver)
-                parts.append(f"{key_display}: {val_display}")
-        return "{" + ", ".join(parts) + "}"
-
-    if isinstance(value, list):
-        if not value:
-            return "[]"
-        parts = [_format_value(v, max_len=30, resolver=resolver) for v in value]
-        return "[" + ", ".join(parts) + "]"
-
-    # Fallback for other types
-    text = str(value)
-    if len(text) > max_len:
-        text = text[: max_len - 3] + "..."
-    return text
-
-
-def _format_path(path: list[str], resolver: UuidResolver | None = None) -> str:
-    """Format a path as dot notation with prefix in dark grey, final in default.
-
-    If resolver is provided, UUIDs in the path are replaced with display names.
-    """
-    if not path:
-        return ""
-
-    # Replace UUIDs in path with display names
-    if resolver:
-        path = [resolver.resolve(p) if _is_uuid(p) else p for p in path]
-
-    if len(path) == 1:
-        return f"{_PATH_FINAL}{path[0]}{_RESET}"
-    prefix = ".".join(path[:-1])
-    final = path[-1]
-    return f"{_PATH_PREFIX}{prefix}.{_RESET}{_PATH_FINAL}{final}{_RESET}"
-
-
-def _get_nested(data: dict | None, path: list[str]) -> Any:
-    """Get a nested value from a dict by path, or None if not found."""
-    if data is None:
-        return None
-    current = data
-    for key in path:
-        if not isinstance(current, dict) or key not in current:
-            return None
-        current = current[key]
-    return current
-
-
-def _collect_changes(
-    diff: dict,
-    path: list[str],
-    changes: list[tuple[str, list[str], Any]],
-    previous: dict | None,
-) -> None:
-    """
-    Recursively collect changes from a diff into a flat list.
-
-    Each change is a tuple of (change_type, path, new_value).
-    change_type is one of: 'add', 'update', 'delete'
-    """
-    if not isinstance(diff, dict):
-        # Leaf value - check if it existed before
-        existed = _get_nested(previous, path) is not None
-        changes.append(("update" if existed else "add", path, diff))
-        return
-
-    for key, value in diff.items():
-        if key == "$delete":
-            # $delete contains a list of keys to delete
-            if isinstance(value, list):
-                for deleted_key in value:
-                    changes.append(("delete", path + [str(deleted_key)], None))
-            else:
-                changes.append(("delete", path + [str(value)], None))
-
-        elif key == "$replace":
-            # $replace replaces the entire collection at this path
-            # We need to track what was added and what was deleted
-            old_collection = _get_nested(previous, path)
-            old_keys = (
-                set(old_collection.keys())
-                if isinstance(old_collection, dict)
-                else set()
-            )
-            new_keys = set(value.keys()) if isinstance(value, dict) else set()
-
-            # Items that existed before but not in new = deleted
-            for deleted_key in old_keys - new_keys:
-                changes.append(("delete", path + [str(deleted_key)], None))
-
-            # Items in new collection
-            if isinstance(value, dict):
-                for rkey, rval in value.items():
-                    existed = rkey in old_keys
-                    changes.append(
-                        ("update" if existed else "add", path + [str(rkey)], rval)
-                    )
-            elif value or not old_keys:
-                # Non-dict replacement or empty replacement with nothing before
-                changes.append(
-                    ("update" if old_collection is not None else "add", path, value)
-                )
-
-        elif key.startswith("$"):
-            # Other special operations (future-proofing)
-            changes.append(("add", path, {key: value}))
-
-        else:
-            # Regular nested key - check if this item existed before
-            new_path = path + [str(key)]
-            existed = _get_nested(previous, new_path) is not None
-            if existed:
-                # Item exists - recurse to show specific field changes
-                _collect_changes(value, new_path, changes, previous)
-            else:
-                # New item - record as add with full value, don't recurse
-                changes.append(("add", new_path, value))
-
-
-def _format_change_lines(
-    change_type: str,
-    path: list[str],
-    value: Any,
-    resolver: UuidResolver | None = None,
-) -> list[str]:
-    """Format a single change as one or more lines.
-
-    If resolver is provided, UUIDs are replaced with display names.
-    """
-
-    # Helper to format a value, checking for censored paths
-    def fmt_value(v: Any, child_path: list[str]) -> str:
-        if child_path[-2:] == ["oidc", "key"]:
-            return f"{_DIM}<hidden>{_RESET}"
-        return _format_value(v, resolver=resolver)
-
-    # Helper to format path with UUID replacement
-    def fmt_path(p: list[str]) -> list[str]:
-        if resolver:
-            return [resolver.resolve(x) if _is_uuid(x) else x for x in p]
-        return p
-
-    formatted_path = fmt_path(path)
-
-    if change_type == "delete":
-        if len(formatted_path) == 1:
-            return [f"  {_DELETE}{formatted_path[0]} ✗{_RESET}"]
-        prefix = ".".join(formatted_path[:-1])
-        final = formatted_path[-1]
-        return [f"  {_PATH_PREFIX}{prefix}.{_RESET}{_DELETE}{final} ✗{_RESET}"]
-
-    if change_type == "add":
-        # New item being created - only final element in green
-        # For dict values, show children on separate indented lines
-        if isinstance(value, dict) and value:
-            lines = []
-            # First line: path with green final element and grey =
-            if len(formatted_path) == 1:
-                lines.append(f"  {_ADD}{formatted_path[0]}{_RESET} {_DIM}={_RESET}")
-            else:
-                prefix = ".".join(formatted_path[:-1])
-                final = formatted_path[-1]
-                lines.append(
-                    f"  {_PATH_PREFIX}{prefix}.{_RESET}{_ADD}{final}{_RESET} {_DIM}={_RESET}"
-                )
-            # Child lines: indented key: value, with aligned values
-            # Format keys (may contain UUIDs)
-            formatted_items = []
-            for k, v in value.items():
-                k_display = resolver.resolve(k) if resolver and _is_uuid(k) else k
-                v_str = fmt_value(v, path + [k])
-                formatted_items.append((k_display, v_str))
-            max_key_len = max(len(k) for k, _ in formatted_items)
-            field_width = max(max_key_len, 12)  # minimum 12 chars
-            for k_display, v_str in formatted_items:
-                padding = " " * (field_width - len(k_display))
-                lines.append(f"    {k_display}{_DIM}:{_RESET}{padding} {v_str}")
-            return lines
-        else:
-            value_str = fmt_value(value, path)
-            if len(formatted_path) == 1:
-                return [
-                    f"  {_ADD}{formatted_path[0]}{_RESET} {_DIM}={_RESET} {value_str}"
-                ]
-            prefix = ".".join(formatted_path[:-1])
-            final = formatted_path[-1]
-            return [
-                f"  {_PATH_PREFIX}{prefix}.{_RESET}{_ADD}{final}{_RESET} {_DIM}={_RESET} {value_str}"
-            ]
-
-    # update: Existing item being updated - normal path colors
-    value_str = fmt_value(value, path)
-    path_str = _format_path(path, resolver=resolver)
-    return [f"  {path_str} {_DIM}={_RESET} {value_str}"]
-
-
-def format_diff(
-    diff: dict, previous: dict | None = None, db: "DB | None" = None
-) -> list[str]:
-    """
-    Format a JSON diff as human-readable lines.
-
-    Args:
-        diff: The JSON diff dict
-        previous: The previous state dict (for determining add vs update)
-        db: Optional database for looking up display names
-
-    Returns a list of formatted lines (without newlines).
-    UUIDs are replaced with display names (using previous state for lookups).
-    """
-    changes: list[tuple[str, list[str], Any]] = []
-    _collect_changes(diff, [], changes, previous)
-
-    if not changes:
-        return []
-
-    # Create resolver for UUID replacement (uses previous state for lookups)
-    resolver = UuidResolver(db, previous)
-
-    # Format each change
-    lines = []
-    for change_type, path, value in changes:
-        lines.extend(_format_change_lines(change_type, path, value, resolver))
-
-    return lines
-
-
-def format_action_header(action: str, user_display: str | None = None) -> str:
-    """Format the action header line."""
-    action_str = f"{_ACTION}{action}{_RESET}"
-    if user_display:
-        user_str = f"{_USER}{user_display}{_RESET}"
-        return f"{action_str} by {user_str}"
-    return action_str
-
-
-def log_change(
-    action: str,
-    diff: dict,
-    user_display: str | None = None,
-    previous: dict | None = None,
-    db: "DB | None" = None,
-) -> None:
-    """
-    Log a database change with pretty-printed diff.
-
-    UUIDs are replaced with display names for readability. For types without
-    display names, the full UUID string is used.
-
-    Args:
-        action: The action name (e.g., "login", "admin:delete_user")
-        diff: The JSON diff dict
-        user_display: Optional display name of the user who performed the action
-        previous: The previous state dict (for determining add vs update)
-        db: Optional database for looking up display names
-    """
-    header = format_action_header(action, user_display)
-    diff_lines = format_diff(diff, previous, db)
-
-    if not diff_lines:
-        logger.info(header)
-        return
-
-    if len(diff_lines) == 1:
-        # Single change - combine on one line
-        logger.info(f"{header}{diff_lines[0]}")
-    else:
-        # Multiple changes - header on its own line, then changes
-        logger.info(header)
-        for line in diff_lines:
-            logger.info(line)
-
-
-def configure_db_logging() -> None:
-    """Configure the database logger to output to stderr without prefix."""
-    handler = logging.StreamHandler(sys.stderr)
-    handler.setFormatter(logging.Formatter("%(message)s"))
-    logger.addHandler(handler)
-    logger.setLevel(logging.INFO)
-    logger.propagate = False

paskia/db/migrations.py

@@ -1,80 +0,0 @@
-"""
-Database schema migrations.
-
-Migrations are applied during database load based on the version field.
-Each migration should be idempotent and only run when needed.
-"""
-
-import base64
-from collections.abc import Awaitable, Callable
-
-import msgspec
-
-from paskia.util.crypto import secret_key
-
-
-class MigrationCtx(msgspec.Struct):
-    """Context passed to each migration function."""
-
-    rp_id: str
-
-
-def migrate_v1(d: dict, ctx: MigrationCtx) -> None:
-    """Remove Org.created_at fields."""
-    for org_data in d["orgs"].values():
-        org_data.pop("created_at", None)
-
-
-def migrate_v2(d: dict, ctx: MigrationCtx) -> None:
-    """Add config field if missing."""
-    if "config" not in d:
-        d["config"] = {"rp_id": ctx.rp_id}
-
-
-def migrate_v3(d: dict, ctx: MigrationCtx) -> None:
-    """Ensure all users have visits field."""
-    for user_data in d["users"].values():
-        user_data.setdefault("visits", 0)
-
-
-def migrate_v4(d: dict, ctx: MigrationCtx) -> None:
-    """OpenID Connect support and hardened session keys."""
-    # Session keys changed to hashes, drop old sessions
-    d["sessions"] = {}
-    # Create OIDC structure with a generated new key
-    d["oidc"] = {"clients": {}, "key": base64.standard_b64encode(secret_key()).decode()}
-
-
-migrations = sorted(
-    [f for n, f in globals().items() if n.startswith("migrate_v")],
-    key=lambda f: int(f.__name__.removeprefix("migrate_v")),
-)
-
-DBVER = len(migrations)  # Used by bootstrap to set initial version
-
-
-def apply_migrations_readonly(
-    data_dict: dict,
-    current_version: int,
-    ctx: MigrationCtx,
-) -> int:
-    """Apply migration functions in-place without persistence.
-
-    Returns the new version after all migrations.
-    """
-    while current_version < DBVER:
-        migrations[current_version](data_dict, ctx)
-        current_version += 1
-    return current_version
-
-
-async def apply_all_migrations(
-    data_dict: dict,
-    current_version: int,
-    persist: Callable[[str, int, dict], Awaitable[None]],
-    ctx: MigrationCtx,
-) -> None:
-    while current_version < DBVER:
-        migrations[current_version](data_dict, ctx)
-        current_version += 1
-        await persist(f"migrate:v{current_version}", current_version, data_dict)

paskia/db/operations.py

@@ -1,7 +1,7 @@
 """
 Database for WebAuthn passkey authentication.
 
-Read operations: Access _db directly, use build_* helpers to get public structs.
+Read operations: Access _db directly.
 Context lookup: _db.session_ctx() returns full SessionContext with effective permissions.
 Write operations: Functions that validate and commit, or raise ValueError.
 """
@@ -15,15 +15,13 @@ import uuid7
 
 from paskia import oidc_notify
 from paskia.config import SESSION_LIFETIME
-from paskia.db.jsonl import (
-    JsonlStore,
-)
 from paskia.db.structs import (
     DB,
     Client,
-    Config,
     Credential,
+    DomainConfig,
     Org,
+    OriginEntry,
     Permission,
     ResetToken,
     Role,
@@ -40,10 +38,27 @@ _logger = logging.getLogger(__name__)
 _UNSET = object()
 
 # Global database instance (empty until init() loads data)
-_db = DB(config=Config(rp_id="uninitialized.invalid"))
+_db = DB()
-_store = JsonlStore(_db)
+
-_db._store = _store
+
-_initialized = False
+def _store():
+    """Return active Kanta instance for the current DB object."""
+    store = _db._store
+    if store is None:
+        raise RuntimeError("Kanta store is not initialized")
+    return store
+
+
+def _transaction(
+    action: str,
+    ctx: SessionContext | None = None,
+    *,
+    user: str | None = None,
+    mtime: bool | datetime = True,
+):
+    """Create a Kanta transaction with minimal metadata mapping."""
+    user_id = str(ctx.user.uuid) if ctx else user
+    return _store().transaction(action, user=user_id, mtime=mtime)
 
 
 def is_username_taken(username: str, exclude_uuid: UUID | None = None) -> bool:
@@ -62,17 +77,11 @@ def is_username_taken(username: str, exclude_uuid: UUID | None = None) -> bool:
 # -------------------------------------------------------------------------
 
 
-async def update_config(config: Config) -> None:
-    """Update the stored configuration."""
-    with _db.transaction("update_config"):
-        _db.config = config
-
-
 def create_permission(perm: Permission, *, ctx: SessionContext | None = None) -> None:
     """Create a new permission."""
     if perm.uuid in _db.permissions:
         raise ValueError(f"Permission {perm.uuid} already exists")
-    with _db.transaction("admin:create_permission", ctx):
+    with _transaction("admin:create_permission", ctx):
         perm.store()
 
 
@@ -90,7 +99,7 @@ def update_permission(
     """
     if uuid not in _db.permissions:
         raise ValueError(f"Permission {uuid} not found")
-    with _db.transaction("admin:update_permission", ctx):
+    with _transaction("admin:update_permission", ctx):
         _db.permissions[uuid].scope = scope
         _db.permissions[uuid].display_name = display_name
         _db.permissions[uuid].domain = domain
@@ -100,7 +109,7 @@ def delete_permission(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     """Delete a permission and remove it from all roles."""
     if uuid not in _db.permissions:
         raise ValueError(f"Permission {uuid} not found")
-    with _db.transaction("admin:delete_permission", ctx):
+    with _transaction("admin:delete_permission", ctx):
         _db.permissions[uuid].delete()
 
 
@@ -112,7 +121,7 @@ def create_org(org: Org, *, ctx: SessionContext | None = None) -> None:
     if org.uuid in _db.orgs:
         raise ValueError(f"Organization {org.uuid} already exists")
     now = datetime.now(UTC)
-    with _db.transaction("admin:create_org", ctx):
+    with _transaction("admin:create_org", ctx):
         new_org = Org.create(display_name=org.display_name, created_at=now)
         new_org.uuid = org.uuid
         new_org.store()
@@ -144,7 +153,7 @@ def update_org_name(
     """Update organization display name."""
     if uuid not in _db.orgs:
         raise ValueError(f"Organization {uuid} not found")
-    with _db.transaction("admin:update_org_name", ctx):
+    with _transaction("admin:update_org_name", ctx):
         _db.orgs[uuid].display_name = display_name
 
 
@@ -152,7 +161,7 @@ def delete_org(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     """Delete organization and all its roles/users."""
     if uuid not in _db.orgs:
         raise ValueError(f"Organization {uuid} not found")
-    with _db.transaction("admin:delete_org", ctx):
+    with _transaction("admin:delete_org", ctx):
         _db.orgs[uuid].delete()
 
 
@@ -169,7 +178,7 @@ def add_permission_to_org(
     if permission_uuid not in _db.permissions:
         raise ValueError(f"Permission {permission_uuid} not found")
 
-    with _db.transaction("admin:add_permission_to_org", ctx):
+    with _transaction("admin:add_permission_to_org", ctx):
         _db.permissions[permission_uuid].orgs[org_uuid] = True
 
 
@@ -186,7 +195,7 @@ def remove_permission_from_org(
     if permission_uuid not in _db.permissions:
         return  # Permission not found, silently return
 
-    with _db.transaction("admin:remove_permission_from_org", ctx):
+    with _transaction("admin:remove_permission_from_org", ctx):
         _db.permissions[permission_uuid].orgs.pop(org_uuid, None)
 
 
@@ -196,7 +205,7 @@ def create_role(role: Role, *, ctx: SessionContext | None = None) -> None:
         raise ValueError(f"Role {role.uuid} already exists")
     if role.org_uuid not in _db.orgs:
         raise ValueError(f"Organization {role.org_uuid} not found")
-    with _db.transaction("admin:create_role", ctx):
+    with _transaction("admin:create_role", ctx):
         role.store()
 
 
@@ -209,7 +218,7 @@ def update_role_name(
     """Update role display name."""
     if uuid not in _db.roles:
         raise ValueError(f"Role {uuid} not found")
-    with _db.transaction("admin:update_role_name", ctx):
+    with _transaction("admin:update_role_name", ctx):
         _db.roles[uuid].display_name = display_name
 
 
@@ -224,7 +233,7 @@ def add_permission_to_role(
         raise ValueError(f"Role {role_uuid} not found")
     if permission_uuid not in _db.permissions:
         raise ValueError(f"Permission {permission_uuid} not found")
-    with _db.transaction("admin:add_permission_to_role", ctx):
+    with _transaction("admin:add_permission_to_role", ctx):
         _db.roles[role_uuid].permissions[permission_uuid] = True
 
 
@@ -237,7 +246,7 @@ def remove_permission_from_role(
     """Remove permission from role by UUID."""
     if role_uuid not in _db.roles:
         raise ValueError(f"Role {role_uuid} not found")
-    with _db.transaction("admin:remove_permission_from_role", ctx):
+    with _transaction("admin:remove_permission_from_role", ctx):
         _db.roles[role_uuid].permissions.pop(permission_uuid, None)
 
 
@@ -249,7 +258,7 @@ def delete_role(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     role = _db.roles[uuid]
     if role.users:
         raise ValueError(f"Cannot delete role {uuid}: users still assigned")
-    with _db.transaction("admin:delete_role", ctx):
+    with _transaction("admin:delete_role", ctx):
         _db.roles[uuid].delete()
 
 
@@ -259,7 +268,7 @@ def create_user(new_user: User, *, ctx: SessionContext | None = None) -> None:
         raise ValueError(f"User {new_user.uuid} already exists")
     if new_user.role_uuid not in _db.roles:
         raise ValueError(f"Role {new_user.role_uuid} not found")
-    with _db.transaction("admin:create_user", ctx):
+    with _transaction("admin:create_user", ctx):
         new_user.store()
 
 
@@ -286,7 +295,7 @@ def update_user_display_name(
     if not display_name:
         raise ValueError("Display name cannot be empty")
     user = _db.users[uuid]
-    with _db.transaction("update_user_display_name", ctx):
+    with _transaction("update_user_display_name", ctx):
         user.display_name = display_name
         # Auto-fill preferred_username if not already set
         if user.preferred_username is None:
@@ -360,7 +369,7 @@ def update_user_info(
         elif len(telephone) > 32:
             raise ValueError("telephone too long")
 
-    with _db.transaction("update_user_info", ctx):
+    with _transaction("update_user_info", ctx):
         if display_name is not _UNSET:
             user.display_name = display_name
         if theme is not _UNSET:
@@ -384,7 +393,7 @@ def update_user_role(
         raise ValueError(f"User {uuid} not found")
     if role_uuid not in _db.roles:
         raise ValueError(f"Role {role_uuid} not found")
-    with _db.transaction("admin:update_user_role", ctx):
+    with _transaction("admin:update_user_role", ctx):
         _db.users[uuid].role_uuid = role_uuid
 
 
@@ -392,7 +401,7 @@ def delete_user(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     """Delete user and their credentials/sessions."""
     if uuid not in _db.users:
         raise ValueError(f"User {uuid} not found")
-    with _db.transaction("admin:delete_user", ctx):
+    with _transaction("admin:delete_user", ctx):
         _db.users[uuid].delete()
 
 
@@ -402,7 +411,7 @@ def create_credential(cred: Credential, *, ctx: SessionContext | None = None) ->
         raise ValueError(f"Credential {cred.uuid} already exists")
     if cred.user_uuid not in _db.users:
         raise ValueError(f"User {cred.user_uuid} not found")
-    with _db.transaction("create_credential", ctx):
+    with _transaction("create_credential", ctx):
         cred.store()
 
 
@@ -416,7 +425,7 @@ def update_credential_sign_count(
     """Update credential sign count and last_used."""
     if uuid not in _db.credentials:
         raise ValueError(f"Credential {uuid} not found")
-    with _db.transaction("update_credential_sign_count", ctx):
+    with _transaction("update_credential_sign_count", ctx):
         _db.credentials[uuid].sign_count = sign_count
         if last_used:
             _db.credentials[uuid].last_used = last_used
@@ -438,23 +447,24 @@ def delete_credential(
     if user_uuid is not None:
         if cred.user_uuid != user_uuid:
             raise ValueError(f"Credential {uuid} does not belong to user {user_uuid}")
-    with _db.transaction("delete_credential", ctx):
+    with _transaction("delete_credential", ctx):
         cred.delete()
 
 
 def update_session(
-    key: bytes,
+    key: str,
     host: str | None = None,
     ip: str | None = None,
     user_agent: str | None = None,
     validated: datetime | None = None,
+    issuer: str | None = None,
     *,
     ctx: SessionContext | None = None,
 ) -> None:
     """Update session metadata."""
     if key not in _db.sessions:
         raise ValueError("Session not found")
-    with _db.transaction("update_session", ctx):
+    with _transaction("update_session", ctx):
         s = _db.sessions[key]
         if host is not None:
             s.host = host
@@ -464,13 +474,8 @@ def update_session(
             s.user_agent = user_agent
         if validated is not None:
             s.validated = validated
-
+        if issuer is not None:
-
+            s.issuer = issuer
-def set_session_host(
-    key: bytes, host: str, *, ctx: SessionContext | None = None
-) -> None:
-    """Set the host for a session (first-time binding)."""
-    update_session(key, host=host, ctx=ctx)
 
 
 def delete_session(
@@ -486,7 +491,7 @@ def delete_session(
         raise ValueError("Session not found")
 
     oidc_notify.schedule_notifications([key])
-    with _db.transaction(action, ctx):
+    with _transaction(action, ctx):
         _db.sessions[key].delete()
 
 
@@ -505,7 +510,7 @@ def delete_sessions_for_user(
 
     keys = [s.key for s in user.sessions]
     oidc_notify.schedule_notifications(keys)
-    with _db.transaction("admin:delete_sessions_for_user", ctx):
+    with _transaction("admin:delete_sessions_for_user", ctx):
         for sess in user.sessions:
             sess.delete()
 
@@ -536,19 +541,11 @@ def create_reset_token(
     )
     if token.key in _db.reset_tokens:
         raise ValueError("Reset token already exists")
-    with _db.transaction("create_reset_token", ctx, user=user):
+    with _transaction("create_reset_token", ctx, user=user):
         token.store()
     return passphrase
 
 
-def delete_reset_token(key: bytes, *, ctx: SessionContext | None = None) -> None:
-    """Delete a reset token."""
-    if key not in _db.reset_tokens:
-        raise ValueError("Reset token not found")
-    with _db.transaction("delete_reset_token", ctx):
-        _db.reset_tokens[key].delete()
-
-
 # -------------------------------------------------------------------------
 # Composite operations (used by app code)
 # -------------------------------------------------------------------------
@@ -562,6 +559,7 @@ def login(
     ip: str,
     user_agent: str,
     duration: timedelta = SESSION_LIFETIME,
+    rp_id: str | None = None,
 ) -> str:
     """Update user/credential on login and create session in a single transaction.
 
@@ -569,7 +567,7 @@ def login(
     - user.last_seen, user.visits
     - credential.sign_count, credential.last_used
     Creates:
-    - new session
+    - new session (stamped with rp_id when provided)
 
     Returns the generated session token.
     """
@@ -592,9 +590,10 @@ def login(
         ip=ip,
         user_agent=user_agent,
         validated=now,
+        rp_id=rp_id,
     )
     user_str = str(user_uuid)
-    with _db.transaction("login", user=user_str):
+    with _transaction("login", user=user_str):
         session.store(now)
         # Update credential
         _db.credentials[credential_uuid].sign_count = sign_count
@@ -621,7 +620,7 @@ def oidc_login(
     """
     now = datetime.now(UTC)
     user_str = str(session.user_uuid)
-    with _db.transaction("oidc_login", user=user_str):
+    with _transaction("oidc_login", user=user_str):
         session.store(now)
         # Update credential
         _db.credentials[credential_uuid].sign_count = sign_count
@@ -665,9 +664,10 @@ def create_credential_session(
         ip=ip,
         user_agent=user_agent,
         validated=now,
+        rp_id=credential.rp_id,
     )
     user_str = str(user_uuid)
-    with _db.transaction("create_credential_session", user=user_str):
+    with _transaction("create_credential_session", user=user_str):
         # Update display name if provided
         if display_name:
             _db.users[user_uuid].display_name = display_name
@@ -691,6 +691,59 @@ def create_credential_session(
     return token
 
 
+# -------------------------------------------------------------------------
+# Domain operations
+# -------------------------------------------------------------------------
+
+
+def create_domain(
+    rp_id: str, domain: DomainConfig, *, ctx: SessionContext | None = None
+) -> None:
+    """Add a new domain (rp-id) to the stored configuration.
+
+    The caller must validate the resulting combined configuration.
+    """
+    if rp_id in _db.config.domains:
+        raise ValueError(f"Domain {rp_id} already exists")
+    with _transaction("admin:create_domain", ctx):
+        _db.config.domains[rp_id] = domain
+
+
+def update_domain(
+    rp_id: str,
+    *,
+    rp_name: str | None,
+    origins: dict[str, bool | OriginEntry],
+    ctx: SessionContext | None = None,
+) -> None:
+    """Replace a domain's rp_name and origins table (wholesale).
+
+    The rp-id itself is immutable: credentials are stamped with it, so
+    changing it would orphan them — delete and recreate the domain instead.
+    The caller must validate the resulting combined configuration.
+    """
+    domain = _db.config.domains.get(rp_id)
+    if domain is None:
+        raise ValueError(f"Domain {rp_id} not found")
+    with _transaction("admin:update_domain", ctx):
+        domain.rp_name = rp_name
+        domain.origins = origins
+
+
+def delete_domain(rp_id: str, *, ctx: SessionContext | None = None) -> None:
+    """Delete a domain. Refused for the last domain or while credentials remain."""
+    if rp_id not in _db.config.domains:
+        raise ValueError(f"Domain {rp_id} not found")
+    if len(_db.config.domains) <= 1:
+        raise ValueError("Cannot delete the last remaining domain")
+    if any(c.rp_id == rp_id for c in _db.credentials.values()):
+        raise ValueError(
+            f"Cannot delete domain {rp_id}: credentials still registered under it"
+        )
+    with _transaction("admin:delete_domain", ctx):
+        del _db.config.domains[rp_id]
+
+
 # -------------------------------------------------------------------------
 # OIDC Provider operations
 # -------------------------------------------------------------------------
@@ -700,7 +753,7 @@ def create_oid_client(client: Client, *, ctx: SessionContext | None = None) -> N
     """Create a new OIDC client."""
     if client.uuid in _db.oidc.clients:
         raise ValueError(f"OIDC client {client.uuid} already exists")
-    with _db.transaction("admin:create_oid_client", ctx):
+    with _transaction("admin:create_oid_client", ctx):
         _db.oidc.clients[client.uuid] = client
 
 
@@ -741,7 +794,7 @@ def update_oid_client(
         else client.backchannel_logout_uri
     )
 
-    with _db.transaction("admin:update_oid_client", ctx):
+    with _transaction("admin:update_oid_client", ctx):
         # Create updated client with new values
         updated_client = Client(
             client_secret_hash=secret_hash
@@ -767,7 +820,7 @@ def reset_oid_client_secret(
     if client_uuid not in _db.oidc.clients:
         raise ValueError(f"OIDC client {client_uuid} not found")
     client = _db.oidc.clients[client_uuid]
-    with _db.transaction("admin:reset_oid_client_secret", ctx):
+    with _transaction("admin:reset_oid_client_secret", ctx):
         updated = Client(
             client_secret_hash=new_secret_hash,
             name=client.name,
@@ -782,5 +835,5 @@ def delete_oid_client(client_uuid: UUID, *, ctx: SessionContext | None = None) -
     """Delete an OIDC client."""
     if client_uuid not in _db.oidc.clients:
         raise ValueError(f"OIDC client {client_uuid} not found")
-    with _db.transaction("admin:delete_oid_client", ctx):
+    with _transaction("admin:delete_oid_client", ctx):
         del _db.oidc.clients[client_uuid]

paskia/db/paths.py

@@ -0,0 +1,33 @@
+"""Filesystem paths for paskia persistence.
+
+The combined database is a single kanta JSONL file at the fixed
+CWD-relative path ``paskia.kantadb``. Auxiliary user files (avatars) live
+under ``paskia.data/``. The deployment is selected by the current working
+directory; there is deliberately no environment override.
+"""
+
+from pathlib import Path
+
+DB_FILENAME = "paskia.kantadb"
+DATA_DIRNAME = "paskia.data"
+
+
+def db_file_path() -> Path:
+    """Return the combined database file path."""
+    return Path(DB_FILENAME)
+
+
+def data_root_path(create_root: bool = False) -> Path:
+    """Return the root directory for auxiliary files (avatars etc.)."""
+    root = Path(DATA_DIRNAME)
+    if create_root:
+        root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def users_root_path(create_root: bool = False) -> Path:
+    """Return the filesystem root for persisted user files."""
+    root = data_root_path(create_root=create_root) / "users"
+    if create_root:
+        root.mkdir(parents=True, exist_ok=True)
+    return root

paskia/db/structs.py

@@ -3,13 +3,13 @@ from __future__ import annotations
 import hashlib
 import secrets
 from datetime import UTC, datetime
+from typing import Any
 from uuid import UUID
 
 import msgspec
 import uuid7
 
 from paskia import db
-from paskia.util import hostutil
 from paskia.util import passphrase as passphrase_util
 from paskia.util.crypto import hash_secret
 
@@ -237,6 +237,10 @@ class User(msgspec.Struct, dict=True, omit_defaults=True, kw_only=True):
         """Get credential IDs for this user (for WebAuthn exclude lists)."""
         return [c.credential_id for c in self.credentials]
 
+    def credential_ids_for(self, rp_id: str) -> list[bytes]:
+        """Get credential IDs registered under a specific domain's rp-id."""
+        return [c.credential_id for c in self.credentials if c.rp_id == rp_id]
+
     @property
     def sessions(self) -> list[Session]:
         """Get all sessions for this user."""
@@ -290,8 +294,12 @@ class Credential(msgspec.Struct, dict=True):
     """Credential (passkey) data structure.
 
     Mutable fields: sign_count, last_used, last_verified
-    Immutable fields: credential_id, user, aaguid, public_key, created_at
+    Immutable fields: credential_id, user, aaguid, public_key, created_at, rp_id
     uuid is derived from created_at using uuid7.
+
+    rp_id is the domain the passkey was registered under. With Related Origin
+    Requests it is always the domain's canonical rp-id, regardless of which
+    origin the registration ceremony ran on.
     """
 
     credential_id: bytes  # Long binary ID from the authenticator
@@ -300,6 +308,7 @@ class Credential(msgspec.Struct, dict=True):
     public_key: bytes
     sign_count: int
     created_at: datetime
+    rp_id: str
     last_used: datetime | None = None
     last_verified: datetime | None = None
 
@@ -341,6 +350,7 @@ class Credential(msgspec.Struct, dict=True):
         aaguid: UUID,
         public_key: bytes,
         sign_count: int,
+        rp_id: str,
         created_at: datetime | None = None,
     ) -> Credential:
         """Create a new Credential with auto-generated uuid7."""
@@ -353,6 +363,7 @@ class Credential(msgspec.Struct, dict=True):
             public_key=public_key,
             sign_count=sign_count,
             created_at=now,
+            rp_id=rp_id,
             last_used=now,
             last_verified=now,
         )
@@ -363,8 +374,8 @@ class Credential(msgspec.Struct, dict=True):
 class Session(msgspec.Struct, dict=True, omit_defaults=True):
     """Session data structure.
 
-    Mutable fields: validated (updated on session refresh)
+    Mutable fields: host, ip, user_agent, validated, issuer (update_session)
-    Immutable fields: user_uuid, credential_uuid, host, ip, user_agent, client_uuid
+    Immutable fields: user_uuid, credential_uuid, client_uuid, rp_id
     key is the hashed db_key, stored in the dict key, not in the struct.
 
     If client_uuid is set, this is an OIDC session.
@@ -380,6 +391,8 @@ class Session(msgspec.Struct, dict=True, omit_defaults=True):
     user_agent: str
     validated: datetime
     client_uuid: UUID | None = msgspec.field(name="client", default=None)
+    rp_id: str | None = None  # Owning domain (needed when no request context)
+    issuer: str | None = None  # OIDC issuer URL this session was created under
 
     def __post_init__(self):
         if not hasattr(self, "key"):
@@ -395,14 +408,6 @@ class Session(msgspec.Struct, dict=True, omit_defaults=True):
         """Get the Credential object for this session."""
         return db.data().credentials[self.credential_uuid]
 
-    def metadata(self) -> dict:
-        """Return session metadata for backwards compatibility."""
-        return {
-            "ip": self.ip,
-            "user_agent": self.user_agent,
-            "validated": self.validated.isoformat(),
-        }
-
     def store(self, last_seen: datetime) -> None:
         """Store this session in the database and record a visit.
 
@@ -429,11 +434,15 @@ class Session(msgspec.Struct, dict=True, omit_defaults=True):
         user_agent: str,
         validated: datetime,
         client: UUID | None = None,
+        rp_id: str | None = None,
+        issuer: str | None = None,
     ) -> Session:
         """Create a new Session with the provided key.
 
         Args:
             key: The hashed session key (derived from secret via hash_secret)
+            rp_id: Owning domain's rp-id (used when no request context exists)
+            issuer: OIDC issuer URL (scheme + host) for OIDC sessions
 
         Returns:
             Session object with key set
@@ -452,6 +461,8 @@ class Session(msgspec.Struct, dict=True, omit_defaults=True):
             user_agent=user_agent,
             validated=validated,
             client_uuid=client,
+            rp_id=rp_id,
+            issuer=issuer,
         )
         session.key = key
         return session
@@ -601,14 +612,50 @@ class OIDC(msgspec.Struct, dict=True):
     key: bytes | None = None
 
 
-class Config(msgspec.Struct, frozen=True, dict=True, omit_defaults=True):
+class OriginEntry(msgspec.Struct, omit_defaults=True):
-    """Stored configuration for the instance."""
+    """Extra properties of one allowed origin within a domain.
+
+    Stored as the dict value for an origin key; plain ``True`` instead of an
+    object means presence only, nothing more to store.
+    """
+
+    auth_host: bool = False  # This site hosts the account/admin interface
+
+
+class DomainConfig(msgspec.Struct, omit_defaults=True):
+    """Configuration for one domain (one WebAuthn rp-id).
+
+    ``origins`` is a single table of sites that may sign in with this
+    domain's passkeys, classified by the rp-id: entries within the rp-id
+    domain are in-domain sign-in sites, entries outside it are related
+    origins (WebAuthn Related Origin Requests — individual hosts only,
+    no wildcards). Keys are hosts without the https:// scheme
+    ("app.example.com"), wildcard patterns under the rp-id following the
+    shell-glob convention ("**.example.com" — the base domain and its
+    subdomains at any depth; "*.example.com" — exactly one subdomain
+    level; https only, any scheme and port under localhost), or full
+    origins ("http://localhost:8080", "https://app2.com"). An empty dict
+    means nothing is allowed — list sites explicitly. Ordering carries no
+    meaning — display order is decided by the UI.
+    """
 
-    rp_id: str
     rp_name: str | None = None
-    origins: list[str] | None = None
+    origins: dict[str, bool | OriginEntry] = {}
-    auth_host: str | None = None
+
-    listen: str | None = None
+
+class Config(msgspec.Struct, omit_defaults=True):
+    """Stored configuration for the instance.
+
+    Domains are keyed by rp-id and shared by the whole administrative
+    instance: organizations and users are global across rp-ids.
+    """
+
+    domains: dict[str, DomainConfig] = msgspec.field(
+        default_factory=lambda: {
+            "localhost": DomainConfig(origins={"**.localhost": True})
+        }
+    )
+    listen: list[str] | None = None  # Process-global listen endpoints
 
 
 # -------------------------------------------------------------------------
@@ -619,7 +666,7 @@ class Config(msgspec.Struct, frozen=True, dict=True, omit_defaults=True):
 class DB(msgspec.Struct, dict=True, omit_defaults=False):
     """In-memory database. Access fields directly for reads."""
 
-    config: Config
+    config: Config = msgspec.field(default_factory=Config)
     permissions: dict[UUID, Permission] = {}
     orgs: dict[UUID, Org] = {}
     roles: dict[UUID, Role] = {}
@@ -627,12 +674,13 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
     credentials: dict[UUID, Credential] = {}
     sessions: dict[str, Session] = {}
     reset_tokens: dict[str, ResetToken] = {}
-    # OIDC provider data
+    # OIDC provider data: one instance-global provider (single signing key
-    oidc: OIDC = msgspec.field(default_factory=lambda: OIDC())
+    # and client set); each request Host acts as an issuer alias.
+    oidc: OIDC = msgspec.field(default_factory=OIDC)
 
     def __post_init__(self):
-        # Store reference for persistence (not serialized)
+        # Optional store reference for non-global DB instances (e.g. tests).
-        self._store = None
+        self._store: Any | None = None
         # Set the key fields on all stored objects
         for uuid, perm in self.permissions.items():
             perm.uuid = uuid
@@ -652,10 +700,6 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
         for uuid, client in self.oidc.clients.items():
             client.uuid = uuid
 
-    def transaction(self, action, ctx=None, *, user=None):
-        """Wrap writes in transaction. Delegates to JsonlStore."""
-        return self._store.transaction(action, ctx, user=user)
-
     def session_ctx(
         self, session_secret: str, host: str | None = None
     ) -> SessionContext | None:
@@ -663,7 +707,8 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
 
         Args:
             session_secret: The session secret (cookie value) - will be hashed for lookup
-            host: Optional host for binding/validation and domain-scoped permissions
+            host: The request host; sessions are host-bound and domain-scoped
+                permissions are filtered by it
 
         Returns:
             SessionContext if valid, None if session not found, expired, or host mismatch
@@ -679,12 +724,8 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
         if s.client_uuid is not None:
             return None
 
-        # Normalize host for comparison (stored hosts are already normalized)
+        # Sessions are host-bound
-        normalized_input = hostutil.normalize_host(host)
+        if s.host != host:
-
-        # Validate host matches (sessions are always created with a host)
-        if s.host != normalized_input:
-            # Session bound to different host
             return None
 
         try:
@@ -695,8 +736,8 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
         except KeyError:
             return None
 
-        # Effective permissions: role's permissions that the org can grant
+        # Effective permissions: role's permissions that the org can grant,
-        # Also filter by domain if host is provided
+        # filtered by domain restriction
         org_perm_uuids = {p.uuid for p in org.permissions}
 
         effective_perms = []
@@ -707,8 +748,7 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
                 p = self.permissions[perm_uuid]
             except KeyError:
                 continue
-            # Check domain restriction (normalized_input already has port stripped)
+            if p.domain is not None and p.domain != host:
-            if p.domain is not None and p.domain != normalized_input:
                 continue
             effective_perms.append(p)
 

paskia/domains.py

@@ -0,0 +1,539 @@
+"""Domain registry: per-rp-id runtime state and host resolution.
+
+A **domain** is one rp-id with its associated hosts and origins. The
+registry is built from the stored combined ``Config`` at startup and
+rebuilt on admin domain changes; request dispatch resolves hosts to
+domains through it. The database itself is global — only the *current
+domain* (passkey, site URLs) varies per request, tracked via a
+contextvar set by the dispatch middleware.
+
+Each domain's ``origins`` table holds both in-domain sign-in sites and
+related origins (ROR), classified by the rp-id: entries within the rp-id
+domain are in-domain, entries outside it are related.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import logging
+import os
+
+from fastapi_vue.hostutil import parse_endpoints
+
+from paskia.db.structs import Config, DomainConfig, OriginEntry
+from paskia.sansio import Passkey
+from paskia.util import hostutil
+from paskia.util.constants import DEFAULT_PORT
+
+logger = logging.getLogger(__name__)
+
+# Maximum number of related (non-subdomain) origins per domain. WebAuthn
+# Related Origin Requests require browsers to support at least 5 labels.
+DEFAULT_RELATED_ORIGIN_CAP = 5
+
+
+def origin_url(key: str) -> str:
+    """URL form of an origins-table key (https:// is implied); wildcards
+    pass through unchanged."""
+    if hostutil.is_wildcard_pattern(key) or "://" in key:
+        return key
+    return f"https://{key}"
+
+
+def origin_key(origin: str) -> str:
+    """Origins-table key for a full origin URL (https:// omitted).
+
+    Keys are canonicalized: lowercased, and bare hosts/wildcards lose any
+    trailing dot.
+    """
+    key = origin.removeprefix("https://").rstrip("/")
+    if hostutil.is_wildcard_pattern(key):
+        prefix = "**." if key.startswith("**.") else "*."
+        return prefix + key[len(prefix) :].rstrip(".").lower()
+    if "://" not in key:
+        key = key.rstrip(".")
+    return key.lower()
+
+
+def is_related_key(rp_id: str, key: str) -> bool:
+    """Whether an origins-table key lies outside the rp-id domain (a
+    related origin). Wildcards are never related."""
+    if hostutil.is_wildcard_pattern(key):
+        return False
+    hn = hostutil.origin_hostname(origin_url(key))
+    return bool(hn) and not hostutil.is_subdomain(hn, rp_id)
+
+
+def partition_origins(
+    rp_id: str, origins: dict[str, bool | OriginEntry]
+) -> tuple[list[str], list[str]]:
+    """Split an origins table into (in-domain keys, related keys)."""
+    in_domain = [k for k in origins if not is_related_key(rp_id, k)]
+    related = [k for k in origins if is_related_key(rp_id, k)]
+    return in_domain, related
+
+
+def auth_host_url(domain: DomainConfig) -> str | None:
+    """Full URL of the domain's auth host origin, if one is marked."""
+    for key, props in domain.origins.items():
+        if isinstance(props, OriginEntry) and props.auth_host:
+            return origin_url(key)
+    return None
+
+
+class Domain:
+    """Runtime view of one domain: stored config plus derived values."""
+
+    def __init__(self, rp_id: str, config: DomainConfig, site_url: str, site_path: str):
+        in_domain, related = partition_origins(rp_id, config.origins)
+        self.rp_id = rp_id
+        self.config = config
+        self.site_url = site_url
+        self.site_path = site_path
+        self.passkey = Passkey(
+            rp_id=rp_id,
+            rp_name=config.rp_name,
+            origins=[origin_url(k) for k in in_domain],
+            related_origins=[origin_url(k) for k in related],
+        )
+
+    @property
+    def rp_name(self) -> str:
+        return self.passkey.rp_name
+
+    @property
+    def own_auth_host(self) -> str | None:
+        """This domain's own auth host as host[:port], if configured."""
+        url = auth_host_url(self.config)
+        return hostutil.auth_host_netloc(url) if url else None
+
+    @property
+    def related_origins(self) -> list[str]:
+        """Related (cross-domain) origins for ROR, as URLs."""
+        return sorted(self.passkey.related_origins)
+
+    @property
+    def ui_base_path(self) -> str:
+        """UI base path: site root on an own auth host, /auth/ elsewhere."""
+        return "/" if auth_host_url(self.config) is not None else "/auth/"
+
+    @property
+    def auth_site_url(self) -> str:
+        """Base URL of this domain's auth site UI."""
+        return self.site_url + self.site_path
+
+    def api_url(self, path: str = "") -> str:
+        """Return an absolute URL under the canonical /auth/api/ prefix."""
+        if not path:
+            return f"{self.site_url}/auth/api/"
+        return f"{self.site_url}/auth/api/{path.lstrip('/')}"
+
+    def reset_link_url(self, token: str) -> str:
+        """Generate a reset link URL for the given token on this domain."""
+        return f"{self.auth_site_url}{token}"
+
+
+class DomainRegistry:
+    """Resolved domains and host lookup tables."""
+
+    def __init__(self, domains: list[Domain]):
+        self._by_rp_id = {d.rp_id: d for d in domains}
+        self._auth_hosts: dict[str, list[Domain]] = {}
+        self._related_hosts: dict[str, Domain] = {}
+        self.warnings: list[str] = []
+        for domain in domains:
+            if own := domain.own_auth_host:
+                key = hostutil.normalize_host(own) or own
+                self._auth_hosts.setdefault(key, []).append(domain)
+            for origin in domain.related_origins:
+                if hostname := hostutil.origin_hostname(origin):
+                    # First claimant wins (config order); a related host that
+                    # is another domain's rp-id never reaches this map in
+                    # resolve() — the owning domain is matched first.
+                    self._related_hosts.setdefault(hostname, domain)
+
+    @property
+    def domains(self) -> list[Domain]:
+        """All domains (unordered — ordering is a display-time affair)."""
+        return list(self._by_rp_id.values())
+
+    def get(self, rp_id: str) -> Domain | None:
+        return self._by_rp_id.get(rp_id)
+
+    def resolve(self, host: str | None) -> Domain | None:
+        """Resolve a request Host header to a domain.
+
+        Order: exact rp-id → auth host → exact related-origin hostname →
+        longest-suffix rp-id. Unknown hosts return None. When several
+        domains share an auth host, the best suffix match (longest rp-id
+        the host falls under) wins, first configured as tiebreak — so
+        ``auth.company.com`` shared by ``company.com`` and ``app2.com``
+        serves ``company.com`` for plain HTTP; WebSocket logins still
+        follow the Origin header to the right domain.
+        """
+        h = hostutil.normalize_host(host)
+        if not h:
+            return None
+        if domain := self._by_rp_id.get(h):
+            return domain
+        if claimants := self._auth_hosts.get(h):
+            best = None
+            for candidate in claimants:
+                if h.endswith(f".{candidate.rp_id}") and (
+                    best is None or len(candidate.rp_id) > len(best.rp_id)
+                ):
+                    best = candidate
+            return best or claimants[0]
+        if domain := self._related_hosts.get(h):
+            return domain
+        best = None
+        for rp_id, domain in self._by_rp_id.items():
+            if h.endswith(f".{rp_id}") and (
+                best is None or len(rp_id) > len(best.rp_id)
+            ):
+                best = domain
+        return best
+
+
+def validate_config(
+    config: Config, *, related_origin_cap: int = DEFAULT_RELATED_ORIGIN_CAP
+) -> None:
+    """Validate a combined configuration cross-domain. Raises ValueError."""
+    if not config.domains:
+        raise ValueError("At least one domain (rp-id) is required")
+
+    auth_hosts: dict[str, str] = {}  # normalized host -> owning rp_id
+    related_hosts: dict[str, str] = {}  # hostname -> owning rp_id
+
+    for rp_id, domain in config.domains.items():
+        hostutil.validate_rp_id(rp_id)
+
+        domain_auth_host: str | None = None
+        related_count = 0
+        for key, props in domain.origins.items():
+            is_auth = isinstance(props, OriginEntry) and props.auth_host
+            if key == "*":
+                raise ValueError(
+                    f"Origin '*' is not allowed — list '**.{rp_id}' explicitly"
+                )
+            if hostutil.is_wildcard_pattern(key):
+                base = hostutil.wildcard_base(key)
+                if not base or not hostutil.is_valid_hostname(base):
+                    raise ValueError(f"Invalid wildcard origin: '{key}'")
+                if not hostutil.is_subdomain(base, rp_id):
+                    raise ValueError(
+                        f"Origin '{key}' is a wildcard outside the rp-id "
+                        f"domain '{rp_id}' — related origins must be "
+                        "individual hosts"
+                    )
+                if is_auth:
+                    raise ValueError(f"Wildcard origin '{key}' cannot be the auth host")
+                continue
+            hn = hostutil.origin_hostname(origin_url(key))
+            if not hn or not hostutil.is_valid_hostname(hn):
+                raise ValueError(f"Invalid origin: '{key}'")
+            if hostutil.is_subdomain(hn, rp_id):
+                if is_auth:
+                    if domain_auth_host is not None:
+                        raise ValueError(
+                            f"Domain '{rp_id}' marks several origins as the auth "
+                            f"host ('{domain_auth_host}' and '{key}') — only one allowed"
+                        )
+                    domain_auth_host = key
+                    ah = hostutil.normalize_host(
+                        hostutil.auth_host_netloc(origin_url(key)) or ""
+                    )
+                    # Several domains may share an auth host to consolidate
+                    # logins; resolution picks the best suffix match.
+                    auth_hosts.setdefault(ah, rp_id)
+                continue
+            # Related origin (outside the rp-id domain)
+            if is_auth:
+                raise ValueError(
+                    f"Related origin '{key}' cannot be the auth host — the "
+                    "auth host must be within the rp-id domain"
+                )
+            related_count += 1
+            # A related host may be (or fall inside) another domain's
+            # rp-id: a host that *is* a configured rp-id always serves its
+            # own domain; otherwise the related listing wins dispatch over
+            # suffix matching, so ROR logins from the listed host keep
+            # working.
+            covered_by_rp_id = any(
+                hostutil.is_subdomain(hn, other) for other in config.domains
+            )
+            if hn in related_hosts and not covered_by_rp_id:
+                raise ValueError(
+                    f"Related origin host '{hn}' is configured for both "
+                    f"'{related_hosts[hn]}' and '{rp_id}'"
+                )
+            related_hosts[hn] = rp_id
+        if related_count > related_origin_cap:
+            raise ValueError(
+                f"Domain '{rp_id}' has {related_count} related origins "
+                f"(maximum {related_origin_cap})"
+            )
+
+    rp_ids = set(config.domains)
+    for hn, owner in auth_hosts.items():
+        if hn in rp_ids:
+            raise ValueError(f"auth-host '{hn}' collides with an rp-id")
+        if hn in related_hosts and related_hosts[hn] != owner:
+            raise ValueError(
+                f"auth-host '{hn}' collides with a related origin of "
+                f"domain '{related_hosts[hn]}'"
+            )
+
+
+def sanitize_config(
+    config: Config, *, related_origin_cap: int = DEFAULT_RELATED_ORIGIN_CAP
+) -> tuple[Config, list[str]]:
+    """Best-effort repair of a stored configuration for serving.
+
+    Serving must never fail because of stored domain config: fixing it is
+    the admin's job via the admin UI, which is reachable only on a running
+    server. Returns a sanitized copy (the stored config is left untouched)
+    plus a warning for every degradation made. The result always passes
+    ``validate_config``.
+    """
+    warnings: list[str] = []
+
+    def warn(msg: str) -> None:
+        warnings.append(msg)
+
+    domains: dict[str, DomainConfig] = {}
+    for rp_id, domain in config.domains.items():
+        try:
+            hostutil.validate_rp_id(rp_id)
+        except ValueError as e:
+            warn(f"Domain dropped: {e}")
+            continue
+
+        origins: dict[str, bool | OriginEntry] = {}
+        auth_seen = False
+        for key, props in domain.origins.items():
+            is_auth = isinstance(props, OriginEntry) and props.auth_host
+            if not is_auth:
+                props = True  # canonicalize junk/empty entries to presence-only
+            if key == "*":
+                warn(
+                    f"Domain '{rp_id}': origin '*' rewritten as '**.{rp_id}'"
+                    + (" — auth host mark cleared" if is_auth else "")
+                )
+                origins[f"**.{rp_id}"] = True
+                continue
+            if hostutil.is_wildcard_pattern(key):
+                base = hostutil.wildcard_base(key)
+                if not base or not hostutil.is_valid_hostname(base):
+                    warn(f"Domain '{rp_id}': invalid wildcard origin '{key}' dropped")
+                    continue
+                if not hostutil.is_subdomain(base, rp_id):
+                    warn(
+                        f"Domain '{rp_id}': origin '{key}' is a wildcard "
+                        "outside the rp-id domain — dropped (related origins "
+                        "must be individual hosts)"
+                    )
+                    continue
+                if is_auth:
+                    warn(
+                        f"Domain '{rp_id}': wildcard '{key}' cannot be the "
+                        "auth host — mark cleared"
+                    )
+                    props = True
+                origins[key] = props
+                continue
+            hn = hostutil.origin_hostname(origin_url(key))
+            if not hn or not hostutil.is_valid_hostname(hn):
+                warn(f"Domain '{rp_id}': invalid origin '{key}' dropped")
+                continue
+            if is_auth:
+                if not hostutil.is_subdomain(hn, rp_id):
+                    warn(
+                        f"Domain '{rp_id}': related origin '{key}' cannot be "
+                        "the auth host — mark cleared"
+                    )
+                    props = True
+                elif auth_seen:
+                    warn(
+                        f"Domain '{rp_id}': several origins marked as "
+                        f"auth host — extra mark on '{key}' cleared"
+                    )
+                    props = True
+                else:
+                    auth_seen = True
+            origins[key] = props
+
+        related = sorted(k for k in origins if is_related_key(rp_id, k))
+        if len(related) > related_origin_cap:
+            warn(
+                f"Domain '{rp_id}': {len(related)} related origins exceed "
+                f"the maximum of {related_origin_cap} — extras dropped"
+            )
+            for key in related[related_origin_cap:]:
+                del origins[key]
+
+        domains[rp_id] = DomainConfig(rp_name=domain.rp_name, origins=origins)
+
+    if not domains:
+        raise ValueError("No servable domain in the stored configuration")
+
+    # Cross-domain conflicts: an auth host equal to an rp-id is dead config
+    # (the rp-id always wins dispatch) — clear the mark. Sharing one auth
+    # host between domains is allowed (login consolidation); resolution
+    # picks the best suffix match. Related origins may point at or inside
+    # other domains' rp-ids: a host that *is* a configured rp-id serves its
+    # own domain; otherwise the related listing wins dispatch over suffix
+    # matching.
+    rp_ids = set(domains)
+    seen_auth_hosts: dict[str, str] = {}
+    for rp_id, domain in domains.items():
+        for key, props in domain.origins.items():
+            if not isinstance(props, OriginEntry) or not props.auth_host:
+                continue
+            hn = hostutil.normalize_host(
+                hostutil.auth_host_netloc(origin_url(key)) or ""
+            )
+            if hn in rp_ids:
+                warn(
+                    f"Domain '{rp_id}': auth host '{hn}' collides with "
+                    "an rp-id — mark cleared"
+                )
+                domain.origins[key] = True
+            elif hn:
+                seen_auth_hosts.setdefault(hn, rp_id)
+
+    seen_related: dict[str, str] = {}
+    for rp_id, domain in domains.items():
+        drop = []
+        for key in domain.origins:
+            if not is_related_key(rp_id, key):
+                continue
+            hn = hostutil.origin_hostname(origin_url(key))
+            if any(hostutil.is_subdomain(hn, o) for o in rp_ids):
+                continue  # covered by a configured rp-id
+            if hn in seen_auth_hosts:
+                warn(
+                    f"Domain '{rp_id}': related origin '{key}' is the "
+                    f"auth host of '{seen_auth_hosts[hn]}' — dropped"
+                )
+                drop.append(key)
+            elif hn in seen_related:
+                warn(
+                    f"Domain '{rp_id}': related origin '{key}' is also "
+                    f"used by '{seen_related[hn]}' — dropped (first domain wins)"
+                )
+                drop.append(key)
+            else:
+                seen_related[hn] = rp_id
+        for key in drop:
+            del domain.origins[key]
+
+    return Config(domains=domains, listen=config.listen), warnings
+
+
+def _derive_site(
+    rp_id: str, domain: DomainConfig, *, listen_port: int | None, vite_url: str | None
+) -> tuple[str, str]:
+    """Compute a domain's site_url and site_path.
+
+    Priority: auth host > exact rp-id origin key > first concrete in-domain
+    origin key (sorted) > PASKIA_VITE_URL (localhost domain only) >
+    http://localhost:port (localhost domain) > https://rp-id.
+    """
+    if auth := auth_host_url(domain):
+        return auth, "/"
+    if rp_id in domain.origins:
+        return origin_url(rp_id), "/auth/"
+    concrete = sorted(
+        k
+        for k in domain.origins
+        if not hostutil.is_wildcard_pattern(k) and not is_related_key(rp_id, k)
+    )
+    if concrete:
+        return origin_url(concrete[0]), "/auth/"
+    if rp_id == "localhost":
+        if vite_url:
+            return vite_url.rstrip("/"), "/auth/"
+        if listen_port:
+            return f"http://localhost:{listen_port}", "/auth/"
+    return f"https://{rp_id}", "/auth/"
+
+
+_registry: DomainRegistry | None = None
+_listen: list[str] | None = None
+
+
+def configure(*, listen: list[str] | None = None) -> None:
+    """Record process-global serve parameters for site URL derivation."""
+    global _listen
+    _listen = listen
+
+
+def build(config: Config) -> DomainRegistry:
+    """Build a registry from a stored configuration.
+
+    The config is sanitized best-effort (serving must not fail on stored
+    config problems — the admin UI fixes them on a running server);
+    warnings are logged and exposed on the registry.
+    """
+    config, warnings = sanitize_config(config)
+    validate_config(config)  # sanitize guarantees this; a raise means a bug
+    endpoint = next(iter(parse_endpoints(_listen, DEFAULT_PORT)), {})
+    vite_url = os.environ.get("PASKIA_VITE_URL")
+    domains = [
+        Domain(
+            rp_id,
+            dc,
+            *_derive_site(
+                rp_id, dc, listen_port=endpoint.get("port"), vite_url=vite_url
+            ),
+        )
+        for rp_id, dc in config.domains.items()
+    ]
+    registry = DomainRegistry(domains)
+    registry.warnings = warnings
+    for warning in warnings:
+        logger.warning("Config: %s", warning)
+    return registry
+
+
+def init_registry(config: Config) -> DomainRegistry:
+    """Build and install the global registry from a combined configuration."""
+    global _registry
+    _registry = build(config)
+    return _registry
+
+
+def registry() -> DomainRegistry:
+    """Return the global registry (must be initialized)."""
+    if _registry is None:
+        raise RuntimeError("Domain registry is not initialized")
+    return _registry
+
+
+_current_domain: contextvars.ContextVar[Domain | None] = contextvars.ContextVar(
+    "paskia_current_domain", default=None
+)
+
+
+def set_current_domain(domain: Domain | None) -> contextvars.Token:
+    return _current_domain.set(domain)
+
+
+def reset_current_domain(token: contextvars.Token) -> None:
+    _current_domain.reset(token)
+
+
+def current_domain() -> Domain:
+    """Return the request's domain.
+
+    Without request context (background jobs, CLI), the single configured
+    domain is returned; with several domains a request context is required.
+    """
+    domain = _current_domain.get()
+    if domain is not None:
+        return domain
+    reg = registry()
+    if len(reg.domains) == 1:
+        return reg.domains[0]
+    raise RuntimeError("No current domain: request context required")

paskia/fastapi/__init__.py

@@ -1,3 +0,0 @@
-from paskia.fastapi.mainapp import app
-
-__all__ = ["app"]

paskia/fastapi/admin/__init__.py

@@ -0,0 +1,3 @@
+from paskia.fastapi.admin.adminapp import app
+
+__all__ = ["app"]

paskia/fastapi/admin/adminapp.py

@@ -0,0 +1,122 @@
+from uuid import UUID
+
+from fastapi import FastAPI, Request
+
+from paskia import db
+from paskia.fastapi import authz
+from paskia.fastapi.admin import (
+    domains,
+    oidc_clients,
+    orgs,
+    permissions,
+    roles,
+    users,
+)
+from paskia.fastapi.admin.errors import install_error_handlers
+from paskia.fastapi.front import frontend
+from paskia.fastapi.response import MsgspecResponse
+from paskia.fastapi.session import AUTH_COOKIE
+from paskia.util import (
+    avatar,
+    permutil,
+    vitedev,
+)
+from paskia.util.apistructs import (
+    ApiAdminInfo,
+    ApiOidcClient,
+    ApiOrg,
+    ApiOrgResponse,
+    ApiPermission,
+    ApiUser,
+)
+
+app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+
+install_error_handlers(app)
+app.mount("/oidc-clients", oidc_clients.app)
+app.mount("/orgs", orgs.app)
+app.mount("/roles", roles.app)
+app.mount("/users", users.app)
+app.mount("/permissions", permissions.app)
+app.mount("/domains", domains.app)
+
+
+def master_admin(ctx) -> bool:
+    return any(p.scope == "auth:admin" for p in ctx.permissions)
+
+
+def org_admin(ctx, org_uuid: UUID) -> bool:
+    return ctx.org.uuid == org_uuid and any(
+        p.scope == "auth:org:admin" for p in ctx.permissions
+    )
+
+
+def can_manage_org(ctx, org_uuid: UUID) -> bool:
+    return master_admin(ctx) or org_admin(ctx, org_uuid)
+
+
+@app.get("/")
+async def adminapp(request: Request, auth=AUTH_COOKIE):
+    return await vitedev.handle(request, frontend, "/auth/admin/")
+
+
+@app.get("/info")
+async def admin_info(request: Request, auth=AUTH_COOKIE):
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+    )
+
+    # Orgs
+    orgs = list(db.data().orgs.values())
+    if not master_admin(ctx):
+        # Org admins can only see their own organization
+        orgs = [o for o in orgs if o.uuid == ctx.org.uuid]
+
+    def org_to_dict(o):
+        roles = o.roles
+        return ApiOrgResponse(
+            org=ApiOrg.from_db(o),
+            permissions={p.uuid: p for p in o.permissions},
+            roles={r.uuid: r for r in roles},
+            users={
+                u.uuid: ApiUser.from_db(u, avatar_url=avatar.avatar_browser_url(u.uuid))
+                for r in roles
+                for u in r.users
+            },
+        )
+
+    orgs_dict = {o.uuid: org_to_dict(o) for o in orgs}
+
+    # Permissions
+    perms = db.data().permissions.values() if master_admin(ctx) else ctx.org.permissions
+    perms_dict = {p.uuid: ApiPermission.from_db(p) for p in perms}
+
+    # OIDC Clients (master admin only) — the instance-global provider
+    oidc_clients_dict = {}
+    if master_admin(ctx):
+        clients = sorted(db.data().oidc.clients.values(), key=lambda c: c.uuid)
+        sessions = db.data().sessions
+        # Count active sessions per client
+        client_session_counts = {}
+        for session in sessions.values():
+            if session.client_uuid:
+                client_session_counts[session.client_uuid] = (
+                    client_session_counts.get(session.client_uuid, 0) + 1
+                )
+        oidc_clients_dict = {
+            client.uuid: ApiOidcClient.from_db(
+                client, client_session_counts.get(client.uuid, 0)
+            )
+            for client in clients
+        }
+
+    return MsgspecResponse(
+        ApiAdminInfo(
+            orgs=orgs_dict,
+            permissions=perms_dict,
+            oidc_clients=oidc_clients_dict,
+        )
+    )

paskia/fastapi/admin/domains.py

@@ -0,0 +1,198 @@
+"""Domain (rp-id) management API — master admin only.
+
+Each domain is one rp-id with its own rp-name and an origins table of
+sign-in sites: entries within the rp-id domain are in-domain sites (one of
+which may be marked as the auth host), entries outside it are related
+origins on unrelated domains (WebAuthn Related Origin Requests). All
+changes are validated cross-domain before being persisted, and the runtime
+domain registry is rebuilt after each change so it takes effect
+immediately.
+"""
+
+from fastapi import Body, FastAPI, Request
+
+from paskia import db, domains
+from paskia.db.structs import Config, DomainConfig, OriginEntry
+from paskia.fastapi import authz
+from paskia.fastapi.admin.errors import install_error_handlers
+from paskia.fastapi.response import MsgspecResponse
+from paskia.fastapi.session import AUTH_COOKIE
+from paskia.sansio import Passkey
+from paskia.util import hostutil
+from paskia.util.apistructs import ApiDomain
+
+app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+
+install_error_handlers(app)
+
+
+def _domain_to_api(domain: domains.Domain) -> ApiDomain:
+    return ApiDomain(
+        rp_id=domain.rp_id,
+        rp_name=domain.rp_name,
+        origins=domain.config.origins,
+        site_url=domain.site_url,
+        auth_site_url=domain.auth_site_url,
+        auth_host=domain.own_auth_host,
+    )
+
+
+def _normalize_origins_map(values: dict | None) -> dict[str, bool | OriginEntry]:
+    """Normalize an origins object from the admin UI (raises on malformed).
+
+    Keys arrive as bare hosts, wildcard patterns, or full origins; they are
+    stored as origins-table keys (https:// omitted). In-domain vs. related
+    classification is derived from the rp-id at validation time.
+    """
+    out: dict[str, bool | OriginEntry] = {}
+    for raw_key, raw_props in (values or {}).items():
+        key = raw_key.strip()
+        if not key:
+            continue
+        if key != "*" and not hostutil.is_wildcard_pattern(key):
+            key = domains.origin_key(hostutil.normalize_origin(key))
+        is_auth = raw_props is not True and bool((raw_props or {}).get("auth_host"))
+        out[key] = OriginEntry(auth_host=True) if is_auth else True
+    return out
+
+
+def _rebuild_registry() -> None:
+    """Rebuild the runtime domain registry from the stored configuration."""
+    domains.init_registry(db.data().config)
+
+
+def _check_not_locking_self_out(
+    request: Request,
+    rp_id: str,
+    domain: DomainConfig,
+) -> None:
+    """Refuse domain changes that lock the admin out of their current host.
+
+    Applies when the admin edits the domain they are currently using and the
+    new config has no auth host (with an auth host, ceremonies move there
+    and it is always allowed). The admin's current host must remain able to
+    run passkey ceremonies under the new config.
+    """
+    current: domains.Domain = request.state.domain
+    if rp_id != current.rp_id or domains.auth_host_url(domain):
+        return
+    raw_host = (request.headers.get("host") or "").rstrip(".")
+    if not raw_host:
+        return
+    in_domain, related = domains.partition_origins(rp_id, domain.origins)
+    probe = Passkey(
+        rp_id=rp_id,
+        origins=[domains.origin_url(k) for k in in_domain],
+        related_origins=[domains.origin_url(k) for k in related],
+    )
+    for scheme in ("https", "http"):
+        try:
+            probe.validate_origin(f"{scheme}://{raw_host}")
+            return  # Current host still works — no lockout
+        except ValueError:
+            pass
+    raise ValueError(
+        f"This change would lock you out: '{raw_host}' could no longer "
+        f"run passkey ceremonies for domain '{rp_id}'. Add it to the "
+        "allowed origins (or mark an auth host) before saving."
+    )
+
+
+@app.get("/")
+async def admin_list_domains(request: Request, auth=AUTH_COOKIE):
+    """List all domains with derived URLs (master admin only)."""
+    await authz.verify(auth, ["auth:admin"], host=request.headers.get("host"))
+    registry = domains.registry()
+    return MsgspecResponse([_domain_to_api(domain) for domain in registry.domains])
+
+
+@app.post("/")
+async def admin_create_domain(
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    """Add a new domain (master admin only, recent authentication required)."""
+    ctx = await authz.verify(
+        auth, ["auth:admin"], host=request.headers.get("host"), max_age="5m"
+    )
+
+    rp_id = (payload.get("rp_id") or "").strip().lower()
+    if not rp_id:
+        raise ValueError("rp_id is required")
+    new = DomainConfig(
+        rp_name=(payload.get("rp_name") or "").strip() or None,
+        origins=_normalize_origins_map(payload.get("origins")),
+    )
+
+    config = db.data().config
+    # Validate the would-be combined configuration before persisting
+    domains.validate_config(
+        Config(domains={**config.domains, rp_id: new}, listen=config.listen)
+    )
+
+    db.create_domain(rp_id, new, ctx=ctx)
+    _rebuild_registry()
+    return {"status": "ok"}
+
+
+@app.patch("/{rp_id}")
+async def admin_update_domain(
+    rp_id: str,
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    """Update a domain's rp_name, origins and related origins (replaced
+    wholesale).
+
+    The rp-id itself is immutable: credentials are stamped with it.
+    """
+    ctx = await authz.verify(
+        auth, ["auth:admin"], host=request.headers.get("host"), max_age="5m"
+    )
+
+    config = db.data().config
+    if rp_id not in config.domains:
+        raise ValueError(f"Domain {rp_id} not found")
+
+    updated = DomainConfig(
+        rp_name=(payload.get("rp_name") or "").strip() or None,
+        origins=_normalize_origins_map(payload.get("origins")),
+    )
+    would_be = Config(
+        domains={k: updated if k == rp_id else v for k, v in config.domains.items()},
+        listen=config.listen,
+    )
+    domains.validate_config(would_be)
+    _check_not_locking_self_out(request, rp_id, updated)
+
+    db.update_domain(
+        rp_id,
+        rp_name=updated.rp_name,
+        origins=updated.origins,
+        ctx=ctx,
+    )
+    _rebuild_registry()
+    return {"status": "ok"}
+
+
+@app.delete("/{rp_id}")
+async def admin_delete_domain(
+    rp_id: str,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    """Delete a domain (refused for the last domain or while credentials remain)."""
+    ctx = await authz.verify(
+        auth, ["auth:admin"], host=request.headers.get("host"), max_age="5m"
+    )
+    current: domains.Domain = request.state.domain
+    if rp_id == current.rp_id:
+        raise ValueError(
+            "Cannot delete the domain you are currently using — authenticate "
+            "on another domain first"
+        )
+    db.delete_domain(rp_id, ctx=ctx)
+    _rebuild_registry()
+    return {"status": "ok"}

paskia/fastapi/admin/errors.py

@@ -0,0 +1,30 @@
+"""Shared exception handlers for admin sub-apps."""
+
+import logging
+
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+from paskia.fastapi import authz
+
+
+def install_error_handlers(app: FastAPI) -> None:
+    """Register standard exception handlers on *app*."""
+
+    @app.exception_handler(ValueError)
+    async def value_error_handler(_request, exc: ValueError):
+        return JSONResponse(status_code=400, content={"detail": str(exc)})
+
+    @app.exception_handler(authz.AuthException)
+    async def auth_exception_handler(_request, exc: authz.AuthException):
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=await authz.auth_error_content(exc),
+        )
+
+    @app.exception_handler(Exception)
+    async def general_exception_handler(_request, exc: Exception):  # pragma: no cover
+        logging.exception("Unhandled exception in admin app")
+        return JSONResponse(
+            status_code=500, content={"detail": "Internal server error"}
+        )

paskia/fastapi/admin/oidc_clients.py

@@ -0,0 +1,237 @@
+from uuid import UUID
+
+from fastapi import Body, FastAPI, HTTPException, Request
+
+from paskia import db
+from paskia.db.operations import _UNSET
+from paskia.db.structs import Client
+from paskia.fastapi import authz
+from paskia.fastapi.admin.errors import install_error_handlers
+from paskia.fastapi.session import AUTH_COOKIE
+from paskia.util import permutil
+
+app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+
+install_error_handlers(app)
+
+
+def master_admin(ctx) -> bool:
+    return any(p.scope == "auth:admin" for p in ctx.permissions)
+
+
+@app.post("/")
+async def admin_create_oidc_client(
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    """Create a new OIDC client (master admin only)."""
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin"],
+        host=request.headers.get("host"),
+        match=permutil.has_all,
+        max_age="5m",
+    )
+    if not master_admin(ctx):
+        raise authz.AuthException(
+            status_code=403,
+            detail="Only master admin can manage OIDC clients",
+            mode="forbidden",
+        )
+
+    # Client ID and secret hash are generated client-side
+    client_id = payload.get("client_id", "").strip()
+    secret_hash_hex = payload.get("secret_hash", "").strip()
+    name = payload.get("name", "").strip()
+    redirect_uris = payload.get("redirect_uris", [])
+    backchannel_logout_uri = payload.get("backchannel_logout_uri")
+    if isinstance(backchannel_logout_uri, str):
+        backchannel_logout_uri = backchannel_logout_uri.strip() or None
+
+    if not client_id or not secret_hash_hex:
+        raise ValueError("client_id and secret_hash are required")
+
+    try:
+        client_uuid = UUID(client_id)
+    except ValueError, AttributeError:
+        raise ValueError("client_id must be a valid UUID")
+
+    try:
+        secret_hash = bytes.fromhex(secret_hash_hex)
+    except ValueError:
+        raise ValueError("secret_hash must be a hex-encoded SHA-256 hash")
+    if len(secret_hash) != 32:
+        raise ValueError("secret_hash must be a SHA-256 hash (32 bytes)")
+
+    if not isinstance(redirect_uris, list):
+        raise ValueError("redirect_uris must be a list")
+
+    # Validate redirect URIs
+    for uri in redirect_uris:
+        if not isinstance(uri, str) or not uri.startswith("http"):
+            raise ValueError(f"Invalid redirect URI: {uri}")
+
+    if backchannel_logout_uri and not backchannel_logout_uri.startswith("http"):
+        raise ValueError("backchannel_logout_uri must be an HTTP(S) URL")
+
+    client = Client(
+        client_secret_hash=secret_hash,
+        name=name,
+        redirect_uris=redirect_uris,
+        backchannel_logout_uri=backchannel_logout_uri,
+    )
+    client.uuid = client_uuid
+
+    db.create_oid_client(client, ctx=ctx)
+
+    return {"status": "ok", "client_id": str(client.uuid)}
+
+
+@app.patch("/{client_uuid}")
+async def admin_update_oidc_client(
+    client_uuid: UUID,
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    """Update an OIDC client's name and redirect URIs (master admin only)."""
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin"],
+        host=request.headers.get("host"),
+        match=permutil.has_all,
+        max_age="5m",
+    )
+    if not master_admin(ctx):
+        raise authz.AuthException(
+            status_code=403,
+            detail="Only master admin can manage OIDC clients",
+            mode="forbidden",
+        )
+
+    name = payload.get("name", "").strip() if "name" in payload else None
+    redirect_uris = payload.get("redirect_uris") if "redirect_uris" in payload else None
+    secret_hash_hex = (
+        payload.get("secret_hash", "").strip() if "secret_hash" in payload else None
+    )
+    backchannel_logout_uri = (
+        payload.get("backchannel_logout_uri")
+        if "backchannel_logout_uri" in payload
+        else _UNSET
+    )
+    if isinstance(backchannel_logout_uri, str):
+        backchannel_logout_uri = backchannel_logout_uri.strip() or None
+
+    if name is not None and not name:
+        raise ValueError("Client name cannot be empty")
+
+    if redirect_uris is not None:
+        if not isinstance(redirect_uris, list):
+            raise ValueError("redirect_uris must be a list")
+        # Validate redirect URIs
+        for uri in redirect_uris:
+            if not isinstance(uri, str) or not uri.startswith("http"):
+                raise ValueError(f"Invalid redirect URI: {uri}")
+
+    if (
+        backchannel_logout_uri is not _UNSET
+        and backchannel_logout_uri
+        and not backchannel_logout_uri.startswith("http")
+    ):
+        raise ValueError("backchannel_logout_uri must be an HTTP(S) URL")
+
+    secret_hash = None
+    if secret_hash_hex:
+        try:
+            secret_hash = bytes.fromhex(secret_hash_hex)
+        except ValueError:
+            raise ValueError("secret_hash must be a hex-encoded SHA-256 hash")
+        if len(secret_hash) != 32:
+            raise ValueError("secret_hash must be a SHA-256 hash (32 bytes)")
+
+    try:
+        db.update_oid_client(
+            client_uuid,
+            name=name,
+            redirect_uris=redirect_uris,
+            secret_hash=secret_hash,
+            backchannel_logout_uri=backchannel_logout_uri,
+            ctx=ctx,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+
+    return {"status": "ok"}
+
+
+@app.post("/{client_uuid}/reset-secret")
+async def admin_reset_oidc_client_secret(
+    client_uuid: UUID,
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    """Reset an OIDC client's secret (master admin only).
+
+    The new secret is generated client-side; only the SHA-256 hash is sent.
+    """
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin"],
+        host=request.headers.get("host"),
+        match=permutil.has_all,
+        max_age="5m",
+    )
+    if not master_admin(ctx):
+        raise authz.AuthException(
+            status_code=403,
+            detail="Only master admin can manage OIDC clients",
+            mode="forbidden",
+        )
+
+    secret_hash_hex = payload.get("secret_hash", "").strip()
+    if not secret_hash_hex:
+        raise ValueError("secret_hash is required")
+    try:
+        secret_hash = bytes.fromhex(secret_hash_hex)
+    except ValueError:
+        raise ValueError("secret_hash must be a hex-encoded SHA-256 hash")
+    if len(secret_hash) != 32:
+        raise ValueError("secret_hash must be a SHA-256 hash (32 bytes)")
+
+    try:
+        db.reset_oid_client_secret(client_uuid, secret_hash, ctx=ctx)
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+
+    return {"status": "ok"}
+
+
+@app.delete("/{client_uuid}")
+async def admin_delete_oidc_client(
+    client_uuid: UUID,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    """Delete an OIDC client (master admin only)."""
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin"],
+        host=request.headers.get("host"),
+        match=permutil.has_all,
+        max_age="5m",
+    )
+    if not master_admin(ctx):
+        raise authz.AuthException(
+            status_code=403,
+            detail="Only master admin can manage OIDC clients",
+            mode="forbidden",
+        )
+
+    try:
+        db.delete_oid_client(client_uuid, ctx=ctx)
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+
+    return {"status": "ok"}

paskia/fastapi/admin/orgs.py

@@ -0,0 +1,232 @@
+from uuid import UUID
+
+from fastapi import Body, FastAPI, HTTPException, Query, Request
+
+from paskia import db
+from paskia.db import Org as OrgDC
+from paskia.db import Role as RoleDC
+from paskia.db import User as UserDC
+from paskia.fastapi import authz
+from paskia.fastapi.admin.errors import install_error_handlers
+from paskia.fastapi.response import MsgspecResponse
+from paskia.fastapi.session import AUTH_COOKIE
+from paskia.util import permutil
+from paskia.util.apistructs import ApiUuidResponse
+
+app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+
+install_error_handlers(app)
+
+
+def master_admin(ctx) -> bool:
+    return any(p.scope == "auth:admin" for p in ctx.permissions)
+
+
+def org_admin(ctx, org_uuid: UUID) -> bool:
+    return ctx.org.uuid == org_uuid and any(
+        p.scope == "auth:org:admin" for p in ctx.permissions
+    )
+
+
+def can_manage_org(ctx, org_uuid: UUID) -> bool:
+    return master_admin(ctx) or org_admin(ctx, org_uuid)
+
+
+@app.post("/")
+async def admin_create_org(
+    request: Request, payload: dict = Body(...), auth=AUTH_COOKIE
+):
+    ctx = await authz.verify(
+        auth, ["auth:admin"], host=request.headers.get("host"), match=permutil.has_all
+    )
+
+    display_name = payload.get("display_name") or "New Organization"
+    permissions = payload.get("permissions") or []
+    org = OrgDC.create(display_name=display_name)
+    db.create_org(org, ctx=ctx)
+    # Grant requested permissions to the new org
+    for perm in permissions:
+        db.add_permission_to_org(str(org.uuid), perm, ctx=ctx)
+
+    return MsgspecResponse(ApiUuidResponse(uuid=str(org.uuid)))
+
+
+@app.patch("/{org_uuid}")
+async def admin_update_org_name(
+    org_uuid: UUID,
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    """Update organization display name only."""
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+    )
+    if not can_manage_org(ctx, org_uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+    display_name = payload.get("display_name")
+    if not display_name:
+        raise ValueError("display_name is required")
+
+    db.update_org_name(org_uuid, display_name, ctx=ctx)
+    return {"status": "ok"}
+
+
+@app.delete("/{org_uuid}")
+async def admin_delete_org(org_uuid: UUID, request: Request, auth=AUTH_COOKIE):
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+        max_age="5m",
+    )
+    if not can_manage_org(ctx, org_uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+    if ctx.org.uuid == org_uuid:
+        raise ValueError("Cannot delete the organization you belong to")
+
+    # Delete organization-specific permissions
+    org_perm_pattern = f"org:{str(org_uuid).lower()}"
+    all_permissions = list(db.data().permissions.values())
+    for perm in all_permissions:
+        perm_scope_lower = perm.scope.lower()
+        # Check if permission contains "org:{uuid}" separated by colons or at boundaries
+        if (
+            f":{org_perm_pattern}:" in perm_scope_lower
+            or perm_scope_lower.startswith(f"{org_perm_pattern}:")
+            or perm_scope_lower.endswith(f":{org_perm_pattern}")
+            or perm_scope_lower == org_perm_pattern
+        ):
+            db.delete_permission(perm.uuid, ctx=ctx)
+
+    db.delete_org(org_uuid, ctx=ctx)
+    return {"status": "ok"}
+
+
+@app.post("/{org_uuid}/permission")
+async def admin_add_org_permission(
+    org_uuid: UUID,
+    request: Request,
+    permission_uuid: UUID = Query(...),
+    auth=AUTH_COOKIE,
+):
+    ctx = await authz.verify(
+        auth, ["auth:admin"], host=request.headers.get("host"), match=permutil.has_all
+    )
+
+    db.add_permission_to_org(org_uuid, permission_uuid, ctx=ctx)
+    return {"status": "ok"}
+
+
+@app.delete("/{org_uuid}/permission")
+async def admin_remove_org_permission(
+    org_uuid: UUID,
+    request: Request,
+    permission_uuid: UUID = Query(...),
+    auth=AUTH_COOKIE,
+):
+    ctx = await authz.verify(
+        auth, ["auth:admin"], host=request.headers.get("host"), match=permutil.has_all
+    )
+
+    # Guard rail: prevent removing auth:admin from your own org (lockout)
+    perm = db.data().permissions.get(permission_uuid)
+    if perm is None:
+        raise ValueError(f"Permission {permission_uuid} not found")
+    if perm.scope == "auth:admin" and ctx.org.uuid == org_uuid:
+        raise ValueError(
+            "Cannot remove auth:admin from your own organization. "
+            "This would lock you out of admin access."
+        )
+
+    db.remove_permission_from_org(org_uuid, permission_uuid, ctx=ctx)
+    return {"status": "ok"}
+
+
+@app.post("/{org_uuid}/roles")
+async def admin_create_role(
+    org_uuid: UUID,
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+    )
+    if not can_manage_org(ctx, org_uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+
+    display_name = payload.get("display_name") or "New Role"
+    perms = payload.get("permissions") or []
+    if org_uuid not in db.data().orgs:
+        raise HTTPException(status_code=404, detail="Organization not found")
+    org = db.data().orgs[org_uuid]
+    grantable = {p.uuid for p in org.permissions}
+
+    # Normalize permission IDs to UUIDs
+    permission_uuids: set[UUID] = set()
+    for pid in perms:
+        perm = db.data().permissions.get(UUID(pid))
+        if not perm:
+            raise ValueError(f"Permission {pid} not found")
+        if perm.uuid not in grantable:
+            raise ValueError(f"Permission not grantable by org: {pid}")
+        permission_uuids.add(perm.uuid)
+
+    role = RoleDC.create(
+        org=org_uuid,
+        display_name=display_name,
+        permissions=permission_uuids,
+    )
+    db.create_role(role, ctx=ctx)
+    return MsgspecResponse(ApiUuidResponse(uuid=str(role.uuid)))
+
+
+@app.post("/{org_uuid}/users")
+async def admin_create_user(
+    org_uuid: UUID,
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+    )
+    if not can_manage_org(ctx, org_uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+    display_name = payload.get("display_name")
+    role_name = payload.get("role")
+    if not display_name or not role_name:
+        raise ValueError("display_name and role are required")
+
+    org = db.data().orgs[org_uuid]
+    role_obj = next(
+        (r for r in org.roles if r.display_name == role_name),
+        None,
+    )
+    if not role_obj:
+        raise ValueError("Role not found in organization")
+    user = UserDC.create(
+        display_name=display_name,
+        role=role_obj.uuid,
+    )
+    db.create_user(user, ctx=ctx)
+    return MsgspecResponse(ApiUuidResponse(uuid=str(user.uuid)))

paskia/fastapi/admin/permissions.py

@@ -0,0 +1,225 @@
+from uuid import UUID
+
+from fastapi import Body, FastAPI, Query, Request
+
+from paskia import db
+from paskia.db import Permission as PermDC
+from paskia.domains import registry
+from paskia.fastapi import authz
+from paskia.fastapi.admin.errors import install_error_handlers
+from paskia.fastapi.session import AUTH_COOKIE
+from paskia.util import hostutil, permutil, querysafe
+
+app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+
+install_error_handlers(app)
+
+
+def _validate_permission_domain(domain: str | None) -> None:
+    """Validate that domain is a configured domain host or an OIDC client UUID.
+
+    Accepted: any domain's rp-id or its subdomain, a related-origin hostname
+    of any domain, or the UUID of an OIDC client (used for the
+    groups claim).
+    """
+    if domain is None:
+        return
+
+    # Allow OIDC client UUIDs (used for groups claim)
+    try:
+        client_uuid = UUID(domain)
+        if client_uuid in db.data().oidc.clients:
+            return
+    except ValueError:
+        pass
+
+    reg = registry()
+    if reg.resolve(domain) is not None:
+        return
+    raise ValueError(
+        f"Domain '{domain}' must belong to a configured domain or be an OIDC client UUID"
+    )
+
+
+def _check_admin_lockout(
+    perm_uuid: str, new_domain: str | None, current_host: str | None
+) -> None:
+    """Check if setting domain on auth:admin would lock out the admin.
+
+    Raises ValueError if this change would result in no auth:admin permissions
+    being accessible from the current host.
+    """
+
+    normalized_host = hostutil.normalize_host(current_host)
+    host_without_port = normalized_host.rsplit(":", 1)[0] if normalized_host else None
+
+    # Get all auth:admin permissions
+    all_perms = list(db.data().permissions.values())
+    admin_perms = [p for p in all_perms if p.scope == "auth:admin"]
+
+    # Check if at least one auth:admin would remain accessible
+    for p in admin_perms:
+        # If this is the permission being modified, use the new domain
+        domain = new_domain if str(p.uuid) == perm_uuid else p.domain
+
+        # No domain restriction = accessible from anywhere
+        if domain is None:
+            return
+
+        # Check if domain matches current host
+        if domain == normalized_host or domain == host_without_port:
+            return
+
+        # Check if domain is a subdomain of current host or vice versa
+        if normalized_host and normalized_host.endswith(f".{domain}"):
+            return
+        if host_without_port and host_without_port.endswith(f".{domain}"):
+            return
+
+    raise ValueError(
+        f"Setting domain '{new_domain}' on auth:admin permission would lock you out of "
+        f"admin access from current host '{current_host}'"
+    )
+
+
+def _check_admin_lockout_on_delete(perm_uuid: str, current_host: str | None) -> None:
+    """Check if deleting an auth:admin permission would lock out the admin.
+
+    Raises ValueError if this deletion would result in no auth:admin permissions
+    being accessible from the current host.
+    """
+    normalized_host = hostutil.normalize_host(current_host)
+    host_without_port = normalized_host.rsplit(":", 1)[0] if normalized_host else None
+
+    # Get all auth:admin permissions except the one being deleted
+    all_perms = list(db.data().permissions.values())
+    admin_perms = [
+        p for p in all_perms if p.scope == "auth:admin" and str(p.uuid) != perm_uuid
+    ]
+
+    # Check if at least one auth:admin would remain accessible
+    for p in admin_perms:
+        domain = p.domain
+
+        # No domain restriction = accessible from anywhere
+        if domain is None:
+            return
+
+        # Check if domain matches current host
+        if domain == normalized_host or domain == host_without_port:
+            return
+
+        # Check if domain is a subdomain of current host or vice versa
+        if normalized_host and normalized_host.endswith(f".{domain}"):
+            return
+        if host_without_port and host_without_port.endswith(f".{domain}"):
+            return
+
+    raise ValueError(
+        f"Deleting this auth:admin permission would lock you out of "
+        f"admin access from current host '{current_host}'"
+    )
+
+
+@app.post("/")
+async def admin_create_permission(
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin"],
+        host=request.headers.get("host"),
+        match=permutil.has_all,
+        max_age="5m",
+    )
+
+    scope = payload.get("scope") or payload.get(
+        "id"
+    )  # Support both for backwards compat
+    display_name = payload.get("display_name")
+    domain = payload.get("domain") or None  # Treat empty string as None
+    if not scope or not display_name:
+        raise ValueError("scope and display_name are required")
+    querysafe.assert_safe(scope, field="scope")
+    _validate_permission_domain(domain)
+    db.create_permission(
+        PermDC.create(scope=scope, display_name=display_name, domain=domain),
+        ctx=ctx,
+    )
+    return {"status": "ok"}
+
+
+@app.patch("/{permission_uuid}")
+async def admin_update_permission(
+    permission_uuid: UUID,
+    request: Request,
+    auth=AUTH_COOKIE,
+    display_name: str | None = Query(None),
+    scope: str | None = Query(None),
+    domain: str | None = Query(None),
+):
+    ctx = await authz.verify(
+        auth, ["auth:admin"], host=request.headers.get("host"), match=permutil.has_all
+    )
+
+    # Get existing permission
+    perm = db.data().permissions.get(permission_uuid)
+    if perm is None:
+        raise ValueError(f"Permission {permission_uuid} not found")
+
+    # Update fields that were provided (omitted domain keeps the existing
+    # restriction; an explicit empty domain clears it)
+    new_scope = scope if scope is not None else perm.scope
+    new_display_name = display_name if display_name is not None else perm.display_name
+    domain_value = perm.domain if domain is None else domain or None
+
+    # Sanity check: prevent changing the auth:admin permission scope
+    if perm.scope == "auth:admin" and new_scope != "auth:admin":
+        raise ValueError("Cannot rename the master admin permission")
+
+    if not new_display_name:
+        raise ValueError("display_name is required")
+    querysafe.assert_safe(new_scope, field="scope")
+    _validate_permission_domain(domain_value)
+
+    # Safety check: prevent admin lockout when setting domain on auth:admin
+    if perm.scope == "auth:admin" or new_scope == "auth:admin":
+        _check_admin_lockout(str(perm.uuid), domain_value, request.headers.get("host"))
+
+    db.update_permission(
+        uuid=perm.uuid,
+        scope=new_scope,
+        display_name=new_display_name,
+        domain=domain_value,
+        ctx=ctx,
+    )
+    return {"status": "ok"}
+
+
+@app.delete("/{permission_uuid}")
+async def admin_delete_permission(
+    permission_uuid: UUID,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin"],
+        host=request.headers.get("host"),
+        match=permutil.has_all,
+        max_age="5m",
+    )
+
+    # Get the permission to check its scope
+    perm = db.data().permissions.get(permission_uuid)
+    if perm is None:
+        raise ValueError(f"Permission {permission_uuid} not found")
+
+    # Sanity check: prevent deleting critical permissions if it would lock out admin
+    if perm.scope == "auth:admin":
+        _check_admin_lockout_on_delete(str(perm.uuid), request.headers.get("host"))
+
+    db.delete_permission(permission_uuid, ctx=ctx)
+    return {"status": "ok"}

paskia/fastapi/admin/roles.py

@@ -0,0 +1,160 @@
+from uuid import UUID
+
+from fastapi import Body, FastAPI, HTTPException, Request
+
+from paskia import db
+from paskia.fastapi import authz
+from paskia.fastapi.admin.errors import install_error_handlers
+from paskia.fastapi.session import AUTH_COOKIE
+from paskia.util import permutil
+
+app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+
+install_error_handlers(app)
+
+
+def master_admin(ctx) -> bool:
+    return any(p.scope == "auth:admin" for p in ctx.permissions)
+
+
+def org_admin(ctx, org_uuid: UUID) -> bool:
+    return ctx.org.uuid == org_uuid and any(
+        p.scope == "auth:org:admin" for p in ctx.permissions
+    )
+
+
+def can_manage_org(ctx, org_uuid: UUID) -> bool:
+    return master_admin(ctx) or org_admin(ctx, org_uuid)
+
+
+@app.patch("/{role_uuid}")
+async def admin_update_role_name(
+    role_uuid: UUID,
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    """Update role display name only."""
+    role = db.data().roles.get(role_uuid)
+    if not role:
+        raise HTTPException(status_code=404, detail="Role not found")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+    )
+    if not can_manage_org(ctx, role.org_uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+
+    display_name = payload.get("display_name")
+    if not display_name:
+        raise ValueError("display_name is required")
+
+    db.update_role_name(role_uuid, display_name, ctx=ctx)
+    return {"status": "ok"}
+
+
+@app.post("/{role_uuid}/permissions/{permission_uuid}")
+async def admin_add_role_permission(
+    role_uuid: UUID,
+    permission_uuid: UUID,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    """Add a permission to a role (intent-based API)."""
+    role = db.data().roles.get(role_uuid)
+    if not role:
+        raise HTTPException(status_code=404, detail="Role not found")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+    )
+    if not can_manage_org(ctx, role.org_uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+
+    # Verify permission exists and org can grant it
+    perm = db.data().permissions.get(permission_uuid)
+    if not perm:
+        raise HTTPException(status_code=404, detail="Permission not found")
+    if role.org_uuid not in perm.orgs:
+        raise ValueError("Permission not grantable by organization")
+
+    db.add_permission_to_role(role_uuid, permission_uuid, ctx=ctx)
+    return {"status": "ok"}
+
+
+@app.delete("/{role_uuid}/permissions/{permission_uuid}")
+async def admin_remove_role_permission(
+    role_uuid: UUID,
+    permission_uuid: UUID,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    """Remove a permission from a role (intent-based API)."""
+    role = db.data().roles.get(role_uuid)
+    if not role:
+        raise HTTPException(status_code=404, detail="Role not found")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+    )
+    if not can_manage_org(ctx, role.org_uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+
+    # Sanity check: prevent admin from removing their own access
+    perm = db.data().permissions.get(permission_uuid)
+    if ctx.org.uuid == role.org_uuid and ctx.role.uuid == role_uuid:
+        if perm and perm.scope in ["auth:admin", "auth:org:admin"]:
+            # Check if removing this permission would leave no admin access
+            remaining_perms = role.permission_set - {permission_uuid}
+            has_admin = False
+            for rp_uuid in remaining_perms:
+                rp = db.data().permissions.get(rp_uuid)
+                if rp and rp.scope in ["auth:admin", "auth:org:admin"]:
+                    has_admin = True
+                    break
+            if not has_admin:
+                raise ValueError("Cannot remove your own admin permissions")
+
+    db.remove_permission_from_role(role_uuid, permission_uuid, ctx=ctx)
+    return {"status": "ok"}
+
+
+@app.delete("/{role_uuid}")
+async def admin_delete_role(
+    role_uuid: UUID,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    role = db.data().roles.get(role_uuid)
+    if not role:
+        raise HTTPException(status_code=404, detail="Role not found")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+        max_age="5m",
+    )
+    if not can_manage_org(ctx, role.org_uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+
+    # Sanity check: prevent admin from deleting their own role
+    if ctx.role.uuid == role_uuid:
+        raise ValueError("Cannot delete your own role")
+
+    db.delete_role(role_uuid, ctx=ctx)
+    return {"status": "ok"}

paskia/fastapi/admin/users.py

@@ -0,0 +1,319 @@
+from uuid import UUID
+
+from fastapi import Body, FastAPI, HTTPException, Request
+
+from paskia import aaguid as aaguid_mod
+from paskia import db
+from paskia.authsession import reset_expires
+from paskia.domains import current_domain
+from paskia.fastapi import authz
+from paskia.fastapi.admin.errors import install_error_handlers
+from paskia.fastapi.response import MsgspecResponse
+from paskia.fastapi.session import AUTH_COOKIE
+from paskia.util import avatar, hostutil, permutil
+from paskia.util.apistructs import (
+    ApiAaguidInfo,
+    ApiCreateLinkResponse,
+    ApiOrg,
+    ApiRole,
+    ApiUser,
+    ApiUserDetail,
+    ApiUserSession,
+)
+
+app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+
+install_error_handlers(app)
+
+
+def master_admin(ctx) -> bool:
+    return any(p.scope == "auth:admin" for p in ctx.permissions)
+
+
+def org_admin(ctx, org_uuid: UUID) -> bool:
+    return ctx.org.uuid == org_uuid and any(
+        p.scope == "auth:org:admin" for p in ctx.permissions
+    )
+
+
+def can_manage_org(ctx, org_uuid: UUID) -> bool:
+    return master_admin(ctx) or org_admin(ctx, org_uuid)
+
+
+@app.patch("/{user_uuid}/role")
+async def admin_update_user_role(
+    user_uuid: UUID,
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    try:
+        user = db.data().users[user_uuid]
+    except KeyError:
+        raise HTTPException(status_code=404, detail="User not found")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+    )
+    if not can_manage_org(ctx, user.org.uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+    role_uuid_str = payload.get("role_uuid")
+    if not role_uuid_str:
+        raise ValueError("role_uuid is required")
+    try:
+        new_role_uuid = UUID(role_uuid_str)
+    except ValueError, TypeError:
+        raise ValueError("Invalid role UUID")
+    new_role = db.data().roles.get(new_role_uuid)
+    if not new_role or new_role.org_uuid != user.org.uuid:
+        raise ValueError("Role not found in organization")
+
+    # Sanity check: prevent admin from removing their own access
+    if ctx.user.uuid == user_uuid:
+        # Check if any permission in the new role is an admin permission
+        has_admin_access = False
+        for perm_uuid in new_role.permissions:
+            perm = db.data().permissions.get(perm_uuid)
+            if perm and perm.scope in ["auth:admin", "auth:org:admin"]:
+                has_admin_access = True
+                break
+        if not has_admin_access:
+            raise ValueError(
+                "Cannot change your own role to one without admin permissions"
+            )
+
+    db.update_user_role(user_uuid, new_role_uuid, ctx=ctx)
+    return {"status": "ok"}
+
+
+@app.post("/{user_uuid}/create-link")
+async def admin_create_user_registration_link(
+    user_uuid: UUID,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    try:
+        user = db.data().users[user_uuid]
+    except KeyError:
+        raise HTTPException(status_code=404, detail="User not found")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+        max_age="5m",
+    )
+    if not can_manage_org(ctx, user.org.uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+
+    # Check if user has existing credentials
+    has_credentials = db.data().users[user_uuid].credential_ids
+    token_type = "user registration" if not has_credentials else "account recovery"
+
+    expiry = reset_expires()
+    token = db.create_reset_token(
+        user_uuid=user_uuid,
+        expiry=expiry,
+        token_type=token_type,
+        ctx=ctx,
+    )
+    url = current_domain().reset_link_url(token)
+    return MsgspecResponse(
+        ApiCreateLinkResponse(
+            url=url,
+            expires=expiry,
+            token_type=token_type,
+        )
+    )
+
+
+@app.get("/{user_uuid}")
+async def admin_get_user_detail(
+    user_uuid: UUID,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    try:
+        user = db.data().users[user_uuid]
+    except KeyError:
+        raise HTTPException(status_code=404, detail="User not found")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+    )
+    if not can_manage_org(ctx, user.org.uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+    normalized_host = hostutil.normalize_host(request.headers.get("host"))
+
+    sessions = {
+        s.key: ApiUserSession.from_db(
+            s,
+            current_key=ctx.session.key,
+            normalized_host=normalized_host,
+        )
+        for s in user.sessions
+    }
+
+    return MsgspecResponse(
+        ApiUserDetail(
+            user=ApiUser.from_db(user, avatar_url=avatar.avatar_browser_url(user.uuid)),
+            credentials={c.uuid: c for c in user.credentials},
+            aaguid_info={
+                k: ApiAaguidInfo(**v)
+                for k, v in aaguid_mod.filter(
+                    c.aaguid for c in user.credentials
+                ).items()
+            },
+            sessions=sessions,
+            org=ApiOrg.from_db(user.org),
+            role=ApiRole.from_db(user.role),
+        )
+    )
+
+
+@app.patch("/{user_uuid}/info")
+async def admin_update_user_info(
+    user_uuid: UUID,
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    """Update user profile info (display_name, email, preferred_username, telephone).
+
+    Pass only the fields you want to update. Use null to clear optional fields.
+    """
+    try:
+        user = db.data().users[user_uuid]
+    except KeyError:
+        raise HTTPException(status_code=404, detail="User not found")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+    )
+    if not can_manage_org(ctx, user.org.uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+
+    kwargs = {}
+    if "display_name" in payload:
+        name = (payload["display_name"] or "").strip()
+        if not name:
+            raise HTTPException(status_code=400, detail="display_name cannot be empty")
+        if len(name) > 64:
+            raise HTTPException(status_code=400, detail="display_name too long")
+        kwargs["display_name"] = name
+    if "email" in payload:
+        kwargs["email"] = payload["email"]
+    if "preferred_username" in payload:
+        kwargs["preferred_username"] = payload["preferred_username"]
+    if "telephone" in payload:
+        kwargs["telephone"] = payload["telephone"]
+
+    if not kwargs:
+        raise HTTPException(status_code=400, detail="No fields to update")
+
+    db.update_user_info(user_uuid, **kwargs, ctx=ctx)
+    return {"status": "ok"}
+
+
+@app.delete("/{user_uuid}")
+async def admin_delete_user(
+    user_uuid: UUID,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    """Delete a user and all their credentials/sessions."""
+    try:
+        user = db.data().users[user_uuid]
+    except KeyError:
+        raise HTTPException(status_code=404, detail="User not found")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+        max_age="5m",
+    )
+    if not can_manage_org(ctx, user.org.uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+    # Prevent admin from deleting themselves
+    if ctx.user.uuid == user_uuid:
+        raise ValueError("Cannot delete your own account")
+    db.delete_user(user_uuid, ctx=ctx)
+    return {"status": "ok"}
+
+
+@app.delete("/{user_uuid}/credentials/{credential_uuid}")
+async def admin_delete_user_credential(
+    user_uuid: UUID,
+    credential_uuid: UUID,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    try:
+        user = db.data().users[user_uuid]
+    except KeyError:
+        raise HTTPException(status_code=404, detail="User not found")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+        max_age="5m",
+    )
+    if not can_manage_org(ctx, user.org.uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+    db.delete_credential(credential_uuid, user_uuid, ctx=ctx)
+    return {"status": "ok"}
+
+
+@app.delete("/{user_uuid}/sessions/{session_id}")
+async def admin_delete_user_session(
+    user_uuid: UUID,
+    session_id: str,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    try:
+        user = db.data().users[user_uuid]
+    except KeyError:
+        raise HTTPException(status_code=404, detail="User not found")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+    )
+    if not can_manage_org(ctx, user.org.uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+
+    session_key = session_id
+
+    target_session = db.data().sessions.get(session_key)
+    if not target_session or target_session.user_uuid != user_uuid:
+        raise HTTPException(status_code=404, detail="Session not found")
+
+    db.delete_session(session_key, ctx=ctx, action="admin:delete_session")
+
+    # Check if admin terminated their own session
+    current_terminated = session_key == ctx.session.key
+    return {"status": "ok", "current_session_terminated": current_terminated}