Cleaner database error handling and fixes.

.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,28 +1,35 @@
 # Paskia
 
-![Screenshot](https://git.zi.fi/leovasanko/paskia/raw/main/docs/screenshots/forbidden-light.webp)
+![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
 
@@ -44,20 +51,157 @@ uv tool install paskia
 
 ## Configuration
 
-There is no config file. All settings are passed as CLI options:
+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 [options]
-paskia reset [user]     # Generate passkey reset link
 ```
 
 | Option | Description | Default |
 |--------|-------------|---------|
 | -l, --listen *endpoint* | Listen address: *host*:*port*, :*port* (all interfaces), or */path.sock* | **localhost:4401** |
 | --rp-id *domain* | Main/top domain for passkeys | **localhost** |
-| --rp-name *"text"* | Name shown during passkey registration | Same as rp-id |
-| --origin *url* | Restrict allowed origins for WebSocket auth (repeatable) | All under rp-id |
+| --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 `*.example.com`. The `--rp-name` is shown to users during passkey registration. The `--save` option stores these settings in the database, so future runs only need `paskia --rp-id example.com`.
+
+### 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 Authentication Server
+
+[Service]
+Type=simple
+User=paskia
+WorkingDirectory=/srv/paskia
+ExecStart=uvx paskia --rp-id=example.com
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then enable and start, view output for registration link:
+
+```fish
+sudo systemctl enable --now paskia && sudo journalctl -u paskia -f -n 20 -o cat
+```
+
 
 ## 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/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/db/__init__.py

@@ -47,6 +47,7 @@ from paskia.db.operations import (
     delete_session,
     delete_sessions_for_user,
     delete_user,
+    get_config,
     get_organization_users,
     get_reset_token,
     get_user_credential_ids,
@@ -55,6 +56,7 @@ from paskia.db.operations import (
     login,
     remove_permission_from_org,
     remove_permission_from_role,
+    set_config,
     set_session_host,
     update_credential_sign_count,
     update_org_name,
@@ -110,6 +112,7 @@ __all__ = [
     "build_session",
     "build_user",
     # Read ops
+    "get_config",
     "get_organization_users",
     "get_reset_token",
     "get_user_credential_ids",
@@ -138,6 +141,7 @@ __all__ = [
     "login",
     "remove_permission_from_org",
     "remove_permission_from_role",
+    "set_config",
     "set_session_host",
     "update_credential_sign_count",
     "update_org_name",

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
@@ -69,22 +71,25 @@ def create_change_record(
 # Actions that are allowed to create a new database file
 _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
@@ -94,26 +99,25 @@ async def flush_changes(
                 "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)
@@ -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/migrations.py

@@ -8,12 +8,18 @@ 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")),
@@ -26,8 +32,10 @@ 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

@@ -17,11 +17,11 @@ 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,
@@ -42,16 +42,15 @@ _db._store = _store
 _initialized = False
 
 
-async def init(*args, **kwargs):
+async def init(rp_id: str = "localhost", *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)
+    default_path = f"{rp_id}.paskiadb"
+    db_path = os.environ.get("PASKIA_DB", default_path)
+    await _store.load(db_path, rp_id=rp_id)
     _db = _store.db
     _initialized = True
 
@@ -823,3 +822,19 @@ def bootstrap(
         _db.reset_tokens[reset_token.key] = reset_token
 
     return reset_passphrase
+
+
+# -------------------------------------------------------------------------
+# Config operations
+# -------------------------------------------------------------------------
+
+
+def get_config() -> Config:
+    """Get the stored configuration."""
+    return _db.config
+
+
+async def set_config(config: Config) -> None:
+    """Update the stored configuration."""
+    with _db.transaction("update_config"):
+        _db.config = config

paskia/db/structs.py

@@ -7,6 +7,7 @@ from uuid import UUID
 
 import msgspec
 import uuid7
+from msgspec import field
 
 from paskia import db
 from paskia.util.hostutil import normalize_host
@@ -397,6 +398,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
 # -------------------------------------------------------------------------
@@ -412,6 +423,7 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
     credentials: dict[UUID, Credential] = {}
     sessions: dict[str, Session] = {}
     reset_tokens: dict[bytes, ResetToken] = {}
+    config: Config = field(default_factory=lambda: Config(rp_id="localhost"))
 
     def __post_init__(self):
         # Store reference for persistence (not serialized)

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 globals as _globals
 from paskia.bootstrap import bootstrap_if_needed
 from paskia.config import PaskiaConfig
+from paskia.db import get_config, set_config
+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 -l :8080                  # All interfaces, port 8080
-  paskia -l /tmp/paskia.sock       # Unix socket
-  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,17 +84,6 @@ def main():
         epilog=EPILOG,
     )
 
-    # Subcommand for reset
-    parser.add_argument(
-        "command",
-        nargs="?",
-        help="Command: 'reset' for credential reset, or omit to run server",
-    )
-    parser.add_argument(
-        "reset_query",
-        nargs="?",
-        help="For 'reset' command: user UUID or substring of display name",
-    )
     parser.add_argument(
         "-l",
         "--listen",
@@ -105,16 +97,30 @@ def main():
 
     args = parser.parse_args()
 
-    # Detect "reset" subcommand
-    is_reset = args.command == "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:
-        if args.command is not None:
-            raise SystemExit(f"Unknown command: {args.command}")
-        # Parse endpoint using fastapi_vue.hostutil
-        endpoints = parse_endpoint(args.listen, DEFAULT_PORT)
+    # Init db and load stored config
+    asyncio.run(db_init(rp_id=args.rp_id))
+    stored_config = get_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 {}
@@ -193,14 +199,22 @@ def main():
 
     startupbox.print_startup_config(config)
 
-    devmode = bool(os.environ.get("FASTAPI_VUE_FRONTEND_URL"))
+    if args.save:
+        new_config = Config(
+            rp_id=args.rp_id,
+            rp_name=args.rp_name,
+            origins=args.origins,
+            auth_host=args.auth_host,
+            listen=args.listen,
+        )
+        asyncio.run(set_config(new_config))
 
     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:
@@ -218,25 +232,21 @@ def main():
         await bootstrap_if_needed()
         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/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
@@ -59,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()
@@ -74,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)

paskia/fastapi/reset.py

@@ -1,106 +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
-
-
-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):
-    expiry = _authsession.reset_expires()
-    token = db.create_reset_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/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/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

scripts/devserver.py

@@ -13,9 +13,9 @@ 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)
@@ -34,12 +34,16 @@ from contextlib import suppress
 from pathlib import Path
 from urllib.parse import urlparse
 
-from fastapi_vue.hostutil import parse_endpoint
-
 # 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 buildutil import find_dev_tool, find_install_tool, logger  # noqa: E402
-from devutil import ProcessGroup, check_ports_free  # noqa: E402
+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
@@ -60,35 +64,6 @@ SITE_ADDR {
 """
 
 
-def build_vite_cmd(vite_host: str, vite_port: int) -> list[str] | None:
-    """Build the Vite dev command, or None if not available."""
-    devpath = Path(__file__).parent.parent / "frontend"
-    if not (devpath / "package.json").exists():
-        logger.warning("Frontend source not found at %s", devpath)
-        return None
-
-    try:
-        cmd = find_dev_tool()
-    except RuntimeError as e:
-        logger.warning(str(e))
-        return None
-
-    # Add Vite CLI args for host/port
-    cmd.extend([f"--port={vite_port}", "--logLevel=silent"])
-    if vite_host and vite_host != "localhost":
-        cmd.append("--host" if vite_host == "0.0.0.0" else f"--host={vite_host}")
-
-    return cmd
-
-
-def build_npm_install_cmd() -> list[str] | None:
-    """Build the npm install command, or None if not available."""
-    try:
-        return find_install_tool()
-    except RuntimeError:
-        return None
-
-
 def build_caddyfile(origins: list[str], vite_port: int) -> str:
     """Build a Caddyfile for the given origins."""
     caddyfile_parts = []
@@ -181,22 +156,26 @@ async def run_caddy(origins: list[str], vite_port: int) -> asyncio.subprocess.Pr
 
 async def run_devserver(args: argparse.Namespace, remaining: list[str]) -> None:
     """Run the development server with all components."""
-    # Parse Vite endpoint
-    endpoints = parse_endpoint(args.listen, DEFAULT_VITE_PORT)
-    ep = endpoints[0]
-
-    if "uds" in ep:
-        logger.warning("Unix sockets are not supported for Vite frontend")
+    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)
 
-    vite_host = ep["host"]
-    vite_port = ep["port"]
-    # Multiple endpoints means all-interfaces (:port syntax)
-    if len(endpoints) > 1:
-        vite_host = "0.0.0.0"
+    viteurl, npm_install, vite = setup_vite(args.listen, DEFAULT_VITE_PORT)
+    backurl, paskia = setup_cli("paskia", f"localhost:{BACKEND_PORT}", BACKEND_PORT)
 
-    vite_url = f"http://localhost:{vite_port}"
-    backend_url = f"http://localhost:{BACKEND_PORT}"
+    # Extract vite port for Caddy config
+    vite_port = int(viteurl.rsplit(":", 1)[1])
+
+    # 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)
 
     # Compute origins for Caddy
     caddy_origins = []
@@ -217,30 +196,13 @@ async def run_devserver(args: argparse.Namespace, remaining: list[str]) -> None:
     seen = set()
     caddy_origins = [x for x in caddy_origins if not (x in seen or seen.add(x))]
 
-    # Check ports are free before starting
-    await check_ports_free(vite_url, backend_url)
-
     # Set environment for subprocesses
-    os.environ["FASTAPI_VUE_FRONTEND_URL"] = vite_url
-    os.environ["FASTAPI_VUE_BACKEND_URL"] = backend_url
-    os.environ["PASKIA_SITE_URL"] = caddy_origins[0] if args.caddy else vite_url
+    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
 
-    # Build commands
-    frontend_path = Path(__file__).parent.parent / "frontend"
-    vite_cmd = build_vite_cmd(vite_host, vite_port)
-    install_cmd = build_npm_install_cmd()
-
-    paskia_cmd = ["paskia", "-l", f"localhost:{BACKEND_PORT}"]
-    paskia_cmd.extend(["--rp-id", args.rp_id])
-    if args.auth_host:
-        paskia_cmd.extend(["--auth-host", args.auth_host])
-    if args.origins:
-        for origin in args.origins:
-            paskia_cmd.extend(["--origin", origin])
-    paskia_cmd.extend(remaining)
-
     async with ProcessGroup() as pg:
         # Start Caddy first if requested (needs to bind ports)
         if args.caddy:
@@ -248,29 +210,11 @@ async def run_devserver(args: argparse.Namespace, remaining: list[str]) -> None:
             pg._procs.append(caddy_proc)
             pg._cmds[caddy_proc.pid] = "caddy"
 
-        # Run npm install concurrently with backend startup
-        if install_cmd and (frontend_path / "package.json").exists():
-            npm_proc = await pg.spawn(*install_cmd, cwd=str(frontend_path))
-        else:
-            npm_proc = None
-
-        # Start paskia backend
-        logger.info(">>> (devmode) %s", " ".join(paskia_cmd))
-        paskia_proc = await asyncio.create_subprocess_exec(*paskia_cmd)
-        pg._procs.append(paskia_proc)
-        pg._cmds[paskia_proc.pid] = "paskia"
-
-        # Wait for npm install to complete before starting Vite
-        if npm_proc:
-            await pg.wait(npm_proc)
-
-        # Start Vite dev server
-        if vite_cmd:
-            await pg.spawn(*vite_cmd, cwd=str(frontend_path))
-        else:
-            logger.info(
-                "Backend expects Vite at %s - start it manually if needed", vite_url
-            )
+        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():

scripts/fastapi-vue/buildutil.py

@@ -134,7 +134,7 @@ def find_dev_tool() -> list[str]:
     Raises RuntimeError if no runtime is found.
     """
     dev_args = {
-        "deno": ("run", "dev", "--"),
+        "deno": ("run", "-A", "npm:vite"),
         "npm": ("--silent", "run", "dev", "--"),
         "bun": ("run", "dev", "--"),
     }

scripts/fastapi-vue/devutil.py

@@ -21,12 +21,12 @@ class ProcessGroup:
         self._cmds: dict[int, str] = {}  # pid -> command name
 
     async def spawn(
-        self, *cmd: str, cwd: str | None = None, env: dict | None = None
+        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, env=env)
+        proc = await asyncio.create_subprocess_exec(*cmd, cwd=cwd)
         self._procs.append(proc)
         self._cmds[proc.pid] = cmd_name
         return proc
@@ -188,3 +188,24 @@ def setup_fastapi(
         "--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