Add version indication and link to our site on profile page (bottom right corner).

.gitignore

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

README.md

@@ -1,38 +1,47 @@
 # 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
-   * Master admin makes permissions available for orgs to assign
-- User Profile and Administration by API and web interface.
-under `/auth/` or `auth.example.com`
-- Reset tokens and additional device linking via QR code or codewords.
-- Pure Python, FastAPI, packaged with prebuilt Vue frontend
+   * Multiple independent orgs
+   * Master admin can do everything or delegate to org admins
+- User Profile and Admin by API and web interface
+- Implements login/reauth/forbidden flows for you
+- Single Sign-On (SSO): Users register once and authenticate across your services
+- 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
-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.  The server will start up on [localhost:4401](http://localhost:4401) *for authentication required*, serving for `*.example.com`. 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`.
 
-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 (see documentation below).
+For production you need a web server such as [Caddy](https://caddyserver.com/) to serve HTTPS on your actual domain names and proxy requests to Paskia and your backend apps (see documentation below).
 
 For a permanent install of `paskia` CLI command, not needing `uvx`:
 
@@ -42,19 +51,178 @@ 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]
 ```
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| Listen address | One of *host***:***port* (default all hosts, port 4401) or **unix:***path***/paskia.socket** (Unix socket) | **localhost:4401** |
-| --rp-id *domain* | Main/top domain | **localhost** |
-| --rp-name *"text"* | Name of your company or site | Same as rp-id |
-| --origin *url* | Explicitly list the domain names served | **https://**_rp-id_ |
-| --auth-host *domain* | Dedicated authentication site (e.g., **auth.example.com**) | **Unspecified:** we use **/auth/** on **every** site under rp-id.|
+| -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) |
+
+To clear a stored setting, pass an empty value like `--auth-host=`. The database is stored in `{rp-id}.paskiadb` in current directory. This can be overridden by environment `PASKIA_DB` if needed.
+
+## Tutorial: From Local Testing to Production
+
+This section walks you through a complete example, from running Paskia locally to protecting a real site in production.
+
+### Step 1: Local Testing
+
+For development and testing, run Paskia without any arguments:
+
+```fish
+paskia
+```
+
+This starts the server on [localhost:4401](http://localhost:4401) with passkeys bound to `localhost`. On first run, Paskia prints a registration link for the Master Admin—click it to register your first passkey.
+
+### Step 2: Production Configuration
+
+For a real deployment, configure Paskia with your domain name (rp-id). This enables SSO setup for that domain and any subdomains.
+
+```fish
+paskia --rp-id=example.com --rp-name="Example Corp" --save
+```
+
+This binds passkeys to the rp-id, allowing them to be used there or on any subdomain of it. The `--rp-name` is the branding shown in UI and registered with passkeys for everything on your domain (rp id). The `--save` option stores these settings in the database, so future runs only need `paskia --rp-id example.com`, of which we will make use of with the systemd config later on.
+
+### Step 3: Set Up Caddy
+
+Install [Caddy](https://caddyserver.com/) and copy the [auth folder](caddy/auth) to `/etc/caddy/auth`. Say your current unprotected Caddyfile looks like this:
+
+```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 4: 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 5: 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 6: Run Paskia as a Service
+
+Create a system user paskia, install UV on the system, and create a systemd unit:
+
+```fish
+sudo useradd --system --home-dir /srv/paskia --create-home paskia
+curl -LsSf https://astral.sh/uv/install.sh | sudo env UV_INSTALL_DIR=/usr/local/bin 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 --rp-id=%i
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then enable and start, view output for registration link:
+
+```fish
+sudo systemctl enable --now paskia@example.com && sudo journalctl -u paskia@example.com -f -n 30 -o cat
+```
+
+### Optional: Dedicated Authentication Site
+
+By default, Paskia serves login dialogs and admin interface at the `/auth/` path on each protected site. For a cleaner setup, you can use a dedicated authentication subdomain instead. We assume you have your DNS setup for that domain or a wildcard of all subdomains to current machine.
+
+Configure Paskia with the authentication host:
+
+```fish
+paskia --rp-id example.com --auth-host=auth.example.com --save
+```
+
+Add a Caddy configuration for the authentication domain:
+
+```caddyfile
+auth.example.com {
+    reverse_proxy :4401
+}
+```
+
+Now all authentication happens at `auth.example.com` instead of `/auth/` paths on your apps. No other changes are needed. Your existing protected sites continue to work as before but they just forward to the dedicated site for user profile and other such functionality.
+
+
 
 ## Further Documentation
 

docs/Integration.md

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

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>
@@ -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 });
-
-            // 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' });
-            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,
-        // then back to the original URL after authentication.
-        function browserNav(url) {
+        window.browserNav = function(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

@@ -148,6 +148,3 @@ onUnmounted(() => {
   removeAuthIframe()
 })
 </script>
-
-<style scoped>
-</style>

frontend/auth/admin/AdminApp.vue

@@ -239,12 +239,44 @@ function deleteOrg(org) {
 
 function createUserInRole(org, role) { openDialog('user-create', { org, role }) }
 
-async function moveUserToRole(org, user, targetRoleDisplayName) {
-  if (user.role === targetRoleDisplayName) return
+function deleteUser(user, userDetail) {
+  const credentialCount = 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' })
+    authStore.showMessage(`User "${userName}" deleted.`, 'success', 2500)
+    await loadOrgs()
+    window.location.hash = `#org/${orgUuid}`
+  } catch (e) {
+    authStore.showMessage(e.message || 'Failed to delete user', 'error')
+  }
+}
+
+async function moveUserToRole(user, targetRoleUuid) {
+  if (user.role_uuid === targetRoleUuid) return
+  try {
+    await apiJson(`/auth/api/admin/users/${user.uuid}/role`, {
       method: 'PATCH',
-      body: { role: targetRoleDisplayName }
+      body: { role_uuid: targetRoleUuid }
     })
     await loadOrgs()
   } catch (e) {
@@ -268,7 +300,7 @@ function onRoleDrop(e, org, role) {
     const data = JSON.parse(e.dataTransfer.getData('text/plain'))
     if (data.org !== 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)
+    if (user) moveUserToRole(user, role.uuid)
   } catch (_) { /* ignore */ }
 }
 
@@ -279,7 +311,7 @@ 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}/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()
@@ -299,7 +331,7 @@ async function toggleRolePermission(role, pid, checked) {
 
   try {
     const method = checked ? 'POST' : 'DELETE'
-    await apiJson(`/auth/api/admin/orgs/${role.org}/roles/${role.uuid}/permissions/${pid}`, {
+    await apiJson(`/auth/api/admin/roles/${role.uuid}/permissions/${pid}`, {
       method
     })
     await loadOrgs()
@@ -406,7 +438,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}/users/${u.uuid}`)
+    userDetail.value = await apiJson(`/auth/api/admin/users/${u.uuid}`)
   } catch (e) {
     userDetail.value = { error: e.message }
   }
@@ -542,7 +574,7 @@ async function refreshUserDetail() {
   await loadOrgs()
   if (selectedUser.value) {
     try {
-      userDetail.value = await apiJson(`/auth/api/admin/orgs/${selectedUser.value.org}/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') }
   }
 }
@@ -604,7 +636,7 @@ async function submitDialog() {
 
       // Close dialog immediately, then perform async operation
       closeDialog()
-      apiJson(`/auth/api/admin/orgs/${role.org}/roles/${role.uuid}`, { method: 'PATCH', body: { display_name: name } })
+      apiJson(`/auth/api/admin/roles/${role.uuid}`, { method: 'PATCH', body: { display_name: name } })
         .then(() => {
           authStore.showMessage(`Role renamed to "${name}".`, 'success', 2500)
           loadOrgs()
@@ -632,7 +664,7 @@ async function submitDialog() {
 
       // Close dialog immediately, then perform async operation
       closeDialog()
-      apiJson(`/auth/api/admin/orgs/${user.org}/users/${user.uuid}/display-name`, { method: 'PATCH', body: { display_name: name } })
+      apiJson(`/auth/api/admin/users/${user.uuid}/display-name`, { method: 'PATCH', body: { display_name: name } })
         .then(() => {
           authStore.showMessage(`User renamed to "${name}".`, 'success', 2500)
           onUserNameSaved()
@@ -771,6 +803,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"
@@ -808,7 +841,6 @@ async function submitDialog() {
 
 <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); }

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

@@ -8,7 +8,7 @@
 </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}
@@ -30,14 +30,9 @@ function extractRemoteToken() {
   return null
 }
 
-// Detect mode from URL hash fragment
-const authMode = computed(() => {
-  const params = new URLSearchParams(window.location.hash.slice(1))
-  const mode = params.get('mode')
-  if (mode === 'reauth') return 'reauth'
-  if (mode === 'forbidden') return 'forbidden'
-  return 'login'
-})
+// Parse URL hash fragment
+const hashParams = new URLSearchParams(window.location.hash.slice(1))
+const authMode = ['reauth', 'forbidden'].includes(hashParams.get('mode')) ? hashParams.get('mode') : 'login'
 
 function postToParent(message) {
   if (window.parent && window.parent !== window) {

frontend/auth/restricted/index.html

@@ -3,6 +3,8 @@
   <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!=='light'&&t!=='dark')t=new URLSearchParams(location.hash.slice(1)).get('theme');(t==='dark'||t!=='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/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 - first URL param wins, then localStorage
+import { applyTheme, getCachedTheme } from '@/utils/theme.js'
+
+function getTheme() {
+  const params = new URLSearchParams(location.hash.slice(1))
+  return params.get('theme') || getCachedTheme() || ''
+}
+
+// Apply theme class to document root
+applyTheme(getTheme())
+addEventListener('hashchange', () => applyTheme(getTheme()))

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%;">
-        <header class="view-header" style="text-align: center;">
+      <div class="surface surface--tight reset-container">
+        <header class="view-header reset-header">
           <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>
@@ -203,13 +203,14 @@ onMounted(async () => {
 </script>
 
 <style scoped>
-.center {
-  text-align: center;
+.reset-container {
+  max-width: 560px;
+  margin: 0 auto;
+  width: 100%;
 }
 
-.button-row.center {
-  display: flex;
-  justify-content: center;
+.reset-header {
+  text-align: center;
 }
 
 .section-body {

frontend/src/admin/AdminDialogs.vue

@@ -110,8 +110,5 @@ const rpId = computed(() => props.settings?.rp_id || 'the configured domain')
 </template>
 
 <style scoped>
-.error { color: var(--color-danger-text); }
-.small { font-size: 0.9rem; }
-.muted { color: var(--color-text-muted); }
 .optional { font-weight: normal; color: var(--color-text-muted); font-size: 0.85em; }
 </style>

frontend/src/admin/AdminOrgDetail.vue

@@ -339,6 +339,7 @@ defineExpose({ focusFirstElement })
           <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="r.users.length === 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>
@@ -369,9 +370,8 @@ defineExpose({ focusFirstElement })
             </li>
           </ul>
         </template>
-        <div v-else class="empty-role" @keydown="e => handleEmptyRoleKeydown(e, roleIndex)">
+        <div v-else class="empty-role">
           <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>
         </div>
       </div>
     </div>
@@ -381,25 +381,15 @@ defineExpose({ focusFirstElement })
 .card.surface { padding: var(--space-lg); }
 .org-title { display: flex; align-items: center; gap: var(--space-sm); margin-bottom: var(--space-lg); }
 .org-name { font-size: 1.5rem; 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; gap: var(--space-lg); margin-top: var(--space-lg); }
 .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-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; }
@@ -407,9 +397,6 @@ defineExpose({ focusFirstElement })
 .user-chip .meta { font-size: 0.7rem; color: var(--color-text-muted); }
 .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; }
 .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

@@ -353,8 +353,6 @@ defineExpose({ focusFirstElement })
 <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; }
@@ -363,24 +361,10 @@ defineExpose({ focusFirstElement })
 .perm-title { font-weight: 600; color: var(--color-heading); }
 .perm-id-info { font-size: 0.8rem; color: var(--color-text-muted); display: flex; align-items: center; gap: 0.5rem; flex-wrap: wrap; }
 .perm-domain { color: var(--color-text-muted); 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-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); }
 </style>

frontend/src/admin/AdminUserDetail.vue

@@ -17,7 +17,7 @@ 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({})
@@ -45,7 +45,7 @@ function handleEditName() {
 
 async function handleDelete(credential) {
   try {
-    const data = await apiJson(`/auth/api/admin/orgs/${props.selectedUser.org}/users/${props.selectedUser.uuid}/credentials/${credential.credential}`, { 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 {
@@ -61,7 +61,7 @@ async function handleTerminateSession(session) {
   if (!sessionId) return
   terminatingSessions.value = { ...terminatingSessions.value, [sessionId]: true }
   try {
-    const data = await apiJson(`/auth/api/admin/orgs/${props.selectedUser.org}/users/${props.selectedUser.uuid}/sessions/${sessionId}`, { method: 'DELETE' })
+    const data = await apiJson(`/auth/api/admin/users/${props.selectedUser.uuid}/sessions/${sessionId}`, { method: 'DELETE' })
     if (data.status === 'ok') {
       if (data.current_session_terminated) {
         sessionStorage.clear()
@@ -83,6 +83,10 @@ async function handleTerminateSession(session) {
   }
 }
 
+async function handleDeleteUser() {
+  emit('deleteUser')
+}
+
 // Handle user info section keynav
 function handleUserInfoKeydown(event) {
   if (hasActiveModal.value || props.navigationDisabled) return
@@ -183,24 +187,27 @@ defineExpose({ focusFirstElement })
         :loading="loading"
         :org-display-name="userDetail.org.display_name"
         :role-name="userDetail.role"
-        :update-endpoint="`/auth/api/admin/orgs/${selectedUser.org}/users/${selectedUser.uuid}/display-name`"
+        :update-endpoint="`/auth/api/admin/users/${selectedUser.uuid}/display-name`"
         @saved="$emit('onUserNameSaved')"
         @edit-name="handleEditName"
-      />
+      >
+        <div class="admin-actions">
+          <button
+            class="btn-primary"
+            @click="$emit('generateUserRegistrationLink', selectedUser)"
+            :disabled="loading"
+          >{{ userDetail?.credentials?.length ? '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>
@@ -238,7 +245,7 @@ defineExpose({ focusFirstElement })
     </div>
     <RegistrationLinkModal
       v-if="showRegModal"
-      :endpoint="`/auth/api/admin/orgs/${selectedUser.org}/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"
@@ -248,14 +255,6 @@ defineExpose({ focusFirstElement })
 
 <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/style.css

@@ -1,68 +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-surface: #eff6ff;
-  --color-surface-subtle: #dbeafe;
-  --color-border: #2563eb;
-  --color-border-strong: #1e40af;
-  --color-heading: #1e3a8a;
-  --color-text: #1e293b;
-  --color-text-muted: #475569;
-  --color-link: #1d4ed8;
-  --color-link-hover: #1e40af;
-  --color-accent: #2563eb;
-  --color-accent-strong: #1e40af;
-  --color-accent-contrast: #ffffff;
-  --color-success-text: #166534;
-  --color-success-bg: #dcfce7;
-  --color-error-text: #b91c1c;
-  --color-error-bg: #fee2e2;
-  --color-info-text: #1e40af;
-  --color-info-bg: #dbeafe;
-  --color-danger: #dc2626;
-  --shadow-soft: 0 10px 30px rgba(30, 64, 175, 0.15);
-  --radius-none: 0;
+  --color-canvas: white;
+  --color-surface: oklch(0.95 0.03 var(--hue));
+  --color-surface-subtle: oklch(0.9 0.03 var(--hue));
+  --color-surface-hover: white;
+  --color-dialog: white;
+  --color-border: oklch(0.8 0.02 var(--hue));
+  --color-border-strong: oklch(0.55 0.15 var(--hue));
+  --color-heading: oklch(0.3 0.05 var(--hue));
+  --color-text: oklch(0.25 0.02 var(--hue));
+  --color-text-muted: oklch(0.5 0.02 var(--hue));
+  --color-link: oklch(0.5 0.18 var(--hue));
+  --color-link-hover: oklch(0.45 0.2 var(--hue));
+  --color-accent: oklch(0.55 0.2 var(--hue));
+  --color-accent-strong: oklch(0.45 0.2 var(--hue));
+  --color-accent-contrast: white;
+  --color-secondary: oklch(0.55 0.05 var(--hue));
+  --color-secondary-strong: oklch(0.45 0.05 var(--hue));
+  --color-success-text: oklch(0.4 0.15 0.4turn);
+  --color-success-bg: oklch(0.95 0.03 0.4turn);
+  --color-error-text: oklch(0.45 0.2 0.07turn);
+  --color-error-bg: oklch(0.95 0.03 0.07turn);
+  --color-info-text: oklch(0.45 0.15 var(--hue));
+  --color-info-bg: oklch(0.95 0.02 var(--hue));
+  --color-danger: oklch(0.55 0.22 0.07turn);
+  --color-primary: oklch(0.55 0.2 var(--hue));
+  --color-error: oklch(0.45 0.2 0.07turn);
+  --color-success: oklch(0.4 0.15 0.4turn);
+  --color-bg: oklch(0.97 0.005 var(--hue));
+  --color-accent-soft: oklch(0.95 0.08 var(--hue));
+  --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-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 {
-    --color-canvas: #0f172a;
-    --color-surface: #141b2f;
-    --color-surface-subtle: #1b243b;
-    --color-border: #25304a;
-    --color-border-strong: #3d4d6b;
-    --color-heading: #fff;
-    --color-text: #e2e8f0;
-    --color-text-muted: #94a3b8;
-    --color-link: #60a5fa;
-    --color-link-hover: #93c5fd;
-    --color-accent: #60a5fa;
-    --color-accent-strong: #3b82f6;
-    --color-accent-contrast: #0b1120;
-    --color-success-text: #34d399;
-    --color-success-bg: #1a4d2e;
-    --color-error-text: #fca5a5;
-    --color-error-bg: #4a1f1f;
-    --color-info-text: #bae6fd;
-    --color-info-bg: #1e3a5f;
-    --color-danger: #f87171;
-    --shadow-soft: 0 0 0 #000000;
-  }
+:root.dark {
+  --color-canvas: oklch(0.17 0.05 var(--hue));
+  --color-surface: oklch(0.22 0.05 var(--hue));
+  --color-surface-subtle: oklch(0.25 0.05 var(--hue));
+  --color-surface-hover: oklch(0.28 0.05 var(--hue));
+  --color-dialog: oklch(0.22 0.05 var(--hue));
+  --color-border: oklch(0.3 0.05 var(--hue));
+  --color-border-strong: oklch(0.4 0.05 var(--hue));
+  --color-heading: white;
+  --color-text: oklch(0.9 0.01 var(--hue));
+  --color-text-muted: oklch(0.7 0.02 var(--hue));
+  --color-link: oklch(0.7 0.15 var(--hue));
+  --color-link-hover: oklch(0.8 0.12 var(--hue));
+  --color-accent: oklch(0.7 0.15 var(--hue));
+  --color-accent-strong: oklch(0.6 0.18 var(--hue));
+  --color-accent-contrast: oklch(0.12 0.03 var(--hue));
+  --color-secondary: oklch(0.6 0.05 var(--hue));
+  --color-secondary-strong: oklch(0.5 0.05 var(--hue));
+  --color-success-text: oklch(0.75 0.15 0.4turn);
+  --color-success-bg: oklch(0.3 0.08 0.4turn);
+  --color-error-text: oklch(0.8 0.12 0.07turn);
+  --color-error-bg: oklch(0.3 0.08 0.07turn);
+  --color-info-text: oklch(0.8 0.1 var(--hue));
+  --color-info-bg: oklch(0.3 0.05 var(--hue));
+  --color-danger: oklch(0.7 0.18 0.07turn);
+  --color-primary: oklch(0.7 0.15 var(--hue));
+  --color-error: oklch(0.8 0.12 0.07turn);
+  --color-success: oklch(0.75 0.15 0.4turn);
+  --color-bg: oklch(0.18 0.03 var(--hue));
+  --color-accent-soft: oklch(0.25 0.08 var(--hue));
+  --shadow-soft: 0 0 0 black;
+  --shadow-xl: 0 10px 40px rgba(0, 0, 0, 0.4);
 }
 
 *,
@@ -78,7 +100,6 @@ html {
 }
 
 body {
-  color-scheme: light dark;
   overflow: auto;
   scrollbar-gutter: stable;
   height: 100%;
@@ -132,6 +153,7 @@ a:focus-visible {
 }
 
 .view-root {
+  position: relative;
   flex: 1;
   width: 100%;
   display: flex;
@@ -150,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;
@@ -197,6 +238,7 @@ a:focus-visible {
   flex-wrap: nowrap;
   gap: 0.75rem;
   justify-content: flex-start;
+  width: 100%;
 }
 
 .button-row button {
@@ -229,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 {
@@ -237,43 +280,41 @@ button:disabled {
 }
 
 .btn-primary {
-  background: var(--color-accent);
+  background: linear-gradient(to bottom, oklch(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, oklch(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;
-  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);
+  background: linear-gradient(to bottom, oklch(1 0 0 / 0.15), transparent 60%) var(--color-secondary);
   color: var(--color-accent-contrast);
   border-color: transparent;
 }
 
-.btn-danger:hover:not(:disabled) {
-  filter: brightness(0.92);
+.btn-secondary:hover:not(:disabled),
+.btn-secondary:focus-visible {
+  background: linear-gradient(to bottom, oklch(1 0 0 / 0.15), transparent 60%) var(--color-secondary-strong);
+  box-shadow: var(--shadow-soft);
 }
 
-/* Focus-visible outlines for buttons */
-.btn-primary:focus-visible,
-.btn-secondary:focus-visible,
+.btn-danger {
+  background: linear-gradient(to bottom, oklch(1 0 0 / 0.15), transparent 60%) var(--color-danger);
+  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, oklch(1 0 0 / 0.15), transparent 60%) var(--color-danger);
+  filter: brightness(0.92);
+  box-shadow: var(--shadow-soft);
 }
 
 input[type="text"],
@@ -331,10 +372,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;
@@ -360,6 +509,10 @@ th {
   display: none;
 }
 
+.global-status.show {
+  display: block;
+}
+
 .global-status .status {
   display: flex;
   align-items: center;
@@ -407,7 +560,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%);
@@ -429,7 +582,7 @@ th {
 
 .qr-code {
   padding: 1rem;
-  background: #fff;
+  background: white;
   box-shadow: var(--shadow-soft);
 }
 
@@ -567,7 +720,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; }
 
 
@@ -692,8 +845,8 @@ th {
   width: 100vw;
   height: 100vh;
   background: transparent;
-  backdrop-filter: blur(.1rem) brightness(0.7);
-  -webkit-backdrop-filter: blur(.1rem) brightness(0.7);
+  backdrop-filter: blur(.2rem) brightness(0.7);
+  -webkit-backdrop-filter: blur(.2rem) brightness(0.7);
   display: flex;
   align-items: center;
   justify-content: center;
@@ -711,7 +864,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,7 +886,7 @@ th {
 
 .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;
@@ -754,3 +907,28 @@ th {
   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/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>
@@ -125,12 +125,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-top: 4px solid var(--color-primary);
+  border: 3px solid var(--color-border);
+  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/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/ProfileView.vue

@@ -1,12 +1,17 @@
 <template>
-  <section class="view-root" data-view="profile">
-    <header class="view-header">
-      <h1>User Profile</h1>
-      <Breadcrumbs ref="breadcrumbs" :entries="breadcrumbEntries" @keydown="handleBreadcrumbKeydown" />
-      <p class="view-lede">Account dashboard for managing credentials and authenticating with other devices.</p>
-    </header>
+  <section class="view-root view-root--profile" data-view="profile">
+    <div class="view-header-wrapper">
+      <div class="theme-toggle">
+        <ThemeSelector />
+      </div>
+      <header class="view-header">
+        <h1>User Profile</h1>
+        <Breadcrumbs ref="breadcrumbs" :entries="breadcrumbEntries" @keydown="handleBreadcrumbKeydown" />
+        <p class="view-lede">Account dashboard for managing credentials and authenticating with other devices.</p>
+      </header>
+    </div>
 
-    <section class="section-block" ref="userInfoSection">
+    <section class="section-block section-block--constrained" ref="userInfoSection">
       <UserBasicInfo
         v-if="authStore.userInfo?.ctx"
         ref="userBasicInfo"
@@ -35,7 +40,7 @@
       </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>
@@ -67,6 +72,7 @@
       :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"
@@ -85,7 +91,7 @@
       </form>
     </Modal>
 
-    <section class="section-block">
+    <section :class="['section-block', { 'section-block--constrained': !useWideLayout }]">
       <div class="button-row" ref="logoutButtons">
         <button
           type="button"
@@ -101,8 +107,11 @@
           <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>
-      <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>
+      <div class="logout-footer">
+        <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 }}. You'll need to log in again with your passkey afterwards.</p>
+        <a class="paskia-version" href="https://git.zi.fi/leovasanko/paskia" target="_blank" rel="noopener noreferrer">Paskia {{ paskiaVersion }}</a>
+      </div>
     </section>
     <RegistrationLinkModal
       v-if="showRegLink"
@@ -117,6 +126,7 @@
 import { ref, onMounted, onUnmounted, computed, watch } from 'vue'
 import Breadcrumbs from '@/components/Breadcrumbs.vue'
 import CredentialList from '@/components/CredentialList.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'
@@ -301,6 +311,7 @@ const handleDelete = async (credential) => {
 }
 
 const rpName = computed(() => authStore.settings?.rp_name || 'this service')
+const paskiaVersion = computed(() => authStore.settings?.version || '')
 const sessions = computed(() => authStore.userInfo?.sessions || [])
 const currentSessionHost = computed(() => {
   const currentSession = sessions.value.find(session => session.is_current)
@@ -329,6 +340,22 @@ const isAdmin = computed(() => {
   return perms.includes('auth:admin') || perms.includes('auth:org:admin')
 })
 const hasMultipleSessions = computed(() => sessions.value.length > 1)
+const credentials = computed(() => authStore.userInfo?.credentials || [])
+const useWideLayout = computed(() => {
+  // Check if any single site has more than 8 sessions
+  const groups = {}
+  for (const session of 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)
+
+  // Check if passkeys exceed 8
+  const hasManyCredentials = credentials.value.length > 8
+
+  return hasLargeSessionGroup || hasManyCredentials
+})
 const breadcrumbEntries = computed(() => { const entries = [{ label: 'Auth', href: makeUiHref() }]; if (isAdmin.value) entries.push({ label: 'Admin', href: adminUiPath() }); return entries })
 
 const saveName = async () => {
@@ -346,14 +373,14 @@ const saveName = async () => {
 </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 {
-  font-size: 0.75rem;
-  color: var(--color-text-muted);
-}
+.remote-auth-description { font-size: 0.75rem; color: var(--color-text-muted); }
+.theme-toggle { position: absolute; top: var(--layout-padding); right: var(--layout-padding); }
 </style>

frontend/src/components/RegistrationLinkModal.vue

@@ -3,14 +3,14 @@
     <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
@@ -33,7 +33,7 @@
 </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 'paskia'
 import { formatDate } from '@/utils/helpers'
@@ -51,16 +51,31 @@ 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
       await nextTick()

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>
@@ -921,10 +919,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 +939,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 -->
@@ -293,10 +293,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 +495,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"
@@ -284,7 +284,6 @@ defineExpose({
 </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,5 +1,5 @@
 <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>
@@ -30,7 +30,7 @@
                 @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>
@@ -75,6 +75,7 @@ const props = defineProps({
   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'])

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/stores/auth.js

@@ -2,6 +2,7 @@ import { defineStore } from 'pinia'
 import { register, authenticate } from '@/utils/passkey'
 import { getSettings } from '@/utils/settings'
 import { apiJson } from 'paskia'
+import { updateThemeFromSession } from '@/utils/theme'
 
 export const useAuthStore = defineStore('auth', {
   state: () => ({
@@ -86,6 +87,7 @@ export const useAuthStore = defineStore('auth', {
     async loadUserInfo() {
       try {
         this.userInfo = await apiJson('/auth/api/user-info', { method: 'POST' })
+        updateThemeFromSession(this.userInfo?.ctx)
         console.log('User info loaded:', this.userInfo)
       } catch (error) {
         // Suppress toast for 401/403 errors - the auth iframe will handle these

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

@@ -1,17 +1,18 @@
 /**
  * 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
  *
- * Environment variables (with defaults):
- *   FASTAPI_VUE_BACKEND_URL=http://localhost:5180 - Backend API URL for proxying
+ * Options:
+ *   paths - Array of paths to proxy (default: ["/api"])
  */
 
-const backendUrl = process.env.FASTAPI_VUE_BACKEND_URL || "http://localhost:5180"
-
 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) {
@@ -23,7 +24,7 @@ export default function fastapiVue({ paths = ["/api"] } = {}) {
   }
 
   return {
-    name: "fastapi-vite",
+    name: "vite-plugin-fastapi-paskia",
     config: () => ({
       server: { proxy },
       build: {

paskia-js/README.md

@@ -1,6 +1,6 @@
 # Paskia
 
-![Paskia](https://git.zi.fi/leovasanko/paskia/raw/main/docs/screenshots/forbidden-light.webp)
+![Screenshot](https://git.zi.fi/leovasanko/paskia/raw/main/docs/screenshots/forbidden-light.webp)
 
 JavaScript utilities for [Paskia authentication system](https://git.zi.fi/leovasanko/paskia) integration into web apps.
 

paskia-js/package.json

@@ -1,7 +1,15 @@
 {
   "name": "paskia",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",
@@ -26,7 +34,8 @@
   "keywords": [
     "auth",
     "authentication",
-    "paskia"
-  ],
-  "license": "Unlicense"
+    "paskia",
+    "passkey",
+    "webauthn"
+  ]
 }

paskia-js/src/overlay.ts

@@ -14,8 +14,8 @@ body::before {
   transition: all 0.2s ease-out;
 }
 body.paskia-backdrop::before {
-  -webkit-backdrop-filter: blur(.2rem) brightness(0.5);
-  backdrop-filter: blur(.2rem) brightness(0.5);
+  backdrop-filter: blur(.2rem) brightness(0.7);
+  -webkit-backdrop-filter: blur(.2rem) brightness(0.7);
   visibility: visible;
 }
 body.paskia-backdrop {

paskia/authsession.py

@@ -14,6 +14,7 @@ from uuid import UUID
 
 from paskia import db
 from paskia.config import RESET_LIFETIME, SESSION_LIFETIME
+from paskia.db.structs import ResetToken
 from paskia.util import hostutil
 
 if TYPE_CHECKING:
@@ -33,7 +34,7 @@ def reset_expires() -> datetime:
 def get_reset(token: str) -> "ResetToken":
     """Validate a credential reset token."""
 
-    record = db.get_reset_token(token)
+    record = ResetToken.by_passphrase(token)
     if record:
         return record
     raise ValueError("This authentication link is no longer valid.")

paskia/bootstrap.py

@@ -10,38 +10,42 @@ import asyncio
 import logging
 
 from paskia import authsession, db, globals
-from paskia.util import hostutil, passphrase
+from paskia.db.structs import Config
+from paskia.util import hostutil
 
 logger = logging.getLogger(__name__)
 
 # Shared log message template for admin reset links
-ADMIN_RESET_MESSAGE = """\
-%s
-
+ADMIN_RESET_MESSAGE = """
 👤 Admin  %s
    - Use this link to register a Passkey for the admin user!
 """
 
 
-def _log_reset_link(message: str, passphrase: str) -> str:
+def _log_reset_link(passphrase: str, message: str | None = None) -> str:
     """Log a reset link message and return the URL."""
     reset_link = hostutil.reset_link_url(passphrase)
-    logger.info(ADMIN_RESET_MESSAGE, message, reset_link)
+    if message:
+        logger.info(message)
+    logger.info(ADMIN_RESET_MESSAGE, reset_link)
     return reset_link
 
 
-async def bootstrap_system() -> None:
+async def bootstrap_system(config: Config | None = None) -> None:
     """
     Bootstrap the entire system with default data.
 
     Uses db.bootstrap() which performs all operations in a single transaction.
     The transaction log will show a single "bootstrap" action with all changes.
+
+    Args:
+        config: Configuration to store (rp_id, rp_name, origins, etc.)
     """
     # Call the single-transaction bootstrap function
-    reset_passphrase = db.bootstrap()
+    reset_passphrase = db.bootstrap(config=config)
 
     # Log the reset link (this is separate from the transaction log)
-    _log_reset_link("✅ Bootstrap completed!", reset_passphrase)
+    _log_reset_link(reset_passphrase, "✅ Bootstrap completed!")
 
 
 async def check_admin_credentials() -> bool:
@@ -52,17 +56,24 @@ 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
         p = next(
             (p for p in db.data().permissions.values() if p.scope == "auth:admin"), None
         )
-        if not p or not p.orgs:
+        if not p:
             return False
 
-        # Get users from the first organization with admin permission
-        first_org_uuid = next(iter(p.orgs))
-        org_users = db.get_organization_users(first_org_uuid)
-        admin_users = [user for user, role in org_users if role == "Administration"]
+        perm_uuid = p.uuid
+
+        # Find all roles that have the auth:admin permission
+        admin_roles = [
+            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
@@ -70,18 +81,17 @@ async def check_admin_credentials() -> bool:
         # Check first admin user for credentials
         admin_user = admin_users[0]
 
-        if not db.get_user_credential_ids(admin_user.uuid):
+        if not admin_user.credential_ids:
             # Admin exists but has no credentials, create reset link
+            logger.info("⚠️  Admin user has no credentials!")
 
-            token = passphrase.generate()
             expiry = authsession.reset_expires()
-            db.create_reset_token(
+            token = db.create_reset_token(
                 user_uuid=admin_user.uuid,
-                passphrase=token,
                 expiry=expiry,
                 token_type="admin registration",
             )
-            _log_reset_link("⚠️  Admin user has no credentials!", token)
+            _log_reset_link(token)
             return True
 
         return False
@@ -90,10 +100,13 @@ 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
     """
@@ -106,7 +119,7 @@ async def bootstrap_if_needed() -> bool:
 
     # 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
 
 

paskia/db/__init__.py

@@ -26,11 +26,11 @@ from paskia.db.background import (
     stop_background,
     stop_cleanup,
 )
+from paskia.db.bootstrap import bootstrap
+from paskia.db.lifecycle import cleanup_expired, init
 from paskia.db.operations import (
     add_permission_to_org,
     add_permission_to_role,
-    bootstrap,
-    cleanup_expired,
     create_credential,
     create_credential_session,
     create_org,
@@ -47,15 +47,11 @@ from paskia.db.operations import (
     delete_session,
     delete_sessions_for_user,
     delete_user,
-    get_organization_users,
-    get_reset_token,
-    get_user_credential_ids,
-    get_user_organization,
-    init,
     login,
     remove_permission_from_org,
     remove_permission_from_role,
     set_session_host,
+    update_config,
     update_credential_sign_count,
     update_org_name,
     update_permission,
@@ -63,10 +59,11 @@ from paskia.db.operations import (
     update_session,
     update_user_display_name,
     update_user_role,
-    update_user_role_in_organization,
+    update_user_theme,
 )
 from paskia.db.structs import (
     DB,
+    Config,
     Credential,
     Org,
     Permission,
@@ -85,6 +82,7 @@ def data() -> DB:
 
 __all__ = [
     # Types
+    "Config",
     "Credential",
     "DB",
     "Org",
@@ -110,10 +108,6 @@ __all__ = [
     "build_session",
     "build_user",
     # Read ops
-    "get_organization_users",
-    "get_reset_token",
-    "get_user_credential_ids",
-    "get_user_organization",
     # Write ops
     "add_permission_to_org",
     "add_permission_to_role",
@@ -139,6 +133,7 @@ __all__ = [
     "remove_permission_from_org",
     "remove_permission_from_role",
     "set_session_host",
+    "update_config",
     "update_credential_sign_count",
     "update_org_name",
     "update_permission",
@@ -146,5 +141,5 @@ __all__ = [
     "update_session",
     "update_user_display_name",
     "update_user_role",
-    "update_user_role_in_organization",
+    "update_user_theme",
 ]

paskia/db/background.py

@@ -8,7 +8,8 @@ import asyncio
 import logging
 from datetime import UTC, datetime
 
-from paskia.db.operations import _store, cleanup_expired
+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
@@ -20,11 +21,11 @@ _background_task: asyncio.Task | None = None
 
 async def flush() -> None:
     """Write all pending database changes to disk."""
-
-    if _store is None:
+    store = _ops._store
+    if store is None:
         _logger.warning("flush() called but _store is None")
         return
-    await _store.flush()
+    await store.flush()
 
 
 async def _background_loop():
@@ -74,21 +75,18 @@ async def start_background():
                     _logger.debug("Background task in different event loop, restarting")
                     _background_task = None
                 else:
-                    # Task is running in the same event loop - this is an error
-                    raise RuntimeError(
-                        "Background task is already running. "
-                        "start_background() must not be called multiple times in the same event loop."
+                    # 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"
                     )
-            except RuntimeError:
-                raise  # Re-raise RuntimeError from above
+                    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())
-    else:
-        _logger.debug("Background task already running: %s", _background_task)
 
 
 async def stop_background():

paskia/db/bootstrap.py

@@ -0,0 +1,122 @@
+"""
+Bootstrap operations for initial system setup.
+"""
+
+from datetime import UTC, datetime
+
+import uuid7
+
+import paskia.db.operations as _ops
+from paskia.db.structs import Config, Org, Permission, ResetToken, Role, User
+
+
+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:
+        from paskia.authsession import reset_expires  # noqa: PLC0415
+
+        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,
+        )
+        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
+
+    return reset_passphrase

paskia/db/jsonl.py

@@ -4,6 +4,8 @@ JSONL persistence layer for the database.
 
 import copy
 import logging
+import os
+import signal
 from collections import deque
 from contextlib import contextmanager
 from datetime import UTC, datetime
@@ -67,53 +69,55 @@ def create_change_record(
 
 
 # Actions that are allowed to create a new database file
-_BOOTSTRAP_ACTIONS = frozenset({"bootstrap", "migrate:sql"})
+_BOOTSTRAP_ACTIONS = frozenset({"bootstrap"})
+
+# Flag to prevent duplicate error messages on fatal flush failure
+_flush_failed = False
 
 
 async def flush_changes(
     db_path: Path,
     pending_changes: deque[_ChangeRecord],
-) -> bool:
+) -> None:
     """Write all pending changes to disk.
 
     Args:
         db_path: Path to the JSONL database file
         pending_changes: Queue of pending change records (will be cleared on success)
 
-    Returns:
-        True if flush succeeded, False otherwise
+    On failure, logs an error and sends SIGTERM to trigger graceful shutdown.
     """
-    if not pending_changes:
-        return True
+    global _flush_failed
+    if _flush_failed or not pending_changes:
+        return
 
     if not db_path.exists():
         first_action = pending_changes[0].a
         if first_action not in _BOOTSTRAP_ACTIONS:
             _logger.error(
                 "Refusing to create database file with action '%s' - "
-                "only bootstrap or migrate can create a new database",
+                "only bootstrap can create a new database",
                 first_action,
             )
-            pending_changes.clear()
-            return False
+            _flush_failed = True
+            os.kill(os.getpid(), signal.SIGTERM)
+            return
 
     changes_to_write = list(pending_changes)
-    pending_changes.clear()
 
     try:
         lines = [_change_encoder.encode(change) for change in changes_to_write]
         if not lines:
-            return True
+            pending_changes.clear()
+            return
 
         async with aiofiles.open(db_path, "ab") as f:
             await f.write(b"\n".join(lines) + b"\n")
-        return True
-    except OSError:
-        _logger.exception("Failed to flush database changes")
-        # Re-queue the changes on failure
-        for change in reversed(changes_to_write):
-            pending_changes.appendleft(change)
-        return False
+        pending_changes.clear()
+    except OSError as e:
+        _logger.error("Failed to flush database: %s", e)
+        _flush_failed = True
+        os.kill(os.getpid(), signal.SIGTERM)
 
 
 class JsonlStore:
@@ -130,10 +134,13 @@ class JsonlStore:
         self._transaction_snapshot: dict[str, Any] | None = None
         self._current_version: int = DBVER  # Schema version for new databases
 
-    async def load(self, db_path: str | None = None) -> None:
+    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
 
@@ -152,8 +159,10 @@ class JsonlStore:
                     self._current_version = change.get("v", 0)
                 except Exception as e:
                     raise ValueError(f"Error parsing line {line_num}: {e}")
-        except (OSError, ValueError, msgspec.DecodeError) as e:
-            raise ValueError(f"Failed to load database: {e}")
+        except OSError as e:
+            raise SystemExit(f"Failed to load database: {e}")
+        except (ValueError, msgspec.DecodeError) as e:
+            raise SystemExit(f"Failed to load database: {e}")
 
         if not data_dict:
             return
@@ -169,7 +178,9 @@ class JsonlStore:
             self._queue_change(action, new_version, current)
 
         # Apply schema migrations one at a time
-        await apply_all_migrations(data_dict, self._current_version, persist_migration)
+        await apply_all_migrations(
+            data_dict, self._current_version, persist_migration, rp_id=rp_id
+        )
 
         # Decode to msgspec struct
         decoder = msgspec.json.Decoder(DB)
@@ -209,7 +220,7 @@ class JsonlStore:
             except (ValueError, KeyError):
                 user_display = user
 
-        log_change(action, diff, user_display, self._previous_builtins)
+        log_change(action, diff, user_display, self._previous_builtins, self.db)
         self._previous_builtins = copy.deepcopy(current)
 
     @contextmanager
@@ -233,8 +244,8 @@ class JsonlStore:
         # Check for out-of-transaction modifications
         current_state = msgspec.to_builtins(self.db)
         if current_state != self._previous_builtins:
-            # Allow bootstrap/migrate to create a new database from empty state
-            is_bootstrap = action in _BOOTSTRAP_ACTIONS or action.startswith("migrate:")
+            # Allow bootstrap to create a new database from empty state
+            is_bootstrap = action in _BOOTSTRAP_ACTIONS
             if is_bootstrap and not self._previous_builtins:
                 pass  # Expected: creating database from scratch
             else:
@@ -277,6 +288,6 @@ class JsonlStore:
             self._in_transaction = False
             self._transaction_snapshot = None
 
-    async def flush(self) -> bool:
+    async def flush(self) -> None:
         """Write all pending changes to disk."""
-        return await flush_changes(self.db_path, self._pending_changes)
+        await flush_changes(self.db_path, self._pending_changes)

paskia/db/lifecycle.py

@@ -0,0 +1,39 @@
+"""
+Database lifecycle: initialization and maintenance.
+"""
+
+import logging
+import os
+from datetime import UTC, datetime
+
+import paskia.db.operations as _ops
+
+_logger = logging.getLogger(__name__)
+
+
+async def init(rp_id: str = "localhost", *args, **kwargs):
+    """Load database from JSONL file."""
+    if _ops._initialized:
+        _logger.debug("Database already initialized, skipping reload")
+        return
+    default_path = f"{rp_id}.paskiadb"
+    db_path = os.environ.get("PASKIA_DB", default_path)
+    await _ops._store.load(db_path, rp_id=rp_id)
+    _ops._db = _ops._store.db
+    _ops._initialized = True
+
+
+def cleanup_expired() -> int:
+    """Remove expired sessions and reset tokens. Returns count removed."""
+    now = datetime.now(UTC)
+    count = 0
+    with _ops._db.transaction("expiry"):
+        expired_sessions = [k for k, s in _ops._db.sessions.items() if s.expiry < now]
+        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

@@ -3,15 +3,27 @@ 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 last
+section of the UUID hex for types without display names.
 """
 
 import logging
 import re
 import sys
-from typing import Any
+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
@@ -32,13 +44,145 @@ _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))
+
+
+def _uuid_suffix(uuid_str: str) -> str:
+    """Get the last section of a UUID (after the last hyphen)."""
+    return uuid_str.rsplit("-", 1)[-1]
+
+
+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 short suffix."""
+        display = self._get_display_name(uuid_str)
+        if display:
+            return display
+        return _uuid_suffix(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"]
+
+        # Check credentials - look up user name
+        if (
+            "credentials" in self._previous
+            and uuid_str in self._previous["credentials"]
+        ):
+            cred_data = self._previous["credentials"][uuid_str]
+            if isinstance(cred_data, dict) and "user" in cred_data:
+                user_uuid = cred_data["user"]
+                if "users" in self._previous and user_uuid in self._previous["users"]:
+                    user_data = self._previous["users"][user_uuid]
+                    if isinstance(user_data, dict) and "display_name" in user_data:
+                        return f"credential of {user_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
+
+        # Check credentials - identify by user name
+        if uuid_obj in self._db.credentials:
+            cred = self._db.credentials[uuid_obj]
+            if cred.user_uuid in self._db.users:
+                user_name = self._db.users[cred.user_uuid].display_name
+                return f"credential of {user_name}"
+
+        return None
+
+
 def _use_color() -> bool:
     """Check if we should use color output."""
     return sys.stderr.isatty()
 
 
-def _format_value(value: Any, use_color: bool, max_len: int = 60) -> str:
-    """Format a value for display, truncating if needed."""
+def _format_value(
+    value: Any,
+    use_color: bool,
+    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"
 
@@ -49,6 +193,9 @@ def _format_value(value: Any, use_color: bool, max_len: int = 60) -> str:
         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
@@ -59,18 +206,26 @@ def _format_value(value: Any, use_color: bool, max_len: int = 60) -> str:
     if isinstance(value, dict):
         if not value:
             return "{}"
-        # For small dicts, show inline
-        if len(value) == 1:
-            k, v = next(iter(value.items()))
-            return "{" + f"{k}: {_format_value(v, use_color, max_len=30)}" + "}"
-        return f"{{...{len(value)} keys}}"
+        # 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, use_color, max_len=30, resolver=resolver)
+                parts.append(f"{key_display}: {val_display}")
+        return "{" + ", ".join(parts) + "}"
 
     if isinstance(value, list):
         if not value:
             return "[]"
-        if len(value) == 1:
-            return "[" + _format_value(value[0], use_color, max_len=30) + "]"
-        return f"[...{len(value)} items]"
+        parts = [
+            _format_value(v, use_color, max_len=30, resolver=resolver) for v in value
+        ]
+        return "[" + ", ".join(parts) + "]"
 
     # Fallback for other types
     text = str(value)
@@ -79,10 +234,20 @@ def _format_value(value: Any, use_color: bool, max_len: int = 60) -> str:
     return text
 
 
-def _format_path(path: list[str], use_color: bool) -> str:
-    """Format a path as dot notation with prefix in dark grey, final in default."""
+def _format_path(
+    path: list[str], use_color: bool, 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 not use_color:
         return ".".join(path)
     if len(path) == 1:
@@ -176,16 +341,32 @@ def _collect_changes(
 
 
 def _format_change_lines(
-    change_type: str, path: list[str], value: Any, use_color: bool
+    change_type: str,
+    path: list[str],
+    value: Any,
+    use_color: bool,
+    resolver: UuidResolver | None = None,
 ) -> list[str]:
-    """Format a single change as one or more lines."""
+    """Format a single change as one or more lines.
+
+    If resolver is provided, UUIDs are replaced with display names.
+    """
+
+    # 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 not use_color:
-            return [f"  {'.'.join(path)} ✗"]
-        if len(path) == 1:
-            return [f"  {_DELETE}{path[0]} ✗{_RESET}"]
-        prefix = ".".join(path[:-1])
-        final = path[-1]
+            return [f"  {'.'.join(formatted_path)} ✗"]
+        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":
@@ -195,56 +376,66 @@ def _format_change_lines(
             lines = []
             # First line: path with green final element and grey =
             if not use_color:
-                lines.append(f"  {'.'.join(path)} =")
-            elif len(path) == 1:
-                lines.append(f"  {_ADD}{path[0]}{_RESET} {_DIM}={_RESET}")
+                lines.append(f"  {'.'.join(formatted_path)} =")
+            elif len(formatted_path) == 1:
+                lines.append(f"  {_ADD}{formatted_path[0]}{_RESET} {_DIM}={_RESET}")
             else:
-                prefix = ".".join(path[:-1])
-                final = path[-1]
+                prefix = ".".join(formatted_path[:-1])
+                final = formatted_path[-1]
                 lines.append(
                     f"  {_PATH_PREFIX}{prefix}.{_RESET}{_ADD}{final}{_RESET} {_DIM}={_RESET}"
                 )
             # Child lines: indented key: value, with aligned values
-            max_key_len = max(len(k) for k in value.keys())
-            field_width = max(max_key_len, 12)  # minimum 12 chars
+            # Format keys (may contain UUIDs)
+            formatted_items = []
             for k, v in value.items():
-                v_str = _format_value(v, use_color)
-                padding = " " * (field_width - len(k))
+                k_display = resolver.resolve(k) if resolver and _is_uuid(k) else k
+                v_str = _format_value(v, use_color, resolver=resolver)
+                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))
                 if use_color:
-                    lines.append(f"    {k}{_DIM}:{_RESET}{padding} {v_str}")
+                    lines.append(f"    {k_display}{_DIM}:{_RESET}{padding} {v_str}")
                 else:
-                    lines.append(f"    {k}:{padding} {v_str}")
+                    lines.append(f"    {k_display}:{padding} {v_str}")
             return lines
         else:
-            value_str = _format_value(value, use_color)
+            value_str = _format_value(value, use_color, resolver=resolver)
             if not use_color:
-                return [f"  {'.'.join(path)} = {value_str}"]
-            if len(path) == 1:
-                return [f"  {_ADD}{path[0]}{_RESET} {_DIM}={_RESET} {value_str}"]
-            prefix = ".".join(path[:-1])
-            final = path[-1]
+                return [f"  {'.'.join(formatted_path)} = {value_str}"]
+            if len(formatted_path) == 1:
+                return [
+                    f"  {_ADD}{formatted_path[0]}{_RESET} {_DIM}={_RESET} {value_str}"
+                ]
+            prefix = ".".join(formatted_path[:-1])
+            final = formatted_path[-1]
             return [
                 f"  {_PATH_PREFIX}{prefix}.{_RESET}{_ADD}{final}{_RESET} {_DIM}={_RESET} {value_str}"
             ]
 
     # update: Existing item being updated - normal path colors
-    value_str = _format_value(value, use_color)
-    path_str = _format_path(path, use_color)
+    value_str = _format_value(value, use_color, resolver=resolver)
+    path_str = _format_path(path, use_color, resolver=resolver)
     if use_color:
         return [f"  {path_str} {_DIM}={_RESET} {value_str}"]
     return [f"  {path_str} = {value_str}"]
 
 
-def format_diff(diff: dict, previous: dict | None = None) -> list[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).
-    Single changes return one line, multiple changes return multiple lines.
+    UUIDs are replaced with display names (using previous state for lookups).
     """
     use_color = _use_color()
     changes: list[tuple[str, list[str], Any]] = []
@@ -253,10 +444,15 @@ def format_diff(diff: dict, previous: dict | None = None) -> list[str]:
     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, use_color))
+        lines.extend(
+            _format_change_lines(change_type, path, value, use_color, resolver)
+        )
 
     return lines
 
@@ -282,18 +478,23 @@ def log_change(
     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 (e.g., credentials), the last section of the UUID 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)
+    diff_lines = format_diff(diff, previous, db)
 
     if not diff_lines:
         logger.info(header)

paskia/db/migrations.py

@@ -8,26 +8,34 @@ Each migration should be idempotent and only run when needed.
 from collections.abc import Awaitable, Callable
 
 
-def migrate_v1(d: dict) -> None:
+def migrate_v1(d: dict, **kwargs) -> None:
     """Remove Org.created_at fields."""
     for org_data in d["orgs"].values():
         org_data.pop("created_at", None)
 
 
+def migrate_v2(d: dict, *, rp_id: str = "localhost") -> None:
+    """Add config field if missing."""
+    if "config" not in d:
+        d["config"] = {"rp_id": rp_id}
+
+
 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 and migrate:sql to set initial version
+DBVER = len(migrations)  # Used by bootstrap to set initial version
 
 
 async def apply_all_migrations(
     data_dict: dict,
     current_version: int,
     persist: Callable[[str, int, dict], Awaitable[None]],
+    *,
+    rp_id: str = "localhost",
 ) -> None:
     while current_version < DBVER:
-        migrations[current_version](data_dict)
+        migrations[current_version](data_dict, rp_id=rp_id)
         current_version += 1
         await persist(f"migrate:v{current_version}", current_version, data_dict)

paskia/db/operations.py

@@ -6,22 +6,19 @@ Context lookup: _db.session_ctx() returns full SessionContext with effective per
 Write operations: Functions that validate and commit, or raise ValueError.
 """
 
-import hashlib
 import logging
-import os
-import secrets
-from datetime import UTC, datetime
+from datetime import UTC, datetime, timedelta
 from uuid import UUID
 
 import uuid7
 
 from paskia.config import SESSION_LIFETIME
 from paskia.db.jsonl import (
-    DB_PATH_DEFAULT,
     JsonlStore,
 )
 from paskia.db.structs import (
     DB,
+    Config,
     Credential,
     Org,
     Permission,
@@ -31,107 +28,33 @@ from paskia.db.structs import (
     SessionContext,
     User,
 )
-from paskia.util.passphrase import generate as generate_passphrase
-from paskia.util.passphrase import is_well_formed as _is_passphrase
 
 _logger = logging.getLogger(__name__)
 
 # Global database instance (empty until init() loads data)
-_db = DB()
+_db = DB(config=Config(rp_id="uninitialized.invalid"))
 _store = JsonlStore(_db)
 _db._store = _store
 _initialized = False
 
 
-async def init(*args, **kwargs):
-    """Load database from JSONL file."""
-    global _db, _initialized
-    if _initialized:
-        _logger.debug("Database already initialized, skipping reload")
-        return
-    db_path = os.environ.get("PASKIA_DB", DB_PATH_DEFAULT)
-    if db_path.startswith("json:"):
-        db_path = db_path[5:]
-    await _store.load(db_path)
-    _db = _store.db
-    _initialized = True
-
-
-# -------------------------------------------------------------------------
-# Read/lookup functions
-# -------------------------------------------------------------------------
-
-
-def get_user_organization(user_uuid: UUID) -> tuple[Org, str]:
-    """Get the organization a user belongs to and their role name.
-
-    Raises ValueError if user not found.
-
-    Call sites:
-    - update_user_role_in_organization: org only
-    - admin_create_user_registration_link: org only
-    - admin_get_user_detail: org and role
-    - admin_update_user_display_name: org only
-    - admin_delete_user_credential: org only
-    - admin_delete_user_session: org only
-    """
-    if user_uuid not in _db.users:
-        raise ValueError(f"User {user_uuid} not found")
-    user = _db.users[user_uuid]
-    role = user.role
-    return role.org, role.display_name
-
-
-def get_organization_users(org_uuid: UUID) -> list[tuple[User, str]]:
-    """Get all users in an organization with their role names.
-
-    Returns list of (User, role_display_name) tuples.
-    """
-    org = _db.orgs[org_uuid]
-    return [(u, u.role.display_name) for role in org.roles for u in role.users]
-
-
-def get_user_credential_ids(user_uuid: UUID) -> list[bytes]:
-    """Get credential IDs for a user (for WebAuthn exclude lists).
-
-    Returns empty list if user has no credentials.
-    """
-    assert user_uuid
-    return [c.credential_id for c in _db.users[user_uuid].credentials]
-
-
-def _reset_key(passphrase: str) -> bytes:
-    """Hash a passphrase to bytes for reset token storage."""
-    if not _is_passphrase(passphrase):
-        raise ValueError(
-            "Trying to reset with a session token in place of a passphrase"
-            if len(passphrase) == 16
-            else "Invalid passphrase format"
-        )
-    return hashlib.sha512(passphrase.encode()).digest()[:9]
-
-
-def get_reset_token(passphrase: str) -> ResetToken | None:
-    """Get reset token by passphrase.
-
-    Call sites:
-    - Get reset token to validate it (authsession.py:34)
-    """
-    key = _reset_key(passphrase)
-    return _db.reset_tokens.get(key)
-
-
 # -------------------------------------------------------------------------
 # Write operations (validate, modify, commit or raise ValueError)
 # -------------------------------------------------------------------------
 
 
+async def update_config(config: Config) -> None:
+    """Update the stored configuration."""
+    with _db.transaction("update_config"):
+        _db.config = config
+
+
 def create_permission(perm: Permission, *, ctx: SessionContext | None = None) -> None:
     """Create a new permission."""
     if perm.uuid in _db.permissions:
         raise ValueError(f"Permission {perm.uuid} already exists")
     with _db.transaction("admin:create_permission", ctx):
-        _db.permissions[perm.uuid] = perm
+        perm.store()
 
 
 def update_permission(
@@ -159,10 +82,7 @@ def delete_permission(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     if uuid not in _db.permissions:
         raise ValueError(f"Permission {uuid} not found")
     with _db.transaction("admin:delete_permission", ctx):
-        # Remove this permission from all roles
-        for role in _db.roles.values():
-            role.permissions.pop(uuid, None)
-        del _db.permissions[uuid]
+        _db.permissions[uuid].delete()
 
 
 def create_org(org: Org, *, ctx: SessionContext | None = None) -> None:
@@ -172,13 +92,14 @@ def create_org(org: Org, *, ctx: SessionContext | None = None) -> None:
     """
     if org.uuid in _db.orgs:
         raise ValueError(f"Organization {org.uuid} already exists")
+    now = datetime.now(UTC)
     with _db.transaction("admin:create_org", ctx):
-        new_org = Org.create(display_name=org.display_name)
+        new_org = Org.create(display_name=org.display_name, created_at=now)
         new_org.uuid = org.uuid
-        _db.orgs[org.uuid] = new_org
+        new_org.store()
         # Create Administration role with org admin permission
 
-        admin_role_uuid = uuid7.create()
+        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():
@@ -192,7 +113,7 @@ def create_org(org: Org, *, ctx: SessionContext | None = None) -> None:
             permissions=role_permissions,
         )
         admin_role.uuid = admin_role_uuid
-        _db.roles[admin_role_uuid] = admin_role
+        admin_role.store()
 
 
 def update_org_name(
@@ -213,16 +134,7 @@ def delete_org(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     if uuid not in _db.orgs:
         raise ValueError(f"Organization {uuid} not found")
     with _db.transaction("admin:delete_org", ctx):
-        org = _db.orgs[uuid]
-        # Remove org from all permissions
-        for p in _db.permissions.values():
-            p.orgs.pop(uuid, None)
-        # Delete roles in this org and their users
-        for role in org.roles:
-            for user in role.users:
-                del _db.users[user.uuid]
-            del _db.roles[role.uuid]
-        del _db.orgs[uuid]
+        _db.orgs[uuid].delete()
 
 
 def add_permission_to_org(
@@ -266,7 +178,7 @@ def create_role(role: Role, *, ctx: SessionContext | None = None) -> None:
     if role.org_uuid not in _db.orgs:
         raise ValueError(f"Organization {role.org_uuid} not found")
     with _db.transaction("admin:create_role", ctx):
-        _db.roles[role.uuid] = role
+        role.store()
 
 
 def update_role_name(
@@ -319,7 +231,7 @@ def delete_role(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     if role.users:
         raise ValueError(f"Cannot delete role {uuid}: users still assigned")
     with _db.transaction("admin:delete_role", ctx):
-        del _db.roles[uuid]
+        _db.roles[uuid].delete()
 
 
 def create_user(new_user: User, *, ctx: SessionContext | None = None) -> None:
@@ -329,7 +241,7 @@ def create_user(new_user: User, *, ctx: SessionContext | None = None) -> None:
     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):
-        _db.users[new_user.uuid] = new_user
+        new_user.store()
 
 
 def update_user_display_name(
@@ -352,6 +264,23 @@ def update_user_display_name(
         _db.users[uuid].display_name = display_name
 
 
+def update_user_theme(
+    uuid: UUID,
+    theme: str,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Update user theme preference ('' for auto, 'light', 'dark')."""
+    if isinstance(uuid, str):
+        uuid = UUID(uuid)
+    if uuid not in _db.users:
+        raise ValueError(f"User {uuid} not found")
+    if theme not in ("", "light", "dark"):
+        raise ValueError(f"Invalid theme: {theme}")
+    with _db.transaction("update_user_theme", ctx):
+        _db.users[uuid].theme = theme
+
+
 def update_user_role(
     uuid: UUID,
     role_uuid: UUID,
@@ -367,45 +296,12 @@ def update_user_role(
         _db.users[uuid].role_uuid = role_uuid
 
 
-def update_user_role_in_organization(
-    user_uuid: UUID,
-    role_name: str,
-    *,
-    ctx: SessionContext | None = None,
-) -> None:
-    """Update user's role by role name within their current organization."""
-    if user_uuid not in _db.users:
-        raise ValueError(f"User {user_uuid} not found")
-    user = _db.users[user_uuid]
-    org = user.org
-    # Find role by name in the same org
-    new_role_uuid = None
-    for r in org.roles:
-        if r.display_name == role_name:
-            new_role_uuid = r.uuid
-            break
-    if new_role_uuid is None:
-        raise ValueError(f"Role '{role_name}' not found in organization")
-    with _db.transaction("admin:update_user_role", ctx):
-        _db.users[user_uuid].role_uuid = new_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")
-    user = _db.users[uuid]
     with _db.transaction("admin:delete_user", ctx):
-        # Delete credentials
-        for cred in user.credentials:
-            del _db.credentials[cred.uuid]
-        # Delete sessions
-        for sess in user.sessions:
-            del _db.sessions[sess.key]
-        # Delete reset tokens
-        for token in user.reset_tokens:
-            del _db.reset_tokens[token.key]
-        del _db.users[uuid]
+        _db.users[uuid].delete()
 
 
 def create_credential(cred: Credential, *, ctx: SessionContext | None = None) -> None:
@@ -415,7 +311,7 @@ def create_credential(cred: Credential, *, ctx: SessionContext | None = None) ->
     if cred.user_uuid not in _db.users:
         raise ValueError(f"User {cred.user_uuid} not found")
     with _db.transaction("create_credential", ctx):
-        _db.credentials[cred.uuid] = cred
+        cred.store()
 
 
 def update_credential_sign_count(
@@ -451,11 +347,7 @@ def delete_credential(
         if cred.user_uuid != user_uuid:
             raise ValueError(f"Credential {uuid} does not belong to user {user_uuid}")
     with _db.transaction("delete_credential", ctx):
-        # Delete all sessions using this credential
-        for sess in cred.sessions:
-            print(sess, repr(sess.key))
-            del _db.sessions[sess.key]
-        del _db.credentials[uuid]
+        cred.delete()
 
 
 def create_session(
@@ -464,7 +356,7 @@ def create_session(
     host: str,
     ip: str,
     user_agent: str,
-    expiry: datetime,
+    duration: timedelta = SESSION_LIFETIME,
     *,
     ctx: SessionContext | None = None,
 ) -> str:
@@ -473,18 +365,19 @@ def create_session(
         raise ValueError(f"User {user_uuid} not found")
     if credential_uuid not in _db.credentials:
         raise ValueError(f"Credential {credential_uuid} not found")
+    now = datetime.now(UTC)
     session = Session.create(
         user=user_uuid,
         credential=credential_uuid,
         host=host,
         ip=ip,
         user_agent=user_agent,
-        expiry=expiry,
+        expiry=now + duration,
     )
     if session.key in _db.sessions:
         raise ValueError("Session already exists")
     with _db.transaction("create_session", ctx):
-        _db.sessions[session.key] = session
+        session.store(now)
     return session.key
 
 
@@ -529,7 +422,7 @@ def delete_session(
     if key not in _db.sessions:
         raise ValueError("Session not found")
     with _db.transaction(action, ctx):
-        del _db.sessions[key]
+        _db.sessions[key].delete()
 
 
 def delete_sessions_for_user(
@@ -546,35 +439,38 @@ def delete_sessions_for_user(
         return
     with _db.transaction("admin:delete_sessions_for_user", ctx):
         for sess in user.sessions:
-            del _db.sessions[sess.key]
+            sess.delete()
 
 
 def create_reset_token(
-    passphrase: str,
     user_uuid: UUID,
     expiry: datetime,
     token_type: str,
     *,
     ctx: SessionContext | None = None,
     user: str | None = None,
-) -> None:
-    """Create a reset token from a passphrase.
+) -> 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.
     """
-    key = _reset_key(passphrase)
-    if key in _db.reset_tokens:
-        raise ValueError("Reset token already exists")
     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):
-        _db.reset_tokens[key] = ResetToken(
-            user_uuid=user_uuid, expiry=expiry, token_type=token_type
-        )
+        token.store()
+    return passphrase
 
 
 def delete_reset_token(key: bytes, *, ctx: SessionContext | None = None) -> None:
@@ -582,28 +478,7 @@ def delete_reset_token(key: bytes, *, ctx: SessionContext | None = None) -> None
     if key not in _db.reset_tokens:
         raise ValueError("Reset token not found")
     with _db.transaction("delete_reset_token", ctx):
-        del _db.reset_tokens[key]
-
-
-# -------------------------------------------------------------------------
-# Cleanup (called by background task)
-# -------------------------------------------------------------------------
-
-
-def cleanup_expired() -> int:
-    """Remove expired sessions and reset tokens. Returns count removed."""
-    now = datetime.now(UTC)
-    count = 0
-    with _db.transaction("expiry"):
-        expired_sessions = [k for k, s in _db.sessions.items() if s.expiry < now]
-        for k in expired_sessions:
-            del _db.sessions[k]
-            count += 1
-        expired_tokens = [k for k, t in _db.reset_tokens.items() if t.expiry < now]
-        for k in expired_tokens:
-            del _db.reset_tokens[k]
-            count += 1
-    return count
+        _db.reset_tokens[key].delete()
 
 
 # -------------------------------------------------------------------------
@@ -611,11 +486,6 @@ def cleanup_expired() -> int:
 # -------------------------------------------------------------------------
 
 
-def _create_token() -> str:
-    """Generate a 16-character URL-safe session token."""
-    return secrets.token_urlsafe(12)
-
-
 def login(
     user_uuid: UUID,
     credential_uuid: UUID,
@@ -623,7 +493,7 @@ def login(
     host: str,
     ip: str,
     user_agent: str,
-    expiry: datetime,
+    duration: timedelta = SESSION_LIFETIME,
 ) -> str:
     """Update user/credential on login and create session in a single transaction.
 
@@ -649,18 +519,14 @@ def login(
         host=host,
         ip=ip,
         user_agent=user_agent,
-        expiry=expiry,
+        expiry=now + duration,
     )
     user_str = str(user_uuid)
     with _db.transaction("login", user=user_str):
-        # Update user
-        _db.users[user_uuid].last_seen = now
-        _db.users[user_uuid].visits += 1
+        session.store(now)
         # Update credential
         _db.credentials[credential_uuid].sign_count = sign_count
         _db.credentials[credential_uuid].last_used = now
-        # Create session
-        _db.sessions[session.key] = session
     return session.key
 
 
@@ -685,7 +551,6 @@ def create_credential_session(
     """
 
     now = datetime.now(UTC)
-    expiry = now + SESSION_LIFETIME
 
     if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
@@ -696,7 +561,7 @@ def create_credential_session(
         host=host,
         ip=ip,
         user_agent=user_agent,
-        expiry=expiry,
+        expiry=now + SESSION_LIFETIME,
     )
     user_str = str(user_uuid)
     with _db.transaction("create_credential_session", user=user_str):
@@ -704,126 +569,20 @@ def create_credential_session(
         if display_name:
             _db.users[user_uuid].display_name = display_name
 
-        # Create credential
-        _db.credentials[credential.uuid] = credential
+        # Align credential timestamps with transaction time
+        credential.created_at = now
+        credential.last_used = now
+        credential.last_verified = now
 
-        # Create session
-        _db.sessions[session.key] = session
+        # Create credential
+        credential.store()
+
+        # Store session and record visit
+        session.store(now)
 
         # Delete reset token if provided
         if reset_key:
-            if reset_key in _db.reset_tokens:
-                del _db.reset_tokens[reset_key]
+            token = _db.reset_tokens.get(reset_key)
+            if token:
+                token.delete()
     return session.key
-
-
-# -------------------------------------------------------------------------
-# Bootstrap (single transaction for initial system setup)
-# -------------------------------------------------------------------------
-
-
-def bootstrap(
-    org_name: str = "Organization",
-    admin_name: str = "Admin",
-    reset_passphrase: str | None = None,
-    reset_expiry: datetime | 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
-
-    This is the only way to create a new database file (besides migrate).
-    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)
-
-    Returns:
-        The reset passphrase for admin registration.
-    """
-
-    # Check if system is already bootstrapped
-    for p in _db.permissions.values():
-        if p.scope == "auth:admin":
-            raise ValueError(
-                "System already bootstrapped (auth:admin permission exists)"
-            )
-
-    # Generate UUIDs upfront
-    perm_admin_uuid = uuid7.create()
-    perm_org_admin_uuid = uuid7.create()
-    org_uuid = uuid7.create()
-    role_uuid = uuid7.create()
-    user_uuid = uuid7.create()
-
-    # Generate reset token components
-    if reset_passphrase is None:
-        reset_passphrase = generate_passphrase()
-    if reset_expiry is None:
-        from paskia.authsession import reset_expires  # noqa: PLC0415
-
-        reset_expiry = reset_expires()
-    reset_key = _reset_key(reset_passphrase)
-
-    now = datetime.now(UTC)
-
-    with _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
-        _db.permissions[perm_admin_uuid] = perm_admin
-
-        # 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
-        _db.permissions[perm_org_admin_uuid] = perm_org_admin
-
-        # Create organization
-        new_org = Org.create(display_name=org_name)
-        new_org.uuid = org_uuid
-        _db.orgs[org_uuid] = new_org
-
-        # 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
-        _db.roles[role_uuid] = admin_role
-
-        # Create admin user
-        admin_user = User(
-            display_name=admin_name,
-            role_uuid=role_uuid,
-            created_at=now,
-            last_seen=None,
-            visits=0,
-        )
-        admin_user.uuid = user_uuid
-        _db.users[user_uuid] = admin_user
-
-        # Create reset token
-        _db.reset_tokens[reset_key] = ResetToken(
-            user_uuid=user_uuid,
-            expiry=reset_expiry,
-            token_type="admin bootstrap",
-        )
-
-    return reset_passphrase

paskia/db/structs.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 import secrets
 from datetime import UTC, datetime
 from uuid import UUID
@@ -8,7 +9,8 @@ import msgspec
 import uuid7
 
 from paskia import db
-from paskia.util.hostutil import normalize_host
+from paskia.util import hostutil
+from paskia.util import passphrase as passphrase_util
 
 # Sentinel for uuid fields before they are set by create() or DB post init
 _UUID_UNSET = UUID(int=0)
@@ -45,20 +47,36 @@ class Permission(msgspec.Struct, dict=True, omit_defaults=True):
             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()
+        perm.uuid = uuid7.create(now)
         return perm
 
 
@@ -81,11 +99,30 @@ class Org(msgspec.Struct, dict=True):
         """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) -> Org:
+    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()
+        org.uuid = uuid7.create(now)
         return org
 
 
@@ -129,28 +166,38 @@ class Role(msgspec.Struct, dict=True, omit_defaults=True):
         """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()
+        role.uuid = uuid7.create(now)
         return role
 
 
-class User(msgspec.Struct, dict=True):
+class User(msgspec.Struct, dict=True, omit_defaults=True):
     """User data structure.
 
-    Mutable fields: display_name, role_uuid, last_seen, visits
+    Mutable fields: display_name, role_uuid, last_seen, visits, theme
     Immutable fields: created_at (set at creation, never modified)
     uuid is derived from created_at using uuid7.
     """
@@ -160,6 +207,7 @@ class User(msgspec.Struct, dict=True):
     created_at: datetime
     last_seen: datetime | None = None
     visits: int = 0
+    theme: str = ""  # "" or "auto" = OS default, "light", "dark"
 
     def __post_init__(self):
         if not hasattr(self, "uuid"):
@@ -180,6 +228,11 @@ class User(msgspec.Struct, dict=True):
         """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."""
@@ -190,6 +243,24 @@ class User(msgspec.Struct, dict=True):
         """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,
@@ -241,6 +312,20 @@ class Credential(msgspec.Struct, dict=True):
             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,
@@ -305,6 +390,21 @@ class Session(msgspec.Struct, dict=True):
             "expiry": self.expiry.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,
@@ -352,6 +452,59 @@ class ResetToken(msgspec.Struct, dict=True):
         """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
+
+    @staticmethod
+    def hash(passphrase: str) -> bytes:
+        """Hash a passphrase to bytes 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 hashlib.sha512(passphrase.encode()).digest()[:9]
+
+    @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
+
 
 class SessionContext(msgspec.Struct):
     session: Session
@@ -362,6 +515,16 @@ class SessionContext(msgspec.Struct):
     permissions: list[Permission] = []
 
 
+class Config(msgspec.Struct, frozen=True, dict=True, omit_defaults=True):
+    """Stored configuration for the instance."""
+
+    rp_id: str
+    rp_name: str | None = None
+    origins: list[str] | None = None
+    auth_host: str | None = None
+    listen: str | None = None
+
+
 # -------------------------------------------------------------------------
 # Database storage structure
 # -------------------------------------------------------------------------
@@ -370,6 +533,7 @@ class SessionContext(msgspec.Struct):
 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] = {}
@@ -418,8 +582,11 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
         except KeyError:
             return None
 
+        # Normalize host for comparison (stored hosts are already normalized)
+        normalized_input = hostutil.normalize_host(host)
+
         # Validate host matches (sessions are always created with a host)
-        if s.host != host:
+        if s.host != normalized_input:
             # Session bound to different host
             return None
 
@@ -434,10 +601,6 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
         # 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}
-        normalized_host = normalize_host(host)
-        host_without_port = (
-            normalized_host.rsplit(":", 1)[0] if normalized_host else None
-        )
 
         effective_perms = []
         for perm_uuid in role.permission_set:
@@ -447,8 +610,8 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
                 p = self.permissions[perm_uuid]
             except KeyError:
                 continue
-            # Check domain restriction
-            if p.domain is not None and p.domain != host_without_port:
+            # 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)
 

paskia/fastapi/__main__.py

@@ -6,25 +6,26 @@ import os
 from urllib.parse import urlparse
 
 from fastapi_vue.hostutil import parse_endpoint
-from uvicorn import Config, Server
+from uvicorn import Config as UvicornConfig
+from uvicorn import Server
 from uvicorn import run as uvicorn_run
 
+from paskia import db
 from paskia import globals as _globals
 from paskia.bootstrap import bootstrap_if_needed
 from paskia.config import PaskiaConfig
+from paskia.db import init as db_init
 from paskia.db.background import flush
-from paskia.fastapi import reset as reset_cmd
+from paskia.db.structs import Config
 from paskia.util import startupbox
 from paskia.util.hostutil import normalize_origin
 
 DEFAULT_PORT = 4401
+DEVMODE = bool(os.getenv("PASKIA_FRONTEND_URL"))
 
 EPILOG = """\
-Examples:
-  paskia                      # localhost:4401
-  paskia :8080                # All interfaces, port 8080
-  paskia unix:/tmp/paskia.sock
-  paskia reset [user]         # Generate passkey reset link
+Example:
+  paskia --rp-id example.com --rp-name "Example Corporation" --auth-host auth.example.com
 """
 
 
@@ -63,10 +64,12 @@ def add_common_options(p: argparse.ArgumentParser) -> None:
     )
     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"
-        ),
+        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.",
     )
 
 
@@ -81,32 +84,43 @@ def main():
         epilog=EPILOG,
     )
 
-    # Primary argument: either host:port or "reset" subcommand
     parser.add_argument(
-        "hostport",
-        nargs="?",
+        "-l",
+        "--listen",
+        metavar="LISTEN",
         help=(
-            "Endpoint (default: localhost:4401). Forms: host[:port] | :port | "
-            "[ipv6][:port] | ipv6 | unix:/path.sock | 'reset' for credential reset"
+            "Endpoint to listen on (default: localhost:4401). "
+            "Forms: host:port  port  :port  [ipv6]:port  unix:path  /path.sock"
         ),
     )
-    parser.add_argument(
-        "reset_query",
-        nargs="?",
-        help="For 'reset' command: user UUID or substring of display name",
-    )
     add_common_options(parser)
 
     args = parser.parse_args()
 
-    # Detect "reset" subcommand (first positional is "reset")
-    is_reset = args.hostport == "reset"
+    # Handle clearing options
+    if getattr(args, "auth_host", None) == "":
+        args.auth_host = None
+    if getattr(args, "rp_name", None) == "":
+        args.rp_name = None
+    if getattr(args, "listen", None) == "":
+        args.listen = None
 
-    if is_reset:
-        endpoints = []
-    else:
-        # Parse endpoint using fastapi_vue.hostutil
-        endpoints = parse_endpoint(args.hostport, DEFAULT_PORT)
+    # Init db and load stored config
+    asyncio.run(db_init(rp_id=args.rp_id))
+    stored_config = db.data().config
+
+    # Apply defaults from stored config
+    if args.rp_name is None and stored_config.rp_name is not None:
+        args.rp_name = stored_config.rp_name
+    if args.origins is None and stored_config.origins is not None:
+        args.origins = stored_config.origins
+    if args.auth_host is None and stored_config.auth_host is not None:
+        args.auth_host = stored_config.auth_host
+    if args.listen is None and stored_config.listen is not None:
+        args.listen = stored_config.listen
+
+    # Parse endpoint using fastapi_vue.hostutil
+    endpoints = parse_endpoint(args.listen, DEFAULT_PORT)
 
     # Extract host/port/uds from first endpoint for config display and site_url
     ep = endpoints[0] if endpoints else {}
@@ -185,14 +199,21 @@ def main():
 
     startupbox.print_startup_config(config)
 
-    devmode = bool(os.environ.get("FASTAPI_VUE_FRONTEND_URL"))
+    # Build config to save (for bootstrap or explicit --save)
+    cli_config = Config(
+        rp_id=args.rp_id,
+        rp_name=args.rp_name,
+        origins=args.origins,
+        auth_host=args.auth_host,
+        listen=args.listen,
+    )
 
     run_kwargs: dict = {
         "log_level": "warning",  # Suppress startup messages; we use custom logging
         "access_log": False,  # We use custom AccessLogMiddleware instead
     }
 
-    if 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:
@@ -207,28 +228,28 @@ def main():
             origins=config.origins,
             bootstrap=False,
         )
-        await bootstrap_if_needed()
+        # Pass config to bootstrap - it will be saved within the bootstrap transaction
+        await bootstrap_if_needed(config=cli_config)
+        # Also save config if --save was explicitly used (even without bootstrap)
+        if args.save:
+            await db.update_config(cli_config)
         await flush()
 
-        if is_reset:
-            exit_code = reset_cmd.run(args.reset_query)
-            raise SystemExit(exit_code)
-
         if len(endpoints) > 1:
             async with asyncio.TaskGroup() as tg:
                 for ep in endpoints:
                     tg.create_task(
                         Server(
-                            Config(app="paskia.fastapi:app", **run_kwargs, **ep)
+                            UvicornConfig(app="paskia.fastapi:app", **run_kwargs, **ep)
                         ).serve()
                     )
-        elif devmode:
+        elif DEVMODE:
             # Use uvicorn.run for proper reload support (it handles subprocess spawning)
             ep = endpoints[0]
             uvicorn_run("paskia.fastapi:app", **run_kwargs, **ep)
         else:
             server = Server(
-                Config(app="paskia.fastapi:app", **run_kwargs, **endpoints[0])
+                UvicornConfig(app="paskia.fastapi:app", **run_kwargs, **endpoints[0])
             )
             await server.serve()
 

paskia/fastapi/admin.py

@@ -17,7 +17,6 @@ from paskia.fastapi.session import AUTH_COOKIE
 from paskia.globals import passkey
 from paskia.util import (
     hostutil,
-    passphrase,
     permutil,
     querysafe,
     vitedev,
@@ -84,7 +83,6 @@ async def admin_list_orgs(request: Request, auth=AUTH_COOKIE):
         orgs = [o for o in orgs if o.uuid == ctx.org.uuid]
 
     def org_to_dict(o):
-        users = db.get_organization_users(o.uuid)
         return {
             "uuid": o.uuid,
             "display_name": o.display_name,
@@ -102,11 +100,13 @@ async def admin_list_orgs(request: Request, auth=AUTH_COOKIE):
                 {
                     "uuid": u.uuid,
                     "display_name": u.display_name,
-                    "role": role_name,
+                    "role": r.display_name,
+                    "role_uuid": u.role_uuid,
                     "visits": u.visits,
                     "last_seen": u.last_seen,
                 }
-                for (u, role_name) in users
+                for r in o.roles
+                for u in r.users
             ],
         }
 
@@ -281,28 +281,27 @@ async def admin_create_role(
     return {"uuid": str(role.uuid)}
 
 
-@app.patch("/orgs/{org_uuid}/roles/{role_uuid}")
+@app.patch("/roles/{role_uuid}")
 async def admin_update_role_name(
-    org_uuid: UUID,
     role_uuid: UUID,
     request: Request,
     payload: dict = Body(...),
     auth=AUTH_COOKIE,
 ):
     """Update role display name only."""
+    role = db.data().roles.get(role_uuid)
+    if not role:
+        raise HTTPException(status_code=404, detail="Role not found")
     ctx = await authz.verify(
         auth,
         ["auth:admin", "auth:org:admin"],
         match=permutil.has_any,
         host=request.headers.get("host"),
     )
-    if not can_manage_org(ctx, org_uuid):
+    if not can_manage_org(ctx, role.org_uuid):
         raise authz.AuthException(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )
-    role = db.data().roles.get(role_uuid)
-    if not role or role.org_uuid != org_uuid:
-        raise HTTPException(status_code=404, detail="Role not found in organization")
 
     display_name = payload.get("display_name")
     if not display_name:
@@ -312,68 +311,64 @@ async def admin_update_role_name(
     return {"status": "ok"}
 
 
-@app.post("/orgs/{org_uuid}/roles/{role_uuid}/permissions/{permission_uuid}")
+@app.post("/roles/{role_uuid}/permissions/{permission_uuid}")
 async def admin_add_role_permission(
-    org_uuid: UUID,
     role_uuid: UUID,
     permission_uuid: UUID,
     request: Request,
     auth=AUTH_COOKIE,
 ):
     """Add a permission to a role (intent-based API)."""
+    role = db.data().roles.get(role_uuid)
+    if not role:
+        raise HTTPException(status_code=404, detail="Role not found")
     ctx = await authz.verify(
         auth,
         ["auth:admin", "auth:org:admin"],
         match=permutil.has_any,
         host=request.headers.get("host"),
     )
-    if not can_manage_org(ctx, org_uuid):
+    if not can_manage_org(ctx, role.org_uuid):
         raise authz.AuthException(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )
 
-    role = db.data().roles.get(role_uuid)
-    if not role or role.org_uuid != org_uuid:
-        raise HTTPException(status_code=404, detail="Role not found in organization")
-
     # Verify permission exists and org can grant it
     perm = db.data().permissions.get(permission_uuid)
     if not perm:
         raise HTTPException(status_code=404, detail="Permission not found")
-    if org_uuid not in perm.orgs:
+    if role.org_uuid not in perm.orgs:
         raise ValueError("Permission not grantable by organization")
 
     db.add_permission_to_role(role_uuid, permission_uuid, ctx=ctx)
     return {"status": "ok"}
 
 
-@app.delete("/orgs/{org_uuid}/roles/{role_uuid}/permissions/{permission_uuid}")
+@app.delete("/roles/{role_uuid}/permissions/{permission_uuid}")
 async def admin_remove_role_permission(
-    org_uuid: UUID,
     role_uuid: UUID,
     permission_uuid: UUID,
     request: Request,
     auth=AUTH_COOKIE,
 ):
     """Remove a permission from a role (intent-based API)."""
+    role = db.data().roles.get(role_uuid)
+    if not role:
+        raise HTTPException(status_code=404, detail="Role not found")
     ctx = await authz.verify(
         auth,
         ["auth:admin", "auth:org:admin"],
         match=permutil.has_any,
         host=request.headers.get("host"),
     )
-    if not can_manage_org(ctx, org_uuid):
+    if not can_manage_org(ctx, role.org_uuid):
         raise authz.AuthException(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )
 
-    role = db.data().roles.get(role_uuid)
-    if not role or role.org_uuid != org_uuid:
-        raise HTTPException(status_code=404, detail="Role not found in organization")
-
     # Sanity check: prevent admin from removing their own access
     perm = db.data().permissions.get(permission_uuid)
-    if ctx.org.uuid == org_uuid and ctx.role.uuid == role_uuid:
+    if ctx.org.uuid == role.org_uuid and ctx.role.uuid == role_uuid:
         if perm and perm.scope in ["auth:admin", "auth:org:admin"]:
             # Check if removing this permission would leave no admin access
             remaining_perms = role.permission_set - {permission_uuid}
@@ -390,13 +385,15 @@ async def admin_remove_role_permission(
     return {"status": "ok"}
 
 
-@app.delete("/orgs/{org_uuid}/roles/{role_uuid}")
+@app.delete("/roles/{role_uuid}")
 async def admin_delete_role(
-    org_uuid: UUID,
     role_uuid: UUID,
     request: Request,
     auth=AUTH_COOKIE,
 ):
+    role = db.data().roles.get(role_uuid)
+    if not role:
+        raise HTTPException(status_code=404, detail="Role not found")
     ctx = await authz.verify(
         auth,
         ["auth:admin", "auth:org:admin"],
@@ -404,13 +401,10 @@ async def admin_delete_role(
         host=request.headers.get("host"),
         max_age="5m",
     )
-    if not can_manage_org(ctx, org_uuid):
+    if not can_manage_org(ctx, role.org_uuid):
         raise authz.AuthException(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )
-    role = db.data().roles.get(role_uuid)
-    if not role or 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:
@@ -460,70 +454,66 @@ async def admin_create_user(
     return {"uuid": str(user.uuid)}
 
 
-@app.patch("/orgs/{org_uuid}/users/{user_uuid}/role")
+@app.patch("/users/{user_uuid}/role")
 async def admin_update_user_role(
-    org_uuid: UUID,
     user_uuid: UUID,
     request: Request,
     payload: dict = Body(...),
     auth=AUTH_COOKIE,
 ):
+    try:
+        user = db.data().users[user_uuid]
+    except KeyError:
+        raise HTTPException(status_code=404, detail="User not found")
     ctx = await authz.verify(
         auth,
         ["auth:admin", "auth:org:admin"],
         match=permutil.has_any,
         host=request.headers.get("host"),
     )
-    if not can_manage_org(ctx, org_uuid):
+    if not can_manage_org(ctx, user.org.uuid):
         raise authz.AuthException(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )
-    new_role = payload.get("role")
-    if not new_role:
-        raise ValueError("role is required")
+    role_uuid_str = payload.get("role_uuid")
+    if not role_uuid_str:
+        raise ValueError("role_uuid is required")
     try:
-        user_org, _current_role = db.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 = user_org.roles
-    if not any(r.display_name == new_role for r in roles):
+        new_role_uuid = UUID(role_uuid_str)
+    except (ValueError, TypeError):
+        raise ValueError("Invalid role UUID")
+    new_role = db.data().roles.get(new_role_uuid)
+    if not new_role or new_role.org_uuid != user.org.uuid:
         raise ValueError("Role not found in organization")
 
     # Sanity check: prevent admin from removing their own access
     if ctx.user.uuid == user_uuid:
-        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
-            # Check if any permission in the new role is an admin permission
-            has_admin_access = False
-            for perm_uuid in new_role_obj.permissions:
-                perm = db.data().permissions.get(perm_uuid)
-                if perm and perm.scope in ["auth:admin", "auth:org:admin"]:
-                    has_admin_access = True
-                    break
-            if not has_admin_access:
-                raise ValueError(
-                    "Cannot change your own role to one without admin permissions"
-                )
+        # Check if any permission in the new role is an admin permission
+        has_admin_access = False
+        for perm_uuid in new_role.permissions:
+            perm = db.data().permissions.get(perm_uuid)
+            if perm and perm.scope in ["auth:admin", "auth:org:admin"]:
+                has_admin_access = True
+                break
+        if not has_admin_access:
+            raise ValueError(
+                "Cannot change your own role to one without admin permissions"
+            )
 
-    db.update_user_role_in_organization(user_uuid, new_role, ctx=ctx)
+    db.update_user_role(user_uuid, new_role_uuid, ctx=ctx)
     return {"status": "ok"}
 
 
-@app.post("/orgs/{org_uuid}/users/{user_uuid}/create-link")
+@app.post("/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 = db.get_user_organization(user_uuid)
-    except ValueError:
+        user = db.data().users[user_uuid]
+    except KeyError:
         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", "auth:org:admin"],
@@ -531,20 +521,18 @@ async def admin_create_user_registration_link(
         host=request.headers.get("host"),
         max_age="5m",
     )
-    if not can_manage_org(ctx, org_uuid):
+    if not can_manage_org(ctx, user.org.uuid):
         raise authz.AuthException(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )
 
     # Check if user has existing credentials
-    has_credentials = db.get_user_credential_ids(user_uuid)
+    has_credentials = db.data().users[user_uuid].credential_ids
     token_type = "user registration" if not has_credentials else "account recovery"
 
-    token = passphrase.generate()
     expiry = reset_expires()
-    db.create_reset_token(
+    token = db.create_reset_token(
         user_uuid=user_uuid,
-        passphrase=token,
         expiry=expiry,
         token_type=token_type,
         ctx=ctx,
@@ -553,39 +541,37 @@ async def admin_create_user_registration_link(
     return {
         "url": url,
         "expires": format_datetime(expiry),
+        "token_type": token_type,
     }
 
 
-@app.get("/orgs/{org_uuid}/users/{user_uuid}")
+@app.get("/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 = db.get_user_organization(user_uuid)
-    except ValueError:
+        user = db.data().users[user_uuid]
+        role_name = user.role.display_name
+    except KeyError:
         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", "auth:org:admin"],
         match=permutil.has_any,
         host=request.headers.get("host"),
     )
-    if not can_manage_org(ctx, org_uuid):
+    if not can_manage_org(ctx, user.org.uuid):
         raise authz.AuthException(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )
-    user = db.data().users.get(user_uuid)
     normalized_host = hostutil.normalize_host(request.headers.get("host"))
 
     return MsgspecResponse(
         {
             "display_name": user.display_name,
-            "org": {"display_name": user_org.display_name},
+            "org": {"display_name": user.org.display_name},
             "role": role_name,
             "visits": user.visits,
             "created_at": user.created_at,
@@ -615,27 +601,24 @@ async def admin_get_user_detail(
     )
 
 
-@app.patch("/orgs/{org_uuid}/users/{user_uuid}/display-name")
+@app.patch("/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 = db.get_user_organization(user_uuid)
-    except ValueError:
+        user = db.data().users[user_uuid]
+    except KeyError:
         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", "auth:org:admin"],
         match=permutil.has_any,
         host=request.headers.get("host"),
     )
-    if not can_manage_org(ctx, org_uuid):
+    if not can_manage_org(ctx, user.org.uuid):
         raise authz.AuthException(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )
@@ -648,20 +631,17 @@ async def admin_update_user_display_name(
     return {"status": "ok"}
 
 
-@app.delete("/orgs/{org_uuid}/users/{user_uuid}/credentials/{credential_uuid}")
-async def admin_delete_user_credential(
-    org_uuid: UUID,
+@app.delete("/users/{user_uuid}")
+async def admin_delete_user(
     user_uuid: UUID,
-    credential_uuid: UUID,
     request: Request,
     auth=AUTH_COOKIE,
 ):
+    """Delete a user and all their credentials/sessions."""
     try:
-        user_org, _role_name = db.get_user_organization(user_uuid)
-    except ValueError:
+        user = db.data().users[user_uuid]
+    except KeyError:
         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", "auth:org:admin"],
@@ -669,7 +649,36 @@ async def admin_delete_user_credential(
         host=request.headers.get("host"),
         max_age="5m",
     )
-    if not can_manage_org(ctx, org_uuid):
+    if not can_manage_org(ctx, user.org.uuid):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+    # Prevent admin from deleting themselves
+    if ctx.user.uuid == user_uuid:
+        raise ValueError("Cannot delete your own account")
+    db.delete_user(user_uuid, ctx=ctx)
+    return {"status": "ok"}
+
+
+@app.delete("/users/{user_uuid}/credentials/{credential_uuid}")
+async def admin_delete_user_credential(
+    user_uuid: UUID,
+    credential_uuid: UUID,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    try:
+        user = db.data().users[user_uuid]
+    except KeyError:
+        raise HTTPException(status_code=404, detail="User not found")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", "auth:org:admin"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+        max_age="5m",
+    )
+    if not can_manage_org(ctx, user.org.uuid):
         raise authz.AuthException(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )
@@ -677,27 +686,24 @@ async def admin_delete_user_credential(
     return {"status": "ok"}
 
 
-@app.delete("/orgs/{org_uuid}/users/{user_uuid}/sessions/{session_id}")
+@app.delete("/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 = db.get_user_organization(user_uuid)
-    except ValueError:
+        user = db.data().users[user_uuid]
+    except KeyError:
         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", "auth:org:admin"],
         match=permutil.has_any,
         host=request.headers.get("host"),
     )
-    if not can_manage_org(ctx, org_uuid):
+    if not can_manage_org(ctx, user.org.uuid):
         raise authz.AuthException(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )

paskia/fastapi/api.py

@@ -14,10 +14,11 @@ from fastapi.responses import JSONResponse
 from fastapi.security import HTTPBearer
 
 from paskia import db
+from paskia._version import __version__
 from paskia.authsession import EXPIRES, expires, get_reset
 from paskia.fastapi import authz, session, user
 from paskia.fastapi.response import MsgspecResponse
-from paskia.fastapi.session import AUTH_COOKIE, AUTH_COOKIE_NAME
+from paskia.fastapi.session import AUTH_COOKIE, AUTH_COOKIE_NAME, get_client_ip
 from paskia.globals import passkey as global_passkey
 from paskia.util import hostutil, htmlutil, passphrase, userinfo, vitedev
 
@@ -91,7 +92,7 @@ async def validate_token(
         if not timedelta(0) < consumed < _REFRESH_INTERVAL:
             db.update_session(
                 auth,
-                ip=request.client.host if request.client else "",
+                ip=get_client_ip(request),
                 user_agent=request.headers.get("user-agent") or "",
                 expiry=expires(),
                 ctx=ctx,
@@ -195,6 +196,7 @@ async def get_settings():
         "auth_host": hostutil.dedicated_auth_host(),
         "auth_site_url": hostutil.auth_site_url(),
         "session_cookie": AUTH_COOKIE_NAME,
+        "version": __version__,
     }
 
 

paskia/fastapi/authz.py

@@ -80,6 +80,9 @@ async def verify(
             mode="login",
             clear_session=True,
         )
+    # User's theme preference for iframe (only if explicitly set)
+    user_theme = ctx.user.theme if ctx.user.theme else None
+
     # Check max_age requirement if specified
     if max_age:
         try:
@@ -88,6 +91,7 @@ async def verify(
                     status_code=401,
                     detail="Additional authentication required",
                     mode="reauth",
+                    theme=user_theme,
                 )
         except ValueError as e:
             # Invalid max_age format - log but don't fail the request
@@ -104,7 +108,10 @@ async def verify(
             ctx, perm, missing, require_all=(match == permutil.has_all)
         )
         raise AuthException(
-            status_code=403, mode="forbidden", detail="Permission required"
+            status_code=403,
+            mode="forbidden",
+            detail="Permission required",
+            theme=user_theme,
         )
 
     return ctx

paskia/fastapi/logging.py

@@ -38,10 +38,33 @@ _AUTHZ_GRANTED = "\033[0;32m"  # Granted scope (green)
 
 
 def format_ipv6_network(ip: str) -> str:
-    """Format IPv6 address to show only network part (first 64 bits)."""
+    """Format IPv6 address to show only network part (first 64 bits).
+
+    Special addresses are returned as-is for clarity:
+    - ::1 (loopback)
+    - :: (unspecified)
+    - ::ffff:x.x.x.x (IPv4-mapped, returns just the IPv4 part)
+    - fe80:: (link-local, returned as-is since interface-specific)
+    """
     try:
+        # Strip brackets that some proxies add around IPv6
+        ip = ip.strip("[]")
+        # Strip zone ID (e.g., fe80::1%eth0)
+        if "%" in ip:
+            ip = ip.split("%")[0]
         addr = IPv6Address(ip)
-        # Get the integer representation and mask to first 64 bits
+
+        # Special cases - return as-is or with minimal processing
+        if addr.is_loopback:  # ::1
+            return "::1"
+        if addr.is_unspecified:  # ::
+            return "::"
+        if addr.ipv4_mapped:  # ::ffff:x.x.x.x
+            return str(addr.ipv4_mapped)
+        if addr.is_link_local:  # fe80::/10 - interface-specific, keep full
+            return str(addr)
+
+        # Regular addresses: truncate to /64 network prefix
         network_int = int(addr) >> 64
         # Format as IPv6 with trailing ::
         # Split into 4 groups of 16 bits
@@ -61,7 +84,9 @@ def format_client_ip(ip: str) -> str:
     """Format client IP, compressing IPv6 to network part only."""
     if not ip or ip == "-":
         return "-"
-    if ":" in ip:
+    # Strip brackets for detection (some proxies add them)
+    stripped = ip.strip("[]")
+    if ":" in stripped:
         return format_ipv6_network(ip)
     return ip
 

paskia/fastapi/mainapp.py

@@ -12,6 +12,7 @@ from paskia import globals
 from paskia.db import start_background, stop_background
 from paskia.db.logging import configure_db_logging
 from paskia.fastapi import admin, api, auth_host, ws
+from paskia.fastapi.__main__ import DEVMODE
 from paskia.fastapi.logging import AccessLogMiddleware, configure_access_logging
 from paskia.fastapi.session import AUTH_COOKIE
 from paskia.util import hostutil, passphrase, vitedev
@@ -26,6 +27,7 @@ _access_logger = logging.getLogger("paskia.access")
 frontend = Frontend(
     Path(__file__).parent.parent / "frontend-build",
     cached=["/auth/assets/"],
+    favicon="/paskia.webp",
 )
 
 
@@ -58,7 +60,7 @@ async def lifespan(app: FastAPI):  # pragma: no cover - startup path
 
     # Restore uvicorn info logging (suppressed during startup in dev mode)
     # Keep uvicorn.error at WARNING to suppress WebSocket "connection open/closed" messages
-    if frontend.devmode:
+    if app.debug:
         logging.getLogger("uvicorn").setLevel(logging.INFO)
     logging.getLogger("uvicorn.error").setLevel(logging.WARNING)
     await frontend.load()
@@ -73,6 +75,7 @@ app = FastAPI(
     docs_url=None,
     redoc_url=None,
     openapi_url=None,
+    debug=DEVMODE,
 )
 
 # Custom access logging (uvicorn's access_log is disabled)
@@ -135,6 +138,11 @@ async def examples_page():
     return FileResponse(index_file, media_type="text/html")
 
 
+# Frontend static files - must be before /{token} catch-all routes
+# (actual routes registered during lifespan after frontend.load())
+frontend.route(app, "/")
+
+
 # Note: this catch-all handler must be the last route defined
 @app.get("/{token}")
 @app.get("/auth/{token}")
@@ -147,7 +155,3 @@ async def token_link(token: str):
         raise HTTPException(status_code=404)
 
     return Response(*await vitedev.read("/int/reset/index.html"))
-
-
-# Final catch-all route for frontend files (keep at end of file)
-frontend.route(app, "/")

paskia/fastapi/remote.py

@@ -20,7 +20,7 @@ from paskia.authsession import expires
 from paskia.fastapi.session import AUTH_COOKIE, infodict
 from paskia.fastapi.wschat import authenticate_and_login
 from paskia.fastapi.wsutil import validate_origin, websocket_error_handler
-from paskia.util import passphrase, pow, useragent
+from paskia.util import pow, useragent
 
 # Create a FastAPI subapp for remote auth WebSocket endpoints
 app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
@@ -317,16 +317,13 @@ async def websocket_remote_auth_permit(ws: WebSocket, auth=AUTH_COOKIE):
 
                 if request.action == "register":
                     # For registration, create a reset token for device addition
-                    token_str = passphrase.generate()
                     expiry = expires()
-                    db.create_reset_token(
+                    reset_token = db.create_reset_token(
                         user_uuid=ctx.user.uuid,
-                        passphrase=token_str,
                         expiry=expiry,
                         token_type="device addition",
                         user=str(ctx.user.uuid),
                     )
-                    reset_token = token_str
 
                 # Complete the remote auth request (notifies the waiting device)
                 cred = db.data().credentials[ctx.session.credential_uuid]

paskia/fastapi/reset.py

@@ -1,108 +0,0 @@
-"""CLI support for creating user credential reset links.
-
-Usage (via main CLI):
-    paskia reset [query]
-
-If query is omitted, the master admin (first Administration role user in
-an organization granting auth:admin) is targeted. Otherwise query is
-matched as either an exact UUID or a case-insensitive substring of the
-display name. If multiple users match, they are listed and the command
-aborts. A new one-time reset link is always created.
-"""
-
-import asyncio
-from uuid import UUID
-
-from paskia import authsession as _authsession
-from paskia import db
-from paskia.util import hostutil, passphrase
-
-
-async def _resolve_targets(query: str | None):
-    if query:
-        # Try UUID
-        targets: list[tuple] = []
-        try:
-            q_uuid = UUID(query)
-            p = next(
-                (p for p in db.data().permissions.values() if p.scope == "auth:admin"),
-                None,
-            )
-            if p:
-                for org_uuid in p.orgs:
-                    users = db.get_organization_users(org_uuid)
-                    for u, role_name in users:
-                        if u.uuid == q_uuid:
-                            return [(u, role_name)]
-            # UUID not found among admin orgs -> fall back to substring search (rare case)
-        except ValueError:
-            pass
-        # Substring search
-        needle = query.lower()
-        p = next(
-            (p for p in db.data().permissions.values() if p.scope == "auth:admin"), None
-        )
-        if p:
-            for org_uuid in p.orgs:
-                users = db.get_organization_users(org_uuid)
-                for u, role_name in users:
-                    if needle in (u.display_name or "").lower():
-                        targets.append((u, role_name))
-        # De-duplicate
-        seen = set()
-        deduped = []
-        for u, role_name in targets:
-            if u.uuid not in seen:
-                seen.add(u.uuid)
-                deduped.append((u, role_name))
-        return deduped
-    # No query -> master admin
-    p = next(
-        (p for p in db.data().permissions.values() if p.scope == "auth:admin"), None
-    )
-    if not p or not p.orgs:
-        return []
-    first_org_uuid = next(iter(p.orgs))
-    users = db.get_organization_users(first_org_uuid)
-    admin_users = [pair for pair in users if pair[1] == "Administration"]
-    return admin_users[:1]
-
-
-async def _create_reset(user, role_name: str):
-    token = passphrase.generate()
-    expiry = _authsession.reset_expires()
-    db.create_reset_token(
-        passphrase=token,
-        user_uuid=user.uuid,
-        expiry=expiry,
-        token_type="manual reset",
-    )
-    return hostutil.reset_link_url(token), token
-
-
-async def _main(query: str | None) -> int:
-    try:
-        candidates = await _resolve_targets(query)
-        if not candidates:
-            print("No matching users found")
-            return 1
-        if len(candidates) > 1:
-            print("Multiple matches. Refine your query:")
-            for u, role_name in candidates:
-                print(f" - {u.display_name}  ({u.uuid}) role={role_name}")
-            return 2
-        user, role_name = candidates[0]
-        link, token = await _create_reset(user, role_name)
-        print(f"Reset link for {user.display_name} ({user.uuid}):\n{link}\n")
-        return 0
-    except Exception as e:  # pragma: no cover
-        print("Failed to create reset link:", e)
-        return 1
-
-
-def run(query: str | None) -> int:
-    """Synchronous wrapper for CLI entrypoint."""
-    return asyncio.run(_main(query))
-
-
-__all__ = ["run"]

paskia/fastapi/session.py

@@ -8,6 +8,8 @@ This module provides FastAPI-specific session management functionality:
 Generic session management functions have been moved to authsession.py
 """
 
+from ipaddress import IPv4Address, IPv6Address
+
 from fastapi import Cookie, Request, Response, WebSocket
 
 from paskia.authsession import EXPIRES
@@ -16,10 +18,44 @@ AUTH_COOKIE_NAME = "__Host-paskia"
 AUTH_COOKIE = Cookie(None, alias=AUTH_COOKIE_NAME)
 
 
+def normalize_ip(ip: str) -> str:
+    """Normalize IP address, stripping brackets and validating format.
+
+    Proxies may pass IPv6 in brackets like [::1] or with zone IDs.
+    IPv4-mapped IPv6 addresses (::ffff:x.x.x.x) are converted to plain IPv4.
+    Returns empty string for invalid addresses.
+    """
+    if not ip:
+        return ""
+    # Strip brackets that some proxies add around IPv6
+    ip = ip.strip("[]")
+    # Strip zone ID (e.g., fe80::1%eth0)
+    if "%" in ip:
+        ip = ip.split("%")[0]
+    try:
+        # Validate and normalize
+        if ":" in ip:
+            addr = IPv6Address(ip)
+            # Convert IPv4-mapped addresses to plain IPv4
+            if addr.ipv4_mapped:
+                return str(addr.ipv4_mapped)
+            return str(addr)
+        return str(IPv4Address(ip))
+    except ValueError:
+        return ip  # Return as-is if not a valid IP (could be hostname)
+
+
+def get_client_ip(request: Request | WebSocket) -> str:
+    """Get client IP from request, normalized."""
+    if not request.client:
+        return ""
+    return normalize_ip(request.client.host)
+
+
 def infodict(request: Request | WebSocket, type: str) -> dict:
     """Extract client information from request."""
     return {
-        "ip": request.client.host if request.client else "",
+        "ip": get_client_ip(request),
         "user_agent": request.headers.get("user-agent", "")[:500],
         "session_type": type,
     }

paskia/fastapi/user.py

@@ -17,7 +17,7 @@ from paskia.authsession import (
 )
 from paskia.fastapi import authz, session
 from paskia.fastapi.session import AUTH_COOKIE
-from paskia.util import hostutil, passphrase
+from paskia.util import hostutil
 
 app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
 
@@ -57,6 +57,28 @@ async def user_update_display_name(
     return {"status": "ok"}
 
 
+@app.patch("/theme")
+async def user_update_theme(
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    if not auth:
+        raise authz.AuthException(
+            status_code=401, detail="Authentication Required", mode="login"
+        )
+    ctx = db.data().session_ctx(auth, request.headers.get("host"))
+    if not ctx:
+        raise authz.AuthException(
+            status_code=401, detail="Session expired", mode="login"
+        )
+    theme = payload.get("theme", "")
+    if theme not in ("", "light", "dark"):
+        raise HTTPException(status_code=400, detail="Invalid theme")
+    db.update_user_theme(ctx.user.uuid, theme, ctx=ctx)
+    return {"status": "ok"}
+
+
 @app.post("/logout-all")
 async def api_logout_all(request: Request, response: Response, auth=AUTH_COOKIE):
     if not auth:
@@ -127,11 +149,9 @@ async def api_create_link(
 ):
     # Require recent authentication for sensitive operation
     ctx = await authz.verify(auth, [], host=request.headers.get("host"), max_age="5m")
-    token = passphrase.generate()
     expiry = expires()
-    db.create_reset_token(
+    token = db.create_reset_token(
         user_uuid=ctx.user.uuid,
-        passphrase=token,
         expiry=expiry,
         token_type="device addition",
         ctx=ctx,
@@ -145,4 +165,5 @@ async def api_create_link(
             if expiry.tzinfo
             else expiry.replace(tzinfo=UTC).isoformat().replace("+00:00", "Z")
         ),
+        "token_type": "device addition",
     }

paskia/fastapi/ws.py

@@ -7,7 +7,7 @@ from paskia.fastapi.session import AUTH_COOKIE, infodict
 from paskia.fastapi.wschat import authenticate_and_login, register_chat
 from paskia.fastapi.wsutil import validate_origin, websocket_error_handler
 from paskia.globals import passkey
-from paskia.util import passphrase
+from paskia.util import hostutil, passphrase
 
 # Create a FastAPI subapp for WebSocket endpoints
 app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
@@ -31,7 +31,7 @@ async def websocket_register_add(
     - Reset token supplied as ?reset=... (auth cookie ignored)
     """
     origin = validate_origin(ws)
-    host = origin.split("://", 1)[1]
+    host = hostutil.normalize_host(origin.split("://", 1)[1])
     if reset is not None:
         if not passphrase.is_well_formed(reset):
             raise ValueError(
@@ -52,7 +52,7 @@ async def websocket_register_add(
         stripped = name.strip()
         if stripped:
             user_name = stripped
-    credential_ids = db.get_user_credential_ids(user_uuid) or None
+    credential_ids = user.credential_ids or None
 
     # WebAuthn registration
     credential = await register_chat(ws, user_uuid, user_name, origin, credential_ids)

paskia/fastapi/wschat.py

@@ -7,7 +7,6 @@ from uuid import UUID
 from fastapi import WebSocket
 
 from paskia import db
-from paskia.authsession import expires
 from paskia.db import Credential, SessionContext
 from paskia.fastapi.session import infodict
 from paskia.fastapi.wsutil import validate_origin
@@ -93,7 +92,7 @@ async def authenticate_and_login(
     if auth:
         existing_ctx = db.data().session_ctx(auth, host)
         if existing_ctx:
-            credential_ids = db.get_user_credential_ids(existing_ctx.user.uuid) or None
+            credential_ids = existing_ctx.user.credential_ids or None
 
     cred, new_sign_count = await authenticate_chat(ws, credential_ids)
 
@@ -105,7 +104,6 @@ async def authenticate_and_login(
         host=normalized_host,
         ip=metadata["ip"],
         user_agent=metadata["user_agent"],
-        expiry=expires(),
     )
 
     # Fetch and return the full session context

paskia/globals.py

@@ -42,7 +42,7 @@ async def init(
 
     Database configuration:
         Set PASKIA_DB environment variable to specify the JSONL database file path.
-        Default: paskia.jsonl
+        Default: {rp_id}.paskiadb
     """
 
     # Initialize passkey instance with provided parameters
@@ -53,7 +53,7 @@ async def init(
     )
 
     # Initialize database
-    await db.init()
+    await db.init(rp_id=rp_id)
 
     # Initialize remote auth manager
     await remoteauth.init()

paskia/migrate/__init__.py

@@ -1,281 +0,0 @@
-"""
-SQL to JSON migration module for Paskia.
-
-This module contains the legacy SQL database implementation and migration tools
-for converting from the old SQLite database to the new JSONL format.
-
-Usage:
-    python -m paskia.migrate --sql sqlite+aiosqlite:///paskia.sqlite --json paskia.jsonl
-
-Or via the CLI entry point (if installed):
-    paskia-migrate --sql sqlite+aiosqlite:///paskia.sqlite --json paskia.jsonl
-"""
-
-import argparse
-import asyncio
-import re
-from datetime import UTC, datetime
-from uuid import UUID
-
-import base64url
-import uuid7
-from sqlalchemy import select
-
-from paskia.authsession import EXPIRES
-from paskia.db.jsonl import JsonlStore
-from paskia.db.structs import (
-    DB,
-    Credential,
-    Org,
-    Permission,
-    ResetToken,
-    Role,
-    Session,
-    User,
-)
-
-from .sql import (
-    DB as SQLDB,
-)
-from .sql import (
-    CredentialModel,
-    ResetTokenModel,
-    SessionModel,
-    UserModel,
-)
-
-# Re-export for convenience
-__all__ = ["migrate_from_sql", "main", "SQLDB"]
-
-# Default paths
-SQL_DB_DEFAULT = "sqlite+aiosqlite:///paskia.sqlite"
-JSON_DB_DEFAULT = "paskia.jsonl"
-
-
-async def migrate_from_sql(
-    sql_db_path: str = SQL_DB_DEFAULT,
-    json_db_path: str = JSON_DB_DEFAULT,
-) -> None:
-    """Migrate data from SQL database to JSON format.
-
-    Args:
-        sql_db_path: SQLAlchemy connection string for the source SQL database
-        json_db_path: Path for the destination JSONL file
-    """
-    # Initialize source SQL database
-    sql_db = SQLDB(sql_db_path)
-    await sql_db.init_db()
-
-    # Initialize destination JSON database (fresh, don't load existing)
-    db = DB()
-    store = JsonlStore(db, json_db_path)
-    db._store = store
-
-    print(f"Migrating from {sql_db_path} to {json_db_path}...")
-
-    # Build all data directly without saving (we'll save once at the end)
-    # Track old permission ID -> new scope mapping for migration
-    # Also track org-specific admin permissions to consolidate
-    old_org_admin_pattern = re.compile(r"^auth:org:([0-9a-f-]+)$", re.IGNORECASE)
-    org_admin_uuids = set()  # org UUIDs that had org-specific admin permissions
-
-    # First pass: identify org-specific admin permissions
-    permissions = await sql_db.list_permissions()
-    for perm in permissions:
-        match = old_org_admin_pattern.match(perm.id)
-        if match:
-            org_admin_uuids.add(match.group(1).lower())
-
-    # Migrate permissions with UUID keys and scope field
-    # Always create exactly one common auth:org:admin permission for all org admin needs
-    org_admin_perm_uuid: UUID = uuid7.create()
-    org_admin_perm = Permission(
-        scope="auth:org:admin",
-        display_name="Org Admin",
-        orgs={},
-    )
-    org_admin_perm.uuid = org_admin_perm_uuid
-    db.permissions[org_admin_perm_uuid] = org_admin_perm
-
-    # Mapping from old permission ID to new permission UUID
-    perm_id_to_uuid: dict[str, UUID] = {}
-
-    for perm in permissions:
-        # Skip old org-specific admin permissions (auth:org:{uuid}) - they map to auth:org:admin
-        match = old_org_admin_pattern.match(perm.id)
-        if match:
-            perm_id_to_uuid[perm.id] = org_admin_perm_uuid
-            continue
-
-        # Skip if this is already auth:org:admin - we created one above
-        if perm.id == "auth:org:admin":
-            perm_id_to_uuid[perm.id] = org_admin_perm_uuid
-            continue
-
-        # Regular permission - create with UUID key
-        perm_uuid: UUID = uuid7.create()
-        new_perm = Permission(
-            scope=perm.id,  # Old ID becomes the scope
-            display_name=perm.display_name,
-            orgs={},
-        )
-        new_perm.uuid = perm_uuid
-        db.permissions[perm_uuid] = new_perm
-        perm_id_to_uuid[perm.id] = perm_uuid
-    print(
-        f"  Migrated {len(permissions)} permissions (with {len(org_admin_uuids)} org-specific admins consolidated to auth:org:admin)"
-    )
-
-    # Migrate organizations
-    orgs = await sql_db.list_organizations()
-    for org in orgs:
-        org_key: UUID = org.uuid
-        new_org = Org(display_name=org.display_name)
-        new_org.uuid = org_key
-        db.orgs[org_key] = new_org
-        # Update permissions to allow this org to grant them (by UUID)
-        for old_perm_id in org.permissions:
-            perm_uuid = perm_id_to_uuid.get(old_perm_id)
-            if perm_uuid and perm_uuid in db.permissions:
-                db.permissions[perm_uuid].orgs[org_key] = True
-        # Ensure every org can grant auth:org:admin
-        db.permissions[org_admin_perm_uuid].orgs[org_key] = True
-    print(f"  Migrated {len(orgs)} organizations")
-
-    # Migrate roles - convert old permission IDs to UUIDs
-    role_count = 0
-    for org in orgs:
-        for role in org.roles:
-            role_key: UUID = role.uuid
-            # Convert old permission IDs to UUIDs
-            new_permissions: dict[UUID, bool] = {}
-            for old_perm_id in role.permissions or []:
-                perm_uuid = perm_id_to_uuid.get(old_perm_id)
-                if perm_uuid:
-                    new_permissions[perm_uuid] = True
-            new_role = Role(
-                org_uuid=role.org_uuid,
-                display_name=role.display_name,
-                permissions=new_permissions,
-            )
-            new_role.uuid = role_key
-            db.roles[role_key] = new_role
-            role_count += 1
-    print(f"  Migrated {role_count} roles")
-
-    # Migrate users
-    async with sql_db.session() as session:
-        result = await session.execute(select(UserModel))
-        user_models = result.scalars().all()
-        for um in user_models:
-            legacy_user = um.as_dataclass()
-            user_key: UUID = legacy_user.uuid
-            new_user = User(
-                display_name=legacy_user.display_name,
-                role_uuid=legacy_user.role_uuid,
-                created_at=legacy_user.created_at or datetime.now(UTC),
-                last_seen=legacy_user.last_seen,
-                visits=legacy_user.visits,
-            )
-            new_user.uuid = user_key
-            db.users[user_key] = new_user
-        print(f"  Migrated {len(user_models)} users")
-
-    # Migrate credentials
-    async with sql_db.session() as session:
-        result = await session.execute(select(CredentialModel))
-        cred_models = result.scalars().all()
-        for cm in cred_models:
-            legacy_cred = cm.as_dataclass()
-            cred_key: UUID = legacy_cred.uuid
-            new_cred = Credential(
-                credential_id=legacy_cred.credential_id,
-                user_uuid=legacy_cred.user_uuid,
-                aaguid=legacy_cred.aaguid,
-                public_key=legacy_cred.public_key,
-                sign_count=legacy_cred.sign_count,
-                created_at=legacy_cred.created_at,
-                last_used=legacy_cred.last_used,
-                last_verified=legacy_cred.last_verified,
-            )
-            new_cred.uuid = cred_key
-            db.credentials[cred_key] = new_cred
-        print(f"  Migrated {len(cred_models)} credentials")
-
-    # Migrate sessions
-    # Old format: b"sess" + 12 bytes -> New format: base64url string (16 chars)
-    async with sql_db.session() as session:
-        result = await session.execute(select(SessionModel))
-        session_models = result.scalars().all()
-        for sm in session_models:
-            sess = sm.as_dataclass()
-            old_key: bytes = sess.key
-            # Strip b"sess" prefix and encode remaining 12 bytes as base64url
-            if old_key.startswith(b"sess"):
-                session_key = base64url.enc(old_key[4:])
-            else:
-                # Already in new format or unknown - try to use as-is
-                session_key = base64url.enc(old_key[:12])
-            db.sessions[session_key] = Session(
-                user_uuid=sess.user_uuid,
-                credential_uuid=sess.credential_uuid,
-                host=sess.host,
-                ip=sess.ip,
-                user_agent=sess.user_agent,
-                expiry=sess.renewed + EXPIRES,  # Convert renewed to expiry
-            )
-        print(f"  Migrated {len(session_models)} sessions")
-
-    # Migrate reset tokens
-    # Old format: b"rset" + 16 bytes hash -> New format: 9 bytes (truncated hash)
-    async with sql_db.session() as session:
-        result = await session.execute(select(ResetTokenModel))
-        token_models = result.scalars().all()
-        for tm in token_models:
-            token = tm.as_dataclass()
-            old_key: bytes = token.key
-            # Strip b"rset" prefix and take first 9 bytes of hash
-            if old_key.startswith(b"rset"):
-                token_key = old_key[4:13]  # 9 bytes after prefix
-            else:
-                # Already in new format or unknown - truncate to 9 bytes
-                token_key = old_key[:9]
-            db.reset_tokens[token_key] = ResetToken(
-                user_uuid=token.user_uuid,
-                expiry=token.expiry,
-                token_type=token.token_type,
-            )
-        print(f"  Migrated {len(token_models)} reset tokens")
-
-    # Queue and flush all changes using the transaction mechanism
-    with db.transaction("migrate:sql"):
-        pass  # All data already added to _data, transaction commits on exit
-
-    await store.flush()
-
-    print("Migration complete!")
-
-
-def main():
-    """CLI entry point for migration."""
-
-    parser = argparse.ArgumentParser(
-        description="Migrate Paskia database from SQL to JSON"
-    )
-    parser.add_argument(
-        "--sql",
-        default=SQL_DB_DEFAULT,
-        help=f"Source SQL database connection string (default: {SQL_DB_DEFAULT})",
-    )
-    parser.add_argument(
-        "--json",
-        default=JSON_DB_DEFAULT,
-        help=f"Destination JSONL file path (default: {JSON_DB_DEFAULT})",
-    )
-    args = parser.parse_args()
-
-    asyncio.run(migrate_from_sql(args.sql, args.json))
-
-
-if __name__ == "__main__":
-    main()

paskia/migrate/sql.py

@@ -1,438 +0,0 @@
-"""
-Legacy SQL database implementation for migration purposes.
-
-This module provides the async SQLAlchemy database layer that was used
-before the JSONL format. It is kept here for migration purposes only.
-
-DO NOT use this module for new code. Use paskia.db instead.
-"""
-
-from contextlib import asynccontextmanager
-from dataclasses import dataclass
-from datetime import UTC, datetime
-from uuid import UUID
-
-from sqlalchemy import (
-    DateTime,
-    ForeignKey,
-    Integer,
-    LargeBinary,
-    String,
-    event,
-    select,
-)
-from sqlalchemy.dialects.sqlite import BLOB
-from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
-from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
-
-
-# Legacy User class for SQL schema (uses 'role_uuid' not 'role')
-@dataclass
-class _LegacyUser:
-    """User as stored in the old SQL schema with role_uuid field."""
-
-    uuid: UUID
-    display_name: str
-    role_uuid: UUID
-    created_at: datetime | None = None
-    last_seen: datetime | None = None
-    visits: int = 0
-
-
-# Legacy Credential class for SQL schema (uses 'user_uuid' not 'user')
-@dataclass
-class _LegacyCredential:
-    """Credential as stored in the old SQL schema with user_uuid field."""
-
-    uuid: UUID
-    credential_id: bytes
-    user_uuid: UUID
-    aaguid: UUID
-    public_key: bytes
-    sign_count: int
-    created_at: datetime
-    last_used: datetime | None = None
-    last_verified: datetime | None = None
-
-
-# Legacy Role class for SQL schema (uses 'org_uuid' not 'org')
-@dataclass
-class _LegacyRole:
-    """Role as stored in the old SQL schema with org_uuid field."""
-
-    uuid: UUID
-    org_uuid: UUID
-    display_name: str
-    permissions: list[str] | None = None
-
-
-# Legacy Org class for SQL schema (has mutable permissions/roles lists)
-@dataclass
-class _LegacyOrg:
-    """Org as stored in the old SQL schema with mutable permissions/roles."""
-
-    uuid: UUID
-    display_name: str
-    permissions: list[str] | None = None
-    roles: list[_LegacyRole] | None = None
-
-
-# Legacy Session class for SQL schema (uses 'key' as field, 'user_uuid', 'credential_uuid')
-@dataclass
-class _LegacySession:
-    """Session as stored in the old SQL schema."""
-
-    key: bytes
-    user_uuid: UUID
-    credential_uuid: UUID
-    host: str
-    ip: str
-    user_agent: str
-    renewed: datetime
-
-
-# Legacy ResetToken class for SQL schema (uses 'key' as field, 'user_uuid')
-@dataclass
-class _LegacyResetToken:
-    """ResetToken as stored in the old SQL schema."""
-
-    key: bytes
-    user_uuid: UUID
-    token_type: str
-    expiry: datetime
-
-
-# Local Permission class for SQL schema (uses 'id' not 'uuid' + 'scope')
-@dataclass
-class SqlPermission:
-    """Permission as stored in the old SQL schema with id field."""
-
-    id: str
-    display_name: str
-
-
-DB_PATH_DEFAULT = "sqlite+aiosqlite:///paskia.sqlite"
-
-
-def _normalize_dt(value: datetime | None) -> datetime | None:
-    if value is None:
-        return None
-    if value.tzinfo is None:
-        return value.replace(tzinfo=UTC)
-    return value.astimezone(UTC)
-
-
-class Base(DeclarativeBase):
-    pass
-
-
-class OrgModel(Base):
-    __tablename__ = "orgs"
-
-    uuid: Mapped[bytes] = mapped_column(LargeBinary(16), primary_key=True)
-    display_name: Mapped[str] = mapped_column(String, nullable=False)
-
-    def as_dataclass(self):
-        # Base Org without permissions/roles (filled by data accessors)
-        return _LegacyOrg(
-            uuid=UUID(bytes=self.uuid),
-            display_name=self.display_name,
-        )
-
-    @staticmethod
-    def from_dataclass(org: _LegacyOrg):
-        return OrgModel(uuid=org.uuid.bytes, display_name=org.display_name)
-
-
-class RoleModel(Base):
-    __tablename__ = "roles"
-
-    uuid: Mapped[bytes] = mapped_column(LargeBinary(16), primary_key=True)
-    org_uuid: Mapped[bytes] = mapped_column(
-        LargeBinary(16), ForeignKey("orgs.uuid", ondelete="CASCADE"), nullable=False
-    )
-    display_name: Mapped[str] = mapped_column(String, nullable=False)
-
-    def as_dataclass(self):
-        # Base Role without permissions (filled by data accessors)
-        return _LegacyRole(
-            uuid=UUID(bytes=self.uuid),
-            org_uuid=UUID(bytes=self.org_uuid),
-            display_name=self.display_name,
-        )
-
-    @staticmethod
-    def from_dataclass(role: _LegacyRole):
-        return RoleModel(
-            uuid=role.uuid.bytes,
-            org_uuid=role.org_uuid.bytes,
-            display_name=role.display_name,
-        )
-
-
-class UserModel(Base):
-    __tablename__ = "users"
-
-    uuid: Mapped[bytes] = mapped_column(LargeBinary(16), primary_key=True)
-    display_name: Mapped[str] = mapped_column(String, nullable=False)
-    role_uuid: Mapped[bytes] = mapped_column(
-        LargeBinary(16), ForeignKey("roles.uuid", ondelete="CASCADE"), nullable=False
-    )
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(UTC)
-    )
-    last_seen: Mapped[datetime | None] = mapped_column(
-        DateTime(timezone=True), nullable=True
-    )
-    visits: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
-
-    def as_dataclass(self) -> "_LegacyUser":
-        return _LegacyUser(
-            uuid=UUID(bytes=self.uuid),
-            display_name=self.display_name,
-            role_uuid=UUID(bytes=self.role_uuid),
-            created_at=_normalize_dt(self.created_at) or self.created_at,
-            last_seen=_normalize_dt(self.last_seen) or self.last_seen,
-            visits=self.visits,
-        )
-
-    @staticmethod
-    def from_dataclass(user: "_LegacyUser"):
-        return UserModel(
-            uuid=user.uuid.bytes,
-            display_name=user.display_name,
-            role_uuid=user.role_uuid.bytes,
-            created_at=user.created_at or datetime.now(UTC),
-            last_seen=user.last_seen,
-            visits=user.visits,
-        )
-
-
-class CredentialModel(Base):
-    __tablename__ = "credentials"
-
-    uuid: Mapped[bytes] = mapped_column(LargeBinary(16), primary_key=True)
-    credential_id: Mapped[bytes] = mapped_column(
-        LargeBinary(64), unique=True, index=True
-    )
-    user_uuid: Mapped[bytes] = mapped_column(
-        LargeBinary(16), ForeignKey("users.uuid", ondelete="CASCADE")
-    )
-    aaguid: Mapped[bytes] = mapped_column(LargeBinary(16), nullable=False)
-    public_key: Mapped[bytes] = mapped_column(BLOB, nullable=False)
-    sign_count: Mapped[int] = mapped_column(Integer, nullable=False)
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(UTC)
-    )
-    last_used: Mapped[datetime | None] = mapped_column(
-        DateTime(timezone=True), nullable=True
-    )
-    last_verified: Mapped[datetime | None] = mapped_column(
-        DateTime(timezone=True), nullable=True
-    )
-
-    def as_dataclass(self):
-        return _LegacyCredential(
-            uuid=UUID(bytes=self.uuid),
-            credential_id=self.credential_id,
-            user_uuid=UUID(bytes=self.user_uuid),
-            aaguid=UUID(bytes=self.aaguid),
-            public_key=self.public_key,
-            sign_count=self.sign_count,
-            created_at=_normalize_dt(self.created_at) or self.created_at,
-            last_used=_normalize_dt(self.last_used) or self.last_used,
-            last_verified=_normalize_dt(self.last_verified) or self.last_verified,
-        )
-
-
-class SessionModel(Base):
-    __tablename__ = "sessions"
-
-    key: Mapped[bytes] = mapped_column(LargeBinary(16), primary_key=True)
-    user_uuid: Mapped[bytes] = mapped_column(
-        LargeBinary(16), ForeignKey("users.uuid", ondelete="CASCADE"), nullable=False
-    )
-    credential_uuid: Mapped[bytes] = mapped_column(
-        LargeBinary(16),
-        ForeignKey("credentials.uuid", ondelete="CASCADE"),
-        nullable=False,
-    )
-    host: Mapped[str] = mapped_column(String, nullable=False)
-    ip: Mapped[str] = mapped_column(String(64), nullable=False)
-    user_agent: Mapped[str] = mapped_column(String(512), nullable=False)
-    renewed: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True),
-        default=lambda: datetime.now(UTC),
-        nullable=False,
-    )
-
-    def as_dataclass(self):
-        return _LegacySession(
-            key=self.key,
-            user_uuid=UUID(bytes=self.user_uuid),
-            credential_uuid=UUID(bytes=self.credential_uuid),
-            host=self.host,
-            ip=self.ip,
-            user_agent=self.user_agent,
-            renewed=_normalize_dt(self.renewed) or self.renewed,
-        )
-
-    @staticmethod
-    def from_dataclass(session: _LegacySession):
-        return SessionModel(
-            key=session.key,
-            user_uuid=session.user_uuid.bytes,
-            credential_uuid=session.credential_uuid.bytes,
-            host=session.host,
-            ip=session.ip,
-            user_agent=session.user_agent,
-            renewed=session.renewed,
-        )
-
-
-class ResetTokenModel(Base):
-    __tablename__ = "reset_tokens"
-
-    key: Mapped[bytes] = mapped_column(LargeBinary(16), primary_key=True)
-    user_uuid: Mapped[bytes] = mapped_column(
-        LargeBinary(16), ForeignKey("users.uuid", ondelete="CASCADE"), nullable=False
-    )
-    token_type: Mapped[str] = mapped_column(String, nullable=False)
-    expiry: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
-
-    def as_dataclass(self) -> _LegacyResetToken:
-        return _LegacyResetToken(
-            key=self.key,
-            user_uuid=UUID(bytes=self.user_uuid),
-            token_type=self.token_type,
-            expiry=_normalize_dt(self.expiry) or self.expiry,
-        )
-
-
-class PermissionModel(Base):
-    __tablename__ = "permissions"
-
-    id: Mapped[str] = mapped_column(String(64), primary_key=True)
-    display_name: Mapped[str] = mapped_column(String, nullable=False)
-
-    def as_dataclass(self):
-        return SqlPermission(self.id, self.display_name)
-
-    @staticmethod
-    def from_dataclass(permission: SqlPermission):
-        return PermissionModel(
-            id=permission.id,
-            display_name=permission.display_name,
-        )
-
-
-class OrgPermission(Base):
-    """Permissions each organization is allowed to grant to its roles."""
-
-    __tablename__ = "org_permissions"
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True)
-    org_uuid: Mapped[bytes] = mapped_column(
-        LargeBinary(16), ForeignKey("orgs.uuid", ondelete="CASCADE")
-    )
-    permission_id: Mapped[str] = mapped_column(
-        String(64), ForeignKey("permissions.id", ondelete="CASCADE")
-    )
-
-
-class RolePermission(Base):
-    """Permissions that each role grants to its members."""
-
-    __tablename__ = "role_permissions"
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True)
-    role_uuid: Mapped[bytes] = mapped_column(
-        LargeBinary(16), ForeignKey("roles.uuid", ondelete="CASCADE")
-    )
-    permission_id: Mapped[str] = mapped_column(
-        String(64), ForeignKey("permissions.id", ondelete="CASCADE")
-    )
-
-
-class DB:
-    """Legacy SQL database class for migration purposes only."""
-
-    def __init__(self, db_path: str = DB_PATH_DEFAULT):
-        """Initialize with database path."""
-        self.engine = create_async_engine(db_path, echo=False)
-        # Ensure SQLite foreign key enforcement is ON for every new connection
-        if db_path.startswith("sqlite"):
-
-            @event.listens_for(self.engine.sync_engine, "connect")
-            def _fk_on(dbapi_connection, connection_record):
-                try:
-                    cursor = dbapi_connection.cursor()
-                    cursor.execute("PRAGMA foreign_keys=ON;")
-                    cursor.close()
-                except Exception:
-                    pass
-
-        self.async_session_factory = async_sessionmaker(
-            self.engine, expire_on_commit=False
-        )
-
-    @asynccontextmanager
-    async def session(self):
-        """Async context manager that provides a database session with transaction."""
-        async with self.async_session_factory() as session:
-            async with session.begin():
-                yield session
-                await session.flush()
-            await session.commit()
-
-    async def init_db(self) -> None:
-        """Initialize database tables."""
-        async with self.engine.begin() as conn:
-            await conn.run_sync(Base.metadata.create_all)
-
-    async def list_permissions(self) -> list[SqlPermission]:
-        async with self.session() as session:
-            result = await session.execute(select(PermissionModel))
-            return [p.as_dataclass() for p in result.scalars().all()]
-
-    async def list_organizations(self) -> list[_LegacyOrg]:
-        async with self.session() as session:
-            # Load all orgs
-            orgs_result = await session.execute(select(OrgModel))
-            org_models = orgs_result.scalars().all()
-            if not org_models:
-                return []
-
-            # Preload org permissions mapping
-            org_perms_result = await session.execute(select(OrgPermission))
-            org_perms = org_perms_result.scalars().all()
-            perms_by_org: dict[bytes, list[str]] = {}
-            for op in org_perms:
-                perms_by_org.setdefault(op.org_uuid, []).append(op.permission_id)
-
-            # Preload roles
-            roles_result = await session.execute(select(RoleModel))
-            role_models = roles_result.scalars().all()
-
-            # Preload role permissions mapping
-            rp_result = await session.execute(select(RolePermission))
-            rps = rp_result.scalars().all()
-            perms_by_role: dict[bytes, list[str]] = {}
-            for rp in rps:
-                perms_by_role.setdefault(rp.role_uuid, []).append(rp.permission_id)
-
-            # Build org dataclasses with roles and permission IDs
-            roles_by_org: dict[bytes, list[_LegacyRole]] = {}
-            for rm in role_models:
-                r_dc = rm.as_dataclass()
-                r_dc.permissions = perms_by_role.get(rm.uuid, [])
-                roles_by_org.setdefault(rm.org_uuid, []).append(r_dc)
-
-            orgs: list[_LegacyOrg] = []
-            for om in org_models:
-                o_dc = om.as_dataclass()
-                o_dc.permissions = perms_by_org.get(om.uuid, [])
-                o_dc.roles = roles_by_org.get(om.uuid, [])
-                orgs.append(o_dc)
-
-            return orgs

paskia/sansio.py

@@ -8,6 +8,7 @@ This module provides a unified interface for WebAuthn operations including:
 """
 
 import json
+import re
 from urllib.parse import urlparse
 from uuid import UUID
 
@@ -62,6 +63,7 @@ class Passkey:
             ValueError: If any origin domain doesn't match or isn't a subdomain of rp_id.
         """
         self.rp_id = rp_id
+        self._validate_rp_id(rp_id)
         self.rp_name = rp_name or rp_id
         self.allowed_origins: set[str] | None = None
         if origins:
@@ -75,6 +77,21 @@ class Passkey:
             COSEAlgorithmIdentifier.RSASSA_PKCS1_v1_5_SHA_256,
         ]
 
+    def _validate_rp_id(self, rp_id: str) -> None:
+        """Validate that rp_id is a valid domain name."""
+        if not rp_id:
+            raise ValueError("rp_id cannot be empty")
+        # Allow localhost, or domain-like strings
+        if rp_id == "localhost":
+            return
+        # Regex for valid domain: letters, digits, hyphens, dots, but not starting/ending with hyphen, etc.
+        # Simplified: alphanumeric, dots, hyphens
+        if not re.match(
+            r"^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$",
+            rp_id,
+        ):
+            raise ValueError(f"rp_id '{rp_id}' is not a valid domain name")
+
     def _validate_origin(self, origin: str, rp_id: str) -> None:
         """Validate an origin URL against the rp_id."""
         hostname = urlparse(origin).hostname

paskia/util/hostutil.py

@@ -56,7 +56,7 @@ def reload_config() -> None:
 
 
 def normalize_host(raw_host: str | None) -> str | None:
-    """Normalize a Host header preserving port (exact match required)."""
+    """Normalize a Host header, stripping port numbers for consistent matching."""
     if not raw_host:
         return None
     candidate = raw_host.strip()
@@ -65,11 +65,12 @@ def normalize_host(raw_host: str | None) -> str | None:
     # urlsplit to parse (add // for scheme-less); prefer netloc to retain port.
     parsed = urlsplit(candidate if "//" in candidate else f"//{candidate}")
     netloc = parsed.netloc or parsed.path or ""
-    # Strip IPv6 brackets around host part but retain port suffix.
+    # Handle IPv6 addresses: [ipv6]:port or [ipv6]
     if netloc.startswith("["):
-        # format: [ipv6]:port or [ipv6]
         if "]" in netloc:
-            host_part, _, rest = netloc.partition("]")
-            port_part = rest.lstrip(":")
-            netloc = host_part.strip("[]") + (f":{port_part}" if port_part else "")
+            host_part, _, _ = netloc.partition("]")
+            netloc = host_part.strip("[]")
+    else:
+        # Strip port from host:port
+        netloc = netloc.rsplit(":", 1)[0]
     return netloc.lower() or None

paskia/util/startupbox.py

@@ -1,6 +1,7 @@
 """Startup configuration box formatting utilities."""
 
 import os
+import re
 from sys import stderr
 from typing import TYPE_CHECKING
 
@@ -11,12 +12,26 @@ if TYPE_CHECKING:
 
 BOX_WIDTH = 60  # Inner width (excluding box chars)
 
+# ANSI color codes
+RESET = "\033[0m"
+YELLOW = "\033[33m"  # Dark yellow
+BRIGHT_YELLOW = "\033[93m"  # Bright yellow
+BRIGHT_WHITE = "\033[1;37m"  # Bold bright white
+
+
+def _visible_len(text: str) -> int:
+    """Calculate visible length of text, ignoring ANSI escape codes."""
+    return len(re.sub(r"\033\[[0-9;]*m", "", text))
+
 
 def line(text: str = "") -> str:
     """Format a line inside the box with proper padding, truncating if needed."""
-    if len(text) > BOX_WIDTH:
+    visible = _visible_len(text)
+    if visible > BOX_WIDTH:
         text = text[: BOX_WIDTH - 1] + "…"
-    return f"┃ {text:<{BOX_WIDTH}} ┃\n"
+        visible = BOX_WIDTH
+    padding = BOX_WIDTH - visible
+    return f"┃ {text}{' ' * padding} ┃\n"
 
 
 def top() -> str:
@@ -29,12 +44,25 @@ def bottom() -> str:
 
 def print_startup_config(config: "PaskiaConfig") -> None:
     """Print server configuration on startup."""
+    # Key graphic with yellow shading (bright for highlights, dark for body)
+    y = YELLOW  # Dark yellow for main body
+    b = BRIGHT_YELLOW  # Bright yellow for highlights/edges
+    w = BRIGHT_WHITE  # Bold white for URL
+    r = RESET
+
     lines = [top()]
-    lines.append(line(" ▄▄▄▄▄"))
-    lines.append(line("█     █ Paskia " + __version__))
-    lines.append(line("█     █▄▄▄▄▄▄▄▄▄▄▄▄"))
-    lines.append(line("█     █▀▀▀▀█▀▀█▀▀█    " + config.site_url + config.site_path))
-    lines.append(line(" ▀▀▀▀▀"))
+    lines.append(line(f" {b}▄▄▄▄▄{r}"))
+    lines.append(line(f"{b}█{y}     {b}█{r} Paskia " + __version__))
+    lines.append(line(f"{b}█{y}     {b}█{y}▄▄▄▄▄▄▄▄▄▄▄▄{r}"))
+    lines.append(
+        line(
+            f"{b}█{y}     {b}█{y}▀▀▀▀{b}█{y}▀▀{b}█{y}▀▀{b}█{r}    {w}"
+            + config.site_url
+            + config.site_path
+            + r
+        )
+    )
+    lines.append(line(f" {y}▀▀▀▀▀{r}"))
 
     # Format auth host section
     if config.auth_host:

paskia/util/useragent.py

@@ -1,10 +1,29 @@
-import user_agents
+from ua_parser import parse
 
 
 def compact_user_agent(ua: str | None) -> str:
-    if not ua:
-        return "-"
-    u = user_agents.parse(ua)
-    ver = u.browser.version_string.split(".")[0]
-    dev = u.device.family if u.device.family not in ["Other", "Mac"] else ""
-    return f"{u.browser.family}/{ver} {u.os.family} {dev}".strip()
+    """Format user agent string into a compact display format.
+
+    Returns empty string for empty/missing user agents.
+    Returns original UA for unrecognized ones.
+    """
+    if not ua or not ua.strip() or ua == "-":
+        return ""
+    r = parse(ua)
+    browser = r.user_agent.family if r.user_agent else None
+    ver = r.user_agent.major if r.user_agent else ""
+    os_name = r.os.family if r.os else None
+    dev = r.device.family if r.device else None
+    # If browser is unrecognized, return original UA
+    if browser in (None, "Other") and os_name in (None, "Other"):
+        return ua
+    # Filter out "Other" values
+    browser = browser if browser and browser != "Other" else ""
+    os_name = os_name if os_name and os_name != "Other" else ""
+    # Exclude device if it's "Other" or matches browser family (parser bug)
+    if dev in (None, "Other") or dev == browser:
+        dev = ""
+    # Build compact string, filtering empty parts
+    parts = [f"{browser}/{ver}" if browser else "", os_name, dev]
+    result = " ".join(p for p in parts if p).strip()
+    return result

paskia/util/userinfo.py

@@ -9,12 +9,15 @@ from paskia.util.apistructs import ApiSession
 
 def build_session_context(ctx: SessionContext) -> dict:
     """Build session context dict from SessionContext."""
-    return {
+    result = {
         "user": {"uuid": ctx.user.uuid, "display_name": ctx.user.display_name},
         "org": {"uuid": ctx.org.uuid, "display_name": ctx.org.display_name},
         "role": {"uuid": ctx.role.uuid, "display_name": ctx.role.display_name},
         "permissions": [p.scope for p in ctx.permissions],
     }
+    if ctx.user.theme:
+        result["user"]["theme"] = ctx.user.theme
+    return result
 
 
 async def build_user_info(

pyproject.toml

@@ -18,11 +18,11 @@ dependencies = [
     "base64url>=1.0.0",
     "uuid7-standard>=1.0.0",
     "pyjwt>=2.8.0",
-    "user-agents>=2.2.0",
     "jsondiff>=2.2.1",
     "msgspec>=0.20.0",
     "aiofiles>=25.1.0",
     "fastapi-vue>=0.3.0",
+    "ua-parser[regex]>=1.0.1",
 ]
 requires-python = ">=3.11"
 
@@ -44,10 +44,6 @@ dev = [
     "pytest-asyncio>=0.24.0",
     "httpx>=0.27.0",
 ]
-migrate = [
-    "sqlalchemy[asyncio]>=2.0.0",
-    "aiosqlite>=0.19.0",
-]
 
 [tool.coverage.run]
 source = ["paskia"]
@@ -91,7 +87,6 @@ dev = [
 
 [project.scripts]
 paskia = "paskia.fastapi.__main__:main"
-paskia-migrate = "paskia.migrate:main"
 
 [tool.hatch.build]
 artifacts = ["paskia/frontend-build"]

scripts/build-frontend.py

@@ -1,20 +1,12 @@
 """Hatch build hook for building paskia-js and Vue frontend during package build."""
 
-import subprocess
+import sys
 from pathlib import Path
-from sys import stderr
 
 from hatchling.builders.hooks.plugin.interface import BuildHookInterface  # type: ignore
 
-# Import utilities from fastapi-vue
-exec(Path(__file__).parent.joinpath("fastapi-vue", "util.py").read_text("UTF-8"))  # noqa: S102
-
-
-def run(cmd, **kwargs):
-    """Run a command and display it."""
-    display_cmd = [Path(cmd[0]).name, *cmd[1:]]
-    stderr.write(f"### {' '.join(display_cmd)}\n")
-    subprocess.run(cmd, check=True, **kwargs)
+sys.path.insert(0, str(Path(__file__).parent / "fastapi-vue"))
+from buildutil import build  # noqa: E402
 
 
 class CustomBuildHook(BuildHookInterface):
@@ -22,27 +14,5 @@ class CustomBuildHook(BuildHookInterface):
 
     def initialize(self, version, build_data):
         super().initialize(version, build_data)
-        stderr.write(">>> Building paskia-js library\n")
-
-        install_cmd, build_cmd = find_build_tool()  # noqa: F821 # type: ignore
-
-        try:
-            # Install dependencies for paskia-js
-            run(install_cmd, cwd="paskia-js")
-            stderr.write("\n")
-            # Build paskia-js
-            run(build_cmd, cwd="paskia-js")
-            stderr.write("\n")
-        except Exception as e:
-            stderr.write(f"Error occurred while building paskia-js: {e}\n")
-            raise
-
-        stderr.write(">>> Building the frontend\n")
-
-        try:
-            run(install_cmd, cwd="frontend")
-            stderr.write("\n")
-            run(build_cmd, cwd="frontend")
-        except Exception as e:
-            stderr.write(f"Error occurred while building frontend: {e}\n")
-            raise
+        build("paskia-js")
+        build("frontend")

scripts/devserver.new.py

@@ -1,277 +0,0 @@
-#!/usr/bin/env -S uv run
-# auto-upgrade@fastapi-vue-setup - remove this if you modify this file
-"""Run Vite development server for frontend and FastAPI backend with auto-reload.
-
-Usage:
-    uv run scripts/devserver.py [host:port] [--backend host:port]
-
-The optional host:port argument sets where the Vite frontend listens.
-Supported forms: host[:port], :port (all interfaces), or just port.
-The --backend option sets where the FastAPI backend listens (default: localhost:5180).
-
-Environment:
-    JS_RUNTIME          Path or name of JS runtime to use (deno, npm/node or bun).
-    FASTAPI_VUE_FRONTEND_URL    Set by this script for the backend to know where Vite is.
-"""
-
-import argparse
-import asyncio
-import contextlib
-import os
-from pathlib import Path
-from sys import stderr
-
-import httpx
-from fastapi_vue.hostutil import parse_endpoint
-
-exec((Path(__file__).parent / "fastapi-vue/util.py").read_text("UTF-8"))  # noqa: S102
-
-DEFAULT_VITE_PORT = 5173
-DEFAULT_BACKEND_PORT = 5180
-FRONTEND_PATH = Path(__file__).parent.parent / "frontend"
-
-EPILOG = """
-  scripts/devserver.py                       # Default ports on localhost
-  scripts/devserver.py 3000                  # Vite on localhost:3000
-  scripts/devserver.py :3000 --backend 8000  # *:3000, localhost:8000
-"""
-
-BUN_BUG = """\
-┃ ⚠️  Bun cannot correctly proxy API requests to the backend.
-┃ Bug report: https://github.com/oven-sh/bun/issues/9882
-┃
-┃ Consider using deno or npm instead for development.
-"""
-
-
-def resolve_frontend_tools(
-    vite_port: int, all_ifaces: bool
-) -> tuple[list[str], list[str], str]:
-    """Resolve frontend install and dev commands.
-
-    Returns (install_cmd, dev_cmd, tool_name).
-    Raises SystemExit if tools are not available.
-    """
-    if not (FRONTEND_PATH / "package.json").exists():
-        stderr.write(f"┃ ⚠️  Frontend source not found at {FRONTEND_PATH}\n")
-        raise SystemExit(1)
-
-    result = find_js_runtime()  # noqa # type: ignore
-    if result is None:
-        if not os.environ.get("JS_RUNTIME"):
-            stderr.write("┃ ⚠️  deno, npm or bun needed to run the frontend server.\n")
-        raise SystemExit(1)
-
-    tool, name = result
-
-    install_args = {
-        "deno": ("install", "--quiet", "--allow-scripts=npm:vue-demi"),
-        "npm": ("install", "--silent"),
-        "bun": ("install", "--silent"),
-    }
-    dev_args = {
-        "deno": ("run", "dev", "--"),
-        "npm": ("--silent", "run", "dev", "--"),
-        "bun": ("run", "dev", "--"),
-    }
-
-    install_cmd = [tool, *install_args[name]]
-    dev_cmd = [
-        tool,
-        *dev_args[name],
-        "--clearScreen=false",
-        f"--port={vite_port}",
-    ]
-
-    if all_ifaces:
-        dev_cmd.append("--host")
-
-    if name == "bun":
-        stderr.write(BUN_BUG)
-
-    return install_cmd, dev_cmd, name
-
-
-async def wait_for_backend(host: str, port: int):
-    """Wait for the backend to be ready by polling the health endpoint."""
-    max_attempts = 50
-    url = f"http://{host}:{port}"
-
-    async with httpx.AsyncClient() as client:
-        for attempt in range(max_attempts):
-            try:
-                await client.get(url, timeout=1.0)
-                stderr.write("✓ Backend ready!\n")
-                return True
-            except httpx.RequestError:
-                if attempt == max_attempts - 1:
-                    stderr.write("┃ ⚠️  Backend didn't start in time\n")
-                    return False
-                await asyncio.sleep(0.1)
-    return False
-
-
-async def _terminate_process(proc: asyncio.subprocess.Process, name: str) -> None:
-    """Gracefully terminate a subprocess."""
-    if proc.returncode is not None:
-        return
-    try:
-        proc.terminate()
-    except ProcessLookupError:
-        return
-    try:
-        await asyncio.wait_for(proc.wait(), timeout=2)
-    except TimeoutError:
-        try:
-            proc.kill()
-        except ProcessLookupError:
-            return
-        await proc.wait()
-
-
-async def run_devserver(
-    vite_port: int,
-    all_ifaces: bool,
-    backend_host: str,
-    backend_port: int,
-) -> None:
-    """Run the development server with install, backend, and frontend."""
-    install_cmd, dev_cmd, tool_name = resolve_frontend_tools(vite_port, all_ifaces)
-
-    # Tell the backend where the Vite dev server is
-    os.environ["FASTAPI_VUE_FRONTEND_URL"] = f"http://localhost:{vite_port}"
-    # Tell Vite where the backend is (for proxying /api requests)
-    os.environ["FASTAPI_VUE_BACKEND_URL"] = f"http://{backend_host}:{backend_port}"
-
-    backend_cmd = [
-        "uvicorn",
-        "paskia.app:app",
-        "--host",
-        backend_host,
-        "--port",
-        str(backend_port),
-        "--reload",
-    ]
-
-    cwd = str(Path(__file__).parent.parent)
-    frontend_cwd = str(FRONTEND_PATH)
-
-    backend_proc: asyncio.subprocess.Process | None = None
-    install_proc: asyncio.subprocess.Process | None = None
-    frontend_proc: asyncio.subprocess.Process | None = None
-
-    try:
-        # Start install (concurrent with backend)
-        stderr.write(f">>> {tool_name} {' '.join(install_cmd[1:])}\n")
-        install_proc = await asyncio.create_subprocess_exec(
-            *install_cmd, cwd=frontend_cwd
-        )
-
-        await asyncio.sleep(0.1)
-
-        # Start backend (concurrent with install)
-        stderr.write(f">>> {' '.join(backend_cmd)}\n")
-        backend_proc = await asyncio.create_subprocess_exec(*backend_cmd, cwd=cwd)
-
-        # Wait for install to complete and backend to be ready
-        install_task = asyncio.create_task(install_proc.wait(), name="install")
-        backend_ready_task = asyncio.create_task(
-            wait_for_backend(backend_host, backend_port), name="backend_ready"
-        )
-
-        done, pending = await asyncio.wait(
-            {install_task, backend_ready_task},
-            return_when=asyncio.FIRST_COMPLETED,
-        )
-
-        for task in done:
-            if task.get_name() == "install":
-                if task.result() != 0:
-                    stderr.write("┃ ⚠️  Install failed\n")
-                    raise SystemExit(1)
-            elif task.get_name() == "backend_ready" and not task.result():
-                raise SystemExit(1)
-
-        if pending:
-            done2, _ = await asyncio.wait(pending)
-            for task in done2:
-                if task.get_name() == "install":
-                    if task.result() != 0:
-                        stderr.write("┃ ⚠️  Install failed\n")
-                        raise SystemExit(1)
-                elif task.get_name() == "backend_ready" and not task.result():
-                    raise SystemExit(1)
-
-        install_proc = None
-
-        # Start Vite dev server
-        stderr.write(f">>> {tool_name} {' '.join(dev_cmd[1:])}\n")
-        frontend_proc = await asyncio.create_subprocess_exec(*dev_cmd, cwd=frontend_cwd)
-
-        # Wait for either process to exit
-        done, pending = await asyncio.wait(
-            {
-                asyncio.create_task(backend_proc.wait(), name="backend"),
-                asyncio.create_task(frontend_proc.wait(), name="frontend"),
-            },
-            return_when=asyncio.FIRST_COMPLETED,
-        )
-        for t in done:
-            t.result()
-        for t in pending:
-            t.cancel()
-
-    except asyncio.CancelledError:
-        stderr.write("\n✓ Shutting down...\n")
-    finally:
-        if frontend_proc is not None:
-            await _terminate_process(frontend_proc, "frontend")
-        if install_proc is not None:
-            await _terminate_process(install_proc, "install")
-        if backend_proc is not None:
-            await _terminate_process(backend_proc, "backend")
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Run Vite and FastAPI development servers",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog=EPILOG,
-    )
-    parser.add_argument(
-        "frontend",
-        nargs="?",
-        metavar="host:port",
-        help="Vite frontend endpoint (default: localhost:5173)",
-    )
-    parser.add_argument(
-        "--backend",
-        metavar="host:port",
-        help="FastAPI backend endpoint (default: localhost:5180)",
-    )
-    args = parser.parse_args()
-
-    # parse_endpoint returns list of dicts with host/port or uds keys
-    # Multiple entries means bind all interfaces (IPv4 + IPv6)
-    vite_endpoints = parse_endpoint(args.frontend, DEFAULT_VITE_PORT)
-    backend_endpoints = parse_endpoint(args.backend, DEFAULT_BACKEND_PORT)
-
-    # Vite doesn't support unix sockets
-    if "uds" in vite_endpoints[0]:
-        stderr.write("┃ ⚠️  Unix sockets not supported for frontend\n")
-        raise SystemExit(1)
-    if "uds" in backend_endpoints[0]:
-        stderr.write("┃ ⚠️  Unix sockets not supported for backend\n")
-        raise SystemExit(1)
-
-    vite_port = vite_endpoints[0]["port"]
-    all_ifaces = len(vite_endpoints) > 1
-    backend_host = backend_endpoints[0]["host"]
-    backend_port = backend_endpoints[0]["port"]
-
-    with contextlib.suppress(KeyboardInterrupt):
-        asyncio.run(run_devserver(vite_port, all_ifaces, backend_host, backend_port))
-
-
-if __name__ == "__main__":
-    main()

scripts/devserver.py

@@ -1,21 +1,21 @@
 #!/usr/bin/env -S uv run
-"""Run Vite development server for frontend and FastAPI backend with auto-reload.
+"""Run Vite development server for frontend and Paskia backend with auto-reload.
 
 This script is only available when running from the git repository source,
 not from the installed package. It starts both the Vite frontend dev server
-and the FastAPI backend with auto-reload enabled.
+and the Paskia backend with auto-reload enabled.
 
 Usage:
-    uv run scripts/devserver.py [host:port] [options...]
+    uv run scripts/devserver.py [-l host:port] [options...]
 
-The optional host:port argument sets where the Vite frontend listens.
+The optional -l/--listen argument sets where the Vite frontend listens.
 All other options are forwarded to `paskia`.
 Backend always listens on localhost:4402.
 
 Environment:
-    FASTAPI_VUE_FRONTEND_URL    Set by this script for the backend to know where Vite is.
-    FASTAPI_VUE_BACKEND_URL     Set by this script for Vite to know where to proxy API calls.
-    PASKIA_SITE_URL             User-facing URL for reset links (Caddy HTTPS or Vite HTTP).
+    PASKIA_FRONTEND_URL    Set by this script for the backend to know where Vite is.
+    PASKIA_BACKEND_URL     Set by this script for Vite to know where to proxy API calls.
+    PASKIA_SITE_URL        User-facing URL for reset links (Caddy HTTPS or Vite HTTP).
 
 Options:
     --caddy         Run Caddy as HTTPS proxy on port 443 (requires sudo)
@@ -25,45 +25,30 @@ Options:
 """
 
 import argparse
-import atexit
-import ipaddress
+import asyncio
 import json
 import os
 import shutil
-import signal
-import subprocess
+import sys
+from contextlib import suppress
 from pathlib import Path
-from sys import stderr
-from threading import Thread
 from urllib.parse import urlparse
 
+# Import utilities from scripts/fastapi-vue (not a package, so we adjust sys.path)
+sys.path.insert(0, str(Path(__file__).with_name("fastapi-vue")))
+from devutil import (  # noqa: E402
+    ProcessGroup,
+    check_ports_free,
+    logger,
+    ready,
+    setup_cli,
+    setup_vite,
+)
+
 DEFAULT_VITE_PORT = 4403  # overrides by CLI option
 BACKEND_PORT = 4402  # hardcoded, also in vite.config.ts
 CADDY_PORT = 443  # HTTPS port for Caddy proxy
 CADDY_HTTP_PORT = 80  # HTTP port for ACME challenges
-DEFAULT_HOST = "localhost"
-
-NO_FRONTEND_TOOL = """\
-┃ ⚠️  deno, npm or bunx needed to run the frontend server.
-"""
-
-BUN_BUG = """\
-┃ ⚠️  Bun cannot correctly proxy API requests to the backend.
-┃ Bug report: https://github.com/oven-sh/bun/issues/9882
-┃
-┃ Options:
-┃   - sudo caddy run --config caddy/Caddyfile.dev
-┃   - Install deno or npm instead
-┃
-┃ Caddy will skip the Vite for API calls and serve everything at port 443.
-┃ Otherwise Vite serves at port 8077 and proxies to backend (broken with bun).
-"""
-
-NO_FRONTEND = """\
-┃
-┃ The backend will still try reaching Vite at {vite_url}
-┃ for various frontend assets, so make sure to start it manually.
-"""
 
 CADDYFILE_SITE_BLOCK = """\
 SITE_ADDR {
@@ -79,140 +64,14 @@ SITE_ADDR {
 """
 
 
-def parse_endpoint(
-    value: str | None, default_port: int
-) -> tuple[str | None, int | None, str | None, bool]:
-    """Parse an endpoint for Vite (simplified version for dev.py).
-
-    Returns (host, port, uds_path, all_ifaces).
-    """
-    if not value:
-        return DEFAULT_HOST, default_port, None, False
-
-    # Port only (numeric) -> localhost:port
-    if value.isdigit():
-        return DEFAULT_HOST, int(value), None, False
-
-    # Leading colon :port -> bind all interfaces
-    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)
-    if value.count(":") > 1 and not value.startswith("["):
-        try:
-            ipaddress.IPv6Address(value)
-        except ValueError as e:
-            raise SystemExit(f"Invalid IPv6 address '{value}': {e}")
-        return value, default_port, None, False
-
-    # Use urllib.parse for everything else
-    parsed = urlparse(f"//{value}")
-    host = parsed.hostname or DEFAULT_HOST
-    port = parsed.port or default_port
-
-    return host, port, None, False
-
-
-def run_vite(
-    vite_url: str,
-    vite_host: str | None,
-    vite_port: int,
-    env: dict,
-    auth_host: str | None = None,
-):
-    """Spawn the frontend dev server (deno, npm, or bunx) as a background process."""
-    devpath = Path(__file__).parent.parent / "frontend"
-    if not (devpath / "package.json").exists():
-        stderr.write(
-            f"┃ ⚠️  Frontend source not found at {devpath}\n"
-            + NO_FRONTEND.format(vite_url=vite_url)
-        )
-        return
-
-    options = [
-        ("deno", "run", "dev"),
-        ("npm", "--silent", "run", "dev", "--"),
-        ("bunx", "--bun", "vite"),
-    ]
-    cmd = None
-    tool_name = None
-    for option in options:
-        if tool := shutil.which(option[0]):
-            cmd = [tool, *option[1:]]
-            tool_name = option[0]
-            break
-
-    # Add Vite CLI args for host/port
-    vite_args = ["--port", str(vite_port), "--logLevel", "silent"]
-    if vite_host:
-        vite_args.extend(["--host", vite_host])
-
-    vite_process = None
-
-    def start_vite():
-        nonlocal vite_process
-        if cmd is None:
-            stderr.write(NO_FRONTEND_TOOL + NO_FRONTEND.format(vite_url=vite_url))
-            return
-        assert tool_name is not None
-        try:
-            if tool_name == "bunx":
-                stderr.write(BUN_BUG)
-
-            full_cmd = cmd + vite_args
-            stderr.write(f">>> {' '.join([tool_name, *full_cmd[1:]])}\n")
-            vite_env = env.copy()
-            if auth_host:
-                vite_env["PASKIA_AUTH_HOST"] = auth_host
-            vite_process = subprocess.Popen(
-                full_cmd, cwd=str(devpath), shell=False, env=vite_env
-            )
-        except Exception as e:
-            stderr.write(
-                f"┃ ⚠️  Vite couldn't start: {e}\n"
-                + NO_FRONTEND.format(vite_url=vite_url)
-            )
-
-    def cleanup():
-        if vite_process:
-            vite_process.terminate()
-            vite_process.wait()
-
-    # Start Vite in a separate thread
-    vite_thread = Thread(target=start_vite, daemon=True)
-    vite_thread.start()
-
-    atexit.register(cleanup)
-    signal.signal(signal.SIGTERM, lambda *_: cleanup())
-    signal.signal(signal.SIGINT, lambda *_: cleanup())
-
-
-def run_caddy(origins: list[str], vite_port: int) -> subprocess.Popen | None:
-    """Spawn Caddy as HTTPS reverse proxy for the given origins."""
-    caddy_path = shutil.which("caddy")
-    if not caddy_path:
-        stderr.write("┃ ⚠️  Caddy not found. Install it to use --caddy option.\n")
-        return None
-
-    # Build Caddyfile with a site block for each origin
+def build_caddyfile(origins: list[str], vite_port: int) -> str:
+    """Build a Caddyfile for the given origins."""
     caddyfile_parts = []
     for origin in origins:
         parsed = urlparse(origin)
-        # Extract scheme://host:port from origin URL
         scheme = parsed.scheme or "https"
-        host = parsed.hostname or parsed.path  # handle case without scheme
+        host = parsed.hostname or parsed.path
         port = parsed.port or (CADDY_HTTP_PORT if scheme == "http" else CADDY_PORT)
-        # Use standard ports without explicit port in address (cleaner URLs)
         if port in (80, 443):
             site_addr = f"{scheme}://{host}"
         else:
@@ -223,162 +82,150 @@ def run_caddy(origins: list[str], vite_port: int) -> subprocess.Popen | None:
             .replace("VITE_PORT", str(vite_port))
         )
         caddyfile_parts.append(block)
+    return "\n".join(caddyfile_parts)
 
-    caddyfile = "\n".join(caddyfile_parts)
-    caddy_process = None
 
-    try:
-        # Use sudo to bind to privileged ports (80/443) for ACME certificate fetching
-        cmd = ["sudo", caddy_path, "run", "--config", "-", "--adapter", "caddyfile"]
-        caddy_process = subprocess.Popen(
-            cmd,
-            stdin=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-        )
-        caddy_process.stdin.write(caddyfile.encode())
-        caddy_process.stdin.close()
-    except Exception as e:
-        stderr.write(f"┃ ⚠️  Caddy couldn't start: {e}\n")
-        return None
+async def run_caddy(origins: list[str], vite_port: int) -> asyncio.subprocess.Process:
+    """Start Caddy as HTTPS reverse proxy, wait for ready signal."""
+    caddy_path = shutil.which("caddy")
+    if not caddy_path:
+        logger.warning("Caddy not found. Install it to use --caddy option.")
+        raise SystemExit(1)
 
-    # Helper to parse Caddy log line (JSON or plain text) into (level, logger, msg)
-    def parse_caddy_log(line: str) -> tuple[str, str, str] | None:
-        """Parse a Caddy log line, return (level, logger, msg) or None if unparseable."""
-        line = line.rstrip("\n")
-        if not line:
-            return None
+    caddyfile = build_caddyfile(origins, vite_port)
+    cmd = ["sudo", caddy_path, "run", "--config", "-", "--adapter", "caddyfile"]
 
-        # Try JSON format first
-        try:
-            log = json.loads(line)
-            return (
-                log.get("level", ""),
-                log.get("logger", ""),
-                log.get("msg", ""),
-            )
-        except json.JSONDecodeError:
-            pass
+    logger.info(">>> sudo caddy @ %s", " ".join(origins))
+    proc = await asyncio.create_subprocess_exec(
+        *cmd,
+        stdin=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    proc.stdin.write(caddyfile.encode())
+    await proc.stdin.drain()
+    proc.stdin.close()
 
-        # Plain text format: "2025/12/06 22:59:41.390 INFO    logger    msg..."
-        # or "2025/12/06 22:59:41.390 INFO    msg..." (no logger)
-        parts = line.split("\t")
-        if len(parts) >= 2:
-            # First part is "timestamp LEVEL", rest are logger and/or message
-            first = parts[0].rsplit(None, 1)  # split off the level from timestamp
-            if len(first) == 2:
-                level = first[1].lower()
-                if len(parts) == 2:
-                    return (level, "", parts[1])
-                else:
-                    return (level, parts[1], "\t".join(parts[2:]))
-
-        # Unparseable - return as-is with no level/logger
-        return ("", "", line)
-
-    def strip_caddy_verbose(msg: str) -> str:
-        """Remove verbose prefixes from Caddy error messages."""
-        return msg.replace("loading initial config: loading new config: ", "")
-
-    def format_caddy_log(level: str, logger: str, msg: str) -> str:
-        """Format a parsed Caddy log for display."""
-        msg = strip_caddy_verbose(msg)
-        if logger:
-            return f"┃ [{level.upper()}] {logger}: {msg}\n"
-        else:
-            return f"┃ [{level.upper()}] {msg}\n"
-
-    # Read stderr line by line until Caddy signals it's ready or exits
-    # Caddy outputs logs; "serving initial configuration" means it's ready
+    # Wait for ready signal or failure
     while True:
-        exit_code = caddy_process.poll()
-        if exit_code is not None:
-            # Process exited - read remaining stderr and report failure
-            remaining = (
-                caddy_process.stderr.read().decode() if caddy_process.stderr else ""
-            )
-            if remaining:
-                for line in remaining.splitlines():
-                    if line:
-                        parsed = parse_caddy_log(line)
-                        if parsed:
-                            level, logger, msg = parsed
-                            if level:
-                                stderr.write(format_caddy_log(level, logger, msg))
-                            else:
-                                stderr.write(f"┃ {strip_caddy_verbose(msg)}\n")
-                        else:
-                            stderr.write(f"┃ {strip_caddy_verbose(line)}\n")
-            stderr.write(f"┃ ⚠️  Caddy startup failed (exit code {exit_code})\n")
-            return None
+        if proc.returncode is not None:
+            remaining = await proc.stderr.read()
+            for line in remaining.decode().splitlines():
+                if line:
+                    logger.info("caddy: %s", line)
+            logger.warning("Caddy startup failed (exit code %d)", proc.returncode)
+            raise SystemExit(1)
 
-        # Read one line from stderr (blocks until data available)
-        line = caddy_process.stderr.readline().decode()
+        line = await proc.stderr.readline()
         if not line:
             continue
 
-        # Check for ready signal
-        if "serving initial configuration" in line:
+        decoded = line.decode().rstrip()
+        if "serving initial configuration" in decoded:
             break
 
-        parsed = parse_caddy_log(line)
-        if not parsed:
-            continue
+        # Parse and show errors during startup
+        if decoded:
+            try:
+                log = json.loads(decoded)
+                level = log.get("level", "")
+                if level in ("error", "fatal", "warn"):
+                    logger.warning("caddy: %s", log.get("msg", decoded))
+            except json.JSONDecodeError:
+                if "error" in decoded.lower() or "fatal" in decoded.lower():
+                    logger.warning("caddy: %s", decoded)
 
-        level, logger, msg = parsed
-
-        # Filter out info-level and admin messages
-        if level == "info" or logger == "admin":
-            continue
-
-        # Show errors/fatal to user
-        if level in ("error", "fatal"):
-            stderr.write(format_caddy_log(level, logger, msg))
-        elif not level:
-            # Unparseable non-empty line (e.g., sudo prompt) - pass through with prefix
-            stderr.write(f"┃ {strip_caddy_verbose(msg)}\n")
-            stderr.flush()
-
-    # Start a background thread to drain stderr and show errors
-    def drain_stderr():
+    # Start background task to drain stderr
+    async def drain_caddy_stderr():
         while True:
-            line = caddy_process.stderr.readline().decode()
+            line = await proc.stderr.readline()
             if not line:
                 break
+            decoded = line.decode().rstrip()
+            if decoded:
+                try:
+                    log = json.loads(decoded)
+                    level = log.get("level", "")
+                    if level in ("error", "fatal", "warn"):
+                        logger.warning("caddy: %s", log.get("msg", decoded))
+                except json.JSONDecodeError:
+                    pass  # Ignore non-JSON output after startup
 
-            parsed = parse_caddy_log(line)
-            if not parsed:
-                continue
+    asyncio.create_task(drain_caddy_stderr())
+    return proc
 
-            level, logger, msg = parsed
 
-            # Filter out info-level and admin messages
-            if level == "info" or logger == "admin":
-                continue
+async def run_devserver(args: argparse.Namespace, remaining: list[str]) -> None:
+    """Run the development server with all components."""
+    reporoot = Path(__file__).parent.parent
+    frontend_path = reporoot / "frontend"
+    if not (frontend_path / "package.json").exists():
+        logger.warning("Frontend source not found at %s", frontend_path)
+        raise SystemExit(1)
 
-            # Show errors/warnings to user
-            if level in ("error", "fatal", "warn"):
-                stderr.write(format_caddy_log(level, logger, msg))
-            elif not level:
-                # Unparseable line - pass through with prefix
-                stderr.write(f"┃ {strip_caddy_verbose(msg)}\n")
+    viteurl, npm_install, vite = setup_vite(args.listen, DEFAULT_VITE_PORT)
+    backurl, paskia = setup_cli("paskia", f"localhost:{BACKEND_PORT}", BACKEND_PORT)
 
-    drain_thread = Thread(target=drain_stderr, daemon=True)
-    drain_thread.start()
+    # Extract vite port for Caddy config
+    vite_port = int(viteurl.rsplit(":", 1)[1])
 
-    def cleanup():
-        if caddy_process:
-            caddy_process.terminate()
-            caddy_process.wait()
+    # Build paskia command with options
+    paskia.extend(["--rp-id", args.rp_id])
+    if args.auth_host:
+        paskia.extend(["--auth-host", args.auth_host])
+    if args.origins:
+        for origin in args.origins:
+            paskia.extend(["--origin", origin])
+    paskia.extend(remaining)
 
-    atexit.register(cleanup)
+    # Compute origins for Caddy
+    caddy_origins = []
+    if args.auth_host:
+        auth_host = args.auth_host
+        if "://" not in auth_host:
+            auth_host = f"https://{auth_host}"
+        caddy_origins.append(auth_host)
+        caddy_origins.append(f"https://{args.rp_id}")
+    if args.origins:
+        for origin in args.origins:
+            if "://" not in origin:
+                origin = f"https://{origin}"
+            caddy_origins.append(origin)
+    if not args.auth_host and not args.origins:
+        caddy_origins.append(f"https://{args.rp_id}")
+    # Remove duplicates while preserving order
+    seen = set()
+    caddy_origins = [x for x in caddy_origins if not (x in seen or seen.add(x))]
 
-    return caddy_process
+    # Set environment for subprocesses
+    os.environ["PASKIA_FRONTEND_URL"] = viteurl
+    os.environ["PASKIA_BACKEND_URL"] = backurl
+    os.environ["PASKIA_SITE_URL"] = caddy_origins[0] if args.caddy else viteurl
+    if args.auth_host:
+        os.environ["PASKIA_AUTH_HOST"] = args.auth_host
+
+    async with ProcessGroup() as pg:
+        # Start Caddy first if requested (needs to bind ports)
+        if args.caddy:
+            caddy_proc = await run_caddy(caddy_origins, vite_port)
+            pg._procs.append(caddy_proc)
+            pg._cmds[caddy_proc.pid] = "caddy"
+
+        npm_proc = await pg.spawn(*npm_install, cwd=frontend_path)
+        await check_ports_free(viteurl, backurl)
+        await pg.spawn(*paskia)
+        await pg.wait(npm_proc, ready(backurl, path="/api/health?from=devserver.py"))
+        await pg.spawn(*vite, cwd=frontend_path)
 
 
 def main():
-    # Parse optional hostport argument for Vite frontend
     parser = argparse.ArgumentParser(add_help=False)
-    parser.add_argument("hostport", nargs="?", default=None)
+    parser.add_argument(
+        "-l",
+        "--listen",
+        metavar="ENDPOINT",
+        default=None,
+        help="Vite frontend endpoint (default: localhost:4403)",
+    )
     parser.add_argument("--caddy", action="store_true", help="Run Caddy as HTTPS proxy")
     parser.add_argument("--rp-id", default="localhost", help="Relying Party ID")
     parser.add_argument(
@@ -387,85 +234,8 @@ def main():
     parser.add_argument("--auth-host", help="Dedicated auth host")
     args, remaining = parser.parse_known_args()
 
-    # Parse Vite endpoint
-    vite_host, vite_port, vite_uds, all_ifaces = parse_endpoint(
-        args.hostport, DEFAULT_VITE_PORT
-    )
-
-    if vite_uds:
-        raise SystemExit("┃ ⚠️  Unix sockets are not supported for Vite frontend")
-
-    # Handle all-interfaces case (:port syntax)
-    # Vite uses 0.0.0.0 to listen on all interfaces (IPv4 only, sufficient for dev)
-    if all_ifaces:
-        vite_host = "0.0.0.0"
-
-    # Build Vite URL for FASTAPI_VUE_FRONTEND_URL (always use localhost for URL)
-    vite_url = f"http://localhost:{vite_port}"
-
-    # Compute origins for Caddy (user-specified or auto-generated)
-    caddy_origins = []
-    if args.auth_host:
-        auth_host = args.auth_host
-        if "://" not in auth_host:
-            auth_host = f"https://{auth_host}"
-        caddy_origins.append(auth_host)
-        # Also run on rp-id when auth-host is specified
-        caddy_origins.append(f"https://{args.rp_id}")
-    if args.origins:
-        for origin in args.origins:
-            if "://" not in origin:
-                origin = f"https://{origin}"
-            caddy_origins.append(origin)
-    # If neither auth-host nor origins specified, run on rp-id
-    if not args.auth_host and not args.origins:
-        caddy_origins.append(f"https://{args.rp_id}")
-
-    # Remove duplicates while preserving order
-    seen = set()
-    caddy_origins = [x for x in caddy_origins if not (x in seen or seen.add(x))]
-
-    # Start Caddy if requested (after computing origins)
-    if args.caddy:
-        if not caddy_origins:
-            caddy_origins = [f"https://{args.rp_id}"]
-        stderr.write(f">>> sudo caddy @ {' '.join(caddy_origins)}\n")
-        if not run_caddy(caddy_origins, vite_port):
-            raise SystemExit(1)
-
-    # Set dev mode env vars for subprocesses (fastapi-vue convention)
-    env = os.environ.copy()
-    env["FASTAPI_VUE_FRONTEND_URL"] = vite_url
-    env["FASTAPI_VUE_BACKEND_URL"] = f"http://localhost:{BACKEND_PORT}"
-    # User-facing URL: Caddy HTTPS when running, else Vite HTTP
-    if args.caddy:
-        env["PASKIA_SITE_URL"] = caddy_origins[0]  # auth-host or https://{rp-id}
-    else:
-        env["PASKIA_SITE_URL"] = vite_url
-
-    # Start Vite dev server
-    run_vite(vite_url, vite_host, vite_port, env, args.auth_host)
-
-    # Build command with origin args (no serve subcommand, host:port is first arg)
-    cmd = ["paskia", f"localhost:{BACKEND_PORT}"]
-
-    # Pass through rp-id (always pass, has default)
-    cmd.extend(["--rp-id", args.rp_id])
-
-    # Pass through auth-host if specified
-    if args.auth_host:
-        cmd.extend(["--auth-host", args.auth_host])
-
-    # Pass through origins as specified
-    if args.origins:
-        for origin in args.origins:
-            cmd.extend(["--origin", origin])
-
-    # Add remaining args (ones we didn't parse)
-    cmd.extend(remaining)
-
-    stderr.write(f">>> (devmode) {' '.join(cmd)}\n")
-    subprocess.run(cmd, env=env)
+    with suppress(KeyboardInterrupt):
+        asyncio.run(run_devserver(args, remaining))
 
 
 if __name__ == "__main__":

scripts/fastapi-vue/build-frontend.py

@@ -1,34 +1,15 @@
 """Hatch build hook for building Vue frontend during package build."""
 
-import subprocess
+import sys
 from pathlib import Path
-from sys import stderr
 
 from hatchling.builders.hooks.plugin.interface import BuildHookInterface  # type: ignore
 
-exec(Path(__file__).with_name("util.py").read_text("UTF-8"))  # noqa: S102
-
-
-def run(cmd, **kwargs):
-    """Run a command and display it."""
-    display_cmd = [Path(cmd[0]).name, *cmd[1:]]
-    stderr.write(f"### {' '.join(display_cmd)}\n")
-    subprocess.run(cmd, check=True, **kwargs)
+sys.path.insert(0, str(Path(__file__).parent))
+from buildutil import build
 
 
 class CustomBuildHook(BuildHookInterface):
-    """Build hook that compiles Vue frontend before packaging."""
-
     def initialize(self, version, build_data):
         super().initialize(version, build_data)
-        stderr.write(">>> Building the frontend\n")
-
-        install_cmd, build_cmd = find_build_tool()  # noqa # type: ignore
-
-        try:
-            run(install_cmd, cwd="frontend")
-            stderr.write("\n")
-            run(build_cmd, cwd="frontend")
-        except Exception as e:
-            stderr.write(f"Error occurred while building frontend: {e}\n")
-            raise
+        build("frontend")

scripts/fastapi-vue/buildutil.py

@@ -0,0 +1,191 @@
+"""Utilities used at build time and in devserver script. No dependencies."""
+
+import logging
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+
+class _PrefixFormatter(logging.Formatter):
+    """Formatter that adds prefix based on log level."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        if record.levelno >= logging.WARNING:
+            return f"⚠️  {record.getMessage()}"
+        return record.getMessage()
+
+
+_handler = logging.StreamHandler()
+_handler.setFormatter(_PrefixFormatter())
+logger = logging.getLogger("fastapi-vue")
+logger.addHandler(_handler)
+logger.setLevel(logging.INFO)
+
+
+def _check_node_version(node_path: str) -> None:
+    """Check if Node.js version is >= 20.
+
+    Raises RuntimeError if version is too old or cannot be determined.
+    """
+    try:
+        result = subprocess.run(
+            [node_path, "--version"], capture_output=True, text=True, check=True
+        )
+        version_str = result.stdout.strip()
+        # Parse version like "v20.10.0" or "v18.17.1"
+        match = re.match(r"v(\d+)", version_str)
+        if match:
+            major_version = int(match.group(1))
+            if major_version >= 20:
+                return
+            raise RuntimeError(
+                f"Node.js {version_str} found, but v20+ required (install with nvm)"
+            )
+    except (subprocess.CalledProcessError, FileNotFoundError, ValueError):
+        pass
+    raise RuntimeError("Could not determine Node.js version")
+
+
+def find_js_runtime() -> tuple[str, str]:
+    """Find a JavaScript runtime from JS_RUNTIME env or auto-detect.
+
+    Returns (tool_path, tool_name) where tool_name is "deno", "npm", or "bun".
+    Raises JSRuntimeError if no suitable runtime is found.
+    """
+    options = ["npm", "deno", "bun"]
+    node_version_error: RuntimeError | None = None
+
+    # Check for JS_RUNTIME environment variable
+    if js_runtime_env := os.environ.get("JS_RUNTIME"):
+        js_runtime = js_runtime_env
+        js_path = Path(js_runtime)
+        runtime_name = js_path.name
+        # Map node to npm
+        if runtime_name == "node":
+            runtime_name = "npm"
+            js_runtime = str(js_path.parent / "npm") if js_path.parent.name else "npm"
+        for option in options:
+            if option == runtime_name or runtime_name.startswith(option):
+                tool = shutil.which(js_runtime)
+                if tool is None:
+                    raise RuntimeError(
+                        f"JS_RUNTIME={js_runtime_env}: {option} not found"
+                    )
+                # Check Node.js version if using npm
+                if option == "npm":
+                    node_path = shutil.which("node", path=str(Path(tool).parent))
+                    if node_path is None:
+                        raise RuntimeError(
+                            f"JS_RUNTIME={js_runtime_env}: node not found"
+                        )
+                    _check_node_version(node_path)  # Raises on failure
+                return tool, option
+        raise RuntimeError(f"JS_RUNTIME={js_runtime_env} not recognized")
+
+    # Auto-detect
+    for option in options:
+        if tool := shutil.which(option):
+            # Check Node.js version if using npm
+            if option == "npm":
+                node_path = shutil.which("node", path=str(Path(tool).parent))
+                if node_path is None:
+                    continue
+                try:
+                    _check_node_version(node_path)
+                except RuntimeError as e:
+                    node_version_error = e
+                    continue  # Try next runtime
+            return tool, option
+
+    # No runtime found - provide helpful error
+    if node_version_error:
+        raise node_version_error
+    raise RuntimeError("Node.js (v20+), Deno or Bun is required but none was found")
+
+
+def find_build_tool():
+    """Find JavaScript runtime and construct install/build commands.
+
+    Returns (install_cmd, build_cmd) tuples of command lists.
+    Raises RuntimeError if no runtime is found.
+    """
+    install = {
+        "deno": ("install", "--allow-scripts=npm:vue-demi"),
+        "npm": ("install",),
+        "bun": ("--bun", "install"),
+    }
+    # Run vite directly for deno to avoid npm-run-all2/run-p issues
+    build = {
+        "deno": ("run", "-A", "npm:vite", "build"),
+        "npm": ("run", "build"),
+        "bun": ("--bun", "run", "build"),
+    }
+
+    tool, name = find_js_runtime()
+    return [tool, *install[name]], [tool, *build[name]]
+
+
+def find_dev_tool() -> list[str]:
+    """Find JavaScript runtime and construct dev command.
+
+    Returns dev_cmd (without vite-specific args).
+    Raises RuntimeError if no runtime is found.
+    """
+    dev_args = {
+        "deno": ("run", "-A", "npm:vite"),
+        "npm": ("--silent", "run", "dev", "--"),
+        "bun": ("run", "dev", "--"),
+    }
+
+    tool, name = find_js_runtime()
+
+    if name == "bun":
+        logger.warning(
+            "Bun has a bug in WS proxying (https://github.com/oven-sh/bun/issues/9882). Consider using npm instead."
+        )
+
+    return [tool, *dev_args[name]]
+
+
+def find_install_tool() -> list[str]:
+    """Find JavaScript runtime and construct install command.
+
+    Returns install_cmd.
+    Raises RuntimeError if no runtime is found.
+    """
+    install_args = {
+        "deno": ("install", "--quiet", "--allow-scripts=npm:vue-demi"),
+        "npm": ("install", "--silent"),
+        "bun": ("install", "--silent"),
+    }
+
+    tool, name = find_js_runtime()
+    return [tool, *install_args[name]]
+
+
+def build(folder: str = "frontend") -> None:
+    """Build the frontend in the specified folder.
+
+    Raises SystemExit(1) on failure.
+    """
+    logger.info(">>> Building %s", folder)
+
+    try:
+        install_cmd, build_cmd = find_build_tool()
+    except RuntimeError as e:
+        logger.warning(e)
+        raise SystemExit(1)
+
+    def run(cmd):
+        display_cmd = [Path(cmd[0]).stem, *cmd[1:]]
+        logger.info("### %s", " ".join(display_cmd))
+        subprocess.run(cmd, check=True, cwd=folder)
+
+    try:
+        run(install_cmd)
+        logger.info("")
+        run(build_cmd)
+    except subprocess.CalledProcessError:
+        raise SystemExit(1)

scripts/fastapi-vue/devutil.py

@@ -0,0 +1,211 @@
+"""Utilities meant for devserver script, used only in source repository with dev deps."""
+
+import asyncio
+import subprocess
+import sys
+from collections.abc import Coroutine
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+import httpx
+from buildutil import find_dev_tool, find_install_tool, logger
+from fastapi_vue.hostutil import parse_endpoint
+
+
+class ProcessGroup:
+    """Manage async subprocesses with automatic cleanup, like TaskGroup for processes."""
+
+    def __init__(self):
+        self._procs: list[asyncio.subprocess.Process] = []
+        self._cmds: dict[int, str] = {}  # pid -> command name
+
+    async def spawn(
+        self, *cmd: str, cwd: str | None = None
+    ) -> asyncio.subprocess.Process:
+        """Spawn a subprocess and track it."""
+        cmd_name = Path(cmd[0]).stem
+        logger.info(">>> %s", " ".join([cmd_name, *cmd[1:]]))
+        proc = await asyncio.create_subprocess_exec(*cmd, cwd=cwd)
+        self._procs.append(proc)
+        self._cmds[proc.pid] = cmd_name
+        return proc
+
+    async def wait(
+        self, *waitables: "asyncio.subprocess.Process | Coroutine[Any, Any, Any]"
+    ) -> None:
+        """Wait for processes/coroutines to complete, raise SystemExit on failure."""
+
+        async def wait_proc(proc: asyncio.subprocess.Process) -> None:
+            returncode = await proc.wait()
+            if returncode != 0:
+                cmd_name = self._cmds.get(proc.pid, "unknown")
+                raise subprocess.CalledProcessError(returncode, cmd_name)
+
+        tasks = [
+            wait_proc(w) if isinstance(w, asyncio.subprocess.Process) else w
+            for w in waitables
+        ]
+        try:
+            await asyncio.gather(*tasks)
+        except subprocess.CalledProcessError as e:
+            logger.warning("%s failed with exit status %d", e.cmd, e.returncode)
+            raise SystemExit(1) from None
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, *_):
+        """Wait for one process to exit, terminate others, then wait for all."""
+        await self._cleanup(immediate=exc_type is not None)
+
+    async def _cleanup(self, immediate: bool = False):
+        running = [p for p in self._procs if p.returncode is None]
+        if not running:
+            return
+
+        if not immediate:
+            # Wait for any one process to exit
+            with suppress(asyncio.CancelledError):
+                await asyncio.wait(
+                    [asyncio.create_task(p.wait()) for p in running],
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+
+        # Terminate remaining processes
+        for p in self._procs:
+            if p.returncode is None:
+                with suppress(ProcessLookupError):
+                    p.terminate()
+
+        # Wait for all to finish (with overall timeout), shielded from cancellation
+        still_running = [p for p in self._procs if p.returncode is None]
+        if still_running:
+            with suppress(asyncio.CancelledError):
+                try:
+                    await asyncio.shield(
+                        asyncio.wait_for(
+                            asyncio.gather(*[p.wait() for p in still_running]),
+                            timeout=10,
+                        )
+                    )
+                except TimeoutError:
+                    for p in self._procs:
+                        if p.returncode is None:
+                            with suppress(ProcessLookupError):
+                                p.kill()
+                            await p.wait()
+
+
+async def check_ports_free(*urls: str) -> None:
+    """Verify URLs are not responding (ports are free). Raise SystemExit if any respond."""
+
+    async def check(client: httpx.AsyncClient, url: str) -> None:
+        with suppress(httpx.RequestError):
+            res = await client.get(url, timeout=0.1)
+            server = res.headers.get("server", "server")
+            logger.warning("Conflicting %s already running at %s", server, url)
+            raise SystemExit(1)
+
+    async with httpx.AsyncClient() as client:
+        await asyncio.gather(*[check(client, url) for url in urls])
+
+
+async def ready(url: str, path: str = "") -> None:
+    """Wait for the server to be ready by polling an endpoint.
+
+    Raises SystemExit(1) if server doesn't start in time.
+    """
+    max_attempts = 50
+    full_url = f"{url}{path}"
+
+    async with httpx.AsyncClient() as client:
+        for attempt in range(max_attempts):
+            try:
+                await client.get(full_url, timeout=1.0)
+                logger.info("✓ Backend ready!")
+                return
+            except httpx.RequestError:
+                if attempt == max_attempts - 1:
+                    logger.warning("Backend didn't start in time")
+                    raise SystemExit(1)
+                await asyncio.sleep(0.1)
+
+
+def setup_vite(
+    endpoint: str, default_port: int = 5173
+) -> tuple[str, list[str], list[str]]:
+    """Parse frontend endpoint and build commands.
+
+    Returns (url, install_cmd, dev_cmd).
+    Raises SystemExit(1) on invalid config.
+    """
+    endpoints = parse_endpoint(endpoint, default_port)
+
+    if "uds" in endpoints[0]:
+        logger.warning("Unix sockets not supported with vite devserver")
+        raise SystemExit(1)
+
+    port = endpoints[0]["port"]
+    host = endpoints[0]["host"]
+
+    install_cmd = find_install_tool()
+    dev_cmd = find_dev_tool()
+    if host != "localhost":
+        dev_cmd.append("--host" if len(endpoints) > 1 else f"--host={host}")
+    dev_cmd.append(f"--port={port}")
+
+    return f"http://{host}:{port}", install_cmd, dev_cmd
+
+
+def setup_fastapi(
+    endpoint: str, module: str, default_port: int = 8000
+) -> tuple[str, list[str]]:
+    """Parse backend endpoint and build uvicorn command.
+
+    Returns (url, uvicorn_cmd).
+    Raises SystemExit(1) on invalid config.
+    """
+    endpoints = parse_endpoint(endpoint, default_port)
+
+    if "uds" in endpoints[0]:
+        logger.warning("Unix sockets not supported with vite devserver")
+        raise SystemExit(1)
+
+    host = endpoints[0]["host"]
+    port = endpoints[0]["port"]
+    reload_dir = module.split(".")[0]  # Don't reload on frontend changes
+
+    cmd = [
+        sys.executable,
+        "-m",
+        "uvicorn",
+        module,
+        f"--host={host}",
+        f"--port={port}",
+        "--reload",
+        f"--reload-dir={reload_dir}",
+        "--forwarded-allow-ips=*",
+    ]
+    return f"http://{host}:{port}", cmd
+
+
+def setup_cli(
+    cli: str, endpoint: str, default_port: int = 8000
+) -> tuple[str, list[str]]:
+    """Parse backend endpoint and build CLI command.
+
+    Returns (url, cli_cmd).
+    Raises SystemExit(1) on invalid config.
+    """
+    endpoints = parse_endpoint(endpoint, default_port)
+
+    if "uds" in endpoints[0]:
+        logger.warning("Unix sockets not supported with vite devserver")
+        raise SystemExit(1)
+
+    host = endpoints[0]["host"]
+    port = endpoints[0]["port"]
+
+    cmd = [cli, f"--listen={host}:{port}"]
+    return f"http://{host}:{port}", cmd

scripts/fastapi-vue/util.py

@@ -1,87 +0,0 @@
-"""Shared utilities for build and dev scripts."""
-
-import os
-import shutil
-from pathlib import Path
-from sys import stderr
-
-
-def find_js_runtime() -> tuple[str, str] | None:
-    """Find a JavaScript runtime from JS_RUNTIME env or auto-detect.
-
-    Returns (tool_path, tool_name) where tool_name is "deno", "npm", or "bun".
-    Returns None if no runtime is found.
-    """
-    options = ["deno", "npm", "bun"]
-
-    # Check for JS_RUNTIME environment variable
-    if js_runtime_env := os.environ.get("JS_RUNTIME"):
-        js_runtime = js_runtime_env
-        js_path = Path(js_runtime)
-        runtime_name = js_path.name
-        # Map node to npm
-        if runtime_name == "node":
-            runtime_name = "npm"
-            js_runtime = str(js_path.parent / "npm") if js_path.parent.name else "npm"
-        for option in options:
-            if option == runtime_name or runtime_name.startswith(option):
-                tool = shutil.which(js_runtime)
-                if tool is None:
-                    stderr.write(f"┃ ⚠️  JS_RUNTIME={js_runtime_env} not found\n")
-                    return None
-                return tool, option
-        stderr.write(f"┃ ⚠️  JS_RUNTIME={js_runtime_env} not recognized\n")
-        return None
-
-    # Auto-detect
-    for option in options:
-        if tool := shutil.which(option):
-            return tool, option
-    return None
-
-
-def find_build_tool():
-    """Find JavaScript runtime and construct install/build commands.
-
-    Returns (install_cmd, build_cmd) tuples of command lists.
-    Raises RuntimeError if no runtime is found.
-    """
-    install = {
-        "deno": ("install", "--allow-scripts=npm:vue-demi"),
-        "npm": ("install",),
-        "bun": ("--bun", "install"),
-    }
-    # Run vite directly for deno to avoid npm-run-all2/run-p issues
-    build = {
-        "deno": ("run", "-A", "npm:vite", "build"),
-        "npm": ("run", "build"),
-        "bun": ("--bun", "run", "build"),
-    }
-
-    result = find_js_runtime()
-    if result is None:
-        raise RuntimeError(
-            "Deno, npm or Bun is required for building but none was found"
-        )
-
-    tool, name = result
-    return [tool, *install[name]], [tool, *build[name]]
-
-
-def find_dev_tool():
-    """Find JavaScript runtime and construct dev command.
-
-    Returns (dev_cmd, tool_name) or (None, None) if not found.
-    """
-    dev_args = {
-        "deno": ("run", "dev", "--"),
-        "npm": ("--silent", "run", "dev", "--"),
-        "bun": ("run", "dev", "--"),
-    }
-
-    result = find_js_runtime()
-    if result is None:
-        return None, None
-
-    tool, name = result
-    return [tool, *dev_args[name]], name

tests/conftest.py

@@ -21,13 +21,15 @@ import pytest_asyncio
 
 import paskia.db.operations as ops_db
 from paskia import globals as paskia_globals
-from paskia.authsession import expires, reset_expires
+from paskia.authsession import reset_expires
 from paskia.db import (
+    Config,
     Credential,
     Org,
     Permission,
     Role,
     User,
+    bootstrap,
     create_credential,
     create_reset_token,
     create_role,
@@ -39,7 +41,6 @@ from paskia.db.operations import DB
 from paskia.fastapi.mainapp import app
 from paskia.fastapi.session import AUTH_COOKIE_NAME
 from paskia.sansio import Passkey
-from paskia.util.passphrase import generate
 
 
 @pytest.fixture(scope="session")
@@ -61,14 +62,14 @@ async def test_db() -> AsyncGenerator[DB, None]:
     """
 
     with tempfile.NamedTemporaryFile(suffix=".jsonl", delete=True) as f:
-        db = DB()
+        db = DB(config=Config(rp_id="test.example.com"))
         store = JsonlStore(db, f.name)
         db._store = store
         await store.load()
         ops_db._db = db
         ops_db._store = store
         # Bootstrap creates the initial permissions, org, role, and admin user
-        ops_db.bootstrap(
+        bootstrap(
             org_name="Test Organization",
             admin_name="Test Admin",
         )
@@ -181,10 +182,9 @@ async def session_token(
     return create_session(
         user_uuid=test_user.uuid,
         credential_uuid=test_credential.uuid,
-        host="localhost:4401",
+        host="localhost",
         ip="127.0.0.1",
         user_agent="pytest",
-        expiry=expires(),
     )
 
 
@@ -196,25 +196,20 @@ async def regular_session_token(
     return create_session(
         user_uuid=regular_user.uuid,
         credential_uuid=regular_credential.uuid,
-        host="localhost:4401",
+        host="localhost",
         ip="127.0.0.1",
         user_agent="pytest",
-        expiry=expires(),
     )
 
 
 @pytest_asyncio.fixture(scope="function")
 async def reset_token(test_db: DB, test_user: User, test_credential: Credential) -> str:
     """Create a reset token for the test user."""
-
-    token = generate()
-    create_reset_token(
+    return create_reset_token(
         user_uuid=test_user.uuid,
-        passphrase=token,
         expiry=reset_expires(),
         token_type="reset",
     )
-    return token
 
 
 @pytest_asyncio.fixture(scope="function")

tests/test_admin.py

@@ -22,7 +22,6 @@ import pytest_asyncio
 import uuid7
 
 from paskia import db
-from paskia.authsession import expires
 from paskia.db import (
     Credential,
     Org,
@@ -101,10 +100,9 @@ async def second_org_session_token(
     return create_session(
         user_uuid=second_org_user.uuid,
         credential_uuid=second_org_credential.uuid,
-        host="localhost:4401",
+        host="localhost",
         ip="127.0.0.1",
         user_agent="pytest",
-        expiry=expires(),
     )
 
 
@@ -158,10 +156,9 @@ async def org_admin_session_token(
     return create_session(
         user_uuid=org_admin_user.uuid,
         credential_uuid=org_admin_credential.uuid,
-        host="localhost:4401",
+        host="localhost",
         ip="127.0.0.1",
         user_agent="pytest",
-        expiry=expires(),
     )
 
 
@@ -604,7 +601,7 @@ class TestAdminRoles:
     ):
         """Admin should be able to update a role."""
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/roles/{test_role.uuid}",
+            f"/auth/api/admin/roles/{test_role.uuid}",
             json={"display_name": "Updated Role Name"},
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
@@ -614,17 +611,19 @@ class TestAdminRoles:
 
     @pytest.mark.asyncio
     async def test_update_role_wrong_org(
-        self, client: httpx.AsyncClient, session_token: str, test_org, second_org_role
+        self,
+        client: httpx.AsyncClient,
+        org_admin_session_token: str,
+        test_org,
+        second_org_role,
     ):
-        """Cannot update role from another org."""
+        """Org admin cannot update role from another org."""
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/roles/{second_org_role.uuid}",
+            f"/auth/api/admin/roles/{second_org_role.uuid}",
             json={"display_name": "Try Update Wrong Org"},
-            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+            headers={**auth_headers(org_admin_session_token), "Host": "localhost:4401"},
         )
-        assert response.status_code == 404
-        data = response.json()
-        assert "Role not found" in data["detail"]
+        assert response.status_code == 403
 
     @pytest.mark.asyncio
     async def test_update_role_add_grantable_permission(
@@ -637,7 +636,7 @@ class TestAdminRoles:
     ):
         """Admin should be able to add grantable permissions to role."""
         response = await client.post(
-            f"/auth/api/admin/orgs/{test_org.uuid}/roles/{user_role.uuid}/permissions/{grantable_permission.uuid}",
+            f"/auth/api/admin/roles/{user_role.uuid}/permissions/{grantable_permission.uuid}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 200
@@ -659,7 +658,7 @@ class TestAdminRoles:
         create_permission(perm)
 
         response = await client.post(
-            f"/auth/api/admin/orgs/{test_org.uuid}/roles/{user_role.uuid}/permissions/{perm.uuid}",
+            f"/auth/api/admin/roles/{user_role.uuid}/permissions/{perm.uuid}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 400
@@ -680,14 +679,14 @@ class TestAdminRoles:
         # test_role has both auth:admin and auth:org:admin
         # Remove auth:admin first (should succeed since org:admin remains)
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/roles/{test_role.uuid}/permissions/{admin_permission.uuid}",
+            f"/auth/api/admin/roles/{test_role.uuid}/permissions/{admin_permission.uuid}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 200
 
         # Now try to remove auth:org:admin (should fail - would leave no admin access)
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/roles/{test_role.uuid}/permissions/{org_admin_permission.uuid}",
+            f"/auth/api/admin/roles/{test_role.uuid}/permissions/{org_admin_permission.uuid}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 400
@@ -700,7 +699,7 @@ class TestAdminRoles:
     ):
         """Admin should be able to delete a role."""
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/roles/{user_role.uuid}",
+            f"/auth/api/admin/roles/{user_role.uuid}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 200
@@ -709,16 +708,18 @@ class TestAdminRoles:
 
     @pytest.mark.asyncio
     async def test_delete_role_wrong_org(
-        self, client: httpx.AsyncClient, session_token: str, test_org, second_org_role
+        self,
+        client: httpx.AsyncClient,
+        org_admin_session_token: str,
+        test_org,
+        second_org_role,
     ):
-        """Cannot delete role from another org."""
+        """Org admin cannot delete role from another org."""
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/roles/{second_org_role.uuid}",
-            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+            f"/auth/api/admin/roles/{second_org_role.uuid}",
+            headers={**auth_headers(org_admin_session_token), "Host": "localhost:4401"},
         )
-        assert response.status_code == 404
-        data = response.json()
-        assert "Role not found" in data["detail"]
+        assert response.status_code == 403
 
     @pytest.mark.asyncio
     async def test_delete_own_role_fails(
@@ -726,7 +727,7 @@ class TestAdminRoles:
     ):
         """Admin cannot delete their own role."""
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/roles/{test_role.uuid}",
+            f"/auth/api/admin/roles/{test_role.uuid}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 400
@@ -788,7 +789,7 @@ class TestAdminUsersInOrg:
     ):
         """Admin should be able to get user details within an org."""
         response = await client.get(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}",
+            f"/auth/api/admin/users/{test_user.uuid}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 200
@@ -807,7 +808,7 @@ class TestAdminUsersInOrg:
         """Getting non-existent user should return 404."""
         fake_uuid = uuid7.create()
         response = await client.get(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{fake_uuid}",
+            f"/auth/api/admin/users/{fake_uuid}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 404
@@ -816,16 +817,18 @@ class TestAdminUsersInOrg:
 
     @pytest.mark.asyncio
     async def test_get_user_wrong_org(
-        self, client: httpx.AsyncClient, session_token: str, test_org, second_org_user
+        self,
+        client: httpx.AsyncClient,
+        org_admin_session_token: str,
+        test_org,
+        second_org_user,
     ):
-        """Getting user from another org should return 404."""
+        """Org admin cannot get user from another org."""
         response = await client.get(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{second_org_user.uuid}",
-            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+            f"/auth/api/admin/users/{second_org_user.uuid}",
+            headers={**auth_headers(org_admin_session_token), "Host": "localhost:4401"},
         )
-        assert response.status_code == 404
-        data = response.json()
-        assert "User not found" in data["detail"]
+        assert response.status_code == 403
 
     @pytest.mark.asyncio
     async def test_get_user_with_org_admin(
@@ -837,7 +840,7 @@ class TestAdminUsersInOrg:
     ):
         """Org admin should be able to get user details."""
         response = await client.get(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{org_admin_user.uuid}",
+            f"/auth/api/admin/users/{org_admin_user.uuid}",
             headers={**auth_headers(org_admin_session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 200
@@ -850,7 +853,7 @@ class TestAdminUsersInOrg:
     ):
         """Admin should be able to update user display name."""
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/display-name",
+            f"/auth/api/admin/users/{test_user.uuid}/display-name",
             json={"display_name": "Updated Admin Name"},
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
@@ -863,7 +866,7 @@ class TestAdminUsersInOrg:
         """Updating non-existent user should return 404."""
         fake_uuid = uuid7.create()
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{fake_uuid}/display-name",
+            f"/auth/api/admin/users/{fake_uuid}/display-name",
             json={"display_name": "New Name"},
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
@@ -873,15 +876,19 @@ class TestAdminUsersInOrg:
 
     @pytest.mark.asyncio
     async def test_update_user_display_name_wrong_org(
-        self, client: httpx.AsyncClient, session_token: str, test_org, second_org_user
+        self,
+        client: httpx.AsyncClient,
+        org_admin_session_token: str,
+        test_org,
+        second_org_user,
     ):
-        """Updating user from another org should return 404."""
+        """Org admin cannot update user from another org."""
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{second_org_user.uuid}/display-name",
+            f"/auth/api/admin/users/{second_org_user.uuid}/display-name",
             json={"display_name": "New Name"},
-            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+            headers={**auth_headers(org_admin_session_token), "Host": "localhost:4401"},
         )
-        assert response.status_code == 404
+        assert response.status_code == 403
 
     @pytest.mark.asyncio
     async def test_update_user_display_name_empty(
@@ -889,7 +896,7 @@ class TestAdminUsersInOrg:
     ):
         """Updating user with empty display name should fail."""
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/display-name",
+            f"/auth/api/admin/users/{test_user.uuid}/display-name",
             json={"display_name": "   "},
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
@@ -903,7 +910,7 @@ class TestAdminUsersInOrg:
     ):
         """Updating user with too long display name should fail."""
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/display-name",
+            f"/auth/api/admin/users/{test_user.uuid}/display-name",
             json={"display_name": "x" * 100},
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
@@ -923,8 +930,8 @@ class TestAdminUsersInOrg:
         """Admin should be able to change user's role within org."""
         # Use regular_user who is in the same org but not the session owner
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{regular_user.uuid}/role",
-            json={"role": user_role.display_name},
+            f"/auth/api/admin/users/{regular_user.uuid}/role",
+            json={"role_uuid": str(user_role.uuid)},
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 200
@@ -935,13 +942,13 @@ class TestAdminUsersInOrg:
     ):
         """Updating user role without specifying role should fail."""
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/role",
+            f"/auth/api/admin/users/{test_user.uuid}/role",
             json={},
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 400
         data = response.json()
-        assert "role is required" in data["detail"]
+        assert "role_uuid is required" in data["detail"]
 
     @pytest.mark.asyncio
     async def test_update_user_role_user_not_found(
@@ -950,27 +957,29 @@ class TestAdminUsersInOrg:
         """Updating role for non-existent user should fail."""
         fake_uuid = uuid7.create()
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{fake_uuid}/role",
-            json={"role": "User Role"},
+            f"/auth/api/admin/users/{fake_uuid}/role",
+            json={"role_uuid": str(uuid7.create())},
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
-        assert response.status_code == 400
+        assert response.status_code == 404
         data = response.json()
         assert "User not found" in data["detail"]
 
     @pytest.mark.asyncio
     async def test_update_user_role_wrong_org(
-        self, client: httpx.AsyncClient, session_token: str, test_org, second_org_user
+        self,
+        client: httpx.AsyncClient,
+        org_admin_session_token: str,
+        test_org,
+        second_org_user,
     ):
-        """Updating role for user in another org should fail."""
+        """Org admin cannot update role for user in another org."""
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{second_org_user.uuid}/role",
-            json={"role": "User Role"},
-            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+            f"/auth/api/admin/users/{second_org_user.uuid}/role",
+            json={"role_uuid": str(uuid7.create())},
+            headers={**auth_headers(org_admin_session_token), "Host": "localhost:4401"},
         )
-        assert response.status_code == 400
-        data = response.json()
-        assert "does not belong" in data["detail"]
+        assert response.status_code == 403
 
     @pytest.mark.asyncio
     async def test_update_user_role_invalid_role(
@@ -978,8 +987,8 @@ class TestAdminUsersInOrg:
     ):
         """Updating user to non-existent role should fail."""
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/role",
-            json={"role": "Nonexistent Role"},
+            f"/auth/api/admin/users/{test_user.uuid}/role",
+            json={"role_uuid": str(uuid7.create())},
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 400
@@ -997,8 +1006,8 @@ class TestAdminUsersInOrg:
     ):
         """Admin cannot change their own role to non-admin role."""
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{org_admin_user.uuid}/role",
-            json={"role": user_role.display_name},
+            f"/auth/api/admin/users/{org_admin_user.uuid}/role",
+            json={"role_uuid": str(user_role.uuid)},
             headers={**auth_headers(org_admin_session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 400
@@ -1018,8 +1027,8 @@ class TestAdminUsersInOrg:
         # test_user is already on test_role which has auth:admin
         # Changing to the same role should succeed (no permission loss)
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/role",
-            json={"role": test_role.display_name},
+            f"/auth/api/admin/users/{test_user.uuid}/role",
+            json={"role_uuid": str(test_role.uuid)},
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 200
@@ -1030,7 +1039,7 @@ class TestAdminUsersInOrg:
     ):
         """Admin should be able to create reset links for users."""
         response = await client.post(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/create-link",
+            f"/auth/api/admin/users/{test_user.uuid}/create-link",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 200
@@ -1045,7 +1054,7 @@ class TestAdminUsersInOrg:
         """Creating reset link for non-existent user should fail."""
         fake_uuid = uuid7.create()
         response = await client.post(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{fake_uuid}/create-link",
+            f"/auth/api/admin/users/{fake_uuid}/create-link",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 404
@@ -1054,16 +1063,18 @@ class TestAdminUsersInOrg:
 
     @pytest.mark.asyncio
     async def test_create_user_reset_link_wrong_org(
-        self, client: httpx.AsyncClient, session_token: str, test_org, second_org_user
+        self,
+        client: httpx.AsyncClient,
+        org_admin_session_token: str,
+        test_org,
+        second_org_user,
     ):
-        """Creating reset link for user in another org should fail."""
+        """Org admin cannot create reset link for user in another org."""
         response = await client.post(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{second_org_user.uuid}/create-link",
-            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+            f"/auth/api/admin/users/{second_org_user.uuid}/create-link",
+            headers={**auth_headers(org_admin_session_token), "Host": "localhost:4401"},
         )
-        assert response.status_code == 404
-        data = response.json()
-        assert "not found in organization" in data["detail"]
+        assert response.status_code == 403
 
     @pytest.mark.asyncio
     async def test_create_user_registration_link_without_credentials(
@@ -1083,7 +1094,7 @@ class TestAdminUsersInOrg:
         create_user(user_no_cred)
 
         response = await client.post(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{user_no_cred.uuid}/create-link",
+            f"/auth/api/admin/users/{user_no_cred.uuid}/create-link",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 200
@@ -1091,6 +1102,120 @@ class TestAdminUsersInOrg:
         assert "url" in data
 
 
+# -------------------- User Deletion Tests --------------------
+
+
+class TestAdminUserDeletion:
+    """Tests for admin user deletion"""
+
+    @pytest.mark.asyncio
+    async def test_delete_user_success(
+        self,
+        client: httpx.AsyncClient,
+        session_token: str,
+        test_org,
+        user_role,
+        test_db: DB,
+    ):
+        """Admin should be able to delete a user."""
+        # Create a user to delete
+        user_to_delete = User.create(
+            display_name="User To Delete",
+            role=user_role.uuid,
+        )
+        create_user(user_to_delete)
+
+        response = await client.delete(
+            f"/auth/api/admin/users/{user_to_delete.uuid}",
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["status"] == "ok"
+        # Verify user is actually deleted
+        assert user_to_delete.uuid not in db.data().users
+
+    @pytest.mark.asyncio
+    async def test_delete_user_not_found(
+        self, client: httpx.AsyncClient, session_token: str
+    ):
+        """Deleting non-existent user should return 404."""
+        fake_uuid = uuid7.create()
+        response = await client.delete(
+            f"/auth/api/admin/users/{fake_uuid}",
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert response.status_code == 404
+        data = response.json()
+        assert "User not found" in data["detail"]
+
+    @pytest.mark.asyncio
+    async def test_delete_own_user_fails(
+        self, client: httpx.AsyncClient, session_token: str, test_user
+    ):
+        """Admin cannot delete their own account."""
+        response = await client.delete(
+            f"/auth/api/admin/users/{test_user.uuid}",
+            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+        )
+        assert response.status_code == 400
+        data = response.json()
+        assert "Cannot delete your own account" in data["detail"]
+
+    @pytest.mark.asyncio
+    async def test_delete_user_wrong_org(
+        self,
+        client: httpx.AsyncClient,
+        org_admin_session_token: str,
+        second_org_user,
+    ):
+        """Org admin cannot delete user from another org."""
+        response = await client.delete(
+            f"/auth/api/admin/users/{second_org_user.uuid}",
+            headers={**auth_headers(org_admin_session_token), "Host": "localhost:4401"},
+        )
+        assert response.status_code == 403
+
+    @pytest.mark.asyncio
+    async def test_delete_user_org_admin_success(
+        self,
+        client: httpx.AsyncClient,
+        org_admin_session_token: str,
+        test_org,
+        user_role,
+        test_db: DB,
+    ):
+        """Org admin should be able to delete users in their org."""
+        # Create a user in the same org to delete
+        user_to_delete = User.create(
+            display_name="Org User To Delete",
+            role=user_role.uuid,
+        )
+        create_user(user_to_delete)
+
+        response = await client.delete(
+            f"/auth/api/admin/users/{user_to_delete.uuid}",
+            headers={**auth_headers(org_admin_session_token), "Host": "localhost:4401"},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["status"] == "ok"
+
+    @pytest.mark.asyncio
+    async def test_delete_user_regular_user_forbidden(
+        self,
+        client: httpx.AsyncClient,
+        regular_session_token: str,
+        test_user,
+    ):
+        """Regular user trying to delete user should get 403."""
+        response = await client.delete(
+            f"/auth/api/admin/users/{test_user.uuid}",
+            headers={**auth_headers(regular_session_token), "Host": "localhost:4401"},
+        )
+        assert response.status_code == 403
+
+
 # -------------------- Credential Tests --------------------
 
 
@@ -1108,7 +1233,7 @@ class TestAdminCredentials:
     ):
         """Admin should be able to delete a user's credential."""
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/credentials/{test_credential.uuid}",
+            f"/auth/api/admin/users/{test_user.uuid}/credentials/{test_credential.uuid}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 200
@@ -1123,7 +1248,7 @@ class TestAdminCredentials:
         fake_user_uuid = uuid7.create()
         fake_cred_uuid = uuid7.create()
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{fake_user_uuid}/credentials/{fake_cred_uuid}",
+            f"/auth/api/admin/users/{fake_user_uuid}/credentials/{fake_cred_uuid}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 404
@@ -1134,17 +1259,17 @@ class TestAdminCredentials:
     async def test_delete_credential_wrong_org(
         self,
         client: httpx.AsyncClient,
-        session_token: str,
+        org_admin_session_token: str,
         test_org,
         second_org_user,
         second_org_credential,
     ):
-        """Deleting credential for user in another org should fail."""
+        """Org admin cannot delete credential for user in another org."""
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{second_org_user.uuid}/credentials/{second_org_credential.uuid}",
-            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+            f"/auth/api/admin/users/{second_org_user.uuid}/credentials/{second_org_credential.uuid}",
+            headers={**auth_headers(org_admin_session_token), "Host": "localhost:4401"},
         )
-        assert response.status_code == 404
+        assert response.status_code == 403
 
 
 # -------------------- Session Tests --------------------
@@ -1171,11 +1296,10 @@ class TestAdminSessions:
             host="other.host:4401",
             ip="192.168.1.1",
             user_agent="other-agent",
-            expiry=expires(),
         )
 
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/sessions/{extra_token}",
+            f"/auth/api/admin/users/{test_user.uuid}/sessions/{extra_token}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 200
@@ -1193,7 +1317,7 @@ class TestAdminSessions:
     ):
         """Admin can delete their own current session."""
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/sessions/{session_token}",
+            f"/auth/api/admin/users/{test_user.uuid}/sessions/{session_token}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 200
@@ -1207,7 +1331,7 @@ class TestAdminSessions:
         """Deleting session for non-existent user should fail."""
         fake_uuid = uuid7.create()
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{fake_uuid}/sessions/fake-session-id",
+            f"/auth/api/admin/users/{fake_uuid}/sessions/fake-session-id",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 404
@@ -1218,16 +1342,16 @@ class TestAdminSessions:
     async def test_delete_session_wrong_org(
         self,
         client: httpx.AsyncClient,
-        session_token: str,
+        org_admin_session_token: str,
         test_org,
         second_org_user,
     ):
-        """Deleting session for user in another org should fail."""
+        """Org admin cannot delete session for user in another org."""
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{second_org_user.uuid}/sessions/fake-session",
-            headers={**auth_headers(session_token), "Host": "localhost:4401"},
+            f"/auth/api/admin/users/{second_org_user.uuid}/sessions/fake-session",
+            headers={**auth_headers(org_admin_session_token), "Host": "localhost:4401"},
         )
-        assert response.status_code == 404
+        assert response.status_code == 403
 
     @pytest.mark.asyncio
     async def test_delete_session_invalid_id(
@@ -1235,7 +1359,7 @@ class TestAdminSessions:
     ):
         """Deleting session with invalid/non-existent ID should fail."""
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/sessions/invalid!!id",
+            f"/auth/api/admin/users/{test_user.uuid}/sessions/invalid!!id",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 404
@@ -1250,7 +1374,7 @@ class TestAdminSessions:
         # Use a valid format but non-existent key
         fake_token = secrets.token_urlsafe(12)
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/sessions/{fake_token}",
+            f"/auth/api/admin/users/{test_user.uuid}/sessions/{fake_token}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 404
@@ -1550,7 +1674,7 @@ class TestOrgAdminAuthExceptions:
     ):
         """Regular user (not org admin) trying to create reset link should get 403."""
         response = await client.post(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/create-link",
+            f"/auth/api/admin/users/{test_user.uuid}/create-link",
             headers={**auth_headers(regular_session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 403
@@ -1565,7 +1689,7 @@ class TestOrgAdminAuthExceptions:
     ):
         """Regular user trying to get user details should get 403."""
         response = await client.get(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}",
+            f"/auth/api/admin/users/{test_user.uuid}",
             headers={**auth_headers(regular_session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 403
@@ -1580,7 +1704,7 @@ class TestOrgAdminAuthExceptions:
     ):
         """Regular user trying to update display name should get 403."""
         response = await client.patch(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/display-name",
+            f"/auth/api/admin/users/{test_user.uuid}/display-name",
             json={"display_name": "New Name"},
             headers={**auth_headers(regular_session_token), "Host": "localhost:4401"},
         )
@@ -1597,7 +1721,7 @@ class TestOrgAdminAuthExceptions:
     ):
         """Regular user trying to delete credential should get 403."""
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/credentials/{test_credential.uuid}",
+            f"/auth/api/admin/users/{test_user.uuid}/credentials/{test_credential.uuid}",
             headers={**auth_headers(regular_session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 403
@@ -1612,7 +1736,7 @@ class TestOrgAdminAuthExceptions:
     ):
         """Regular user trying to delete session should get 403."""
         response = await client.delete(
-            f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/sessions/some-session",
+            f"/auth/api/admin/users/{test_user.uuid}/sessions/some-session",
             headers={**auth_headers(regular_session_token), "Host": "localhost:4401"},
         )
         assert response.status_code == 403

tests/test_api.py

@@ -11,7 +11,7 @@ These tests cover:
 """
 
 import secrets
-from datetime import UTC, datetime, timedelta
+from datetime import timedelta
 
 import httpx
 import pytest
@@ -521,15 +521,14 @@ class TestValidateSessionRefresh:
     ):
         """Validate should return 401 if session disappears during refresh."""
 
-        # Create a session with an old expiry time to trigger refresh
-        old_expiry = datetime.now(UTC) + EXPIRES - timedelta(minutes=10)
+        # Create a session with a short remaining duration to trigger refresh
         token = create_session(
             user_uuid=test_user.uuid,
             credential_uuid=test_credential.uuid,
-            host="localhost:4401",
+            host="localhost",
             ip="127.0.0.1",
             user_agent="pytest",
-            expiry=old_expiry,
+            duration=EXPIRES - timedelta(minutes=10),
         )
 
         # Delete the session right before validate tries to refresh