Fix profile image path on OIDC.

- backend avatar storage and OIDC picture claims
- profile and admin UI components
- admin org cards, tests, and docs

.gitignore

@@ -5,6 +5,8 @@ dist/
 *.lock
 package-lock.json
 paskia.sqlite
+*.paskiadb
+*.data
 /paskia/frontend-build
 /paskia/_version.py
 coverage-html/

API.md

@@ -1,105 +0,0 @@
-# Paskia API Documentation
-
-This document lists the HTTP and WebSocket endpoints exposed by the Paskia
-service and how they behave depending on whether a dedicated authentication host
-(`--auth-host` / environment `PASSKEY_AUTH_HOST`) is configured.
-
-## Base Paths & Host Modes
-
-Two deployment modes:
-
-1. Multi‑host (default – no `--auth-host` provided)
-   - All endpoints are reachable on any host under the `/auth/` prefix.
-   - A convenience root (`/`) also serves the main app.
-
-2. Dedicated auth host (`--auth-host auth.example.com`)
-   - The specified auth host serves the UI at the root (`/`, `/admin/`, reset tokens, etc.).
-   - Other (non‑auth) hosts show a lightweight account summary at `/` or `/auth/`, while other UI routes still redirect to the auth host.
-   - Restricted endpoints on non‑auth hosts return `404` instead of redirecting.
-
-### Path Mapping When Auth Host Enabled
-
-| Purpose | On Auth Host | On Other Hosts (incoming) | Action |
-|---------|--------------|---------------------------|--------|
-| Main UI | `/` | `/auth/` or `/` | Serve account summary SPA (no redirect) |
-| Admin UI root | `/admin/` | `/auth/admin/` or `/admin/` | Redirect -> auth host `/admin/` (strip `/auth`) |
-| Reset / device addition token | `/{token}` | `/auth/{token}` | Redirect -> auth host `/{token}` (strip `/auth`) |
-| Static assets | `/auth/assets/*` | `/auth/assets/*` | Served directly (no redirect) |
-| Unrestricted API | `/auth/api/...` | `/auth/api/...` | Served directly |
-| Restricted API (admin,user,ws namespaces) | `/auth/api/{admin|user|ws}*` | same path | 404 on non‑auth hosts |
-| WebSocket (register/auth) | `/auth/ws/*` | `/auth/ws/*` | 404 on non‑auth hosts |
-
-Notes:
-- “Strip `/auth`” means only when the path starts with that exact segment.
-- A reset token is a single path segment validated by server logic; malformed tokens 404.
-- Method and body are preserved for UI redirects (307 Temporary Redirect).
-
-## HTTP UI Endpoints
-
-| Method | Path (multi‑host) | Path (auth host) | Description |
-|--------|-------------------|------------------|-------------|
-| GET | `/auth/` | `/` | Main authentication SPA (non-auth hosts show an account summary view) |
-| GET | `/auth/admin/` | `/admin/` | Admin SPA root |
-| GET | `/auth/{reset_token}` | `/{reset_token}` | Reset / device addition SPA (token validated) |
-
-## Core API (Unrestricted – available on all hosts)
-
-Always under `/auth/api/` (even on auth host):
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/auth/restricted/` | Authentication UI for iframe embedding (supports `?mode=login` or `?mode=reauth`) |
-|--------|------|-------------|
-| POST | `/auth/api/validate` | Validate & (conditionally) renew session |
-| GET | `/auth/api/forward` | Auth proxy endpoint for reverse proxies (204 or 4xx) |
-| POST | `/auth/api/set-session` | Set cookie from Bearer token |
-| POST | `/auth/api/logout` | Logout current session |
-| POST | `/auth/api/user-info` | Authenticated user + context info (also handles reset tokens) |
-| POST | `/auth/api/create-link` | Create a device addition link (reset token) |
-| DELETE | `/auth/api/credential/{uuid}` | Delete user credential |
-| DELETE | `/auth/api/session/{session_id}` | Terminate a specific session |
-| POST | `/auth/api/user/logout-all` | Terminate all sessions for the user |
-| PUT | `/auth/api/user/display-name` | Update display name |
-
-## Restricted API Namespaces
-
-When `--auth-host` is set, requests to these paths on non‑auth hosts return 404:
-
-| Namespace | Examples |
-|-----------|----------|
-| `/auth/api/admin` | `/auth/api/admin/orgs`, `/auth/api/admin/orgs/{uuid}` ... |
-| `/auth/api/user` | Segment prefix – includes `/auth/api/user/...` endpoints (logout-all, display-name, session, credential) |
-| `/auth/api/ws` | (Reserved / future) |
-
-## WebSockets (Passkey)
-
-| Path | Description | Host Mode Behavior |
-|------|-------------|--------------------|
-| `/auth/ws/register` | Register new credential (new or existing user) | 404 on non‑auth hosts when auth host configured |
-| `/auth/ws/authenticate` | Authenticate user & issue session | 404 on non‑auth hosts when auth host configured |
-
-## Redirection & Status Codes
-
-| Scenario | Response |
-|----------|----------|
-| UI path on non‑auth host (auth host configured) | 307 redirect to auth host; `/auth` prefix stripped |
-| Reset token UI path on non‑auth host | 307 redirect (token preserved) |
-| Restricted API on non‑auth host | 404 |
-| Unrestricted API on any host | Normal response |
-| No auth host configured | All hosts behave like multi-host mode (no redirects; everything accessible) |
-
-## Headers for /auth/api/forward
-See `Headers.md` for details of headers returned on success (204).
-
-## Notes for Integrators
-1. Always use absolute `/auth/api/...` paths for programmatic requests (they do not move when an auth host is introduced).
-2. Bookmark / deep links to UI should resolve correctly after redirection if users access via a non-auth application host.
-3. Treat 404 from restricted namespaces on non-auth hosts as a signal to direct users to the central auth site.
-
-## Environment & CLI Summary
-| Option | Effect |
-|--------|--------|
-| `--auth-host` / `PASSKEY_AUTH_HOST` | Enables dedicated host mode, root-mounts UI there, restricts certain namespaces elsewhere |
-
----
-This document reflects current behavior of the middleware-based host routing logic.

Caddy.md

@@ -1,64 +0,0 @@
-## Caddy configuration
-
-We provide a few Caddy snippets that make the configuration easier, although the `forward_auth` directive of Caddy can be used directly as well. Place the auth folder with the snippets where your Caddyfile is.
-
-What these snippets do
-- Mount the auth UI at `/auth/` proxying to `:4401` (auth backend)
-- Use the forward-auth interface `/auth/api/forward` to verify the required credentials
-- Render a login page or a permission denied page if needed (without changing URL)
-
-Your backend may not use authentication at all, or it can make use of the user information passed via `Remote-*` headers by the authentication system, see [Headers.md](Headers.md) for details.
-
-### 1) Protect the full site (auth/all)
-
-Use this when you want “login required everywhere” which is useful to protect some service that doesn't have any authentication of its own:
-
-```caddyfile
-localhost {
-    import auth/all "" {
-        reverse_proxy :3000  # your app
-    }
-}
-```
-
-The auth/all protects the entire site with a simple directive. Put your normal setup inside the block. In this example we don't require any permissions, only that the user is logged in. Instead of `""` you may specify `perm=myapp:login` or other permissions.
-
-It is possible to add your own `handle @matcher` blocks prior importing `auth/all` for endpoints that don't require authentication, e.g. to exclude `/favicon.ico`.
-
-### 2) Different areas, different permissions (auth/setup, auth/require)
-
-When you need a more fine-grained control, use the auth/setup and auth/require snippets:
-
-```caddyfile
-localhost {
-    import auth/setup
-
-    @public path /.well-known/* /favicon.ico
-    handle @public {
-        root * /var/www/
-        file_server
-    }
-
-    @reports path /reports
-    handle @reports {
-        import auth/require perm=myapp:reports
-        reverse_proxy :3000
-    }
-
-    # Anywhere else, require login only
-    handle {
-        import auth/require ""
-        reverse_proxy :3000
-    }
-}
-```
-
-Note: We use the `handle @name` approach rather than `handle_path` to prevent the matched path being removed out of upstream URL. Unlike bare directives, these blocks will be tried in sequence and each can contain what you'd typically put in your site definition.
-
----
-
-## Override the auth backend URL (AUTH_UPSTREAM)
-
-By default, the auth service is contacted at localhost port 4401 ("for authentication required"). You can point Caddy to a different by setting the `AUTH_UPSTREAM` environment variable for Caddy.
-
-If unset, the snippets use `:4401` by default.

Headers.md

@@ -1,17 +0,0 @@
-## Headers your app receives
-
-When a request is allowed, the auth service adds these headers before proxying to your app (e.g., the service at `:3000`). Your app can use them for user context and authorization.
-
-| Header | Meaning | Example |
-|---|---|---|
-| `Remote-User` | Authenticated user UUID | `3f1a2b3c-4d5e-6789-abcd-ef0123456789` |
-| `Remote-Name` | User display name | `Jane Doe` |
-| `Remote-Org` | Organization UUID | `a1b2c3d4-1111-2222-3333-444455556666` |
-| `Remote-Org-Name` | Organization display name | `Acme Inc` |
-| `Remote-Role` | Role UUID | `b2c3d4e5-2222-3333-4444-555566667777` |
-| `Remote-Role-Name` | Role display name | `Administrators` |
-| `Remote-Groups` | Comma‑separated permissions the user has | `myapp:reports,auth:admin` |
-| `Remote-Session-Expires` | Session expiry timestamp (ISO 8601) | `2025-09-25T14:30:00Z` |
-| `Remote-Credential` | Credential UUID backing the session | `c3d4e5f6-3333-4444-5555-666677778888` |
-
-Note: Any incoming `Remote-*` headers from clients are stripped by our [Caddy configuration](Caddy.md), so that apps can trust these values.

README.md

@@ -1,72 +1,225 @@
 # Paskia
 
+![Login dialog screenshot](https://git.zi.fi/leovasanko/paskia/raw/main/docs/screenshots/login-light.webp)
+
 An easy to install passkey-based authentication service that protects any web application with strong passwordless login.
 
 ## What is Paskia?
 
 - Easy to use fully featured auth&auth system (login and permissions)
-- Organization and role-based access control (optional)
+- Organization and role-based access control
    * Org admins control their users and roles
-   * Master admin can create multiple independent orgs
+   * Multiple independent orgs
-   * Master admin makes permissions available for orgs to assign
+   * Master admin can do everything or delegate to org admins
-- User Profile and Administration by API and web interface.
+- User Profile and Admin by API and web interface
-under `/auth/` or `auth.example.com`
+- Implements login/reauth/forbidden flows for you
-- Reset tokens and additional device linking via QR code or codewords.
+- Single Sign-On (SSO): Users register once and authenticate across your services
-- Pure Python, FastAPI, packaged with prebuilt Vue frontend
+- Remote autentication by entering random keywords from another device (like 2fa)
+- No CORS, NodeJS or anything extra needed.
+
+## Authenticate to get to your app, or in your app
 
-Two interfaces:
 - API fetch: auth checks and login without leaving your app
 - Forward-auth proxy: protect any unprotected site or service (Caddy, Nginx)
 
 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.
 
-Single Sign-On (SSO): Users register once and authenticate across all applications under your domain name (configured rp-id).
+## Authentication flows already done
+
+![Forbidden dialog, dark mode](https://git.zi.fi/leovasanko/paskia/raw/main/docs/screenshots/forbidden-dark.webp)
+**Automatic light/dark mode switching with overrides by user profile and protected app's theme.**
+
+Paskia includes set of login, reauthentication and forbidden dialogs that it can use to perform the needed flows. We never leave the URL, no redirections, and if you make use of API mode, we won't even interrupt whatever your app was doing but retry the blocked API fetch after login like nothing happened.
 
 ## Quick Start
 
 Install [UV](https://docs.astral.sh/uv/getting-started/installation/) and run:
 
-```fish
+```sh
-uvx paskia serve --rp-id example.com
+uvx paskia --rp-id example.com
 ```
 
-On the first run it downloads the software and prints a registration link for the Admin. If you are going to be connecting `localhost` directly, for testing, leave out the rp-id.
+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 server will start up on [localhost:4401](http://localhost:4401) "for authentication required", serving for `*.example.com`.
+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).
-
-Otherwise you will 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.
-
-A quick example without any config file:
-```fish
-sudo caddy reverse-proxy --from example.com --to :4401
-```
 
 For a permanent install of `paskia` CLI command, not needing `uvx`:
 
-```fish
+```sh
 uv tool install paskia
 ```
 
 ## Configuration
 
-There is no config file. Pass only the options on CLI:
+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.
 
 ```text
-paskia serve [options]
+paskia [options]
 ```
 
-Optional options:
+| Option | Description | Default |
+|--------|-------------|---------|
+| -l, --listen *endpoint* | Listen address: *host*:*port*, :*port* (all interfaces), or */path.sock* | **localhost:4401** |
+| --rp-id *domain* | Main/top domain for passkeys | **localhost** |
+| --rp-name *"text"* | Branding name for the entire system (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) |
 
-- Listen address (one of):
+To clear a stored setting, pass an empty value like `--auth-host=`. The database is stored in `{rp-id}.paskiadb` folder in current directory. This can be overridden by environment `PASKIA_DB` if needed.
-    * `[host]:port`: Address and port (default: `localhost:4401`)
-    * `unix:/path.sock`: Unix socket
-- `--rp-id <domain>`: Main domain (required for production)
-- `--rp-name "<text>"`: Name of your company or site (default: same as rp-id)
-- `--origin <url>`: Explicit single site (default: `https://<rp-id>`)
-- `--auth-host <domain>`: Dedicated authentication site (e.g., `auth.example.com`)
 
-## Documentation
+## Tutorial: From Local Testing to Production
 
-- `API.md`: Complete HTTP and WebSocket API reference
+This section walks you through a complete example, from running Paskia locally to protecting a real site in production.
-- `Caddy.md`: Caddy configuration examples
+
-- `Headers.md`: HTTP headers passed to protected applications
+### Step 1: Production Configuration
+
+For a real deployment, configure Paskia with your domain name (rp-id). This enables SSO setup for that domain and any subdomains.
+
+```sh
+uvx paskia --rp-id=example.com --rp-name="Example Corp"
+```
+
+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). On the first run, you'll see 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: 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:
+
+```caddyfile
+app.example.com {
+    reverse_proxy :3000
+}
+```
+
+Add Paskia full site protection:
+
+```caddyfile
+app.example.com {
+    import auth/setup
+    handle {
+        import auth/require perm=myapp:login
+        reverse_proxy :3000
+    }
+}
+```
+
+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 3: Assign Permissions via Admin Panel
+
+![Admin panel permissions](https://git.zi.fi/leovasanko/paskia/raw/main/docs/screenshots/master-permissions.webp)
+
+1. Go to `app.example.com/auth/admin/`
+2. Create a permission, give it a name and scope `myapp:login`
+3. Assign it to Organization
+4. In that organization, assign it to the Administration role
+
+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 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):
+
+```js
+import { apiJson } from 'https://cdn.jsdelivr.net/npm/paskia@latest/dist/paskia.js'
+
+const data = await apiJson('/api/sensitive', { method: 'POST' })
+```
+
+When a 401/403 occurs, the auth dialog appears automatically, and the request retries after authentication.
+
+To protect the API path with a different permission, update your Caddyfile:
+
+```caddyfile
+app.example.com {
+    import auth/setup
+
+    @api path /api/*
+    handle @api {
+        import auth/require perm=myapp:api
+        reverse_proxy :3000
+    }
+
+    handle {
+        import auth/require perm=myapp:login
+        reverse_proxy :3000
+    }
+}
+```
+
+Create the `myapp:api` permission in the admin panel, that will be required for all API access. Link to `/auth/` for the built-in profile page.
+
+You may also remove the `myapp:login` protection from the rest of your site paths, unless you wish to keep all your assets behind a login page. Having this as the last entry in your config allows free access to everything not matched by other sections.
+
+```Caddyfile
+    handle {
+        reverse_proxy :3000
+    }
+```
+
+### Step 5: Run Paskia as a Service
+
+Create a system user paskia, install UV on the system, and create a systemd unit:
+
+```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
+```
+
+Create a systemd unit:
+
+```sh
+sudo systemctl edit --force --full paskia@.service
+```
+
+Paste the following and save:
+
+```ini
+[Unit]
+Description=Paskia for %i
+
+[Service]
+Type=simple
+User=paskia
+WorkingDirectory=/srv/paskia
+ExecStart=uvx paskia@latest --rp-id=%i
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Run the service and view log:
+
+```sh
+sudo systemctl enable --now paskia@example.com && sudo journalctl -n30 -ocat -fu paskia@example.com
+```
+
+### Optional: Dedicated Authentication Site
+
+Add a Caddy configuration for the authentication domain:
+
+```caddyfile
+auth.example.com {
+    reverse_proxy :4401
+}
+```
+
+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.
+
+Enter your auth site domain on Admin / Server Options panel or use `--auth-host=auth.example.com` when starting the server.
+
+
+## Further Documentation
+
+- [Caddy configuration](https://git.zi.fi/LeoVasanko/paskia/src/branch/main/docs/Caddy.md)
+- [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)

docs/API.md

@@ -0,0 +1,102 @@
+# Paskia API
+
+For integrating Paskia with your app frontend, see [integration](Integration.md).
+
+## Web Interface
+
+| Method | Path | What it is for | Notes |
+|---:|---|---|---|
+| GET | `/auth/` | User profile page | |
+| GET | `/auth/admin/` | Admin panel | Requires auth:admin (master) or org admin permissions. |
+| GET | `/auth/{token}` | Reset / add credential URL (QR code link) | E.g. `/auth/fun.cotton.fresh.xray.lava` |
+
+### Public JSON API: `/auth/api/*`
+
+| Method | Path | Used for | Notes |
+|---:|---|---|---|
+| GET | `/auth/api/settings` | Paskia configuration | Returns RP info + base paths + session cookie name |
+| GET | `/auth/api/user-info` | Full user profile | Basic information, credentials, sessions, permissions |
+| POST | `/auth/api/logout` | Terminate session and delete session cookie | Signs out of the current site |
+| POST | `/auth/api/validate` | Validate and renew session cookie | Optional query: `perm=` (repeatable), `max_age=` |
+| GET | `/auth/api/forward` | Validate access (Caddy/Nginx) | 204 on success; 401/403 otherwise (HTML if requested) |
+
+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/*`
+
+| Method | Path | Used for | Notes |
+|---:|---|---|---|
+| PATCH | `/auth/api/user/display-name` | Update the user’s display name | Body: JSON `{ "display_name": "..." }` |
+| GET | `/auth/api/user/{uuid}/profile.webp` | Canonical avatar image URL | Public on the auth host; serves `image/webp` with `ETag` and short-lived cache headers |
+| PUT | `/auth/api/user/{uuid}/profile.webp` | Upload or replace a user avatar | Multipart form with `file`; upload must already be square WebP prepared in the browser |
+| DELETE | `/auth/api/user/{uuid}/profile.webp` | Remove a user avatar | Allowed for the user, master admin, or org admin for users in the same org |
+| POST | `/auth/api/user/logout-all` | Terminate all user sessions | Clears current host cookie |
+| DELETE | `/auth/api/user/session/{session_id}` | Terminate one session | Session IDs are server-issued |
+| DELETE | `/auth/api/user/credential/{uuid}` | Delete a credential | Requires recent authentication |
+| POST | `/auth/api/user/create-link` | Create a device-add link | Requires recent authentication |
+
+These are used mostly from the user profile panel. The avatar route is also used by admins when managing other users.
+`GET /auth/api/user-info` includes `user.avatar_url` when the user has an uploaded avatar, using the same canonical `/auth/api/user/{uuid}/profile.webp` path.
+
+### 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.
+
+| Method | Path | Used for | Notes |
+|---:|---|---|---|
+| GET | `/auth/api/admin/info` | Admin overview | Returns orgs, permissions, OIDC clients info |
+| POST | `/auth/api/admin/permissions/` | Create permission | Body: JSON with scope, display_name, domain |
+| PATCH | `/auth/api/admin/permissions/{uuid}` | Update permission | Query params: display_name, scope, domain |
+| DELETE | `/auth/api/admin/permissions/{uuid}` | Delete permission | |
+| POST | `/auth/api/admin/orgs/` | Create organization | Body: JSON with display_name, permissions |
+| GET | `/auth/api/admin/orgs/{uuid}` | Get organization details | |
+| PATCH | `/auth/api/admin/orgs/{uuid}` | Update organization | Body: JSON with display_name |
+| DELETE | `/auth/api/admin/orgs/{uuid}` | Delete organization | |
+| POST | `/auth/api/admin/orgs/{uuid}/users` | Create user in org | Body: JSON with display_name, role_uuid |
+| POST | `/auth/api/admin/orgs/{uuid}/roles` | Create role in org | Body: JSON with display_name, permissions |
+| POST | `/auth/api/admin/orgs/{uuid}/permission` | Grant permission to org | Query param: permission_uuid |
+| DELETE | `/auth/api/admin/orgs/{uuid}/permission` | Revoke permission from org | Query param: permission_uuid |
+| PATCH | `/auth/api/admin/roles/{uuid}` | Update role | Body: JSON with display_name |
+| POST | `/auth/api/admin/roles/{uuid}/permissions/{uuid}` | Add permission to role | |
+| DELETE | `/auth/api/admin/roles/{uuid}/permissions/{uuid}` | Remove permission from role | |
+| DELETE | `/auth/api/admin/roles/{uuid}` | Delete role | |
+| PATCH | `/auth/api/admin/users/{uuid}/role` | Update user role | Body: JSON with role_uuid |
+| PATCH | `/auth/api/admin/users/{uuid}/info` | Update user info | Body: JSON with display_name |
+| GET | `/auth/api/admin/users/{uuid}` | Get user details | |
+| DELETE | `/auth/api/admin/users/{uuid}` | Delete user | |
+| POST | `/auth/api/admin/users/{uuid}/create-link` | Create device add link | |
+| DELETE | `/auth/api/admin/users/{uuid}/credentials/{uuid}` | Delete user credential | |
+| DELETE | `/auth/api/admin/users/{uuid}/sessions/{key}` | Delete user session | |
+| POST | `/auth/api/admin/oidc-clients/` | Create OIDC client | Body: JSON with client_name, redirect_uris |
+| PATCH | `/auth/api/admin/oidc-clients/{uuid}` | Update OIDC client | Body: JSON with client_name, redirect_uris |
+| PATCH | `/auth/api/admin/oidc-clients/{uuid}/reset-secret` | Reset client secret | |
+| DELETE | `/auth/api/admin/oidc-clients/{uuid}` | Delete OIDC client | |
+| GET | `/auth/api/admin/server-config/` | Get server config | Returns rp_name, auth_host, origins |
+| PATCH | `/auth/api/admin/server-config/` | Update server config | Body: JSON with rp_name, auth_host, origins |
+
+Admins edit user avatars through the same canonical `/auth/api/user/{uuid}/profile.webp` PUT and DELETE endpoints.
+
+### WebSockets: `/auth/ws/*`
+
+| Path | Used for | Notes |
+|---|---|---|
+| `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/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 |
+
+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`)
+
+#### 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.
+- 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.
+
+#### On non-auth hosts:
+- `/auth/` shows only minimal profile and allows logging out of the current site
+- `/auth/api/*` is served normally.
+- `/auth/api/user/*`, `/auth/api/admin/*`, and `/auth/ws/*` don't exist.

docs/Caddy.md

@@ -0,0 +1,79 @@
+# 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`)
+
+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.
+
+We assume the normal unprotected **Caddyfile** for your site looks like this:
+
+```caddyfile
+app.example.com {
+    @public path /.well-known/* /favicon.ico
+    handle @public {
+        root * /var/www/
+        file_server
+    }
+
+    handle {
+        reverse_proxy :3000  # Your app backend
+    }
+}
+```
+
+Note: We use the `handle @name` approach rather than `handle_path` to keep the path unaltered. Unlike bare directives, these blocks will be tried in sequence and each can contain what you'd typically put in your site definition (by default `reverse_proxy` takes precedence and nothing reaches the static files).
+
+We will adapt from this to protect your app.
+
+### Protect your site (auth/setup, auth/require)
+
+```caddyfile
+app.example.com {
+    import auth/setup
+
+    @public path /.well-known/* /favicon.ico
+    handle @public {
+        root * /var/www/
+        file_server
+    }
+
+    @reports path /reports
+    handle @reports {
+        import auth/require perm=myapp:reports
+        reverse_proxy :3000
+    }
+
+    handle {
+        import auth/require max-age=12h
+        reverse_proxy :3000
+    }
+}
+```
+
+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.
+
+### Dedicated Authentication Site
+
+When you setup a separate subdomain for the authentication site, just add to your config another section for the auth host:
+
+```caddyfile
+auth.example.com {
+    reverse_proxy :4401
+}
+```
+
+Remember to specify `paskia serve --auth-host auth.example.com` 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.
+
+Paskia does not require CORS configuration, but it can access the authentication and registration of auth host WS API from the other sites as WebSockets don't require any CORS.
+
+### Override the paskia backend address (AUTH_UPSTREAM)
+
+By default, the auth service is contacted at localhost port 4401. You can point Caddy to a different address by setting the `AUTH_UPSTREAM` environment variable for Caddy.
+
+If unset, the snippets use `:4401` by default.

docs/Headers.md

@@ -0,0 +1,23 @@
+# Paskia Trusted Headers for Backend Apps
+
+| HTTP Header | Meaning | Example |
+|---|---|---|
+| `Remote-User` | Authenticated user UUID | **01c03276-b8f0-**… (string) |
+| `Remote-Name` | User display name | **John Doe** |
+| `Remote-Org` | Organization UUID | Identifier for user's org (string) |
+| `Remote-Org-Name` | Organization display name | **The Company Ltd.** |
+| `Remote-Role` | Role UUID | Identifier for user's role (string) |
+| `Remote-Role-Name` | Role display name | **Employee** |
+| `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-Credential` | Credential UUID | Identifier for the sign-in passkey (string) |
+
+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.
+
+When a request is allowed, the auth service adds these headers by the forward-auth mechanism before proxying to your app as **request headers**. Your app can use them for user context to show on UI, or for its own authentication needs (e.g. prevent different orgs messing up with each other's data, logging which user performed an action).
+
+Only the UUID values should be used for identification needs, because they never change, even when things are renamed (display names change), and are never reused (created on authentication server). They are UUIDv7 so you can also extract the creation timestamp from them.
+
+Any `Remote-*` headers from clients are stripped by our [Caddy configuration](Caddy.md) to avoid dealing with any fake headers.
+
+Note: the headers are intended primarily for the backend, while either frontend or backend (passing the session cookie) can request `/auth/api/user-info` for more complete information, and that is the recommended way to do it in the frontend. See [integration](Integration.md) for more.

docs/Integration.md

@@ -0,0 +1,198 @@
+# Integrating Paskia with your App
+
+This guide covers frontend and backend integration with Paskia. For Caddy forward-auth setup, see [Caddy configuration](Caddy.md).
+
+## Frontend Integration
+
+### Using the paskia-js Module
+
+The [paskia](https://www.npmjs.com/package/paskia) JavaScript module provides utilities for API calls, session validation, and authentication overlays. Works with any framework or vanilla JS.
+
+```html
+<script type="module">
+  import { apiJson, apiFetch, SessionValidator } from 'https://cdn.jsdelivr.net/npm/paskia@latest/dist/paskia.js'
+</script>
+```
+
+Or install to your project:
+
+```sh
+npm install paskia
+```
+
+### API Fetch with Automatic Auth
+
+Use `apiJson` or `apiFetch` for API calls. When a 401/403 response includes an auth URL, the authentication dialog appears automatically, then the request retries. The JSON variant is purely for convenience, doing JSON headers and conversions for you.
+
+```js
+import { apiJson, apiFetch, AuthCancelledError } from 'paskia'
+
+// JSON API call (sets Content-Type, parses response)
+try {
+  const data = await apiJson('/api/endpoint', { method: 'POST', body: { key: 'value' } })
+} catch (e) {
+  if (e instanceof AuthCancelledError) {
+    // User cancelled auth dialog
+  }
+}
+
+// Raw fetch with auth handling (returns Response object)
+const response = await apiFetch('/api/endpoint')
+```
+
+For requests that shouldn't trigger auth dialogs, use standard `fetch` or our `fetchJson`.
+
+### Session Validation Polling
+
+Keep sessions alive and detect when the user logs out or switches accounts:
+
+```js
+import { SessionValidator } from 'paskia'
+
+const validator = new SessionValidator(
+  () => currentUser?.uuid,              // getter for current user ID
+  (error) => handleSessionLost(error)   // callback when session is lost or user changes
+)
+
+validator.start()  // start polling (pauses on idle)
+validator.stop()   // stop polling
+```
+
+The validator calls `/auth/api/validate` 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
+
+### Manual Auth Flow
+
+If you need custom control, handle 401/403 responses manually:
+
+```js
+import { showAuthIframe, AuthCancelledError } from 'paskia'
+
+const response = await fetch('/api/protected')
+if (response.status === 401 || response.status === 403) {
+  const data = await response.json()
+  if (data.auth?.iframe) {
+    try {
+      await showAuthIframe(data.auth.iframe)
+      // Retry the original request
+    } catch (e) {
+      if (e instanceof AuthCancelledError) {
+        // User clicked Back
+      }
+    }
+  }
+}
+```
+
+### User Info and Profile
+
+Get current user details:
+
+```js
+const user = await apiJson('/auth/api/user-info', { method: 'GET' })
+// Returns: { uuid, display_name, credentials, sessions, permissions, ... }
+```
+
+Or link to the built-in profile page: `/auth/`
+
+## Backend Integration
+
+### 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.
+
+```python
+# Example: Python/FastAPI
+@app.get("/api/data")
+def get_data(request: Request):
+    user_id = request.headers.get("Remote-User")
+    org_id = request.headers.get("Remote-Org")
+    permissions = request.headers.get("Remote-Groups", "").split(",")
+    # ...
+```
+
+### Direct Validation from Backend
+
+Your backend can validate sessions directly by calling Paskia's validate endpoint:
+
+```python
+import httpx
+
+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:
+- 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
+
+`POST /auth/api/validate` accepts query parameters:
+
+| Parameter | Description |
+|-----------|-------------|
+| `perm=scope:name` | Require this permission (repeatable) |
+| `max_age=5min` | Require recent passkey use |
+
+Returns 200 with user info on success, 401/403 on failure.
+
+## 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.
+
+### Caddy
+
+This handles both HTTP and WebSocket connections. Caddy's `reverse_proxy` handles HTTP and WebSocket transparently. This is essentially what our Caddy [auth/setup](../caddy/auth/setup) snippet does: `reverse_proxy :4401`.
+
+```caddyfile
+app.example.com {
+    import auth/setup
+    # ... your routes in handle blocks
+}
+```
+
+### Nginx
+
+Certain headers need to be configured for correct host and WS support:
+
+```nginx
+location /auth/ {
+    proxy_pass http://localhost:4401;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+}
+```
+
+### Node.js / Express
+
+Using `http-proxy-middleware`:
+
+```js
+import { createProxyMiddleware } from 'http-proxy-middleware'
+
+app.use('/auth', createProxyMiddleware({ target: 'http://localhost:4401', ws: true, changeOrigin: false }))
+```
+
+### Python / FastAPI
+
+You will need to process and handle `/auth/` for HTTP requests and `/auth/ws/` for WebSockets manually, which is beyond the scope of this documentation.
+
+We highly recommend Caddy instead as the simpler and more production-worthy solution that Just Works.

e2e/package-lock.json

@@ -10,7 +10,7 @@
       "devDependencies": {
         "@playwright/test": "^1.49.0",
         "@simplewebauthn/browser": "^13.1.2",
-        "@types/bun": "^1.3.3",
+        "@types/node": "*",
         "c8": "^10.1.3"
       }
     },
@@ -92,11 +92,13 @@
       }
     },
     "node_modules/@playwright/test": {
-      "version": "1.57.0",
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.58.2.tgz",
+      "integrity": "sha512-akea+6bHYBBfA9uQqSYmlJXn61cTa+jbO87xVLCWbTqbWadRVmhxlXATaOjOgcBaWU4ePo0wB41KMFv3o35IXA==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright": "1.57.0"
+        "playwright": "1.58.2"
       },
       "bin": {
         "playwright": "cli.js"
@@ -107,17 +109,11 @@
     },
     "node_modules/@simplewebauthn/browser": {
       "version": "13.2.2",
+      "resolved": "https://registry.npmjs.org/@simplewebauthn/browser/-/browser-13.2.2.tgz",
+      "integrity": "sha512-FNW1oLQpTJyqG5kkDg5ZsotvWgmBaC6jCHR7Ej0qUNep36Wl9tj2eZu7J5rP+uhXgHaLk+QQ3lqcw2vS5MX1IA==",
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/@types/bun": {
-      "version": "1.3.3",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "bun-types": "1.3.3"
-      }
-    },
     "node_modules/@types/istanbul-lib-coverage": {
       "version": "2.0.6",
       "resolved": "https://registry.npmjs.org/@types/istanbul-lib-coverage/-/istanbul-lib-coverage-2.0.6.tgz",
@@ -126,7 +122,9 @@
       "license": "MIT"
     },
     "node_modules/@types/node": {
-      "version": "24.10.1",
+      "version": "25.2.3",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.2.3.tgz",
+      "integrity": "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -176,14 +174,6 @@
         "balanced-match": "^1.0.0"
       }
     },
-    "node_modules/bun-types": {
-      "version": "1.3.3",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@types/node": "*"
-      }
-    },
     "node_modules/c8": {
       "version": "10.1.3",
       "resolved": "https://registry.npmjs.org/c8/-/c8-10.1.3.tgz",
@@ -412,6 +402,21 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
     "node_modules/get-caller-file": {
       "version": "2.0.5",
       "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
@@ -426,6 +431,7 @@
       "version": "10.5.0",
       "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz",
       "integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==",
+      "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -674,11 +680,13 @@
       }
     },
     "node_modules/playwright": {
-      "version": "1.57.0",
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.58.2.tgz",
+      "integrity": "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright-core": "1.57.0"
+        "playwright-core": "1.58.2"
       },
       "bin": {
         "playwright": "cli.js"
@@ -691,7 +699,9 @@
       }
     },
     "node_modules/playwright-core": {
-      "version": "1.57.0",
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.58.2.tgz",
+      "integrity": "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg==",
       "dev": true,
       "license": "Apache-2.0",
       "bin": {
@@ -712,9 +722,9 @@
       }
     },
     "node_modules/semver": {
-      "version": "7.7.3",
+      "version": "7.7.4",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
-      "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==",
+      "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
       "dev": true,
       "license": "ISC",
       "bin": {
@@ -894,6 +904,8 @@
     },
     "node_modules/undici-types": {
       "version": "7.16.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz",
+      "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==",
       "dev": true,
       "license": "MIT"
     },

e2e/package.json

@@ -5,18 +5,18 @@
   "description": "E2E tests for Paskia using Playwright with Virtual Authenticator",
   "type": "module",
   "scripts": {
-    "test": "bunx playwright test",
+    "test": "npx playwright test",
-    "test:headed": "bunx playwright test --headed",
+    "test:headed": "npx playwright test --headed",
-    "test:debug": "bunx playwright test --debug",
+    "test:debug": "npx playwright test --debug",
-    "test:ui": "bunx playwright test --ui",
+    "test:ui": "npx playwright test --ui",
-    "test:coverage": "COVERAGE=1 bunx playwright test",
+    "test:coverage": "COVERAGE=1 npx playwright test",
-    "report": "bunx playwright show-report",
+    "report": "npx playwright show-report",
-    "install:browsers": "bunx playwright install chromium"
+    "install:browsers": "npx playwright install chromium"
   },
   "devDependencies": {
     "@playwright/test": "^1.49.0",
     "@simplewebauthn/browser": "^13.1.2",
-    "@types/bun": "^1.3.3",
+    "@types/node": "*",
     "c8": "^10.1.3"
   }
 }

e2e/playwright.config.js

@@ -4,7 +4,7 @@ import { defineConfig, devices } from '@playwright/test'
  * Playwright configuration for Paskia E2E tests.
  * Uses Chrome's Virtual Authenticator for automated passkey testing.
  *
- * Run with: bun run test
+ * Run with: npm test
  */
 
 export default defineConfig({

e2e/tests/10-passkey.spec.ts

@@ -97,14 +97,14 @@ test.describe('Passkey Authentication E2E', () => {
     // Verify registration result
     expect(result.session_token).toBeDefined()
     expect(result.session_token).toHaveLength(16)
-    expect(result.user_uuid).toBeDefined()
+    expect(result.user).toBeDefined()
-    expect(result.credential_uuid).toBeDefined()
+    expect(result.credential).toBeDefined()
     expect(result.message).toContain('successfully')
 
     // Store for subsequent tests
     sessionToken = result.session_token
-    userUuid = result.user_uuid
+    userUuid = result.user
-    credentialUuid = result.credential_uuid
+    credentialUuid = result.credential
 
     // Save session token for other test groups to use
     saveSessionToken(sessionToken)
@@ -138,9 +138,9 @@ test.describe('Passkey Authentication E2E', () => {
     const validation = await validateSession(page, baseUrl, sessionToken)
 
     expect(validation.valid).toBe(true)
-    expect(validation.user_uuid).toBe(userUuid)
+    expect(validation.ctx.user.uuid).toBe(userUuid)
 
-    console.log(`✓ Session validated for user: ${validation.user_uuid}`)
+    console.log(`✓ Session validated for user: ${validation.ctx.user.uuid}`)
   })
 
   test('should retrieve user info', async ({ page }) => {
@@ -148,10 +148,10 @@ test.describe('Passkey Authentication E2E', () => {
 
     const userInfo = await getUserInfo(page, baseUrl, sessionToken)
 
-    expect(userInfo.user.user_uuid).toBe(userUuid)
+    expect(userInfo.user.uuid).toBe(userUuid)
-    expect(userInfo.user.user_name).toBe('Admin User')
+    expect(userInfo.user.display_name).toBe('Admin User')
     expect(userInfo.credentials).toBeDefined()
-    expect(userInfo.credentials.length).toBeGreaterThanOrEqual(1)
+    expect(Object.keys(userInfo.credentials).length).toBeGreaterThanOrEqual(1)
 
     // Navigate to profile and take screenshot
     const cookieName = getSessionCookieName()
@@ -169,8 +169,8 @@ test.describe('Passkey Authentication E2E', () => {
     await page.screenshot({ path: 'test-results/profile-view.png' })
     console.log('✓ Screenshot saved: test-results/profile-view.png')
 
-    console.log(`✓ User info retrieved: ${userInfo.user.user_name}`)
+    console.log(`✓ User info retrieved: ${userInfo.user.display_name}`)
-    console.log(`✓ Credentials count: ${userInfo.credentials.length}`)
+    console.log(`✓ Credentials count: ${Object.keys(userInfo.credentials).length}`)
   })
 
   test('should authenticate with existing passkey', async ({ page, virtualAuthenticator }) => {
@@ -190,7 +190,7 @@ test.describe('Passkey Authentication E2E', () => {
       displayName: 'Admin User (test device)'
     })
 
-    console.log(`✓ Added test credential: ${regResult.credential_uuid}`)
+    console.log(`✓ Added test credential: ${regResult.credential}`)
 
     // Now logout and authenticate with the fresh credential
     await logout(page, baseUrl, regResult.session_token)
@@ -201,7 +201,7 @@ test.describe('Passkey Authentication E2E', () => {
 
     expect(result.session_token).toBeDefined()
     expect(result.session_token).toHaveLength(16)
-    expect(result.user_uuid).toBe(userUuid)
+    expect(result.user).toBe(userUuid)
 
     // Update session token for subsequent tests
     sessionToken = result.session_token
@@ -209,7 +209,7 @@ test.describe('Passkey Authentication E2E', () => {
     // Save session token for other test groups to use
     saveSessionToken(sessionToken)
 
-    console.log(`✓ Authenticated as user: ${result.user_uuid}`)
+    console.log(`✓ Authenticated as user: ${result.user}`)
     console.log(`✓ New session token: ${sessionToken.substring(0, 4)}...`)
   })
 
@@ -219,7 +219,7 @@ test.describe('Passkey Authentication E2E', () => {
     const validation = await validateSession(page, baseUrl, sessionToken)
 
     expect(validation.valid).toBe(true)
-    expect(validation.user_uuid).toBe(userUuid)
+    expect(validation.ctx.user.uuid).toBe(userUuid)
 
     console.log(`✓ New session validated`)
   })
@@ -291,8 +291,8 @@ test.describe('Device Addition Dialog', () => {
     // Wait for the profile view to load
     await page.waitForSelector('[data-view="profile"]', { timeout: 5000 })
 
-    // Click the "Add Another Device" button
+    // Click the "Another Device" button
-    const addDeviceButton = page.getByRole('button', { name: 'Add Another Device' })
+    const addDeviceButton = page.getByRole('button', { name: 'Another Device' })
     await expect(addDeviceButton).toBeVisible()
     await addDeviceButton.click()
 
@@ -301,7 +301,7 @@ test.describe('Device Addition Dialog', () => {
     await expect(dialog).toBeVisible({ timeout: 5000 })
 
     // Verify dialog contains expected elements
-    await expect(dialog.locator('h2')).toContainText('Device Registration Link')
+    await expect(dialog.locator('h2')).toContainText('Add Another Device')
 
     // Wait for QR code to be generated (canvas should have content)
     const qrCanvas = dialog.locator('.qr-code')
@@ -318,16 +318,16 @@ test.describe('Device Addition Dialog', () => {
     expect(linkHref).toContain('http://localhost:4404/auth/')
     console.log(`✓ Device link displayed: ${linkText} (href: ${linkHref})`)
 
-    // Verify expiration warning is shown
+    // Verify help text is shown
-    await expect(dialog.locator('.reg-help')).toContainText('Expires')
+    await expect(dialog.locator('.reg-help')).toContainText('Scan this QR code')
 
     // Take screenshot of the dialog
     await dialog.screenshot({ path: 'test-results/device-addition-dialog.png' })
     console.log(`✓ Screenshot saved: test-results/device-addition-dialog.png`)
 
-    // Verify Copy Link button exists
+    // Verify the QR link element is clickable (copy functionality is built into clicking it)
-    const copyButton = dialog.getByRole('button', { name: 'Copy Link' })
+    const qrLink = dialog.locator('a.qr-link')
-    await expect(copyButton).toBeVisible()
+    await expect(qrLink).toBeVisible()
 
     // Close the dialog (use the text button, not the icon button)
     const closeButton = dialog.locator('button.btn-secondary', { hasText: 'Close' })
@@ -357,12 +357,12 @@ test.describe('Device Addition Dialog', () => {
     await page.waitForSelector('[data-view="profile"]', { timeout: 5000 })
 
     // Open the dialog
-    await page.getByRole('button', { name: 'Add Another Device' }).click()
+    await page.getByRole('button', { name: 'Another Device' }).click()
     const dialog = page.locator('.device-dialog')
     await expect(dialog).toBeVisible({ timeout: 5000 })
 
     // Extract the reset token from the displayed URL
-    const linkText = dialog.locator('.qr-link p')
+    const linkText = dialog.locator('.qr-link .link-text')
     const linkContent = await linkText.textContent()
 
     // URL format: localhost/auth/word1.word2.word3.word4.word5
@@ -405,7 +405,7 @@ test.describe('Device Addition Dialog', () => {
   })
 })
 
-test.describe('ProfileView - Add New Passkey', () => {
+test.describe('ProfileView - Register New', () => {
   const baseUrl = process.env.BASE_URL || 'http://localhost:4404'
 
   test('should show credentials list in profile', async ({ page }) => {
@@ -427,7 +427,7 @@ test.describe('ProfileView - Add New Passkey', () => {
     console.log(`✓ Profile shows ${credentialItems} credential(s) in list`)
   })
 
-  test('should add a new passkey using Add New Passkey button', async ({ page }) => {
+  test('should add a new passkey using Register New button', async ({ page }) => {
     const sessionToken = getSavedSessionToken()
     test.skip(!sessionToken, 'Requires saved session token')
 
@@ -444,8 +444,8 @@ test.describe('ProfileView - Add New Passkey', () => {
     const initialCredentialCount = await page.locator('.credential-item').count()
     console.log(`Initial credential count: ${initialCredentialCount}`)
 
-    // Click "Add New Passkey" button
+    // Click "Register New" button
-    const addPasskeyBtn = page.locator('button:has-text("Add New Passkey")')
+    const addPasskeyBtn = page.locator('button:has-text("Register New")')
     await expect(addPasskeyBtn).toBeVisible()
     await addPasskeyBtn.click()
 
@@ -490,7 +490,7 @@ test.describe('ProfileView - Add New Passkey', () => {
 
     // Try to add a passkey - with excludeCredentials the authenticator should
     // prevent re-registration of the same credential
-    const addPasskeyBtn = page.locator('button:has-text("Add New Passkey")')
+    const addPasskeyBtn = page.locator('button:has-text("Register New")')
     await expect(addPasskeyBtn).toBeVisible()
     await addPasskeyBtn.click()
 
@@ -541,8 +541,8 @@ test.describe('ProfileView - Multi-Authenticator', () => {
     await page.waitForSelector('.credential-list', { timeout: 10000 })
     const initialCredentialCount = await page.locator('.credential-item').count()
 
-    // Click "Add New Passkey" button
+    // Click "Register New" button
-    const addPasskeyBtn = page.locator('button:has-text("Add New Passkey")')
+    const addPasskeyBtn = page.locator('button:has-text("Register New")')
     await expect(addPasskeyBtn).toBeVisible()
     await addPasskeyBtn.click()
 

e2e/tests/20-api-auth.spec.ts

@@ -10,6 +10,12 @@ import {
   logout,
 } from './fixtures/passkey-helpers'
 import type { Page, Frame } from '@playwright/test'
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
 
 /**
  * E2E tests for API mode authentication flows.
@@ -55,8 +61,18 @@ async function clearSessionCookie(page: Page): Promise<void> {
 /**
  * Set up the test page using the examples page directly.
  * The examples page already has iframe handling - we just add a Promise wrapper.
+ * We route the paskia-js module request to serve from the local dist.
  */
 async function setupTestHarness(page: Page): Promise<void> {
+  // Serve paskia.js from the local filesystem since the server doesn't serve /paskia-js/
+  const paskiaJsPath = join(__dirname, '..', '..', 'paskia-js', 'dist', 'paskia.js')
+  await page.route('**/paskia-js/dist/paskia.js', async route => {
+    const body = readFileSync(paskiaJsPath, 'utf-8')
+    await route.fulfill({
+      body,
+      contentType: 'application/javascript',
+    })
+  })
   // Navigate to the examples page which already has the auth iframe handling
   await page.goto(`${baseUrl}/auth/examples/`)
 }
@@ -84,7 +100,7 @@ async function makeApiCall(page: Page, url: string, method = 'GET'): Promise<{ s
           // Wait a tick for the page's handler to retry, then make our own call
           setTimeout(async () => {
             try {
-              const response = await fetch(url, { method, credentials: 'include' });
+              const response = await fetch(url, { method });
               if (response.status === 204) {
                 resolve({ status: 204 });
               } else if (response.ok) {
@@ -111,7 +127,7 @@ async function makeApiCall(page: Page, url: string, method = 'GET'): Promise<{ s
       setTimeout(async () => {
         if (resolved) return;
         try {
-          const response = await fetch(url, { method, credentials: 'include' });
+          const response = await fetch(url, { method });
           // Only resolve if this is a success or non-auth error
           if (response.status !== 401 && response.status !== 403) {
             if (resolved) return;
@@ -143,8 +159,8 @@ async function makeApiCall(page: Page, url: string, method = 'GET'): Promise<{ s
  * Wait for auth iframe to appear and return a reference to it.
  */
 async function waitForAuthIframe(page: Page, timeout = 5000): Promise<Frame> {
-  await page.waitForSelector('#auth-iframe', { timeout })
+  await page.waitForSelector('#paskia-iframe', { timeout })
-  const iframe = page.frameLocator('#auth-iframe')
+  const iframe = page.frameLocator('#paskia-iframe')
   // Wait for iframe content to load
   await iframe.locator('.view-root').waitFor({ timeout })
   return page.frame({ url: /\/auth\/restricted\// })!
@@ -154,14 +170,14 @@ async function waitForAuthIframe(page: Page, timeout = 5000): Promise<Frame> {
  * Wait for auth iframe to disappear.
  */
 async function waitForAuthIframeHidden(page: Page, timeout = 5000): Promise<void> {
-  await page.waitForSelector('#auth-iframe', { state: 'detached', timeout })
+  await page.waitForSelector('#paskia-iframe', { state: 'detached', timeout })
 }
 
 /**
  * Click Back button in auth iframe.
  */
 async function clickBackInIframe(page: Page): Promise<void> {
-  const iframe = page.frameLocator('#auth-iframe')
+  const iframe = page.frameLocator('#paskia-iframe')
   await iframe.getByRole('button', { name: 'Back' }).click()
 }
 
@@ -169,7 +185,7 @@ async function clickBackInIframe(page: Page): Promise<void> {
  * Click Login button in auth iframe.
  */
 async function clickLoginInIframe(page: Page): Promise<void> {
-  const iframe = page.frameLocator('#auth-iframe')
+  const iframe = page.frameLocator('#paskia-iframe')
   await iframe.getByRole('button', { name: 'Login' }).click()
 }
 
@@ -177,7 +193,7 @@ async function clickLoginInIframe(page: Page): Promise<void> {
  * Click Verify button in auth iframe (for reauth mode).
  */
 async function clickVerifyInIframe(page: Page): Promise<void> {
-  const iframe = page.frameLocator('#auth-iframe')
+  const iframe = page.frameLocator('#paskia-iframe')
   await iframe.getByRole('button', { name: 'Verify' }).click()
 }
 
@@ -185,7 +201,7 @@ async function clickVerifyInIframe(page: Page): Promise<void> {
  * Click Logout button in auth iframe (for forbidden mode).
  */
 async function clickLogoutInIframe(page: Page): Promise<void> {
-  const iframe = page.frameLocator('#auth-iframe')
+  const iframe = page.frameLocator('#paskia-iframe')
   await iframe.getByRole('button', { name: 'Logout' }).click()
 }
 
@@ -200,11 +216,11 @@ test.describe('API Mode - 401 Login Flow', () => {
     await clearSessionCookie(page)
 
     // Make API call that triggers 401 (don't await - it blocks until iframe resolves)
-    const apiCallPromise = makeApiCall(page, '/auth/api/user-info', 'POST').catch(e => e)
+    const apiCallPromise = makeApiCall(page, '/auth/api/user-info', 'GET').catch(e => e)
     console.log('✓ Auth iframe appeared on 401')
 
     // Verify it's in login mode (not reauth)
-    const iframe = page.frameLocator('#auth-iframe')
+    const iframe = page.frameLocator('#paskia-iframe')
     await expect(iframe.locator('h1')).toContainText('🔐')
     await expect(iframe.getByRole('button', { name: 'Login' })).toBeVisible()
 
@@ -242,7 +258,7 @@ test.describe('API Mode - 401 Login Flow', () => {
       resetToken: deviceToken,
       displayName: 'API Test Device',
     })
-    console.log(`✓ Registered credential: ${regResult.credential_uuid}`)
+    console.log(`✓ Registered credential: ${regResult.credential}`)
 
     // Logout to clear session (but keep the passkey in virtual authenticator)
     await logout(page, baseUrl, regResult.session_token)
@@ -252,7 +268,7 @@ test.describe('API Mode - 401 Login Flow', () => {
     await setupTestHarness(page)
 
     // Make API call that triggers 401
-    const apiCallPromise = makeApiCall(page, '/auth/api/user-info', 'POST')
+    const apiCallPromise = makeApiCall(page, '/auth/api/user-info', 'GET')
 
     // Wait for auth iframe to appear
     await waitForAuthIframe(page)
@@ -314,7 +330,7 @@ test.describe('API Mode - 401 Reauth Flow', () => {
     console.log('✓ Reauth iframe appeared (session older than max_age)')
 
     // Verify it's in reauth mode
-    const iframe = page.frameLocator('#auth-iframe')
+    const iframe = page.frameLocator('#paskia-iframe')
     await expect(iframe.locator('h1')).toContainText('Additional Authentication')
     await expect(iframe.getByRole('button', { name: 'Verify' })).toBeVisible()
 
@@ -362,7 +378,7 @@ test.describe('API Mode - 401 Reauth Flow', () => {
     await waitForAuthIframe(page)
     console.log('✓ Reauth iframe appeared')
 
-    const iframe = page.frameLocator('#auth-iframe')
+    const iframe = page.frameLocator('#paskia-iframe')
     await expect(iframe.locator('h1')).toContainText('Additional Authentication')
 
     // Click Verify - virtual authenticator handles passkey
@@ -394,7 +410,7 @@ test.describe('API Mode - 403 Forbidden Flow', () => {
     const apiCallPromise = makeApiCall(page, '/auth/api/forward?perm=auth:admin', 'GET').catch(e => e)
 
     // Check if auth iframe appeared
-    const iframeAppeared = await page.waitForSelector('#auth-iframe', { timeout: 3000 }).then(() => true).catch(() => false)
+    const iframeAppeared = await page.waitForSelector('#paskia-iframe', { timeout: 3000 }).then(() => true).catch(() => false)
 
     if (!iframeAppeared) {
       // User might already have admin permission
@@ -410,7 +426,7 @@ test.describe('API Mode - 403 Forbidden Flow', () => {
 
     // Wait for view to stabilize and check mode
     await page.waitForTimeout(500)
-    const iframe = page.frameLocator('#auth-iframe')
+    const iframe = page.frameLocator('#paskia-iframe')
     const headingText = await iframe.locator('h1').textContent()
     console.log(`  Heading: ${headingText}`)
 
@@ -459,7 +475,7 @@ test.describe('API Mode - 403 Forbidden Flow', () => {
     const apiCallPromise = makeApiCall(page, '/auth/api/forward?perm=auth:admin', 'GET').catch(e => e)
 
     // Check if auth iframe appeared
-    const iframeAppeared = await page.waitForSelector('#auth-iframe', { timeout: 3000 }).then(() => true).catch(() => false)
+    const iframeAppeared = await page.waitForSelector('#paskia-iframe', { timeout: 3000 }).then(() => true).catch(() => false)
 
     if (!iframeAppeared) {
       const result = await apiCallPromise
@@ -470,7 +486,7 @@ test.describe('API Mode - 403 Forbidden Flow', () => {
     }
 
     await waitForAuthIframe(page)
-    const iframe = page.frameLocator('#auth-iframe')
+    const iframe = page.frameLocator('#paskia-iframe')
     await page.waitForTimeout(500)
 
     const headingText = await iframe.locator('h1').textContent()
@@ -534,7 +550,7 @@ test.describe('API Mode - Direct API Response Format', () => {
     expect(data.auth).toBeDefined()
     expect(data.auth.iframe).toBeDefined()
     expect(data.auth.mode).toBe('login')
-    expect(data.auth.iframe).toContain('/auth/restricted/')
+    expect(data.auth.iframe).toContain('/auth/restricted/iframe')
 
     console.log(`✓ 401 response includes auth.iframe: ${data.auth.iframe}`)
   })

e2e/tests/fixtures/passkey-helpers.ts

@@ -12,17 +12,51 @@ const stateFile = join(__dirname, '..', '..', 'test-data', 'test-state.json')
  */
 
 export interface RegistrationResult {
-  user_uuid: string
+  user: string
-  credential_uuid: string
+  credential: string
   session_token: string
   message: string
 }
 
 export interface AuthenticationResult {
-  user_uuid: string
+  user: string
   session_token: string
 }
 
+export interface SessionContext {
+  user: { uuid: string; display_name: string }
+  org: { uuid: string; display_name: string }
+  role: { uuid: string; display_name: string }
+  permissions: string[]
+}
+
+export interface UserInfo {
+  ctx: SessionContext
+  created_at: string
+  last_seen: string
+  visits: number
+  credentials: Array<{
+    credential: string
+    aaguid: string
+    created_at: string
+    last_used: string | null
+    last_verified: string | null
+    sign_count: number
+    is_current_session: boolean
+  }>
+  aaguid_info: Record<string, { name: string; icon?: string; icon_dark?: string }>
+  sessions: Array<{
+    id: string
+    credential: string
+    host: string
+    ip: string
+    user_agent: string
+    last_renewed: string
+    is_current: boolean
+    is_current_host: boolean
+  }>
+}
+
 /**
  * Get the bootstrap reset token from the test state file.
  */
@@ -159,7 +193,8 @@ export async function registerPasskey(
   baseUrl: string,
   options: { resetToken?: string; displayName?: string } = {}
 ): Promise<RegistrationResult> {
-  return await page.evaluate(async ({ baseUrl, resetToken, displayName }) => {
+  // Step 1: Do WebSocket registration + exchange code in browser context
+  const wsResult = await page.evaluate(async ({ baseUrl, resetToken, displayName }) => {
     // Build WebSocket URL with query parameters
     let wsUrl = `${baseUrl.replace('http', 'ws')}/auth/ws/register`
     const params: string[] = []
@@ -169,6 +204,7 @@ export async function registerPasskey(
 
     return new Promise<any>((resolve, reject) => {
       const ws = new WebSocket(wsUrl)
+      let done = false
 
       ws.onopen = () => {
         console.log('WebSocket connected for registration')
@@ -179,15 +215,31 @@ export async function registerPasskey(
 
         // Check for error response
         if (data.detail) {
+          done = true
           ws.close()
           reject(new Error(data.detail))
           return
         }
 
-        // Check if this is the final success response
+        // Check if this is the final success response (exchange_code flow)
-        if (data.session_token) {
+        if (data.exchange_code) {
+          done = true
           ws.close()
-          resolve(data)
+          // Exchange the code for a session cookie
+          try {
+            const resp = await fetch(`${baseUrl}/auth/api/set-session`, {
+              method: 'POST',
+              headers: { 'Authorization': `Bearer ${data.exchange_code}` },
+            })
+            if (!resp.ok) throw new Error(`Exchange failed: ${resp.status}`)
+            resolve({
+              user: data.user,
+              credential: data.credential,
+              message: data.message || 'Registration successful',
+            })
+          } catch (err: any) {
+            reject(new Error(`Code exchange failed: ${err.message}`))
+          }
           return
         }
 
@@ -259,12 +311,21 @@ export async function registerPasskey(
       }
 
       ws.onclose = (event) => {
-        if (!event.wasClean && event.code !== 1000) {
+        if (!done && !event.wasClean && event.code !== 1000) {
           reject(new Error(`WebSocket closed unexpectedly: ${event.code}`))
         }
       }
     })
   }, { baseUrl, resetToken: options.resetToken, displayName: options.displayName })
+
+  // Step 2: Extract the session token from the cookie set by the exchange
+  const cookies = await page.context().cookies()
+  const cookieName = getSessionCookieName()
+  const sessionCookie = cookies.find(c => c.name === cookieName)
+  return {
+    ...wsResult,
+    session_token: sessionCookie?.value || '',
+  }
 }
 
 /**
@@ -275,11 +336,13 @@ export async function authenticatePasskey(
   page: Page,
   baseUrl: string
 ): Promise<AuthenticationResult> {
-  return await page.evaluate(async ({ baseUrl }) => {
+  // Step 1: Do WebSocket authentication + exchange code in browser context
+  const wsResult = await page.evaluate(async ({ baseUrl }) => {
     const wsUrl = `${baseUrl.replace('http', 'ws')}/auth/ws/authenticate`
 
     return new Promise<any>((resolve, reject) => {
       const ws = new WebSocket(wsUrl)
+      let done = false
 
       ws.onopen = () => {
         console.log('WebSocket connected for authentication')
@@ -290,15 +353,27 @@ export async function authenticatePasskey(
 
         // Check for error response
         if (data.detail) {
+          done = true
           ws.close()
           reject(new Error(data.detail))
           return
         }
 
-        // Check if this is the final success response
+        // Check if this is the final success response (exchange_code flow)
-        if (data.session_token) {
+        if (data.exchange_code) {
+          done = true
           ws.close()
-          resolve(data)
+          // Exchange the code for a session cookie
+          try {
+            const resp = await fetch(`${baseUrl}/auth/api/set-session`, {
+              method: 'POST',
+              headers: { 'Authorization': `Bearer ${data.exchange_code}` },
+            })
+            if (!resp.ok) throw new Error(`Exchange failed: ${resp.status}`)
+            resolve({ user: data.user })
+          } catch (err: any) {
+            reject(new Error(`Code exchange failed: ${err.message}`))
+          }
           return
         }
 
@@ -361,12 +436,21 @@ export async function authenticatePasskey(
       }
 
       ws.onclose = (event) => {
-        if (!event.wasClean && event.code !== 1000) {
+        if (!done && !event.wasClean && event.code !== 1000) {
           reject(new Error(`WebSocket closed unexpectedly: ${event.code}`))
         }
       }
     })
   }, { baseUrl })
+
+  // Step 2: Extract the session token from the cookie set by the exchange
+  const cookies = await page.context().cookies()
+  const cookieName = getSessionCookieName()
+  const sessionCookie = cookies.find(c => c.name === cookieName)
+  return {
+    ...wsResult,
+    session_token: sessionCookie?.value || '',
+  }
 }
 
 /**
@@ -376,7 +460,7 @@ export async function validateSession(
   page: Page,
   baseUrl: string,
   sessionToken: string
-): Promise<{ valid: boolean; user_uuid: string; renewed: boolean }> {
+): Promise<{ valid: boolean; ctx: SessionContext; renewed: boolean }> {
   const cookieName = getSessionCookieName()
   const response = await page.request.post(`${baseUrl}/auth/api/validate`, {
     headers: {
@@ -393,9 +477,9 @@ export async function getUserInfo(
   page: Page,
   baseUrl: string,
   sessionToken: string
-): Promise<any> {
+): Promise<UserInfo> {
   const cookieName = getSessionCookieName()
-  const response = await page.request.post(`${baseUrl}/auth/api/user-info`, {
+  const response = await page.request.get(`${baseUrl}/auth/api/user-info`, {
     headers: {
       'Cookie': `${cookieName}=${sessionToken}`,
     },

e2e/tests/global-setup.ts

@@ -1,6 +1,6 @@
-import { spawn } from 'child_process'
+import { execSync, spawn } 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))
@@ -31,6 +31,11 @@ export default async function globalSetup() {
     mkdirSync(testDataDir, { recursive: true })
   }
 
+  // Build the package first
+  console.log('  Building package with uv build...')
+  execSync('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')
@@ -42,21 +47,28 @@ export default async function globalSetup() {
   const serverArgs = COLLECT_COVERAGE
     ? [
         'run', 'coverage', 'run', '--parallel-mode',
-        '-m', 'paskia.fastapi', 'serve', 'localhost:4404',
+        '-m', 'paskia', '-l', 'localhost:4404',
         '--rp-id', 'localhost'
       ]
     : [
-        'run', 'paskia', 'serve', 'localhost:4404',
+        'run', 'paskia', '-l', 'localhost:4404',
         '--rp-id', 'localhost'
       ]
 
+  // Use a fresh database file for tests
+  const testDbFile = join(testDataDir, 'test.paskiadb')
+
+  if (existsSync(testDbFile)) {
+    console.log('  Removing stale test database...')
+    rmSync(testDbFile, { force: true, recursive: true })
+  }
+
   // Start the server using Node's spawn
-  // Use in-memory SQLite for faster tests
   const serverProcess = spawn('uv', serverArgs, {
     cwd: projectRoot,
     env: {
       ...process.env,
-      PASKIA_DB: 'sqlite+aiosqlite:///:memory:',
+      PASKIA_DB: testDbFile,
       COVERAGE_FILE: join(projectRoot, '.coverage'),
     },
     stdio: ['ignore', 'pipe', 'pipe'],

e2e/tests/global-teardown.ts

@@ -59,18 +59,11 @@ export default async function globalTeardown() {
     rmSync(stateFile, { force: true })
   }
 
-  // Optionally clean up test database (keep it for debugging by default)
+  // Clean up test database
-  if (process.env.CLEANUP_TEST_DB === 'true') {
+  const testDbFile = join(testDataDir, 'test.paskiadb')
-    const dbPath = join(testDataDir, 'test.sqlite')
+  if (existsSync(testDbFile)) {
-    if (existsSync(dbPath)) {
+    console.log('  Removing test database...')
-      console.log('  Removing test database...')
+    rmSync(testDbFile, { force: true, recursive: true })
-      rmSync(dbPath)
-    }
-    // Remove wal/shm files too
-    for (const ext of ['-wal', '-shm']) {
-      const file = dbPath + ext
-      if (existsSync(file)) rmSync(file)
-    }
   }
 
   // Generate Python coverage report if coverage was collected

e2e/tsconfig.json

@@ -8,7 +8,7 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "resolveJsonModule": true,
-    "types": ["bun-types"]
+    "types": ["node"]
   },
   "include": ["tests/**/*.ts", "playwright.config.ts"],
   "exclude": ["node_modules"]

examples/index.html

@@ -8,26 +8,6 @@
         :root {
             color-scheme: light dark;  /* Automatic themes by browser */
         }
-        /* Login/reauth/forbidden dialog will appear in this iframe */
-        #auth-iframe {
-            /* Full viewport overlay */
-            border: none;
-            position: fixed;
-            top: 0;
-            left: 0;
-            width: 100%;
-            height: 100%;
-            z-index: 9999;
-            /* Optional transparent background with optional blur backdrop */
-            color-scheme: auto;
-            background: transparent;
-            backdrop-filter: blur(.1rem) brightness(0.7);
-            -webkit-backdrop-filter: blur(.1rem) brightness(0.7);
-        }
-        /* Prevent background scroll when auth-iframe is shown */
-        body:has(#auth-iframe) {
-            overflow: hidden;
-        }
     </style>
 </head>
 <body>
@@ -47,7 +27,7 @@
             <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="apiCall('/auth/api/user-info', 'POST')">📋 Get User Info</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>
                 <button onclick="logout()">🚪 Logout</button>
@@ -65,99 +45,50 @@
         </div>
     </div>
 
-    <script>
+    <script type="module">
+        import { apiFetch, apiJson, AuthCancelledError } from '/paskia-js/dist/paskia.js'
+
         const output = document.getElementById('output');
-        let pendingCall = null;  // Stores the API call to retry after auth
-
-        // The auth iframe posts messages when authentication completes or is cancelled.
-        // Message types: 'auth-success' (proceed), 'auth-back' (user cancelled)
-        // Errors during auth stay in the dialog allowing retry, no message is sent.
-        window.addEventListener('message', (event) => {
-            const { type, message } = event.data || {};
-
-            if (type === 'auth-success') {
-                log('✓ Authentication successful, retrying...');
-                hideAuthIframe();
-                // Retry the original API call that triggered authentication
-                if (pendingCall) {
-                    const { url, method } = pendingCall;
-                    pendingCall = null;
-                    apiCall(url, method);
-                }
-            } else if (type === 'auth-back') {
-                log(message || 'Authentication cancelled');
-                hideAuthIframe();
-                pendingCall = null;
-            }
-        });
-
-        // Make an API call, handling 401/403 by showing the auth iframe.
-        // The server returns JSON with auth.iframe URL when authentication is needed.
-        async function apiCall(url, method = 'GET') {
-            log(`${method} ${url}...`);
-
-            const response = await fetch(url, { method, credentials: 'include' });
-
-            // Server returns 401 (login/reauth) or 403 (missing permissions)
-            // with a JSON body containing the iframe URL for authentication
-            if (response.status === 401 || response.status === 403) {
-                const data = await response.json();
-                if (data.auth?.iframe) {
-                    const mode = data.auth.mode;  // 'login' or 'reauth'
-                    log(`${mode === 'reauth' ? 'Re-authentication' : 'Authentication'} required...`);
-                    pendingCall = { url, method };
-                    showAuthIframe(data.auth.iframe);
-                    return;
-                }
-                log(`Error: ${response.status} - ${data.detail}`);
-                return;
-            }
-
-            // Forward endpoint returns 204 on success (Caddy then adds Remote-* headers)
-            if (response.status === 204) {
-                log('✓ Success (204 No Content)\nHeaders:\n' +
-                    [...response.headers].filter(([k]) => k.startsWith('remote-'))
-                        .map(([k, v]) => `  ${k}: ${v}`).join('\n'));
-                return;
-            }
-
-            if (!response.ok) {
-                log(`Error: ${response.status} ${response.statusText}`);
-                return;
-            }
-
-            const data = await response.json();
-            log('✓ Response:\n' + JSON.stringify(data, null, 2));
-        }
-
-        async function logout() {
-            await fetch('/auth/api/logout', { method: 'POST', credentials: 'include' });
-            log('Logged out');
-        }
-
-        // Create fullscreen iframe for authentication.
-        // The 'allow' attribute enables WebAuthn (passkey) API inside the iframe.
-        function showAuthIframe(url) {
-            hideAuthIframe();
-            const iframe = document.createElement('iframe');
-            iframe.id = 'auth-iframe';
-            iframe.src = url;
-            document.body.appendChild(iframe);
-            log("Authentication dialog open...")
-        }
-
-        function hideAuthIframe() {
-            document.getElementById('auth-iframe')?.remove();
-        }
 
         function log(msg) {
             output.textContent = msg;
         }
 
+        // Make an API call using paskia module (handles 401/403 automatically)
+        window.apiCall = async function(url, method = 'GET') {
+            log(`${method} ${url}...`);
+            try {
+                const response = await apiFetch(url, { method });
+
+                // Forward endpoint returns 204 on success
+                if (response.status === 204) {
+                    log('✓ Success (204 No Content)');
+                    return;
+                }
+
+                if (!response.ok) {
+                    log(`Error: ${response.status} ${response.statusText}`);
+                    return;
+                }
+
+                const data = await response.json();
+                log('✓ Response:\n' + JSON.stringify(data, null, 2));
+            } catch (e) {
+                if (e instanceof AuthCancelledError) {
+                    log('Authentication cancelled');
+                } else {
+                    log(`Error: ${e.message}`);
+                }
+            }
+        }
+
+        window.logout = async function() {
+            await fetch('/auth/api/logout', { method: 'POST' });
+            log('Logged out');
+        }
+
         // Browser mode: open the forward endpoint directly in a new window.
-        // When Accept: text/html, the server redirects to the login page if needed,
+        window.browserNav = function(url) {
-        // then back to the original URL after authentication.
-        function browserNav(url) {
             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).');
             window.open(url, '_blank');
         }

frontend/auth/App.vue

@@ -2,10 +2,10 @@
   <div class="app-shell">
     <StatusMessage />
     <main class="app-main">
-      <HostProfileView v-if="authenticated && isHostMode" :initializing="loading" />
+      <HostProfileView v-if="viewState === 'profile' && isHostMode" />
-      <ProfileView v-else-if="authenticated" />
+      <ProfileView v-else-if="viewState === 'profile'" />
-      <LoadingView v-else-if="loading" :message="loadingMessage" />
+      <LoadingView v-else-if="viewState === 'loading'" :message="loadingMessage" />
-      <AuthRequiredMessage v-else-if="showBackMessage" @reload="reloadPage" />
+      <AccessDenied v-else-if="viewState === 'terminal'" />
     </main>
   </div>
 </template>
@@ -13,18 +13,17 @@
 <script setup>
 import { computed, onMounted, onUnmounted, ref } from 'vue'
 import { useAuthStore } from '@/stores/auth'
-import { apiJson, getAuthIframeUrl } from '@/utils/api'
+import { apiJson, SessionValidator, settings as paskiaSettings } from 'paskia'
+import { updateThemeFromSession } from '@/utils/theme'
 import StatusMessage from '@/components/StatusMessage.vue'
 import ProfileView from '@/components/ProfileView.vue'
 import HostProfileView from '@/components/HostProfileView.vue'
 import LoadingView from '@/components/LoadingView.vue'
-import AuthRequiredMessage from '@/components/AccessDenied.vue'
+import AccessDenied from '@/components/AccessDenied.vue'
 
 const store = useAuthStore()
-const loading = ref(true)
+const viewState = ref('loading')  // 'loading' | 'profile' | 'terminal'
 const loadingMessage = ref('Loading...')
-const authenticated = ref(false)
-const showBackMessage = ref(false)
 
 /**
  * Normalize a host string for comparison (lowercase, strip default ports).
@@ -48,128 +47,50 @@ const isHostMode = computed(() => {
   const configuredHost = normalizeHost(authHost)
   return currentHost !== configuredHost
 })
-let validationTimer = null
+
-let authIframe = null
+function onSessionLost(e) {
+  store.userInfo = null
+  store.ctx = null
+  if (e?.name === 'AuthCancelledError') {
+    viewState.value = 'terminal'
+  } else {
+    store.showMessage(e?.message || 'Session lost', 'error', 5000)
+    viewState.value = 'terminal'
+  }
+}
+
+const userUuidGetter = () => store.ctx?.user.uuid
+const sessionValidator = new SessionValidator(userUuidGetter, onSessionLost)
+
+onMounted(() => sessionValidator.start())
+onUnmounted(() => sessionValidator.stop())
 
 async function loadUserInfo() {
+  viewState.value = 'loading'
+  loadingMessage.value = 'Loading...'
   try {
-    store.userInfo = await apiJson('/auth/api/user-info', { method: 'POST' })
+    // apiJson handles 401/403 with auth.iframe automatically:
-    authenticated.value = true
+    // shows overlay iframe, waits for auth, retries the request.
-    loading.value = false
+    const [validateData, userInfoData] = await Promise.all([
-    startSessionValidation()
+      apiJson('/auth/api/validate', { method: 'POST', timeout: paskiaSettings.auth_ms }),
-    return true
+      apiJson('/auth/api/user-info', { method: 'GET', timeout: paskiaSettings.auth_ms })
-  } catch (e) {
+    ])
-    return false
+    store.userInfo = userInfoData
-  }
+    store.ctx = validateData.ctx
-}
+    updateThemeFromSession(store.userInfo)
-
+    // Verify that the user UUIDs match between user-info and validate responses
-async function showAuthIframe() {
+    if (store.userInfo.user.uuid !== store.ctx.user.uuid) {
-  // Remove existing iframe if any
+      console.error('User UUID mismatch between user-info and validate responses')
-  hideAuthIframe()
+      window.location.reload()
-
+      return
-  // Create new iframe for authentication using src URL
-  const url = await getAuthIframeUrl('login')
-  authIframe = document.createElement('iframe')
-  authIframe.id = 'auth-iframe'
-  authIframe.title = 'Authentication'
-  authIframe.allow = 'publickey-credentials-get; publickey-credentials-create'
-  authIframe.src = url
-  document.body.appendChild(authIframe)
-  loadingMessage.value = 'Authentication required...'
-}
-
-function hideAuthIframe() {
-  if (authIframe) {
-    authIframe.remove()
-    authIframe = null
-  }
-}
-
-function reloadPage() {
-  window.location.reload()
-}
-
-function handleAuthMessage(event) {
-  const data = event.data
-  if (!data?.type) return
-
-  switch (data.type) {
-    case 'auth-success':
-      // Authentication successful - reload user info
-      hideAuthIframe()
-      loading.value = true
-      loadingMessage.value = 'Loading user profile...'
-      loadUserInfo()
-      break
-
-    case 'auth-error':
-      // Authentication failed - keep iframe open so user can retry
-      if (data.cancelled) {
-        console.log('Authentication cancelled by user')
-      } else {
-        store.showMessage(data.message || 'Authentication failed', 'error', 5000)
-      }
-      break
-
-    case 'auth-cancelled':
-      // Legacy support - treat as auth-error with cancelled flag
-      console.log('Authentication cancelled')
-      break
-
-    case 'auth-back':
-      // User clicked Back - show message with reload option
-      hideAuthIframe()
-      loading.value = false
-      showBackMessage.value = true
-      store.showMessage('Authentication cancelled', 'info', 3000)
-      break
-
-    case 'auth-close-request':
-      // Legacy support - treat as back
-      hideAuthIframe()
-      break
-  }
-}
-
-async function validateSession() {
-  try {
-    await apiJson('/auth/api/validate', {
-      method: 'POST',
-      credentials: 'include'
-    })
-    // If successful, session was renewed automatically
-  } catch (error) {
-    if (error.status === 401) {
-      // Session expired - need to re-authenticate
-      console.log('Session expired, requiring re-authentication')
-      authenticated.value = false
-      loading.value = true
-      stopSessionValidation()
-      showAuthIframe()
-    } else {
-      console.error('Session validation error:', error)
-      // Don't treat network errors as session expiry
     }
-  }
+    viewState.value = 'profile'
-}
+  } catch (e) {
-
+    onSessionLost(e)
-function startSessionValidation() {
-  // Validate session every 2 minutes
-  stopSessionValidation()
-  validationTimer = setInterval(validateSession, 2 * 60 * 1000)
-}
-
-function stopSessionValidation() {
-  if (validationTimer) {
-    clearInterval(validationTimer)
-    validationTimer = null
   }
 }
 
 onMounted(async () => {
-  // Listen for postMessage from auth iframe
-  window.addEventListener('message', handleAuthMessage)
-
   // Load settings
   await store.loadSettings()
 
@@ -183,21 +104,7 @@ onMounted(async () => {
     document.title = inHostMode ? `${rpName} · Account summary` : rpName
   }
 
-  // Try to load user info
+  // Load user info (apiJson handles auth iframe if needed)
-  const success = await loadUserInfo()
+  await loadUserInfo()
-
-  if (!success) {
-    // Need authentication - show login iframe
-    showAuthIframe()
-  }
-})
-
-onUnmounted(() => {
-  window.removeEventListener('message', handleAuthMessage)
-  stopSessionValidation()
-  hideAuthIframe()
 })
 </script>
-
-<style scoped>
-</style>

frontend/auth/admin/AdminApp.vue

@@ -5,15 +5,19 @@ import CredentialList from '@/components/CredentialList.vue'
 import UserBasicInfo from '@/components/UserBasicInfo.vue'
 import StatusMessage from '@/components/StatusMessage.vue'
 import LoadingView from '@/components/LoadingView.vue'
-import AuthRequiredMessage from '@/components/AccessDenied.vue'
+import AccessDenied from '@/components/AccessDenied.vue'
 import AdminOverview from '@/admin/AdminOverview.vue'
 import AdminOrgDetail from '@/admin/AdminOrgDetail.vue'
 import AdminUserDetail from '@/admin/AdminUserDetail.vue'
+import AdminOidcDetail from '@/admin/AdminOidcDetail.vue'
 import AdminDialogs from '@/admin/AdminDialogs.vue'
 import { useAuthStore } from '@/stores/auth'
-import { getSettings, adminUiPath, makeUiHref } from '@/utils/settings'
+import { adminUiPath, makeUiHref } from '@/utils/settings'
-import { apiJson } from '@/utils/api'
+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'
 
 const info = ref(null)
 const loading = ref(true)
@@ -23,9 +27,12 @@ const showBackMessage = ref(false)
 const error = ref(null)
 const orgs = ref([])
 const permissions = ref([])
+const oidcClients = 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
 const userDetail = ref(null) // cached user detail object
+const editingOidcClient = ref(null) // OIDC client being edited (with local changes)
 const authStore = useAuthStore()
 const addingOrgForPermission = ref(null)
 const PERMISSION_ID_PATTERN = '^[A-Za-z0-9:._~-]+$'
@@ -42,10 +49,15 @@ const breadcrumbsRef = ref(null)
 const adminOverviewRef = ref(null)
 const adminOrgDetailRef = ref(null)
 const adminUserDetailRef = ref(null)
+const adminOidcDetailRef = ref(null)
 
 // Check if any modal/dialog is open (blocks arrow key navigation)
 const hasActiveModal = computed(() => dialog.value.type !== null || showRegModal.value)
 
+// Derive admin status from permissions
+const isMasterAdmin = computed(() => info.value?.ctx.permissions.includes('auth:admin'))
+const isOrgAdmin = computed(() => info.value?.ctx.permissions.includes('auth:org:admin'))
+
 function sanitizeRenameId() { if (renameIdValue.value) renameIdValue.value = renameIdValue.value.replace(safeIdRegex, '') }
 
 function handleGlobalClick(e) {
@@ -60,8 +72,8 @@ function handleGlobalClick(e) {
 onMounted(async () => {
   document.addEventListener('click', handleGlobalClick)
   window.addEventListener('hashchange', parseHash)
-  const settings = await getSettings()
+  await authStore.loadSettings()
-  if (settings?.rp_name) document.title = settings.rp_name + ' Admin'
+  if (authStore.settings?.rp_name) document.title = authStore.settings.rp_name + ' Admin'
   await load()
 })
 
@@ -74,11 +86,12 @@ onUnmounted(() => {
 const permissionSummary = computed(() => {
   const summary = {}
   for (const o of orgs.value) {
-    const orgBase = { uuid: o.uuid, display_name: o.display_name }
+    const orgBase = { uuid: o.uuid, display_name: o.org.display_name }
-    const orgPerms = new Set(o.permissions || [])
+    // o.permissions is a dict[UUID, Permission]
+    const orgPermUuids = new Set(Object.keys(o.permissions || {}))
 
     // Org-level permissions (direct) - only count if org can grant them
-    for (const pid of o.permissions || []) {
+    for (const pid of Object.keys(o.permissions || {})) {
       if (!summary[pid]) summary[pid] = { orgs: [], orgSet: new Set(), userCount: 0 }
       if (!summary[pid].orgSet.has(o.uuid)) {
         summary[pid].orgs.push(orgBase)
@@ -87,17 +100,18 @@ const permissionSummary = computed(() => {
     }
 
     // Role-based permissions (inheritance) - only count if org can grant them
-    for (const r of o.roles) {
+    for (const [roleUuid, r] of Object.entries(o.roles || {})) {
-      for (const pid of r.permissions) {
+      // r.permissions is dict[UUID, bool]
+      for (const pid of Object.keys(r.permissions || {})) {
         // Only count if the org can grant this permission
-        if (!orgPerms.has(pid)) continue
+        if (!orgPermUuids.has(pid)) continue
 
         if (!summary[pid]) summary[pid] = { orgs: [], orgSet: new Set(), userCount: 0 }
         if (!summary[pid].orgSet.has(o.uuid)) {
           summary[pid].orgs.push(orgBase)
           summary[pid].orgSet.add(o.uuid)
         }
-        summary[pid].userCount += r.users.length
+        summary[pid].userCount += roleUserCount(o, roleUuid)
       }
     }
   }
@@ -108,66 +122,131 @@ const permissionSummary = computed(() => {
   return display
 })
 
-function renamePermissionDisplay(p) { openDialog('perm-display', { permission: p, id: p.id, display_name: p.display_name }) }
+function renamePermissionDisplay(p) { openDialog('perm-display', { permission: p, scope: p.scope, display_name: p.display_name, domain: p.domain || '' }) }
 
 
 function parseHash() {
   const h = window.location.hash || ''
   currentOrgId.value = null
   currentUserId.value = null
+  currentOidcId.value = null
+  editingOidcClient.value = null
   if (h.startsWith('#org/')) {
     currentOrgId.value = h.slice(5)
   } else if (h.startsWith('#user/')) {
     currentUserId.value = h.slice(6)
+  } else if (h.startsWith('#oidc:')) {
+    const oidcUuid = h.slice(6)
+    currentOidcId.value = oidcUuid
+    // Initialize editing client data
+    if (oidcUuid === 'new') {
+      // Generate client_id and secret for new client
+      const bytes = new Uint8Array(32)
+      crypto.getRandomValues(bytes)
+      const client_secret = btoa(String.fromCharCode(...bytes))
+        .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+      editingOidcClient.value = {
+        client_id: uuidv7(),
+        client_secret,
+        isNew: true,
+        name: '',
+        redirect_uris: []
+      }
+    } else {
+      const client = oidcClients.value.find(c => c.uuid === oidcUuid)
+      if (client) {
+        editingOidcClient.value = {
+          ...client,
+          client_id: client.uuid,
+          client_secret: null,
+          isNew: false
+        }
+      }
+    }
   }
 }
 
-async function loadOrgs() {
+async function loadAdminData() {
-  const data = await apiJson('/auth/api/admin/orgs')
+  const data = await apiJson('/auth/api/admin/info')
-  orgs.value = data.map(o => {
+  // Convert dicts to arrays with uuid added
-    const roles = o.roles.map(r => ({ ...r, org_uuid: o.uuid, users: [] }))
+  orgs.value = Object.entries(data.orgs).map(([uuid, o]) => ({ uuid, ...o }))
-    const roleMap = Object.fromEntries(roles.map(r => [r.display_name, r]))
+  permissions.value = Object.entries(data.permissions).map(([uuid, p]) => ({ uuid, ...p }))
-    for (const u of o.users || []) {
+  oidcClients.value = Object.entries(data.oidc_clients).map(([uuid, c]) => ({ uuid, ...c }))
-      if (roleMap[u.role]) roleMap[u.role].users.push(u)
-    }
-    return { ...o, roles }
-  })
 }
 
-async function loadPermissions() {
+// Helper to get users for a role as sorted array of [uuid, user]
-  permissions.value = await apiJson('/auth/api/admin/permissions')
+function roleUsers(org, roleUuid) {
+  return Object.entries(org.users)
+    .filter(([_, u]) => u.role === roleUuid)
+    .sort(([, a], [, b]) => {
+      const nameA = a.display_name.toLowerCase()
+      const nameB = b.display_name.toLowerCase()
+      return nameA.localeCompare(nameB)
+    })
+}
+
+// Helper to count users in a role
+function roleUserCount(org, roleUuid) {
+  return Object.values(org.users).filter(u => u.role === roleUuid).length
+}
+
+// Helper to count total users in an org
+function orgUserCount(org) {
+  return Object.keys(org.users).length
 }
 
 async function loadUserInfo() {
-  info.value = await apiJson('/auth/api/user-info', { method: 'POST' })
+  const data = await apiJson('/auth/api/validate', { method: 'POST', timeout: paskiaSettings.auth_ms })
+  info.value = data
+  updateThemeFromSession(data.ctx)
   authenticated.value = true
 }
 
+function clearSensitiveState() {
+  info.value = null
+  orgs.value = []
+  permissions.value = []
+  oidcClients.value = []
+  userDetail.value = null
+  editingOidcClient.value = null
+  authenticated.value = false
+}
+
+function onSessionLost(e) {
+  clearSensitiveState()
+  if (e.name === 'AuthCancelledError') {
+    showBackMessage.value = true
+  } else {
+    error.value = e.message
+  }
+}
+
+const userUuidGetter = () => info.value?.ctx.user.uuid
+const sessionValidator = new SessionValidator(userUuidGetter, onSessionLost)
+
+onMounted(() => sessionValidator.start())
+onUnmounted(() => sessionValidator.stop())
+
 async function load() {
   loading.value = true
   loadingMessage.value = 'Loading...'
   error.value = null
   try {
     // Load admin data first - apiJson will handle 401/403 with iframe authentication
-    await Promise.all([loadOrgs(), loadPermissions()])
+    await loadAdminData()
     // If we get here, user has admin access - now fetch user info for display
     await loadUserInfo()
 
-    if (!info.value.is_global_admin && info.value.is_org_admin && orgs.value.length === 1) {
+    if (!isMasterAdmin.value && isOrgAdmin.value && orgs.value.length === 1) {
       if (!window.location.hash || window.location.hash === '#overview') {
         currentOrgId.value = orgs.value[0].uuid
         window.location.hash = `#org/${currentOrgId.value}`
-        authStore.showMessage(`Navigating to ${orgs.value[0].display_name} Administration`, 'info', 3000)
       } else {
         parseHash()
       }
     } else parseHash()
   } catch (e) {
-    if (e.name === 'AuthCancelledError') {
+    onSessionLost(e)
-      showBackMessage.value = true
-    } else {
-      error.value = e.message
-    }
   } finally {
     loading.value = false
   }
@@ -182,19 +261,17 @@ function editUserName(user) { openDialog('user-update-name', { user, name: user.
 
 async function performOrgDeletion(orgUuid) {
   await apiJson(`/auth/api/admin/orgs/${orgUuid}`, { method: 'DELETE' })
-  await Promise.all([loadOrgs(), loadPermissions()])
+  await Promise.all([loadAdminData()])
 }
 
 function deleteOrg(org) {
-  if (!info.value?.is_global_admin) { authStore.showMessage('Global admin only'); return }
+  const userCount = orgUserCount(org)
-
-  const userCount = org.roles.reduce((acc, r) => acc + r.users.length, 0)
 
   if (userCount === 0) {
     // No users in the organization, safe to delete directly
     performOrgDeletion(org.uuid)
       .then(() => {
-        authStore.showMessage(`Organization "${org.display_name}" deleted.`, 'success', 2500)
+        authStore.showMessage(`Organization "${org.org.display_name}" deleted.`, 'success', 2500)
       })
       .catch(e => {
         authStore.showMessage(e.message || 'Failed to delete organization', 'error')
@@ -203,50 +280,68 @@ function deleteOrg(org) {
   }
 
   // Build detailed breakdown of users by role
-  const roleParts = org.roles
+  const roleParts = Object.entries(org.roles)
-    .filter(r => r.users.length > 0)
+    .map(([uuid, r]) => ({ role: r, count: roleUserCount(org, uuid) }))
-    .map(r => `${r.users.length} ${r.display_name}`)
+    .filter(x => x.count > 0)
+    .map(x => `${x.count} ${x.role.display_name}`)
 
   const affects = roleParts.join(', ')
 
-  openDialog('confirm', { message: `Delete organization "${org.display_name}", including accounts of ${affects})?`, action: async () => {
+  openDialog('confirm', { message: `Delete organization "${org.org.display_name}", including accounts of ${affects})?`, action: async () => {
     await performOrgDeletion(org.uuid)
   } })
 }
 
 function createUserInRole(org, role) { openDialog('user-create', { org, role }) }
 
-async function moveUserToRole(org, user, targetRoleDisplayName) {
+function deleteUser(user, userDetail) {
-  if (user.role === targetRoleDisplayName) return
+  const credentialCount = userDetail?.credentials ? Object.keys(userDetail.credentials).length : 0
+  const userUuid = user.uuid
+  const userName = user.display_name
+  const orgUuid = user.org  // org UUID is stored in selectedUser
+
+  if (credentialCount === 0) {
+    // No credentials, safe to delete directly
+    performUserDeletion(userUuid, userName, orgUuid)
+    return
+  }
+
+  const passkeys = credentialCount === 1 ? '1 passkey' : `${credentialCount} passkeys`
+  openDialog('confirm', {
+    message: `Delete user "${userName}" with ${passkeys}? This action cannot be undone.`,
+    action: async () => {
+      await performUserDeletion(userUuid, userName, orgUuid)
+    }
+  })
+}
+
+async function performUserDeletion(userUuid, userName, orgUuid) {
   try {
-    await apiJson(`/auth/api/admin/orgs/${org.uuid}/users/${user.uuid}/role`, {
+    await apiJson(`/auth/api/admin/users/${userUuid}`, { method: 'DELETE' })
-      method: 'PUT',
+    authStore.showMessage(`User "${userName}" deleted.`, 'success', 2500)
-      body: { role: targetRoleDisplayName }
+    await loadAdminData()
+    window.location.hash = `#org/${orgUuid}`
+  } catch (e) {
+    authStore.showMessage(e.message || 'Failed to delete user', 'error')
+  }
+}
+
+async function moveUserToRole(userUuid, user, targetRoleUuid) {
+  if (user.role === targetRoleUuid) return
+  try {
+    await apiJson(`/auth/api/admin/users/${userUuid}/role`, {
+      method: 'PATCH',
+      body: { role_uuid: targetRoleUuid }
     })
-    await loadOrgs()
+    await loadAdminData()
   } catch (e) {
     authStore.showMessage(e.message || 'Failed to update user role')
   }
 }
 
-function onUserDragStart(e, user, org_uuid) {
+function moveUserToRoleFromDrag(userUuid, newRoleUuid) {
-  e.dataTransfer.effectAllowed = 'move'
+  const user = selectedOrg.value?.users?.[userUuid]
-  e.dataTransfer.setData('text/plain', JSON.stringify({ user_uuid: user.uuid, org_uuid }))
+  if (user) moveUserToRole(userUuid, user, newRoleUuid)
-}
-
-function onRoleDragOver(e) {
-  e.preventDefault()
-  e.dataTransfer.dropEffect = 'move'
-}
-
-function onRoleDrop(e, org, role) {
-  e.preventDefault()
-  try {
-    const data = JSON.parse(e.dataTransfer.getData('text/plain'))
-    if (data.org_uuid !== org.uuid) return // only within same org
-    const user = org.roles.flatMap(r => r.users).find(u => u.uuid === data.user_uuid)
-    if (user) moveUserToRole(org, user, role.display_name)
-  } catch (_) { /* ignore */ }
 }
 
 // Role actions
@@ -256,10 +351,10 @@ function updateRole(role) { openDialog('role-update', { role, name: role.display
 
 function deleteRole(role) {
   // UI only allows deleting empty roles, so no confirmation needed
-  apiJson(`/auth/api/admin/orgs/${role.org_uuid}/roles/${role.uuid}`, { method: 'DELETE' })
+  apiJson(`/auth/api/admin/roles/${role.uuid}`, { method: 'DELETE' })
     .then(() => {
       authStore.showMessage(`Role "${role.display_name}" deleted.`, 'success', 2500)
-      loadOrgs()
+      loadAdminData()
     })
     .catch(e => {
       authStore.showMessage(e.message || 'Failed to delete role', 'error')
@@ -267,21 +362,22 @@ function deleteRole(role) {
 }
 
 async function toggleRolePermission(role, pid, checked) {
-  // Calculate new permissions array
+  // Optimistic update - role.permissions is dict[UUID, bool]
-  const newPermissions = checked
+  const prevPermissions = { ...role.permissions }
-    ? [...role.permissions, pid]
+  const newPermissions = { ...role.permissions }
-    : role.permissions.filter(p => p !== pid)
+  if (checked) {
-
+    newPermissions[pid] = true
-  // Optimistic update
+  } else {
-  const prevPermissions = [...role.permissions]
+    delete newPermissions[pid]
+  }
   role.permissions = newPermissions
 
   try {
-    await apiJson(`/auth/api/admin/orgs/${role.org_uuid}/roles/${role.uuid}`, {
+    const method = checked ? 'POST' : 'DELETE'
-      method: 'PUT',
+    await apiJson(`/auth/api/admin/roles/${role.uuid}/permissions/${pid}`, {
-      body: { display_name: role.display_name, permissions: newPermissions }
+      method
     })
-    await loadOrgs()
+    await loadAdminData()
   } catch (e) {
     authStore.showMessage(e.message || 'Failed to update role permission')
     role.permissions = prevPermissions // revert
@@ -289,20 +385,20 @@ async function toggleRolePermission(role, pid, checked) {
 }
 
 // Permission actions
-async function performPermissionDeletion(permissionId) {
+async function performPermissionDeletion(permissionUuid) {
-  const params = new URLSearchParams({ permission_id: permissionId })
+  const params = new URLSearchParams({ permission_uuid: permissionUuid })
   await apiJson(`/auth/api/admin/permission?${params.toString()}`, { method: 'DELETE' })
-  await loadPermissions()
+  await loadAdminData()
 }
 
 function deletePermission(p) {
-  const userCount = permissionSummary.value[p.id]?.userCount || 0
+  const userCount = permissionSummary.value[p.uuid]?.userCount || 0
 
   // Count roles that have this permission
   let roleCount = 0
   for (const org of orgs.value) {
-    for (const role of org.roles) {
+    for (const role of Object.values(org.roles)) {
-      if (role.permissions.includes(p.id)) {
+      if (p.uuid in (role.permissions || {})) {
         roleCount++
       }
     }
@@ -310,7 +406,7 @@ function deletePermission(p) {
 
   if (roleCount === 0) {
     // No roles have this permission, safe to delete directly
-    performPermissionDeletion(p.id)
+    performPermissionDeletion(p.uuid)
       .then(() => {
         authStore.showMessage(`Permission "${p.display_name}" deleted.`, 'success', 2500)
       })
@@ -326,12 +422,106 @@ function deletePermission(p) {
   const affects = parts.join(', ')
 
   openDialog('confirm', { message: `Delete permission "${p.display_name}" (${affects})?`, action: async () => {
-    await performPermissionDeletion(p.id)
+    await performPermissionDeletion(p.uuid)
   } })
 }
 
-function reloadPage() {
+// OIDC Client actions
-  window.location.reload()
+async function sha256Hex(text) {
+  const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text))
+  return [...new Uint8Array(hash)].map(b => b.toString(16).padStart(2, '0')).join('')
+}
+
+function createOidcClient() {
+  // Navigate to new OIDC client page
+  window.location.hash = '#oidc:new'
+}
+
+function openOidcClient(client) {
+  // Navigate to OIDC client detail page
+  window.location.hash = `#oidc:${client.uuid}`
+}
+
+function resetOidcSecret(clientId) {
+  // Generate new secret locally; it will be sent to server on Save
+  const bytes = new Uint8Array(32)
+  crypto.getRandomValues(bytes)
+  const client_secret = btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+  // Update editingOidcClient if we're on the detail page
+  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 })
+}
+
+async function openServerConfig() {
+  try {
+    const config = await apiJson('/auth/api/admin/server-config')
+    // Strip https:// scheme from stored origins and auth_host for editing
+    const origins = (config.origins || []).map(o => o.replace(/^https:\/\//, ''))
+    const auth_host = (config.auth_host || '').replace(/^https:\/\//, '')
+    openDialog('server-config', {
+      rp_name: config.rp_name || '',
+      auth_host,
+      origins,
+      originValidation: origins.map(() => null),
+    })
+  } catch (e) {
+    authStore.showMessage(e.message || 'Failed to load server configuration', 'error')
+  }
+}
+
+function deleteOidcClient(client) {
+  openDialog('confirm', {
+    message: `Delete OIDC client "${client.name}"? This will break any applications using this client.`,
+    action: async () => {
+      await performOidcClientDeletion(client.uuid, client.name)
+      // Navigate back to overview if we were on the detail page
+      if (currentOidcId.value === client.uuid) {
+        window.location.hash = '#overview'
+      }
+    }
+  })
+}
+
+async function performOidcClientDeletion(clientUuid, clientName) {
+  await apiJson(`/auth/api/admin/oidc-clients/${clientUuid}`, { method: 'DELETE' })
+  authStore.showMessage(`OIDC client "${clientName}" deleted.`, 'success', 2500)
+  await loadAdminData()
+}
+
+async function handleOidcSave(data) {
+  const { client_id, client_secret, name, redirect_uris, isNew } = data
+
+  try {
+    if (client_secret) {
+      const secret_hash = await sha256Hex(client_secret)
+      if (isNew) {
+        await apiJson('/auth/api/admin/oidc-clients', { method: 'POST', body: { client_id, secret_hash, name, redirect_uris } })
+      } else {
+        await apiJson(`/auth/api/admin/oidc-clients/${client_id}`, { method: 'PATCH', body: { name, redirect_uris, secret_hash } })
+      }
+    } else {
+      await apiJson(`/auth/api/admin/oidc-clients/${client_id}`, { method: 'PATCH', body: { name, redirect_uris } })
+    }
+    authStore.showMessage(`OIDC client "${name}" ${isNew ? 'created' : 'updated'}.`, 'success', 2500)
+    await loadAdminData()
+    window.location.hash = '#overview'
+  } catch (e) {
+    authStore.showMessage(e.message || `Failed to ${isNew ? 'create' : 'update'} OIDC client`, 'error')
+  }
+}
+
+function handleOidcCancel() {
+  goOverview()
 }
 
 const selectedOrg = computed(() => orgs.value.find(o => o.uuid === currentOrgId.value) || null)
@@ -351,37 +541,44 @@ function openUser(u) {
 const selectedUser = computed(() => {
   if (!currentUserId.value) return null
   for (const o of orgs.value) {
-    for (const r of o.roles) {
+    const u = o.users[currentUserId.value]
-      const u = r.users.find(x => x.uuid === currentUserId.value)
+    if (u) {
-      if (u) return { ...u, org_uuid: o.uuid, role_display_name: r.display_name }
+      const role = o.roles[u.role]
+      return { ...u, uuid: currentUserId.value, org: o.uuid, role_display_name: role?.display_name }
     }
   }
   return null
 })
 
-const pageHeading = computed(() => {
-  if (selectedUser.value) return 'Admin: User'
-  if (selectedOrg.value) return 'Admin: Org'
-  return ((authStore.settings?.rp_name) || 'Master') + ' Admin'
-})
-
 // Breadcrumb entries for admin app.
 const breadcrumbEntries = computed(() => {
   const entries = [
-    { label: 'Auth', href: makeUiHref() },
+    { label: 'My Profile', href: makeUiHref() }
-    { label: 'Admin', href: adminUiPath() }
   ]
+  // For org admins, combine Admin and their org
+  if (isOrgAdmin.value && !isMasterAdmin.value && orgs.value.length > 0) {
+    const org = orgs.value[0]
+    entries.push({ label: `Admin: ${org.org.display_name}`, href: `#org/${org.uuid}` })
+  } else {
+    entries.push({ label: 'Admin', href: adminUiPath() })
+  }
   // Determine organization for user view if selectedOrg not explicitly chosen.
   let orgForUser = null
   if (selectedUser.value) {
-    orgForUser = orgs.value.find(o => o.uuid === selectedUser.value.org_uuid) || null
+    orgForUser = orgs.value.find(o => o.uuid === selectedUser.value.org) || null
   }
   const orgToShow = selectedOrg.value || orgForUser
-  if (orgToShow) {
+  // Add org breadcrumb only if it's not already included in the Admin entry
-    entries.push({ label: orgToShow.display_name, href: `#org/${orgToShow.uuid}` })
+  const adminOrg = (isOrgAdmin.value && !isMasterAdmin.value && orgs.value.length > 0) ? orgs.value[0] : null
+  if (orgToShow && (!adminOrg || orgToShow.uuid !== adminOrg.uuid)) {
+    entries.push({ label: orgToShow.org.display_name, href: `#org/${orgToShow.uuid}` })
+  }
+  if (currentOidcId.value) {
+    const label = editingOidcClient.value?.isNew ? 'New Client' : (editingOidcClient.value?.name || 'OIDC Client')
+    entries.push({ label, href: `#oidc:${currentOidcId.value}` })
   }
   if (selectedUser.value) {
-    entries.push({ label: selectedUser.value.display_name || 'User', href: `#user/${selectedUser.value.uuid}` })
+    entries.push({ label: selectedUser.value.display_name, href: `#user/${selectedUser.value.uuid}` })
   }
   return entries
 })
@@ -389,7 +586,7 @@ const breadcrumbEntries = computed(() => {
 watch(selectedUser, async (u) => {
   if (!u) { userDetail.value = null; return }
   try {
-    userDetail.value = await apiJson(`/auth/api/admin/orgs/${u.org_uuid}/users/${u.uuid}`)
+    userDetail.value = await apiJson(`/auth/api/admin/users/${u.uuid}`)
   } catch (e) {
     userDetail.value = { error: e.message }
   }
@@ -401,20 +598,29 @@ function generateUserRegistrationLink(u) {
 }
 
 async function toggleOrgPermission(org, permId, checked) {
-  // Build next permission list
+  // org.permissions is dict[UUID, Permission]
-  const has = org.permissions.includes(permId)
+  const has = permId in org.permissions
   if (checked && has) return
   if (!checked && !has) return
-  const next = checked ? [...org.permissions, permId] : org.permissions.filter(p => p !== permId)
   // Optimistic update
-  const prev = [...org.permissions]
+  const prev = { ...org.permissions }
-  org.permissions = next
+  if (checked) {
+    // Need to fetch the permission object to add it
+    const perm = permissions.value.find(p => p.uuid === permId)
+    if (perm) {
+      org.permissions = { ...org.permissions, [permId]: perm }
+    }
+  } else {
+    const next = { ...org.permissions }
+    delete next[permId]
+    org.permissions = next
+  }
   try {
-    const params = new URLSearchParams({ permission_id: permId })
+    const params = new URLSearchParams({ permission_uuid: permId })
     await apiJson(`/auth/api/admin/orgs/${org.uuid}/permission?${params.toString()}`, { method: checked ? 'POST' : 'DELETE' })
-    await loadOrgs()
+    await loadAdminData()
   } catch (e) {
-    authStore.showMessage(e.message || 'Failed to update organization permission')
+    authStore.showMessage(e.message || 'Failed to update organization permission', 'error')
     org.permissions = prev // revert
   }
 }
@@ -522,10 +728,10 @@ function handlePanelNavigateOut(direction) {
 }
 
 async function refreshUserDetail() {
-  await loadOrgs()
+  await loadAdminData()
   if (selectedUser.value) {
     try {
-      userDetail.value = await apiJson(`/auth/api/admin/orgs/${selectedUser.value.org_uuid}/users/${selectedUser.value.uuid}`)
+      userDetail.value = await apiJson(`/auth/api/admin/users/${selectedUser.value.uuid}`)
     } catch (e) { authStore.showMessage(e.message || 'Failed to reload user', 'error') }
   }
 }
@@ -548,7 +754,7 @@ async function submitDialog() {
       apiJson('/auth/api/admin/orgs', { method: 'POST', body: { display_name: name, permissions: [] } })
         .then(() => {
           authStore.showMessage(`Organization "${name}" created.`, 'success', 2500)
-          Promise.all([loadOrgs(), loadPermissions()])
+          loadAdminData()
         })
         .catch(e => {
           authStore.showMessage(e.message || 'Failed to create organization', 'error')
@@ -559,10 +765,10 @@ async function submitDialog() {
 
       // Close dialog immediately, then perform async operation
       closeDialog()
-      apiJson(`/auth/api/admin/orgs/${org.uuid}`, { method: 'PUT', body: { display_name: name, permissions: org.permissions } })
+      apiJson(`/auth/api/admin/orgs/${org.uuid}`, { method: 'PATCH', body: { display_name: name } })
         .then(() => {
           authStore.showMessage(`Organization renamed to "${name}".`, 'success', 2500)
-          loadOrgs()
+          loadAdminData()
         })
         .catch(e => {
           authStore.showMessage(e.message || 'Failed to update organization', 'error')
@@ -576,7 +782,7 @@ async function submitDialog() {
       apiJson(`/auth/api/admin/orgs/${org.uuid}/roles`, { method: 'POST', body: { display_name: name, permissions: [] } })
         .then(() => {
           authStore.showMessage(`Role "${name}" created.`, 'success', 2500)
-          loadOrgs()
+          loadAdminData()
         })
         .catch(e => {
           authStore.showMessage(e.message || 'Failed to create role', 'error')
@@ -587,10 +793,10 @@ async function submitDialog() {
 
       // Close dialog immediately, then perform async operation
       closeDialog()
-      apiJson(`/auth/api/admin/orgs/${role.org_uuid}/roles/${role.uuid}`, { method: 'PUT', body: { display_name: name, permissions: role.permissions } })
+      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')
@@ -604,7 +810,7 @@ async function submitDialog() {
       apiJson(`/auth/api/admin/orgs/${org.uuid}/users`, { method: 'POST', body: { display_name: name, role: role.display_name } })
         .then(() => {
           authStore.showMessage(`User "${name}" added to ${role.display_name} role.`, 'success', 2500)
-          loadOrgs()
+          loadAdminData()
         })
         .catch(e => {
           authStore.showMessage(e.message || 'Failed to add user', 'error')
@@ -615,7 +821,7 @@ async function submitDialog() {
 
       // Close dialog immediately, then perform async operation
       closeDialog()
-      apiJson(`/auth/api/admin/orgs/${user.org_uuid}/users/${user.uuid}/display-name`, { method: 'PUT', body: { display_name: name } })
+      apiJson(`/auth/api/admin/users/${user.uuid}/info`, { method: 'PATCH', body: { display_name: name } })
         .then(() => {
           authStore.showMessage(`User renamed to "${name}".`, 'success', 2500)
           onUserNameSaved()
@@ -626,52 +832,110 @@ async function submitDialog() {
       return // Don't call closeDialog() again
     } else if (t === 'perm-display') {
       const { permission } = dialog.value.data
-      const newId = dialog.value.data.id?.trim()
+      const newScope = dialog.value.data.scope?.trim()
       const newDisplay = dialog.value.data.display_name?.trim()
+      const newDomain = dialog.value.data.domain?.trim() || ''
       if (!newDisplay) throw new Error('Display name required')
-      if (!newId) throw new Error('ID required')
+      if (!newScope) throw new Error('Scope required')
 
       // Close dialog immediately, then perform async operation
       closeDialog()
 
-      let apiCall;
+      const oldDomain = permission.domain || ''
-      if (newId !== permission.id) {
+      // Check if anything changed
-        // ID changed, use rename endpoint
+      if (newScope === permission.scope && newDisplay === permission.display_name && newDomain === oldDomain) {
-        apiCall = apiJson('/auth/api/admin/permission/rename', { method: 'POST', body: { old_id: permission.id, new_id: newId, display_name: newDisplay } })
+        return // No changes
-      } else if (newDisplay !== permission.display_name) {
-        // Only display name changed
-        const params = new URLSearchParams({ permission_id: permission.id, display_name: newDisplay })
-        apiCall = apiJson(`/auth/api/admin/permission?${params.toString()}`, { method: 'PUT' })
-      } else {
-        // No changes
-        return
       }
 
-      apiCall
+      // Always use PATCH with permission_uuid
+      const params = new URLSearchParams({ permission_uuid: permission.uuid })
+      if (newScope !== permission.scope) params.set('scope', newScope)
+      if (newDisplay !== permission.display_name) params.set('display_name', newDisplay)
+      if (newDomain !== oldDomain) params.set('domain', newDomain || '')
+
+      apiJson(`/auth/api/admin/permission?${params.toString()}`, { method: 'PATCH' })
         .then(() => {
           authStore.showMessage(`Permission "${newDisplay}" updated.`, 'success', 2500)
-          loadPermissions()
+          loadAdminData()
         })
         .catch(e => {
           authStore.showMessage(e.message || 'Failed to update permission', 'error')
         })
-      return // Don't call closeDialog() again else if (t === 'perm-create') {
+      return // Don't call closeDialog() again
-      const id = dialog.value.data.id?.trim(); if (!id) throw new Error('ID required')
+    } else if (t === 'perm-create') {
+      const scope = dialog.value.data.scope?.trim(); if (!scope) throw new Error('Scope required')
       const display_name = dialog.value.data.display_name?.trim(); if (!display_name) throw new Error('Display name required')
+      const domain = dialog.value.data.domain?.trim() || ''
 
       // Close dialog immediately, then perform async operation
       closeDialog()
-      apiJson('/auth/api/admin/permissions', { method: 'POST', body: { id, display_name } })
+      apiJson('/auth/api/admin/permissions', { method: 'POST', body: { scope, display_name, domain: domain || undefined } })
         .then(() => {
           authStore.showMessage(`Permission "${display_name}" created.`, 'success', 2500)
-          loadPermissions()
+          loadAdminData()
         })
         .catch(e => {
           authStore.showMessage(e.message || 'Failed to create permission', 'error')
         })
       return // Don't call closeDialog() again
+    } else if (t === 'oidc-edit') {
+      const { client_id, client_secret, isNew } = dialog.value.data
+      const name = dialog.value.data.name?.trim()
+      const uris = dialog.value.data.redirect_uris?.trim()
+      if (!name) throw new Error('Client name required')
+
+      const redirect_uris = uris ? uris.split('\n').map(u => u.trim()).filter(u => u) : []
+
+      // Close dialog immediately, then perform async operation
+      closeDialog()
+
+      const req = client_secret
+        ? sha256Hex(client_secret).then(secret_hash => isNew
+            ? 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)
+          loadAdminData()
+        })
+        .catch(e => {
+          authStore.showMessage(e.message || `Failed to ${isNew ? 'create' : 'update'} OIDC client`, 'error')
+        })
+      return // Don't call closeDialog() again
+    } else if (t === 'server-config') {
+      const rp_name = dialog.value.data.rp_name?.trim() || ''
+      const auth_host = dialog.value.data.auth_host?.trim() || ''
+      // Origins are stored as-is (hostnames); backend normalizes with https://
+      const origins = dialog.value.data.origins
+        .map(o => o.trim())
+        .filter(o => o)
+
+      closeDialog()
+      apiJson('/auth/api/admin/server-config', { method: 'PATCH', body: { rp_name, auth_host, origins } })
+        .then(() => {
+          authStore.showMessage('Server configuration updated.', 'success', 2500)
+          // Reload settings to reflect rp_name changes
+          authStore.loadSettings().then(() => {
+            if (authStore.settings?.rp_name) document.title = authStore.settings.rp_name + ' Admin'
+          })
+        })
+        .catch(e => {
+          authStore.showMessage(e.message || 'Failed to update server configuration', 'error')
+        })
+      return // Don't call closeDialog() again
     } else if (t === 'confirm') {
-      const action = dialog.value.data.action; if (action) await action()
+      const action = dialog.value.data.action
+      // Close dialog first, then perform action (errors shown via showMessage)
+      closeDialog()
+      if (action) {
+        try {
+          await action()
+        } catch (e) {
+          authStore.showMessage(e.message || 'Action failed', 'error')
+        }
+      }
+      return // Already closed
     }
     closeDialog()
   } catch (e) {
@@ -685,26 +949,33 @@ async function submitDialog() {
     <StatusMessage />
     <main class="app-main">
       <LoadingView v-if="loading" :message="loadingMessage" />
-      <AuthRequiredMessage
+      <AccessDenied v-else-if="showBackMessage" />
-        v-else-if="showBackMessage"
+      <AccessDenied
-        @reload="reloadPage"
+        v-else-if="error"
+        icon="⚠️"
+        title="Error"
+        :message="error"
       />
-      <section v-else-if="authenticated && (info?.is_global_admin || info?.is_org_admin)" class="view-root view-root--wide view-admin">
+      <AccessDenied
+        v-else-if="authenticated && !isMasterAdmin && !isOrgAdmin"
+        icon="⛔"
+        message="You do not have admin permissions for this application."
+      />
+      <section v-else-if="authenticated && (isMasterAdmin || isOrgAdmin)" class="view-root view-root--wide view-admin">
         <header class="view-header">
-          <h1>{{ pageHeading }}</h1>
           <Breadcrumbs ref="breadcrumbsRef" :entries="breadcrumbEntries" @keydown="handleBreadcrumbKeydown" />
         </header>
 
         <section class="section-block admin-section">
           <div class="section-body admin-section-body">
-            <div v-if="error" class="surface surface--tight error">{{ error }}</div>
+            <div class="admin-panels">
-            <div v-else class="admin-panels">
                                   <AdminOverview
-                  v-if="!selectedUser && !selectedOrg && (info.is_global_admin || info.is_org_admin)"
+                  v-if="!selectedUser && !selectedOrg && !currentOidcId && (isMasterAdmin || isOrgAdmin)"
                   ref="adminOverviewRef"
                   :info="info"
                   :orgs="orgs"
                   :permissions="permissions"
+                  :oidc-clients="oidcClients"
                   :navigation-disabled="hasActiveModal"
                   :permission-summary="permissionSummary"
                   @create-org="createOrg"
@@ -715,6 +986,10 @@ async function submitDialog() {
                   @open-dialog="openDialog"
                   @delete-permission="deletePermission"
                   @rename-permission-display="renamePermissionDisplay"
+                  @create-oidc-client="createOidcClient"
+                  @open-oidc-client="openOidcClient"
+                  @delete-oidc-client="deleteOidcClient"
+                  @open-server-config="openServerConfig"
                   @navigate-out="handlePanelNavigateOut"
                 />
 
@@ -735,6 +1010,7 @@ async function submitDialog() {
                   @edit-user-name="editUserName"
                   @close-reg-modal="showRegModal = false"
                   @navigate-out="handlePanelNavigateOut"
+                  @delete-user="deleteUser(selectedUser, userDetail)"
                 />
                 <AdminOrgDetail
                   v-else-if="selectedOrg"
@@ -749,10 +1025,23 @@ async function submitDialog() {
                   @create-user-in-role="createUserInRole"
                   @open-user="openUser"
                   @toggle-role-permission="toggleRolePermission"
-                  @on-role-drag-over="onRoleDragOver"
+                  @move-user-to-role="moveUserToRoleFromDrag"
+                  @navigate-out="handlePanelNavigateOut"
+                />
+
+                <AdminOidcDetail
+                  v-else-if="currentOidcId && editingOidcClient"
+                  ref="adminOidcDetailRef"
+                  :client="editingOidcClient"
+                  :permissions="permissions"
+                  :is-new="editingOidcClient.isNew"
+                  :navigation-disabled="hasActiveModal"
+                  @save="handleOidcSave"
+                  @cancel="handleOidcCancel"
+                  @delete="deleteOidcClient"
+                  @reset-secret="resetOidcSecret"
+                  @create-permission="createPermissionForClient"
                   @navigate-out="handlePanelNavigateOut"
-                  @on-role-drop="onRoleDrop"
-                  @on-user-drag-start="onUserDragStart"
                 />
 
               </div>
@@ -763,16 +1052,17 @@ 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>
 
 <style scoped>
 .view-admin { padding-bottom: var(--space-3xl); }
-.view-header { display: flex; flex-direction: column; gap: var(--space-sm); }
-.admin-section { margin-top: var(--space-xl); }
 .admin-section-body { display: flex; flex-direction: column; gap: var(--space-xl); }
 .admin-panels { display: flex; flex-direction: column; gap: var(--space-xl); }
 </style>

frontend/auth/admin/index.html

@@ -3,7 +3,9 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Admin</title>
+    <title>Admin</title>
+    <script>(localStorage.getItem('paskia-theme')==='dark'||localStorage.getItem('paskia-theme')!=='light'&&matchMedia('(prefers-color-scheme:dark)').matches)&&document.documentElement.classList.add('dark')</script>
+    <link rel="stylesheet" href="/src/assets/style.css">
   </head>
   <body>
     <div id="admin-app"></div>

frontend/auth/admin/main.js

@@ -1,4 +1,5 @@
-import '@/assets/style.css'
+import { initThemeFromCache } from '@/utils/theme'
+initThemeFromCache()
 
 import { createApp } from 'vue'
 import { createPinia } from 'pinia'

frontend/auth/index.html

@@ -4,6 +4,8 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Auth Profile</title>
+    <script>(localStorage.getItem('paskia-theme')==='dark'||localStorage.getItem('paskia-theme')!=='light'&&matchMedia('(prefers-color-scheme:dark)').matches)&&document.documentElement.classList.add('dark')</script>
+    <link rel="stylesheet" href="/src/assets/style.css">
   </head>
   <body>
     <div id="app"></div>

frontend/auth/main.js

@@ -1,4 +1,5 @@
-import '@/assets/style.css'
+import { initThemeFromCache } from '@/utils/theme'
+initThemeFromCache()
 
 import { createApp } from 'vue'
 import { createPinia } from 'pinia'

frontend/auth/restricted/RestrictedApi.vue

@@ -2,19 +2,23 @@
   <RestrictedAuth
     :mode="authMode"
     :remote-auth-token="remoteAuthToken"
+    :oidc-query-string="oidcQueryString"
     @authenticated="handleAuthenticated"
     @back="handleBack"
   />
 </template>
 
 <script setup>
-import { computed, onMounted, ref } from 'vue'
+import { onMounted, ref } from 'vue'
 import RestrictedAuth from '@/components/RestrictedAuth.vue'
 
 // Check if this is a remote auth URL: /auth/{token}
 // The token is a 5-word passphrase like "word1.word2.word3.word4.word5"
 const remoteAuthToken = ref(null)
 
+// For OIDC flow, pass the raw query string to preserve exact param values
+const oidcQueryString = window.location.search.includes('client_id=') ? window.location.search : null
+
 function extractRemoteToken() {
   const path = window.location.pathname
   // Match /auth/{token} where token is a passphrase with dots
@@ -30,14 +34,20 @@ function extractRemoteToken() {
   return null
 }
 
-// Detect mode from URL hash fragment
+// Parse URL hash fragment
-const authMode = computed(() => {
+const hashParams = new URLSearchParams(window.location.hash.slice(1))
-  const params = new URLSearchParams(window.location.hash.slice(1))
+
-  const mode = params.get('mode')
+// Determine auth mode based on URL path
-  if (mode === 'reauth') return 'reauth'
+// - /auth/restricted/oidc: OIDC flow, no session dependency
-  if (mode === 'forbidden') return 'forbidden'
+// - /auth/restricted/iframe: iframe embedding, mode from hash params
-  return 'login'
+// - Other paths: forward auth, mode from hash params
-})
+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)
+  authMode = ['reauth', 'forbidden'].includes(hashParams.get('mode')) ? hashParams.get('mode') : 'login'
+}
 
 function postToParent(message) {
   if (window.parent && window.parent !== window) {
@@ -46,10 +56,15 @@ function postToParent(message) {
 }
 
 function handleAuthenticated(result) {
+  if (result.redirect_url) {
+    // OIDC flow: redirect to client with auth code
+    window.location.href = result.redirect_url
+    return
+  }
   postToParent({
     type: 'auth-success',
     authenticated: true,
-    sessionToken: result.session_token
+    exchangeCode: result.exchange_code
   })
 }
 

frontend/auth/restricted/index.html

@@ -1,8 +1,10 @@
 <!DOCTYPE html>
-<html lang="en" style="background: transparent">
+<html lang="en">
   <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>
+    <link rel="stylesheet" href="/src/assets/style.css">
   </head>
   <body>
     <div id="app"></div>

frontend/auth/restricted/main.js

@@ -1,6 +1,6 @@
+import './theme.js'
 import { createApp } from 'vue'
 import RestrictedApi from './RestrictedApi.vue'
-import '@/assets/style.css'
 import { initKeyboardNavigation } from '@/utils/keynav'
 
 createApp(RestrictedApi).mount('#app')

frontend/auth/restricted/theme.js

@@ -0,0 +1,11 @@
+// Early theme for restricted app - user preference (localStorage) wins, then URL param
+import { applyTheme, getCachedTheme } from '@/utils/theme.js'
+
+function getTheme() {
+  const params = new URLSearchParams(location.hash.slice(1))
+  return getCachedTheme() || params.get('theme') || ''
+}
+
+// Apply theme class to document root
+applyTheme(getTheme())
+addEventListener('hashchange', () => applyTheme(getTheme()))

frontend/int/forward/index.html

@@ -4,6 +4,7 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Access Restricted</title>
+    <script>(localStorage.getItem('paskia-theme')==='dark'||localStorage.getItem('paskia-theme')!=='light'&&matchMedia('(prefers-color-scheme:dark)').matches)&&document.documentElement.classList.add('dark')</script>
   </head>
   <body>
     <div id="app"></div>

frontend/int/reset/ResetApp.vue

@@ -1,14 +1,14 @@
 <template>
   <div class="app-shell">
-    <div v-if="status.show" class="global-status" style="display: block;">
+    <div v-if="status.show" class="global-status show">
       <div :class="['status', status.type]">
         {{ status.message }}
       </div>
     </div>
 
     <main class="view-root">
-      <div class="surface surface--tight" style="max-width: 560px; margin: 0 auto; width: 100%;">
+      <div class="surface surface--tight reset-container">
-        <header class="view-header" style="text-align: center;">
+        <header class="view-header center">
           <h1>🔑 Registration</h1>
           <p class="view-lede">
             {{ subtitleMessage }}
@@ -23,7 +23,7 @@
 
         <section class="section-block" v-else-if="!canRegister">
           <div class="section-body center">
-            <div class="button-row center" style="justify-content: center;">
+            <div class="button-row button-row--center">
               <button class="btn-secondary" @click="goHome">Return to sign-in</button>
             </div>
           </div>
@@ -59,7 +59,8 @@
 import { computed, onMounted, reactive, ref } from 'vue'
 import passkey from '@/utils/passkey'
 import { getSettings, uiBasePath } from '@/utils/settings'
-import { apiJson, ApiError, getUserFriendlyErrorMessage } from '@/utils/api'
+import { apiJson, ApiError, getUserFriendlyErrorMessage, settings as paskiaSettings } from 'paskia'
+import { updateThemeFromSession } from '@/utils/theme'
 
 const status = reactive({
   show: false,
@@ -71,21 +72,21 @@ const initializing = ref(true)
 const loading = ref(false)
 const token = ref('')
 const settings = ref(null)
-const userInfo = ref(null)
+const tokenInfo = ref(null)
 const displayName = ref('')
 const errorMessage = ref('')
 let statusTimer = null
 
-const sessionDescriptor = computed(() => userInfo.value?.session_type || 'your enrollment')
+const sessionDescriptor = computed(() => tokenInfo.value?.token_type || 'your enrollment')
 const subtitleMessage = computed(() => {
   if (initializing.value) return 'Preparing your secure enrollment…'
   if (!canRegister.value) return 'This authentication link is no longer valid.'
-  return `Finish up ${sessionDescriptor.value}. You may edit the name below if needed, and it will be saved to your passkey.`
+  return `Finish up ${sessionDescriptor.value}. The name entered will be stored on your passkey and on our system.`
 })
 
 const basePath = computed(() => uiBasePath())
 
-const canRegister = computed(() => !!(token.value && userInfo.value))
+const canRegister = computed(() => !!(token.value && tokenInfo.value))
 
 function showMessage(message, type = 'info', duration = 3000) {
   status.show = true
@@ -109,15 +110,17 @@ async function fetchSettings() {
   }
 }
 
-async function fetchUserInfo() {
+async function fetchTokenInfo() {
   if (!token.value) return
   try {
-    userInfo.value = await apiJson(`/auth/api/user-info?reset=${encodeURIComponent(token.value)}`, {
+    tokenInfo.value = await apiJson('/auth/api/token-info', {
-      method: 'POST'
+      method: 'GET',
+      headers: { 'Authorization': `Bearer ${token.value}` },
     })
-    displayName.value = userInfo.value?.user?.user_name || ''
+    displayName.value = tokenInfo.value.display_name
+    if (tokenInfo.value.theme) updateThemeFromSession({ user: { theme: tokenInfo.value.theme } })
   } catch (error) {
-    console.error('Failed to load user info', error)
+    console.error('Failed to load token info', error)
     const message = error instanceof ApiError
       ? (error.data?.detail || 'The authentication link is invalid or expired.')
       : getUserFriendlyErrorMessage(error)
@@ -143,7 +146,7 @@ async function registerPasskey() {
   }
 
   try {
-    await setSessionCookie(result)
+    await exchangeCode(result)
   } catch (error) {
     loading.value = false
     const message = error?.message || 'Failed to establish session'
@@ -155,15 +158,14 @@ async function registerPasskey() {
   setTimeout(() => { loading.value = false; goHome() }, 800)
 }
 
-async function setSessionCookie(result) {
+async function exchangeCode(result) {
-  if (!result?.session_token) {
+  if (!result?.exchange_code) {
-    throw new Error('Registration response missing session_token')
+    throw new Error('Registration response missing exchange_code')
   }
   return await apiJson('/auth/api/set-session', {
     method: 'POST',
-    headers: {
+    headers: { 'Authorization': `Bearer ${result.exchange_code}` },
-      Authorization: `Bearer ${result.session_token}`
+    timeout: paskiaSettings.auth_ms,
-    }
   })
 }
 
@@ -196,19 +198,20 @@ onMounted(async () => {
     initializing.value = false
     return
   }
-  await fetchUserInfo()
+  await fetchTokenInfo()
   initializing.value = false
 })
 </script>
 
 <style scoped>
-.center {
+main.view-root { min-height: 100vh; align-items: center; justify-content: center; padding: 2rem 1rem; }
-  text-align: center;
+.reset-container {
-}
+  max-width: 520px;
-
+  margin: 0 auto;
-.button-row.center {
+  width: 100%;
   display: flex;
-  justify-content: center;
+  flex-direction: column;
+  gap: 1.75rem;
 }
 
 .section-body {

frontend/int/reset/index.html

@@ -4,6 +4,7 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Complete Passkey Setup</title>
+    <script>(localStorage.getItem('paskia-theme')==='dark'||localStorage.getItem('paskia-theme')!=='light'&&matchMedia('(prefers-color-scheme:dark)').matches)&&document.documentElement.classList.add('dark')</script>
   </head>
   <body>
     <div id="app"></div>

frontend/package.json

@@ -10,10 +10,13 @@
   },
   "dependencies": {
     "@simplewebauthn/browser": "^13.1.2",
+    "paskia": "file:../paskia-js",
     "pinia": "^3.0.3",
     "qrcode": "^1.5.4",
     "sirv": "^3.0.2",
-    "vue": "^3.5.17"
+    "uuidv7": "^1.1.0",
+    "vue": "^3.5.17",
+    "vuedraggable": "^4.1.0"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.0",

frontend/src/admin/AdminDialogs.vue

@@ -1,15 +1,173 @@
 <script setup>
+import { computed } from 'vue'
 import Modal from '@/components/Modal.vue'
 import NameEditForm from '@/components/NameEditForm.vue'
+import { useAuthStore } from '@/stores/auth'
 
 const props = defineProps({
   dialog: Object,
-  PERMISSION_ID_PATTERN: String
+  PERMISSION_ID_PATTERN: String,
+  settings: Object
 })
 
-const emit = defineEmits(['submitDialog', 'closeDialog'])
+const emit = defineEmits(['submitDialog', 'closeDialog', 'resetOidcSecret', 'createPermissionForClient'])
 
 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`)
+
+// Initialize validation properties
+if (props.dialog?.data && props.dialog.type === 'server-config') {
+  if (!('authHostValidation' in props.dialog.data)) {
+    props.dialog.data.authHostValidation = null
+  }
+}
+
+const isValidationInvalid = computed(() => {
+  if (props.dialog?.type !== 'server-config') return false
+  const d = props.dialog.data
+  if (d.authHostValidation?.startsWith('invalid') || d.authHostValidation === 'validating') return true
+  if (d.originValidation?.some(v => v === 'invalid' || v === 'validating')) return true
+  return false
+})
+
+// Copy-to-clipboard helper
+const authStore = useAuthStore()
+function copyText(value, label) {
+  navigator.clipboard.writeText(value).then(() => {
+    authStore.showMessage(`${label} copied to clipboard`, 'success', 1500)
+  })
+}
+
+function addOrigin() {
+  const d = props.dialog?.data
+  if (d) {
+    d.origins.push(rpId.value)
+    d.originValidation.push(null)
+    validateOrigin(d.origins[d.origins.length - 1], d.origins.length - 1)
+  }
+}
+function removeOrigin(i) {
+  const d = props.dialog?.data
+  if (d) {
+    d.origins.splice(i, 1)
+    d.originValidation.splice(i, 1)
+  }
+}
+function stripScheme(val, i) {
+  const d = props.dialog?.data
+  if (d) d.origins[i] = val.replace(/^https:\/\//, '').replace(/\/+$/, '')
+}
+function stripSchemeAuthHost() {
+  const d = props.dialog?.data
+  if (d && d.auth_host) d.auth_host = d.auth_host.replace(/^https:\/\//, '').replace(/\/+$/, '')
+}
+function focusOriginStart(e) {
+  e.target.setSelectionRange(0, 0)
+}
+
+function validateOriginDomain(origin, rpId) {
+  if (!origin.trim()) return false
+  try {
+    const url = origin.startsWith('http') ? new URL(origin) : new URL('https://' + origin)
+    const hostname = url.hostname
+    return hostname === rpId || hostname.endsWith('.' + rpId)
+  } catch {
+    return false
+  }
+}
+
+async function validateOriginConnectivity(origin, i) {
+  const d = props.dialog?.data
+  if (!d) return
+
+  d.originValidation[i] = 'validating'
+  try {
+    const cleanOrigin = origin.replace(/\/+$/, '')
+    const testUrl = cleanOrigin.startsWith('http') ? cleanOrigin : 'https://' + cleanOrigin
+    const response = await fetch(testUrl + '/auth/api/settings', {
+      method: 'GET',
+      headers: { 'Accept': 'application/json' }
+    })
+    if (response.ok) {
+      const data = await response.json()
+      // Check if it returns valid settings (has rp_id and matches current rp_id)
+      const result = (data.rp_id && data.rp_id === rpId.value) ? 'valid' : 'invalid'
+      // Only update if the origin hasn't changed
+      if (d.origins[i] === origin) {
+        d.originValidation[i] = result
+      }
+    } else {
+      if (d.origins[i] === origin) {
+        d.originValidation[i] = 'invalid'
+      }
+    }
+  } catch (e) {
+    if (d.origins[i] === origin) {
+      d.originValidation[i] = 'invalid'
+    }
+  }
+}
+
+function validateOrigin(origin, i) {
+  const d = props.dialog?.data
+  if (!d) return
+
+  const id = rpId.value
+  if (validateOriginDomain(origin, id)) {
+    validateOriginConnectivity(origin, i)
+  } else {
+    d.originValidation[i] = 'invalid'
+  }
+}
+
+async function validateAuthHostConnectivity(authHost) {
+  const d = props.dialog?.data
+  if (!d) return
+
+  d.authHostValidation = 'validating'
+  try {
+    const cleanAuthHost = authHost.replace(/\/+$/, '')
+    const testUrl = cleanAuthHost.startsWith('http') ? cleanAuthHost : 'https://' + cleanAuthHost
+    const response = await fetch(testUrl + '/auth/api/settings', {
+      method: 'GET',
+      headers: { 'Accept': 'application/json' }
+    })
+    if (response.ok) {
+      const data = await response.json()
+      // Check if it returns valid settings (has rp_id and matches current rp_id)
+      const result = (data.rp_id && data.rp_id === rpId.value) ? 'valid' : 'invalid'
+      // Only update if the auth_host hasn't changed
+      if (d.auth_host === authHost) {
+        d.authHostValidation = result
+      }
+    } else {
+      if (d.auth_host === authHost) {
+        d.authHostValidation = 'invalid-connectivity'
+      }
+    }
+  } catch (e) {
+    if (d.auth_host === authHost) {
+      d.authHostValidation = 'invalid-connectivity'
+    }
+  }
+}
+
+function validateAuthHost() {
+  const d = props.dialog?.data
+  if (!d || !d.auth_host?.trim()) {
+    d.authHostValidation = null // Allow empty
+    return
+  }
+
+  const id = rpId.value
+  if (validateOriginDomain(d.auth_host, id)) {
+    validateAuthHostConnectivity(d.auth_host)
+  } else {
+    d.authHostValidation = 'invalid-domain'
+  }
+}
 </script>
 
 <template>
@@ -21,7 +179,9 @@ const NAME_EDIT_TYPES = new Set(['org-update', 'role-update', 'user-update-name'
         <template v-else-if="dialog.type==='role-update'">Edit Role</template>
         <template v-else-if="dialog.type==='user-create'">Add User To Role</template>
         <template v-else-if="dialog.type==='user-update-name'">Edit User Name</template>
-        <template v-else-if="dialog.type==='perm-create' || dialog.type==='perm-display'">{{ dialog.type === 'perm-create' ? 'Create Permission' : 'Edit Permission Display' }}</template>
+        <template v-else-if="dialog.type==='perm-create' || dialog.type==='perm-display'">{{ dialog.type === 'perm-create' ? 'Create Permission' : 'Edit Permission' }}</template>
+        <template v-else-if="dialog.type==='oidc-edit'">{{ dialog.data?.isNew ? 'New OIDC Client' : 'OIDC Client' }}</template>
+        <template v-else-if="dialog.type==='server-config'">Server Options</template>
         <template v-else-if="dialog.type==='confirm'">Confirm</template>
       </h3>
       <form @submit.prevent="$emit('submitDialog')" class="modal-form">
@@ -72,16 +232,52 @@ const NAME_EDIT_TYPES = new Set(['org-update', 'role-update', 'user-update-name'
           <label>Display Name
             <input ref="displayNameInput" v-model="dialog.data.display_name" required />
           </label>
-          <label>Permission ID
+          <label>Permission Scope
-            <input v-model="dialog.data.id" :placeholder="dialog.type === 'perm-create' ? 'yourapp:permission' : dialog.data.permission.id" required :pattern="PERMISSION_ID_PATTERN" title="Allowed: A-Za-z0-9:._~-" data-form-type="other" />
+            <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">The permission ID is used for permission checks in the application. Changing it may break deployed applications that reference this permission.</p>
+          <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==='server-config'">
+          <label>Site Branding (rp-name)
+            <input v-model="dialog.data.rp_name" :placeholder="rpId" />
+          </label>
+          <label>Dedicated Authentication Site (auth-host)
+            <input v-model="dialog.data.auth_host" @input="validateAuthHost()" :class="{ 'input-error': dialog.data.authHostValidation?.startsWith('invalid') }" />
+          </label>
+          <p v-if="dialog.data.authHostValidation === 'validating'" class="small muted">Validating...</p>
+          <p v-else-if="dialog.data.authHostValidation === 'valid'" class="small muted">Valid</p>
+          <p v-else-if="dialog.data.authHostValidation === 'invalid-domain'" class="small muted">Invalid domain</p>
+          <p v-else-if="dialog.data.authHostValidation === 'invalid-connectivity'" class="small muted">Well-formed but unreachable</p>
+          <p v-else-if="dialog.data.authHostValidation === 'invalid'" class="small muted">Invalid configuration</p>
+          <p v-else-if="dialog.data.authHostValidation === 'invalid'" class="small muted">Enter {{ rpId }} or any subdomain of it.</p>
+          <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
+                :value="dialog.data.origins[i]"
+                @input="e => { dialog.data.origins[i] = e.target.value; validateOrigin(e.target.value, i) }"
+                @focus="focusOriginStart"
+                class="origin-input"
+                :class="{ 'input-error': dialog.data.originValidation[i] === 'invalid' }"
+              />
+              <button type="button" class="icon-btn delete-icon" @click="removeOrigin(i)" aria-label="Remove origin" title="Remove origin">❌</button>
+            </div>
+          </div>
+          <p v-if="!dialog.data.origins.length" class="small muted">{{ rpId }} and all subdomains allowed.</p>
+          <p v-else class="small muted">Only the above sites are allowed to authenticate.</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)" class="modal-actions">
+        <div v-if="!NAME_EDIT_TYPES.has(dialog.type) && !NO_SUBMIT_TYPES.has(dialog.type)" class="modal-actions">
           <button
             type="button"
             class="btn-secondary"
@@ -93,17 +289,46 @@ const NAME_EDIT_TYPES = new Set(['org-update', 'role-update', 'user-update-name'
           <button
             type="submit"
             class="btn-primary"
-            :disabled="dialog.busy"
+            :disabled="dialog.busy || isValidationInvalid"
           >
             {{ 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>
-.error { color: var(--color-danger-text); }
+.optional { font-weight: normal; color: var(--color-text-muted); font-size: 0.85em; }
-.small { font-size: 0.9rem; }
+.oidc-divider { border: none; border-top: 1px solid var(--color-border); margin: var(--space-sm) 0; }
-.muted { color: var(--color-text-muted); }
+.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; }
+
+/* Server config 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-row .delete-icon { flex-shrink: 0; }
+.origin-add-btn { font-size: 1.2rem; }
+
+.input-error {
+  border-color: var(--color-error);
+  background: var(--color-error-bg, rgba(239, 68, 68, 0.05));
+}
 </style>

frontend/src/admin/AdminOidcDetail.vue

@@ -0,0 +1,283 @@
+<script setup>
+import { ref, computed, watch, onMounted } from 'vue'
+import { getDirection, navigateButtonRow } from '@/utils/keynav'
+import { useAuthStore } from '@/stores/auth'
+
+const props = defineProps({
+  client: Object,
+  permissions: Array,
+  isNew: { type: Boolean, default: false },
+  navigationDisabled: { type: Boolean, default: false }
+})
+
+const emit = defineEmits(['save', 'cancel', 'delete', 'resetSecret', 'createPermission', 'navigateOut'])
+
+const authStore = useAuthStore()
+const headerRef = ref(null)
+
+// Helper function to build URLs
+function authSitePath(path) {
+  const url = new URL(authStore.settings.auth_site_url)
+  url.pathname = path
+  return url.toString()
+}
+
+// Local form state
+const name = ref('')
+const redirectUris = ref('')
+const clientSecret = ref(null)
+
+// Computed
+const clientId = computed(() => props.client?.client_id || props.client?.uuid || '')
+const discoveryUrl = computed(() => authSitePath('/.well-known/openid-configuration'))
+const iconUrl = computed(() => authSitePath('/favicon.ico'))
+
+// Groups (permissions) scoped to this client
+const clientGroups = computed(() => {
+  if (!props.client || !props.permissions) return []
+  const clientUuid = props.client.uuid || props.client.client_id
+  return props.permissions.filter(p => p.domain === clientUuid).sort((a, b) => a.scope.localeCompare(b.scope))
+})
+
+// Initialize form data from props
+watch(() => props.client, (c) => {
+  if (c) {
+    name.value = c.name || ''
+    redirectUris.value = Array.isArray(c.redirect_uris) ? c.redirect_uris.join('\n') : (c.redirect_uris || '')
+    clientSecret.value = c.client_secret || null
+  }
+}, { immediate: true })
+
+// Copy-to-clipboard helper
+function copyText(value, label) {
+  navigator.clipboard.writeText(value).then(() => {
+    authStore.showMessage(`${label} copied to clipboard`, 'success', 1500)
+  })
+}
+
+function handleResetSecret() {
+  emit('resetSecret', clientId.value)
+}
+
+// When parent resets secret, update local state
+watch(() => props.client?.client_secret, (newSecret) => {
+  if (newSecret) {
+    clientSecret.value = newSecret
+  }
+})
+
+function handleSave() {
+  const trimmedName = name.value.trim()
+  if (!trimmedName) {
+    authStore.showMessage('Client name is required', 'error')
+    return
+  }
+  const uris = redirectUris.value.trim()
+  const redirect_uris = uris ? uris.split('\n').map(u => u.trim()).filter(u => u) : []
+
+  emit('save', {
+    client_id: clientId.value,
+    client_secret: clientSecret.value,
+    name: trimmedName,
+    redirect_uris,
+    isNew: props.isNew
+  })
+}
+
+function handleDelete() {
+  emit('delete', props.client)
+}
+
+function handleCreatePermission() {
+  emit('createPermission', clientId.value)
+}
+
+function handleCancel() {
+  emit('cancel')
+}
+
+// Keyboard navigation
+function handleHeaderKeydown(event) {
+  if (props.navigationDisabled) return
+
+  const direction = getDirection(event)
+  if (!direction) return
+
+  event.preventDefault()
+
+  if (direction === 'left' || direction === 'right') {
+    navigateButtonRow(headerRef.value, event.target, direction, { itemSelector: 'button, a' })
+  } else if (direction === 'up') {
+    emit('navigateOut', 'up')
+  }
+}
+
+function focusFirstElement() {
+  const firstFocusable = headerRef.value?.querySelector('button, a, input')
+  if (firstFocusable) firstFocusable.focus()
+}
+
+defineExpose({ focusFirstElement })
+</script>
+
+<template>
+  <div class="oidc-detail">
+    <form @submit.prevent="handleSave" class="oidc-form">
+      <!-- Client credentials section -->
+      <section class="section-block">
+        <div class="section-header">
+          <h2>Client Configuration</h2>
+          <p class="section-description">Configure these values in the client application.</p>
+        </div>
+        <div class="section-body">
+
+        <dl class="oidc-dl">
+          <dt>Authentication Name</dt>
+          <dd>
+            <output @click="copyText(authStore.settings.rp_name, 'Authentication Name')" title="Click to copy">{{ authStore.settings.rp_name }}</output>
+            <span class="small muted"> (Login With, may affect URLs – optional)</span>
+          </dd>
+
+          <dt>Client ID</dt>
+          <dd><output @click="copyText(clientId, 'Client ID')" title="Click to copy">{{ clientId }}</output></dd>
+
+          <dt>Client Secret <button v-if="!clientSecret" type="button" class="icon-btn" @click="handleResetSecret" title="Revoke and re-generate secret">🔄</button></dt>
+          <dd>
+            <output v-if="clientSecret" @click="copyText(clientSecret, 'Client Secret')" title="Click to copy">{{ clientSecret }}</output>
+            <span v-else class="small muted">(only stored in hashed form)</span>
+          </dd>
+
+          <dt>Auto Discovery URL</dt>
+          <dd><output @click="copyText(discoveryUrl, 'OpenID Connect Auto Discovery URL')" title="Click to copy">{{ discoveryUrl }}</output></dd>
+
+          <dt>Icon URL</dt>
+          <dd>
+            <output @click="copyText(iconUrl, 'Icon URL')" title="Click to copy">{{ iconUrl }}</output>
+            <span class="small muted"> (optional)</span>
+          </dd>
+
+
+          <template v-if="clientGroups.length">
+            <dt>Groups Claim Name</dt>
+            <dd>
+              <output @click="copyText('groups', 'Groups Claim Name')" title="Click to copy">groups</output>
+            </dd>
+          </template>
+
+          <dt>Groups <button type="button" class="icon-btn" @click="handleCreatePermission" title="Add permission scoped to this client">➕</button></dt>
+          <dd class="oidc-groups">
+            <template v-if="clientGroups.length">
+              <output v-for="group in clientGroups" :key="group.uuid" class="oidc-group" @click="copyText(group.scope, 'Group Value')" :title="group.display_name">{{ group.scope }}</output>
+            </template>
+            <span v-else class="small muted">(no permissions defined)</span>
+          </dd>
+        </dl>
+
+        <span class="warning-text">
+          <strong v-if="clientSecret">⚠️ {{ isNew ? 'Save the secret now — it cannot be retrieved later.' : 'Saving will prevent access with the old secret.' }}</strong>
+          <span v-else>ℹ️ The client may use groups to check for required permissions.</span>
+        </span>
+        </div>
+      </section>
+
+      <!-- Editable fields -->
+      <section class="section-block">
+        <div class="section-header">
+          <h2>Paskia Configuration</h2>
+        </div>
+        <div class="section-body">
+        <label>Client Name
+          <input v-model="name" required />
+        </label>
+
+        <label>Redirect URIs
+          <p class="small muted">This should be provided by the client application.</p>
+          <textarea v-model="redirectUris" placeholder="(autodiscover one on first use)" rows="3"></textarea>
+        </label>
+        </div>
+      </section>
+
+      <!-- Actions -->
+      <div class="oidc-actions">
+        <button type="button" class="btn-secondary" @click="handleCancel">Cancel</button>
+        <button v-if="!isNew" type="button" class="btn-danger" @click="handleDelete">Delete Client</button>
+        <button type="submit" class="btn-primary">Save</button>
+      </div>
+    </form>
+  </div>
+</template>
+
+<style scoped>
+.oidc-detail {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-lg);
+}
+
+.oidc-header {
+  margin-bottom: 0;
+}
+
+.oidc-header h2 {
+  margin: 0;
+}
+
+.oidc-form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-lg);
+}
+
+.oidc-dl {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 0.3rem 1rem;
+  align-items: baseline;
+  margin: var(--space-sm) 0;
+}
+
+.oidc-dl dt {
+  font-size: 0.85rem;
+  color: var(--color-text-muted);
+  white-space: nowrap;
+}
+
+.oidc-dl dd {
+  margin: 0;
+  overflow: hidden;
+  display: flex;
+  align-items: baseline;
+  gap: 0.5em;
+}
+
+.oidc-dl output {
+  font-family: var(--font-mono, monospace);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  min-width: 0;
+}
+
+.warning-text {
+  display: block;
+  font-size: 0.9rem;
+  min-height: 1.4em;
+}
+
+.oidc-group { display: block; }
+.oidc-group { white-space: normal; word-break: break-all; }
+
+.section-body label {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-xs);
+  font-weight: 500;
+}
+
+.oidc-actions {
+  display: flex;
+  gap: var(--space-sm);
+  justify-content: flex-end;
+  margin-top: var(--space-md);
+}
+</style>

frontend/src/admin/AdminOrgDetail.vue

@@ -1,5 +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({
@@ -8,7 +10,7 @@ const props = defineProps({
   navigationDisabled: { type: Boolean, default: false }
 })
 
-const emit = defineEmits(['updateOrg', 'createRole', 'updateRole', 'deleteRole', 'createUserInRole', 'openUser', 'toggleRolePermission', 'onRoleDragOver', 'onRoleDrop', 'onUserDragStart', 'navigateOut'])
+const emit = defineEmits(['updateOrg', 'createRole', 'updateRole', 'deleteRole', 'createUserInRole', 'openUser', 'toggleRolePermission', 'moveUserToRole', 'navigateOut'])
 
 // Template refs for navigation
 const orgTitleRef = ref(null)
@@ -16,7 +18,8 @@ const permMatrixRef = ref(null)
 const rolesGridRef = ref(null)
 
 const sortedRoles = computed(() => {
-  return [...props.selectedOrg.roles].sort((a, b) => {
+  // o.roles is dict[UUID, Role], convert to array for sorting with uuid added
+  return Object.entries(props.selectedOrg.roles).map(([uuid, r]) => ({ uuid, ...r })).sort((a, b) => {
     const nameA = a.display_name.toLowerCase()
     const nameB = b.display_name.toLowerCase()
     if (nameA !== nameB) {
@@ -26,8 +29,47 @@ const sortedRoles = computed(() => {
   })
 })
 
-function permissionDisplayName(id) {
+// Get org's grantable permissions as full permission objects (with UUIDs)
-  return props.permissions.find(p => p.id === id)?.display_name || id
+const orgPermissions = computed(() => {
+  // props.selectedOrg.permissions is dict[UUID, Permission]
+  const uuidSet = new Set(Object.keys(props.selectedOrg.permissions || {}))
+  return props.permissions.filter(p => uuidSet.has(p.uuid))
+})
+
+// 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 normA = getNormalizedName(a.display_name);
+      const normB = getNormalizedName(b.display_name);
+      return normA.localeCompare(normB);
+    })
+}
+
+function roleUserCount(roleUuid) {
+  return Object.values(props.selectedOrg.users).filter(u => u.role === roleUuid).length
+}
+
+function onUserChange(evt, targetRoleUuid) {
+  // Only handle 'added' events (when a user is dropped into this role)
+  if (evt.added) {
+    const userUuid = evt.added.element.uuid
+    emit('moveUserToRole', userUuid, targetRoleUuid)
+  }
 }
 
 function toggleRolePermission(role, pid, checked) {
@@ -77,7 +119,7 @@ function handleMatrixKeydown(event) {
 
   // Calculate grid dimensions
   const cols = sortedRoles.value.length
-  const rows = props.selectedOrg.permissions.length
+  const rows = Object.keys(props.selectedOrg.permissions).length
 
   const currentRow = Math.floor(currentIndex / cols)
   const currentCol = currentIndex % cols
@@ -213,7 +255,7 @@ function handleRoleHeaderKeydown(event, roleIndex) {
     if (checkboxes?.length) {
       // Focus the checkbox in the corresponding column
       const cols = sortedRoles.value.length
-      const rows = props.selectedOrg.permissions.length
+      const rows = Object.keys(props.selectedOrg.permissions).length
       const targetIndex = (rows - 1) * cols + roleIndex
       if (checkboxes[targetIndex]) checkboxes[targetIndex].focus()
       else checkboxes[checkboxes.length - 1].focus()
@@ -281,7 +323,7 @@ defineExpose({ focusFirstElement })
 
 <template>
   <h2 class="org-title" ref="orgTitleRef" @keydown="handleTitleKeydown" :title="selectedOrg.uuid">
-    <span class="org-name">{{ selectedOrg.display_name }}</span>
+    <span class="org-name">{{ selectedOrg.org.display_name }}</span>
     <button @click="$emit('updateOrg', selectedOrg)" class="icon-btn" aria-label="Rename organization" title="Rename organization">✏️</button>
   </h2>
 
@@ -302,17 +344,17 @@ defineExpose({ focusFirstElement })
           </div>
           <div class="grid-head role-head add-role-head" title="Add role" @click="$emit('createRole', selectedOrg)" role="button" tabindex="0" @keydown.enter="$emit('createRole', selectedOrg)">➕</div>
 
-          <template v-for="pid in selectedOrg.permissions" :key="pid">
+          <template v-for="p in orgPermissions" :key="p.uuid">
-            <div class="perm-name" :title="pid">{{ permissionDisplayName(pid) }}</div>
+            <div class="perm-name" :title="p.scope">{{ p.display_name }}</div>
             <div
               v-for="r in sortedRoles"
-              :key="r.uuid + '-' + pid"
+              :key="r.uuid + '-' + p.uuid"
               class="matrix-cell"
             >
               <input
                 type="checkbox"
-                :checked="r.permissions.includes(pid)"
+                :checked="p.uuid in (r.permissions || {})"
-                @change="e => toggleRolePermission(r, pid, e.target.checked)"
+                @change="e => toggleRolePermission(r, p.uuid, e.target.checked)"
               />
             </div>
             <div class="matrix-cell add-role-cell" />
@@ -326,84 +368,87 @@ defineExpose({ focusFirstElement })
         v-for="(r, roleIndex) in sortedRoles"
         :key="r.uuid"
         class="role-column"
-        @dragover="$emit('onRoleDragOver', $event)"
-        @drop="e => $emit('onRoleDrop', e, selectedOrg, r)"
       >
         <div class="role-header" @keydown="e => handleRoleHeaderKeydown(e, roleIndex)">
           <strong class="role-name" :title="r.uuid">
             <span>{{ r.display_name }}</span>
             <button @click="$emit('updateRole', r)" class="icon-btn" aria-label="Edit role" title="Edit role">✏️</button>
+            <button v-if="roleUserCount(r.uuid) === 0" @click="$emit('deleteRole', r)" class="icon-btn delete-icon" aria-label="Delete role" title="Delete role">❌</button>
           </strong>
           <div class="role-actions">
             <button @click="$emit('createUserInRole', selectedOrg, r)" class="plus-btn" aria-label="Add user" title="Add user">➕</button>
           </div>
         </div>
-        <template v-if="r.users.length > 0">
+        <div class="user-list-wrapper">
-          <ul class="user-list" @keydown="handleUserListKeydown">
+          <draggable
-            <li
+            :list="roleUsers(r.uuid)"
-              v-for="u in r.users.slice().sort((a, b) => {
+            group="users"
-                const nameA = a.display_name.toLowerCase()
+            item-key="uuid"
-                const nameB = b.display_name.toLowerCase()
+            tag="ul"
-                if (nameA !== nameB) {
+            class="user-list"
-                  return nameA.localeCompare(nameB)
+            @change="evt => onUserChange(evt, r.uuid)"
-                }
+            @keydown="handleUserListKeydown"
-                return a.uuid.localeCompare(b.uuid)
+          >
-              })"
+            <template #item="{ element: u }">
-              :key="u.uuid"
+              <li
-              class="user-chip"
+                class="user-chip"
-              tabindex="0"
+                tabindex="0"
-              draggable="true"
+                @click="$emit('openUser', u)"
-              @dragstart="e => $emit('onUserDragStart', e, u, selectedOrg.uuid)"
+                @keydown.enter="$emit('openUser', u)"
-              @click="$emit('openUser', u)"
+                :title="u.uuid"
-              @keydown.enter="$emit('openUser', u)"
+              >
-              :title="u.uuid"
+                <ProfilePicture
-            >
+                  class="user-chip-picture"
-              <span class="name">{{ u.display_name }}</span>
+                  :src="u.avatar_url"
-              <span class="meta">{{ u.last_seen ? new Date(u.last_seen).toLocaleDateString() : '—' }}</span>
+                  :title="u.display_name"
-            </li>
+                  width="3.25rem"
-          </ul>
+                  height="100%"
-        </template>
+                  radius="0"
-        <div v-else class="empty-role" @keydown="e => handleEmptyRoleKeydown(e, roleIndex)">
+                  fallback-size="1.3rem"
-          <p class="empty-text muted">No members</p>
+                />
-          <button @click="$emit('deleteRole', r)" class="icon-btn delete-icon" aria-label="Delete empty role" title="Delete role">❌</button>
+                <span class="user-chip-body">
+                  <span class="name">{{ u.display_name }}</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>
+          <div v-if="roleUserCount(r.uuid) === 0" class="empty-role">
+            <p class="empty-text muted">No members</p>
+          </div>
         </div>
       </div>
     </div>
+    <p v-if="sortedRoles.length >= 2" class="roles-hint muted">Members can be drag&dropped to different roles.</p>
 </template>
 
 <style scoped>
 .card.surface { padding: var(--space-lg); }
-.org-title { display: flex; align-items: center; gap: var(--space-sm); margin-bottom: var(--space-lg); }
+.org-title { display: flex; align-items: center; gap: var(--space-sm); margin-bottom: var(--space-lg); font-size: 1.65rem; }
-.org-name { font-size: 1.5rem; font-weight: 600; color: var(--color-heading); }
+.org-name { font-weight: 600; color: var(--color-heading); }
-.icon-btn { background: none; border: none; color: var(--color-text-muted); padding: 0.2rem; border-radius: var(--radius-sm); cursor: pointer; transition: background 0.2s ease, color 0.2s ease; }
-.icon-btn:hover { color: var(--color-heading); background: var(--color-surface-muted); }
-.matrix-wrapper { margin: var(--space-md) 0; padding: var(--space-lg); }
-.matrix-scroll { overflow-x: auto; }
-.matrix-hint { font-size: 0.8rem; color: var(--color-text-muted); }
-.perm-matrix-grid { display: inline-grid; gap: 0.25rem; align-items: stretch; }
-.perm-matrix-grid > * { padding: 0.35rem 0.45rem; font-size: 0.75rem; }
-.perm-matrix-grid .grid-head { color: var(--color-text-muted); text-transform: uppercase; font-weight: 600; letter-spacing: 0.05em; }
-.perm-matrix-grid .perm-head { display: flex; align-items: flex-end; justify-content: flex-start; padding: 0.35rem 0.45rem; font-size: 0.75rem; }
 .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; }
-.perm-name { font-weight: 600; color: var(--color-heading); padding: 0.35rem 0.45rem; font-size: 0.75rem; }
+.roles-grid { display: flex; flex-wrap: wrap; gap: 0; margin-top: var(--space-lg); justify-content: flex-start; align-items: stretch; }
-.roles-grid { display: flex; gap: var(--space-lg); margin-top: var(--space-lg); }
+.role-column { flex: 0 0 17em; border-radius: var(--radius-md); padding: var(--space-md); display: flex; flex-direction: column; }
-.role-column { flex: 1; min-width: 200px; border: 1px solid var(--color-border); border-radius: var(--radius-md); padding: var(--space-md); }
 .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); }
-.plus-btn { background: var(--color-accent-soft); color: var(--color-accent); border: none; border-radius: var(--radius-sm); padding: 0.25rem 0.45rem; font-size: 1.1rem; cursor: pointer; }
+.plus-btn { background: none; color: var(--color-accent); border: none; border-radius: var(--radius-sm); padding: 0.25rem 0.45rem; font-size: 1.1rem; cursor: pointer; }
 .plus-btn:hover { background: rgba(37, 99, 235, 0.18); }
-.user-list { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: var(--space-xs); }
+.user-list-wrapper { position: relative; flex: 1; display: flex; flex-direction: column; min-height: 5.5rem; }
-.user-chip { background: var(--color-surface); border: 1px solid var(--color-border); border-radius: var(--radius-md); padding: 0.45rem 0.6rem; display: flex; justify-content: space-between; gap: var(--space-sm); cursor: grab; }
+.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: 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: var(--color-text-muted); }
+.user-chip-picture { align-self: stretch; }
-.empty-role { border: 1px dashed var(--color-border-strong); border-radius: var(--radius-md); padding: var(--space-sm); display: flex; flex-direction: column; gap: var(--space-xs); align-items: flex-start; }
+.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; }
+.user-list:has(.sortable-ghost) + .empty-role { display: none; }
 .empty-text { margin: 0; }
-.delete-icon { color: var(--color-danger); }
-.delete-icon:hover { background: var(--color-danger-bg); color: var(--color-danger-text); }
-.muted { color: var(--color-text-muted); }
 
 @media (max-width: 720px) {
   .roles-grid { flex-direction: column; }

frontend/src/admin/AdminOverview.vue

@@ -1,19 +1,20 @@
 <script setup>
 import { computed, ref } from 'vue'
 import { getDirection, navigateButtonRow, focusPreferred, focusAtIndex } from '@/utils/keynav'
+import { formatDate } from '@/utils/helpers'
 
 const props = defineProps({
   info: Object,
   orgs: Array,
   permissions: Array,
+  oidcClients: Array,
   permissionSummary: Object,
   navigationDisabled: { type: Boolean, default: false }
 })
 
-const emit = defineEmits(['createOrg', 'openOrg', 'updateOrg', 'deleteOrg', 'toggleOrgPermission', 'openDialog', 'deletePermission', 'renamePermissionDisplay', 'navigateOut'])
+const emit = defineEmits(['createOrg', 'openOrg', 'updateOrg', 'deleteOrg', 'toggleOrgPermission', 'openDialog', 'deletePermission', 'renamePermissionDisplay', 'createOidcClient', 'openOidcClient', 'deleteOidcClient', 'openServerConfig', 'navigateOut'])
 
 // Template refs for navigation
-const orgSection = ref(null)
 const orgActionsRef = ref(null)
 const orgTableRef = ref(null)
 const permMatrixRef = ref(null)
@@ -21,23 +22,56 @@ const permActionsRef = ref(null)
 const permTableRef = ref(null)
 
 const sortedOrgs = computed(() => [...props.orgs].sort((a,b)=> {
-  const nameCompare = a.display_name.localeCompare(b.display_name)
+  const nameCompare = a.org.display_name.localeCompare(b.org.display_name)
   return nameCompare !== 0 ? nameCompare : a.uuid.localeCompare(b.uuid)
 }))
-const sortedPermissions = computed(() => [...props.permissions].sort((a,b)=> a.id.localeCompare(b.id)))
 
-function permissionDisplayName(id) {
+// Map OIDC client UUIDs to display names for permission domain column
-  return props.permissions.find(p => p.id === id)?.display_name || id
+const oidcClientNames = computed(() => {
+  const map = {}
+  for (const c of props.oidcClients || []) map[c.uuid] = c.name
+  return map
+})
+function domainDisplay(domain) {
+  if (!domain) return '—'
+  return oidcClientNames.value[domain] || domain
 }
 
+// Map OIDC client UUIDs to their group permissions (sorted by scope)
+const clientGroups = computed(() => {
+  const map = {}
+  for (const p of props.permissions || []) {
+    if (p.domain) {
+      if (!map[p.domain]) map[p.domain] = []
+      map[p.domain].push(p)
+    }
+  }
+  // Sort each group array by scope
+  for (const key in map) {
+    map[key].sort((a, b) => a.scope.localeCompare(b.scope))
+  }
+  return map
+})
+
+const sortedPermissions = computed(() => [...props.permissions].sort((a,b)=> a.scope.localeCompare(b.scope)))
+
+// Derive admin status from permissions (info contains ctx from validate response)
+const isMasterAdmin = computed(() => props.info?.ctx.permissions.includes('auth:admin'))
+const isOrgAdmin = computed(() => props.info?.ctx.permissions.includes('auth:org:admin'))
+
 function getRoleNames(org) {
-  return org.roles
+  // org.roles is dict[UUID, Role]
+  return Object.values(org.roles)
     .slice()
     .sort((a, b) => a.display_name.localeCompare(b.display_name))
     .map(r => r.display_name)
     .join(', ')
 }
 
+function orgUserCount(org) {
+  return Object.keys(org.users).length
+}
+
 // Table navigation for both org and permissions tables
 function handleTableKeydown(event, tableType) {
   if (props.navigationDisabled) return
@@ -89,7 +123,7 @@ function handleTableKeydown(event, tableType) {
   } else if (direction === 'down' && currentIndex === rows.length - 1) {
     // At bottom of org table, navigate to permissions section
     event.preventDefault()
-    if (tableType === 'org' && props.info.is_global_admin) {
+    if (tableType === 'org' && isMasterAdmin.value) {
       // Navigate to permissions matrix or actions
       if (permMatrixRef.value) {
         const firstCheckbox = permMatrixRef.value.querySelector('input[type="checkbox"]')
@@ -232,7 +266,7 @@ function handlePermActionsKeydown(event) {
 
 // Focus helper for external navigation
 function focusFirstElement() {
-  if (props.info.is_global_admin) {
+  if (isMasterAdmin.value) {
     focusPreferred(orgActionsRef.value, { itemSelector: 'button' })
   } else {
     const firstFocusable = orgTableRef.value?.querySelector('tbody tr a, tbody tr button:not([disabled])')
@@ -245,9 +279,9 @@ defineExpose({ focusFirstElement })
 
 <template>
   <div class="permissions-section" ref="orgSection">
-    <h2>{{ info.is_global_admin ? 'Organizations' : 'Your Organizations' }}</h2>
+    <h2>{{ isMasterAdmin ? 'Organizations' : 'Your Organizations' }}</h2>
     <div class="actions" ref="orgActionsRef" @keydown="handleOrgActionsKeydown">
-      <button v-if="info.is_global_admin" @click="$emit('createOrg')">+ Create Org</button>
+      <button v-if="isMasterAdmin" @click="$emit('createOrg')">+ Create Org</button>
     </div>
     <table class="org-table" ref="orgTableRef" @keydown="e => handleTableKeydown(e, 'org')">
       <thead>
@@ -255,18 +289,18 @@ defineExpose({ focusFirstElement })
           <th>Name</th>
           <th>Roles</th>
           <th>Members</th>
-          <th v-if="info.is_global_admin">Actions</th>
+          <th v-if="isMasterAdmin">Actions</th>
         </tr>
       </thead>
       <tbody>
         <tr v-for="o in sortedOrgs" :key="o.uuid">
           <td>
-            <a href="#org/{{o.uuid}}" @click.prevent="$emit('openOrg', o)">{{ o.display_name }}</a>
+            <a href="#org/{{o.uuid}}" @click.prevent="$emit('openOrg', o)">{{ o.org.display_name }}</a>
-            <button v-if="info.is_global_admin || info.is_org_admin" @click="$emit('updateOrg', o)" class="icon-btn edit-org-btn" aria-label="Rename organization" title="Rename organization">✏️</button>
+            <button v-if="isMasterAdmin || isOrgAdmin" @click="$emit('updateOrg', o)" class="icon-btn edit-org-btn" aria-label="Rename organization" title="Rename organization">✏️</button>
           </td>
           <td class="role-names">{{ getRoleNames(o) }}</td>
-          <td class="center">{{ o.roles.reduce((acc,r)=>acc + r.users.length,0) }}</td>
+          <td class="center">{{ orgUserCount(o) }}</td>
-          <td v-if="info.is_global_admin" class="center">
+          <td v-if="isMasterAdmin" class="center">
             <button @click="$emit('deleteOrg', o)" class="icon-btn delete-icon" aria-label="Delete organization" title="Delete organization">❌</button>
           </td>
         </tr>
@@ -274,7 +308,7 @@ defineExpose({ focusFirstElement })
     </table>
   </div>
 
-  <div v-if="info.is_global_admin" class="permissions-section">
+  <div v-if="isMasterAdmin" class="permissions-section">
     <h2>Permissions</h2>
     <div class="matrix-wrapper" ref="permMatrixRef" @keydown="handleMatrixKeydown">
       <div class="matrix-scroll">
@@ -287,24 +321,24 @@ defineExpose({ focusFirstElement })
             v-for="o in sortedOrgs"
             :key="'head-' + o.uuid"
             class="grid-head org-head"
-            :title="o.display_name"
+            :title="o.org.display_name"
           >
-            <span>{{ o.display_name }}</span>
+            <span>{{ o.org.display_name }}</span>
           </div>
 
-          <template v-for="p in sortedPermissions" :key="p.id">
+          <template v-for="p in sortedPermissions" :key="p.uuid">
-            <div class="perm-name" :title="p.id">
+            <div class="perm-name" :title="p.scope">
               <span class="display-text">{{ p.display_name }}</span>
             </div>
             <div
               v-for="o in sortedOrgs"
-              :key="o.uuid + '-' + p.id"
+              :key="o.uuid + '-' + p.uuid"
               class="matrix-cell"
             >
               <input
                 type="checkbox"
-                :checked="o.permissions.includes(p.id)"
+                :checked="p.uuid in o.permissions"
-                @change="e => $emit('toggleOrgPermission', o, p.id, e.target.checked)"
+                @change="e => $emit('toggleOrgPermission', o, p.uuid, e.target.checked)"
               />
             </div>
           </template>
@@ -313,28 +347,30 @@ defineExpose({ focusFirstElement })
       <p class="matrix-hint muted">Toggle which permissions each organization can grant to its members.</p>
     </div>
     <div class="actions" ref="permActionsRef" @keydown="handlePermActionsKeydown">
-      <button v-if="info.is_global_admin" @click="$emit('openDialog', 'perm-create', { display_name: '', id: '' })">+ Create Permission</button>
+      <button v-if="isMasterAdmin" @click="$emit('openDialog', 'perm-create', { display_name: '', scope: '', domain: '' })">+ Create Permission</button>
     </div>
     <table class="org-table" ref="permTableRef" @keydown="e => handleTableKeydown(e, 'perm')">
         <thead>
           <tr>
             <th scope="col">Permission</th>
+            <th scope="col">Domain</th>
             <th scope="col" class="center">Members</th>
             <th scope="col" class="center">Actions</th>
           </tr>
         </thead>
         <tbody>
-          <tr v-for="p in sortedPermissions" :key="p.id">
+          <tr v-for="p in sortedPermissions" :key="p.uuid">
             <td class="perm-name-cell">
               <div class="perm-title">
                 <span class="display-text">{{ p.display_name }}</span>
-                <button @click="$emit('renamePermissionDisplay', p)" class="icon-btn edit-display-btn" aria-label="Edit display name" title="Edit display name">✏️</button>
+                <button @click="$emit('renamePermissionDisplay', p)" class="icon-btn edit-display-btn" aria-label="Edit permission" title="Edit permission">✏️</button>
               </div>
               <div class="perm-id-info">
-                <span class="id-text">{{ p.id }}</span>
+                <span class="id-text">{{ p.scope }}</span>
               </div>
             </td>
-            <td class="perm-members center">{{ permissionSummary[p.id]?.userCount || 0 }}</td>
+            <td class="perm-domain">{{ domainDisplay(p.domain) }}</td>
+            <td class="perm-members center">{{ permissionSummary[p.uuid]?.userCount || 0 }}</td>
             <td class="perm-actions center">
               <button @click="$emit('deletePermission', p)" class="icon-btn delete-icon" aria-label="Delete permission" title="Delete permission">❌</button>
             </td>
@@ -342,38 +378,88 @@ defineExpose({ focusFirstElement })
         </tbody>
       </table>
   </div>
+
+  <div v-if="isMasterAdmin" class="oidc-clients-section">
+    <div class="section-header">
+      <h2>OAuth2 / OpenID Connect</h2>
+      <p class="section-description">
+        Allow external websites and applications to securely authenticate users through this system.
+        The clients are remote sites or applications that we allow to use Paskia for Single Sign-On.
+      </p>
+    </div>
+    <div ref="oidcActionsRef">
+      <button @click="$emit('createOidcClient')">+ Add Site</button>
+    </div>
+    <table class="org-table" ref="oidcTableRef">
+      <thead>
+        <tr>
+          <th scope="col">Client</th>
+          <th scope="col">Groups</th>
+          <th scope="col" class="center">Sessions</th>
+          <th scope="col" class="center">Actions</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr v-if="!oidcClients || oidcClients.length === 0">
+          <td colspan="4" class="center muted">No OIDC clients configured</td>
+        </tr>
+        <tr v-for="client in oidcClients" :key="client.uuid">
+          <td class="perm-name-cell">
+            <div class="perm-title">
+              <a :href="'#oidc:' + client.uuid" @click.prevent="$emit('openOidcClient', client)">{{ client.name }}</a>
+            </div>
+            <div class="perm-id-info">
+              <span class="id-text">{{ client.uuid }}</span>
+            </div>
+          </td>
+          <td class="client-groups">
+            <span v-if="clientGroups[client.uuid]?.length">{{ clientGroups[client.uuid].map(g => g.scope).join(' ') }}</span>
+            <span v-else class="muted">—</span>
+          </td>
+          <td class="center">{{ client.active_sessions || 0 }}</td>
+          <td class="center">
+            <button @click="$emit('deleteOidcClient', client)" class="icon-btn delete-icon" aria-label="Delete OIDC client" title="Delete OIDC client">❌</button>
+          </td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+
+  <div v-if="isMasterAdmin" class="server-options-section">
+    <div class="section-header">
+      <h2>Server</h2>
+      <p class="section-description">
+        Configure core server settings such as the display name, authentication host, and allowed origins.
+      </p>
+    </div>
+    <button @click="$emit('openServerConfig')">⚙ Server Options</button>
+  </div>
 </template>
 
 <style scoped>
 .permissions-section { margin-bottom: var(--space-xl); }
 .permissions-section h2 { margin-bottom: var(--space-md); }
-.actions { display: flex; flex-wrap: wrap; gap: var(--space-sm); align-items: center; }
-.actions button { width: auto; }
 .org-table a { text-decoration: none; color: var(--color-link); }
 .org-table a:hover { text-decoration: underline; }
 .org-table .center { width: 6rem; min-width: 6rem; }
 .org-table .role-names { max-width: 200px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .perm-name-cell { display: flex; flex-direction: column; gap: 0.3rem; }
 .perm-title { font-weight: 600; color: var(--color-heading); }
-.perm-id-info { font-size: 0.8rem; color: var(--color-text-muted); }
+.perm-id-info { font-size: 0.8rem; color: var(--color-text-muted); display: flex; align-items: center; gap: 0.5rem; flex-wrap: wrap; }
-.icon-btn { background: none; border: none; color: var(--color-text-muted); padding: 0.2rem; border-radius: var(--radius-sm); cursor: pointer; transition: background 0.2s ease, color 0.2s ease; }
+.perm-domain { color: var(--color-text-muted); font-size: 0.9rem; }
-.icon-btn:hover { color: var(--color-heading); background: var(--color-surface-muted); }
-.delete-icon { color: var(--color-danger); }
-.delete-icon:hover { background: var(--color-danger-bg); color: var(--color-danger-text); }
-.matrix-wrapper { margin: var(--space-md) 0; padding: var(--space-lg); }
-.matrix-scroll { overflow-x: auto; }
-.matrix-hint { font-size: 0.8rem; color: var(--color-text-muted); }
-.perm-matrix-grid { display: inline-grid; gap: 0.25rem; align-items: stretch; }
-.perm-matrix-grid > * { padding: 0.35rem 0.45rem; font-size: 0.75rem; }
-.perm-matrix-grid .grid-head { color: var(--color-text-muted); text-transform: uppercase; font-weight: 600; letter-spacing: 0.05em; }
-.perm-matrix-grid .perm-head { display: flex; align-items: flex-end; justify-content: flex-start; padding: 0.35rem 0.45rem; font-size: 0.75rem; }
 .perm-matrix-grid .org-head { display: flex; align-items: flex-end; justify-content: center; }
 .perm-matrix-grid .org-head span { writing-mode: vertical-rl; transform: rotate(180deg); font-size: 0.65rem; }
-.perm-name { font-weight: 600; color: var(--color-heading); padding: 0.35rem 0.45rem; font-size: 0.75rem; }
 .display-text { margin-right: var(--space-xs); }
 .edit-display-btn { padding: 0.1rem 0.2rem; font-size: 0.8rem; }
 .edit-org-btn { padding: 0.1rem 0.2rem; font-size: 0.8rem; margin-left: var(--space-xs); }
 .perm-actions { text-align: center; }
-.center { text-align: center; }
+
-.muted { color: var(--color-text-muted); }
+/* OIDC Clients Section */
+.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); }
+
+/* Server Options Section */
+.server-options-section { margin-top: var(--space-2xl); }
+.server-options-section .section-header { display: flex; flex-direction: column; gap: 0.4rem; margin-bottom: var(--space-md); }
 </style>

frontend/src/admin/AdminUserDetail.vue

@@ -2,10 +2,11 @@
 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'
-import { apiJson } from '@/utils/api'
+import { apiJson } from 'paskia'
 import { getDirection, navigateButtonRow, focusPreferred, focusAtIndex } from '@/utils/keynav'
 
 const props = defineProps({
@@ -17,12 +18,19 @@ const props = defineProps({
   navigationDisabled: { type: Boolean, default: false }
 })
 
-const emit = defineEmits(['generateUserRegistrationLink', 'goOverview', 'openOrg', 'onUserNameSaved', 'closeRegModal', 'editUserName', 'refreshUserDetail', 'navigateOut'])
+const emit = defineEmits(['generateUserRegistrationLink', 'goOverview', 'openOrg', 'onUserNameSaved', '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(() =>
+  Object.entries(props.userDetail?.credentials || {}).map(([uuid, c]) => ({ ...c, credential: uuid }))
+)
 
 // Template refs for navigation
 const userInfoRef = ref(null)
@@ -43,9 +51,23 @@ 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/orgs/${props.selectedUser.org_uuid}/users/${props.selectedUser.uuid}/credentials/${credential.credential_uuid}`, { method: 'DELETE' })
+    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
     } else {
@@ -57,11 +79,11 @@ async function handleDelete(credential) {
 }
 
 async function handleTerminateSession(session) {
-  const sessionId = session?.id
+  const sessionKey = session?.key
-  if (!sessionId) return
+  if (!sessionKey) return
-  terminatingSessions.value = { ...terminatingSessions.value, [sessionId]: true }
+  terminatingSessions.value = { ...terminatingSessions.value, [sessionKey]: true }
   try {
-    const data = await apiJson(`/auth/api/admin/orgs/${props.selectedUser.org_uuid}/users/${props.selectedUser.uuid}/sessions/${sessionId}`, { method: 'DELETE' })
+    const data = await apiJson(`/auth/api/admin/users/${props.selectedUser.uuid}/sessions/${sessionKey}`, { method: 'DELETE' })
     if (data.status === 'ok') {
       if (data.current_session_terminated) {
         sessionStorage.clear()
@@ -78,11 +100,15 @@ async function handleTerminateSession(session) {
     authStore.showMessage(err.message || 'Failed to terminate session', 'error')
   } finally {
     const next = { ...terminatingSessions.value }
-    delete next[sessionId]
+    delete next[sessionKey]
     terminatingSessions.value = next
   }
 }
 
+async function handleDeleteUser() {
+  emit('deleteUser')
+}
+
 // Handle user info section keynav
 function handleUserInfoKeydown(event) {
   if (hasActiveModal.value || props.navigationDisabled) return
@@ -93,7 +119,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') {
@@ -115,7 +141,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()
@@ -165,10 +191,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>
@@ -176,31 +214,41 @@ defineExpose({ focusFirstElement })
     <div ref="userInfoRef" @keydown="handleUserInfoKeydown">
       <UserBasicInfo
         v-if="userDetail && !userDetail.error"
-        :name="userDetail.display_name || selectedUser.display_name"
+        :name="userDetail.user.display_name || selectedUser.display_name"
-        :visits="userDetail.visits"
+        :avatar-url="userDetail.user.avatar_url"
-        :created-at="userDetail.created_at"
+        :avatar-render-version="avatarRenderVersion"
-        :last-seen="userDetail.last_seen"
+        avatar-clickable
+        :visits="userDetail.user.visits"
+        :created-at="userDetail.user.created_at"
+        :last-seen="userDetail.user.last_seen"
+        :email="userDetail.user.email"
+        :telephone="userDetail.user.telephone"
         :loading="loading"
         :org-display-name="userDetail.org.display_name"
-        :role-name="userDetail.role"
+        :role-name="userDetail.role.display_name"
-        :update-endpoint="`/auth/api/admin/orgs/${selectedUser.org_uuid}/users/${selectedUser.uuid}/display-name`"
+        :update-endpoint="`/auth/api/admin/users/${selectedUser.uuid}/info`"
         @saved="$emit('onUserNameSaved')"
-        @edit-name="handleEditName"
+        @avatar-click="openPictureDialog"
-      />
+        @edit="handleEditName"
+      >
+        <div class="admin-actions">
+          <button
+            class="btn-primary"
+            @click="$emit('generateUserRegistrationLink', selectedUser)"
+            :disabled="loading"
+            title="Generate a one-time link for this user"
+          >{{ userDetail?.credentials && Object.keys(userDetail.credentials).length > 0 ? 'Recovery Link' : 'Registration Link' }}</button>
+          <button
+            class="btn-danger"
+            @click="handleDeleteUser"
+            :disabled="loading"
+            title="Delete this user"
+          >Delete User</button>
+        </div>
+      </UserBasicInfo>
     </div>
     <div v-if="userDetail?.error" class="error small">{{ userDetail.error }}</div>
     <template v-if="userDetail && !userDetail.error">
-      <div class="registration-actions" ref="regActionsRef" @keydown="handleRegActionsKeydown">
-        <button
-          class="btn-secondary reg-token-btn"
-          @click="$emit('generateUserRegistrationLink', selectedUser)"
-          :disabled="loading"
-        >Generate Registration Token</button>
-        <p class="matrix-hint muted">
-          Generate a one-time registration link so this user can register or add another passkey.
-          Copy the link from the dialog and send it to the user, or have the user scan the QR code on their device.
-        </p>
-      </div>
       <section class="section-block" data-section="registered-passkeys">
         <div class="section-header">
           <h2>Registered Passkeys</h2>
@@ -208,11 +256,11 @@ defineExpose({ focusFirstElement })
         <div class="section-body">
           <CredentialList
             ref="credentialListRef"
-            :credentials="userDetail.credentials"
+            :credentials="credentials"
             :aaguid-info="userDetail.aaguid_info"
             :allow-delete="true"
             :hovered-credential-uuid="hoveredCredentialUuid"
-            :hovered-session-credential-uuid="hoveredSession?.credential_uuid"
+            :hovered-session-credential-uuid="hoveredSession?.credential"
             :navigation-disabled="hasActiveModal"
             @delete="handleDelete"
             @credential-hover="hoveredCredentialUuid = $event"
@@ -222,7 +270,7 @@ defineExpose({ focusFirstElement })
       </section>
       <SessionList
         ref="sessionListRef"
-        :sessions="userDetail.sessions || []"
+        :sessions="userDetail.sessions || {}"
         :terminating-sessions="terminatingSessions"
         :hovered-credential-uuid="hoveredCredentialUuid"
         :navigation-disabled="hasActiveModal"
@@ -238,24 +286,25 @@ defineExpose({ focusFirstElement })
     </div>
     <RegistrationLinkModal
       v-if="showRegModal"
-      :endpoint="`/auth/api/admin/orgs/${selectedUser.org_uuid}/users/${selectedUser.uuid}/create-link`"
+      :endpoint="`/auth/api/admin/users/${selectedUser.uuid}/create-link`"
       :user-name="userDetail?.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>
 
 <style scoped>
 .user-detail { display: flex; flex-direction: column; gap: var(--space-lg); }
-.actions { display: flex; flex-wrap: wrap; gap: var(--space-sm); align-items: center; }
+.admin-actions { display: flex; gap: 0.5rem; }
 .ancillary-actions { margin-top: -0.5rem; }
-.reg-token-btn { align-self: flex-start; }
-.registration-actions { display: flex; flex-direction: column; gap: 0.5rem; }
-.icon-btn { background: none; border: none; color: var(--color-text-muted); padding: 0.2rem; border-radius: var(--radius-sm); cursor: pointer; transition: background 0.2s ease, color 0.2s ease; }
-.icon-btn:hover { color: var(--color-heading); background: var(--color-surface-muted); }
-.matrix-hint { font-size: 0.8rem; color: var(--color-text-muted); }
-.error { color: var(--color-danger-text); }
-.small { font-size: 0.9rem; }
-.muted { color: var(--color-text-muted); }
 </style>

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

@@ -1,69 +1,90 @@
 
+@property --hue {
+  syntax: '<angle>';
+  inherits: true;
+  initial-value: 0.72turn;
+}
+
 :root {
   --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: #ffffff;
+  --color-canvas: white;
-  --color-surface: #eff6ff;
+  --color-surface: #def;
-  --color-surface-subtle: #dbeafe;
+  --color-surface-subtle: #bcf;
-  --color-border: #2563eb;
+  --color-surface-hover: oklab(0.97 -0.01 -0.02);
-  --color-border-strong: #1e40af;
+  --color-dialog: oklab(0.96 -0.01 -0.03);
-  --color-heading: #1e3a8a;
+  --color-border: oklab(0.82 -0.02 -0.06);
-  --color-text: #1e293b;
+  --color-border-strong: oklab(0.55 -0.05 -0.14);
-  --color-text-muted: #475569;
+  --color-heading: oklab(0.22 -0.03 -0.09);
-  --color-link: #1d4ed8;
+  --color-text: oklab(0.2 -0.02 -0.05);
-  --color-link-hover: #1e40af;
+  --color-text-muted: oklab(0.42 -0.02 -0.06);
-  --color-accent: #2563eb;
+  --color-link: oklab(0.5 -0.06 -0.17);
-  --color-accent-strong: #1e40af;
+  --color-link-hover: oklab(0.45 -0.06 -0.19);
-  --color-accent-contrast: #ffffff;
+  --color-accent: oklab(0.55 -0.06 -0.19);
-  --color-success-text: #166534;
+  --color-accent-strong: #46f;
-  --color-success-bg: #dcfce7;
+  --color-accent-contrast: white;
-  --color-error-text: #b91c1c;
+  --color-secondary: oklab(0.55 -0.02 -0.05);
-  --color-error-bg: #fee2e2;
+  --color-secondary-strong: oklab(0.45 -0.02 -0.05);
-  --color-info-text: #1e40af;
+  --color-success-text: oklab(0.4 -0.12 0.09);
-  --color-info-bg: #dbeafe;
+  --color-success-bg: oklab(0.95 -0.02 0.02);
-  --color-danger: #dc2626;
+  --color-error-text: oklab(0.45 0.18 0.09);
-  --shadow-soft: 0 10px 30px rgba(30, 64, 175, 0.15);
+  --color-error-bg: oklab(0.95 0.03 0.01);
-  --radius-none: 0;
+  --color-info-text: oklab(0.45 -0.05 -0.14);
+  --color-info-bg: oklab(0.95 -0.01 -0.02);
+  --color-danger: oklab(0.55 0.20 0.09);
+  --color-primary: oklab(0.55 -0.06 -0.19);
+  --color-error: oklab(0.45 0.18 0.09);
+  --color-success: oklab(0.4 -0.12 0.09);
+  --color-bg: oklab(0.94 -0.01 -0.03);
+  --color-accent-soft: oklab(0.92 -0.03 -0.08);
+  --shadow-soft: 0 0 .2rem black;
+  --shadow-xl: 0 10px 40px rgba(0, 0, 0, 0.15);
   --radius-sm: 4px;
   --radius-md: 6px;
   --radius-lg: 10px;
-  --space-xxs: 0.25rem;
   --space-xs: 0.5rem;
   --space-sm: 0.75rem;
   --space-md: 1rem;
   --space-lg: 1.5rem;
   --space-xl: 2.25rem;
-  --space-xxl: 3.5rem;
+  --space-3xl: 5rem;
-  --layout-max-width: 1400px;
   --layout-padding: clamp(1.5rem, 3vw + 1rem, 3.25rem);
   --transition-base: 160ms ease;
   --focus-ring: 0 0 0 2px var(--color-accent);
 }
 
-@media (prefers-color-scheme: dark) {
+:root.dark {
-  :root {
+  --color-canvas: oklab(0.17 -0.02 -0.05);
-    --color-canvas: #0f172a;
+  --color-surface: oklab(0.22 -0.02 -0.05);
-    --color-surface: #141b2f;
+  --color-surface-subtle: oklab(0.25 -0.02 -0.05);
-    --color-surface-subtle: #1b243b;
+  --color-surface-hover: oklab(0.28 -0.02 -0.05);
-    --color-border: #25304a;
+  --color-dialog: oklab(0.22 -0.02 -0.05);
-    --color-border-strong: #3d4d6b;
+  --color-border: oklab(0.3 -0.02 -0.05);
-    --color-heading: #fff;
+  --color-border-strong: oklab(0.4 -0.02 -0.05);
-    --color-text: #e2e8f0;
+  --color-heading: white;
-    --color-text-muted: #94a3b8;
+  --color-text: oklab(0.9 0.00 -0.01);
-    --color-link: #60a5fa;
+  --color-text-muted: oklab(0.7 -0.01 -0.02);
-    --color-link-hover: #93c5fd;
+  --color-link: oklab(0.7 -0.05 -0.14);
-    --color-accent: #60a5fa;
+  --color-link-hover: oklab(0.8 -0.04 -0.11);
-    --color-accent-strong: #3b82f6;
+  --color-accent: oklab(0.7 -0.05 -0.14);
-    --color-accent-contrast: #0b1120;
+  --color-accent-strong: oklab(0.6 -0.06 -0.17);
-    --color-success-text: #34d399;
+  --color-accent-contrast: oklab(0.12 -0.01 -0.03);
-    --color-success-bg: #1a4d2e;
+  --color-secondary: oklab(0.6 -0.02 -0.05);
-    --color-error-text: #fca5a5;
+  --color-secondary-strong: oklab(0.5 -0.02 -0.05);
-    --color-error-bg: #4a1f1f;
+  --color-success-text: oklab(0.75 -0.12 0.09);
-    --color-info-text: #bae6fd;
+  --color-success-bg: oklab(0.3 -0.07 0.05);
-    --color-info-bg: #1e3a5f;
+  --color-error-text: oklab(0.8 0.11 0.05);
-    --color-danger: #f87171;
+  --color-error-bg: oklab(0.3 0.07 0.03);
-    --shadow-soft: 0 0 0 #000000;
+  --color-info-text: oklab(0.8 -0.03 -0.10);
-  }
+  --color-info-bg: oklab(0.3 -0.02 -0.05);
+  --color-danger: oklab(0.7 0.16 0.08);
+  --color-primary: oklab(0.7 -0.05 -0.14);
+  --color-error: oklab(0.8 0.11 0.05);
+  --color-success: oklab(0.75 -0.12 0.09);
+  --color-bg: oklab(0.18 -0.01 -0.03);
+  --color-accent-soft: oklab(0.25 -0.03 -0.08);
+  --shadow-soft: 0 0 0 black;
+  --shadow-xl: 0 10px 40px rgba(0, 0, 0, 0.4);
 }
 
 *,
@@ -79,7 +100,6 @@ html {
 }
 
 body {
-  color-scheme: light dark;
   overflow: auto;
   scrollbar-gutter: stable;
   height: 100%;
@@ -133,6 +153,7 @@ a:focus-visible {
 }
 
 .view-root {
+  position: relative;
   flex: 1;
   width: 100%;
   display: flex;
@@ -141,7 +162,6 @@ a:focus-visible {
   padding: var(--layout-padding);
   box-sizing: border-box;
   margin: 0 auto;
-  width: min(100%, var(--layout-max-width));
 }
 
 .view-root--wide {
@@ -152,6 +172,25 @@ a:focus-visible {
   max-width: 540px;
 }
 
+.view-root--profile .view-header-wrapper {
+  width: 100%;
+  max-width: calc(1200px - 2 * var(--layout-padding));
+  margin: 0 auto;
+  position: relative;
+}
+
+.view-root--profile .theme-toggle {
+  position: absolute;
+  top: 0;
+  right: 0;
+}
+
+.section-block--constrained {
+  width: 100%;
+  max-width: calc(1200px - 2 * var(--layout-padding));
+  margin: 0 auto;
+}
+
 .view-header {
   display: flex;
   flex-direction: column;
@@ -199,6 +238,7 @@ a:focus-visible {
   flex-wrap: nowrap;
   gap: 0.75rem;
   justify-content: flex-start;
+  width: 100%;
 }
 
 .button-row button {
@@ -231,6 +271,7 @@ button {
   gap: 0.4rem;
   background: var(--color-surface);
   color: var(--color-text);
+  transition: box-shadow var(--transition-base), background var(--transition-base), border-color var(--transition-base);
 }
 
 button:disabled {
@@ -238,49 +279,53 @@ button:disabled {
   filter: opacity(0.6);
 }
 
+output[title="Click to copy"] {
+  cursor: pointer;
+}
+
 .btn-primary {
-  background: var(--color-accent);
+  background: linear-gradient(to bottom, oklab(1 0 0 / 0.15), transparent 60%) var(--color-accent);
   color: var(--color-accent-contrast);
   border-color: var(--color-accent);
+}
+
+.btn-primary:hover:not(:disabled),
+.btn-primary:focus-visible {
+  background: linear-gradient(to bottom, oklab(1 0 0 / 0.15), transparent 60%) var(--color-accent-strong);
+  border-color: var(--color-accent-strong);
   box-shadow: var(--shadow-soft);
 }
 
-.btn-primary:hover:not(:disabled) {
-  background: var(--color-accent-strong);
-  border-color: var(--color-accent-strong);
-}
-
 .btn-secondary {
-  background: transparent;
+  background: linear-gradient(to bottom, oklab(1 0 0 / 0.15), transparent 60%) var(--color-secondary);
-  color: var(--color-text);
-  border-color: var(--color-border);
-}
-
-.btn-secondary:hover:not(:disabled) {
-  border-color: var(--color-border-strong);
-  background: var(--color-surface-subtle);
-}
-
-.btn-danger {
-  background: var(--color-danger);
   color: var(--color-accent-contrast);
   border-color: transparent;
 }
 
-.btn-danger:hover:not(:disabled) {
+.btn-secondary:hover:not(:disabled),
-  filter: brightness(0.92);
+.btn-secondary:focus-visible {
+  background: linear-gradient(to bottom, oklab(1 0 0 / 0.15), transparent 60%) var(--color-secondary-strong);
+  box-shadow: var(--shadow-soft);
 }
 
-/* Focus-visible outlines for buttons */
+.btn-danger {
-.btn-primary:focus-visible,
+  background: linear-gradient(to bottom, oklab(1 0 0 / 0.15), transparent 60%) var(--color-danger);
-.btn-secondary:focus-visible,
+  color: var(--color-accent-contrast);
+  border-color: transparent;
+}
+
+.btn-danger:hover:not(:disabled),
 .btn-danger:focus-visible {
-  outline: 1px solid var(-webkit-focus-ring-color);
+  background: linear-gradient(to bottom, oklab(1 0 0 / 0.15), transparent 60%) var(--color-danger);
+  filter: brightness(0.92);
+  box-shadow: var(--shadow-soft);
 }
 
+input:not([type]),
 input[type="text"],
 input[type="search"],
 input[type="email"],
+input[type="tel"],
 textarea,
 select {
   font: inherit;
@@ -293,6 +338,18 @@ select {
   transition: border-color var(--transition-base), box-shadow var(--transition-base);
 }
 
+input:not([type]):focus,
+input[type="text"]:focus,
+input[type="search"]:focus,
+input[type="email"]:focus,
+input[type="tel"]:focus,
+textarea:focus,
+select:focus {
+  outline: none;
+  border-color: var(--color-accent);
+  box-shadow: var(--focus-ring);
+}
+
 label {
   display: flex;
   flex-direction: column;
@@ -333,10 +390,118 @@ th {
   text-align: left;
 }
 
+/* Permission matrix styles */
+.matrix-wrapper {
+  margin: var(--space-md) 0;
+  padding: var(--space-lg);
+}
+
+.matrix-scroll {
+  overflow-x: auto;
+}
+
+.matrix-hint {
+  font-size: 0.8rem;
+  color: var(--color-text-muted);
+}
+
+.perm-matrix-grid {
+  display: inline-grid;
+  gap: 0.25rem;
+  align-items: stretch;
+}
+
+.perm-matrix-grid > * {
+  padding: 0.35rem 0.45rem;
+  font-size: 0.75rem;
+}
+
+.perm-matrix-grid .grid-head {
+  color: var(--color-text-muted);
+  text-transform: uppercase;
+  font-weight: 600;
+  letter-spacing: 0.05em;
+}
+
+.perm-matrix-grid .perm-head {
+  display: flex;
+  align-items: flex-end;
+  justify-content: flex-start;
+  padding: 0.35rem 0.45rem;
+  font-size: 0.75rem;
+}
+
+.perm-matrix-grid .rotated-head {
+  display: flex;
+  align-items: flex-end;
+  justify-content: center;
+}
+
+.perm-matrix-grid .rotated-head span {
+  writing-mode: vertical-rl;
+  transform: rotate(180deg);
+  font-size: 0.65rem;
+}
+
+.perm-name {
+  font-weight: 600;
+  color: var(--color-heading);
+  padding: 0.35rem 0.45rem;
+  font-size: 0.75rem;
+}
+
 .center {
   text-align: center;
 }
 
+/* Utility classes */
+.muted {
+  color: var(--color-text-muted);
+}
+
+.error {
+  color: var(--color-danger-text);
+}
+
+.small {
+  font-size: 0.9rem;
+}
+
+.icon-btn {
+  background: none;
+  border: none;
+  color: var(--color-text-muted);
+  padding: 0.2rem;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  transition: background 0.2s ease, color 0.2s ease;
+}
+
+.icon-btn:hover {
+  color: var(--color-heading);
+  background: var(--color-surface-subtle);
+}
+
+.delete-icon {
+  color: var(--color-danger);
+}
+
+.delete-icon:hover {
+  background: var(--color-error-bg);
+  color: var(--color-error-text);
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-sm);
+  align-items: center;
+}
+
+.button-row--center {
+  justify-content: center;
+}
+
 .badge {
   display: inline-flex;
   align-items: center;
@@ -355,13 +520,17 @@ th {
   left: 0;
   right: 0;
   margin: 0 auto;
-  z-index: 1200;
+  z-index: 2000;
   width: fit-content;
   min-width: min(520px, calc(100% - 2rem));
   max-width: calc(100% - 2rem);
   display: none;
 }
 
+.global-status.show {
+  display: block;
+}
+
 .global-status .status {
   display: flex;
   align-items: center;
@@ -409,7 +578,7 @@ th {
 
 .device-dialog,
 .modal {
-  background: var(--color-surface);
+  background: var(--color-dialog);
   border: 1px solid var(--color-border);
   border-radius: var(--radius-md);
   width: min(520px, 100%);
@@ -431,8 +600,7 @@ th {
 
 .qr-code {
   padding: 1rem;
-  background: #fff;
+  background: white;
-  box-shadow: var(--shadow-soft);
 }
 
 .link-container,
@@ -489,9 +657,18 @@ th {
 
 .record-item.is-current,
 .credential-item.current-session,
+.session-item.is-current {
+  border-color: var(--color-accent);
+  background-color: var(--color-surface-subtle);
+}
+
 .credential-item.is-hovered,
-.session-item.is-current,
+.session-item.is-hovered {
-.session-item.is-hovered { border-color: var(--color-accent); background-color: var(--color-surface-subtle); }
+  border-color: var(--color-accent);
+  background-color: var(--color-surface-subtle);
+  box-shadow: 0 10px 24px rgba(15, 23, 42, 0.12);
+  transform: translateY(-1px);
+}
 
 .credential-item.is-linked-session,
 .session-item.is-linked-credential { border-color: var(--color-accent); background-color: var(--color-surface-subtle); }
@@ -569,7 +746,7 @@ th {
 }
 
 .btn-card-delete { background: transparent; border: none; color: var(--color-danger); padding: 0.35rem 0.5rem; font-size: 1.05rem; line-height: 1; border-radius: var(--radius-sm); cursor: pointer; display: inline-flex; align-items: center; justify-content: center; }
-.btn-card-delete:hover:not(:disabled) { background: #fee; }
+.btn-card-delete:hover:not(:disabled) { filter: brightness(0.85); }
 .btn-card-delete:disabled { filter: opacity(0.4); cursor: not-allowed; }
 
 
@@ -646,9 +823,6 @@ th {
 
 .user-info {
   display: grid;
-  border-radius: var(--radius-md);
-  background: var(--color-surface);
-  padding: 1.1rem 1.25rem;
 }
 
 .user-details {
@@ -694,8 +868,8 @@ th {
   width: 100vw;
   height: 100vh;
   background: transparent;
-  backdrop-filter: blur(.1rem) brightness(0.7);
+  backdrop-filter: blur(.2rem) brightness(0.7);
-  -webkit-backdrop-filter: blur(.1rem) brightness(0.7);
+  -webkit-backdrop-filter: blur(.2rem) brightness(0.7);
   display: flex;
   align-items: center;
   justify-content: center;
@@ -713,7 +887,7 @@ th {
   width: 100%;
   max-width: 480px;
   padding: 2rem;
-  background: var(--color-surface);
+  background: var(--color-dialog);
   border-radius: var(--radius-lg);
   box-shadow: 0 20px 60px #1e293b;
   border: 1px solid var(--color-border);
@@ -733,45 +907,9 @@ th {
   }
 }
 
-/* Global backdrop controlled by api.js ref-counting */
-body::before {
-  content: '';
-  position: fixed;
-  inset: 0;
-  z-index: 1099;
-  background: transparent;
-  backdrop-filter: blur(0) brightness(1);
-  -webkit-backdrop-filter: blur(0) brightness(1);
-  pointer-events: none;
-  visibility: hidden;
-  transition: all 0.2s ease-out;
-}
-
-body.has-backdrop::before {
-  -webkit-backdrop-filter: blur(.2rem) brightness(0.5);
-  backdrop-filter: blur(.2rem) brightness(0.5);
-  visibility: visible;
-}
-
-body.has-backdrop {
-  overflow: auto;
-}
-
-#auth-iframe {
-  border: none;
-  position: fixed;
-  top: 0;
-  left: 0;
-  width: 100%;
-  height: 100%;
-  z-index: 9999;
-  color-scheme: auto;
-  background: transparent;
-}
-
 .slot-machine {
   padding: 0.875rem 1rem;
-  background: var(--color-surface-hover, rgba(0, 0, 0, 0.03));
+  background: var(--color-surface-hover);
   border: 1px solid var(--color-border);
   border-radius: var(--radius-sm);
   font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;
@@ -792,3 +930,28 @@ body.has-backdrop {
   height: 1.8em;
   position: relative;
 }
+
+/* Spinner utilities */
+.spinner {
+  border: 3px solid var(--color-border);
+  border-top-color: var(--color-primary);
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+}
+
+.spinner--sm {
+  width: 16px;
+  height: 16px;
+  border-width: 2px;
+}
+
+.spinner--md {
+  width: 40px;
+  height: 40px;
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}

frontend/src/components/AccessDenied.vue

@@ -1,10 +1,11 @@
 <template>
   <div class="message-container">
     <div class="message-content">
-      <h2>🔒 Access Denied</h2>
+      <h2>{{ icon }} {{ title }}</h2>
+      <p v-if="message" class="error-detail">{{ message }}</p>
       <div class="button-row">
         <button class="btn-secondary" @click="goBack">Back</button>
-        <button class="btn-primary" @click="$emit('reload')">Reload Page</button>
+        <button class="btn-primary" @click="reload">Reload Page</button>
       </div>
     </div>
   </div>
@@ -13,7 +14,15 @@
 <script setup>
 import { goBack } from '@/utils/helpers'
 
-defineEmits(['reload'])
+const props = defineProps({
+  title: { type: String, default: 'Access Denied' },
+  icon: { type: String, default: '🔒' },
+  message: { type: String, default: null },
+})
+
+function reload() {
+  window.location.reload()
+}
 </script>
 
 <style scoped>
@@ -32,10 +41,15 @@ defineEmits(['reload'])
 }
 
 .message-content h2 {
-  margin: 0 0 1.5rem;
+  margin: 0 0 1rem;
   color: var(--color-heading);
 }
 
+.message-content .error-detail {
+  margin: 0 0 1.5rem;
+  color: var(--color-text-muted);
+}
+
 .message-content .button-row {
   display: flex;
   gap: 0.75rem;

frontend/src/components/CredentialList.vue

@@ -5,16 +5,16 @@
     <template v-else>
       <div
         v-for="credential in credentials"
-        :key="credential.credential_uuid"
+        :key="credential.credential"
         :class="['credential-item', {
           'current-session': credential.is_current_session && !hoveredCredentialUuid && !hoveredSessionCredentialUuid,
-          'is-hovered': hoveredCredentialUuid === credential.credential_uuid,
+          'is-hovered': hoveredCredentialUuid === credential.credential,
-          'is-linked-session': hoveredSessionCredentialUuid === credential.credential_uuid
+          'is-linked-session': hoveredSessionCredentialUuid === credential.credential
         }]"
         tabindex="-1"
         @mousedown.prevent
         @click.capture="handleCardClick"
-        @focusin="handleCredentialFocus(credential.credential_uuid)"
+        @focusin="handleCredentialFocus(credential.credential)"
         @focusout="handleCredentialBlur($event)"
         @keydown="handleItemKeydown($event, credential)"
       >
@@ -33,8 +33,8 @@
           <h4 class="item-title">{{ getCredentialAuthName(credential) }}</h4>
           <div class="item-actions">
             <span v-if="credential.is_current_session && !hoveredCredentialUuid && !hoveredSessionCredentialUuid" class="badge badge-current">Current</span>
-            <span v-else-if="hoveredCredentialUuid === credential.credential_uuid" class="badge badge-current">Selected</span>
+            <span v-else-if="hoveredCredentialUuid === credential.credential" class="badge badge-current">Selected</span>
-            <span v-else-if="hoveredSessionCredentialUuid === credential.credential_uuid" class="badge badge-current">Linked</span>
+            <span v-else-if="hoveredSessionCredentialUuid === credential.credential" class="badge badge-current">Linked</span>
             <button
               v-if="allowDelete"
               @click="$emit('delete', credential)"
@@ -148,8 +148,8 @@ const getCredentialAuthIcon = (credential) => {
   const info = props.aaguidInfo?.[credential.aaguid]
   if (!info) return null
   const isDarkMode = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches
-  const iconKey = isDarkMode ? 'icon_dark' : 'icon_light'
+  // Fall back to icon if icon_dark is not available
-  return info[iconKey] || null
+  return (isDarkMode && info.icon_dark) || info.icon || null
 }
 </script>
 

frontend/src/components/HostProfileView.vue

@@ -1,5 +1,5 @@
 <template>
-  <section class="view-root host-view" data-view="host-profile">
+  <section class="view-root view-root--wide host-view" data-view="host-profile">
     <header class="view-header">
       <h1>{{ headingTitle }}</h1>
       <p class="view-lede">{{ subheading }}</p>
@@ -8,11 +8,14 @@
     <section class="section-block" ref="userInfoSection">
       <div class="section-body">
         <UserBasicInfo
-          v-if="user"
+          v-if="ctx"
-          :name="user.user_name"
+          :name="ctx.user.display_name"
-          :visits="user.visits || 0"
+          :avatar-url="authStore.userInfo.user.avatar_url"
-          :created-at="user.created_at"
+          :visits="authStore.userInfo.user.visits"
-          :last-seen="user.last_seen"
+          :created-at="authStore.userInfo.user.created_at"
+          :last-seen="authStore.userInfo.user.last_seen"
+          :email="ctx.user.email"
+          :telephone="ctx.user.telephone"
           :org-display-name="orgDisplayName"
           :role-name="roleDisplayName"
           :can-edit="false"
@@ -78,9 +81,9 @@ const currentHost = window.location.host
 const userInfoSection = ref(null)
 const buttonRow = ref(null)
 
-const user = computed(() => authStore.userInfo?.user || null)
+const ctx = computed(() => authStore.userInfo || null)
-const orgDisplayName = computed(() => authStore.userInfo?.org?.display_name || '')
+const orgDisplayName = computed(() => ctx.value?.org?.display_name ?? '')
-const roleDisplayName = computed(() => authStore.userInfo?.role?.display_name || '')
+const roleDisplayName = computed(() => ctx.value?.role?.display_name ?? '')
 
 const headingTitle = computed(() => {
   const service = authStore.settings?.rp_name
@@ -125,12 +128,3 @@ const handleButtonRowKeydown = (event) => {
   // Down does nothing (no elements below to navigate to)
 }
 </script>
-
-<style scoped>
-.host-view { padding: 3rem 1.5rem 4rem; }
-.host-actions { display: flex; flex-direction: column; gap: 0.75rem; }
-.host-actions .button-row { gap: 0.75rem; flex-wrap: wrap; }
-.host-actions .button-row button { flex: 1 1 0; }
-.note { margin: 0; color: var(--color-text-muted); }
-.empty-state { margin: 0; color: var(--color-text-muted); }
-</style>

frontend/src/components/LoadingView.vue

@@ -27,17 +27,12 @@ defineProps({
 .loading-spinner {
   width: 40px;
   height: 40px;
-  border: 4px solid var(--color-border);
+  border: 3px solid var(--color-border);
-  border-top: 4px solid var(--color-primary);
+  border-top-color: var(--color-primary);
   border-radius: 50%;
   animation: spin 1s linear infinite;
 }
 
-@keyframes spin {
-  0% { transform: rotate(0deg); }
-  100% { transform: rotate(360deg); }
-}
-
 .loading-container p {
   color: var(--color-text-muted);
   margin: 0;

frontend/src/components/Modal.vue

@@ -1,12 +1,15 @@
 <template>
-  <dialog ref="dialog" @close="$emit('close')" @keydown="handleDialogKeydown">
+  <div class="dialog-overlay" @click="$emit('close')">
-    <slot />
+    <div ref="dialog" :class="['modal-panel', panelClass]" @keydown="handleDialogKeydown" @click.stop>
-  </dialog>
+      <slot />
+    </div>
+  </div>
 </template>
 
 <script setup>
 import { ref, onMounted, onUnmounted, nextTick } from 'vue'
 import { navigateButtonRow, getDirection, focusPreferred, focusDialogDefault } from '@/utils/keynav'
+import { holdGlobalBackdrop, releaseGlobalBackdrop } from 'paskia'
 
 const props = defineProps({
   // Optional: provide a fallback element to focus if original element is gone
@@ -14,10 +17,12 @@ 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: '' }
 })
 
-defineEmits(['close'])
+const emit = defineEmits(['close'])
 
 // Dialog element reference
 const dialog = ref(null)
@@ -76,6 +81,13 @@ const restoreFocus = () => {
 }
 
 const handleDialogKeydown = (event) => {
+  // ESC to close (previously handled by <dialog> natively)
+  if (event.key === 'Escape') {
+    event.preventDefault()
+    emit('close')
+    return
+  }
+
   const direction = getDirection(event)
   if (!direction) return
 
@@ -111,11 +123,11 @@ onMounted(() => {
   // Save currently focused element before modal takes focus
   previouslyFocusedElement.value = document.activeElement
 
-  // Show the dialog as a modal
+  holdGlobalBackdrop()
+
+  // Focus the most appropriate element
   nextTick(() => {
     if (dialog.value) {
-      dialog.value.showModal()
-
       // Autofocus the most appropriate element:
       // - For form dialogs (rename, edit): focus first input and select text
       // - For other dialogs: focus primary button (or fallback)
@@ -131,14 +143,16 @@ onMounted(() => {
 })
 
 onUnmounted(() => {
+  releaseGlobalBackdrop()
   // Restore focus when modal closes
   restoreFocus()
 })
 </script>
 
 <style scoped>
-dialog {
+.modal-panel {
-  background: var(--color-surface);
+  background: var(--color-dialog);
+  color: var(--color-text);
   border: 1px solid var(--color-border);
   border-radius: var(--radius-lg);
   box-shadow: var(--shadow-xl);
@@ -147,65 +161,36 @@ dialog {
   width: min(500px, 90vw);
   max-height: 90vh;
   overflow-y: auto;
-  position: fixed;
-  inset: 0;
-  margin: auto;
-  height: fit-content;
 }
 
-dialog::backdrop {
+.modal-panel :deep(.modal-title),
-  background: transparent;
+.modal-panel :deep(h3) {
-  backdrop-filter: blur(.1rem) brightness(0.7);
-  -webkit-backdrop-filter: blur(.1rem) brightness(0.7);
-}
-
-dialog :deep(.modal-title),
-dialog :deep(h3) {
   margin: 0 0 var(--space-md);
   font-size: 1.25rem;
   font-weight: 600;
   color: var(--color-heading);
 }
 
-dialog :deep(form) {
+.modal-panel :deep(form) {
   display: flex;
   flex-direction: column;
   gap: var(--space-md);
 }
 
-dialog :deep(.modal-form) {
+.modal-panel :deep(.modal-form) {
   display: flex;
   flex-direction: column;
   gap: var(--space-md);
 }
 
-dialog :deep(.modal-form label) {
+.modal-panel :deep(.modal-form label) {
   display: flex;
   flex-direction: column;
   gap: var(--space-xs);
   font-weight: 500;
 }
 
-dialog :deep(.modal-form input),
+.modal-panel :deep(.modal-actions) {
-dialog :deep(.modal-form textarea) {
-  padding: var(--space-md);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-sm);
-  background: var(--color-bg);
-  color: var(--color-text);
-  font-size: 1rem;
-  line-height: 1.4;
-  min-height: 2.5rem;
-}
-
-dialog :deep(.modal-form input:focus),
-dialog :deep(.modal-form textarea:focus) {
-  outline: none;
-  border-color: var(--color-accent);
-  box-shadow: 0 0 0 2px #c7d2fe;
-}
-
-dialog :deep(.modal-actions) {
   display: flex;
   justify-content: flex-end;
   gap: var(--space-sm);

frontend/src/components/NameEditForm.vue

@@ -84,12 +84,4 @@ function handleCancel() {
   flex-direction: column;
   gap: var(--space-md);
 }
-
-.error {
-  color: var(--color-danger-text);
-}
-
-.small {
-  font-size: 0.9rem;
-}
 </style>

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

@@ -1,23 +1,36 @@
 <template>
-  <section class="view-root" data-view="profile">
+  <section class="view-root view-root--profile" data-view="profile">
-    <header class="view-header">
+    <div class="view-header-wrapper">
-      <h1>User Profile</h1>
+      <div class="theme-toggle">
-      <Breadcrumbs ref="breadcrumbs" :entries="breadcrumbEntries" @keydown="handleBreadcrumbKeydown" />
+        <ThemeSelector />
-      <p class="view-lede">Account dashboard for managing credentials and authenticating with other devices.</p>
+      </div>
-    </header>
+      <header class="view-header">
+        <Breadcrumbs ref="breadcrumbs" :entries="breadcrumbEntries" @keydown="handleBreadcrumbKeydown" />
+        <p class="view-lede">Account dashboard to manage your profile and authentications.</p>
+      </header>
+    </div>
 
-    <section class="section-block" ref="userInfoSection">
+    <section class="section-block section-block--constrained" ref="userInfoSection">
       <UserBasicInfo
         v-if="authStore.userInfo?.user"
         ref="userBasicInfo"
-        :name="authStore.userInfo.user.user_name"
+        :name="authStore.userInfo.user.display_name"
-        :visits="authStore.userInfo.user.visits || 0"
+        :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"
+        :visits="authStore.userInfo.user.visits"
         :created-at="authStore.userInfo.user.created_at"
         :last-seen="authStore.userInfo.user.last_seen"
         :loading="authStore.isLoading"
-        update-endpoint="/auth/api/user/display-name"
+        :org-display-name="authStore.userInfo.org.display_name"
+        :role-name="authStore.userInfo.role.display_name"
+        update-endpoint="/auth/api/user/info"
         @saved="authStore.loadUserInfo()"
-        @edit-name="openNameDialog"
+        @avatar-click="openAvatarDialog"
+        @edit="openEditDialog"
         @keydown="handleUserInfoKeydown"
       >
         <div class="remote-auth-inline">
@@ -31,11 +44,11 @@
             @device-info-visible="showDeviceInfo = $event"
           />
         </div>
-        <p class="remote-auth-description">Provided by another device requesting remote auth.</p>
+        <p class="remote-auth-description">Login from another device</p>
       </UserBasicInfo>
     </section>
 
-    <section class="section-block">
+    <section :class="['section-block', { 'section-block--constrained': !useWideLayout }]">
       <div class="section-header">
         <h2>Your Passkeys</h2>
         <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>
@@ -43,11 +56,11 @@
       <div class="section-body">
         <CredentialList
           ref="credentialList"
-          :credentials="authStore.userInfo?.credentials || []"
+          :credentials="credentials"
-          :aaguid-info="authStore.userInfo?.aaguid_info || {}"
+          :aaguid-info="authStore.userInfo.aaguid_info"
           :loading="authStore.isLoading"
           :hovered-credential-uuid="hoveredCredentialUuid"
-          :hovered-session-credential-uuid="hoveredSession?.credential_uuid"
+          :hovered-session-credential-uuid="hoveredSession?.credential"
           :navigation-disabled="hasActiveModal"
           allow-delete
           @delete="handleDelete"
@@ -67,25 +80,14 @@
       :terminating-sessions="terminatingSessions"
       :hovered-credential-uuid="hoveredCredentialUuid"
       :navigation-disabled="hasActiveModal"
+      :section-class="useWideLayout ? '' : 'section-block--constrained'"
       @terminate="terminateSession"
       @session-hover="hoveredSession = $event"
       @navigate-out="handleSessionNavigateOut"
       section-description="You are currently signed in to the following sessions. If you don't recognize something, consider deleting not only the session but the associated passkey you suspect is compromised, as only this terminates all linked sessions and prevents logging in again."
     />
 
-    <Modal v-if="showNameDialog" @close="showNameDialog = false">
+    <section :class="['section-block', { 'section-block--constrained': !useWideLayout }]">
-      <h3>Edit Display Name</h3>
-      <form @submit.prevent="saveName" class="modal-form">
-        <NameEditForm
-          label="Display Name"
-          v-model="newName"
-          :busy="saving"
-          @cancel="showNameDialog = false"
-        />
-      </form>
-    </Modal>
-
-    <section class="section-block">
       <div class="button-row" ref="logoutButtons">
         <button
           type="button"
@@ -101,9 +103,47 @@
           <button @click="logoutEverywhere" class="btn-danger" :disabled="authStore.isLoading" @keydown="handleLogoutButtonKeydown">All</button>
         </template>
       </div>
-      <p class="logout-note" v-if="!hasMultipleSessions"><strong>Logout</strong> from {{ currentSessionHost }}.</p>
+      <div class="logout-footer">
-      <p class="logout-note" v-else><strong>Logout</strong> this session on {{ currentSessionHost }}, or <strong>All</strong> sessions across all sites and devices for {{ rpName }}. You'll need to log in again with your passkey afterwards.</p>
+        <p class="logout-note" v-if="!hasMultipleSessions"><strong>Logout</strong> from {{ currentSessionHost }}.</p>
+        <p class="logout-note" v-else><strong>Logout</strong> this session on {{ currentSessionHost }}, or <strong>All</strong> sessions across all sites and devices for {{ rpName }}.</p>
+        <a class="paskia-version" href="https://git.zi.fi/leovasanko/paskia" target="_blank" rel="noopener noreferrer">Paskia {{ paskiaVersion }}</a>
+      </div>
     </section>
+
+    <Modal v-if="showEditDialog" @close="showEditDialog = false">
+      <h3>Edit Profile</h3>
+      <form @submit.prevent="saveProfile" class="modal-form">
+        <div class="profile-edit-form">
+          <label for="edit-display-name">Display Name
+            <input id="edit-display-name" type="text" v-model="editName" :disabled="saving" required />
+          </label>
+          <label for="edit-email">Email
+            <input id="edit-email" type="email" v-model="editEmail" :disabled="saving" />
+          </label>
+          <label for="edit-username">Preferred Username
+            <input id="edit-username" type="text" v-model="editUsername" :disabled="saving" placeholder="username" />
+          </label>
+          <label for="edit-telephone">Telephone
+            <input id="edit-telephone" type="tel" v-model="editTelephone" :disabled="saving" />
+          </label>
+          <div v-if="editError" class="error small">{{ editError }}</div>
+          <div class="modal-actions">
+            <button type="button" class="btn-secondary" @click="showEditDialog = false" :disabled="saving">Cancel</button>
+            <button type="submit" class="btn-primary" :disabled="saving" data-nav-primary>Save</button>
+          </div>
+        </div>
+      </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"
@@ -117,9 +157,10 @@
 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'
-import NameEditForm from '@/components/NameEditForm.vue'
 import SessionList from '@/components/SessionList.vue'
 import RegistrationLinkModal from '@/components/RegistrationLinkModal.vue'
 import RemoteAuthPermit from '@/components/RemoteAuthPermit.vue'
@@ -127,15 +168,21 @@ import { useAuthStore } from '@/stores/auth'
 import { adminUiPath, makeUiHref } from '@/utils/settings'
 import passkey from '@/utils/passkey'
 import { goBack } from '@/utils/helpers'
-import { apiJson } from '@/utils/api'
+import { apiJson } from 'paskia'
 import { navigateButtonRow, focusPreferred, focusAtIndex, getDirection } from '@/utils/keynav'
 
 const authStore = useAuthStore()
 const updateInterval = ref(null)
-const showNameDialog = ref(false)
+const showEditDialog = ref(false)
+const showAvatarDialog = ref(false)
 const showRegLink = ref(false)
-const newName = ref('')
+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)
 const hoveredSession = ref(null)
 const showDeviceInfo = ref(false)
@@ -145,19 +192,49 @@ 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(() => showNameDialog.value || showRegLink.value)
+const hasActiveModal = computed(() => showEditDialog.value || showAvatarDialog.value || showRegLink.value)
 
-watch(showNameDialog, (newVal) => { if (newVal) newName.value = authStore.userInfo?.user?.user_name || '' })
+watch(showEditDialog, (open) => {
+  if (!open) {
+    return
+  }
+  const user = authStore.userInfo.user
+  editName.value = user.display_name ?? ''
+  editEmail.value = user.email ?? ''
+  editUsername.value = user.preferred_username ?? ''
+  editTelephone.value = user.telephone ?? ''
+  editError.value = ''
+})
 
 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 {
@@ -206,7 +283,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
 }
@@ -218,7 +295,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 })
@@ -239,7 +316,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' })
   }
 }
 
@@ -292,7 +369,7 @@ const handleLogoutButtonKeydown = (event) => {
 }
 
 const handleDelete = async (credential) => {
-  const credentialId = credential?.credential_uuid
+  const credentialId = credential?.credential
   if (!credentialId) return
   try {
     await authStore.deleteCredential(credentialId)
@@ -301,56 +378,96 @@ const handleDelete = async (credential) => {
 }
 
 const rpName = computed(() => authStore.settings?.rp_name || 'this service')
-const sessions = computed(() => authStore.userInfo?.sessions || [])
+const paskiaVersion = computed(() => authStore.settings?.version || '')
+const sessions = computed(() => authStore.userInfo.sessions)
 const currentSessionHost = computed(() => {
-  const currentSession = sessions.value.find(session => session.is_current)
+  const currentSession = Object.values(sessions.value).find(session => session.is_current)
   return currentSession?.host || 'this host'
 })
 const terminatingSessions = ref({})
 
 const terminateSession = async (session) => {
-  const sessionId = session?.id
+  const sessionKey = session?.key
-  if (!sessionId) return
+  if (!sessionKey) return
-  terminatingSessions.value = { ...terminatingSessions.value, [sessionId]: true }
+  terminatingSessions.value = { ...terminatingSessions.value, [sessionKey]: true }
-  try { await authStore.terminateSession(sessionId) }
+  try { await authStore.terminateSession(sessionKey) }
   catch (error) { authStore.showMessage(error.message || 'Failed to terminate session', 'error', 5000) }
   finally {
     const next = { ...terminatingSessions.value }
-    delete next[sessionId]
+    delete next[sessionKey]
     terminatingSessions.value = next
   }
 }
 
 const logoutEverywhere = async () => { await authStore.logoutEverywhere() }
 const logout = async () => { await authStore.logout() }
-const openNameDialog = () => { newName.value = authStore.userInfo?.user?.user_name || ''; showNameDialog.value = true }
+const openEditDialog = () => { showEditDialog.value = true }
-const isAdmin = computed(() => !!(authStore.userInfo?.is_global_admin || authStore.userInfo?.is_org_admin))
+const isAdmin = computed(() => {
-const hasMultipleSessions = computed(() => sessions.value.length > 1)
+  const perms = Object.values(authStore.userInfo.permissions).map(p => p.scope)
-const breadcrumbEntries = computed(() => { const entries = [{ label: 'Auth', href: makeUiHref() }]; if (isAdmin.value) entries.push({ label: 'Admin', href: adminUiPath() }); return entries })
+  return perms.includes('auth:admin') || perms.includes('auth:org:admin')
+})
+const hasMultipleSessions = computed(() => Object.keys(sessions.value).length > 1)
+const credentials = computed(() =>
+  Object.entries(authStore.userInfo.credentials).map(([uuid, c]) => ({ ...c, credential: uuid }))
+)
+const useWideLayout = computed(() => {
+  // Check if any single site has more than 8 sessions
+  const groups = {}
+  for (const session of Object.values(sessions.value)) {
+    const host = session.host || ''
+    if (!groups[host]) groups[host] = []
+    groups[host].push(session)
+  }
+  const hasLargeSessionGroup = Object.values(groups).some(group => group.length > 8)
 
-const saveName = async () => {
+  // Check if passkeys exceed 8
-  const name = newName.value.trim()
+  const hasManyCredentials = credentials.value.length > 8
-  if (!name) { authStore.showMessage('Name cannot be empty', 'error'); return }
+
+  return hasLargeSessionGroup || hasManyCredentials
+})
+const breadcrumbEntries = computed(() => { const entries = [{ label: 'My Profile', href: makeUiHref() }]; if (isAdmin.value) entries.push({ label: 'Admin', href: adminUiPath() }); return entries })
+
+const saveProfile = async () => {
+  const name = editName.value.trim()
+  if (!name) { editError.value = 'Name cannot be empty'; return }
+  const user = authStore.userInfo.user
+  const emailVal = editEmail.value.trim() || null
+  const usernameVal = editUsername.value.trim() || null
+  const telephoneVal = editTelephone.value.trim() || null
   try {
+    editError.value = ''
     saving.value = true
-    await apiJson('/auth/api/user/display-name', { method: 'PUT', body: { display_name: name } })
+    let changed = false
-    showNameDialog.value = false
+    const body = {}
-    await authStore.loadUserInfo()
+    if (name !== user.display_name) body.display_name = name
-    authStore.showMessage('Name updated successfully!', 'success', 3000)
+    if (emailVal !== (user.email || null)) body.email = emailVal
-  } catch (e) { authStore.showMessage(e.message || 'Failed to update name', 'error') }
+    if (usernameVal !== (user.preferred_username || null)) body.preferred_username = usernameVal
-  finally { saving.value = false }
+    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)
+    }
+    showEditDialog.value = false
+  } catch (e) {
+    editError.value = e.message || 'Failed to update profile'
+  } finally { saving.value = false }
 }
 </script>
 
 <style scoped>
-.view-lede { margin: 0; color: var(--color-text-muted); font-size: 1rem; }
 .section-header { display: flex; flex-direction: column; gap: 0.4rem; }
 .empty-state { margin: 0; color: var(--color-text-muted); text-align: center; padding: 1rem 0; }
-.logout-note { margin: 0.75rem 0 0; color: var(--color-text-muted); font-size: 0.875rem; }
+.logout-note { margin: 0; color: var(--color-text-muted); }
+.logout-footer { display: flex; justify-content: space-between; align-items: baseline; gap: 1rem; margin-top: 0.75rem; }
+.paskia-version { color: var(--color-text-muted); text-decoration: none; white-space: nowrap; font-weight: 700; }
+.paskia-version:hover { color: var(--color-link-hover); }
 .remote-auth-inline { display: flex; flex-direction: column; gap: 0.5rem; }
 .remote-auth-label { display: block; margin: 0; font-size: 0.875rem; color: var(--color-text-muted); font-weight: 500; }
-.remote-auth-description {
+.remote-auth-description { font-size: 0.75rem; color: var(--color-text-muted); }
-  font-size: 0.75rem;
+.theme-toggle { position: absolute; top: var(--layout-padding); right: var(--layout-padding); }
-  color: var(--color-text-muted);
+.profile-edit-form { display: flex; flex-direction: column; gap: var(--space-md); }
-}
 </style>

frontend/src/components/RegistrationLinkModal.vue

@@ -1,16 +1,17 @@
 <template>
-  <dialog ref="dialog" @close="$emit('close')" @keydown="handleDialogKeydown">
+  <div v-if="linkUrl" class="dialog-overlay" @click="$emit('close')">
-    <div class="device-dialog" role="dialog" aria-modal="true" aria-labelledby="regTitle">
+    <div ref="dialog" class="modal-panel" @keydown="handleDialogKeydown" @click.stop>
+      <div class="device-dialog" role="dialog" aria-modal="true" aria-labelledby="regTitle">
       <div class="reg-header-row">
         <h2 id="regTitle" class="reg-title">
-          📱 <span v-if="userName">Registration for {{ userName }}</span><span v-else>Add Another Device</span>
+          📱 <span v-if="userName">{{ tokenType === 'account recovery' ? 'Recovery' : 'Registration' }} for {{ userName }}</span><span v-else>Add Another Device</span>
         </h2>
         <button class="icon-btn" @click="$emit('close')" aria-label="Close" tabindex="-1">✕</button>
       </div>
 
       <div class="device-link-section">
         <p class="reg-help">
-          Scan this QR code on the new device, or copy the link and open it there.
+          {{ helpText }}
         </p>
 
         <QRCodeDisplay
@@ -28,16 +29,18 @@
       <div class="reg-actions" ref="actionsRow" @keydown="handleActionsKeydown">
         <button class="btn-secondary" @click="$emit('close')">Close</button>
       </div>
+      </div>
     </div>
-  </dialog>
+  </div>
 </template>
 
 <script setup>
-import { ref, onMounted, onUnmounted, nextTick } from 'vue'
+import { ref, computed, onMounted, onUnmounted, nextTick } from 'vue'
 import QRCodeDisplay from '@/components/QRCodeDisplay.vue'
-import { apiJson } from '@/utils/api'
+import { apiJson, AuthCancelledError, holdGlobalBackdrop, releaseGlobalBackdrop } from 'paskia'
 import { formatDate } from '@/utils/helpers'
 import { getDirection } from '@/utils/keynav'
+import { useAuthStore } from '@/stores/auth'
 
 const props = defineProps({
   endpoint: { type: String, required: true },
@@ -46,34 +49,50 @@ const props = defineProps({
 
 const emit = defineEmits(['close', 'copied'])
 
+const authStore = useAuthStore()
 const dialog = ref(null)
 const linkUrl = ref(null)
 const expiresAt = ref(null)
+const tokenType = ref(null)
 const actionsRow = ref(null)
 // Store the element that had focus before modal opened
 const previouslyFocusedElement = ref(null)
 
+// Determine if this is an admin action for another user
+const isAdminAction = computed(() => !!props.userName)
+
+// Compute the help text based on token type and context
+const helpText = computed(() => {
+  if (!isAdminAction.value) {
+    // User adding their own device
+    return 'Scan this QR code on the new device, or copy the link and open it there.'
+  }
+  // Admin action for another user
+  return `Send this link to ${props.userName}, or have them scan the QR code.`
+})
+
 async function generateLink() {
   try {
     const data = await apiJson(props.endpoint, { method: 'POST' })
     if (data.url) {
       linkUrl.value = data.url
       expiresAt.value = data.expires ? new Date(data.expires) : null
+      tokenType.value = data.token_type || null
 
-      // Show the dialog as modal
+      holdGlobalBackdrop()
+
+      // Focus primary button (or first button if no primary) after content renders
       await nextTick()
-      if (dialog.value) {
+      const actions = actionsRow.value
-        dialog.value.showModal()
+      const target = actions?.querySelector('.btn-primary') || actions?.querySelector('button')
-
+      target?.focus()
-        // Focus primary button (or first button if no primary) after content renders
-        const actions = actionsRow.value
-        const target = actions?.querySelector('.btn-primary') || actions?.querySelector('button')
-        target?.focus()
-      }
     } else {
       emit('close')
     }
-  } catch {
+  } catch (e) {
+    if (!(e instanceof AuthCancelledError)) {
+      authStore.showMessage(e.message || 'Failed to generate link', 'error')
+    }
     emit('close')
   }
 }
@@ -83,7 +102,12 @@ function onCopied() {
 }
 
 const handleDialogKeydown = (event) => {
-  // ESC is handled automatically by <dialog>
+  // ESC to close
+  if (event.key === 'Escape') {
+    event.preventDefault()
+    emit('close')
+    return
+  }
   // Handle other key navigation
   const direction = getDirection(event)
   if (!direction) return
@@ -129,6 +153,7 @@ onMounted(() => {
 })
 
 onUnmounted(() => {
+  if (linkUrl.value) releaseGlobalBackdrop()
   // Restore focus when modal closes
   const prev = previouslyFocusedElement.value
   if (prev && document.body.contains(prev) && !prev.disabled) {
@@ -138,23 +163,6 @@ onUnmounted(() => {
 </script>
 
 <style scoped>
-dialog {
-  border: none;
-  background: transparent;
-  padding: 0;
-  max-width: none;
-  width: fit-content;
-  height: fit-content;
-  position: fixed;
-  inset: 0;
-  margin: auto;
-}
-
-dialog::backdrop {
-  -webkit-backdrop-filter: blur(.2rem) brightness(0.5);
-  backdrop-filter: blur(.2rem) brightness(0.5);
-}
-
 .icon-btn { background: none; border: none; cursor: pointer; font-size: 1rem; opacity: .6; }
 .icon-btn:hover { opacity: 1; }
 .reg-header-row { display: flex; justify-content: space-between; align-items: center; gap: .75rem; margin-bottom: .75rem; }

frontend/src/components/RemoteAuthPermit.vue

@@ -53,17 +53,16 @@
       <!-- 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 class="device-meta">{{ deviceInfo.user_agent_pretty }}</p>
+        <p class="device-meta">{{ deviceInfo.user_agent_pretty || '—' }}</p>
 
-        <p v-if="error" class="error-message" style="margin-top: 0.5rem;">{{ error }}</p>
+        <p v-if="error" class="error-message">{{ error }}</p>
 
-        <div class="button-row" style="margin-top: 0.75rem; display: flex; gap: 0.5rem;">
+        <div class="button-row device-actions">
           <button
             type="button"
             class="btn-secondary"
             :disabled="loading"
             @click="deny"
-            style="flex: 1;"
           >
             Deny
           </button>
@@ -72,7 +71,6 @@
             type="submit"
             :disabled="loading"
             class="btn-primary"
-            style="flex: 1;"
           >
             {{ loading ? 'Authenticating…' : 'Authorize' }}
           </button>
@@ -773,7 +771,6 @@ defineExpose({ reset, deny, code, handleInput, loading, error })
 .input-wrapper {
   position: relative;
   display: flex;
-  width: 280px;
   max-width: 100%;
 }
 
@@ -921,10 +918,6 @@ defineExpose({ reset, deny, code, handleInput, loading, error })
   animation: spin 0.8s linear infinite;
 }
 
-@keyframes spin {
-  to { transform: rotate(360deg); }
-}
-
 .device-info {
   display: flex;
   flex-direction: column;
@@ -945,9 +938,18 @@ defineExpose({ reset, deny, code, handleInput, loading, error })
 }
 
 .error-message {
-  margin: 0;
+  margin: 0.5rem 0 0;
   font-size: 0.875rem;
   color: var(--color-error, #ef4444);
-  margin-bottom: 1rem;
+}
+
+.device-actions {
+  margin-top: 0.75rem;
+  display: flex;
+  gap: 0.5rem;
+}
+
+.device-actions button {
+  flex: 1;
 }
 </style>

frontend/src/components/RemoteAuthRequest.vue

@@ -8,7 +8,7 @@
     <!-- Error state -->
     <div v-else-if="error" class="error-section">
       <p class="error-message">{{ error }}</p>
-      <button class="btn-primary" @click="retry" style="margin-top: 0.75rem;">Try Again</button>
+      <button class="btn-primary" @click="retry">Try Again</button>
     </div>
 
     <!-- Connecting phase -->
@@ -163,6 +163,9 @@ async function startRemoteAuth() {
 
     // PoW challenge
     const powChallenge = await ws.receive_json()
+    if (powChallenge.status) {
+      throw new Error(powChallenge.detail || `Failed to connect: ${powChallenge.status}`)
+    }
     if (powChallenge.pow) {
       const challenge = b64dec(powChallenge.pow.challenge)
       const nonces = await solvePoW(challenge, powChallenge.pow.work)
@@ -196,7 +199,7 @@ async function startRemoteAuth() {
       } else if (msg.status === 'authenticated') {
         // Success
         completed.value = true
-        emit('authenticated', { session_token: msg.session_token })
+        emit('authenticated', { exchange_code: msg.exchange_code })
         break
       } else if (msg.status === 'denied') {
         // Explicitly denied by the authenticating device
@@ -293,10 +296,6 @@ defineExpose({ retry, cancel })
   animation: spin 0.8s linear infinite;
 }
 
-@keyframes spin {
-  to { transform: rotate(360deg); }
-}
-
 .auth-display {
   display: flex;
   flex-direction: column;
@@ -499,6 +498,10 @@ defineExpose({ retry, cancel })
   color: var(--color-error, #ef4444);
 }
 
+.error-section button {
+  margin-top: 0.75rem;
+}
+
 /* Responsive adjustments */
 @media (max-width: 640px) {
   .auth-content {

frontend/src/components/RestrictedAuth.vue

@@ -1,6 +1,6 @@
 <template>
   <div class="app-shell">
-    <div v-if="status.show" class="global-status" style="display: block;">
+    <div v-if="status.show" class="global-status show">
       <div :class="['status', status.type]">
         {{ status.message }}
       </div>
@@ -18,7 +18,7 @@
           <div class="section-body center">
             <!-- Local passkey authentication view -->
             <div v-if="authView === 'local'" class="auth-view">
-              <div class="button-row center" ref="buttonRow">
+              <div class="button-row button-row--center" ref="buttonRow">
                 <slot name="actions"
                   :loading="loading"
                   :can-authenticate="canAuthenticate"
@@ -58,15 +58,20 @@
 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 '@/utils/api'
+import { fetchJson, getUserFriendlyErrorMessage, settings as paskiaSettings } from 'paskia'
 import RemoteAuthRequest from '@/components/RemoteAuthRequest.vue'
 import { focusDialogButton } from '@/utils/keynav'
+import { updateThemeFromSession } from '@/utils/theme'
 
 const props = defineProps({
   mode: {
     type: String,
     default: 'login',
-    validator: (value) => ['login', 'reauth', 'forbidden'].includes(value)
+    validator: (value) => ['login', 'reauth', 'forbidden', 'oidc'].includes(value)
+  },
+  oidcQueryString: {
+    type: String,
+    default: null
   }
 })
 
@@ -76,13 +81,13 @@ const status = reactive({ show: false, message: '', type: 'info' })
 const initializing = ref(true)
 const loading = ref(false)
 const settings = ref(null)
-const userInfo = ref(null)
+const session = ref(null)
 const currentView = ref('initial') // 'initial', 'login', 'forbidden'
 const authView = ref('local') // 'local' or 'remote'
 const buttonRow = ref(null)
 let statusTimer = null
 
-const isAuthenticated = computed(() => !!userInfo.value?.authenticated)
+const isAuthenticated = computed(() => !!session.value)
 
 const canAuthenticate = computed(() => {
   if (initializing.value) return false
@@ -115,7 +120,7 @@ const headerMessage = computed(() => {
   return 'Please sign in with your passkey.'
 })
 
-const userDisplayName = computed(() => userInfo.value?.user?.user_name || 'User')
+const userDisplayName = computed(() => session.value?.ctx.user.display_name || 'User')
 
 function showMessage(message, type = 'info', duration = 3000) {
   status.show = true
@@ -140,22 +145,22 @@ async function fetchSettings() {
   }
 }
 
-async function fetchUserInfo() {
+async function validateSession() {
   try {
-    userInfo.value = await fetchJson('/auth/api/user-info', { 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'
-      emit('forbidden', userInfo.value)
+      emit('forbidden', session.value)
     } else {
       currentView.value = 'login'
     }
   } catch (error) {
-    console.error('Failed to load user info', error)
+    session.value = null
+    currentView.value = 'login'
     if (error.status !== 401 && error.status !== 403) {
       showMessage(getUserFriendlyErrorMessage(error), 'error', 4000)
     }
-    userInfo.value = null
-    currentView.value = 'login'
   }
 }
 
@@ -164,7 +169,7 @@ async function authenticateUser() {
   loading.value = true
   showMessage('Starting authentication…', 'info')
   let result
-  try { result = await passkey.authenticate() } catch (error) {
+  try { result = await passkey.authenticate(props.oidcQueryString) } catch (error) {
     loading.value = false
     const message = error?.message || 'Passkey authentication cancelled'
     const cancelled = message === 'Passkey authentication cancelled'
@@ -172,7 +177,13 @@ async function authenticateUser() {
     emit('auth-error', { message, cancelled })
     return
   }
-  try { await setSessionCookie(result) } catch (error) {
+  // OIDC flow: no session cookie, just emit the redirect_url
+  if (result.redirect_url) {
+    loading.value = false
+    emit('authenticated', result)
+    return
+  }
+  try { await exchangeCode(result) } catch (error) {
     loading.value = false
     const message = error?.message || 'Failed to establish session'
     showMessage(message, 'error', 4000)
@@ -187,8 +198,8 @@ 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 })
-    userInfo.value = null
+    session.value = null
     currentView.value = 'login'
     showMessage('Logged out. You can sign in with a different account.', 'info', 3000)
   } catch (error) {
@@ -203,13 +214,13 @@ function openProfile() {
   if (profileWindow) profileWindow.focus()
 }
 
-async function setSessionCookie(result) {
+async function exchangeCode(result) {
-  if (!result?.session_token) {
+  if (!result?.exchange_code) {
-    console.error('setSessionCookie called with missing session_token:', result)
+    console.error('exchangeCode called with missing exchange_code:', result)
-    throw new Error('Authentication response missing session_token')
+    throw new Error('Authentication response missing exchange_code')
   }
   return await fetchJson('/auth/api/set-session', {
-    method: 'POST', headers: { Authorization: `Bearer ${result.session_token}` }
+    method: 'POST', headers: { 'Authorization': `Bearer ${result.exchange_code}` }, timeout: paskiaSettings.auth_ms
   })
 }
 
@@ -224,7 +235,7 @@ function switchToLocal() {
 async function handleRemoteAuthenticated(result) {
   showMessage('Authenticated from another device!', 'success', 2000)
   try {
-    await setSessionCookie(result)
+    await exchangeCode(result)
   } catch (error) {
     const message = error?.message || 'Failed to establish session'
     showMessage(message, 'error', 4000)
@@ -266,7 +277,12 @@ watch(initializing, (newVal) => {
 
 onMounted(async () => {
   await fetchSettings()
-  await fetchUserInfo()
+  // OIDC mode doesn't depend on session state - skip validation
+  if (props.mode !== 'oidc') {
+    await validateSession()
+  } else {
+    currentView.value = 'login'
+  }
   initializing.value = false
 
   // Add click handler for inline links
@@ -280,12 +296,11 @@ onUnmounted(() => {
 defineExpose({
   showMessage,
   isAuthenticated,
-  userInfo
+  session
 })
 </script>
 
 <style scoped>
-.button-row.center { display: flex; justify-content: center; gap: 0.75rem; flex-wrap: wrap; }
 .user-line { margin: 0.5rem 0 0; font-weight: 500; color: var(--color-text); }
 main.view-root { min-height: 100vh; align-items: center; justify-content: center; padding: 2rem 1rem; }
 .surface.surface--tight {

frontend/src/components/SessionList.vue

@@ -1,26 +1,27 @@
 <template>
-  <section class="section-block" data-component="session-list-section">
+  <section :class="['section-block', sectionClass]" data-component="session-list-section">
     <div class="section-header">
       <h2>Active Sessions</h2>
       <p class="section-description">{{ sectionDescription }}</p>
     </div>
     <div class="section-body">
       <div>
-        <template v-if="Array.isArray(sessions) && sessions.length">
+        <template v-if="sessionsArray.length">
-          <div v-for="(group, host) in groupedSessions" :key="host" class="session-group" tabindex="0" @keydown="handleGroupKeydown($event, host)">
+          <div v-for="(group, key) in groupedSessions" :key="key" class="session-group" tabindex="0" @keydown="handleGroupKeydown($event, key)">
             <span :class="['session-group-host', { 'is-current-site': group.isCurrentSite }]">
-              <span class="session-group-icon">🌐</span>
+              <span class="session-group-icon">{{ group.isOIDC ? '🪪' : '🌐' }}</span>
-              <a v-if="host" :href="hostUrl(host)" tabindex="-1" target="_blank" rel="noopener noreferrer">{{ host }}</a>
+              <template v-if="group.isOIDC">{{ group.displayName }}</template>
+              <a v-else-if="key" :href="hostUrl(key)" tabindex="-1" target="_blank" rel="noopener noreferrer">{{ key }}</a>
               <template v-else>Unbound host</template>
             </span>
             <div class="session-list">
               <div
                 v-for="session in group.sessions"
-                :key="session.id"
+                :key="session.key"
                 :class="['session-item', {
                   'is-current': session.is_current && !hoveredIp && !hoveredCredentialUuid,
-                  'is-hovered': hoveredSession?.id === session.id,
+                  'is-hovered': hoveredSession?.key === session.key,
-                  'is-linked-credential': hoveredCredentialUuid === session.credential_uuid
+                  'is-linked-credential': hoveredCredentialUuid === session.credential
                 }]"
                 tabindex="-1"
                 @mousedown.prevent
@@ -30,17 +31,17 @@
                 @keydown="handleItemKeydown($event, session)"
               >
                 <div class="item-top">
-                  <h4 class="item-title">{{ session.user_agent }}</h4>
+                  <h4 class="item-title">{{ session.user_agent || '—' }}</h4>
                   <div class="item-actions">
                     <span v-if="session.is_current && !hoveredIp && !hoveredCredentialUuid" class="badge badge-current">Current</span>
-                    <span v-else-if="hoveredSession?.id === session.id" class="badge badge-current">Selected</span>
+                    <span v-else-if="hoveredSession?.key === session.key" class="badge badge-current">Selected</span>
-                    <span v-else-if="hoveredCredentialUuid === session.credential_uuid" class="badge badge-current">Linked</span>
+                    <span v-else-if="hoveredCredentialUuid === session.credential" class="badge badge-current">Linked</span>
                     <span v-else-if="!hoveredCredentialUuid && isSameHost(session.ip)" class="badge">Same IP</span>
                     <button
                       @click="$emit('terminate', session)"
                       class="btn-card-delete"
-                      :disabled="isTerminating(session.id)"
+                      :disabled="isTerminating(session.key)"
-                      :title="isTerminating(session.id) ? 'Terminating...' : 'Terminate session'"
+                      :title="isTerminating(session.key) ? 'Terminating...' : 'Terminate session'"
                       tabindex="-1"
                     >❌</button>
                   </div>
@@ -69,12 +70,13 @@ import { hostIP } from '@/utils/helpers'
 import { navigateGrid, handleDeleteKey, handleEscape, getDirection } from '@/utils/keynav'
 
 const props = defineProps({
-  sessions: { type: Array, default: () => [] },
+  sessions: { type: Object, default: () => ({}) },
   emptyMessage: { type: String, default: 'You currently have no other active sessions.' },
   sectionDescription: { type: String, default: "Review where you're signed in and end any sessions you no longer recognize." },
   terminatingSessions: { type: Object, default: () => ({}) },
   hoveredCredentialUuid: { type: String, default: null },
   navigationDisabled: { type: Boolean, default: false },
+  sectionClass: { type: String, default: '' },
 })
 
 const emit = defineEmits(['terminate', 'sessionHover', 'navigate-out'])
@@ -106,7 +108,7 @@ const handleCardClick = (event) => {
   }
 }
 
-const isTerminating = (sessionId) => !!props.terminatingSessions[sessionId]
+const isTerminating = (sessionKey) => !!props.terminatingSessions[sessionKey]
 
 const handleGroupKeydown = (event, host) => {
   const group = event.currentTarget
@@ -149,7 +151,7 @@ const handleGroupKeydown = (event, host) => {
 const handleItemKeydown = (event, session) => {
   // Handle delete (always allowed even with modal)
   handleDeleteKey(event, () => {
-    if (!isTerminating(session.id)) emit('terminate', session)
+    if (!isTerminating(session.key)) emit('terminate', session)
   })
   if (event.defaultPrevented) return
 
@@ -208,9 +210,14 @@ const copyIp = async (ip) => {
 
 const displayIp = ip => hostIP(ip) ?? ip
 
+// Convert sessions dict to array with key attached
+const sessionsArray = computed(() =>
+  Object.entries(props.sessions || {}).map(([key, session]) => ({ ...session, key }))
+)
+
 const currentHostIP = computed(() => {
   if (hoveredIp.value) return hostIP(hoveredIp.value)
-  const current = props.sessions.find(s => s.is_current)
+  const current = sessionsArray.value.find(s => s.is_current)
   return current ? hostIP(current.ip) : null
 })
 
@@ -218,27 +225,20 @@ const isSameHost = ip => currentHostIP.value && hostIP(ip) === currentHostIP.val
 
 const groupedSessions = computed(() => {
   const groups = {}
-  for (const session of props.sessions) {
+  for (const session of sessionsArray.value) {
-    const host = session.host || ''
+    const groupKey = session.client || session.host || ''
-    if (!groups[host]) {
+    if (!groups[groupKey]) {
-      groups[host] = { sessions: [], isCurrentSite: false }
+      groups[groupKey] = { sessions: [], isCurrentSite: false, isOIDC: !!session.client, displayName: session.client_name || groupKey }
-    }
-    groups[host].sessions.push(session)
-    if (session.is_current_host) {
-      groups[host].isCurrentSite = true
     }
+    groups[groupKey].sessions.push(session)
+    if (session.is_current_host) groups[groupKey].isCurrentSite = true
   }
-  // Sort sessions within each group by last_renewed descending
+  for (const groupKey in groups) groups[groupKey].sessions.sort((a, b) => new Date(b.last_renewed) - new Date(a.last_renewed))
-  for (const host in groups) {
-    groups[host].sessions.sort((a, b) => new Date(b.last_renewed) - new Date(a.last_renewed))
-  }
-  // Sort groups by host name (natural sort)
   const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' })
-  const sortedHosts = Object.keys(groups).sort(collator.compare)
+  const sorted = Object.entries(groups).sort(([, a], [, b]) => {
-  const sortedGroups = {}
+    if (a.isOIDC !== b.isOIDC) return a.isOIDC ? 1 : -1
-  for (const host of sortedHosts) {
+    return collator.compare(a.displayName, b.displayName) || collator.compare(a.sessions[0]?.client || '', b.sessions[0]?.client || '')
-    sortedGroups[host] = groups[host]
+  })
-  }
+  return Object.fromEntries(sorted)
-  return sortedGroups
 })
 </script>

frontend/src/components/StatusMessage.vue

@@ -1,5 +1,5 @@
 <template>
-  <div v-if="authStore.status.show" class="global-status" style="display: block;">
+  <div v-if="authStore.status.show" class="global-status show">
     <div :class="['status', authStore.status.type]">
       {{ authStore.status.message }}
     </div>

frontend/src/components/ThemeSelector.vue

@@ -0,0 +1,48 @@
+<template>
+  <div class="theme-selector" @click.stop>
+    <button v-for="t in themes" :key="t.value" class="theme-icon" :class="{ hidden: isHidden(t.value) }"
+      :style="{ top: getPos(t.value).y + 'px', left: getPos(t.value).x + 'px' }" :title="t.title"
+      @click="handleClick(t.value)">{{ t.icon }}</button>
+  </div>
+</template>
+
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue'
+import { apiJson } from 'paskia'
+import { updateThemeFromSession, getCachedTheme } from '@/utils/theme'
+
+const open = ref(false), closing = ref(false), closingValue = ref(null), selected = ref(getCachedTheme())
+const themes = [{ value: '', icon: '🌓', title: 'Auto' }, { value: 'light', icon: '☀️', title: 'Light' }, { value: 'dark', icon: '🌙', title: 'Dark' }]
+const center = { x: 16, y: 16 }
+const expanded = { '': { x: 16, y: 0 }, light: { x: 0, y: 28 }, dark: { x: 32, y: 28 } }
+
+const getPos = v => closing.value ? (v === closingValue.value ? center : expanded[v]) : open.value ? expanded[v] : (v === selected.value ? center : expanded[v])
+const isHidden = v => closing.value ? v !== closingValue.value : !open.value && v !== selected.value
+
+function close(v) {
+  closingValue.value = v
+  closing.value = true
+  setTimeout(() => { open.value = closing.value = false; closingValue.value = null }, 200)
+}
+
+function handleClick(v) {
+  if (!open.value) { open.value = true; return }
+  close(v)
+  setTimeout(() => {
+    selected.value = v
+    updateThemeFromSession({ user: { theme: v } }, true)
+    apiJson('/auth/api/user/theme', { method: 'PATCH', body: { theme: v } }).catch(() => {})
+  }, 200)
+}
+
+function onOutside(e) { if (open.value && !closing.value && !e.target.closest('.theme-selector')) close(selected.value) }
+onMounted(() => document.addEventListener('click', onOutside))
+onUnmounted(() => document.removeEventListener('click', onOutside))
+</script>
+
+<style scoped>
+.theme-selector { position: relative; width: 2rem; height: 2rem; }
+.theme-icon { position: absolute; transform: translate(-50%, -50%); background: none; border: none; font-size: 1.25rem; cursor: pointer; padding: 0.25rem; transition: top 0.2s, left 0.2s, opacity 0.15s; }
+.theme-icon:hover, .theme-icon:focus-visible { transform: translate(-50%, -50%) scale(1.15); }
+.theme-icon.hidden { opacity: 0; pointer-events: none; }
+</style>

frontend/src/components/UserBasicInfo.vue

@@ -1,23 +1,49 @@
 <template>
   <div v-if="userLoaded" class="user-info" :class="{ 'has-extra': $slots.default }">
-    <h3 class="user-name-heading">
+    <div class="user-info-content">
-      <span class="icon">👤</span>
+      <ProfilePicture
-      <span class="user-name-row">
+        :src="avatarUrl"
-        <span class="display-name" :title="name">{{ name }}</span>
+        :render-version="avatarRenderVersion"
-        <button v-if="canEdit && updateEndpoint" class="mini-btn" @click="emit('editName')" title="Edit name">✏️</button>
+        :clickable="avatarClickable"
-      </span>
+        :loading="loading"
-    </h3>
+        :title="avatarClickable ? 'Change profile picture' : ''"
-    <div v-if="orgDisplayName || roleName" class="org-role-sub">
+        width="5.25rem"
-      <div class="org-line" v-if="orgDisplayName">{{ orgDisplayName }}</div>
+        height="5.25rem"
-      <div class="role-line" v-if="roleName">{{ roleName }}</div>
+        radius="var(--radius-sm)"
-    </div>
+        fallback-size="2.8em"
-    <div class="user-details">
+        class="user-picture"
-      <span class="date-label"><strong>Visits:</strong></span>
+        :class="avatarClickable ? 'user-picture-btn' : ''"
-      <span class="date-value">{{ visits || 0 }}</span>
+        @click="emit('avatar-click')"
-      <span class="date-label"><strong>Registered:</strong></span>
+      />
-      <span class="date-value">{{ formatDate(createdAt) }}</span>
+      <h3 class="user-name-heading">
-      <span class="date-label"><strong>Last seen:</strong></span>
+        <span class="user-name-row">
-      <span class="date-value">{{ formatDate(lastSeen) }}</span>
+          <span class="display-name" :title="name">{{ name }}</span>
+          <button v-if="canEdit && updateEndpoint" class="mini-btn" @click="emit('edit')" title="Edit profile">✏️</button>
+        </span>
+      </h3>
+      <div v-if="orgDisplayName || roleName" class="org-role-sub">
+        <div class="org-line" v-if="orgDisplayName">{{ orgDisplayName }}</div>
+        <div class="role-line" v-if="roleName">{{ roleName }}</div>
+      </div>
+      <div class="info-fields-block">
+        <div v-if="preferred_username" class="contact-item">🆔 {{ preferred_username }}</div>
+        <a v-if="email" :href="`mailto:${email}`" class="contact-link">✉️ {{ email }}</a>
+        <a v-if="telephone" :href="`tel:${telephone}`" class="contact-link">📞 {{ telephone }}</a>
+      </div>
+      <div class="info-line">
+        <span v-if="visits">
+          <span class="info-date">{{ formatDate(createdAt) }}</span>
+          <span class="info-punct"> – </span>
+          <span class="info-date">{{ formatDate(lastSeen) }}</span>
+          <span class="info-punct"> ×</span>
+          <span class="info-count">{{ visits }}</span>
+        </span>
+        <span v-else>
+          <span class="info-label">Created </span>
+          <span class="info-date">{{ formatDate(createdAt) }}</span>
+          <span class="info-punct"> — Never signed in</span>
+        </span>
+      </div>
     </div>
     <div v-if="$slots.default" class="user-info-extra">
       <slot></slot>
@@ -26,80 +52,85 @@
 </template>
 
 <script setup>
-import { ref, computed, watch } from 'vue'
+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 },
   visits: { type: [Number, String], default: 0 },
   createdAt: { type: [String, Number, Date], default: null },
   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', 'editName'])
+const emit = defineEmits(['saved', 'edit', 'avatar-click'])
-const authStore = useAuthStore()
-
 const userLoaded = computed(() => !!props.name)
 </script>
 
 <style scoped>
 .user-info.has-extra {
-  grid-template-columns: auto 1fr 2fr;
+  grid-template-columns: minmax(0, 1fr) 14rem;
   grid-template-areas:
-    "heading heading extra"
+    "content extra";
-    "org org extra"
+  gap: 1.5rem;
-    "label1 value1 extra"
-    "label2 value2 extra"
-    "label3 value3 extra";
 }
 
 .user-info:not(.has-extra) {
-  grid-template-columns: auto 1fr;
+  grid-template-columns: minmax(0, 1fr);
   grid-template-areas:
-    "heading heading"
+    "content";
-    "org org"
-    "label1 value1"
-    "label2 value2"
-    "label3 value3";
 }
 
 @media (max-width: 720px) {
   .user-info.has-extra {
-    grid-template-columns: auto 1fr;
+    grid-template-columns: 1fr;
     grid-template-areas:
-      "heading heading"
+      "content"
-      "org org"
+      "extra";
-      "label1 value1"
-      "label2 value2"
-      "label3 value3"
-      "extra extra";
   }
 }
 
-.user-name-heading { grid-area: heading; display: flex; align-items: center; flex-wrap: wrap; margin: 0 0 0.25rem 0; }
+.user-info-content {
-.org-role-sub { grid-area: org; display:flex; flex-direction:column; margin: -0.15rem 0 0.25rem; }
+  grid-area: content;
-.org-line { font-size: .7rem; font-weight:600; line-height:1.1; color: var(--color-text-muted); text-transform: uppercase; letter-spacing: 0.05em; }
+  display: grid;
-.role-line { font-size:.65rem; color: var(--color-text-muted); line-height:1.1; }
+  grid-template-columns: auto minmax(0, 1fr) minmax(0, 1fr);
-.info-label:nth-of-type(1) { grid-area: label1; }
+  grid-template-areas:
-.info-value:nth-of-type(2) { grid-area: value1; }
+    "picture heading fields"
-.info-label:nth-of-type(3) { grid-area: label2; }
+    "picture org fields"
-.info-value:nth-of-type(4) { grid-area: value2; }
+    "picture info info";
-.info-label:nth-of-type(5) { grid-area: label3; }
+  gap: 0 1rem;
-.info-value:nth-of-type(6) { grid-area: value3; }
+  min-width: 0;
-.user-info-extra { grid-area: extra; padding-left: 2rem; border-left: 1px solid var(--color-border); }
+}
-.user-name-row { display: inline-flex; align-items: center; gap: 0.35rem; max-width: 100%; }
+
-.user-name-row.editing { flex: 1 1 auto; }
+:deep(.user-picture) { grid-area: picture; align-self: stretch; }
-.display-name { font-weight: 600; font-size: 1.05em; line-height: 1.2; max-width: 14ch; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.user-name-heading { grid-area: heading; display: flex; align-items: center; flex-wrap: wrap; margin: 0 0 0.25rem 0; min-width: 0; }
-.name-input { width: auto; flex: 1 1 140px; min-width: 120px; padding: 6px 8px; font-size: 0.9em; border: 1px solid var(--color-border-strong); border-radius: 6px; background: var(--color-surface); color: var(--color-text); }
+.org-role-sub { grid-area: org; display: flex; flex-direction: column; min-width: 0; }
-.user-name-heading .name-input { width: auto; }
+.org-line { font-size: .7rem; font-weight: 600; line-height: 1.1; color: var(--color-text-muted); text-transform: uppercase; letter-spacing: 0.05em; }
-.name-input:focus { outline: none; border-color: var(--color-accent); box-shadow: var(--focus-ring); }
+.role-line { font-size: .65rem; color: var(--color-text-muted); line-height: 1.1; }
-.mini-btn { width: auto; padding: 4px 6px; margin: 0; font-size: 0.75em; line-height: 1; cursor: pointer; }
+.info-fields-block { grid-area: fields; display: flex; flex-direction: column; gap: 0.25rem; min-width: 0; }
+.contact-item { display: block; color: var(--color-text); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.contact-link { color: var(--color-text); text-decoration: none; display: block; transition: transform 0.1s ease; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.contact-link:hover { transform: scale(1.01); }
+.info-line { grid-area: info; line-height: 1.4; font-size: 0.9em; }
+.info-date { color: var(--color-text) !important; }
+.info-label { color: var(--color-text) !important; }
+.info-punct { color: var(--color-text-muted) !important; }
+.info-count { color: var(--color-text-muted) !important; }
+.user-info-extra { grid-area: extra; padding-left: 1rem; border-left: 1px solid var(--color-border); flex-shrink: 0; }
+.user-name-row { display: inline-flex; align-items: center; gap: 0.35rem; max-width: 100%; min-width: 0; }
+.display-name { font-weight: 600; font-size: 1.05em; line-height: 1.2; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; }
+.mini-btn { width: auto; padding: 4px 6px; margin: 0; font-size: 0.75em; line-height: 1; cursor: pointer; background: transparent; }
 .mini-btn:hover:not(:disabled) { background: var(--color-accent-soft); color: var(--color-accent); }
 .mini-btn:active:not(:disabled) { transform: translateY(1px); }
 .mini-btn:disabled { opacity: 0.5; cursor: not-allowed; }

frontend/src/stores/auth.js

@@ -1,12 +1,14 @@
 import { defineStore } from 'pinia'
 import { register, authenticate } from '@/utils/passkey'
 import { getSettings } from '@/utils/settings'
-import { apiJson } from '@/utils/api'
+import { apiJson, settings as paskiaSettings } from 'paskia'
+import { updateThemeFromSession } from '@/utils/theme'
 
 export const useAuthStore = defineStore('auth', {
   state: () => ({
     // Auth State
     userInfo: null, // Contains the full user info response: {user, credentials, aaguid_info}
+    ctx: null, // Session context from validate
     isLoading: false,
 
     // Settings
@@ -26,16 +28,18 @@ export const useAuthStore = defineStore('auth', {
     setLoading(flag) {
       this.isLoading = !!flag
     },
-    showMessage(message, type = 'info', duration = 3000) {
+    showMessage(message, type = 'info', duration = null) {
+      // Default duration: 5 seconds for errors, 3 seconds for others
+      const effectiveDuration = duration ?? (type === 'error' ? 5000 : 3000)
       this.status = {
         message,
         type,
         show: true
       }
-      if (duration > 0) {
+      if (effectiveDuration > 0) {
         setTimeout(() => {
           this.status.show = false
-        }, duration)
+        }, effectiveDuration)
       }
     },
     async setSessionCookie(result) {
@@ -46,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() {
@@ -83,7 +88,8 @@ export const useAuthStore = defineStore('auth', {
     },
     async loadUserInfo() {
       try {
-        this.userInfo = await apiJson('/auth/api/user-info', { method: 'POST' })
+        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) {
         // Suppress toast for 401/403 errors - the auth iframe will handle these
@@ -99,9 +105,9 @@ export const useAuthStore = defineStore('auth', {
       await apiJson(`/auth/api/user/credential/${uuid}`, { method: 'DELETE' })
       await this.loadUserInfo()
     },
-    async terminateSession(sessionId) {
+    async terminateSession(sessionKey) {
       try {
-        const payload = await apiJson(`/auth/api/user/session/${sessionId}`, { method: 'DELETE' })
+        const payload = await apiJson(`/auth/api/user/session/${sessionKey}`, { method: 'DELETE' })
         if (payload?.current_session_terminated) {
           sessionStorage.clear()
           location.reload()
@@ -116,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) {
@@ -129,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/api.js

@@ -1,406 +0,0 @@
-/**
- * API fetch wrapper that handles authentication errors with iframe-based re-authentication.
- *
- * When a 401 or 403 response is received with an `auth` object containing `iframe` URL,
- * this wrapper shows an authentication iframe and retries the original request after
- * successful authentication.
- */
-
-/** Default timeout for API requests in milliseconds */
-const DEFAULT_TIMEOUT_MS = 1000
-
-/**
- * Custom error class for API errors with full response context.
- */
-export class ApiError extends Error {
-  constructor(url, response, data) {
-    super(data?.detail || `Request failed: ${response.status}`)
-    this.name = 'ApiError'
-    this.url = url
-    this.status = response.status
-    this.statusText = response.statusText
-    this.data = data
-  }
-}
-
-/**
- * Custom error class for network/timeout errors.
- */
-export class NetworkError extends Error {
-  constructor(message, originalError = null) {
-    super(message)
-    this.name = 'NetworkError'
-    this.originalError = originalError
-  }
-}
-
-/**
- * Error thrown when user cancels authentication.
- */
-export class AuthCancelledError extends Error {
-  constructor() {
-    super('Authentication cancelled')
-    this.name = 'AuthCancelledError'
-  }
-}
-
-let authIframe = null
-let authPromise = null
-let authResolve = null
-let authReject = null
-
-// Global backdrop ref-count (works independently of Pinia store)
-let backdropHolders = 0
-
-/**
- * Hold global backdrop (increment ref-count).
- * Multiple callers can hold the backdrop; it only hides when all release.
- */
-export function holdGlobalBackdrop() {
-  backdropHolders++
-  document.body.classList.add('has-backdrop')
-}
-
-/**
- * Release global backdrop (decrement ref-count).
- * Backdrop hides only when ref-count reaches zero.
- */
-export function releaseGlobalBackdrop() {
-  backdropHolders = Math.max(0, backdropHolders - 1)
-  if (backdropHolders === 0) {
-    document.body.classList.remove('has-backdrop')
-  }
-}
-
-// Cache for auth iframe URL by mode
-const authIframeUrlCache = {}
-
-/**
- * Get the auth iframe URL for a given mode.
- * Fetches from /auth/api/forward which returns URL in the auth.iframe field.
- * Results are cached per mode.
- * @param {string} mode - The auth mode ('login', 'reauth', 'forbidden')
- * @returns {Promise<string>} - The URL for the iframe
- */
-export async function getAuthIframeUrl(mode = 'login') {
-  if (authIframeUrlCache[mode]) {
-    return authIframeUrlCache[mode]
-  }
-
-  // Fetch from forward endpoint - it returns URL in auth.iframe on 401/403
-  const response = await fetch('/auth/api/forward', { credentials: 'include' })
-  if (response.status === 401 || response.status === 403) {
-    const data = await response.json()
-    if (data.auth?.iframe) {
-      // The iframe field now contains a URL with hash fragment
-      // If mode differs, update the hash param
-      let url = data.auth.iframe
-      if (mode !== data.auth.mode) {
-        url = url.replace(/mode=[^&]*/, `mode=${mode}`)
-      }
-      authIframeUrlCache[mode] = url
-      return url
-    }
-  }
-  throw new Error('Unable to fetch auth iframe URL')
-}
-
-/**
- * Check if an auth iframe is already open (from any source).
- * @returns {boolean}
- */
-export function isAuthIframeOpen() {
-  return !!document.getElementById('auth-iframe')
-}
-
-/**
- * Show the authentication iframe and return a promise that resolves on success.
- * If an auth iframe is already open (from any source), hooks into its completion.
- * Uses global backdrop system to avoid flicker between auth and caller's UI.
- * @param {string} iframeUrl - The URL for the iframe src
- * @returns {Promise<void>}
- * @throws {AuthCancelledError} - If authentication is cancelled by user
- */
-export function showAuthIframe(iframeUrl) {
-  // If we already have a promise (from us), return it
-  if (authPromise) return authPromise
-
-  // If there's already an iframe in the DOM (from App.vue or elsewhere),
-  // create a promise that hooks into the message handler
-  if (document.getElementById('auth-iframe')) {
-    authPromise = new Promise((resolve, reject) => {
-      authResolve = resolve
-      authReject = reject
-    })
-    return authPromise
-  }
-
-  authPromise = new Promise((resolve, reject) => {
-    authResolve = resolve
-    authReject = reject
-  })
-
-  // Remove existing iframe if any
-  hideAuthIframe()
-
-  // Hold global backdrop for auth iframe
-  holdGlobalBackdrop()
-
-  // Create new iframe for authentication using src URL
-  authIframe = document.createElement('iframe')
-  authIframe.id = 'auth-iframe'
-  authIframe.title = 'Authentication'
-  authIframe.allow = 'publickey-credentials-get; publickey-credentials-create'
-  authIframe.src = iframeUrl
-  document.body.appendChild(authIframe)
-
-  return authPromise
-}
-
-function hideAuthIframe() {
-  if (authIframe) {
-    authIframe.remove()
-    authIframe = null
-    releaseGlobalBackdrop()
-  }
-}
-
-function handleAuthMessage(event) {
-  const data = event.data
-  if (!data?.type) return
-
-  switch (data.type) {
-    case 'auth-success':
-      hideAuthIframe()
-      if (authResolve) {
-        authResolve()
-        authPromise = null
-        authResolve = null
-        authReject = null
-      }
-      break
-
-    case 'auth-back':
-    case 'auth-close-request':
-      hideAuthIframe()
-      if (authReject) {
-        authReject(new AuthCancelledError())
-        authPromise = null
-        authResolve = null
-        authReject = null
-      }
-      break
-
-    case 'auth-error':
-      // Keep iframe open for retry, but if cancelled, treat as back
-      if (data.cancelled && authReject) {
-        hideAuthIframe()
-        authReject(new AuthCancelledError())
-        authPromise = null
-        authResolve = null
-        authReject = null
-      }
-      break
-  }
-}
-
-// Install global message listener
-if (typeof window !== 'undefined') {
-  window.addEventListener('message', handleAuthMessage)
-}
-
-/**
- * Fetch wrapper that handles auth errors with iframe-based re-authentication.
- * Loops until successful or user cancels authentication.
- *
- * @param {string|URL} url - The URL to fetch
- * @param {RequestInit} [options] - Fetch options
- * @param {number} [options.timeout] - Timeout in ms (default: 10000, use 0 to disable)
- * @returns {Promise<Response>} - The fetch response
- * @throws {AuthCancelledError} - If authentication is cancelled by user
- * @throws {NetworkError} - If network error or timeout occurs
- */
-export async function apiFetch(url, options = {}) {
-  const { timeout = DEFAULT_TIMEOUT_MS, ...fetchOptions } = options
-
-  // Ensure credentials are included for cookie-based auth
-  fetchOptions.credentials = fetchOptions.credentials || 'include'
-
-  while (true) {
-    let response
-    try {
-      response = await fetch(url, {...fetchOptions, signal: timeout && AbortSignal.timeout(timeout)})
-    } catch (error) {
-      // Handle network errors and timeouts
-      if (error.name === 'TimeoutError') {
-        throw new NetworkError('Request timed out', error)
-      }
-      if (error.name === 'AbortError') {
-        // Re-throw abort errors as-is (user-initiated cancellation)
-        throw error
-      }
-      if (error.name === 'TypeError' && error.message === 'Failed to fetch') {
-        throw new NetworkError('Unable to connect to server', error)
-      }
-      throw new NetworkError(error.message || 'Network error', error)
-    }
-
-    // Check for auth errors (401/403)
-    if (response.status === 401 || response.status === 403) {
-      // Try to parse the response to get the iframe URL
-      let authInfo = null
-      try {
-        const data = await response.clone().json()
-        authInfo = data.auth
-      } catch {
-        // If we can't parse JSON, no iframe available
-      }
-
-      // Authenticate via iframe (only in top-level window)
-      if (authInfo?.iframe && window === window.top) {
-        // Show auth iframe (or wait for existing one) and retry on success
-        // showAuthIframe returns existing promise if iframe is already open
-        await showAuthIframe(authInfo.iframe)
-        continue  // Retry the original request
-      }
-    }
-
-    return response
-  }
-}
-
-/**
- * Convenience method for JSON API calls.
- * Automatically sets Accept and Content-Type headers.
- * Returns parsed JSON directly if response is ok, throws ApiError otherwise.
- *
- * @param {string|URL} url - The URL to fetch
- * @param {RequestInit} [options] - Fetch options
- * @returns {Promise<any>} - Parsed JSON response
- * @throws {ApiError} - If response is not ok
- * @throws {NetworkError} - If network error or timeout occurs
- * @throws {AuthCancelledError} - If authentication is cancelled by user
- */
-export async function apiJson(url, options = {}) {
-  const fetchOptions = { ...options }
-
-  // Set default headers, allowing caller overrides
-  fetchOptions.headers = {
-    'Accept': 'application/json',
-    ...fetchOptions.headers,
-  }
-
-  // Set Content-Type for requests with JSON body
-  if (fetchOptions.body && typeof fetchOptions.body === 'object' && !(fetchOptions.body instanceof FormData)) {
-    fetchOptions.headers = {
-      'Content-Type': 'application/json',
-      ...fetchOptions.headers,
-    }
-    fetchOptions.body = JSON.stringify(fetchOptions.body)
-  }
-
-  const response = await apiFetch(url, fetchOptions)
-  const data = await response.json()
-
-  if (!response.ok) {
-    throw new ApiError(url, response, data)
-  }
-
-  return data
-}
-
-/**
- * Simple JSON fetch without auto-auth iframe handling.
- * Use this in contexts where showing an auth iframe would be inappropriate
- * (e.g., inside the auth iframe itself).
- *
- * @param {string|URL} url - The URL to fetch
- * @param {RequestInit} [options] - Fetch options
- * @returns {Promise<any>} - Parsed JSON response
- * @throws {ApiError} - If response is not ok
- */
-export async function fetchJson(url, options = {}) {
-  const fetchOptions = {
-    credentials: 'include',
-    ...options,
-    headers: {
-      'Accept': 'application/json',
-      ...options.headers,
-    },
-  }
-
-  const response = await fetch(url, fetchOptions)
-  const data = await response.json()
-
-  if (!response.ok) {
-    throw new ApiError(url, response, data)
-  }
-
-  return data
-}
-
-/**
- * Convert an error to a user-friendly message.
- * @param {Error} error - The error to convert
- * @returns {string} - User-friendly error message
- */
-export function getUserFriendlyErrorMessage(error) {
-  if (error instanceof NetworkError) {
-    return error.message
-  }
-  if (error instanceof ApiError) {
-    return error.message
-  }
-  if (error.name === 'TimeoutError') {
-    return 'Request timed out'
-  }
-  if (error.name === 'TypeError' && error.message === 'Failed to fetch') {
-    return 'Unable to connect to server'
-  }
-  return error.message || 'An error occurred'
-}
-
-/**
- * Check if an error should show a toast to the user.
- * @param {Error} error - The error to check
- * @returns {boolean} - Whether to show a toast
- */
-export function shouldShowErrorToast(error) {
-  // Don't show toast for user cancellations
-  if (error instanceof AuthCancelledError) return false
-  if (error.name === 'AbortError') return false
-  // Don't show toast for 401/403 errors - the auth iframe will handle these
-  if (error instanceof ApiError && (error.status === 401 || error.status === 403)) return false
-  return true
-}
-
-/**
- * Create an API caller with error handling (toast + console.error).
- * Wraps apiJson calls with consistent error handling for apps.
- *
- * @param {Function} showMessage - Function to show toast messages: (message, type, duration) => void
- * @returns {Function} - Wrapped apiJson that handles errors
- */
-export function createApiCaller(showMessage) {
-  /**
-   * @param {string|URL} url - The URL to fetch
-   * @param {RequestInit} [options] - Fetch options
-   * @returns {Promise<any>} - Parsed JSON response, or undefined on error
-   */
-  return async function apiCall(url, options = {}) {
-    try {
-      return await apiJson(url, options)
-    } catch (error) {
-      if (!shouldShowErrorToast(error)) {
-        throw error
-      }
-      // Log full error details
-      console.error(`API error for ${url}:`, error instanceof ApiError ? { status: error.status, statusText: error.statusText, data: error.data } : error)
-      // Show user-friendly toast
-      showMessage(getUserFriendlyErrorMessage(error), 'error', 4000)
-      throw error
-    }
-  }
-}
-
-export default apiFetch

frontend/src/utils/passkey.js

@@ -1,7 +1,7 @@
 import { startRegistration, startAuthentication } from '@simplewebauthn/browser'
 import aWebSocket from '@/utils/awaitable-websocket'
 import { getSettings } from '@/utils/settings'
-import { showAuthIframe } from '@/utils/api'
+import { showAuthIframe } from 'paskia'
 
 // Generic path normalizer: if an auth_host is configured and differs from current
 // host, return absolute URL (scheme derived by aWebSocket). Otherwise, keep as-is.
@@ -54,8 +54,13 @@ export async function register(resetToken = null, displayName = null, onstartreg
   }
 }
 
-export async function authenticate() {
+export async function authenticate(queryString = null) {
-  const ws = await aWebSocket(await makeUrl('/auth/ws/authenticate'))
+  // Build URL, optionally appending raw query string (e.g. for OIDC params)
+  let url = await makeUrl('/auth/ws/authenticate')
+  if (queryString) {
+    url += queryString.startsWith('?') ? queryString : `?${queryString}`
+  }
+  const ws = await aWebSocket(url)
   try {
     let res = await ws.receive_json()
     if (res.status >= 400) throw new Error(res.detail || `Authentication failed: ${res.status}`)

frontend/src/utils/theme.js

@@ -0,0 +1,46 @@
+// Theme override utilities - shared across apps
+// User preference or URL hash can force light/dark mode
+
+const TRANSITION_ID = 'theme-transition'
+const STORAGE_KEY = 'paskia-theme'
+
+/** Apply theme by setting class on documentElement */
+export function applyTheme(theme, element = document.documentElement, animate = false) {
+  // Add temporary transition for smooth theme change
+  if (animate) {
+    let transitionStyle = document.getElementById(TRANSITION_ID)
+    if (!transitionStyle) {
+      transitionStyle = document.createElement('style')
+      transitionStyle.id = TRANSITION_ID
+      transitionStyle.textContent = '*, *::before, *::after { transition: background-color 0.3s, color 0.3s, border-color 0.3s, box-shadow 0.3s !important; }'
+      document.head.appendChild(transitionStyle)
+    }
+    setTimeout(() => document.getElementById(TRANSITION_ID)?.remove(), 350)
+  }
+  // If no explicit theme, check system preference
+  const isDark = theme === 'dark' || (theme !== 'light' && matchMedia('(prefers-color-scheme:dark)').matches)
+  element.classList.toggle('dark', isDark)
+}
+
+/** Get theme from localStorage cache */
+export function getCachedTheme() {
+  return localStorage.getItem(STORAGE_KEY) || ''
+}
+
+/** Cache theme in localStorage */
+export function setCachedTheme(theme) {
+  if (theme) localStorage.setItem(STORAGE_KEY, theme)
+  else localStorage.removeItem(STORAGE_KEY)
+}
+
+/** Initialize theme from user preference (with localStorage cache for fast load) */
+export function initThemeFromCache() {
+  applyTheme(getCachedTheme())
+}
+
+/** Update theme from session context (call after login/session load) */
+export function updateThemeFromSession(ctx, animate = false) {
+  const theme = ctx?.user?.theme || ''
+  setCachedTheme(theme)
+  applyTheme(theme, document.documentElement, animate)
+}

frontend/vite-plugin-fastapi.js

@@ -0,0 +1,36 @@
+/**
+ * FastAPI-Vue Vite Plugin
+ * auto-upgrade@fastapi-vue-setup -- remove this if you edit the plugin
+ *
+ * Configures Vite for FastAPI backend integration:
+ * - Proxies /api/* requests to the FastAPI backend
+ * - Builds to the Python module's frontend-build directory
+ *
+ * Options:
+ *   paths - Array of paths to proxy (default: ["/api"])
+ */
+
+export default function fastapiVue({ paths = ["/api"] } = {}) {
+  const backendUrl = process.env.PASKIA_BACKEND_URL || "http://localhost:4402"
+
+  // Build proxy configuration for each path
+  const proxy = {}
+  for (const path of paths) {
+    proxy[path] = {
+      target: backendUrl,
+      changeOrigin: false,
+      ws: true,
+    }
+  }
+
+  return {
+    name: "vite-plugin-fastapi-paskia",
+    config: () => ({
+      server: { proxy },
+      build: {
+        outDir: "../paskia/frontend-build",
+        emptyOutDir: true,
+      },
+    }),
+  }
+}

frontend/vite.config.js

@@ -4,6 +4,7 @@ import { resolve } from 'node:path'
 import vue from '@vitejs/plugin-vue'
 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/
 const authHost = process.env.PASKIA_AUTH_HOST
@@ -12,6 +13,15 @@ export default defineConfig(({ command }) => ({
   appType: 'mpa',
   publicDir: 'public',
   plugins: [
+    fastapiVue({ paths: [
+      "/auth/api",
+      "/auth/ws",
+      "/.well-known/openid-configuration",
+      // 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
+      "^/[a-z]+\\.[a-z]+\\.[a-z]+\\.[a-z]+\\.[a-z]+$",
+    ] }),
     vue(),
     // Auth host routing: rewrite paths when accessing dedicated auth host
     // Must run before serve-examples to handle / correctly
@@ -37,6 +47,18 @@ export default defineConfig(({ command }) => ({
         })
       }
     },
+    {
+      name: 'restricted-endpoints-rewrite',
+      configureServer(server) {
+        server.middlewares.use((req, _res, next) => {
+          // Rewrite /auth/restricted/iframe and /auth/restricted/oidc to /auth/restricted/
+          if (req.url === '/auth/restricted/iframe' || req.url === '/auth/restricted/oidc') {
+            req.url = '/auth/restricted/'
+          }
+          next()
+        })
+      }
+    },
     {
       name: 'serve-examples',
       configureServer(server) {
@@ -81,7 +103,9 @@ export default defineConfig(({ command }) => ({
     }
   ].filter(Boolean),
   resolve: {
-    alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) }
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    }
   },
   base: '/',
   server: {
@@ -89,24 +113,6 @@ export default defineConfig(({ command }) => ({
     allowedHosts: true,
     fs: {
       allow: ['..']
-    },
-    proxy: {
-      // Only proxy these two specific backend API paths
-      '/auth/api': {
-        target: 'http://localhost:4402'
-      },
-      '/auth/ws': {
-        target: 'http://localhost:4402',
-        ws: true
-      },
-      // Passphrase links: /auth/word1.word2.word3.word4.word5
-      '^/auth/[a-z]+\\.[a-z]+\\.[a-z]+\\.[a-z]+\\.[a-z]+$': {
-        target: 'http://localhost:4402'
-      },
-      // Passphrase links: /word1.word2.word3.word4.word5
-      '^/[a-z]+\\.[a-z]+\\.[a-z]+\\.[a-z]+\\.[a-z]+$': {
-        target: 'http://localhost:4402'
-      }
     }
   },
   build: {

oidc.md

@@ -0,0 +1,92 @@
+# OIDC Provider Implementation
+
+OpenID Connect 1.0 provider enabling third-party apps to authenticate users via passkey. Also supports native cookie-based authentication.
+
+## Data Models
+
+**User** — Added: `email`, `preferred_username`
+
+**Session** — Added: `client_uuid` (None = native, set = OIDC)
+- `key: bytes` — hashed DB key, never stored raw
+- `secret` → `hash_secret("session", secret)` → DB lookup
+- OIDC `sid` → `base64url.encode(hash_secret("oidc", session.key))`
+
+**OIDClient** — `uuid, client_secret_hash, name, redirect_uris`
+
+## Auth Codes (In-Memory Only)
+
+60-second lifetime, auto-cleaned:
+
+```python
+from paskia.authcode import AuthCode, OIDC, codes
+
+class AuthCode(msgspec.Struct):
+    session_key: str       # Session DB key
+    created: datetime
+    oidc: OIDC | None      # Only for OIDC mode
+
+class OIDC(msgspec.Struct):
+    redirect_uri, scope, nonce, code_challenge, code_challenge_method: str
+```
+
+Usage: `code = authcode.store(AuthCode(...))` → later `codes.pop(code, None)`
+
+## Authorization Flows
+
+### OIDC (Authorization Code)
+
+1. `GET /auth/restricted/oidc?client_id=UUID&redirect_uri=...&scope=openid&nonce=...&code_challenge=...`
+2. Frontend → WebSocket: `/auth/ws/authenticate?client_id=...&redirect_uri=...&...`
+3. Validate client/redirect_uri, authenticate via passkey
+4. `db.oidc_login()` → `(secret, session_key)`
+5. Create `AuthCode(session_key, oidc=OIDC(...))` → code
+6. Return: `{"redirect_url": "{redirect_uri}?code={code}&state={state}"}`
+7. Client exchanges code at `/auth/oidc/token` with `code_verifier` (PKCE S256)
+
+**Token:** `access_token, id_token, refresh_token={secret}, expires_in=3600`
+
+**ID token:** `sub, sid (base64url), name, preferred_username, email, groups`
+
+### Native (Cookie)
+
+1. WebSocket: `/auth/ws/authenticate` (no OIDC params)
+2. Authenticate via passkey
+3. `db.login()` → secret
+4. Create `AuthCode(session_key=secret, oidc=None)` → exchange_code
+5. Return: `{"user": "UUID", "exchange_code": "..."}`
+6. `POST /auth/api/exchange` with code → sets cookie
+
+## Refresh & Logout
+
+**Refresh:** `POST /auth/oidc/token` with `grant_type=refresh_token&refresh_token={secret}&client_id=...&client_secret=...`
+- Looks up session, validates client match
+- Extends expiry +24h (sliding window)
+- Returns new tokens with same `sid`
+
+**Back-channel logout:** `POST /auth/oidc/backchannel-logout` with `logout_token={jwt}`
+- Verify signature, extract `sid` or `sub`
+- Delete matched sessions
+- Return 200 OK
+
+Discovery: `backchannel_logout_supported: true`
+
+## Endpoints
+
+- `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, 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)

paskia-js/.gitignore

@@ -0,0 +1,30 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+.DS_Store
+dist
+dist-ssr
+coverage
+*.local
+
+/cypress/videos/
+/cypress/screenshots/
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+*.tsbuildinfo

paskia-js/README.md

@@ -0,0 +1,155 @@
+# 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.
+
+## Installation
+
+### NPM
+
+No framework dependencies. Works with any framework (Vue, React, Svelte, etc.) or vanilla JS. Typescript typing included.
+
+```sh
+npm install paskia
+```
+
+```js
+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.
+
+```html
+<script type="module">
+  import { ... } from 'https://cdn.jsdelivr.net/npm/paskia@latest/dist/paskia.js'
+</script>
+```
+
+## Features
+
+### Session Validation
+
+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.
+
+```js
+import { SessionValidator } from 'paskia'
+
+const validator = new SessionValidator(
+  () => currentUser?.uuid,  // getter for current user ID that we track
+  (error) => handleSessionLost(error)  // callback when session is lost
+)
+
+validator.start()  // call at your app startup/login
+validator.stop()   // stop the system (optional)
+```
+
+### API Fetch Utilities
+
+Enhanced fetch functions with automatic error handling and authentication retry:
+
+```js
+import { apiJson, apiFetch } from 'paskia'
+
+// JSON API calls with automatic auth handling
+const data = await apiJson('/api/endpoint', { method: 'POST', body: { key: 'value' } })
+
+// Raw fetch with auth handling
+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`.
+
+The JSON variants set headers automatically, with body and response in JSON.
+
+### Timeout Settings
+
+Paskia exports a mutable settings object for defaults used by fetch/auth/session validation timers. Default values shown below.
+
+```js
+import { settings } from 'paskia'
+
+// General fetch timeout used by apiFetch/apiJson/fetchJson when no timeout is passed
+settings.fetch_ms = 10000
+
+// Fetch timeout used by SessionValidator (/auth/api/validate is fast)
+settings.auth_ms = 1000
+
+// SessionValidator polling and idle timers
+settings.poll_ms = 60000
+settings.idle_ms = 300000
+```
+
+You can still override timeout per request:
+
+```js
+await apiJson('/api/upload', { method: 'POST', body: data, timeout: 30000 })
+```
+
+### 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'
+
+const response = await fetch('/api/protected')
+if (response.status === 401 || response.status === 403) {
+  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
+
+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.
+
+The backdrop is also reusable/refcounted, so you can keep consistent visuals for your own dialogs:
+
+```js
+import { holdGlobalBackdrop, releaseGlobalBackdrop } from 'paskia'
+
+holdGlobalBackdrop()
+try {
+  await your.own.dialog()
+} finally {
+  releaseGlobalBackdrop()
+}
+```
+
+The backdrop only disappears after all holders have released it.
+
+## Error Handling
+
+### AuthCancelledError (apiFetch, apiJson, showAuthIframe)
+
+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.
+
+- Do nothing if the app can continue despite the failed operation (no UI notification needed)
+- Display a simple Access Denied page with suggestion/button to reload the page to try again
+
+Do not retry automatically.
+
+### 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) {
+  if (shouldShowErrorToast(e)) {
+    your.message.display(getUserFriendlyErrorMessage(e))
+  }
+}
+```

paskia-js/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "paskia",
+  "version": "1.4.0",
+  "description": "Paskia authentication utilities for JavaScript",
+  "author": "Leo Vasanko",
+  "license": "Unlicense",
+  "homepage": "https://git.zi.fi/LeoVasanko/paskia",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LeoVasanko/paskia",
+    "directory": "paskia-js"
+  },
+  "type": "module",
+  "main": "./dist/paskia.js",
+  "types": "./dist/paskia.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/paskia.d.ts",
+      "import": "./dist/paskia.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "~5.8.0",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "paskia",
+    "passkey",
+    "webauthn"
+  ]
+}

paskia-js/src/fetch.ts

@@ -0,0 +1,145 @@
+import { showAuthIframe, AuthCancelledError } from './overlay'
+import settings from './settings'
+
+export { AuthCancelledError }
+
+export interface ApiFetchOptions extends RequestInit {
+  timeout?: number
+}
+
+export interface FetchJsonOptions extends Omit<RequestInit, 'body'> {
+  timeout?: number
+  body?: BodyInit | Record<string, unknown> | null
+}
+
+export class ApiError extends Error {
+  readonly url: string
+  readonly status: number
+  readonly statusText: string
+  readonly data: unknown
+
+  constructor(url: string, response: Response, data: unknown) {
+    super((data as { detail?: string })?.detail || `Request failed: ${response.status}`)
+    this.name = 'ApiError'
+    this.url = url
+    this.status = response.status
+    this.statusText = response.statusText
+    this.data = data
+  }
+}
+
+export class NetworkError extends Error {
+  readonly originalError: Error | null
+
+  constructor(message: string, originalError: Error | null = null) {
+    super(message)
+    this.name = 'NetworkError'
+    this.originalError = originalError
+  }
+}
+
+export async function apiFetch(url: string, options: ApiFetchOptions = {}): Promise<Response> {
+  const { timeout = settings.fetch_ms, ...fetchOptions } = options
+  fetchOptions.credentials = fetchOptions.credentials || 'include'
+
+  while (true) {
+    let response: Response
+    try {
+      response = await fetch(url, {...fetchOptions, signal: timeout ? AbortSignal.timeout(timeout) : undefined})
+    } catch (error) {
+      const err = error as Error
+      if (err.name === 'TimeoutError') {
+        throw new NetworkError('Request timed out', err)
+      }
+      if (err.name === 'AbortError') {
+        throw error
+      }
+      if (err.name === 'TypeError' && err.message === 'Failed to fetch') {
+        throw new NetworkError('Unable to connect to server', err)
+      }
+      throw new NetworkError(err.message || 'Network error', err)
+    }
+
+    if (response.status === 401 || response.status === 403) {
+      let data: { auth?: { iframe?: string } } | null = null
+      try {
+        data = await response.clone().json()
+      } catch {}
+      if (data?.auth?.iframe && window === window.top) {
+        await showAuthIframe(data.auth.iframe)
+        continue  // Retry the original request after successful auth
+      }
+    }
+
+    return response
+  }
+}
+
+type FetchFn = (url: string, options?: RequestInit) => Promise<Response>
+
+export async function apiJson<T = unknown>(url: string, options: FetchJsonOptions = {}): Promise<T> {
+  return fetchJson<T>(url, options, apiFetch)
+}
+
+export async function fetchJson<T = unknown>(url: string, options: FetchJsonOptions = {}, fetchFn: FetchFn = fetch): Promise<T> {
+  const headers: Record<string, string> = {
+    'Accept': 'application/json',
+    ...(options.headers as Record<string, string>),
+  }
+
+  let body: BodyInit | undefined
+  if (options.body && typeof options.body === 'object' && !(options.body instanceof FormData)) {
+    headers['Content-Type'] = 'application/json'
+    body = JSON.stringify(options.body)
+  } else {
+    body = options.body as BodyInit
+  }
+
+  const opt: RequestInit = { ...options, headers, body }
+
+  const response = await fetchFn(url, opt)
+  const data = await response.json() as T
+
+  if (!response.ok) {
+    throw new ApiError(url, response, data)
+  }
+
+  return data
+}
+
+export function getUserFriendlyErrorMessage(error: Error): string {
+  if (error instanceof NetworkError) return error.message
+  if (error instanceof ApiError) return error.message
+  if (error.name === 'TimeoutError') return 'Request timed out'
+  if (error.name === 'TypeError' && error.message === 'Failed to fetch') {
+    return 'Unable to connect to server'
+  }
+  return error.message || 'An error occurred'
+}
+
+export function shouldShowErrorToast(error: Error): boolean {
+  if (error instanceof AuthCancelledError) return false
+  if (error.name === 'AbortError') return false
+  if (error instanceof ApiError && (error.status === 401 || error.status === 403)) return false
+  return true
+}
+
+type ShowMessageFn = (message: string, type: string, duration: number) => void
+
+export function createApiCaller(showMessage: ShowMessageFn) {
+  return async function apiCall<T = unknown>(url: string, options: FetchJsonOptions = {}): Promise<T> {
+    try {
+      return await apiJson<T>(url, options)
+    } catch (error) {
+      if (!shouldShowErrorToast(error as Error)) {
+        throw error
+      }
+      const err = error as Error
+      console.error(`API error for ${url}:`, err instanceof ApiError ? { status: err.status, statusText: err.statusText, data: err.data } : err)
+      showMessage(getUserFriendlyErrorMessage(err), 'error', 4000)
+      throw error
+    }
+  }
+}
+
+export default apiFetch

paskia-js/src/index.ts

@@ -0,0 +1,25 @@
+export {
+  ApiError,
+  NetworkError,
+  AuthCancelledError,
+  apiFetch,
+  apiJson,
+  fetchJson,
+  getUserFriendlyErrorMessage,
+  shouldShowErrorToast,
+  createApiCaller,
+} from './fetch'
+
+export type { ApiFetchOptions, FetchJsonOptions } from './fetch'
+
+export { default as settings } from './settings'
+
+export {
+  holdGlobalBackdrop,
+  releaseGlobalBackdrop,
+  isAuthIframeOpen,
+  hideAuthIframe,
+  showAuthIframe,
+} from './overlay'
+
+export { SessionValidator } from './validate'

paskia-js/src/overlay.ts

@@ -0,0 +1,167 @@
+const AUTH_IFRAME_ID = 'paskia-iframe'
+const STYLES_ID = 'paskia-dialog'
+const STYLES_TEXT = `\
+body::before {
+  content: '';
+  position: fixed;
+  inset: 0;
+  z-index: 1099;
+  background: transparent;
+  backdrop-filter: blur(0) brightness(1);
+  -webkit-backdrop-filter: blur(0) brightness(1);
+  pointer-events: none;
+  visibility: hidden;
+  transition: all 0.2s ease-out;
+}
+body.paskia-backdrop::before {
+  backdrop-filter: blur(.2rem) brightness(0.7);
+  -webkit-backdrop-filter: blur(.2rem) brightness(0.7);
+  visibility: visible;
+}
+body.paskia-backdrop {
+  overflow: auto;
+}
+#${AUTH_IFRAME_ID} {
+  border: none;
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  z-index: 9999;
+  color-scheme: auto;
+  background: transparent;
+}
+`
+
+let authIframe: HTMLIFrameElement | null = null
+let authPromise: Promise<void> | null = null
+let authResolve: (() => void) | null = null
+let authReject: ((error: Error) => void) | null = null
+let messageListenerInstalled = false
+let backdropHolders = 0
+
+function injectStyles(): void {
+  if (document.getElementById(STYLES_ID)) return
+  const style = document.createElement('style')
+  style.id = STYLES_ID
+  style.textContent = STYLES_TEXT
+  document.head.insertBefore(style, document.head.firstChild)
+}
+
+export class AuthCancelledError extends Error {
+  constructor() {
+    super('Authentication cancelled')
+    this.name = 'AuthCancelledError'
+  }
+}
+
+export function holdGlobalBackdrop(): void {
+  injectStyles()
+  backdropHolders++
+  document.body.classList.add('paskia-backdrop')
+}
+
+export function releaseGlobalBackdrop(): void {
+  backdropHolders = Math.max(0, backdropHolders - 1)
+  if (backdropHolders === 0) {
+    document.body.classList.remove('paskia-backdrop')
+  }
+}
+
+export function isAuthIframeOpen(): boolean {
+  return !!document.getElementById(AUTH_IFRAME_ID)
+}
+
+export function hideAuthIframe(): void {
+  if (authIframe) {
+    authIframe.remove()
+    authIframe = null
+    releaseGlobalBackdrop()
+  }
+}
+
+function handleAuthMessage(event: MessageEvent): void {
+  const data = event.data as { type?: string }
+  if (!data?.type) return
+
+  switch (data.type) {
+    case 'auth-success':
+      hideAuthIframe()
+      if (authResolve) {
+        authResolve()
+        authPromise = null
+        authResolve = null
+        authReject = null
+      }
+      break
+
+    case 'auth-back':
+      hideAuthIframe()
+      if (authReject) {
+        authReject(new AuthCancelledError())
+        authPromise = null
+        authResolve = null
+        authReject = null
+      }
+      break
+  }
+}
+
+function ensureMessageListener(): void {
+  if (messageListenerInstalled) return
+  if (typeof window !== 'undefined') {
+    window.addEventListener('message', handleAuthMessage)
+    messageListenerInstalled = true
+  }
+}
+
+export function showAuthIframe(iframeUrl: string, title = 'Authentication'): Promise<void> {
+  injectStyles()
+  ensureMessageListener()
+
+  if (authPromise) return authPromise
+
+  if (document.getElementById(AUTH_IFRAME_ID)) {
+    authPromise = new Promise((resolve, reject) => {
+      authResolve = resolve
+      authReject = reject
+    })
+    return authPromise
+  }
+
+  authPromise = new Promise((resolve, reject) => {
+    authResolve = resolve
+    authReject = reject
+  })
+
+  hideAuthIframe()
+  holdGlobalBackdrop()
+
+  authIframe = document.createElement('iframe')
+  authIframe.id = AUTH_IFRAME_ID
+  authIframe.title = title
+  authIframe.src = iframeUrl
+  document.body.appendChild(authIframe)
+
+  return authPromise
+}
+
+export function createAuthIframe(iframeUrl: string, title = 'Authentication'): HTMLIFrameElement {
+  injectStyles()
+  const existing = document.getElementById(AUTH_IFRAME_ID)
+  if (existing) existing.remove()
+
+  const iframe = document.createElement('iframe')
+  iframe.id = AUTH_IFRAME_ID
+  iframe.title = title
+  iframe.src = iframeUrl
+  document.body.appendChild(iframe)
+
+  return iframe
+}
+
+export function removeAuthIframe(): void {
+  const iframe = document.getElementById(AUTH_IFRAME_ID)
+  if (iframe) iframe.remove()
+}

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

@@ -0,0 +1,64 @@
+import { apiJson } from './fetch'
+import settings from './settings'
+
+export class SessionValidator {
+  private userUuidGetter: () => string | undefined
+  private onSessionLost: (error: Error) => void
+  private pollTimer: ReturnType<typeof setInterval> | null = null
+  private idleTimer: ReturnType<typeof setTimeout> | null = null
+  private active = false
+
+  constructor(userUuidGetter: () => string | undefined, onSessionLost: (error: Error) => void) {
+    this.userUuidGetter = userUuidGetter
+    this.onSessionLost = onSessionLost
+    this.resetIdleTimer = this.resetIdleTimer.bind(this)
+  }
+
+  resetIdleTimer(): void {
+    if (this.idleTimer) clearTimeout(this.idleTimer)
+    if (!this.active) this.startPolling()
+    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', timeout: settings.auth_ms })
+      const newUuid = data.ctx?.user?.uuid
+      if (newUuid !== this.userUuidGetter()) {
+        window.location.reload()
+      }
+    } catch (error) {
+      if ((error as Error).name !== 'NetworkError') {
+        this.stopPolling()
+        this.onSessionLost(error as Error)
+      }
+    }
+  }
+
+  startPolling(): void {
+    if (this.active) return
+    this.active = true
+    this.pollTimer = setInterval(() => this.validate(), settings.poll_ms)
+  }
+
+  stopPolling(): void {
+    this.active = false
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer)
+      this.pollTimer = null
+    }
+  }
+
+  start(): void {
+    window.addEventListener('pointermove', this.resetIdleTimer)
+    window.addEventListener('pointerdown', this.resetIdleTimer)
+    this.resetIdleTimer()
+  }
+
+  stop(): void {
+    window.removeEventListener('pointermove', this.resetIdleTimer)
+    window.removeEventListener('pointerdown', this.resetIdleTimer)
+    if (this.idleTimer) clearTimeout(this.idleTimer)
+    this.stopPolling()
+  }
+}

paskia-js/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "declaration": true,
+    "declarationDir": "./dist",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "lib": ["ES2020", "DOM"],
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}

paskia-js/vite.config.js

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vite'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import dts from 'vite-plugin-dts'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+
+export default defineConfig({
+  plugins: [dts({ rollupTypes: true })],
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'src/index.ts'),
+      fileName: 'paskia',
+      formats: ['es'],
+    },
+  },
+})

paskia/__main__.py

@@ -0,0 +1,148 @@
+import argparse
+import logging
+import os
+import sys
+
+import msgspec
+from fastapi_vue import server
+from fastapi_vue.hostutil import parse_endpoints
+
+from paskia._version import __version__
+from paskia.db.jsonl import load_readonly
+from paskia.db.paths import db_file_path
+from paskia.util import startupbox
+from paskia.util.hostutil import (
+    normalize_auth_host_and_origins,
+    normalize_origin,
+    validate_auth_host,
+)
+from paskia.util.runtime import RuntimeConfig
+
+DEFAULT_PORT = 4401
+DEVMODE = os.getenv("PASKIA_DEV") == "1"
+
+EPILOG = """\
+Example:
+  paskia --rp-id example.com --rp-name "Example Corporation" --auth-host auth.example.com
+"""
+
+
+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",
+        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",
+        metavar="LISTEN",
+        help=(
+            "Endpoint to listen on (default: localhost:4401). "
+            "Forms: host:port  port  :port  [ipv6]:port  unix:path  /path.sock"
+        ),
+    )
+    add_common_options(parser)
+
+    args = parser.parse_args()
+
+    # Load stored config (read-only, no writes, no global state)
+    db_path = db_file_path(rp_id=args.rp_id, create_root=True)
+    try:
+        config = load_readonly(str(db_path), rp_id=args.rp_id).config
+    except SystemExit as e:
+        print(f"🛑 Paskia {__version__} could not load")
+        sys.exit(str(e))
+
+    # Override stored config with CLI args, or clear with empty string
+    if args.rp_name is not None:
+        config.rp_name = args.rp_name or None
+    if args.auth_host is not None:
+        config.auth_host = args.auth_host or None
+    if args.origins is not None:
+        config.origins = None if args.origins == [""] else args.origins
+    if args.listen is not None:
+        config.listen = None if args.listen == [""] else args.listen
+
+    # Process and normalize auth_host and origins
+    try:
+        validate_auth_host(config.auth_host, config.rp_id) if config.auth_host else None
+    except ValueError as e:
+        raise SystemExit(str(e))
+    if config.origins:
+        config.origins = [normalize_origin(o) for o in config.origins]
+    config.auth_host, config.origins = normalize_auth_host_and_origins(
+        config.auth_host, config.origins
+    )
+
+    # Parse first endpoint for site_url fallback
+    ep = next(iter(parse_endpoints(config.listen, DEFAULT_PORT)), {})
+    port = ep.get("port")
+
+    # Compute site_url and site_path
+    # Priority: auth_host > origins[0] > PASKIA_VITE_URL > http://localhost:port > https://rp_id
+    site_path = "/auth/"
+    if config.auth_host:
+        site_url, site_path = config.auth_host, "/"
+    elif config.origins:
+        site_url = config.origins[0]
+    elif vite_url := os.environ.get("PASKIA_VITE_URL"):
+        site_url = vite_url.rstrip("/")  # Devserver
+    elif config.rp_id == "localhost" and port:
+        site_url = f"http://localhost:{port}"  # Backend directly if we can
+    else:
+        site_url = f"https://{config.rp_id}"  # Assume external reverse proxy
+
+    # Build runtime configuration for the server
+    runtime = RuntimeConfig(
+        config=config,
+        site_url=site_url,
+        site_path=site_path,
+        save=args.save,
+    )
+    startupbox.print_startup_config(runtime)
+    os.environ["PASKIA_CONFIG"] = msgspec.json.encode(runtime).decode()
+
+    # Run the server (spawns processes in dev mode)
+    dev = {"reload": True, "reload_dirs": ["paskia"]} if DEVMODE else {}
+    server.run(
+        "paskia.fastapi.mainapp:app",
+        listen=config.listen,
+        default_port=DEFAULT_PORT,
+        log_level="warning",
+        access_log=False,
+        **dev,
+    )
+
+
+if __name__ == "__main__":
+    main()

paskia/aaguid/__init__.py

@@ -10,6 +10,7 @@ This module provides functionality to:
 import json
 from collections.abc import Iterable
 from importlib.resources import files
+from uuid import UUID
 
 __ALL__ = ["AAGUID", "filter"]
 
@@ -18,15 +19,27 @@ AAGUID_FILE = files("paskia") / "aaguid" / "combined_aaguid.json"
 AAGUID: dict[str, dict] = json.loads(AAGUID_FILE.read_text(encoding="utf-8"))
 
 
-def filter(aaguids: Iterable[str]) -> dict[str, dict]:
+def filter(aaguids: Iterable[UUID]) -> dict[str, dict]:
     """
     Get AAGUID information only for the provided set of AAGUIDs.
 
     Args:
-        aaguids: Set of AAGUID strings that the user has credentials for
+        aaguids: Iterable of AAGUIDs (UUIDs) that the user has credentials for
 
     Returns:
-        Dictionary mapping AAGUID to authenticator information for only
+        Dictionary mapping AAGUID string to authenticator information for only
         the AAGUIDs that the user has and that we have data for
     """
-    return {aaguid: AAGUID[aaguid] for aaguid in aaguids if aaguid in AAGUID}
+    result = {}
+    for a in aaguids:
+        s = str(a)
+        if s in AAGUID:
+            info = AAGUID[s].copy()
+            # Rename icon_light to icon
+            if "icon_light" in info:
+                info["icon"] = info.pop("icon_light")
+            # If icons are the same, set dark to None to save space
+            if info.get("icon") == info.get("icon_dark"):
+                info["icon_dark"] = None
+            result[s] = info
+    return result

paskia/authcode.py

@@ -0,0 +1,113 @@
+"""
+Authorization code management for OIDC and cookie exchange flows.
+
+Codes are short-lived (60 seconds) and stored in-memory only.
+Two separate stores maintain full isolation between OIDC and cookie flows.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import secrets
+from datetime import UTC, datetime, timedelta
+
+import msgspec
+
+_logger = logging.getLogger(__name__)
+
+# Auth codes expire after this duration
+AUTH_CODE_LIFETIME = timedelta(seconds=60)
+
+
+class OIDCCode(msgspec.Struct):
+    """An OIDC authorization code pending token exchange.
+
+    PKCE uses S256 only when provided (verified at token exchange).
+    """
+
+    session_key: str
+    created: datetime
+    redirect_uri: str
+    scope: str
+    nonce: str | None = None
+    code_challenge: str | None = None
+
+
+class CookieCode(msgspec.Struct):
+    """A cookie exchange code for setting session cookie after WebSocket auth."""
+
+    session_key: str
+    created: datetime
+
+
+# Separate stores for each code type
+oidc_codes: dict[str, OIDCCode] = {}
+cookie_codes: dict[str, CookieCode] = {}
+
+# Background cleanup task
+_cleanup_task: asyncio.Task | None = None
+
+
+async def start():
+    """Start the cleanup background task."""
+    global _cleanup_task
+    if _cleanup_task is None:
+        _cleanup_task = asyncio.create_task(_cleanup_loop())
+
+
+async def stop():
+    """Stop the cleanup background task."""
+    global _cleanup_task
+    if _cleanup_task:
+        _cleanup_task.cancel()
+        try:
+            await _cleanup_task
+        except asyncio.CancelledError:
+            pass
+        _cleanup_task = None
+
+
+async def _cleanup_loop():
+    while True:
+        try:
+            await asyncio.sleep(30)  # Check every 30 seconds
+            _cleanup_expired()
+        except asyncio.CancelledError:
+            break
+        except Exception:
+            _logger.exception("Error in auth code cleanup loop")
+
+
+def _cleanup_expired():
+    oldest = datetime.now(UTC) - AUTH_CODE_LIFETIME
+    for code, auth_code in list(oidc_codes.items()):
+        if auth_code.created < oldest:
+            del oidc_codes[code]
+    for code, auth_code in list(cookie_codes.items()):
+        if auth_code.created < oldest:
+            del cookie_codes[code]
+
+
+def store_oidc(code: OIDCCode) -> str:
+    """Store an OIDC authorization code and return the code string."""
+    token = secrets.token_urlsafe(12)
+    oidc_codes[token] = code
+    return token
+
+
+def consume_oidc(token: str) -> OIDCCode | None:
+    """Consume an OIDC code, returning it if valid. Atomic removal."""
+    return oidc_codes.pop(token, None)
+
+
+def store_cookie(code: CookieCode) -> str:
+    """Store a cookie exchange code and return the code string."""
+    token = secrets.token_urlsafe(12)
+    cookie_codes[token] = code
+    return token
+
+
+def consume_cookie(token: str) -> CookieCode | None:
+    """Consume a cookie exchange code, returning it if valid. Atomic removal."""
+    return cookie_codes.pop(token, None)

paskia/authsession.py

@@ -8,105 +8,46 @@ independent of any web framework:
 - Credential management
 """
 
-from datetime import datetime, timezone
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
 from uuid import UUID
 
-from paskia.config import SESSION_LIFETIME
+from paskia import db
-from paskia.db import ResetToken, Session
+from paskia.config import RESET_LIFETIME, SESSION_LIFETIME
-from paskia.globals import db, passkey
+from paskia.db.structs import ResetToken
 from paskia.util import hostutil
-from paskia.util.tokens import create_token, reset_key, session_key
+
+if TYPE_CHECKING:
+    from paskia.db import ResetToken
 
 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(timezone.utc) + EXPIRES
+    return datetime.now(UTC) + EXPIRES
 
 
 def reset_expires() -> datetime:
-    from .config import RESET_LIFETIME
+    return datetime.now(UTC) + RESET_LIFETIME
-
-    return datetime.now(timezone.utc) + RESET_LIFETIME
 
 
-def session_expiry(session: Session) -> datetime:
+def get_reset(token: str) -> "ResetToken":
-    """Calculate the expiration timestamp for a session (UTC aware)."""
+    """Validate a credential reset token."""
-    # After migration all renewed timestamps are timezone-aware UTC
-    return session.renewed + EXPIRES
 
-
+    record = ResetToken.by_passphrase(token)
-async def create_session(
+    if record:
-    user_uuid: UUID,
-    credential_uuid: UUID,
-    *,
-    host: str,
-    ip: str,
-    user_agent: str,
-) -> str:
-    """Create a new session and return a session token."""
-    normalized_host = hostutil.normalize_host(host)
-    if not normalized_host:
-        raise ValueError("Host required for session creation")
-    hostname = normalized_host.split(":")[0]  # Domain names only, IPs aren't supported
-    rp_id = passkey.instance.rp_id
-    if not (hostname == rp_id or hostname.endswith(f".{rp_id}")):
-        raise ValueError(f"Host must be the same as or a subdomain of {rp_id}")
-    token = create_token()
-    now = datetime.now(timezone.utc)
-    await db.instance.create_session(
-        user_uuid=user_uuid,
-        credential_uuid=credential_uuid,
-        key=session_key(token),
-        host=normalized_host,
-        ip=ip,
-        user_agent=user_agent,
-        renewed=now,
-    )
-    return token
-
-
-async def get_reset(token: str) -> ResetToken:
-    """Validate a credential reset token. Returns None if the token is not well formed (i.e. it is another type of token)."""
-    record = await db.instance.get_reset_token(reset_key(token))
-    if record and record.expiry >= datetime.now(timezone.utc):
         return record
     raise ValueError("This authentication link is no longer valid.")
 
 
-async def get_session(token: str, host: str | None = None) -> Session:
+def delete_credential(credential_uuid: UUID, auth: str, host: str | None = None):
-    """Validate a session token and return session data if valid."""
-    host = hostutil.normalize_host(host)
-    if not host:
-        raise ValueError("Invalid host")
-    session = await db.instance.get_session(session_key(token))
-    if session and session_expiry(session) >= datetime.now(timezone.utc):
-        if session.host is None:
-            # First time binding: store exact host:port (or IPv6 form) now.
-            await db.instance.set_session_host(session.key, host)
-            session.host = host
-        elif session.host != host:
-            raise ValueError("Session host mismatch")
-        return session
-    raise ValueError("Your session has expired. Please sign in again!")
-
-
-async def refresh_session_token(token: str, *, ip: str, user_agent: str):
-    """Refresh a session extending its expiry."""
-    session_record = await db.instance.get_session(session_key(token))
-    if not session_record:
-        raise ValueError("Session not found or expired")
-    updated = await db.instance.update_session(
-        session_key(token),
-        ip=ip,
-        user_agent=user_agent,
-        renewed=datetime.now(timezone.utc),
-    )
-    if not updated:
-        raise ValueError("Session not found or expired")
-
-
-async def delete_credential(credential_uuid: UUID, auth: str, host: str | None = None):
     """Delete a specific credential for the current user."""
-    s = await get_session(auth, host=host)
+    ctx = session_ctx(auth, host)
-    await db.instance.delete_credential(credential_uuid, s.user_uuid)
+    if not ctx:
+        raise ValueError("Session expired")
+    db.delete_credential(credential_uuid, ctx.user.uuid)

paskia/bootstrap.py

@@ -6,105 +6,58 @@ including creating default admin user, organization, permissions, and
 generating a reset link for initial admin setup.
 """
 
-import asyncio
 import logging
-from datetime import datetime, timezone
 
-import uuid7
+from paskia import authsession, db
+from paskia.db.structs import Config
+from paskia.util import hostutil
 
-from paskia import authsession, globals
+logger = logging.getLogger(__name__)
-from paskia.db import Org, Permission, Role, User
-from paskia.util import hostutil, passphrase, tokens
 
 
-def _init_logger() -> logging.Logger:
+def _configure_logger() -> None:
-    logger = logging.getLogger(__name__)
+    if logger.handlers:
-    if not logger.handlers and not logging.getLogger().handlers:
+        return
-        h = logging.StreamHandler()
+    handler = logging.StreamHandler()
-        h.setFormatter(logging.Formatter("%(message)s"))
+    handler.setFormatter(logging.Formatter("%(message)s"))
-        logger.addHandler(h)
+    logger.addHandler(handler)
-        logger.setLevel(logging.INFO)
+    logger.setLevel(logging.INFO)
-    return logger
+    logger.propagate = False
 
 
-logger = _init_logger()
+_configure_logger()
 
 # Shared log message template for admin reset links
-ADMIN_RESET_MESSAGE = """\
+ADMIN_RESET_MESSAGE = """
-%s
-
 👤 Admin  %s
    - Use this link to register a Passkey for the admin user!
 """
 
 
-async def _create_and_log_admin_reset_link(user_uuid, message, session_type) -> str:
+def _log_reset_link(passphrase: str, message: str | None = None) -> str:
-    """Create an admin reset link and log it with the provided message."""
+    """Log a reset link message and return the URL."""
-    token = passphrase.generate()
+    reset_link = hostutil.reset_link_url(passphrase)
-    expiry = authsession.reset_expires()
+    if message:
-    await globals.db.instance.create_reset_token(
+        logger.info(message)
-        user_uuid=user_uuid,
+    logger.info(ADMIN_RESET_MESSAGE, reset_link)
-        key=tokens.reset_key(token),
-        expiry=expiry,
-        token_type=session_type,
-    )
-    reset_link = hostutil.reset_link_url(token)
-    logger.info(ADMIN_RESET_MESSAGE, message, reset_link)
     return reset_link
 
 
-async def bootstrap_system() -> dict:
+async def bootstrap_system(config: Config | None = None) -> None:
     """
     Bootstrap the entire system with default data.
 
-    Returns:
+    Uses db.bootstrap() which performs all operations in a single transaction.
-        dict: Contains information about created entities and reset link
+    The transaction log will show a single "bootstrap" action with all changes.
+
+    Args:
+        config: Configuration to store (rp_id, rp_name, origins, etc.)
     """
-    # Create permission first - will fail if already exists
+    # Call the single-transaction bootstrap function
-    perm0 = Permission(id="auth:admin", display_name="Master Admin")
+    reset_passphrase = db.bootstrap(config=config)
-    await globals.db.instance.create_permission(perm0)
 
-    org = Org(uuid7.create(), "Organization")
+    # Log the reset link (this is separate from the transaction log)
-    await globals.db.instance.create_organization(org)
+    _log_reset_link(reset_passphrase, "✅ Bootstrap completed!")
-
-    # After creation, org.permissions now includes the auto-created org admin permission
-    # Allow this org to grant global admin explicitly
-    await globals.db.instance.add_permission_to_organization(str(org.uuid), perm0.id)
-
-    # Create an Administration role granting both org and global admin
-    # Compose permissions for Administration role: global admin + org admin auto-perm
-    role = Role(
-        uuid7.create(),
-        org.uuid,
-        "Administration",
-        permissions=[perm0.id, *org.permissions],
-    )
-    await globals.db.instance.create_role(role)
-
-    user = User(
-        uuid=uuid7.create(),
-        display_name="Admin",
-        role_uuid=role.uuid,
-        created_at=datetime.now(timezone.utc),
-        visits=0,
-    )
-    await globals.db.instance.create_user(user)
-
-    # Generate reset link and log it
-    reset_link = await _create_and_log_admin_reset_link(
-        user.uuid, "✅ Bootstrap completed!", "admin bootstrap"
-    )
-
-    return {
-        "user": user,
-        "org": org,
-        "role": role,
-        "permissions": [
-            perm0,
-            *[Permission(id=p, display_name="") for p in org.permissions],
-        ],
-        "reset_link": reset_link,
-    }
 
 
 async def check_admin_credentials() -> bool:
@@ -115,36 +68,42 @@ async def check_admin_credentials() -> bool:
         bool: True if a reset link was created, False if admin already has credentials
     """
     try:
-        # Get permission organizations to find admin users
+        # Find the auth:admin permission
-        permission_orgs = await globals.db.instance.get_permission_organizations(
+        p = next(
-            "auth:admin"
+            (p for p in db.data().permissions.values() if p.scope == "auth:admin"), None
         )
-
+        if not p:
-        if not permission_orgs:
             return False
 
-        # Get users from the first organization with admin permission
+        perm_uuid = p.uuid
-        org_users = await globals.db.instance.get_organization_users(
+
-            str(permission_orgs[0].uuid)
+        # Find all roles that have the auth:admin permission
-        )
+        admin_roles = [
-        admin_users = [user for user, role in org_users if role == "Administration"]
+            r for r in db.data().roles.values() if perm_uuid in r.permissions
+        ]
+
+        # Collect all users from those roles
+        admin_users = []
+        for role in admin_roles:
+            admin_users.extend(role.users)
 
         if not admin_users:
             return False
 
         # Check first admin user for credentials
         admin_user = admin_users[0]
-        credentials = await globals.db.instance.get_credentials_by_user_uuid(
-            admin_user.uuid
-        )
 
-        if not credentials:
+        if not admin_user.credential_ids:
             # Admin exists but has no credentials, create reset link
-            await _create_and_log_admin_reset_link(
+            logger.info("⚠️  Admin user has no credentials!")
-                admin_user.uuid,
+
-                "⚠️  Admin user has no credentials!",
+            expiry = authsession.reset_expires()
-                "admin registration",
+            token = db.create_reset_token(
+                user_uuid=admin_user.uuid,
+                expiry=expiry,
+                token_type="admin registration",
             )
+            _log_reset_link(token)
             return True
 
         return False
@@ -153,38 +112,24 @@ async def check_admin_credentials() -> bool:
         return False
 
 
-async def bootstrap_if_needed() -> bool:
+async def bootstrap_if_needed(config: Config | None = None) -> bool:
     """
     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
     """
-    try:
+    # Check if the admin permission exists - if it does, system is already bootstrapped
-        # 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()):
-        await globals.db.instance.get_permission("auth:admin")
         # Permission exists, system is already bootstrapped
         # Check if admin needs credentials (only for already-bootstrapped systems)
         await check_admin_credentials()
         return False
-    except Exception:
-        # Permission doesn't exist, need to bootstrap
-        pass
 
     # 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()
+    await bootstrap_system(config=config)
     return True
-
-
-# CLI interface
-async def main():
-    """Main CLI entry point for bootstrapping."""
-    # Configure logging for CLI usage
-    logging.basicConfig(level=logging.INFO, format="%(message)s", force=True)
-
-    await globals.init()
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

paskia/config.py

@@ -1,4 +1,3 @@
-from dataclasses import dataclass
 from datetime import timedelta
 
 # Shared configuration constants for session management.
@@ -6,20 +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
-    devmode: bool = False

paskia/db/__init__.py

@@ -1,415 +1,152 @@
 """
 Database module for WebAuthn passkey authentication.
 
-This module provides dataclasses and database abstractions for managing
+Read: Access data() directly for structs.
-users, credentials, and sessions in a WebAuthn authentication system.
+CTX: data().session_ctx(key) returns SessionContext with effective permissions.
+Write: Functions validate and commit, or raise ValueError.
+
+Usage:
+    from paskia import db
+
+    # Read (after init)
+    user_data = db.data().users[user_uuid]
+
+    # Context
+    ctx = db.data().session_ctx(session_key)
+
+    # Write
+    db.create_user(user)
 """
 
-from abc import ABC, abstractmethod
+import paskia.db.operations as operations
-from dataclasses import dataclass, field
+from paskia.db.background import (
-from datetime import datetime
+    start_background,
-from uuid import UUID
+    start_cleanup,
-
+    stop_background,
-
+    stop_cleanup,
-@dataclass
+)
-class Permission:
+from paskia.db.bootstrap import bootstrap
-    id: str  # String primary key (max 128 chars)
+from paskia.db.jsonl import load_readonly
-    display_name: str
+from paskia.db.lifecycle import cleanup_expired, init
-
+from paskia.db.operations import (
-
+    add_permission_to_org,
-@dataclass
+    add_permission_to_role,
-class Role:
+    create_credential,
-    uuid: UUID
+    create_credential_session,
-    org_uuid: UUID
+    create_oid_client,
-    display_name: str
+    create_org,
-    # List of permission IDs this role grants to its members
+    create_permission,
-    permissions: list[str] = field(default_factory=list)  # permission IDs
+    create_reset_token,
-
+    create_role,
-
+    create_user,
-@dataclass
+    delete_credential,
-class Org:
+    delete_oid_client,
-    uuid: UUID
+    delete_org,
-    display_name: str
+    delete_permission,
-    # All permission IDs that the Org is allowed to grant to its roles
+    delete_reset_token,
-    permissions: list[str] = field(default_factory=list)  # permission IDs
+    delete_role,
-    # Roles belonging to this org
+    delete_session,
-    roles: list[Role] = field(default_factory=list)
+    delete_sessions_for_user,
-
+    delete_user,
-
+    is_username_taken,
-@dataclass
+    login,
-class User:
+    oidc_login,
-    uuid: UUID
+    remove_permission_from_org,
-    display_name: str
+    remove_permission_from_role,
-    role_uuid: UUID
+    reset_oid_client_secret,
-    created_at: datetime | None = None
+    set_session_host,
-    last_seen: datetime | None = None
+    update_config,
-    visits: int = 0
+    update_credential_sign_count,
-
+    update_oid_client,
-
+    update_org_name,
-@dataclass
+    update_permission,
-class Credential:
+    update_role_name,
-    uuid: UUID
+    update_session,
-    credential_id: bytes  # Long binary ID passed from the authenticator
+    update_user_display_name,
-    user_uuid: UUID
+    update_user_info,
-    aaguid: UUID
+    update_user_role,
-    public_key: bytes
+)
-    sign_count: int
+from paskia.db.structs import (
-    created_at: datetime
+    DB,
-    last_used: datetime | None = None
+    Client,
-    last_verified: datetime | None = None
+    Config,
-
+    Credential,
-
+    Org,
-@dataclass
+    Permission,
-class Session:
+    ResetToken,
-    key: bytes
+    Role,
-    user_uuid: UUID
+    Session,
-    credential_uuid: UUID
+    SessionContext,
-    host: str
+    User,
-    ip: str
+)
-    user_agent: str
+
-    renewed: datetime
+
-
+def data() -> DB:
-    def metadata(self) -> dict:
+    """Get the database instance for direct read access."""
-        """Return session metadata for backwards compatibility."""
+    return operations._db
-        return {
-            "ip": self.ip,
-            "user_agent": self.user_agent,
-            "renewed": self.renewed.isoformat(),
-        }
-
-
-@dataclass
-class ResetToken:
-    key: bytes
-    user_uuid: UUID
-    expiry: datetime
-    token_type: str
-
-
-@dataclass
-class SessionContext:
-    session: Session
-    user: User
-    org: Org
-    role: Role
-    credential: Credential | None = None
-    permissions: list[Permission] | None = None
-
-
-class DatabaseInterface(ABC):
-    """Abstract base class defining the database interface.
-
-    This class defines the public API that database implementations should provide.
-    Implementations may use decorators like @with_session that modify method signatures
-    at runtime, so this interface focuses on the logical operations rather than
-    exact parameter matching.
-    """
-
-    @abstractmethod
-    async def init_db(self) -> None:
-        """Initialize database tables."""
-        pass
-
-    # User operations
-    @abstractmethod
-    async def get_user_by_uuid(self, user_uuid: UUID) -> User:
-        """Get user record by WebAuthn user UUID."""
-
-    @abstractmethod
-    async def create_user(self, user: User) -> None:
-        """Create a new user."""
-
-    @abstractmethod
-    async def update_user_display_name(
-        self, user_uuid: UUID, display_name: str
-    ) -> None:
-        """Update a user's display name."""
-
-    # Role operations
-    @abstractmethod
-    async def create_role(self, role: Role) -> None:
-        """Create new role."""
-
-    @abstractmethod
-    async def update_role(self, role: Role) -> None:
-        """Update a role's display name and synchronize its permissions."""
-
-    @abstractmethod
-    async def delete_role(self, role_uuid: UUID) -> None:
-        """Delete a role by UUID. Implementations may prevent deletion if users exist."""
-
-    # Credential operations
-    @abstractmethod
-    async def create_credential(self, credential: Credential) -> None:
-        """Store a credential for a user."""
-
-    @abstractmethod
-    async def get_credential_by_id(self, credential_id: bytes) -> Credential:
-        """Get credential by credential ID."""
-
-    @abstractmethod
-    async def get_credentials_by_user_uuid(self, user_uuid: UUID) -> list[bytes]:
-        """Get all credential IDs for a user."""
-
-    @abstractmethod
-    async def update_credential(self, credential: Credential) -> None:
-        """Update the sign count, created_at, last_used, and last_verified for a credential."""
-
-    @abstractmethod
-    async def delete_credential(self, uuid: UUID, user_uuid: UUID) -> None:
-        """Delete a specific credential for a user."""
-
-    # Session operations
-    @abstractmethod
-    async def create_session(
-        self,
-        user_uuid: UUID,
-        key: bytes,
-        credential_uuid: UUID,
-        host: str,
-        ip: str,
-        user_agent: str,
-        renewed: datetime,
-    ) -> None:
-        """Create a new session."""
-
-    @abstractmethod
-    async def get_session(self, key: bytes) -> Session | None:
-        """Get session by key."""
-
-    @abstractmethod
-    async def delete_session(self, key: bytes) -> None:
-        """Delete session by key."""
-
-    @abstractmethod
-    async def update_session(
-        self,
-        key: bytes,
-        *,
-        ip: str,
-        user_agent: str,
-        renewed: datetime,
-    ) -> Session | None:
-        """Update session metadata and touch renewed timestamp."""
-
-    @abstractmethod
-    async def set_session_host(self, key: bytes, host: str) -> None:
-        """Bind a session to a specific host if not already set."""
-
-    @abstractmethod
-    async def list_sessions_for_user(self, user_uuid: UUID) -> list[Session]:
-        """Return all sessions for a user (including other hosts)."""
-
-    @abstractmethod
-    async def cleanup(self) -> None:
-        """Called periodically to clean up expired records."""
-
-    @abstractmethod
-    async def delete_sessions_for_user(self, user_uuid: UUID) -> None:
-        """Delete all sessions belonging to the provided user."""
-
-    # Reset token operations
-    @abstractmethod
-    async def create_reset_token(
-        self,
-        user_uuid: UUID,
-        key: bytes,
-        expiry: datetime,
-        token_type: str,
-    ) -> None:
-        """Create a reset token for a user."""
-
-    @abstractmethod
-    async def get_reset_token(self, key: bytes) -> ResetToken | None:
-        """Retrieve a reset token by key."""
-
-    @abstractmethod
-    async def delete_reset_token(self, key: bytes) -> None:
-        """Delete a reset token by key."""
-
-    # Organization operations
-    @abstractmethod
-    async def create_organization(self, org: Org) -> None:
-        """Add a new organization."""
-
-    @abstractmethod
-    async def get_organization(self, org_id: str) -> Org:
-        """Get organization by ID, including its permission IDs and roles (with their permission IDs)."""
-
-    @abstractmethod
-    async def list_organizations(self) -> list[Org]:
-        """List all organizations with their roles and permission IDs."""
-
-    @abstractmethod
-    async def update_organization(self, org: Org) -> None:
-        """Update organization options."""
-
-    @abstractmethod
-    async def delete_organization(self, org_uuid: UUID) -> None:
-        """Delete organization by ID."""
-
-    @abstractmethod
-    async def add_user_to_organization(
-        self, user_uuid: UUID, org_id: str, role: str
-    ) -> None:
-        """Set a user's organization and role."""
-
-    @abstractmethod
-    async def transfer_user_to_organization(
-        self, user_uuid: UUID, new_org_id: str, new_role: str | None = None
-    ) -> None:
-        """Transfer a user to another organization with an optional role."""
-
-    @abstractmethod
-    async def get_user_organization(self, user_uuid: UUID) -> tuple[Org, str]:
-        """Get the organization and role for a user."""
-
-    @abstractmethod
-    async def get_organization_users(self, org_id: str) -> list[tuple[User, str]]:
-        """Get all users in an organization with their roles."""
-
-    @abstractmethod
-    async def get_roles_by_organization(self, org_id: str) -> list[Role]:
-        """List roles belonging to an organization."""
-
-    @abstractmethod
-    async def get_user_role_in_organization(
-        self, user_uuid: UUID, org_id: str
-    ) -> str | None:
-        """Get a user's role in a specific organization."""
-
-    @abstractmethod
-    async def update_user_role_in_organization(
-        self, user_uuid: UUID, new_role: str
-    ) -> None:
-        """Update a user's role in their organization."""
-
-    # Permission operations
-    @abstractmethod
-    async def create_permission(self, permission: Permission) -> None:
-        """Create a new permission."""
-
-    @abstractmethod
-    async def get_permission(self, permission_id: str) -> Permission:
-        """Get permission by ID."""
-
-    @abstractmethod
-    async def list_permissions(self) -> list[Permission]:
-        """List all permissions."""
-
-    @abstractmethod
-    async def update_permission(self, permission: Permission) -> None:
-        """Update permission details."""
-
-    @abstractmethod
-    async def delete_permission(self, permission_id: str) -> None:
-        """Delete permission by ID."""
-
-    @abstractmethod
-    async def rename_permission(
-        self, old_id: str, new_id: str, display_name: str
-    ) -> None:
-        """Rename a permission's ID (and display name) updating all references.
-
-        This must update:
-            - permissions.id (primary key)
-            - org_permissions.permission_id
-            - role_permissions.permission_id
-        """
-
-    @abstractmethod
-    async def add_permission_to_organization(
-        self, org_id: str, permission_id: str
-    ) -> None:
-        """Add a permission to an organization."""
-
-    @abstractmethod
-    async def remove_permission_from_organization(
-        self, org_id: str, permission_id: str
-    ) -> None:
-        """Remove a permission from an organization."""
-
-    @abstractmethod
-    async def get_organization_permissions(self, org_id: str) -> list[Permission]:
-        """Get all permissions assigned to an organization."""
-
-    @abstractmethod
-    async def get_permission_organizations(self, permission_id: str) -> list[Org]:
-        """Get all organizations that have a specific permission."""
-
-    # Role-permission operations
-    @abstractmethod
-    async def add_permission_to_role(self, role_uuid: UUID, permission_id: str) -> None:
-        """Add a permission to a role."""
-
-    @abstractmethod
-    async def remove_permission_from_role(
-        self, role_uuid: UUID, permission_id: str
-    ) -> None:
-        """Remove a permission from a role."""
-
-    @abstractmethod
-    async def get_role_permissions(self, role_uuid: UUID) -> list[Permission]:
-        """List all permissions granted to a role."""
-
-    @abstractmethod
-    async def get_permission_roles(self, permission_id: str) -> list[Role]:
-        """List all roles that grant a permission."""
-
-    @abstractmethod
-    async def get_role(self, role_uuid: UUID) -> Role:
-        """Get a role by UUID, including its permission IDs."""
-
-    # Combined operations
-    @abstractmethod
-    async def login(self, user_uuid: UUID, credential: Credential) -> None:
-        """Update user and credential timestamps after successful login."""
-
-    @abstractmethod
-    async def create_user_and_credential(
-        self, user: User, credential: Credential
-    ) -> None:
-        """Create a new user and their first credential in a transaction."""
-
-    @abstractmethod
-    async def get_session_context(
-        self, session_key: bytes, host: str | None = None
-    ) -> SessionContext | None:
-        """Get complete session context including user, organization, role, and permissions."""
-
-    # Combined atomic operations
-    @abstractmethod
-    async def create_credential_session(
-        self,
-        user_uuid: UUID,
-        credential: Credential,
-        reset_key: bytes | None,
-        session_key: bytes,
-        *,
-        display_name: str | None = None,
-        host: str | None = None,
-        ip: str | None = None,
-        user_agent: str | None = None,
-    ) -> None:
-        """Atomically add a credential and create a session.
-
-        Steps (single transaction):
-            1. Insert credential
-            2. Optionally delete old reset token if provided
-            3. Optionally update user's display name
-            4. Insert new session referencing the credential
-            5. Update user's last_seen and increment visits (treat as a login)
-        """
 
 
 __all__ = [
-    "User",
+    # Types
+    "Config",
     "Credential",
-    "Session",
+    "DB",
-    "ResetToken",
+    "Client",
-    "SessionContext",
     "Org",
-    "Role",
     "Permission",
-    "DatabaseInterface",
+    "ResetToken",
+    "Role",
+    "Session",
+    "SessionContext",
+    "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_reset_token",
+    "create_role",
+    "create_user",
+    "delete_credential",
+    "delete_org",
+    "delete_permission",
+    "delete_reset_token",
+    "delete_role",
+    "delete_session",
+    "delete_sessions_for_user",
+    "delete_user",
+    "login",
+    "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_role_name",
+    "update_session",
+    "update_user_display_name",
+    "update_user_info",
+    "update_user_role",
+    "is_username_taken",
+    # OIDC
+    "create_oid_client",
+    "update_oid_client",
+    "reset_oid_client_secret",
+    "delete_oid_client",
 ]

paskia/db/background.py

@@ -0,0 +1,111 @@
+"""
+Background task for database maintenance.
+
+Periodically flushes pending changes to disk and cleans up expired items.
+"""
+
+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._db._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."""
+    # 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)
+            # 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
+
+            # Conditionally write a snapshot to speed up future startups
+            if _ops._db._store is not None:
+                _ops._db._store.maybe_snapshot()
+        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."""
+    global _background_task
+
+    # Check if task exists but is no longer running (e.g., after uvicorn reload)
+    if _background_task is not None:
+        if _background_task.done():
+            _logger.debug("Previous background task was done, restarting")
+            _background_task = None
+        else:
+            # Task exists and is running - but might be in a dead event loop
+            try:
+                # 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:
+                    _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
+            except Exception as e:
+                _logger.debug("Error checking background task loop: %s, restarting", e)
+                _background_task = None
+
+    if _background_task is None:
+        _background_task = asyncio.create_task(_background_loop())
+
+
+async def stop_background():
+    """Stop the background task, flush pending changes, and release the file lock."""
+    global _background_task
+    if _background_task:
+        _background_task.cancel()
+        try:
+            await _background_task
+        except asyncio.CancelledError:
+            pass
+        _background_task = None
+    _ops._db._store.close()
+
+
+# Aliases for backwards compatibility
+start_cleanup = start_background
+stop_cleanup = stop_background

paskia/db/bootstrap.py

@@ -0,0 +1,126 @@
+"""
+Bootstrap operations for initial system setup.
+"""
+
+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.util.crypto import secret_key
+
+
+def bootstrap(
+    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.
+
+    Creates:
+    - auth:admin permission (Master Admin)
+    - auth:org:admin permission (Org Admin)
+    - Organization with Administration role
+    - Admin user with Administration role
+    - 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:
+        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)
+        reset_expiry: Expiry datetime for the reset token (default: 14 days)
+        config: Configuration to store (rp_id, rp_name, origins, etc.)
+
+    Returns:
+        The reset passphrase for admin registration.
+    """
+
+    # Check if system is already bootstrapped
+    for p in _ops._db.permissions.values():
+        if p.scope == "auth:admin":
+            raise ValueError(
+                "System already bootstrapped (auth:admin permission exists)"
+            )
+
+    # Generate UUIDs upfront
+    now = datetime.now(UTC)
+    perm_admin_uuid = uuid7.create(now)
+    perm_org_admin_uuid = uuid7.create(now)
+    org_uuid = uuid7.create(now)
+    role_uuid = uuid7.create(now)
+    user_uuid = uuid7.create(now)
+
+    # Set reset token expiry (passphrase generated by ResetToken.create)
+    if reset_expiry is None:
+        reset_expiry = reset_expires()
+
+    with _ops._db.transaction("bootstrap"):
+        # Create auth:admin permission
+        perm_admin = Permission(
+            scope="auth:admin",
+            display_name="Master Admin",
+            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(
+            scope="auth:org:admin",
+            display_name="Org Admin",
+            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(
+            org_uuid=org_uuid,
+            display_name="Administration",
+            permissions={perm_admin_uuid: True, perm_org_admin_uuid: True},
+        )
+        admin_role.uuid = role_uuid
+        admin_role.store()
+
+        # Create admin user
+        admin_user = User(
+            display_name=admin_name,
+            role_uuid=role_uuid,
+            created_at=now,
+            last_seen=None,
+            visits=0,
+            theme="",
+        )
+        admin_user.uuid = user_uuid
+        admin_user.store()
+
+        # Create reset token
+        reset_token, reset_passphrase = ResetToken.create(
+            user=user_uuid,
+            expiry=reset_expiry,
+            token_type="admin bootstrap",
+            passphrase=reset_passphrase,
+        )
+        reset_token.store()
+
+        # Set config if provided
+        if config is not None:
+            _ops._db.config = config
+
+        # Generate OIDC signing key
+        _ops._db.oidc.key = secret_key()
+
+    return reset_passphrase

paskia/db/filelock.py

@@ -0,0 +1,247 @@
+"""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

@@ -0,0 +1,352 @@
+"""
+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.snapshot import SnapshotState
+from paskia.db.structs import DB, Config, SessionContext
+
+_logger = logging.getLogger(__name__)
+
+
+class ReplayResult(msgspec.Struct, frozen=False):
+    """Return value of _replay_from_data"""
+
+    state: dict = {}
+    v: int = 0
+    ts: datetime | None = None
+    snapts: datetime | None = None
+    changes: int = 0
+
+
+class DatabaseError(ValueError):
+    """Exception raised for database loading errors."""
+
+
+def _replay_from_data(data: bytes, db_path: str) -> ReplayResult:
+    """Replay database state from file data, using the last snapshot if available."""
+    resolved_path = str(Path(db_path).resolve())
+    result = ReplayResult()
+
+    # Find and apply the last snapshot
+    snap, start_offset = SnapshotState.load(data)
+    if snap:
+        result.state = snap.state
+        result.v = snap.v
+        result.snapts = snap.ts
+
+    # Replay change records after the snapshot
+    lines = data[start_offset:].split(b"\n")
+    for raw in lines:
+        line = raw.strip()
+        if not line:
+            continue
+        try:
+            change = msgspec.json.decode(line, type=ChangeRecord)
+        except msgspec.DecodeError as e:
+            raise DatabaseError(
+                f"{resolved_path}: {e}\n{line.decode(errors='replace')}"
+            )
+        result.state = jsondiff.patch(result.state, change.diff, marshal=True)
+        result.v = change.v
+        result.ts = change.ts
+        result.changes += 1
+
+    return result
+
+
+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))
+
+    try:
+        content = path.read_bytes()
+        r = _replay_from_data(content, str(path.resolve()))
+        data_dict = r.state
+        version = r.v
+
+        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
+        try:
+            return msgspec.json.decode(msgspec.json.encode(data_dict), type=DB)
+        except msgspec.ValidationError as e:
+            raise DatabaseError(f"{path.resolve()}: {e}") from None
+    except OSError as e:
+        _logger.exception("Failed to load database")
+        raise SystemExit(f"{e}")
+    except (ValueError, msgspec.DecodeError) as e:
+        raise SystemExit(f"{e}")
+    except Exception as e:
+        _logger.exception("Unexpected error loading database")
+        raise SystemExit(f"{e}")
+
+
+class ChangeRecord(msgspec.Struct, omit_defaults=True, kw_only=True):
+    ts: datetime = msgspec.field(default_factory=lambda: datetime.now(UTC))
+    a: str = ""  # action (e.g., "migrate", "login", "create_user")
+    v: int = 0  # schema version after this change
+    u: str | None = None  # user UUID who performed the action (None for system)
+    diff: dict
+
+
+def compute_diff(previous: dict, current: dict) -> dict | None:
+    return jsondiff.diff(previous, current, marshal=True) or None
+
+
+# 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):
+        self.db: DB = db
+        self.db_path = Path(db_path)
+        self._file = LockedFile()
+        self._flush_failed = False
+        self._statedict: 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._v: int = DBVER  # Schema version for new databases
+        self._snapshot = SnapshotState()
+
+    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 (snapshot-accelerated)
+        try:
+            r = _replay_from_data(content, str(self.db_path.resolve()))
+            statedict = r.state
+            self._v = r.v
+            self._snapshot.ts = r.snapts
+            self._snapshot.changes = r.changes
+        except (OSError, ValueError, msgspec.DecodeError, DatabaseError) as e:
+            raise SystemExit(f"{e}")
+        except Exception as e:
+            _logger.exception("Unexpected error loading database")
+            raise SystemExit(f"{e}")
+
+        if not statedict:
+            return
+
+        # Set previous state for diffing (will be updated by _queue_change)
+        self._statedict = copy.deepcopy(statedict)
+
+        # Callback to persist each migration
+        async def persist_migration(
+            action: str, new_version: int, current: dict
+        ) -> None:
+            self._v = new_version
+            self._queue_change(action, new_version, current)
+
+        # Apply schema migrations one at a time
+        await apply_all_migrations(
+            statedict,
+            self._v,
+            persist_migration,
+            MigrationCtx(rp_id=rp_id),
+        )
+
+        # Decode to msgspec struct
+        decoder = msgspec.json.Decoder(DB)
+        self.db = decoder.decode(msgspec.json.encode(statedict))
+        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._v, 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._statedict, current)
+        if not diff:
+            return
+        self._pending_changes.append(
+            ChangeRecord(
+                a=action,
+                v=version,
+                u=user,
+                diff=diff,
+            )
+        )
+
+        # 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._statedict, self.db)
+        self._statedict = 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._statedict:
+            # Allow bootstrap to create a new database from empty state
+            is_bootstrap = action in _BOOTSTRAP_ACTIONS
+            if is_bootstrap and not self._statedict:
+                pass  # Expected: creating database from scratch
+            else:
+                diff = compute_diff(self._statedict, 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._v, 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 = [msgspec.json.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._snapshot.record_lines(len(lines))
+            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 maybe_snapshot(self) -> None:
+        """Write a snapshot if conditions are met."""
+        self._snapshot.maybe_write(self._file, self._v, self._statedict)
+
+    def close(self) -> None:
+        """Release the file lock and close the file."""
+        self._file.close()

paskia/db/lifecycle.py

@@ -0,0 +1,47 @@
+"""
+Database lifecycle: initialization and maintenance.
+"""
+
+import logging
+from datetime import UTC, datetime
+
+import paskia.db.operations as _ops
+from paskia import oidc_notify
+from paskia.authsession import EXPIRES
+from paskia.db.jsonl import JsonlStore
+from paskia.db.paths import db_file_path
+
+_logger = logging.getLogger(__name__)
+
+
+async def init(rp_id: str, *args, **kwargs):
+    """Load database from JSONL file."""
+    if _ops._db._store:
+        _logger.debug("Database already initialized, skipping reload")
+        return
+    db_path = db_file_path(rp_id=rp_id, create_root=True)
+    store = JsonlStore(_ops._db, str(db_path))
+    await store.load(str(db_path), rp_id=rp_id)
+    _ops._db = store.db
+    _ops._db._store = store
+    # Request a snapshot after successful startup
+    store._snapshot.request_force()
+
+
+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"):
+        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 count

paskia/db/logging.py

@@ -0,0 +1,466 @@
+"""
+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"
+_SEP = "\033[38;5;242m"  # Dark grey for separators (like host/timing in access log)
+_PATH_PREFIX = "\033[38;5;242m"  # Dark grey for path prefix (like host in access log)
+_PATH_FINAL = "\033[38;5;250m"  # 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"{_SEP}<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} {_SEP}={_RESET}")
+            else:
+                prefix = ".".join(formatted_path[:-1])
+                final = formatted_path[-1]
+                lines.append(
+                    f"  {_PATH_PREFIX}{prefix}.{_RESET}{_ADD}{final}{_RESET} {_SEP}={_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}{_SEP}:{_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} {_SEP}={_RESET} {value_str}"
+                ]
+            prefix = ".".join(formatted_path[:-1])
+            final = formatted_path[-1]
+            return [
+                f"  {_PATH_PREFIX}{prefix}.{_RESET}{_ADD}{final}{_RESET} {_SEP}={_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} {_SEP}={_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

@@ -0,0 +1,87 @@
+"""
+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()}
+
+
+def migrate_v5(d: dict, ctx: MigrationCtx) -> None:
+    """Convert config.listen from str to list[str] if needed."""
+    listen = d["config"].get("listen")
+    if listen and isinstance(listen, str):
+        d["config"]["listen"] = [listen]
+
+
+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

@@ -0,0 +1,778 @@
+"""
+Database for WebAuthn passkey authentication.
+
+Read operations: Access _db directly, use build_* helpers to get public structs.
+Context lookup: _db.session_ctx() returns full SessionContext with effective permissions.
+Write operations: Functions that validate and commit, or raise ValueError.
+"""
+
+import logging
+import secrets
+from datetime import UTC, datetime, timedelta
+from uuid import UUID
+
+import uuid7
+
+from paskia import oidc_notify
+from paskia.config import SESSION_LIFETIME
+from paskia.db.structs import (
+    DB,
+    Client,
+    Config,
+    Credential,
+    Org,
+    Permission,
+    ResetToken,
+    Role,
+    Session,
+    SessionContext,
+    User,
+)
+from paskia.util.crypto import hash_secret
+from paskia.util.nameutil import slugify_name
+
+_logger = logging.getLogger(__name__)
+
+# Sentinel for distinguishing "not provided" from None
+_UNSET = object()
+
+# Global database instance (empty until init() loads data)
+_db = DB(config=Config(rp_id="uninitialized.invalid"))
+
+
+def is_username_taken(username: str, exclude_uuid: UUID | None = None) -> bool:
+    """Check if a preferred_username is already taken by another user."""
+    if not username:
+        return False
+    for user in _db.users.values():
+        if user.preferred_username == username:
+            if exclude_uuid is None or user.uuid != exclude_uuid:
+                return True
+    return False
+
+
+# -------------------------------------------------------------------------
+# Write operations (validate, modify, commit or raise ValueError)
+# -------------------------------------------------------------------------
+
+
+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):
+        perm.store()
+
+
+def update_permission(
+    uuid: UUID,
+    scope: str,
+    display_name: str,
+    domain: str | None = None,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Update a permission's scope, display_name, and domain.
+
+    Only these fields can be modified; created_at and other metadata remain immutable.
+    """
+    if uuid not in _db.permissions:
+        raise ValueError(f"Permission {uuid} not found")
+    with _db.transaction("admin:update_permission", ctx):
+        _db.permissions[uuid].scope = scope
+        _db.permissions[uuid].display_name = display_name
+        _db.permissions[uuid].domain = domain
+
+
+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):
+        _db.permissions[uuid].delete()
+
+
+def create_org(org: Org, *, ctx: SessionContext | None = None) -> None:
+    """Create a new organization with an Administration role.
+
+    Automatically creates an 'Administration' role with auth:org:admin permission.
+    """
+    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):
+        new_org = Org.create(display_name=org.display_name, created_at=now)
+        new_org.uuid = org.uuid
+        new_org.store()
+        # Create Administration role with org admin permission
+
+        admin_role_uuid = uuid7.create(now)
+        # Find the auth:org:admin permission UUID
+        org_admin_perm_uuid = None
+        for pid, p in _db.permissions.items():
+            if p.scope == "auth:org:admin":
+                org_admin_perm_uuid = pid
+                break
+        role_permissions = {org_admin_perm_uuid: True} if org_admin_perm_uuid else {}
+        admin_role = Role(
+            org_uuid=org.uuid,
+            display_name="Administration",
+            permissions=role_permissions,
+        )
+        admin_role.uuid = admin_role_uuid
+        admin_role.store()
+
+
+def update_org_name(
+    uuid: UUID,
+    display_name: str,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """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):
+        _db.orgs[uuid].display_name = display_name
+
+
+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):
+        _db.orgs[uuid].delete()
+
+
+def add_permission_to_org(
+    org_uuid: UUID,
+    permission_uuid: UUID,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Grant a permission to an organization by UUID."""
+    if org_uuid not in _db.orgs:
+        raise ValueError(f"Organization {org_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_org", ctx):
+        _db.permissions[permission_uuid].orgs[org_uuid] = True
+
+
+def remove_permission_from_org(
+    org_uuid: UUID,
+    permission_uuid: UUID,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Remove a permission from an organization by UUID."""
+    if org_uuid not in _db.orgs:
+        raise ValueError(f"Organization {org_uuid} not found")
+
+    if permission_uuid not in _db.permissions:
+        return  # Permission not found, silently return
+
+    with _db.transaction("admin:remove_permission_from_org", ctx):
+        _db.permissions[permission_uuid].orgs.pop(org_uuid, None)
+
+
+def create_role(role: Role, *, ctx: SessionContext | None = None) -> None:
+    """Create a new role."""
+    if role.uuid in _db.roles:
+        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):
+        role.store()
+
+
+def update_role_name(
+    uuid: UUID,
+    display_name: str,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """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):
+        _db.roles[uuid].display_name = display_name
+
+
+def add_permission_to_role(
+    role_uuid: UUID,
+    permission_uuid: UUID,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Add permission to role by UUID."""
+    if role_uuid not in _db.roles:
+        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):
+        _db.roles[role_uuid].permissions[permission_uuid] = True
+
+
+def remove_permission_from_role(
+    role_uuid: UUID,
+    permission_uuid: UUID,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """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):
+        _db.roles[role_uuid].permissions.pop(permission_uuid, None)
+
+
+def delete_role(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
+    """Delete a role."""
+    if uuid not in _db.roles:
+        raise ValueError(f"Role {uuid} not found")
+    # Check no users have this role
+    role = _db.roles[uuid]
+    if role.users:
+        raise ValueError(f"Cannot delete role {uuid}: users still assigned")
+    with _db.transaction("admin:delete_role", ctx):
+        _db.roles[uuid].delete()
+
+
+def create_user(new_user: User, *, ctx: SessionContext | None = None) -> None:
+    """Create a new user."""
+    if new_user.uuid in _db.users:
+        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):
+        new_user.store()
+
+
+def update_user_display_name(
+    uuid: UUID,
+    display_name: str,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Update user display name.
+
+    The acting user should be logged via ctx.
+    For self-service (user updating own name), pass user's ctx.
+    For admin operations, pass admin's ctx.
+
+    If the user's preferred_username is currently None, this will auto-fill it
+    with a slugified version of the display name (if unique and non-empty).
+    """
+    if isinstance(uuid, str):
+        uuid = UUID(uuid)
+    if uuid not in _db.users:
+        raise ValueError(f"User {uuid} not found")
+    display_name = (display_name or "").strip()
+    if not display_name:
+        raise ValueError("Display name cannot be empty")
+    user = _db.users[uuid]
+    with _db.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:
+            slug = slugify_name(display_name)
+            if slug and not is_username_taken(slug, exclude_uuid=uuid):
+                user.preferred_username = slug
+
+
+def update_user_info(
+    uuid: UUID,
+    *,
+    display_name: str | object = _UNSET,
+    theme: str | object = _UNSET,
+    email: str | None | object = _UNSET,
+    preferred_username: str | None | object = _UNSET,
+    telephone: str | None | object = _UNSET,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Update user profile information.
+
+    Pass only the fields you want to update. Use None to clear optional fields.
+    This does NOT auto-fill preferred_username - use update_user_display_name
+    for the registration flow where auto-fill is desired.
+
+    Args:
+        uuid: User UUID
+        display_name: User display name (cannot be empty)
+        theme: Theme preference ('' for auto, 'light', 'dark')
+        email: Email address (None to clear)
+        preferred_username: Username for OIDC claims (None to clear, must be unique)
+        telephone: Phone number (None to clear)
+        ctx: Session context for audit logging
+    """
+    if isinstance(uuid, str):
+        uuid = UUID(uuid)
+    if uuid not in _db.users:
+        raise ValueError(f"User {uuid} not found")
+
+    user = _db.users[uuid]
+
+    # Validate all fields before transaction
+    if display_name is not _UNSET:
+        display_name = (display_name or "").strip()
+        if not display_name:
+            raise ValueError("Display name cannot be empty")
+
+    if theme is not _UNSET:
+        if theme not in ("", "light", "dark"):
+            raise ValueError(f"Invalid theme: {theme}")
+
+    if email is not _UNSET and email is not None:
+        email = (email or "").strip()
+        if not email:
+            email = None
+        elif "@" not in email or len(email) > 254:
+            raise ValueError("Invalid email format")
+
+    if preferred_username is not _UNSET and preferred_username is not None:
+        preferred_username = (preferred_username or "").strip()
+        if not preferred_username:
+            raise ValueError("Preferred username cannot be empty (use None to clear)")
+        if len(preferred_username) > 128:
+            raise ValueError("preferred_username too long")
+        if is_username_taken(preferred_username, exclude_uuid=uuid):
+            raise ValueError("Username already taken")
+
+    if telephone is not _UNSET and telephone is not None:
+        telephone = (telephone or "").strip()
+        if not telephone:
+            telephone = None
+        elif len(telephone) > 32:
+            raise ValueError("telephone too long")
+
+    with _db.transaction("update_user_info", ctx):
+        if display_name is not _UNSET:
+            user.display_name = display_name
+        if theme is not _UNSET:
+            user.theme = theme
+        if email is not _UNSET:
+            user.email = email
+        if preferred_username is not _UNSET:
+            user.preferred_username = preferred_username
+        if telephone is not _UNSET:
+            user.telephone = telephone
+
+
+def update_user_role(
+    uuid: UUID,
+    role_uuid: UUID,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Update user's role."""
+    if uuid not in _db.users:
+        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):
+        _db.users[uuid].role_uuid = role_uuid
+
+
+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):
+        _db.users[uuid].delete()
+
+
+def create_credential(cred: Credential, *, ctx: SessionContext | None = None) -> None:
+    """Create a new credential."""
+    if cred.uuid in _db.credentials:
+        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):
+        cred.store()
+
+
+def update_credential_sign_count(
+    uuid: UUID,
+    sign_count: int,
+    last_used: datetime | None = None,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """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):
+        _db.credentials[uuid].sign_count = sign_count
+        if last_used:
+            _db.credentials[uuid].last_used = last_used
+
+
+def delete_credential(
+    uuid: UUID,
+    user_uuid: UUID | None = None,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Delete a credential and all sessions using it.
+
+    If user_uuid is provided, validates that the credential belongs to that user.
+    """
+    if uuid not in _db.credentials:
+        raise ValueError(f"Credential {uuid} not found")
+    cred = _db.credentials[uuid]
+    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):
+        cred.delete()
+
+
+def update_session(
+    key: str,
+    host: str | None = None,
+    ip: str | None = None,
+    user_agent: str | None = None,
+    validated: datetime | 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):
+        s = _db.sessions[key]
+        if host is not None:
+            s.host = host
+        if ip is not None:
+            s.ip = ip
+        if user_agent is not None:
+            s.user_agent = user_agent
+        if validated is not None:
+            s.validated = validated
+
+
+def set_session_host(key: str, 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(
+    key: str, *, ctx: SessionContext | None = None, action: str = "delete_session"
+) -> None:
+    """Delete a session.
+
+    The acting user should be logged via ctx.
+    For user logout, pass ctx of the user's session and action="logout".
+    For admin terminating a session, pass admin's ctx.
+    """
+    if key not in _db.sessions:
+        raise ValueError("Session not found")
+
+    oidc_notify.schedule_notifications([key])
+    with _db.transaction(action, ctx):
+        _db.sessions[key].delete()
+
+
+def delete_sessions_for_user(
+    user_uuid: UUID, *, ctx: SessionContext | None = None
+) -> None:
+    """Delete all sessions for a user.
+
+    The acting user should be logged via ctx.
+    For user logout-all, pass ctx of the user's session.
+    For admin bulk termination, pass admin's ctx.
+    """
+    user = _db.users.get(user_uuid)
+    if not user:
+        return
+
+    keys = [s.key for s in user.sessions]
+    oidc_notify.schedule_notifications(keys)
+    with _db.transaction("admin:delete_sessions_for_user", ctx):
+        for sess in user.sessions:
+            sess.delete()
+
+
+def create_reset_token(
+    user_uuid: UUID,
+    expiry: datetime,
+    token_type: str,
+    *,
+    ctx: SessionContext | None = None,
+    user: str | None = None,
+) -> str:
+    """Create a reset token and return the passphrase.
+
+    The acting user should be logged via ctx.
+    For self-service (user creating own recovery link), pass user's ctx.
+    For admin operations, pass admin's ctx.
+    For system operations (bootstrap), pass neither to log no user.
+    For API operations where ctx is not available but user is known, pass user.
+
+    Returns:
+        The passphrase to give to the user.
+    """
+    if user_uuid not in _db.users:
+        raise ValueError(f"User {user_uuid} not found")
+    token, passphrase = ResetToken.create(
+        user=user_uuid, expiry=expiry, token_type=token_type
+    )
+    if token.key in _db.reset_tokens:
+        raise ValueError("Reset token already exists")
+    with _db.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)
+# -------------------------------------------------------------------------
+
+
+def login(
+    user_uuid: UUID,
+    credential_uuid: UUID,
+    sign_count: int,
+    host: str,
+    ip: str,
+    user_agent: str,
+    duration: timedelta = SESSION_LIFETIME,
+) -> str:
+    """Update user/credential on login and create session in a single transaction.
+
+    Updates:
+    - user.last_seen, user.visits
+    - credential.sign_count, credential.last_used
+    Creates:
+    - new session
+
+    Returns the generated session token.
+    """
+    if isinstance(user_uuid, str):
+        user_uuid = UUID(user_uuid)
+    now = datetime.now(UTC)
+    if user_uuid not in _db.users:
+        raise ValueError(f"User {user_uuid} not found")
+    if credential_uuid not in _db.credentials:
+        raise ValueError(f"Credential {credential_uuid} not found")
+
+    # Generate token and derive key
+    token = secrets.token_urlsafe(12)
+
+    session = Session.create(
+        user=user_uuid,
+        credential=credential_uuid,
+        key=hash_secret("cookie", token),
+        host=host,
+        ip=ip,
+        user_agent=user_agent,
+        validated=now,
+    )
+    user_str = str(user_uuid)
+    with _db.transaction("login", user=user_str):
+        session.store(now)
+        # Update credential
+        _db.credentials[credential_uuid].sign_count = sign_count
+        _db.credentials[credential_uuid].last_used = now
+    return token
+
+
+def oidc_login(
+    session: Session,
+    credential_uuid: UUID,
+    sign_count: int,
+) -> None:
+    """Store an OIDC session and update credential in a single transaction.
+
+    The caller is responsible for generating the token, deriving the key,
+    and creating the Session object.  This function only handles the
+    database transaction.
+
+    Updates:
+    - user.last_seen, user.visits
+    - credential.sign_count, credential.last_used
+    Stores:
+    - the provided session
+    """
+    now = datetime.now(UTC)
+    user_str = str(session.user_uuid)
+    with _db.transaction("oidc_login", user=user_str):
+        session.store(now)
+        # Update credential
+        _db.credentials[credential_uuid].sign_count = sign_count
+        _db.credentials[credential_uuid].last_used = now
+
+
+def create_credential_session(
+    user_uuid: UUID,
+    credential: Credential,
+    host: str,
+    ip: str,
+    user_agent: str,
+    display_name: str | None = None,
+    reset_key: bytes | None = None,
+) -> str:
+    """Create a credential and session together, optionally consuming a reset token.
+
+    Used during registration to atomically:
+    1. Update user display_name if provided
+    2. Create the credential
+    3. Create the session
+    4. Delete the reset token if provided
+
+    Returns the generated session token.
+    """
+
+    now = datetime.now(UTC)
+
+    if user_uuid not in _db.users:
+        raise ValueError(f"User {user_uuid} not found")
+
+    # Generate token and derive key
+    token = secrets.token_urlsafe(12)
+    key = hash_secret("cookie", token)
+
+    session = Session.create(
+        user=user_uuid,
+        credential=credential.uuid,
+        key=key,
+        host=host,
+        ip=ip,
+        user_agent=user_agent,
+        validated=now,
+    )
+    user_str = str(user_uuid)
+    with _db.transaction("create_credential_session", user=user_str):
+        # Update display name if provided
+        if display_name:
+            _db.users[user_uuid].display_name = display_name
+
+        # Align credential timestamps with transaction time
+        credential.created_at = now
+        credential.last_used = now
+        credential.last_verified = now
+
+        # Create credential
+        credential.store()
+
+        # Store session and record visit
+        session.store(now)
+
+        # Delete reset token if provided
+        if reset_key:
+            reset_token = _db.reset_tokens.get(reset_key)
+            if reset_token:
+                reset_token.delete()
+    return token
+
+
+# -------------------------------------------------------------------------
+# OIDC Provider operations
+# -------------------------------------------------------------------------
+
+
+def create_oid_client(client: Client, *, ctx: SessionContext | None = None) -> None:
+    """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):
+        _db.oidc.clients[client.uuid] = client
+
+
+def update_oid_client(
+    client_uuid: UUID,
+    name: str | None = None,
+    redirect_uris: list[str] | None = None,
+    secret_hash: bytes | None = None,
+    backchannel_logout_uri: str | None = _UNSET,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Update an OIDC client's name, redirect URIs, and/or secret."""
+    if client_uuid not in _db.oidc.clients:
+        raise ValueError(f"OIDC client {client_uuid} not found")
+
+    client = _db.oidc.clients[client_uuid]
+    changes = {}
+
+    if name is not None and name != client.name:
+        changes["name"] = name
+    if redirect_uris is not None and redirect_uris != client.redirect_uris:
+        changes["redirect_uris"] = redirect_uris
+    if secret_hash is not None and secret_hash != client.client_secret_hash:
+        changes["client_secret_hash"] = secret_hash
+    if (
+        backchannel_logout_uri is not _UNSET
+        and backchannel_logout_uri != client.backchannel_logout_uri
+    ):
+        changes["backchannel_logout_uri"] = backchannel_logout_uri
+
+    if not changes:
+        return  # No changes to make
+
+    new_logout_uri = (
+        backchannel_logout_uri
+        if backchannel_logout_uri is not _UNSET
+        else client.backchannel_logout_uri
+    )
+
+    with _db.transaction("admin:update_oid_client", ctx):
+        # Create updated client with new values
+        updated_client = Client(
+            client_secret_hash=secret_hash
+            if secret_hash is not None
+            else client.client_secret_hash,
+            name=name if name is not None else client.name,
+            redirect_uris=redirect_uris
+            if redirect_uris is not None
+            else client.redirect_uris,
+            backchannel_logout_uri=new_logout_uri,
+        )
+        updated_client.uuid = client.uuid
+        _db.oidc.clients[client_uuid] = updated_client
+
+
+def reset_oid_client_secret(
+    client_uuid: UUID,
+    new_secret_hash: bytes,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Reset an OIDC client's 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):
+        updated = Client(
+            client_secret_hash=new_secret_hash,
+            name=client.name,
+            redirect_uris=client.redirect_uris,
+            backchannel_logout_uri=client.backchannel_logout_uri,
+        )
+        updated.uuid = client.uuid
+        _db.oidc.clients[client_uuid] = updated
+
+
+def delete_oid_client(client_uuid: UUID, *, ctx: SessionContext | None = 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):
+        del _db.oidc.clients[client_uuid]

paskia/db/paths.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+
+def db_root_path(*, rp_id: str = "localhost") -> Path:
+    """Return the configured persistence root directory."""
+    return Path(os.environ.get("PASKIA_DB", f"{rp_id}.paskiadb"))
+
+
+def db_file_path(*, rp_id: str = "localhost", create_root: bool = False) -> Path:
+    """Return the JSONL database file path under the persistence root."""
+    root = db_root_path(rp_id=rp_id)
+
+    if root.is_file():
+        _migrate_legacy_db_file(root)
+
+    if create_root:
+        root.mkdir(parents=True, exist_ok=True)
+
+    return root / "main.db"
+
+
+def users_root_path(*, rp_id: str = "localhost", create_root: bool = False) -> Path:
+    """Return the filesystem root for persisted user files."""
+    root = db_root_path(rp_id=rp_id)
+
+    if root.is_file():
+        _migrate_legacy_db_file(root)
+
+    if create_root:
+        root.mkdir(parents=True, exist_ok=True)
+
+    return root / "users"
+
+
+def _migrate_legacy_db_file(legacy_path: Path) -> None:
+    """Upgrade a legacy single-file database path into a directory root."""
+    temp_root = legacy_path.parent / f".{legacy_path.name}.migrating"
+    shutil.rmtree(temp_root, ignore_errors=True)
+    temp_root.unlink(missing_ok=True)
+
+    temp_root.mkdir(parents=True)
+    legacy_path.replace(temp_root / "main.db")
+    temp_root.rename(legacy_path)

paskia/db/snapshot.py

@@ -0,0 +1,88 @@
+"""
+Snapshot handling for JSONL database persistence.
+"""
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+import msgspec
+
+_logger = logging.getLogger(__name__)
+
+LINEPREFIX = b"SNAPSHOT "
+MINDIFFS = 100
+
+
+class Snapshot(msgspec.Struct):
+    """Snapshot data structure for database persistence."""
+
+    ts: datetime
+    v: int
+    state: dict[str, Any]
+
+
+class SnapshotState:
+    """Tracks snapshot timing and line counts for a database file."""
+
+    def __init__(self) -> None:
+        self.ts: datetime | None = None
+        self.changes: int = 0
+        self._force_pending: bool = False
+
+    def request_force(self) -> None:
+        """Request a forced snapshot on the next maybe_write call."""
+        self._force_pending = True
+
+    def record_lines(self, count: int) -> None:
+        self.changes += count
+
+    def maybe_write(self, file, version: int, state: dict) -> None:
+        """Write a snapshot if conditions are met (enough changes, and Sunday UTC or forced)."""
+        if self.changes < MINDIFFS:
+            return
+        force = self._force_pending
+        now = datetime.now(UTC)
+        if not force and now.weekday() != 6:  # 6 = Sunday
+            return
+        sunday_midnight = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        if not force and self.ts is not None and self.ts >= sunday_midnight:
+            return
+        if not file.is_open:
+            return
+        try:
+            self._write(file, version, state, now)
+            self._force_pending = False
+        except Exception as exc:
+            _logger.error("snapshot: failed to write snapshot: %r", exc)
+
+    def _write(self, file, version: int, state: dict, now: datetime) -> None:
+        """Write a snapshot and update internal state."""
+        data = msgspec.json.encode(Snapshot(ts=now, v=version, state=state))
+        file.write(LINEPREFIX + data + b"\n")
+        self.changes = 0
+        self.ts = now
+
+    @staticmethod
+    def load(data: bytes) -> tuple[Snapshot | None, int]:
+        """Find and parse the last snapshot in file data.
+
+        Returns (snapshot, replay_offset) where replay_offset is the byte
+        position to start replaying change records from. If no valid snapshot
+        is found, returns (None, 0).
+        """
+        marker = b"\n" + LINEPREFIX
+        pos = data.rfind(marker)
+        if pos != -1:
+            pos += 1  # skip the newline
+        elif data.startswith(LINEPREFIX):
+            pos = 0
+        else:
+            return None, 0
+
+        end = data.find(b"\n", pos)
+        if end == -1:
+            raise ValueError("Incomplete snapshot line at end of file")
+
+        snap = msgspec.json.decode(data[pos + len(LINEPREFIX) : end], type=Snapshot)
+        return snap, end + 1

paskia/db/structs.py

@@ -0,0 +1,719 @@
+from __future__ import annotations
+
+import hashlib
+import secrets
+from datetime import UTC, datetime
+from uuid import UUID
+
+import msgspec
+import uuid7
+
+from paskia import db
+from paskia.util import passphrase as passphrase_util
+from paskia.util.crypto import hash_secret
+
+# Sentinel for uuid fields before they are set by create() or DB post init
+_UUID_UNSET = UUID(int=0)
+
+
+class Permission(msgspec.Struct, dict=True, omit_defaults=True):
+    """Permission data structure.
+
+    Mutable fields: scope, display_name, domain, orgs
+    Immutable fields: None (all fields can be updated via update_permission)
+    uuid is generated at creation.
+    """
+
+    scope: str  # Permission scope identifier (e.g. "auth:admin", "myapp:write")
+    display_name: str
+    domain: str | None = None  # If set, scopes permission to this domain
+    orgs: dict[UUID, bool] = {}  # org_uuid -> True (which orgs can grant this)
+
+    def __post_init__(self):
+        if not hasattr(self, "uuid"):
+            self.uuid: UUID = _UUID_UNSET
+
+    @property
+    def org_set(self) -> set[UUID]:
+        """Get orgs that can grant this permission as a set."""
+        return set(self.orgs.keys())
+
+    @property
+    def orgs_list(self) -> list[Org]:
+        """Get list of Org objects that can grant this permission."""
+        return [
+            db.data().orgs[org_uuid]
+            for org_uuid in self.orgs.keys()
+            if org_uuid in db.data().orgs
+        ]
+
+    def store(self) -> None:
+        """Store this permission in the database. Must be called inside a transaction."""
+        db.data().permissions[self.uuid] = self
+
+    def delete(self) -> None:
+        """Delete this permission and remove it from all roles.
+
+        Must be called inside a transaction.
+        """
+        _data = db.data()
+        for role in _data.roles.values():
+            role.permissions.pop(self.uuid, None)
+        del _data.permissions[self.uuid]
+
+    @classmethod
+    def create(
+        cls,
+        scope: str,
+        display_name: str,
+        domain: str | None = None,
+        created_at: datetime | None = None,
+    ) -> Permission:
+        """Create a new Permission with auto-generated uuid7."""
+        now = created_at or datetime.now(UTC)
+        perm = cls(
+            scope=scope,
+            display_name=display_name,
+            domain=domain,
+        )
+        perm.uuid = uuid7.create(now)
+        return perm
+
+
+class Org(msgspec.Struct, dict=True):
+    """Organization data structure."""
+
+    display_name: str
+
+    def __post_init__(self):
+        if not hasattr(self, "uuid"):
+            self.uuid: UUID = _UUID_UNSET
+
+    @property
+    def roles(self) -> list[Role]:
+        """Get all roles that belong to this organization."""
+        return [r for r in db.data().roles.values() if r.org_uuid == self.uuid]
+
+    @property
+    def permissions(self) -> list[Permission]:
+        """Get all permissions that this organization can grant."""
+        return [p for p in db.data().permissions.values() if self.uuid in p.orgs]
+
+    def store(self) -> None:
+        """Store this organization in the database. Must be called inside a transaction."""
+        db.data().orgs[self.uuid] = self
+
+    def delete(self) -> None:
+        """Delete this org and cascade to roles, users. Remove from permissions.
+
+        Must be called inside a transaction.
+        """
+        _data = db.data()
+        for p in _data.permissions.values():
+            p.orgs.pop(self.uuid, None)
+        for role in self.roles:
+            for user in role.users:
+                del _data.users[user.uuid]
+            del _data.roles[role.uuid]
+        del _data.orgs[self.uuid]
+
+    @classmethod
+    def create(cls, display_name: str, created_at: datetime | None = None) -> Org:
+        """Create a new Org with auto-generated uuid7."""
+        now = created_at or datetime.now(UTC)
+        org = cls(display_name=display_name)
+        org.uuid = uuid7.create(now)
+        return org
+
+
+class Role(msgspec.Struct, dict=True, omit_defaults=True):
+    """Role data structure.
+
+    Mutable fields: display_name, permissions
+    Immutable fields: org_uuid (set at creation, never modified)
+    uuid is generated at creation.
+    """
+
+    org_uuid: UUID = msgspec.field(name="org")
+    display_name: str
+    permissions: dict[UUID, bool] = {}  # permission_uuid -> True
+
+    def __post_init__(self):
+        if not hasattr(self, "uuid"):
+            self.uuid: UUID = _UUID_UNSET
+
+    @property
+    def permission_set(self) -> set[UUID]:
+        """Get permissions as a set of UUIDs."""
+        return set(self.permissions.keys())
+
+    @property
+    def permissions_list(self) -> list[Permission]:
+        """Get list of Permission objects for this role."""
+        return [
+            db.data().permissions[perm_uuid]
+            for perm_uuid in self.permissions.keys()
+            if perm_uuid in db.data().permissions
+        ]
+
+    @property
+    def org(self) -> Org:
+        """Get the organization object this role belongs to."""
+        return db.data().orgs[self.org_uuid]
+
+    @property
+    def users(self) -> list[User]:
+        """Get all users that have this role."""
+        return [u for u in db.data().users.values() if u.role_uuid == self.uuid]
+
+    def store(self) -> None:
+        """Store this role in the database. Must be called inside a transaction."""
+        db.data().roles[self.uuid] = self
+
+    def delete(self) -> None:
+        """Delete this role from the database. Must be called inside a transaction."""
+        del db.data().roles[self.uuid]
+
+    @classmethod
+    def create(
+        cls,
+        org: UUID | Org,
+        display_name: str,
+        permissions: set[UUID] | None = None,
+        created_at: datetime | None = None,
+    ) -> Role:
+        """Create a new Role with auto-generated uuid7."""
+        now = created_at or datetime.now(UTC)
+        org_uuid = org if isinstance(org, UUID) else org.uuid
+        role = cls(
+            org_uuid=org_uuid,
+            display_name=display_name,
+            permissions={p: True for p in (permissions or set())},
+        )
+        role.uuid = uuid7.create(now)
+        return role
+
+
+class User(msgspec.Struct, dict=True, omit_defaults=True, kw_only=True):
+    """User data structure.
+
+    Mutable fields: display_name, role_uuid, last_seen, visits, theme, email, preferred_username
+    Immutable fields: created_at (set at creation, never modified)
+    uuid is derived from created_at using uuid7.
+    """
+
+    display_name: str
+    role_uuid: UUID = msgspec.field(name="role")
+    created_at: datetime
+    visits: int
+    last_seen: datetime | None = None
+    theme: str = ""
+    email: str | None = None  # OIDC email claim
+    preferred_username: str | None = None  # OIDC preferred_username claim
+    telephone: str | None = None  # Telephone number
+
+    def __post_init__(self):
+        if not hasattr(self, "uuid"):
+            self.uuid: UUID = _UUID_UNSET
+
+    @property
+    def role(self) -> Role:
+        """Get the role object this user has."""
+        return db.data().roles[self.role_uuid]
+
+    @property
+    def org(self) -> Org:
+        """Get the organization this user belongs to (via role)."""
+        return self.role.org
+
+    @property
+    def credentials(self) -> list[Credential]:
+        """Get all credentials for this user."""
+        return [c for c in db.data().credentials.values() if c.user_uuid == self.uuid]
+
+    @property
+    def credential_ids(self) -> list[bytes]:
+        """Get credential IDs for this user (for WebAuthn exclude lists)."""
+        return [c.credential_id for c in self.credentials]
+
+    @property
+    def sessions(self) -> list[Session]:
+        """Get all sessions for this user."""
+        return [s for s in db.data().sessions.values() if s.user_uuid == self.uuid]
+
+    @property
+    def reset_tokens(self) -> list[ResetToken]:
+        """Get all reset tokens for this user."""
+        return [t for t in db.data().reset_tokens.values() if t.user_uuid == self.uuid]
+
+    def store(self) -> None:
+        """Store this user in the database. Must be called inside a transaction."""
+        db.data().users[self.uuid] = self
+
+    def delete(self) -> None:
+        """Delete this user and cascade to credentials, sessions, reset tokens.
+
+        Must be called inside a transaction.
+        """
+        _data = db.data()
+        for cred in self.credentials:
+            del _data.credentials[cred.uuid]
+        for sess in self.sessions:
+            del _data.sessions[sess.key]
+        for token in self.reset_tokens:
+            del _data.reset_tokens[token.key]
+        del _data.users[self.uuid]
+
+    @classmethod
+    def create(
+        cls,
+        display_name: str,
+        role: UUID | Role,
+        created_at: datetime | None = None,
+    ) -> User:
+        """Create a new User with auto-generated uuid7."""
+        role_uuid = role if isinstance(role, UUID) else role.uuid
+        user = cls(
+            display_name=display_name,
+            role_uuid=role_uuid,
+            created_at=created_at or datetime.now(UTC),
+            last_seen=None,
+            visits=0,
+            theme="",
+        )
+        user.uuid = uuid7.create(user.created_at)
+        return user
+
+
+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
+    uuid is derived from created_at using uuid7.
+    """
+
+    credential_id: bytes  # Long binary ID from the authenticator
+    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
+
+    def __post_init__(self):
+        if not hasattr(self, "uuid"):
+            self.uuid: UUID = _UUID_UNSET
+
+    @property
+    def user(self) -> User:
+        """Get the User object for this credential."""
+        return db.data().users[self.user_uuid]
+
+    @property
+    def sessions(self) -> list[Session]:
+        """Get all sessions using this credential."""
+        return [
+            s for s in db.data().sessions.values() if s.credential_uuid == self.uuid
+        ]
+
+    def store(self) -> None:
+        """Store this credential in the database. Must be called inside a transaction."""
+        db.data().credentials[self.uuid] = self
+
+    def delete(self) -> None:
+        """Delete this credential and all its sessions.
+
+        Must be called inside a transaction.
+        """
+        _data = db.data()
+        for sess in self.sessions:
+            del _data.sessions[sess.key]
+        del _data.credentials[self.uuid]
+
+    @classmethod
+    def create(
+        cls,
+        credential_id: bytes,
+        user: UUID | User,
+        aaguid: UUID,
+        public_key: bytes,
+        sign_count: int,
+        created_at: datetime | None = None,
+    ) -> Credential:
+        """Create a new Credential with auto-generated uuid7."""
+        user_uuid = user if isinstance(user, UUID) else user.uuid
+        now = created_at or datetime.now(UTC)
+        cred = cls(
+            credential_id=credential_id,
+            user_uuid=user_uuid,
+            aaguid=aaguid,
+            public_key=public_key,
+            sign_count=sign_count,
+            created_at=now,
+            last_used=now,
+            last_verified=now,
+        )
+        cred.uuid = uuid7.create(now)
+        return cred
+
+
+class Session(msgspec.Struct, dict=True, omit_defaults=True):
+    """Session data structure.
+
+    Mutable fields: validated (updated on session refresh)
+    Immutable fields: user_uuid, credential_uuid, host, ip, user_agent, client_uuid
+    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.
+
+    Security: The database stores only derived keys, never the raw secret.
+    A database leak does not expose working session credentials.
+    """
+
+    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)
+
+    def __post_init__(self):
+        if not hasattr(self, "key"):
+            self.key: str = ""
+
+    @property
+    def user(self) -> User:
+        """Get the User object for this session."""
+        return db.data().users[self.user_uuid]
+
+    @property
+    def credential(self) -> Credential:
+        """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.
+
+        Updates user.last_seen and user.visits. Must be called inside
+        a database transaction.
+        """
+        _data = db.data()
+        _data.sessions[self.key] = self
+        _data.users[self.user_uuid].last_seen = last_seen
+        _data.users[self.user_uuid].visits += 1
+
+    def delete(self) -> None:
+        """Delete this session from the database. Must be called inside a transaction."""
+        del db.data().sessions[self.key]
+
+    @classmethod
+    def create(
+        cls,
+        user: UUID | User,
+        credential: UUID | Credential,
+        key: str,
+        host: str,
+        ip: str,
+        user_agent: str,
+        validated: datetime,
+        client: UUID | None = None,
+    ) -> Session:
+        """Create a new Session with the provided key.
+
+        Args:
+            key: The hashed session key (derived from secret via hash_secret)
+
+        Returns:
+            Session object with key set
+        """
+
+        user_uuid = user if isinstance(user, UUID) else user.uuid
+        credential_uuid = (
+            credential if isinstance(credential, UUID) else credential.uuid
+        )
+
+        session = cls(
+            user_uuid=user_uuid,
+            credential_uuid=credential_uuid,
+            host=host,
+            ip=ip,
+            user_agent=user_agent,
+            validated=validated,
+            client_uuid=client,
+        )
+        session.key = key
+        return session
+
+
+class ResetToken(msgspec.Struct, dict=True):
+    """Reset/device-addition token data structure.
+
+    Immutable fields: All fields (tokens are created and deleted, never modified)
+    key is stored in the dict key, not in the struct.
+    """
+
+    user_uuid: UUID = msgspec.field(name="user")
+    expiry: datetime
+    token_type: str
+
+    def __post_init__(self):
+        if not hasattr(self, "key"):
+            self.key: str = ""
+
+    @property
+    def user(self) -> User:
+        """Get the User object for this reset token."""
+        return db.data().users[self.user_uuid]
+
+    def store(self) -> None:
+        """Store this reset token in the database. Must be called inside a transaction."""
+        db.data().reset_tokens[self.key] = self
+
+    def delete(self) -> None:
+        """Delete this reset token from the database. Must be called inside a transaction."""
+        del db.data().reset_tokens[self.key]
+
+    @staticmethod
+    def hash(passphrase: str) -> str:
+        """Hash a passphrase to string for reset token storage."""
+        if not passphrase_util.is_well_formed(passphrase):
+            raise ValueError(
+                "Trying to reset with a session token in place of a passphrase"
+                if len(passphrase) == 16
+                else "Invalid passphrase format"
+            )
+        return hash_secret("reset", passphrase)
+
+    @classmethod
+    def by_passphrase(cls, passphrase: str) -> ResetToken | None:
+        """Get a reset token by passphrase."""
+        key = cls.hash(passphrase)
+        return db.data().reset_tokens.get(key)
+
+    @classmethod
+    def create(
+        cls,
+        user: UUID | User,
+        expiry: datetime,
+        token_type: str,
+        passphrase: str | None = None,
+    ) -> tuple[ResetToken, str]:
+        """Create a new ResetToken with auto-generated or provided passphrase.
+
+        Args:
+            user: User UUID or User object
+            expiry: Token expiration datetime
+            token_type: Type of token (e.g., "device addition", "account recovery")
+            passphrase: Optional passphrase to use (auto-generated if not provided)
+
+        Returns:
+            Tuple of (token, passphrase) where passphrase is the human-readable
+            code to give to the user.
+        """
+        if passphrase is None:
+            passphrase = passphrase_util.generate()
+        key = cls.hash(passphrase)
+        user_uuid = user if isinstance(user, UUID) else user.uuid
+        token = cls(
+            user_uuid=user_uuid,
+            expiry=expiry,
+            token_type=token_type,
+        )
+        token.key = key
+        return token, passphrase
+
+
+# -------------------------------------------------------------------------
+# OIDC Provider structures
+# -------------------------------------------------------------------------
+
+
+class Client(msgspec.Struct, dict=True, omit_defaults=True):
+    """OIDC client (relying party) registration.
+
+    client_id is the dict key (UUID).
+    """
+
+    client_secret_hash: bytes
+    name: str
+    redirect_uris: list[str]
+    backchannel_logout_uri: str | None = None
+
+    def __post_init__(self):
+        if not hasattr(self, "uuid"):
+            self.uuid: UUID = _UUID_UNSET
+
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        redirect_uris: list[str],
+        client_secret: str,
+        created_at: datetime | None = None,
+        backchannel_logout_uri: str | None = None,
+    ) -> tuple[Client, str]:
+        """Create a new OIDClient with hashed secret.
+
+        Returns (client, client_secret) tuple.
+        """
+        now = created_at or datetime.now(UTC)
+        secret_hash = hashlib.sha256(client_secret.encode()).digest()
+        client = cls(
+            client_secret_hash=secret_hash,
+            name=name,
+            redirect_uris=redirect_uris,
+            backchannel_logout_uri=backchannel_logout_uri,
+        )
+        client.uuid = uuid7.create(now)
+        return client, client_secret
+
+    def verify_secret(self, client_secret: str) -> bool:
+        """Verify a client secret against stored hash."""
+        return secrets.compare_digest(
+            self.client_secret_hash,
+            hashlib.sha256(client_secret.encode()).digest(),
+        )
+
+
+class SessionContext(msgspec.Struct):
+    session: Session
+    user: User
+    org: Org
+    role: Role
+    credential: Credential
+    permissions: list[Permission] = []
+
+
+class OIDC(msgspec.Struct, dict=True):
+    clients: dict[UUID, Client] = {}
+    key: bytes | None = None
+
+
+class Config(msgspec.Struct, omit_defaults=True):
+    """Stored configuration for the instance."""
+
+    rp_id: str
+    rp_name: str | None = None
+    auth_host: str | None = None
+    origins: list[str] | None = None
+    listen: list[str] | None = None
+
+
+# -------------------------------------------------------------------------
+# Database storage structure
+# -------------------------------------------------------------------------
+
+
+class DB(msgspec.Struct, dict=True, omit_defaults=False):
+    """In-memory database. Access fields directly for reads."""
+
+    config: Config
+    permissions: dict[UUID, Permission] = {}
+    orgs: dict[UUID, Org] = {}
+    roles: dict[UUID, Role] = {}
+    users: dict[UUID, User] = {}
+    credentials: dict[UUID, Credential] = {}
+    sessions: dict[str, Session] = {}
+    reset_tokens: dict[str, ResetToken] = {}
+    # OIDC provider data
+    oidc: OIDC = msgspec.field(default_factory=lambda: OIDC())
+
+    def __post_init__(self):
+        # Store reference for persistence (not serialized)
+        self._store = None
+        # Set the key fields on all stored objects
+        for uuid, perm in self.permissions.items():
+            perm.uuid = uuid
+        for uuid, org in self.orgs.items():
+            org.uuid = uuid
+        for uuid, role in self.roles.items():
+            role.uuid = uuid
+        for uuid, user in self.users.items():
+            user.uuid = uuid
+        for uuid, cred in self.credentials.items():
+            cred.uuid = uuid
+        for key, session in self.sessions.items():
+            session.key = key
+        for key, token in self.reset_tokens.items():
+            token.key = key
+        # OIDC
+        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:
+        """Get full session context with effective permissions.
+
+        Args:
+            session_secret: The session secret (cookie value) - will be hashed for lookup
+            host: Optional host for binding/validation and domain-scoped permissions
+
+        Returns:
+            SessionContext if valid, None if session not found, expired, or host mismatch
+        """
+
+        key = hash_secret("cookie", session_secret)
+        try:
+            s = self.sessions[key]
+        except KeyError:
+            return None
+
+        # OIDC sessions (client_uuid set) are not valid for cookie-based auth
+        if s.client_uuid is not None:
+            return None
+
+        # Validate host matches (sessions are always created with a host)
+        normalized_input = host
+        if s.host != normalized_input:
+            # Session bound to different host
+            return None
+
+        try:
+            user = s.user
+            role = user.role
+            org = role.org
+            credential = s.credential
+        except KeyError:
+            return None
+
+        # Effective permissions: role's permissions that the org can grant
+        # Also filter by domain if host is provided
+        org_perm_uuids = {p.uuid for p in org.permissions}
+
+        effective_perms = []
+        for perm_uuid in role.permission_set:
+            if perm_uuid not in org_perm_uuids:
+                continue
+            try:
+                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 != normalized_input:
+                continue
+            effective_perms.append(p)
+
+        return SessionContext(
+            session=s,
+            user=user,
+            org=org,
+            role=role,
+            credential=credential,
+            permissions=effective_perms,
+        )

paskia/fastapi/__main__.py

@@ -1,335 +0,0 @@
-import argparse
-import asyncio
-import ipaddress
-import logging
-import os
-from urllib.parse import urlparse
-
-import uvicorn
-
-from paskia.util.hostutil import normalize_origin
-
-DEFAULT_HOST = "localhost"
-DEFAULT_SERVE_PORT = 4401
-
-
-def is_subdomain(sub: str, domain: str) -> bool:
-    """Check if sub is a subdomain of domain (or equal)."""
-    sub_parts = sub.lower().split(".")
-    domain_parts = domain.lower().split(".")
-    if len(sub_parts) < len(domain_parts):
-        return False
-    return sub_parts[-len(domain_parts) :] == domain_parts
-
-
-def validate_auth_host(auth_host: str, rp_id: 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 parse_endpoint(
-    value: str | None, default_port: int
-) -> tuple[str | None, int | None, str | None, bool]:
-    """Parse an endpoint using stdlib (urllib.parse, ipaddress).
-
-    Returns (host, port, uds_path). If uds_path is not None, host/port are None.
-
-    Supported forms:
-    - host[:port]
-    - :port (uses default host)
-    - [ipv6][:port] (bracketed for port usage)
-    - ipv6 (unbracketed, no port allowed -> default port)
-    - unix:/path/to/socket.sock
-    - None -> defaults (localhost:4401)
-
-    Notes:
-    - For IPv6 with an explicit port you MUST use brackets (e.g. [::1]:8080)
-    - Unbracketed IPv6 like ::1 implies the default port.
-    """
-    if not value:
-        return DEFAULT_HOST, default_port, None, False
-
-    # Port only (numeric) -> localhost:port
-    if value.isdigit():
-        try:
-            port_only = int(value)
-        except ValueError:  # pragma: no cover (isdigit guards)
-            raise SystemExit(f"Invalid port '{value}'")
-        return DEFAULT_HOST, port_only, None, False
-
-    # Leading colon :port -> bind all interfaces (0.0.0.0 + ::)
-    if value.startswith(":") and value != ":":
-        port_part = value[1:]
-        if not port_part.isdigit():
-            raise SystemExit(f"Invalid port in '{value}'")
-        return None, int(port_part), None, True
-
-    # UNIX domain socket
-    if value.startswith("unix:"):
-        uds_path = value[5:] or None
-        if uds_path is None:
-            raise SystemExit("unix: path must not be empty")
-        return None, None, uds_path, False
-
-    # Unbracketed IPv6 (cannot safely contain a port) -> detect by multiple colons
-    if value.count(":") > 1 and not value.startswith("["):
-        try:
-            ipaddress.IPv6Address(value)
-        except ValueError as e:  # pragma: no cover
-            raise SystemExit(f"Invalid IPv6 address '{value}': {e}")
-        return value, default_port, None, False
-
-    # Use urllib.parse for everything else (host[:port], :port, [ipv6][:port])
-    parsed = urlparse(f"//{value}")  # // prefix lets urlparse treat it as netloc
-    host = parsed.hostname
-    port = parsed.port
-
-    # Host may be None if empty (e.g. ':5500')
-    if not host:
-        host = DEFAULT_HOST
-    if port is None:
-        port = default_port
-
-    # Validate IP literals (optional; hostname passes through)
-    try:
-        # Strip brackets if somehow present (urlparse removes them already)
-        ipaddress.ip_address(host)
-    except ValueError:
-        # Not an IP address -> treat as hostname; no action
-        pass
-
-    return host, port, None, False
-
-
-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",
-        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 host (optionally with scheme/port) to serve the auth UI at the root,"
-            " e.g. auth.example.com or https://auth.example.com"
-        ),
-    )
-
-
-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"
-    )
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    # serve subcommand
-    serve = sub.add_parser(
-        "serve", help="Run the server (production style, no auto-reload)"
-    )
-    serve.add_argument(
-        "hostport",
-        nargs="?",
-        help=(
-            "Endpoint (default: localhost:4401). Forms: host[:port] | :port | "
-            "[ipv6][:port] | ipv6 | unix:/path.sock"
-        ),
-    )
-    add_common_options(serve)
-
-    # reset subcommand
-    reset = sub.add_parser(
-        "reset",
-        help=(
-            "Create a credential reset link for a user. Provide part of the display name or UUID. "
-            "If omitted, targets the master admin (first Administration role user in an auth:admin org)."
-        ),
-    )
-    reset.add_argument(
-        "query",
-        nargs="?",
-        help="User UUID (full) or case-insensitive substring of display name. If omitted, master admin is used.",
-    )
-    add_common_options(reset)
-
-    args = parser.parse_args()
-
-    if args.command == "serve":
-        host, port, uds, all_ifaces = parse_endpoint(args.hostport, DEFAULT_SERVE_PORT)
-    else:
-        host = port = uds = all_ifaces = None  # type: ignore
-
-    # Collect and normalize origins, handle auth_host
-    origins = [normalize_origin(o) for o in (getattr(args, "origins", None) or [])]
-    if args.auth_host:
-        # Normalize auth_host with scheme
-        if "://" not in args.auth_host:
-            args.auth_host = f"https://{args.auth_host}"
-
-        validate_auth_host(args.auth_host, args.rp_id)
-
-        # If origins are configured, ensure auth_host is included at top
-        if origins:
-            # Insert auth_host at the beginning
-            origins.insert(0, args.auth_host)
-
-    # Remove duplicates while preserving order
-    seen = set()
-    origins = [x for x in origins if not (x in seen or seen.add(x))]
-
-    # Compute site_url and site_path for reset links
-    # Priority: auth_host > first origin with localhost > http://localhost:port
-    if args.auth_host:
-        site_url = args.auth_host.rstrip("/")
-        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]).rstrip("/")
-        site_path = "/auth/"
-    elif args.rp_id == "localhost" and port:
-        # Dev mode: use http with port
-        site_url = f"http://localhost:{port}"
-        site_path = "/auth/"
-    else:
-        site_url = f"https://{args.rp_id}"
-        site_path = "/auth/"
-
-    # Build runtime configuration
-    from paskia.config import PaskiaConfig
-
-    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
-    import json
-
-    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,
-    }
-    os.environ["PASKIA_CONFIG"] = json.dumps(config_json)
-
-    # Initialize globals (without bootstrap yet)
-    from paskia import globals as _globals  # local import
-
-    asyncio.run(
-        _globals.init(
-            rp_id=config.rp_id,
-            rp_name=config.rp_name,
-            origins=config.origins,
-            bootstrap=False,
-        )
-    )
-
-    # Print startup configuration
-    from paskia.util import startupbox
-
-    startupbox.print_startup_config(config)
-
-    # Bootstrap after startup box is printed
-    from paskia.bootstrap import bootstrap_if_needed
-
-    asyncio.run(bootstrap_if_needed())
-
-    # Handle recover-admin command (no server start)
-    if args.command == "reset":
-        from paskia.fastapi import reset as reset_cmd  # local import
-
-        exit_code = reset_cmd.run(getattr(args, "query", None))
-        raise SystemExit(exit_code)
-
-    if args.command == "serve":
-        run_kwargs: dict = {
-            "log_level": "info",
-        }
-
-        # Dev mode: enable reload when PASKIA_DEVMODE is set
-        devmode = bool(os.environ.get("PASKIA_DEVMODE"))
-        if devmode:
-            # Security: dev mode must run on localhost:4402 to prevent
-            # accidental public exposure of the Vite dev server
-            if host != "localhost" or port != 4402:
-                raise SystemExit(f"Dev mode requires localhost:4402, got {host}:{port}")
-            run_kwargs["reload"] = True
-            run_kwargs["reload_dirs"] = ["paskia"]
-            # Suppress uvicorn startup messages in dev mode
-            run_kwargs["log_level"] = "warning"
-
-        if uds:
-            run_kwargs["uds"] = uds
-        else:
-            if not all_ifaces:
-                run_kwargs["host"] = host
-                run_kwargs["port"] = port
-
-        if all_ifaces and not uds:
-            # Dev mode with all interfaces: use simple single-server approach
-            if devmode:
-                run_kwargs["host"] = "::"
-                run_kwargs["port"] = port
-                uvicorn.run("paskia.fastapi:app", **run_kwargs)
-            else:
-                # Production: run separate servers for IPv4 and IPv6
-                from uvicorn import Config, Server  # noqa: E402 local import
-
-                from paskia.fastapi import (
-                    app as fastapi_app,  # noqa: E402 local import
-                )
-
-                async def serve_both():
-                    servers = []
-                    assert port is not None
-                    for h in ("0.0.0.0", "::"):
-                        try:
-                            cfg = Config(
-                                app=fastapi_app,
-                                host=h,
-                                port=port,
-                                log_level="info",
-                            )
-                            servers.append(Server(cfg))
-                        except Exception as e:  # pragma: no cover
-                            logging.warning(f"Failed to configure server for {h}: {e}")
-                    tasks = [asyncio.create_task(s.serve()) for s in servers]
-                    await asyncio.gather(*tasks)
-
-                asyncio.run(serve_both())
-        else:
-            uvicorn.run("paskia.fastapi:app", **run_kwargs)
-
-
-if __name__ == "__main__":
-    main()

paskia/fastapi/admin.py

@@ -1,850 +0,0 @@
-import logging
-from datetime import timezone
-from uuid import UUID, uuid4
-
-from fastapi import Body, FastAPI, HTTPException, Request, Response
-from fastapi.responses import JSONResponse
-
-from paskia.authsession import reset_expires
-from paskia.fastapi import authz
-from paskia.fastapi.session import AUTH_COOKIE
-from paskia.globals import db
-from paskia.util import (
-    frontend,
-    hostutil,
-    passphrase,
-    permutil,
-    querysafe,
-    tokens,
-    useragent,
-)
-from paskia.util.tokens import encode_session_key, session_key
-
-app = FastAPI()
-
-
-@app.exception_handler(ValueError)
-async def value_error_handler(_request, exc: ValueError):  # pragma: no cover - simple
-    return JSONResponse(status_code=400, content={"detail": str(exc)})
-
-
-@app.exception_handler(authz.AuthException)
-async def auth_exception_handler(_request, exc: authz.AuthException):
-    """Handle AuthException with auth info for UI."""
-    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"})
-
-
-@app.get("/")
-async def adminapp(request: Request, auth=AUTH_COOKIE):
-    return Response(*await frontend.read("/auth/admin/index.html"))
-
-
-# -------------------- Organizations --------------------
-
-
-@app.get("/orgs")
-async def admin_list_orgs(request: Request, auth=AUTH_COOKIE):
-    ctx = await authz.verify(
-        auth,
-        ["auth:admin", "auth:org:*"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-    )
-    orgs = await db.instance.list_organizations()
-    if "auth:admin" not in ctx.role.permissions:
-        orgs = [o for o in orgs if f"auth:org:{o.uuid}" in ctx.role.permissions]
-
-    def role_to_dict(r):
-        return {
-            "uuid": str(r.uuid),
-            "org_uuid": str(r.org_uuid),
-            "display_name": r.display_name,
-            "permissions": r.permissions,
-        }
-
-    async def org_to_dict(o):
-        users = await db.instance.get_organization_users(str(o.uuid))
-        return {
-            "uuid": str(o.uuid),
-            "display_name": o.display_name,
-            "permissions": o.permissions,
-            "roles": [role_to_dict(r) for r in o.roles],
-            "users": [
-                {
-                    "uuid": str(u.uuid),
-                    "display_name": u.display_name,
-                    "role": role_name,
-                    "visits": u.visits,
-                    "last_seen": u.last_seen.isoformat() if u.last_seen else None,
-                }
-                for (u, role_name) in users
-            ],
-        }
-
-    return [await org_to_dict(o) for o in orgs]
-
-
-@app.post("/orgs")
-async def admin_create_org(
-    request: Request, payload: dict = Body(...), auth=AUTH_COOKIE
-):
-    await authz.verify(
-        auth, ["auth:admin"], host=request.headers.get("host"), match=permutil.has_all
-    )
-    from ..db import Org as OrgDC  # local import to avoid cycles
-    from ..db import Role as RoleDC  # local import to avoid cycles
-
-    org_uuid = uuid4()
-    display_name = payload.get("display_name") or "New Organization"
-    permissions = payload.get("permissions") or []
-    org = OrgDC(uuid=org_uuid, display_name=display_name, permissions=permissions)
-    await db.instance.create_organization(org)
-
-    # Automatically create Administration role with org admin permission
-    role_uuid = uuid4()
-    admin_role = RoleDC(
-        uuid=role_uuid,
-        org_uuid=org_uuid,
-        display_name="Administration",
-        permissions=[f"auth:org:{org_uuid}"],
-    )
-    await db.instance.create_role(admin_role)
-
-    return {"uuid": str(org_uuid)}
-
-
-@app.put("/orgs/{org_uuid}")
-async def admin_update_org(
-    org_uuid: UUID,
-    request: Request,
-    payload: dict = Body(...),
-    auth=AUTH_COOKIE,
-):
-    ctx = await authz.verify(
-        auth,
-        ["auth:admin", f"auth:org:{org_uuid}"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-    )
-    from ..db import Org as OrgDC  # local import to avoid cycles
-
-    current = await db.instance.get_organization(str(org_uuid))
-    display_name = payload.get("display_name") or current.display_name
-    permissions = payload.get("permissions")
-    if permissions is None:
-        permissions = current.permissions or []
-
-    # Sanity check: prevent removing permissions that would break current user's admin access
-    org_admin_perm = f"auth:org:{org_uuid}"
-
-    # If current user is org admin (not global admin), ensure org admin perm remains
-    if (
-        "auth:admin" not in ctx.role.permissions
-        and f"auth:org:{org_uuid}" in ctx.role.permissions
-    ):
-        if org_admin_perm not in permissions:
-            raise ValueError(
-                "Cannot remove organization admin permission from your own organization"
-            )
-
-    org = OrgDC(uuid=org_uuid, display_name=display_name, permissions=permissions)
-    await db.instance.update_organization(org)
-    return {"status": "ok"}
-
-
-@app.delete("/orgs/{org_uuid}")
-async def admin_delete_org(org_uuid: UUID, request: Request, auth=AUTH_COOKIE):
-    ctx = await authz.verify(
-        auth,
-        ["auth:admin", f"auth:org:{org_uuid}"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-        max_age="5m",
-    )
-    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 = await db.instance.list_permissions()
-    for perm in all_permissions:
-        perm_id_lower = perm.id.lower()
-        # Check if permission contains "org:{uuid}" separated by colons or at boundaries
-        if (
-            f":{org_perm_pattern}:" in perm_id_lower
-            or perm_id_lower.startswith(f"{org_perm_pattern}:")
-            or perm_id_lower.endswith(f":{org_perm_pattern}")
-            or perm_id_lower == org_perm_pattern
-        ):
-            await db.instance.delete_permission(perm.id)
-
-    await db.instance.delete_organization(org_uuid)
-    return {"status": "ok"}
-
-
-@app.post("/orgs/{org_uuid}/permission")
-async def admin_add_org_permission(
-    org_uuid: UUID,
-    permission_id: str,
-    request: Request,
-    auth=AUTH_COOKIE,
-):
-    await authz.verify(
-        auth, ["auth:admin"], host=request.headers.get("host"), match=permutil.has_all
-    )
-    await db.instance.add_permission_to_organization(str(org_uuid), permission_id)
-    return {"status": "ok"}
-
-
-@app.delete("/orgs/{org_uuid}/permission")
-async def admin_remove_org_permission(
-    org_uuid: UUID,
-    permission_id: str,
-    request: Request,
-    auth=AUTH_COOKIE,
-):
-    await authz.verify(
-        auth, ["auth:admin"], host=request.headers.get("host"), match=permutil.has_all
-    )
-    await db.instance.remove_permission_from_organization(str(org_uuid), permission_id)
-    return {"status": "ok"}
-
-
-# -------------------- Roles --------------------
-
-
-@app.post("/orgs/{org_uuid}/roles")
-async def admin_create_role(
-    org_uuid: UUID,
-    request: Request,
-    payload: dict = Body(...),
-    auth=AUTH_COOKIE,
-):
-    await authz.verify(
-        auth,
-        ["auth:admin", f"auth:org:{org_uuid}"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-    )
-    from ..db import Role as RoleDC
-
-    role_uuid = uuid4()
-    display_name = payload.get("display_name") or "New Role"
-    perms = payload.get("permissions") or []
-    org = await db.instance.get_organization(str(org_uuid))
-    grantable = set(org.permissions or [])
-    for pid in perms:
-        await db.instance.get_permission(pid)
-        if pid not in grantable:
-            raise ValueError(f"Permission not grantable by org: {pid}")
-    role = RoleDC(
-        uuid=role_uuid,
-        org_uuid=org_uuid,
-        display_name=display_name,
-        permissions=perms,
-    )
-    await db.instance.create_role(role)
-    return {"uuid": str(role_uuid)}
-
-
-@app.put("/orgs/{org_uuid}/roles/{role_uuid}")
-async def admin_update_role(
-    org_uuid: UUID,
-    role_uuid: UUID,
-    request: Request,
-    payload: dict = Body(...),
-    auth=AUTH_COOKIE,
-):
-    # Verify caller is global admin or admin of provided org
-    ctx = await authz.verify(
-        auth,
-        ["auth:admin", f"auth:org:{org_uuid}"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-    )
-    role = await db.instance.get_role(role_uuid)
-    if role.org_uuid != org_uuid:
-        raise HTTPException(status_code=404, detail="Role not found in organization")
-    from ..db import Role as RoleDC
-
-    display_name = payload.get("display_name") or role.display_name
-    permissions = payload.get("permissions")
-    if permissions is None:
-        permissions = role.permissions
-    org = await db.instance.get_organization(str(org_uuid))
-    grantable = set(org.permissions or [])
-    existing_permissions = set(role.permissions)
-    for pid in permissions:
-        await db.instance.get_permission(pid)
-        if pid not in existing_permissions and pid not in grantable:
-            raise ValueError(f"Permission not grantable by org: {pid}")
-
-    # Sanity check: prevent admin from removing their own access via role update
-    if ctx.org.uuid == org_uuid and ctx.role.uuid == role_uuid:
-        has_admin_access = (
-            "auth:admin" in permissions or f"auth:org:{org_uuid}" in permissions
-        )
-        if not has_admin_access:
-            raise ValueError("Cannot update your own role to remove admin permissions")
-
-    updated = RoleDC(
-        uuid=role_uuid,
-        org_uuid=org_uuid,
-        display_name=display_name,
-        permissions=permissions,
-    )
-    await db.instance.update_role(updated)
-    return {"status": "ok"}
-
-
-@app.delete("/orgs/{org_uuid}/roles/{role_uuid}")
-async def admin_delete_role(
-    org_uuid: UUID,
-    role_uuid: UUID,
-    request: Request,
-    auth=AUTH_COOKIE,
-):
-    ctx = await authz.verify(
-        auth,
-        ["auth:admin", f"auth:org:{org_uuid}"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-        max_age="5m",
-    )
-    role = await db.instance.get_role(role_uuid)
-    if role.org_uuid != org_uuid:
-        raise HTTPException(status_code=404, detail="Role not found in organization")
-
-    # Sanity check: prevent admin from deleting their own role
-    if ctx.role.uuid == role_uuid:
-        raise ValueError("Cannot delete your own role")
-
-    await db.instance.delete_role(role_uuid)
-    return {"status": "ok"}
-
-
-# -------------------- Users --------------------
-
-
-@app.post("/orgs/{org_uuid}/users")
-async def admin_create_user(
-    org_uuid: UUID,
-    request: Request,
-    payload: dict = Body(...),
-    auth=AUTH_COOKIE,
-):
-    await authz.verify(
-        auth,
-        ["auth:admin", f"auth:org:{org_uuid}"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-    )
-    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")
-    from ..db import User as UserDC
-
-    roles = await db.instance.get_roles_by_organization(str(org_uuid))
-    role_obj = next((r for r in roles if r.display_name == role_name), None)
-    if not role_obj:
-        raise ValueError("Role not found in organization")
-    user_uuid = uuid4()
-    user = UserDC(
-        uuid=user_uuid,
-        display_name=display_name,
-        role_uuid=role_obj.uuid,
-        visits=0,
-        created_at=None,
-    )
-    await db.instance.create_user(user)
-    return {"uuid": str(user_uuid)}
-
-
-@app.put("/orgs/{org_uuid}/users/{user_uuid}/role")
-async def admin_update_user_role(
-    org_uuid: UUID,
-    user_uuid: UUID,
-    request: Request,
-    payload: dict = Body(...),
-    auth=AUTH_COOKIE,
-):
-    ctx = await authz.verify(
-        auth,
-        ["auth:admin", f"auth:org:{org_uuid}"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-    )
-    new_role = payload.get("role")
-    if not new_role:
-        raise ValueError("role is required")
-    try:
-        user_org, _current_role = await db.instance.get_user_organization(user_uuid)
-    except ValueError:
-        raise ValueError("User not found")
-    if user_org.uuid != org_uuid:
-        raise ValueError("User does not belong to this organization")
-    roles = await db.instance.get_roles_by_organization(str(org_uuid))
-    if not any(r.display_name == new_role for r in roles):
-        raise ValueError("Role not found in organization")
-
-    # Sanity check: prevent admin from removing their own access
-    if ctx.user.uuid == user_uuid:
-        new_role_obj = next((r for r in roles if r.display_name == new_role), None)
-        if new_role_obj:  # pragma: no branch - always true, role validated above
-            has_admin_access = (
-                "auth:admin" in new_role_obj.permissions
-                or f"auth:org:{org_uuid}" in new_role_obj.permissions
-            )
-            if not has_admin_access:
-                raise ValueError(
-                    "Cannot change your own role to one without admin permissions"
-                )
-
-    await db.instance.update_user_role_in_organization(user_uuid, new_role)
-    return {"status": "ok"}
-
-
-@app.post("/orgs/{org_uuid}/users/{user_uuid}/create-link")
-async def admin_create_user_registration_link(
-    org_uuid: UUID,
-    user_uuid: UUID,
-    request: Request,
-    auth=AUTH_COOKIE,
-):
-    try:
-        user_org, _role_name = await db.instance.get_user_organization(user_uuid)
-    except ValueError:
-        raise HTTPException(status_code=404, detail="User not found")
-    if user_org.uuid != org_uuid:
-        raise HTTPException(status_code=404, detail="User not found in organization")
-    ctx = await authz.verify(
-        auth,
-        ["auth:admin", f"auth:org:{org_uuid}"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-        max_age="5m",
-    )
-    if (  # pragma: no cover - defense in depth, authz.verify already checked
-        "auth:admin" not in ctx.role.permissions
-        and f"auth:org:{org_uuid}" not in ctx.role.permissions
-    ):
-        raise authz.AuthException(
-            status_code=403, detail="Insufficient permissions", mode="forbidden"
-        )
-
-    # Check if user has existing credentials
-    credentials = await db.instance.get_credentials_by_user_uuid(user_uuid)
-    token_type = "user registration" if not credentials else "account recovery"
-
-    token = passphrase.generate()
-    expiry = reset_expires()
-    await db.instance.create_reset_token(
-        user_uuid=user_uuid,
-        key=tokens.reset_key(token),
-        expiry=expiry,
-        token_type=token_type,
-    )
-    url = hostutil.reset_link_url(token)
-    return {
-        "url": url,
-        "expires": (
-            expiry.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
-            if expiry.tzinfo
-            else expiry.replace(tzinfo=timezone.utc).isoformat().replace("+00:00", "Z")
-        ),
-    }
-
-
-@app.get("/orgs/{org_uuid}/users/{user_uuid}")
-async def admin_get_user_detail(
-    org_uuid: UUID,
-    user_uuid: UUID,
-    request: Request,
-    auth=AUTH_COOKIE,
-):
-    try:
-        user_org, role_name = await db.instance.get_user_organization(user_uuid)
-    except ValueError:
-        raise HTTPException(status_code=404, detail="User not found")
-    if user_org.uuid != org_uuid:
-        raise HTTPException(status_code=404, detail="User not found in organization")
-    ctx = await authz.verify(
-        auth,
-        ["auth:admin", f"auth:org:{org_uuid}"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-    )
-    if (  # pragma: no cover - defense in depth, authz.verify already checked
-        "auth:admin" not in ctx.role.permissions
-        and f"auth:org:{org_uuid}" not in ctx.role.permissions
-    ):
-        raise authz.AuthException(
-            status_code=403, detail="Insufficient permissions", mode="forbidden"
-        )
-    user = await db.instance.get_user_by_uuid(user_uuid)
-    cred_ids = await db.instance.get_credentials_by_user_uuid(user_uuid)
-    creds: list[dict] = []
-    aaguids: set[str] = set()
-    for cid in cred_ids:
-        try:
-            c = await db.instance.get_credential_by_id(cid)
-        except ValueError:  # pragma: no cover - race condition handling
-            continue
-        aaguid_str = str(c.aaguid)
-        aaguids.add(aaguid_str)
-        creds.append(
-            {
-                "credential_uuid": str(c.uuid),
-                "aaguid": aaguid_str,
-                "created_at": (
-                    c.created_at.astimezone(timezone.utc)
-                    .isoformat()
-                    .replace("+00:00", "Z")
-                    if c.created_at.tzinfo
-                    else c.created_at.replace(tzinfo=timezone.utc)
-                    .isoformat()
-                    .replace("+00:00", "Z")
-                ),
-                "last_used": (
-                    c.last_used.astimezone(timezone.utc)
-                    .isoformat()
-                    .replace("+00:00", "Z")
-                    if c.last_used and c.last_used.tzinfo
-                    else (
-                        c.last_used.replace(tzinfo=timezone.utc)
-                        .isoformat()
-                        .replace("+00:00", "Z")
-                        if c.last_used
-                        else None
-                    )
-                ),
-                "last_verified": (
-                    c.last_verified.astimezone(timezone.utc)
-                    .isoformat()
-                    .replace("+00:00", "Z")
-                    if c.last_verified and c.last_verified.tzinfo
-                    else (
-                        c.last_verified.replace(tzinfo=timezone.utc)
-                        .isoformat()
-                        .replace("+00:00", "Z")
-                        if c.last_verified
-                        else None
-                    )
-                )
-                if c.last_verified
-                else None,
-                "sign_count": c.sign_count,
-            }
-        )
-    from .. import aaguid as aaguid_mod
-
-    aaguid_info = aaguid_mod.filter(aaguids)
-
-    # Get sessions for the user
-    normalized_request_host = hostutil.normalize_host(request.headers.get("host"))
-    session_records = await db.instance.list_sessions_for_user(user_uuid)
-    current_session_key = session_key(auth)
-    sessions_payload: list[dict] = []
-    for entry in session_records:
-        sessions_payload.append(
-            {
-                "id": encode_session_key(entry.key),
-                "credential_uuid": str(entry.credential_uuid),
-                "host": entry.host,
-                "ip": entry.ip,
-                "user_agent": useragent.compact_user_agent(entry.user_agent),
-                "last_renewed": (
-                    entry.renewed.astimezone(timezone.utc)
-                    .isoformat()
-                    .replace("+00:00", "Z")
-                    if entry.renewed.tzinfo
-                    else entry.renewed.replace(tzinfo=timezone.utc)
-                    .isoformat()
-                    .replace("+00:00", "Z")
-                ),
-                "is_current": entry.key == current_session_key,
-                "is_current_host": bool(
-                    normalized_request_host
-                    and entry.host
-                    and entry.host == normalized_request_host
-                ),
-            }
-        )
-
-    return {
-        "display_name": user.display_name,
-        "org": {"display_name": user_org.display_name},
-        "role": role_name,
-        "visits": user.visits,
-        "created_at": (
-            user.created_at.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
-            if user.created_at and user.created_at.tzinfo
-            else (
-                user.created_at.replace(tzinfo=timezone.utc)
-                .isoformat()
-                .replace("+00:00", "Z")
-                if user.created_at
-                else None
-            )
-        ),
-        "last_seen": (
-            user.last_seen.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
-            if user.last_seen and user.last_seen.tzinfo
-            else (
-                user.last_seen.replace(tzinfo=timezone.utc)
-                .isoformat()
-                .replace("+00:00", "Z")
-                if user.last_seen
-                else None
-            )
-        ),
-        "credentials": creds,
-        "aaguid_info": aaguid_info,
-        "sessions": sessions_payload,
-    }
-
-
-@app.put("/orgs/{org_uuid}/users/{user_uuid}/display-name")
-async def admin_update_user_display_name(
-    org_uuid: UUID,
-    user_uuid: UUID,
-    request: Request,
-    payload: dict = Body(...),
-    auth=AUTH_COOKIE,
-):
-    try:
-        user_org, _role_name = await db.instance.get_user_organization(user_uuid)
-    except ValueError:
-        raise HTTPException(status_code=404, detail="User not found")
-    if user_org.uuid != org_uuid:
-        raise HTTPException(status_code=404, detail="User not found in organization")
-    ctx = await authz.verify(
-        auth,
-        ["auth:admin", f"auth:org:{org_uuid}"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-    )
-    if (  # pragma: no cover - defense in depth, authz.verify already checked
-        "auth:admin" not in ctx.role.permissions
-        and f"auth:org:{org_uuid}" not in ctx.role.permissions
-    ):
-        raise authz.AuthException(
-            status_code=403, detail="Insufficient permissions", mode="forbidden"
-        )
-    new_name = (payload.get("display_name") or "").strip()
-    if not new_name:
-        raise HTTPException(status_code=400, detail="display_name required")
-    if len(new_name) > 64:
-        raise HTTPException(status_code=400, detail="display_name too long")
-    await db.instance.update_user_display_name(user_uuid, new_name)
-    return {"status": "ok"}
-
-
-@app.delete("/orgs/{org_uuid}/users/{user_uuid}/credentials/{credential_uuid}")
-async def admin_delete_user_credential(
-    org_uuid: UUID,
-    user_uuid: UUID,
-    credential_uuid: UUID,
-    request: Request,
-    auth=AUTH_COOKIE,
-):
-    try:
-        user_org, _role_name = await db.instance.get_user_organization(user_uuid)
-    except ValueError:
-        raise HTTPException(status_code=404, detail="User not found")
-    if user_org.uuid != org_uuid:
-        raise HTTPException(status_code=404, detail="User not found in organization")
-    ctx = await authz.verify(
-        auth,
-        ["auth:admin", f"auth:org:{org_uuid}"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-        max_age="5m",
-    )
-    if (  # pragma: no cover - defense in depth, authz.verify already checked
-        "auth:admin" not in ctx.role.permissions
-        and f"auth:org:{org_uuid}" not in ctx.role.permissions
-    ):
-        raise authz.AuthException(
-            status_code=403, detail="Insufficient permissions", mode="forbidden"
-        )
-    await db.instance.delete_credential(credential_uuid, user_uuid)
-    return {"status": "ok"}
-
-
-@app.delete("/orgs/{org_uuid}/users/{user_uuid}/sessions/{session_id}")
-async def admin_delete_user_session(
-    org_uuid: UUID,
-    user_uuid: UUID,
-    session_id: str,
-    request: Request,
-    auth=AUTH_COOKIE,
-):
-    try:
-        user_org, _role_name = await db.instance.get_user_organization(user_uuid)
-    except ValueError:
-        raise HTTPException(status_code=404, detail="User not found")
-    if user_org.uuid != org_uuid:
-        raise HTTPException(status_code=404, detail="User not found in organization")
-    ctx = await authz.verify(
-        auth,
-        ["auth:admin", f"auth:org:{org_uuid}"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-    )
-    if (  # pragma: no cover - defense in depth, authz.verify already checked
-        "auth:admin" not in ctx.role.permissions
-        and f"auth:org:{org_uuid}" not in ctx.role.permissions
-    ):
-        raise authz.AuthException(
-            status_code=403, detail="Insufficient permissions", mode="forbidden"
-        )
-
-    try:
-        target_key = tokens.decode_session_key(session_id)
-    except ValueError as exc:
-        raise HTTPException(
-            status_code=400, detail="Invalid session identifier"
-        ) from exc
-
-    target_session = await db.instance.get_session(target_key)
-    if not target_session or target_session.user_uuid != user_uuid:
-        raise HTTPException(status_code=404, detail="Session not found")
-
-    await db.instance.delete_session(target_key)
-
-    # Check if admin terminated their own session
-    current_terminated = target_key == session_key(auth)
-    return {"status": "ok", "current_session_terminated": current_terminated}
-
-
-# -------------------- Permissions (global) --------------------
-
-
-@app.get("/permissions")
-async def admin_list_permissions(request: Request, auth=AUTH_COOKIE):
-    ctx = await authz.verify(
-        auth,
-        ["auth:admin", "auth:org:*"],
-        match=permutil.has_any,
-        host=request.headers.get("host"),
-    )
-    perms = await db.instance.list_permissions()
-
-    # Global admins see all permissions
-    if "auth:admin" in ctx.role.permissions:
-        return [{"id": p.id, "display_name": p.display_name} for p in perms]
-
-    # Org admins only see permissions their org can grant
-    grantable = set(ctx.org.permissions or [])
-    filtered_perms = [p for p in perms if p.id in grantable]
-    return [{"id": p.id, "display_name": p.display_name} for p in filtered_perms]
-
-
-@app.post("/permissions")
-async def admin_create_permission(
-    request: Request,
-    payload: dict = Body(...),
-    auth=AUTH_COOKIE,
-):
-    await authz.verify(
-        auth,
-        ["auth:admin"],
-        host=request.headers.get("host"),
-        match=permutil.has_all,
-        max_age="5m",
-    )
-    from ..db import Permission as PermDC
-
-    perm_id = payload.get("id")
-    display_name = payload.get("display_name")
-    if not perm_id or not display_name:
-        raise ValueError("id and display_name are required")
-    querysafe.assert_safe(perm_id, field="id")
-    await db.instance.create_permission(PermDC(id=perm_id, display_name=display_name))
-    return {"status": "ok"}
-
-
-@app.put("/permission")
-async def admin_update_permission(
-    permission_id: str,
-    display_name: str,
-    request: Request,
-    auth=AUTH_COOKIE,
-):
-    await authz.verify(
-        auth, ["auth:admin"], host=request.headers.get("host"), match=permutil.has_all
-    )
-    from ..db import Permission as PermDC
-
-    if not display_name:
-        raise ValueError("display_name is required")
-    querysafe.assert_safe(permission_id, field="permission_id")
-    await db.instance.update_permission(
-        PermDC(id=permission_id, display_name=display_name)
-    )
-    return {"status": "ok"}
-
-
-@app.post("/permission/rename")
-async def admin_rename_permission(
-    request: Request,
-    payload: dict = Body(...),
-    auth=AUTH_COOKIE,
-):
-    await authz.verify(
-        auth, ["auth:admin"], host=request.headers.get("host"), match=permutil.has_all
-    )
-    old_id = payload.get("old_id")
-    new_id = payload.get("new_id")
-    display_name = payload.get("display_name")
-    if not old_id or not new_id:
-        raise ValueError("old_id and new_id required")
-
-    # Sanity check: prevent renaming critical permissions
-    if old_id == "auth:admin":
-        raise ValueError("Cannot rename the master admin permission")
-
-    querysafe.assert_safe(old_id, field="old_id")
-    querysafe.assert_safe(new_id, field="new_id")
-    if display_name is None:
-        perm = await db.instance.get_permission(old_id)
-        display_name = perm.display_name
-    rename_fn = getattr(db.instance, "rename_permission", None)
-    if not rename_fn:  # pragma: no cover - all current backends support rename
-        raise ValueError("Permission renaming not supported by this backend")
-    await rename_fn(old_id, new_id, display_name)
-    return {"status": "ok"}
-
-
-@app.delete("/permission")
-async def admin_delete_permission(
-    permission_id: str,
-    request: Request,
-    auth=AUTH_COOKIE,
-):
-    await authz.verify(
-        auth,
-        ["auth:admin"],
-        host=request.headers.get("host"),
-        match=permutil.has_all,
-        max_age="5m",
-    )
-    querysafe.assert_safe(permission_id, field="permission_id")
-
-    # Sanity check: prevent deleting critical permissions
-    if permission_id == "auth:admin":
-        raise ValueError("Cannot delete the master admin permission")
-
-    await db.instance.delete_permission(permission_id)
-    return {"status": "ok"}