Implement code word based remote authentication (#1)

Add comprehensive remote authentication system allowing users to log in from one device by authenticating from another trusted device. Features include:

- Proof of Work (PoW) protection using PBKDF2-SHA512 to prevent abuse
- Simple pairing codes (3 words) protected by dynamic PoW difficulty
- Autocomplete pairing code input with error checking
- Real-time WebSocket communication between devices

Unlike device addition links and reset links with QR codes that only allow adding an authentication method, and that work offline over the duration of several days, this mechanism is strictly online, with 5 minute time limit.

.gitignore

@@ -3,7 +3,9 @@ dist/
 .*
 !.gitignore
 *.lock
-passkey-auth.sqlite
-/passkey/frontend-build
-/test_*.py
-passkey/_version.py
+package-lock.json
+paskia.sqlite
+/paskia/frontend-build
+/paskia/_version.py
+coverage-html/
+e2e/coverage-frontend/

API.md

@@ -1,6 +1,6 @@
-# PassKey Auth API Documentation
+# Paskia API Documentation
 
-This document lists the HTTP and WebSocket endpoints exposed by the PassKey Auth
+This document lists the HTTP and WebSocket endpoints exposed by the Paskia
 service and how they behave depending on whether a dedicated authentication host
 (`--auth-host` / environment `PASSKEY_AUTH_HOST`) is configured.
 
@@ -41,7 +41,6 @@ Notes:
 | GET | `/auth/` | `/` | Main authentication SPA (non-auth hosts show an account summary view) |
 | GET | `/auth/admin/` | `/admin/` | Admin SPA root |
 | GET | `/auth/{reset_token}` | `/{reset_token}` | Reset / device addition SPA (token validated) |
-| GET | `/auth/restricted` | `/restricted` | Restricted / permission denied SPA |
 
 ## Core API (Unrestricted – available on all hosts)
 
@@ -49,6 +48,8 @@ Always under `/auth/api/` (even on auth host):
 
 | Method | Path | Description |
 |--------|------|-------------|
+| GET | `/auth/restricted/` | Authentication UI for iframe embedding (supports `?mode=login` or `?mode=reauth`) |
+|--------|------|-------------|
 | POST | `/auth/api/validate` | Validate & (conditionally) renew session |
 | GET | `/auth/api/forward` | Auth proxy endpoint for reverse proxies (204 or 4xx) |
 | POST | `/auth/api/set-session` | Set cookie from Bearer token |

README.md

@@ -1,129 +1,72 @@
-# PasskeyAuth
+# Paskia
 
-A minimal FastAPI WebAuthn server with WebSocket support for passkey registration. This project demonstrates WebAuthn registration flow with Resident Keys (discoverable credentials) using modern Python tooling.
+An easy to install passkey-based authentication service that protects any web application with strong passwordless login.
 
-## Features
+## What is Paskia?
 
-- 🔐 WebAuthn registration with Resident Keys support
-- 🔌 WebSocket-based communication for real-time interaction
-- 🚀 Modern Python packaging with `pyproject.toml`
-- 🎨 Clean, responsive HTML interface using @simplewebauthn/browser
-- 📦 No database required - challenges stored locally per connection
-- 🛠️ Development tools: `ruff` for linting and formatting
-- 🧹 Clean architecture with local challenge management
+- Easy to use fully featured auth&auth system (login and permissions)
+- Organization and role-based access control (optional)
+   * 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
 
-## Docs
+Two interfaces:
+- API fetch: auth checks and login without leaving your app
+- Forward-auth proxy: protect any unprotected site or service (Caddy, Nginx)
 
-- Caddy integration: see `CADDY.md` for short, copy-paste snippets to secure your site with Caddy.
+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.
 
-## Requirements
-
-- Python 3.9+
-- A WebAuthn-compatible authenticator (security key, biometric device, etc.)
+Single Sign-On (SSO): Users register once and authenticate across all applications under your domain name (configured rp-id).
 
 ## Quick Start
 
-### Install (editable dev mode)
+Install [UV](https://docs.astral.sh/uv/getting-started/installation/) and run:
 
 ```fish
-uv pip install -e .[dev]
+uvx paskia serve --rp-id example.com
 ```
 
-### Run (new CLI)
+On the first run it downloads the software and prints a registration link for the Admin. If you are going to be connecting `localhost` directly, for testing, leave out the rp-id.
 
-`passkey-auth` now provides subcommands:
+The server will start up on [localhost:4401](http://localhost:4401) "for authentication required", serving for `*.example.com`.
+
+Otherwise you will need a web server such as [Caddy](https://caddyserver.com/) to serve HTTPS on your actual domain names and proxy requests to Paskia and your backend apps.
+
+A quick example without any config file:
+```fish
+sudo caddy reverse-proxy --from example.com --to :4401
+```
+
+For a permanent install of `paskia` CLI command, not needing `uvx`:
+
+```fish
+uv tool install paskia
+```
+
+## Configuration
+
+There is no config file. Pass only the options on CLI:
 
 ```text
-passkey-auth serve [host:port] [--options]
-passkey-auth dev   [--options]
+paskia serve [options]
 ```
 
-Examples (fish shell shown):
+Optional options:
 
-```fish
-# Production style (no reload)
-passkey-auth serve
-passkey-auth serve 0.0.0.0:8080 --rp-id example.com --origin https://example.com
+- Listen address (one of):
+    * `[host]:port`: Address and port (default: `localhost:4401`)
+    * `unix:/path.sock`: Unix socket
+- `--rp-id <domain>`: Main domain (required for production)
+- `--rp-name "<text>"`: Name of your company or site (default: same as rp-id)
+- `--origin <url>`: Explicit single site (default: `https://<rp-id>`)
+- `--auth-host <domain>`: Dedicated authentication site (e.g., `auth.example.com`)
 
-# Development (auto-reload)
-passkey-auth dev            # localhost:4401
-passkey-auth dev :5500      # localhost on port 5500
-passkey-auth dev 127.0.0.1  # host only, default port 4401
-```
+## Documentation
 
-Available options (both subcommands):
-
-```text
---rp-id <id>        Relying Party ID (default: localhost)
---rp-name <name>    Relying Party name (default: same as rp-id)
---origin <url>      Explicit origin (default: https://<rp-id>)
-```
-
-### Legacy Invocation
-
-If you previously used `python -m passkey.fastapi --dev --host ...`, switch to the new form above. The old flags `--host`, `--port`, and `--dev` are replaced by the `[host:port]` positional and the `dev` subcommand.
-
-## Usage (Web)
-
-1. Start the server with one of the commands above
-2. Open your browser to `http://localhost:4401/auth/` (or your chosen host/port)
-3. Enter a username (or use the default)
-4. Click "Register Passkey"
-5. Follow your authenticator's prompts
-
-Real-time status updates stream over WebSocket.
-
-## Development
-
-### Code Quality
-
-```fish
-# Run linting and formatting with ruff
-uv run ruff check .
-uv run ruff format .
-
-# Or with hatch
-hatch run ruff check .
-hatch run ruff format .
-```
-
-### Project Structure
-
-```
-passkeyauth/
-├── passkeyauth/
-│   ├── __init__.py
-│   └── main.py          # FastAPI server with WebSocket support
-├── static/
-│   └── index.html       # Frontend interface
-├── pyproject.toml       # Modern Python packaging configuration
-└── README.md
-```
-
-## Technical Details
-
-### WebAuthn Configuration
-
-- **Relying Party ID**: `localhost` (for development)
-- **Resident Keys**: Required (enables discoverable credentials)
-- **User Verification**: Preferred
-- **Supported Algorithms**: ECDSA-SHA256, RSASSA-PKCS1-v1_5-SHA256
-
-### WebSocket Message Flow
-
-1. Client connects to `/ws/{client_id}`
-2. Client sends `registration_challenge` message
-3. Server responds with `registration_challenge_response`
-4. Client completes WebAuthn ceremony and sends `registration_response`
-5. Server verifies and responds with `registration_success` or `error`
-
-### Security Notes
-
-- This is a minimal demo - challenges are stored locally per WebSocket connection
-- For production use, implement proper user storage and session management
-- Consider using Redis or similar for challenge storage in production with multiple server instances
-- Ensure HTTPS in production environments
-
-## License
-
-MIT License - feel free to use this as a starting point for your own WebAuthn implementations!
+- `API.md`: Complete HTTP and WebSocket API reference
+- `Caddy.md`: Caddy configuration examples
+- `Headers.md`: HTTP headers passed to protected applications

caddy/Caddyfile.dev

@@ -0,0 +1,10 @@
+localhost {
+	# Forwards API by caddy, bypassing the Vite dev proxy
+	# Avoids bug https://github.com/oven-sh/bun/issues/9882
+	handle /api/* {
+		reverse_proxy :4402   # directly to backend
+	}
+	handle {
+		reverse_proxy :4403   # vite dev server
+	}
+}

e2e/.gitignore

@@ -0,0 +1,13 @@
+# Dependencies
+node_modules/
+
+# Test artifacts
+test-data/
+test-results/
+playwright-report/
+
+# Playwright
+.playwright/
+
+# Bun
+bun.lockb

e2e/README.md

@@ -0,0 +1,167 @@
+# Paskia E2E Tests
+
+End-to-end tests for Paskia using [Playwright](https://playwright.dev/) with Chrome's **Virtual Authenticator**.
+
+## Overview
+
+These tests exercise the complete WebAuthn/passkey authentication flow without requiring physical hardware. Chrome's DevTools Protocol provides a virtual authenticator that can:
+
+- Generate passkey credentials
+- Sign authentication challenges
+- Store resident keys (discoverable credentials)
+- Simulate user verification (biometrics/PIN)
+
+## Prerequisites
+
+- Node.js 18+
+- Python with `uv` (for running the backend server)
+
+## Setup
+
+```bash
+cd e2e
+npm install
+npm run install:browsers
+```
+
+## Running Tests
+
+### Basic Test Run
+
+```bash
+npm test
+```
+
+This will:
+1. Start a fresh Paskia server with a test database
+2. Run all E2E tests against it
+3. Clean up the server when done
+
+### With Coverage
+
+```bash
+npm run test:coverage
+```
+
+Runs tests and collects coverage for both:
+- **Python backend** (via `coverage.py`) - HTML report in `coverage-html/`
+- **Frontend JavaScript** (via Chrome V8 coverage) - JSON data in `e2e/coverage-frontend/`
+
+### Interactive Mode
+
+```bash
+npm run test:ui
+```
+
+Opens Playwright's UI mode for interactive test debugging.
+
+### Headed Mode
+
+```bash
+npm run test:headed
+```
+
+Runs tests with a visible browser window.
+
+### Debug Mode
+
+```bash
+npm run test:debug
+```
+
+Runs tests with Playwright Inspector for step-by-step debugging.
+
+## Test Structure
+
+```
+e2e/
+├── playwright.config.ts      # Playwright configuration
+├── package.json
+├── tsconfig.json
+├── test-data/                # Test database (created at runtime)
+│   └── test.sqlite
+└── tests/
+    ├── global-setup.ts       # Creates fresh DB, captures reset token
+    ├── global-teardown.ts    # Cleanup
+    ├── passkey.spec.ts       # Main E2E tests
+    └── fixtures/
+        ├── virtual-authenticator.ts  # Virtual authenticator setup
+        └── passkey-helpers.ts        # WebSocket helpers
+```
+
+## What's Tested
+
+### Registration Flow
+- Bootstrap admin user registration via reset token
+- WebSocket challenge-response with virtual authenticator
+- Session token creation and validation
+
+### Authentication Flow
+- Passkey authentication via WebSocket
+- Credential verification
+- Session management
+
+### Session Management
+- Token validation (`/auth/api/validate`)
+- User info retrieval (`/auth/api/user-info`)
+- Logout (`/auth/api/logout`)
+- Invalid/missing token rejection
+
+## How Virtual Authenticator Works
+
+The tests use Chrome DevTools Protocol (CDP) to create a virtual authenticator:
+
+```typescript
+const cdpSession = await page.context().newCDPSession(page)
+await cdpSession.send('WebAuthn.enable')
+await cdpSession.send('WebAuthn.addVirtualAuthenticator', {
+  options: {
+    protocol: 'ctap2',
+    transport: 'internal',
+    hasResidentKey: true,
+    hasUserVerification: true,
+    isUserVerified: true,
+    automaticPresenceSimulation: true,
+  },
+})
+```
+
+This creates an in-browser authenticator that:
+- Automatically responds to WebAuthn prompts
+- Stores credentials persistently during the test session
+- Simulates user verification without actual biometric input
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `BASE_URL` | Server URL | `http://localhost:4404` |
+| `CI` | CI environment flag | - |
+| `CLEANUP_TEST_DB` | Remove test DB after run | `false` |
+
+## Limitations
+
+1. **Chromium only**: Virtual authenticator is a Chrome DevTools feature
+2. **No cross-origin**: Tests run on localhost; production-like origins need additional setup
+3. **Single user per run**: Bootstrap creates one admin user; additional users need admin API
+
+## Debugging Tips
+
+1. **Check test database**: `e2e/test-data/test.sqlite` persists after tests
+2. **View server output**: Global setup echoes server bootstrap to console
+3. **Use trace viewer**: `npx playwright show-trace` on failure traces
+
+## CI Integration
+
+The tests are designed for CI environments:
+
+```yaml
+- name: Run E2E Tests
+  run: |
+    cd e2e
+    npm ci
+    npm run install:browsers
+    npm test
+  env:
+    CI: true
+```

e2e/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "paskia-e2e",
+  "version": "1.0.0",
+  "private": true,
+  "description": "E2E tests for Paskia using Playwright with Virtual Authenticator",
+  "type": "module",
+  "scripts": {
+    "test": "bunx playwright test",
+    "test:headed": "bunx playwright test --headed",
+    "test:debug": "bunx playwright test --debug",
+    "test:ui": "bunx playwright test --ui",
+    "test:coverage": "COVERAGE=1 bunx playwright test",
+    "report": "bunx playwright show-report",
+    "install:browsers": "bunx playwright install chromium"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.0",
+    "@simplewebauthn/browser": "^13.1.2",
+    "@types/bun": "^1.3.3",
+    "c8": "^10.1.3"
+  }
+}

e2e/playwright.config.js

@@ -0,0 +1,50 @@
+import { defineConfig, devices } from '@playwright/test'
+
+/**
+ * Playwright configuration for Paskia E2E tests.
+ * Uses Chrome's Virtual Authenticator for automated passkey testing.
+ *
+ * Run with: bun run test
+ */
+
+export default defineConfig({
+  testDir: './tests',
+  fullyParallel: false, // Run tests sequentially for passkey state consistency
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1, // Single worker for database state consistency
+  reporter: [
+    ['html', { open: 'never' }],
+    ['list']
+  ],
+
+  // Global setup/teardown for test database and server
+  globalSetup: './tests/global-setup.ts',
+  globalTeardown: './tests/global-teardown.ts',
+
+  use: {
+    // Base URL for the Paskia server
+    baseURL: process.env.BASE_URL || 'http://localhost:4404',
+
+    // Collect trace on failure for debugging
+    trace: 'on-first-retry',
+
+    // Screenshot on failure
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+        // Chrome-specific settings for virtual authenticator
+        launchOptions: {
+          args: [
+            '--enable-features=WebAuthenticationEnterpriseAttestation',
+          ],
+        },
+      },
+    },
+  ],
+})

e2e/playwright.config.ts.bak

@@ -0,0 +1,50 @@
+import { defineConfig, devices } from '@playwright/test'
+
+/**
+ * Playwright configuration for Paskia E2E tests.
+ * Uses Chrome's Virtual Authenticator for automated passkey testing.
+ *
+ * Run with: bun run test
+ */
+
+export default defineConfig({
+  testDir: './tests',
+  fullyParallel: false, // Run tests sequentially for passkey state consistency
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1, // Single worker for database state consistency
+  reporter: [
+    ['html', { open: 'never' }],
+    ['list']
+  ],
+
+  // Global setup/teardown for test database and server
+  globalSetup: './tests/global-setup.ts',
+  globalTeardown: './tests/global-teardown.ts',
+
+  use: {
+    // Base URL for the Paskia server
+    baseURL: process.env.BASE_URL || 'http://localhost:4401',
+
+    // Collect trace on failure for debugging
+    trace: 'on-first-retry',
+
+    // Screenshot on failure
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+        // Chrome-specific settings for virtual authenticator
+        launchOptions: {
+          args: [
+            '--enable-features=WebAuthenticationEnterpriseAttestation',
+          ],
+        },
+      },
+    },
+  ],
+})

e2e/tests/10-passkey.spec.ts

@@ -0,0 +1,635 @@
+import { test, expect, createVirtualAuthenticator } from './fixtures/virtual-authenticator'
+import {
+  registerPasskey,
+  authenticatePasskey,
+  validateSession,
+  getUserInfo,
+  logout,
+  getBootstrapResetToken,
+  createDeviceLink,
+  getSessionCookieName,
+  saveSessionToken,
+  getSavedSessionToken,
+  saveDeviceTokens,
+} from './fixtures/passkey-helpers'
+import type { Page, BrowserContext } from '@playwright/test'
+
+/**
+ * Helper to set up session cookie for a page.
+ */
+async function setupSessionCookie(page: Page, sessionToken: string): Promise<void> {
+  const cookieName = getSessionCookieName()
+  await page.context().addCookies([{
+    name: cookieName,
+    value: sessionToken,
+    domain: 'localhost',
+    path: '/',
+    secure: true,
+    httpOnly: true,
+    sameSite: 'Strict' as const,
+  }])
+}
+
+/**
+ * E2E tests for Paskia using Chrome's Virtual Authenticator.
+ *
+ * These tests exercise the complete WebAuthn flow:
+ * 1. Registration via WebSocket using bootstrap reset token
+ * 2. Authentication via WebSocket
+ * 3. Session validation
+ * 4. User info retrieval
+ * 5. Logout
+ *
+ * The virtual authenticator simulates a hardware passkey device,
+ * allowing fully automated testing without physical hardware.
+ */
+
+test.describe('Passkey Authentication E2E', () => {
+  const baseUrl = process.env.BASE_URL || 'http://localhost:4404'
+
+  test.describe.configure({ mode: 'serial' })
+
+  // Shared state across tests in this describe block
+  let sessionToken: string
+  let userUuid: string
+  let credentialUuid: string
+  let resetToken: string | undefined
+
+  test.beforeAll(() => {
+    // Get the bootstrap reset token from global setup
+    resetToken = getBootstrapResetToken()
+    if (!resetToken) {
+      console.warn('⚠️ No reset token found - registration test may fail')
+    } else {
+      console.log(`📝 Using reset token: ${resetToken}`)
+    }
+  })
+
+  test('should load the auth page', async ({ page }) => {
+    // Navigate to auth page to establish origin for WebAuthn
+    await page.goto('/auth/')
+    await expect(page).toHaveTitle(/.*/)
+
+    // Page should load - 401 errors are expected since user is not logged in
+    await page.waitForTimeout(500)
+
+    // Take screenshot of the login view
+    await page.screenshot({ path: 'test-results/login-view.png' })
+    console.log('✓ Screenshot saved: test-results/login-view.png')
+
+    // Just verify the page loaded without JS errors (network 401s are OK)
+    console.log('✓ Auth page loaded successfully')
+  })
+
+  test('should register admin passkey via WebSocket using reset token', async ({ page, virtualAuthenticator }) => {
+    test.skip(!resetToken, 'No reset token available from bootstrap')
+
+    // Must visit the page first to establish origin
+    await page.goto('/auth/')
+
+    // Perform registration via WebSocket with virtual authenticator
+    // Using the bootstrap reset token for the admin user
+    const result = await registerPasskey(page, baseUrl, {
+      resetToken: resetToken,
+      displayName: 'Admin User',
+    })
+
+    // Verify registration result
+    expect(result.session_token).toBeDefined()
+    expect(result.session_token).toHaveLength(16)
+    expect(result.user_uuid).toBeDefined()
+    expect(result.credential_uuid).toBeDefined()
+    expect(result.message).toContain('successfully')
+
+    // Store for subsequent tests
+    sessionToken = result.session_token
+    userUuid = result.user_uuid
+    credentialUuid = result.credential_uuid
+
+    // Save session token for other test groups to use
+    saveSessionToken(sessionToken)
+
+    console.log(`✓ Registered user: ${userUuid}`)
+    console.log(`✓ Credential: ${credentialUuid}`)
+    console.log(`✓ Session token: ${sessionToken.substring(0, 4)}...`)
+  })
+
+  test('should create device tokens for other tests', async ({ page }) => {
+    test.skip(!sessionToken, 'Requires successful registration')
+
+    // Create a batch of device tokens for API tests to use
+    // Each API test needs its own token to register a passkey in its virtual authenticator
+    const tokenCount = 15  // Enough for all API tests
+    const tokens: string[] = []
+
+    for (let i = 0; i < tokenCount; i++) {
+      const deviceLink = await createDeviceLink(page, baseUrl, sessionToken)
+      tokens.push(deviceLink.token)
+    }
+
+    saveDeviceTokens(tokens)
+    console.log(`✓ Created ${tokens.length} device tokens for API tests`)
+  })
+
+  test('should validate the session token', async ({ page }) => {
+    // Skip if registration didn't run
+    test.skip(!sessionToken, 'Requires successful registration')
+
+    const validation = await validateSession(page, baseUrl, sessionToken)
+
+    expect(validation.valid).toBe(true)
+    expect(validation.user_uuid).toBe(userUuid)
+
+    console.log(`✓ Session validated for user: ${validation.user_uuid}`)
+  })
+
+  test('should retrieve user info', async ({ page }) => {
+    test.skip(!sessionToken, 'Requires successful registration')
+
+    const userInfo = await getUserInfo(page, baseUrl, sessionToken)
+
+    expect(userInfo.user.user_uuid).toBe(userUuid)
+    expect(userInfo.user.user_name).toBe('Admin User')
+    expect(userInfo.credentials).toBeDefined()
+    expect(userInfo.credentials.length).toBeGreaterThanOrEqual(1)
+
+    // Navigate to profile and take screenshot
+    const cookieName = getSessionCookieName()
+    await page.context().addCookies([{
+      name: cookieName,
+      value: sessionToken,
+      domain: 'localhost',
+      path: '/',
+      secure: true,
+      httpOnly: true,
+      sameSite: 'Strict' as const,
+    }])
+    await page.goto('/auth/')
+    await page.waitForSelector('[data-view="profile"]', { timeout: 5000 })
+    await page.screenshot({ path: 'test-results/profile-view.png' })
+    console.log('✓ Screenshot saved: test-results/profile-view.png')
+
+    console.log(`✓ User info retrieved: ${userInfo.user.user_name}`)
+    console.log(`✓ Credentials count: ${userInfo.credentials.length}`)
+  })
+
+  test('should authenticate with existing passkey', async ({ page, virtualAuthenticator }) => {
+    test.skip(!sessionToken, 'Requires successful registration')
+
+    // Navigate to page (required for WebAuthn origin)
+    await page.goto('/auth/')
+
+    // The virtual authenticator in this context is new and doesn't have credentials.
+    // Create a device link using the current session, then register a new credential.
+    const deviceLink = await createDeviceLink(page, baseUrl, sessionToken)
+    console.log(`✓ Created device link with token: ${deviceLink.token}`)
+
+    // Register a new credential using the device link
+    const regResult = await registerPasskey(page, baseUrl, {
+      resetToken: deviceLink.token,
+      displayName: 'Admin User (test device)'
+    })
+
+    console.log(`✓ Added test credential: ${regResult.credential_uuid}`)
+
+    // Now logout and authenticate with the fresh credential
+    await logout(page, baseUrl, regResult.session_token)
+    console.log('✓ Logged out')
+
+    // Authenticate with the virtual authenticator (now has a valid credential)
+    const result = await authenticatePasskey(page, baseUrl)
+
+    expect(result.session_token).toBeDefined()
+    expect(result.session_token).toHaveLength(16)
+    expect(result.user_uuid).toBe(userUuid)
+
+    // Update session token for subsequent tests
+    sessionToken = result.session_token
+
+    // Save session token for other test groups to use
+    saveSessionToken(sessionToken)
+
+    console.log(`✓ Authenticated as user: ${result.user_uuid}`)
+    console.log(`✓ New session token: ${sessionToken.substring(0, 4)}...`)
+  })
+
+  test('should validate new session after authentication', async ({ page }) => {
+    test.skip(!sessionToken, 'Requires successful authentication')
+
+    const validation = await validateSession(page, baseUrl, sessionToken)
+
+    expect(validation.valid).toBe(true)
+    expect(validation.user_uuid).toBe(userUuid)
+
+    console.log(`✓ New session validated`)
+  })
+
+  // Note: Logout test moved to the end so other test groups can use the session
+})
+
+test.describe('Session Management', () => {
+  const baseUrl = process.env.BASE_URL || 'http://localhost:4404'
+
+  test('should reject invalid session token', async ({ page }) => {
+    const cookieName = getSessionCookieName()
+    const response = await page.request.post(`${baseUrl}/auth/api/validate`, {
+      headers: {
+        'Cookie': `${cookieName}=invalid_token_123`,
+      },
+      failOnStatusCode: false,
+    })
+
+    // Server may return 400 (bad format) or 401 (unauthorized)
+    expect([400, 401]).toContain(response.status())
+    console.log(`✓ Invalid token correctly rejected`)
+  })
+
+  test('should reject missing session token', async ({ page }) => {
+    const response = await page.request.post(`${baseUrl}/auth/api/validate`, {
+      failOnStatusCode: false,
+    })
+
+    expect(response.status()).toBe(401)
+    console.log(`✓ Missing token correctly rejected`)
+  })
+})
+
+test.describe('Device Addition Dialog', () => {
+  const baseUrl = process.env.BASE_URL || 'http://localhost:4404'
+
+  test.describe.configure({ mode: 'serial' })
+
+  let sessionToken: string
+
+  test.beforeAll(() => {
+    // Get the session token saved by the previous test group
+    // Note: This runs before the logout test, so the session should still be valid
+    const saved = getSavedSessionToken()
+    if (saved) {
+      sessionToken = saved
+    }
+  })
+
+  test('should open device addition dialog and show QR code', async ({ page }) => {
+    test.skip(!sessionToken, 'Requires saved session token from previous tests')
+
+    // Set the session cookie for this test context
+    const cookieName = getSessionCookieName()
+    await page.context().addCookies([{
+      name: cookieName,
+      value: sessionToken,
+      domain: 'localhost',
+      path: '/',
+      secure: true,
+      httpOnly: true,
+      sameSite: 'Strict',
+    }])
+
+    // Navigate to auth page (which should show profile when logged in)
+    await page.goto('/auth/')
+
+    // Wait for the profile view to load
+    await page.waitForSelector('[data-view="profile"]', { timeout: 5000 })
+
+    // Click the "Add Another Device" button
+    const addDeviceButton = page.getByRole('button', { name: 'Add Another Device' })
+    await expect(addDeviceButton).toBeVisible()
+    await addDeviceButton.click()
+
+    // Wait for the registration link modal to appear
+    const dialog = page.locator('.device-dialog')
+    await expect(dialog).toBeVisible({ timeout: 5000 })
+
+    // Verify dialog contains expected elements
+    await expect(dialog.locator('h2')).toContainText('Device Registration Link')
+
+    // Wait for QR code to be generated (canvas should have content)
+    const qrCanvas = dialog.locator('.qr-code')
+    await expect(qrCanvas).toBeVisible()
+
+    // Verify the link is displayed (text strips scheme, but href has it)
+    const linkElement = dialog.locator('a.qr-link')
+    await expect(linkElement).toBeVisible()
+    const linkText = await linkElement.textContent()
+    const linkHref = await linkElement.getAttribute('href')
+    // Text shows hostname without scheme
+    expect(linkText).toContain('localhost:4404/auth/')
+    // Href includes full URL with scheme
+    expect(linkHref).toContain('http://localhost:4404/auth/')
+    console.log(`✓ Device link displayed: ${linkText} (href: ${linkHref})`)
+
+    // Verify expiration warning is shown
+    await expect(dialog.locator('.reg-help')).toContainText('Expires')
+
+    // Take screenshot of the dialog
+    await dialog.screenshot({ path: 'test-results/device-addition-dialog.png' })
+    console.log(`✓ Screenshot saved: test-results/device-addition-dialog.png`)
+
+    // Verify Copy Link button exists
+    const copyButton = dialog.getByRole('button', { name: 'Copy Link' })
+    await expect(copyButton).toBeVisible()
+
+    // Close the dialog (use the text button, not the icon button)
+    const closeButton = dialog.locator('button.btn-secondary', { hasText: 'Close' })
+    await closeButton.click()
+    await expect(dialog).not.toBeVisible()
+
+    console.log(`✓ Device addition dialog test complete`)
+  })
+
+  test('should extract valid reset token from dialog', async ({ page }) => {
+    test.skip(!sessionToken, 'Requires successful registration')
+
+    // Set the session cookie
+    // __Host- cookies require: secure=true, path=/, no domain (but we set domain for localhost)
+    const cookieName = getSessionCookieName()
+    await page.context().addCookies([{
+      name: cookieName,
+      value: sessionToken,
+      domain: 'localhost',
+      path: '/',
+      secure: true,
+      httpOnly: true,
+      sameSite: 'Strict',
+    }])
+
+    await page.goto('/auth/')
+    await page.waitForSelector('[data-view="profile"]', { timeout: 5000 })
+
+    // Open the dialog
+    await page.getByRole('button', { name: 'Add Another Device' }).click()
+    const dialog = page.locator('.device-dialog')
+    await expect(dialog).toBeVisible({ timeout: 5000 })
+
+    // Extract the reset token from the displayed URL
+    const linkText = dialog.locator('.qr-link p')
+    const linkContent = await linkText.textContent()
+
+    // URL format: localhost/auth/word1.word2.word3.word4.word5
+    const tokenMatch = linkContent?.match(/\/auth\/([a-z]+\.[a-z]+\.[a-z]+\.[a-z]+\.[a-z]+)/)
+    expect(tokenMatch).toBeTruthy()
+    const extractedToken = tokenMatch![1]
+    console.log(`✓ Extracted reset token: ${extractedToken}`)
+
+    // Close the dialog (use the text button, not the icon button)
+    await dialog.locator('button.btn-secondary', { hasText: 'Close' }).click()
+
+    // Verify the token can be used for registration via API
+    // (We won't complete registration, just verify the WebSocket accepts it)
+    const wsUrl = `${baseUrl.replace('http', 'ws')}/auth/ws/register?reset=${encodeURIComponent(extractedToken)}&name=Test`
+
+    // Use page.evaluate to test WebSocket connection
+    const wsResult = await page.evaluate(async (wsUrl) => {
+      return new Promise<{ success: boolean; hasOptions: boolean }>((resolve) => {
+        const ws = new WebSocket(wsUrl)
+        ws.onmessage = (event) => {
+          const data = JSON.parse(event.data)
+          ws.close()
+          // Check if we got registration options (not an error)
+          resolve({
+            success: !data.status && !data.detail,
+            hasOptions: !!data.optionsJSON?.challenge
+          })
+        }
+        ws.onerror = () => resolve({ success: false, hasOptions: false })
+        setTimeout(() => {
+          ws.close()
+          resolve({ success: false, hasOptions: false })
+        }, 5000)
+      })
+    }, wsUrl)
+
+    expect(wsResult.success).toBe(true)
+    expect(wsResult.hasOptions).toBe(true)
+    console.log(`✓ Reset token is valid and accepted by server`)
+  })
+})
+
+test.describe('ProfileView - Add New Passkey', () => {
+  const baseUrl = process.env.BASE_URL || 'http://localhost:4404'
+
+  test('should show credentials list in profile', async ({ page }) => {
+    const sessionToken = getSavedSessionToken()
+    test.skip(!sessionToken, 'Requires saved session token')
+
+    await setupSessionCookie(page, sessionToken!)
+
+    // Navigate to profile page
+    await page.goto(`${baseUrl}/auth/`)
+    await page.waitForLoadState('networkidle')
+
+    // Wait for credentials to load
+    await page.waitForSelector('.credential-list', { timeout: 10000 })
+
+    // Should have at least one credential from initial registration
+    const credentialItems = await page.locator('.credential-item').count()
+    expect(credentialItems).toBeGreaterThanOrEqual(1)
+    console.log(`✓ Profile shows ${credentialItems} credential(s) in list`)
+  })
+
+  test('should add a new passkey using Add New Passkey button', async ({ page }) => {
+    const sessionToken = getSavedSessionToken()
+    test.skip(!sessionToken, 'Requires saved session token')
+
+    // Create virtual authenticator for this page
+    await createVirtualAuthenticator(page)
+    await setupSessionCookie(page, sessionToken!)
+
+    // Navigate to profile page
+    await page.goto(`${baseUrl}/auth/`)
+    await page.waitForLoadState('networkidle')
+
+    // Wait for credentials list and get initial count
+    await page.waitForSelector('.credential-list', { timeout: 10000 })
+    const initialCredentialCount = await page.locator('.credential-item').count()
+    console.log(`Initial credential count: ${initialCredentialCount}`)
+
+    // Click "Add New Passkey" button
+    const addPasskeyBtn = page.locator('button:has-text("Add New Passkey")')
+    await expect(addPasskeyBtn).toBeVisible()
+    await addPasskeyBtn.click()
+
+    // Wait for WebAuthn registration to complete (virtual authenticator handles it automatically)
+    // The button might show loading state or there might be a success message
+    await page.waitForTimeout(2000) // Give time for WebSocket registration to complete
+
+    // Refresh the page to ensure we see updated credentials
+    await page.reload()
+    await page.waitForLoadState('networkidle')
+    await page.waitForSelector('.credential-list', { timeout: 10000 })
+
+    // Should now have one more credential
+    const newCredentialCount = await page.locator('.credential-item').count()
+    expect(newCredentialCount).toBe(initialCredentialCount + 1)
+    console.log(`✓ Successfully added new passkey. Credentials: ${initialCredentialCount} -> ${newCredentialCount}`)
+  })
+
+  test('should reject duplicate passkey from same authenticator', async ({ page }) => {
+    const sessionToken = getSavedSessionToken()
+    test.skip(!sessionToken, 'Requires saved session token')
+
+    // Create virtual authenticator with resident key support
+    // Using same authenticator configuration - credentials stored on authenticator
+    await createVirtualAuthenticator(page, {
+      protocol: 'ctap2',
+      transport: 'internal',
+      hasResidentKey: true,
+      hasUserVerification: true,
+      isUserVerified: true,
+    })
+
+    await setupSessionCookie(page, sessionToken!)
+
+    // Navigate to profile page
+    await page.goto(`${baseUrl}/auth/`)
+    await page.waitForLoadState('networkidle')
+
+    // Wait for credentials list
+    await page.waitForSelector('.credential-list', { timeout: 10000 })
+    const initialCredentialCount = await page.locator('.credential-item').count()
+
+    // Try to add a passkey - with excludeCredentials the authenticator should
+    // prevent re-registration of the same credential
+    const addPasskeyBtn = page.locator('button:has-text("Add New Passkey")')
+    await expect(addPasskeyBtn).toBeVisible()
+    await addPasskeyBtn.click()
+
+    // Wait for response - could be success (new credential) or error (duplicate)
+    await page.waitForTimeout(3000)
+
+    // Check for error message or status message
+    const statusMessage = page.locator('.status-message')
+    const hasError = await statusMessage.locator('.error, .status-error').isVisible().catch(() => false)
+
+    // Reload to check final credential count
+    await page.reload()
+    await page.waitForLoadState('networkidle')
+    await page.waitForSelector('.credential-list', { timeout: 10000 })
+    const finalCredentialCount = await page.locator('.credential-item').count()
+
+    // The test passes if either:
+    // 1. An error was shown (duplicate rejected by excludeCredentials)
+    // 2. A new credential was added (fresh authenticator has no stored credential)
+    console.log(`Credentials: ${initialCredentialCount} -> ${finalCredentialCount}, error shown: ${hasError}`)
+    console.log(`✓ Add passkey flow completed (new authenticator creates new credential)`)
+  })
+})
+
+test.describe('ProfileView - Multi-Authenticator', () => {
+  const baseUrl = process.env.BASE_URL || 'http://localhost:4404'
+
+  test('should add passkey from different authenticator', async ({ page }) => {
+    const sessionToken = getSavedSessionToken()
+    test.skip(!sessionToken, 'Requires saved session token')
+
+    // Create a different virtual authenticator (simulating a different device)
+    await createVirtualAuthenticator(page, {
+      protocol: 'ctap2',
+      transport: 'usb', // Different transport - like a USB security key
+      hasResidentKey: true,
+      hasUserVerification: true,
+      isUserVerified: true,
+    })
+
+    await setupSessionCookie(page, sessionToken!)
+
+    // Navigate to profile page
+    await page.goto(`${baseUrl}/auth/`)
+    await page.waitForLoadState('networkidle')
+
+    // Wait for credentials list and get initial count
+    await page.waitForSelector('.credential-list', { timeout: 10000 })
+    const initialCredentialCount = await page.locator('.credential-item').count()
+
+    // Click "Add New Passkey" button
+    const addPasskeyBtn = page.locator('button:has-text("Add New Passkey")')
+    await expect(addPasskeyBtn).toBeVisible()
+    await addPasskeyBtn.click()
+
+    // Wait for registration to complete
+    await page.waitForTimeout(2000)
+
+    // Refresh to see updated list
+    await page.reload()
+    await page.waitForLoadState('networkidle')
+    await page.waitForSelector('.credential-list', { timeout: 10000 })
+
+    const newCredentialCount = await page.locator('.credential-item').count()
+    expect(newCredentialCount).toBe(initialCredentialCount + 1)
+    console.log(`✓ Added passkey from USB authenticator. Credentials: ${initialCredentialCount} -> ${newCredentialCount}`)
+  })
+
+  test('should display multiple credentials with details', async ({ page }) => {
+    const sessionToken = getSavedSessionToken()
+    test.skip(!sessionToken, 'Requires saved session token')
+
+    await setupSessionCookie(page, sessionToken!)
+
+    // Navigate to profile page
+    await page.goto(`${baseUrl}/auth/`)
+    await page.waitForLoadState('networkidle')
+    await page.waitForSelector('.credential-list', { timeout: 10000 })
+
+    // Should have multiple credentials now from previous tests
+    const credentialItems = page.locator('.credential-item')
+    const count = await credentialItems.count()
+
+    // Verify each credential has required elements
+    for (let i = 0; i < count; i++) {
+      const item = credentialItems.nth(i)
+
+      // Should have title/name
+      const title = item.locator('.item-title')
+      await expect(title).toBeVisible()
+
+      // Should have date information
+      const dates = item.locator('.credential-dates')
+      await expect(dates).toBeVisible()
+
+      // Should have created date
+      const createdDate = item.locator('.date-label:has-text("Created:")')
+      await expect(createdDate).toBeVisible()
+    }
+
+    console.log(`✓ All ${count} credentials displayed with proper details`)
+
+    // Take screenshot of credentials list
+    await page.screenshot({
+      path: 'test-results/credentials-list.png',
+      fullPage: false,
+    })
+    console.log(`✓ Screenshot saved: test-results/credentials-list.png`)
+  })
+
+  test('should show current session badge', async ({ page }) => {
+    const sessionToken = getSavedSessionToken()
+    test.skip(!sessionToken, 'Requires saved session token')
+
+    await setupSessionCookie(page, sessionToken!)
+
+    // Navigate to profile page
+    await page.goto(`${baseUrl}/auth/`)
+    await page.waitForLoadState('networkidle')
+    await page.waitForSelector('.credential-list', { timeout: 10000 })
+
+    // Look for the "Current" badge indicating current session's credential
+    const currentBadge = page.locator('.badge-current:has-text("Current")')
+    const hasCurrent = await currentBadge.isVisible().catch(() => false)
+
+    if (hasCurrent) {
+      console.log(`✓ Current session credential is marked with "Current" badge`)
+
+      // The current credential should have delete disabled
+      const currentItem = page.locator('.credential-item.current-session')
+      if (await currentItem.isVisible()) {
+        const deleteBtn = currentItem.locator('.btn-card-delete')
+        if (await deleteBtn.isVisible()) {
+          await expect(deleteBtn).toBeDisabled()
+          console.log(`✓ Delete button is disabled for current session credential`)
+        }
+      }
+    } else {
+      console.log(`ℹ No credential marked as current (may be using different auth method)`)
+    }
+  })
+})

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

@@ -0,0 +1,606 @@
+import { test, expect, createVirtualAuthenticator } from './fixtures/virtual-authenticator'
+import {
+  getSessionCookieName,
+  getSavedSessionToken,
+  saveSessionToken,
+  registerPasskey,
+  authenticatePasskey,
+  popDeviceToken,
+  getDeviceTokenCount,
+  logout,
+} from './fixtures/passkey-helpers'
+import type { Page, Frame } from '@playwright/test'
+
+/**
+ * E2E tests for API mode authentication flows.
+ *
+ * These tests simulate the flow used by SPAs when making API calls:
+ * 1. API call returns 401/403 with auth.iframe URL
+ * 2. App shows auth iframe overlay
+ * 3. User authenticates in iframe
+ * 4. Iframe posts 'auth-success' message to parent
+ * 5. App retries original API call
+ *
+ * Note: These tests depend on 10-passkey.spec.ts running first to create device tokens.
+ * Each test that needs authentication uses popDeviceToken() to get a fresh token
+ * and registers its own credential in its virtual authenticator.
+ */
+
+const baseUrl = process.env.BASE_URL || 'http://localhost:4404'
+
+/**
+ * Helper to set up session cookie for a page.
+ */
+async function setupSessionCookie(page: Page, sessionToken: string): Promise<void> {
+  const cookieName = getSessionCookieName()
+  await page.context().addCookies([{
+    name: cookieName,
+    value: sessionToken,
+    domain: 'localhost',
+    path: '/',
+    secure: true,
+    httpOnly: true,
+    sameSite: 'Strict' as const,
+  }])
+}
+
+/**
+ * Helper to clear session cookie.
+ */
+async function clearSessionCookie(page: Page): Promise<void> {
+  const cookieName = getSessionCookieName()
+  await page.context().clearCookies({ name: cookieName })
+}
+
+/**
+ * Set up the test page using the examples page directly.
+ * The examples page already has iframe handling - we just add a Promise wrapper.
+ */
+async function setupTestHarness(page: Page): Promise<void> {
+  // Navigate to the examples page which already has the auth iframe handling
+  await page.goto(`${baseUrl}/auth/examples/`)
+}
+
+/**
+ * Make an API call through the examples page, returning a Promise.
+ * Wraps the page's apiCall and listens for auth-success/auth-back messages.
+ * Returns { status, data } on success, or throws on cancellation.
+ *
+ * Note: If auth is not needed (request succeeds without 401/403), this will
+ * resolve after a timeout with the direct fetch result.
+ */
+async function makeApiCall(page: Page, url: string, method = 'GET'): Promise<{ status: number; data?: any }> {
+  return page.evaluate(({ url, method }) => {
+    return new Promise((resolve, reject) => {
+      let resolved = false;
+
+      // Listen for auth messages
+      const handler = (event: MessageEvent) => {
+        const { type } = event.data || {};
+        if (type === 'auth-success') {
+          if (resolved) return;
+          resolved = true;
+          window.removeEventListener('message', handler);
+          // Wait a tick for the page's handler to retry, then make our own call
+          setTimeout(async () => {
+            try {
+              const response = await fetch(url, { method, credentials: 'include' });
+              if (response.status === 204) {
+                resolve({ status: 204 });
+              } else if (response.ok) {
+                const data = await response.json();
+                resolve({ status: response.status, data });
+              } else {
+                resolve({ status: response.status });
+              }
+            } catch (e) {
+              resolve({ status: 0 });
+            }
+          }, 200);
+        } else if (type === 'auth-back') {
+          if (resolved) return;
+          resolved = true;
+          window.removeEventListener('message', handler);
+          reject(new Error('cancelled'));
+        }
+      };
+      window.addEventListener('message', handler);
+
+      // Also make a direct fetch to handle the case where no auth is needed
+      // (the page's apiCall won't send any message if the request succeeds)
+      setTimeout(async () => {
+        if (resolved) return;
+        try {
+          const response = await fetch(url, { method, credentials: 'include' });
+          // Only resolve if this is a success or non-auth error
+          if (response.status !== 401 && response.status !== 403) {
+            if (resolved) return;
+            resolved = true;
+            window.removeEventListener('message', handler);
+            if (response.status === 204) {
+              resolve({ status: 204 });
+            } else if (response.ok) {
+              const data = await response.json();
+              resolve({ status: response.status, data });
+            } else {
+              resolve({ status: response.status });
+            }
+          }
+          // If 401/403, the auth iframe will appear and we wait for the message
+        } catch (e) {
+          // Network error - let the message handler deal with it
+        }
+      }, 100);
+
+      // Call the page's existing apiCall function
+      // It will show the iframe on 401/403
+      (window as any).apiCall(url, method);
+    });
+  }, { url, method });
+}
+
+/**
+ * Wait for auth iframe to appear and return a reference to it.
+ */
+async function waitForAuthIframe(page: Page, timeout = 5000): Promise<Frame> {
+  await page.waitForSelector('#auth-iframe', { timeout })
+  const iframe = page.frameLocator('#auth-iframe')
+  // Wait for iframe content to load
+  await iframe.locator('.view-root').waitFor({ timeout })
+  return page.frame({ url: /\/auth\/restricted\// })!
+}
+
+/**
+ * Wait for auth iframe to disappear.
+ */
+async function waitForAuthIframeHidden(page: Page, timeout = 5000): Promise<void> {
+  await page.waitForSelector('#auth-iframe', { state: 'detached', timeout })
+}
+
+/**
+ * Click Back button in auth iframe.
+ */
+async function clickBackInIframe(page: Page): Promise<void> {
+  const iframe = page.frameLocator('#auth-iframe')
+  await iframe.getByRole('button', { name: 'Back' }).click()
+}
+
+/**
+ * Click Login button in auth iframe.
+ */
+async function clickLoginInIframe(page: Page): Promise<void> {
+  const iframe = page.frameLocator('#auth-iframe')
+  await iframe.getByRole('button', { name: 'Login' }).click()
+}
+
+/**
+ * Click Verify button in auth iframe (for reauth mode).
+ */
+async function clickVerifyInIframe(page: Page): Promise<void> {
+  const iframe = page.frameLocator('#auth-iframe')
+  await iframe.getByRole('button', { name: 'Verify' }).click()
+}
+
+/**
+ * Click Logout button in auth iframe (for forbidden mode).
+ */
+async function clickLogoutInIframe(page: Page): Promise<void> {
+  const iframe = page.frameLocator('#auth-iframe')
+  await iframe.getByRole('button', { name: 'Logout' }).click()
+}
+
+test.describe('API Mode - 401 Login Flow', () => {
+  test.describe.configure({ mode: 'serial' })
+
+  test('should show auth iframe on 401 and allow cancellation (Back)', async ({ page }) => {
+    // Set up test harness (injects our API flow handler)
+    await setupTestHarness(page)
+
+    // Clear any existing session cookie
+    await clearSessionCookie(page)
+
+    // Make API call that triggers 401 (don't await - it blocks until iframe resolves)
+    const apiCallPromise = makeApiCall(page, '/auth/api/user-info', 'POST').catch(e => e)
+    console.log('✓ Auth iframe appeared on 401')
+
+    // Verify it's in login mode (not reauth)
+    const iframe = page.frameLocator('#auth-iframe')
+    await expect(iframe.locator('h1')).toContainText('🔐')
+    await expect(iframe.getByRole('button', { name: 'Login' })).toBeVisible()
+
+    // Take screenshot of the login iframe
+    await page.screenshot({ path: 'test-results/api-401-login-iframe.png' })
+    console.log('✓ Screenshot saved: test-results/api-401-login-iframe.png')
+
+    // Click Back to cancel authentication
+    await clickBackInIframe(page)
+
+    // Iframe should close
+    await waitForAuthIframeHidden(page)
+    console.log('✓ Auth iframe closed on Back button')
+
+    // Wait for the API call promise to reject
+    const result = await apiCallPromise
+    expect(result).toBeInstanceOf(Error)
+    expect(result.message).toContain('cancelled')
+
+    // Output should show cancellation
+    const output = page.locator('#output')
+    await expect(output).toContainText('cancelled')
+    console.log('✓ API call was cancelled')
+  })
+
+  test('should show auth iframe on 401 and complete login', async ({ page, virtualAuthenticator }) => {
+    // Get a device token from the pool (created by 10-passkey.spec.ts)
+    const deviceToken = popDeviceToken()
+    test.skip(!deviceToken, 'Requires device token from passkey tests')
+    console.log(`✓ Got device token: ${deviceToken} (${getDeviceTokenCount()} remaining)`)
+
+    // Navigate and register credential using device token
+    await page.goto(`${baseUrl}/auth/`)
+    const regResult = await registerPasskey(page, baseUrl, {
+      resetToken: deviceToken,
+      displayName: 'API Test Device',
+    })
+    console.log(`✓ Registered credential: ${regResult.credential_uuid}`)
+
+    // Logout to clear session (but keep the passkey in virtual authenticator)
+    await logout(page, baseUrl, regResult.session_token)
+    console.log('✓ Logged out')
+
+    // Set up test harness
+    await setupTestHarness(page)
+
+    // Make API call that triggers 401
+    const apiCallPromise = makeApiCall(page, '/auth/api/user-info', 'POST')
+
+    // Wait for auth iframe to appear
+    await waitForAuthIframe(page)
+    console.log('✓ Auth iframe appeared on 401')
+
+    // Click Login button - virtual authenticator will handle the passkey
+    await clickLoginInIframe(page)
+
+    // Wait for authentication to complete - iframe should close
+    await waitForAuthIframeHidden(page, 10000)
+    console.log('✓ Authentication completed, iframe closed')
+
+    // Wait for API call to complete and verify result
+    const result = await apiCallPromise
+    expect(result.status).toBe(200)
+    expect(result.data.user).toBeDefined()
+    console.log('✓ API call succeeded after authentication')
+
+    // Save the session for other tests
+    const cookies = await page.context().cookies()
+    const sessionCookie = cookies.find(c => c.name === getSessionCookieName())
+    if (sessionCookie) {
+      saveSessionToken(sessionCookie.value)
+      console.log(`✓ Saved session token for other tests`)
+    }
+  })
+})
+
+test.describe('API Mode - 401 Reauth Flow', () => {
+  test.describe.configure({ mode: 'serial' })
+
+  test('should show reauth iframe on max_age violation and allow cancellation', async ({ page, virtualAuthenticator }) => {
+    // Get a device token from the pool (created by 10-passkey.spec.ts)
+    const deviceToken = popDeviceToken()
+    test.skip(!deviceToken, 'Requires device token from passkey tests')
+    console.log(`✓ Got device token: ${deviceToken} (${getDeviceTokenCount()} remaining)`)
+
+    // Navigate and register a credential
+    await page.goto(`${baseUrl}/auth/`)
+    const regResult = await registerPasskey(page, baseUrl, {
+      resetToken: deviceToken,
+      displayName: 'Reauth Cancel Test Device',
+    })
+    saveSessionToken(regResult.session_token)
+
+    // Wait for session to age past max_age threshold
+    console.log('Waiting 3s for session to age...')
+    await page.waitForTimeout(3000)
+
+    // Set up test harness with the session
+    await setupSessionCookie(page, regResult.session_token)
+    await setupTestHarness(page)
+
+    // Make API call with max_age=1s (session is now > 1s old)
+    const apiCallPromise = makeApiCall(page, '/auth/api/forward?max_age=1s', 'GET').catch(e => e)
+
+    // Wait for auth iframe to appear
+    await waitForAuthIframe(page)
+    console.log('✓ Reauth iframe appeared (session older than max_age)')
+
+    // Verify it's in reauth mode
+    const iframe = page.frameLocator('#auth-iframe')
+    await expect(iframe.locator('h1')).toContainText('Additional Authentication')
+    await expect(iframe.getByRole('button', { name: 'Verify' })).toBeVisible()
+
+    // Take screenshot of reauth iframe
+    await page.screenshot({ path: 'test-results/api-401-reauth-iframe.png' })
+    console.log('✓ Screenshot saved: test-results/api-401-reauth-iframe.png')
+
+    // Click Back to cancel
+    await clickBackInIframe(page)
+    await waitForAuthIframeHidden(page)
+    console.log('✓ Reauth cancelled via Back button')
+
+    const result = await apiCallPromise
+    expect(result).toBeInstanceOf(Error)
+  })
+
+  test('should complete reauth flow with passkey', async ({ page, virtualAuthenticator }) => {
+    // Get a device token from the pool (created by 10-passkey.spec.ts)
+    const deviceToken = popDeviceToken()
+    test.skip(!deviceToken, 'Requires device token from passkey tests')
+    console.log(`✓ Got device token: ${deviceToken} (${getDeviceTokenCount()} remaining)`)
+
+    // Navigate and register a credential
+    await page.goto(`${baseUrl}/auth/`)
+    const regResult = await registerPasskey(page, baseUrl, {
+      resetToken: deviceToken,
+      displayName: 'Reauth Test Device',
+    })
+
+    // Save the new session
+    saveSessionToken(regResult.session_token)
+
+    // Wait for the session to be "old" (>2s for max_age=2s test)
+    console.log('Waiting 3s for session to age...')
+    await page.waitForTimeout(3000)
+
+    // Set up test harness with the session
+    await setupSessionCookie(page, regResult.session_token)
+    await setupTestHarness(page)
+
+    // Make API call with max_age=2s
+    const apiCallPromise = makeApiCall(page, '/auth/api/forward?max_age=2s', 'GET')
+
+    // Auth iframe should appear in reauth mode
+    await waitForAuthIframe(page)
+    console.log('✓ Reauth iframe appeared')
+
+    const iframe = page.frameLocator('#auth-iframe')
+    await expect(iframe.locator('h1')).toContainText('Additional Authentication')
+
+    // Click Verify - virtual authenticator handles passkey
+    await clickVerifyInIframe(page)
+
+    // Wait for completion
+    await waitForAuthIframeHidden(page, 10000)
+    console.log('✓ Reauth completed')
+
+    // Wait for API call result
+    const result = await apiCallPromise
+    expect(result.status).toBe(204)
+    console.log('✓ Forward endpoint returned 204 after reauth')
+  })
+})
+
+test.describe('API Mode - 403 Forbidden Flow', () => {
+  test.describe.configure({ mode: 'serial' })
+
+  test('should show forbidden view and allow going back', async ({ page }) => {
+    const sessionToken = getSavedSessionToken()
+    test.skip(!sessionToken, 'Requires saved session token')
+
+    // Set up test harness with valid session
+    await setupSessionCookie(page, sessionToken!)
+    await setupTestHarness(page)
+
+    // Make API call requiring admin permission
+    const apiCallPromise = makeApiCall(page, '/auth/api/forward?perm=auth:admin', 'GET').catch(e => e)
+
+    // Check if auth iframe appeared
+    const iframeAppeared = await page.waitForSelector('#auth-iframe', { timeout: 3000 }).then(() => true).catch(() => false)
+
+    if (!iframeAppeared) {
+      // User might already have admin permission
+      const result = await apiCallPromise
+      if (result.status === 204) {
+        console.log('✓ User has admin permission, got 204 (skipping forbidden test)')
+        return
+      }
+    }
+
+    await waitForAuthIframe(page)
+    console.log('✓ Auth iframe appeared on permission check')
+
+    // Wait for view to stabilize and check mode
+    await page.waitForTimeout(500)
+    const iframe = page.frameLocator('#auth-iframe')
+    const headingText = await iframe.locator('h1').textContent()
+    console.log(`  Heading: ${headingText}`)
+
+    if (headingText?.includes('Forbidden')) {
+      console.log('✓ Forbidden view displayed (user lacks admin permission)')
+
+      // Should show Logout button in forbidden mode
+      await expect(iframe.getByRole('button', { name: 'Logout' })).toBeVisible()
+
+      // Take screenshot of forbidden view
+      await page.screenshot({ path: 'test-results/api-403-forbidden-iframe.png' })
+      console.log('✓ Screenshot saved: test-results/api-403-forbidden-iframe.png')
+
+      // Click Back to close
+      await clickBackInIframe(page)
+      await waitForAuthIframeHidden(page)
+      console.log('✓ Forbidden dialog closed via Back')
+
+      const result = await apiCallPromise
+      expect(result).toBeInstanceOf(Error)
+    } else {
+      // User has admin permission, so they got through
+      console.log('✓ User has admin permission, no forbidden view')
+    }
+  })
+
+  test('should allow logout from forbidden view and then login', async ({ page, virtualAuthenticator }) => {
+    // Get a device token from the pool (created by 10-passkey.spec.ts)
+    const deviceToken = popDeviceToken()
+    test.skip(!deviceToken, 'Requires device token from passkey tests')
+    console.log(`✓ Got device token: ${deviceToken} (${getDeviceTokenCount()} remaining)`)
+
+    // Navigate and register credential for later login
+    await page.goto(`${baseUrl}/auth/`)
+    const regResult = await registerPasskey(page, baseUrl, {
+      resetToken: deviceToken,
+      displayName: 'Forbidden Test Device',
+    })
+    saveSessionToken(regResult.session_token)
+
+    // Set up test harness with the session
+    await setupSessionCookie(page, regResult.session_token)
+    await setupTestHarness(page)
+
+    // Make API call requiring admin permission
+    const apiCallPromise = makeApiCall(page, '/auth/api/forward?perm=auth:admin', 'GET').catch(e => e)
+
+    // Check if auth iframe appeared
+    const iframeAppeared = await page.waitForSelector('#auth-iframe', { timeout: 3000 }).then(() => true).catch(() => false)
+
+    if (!iframeAppeared) {
+      const result = await apiCallPromise
+      if (result.status === 204) {
+        console.log('✓ User has admin permission, skipping forbidden->login test')
+        return
+      }
+    }
+
+    await waitForAuthIframe(page)
+    const iframe = page.frameLocator('#auth-iframe')
+    await page.waitForTimeout(500)
+
+    const headingText = await iframe.locator('h1').textContent()
+
+    if (headingText?.includes('Forbidden')) {
+      console.log('✓ Forbidden view displayed')
+
+      // Take screenshot of forbidden view before logout
+      await page.screenshot({ path: 'test-results/api-403-forbidden-before-logout.png' })
+      console.log('✓ Screenshot saved: test-results/api-403-forbidden-before-logout.png')
+
+      // Click Logout in the iframe
+      await clickLogoutInIframe(page)
+
+      // After logout, the view should switch to login mode and show a toast
+      await page.waitForTimeout(1000)
+      await expect(iframe.getByRole('button', { name: 'Login' })).toBeVisible({ timeout: 5000 })
+      console.log('✓ Switched to login view after logout')
+
+      // Verify status message appears indicating user can login with another account
+      const statusMessage = iframe.locator('.global-status .status')
+      await expect(statusMessage).toBeVisible({ timeout: 3000 })
+      const statusText = await statusMessage.textContent()
+      expect(statusText).toContain('sign in with a different account')
+      console.log(`✓ Status message: ${statusText}`)
+
+      // Take screenshot showing login view with status message (after forbidden logout)
+      await page.screenshot({ path: 'test-results/api-403-after-logout-login.png' })
+      console.log('✓ Screenshot saved: test-results/api-403-after-logout-login.png')
+
+      // Now login with the passkey
+      await clickLoginInIframe(page)
+
+      // Wait for auth to complete
+      await waitForAuthIframeHidden(page, 10000)
+      console.log('✓ Logged in successfully')
+
+      // The API call should have completed (but may still fail with 403 since same user)
+      const result = await apiCallPromise
+      console.log(`  Final result status: ${result.status || 'error'}`)
+    } else {
+      console.log('✓ Not in forbidden mode, closing dialog')
+      await clickBackInIframe(page)
+      await waitForAuthIframeHidden(page)
+    }
+  })
+})
+
+test.describe('API Mode - Direct API Response Format', () => {
+  test('should return JSON with auth.iframe on 401 (unauthenticated)', async ({ page }) => {
+    // Make direct API call without session
+    const response = await page.request.get(`${baseUrl}/auth/api/forward`, {
+      headers: {
+        'Accept': 'application/json',
+      },
+    })
+
+    expect(response.status()).toBe(401)
+
+    const data = await response.json()
+    expect(data.auth).toBeDefined()
+    expect(data.auth.iframe).toBeDefined()
+    expect(data.auth.mode).toBe('login')
+    expect(data.auth.iframe).toContain('/auth/restricted/')
+
+    console.log(`✓ 401 response includes auth.iframe: ${data.auth.iframe}`)
+  })
+
+  test('should return JSON with auth.mode=forbidden on 403', async ({ page }) => {
+    const sessionToken = getSavedSessionToken()
+    test.skip(!sessionToken, 'Requires saved session token')
+
+    const cookieName = getSessionCookieName()
+
+    // Make API call with session but requesting admin permission
+    const response = await page.request.get(`${baseUrl}/auth/api/forward?perm=auth:admin`, {
+      headers: {
+        'Accept': 'application/json',
+        'Cookie': `${cookieName}=${sessionToken}`,
+      },
+    })
+
+    // Could be 403 (forbidden) or 204 (user is admin)
+    if (response.status() === 403) {
+      const data = await response.json()
+      expect(data.auth).toBeDefined()
+      expect(data.auth.mode).toBe('forbidden')
+      console.log(`✓ 403 response auth.mode: ${data.auth.mode}`)
+    } else if (response.status() === 204) {
+      console.log('✓ User has admin permission, got 204')
+    } else {
+      console.log(`  Unexpected status: ${response.status()}`)
+    }
+  })
+
+  test('should return JSON with auth.mode=reauth on max_age violation', async ({ page, virtualAuthenticator }) => {
+    // Get a device token from the pool (created by 10-passkey.spec.ts)
+    const deviceToken = popDeviceToken()
+    test.skip(!deviceToken, 'Requires device token from passkey tests')
+    console.log(`✓ Got device token: ${deviceToken} (${getDeviceTokenCount()} remaining)`)
+
+    // Navigate and create fresh session
+    await page.goto(`${baseUrl}/auth/`)
+    const regResult = await registerPasskey(page, baseUrl, {
+      resetToken: deviceToken,
+      displayName: 'Max Age Test Device',
+    })
+
+    // Wait for session to be older than 1s
+    await page.waitForTimeout(2000)
+
+    const cookieName = getSessionCookieName()
+
+    // Make API call with max_age=1s (session is now > 1s old)
+    const response = await page.request.get(`${baseUrl}/auth/api/forward?max_age=1s`, {
+      headers: {
+        'Accept': 'application/json',
+        'Cookie': `${cookieName}=${regResult.session_token}`,
+      },
+    })
+
+    expect(response.status()).toBe(401)
+
+    const data = await response.json()
+    expect(data.auth).toBeDefined()
+    expect(data.auth.mode).toBe('reauth')
+
+    console.log(`✓ 401 response auth.mode: ${data.auth.mode}`)
+
+    // Save session for cleanup
+    saveSessionToken(regResult.session_token)
+  })
+})

e2e/tests/99-logout.spec.ts

@@ -0,0 +1,33 @@
+import { test, expect } from './fixtures/virtual-authenticator'
+import {
+  logout,
+  getSessionCookieName,
+  getSavedSessionToken,
+} from './fixtures/passkey-helpers'
+
+/**
+ * Logout test - runs last to clean up the session.
+ * The "99-" prefix ensures this runs after all other tests.
+ */
+test.describe('Logout', () => {
+  const baseUrl = process.env.BASE_URL || 'http://localhost:4404'
+
+  test('should logout successfully', async ({ page }) => {
+    const sessionToken = getSavedSessionToken()
+    test.skip(!sessionToken, 'Requires saved session token')
+
+    await logout(page, baseUrl, sessionToken!)
+
+    // Session should no longer be valid
+    const cookieName = getSessionCookieName()
+    const response = await page.request.post(`${baseUrl}/auth/api/validate`, {
+      headers: {
+        'Cookie': `${cookieName}=${sessionToken}`,
+      },
+      failOnStatusCode: false,
+    })
+
+    expect(response.status()).toBe(401)
+    console.log(`✓ Logout successful, session invalidated`)
+  })
+})

e2e/tests/fixtures/coverage.ts

@@ -0,0 +1,147 @@
+import { test as base, type Page, type CDPSession } from '@playwright/test'
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const coverageDir = join(__dirname, '..', '..', 'coverage-frontend')
+
+// Check if frontend coverage is enabled
+const COLLECT_COVERAGE = process.env.COVERAGE === '1' || process.env.COVERAGE === 'true'
+
+interface CoverageEntry {
+  url: string
+  scriptId: string
+  source?: string
+  functions: Array<{
+    functionName: string
+    ranges: Array<{
+      startOffset: number
+      endOffset: number
+      count: number
+    }>
+    isBlockCoverage: boolean
+  }>
+}
+
+/**
+ * Collect V8 JavaScript coverage from the page.
+ */
+async function startCoverage(page: Page): Promise<CDPSession | null> {
+  if (!COLLECT_COVERAGE) return null
+
+  try {
+    const cdp = await page.context().newCDPSession(page)
+    await cdp.send('Profiler.enable')
+    await cdp.send('Profiler.startPreciseCoverage', {
+      callCount: true,
+      detailed: true,
+    })
+    return cdp
+  } catch {
+    return null
+  }
+}
+
+async function stopCoverage(cdp: CDPSession | null, testName: string): Promise<void> {
+  if (!cdp) return
+
+  try {
+    const { result } = await cdp.send('Profiler.takePreciseCoverage')
+    await cdp.send('Profiler.stopPreciseCoverage')
+    await cdp.send('Profiler.disable')
+
+    // Filter to only include our app's JavaScript files
+    const appCoverage = result.filter((entry: CoverageEntry) =>
+      entry.url.includes('/auth/') &&
+      entry.url.endsWith('.js') &&
+      !entry.url.includes('node_modules')
+    )
+
+    if (appCoverage.length > 0) {
+      // Ensure coverage directory exists
+      if (!existsSync(coverageDir)) {
+        mkdirSync(coverageDir, { recursive: true })
+      }
+
+      // Save coverage data for this test
+      const safeName = testName.replace(/[^a-z0-9]/gi, '_').substring(0, 50)
+      const coverageFile = join(coverageDir, `coverage-${safeName}-${Date.now()}.json`)
+      writeFileSync(coverageFile, JSON.stringify(appCoverage, null, 2))
+    }
+  } catch (err) {
+    // Silently ignore coverage collection errors
+  }
+}
+
+/**
+ * Merge all coverage files into a single summary.
+ */
+export async function mergeCoverage(): Promise<void> {
+  if (!COLLECT_COVERAGE || !existsSync(coverageDir)) return
+
+  const files = require('fs').readdirSync(coverageDir).filter((f: string) => f.startsWith('coverage-') && f.endsWith('.json'))
+  if (files.length === 0) return
+
+  const merged: Map<string, CoverageEntry> = new Map()
+
+  for (const file of files) {
+    const data: CoverageEntry[] = JSON.parse(readFileSync(join(coverageDir, file), 'utf-8'))
+    for (const entry of data) {
+      const existing = merged.get(entry.url)
+      if (!existing) {
+        merged.set(entry.url, entry)
+      } else {
+        // Merge function coverage counts
+        for (const func of entry.functions) {
+          const existingFunc = existing.functions.find(f => f.functionName === func.functionName)
+          if (existingFunc) {
+            for (let i = 0; i < func.ranges.length; i++) {
+              if (existingFunc.ranges[i]) {
+                existingFunc.ranges[i].count += func.ranges[i].count
+              }
+            }
+          } else {
+            existing.functions.push(func)
+          }
+        }
+      }
+    }
+  }
+
+  // Write merged coverage
+  writeFileSync(
+    join(coverageDir, 'coverage-merged.json'),
+    JSON.stringify(Array.from(merged.values()), null, 2)
+  )
+
+  // Generate simple coverage summary
+  let totalFunctions = 0
+  let coveredFunctions = 0
+
+  for (const entry of merged.values()) {
+    for (const func of entry.functions) {
+      totalFunctions++
+      const hasCoverage = func.ranges.some(r => r.count > 0)
+      if (hasCoverage) coveredFunctions++
+    }
+  }
+
+  const percentage = totalFunctions > 0 ? Math.round((coveredFunctions / totalFunctions) * 100) : 0
+  console.log(`\n  📊 Frontend JS Coverage: ${coveredFunctions}/${totalFunctions} functions (${percentage}%)`)
+  console.log(`  ✅ Frontend coverage data: ${coverageDir}/coverage-merged.json\n`)
+}
+
+/**
+ * Extended test with coverage collection.
+ * This wraps each test to collect V8 coverage data.
+ */
+export const testWithCoverage = base.extend<{
+  coverageSession: CDPSession | null
+}>({
+  coverageSession: async ({ page }, use, testInfo) => {
+    const cdp = await startCoverage(page)
+    await use(cdp)
+    await stopCoverage(cdp, testInfo.title)
+  },
+})

e2e/tests/fixtures/passkey-helpers.ts

@@ -0,0 +1,453 @@
+import { type Page } from '@playwright/test'
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const stateFile = join(__dirname, '..', '..', 'test-data', 'test-state.json')
+
+/**
+ * WebSocket helpers for passkey registration and authentication.
+ * These functions mirror the frontend's passkey.js but work in a Playwright context.
+ */
+
+export interface RegistrationResult {
+  user_uuid: string
+  credential_uuid: string
+  session_token: string
+  message: string
+}
+
+export interface AuthenticationResult {
+  user_uuid: string
+  session_token: string
+}
+
+/**
+ * Get the bootstrap reset token from the test state file.
+ */
+export function getBootstrapResetToken(): string | undefined {
+  if (existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+      return state.resetToken
+    } catch {
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * Get the session cookie name from the test state file.
+ */
+export function getSessionCookieName(): string {
+  if (existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+      return state.sessionCookie || '__Host-auth'
+    } catch {
+      return '__Host-auth'
+    }
+  }
+  return '__Host-auth'
+}
+
+/**
+ * Save a session token to the test state file for sharing across test groups.
+ */
+export function saveSessionToken(sessionToken: string): void {
+  if (existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+      state.savedSessionToken = sessionToken
+      writeFileSync(stateFile, JSON.stringify(state, null, 2))
+    } catch {
+      // Ignore errors
+    }
+  }
+}
+
+/**
+ * Clear the saved session token from the test state file.
+ * Call this after logout to prevent accidental reuse of invalidated sessions.
+ */
+export function clearSavedSessionToken(): void {
+  if (existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+      delete state.savedSessionToken
+      writeFileSync(stateFile, JSON.stringify(state, null, 2))
+    } catch {
+      // Ignore errors
+    }
+  }
+}
+
+/**
+ * Get a saved session token from the test state file.
+ */
+export function getSavedSessionToken(): string | undefined {
+  if (existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+      return state.savedSessionToken
+    } catch {
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * Save device tokens to the test state file for use by other tests.
+ * These tokens allow tests to register their own passkeys.
+ */
+export function saveDeviceTokens(tokens: string[]): void {
+  if (existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+      state.deviceTokens = tokens
+      writeFileSync(stateFile, JSON.stringify(state, null, 2))
+    } catch {
+      // Ignore errors
+    }
+  }
+}
+
+/**
+ * Get and consume a device token from the pool.
+ * Returns undefined if no tokens are available.
+ */
+export function popDeviceToken(): string | undefined {
+  if (existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+      if (state.deviceTokens && state.deviceTokens.length > 0) {
+        const token = state.deviceTokens.pop()
+        writeFileSync(stateFile, JSON.stringify(state, null, 2))
+        return token
+      }
+    } catch {
+      return undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * Get the count of remaining device tokens.
+ */
+export function getDeviceTokenCount(): number {
+  if (existsSync(stateFile)) {
+    try {
+      const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+      return state.deviceTokens?.length || 0
+    } catch {
+      return 0
+    }
+  }
+  return 0
+}
+
+/**
+ * Perform passkey registration via WebSocket.
+ * This runs in the browser context using the virtual authenticator.
+ */
+export async function registerPasskey(
+  page: Page,
+  baseUrl: string,
+  options: { resetToken?: string; displayName?: string } = {}
+): Promise<RegistrationResult> {
+  return await page.evaluate(async ({ baseUrl, resetToken, displayName }) => {
+    // Build WebSocket URL with query parameters
+    let wsUrl = `${baseUrl.replace('http', 'ws')}/auth/ws/register`
+    const params: string[] = []
+    if (resetToken) params.push(`reset=${encodeURIComponent(resetToken)}`)
+    if (displayName) params.push(`name=${encodeURIComponent(displayName)}`)
+    if (params.length) wsUrl += `?${params.join('&')}`
+
+    return new Promise<any>((resolve, reject) => {
+      const ws = new WebSocket(wsUrl)
+
+      ws.onopen = () => {
+        console.log('WebSocket connected for registration')
+      }
+
+      ws.onmessage = async (event) => {
+        const data = JSON.parse(event.data)
+
+        // Check for error response
+        if (data.detail) {
+          ws.close()
+          reject(new Error(data.detail))
+          return
+        }
+
+        // Check if this is the final success response
+        if (data.session_token) {
+          ws.close()
+          resolve(data)
+          return
+        }
+
+        // This should be the registration options from server (wrapped in optionsJSON)
+        // Use the native WebAuthn API with the virtual authenticator
+        try {
+          // Extract options from the optionsJSON wrapper
+          const opts = data.optionsJSON
+
+          // Convert base64url challenge to ArrayBuffer
+          const challenge = Uint8Array.from(atob(opts.challenge.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0))
+
+          // Build the credential creation options
+          const publicKeyCredentialCreationOptions: CredentialCreationOptions = {
+            publicKey: {
+              challenge: challenge,
+              rp: {
+                name: opts.rp.name,
+                id: opts.rp.id,
+              },
+              user: {
+                id: Uint8Array.from(atob(opts.user.id.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0)),
+                name: opts.user.name,
+                displayName: opts.user.displayName,
+              },
+              pubKeyCredParams: opts.pubKeyCredParams,
+              authenticatorSelection: opts.authenticatorSelection,
+              timeout: opts.timeout,
+              attestation: opts.attestation,
+              excludeCredentials: opts.excludeCredentials?.map((cred: any) => ({
+                ...cred,
+                id: Uint8Array.from(atob(cred.id.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0)),
+              })) || [],
+            }
+          }
+
+          // Create the credential using native WebAuthn API (virtual authenticator handles it)
+          const credential = await navigator.credentials.create(publicKeyCredentialCreationOptions) as PublicKeyCredential
+
+          if (!credential) {
+            throw new Error('Failed to create credential')
+          }
+
+          const response = credential.response as AuthenticatorAttestationResponse
+
+          // Convert response to JSON format expected by server
+          const registrationResponse = {
+            id: credential.id,
+            rawId: btoa(String.fromCharCode(...new Uint8Array(credential.rawId))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, ''),
+            response: {
+              clientDataJSON: btoa(String.fromCharCode(...new Uint8Array(response.clientDataJSON))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, ''),
+              attestationObject: btoa(String.fromCharCode(...new Uint8Array(response.attestationObject))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, ''),
+              transports: response.getTransports?.() || [],
+            },
+            type: credential.type,
+            clientExtensionResults: credential.getClientExtensionResults(),
+            authenticatorAttachment: (credential as any).authenticatorAttachment,
+          }
+
+          ws.send(JSON.stringify(registrationResponse))
+        } catch (error: any) {
+          ws.close()
+          reject(new Error(error.message || 'Registration failed'))
+        }
+      }
+
+      ws.onerror = () => {
+        reject(new Error('WebSocket error during registration'))
+      }
+
+      ws.onclose = (event) => {
+        if (!event.wasClean && event.code !== 1000) {
+          reject(new Error(`WebSocket closed unexpectedly: ${event.code}`))
+        }
+      }
+    })
+  }, { baseUrl, resetToken: options.resetToken, displayName: options.displayName })
+}
+
+/**
+ * Perform passkey authentication via WebSocket.
+ * This runs in the browser context using the virtual authenticator.
+ */
+export async function authenticatePasskey(
+  page: Page,
+  baseUrl: string
+): Promise<AuthenticationResult> {
+  return await page.evaluate(async ({ baseUrl }) => {
+    const wsUrl = `${baseUrl.replace('http', 'ws')}/auth/ws/authenticate`
+
+    return new Promise<any>((resolve, reject) => {
+      const ws = new WebSocket(wsUrl)
+
+      ws.onopen = () => {
+        console.log('WebSocket connected for authentication')
+      }
+
+      ws.onmessage = async (event) => {
+        const data = JSON.parse(event.data)
+
+        // Check for error response
+        if (data.detail) {
+          ws.close()
+          reject(new Error(data.detail))
+          return
+        }
+
+        // Check if this is the final success response
+        if (data.session_token) {
+          ws.close()
+          resolve(data)
+          return
+        }
+
+        // This should be the authentication options from server (wrapped in optionsJSON)
+        try {
+          // Extract options from the optionsJSON wrapper
+          const opts = data.optionsJSON
+
+          // Convert base64url challenge to ArrayBuffer
+          const challenge = Uint8Array.from(atob(opts.challenge.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0))
+
+          // Build the credential request options
+          const publicKeyCredentialRequestOptions: CredentialRequestOptions = {
+            publicKey: {
+              challenge: challenge,
+              rpId: opts.rpId,
+              timeout: opts.timeout,
+              userVerification: opts.userVerification,
+              allowCredentials: opts.allowCredentials?.map((cred: any) => ({
+                type: cred.type,
+                id: Uint8Array.from(atob(cred.id.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0)),
+                transports: cred.transports,
+              })) || [],
+            }
+          }
+
+          // Get the credential using native WebAuthn API (virtual authenticator handles it)
+          const credential = await navigator.credentials.get(publicKeyCredentialRequestOptions) as PublicKeyCredential
+
+          if (!credential) {
+            throw new Error('Failed to get credential')
+          }
+
+          const response = credential.response as AuthenticatorAssertionResponse
+
+          // Convert response to JSON format expected by server
+          const authenticationResponse = {
+            id: credential.id,
+            rawId: btoa(String.fromCharCode(...new Uint8Array(credential.rawId))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, ''),
+            response: {
+              clientDataJSON: btoa(String.fromCharCode(...new Uint8Array(response.clientDataJSON))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, ''),
+              authenticatorData: btoa(String.fromCharCode(...new Uint8Array(response.authenticatorData))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, ''),
+              signature: btoa(String.fromCharCode(...new Uint8Array(response.signature))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, ''),
+              userHandle: response.userHandle ? btoa(String.fromCharCode(...new Uint8Array(response.userHandle))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '') : null,
+            },
+            type: credential.type,
+            clientExtensionResults: credential.getClientExtensionResults(),
+            authenticatorAttachment: (credential as any).authenticatorAttachment,
+          }
+
+          ws.send(JSON.stringify(authenticationResponse))
+        } catch (error: any) {
+          ws.close()
+          reject(new Error(error.message || 'Authentication failed'))
+        }
+      }
+
+      ws.onerror = () => {
+        reject(new Error('WebSocket error during authentication'))
+      }
+
+      ws.onclose = (event) => {
+        if (!event.wasClean && event.code !== 1000) {
+          reject(new Error(`WebSocket closed unexpectedly: ${event.code}`))
+        }
+      }
+    })
+  }, { baseUrl })
+}
+
+/**
+ * Validate a session token via the API.
+ */
+export async function validateSession(
+  page: Page,
+  baseUrl: string,
+  sessionToken: string
+): Promise<{ valid: boolean; user_uuid: string; renewed: boolean }> {
+  const cookieName = getSessionCookieName()
+  const response = await page.request.post(`${baseUrl}/auth/api/validate`, {
+    headers: {
+      'Cookie': `${cookieName}=${sessionToken}`,
+    },
+  })
+  return await response.json()
+}
+
+/**
+ * Get user info via the API.
+ */
+export async function getUserInfo(
+  page: Page,
+  baseUrl: string,
+  sessionToken: string
+): Promise<any> {
+  const cookieName = getSessionCookieName()
+  const response = await page.request.post(`${baseUrl}/auth/api/user-info`, {
+    headers: {
+      'Cookie': `${cookieName}=${sessionToken}`,
+    },
+  })
+  return await response.json()
+}
+
+/**
+ * Logout via the API.
+ * If the session being logged out matches the saved session token, clears it.
+ */
+export async function logout(
+  page: Page,
+  baseUrl: string,
+  sessionToken: string
+): Promise<void> {
+  const cookieName = getSessionCookieName()
+  await page.request.post(`${baseUrl}/auth/api/logout`, {
+    headers: {
+      'Cookie': `${cookieName}=${sessionToken}`,
+    },
+  })
+  // Clear saved session token if it matches the one being logged out
+  const savedToken = getSavedSessionToken()
+  if (savedToken === sessionToken) {
+    clearSavedSessionToken()
+  }
+}
+
+/**
+ * Create a device link for adding a new credential to an existing user.
+ */
+export async function createDeviceLink(
+  page: Page,
+  baseUrl: string,
+  sessionToken: string
+): Promise<{ url: string; token: string }> {
+  const cookieName = getSessionCookieName()
+  const response = await page.request.post(`${baseUrl}/auth/api/user/create-link`, {
+    headers: {
+      'Cookie': `${cookieName}=${sessionToken}`,
+    },
+  })
+  if (!response.ok()) {
+    throw new Error(`Failed to create device link: ${response.status()} - ${await response.text()}`)
+  }
+  const data = await response.json()
+  if (!data.url) {
+    throw new Error(`No URL in response: ${JSON.stringify(data)}`)
+  }
+  // Extract token from URL (last path segment)
+  const url = new URL(data.url)
+  const token = url.pathname.split('/').pop() || ''
+  return { url: data.url, token }
+}

e2e/tests/fixtures/virtual-authenticator.ts

@@ -0,0 +1,144 @@
+import { test as base, expect, type CDPSession, type Page } from '@playwright/test'
+import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const coverageDir = join(__dirname, '..', '..', 'coverage-frontend')
+
+// Check if frontend coverage is enabled
+const COLLECT_COVERAGE = process.env.COVERAGE === '1' || process.env.COVERAGE === 'true'
+
+/**
+ * Virtual Authenticator configuration for WebAuthn testing.
+ * Uses Chrome DevTools Protocol to create a software authenticator.
+ */
+export interface VirtualAuthenticatorOptions {
+  protocol?: 'ctap1/u2f' | 'ctap2'
+  transport?: 'usb' | 'nfc' | 'ble' | 'internal'
+  hasResidentKey?: boolean
+  hasUserVerification?: boolean
+  isUserVerified?: boolean
+  automaticPresenceSimulation?: boolean
+}
+
+export interface VirtualAuthenticator {
+  authenticatorId: string
+  cdpSession: CDPSession
+}
+
+/**
+ * Create a virtual authenticator using Chrome DevTools Protocol.
+ * This allows fully automated passkey registration and authentication.
+ */
+export async function createVirtualAuthenticator(
+  page: Page,
+  options: VirtualAuthenticatorOptions = {}
+): Promise<VirtualAuthenticator> {
+  const cdpSession = await page.context().newCDPSession(page)
+
+  // Enable WebAuthn in CDP
+  await cdpSession.send('WebAuthn.enable', {
+    enableUI: false, // Suppress any UI prompts
+  })
+
+  // Create the virtual authenticator with resident key support
+  const { authenticatorId } = await cdpSession.send('WebAuthn.addVirtualAuthenticator', {
+    options: {
+      protocol: options.protocol ?? 'ctap2',
+      transport: options.transport ?? 'internal',
+      hasResidentKey: options.hasResidentKey ?? true,
+      hasUserVerification: options.hasUserVerification ?? true,
+      isUserVerified: options.isUserVerified ?? true,
+      automaticPresenceSimulation: options.automaticPresenceSimulation ?? true,
+    },
+  })
+
+  return { authenticatorId, cdpSession }
+}
+
+/**
+ * Remove a virtual authenticator.
+ */
+export async function removeVirtualAuthenticator(
+  authenticator: VirtualAuthenticator
+): Promise<void> {
+  await authenticator.cdpSession.send('WebAuthn.removeVirtualAuthenticator', {
+    authenticatorId: authenticator.authenticatorId,
+  })
+  await authenticator.cdpSession.send('WebAuthn.disable')
+}
+
+/**
+ * Get all credentials stored in a virtual authenticator.
+ */
+export async function getCredentials(
+  authenticator: VirtualAuthenticator
+): Promise<any[]> {
+  const result = await authenticator.cdpSession.send('WebAuthn.getCredentials', {
+    authenticatorId: authenticator.authenticatorId,
+  })
+  return result.credentials
+}
+
+/**
+ * Extended test fixture with virtual authenticator support and optional coverage.
+ */
+export const test = base.extend<{
+  virtualAuthenticator: VirtualAuthenticator
+}>({
+  virtualAuthenticator: async ({ page }, use, testInfo) => {
+    // Start coverage collection if enabled
+    let coverageCdp: CDPSession | null = null
+    if (COLLECT_COVERAGE) {
+      try {
+        coverageCdp = await page.context().newCDPSession(page)
+        await coverageCdp.send('Profiler.enable')
+        await coverageCdp.send('Profiler.startPreciseCoverage', {
+          callCount: true,
+          detailed: true,
+        })
+      } catch {
+        coverageCdp = null
+      }
+    }
+
+    // Create virtual authenticator before test
+    const authenticator = await createVirtualAuthenticator(page)
+
+    // Run the test
+    await use(authenticator)
+
+    // Cleanup after test
+    await removeVirtualAuthenticator(authenticator)
+
+    // Stop and save coverage
+    if (coverageCdp) {
+      try {
+        const { result } = await coverageCdp.send('Profiler.takePreciseCoverage')
+        await coverageCdp.send('Profiler.stopPreciseCoverage')
+        await coverageCdp.send('Profiler.disable')
+
+        // Filter to only include our app's JavaScript files
+        const appCoverage = result.filter((entry: any) =>
+          entry.url.includes('/auth/') &&
+          entry.url.endsWith('.js') &&
+          !entry.url.includes('node_modules')
+        )
+
+        if (appCoverage.length > 0) {
+          if (!existsSync(coverageDir)) {
+            mkdirSync(coverageDir, { recursive: true })
+          }
+          const safeName = testInfo.title.replace(/[^a-z0-9]/gi, '_').substring(0, 50)
+          const coverageFile = join(coverageDir, `coverage-${safeName}-${Date.now()}.json`)
+          writeFileSync(coverageFile, JSON.stringify(appCoverage, null, 2))
+        }
+      } catch {
+        // Silently ignore coverage collection errors
+      }
+    }
+  },
+})
+
+export { expect }

e2e/tests/global-setup.ts

@@ -0,0 +1,132 @@
+import { spawn } from 'child_process'
+import { join, dirname } from 'path'
+import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const testDataDir = join(__dirname, '..', 'test-data')
+const stateFile = join(testDataDir, 'test-state.json')
+const projectRoot = join(__dirname, '..', '..')
+
+// Check if coverage is enabled
+const COLLECT_COVERAGE = process.env.COVERAGE === '1' || process.env.COVERAGE === 'true'
+
+interface TestState {
+  resetToken?: string
+  serverPid?: number
+  sessionCookie?: string
+}
+
+/**
+ * Global setup for E2E tests.
+ *
+ * Uses in-memory SQLite database for fast, isolated tests.
+ * Captures the bootstrap reset token for initial user registration.
+ */
+export default async function globalSetup() {
+  console.log('\n🔧 Setting up E2E test environment...\n')
+
+  // Create test data directory for state file
+  if (!existsSync(testDataDir)) {
+    mkdirSync(testDataDir, { recursive: true })
+  }
+
+  console.log('  Starting server with in-memory database...')
+  if (COLLECT_COVERAGE) {
+    console.log('  📊 Coverage collection enabled for Python backend')
+  }
+
+  const state: TestState = {}
+
+  // Build server command - with or without coverage
+  const serverArgs = COLLECT_COVERAGE
+    ? [
+        'run', 'coverage', 'run', '--parallel-mode',
+        '-m', 'paskia.fastapi', 'serve', 'localhost:4404',
+        '--rp-id', 'localhost'
+      ]
+    : [
+        'run', 'paskia', 'serve', 'localhost:4404',
+        '--rp-id', 'localhost'
+      ]
+
+  // Start the server using Node's spawn
+  // Use in-memory SQLite for faster tests
+  const serverProcess = spawn('uv', serverArgs, {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      PASKIA_DB: 'sqlite+aiosqlite:///:memory:',
+      COVERAGE_FILE: join(projectRoot, '.coverage'),
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+
+  state.serverPid = serverProcess.pid
+
+  // Capture output to find reset token
+  const resetTokenPromise = new Promise<string>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error('Timed out waiting for server bootstrap (30s)'))
+    }, 30000)
+
+    let output = ''
+
+    const handleData = (data: Buffer) => {
+      const text = data.toString()
+      output += text
+      process.stdout.write(text) // Echo to console
+
+      // Look for the reset token URL in the output
+      // Format: https://localhost/auth/{token} or http://localhost:4404/auth/{token}
+      // where token is word.word.word.word.word (dot separated)
+      const match = output.match(/https?:\/\/localhost(?::\d+)?\/auth\/([a-z]+(?:\.[a-z]+)+)/)
+      if (match) {
+        clearTimeout(timeout)
+        // Wait a bit for server to fully start
+        setTimeout(() => resolve(match[1]), 1000)
+      }
+    }
+
+    serverProcess.stdout?.on('data', handleData)
+    serverProcess.stderr?.on('data', handleData)
+
+    serverProcess.on('error', (err) => {
+      clearTimeout(timeout)
+      reject(err)
+    })
+
+    serverProcess.on('exit', (code) => {
+      if (code !== 0 && code !== null) {
+        clearTimeout(timeout)
+        reject(new Error(`Server exited with code ${code}`))
+      }
+    })
+  })
+
+  try {
+    state.resetToken = await resetTokenPromise
+    console.log(`\n  ✅ Captured reset token: ${state.resetToken}\n`)
+  } catch (err) {
+    console.error('Failed to capture reset token:', err)
+    serverProcess.kill()
+    throw err
+  }
+
+  // Fetch session cookie name from server settings
+  try {
+    const response = await fetch('http://localhost:4404/auth/api/settings')
+    const settings = await response.json()
+    state.sessionCookie = settings.session_cookie
+    console.log(`  ✅ Session cookie name: ${state.sessionCookie}\n`)
+  } catch (err) {
+    console.error('Failed to fetch settings:', err)
+    serverProcess.kill()
+    throw err
+  }
+
+  // Save state for tests
+  writeFileSync(stateFile, JSON.stringify(state, null, 2))
+
+  console.log('  ✅ E2E test environment ready\n')
+}

e2e/tests/global-teardown.ts

@@ -0,0 +1,148 @@
+import { join, dirname } from 'path'
+import { existsSync, rmSync, readFileSync, readdirSync, writeFileSync } from 'fs'
+import { fileURLToPath } from 'url'
+import { execSync } from 'child_process'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const testDataDir = join(__dirname, '..', 'test-data')
+const stateFile = join(testDataDir, 'test-state.json')
+const projectRoot = join(__dirname, '..', '..')
+const coverageDir = join(__dirname, '..', 'coverage-frontend')
+
+// Check if coverage is enabled
+const COLLECT_COVERAGE = process.env.COVERAGE === '1' || process.env.COVERAGE === 'true'
+
+interface TestState {
+  resetToken?: string
+  serverPid?: number
+}
+
+interface CoverageEntry {
+  url: string
+  functions: Array<{
+    functionName: string
+    ranges: Array<{ count: number }>
+  }>
+}
+
+/**
+ * Global teardown for E2E tests.
+ *
+ * This cleans up the test server and optionally removes the test database.
+ */
+export default async function globalTeardown() {
+  console.log('\n🧹 Cleaning up E2E test environment...\n')
+
+  // Read state file to get server PID
+  if (existsSync(stateFile)) {
+    try {
+      const state: TestState = JSON.parse(readFileSync(stateFile, 'utf-8'))
+
+      if (state.serverPid) {
+        console.log(`  Stopping server (PID: ${state.serverPid})...`)
+        try {
+          process.kill(state.serverPid, 'SIGTERM')
+          // Wait longer for graceful shutdown and coverage data flush
+          await new Promise(r => setTimeout(r, COLLECT_COVERAGE ? 2000 : 500))
+        } catch (err: any) {
+          // Process may already be dead
+          if (err.code !== 'ESRCH') {
+            console.warn(`  Warning: Could not kill server: ${err.message}`)
+          }
+        }
+      }
+    } catch (err) {
+      console.warn('  Warning: Could not read state file')
+    }
+
+    // Clean up state file
+    rmSync(stateFile, { force: true })
+  }
+
+  // Optionally clean up test database (keep it for debugging by default)
+  if (process.env.CLEANUP_TEST_DB === 'true') {
+    const dbPath = join(testDataDir, 'test.sqlite')
+    if (existsSync(dbPath)) {
+      console.log('  Removing test database...')
+      rmSync(dbPath)
+    }
+    // Remove wal/shm files too
+    for (const ext of ['-wal', '-shm']) {
+      const file = dbPath + ext
+      if (existsSync(file)) rmSync(file)
+    }
+  }
+
+  // Generate Python coverage report if coverage was collected
+  if (COLLECT_COVERAGE) {
+    console.log('  📊 Generating Python coverage report...')
+    try {
+      // Combine parallel coverage data and generate reports
+      execSync('uv run coverage combine', { cwd: projectRoot, stdio: 'inherit' })
+      execSync('uv run coverage report', { cwd: projectRoot, stdio: 'inherit' })
+      execSync('uv run coverage html', { cwd: projectRoot, stdio: 'inherit' })
+      console.log(`  ✅ Python coverage report: ${join(projectRoot, 'coverage-html', 'index.html')}\n`)
+    } catch (err: any) {
+      console.warn(`  Warning: Failed to generate coverage report: ${err.message}`)
+    }
+
+    // Merge and report frontend coverage
+    if (existsSync(coverageDir)) {
+      try {
+        const files = readdirSync(coverageDir).filter(f => f.startsWith('coverage-') && f.endsWith('.json') && f !== 'coverage-merged.json')
+
+        if (files.length > 0) {
+          const merged: Map<string, CoverageEntry> = new Map()
+
+          for (const file of files) {
+            const data: CoverageEntry[] = JSON.parse(readFileSync(join(coverageDir, file), 'utf-8'))
+            for (const entry of data) {
+              const existing = merged.get(entry.url)
+              if (!existing) {
+                merged.set(entry.url, entry)
+              } else {
+                // Merge function coverage counts
+                for (const func of entry.functions) {
+                  const existingFunc = existing.functions.find(f => f.functionName === func.functionName)
+                  if (existingFunc) {
+                    for (let i = 0; i < func.ranges.length && i < existingFunc.ranges.length; i++) {
+                      existingFunc.ranges[i].count += func.ranges[i].count
+                    }
+                  } else {
+                    existing.functions.push(func)
+                  }
+                }
+              }
+            }
+          }
+
+          // Write merged coverage
+          writeFileSync(
+            join(coverageDir, 'coverage-merged.json'),
+            JSON.stringify(Array.from(merged.values()), null, 2)
+          )
+
+          // Generate simple coverage summary
+          let totalFunctions = 0
+          let coveredFunctions = 0
+
+          for (const entry of merged.values()) {
+            for (const func of entry.functions) {
+              totalFunctions++
+              const hasCoverage = func.ranges.some(r => r.count > 0)
+              if (hasCoverage) coveredFunctions++
+            }
+          }
+
+          const percentage = totalFunctions > 0 ? Math.round((coveredFunctions / totalFunctions) * 100) : 0
+          console.log(`  📊 Frontend JS Coverage: ${coveredFunctions}/${totalFunctions} functions (${percentage}%)`)
+          console.log(`  ✅ Frontend coverage data: ${coverageDir}/coverage-merged.json\n`)
+        }
+      } catch (err: any) {
+        console.warn(`  Warning: Failed to merge frontend coverage: ${err.message}`)
+      }
+    }
+  }
+
+  console.log('  ✅ Cleanup complete\n')
+}

e2e/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "types": ["bun-types"]
+  },
+  "include": ["tests/**/*.ts", "playwright.config.ts"],
+  "exclude": ["node_modules"]
+}

examples/index.html

@@ -0,0 +1,166 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Paskia - Dev Mode</title>
+    <style>
+        :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>
+    <div class="container">
+        <header>
+            <h1>🔐 Paskia - Development Server</h1>
+            <p class="subtitle">The following features are available after you have registered your Admin account and logged in. You should also use the Admin Site to create non-privileged users to see the Forbidden dialog caused by missing permissions.</p>
+        </header>
+
+        <div class="content">
+            <div class="section">
+                <h2>Management Site</h2>
+                <button onclick="window.open('/auth/', '_blank')">👤 User Profile</button>
+                <button onclick="window.open('/auth/admin/', '_blank')">⚙️ Admin Panel</button>
+            </div>
+
+            <div class="section">
+                <h2>API Mode (not leaving the page)</h2>
+                <p>For SPAs and fetch() calls - shows auth in an iframe overlay:</p>
+                <button onclick="apiCall('/auth/api/user-info', 'POST')">📋 Get User Info</button>
+                <button onclick="apiCall('/auth/api/forward?max_age=10s')">🔄 Reauth (max_age=10s)</button>
+                <button onclick="apiCall('/auth/api/forward?perm=auth:admin')">🛡️ Admin Only</button>
+                <button onclick="logout()">🚪 Logout</button>
+            </div>
+
+            <div class="section">
+                <h2>Browser Mode (full page)</h2>
+                <p>Block access to otherwise open site - intended for forward-auth mechanism (Caddy, Nginx):</p>
+                <button onclick="browserNav('/auth/api/forward')">🔐 Basic Auth</button>
+                <button onclick="browserNav('/auth/api/forward?max_age=10s')">🔄 Reauth (max_age=10s)</button>
+                <button onclick="browserNav('/auth/api/forward?perm=auth:admin')">🛡️ Admin Only</button>
+            </div>
+
+            <pre id="output">Click a button to test...</pre>
+        </div>
+    </div>
+
+    <script>
+        const output = document.getElementById('output');
+        let pendingCall = null;  // Stores the API call to retry after auth
+
+        // The auth iframe posts messages when authentication completes or is cancelled.
+        // Message types: 'auth-success' (proceed), 'auth-back' (user cancelled)
+        // Errors during auth stay in the dialog allowing retry, no message is sent.
+        window.addEventListener('message', (event) => {
+            const { type, message } = event.data || {};
+
+            if (type === 'auth-success') {
+                log('✓ Authentication successful, retrying...');
+                hideAuthIframe();
+                // Retry the original API call that triggered authentication
+                if (pendingCall) {
+                    const { url, method } = pendingCall;
+                    pendingCall = null;
+                    apiCall(url, method);
+                }
+            } else if (type === 'auth-back') {
+                log(message || 'Authentication cancelled');
+                hideAuthIframe();
+                pendingCall = null;
+            }
+        });
+
+        // Make an API call, handling 401/403 by showing the auth iframe.
+        // The server returns JSON with auth.iframe URL when authentication is needed.
+        async function apiCall(url, method = 'GET') {
+            log(`${method} ${url}...`);
+
+            const response = await fetch(url, { method, credentials: 'include' });
+
+            // Server returns 401 (login/reauth) or 403 (missing permissions)
+            // with a JSON body containing the iframe URL for authentication
+            if (response.status === 401 || response.status === 403) {
+                const data = await response.json();
+                if (data.auth?.iframe) {
+                    const mode = data.auth.mode;  // 'login' or 'reauth'
+                    log(`${mode === 'reauth' ? 'Re-authentication' : 'Authentication'} required...`);
+                    pendingCall = { url, method };
+                    showAuthIframe(data.auth.iframe);
+                    return;
+                }
+                log(`Error: ${response.status} - ${data.detail}`);
+                return;
+            }
+
+            // Forward endpoint returns 204 on success (Caddy then adds Remote-* headers)
+            if (response.status === 204) {
+                log('✓ Success (204 No Content)\nHeaders:\n' +
+                    [...response.headers].filter(([k]) => k.startsWith('remote-'))
+                        .map(([k, v]) => `  ${k}: ${v}`).join('\n'));
+                return;
+            }
+
+            if (!response.ok) {
+                log(`Error: ${response.status} ${response.statusText}`);
+                return;
+            }
+
+            const data = await response.json();
+            log('✓ Response:\n' + JSON.stringify(data, null, 2));
+        }
+
+        async function logout() {
+            await fetch('/auth/api/logout', { method: 'POST', credentials: 'include' });
+            log('Logged out');
+        }
+
+        // Create fullscreen iframe for authentication.
+        // The 'allow' attribute enables WebAuthn (passkey) API inside the iframe.
+        function showAuthIframe(url) {
+            hideAuthIframe();
+            const iframe = document.createElement('iframe');
+            iframe.id = 'auth-iframe';
+            iframe.src = url;
+            document.body.appendChild(iframe);
+            log("Authentication dialog open...")
+        }
+
+        function hideAuthIframe() {
+            document.getElementById('auth-iframe')?.remove();
+        }
+
+        function log(msg) {
+            output.textContent = msg;
+        }
+
+        // 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) {
+            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');
+        }
+    </script>
+</body>
+</html>

frontend/auth/App.vue

@@ -0,0 +1,203 @@
+<template>
+  <div class="app-shell">
+    <StatusMessage />
+    <main class="app-main">
+      <HostProfileView v-if="authenticated && isHostMode" :initializing="loading" />
+      <ProfileView v-else-if="authenticated" />
+      <LoadingView v-else-if="loading" :message="loadingMessage" />
+      <AuthRequiredMessage v-else-if="showBackMessage" @reload="reloadPage" />
+    </main>
+  </div>
+</template>
+
+<script setup>
+import { computed, onMounted, onUnmounted, ref } from 'vue'
+import { useAuthStore } from '@/stores/auth'
+import { apiJson, getAuthIframeUrl } from '@/utils/api'
+import StatusMessage from '@/components/StatusMessage.vue'
+import ProfileView from '@/components/ProfileView.vue'
+import HostProfileView from '@/components/HostProfileView.vue'
+import LoadingView from '@/components/LoadingView.vue'
+import AuthRequiredMessage from '@/components/AccessDenied.vue'
+
+const store = useAuthStore()
+const loading = ref(true)
+const loadingMessage = ref('Loading...')
+const authenticated = ref(false)
+const showBackMessage = ref(false)
+
+/**
+ * Normalize a host string for comparison (lowercase, strip default ports).
+ */
+function normalizeHost(raw) {
+  if (!raw) return null
+  const trimmed = raw.trim().toLowerCase()
+  if (!trimmed) return null
+  // Remove default ports
+  return trimmed.replace(/:80$/, '').replace(/:443$/, '')
+}
+
+/**
+ * Host mode is active when an auth_host is configured AND the current host differs from it.
+ * In host mode, we show a limited profile view with logout and link to full profile.
+ */
+const isHostMode = computed(() => {
+  const authHost = store.settings?.auth_host
+  if (!authHost) return false
+  const currentHost = normalizeHost(window.location.host)
+  const configuredHost = normalizeHost(authHost)
+  return currentHost !== configuredHost
+})
+let validationTimer = null
+let authIframe = null
+
+async function loadUserInfo() {
+  try {
+    store.userInfo = await apiJson('/auth/api/user-info', { method: 'POST' })
+    authenticated.value = true
+    loading.value = false
+    startSessionValidation()
+    return true
+  } catch (e) {
+    return false
+  }
+}
+
+async function showAuthIframe() {
+  // Remove existing iframe if any
+  hideAuthIframe()
+
+  // Create new iframe for authentication using src URL
+  const url = await getAuthIframeUrl('login')
+  authIframe = document.createElement('iframe')
+  authIframe.id = 'auth-iframe'
+  authIframe.title = 'Authentication'
+  authIframe.allow = 'publickey-credentials-get; publickey-credentials-create'
+  authIframe.src = url
+  document.body.appendChild(authIframe)
+  loadingMessage.value = 'Authentication required...'
+}
+
+function hideAuthIframe() {
+  if (authIframe) {
+    authIframe.remove()
+    authIframe = null
+  }
+}
+
+function reloadPage() {
+  window.location.reload()
+}
+
+function handleAuthMessage(event) {
+  const data = event.data
+  if (!data?.type) return
+
+  switch (data.type) {
+    case 'auth-success':
+      // Authentication successful - reload user info
+      hideAuthIframe()
+      loading.value = true
+      loadingMessage.value = 'Loading user profile...'
+      loadUserInfo()
+      break
+
+    case 'auth-error':
+      // Authentication failed - keep iframe open so user can retry
+      if (data.cancelled) {
+        console.log('Authentication cancelled by user')
+      } else {
+        store.showMessage(data.message || 'Authentication failed', 'error', 5000)
+      }
+      break
+
+    case 'auth-cancelled':
+      // Legacy support - treat as auth-error with cancelled flag
+      console.log('Authentication cancelled')
+      break
+
+    case 'auth-back':
+      // User clicked Back - show message with reload option
+      hideAuthIframe()
+      loading.value = false
+      showBackMessage.value = true
+      store.showMessage('Authentication cancelled', 'info', 3000)
+      break
+
+    case 'auth-close-request':
+      // Legacy support - treat as back
+      hideAuthIframe()
+      break
+  }
+}
+
+async function validateSession() {
+  try {
+    await apiJson('/auth/api/validate', {
+      method: 'POST',
+      credentials: 'include'
+    })
+    // If successful, session was renewed automatically
+  } catch (error) {
+    if (error.status === 401) {
+      // Session expired - need to re-authenticate
+      console.log('Session expired, requiring re-authentication')
+      authenticated.value = false
+      loading.value = true
+      stopSessionValidation()
+      showAuthIframe()
+    } else {
+      console.error('Session validation error:', error)
+      // Don't treat network errors as session expiry
+    }
+  }
+}
+
+function startSessionValidation() {
+  // Validate session every 2 minutes
+  stopSessionValidation()
+  validationTimer = setInterval(validateSession, 2 * 60 * 1000)
+}
+
+function stopSessionValidation() {
+  if (validationTimer) {
+    clearInterval(validationTimer)
+    validationTimer = null
+  }
+}
+
+onMounted(async () => {
+  // Listen for postMessage from auth iframe
+  window.addEventListener('message', handleAuthMessage)
+
+  // Load settings
+  await store.loadSettings()
+
+  // Set appropriate page title based on mode
+  const rpName = store.settings?.rp_name
+  if (rpName) {
+    // In host mode, show "account summary" style title
+    // Settings are loaded but isHostMode depends on them, so check here
+    const authHost = store.settings?.auth_host
+    const inHostMode = authHost && normalizeHost(window.location.host) !== normalizeHost(authHost)
+    document.title = inHostMode ? `${rpName} · Account summary` : rpName
+  }
+
+  // Try to load user info
+  const success = await loadUserInfo()
+
+  if (!success) {
+    // Need authentication - show login iframe
+    showAuthIframe()
+  }
+})
+
+onUnmounted(() => {
+  window.removeEventListener('message', handleAuthMessage)
+  stopSessionValidation()
+  hideAuthIframe()
+})
+</script>
+
+<style scoped>
+</style>

frontend/auth/admin/AdminApp.vue

@@ -1,19 +1,24 @@
 <script setup>
-import { ref, onMounted, onBeforeUnmount, computed, watch } from 'vue'
+import { ref, onMounted, onUnmounted, computed, watch } from 'vue'
 import Breadcrumbs from '@/components/Breadcrumbs.vue'
 import CredentialList from '@/components/CredentialList.vue'
 import UserBasicInfo from '@/components/UserBasicInfo.vue'
-import RegistrationLinkModal from '@/components/RegistrationLinkModal.vue'
 import StatusMessage from '@/components/StatusMessage.vue'
-import AdminOverview from './AdminOverview.vue'
-import AdminOrgDetail from './AdminOrgDetail.vue'
-import AdminUserDetail from './AdminUserDetail.vue'
-import AdminDialogs from './AdminDialogs.vue'
+import LoadingView from '@/components/LoadingView.vue'
+import AuthRequiredMessage from '@/components/AccessDenied.vue'
+import AdminOverview from '@/admin/AdminOverview.vue'
+import AdminOrgDetail from '@/admin/AdminOrgDetail.vue'
+import AdminUserDetail from '@/admin/AdminUserDetail.vue'
+import AdminDialogs from '@/admin/AdminDialogs.vue'
 import { useAuthStore } from '@/stores/auth'
 import { getSettings, adminUiPath, makeUiHref } from '@/utils/settings'
+import { apiJson } from '@/utils/api'
 
 const info = ref(null)
 const loading = ref(true)
+const loadingMessage = ref('Loading...')
+const authenticated = ref(false)
+const showBackMessage = ref(false)
 const error = ref(null)
 const orgs = ref([])
 const permissions = ref([])
@@ -43,11 +48,17 @@ function handleGlobalClick(e) {
   }
 }
 
-onMounted(() => {
+onMounted(async () => {
   document.addEventListener('click', handleGlobalClick)
+  window.addEventListener('hashchange', parseHash)
+  const settings = await getSettings()
+  if (settings?.rp_name) document.title = settings.rp_name + ' Admin'
+  await load()
 })
-onBeforeUnmount(() => {
+
+onUnmounted(() => {
   document.removeEventListener('click', handleGlobalClick)
+  window.removeEventListener('hashchange', parseHash)
 })
 
 // Build a summary: for each permission id -> { orgs: Set(org_display_name), userCount }
@@ -56,7 +67,7 @@ const permissionSummary = computed(() => {
   for (const o of orgs.value) {
     const orgBase = { uuid: o.uuid, display_name: o.display_name }
     const orgPerms = new Set(o.permissions || [])
-    
+
     // Org-level permissions (direct) - only count if org can grant them
     for (const pid of o.permissions || []) {
       if (!summary[pid]) summary[pid] = { orgs: [], orgSet: new Set(), userCount: 0 }
@@ -65,13 +76,13 @@ const permissionSummary = computed(() => {
         summary[pid].orgSet.add(o.uuid)
       }
     }
-    
+
     // Role-based permissions (inheritance) - only count if org can grant them
     for (const r of o.roles) {
       for (const pid of r.permissions) {
         // Only count if the org can grant this permission
         if (!orgPerms.has(pid)) continue
-        
+
         if (!summary[pid]) summary[pid] = { orgs: [], orgSet: new Set(), userCount: 0 }
         if (!summary[pid].orgSet.has(o.uuid)) {
           summary[pid].orgs.push(orgBase)
@@ -99,9 +110,7 @@ async function attachPermissionToOrg(pid, orgUuid) {
   if (!orgUuid) return
   try {
     const params = new URLSearchParams({ permission_id: pid })
-    const res = await fetch(`/auth/admin/orgs/${orgUuid}/permission?${params.toString()}`, { method: 'POST' })
-    const data = await res.json()
-    if (data.detail) throw new Error(data.detail)
+    await apiJson(`/auth/api/admin/orgs/${orgUuid}/permission?${params.toString()}`, { method: 'POST' })
     await loadOrgs()
   } catch (e) {
   authStore.showMessage(e.message || 'Failed to add permission to org')
@@ -112,9 +121,7 @@ async function detachPermissionFromOrg(pid, orgUuid) {
   openDialog('confirm', { message: 'Remove permission from this org?', action: async () => {
     try {
       const params = new URLSearchParams({ permission_id: pid })
-      const res = await fetch(`/auth/admin/orgs/${orgUuid}/permission?${params.toString()}`, { method: 'DELETE' })
-      const data = await res.json()
-      if (data.detail) throw new Error(data.detail)
+      await apiJson(`/auth/api/admin/orgs/${orgUuid}/permission?${params.toString()}`, { method: 'DELETE' })
       await loadOrgs()
     } catch (e) {
       authStore.showMessage(e.message || 'Failed to remove permission from org')
@@ -134,10 +141,7 @@ function parseHash() {
 }
 
 async function loadOrgs() {
-  const res = await fetch('/auth/admin/orgs')
-  const data = await res.json()
-  if (data.detail) throw new Error(data.detail)
-  // Restructure to attach users to roles instead of flat user list at org level
+  const data = await apiJson('/auth/api/admin/orgs')
   orgs.value = data.map(o => {
     const roles = o.roles.map(r => ({ ...r, org_uuid: o.uuid, users: [] }))
     const roleMap = Object.fromEntries(roles.map(r => [r.display_name, r]))
@@ -149,25 +153,25 @@ async function loadOrgs() {
 }
 
 async function loadPermissions() {
-  const res = await fetch('/auth/admin/permissions')
-  const data = await res.json()
-  if (data.detail) throw new Error(data.detail)
-  permissions.value = data
+  permissions.value = await apiJson('/auth/api/admin/permissions')
+}
+
+async function loadUserInfo() {
+  info.value = await apiJson('/auth/api/user-info', { method: 'POST' })
+  authenticated.value = true
 }
 
 async function load() {
   loading.value = true
+  loadingMessage.value = 'Loading...'
   error.value = null
   try {
-  const res = await fetch('/auth/api/user-info', { method: 'POST' })
-    const data = await res.json()
-    if (data.detail) throw new Error(data.detail)
-    info.value = data
-    if (data.authenticated && (data.is_global_admin || data.is_org_admin)) {
-      await Promise.all([loadOrgs(), loadPermissions()])
-    }
-    // After loading orgs decide view if not global admin
-    if (!data.is_global_admin && data.is_org_admin && orgs.value.length === 1) {
+    // Load admin data first - apiJson will handle 401/403 with iframe authentication
+    await Promise.all([loadOrgs(), loadPermissions()])
+    // If we get here, user has admin access - now fetch user info for display
+    await loadUserInfo()
+
+    if (!info.value.is_global_admin && info.value.is_org_admin && orgs.value.length === 1) {
       if (!window.location.hash || window.location.hash === '#overview') {
         currentOrgId.value = orgs.value[0].uuid
         window.location.hash = `#org/${currentOrgId.value}`
@@ -177,7 +181,11 @@ async function load() {
       }
     } else parseHash()
   } catch (e) {
-    error.value = e.message
+    if (e.name === 'AuthCancelledError') {
+      showBackMessage.value = true
+    } else {
+      error.value = e.message
+    }
   } finally {
     loading.value = false
   }
@@ -193,8 +201,7 @@ function editUserName(user) { openDialog('user-update-name', { user, name: user.
 function deleteOrg(org) {
   if (!info.value?.is_global_admin) { authStore.showMessage('Global admin only'); return }
   openDialog('confirm', { message: `Delete organization ${org.display_name}?`, action: async () => {
-    const res = await fetch(`/auth/admin/orgs/${org.uuid}`, { method: 'DELETE' })
-    const data = await res.json(); if (data.detail) throw new Error(data.detail)
+    await apiJson(`/auth/api/admin/orgs/${org.uuid}`, { method: 'DELETE' })
     await Promise.all([loadOrgs(), loadPermissions()])
   } })
 }
@@ -203,14 +210,15 @@ function createUserInRole(org, role) { openDialog('user-create', { org, role })
 
 async function moveUserToRole(org, user, targetRoleDisplayName) {
   if (user.role === targetRoleDisplayName) return
-  const res = await fetch(`/auth/admin/orgs/${org.uuid}/users/${user.uuid}/role`, {
-    method: 'PUT',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ role: targetRoleDisplayName })
-  })
-  const data = await res.json()
-  if (data.detail) { authStore.showMessage(data.detail); return }
-  await loadOrgs()
+  try {
+    await apiJson(`/auth/api/admin/orgs/${org.uuid}/users/${user.uuid}/role`, {
+      method: 'PUT',
+      body: { role: targetRoleDisplayName }
+    })
+    await loadOrgs()
+  } catch (e) {
+    authStore.showMessage(e.message || 'Failed to update user role')
+  }
 }
 
 function onUserDragStart(e, user, org_uuid) {
@@ -245,30 +253,26 @@ function updateRole(role) { openDialog('role-update', { role, name: role.display
 
 function deleteRole(role) {
   openDialog('confirm', { message: `Delete role ${role.display_name}?`, action: async () => {
-    const res = await fetch(`/auth/admin/orgs/${role.org_uuid}/roles/${role.uuid}`, { method: 'DELETE' })
-    const data = await res.json(); if (data.detail) throw new Error(data.detail)
+    await apiJson(`/auth/api/admin/orgs/${role.org_uuid}/roles/${role.uuid}`, { method: 'DELETE' })
     await loadOrgs()
   } })
 }
 
 async function toggleRolePermission(role, pid, checked) {
   // Calculate new permissions array
-  const newPermissions = checked 
-    ? [...role.permissions, pid] 
+  const newPermissions = checked
+    ? [...role.permissions, pid]
     : role.permissions.filter(p => p !== pid)
-  
+
   // Optimistic update
   const prevPermissions = [...role.permissions]
   role.permissions = newPermissions
-  
+
   try {
-    const res = await fetch(`/auth/admin/orgs/${role.org_uuid}/roles/${role.uuid}`, {
+    await apiJson(`/auth/api/admin/orgs/${role.org_uuid}/roles/${role.uuid}`, {
       method: 'PUT',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ display_name: role.display_name, permissions: newPermissions })
+      body: { display_name: role.display_name, permissions: newPermissions }
     })
-    const data = await res.json()
-    if (data.detail) throw new Error(data.detail)
     await loadOrgs()
   } catch (e) {
     authStore.showMessage(e.message || 'Failed to update role permission')
@@ -282,18 +286,14 @@ function updatePermission(p) { openDialog('perm-display', { permission: p }) }
 function deletePermission(p) {
   openDialog('confirm', { message: `Delete permission ${p.id}?`, action: async () => {
     const params = new URLSearchParams({ permission_id: p.id })
-    const res = await fetch(`/auth/admin/permission?${params.toString()}`, { method: 'DELETE' })
-    const data = await res.json(); if (data.detail) throw new Error(data.detail)
+    await apiJson(`/auth/api/admin/permission?${params.toString()}`, { method: 'DELETE' })
     await loadPermissions()
   } })
 }
 
-onMounted(async () => {
-  window.addEventListener('hashchange', parseHash)
-  const settings = await getSettings()
-  if (settings?.rp_name) document.title = settings.rp_name + ' Admin'
-  load()
-})
+function reloadPage() {
+  window.location.reload()
+}
 
 const selectedOrg = computed(() => orgs.value.find(o => o.uuid === currentOrgId.value) || null)
 
@@ -350,10 +350,7 @@ const breadcrumbEntries = computed(() => {
 watch(selectedUser, async (u) => {
   if (!u) { userDetail.value = null; return }
   try {
-  const res = await fetch(`/auth/admin/orgs/${u.org_uuid}/users/${u.uuid}`)
-    const data = await res.json()
-    if (data.detail) throw new Error(data.detail)
-    userDetail.value = data
+    userDetail.value = await apiJson(`/auth/api/admin/orgs/${u.org_uuid}/users/${u.uuid}`)
   } catch (e) {
     userDetail.value = { error: e.message }
   }
@@ -389,9 +386,7 @@ async function toggleOrgPermission(org, permId, checked) {
   org.permissions = next
   try {
     const params = new URLSearchParams({ permission_id: permId })
-    const res = await fetch(`/auth/admin/orgs/${org.uuid}/permission?${params.toString()}`, { method: checked ? 'POST' : 'DELETE' })
-    const data = await res.json()
-    if (data.detail) throw new Error(data.detail)
+    await apiJson(`/auth/api/admin/orgs/${org.uuid}/permission?${params.toString()}`, { method: checked ? 'POST' : 'DELETE' })
     await loadOrgs()
   } catch (e) {
     authStore.showMessage(e.message || 'Failed to update organization permission')
@@ -402,16 +397,17 @@ async function toggleOrgPermission(org, permId, checked) {
 function openDialog(type, data) { dialog.value = { type, data, busy: false, error: '' } }
 function closeDialog() { dialog.value = { type: null, data: null, busy: false, error: '' } }
 
-async function onUserNameSaved() {
+async function refreshUserDetail() {
   await loadOrgs()
   if (selectedUser.value) {
     try {
-  const r = await fetch(`/auth/admin/orgs/${selectedUser.value.org_uuid}/users/${selectedUser.value.uuid}`)
-      const jd = await r.json()
-      if (!r.ok || jd.detail) throw new Error(jd.detail || 'Reload failed')
-      userDetail.value = jd
+      userDetail.value = await apiJson(`/auth/api/admin/orgs/${selectedUser.value.org_uuid}/users/${selectedUser.value.uuid}`)
     } catch (e) { authStore.showMessage(e.message || 'Failed to reload user', 'error') }
   }
+}
+
+async function onUserNameSaved() {
+  await refreshUserDetail()
   authStore.showMessage('User renamed', 'success', 1500)
 }
 
@@ -422,53 +418,48 @@ async function submitDialog() {
     const t = dialog.value.type
     if (t === 'org-create') {
       const name = dialog.value.data.name?.trim(); if (!name) throw new Error('Name required')
-      const res = await fetch('/auth/admin/orgs', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ display_name: name, permissions: [] }) })
-      const d = await res.json(); if (d.detail) throw new Error(d.detail); await Promise.all([loadOrgs(), loadPermissions()])
+      await apiJson('/auth/api/admin/orgs', { method: 'POST', body: { display_name: name, permissions: [] } })
+      await Promise.all([loadOrgs(), loadPermissions()])
     } else if (t === 'org-update') {
       const { org } = dialog.value.data; const name = dialog.value.data.name?.trim(); if (!name) throw new Error('Name required')
-      const res = await fetch(`/auth/admin/orgs/${org.uuid}`, { method: 'PUT', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ display_name: name, permissions: org.permissions }) })
-      const d = await res.json(); if (d.detail) throw new Error(d.detail); await loadOrgs()
+      await apiJson(`/auth/api/admin/orgs/${org.uuid}`, { method: 'PUT', body: { display_name: name, permissions: org.permissions } })
+      await loadOrgs()
     } else if (t === 'role-create') {
       const { org } = dialog.value.data; const name = dialog.value.data.name?.trim(); if (!name) throw new Error('Name required')
-      const res = await fetch(`/auth/admin/orgs/${org.uuid}/roles`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ display_name: name, permissions: [] }) })
-      const d = await res.json(); if (d.detail) throw new Error(d.detail); await loadOrgs()
+      await apiJson(`/auth/api/admin/orgs/${org.uuid}/roles`, { method: 'POST', body: { display_name: name, permissions: [] } })
+      await loadOrgs()
     } else if (t === 'role-update') {
       const { role } = dialog.value.data; const name = dialog.value.data.name?.trim(); if (!name) throw new Error('Name required')
-      const res = await fetch(`/auth/admin/orgs/${role.org_uuid}/roles/${role.uuid}`, { method: 'PUT', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ display_name: name, permissions: role.permissions }) })
-      const d = await res.json(); if (d.detail) throw new Error(d.detail); await loadOrgs()
+      await apiJson(`/auth/api/admin/orgs/${role.org_uuid}/roles/${role.uuid}`, { method: 'PUT', body: { display_name: name, permissions: role.permissions } })
+      await loadOrgs()
     } else if (t === 'user-create') {
       const { org, role } = dialog.value.data; const name = dialog.value.data.name?.trim(); if (!name) throw new Error('Name required')
-      const res = await fetch(`/auth/admin/orgs/${org.uuid}/users`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ display_name: name, role: role.display_name }) })
-      const d = await res.json(); if (d.detail) throw new Error(d.detail); await loadOrgs()
+      await apiJson(`/auth/api/admin/orgs/${org.uuid}/users`, { method: 'POST', body: { display_name: name, role: role.display_name } })
+      await loadOrgs()
     } else if (t === 'user-update-name') {
       const { user } = dialog.value.data; const name = dialog.value.data.name?.trim(); if (!name) throw new Error('Name required')
-      const res = await fetch(`/auth/admin/orgs/${user.org_uuid}/users/${user.uuid}/display-name`, { method: 'PUT', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ display_name: name }) })
-      const d = await res.json(); if (d.detail) throw new Error(d.detail); await onUserNameSaved()
+      await apiJson(`/auth/api/admin/orgs/${user.org_uuid}/users/${user.uuid}/display-name`, { method: 'PUT', body: { display_name: name } })
+      await onUserNameSaved()
     } else if (t === 'perm-display') {
       const { permission } = dialog.value.data
       const newId = dialog.value.data.id?.trim()
       const newDisplay = dialog.value.data.display_name?.trim()
       if (!newDisplay) throw new Error('Display name required')
       if (!newId) throw new Error('ID required')
-      
+
       if (newId !== permission.id) {
         // ID changed, use rename endpoint
-        const body = { old_id: permission.id, new_id: newId, display_name: newDisplay }
-        const res = await fetch('/auth/admin/permission/rename', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) })
-        let data; try { data = await res.json() } catch(_) { data = {} }
-        if (!res.ok || data.detail) throw new Error(data.detail || data.error || `Failed (${res.status})`)
+        await apiJson('/auth/api/admin/permission/rename', { method: 'POST', body: { old_id: permission.id, new_id: newId, display_name: newDisplay } })
       } else if (newDisplay !== permission.display_name) {
         // Only display name changed
         const params = new URLSearchParams({ permission_id: permission.id, display_name: newDisplay })
-        const res = await fetch(`/auth/admin/permission?${params.toString()}`, { method: 'PUT' })
-        const d = await res.json(); if (d.detail) throw new Error(d.detail)
+        await apiJson(`/auth/api/admin/permission?${params.toString()}`, { method: 'PUT' })
       }
       await loadPermissions()
     } else if (t === 'perm-create') {
       const id = dialog.value.data.id?.trim(); if (!id) throw new Error('ID required')
       const display_name = dialog.value.data.display_name?.trim(); if (!display_name) throw new Error('Display name required')
-      const res = await fetch('/auth/admin/permissions', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ id, display_name }) })
-      const data = await res.json(); if (data.detail) throw new Error(data.detail)
+      await apiJson('/auth/api/admin/permissions', { method: 'POST', body: { id, display_name } })
       await loadPermissions(); dialog.value.data.display_name = ''; dialog.value.data.id = ''
     } else if (t === 'confirm') {
       const action = dialog.value.data.action; if (action) await action()
@@ -484,76 +475,71 @@ async function submitDialog() {
   <div class="app-shell admin-shell">
     <StatusMessage />
     <main class="app-main">
-      <section class="view-root view-admin">
-        <div class="view-content view-content--wide">
-          <header class="view-header">
-            <h1>{{ pageHeading }}</h1>
-            <Breadcrumbs :entries="breadcrumbEntries" />
-          </header>
+      <LoadingView v-if="loading" :message="loadingMessage" />
+      <AuthRequiredMessage
+        v-else-if="showBackMessage"
+        @reload="reloadPage"
+      />
+      <section v-else-if="authenticated && (info?.is_global_admin || info?.is_org_admin)" class="view-root view-root--wide view-admin">
+        <header class="view-header">
+          <h1>{{ pageHeading }}</h1>
+          <Breadcrumbs :entries="breadcrumbEntries" />
+        </header>
 
-          <section class="section-block admin-section">
-            <div class="section-body admin-section-body">
-              <div v-if="loading" class="surface surface--tight">Loading…</div>
-              <div v-else-if="error" class="surface surface--tight error">{{ error }}</div>
-              <template v-else>
-                <div v-if="!info?.authenticated" class="surface surface--tight">
-                  <p>You must be authenticated.</p>
-                </div>
-                <div v-else-if="!(info?.is_global_admin || info?.is_org_admin)" class="surface surface--tight">
-                  <p>Insufficient permissions.</p>
-                </div>
-                <div v-else class="admin-panels">
-                                    <AdminOverview
-                    v-if="!selectedUser && !selectedOrg && (info.is_global_admin || info.is_org_admin)"
-                    :info="info"
-                    :orgs="orgs"
-                    :permissions="permissions"
-                    :permission-summary="permissionSummary"
-                    @create-org="createOrg"
-                    @open-org="openOrg"
-                    @update-org="updateOrg"
-                    @delete-org="deleteOrg"
-                    @toggle-org-permission="toggleOrgPermission"
-                    @open-dialog="openDialog"
-                    @delete-permission="deletePermission"
-                    @rename-permission-display="renamePermissionDisplay"
-                  />
+        <section class="section-block admin-section">
+          <div class="section-body admin-section-body">
+            <div v-if="error" class="surface surface--tight error">{{ error }}</div>
+            <div v-else class="admin-panels">
+                                  <AdminOverview
+                  v-if="!selectedUser && !selectedOrg && (info.is_global_admin || info.is_org_admin)"
+                  :info="info"
+                  :orgs="orgs"
+                  :permissions="permissions"
+                  :permission-summary="permissionSummary"
+                  @create-org="createOrg"
+                  @open-org="openOrg"
+                  @update-org="updateOrg"
+                  @delete-org="deleteOrg"
+                  @toggle-org-permission="toggleOrgPermission"
+                  @open-dialog="openDialog"
+                  @delete-permission="deletePermission"
+                  @rename-permission-display="renamePermissionDisplay"
+                />
 
-                  <AdminUserDetail
-                    v-else-if="selectedUser"
-                    :selected-user="selectedUser"
-                    :user-detail="userDetail"
-                    :selected-org="selectedOrg"
-                    :loading="loading"
-                    :show-reg-modal="showRegModal"
-                    @generate-user-registration-link="generateUserRegistrationLink"
-                    @go-overview="goOverview"
-                    @open-org="openOrg"
-                    @on-user-name-saved="onUserNameSaved"
-                    @edit-user-name="editUserName"
-                    @close-reg-modal="showRegModal = false"
-                  />
-                  <AdminOrgDetail
-                    v-else-if="selectedOrg"
-                    :selected-org="selectedOrg"
-                    :permissions="permissions"
-                    @update-org="updateOrg"
-                    @create-role="createRole"
-                    @update-role="updateRole"
-                    @delete-role="deleteRole"
-                    @create-user-in-role="createUserInRole"
-                    @open-user="openUser"
-                    @toggle-role-permission="toggleRolePermission"
-                    @on-role-drag-over="onRoleDragOver"
-                    @on-role-drop="onRoleDrop"
-                    @on-user-drag-start="onUserDragStart"
-                  />
+                <AdminUserDetail
+                  v-else-if="selectedUser"
+                  :selected-user="selectedUser"
+                  :user-detail="userDetail"
+                  :selected-org="selectedOrg"
+                  :loading="loading"
+                  :show-reg-modal="showRegModal"
+                  @generate-user-registration-link="generateUserRegistrationLink"
+                  @go-overview="goOverview"
+                  @open-org="openOrg"
+                  @on-user-name-saved="onUserNameSaved"
+                  @refresh-user-detail="refreshUserDetail"
+                  @edit-user-name="editUserName"
+                  @close-reg-modal="showRegModal = false"
+                />
+                <AdminOrgDetail
+                  v-else-if="selectedOrg"
+                  :selected-org="selectedOrg"
+                  :permissions="permissions"
+                  @update-org="updateOrg"
+                  @create-role="createRole"
+                  @update-role="updateRole"
+                  @delete-role="deleteRole"
+                  @create-user-in-role="createUserInRole"
+                  @open-user="openUser"
+                  @toggle-role-permission="toggleRolePermission"
+                  @on-role-drag-over="onRoleDragOver"
+                  @on-role-drop="onRoleDrop"
+                  @on-user-drag-start="onUserDragStart"
+                />
 
-                </div>
-              </template>
-            </div>
-          </section>
-        </div>
+              </div>
+          </div>
+        </section>
       </section>
     </main>
     <AdminDialogs

frontend/auth/admin/index.html

@@ -7,6 +7,6 @@
   </head>
   <body>
     <div id="admin-app"></div>
-    <script type="module" src="/src/admin/main.js"></script>
+    <script type="module" src="./main.js"></script>
   </body>
   </html>

frontend/auth/admin/main.js

@@ -1,4 +1,4 @@
-import '../assets/style.css'
+import '@/assets/style.css'
 
 import { createApp } from 'vue'
 import { createPinia } from 'pinia'

frontend/auth/index.html

@@ -7,6 +7,6 @@
   </head>
   <body>
     <div id="app"></div>
-    <script type="module" src="/src/main.js"></script>
+    <script type="module" src="main.js"></script>
   </body>
 </html>

frontend/auth/main.js

@@ -1,4 +1,4 @@
-import './assets/style.css'
+import '@/assets/style.css'
 
 import { createApp } from 'vue'
 import { createPinia } from 'pinia'

frontend/auth/restricted/RestrictedApi.vue

@@ -0,0 +1,76 @@
+<template>
+  <RestrictedAuth
+    :mode="authMode"
+    :remote-auth-token="remoteAuthToken"
+    @authenticated="handleAuthenticated"
+    @back="handleBack"
+  />
+</template>
+
+<script setup>
+import { computed, onMounted, ref } from 'vue'
+import RestrictedAuth from '@/components/RestrictedAuth.vue'
+
+// Check if this is a remote auth URL: /auth/{token}
+// The token is a 5-word passphrase like "word1.word2.word3.word4.word5"
+const remoteAuthToken = ref(null)
+
+function extractRemoteToken() {
+  const path = window.location.pathname
+  // Match /auth/{token} where token is a passphrase with dots
+  const match = path.match(/\/auth\/([^/]+)$/)
+  if (match) {
+    const token = match[1]
+    // Validate it looks like a 5-word passphrase
+    const parts = token.split('.')
+    if (parts.length === 5 && parts.every(p => p.length > 0)) {
+      return token
+    }
+  }
+  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'
+})
+
+function postToParent(message) {
+  if (window.parent && window.parent !== window) {
+    window.parent.postMessage(message, '*')
+  }
+}
+
+function handleAuthenticated(result) {
+  postToParent({
+    type: 'auth-success',
+    authenticated: true,
+    sessionToken: result.session_token
+  })
+}
+
+function handleBack() {
+  postToParent({
+    type: 'auth-back'
+  })
+}
+
+onMounted(() => {
+  // Check for remote auth token in URL
+  remoteAuthToken.value = extractRemoteToken()
+
+  postToParent({
+    type: 'auth-ready'
+  })
+
+  window.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape') {
+      handleBack()
+    }
+  })
+})
+</script>

frontend/auth/restricted/index.html

@@ -0,0 +1,4 @@
+<html style="background: transparent"><meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<div id="app"></div>
+<script type="module" src="/auth/restricted/main.js"></script>

frontend/auth/restricted/main.js

@@ -0,0 +1,5 @@
+import { createApp } from 'vue'
+import RestrictedApi from './RestrictedApi.vue'
+import '@/assets/style.css'
+
+createApp(RestrictedApi).mount('#app')

frontend/host/index.html

@@ -1,12 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Account Summary</title>
-  </head>
-  <body>
-    <div id="app"></div>
-    <script type="module" src="/src/host/main.js"></script>
-  </body>
-</html>

frontend/int/forward/RestrictedForward.vue

@@ -0,0 +1,45 @@
+<template>
+  <RestrictedAuth
+    :mode="authMode"
+    @authenticated="handleAuthenticated"
+    @back="goBack"
+    @home="returnHome"
+  />
+</template>
+
+<script setup>
+import { computed, onMounted } from 'vue'
+import RestrictedAuth from '@/components/RestrictedAuth.vue'
+import { uiBasePath } from '@/utils/settings'
+import { goBack } from '@/utils/helpers'
+
+const basePath = computed(() => uiBasePath())
+
+// Detect mode from data attribute on html tag only
+// (RestrictedApi uses URL query, RestrictedForward uses data injected by server)
+const authMode = computed(() => {
+  const htmlElement = document.documentElement
+  const dataMode = htmlElement.getAttribute('data-mode')
+  if (dataMode === 'reauth') return 'reauth'
+  if (dataMode === 'forbidden') return 'forbidden'
+  return 'login'
+})
+
+function handleAuthenticated() {
+  // Reload page to re-trigger forward auth validation
+  location.reload()
+}
+
+function returnHome() {
+  const target = basePath.value || '/auth/'
+  if (window.location.pathname !== target) history.replaceState(null, '', target)
+  window.location.href = target
+}
+
+onMounted(() => {
+  // Handle Escape key to trigger back navigation
+  window.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape') goBack()
+  })
+})
+</script>

frontend/int/forward/index.html

@@ -7,6 +7,6 @@
   </head>
   <body>
     <div id="app"></div>
-    <script type="module" src="/src/restricted/main.js"></script>
+    <script type="module" src="/int/forward/main.js"></script>
   </body>
 </html>

frontend/int/forward/main.js

@@ -0,0 +1,5 @@
+import { createApp } from 'vue'
+import App from './RestrictedForward.vue'
+import '@/assets/style.css'
+
+createApp(App).mount('#app')

frontend/int/reset/ResetApp.vue

@@ -7,52 +7,49 @@
     </div>
 
     <main class="view-root">
-      <div class="view-content">
-        <div class="surface surface--tight" style="max-width: 560px; margin: 0 auto; width: 100%;">
-          <header class="view-header" style="text-align: center;">
-            <h1>🔑 Registration</h1>
-            <p class="view-lede">
-              {{ subtitleMessage }}
-            </p>
-          </header>
+      <div class="surface surface--tight" style="max-width: 560px; margin: 0 auto; width: 100%;">
+        <header class="view-header" style="text-align: center;">
+          <h1>🔑 Registration</h1>
+          <p class="view-lede">
+            {{ subtitleMessage }}
+          </p>
+        </header>
 
-          <section class="section-block" v-if="initializing">
-            <div class="section-body center">
-              <p>Loading reset details…</p>
+        <section class="section-block" v-if="initializing">
+          <div class="section-body center">
+            <p>Loading reset details…</p>
+          </div>
+        </section>
+
+        <section class="section-block" v-else-if="!canRegister">
+          <div class="section-body center">
+            <div class="button-row center" style="justify-content: center;">
+              <button class="btn-secondary" @click="goHome">Return to sign-in</button>
             </div>
-          </section>
+          </div>
+        </section>
 
-          <section class="section-block" v-else-if="!canRegister">
-            <div class="section-body center">
-              <p>{{ errorMessage }}</p>
-              <div class="button-row center" style="justify-content: center;">
-                <button class="btn-secondary" @click="goHome">Return to sign-in</button>
-              </div>
-            </div>
-          </section>
-
-          <section class="section-block" v-else>
-            <div class="section-body">
-              <label class="name-edit">
-                <span>👤 Name</span>
-                <input
-                  type="text"
-                  v-model="displayName"
-                  :disabled="loading"
-                  maxlength="64"
-                  @keyup.enter="registerPasskey"
-                />
-              </label>
-              <button
-                class="btn-primary"
+        <section class="section-block" v-else>
+          <div class="section-body">
+            <label class="name-edit">
+              <span>👤 Name</span>
+              <input
+                type="text"
+                v-model="displayName"
                 :disabled="loading"
-                @click="registerPasskey"
-              >
-                {{ loading ? 'Registering…' : 'Register Passkey' }}
-              </button>
-            </div>
-          </section>
-        </div>
+                maxlength="64"
+                @keyup.enter="registerPasskey"
+              />
+            </label>
+            <button
+              class="btn-primary"
+              :disabled="loading"
+              @click="registerPasskey"
+            >
+              {{ loading ? 'Registering…' : 'Register Passkey' }}
+            </button>
+          </div>
+        </section>
       </div>
     </main>
   </div>
@@ -62,6 +59,7 @@
 import { computed, onMounted, reactive, ref } from 'vue'
 import passkey from '@/utils/passkey'
 import { getSettings, uiBasePath } from '@/utils/settings'
+import { apiJson, ApiError, getUserFriendlyErrorMessage } from '@/utils/api'
 
 const status = reactive({
   show: false,
@@ -81,7 +79,7 @@ let statusTimer = null
 const sessionDescriptor = computed(() => userInfo.value?.session_type || 'your enrollment')
 const subtitleMessage = computed(() => {
   if (initializing.value) return 'Preparing your secure enrollment…'
-  if (!canRegister.value) return 'This reset link is no longer valid.'
+  if (!canRegister.value) return 'This authentication link is no longer valid.'
   return `Finish up ${sessionDescriptor.value}. You may edit the name below if needed, and it will be saved to your passkey.`
 })
 
@@ -114,23 +112,16 @@ async function fetchSettings() {
 async function fetchUserInfo() {
   if (!token.value) return
   try {
-    const res = await fetch(`/auth/api/user-info?reset=${encodeURIComponent(token.value)}`, {
+    userInfo.value = await apiJson(`/auth/api/user-info?reset=${encodeURIComponent(token.value)}`, {
       method: 'POST'
     })
-    if (!res.ok) {
-      const payload = await safeParseJson(res)
-      const detail = payload?.detail || 'Reset link is invalid or expired.'
-      errorMessage.value = detail
-      showMessage(detail, 'error', 0)
-      return
-    }
-    userInfo.value = await res.json()
     displayName.value = userInfo.value?.user?.user_name || ''
   } catch (error) {
     console.error('Failed to load user info', error)
-    const message = 'We could not load your reset details. Try refreshing the page.'
+    const message = error instanceof ApiError
+      ? (error.data?.detail || 'The authentication link is invalid or expired.')
+      : getUserFriendlyErrorMessage(error)
     errorMessage.value = message
-    showMessage(message, 'error', 0)
   }
 }
 
@@ -152,7 +143,7 @@ async function registerPasskey() {
   }
 
   try {
-    await setSessionCookie(result.session_token)
+    await setSessionCookie(result)
   } catch (error) {
     loading.value = false
     const message = error?.message || 'Failed to establish session'
@@ -160,29 +151,23 @@ async function registerPasskey() {
     return
   }
 
-  showMessage('Passkey registered successfully!', 'success', 2000)
-  setTimeout(() => {
-    loading.value = false
-    redirectHome()
-  }, 800)
+  showMessage('Passkey registered successfully!', 'success', 800)
+  setTimeout(() => { loading.value = false; goHome() }, 800)
 }
 
-async function setSessionCookie(sessionToken) {
-  const response = await fetch('/auth/api/set-session', {
+async function setSessionCookie(result) {
+  if (!result?.session_token) {
+    throw new Error('Registration response missing session_token')
+  }
+  return await apiJson('/auth/api/set-session', {
     method: 'POST',
     headers: {
-      Authorization: `Bearer ${sessionToken}`
+      Authorization: `Bearer ${result.session_token}`
     }
   })
-  const payload = await safeParseJson(response)
-  if (!response.ok || payload?.detail) {
-    const detail = payload?.detail || 'Session could not be established.'
-    throw new Error(detail)
-  }
-  return payload
 }
 
-function redirectHome() {
+function goHome() {
   const target = uiBasePath.value || '/auth/'
   if (window.location.pathname !== target) {
     history.replaceState(null, '', target)
@@ -190,10 +175,6 @@ function redirectHome() {
   window.location.reload()
 }
 
-function goHome() {
-  redirectHome()
-}
-
 function extractTokenFromPath() {
   const segments = window.location.pathname.split('/').filter(Boolean)
   if (!segments.length) return ''
@@ -205,14 +186,6 @@ function extractTokenFromPath() {
   return candidate
 }
 
-async function safeParseJson(response) {
-  try {
-    return await response.json()
-  } catch (error) {
-    return null
-  }
-}
-
 onMounted(async () => {
   token.value = extractTokenFromPath()
   await fetchSettings()

frontend/int/reset/index.html

@@ -7,6 +7,6 @@
   </head>
   <body>
     <div id="app"></div>
-    <script type="module" src="/src/reset/main.js"></script>
+    <script type="module" src="/int/reset/main.js"></script>
   </body>
 </html>

frontend/package.json

@@ -12,6 +12,7 @@
     "@simplewebauthn/browser": "^13.1.2",
     "pinia": "^3.0.3",
     "qrcode": "^1.5.4",
+    "sirv": "^3.0.2",
     "vue": "^3.5.17"
   },
   "devDependencies": {

frontend/src/App.vue

@@ -1,35 +0,0 @@
-<template>
-  <div class="app-shell">
-    <StatusMessage />
-    <main class="app-main">
-      <ProfileView v-if="initialized" />
-      <div v-else class="loading-container">
-        <div class="loading-spinner"></div>
-        <p>Loading...</p>
-      </div>
-    </main>
-  </div>
-</template>
-
-<script setup>
-import { onMounted, ref } from 'vue'
-import { useAuthStore } from '@/stores/auth'
-import StatusMessage from '@/components/StatusMessage.vue'
-import ProfileView from '@/components/ProfileView.vue'
-const store = useAuthStore()
-const initialized = ref(false)
-
-onMounted(async () => {
-  await store.loadSettings()
-  if (store.settings?.rp_name) document.title = store.settings.rp_name
-  try { await store.loadUserInfo() } catch (_) { /* user info load errors ignored */ }
-  initialized.value = true
-})
-</script>
-
-<style scoped>
-.loading-container { display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100vh; gap: 1rem; }
-.loading-spinner { width: 40px; height: 40px; border: 4px solid var(--color-border); border-top: 4px solid 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; }
-</style>

frontend/src/admin/AdminUserDetail.vue

@@ -5,6 +5,7 @@ import CredentialList from '@/components/CredentialList.vue'
 import RegistrationLinkModal from '@/components/RegistrationLinkModal.vue'
 import SessionList from '@/components/SessionList.vue'
 import { useAuthStore } from '@/stores/auth'
+import { apiJson } from '@/utils/api'
 
 const props = defineProps({
   selectedUser: Object,
@@ -14,9 +15,12 @@ const props = defineProps({
   showRegModal: Boolean
 })
 
-const emit = defineEmits(['generateUserRegistrationLink', 'goOverview', 'openOrg', 'onUserNameSaved', 'closeRegModal', 'editUserName'])
+const emit = defineEmits(['generateUserRegistrationLink', 'goOverview', 'openOrg', 'onUserNameSaved', 'closeRegModal', 'editUserName', 'refreshUserDetail'])
 
 const authStore = useAuthStore()
+const terminatingSessions = ref({})
+const hoveredCredentialUuid = ref(null)
+const hoveredSession = ref(null)
 
 function onLinkCopied() {
   authStore.showMessage('Link copied to clipboard!')
@@ -26,17 +30,44 @@ function handleEditName() {
   emit('editUserName', props.selectedUser)
 }
 
-function handleDelete(credential) {
-  fetch(`/auth/admin/orgs/${props.selectedUser.org_uuid}/users/${props.selectedUser.uuid}/credentials/${credential.credential_uuid}`, { method: 'DELETE' })
-    .then(res => res.json())
-    .then(data => {
-      if (data.status === 'ok') {
-        emit('onUserNameSaved') // Reuse to refresh user detail
-      } else {
-        console.error('Failed to delete credential', data)
+async function handleDelete(credential) {
+  try {
+    const data = await apiJson(`/auth/api/admin/orgs/${props.selectedUser.org_uuid}/users/${props.selectedUser.uuid}/credentials/${credential.credential_uuid}`, { method: 'DELETE' })
+    if (data.status === 'ok') {
+      emit('onUserNameSaved') // Reuse to refresh user detail
+    } else {
+      console.error('Failed to delete credential', data)
+    }
+  } catch (err) {
+    console.error('Delete credential error', err)
+  }
+}
+
+async function handleTerminateSession(session) {
+  const sessionId = session?.id
+  if (!sessionId) return
+  terminatingSessions.value = { ...terminatingSessions.value, [sessionId]: true }
+  try {
+    const data = await apiJson(`/auth/api/admin/orgs/${props.selectedUser.org_uuid}/users/${props.selectedUser.uuid}/sessions/${sessionId}`, { method: 'DELETE' })
+    if (data.status === 'ok') {
+      if (data.current_session_terminated) {
+        sessionStorage.clear()
+        location.reload()
+        return
       }
-    })
-    .catch(err => console.error('Delete credential error', err))
+      emit('refreshUserDetail') // Refresh without showing rename message
+      authStore.showMessage('Session terminated', 'success', 2500)
+    } else {
+      authStore.showMessage(data.detail || 'Failed to terminate session', 'error')
+    }
+  } catch (err) {
+    console.error('Terminate session error', err)
+    authStore.showMessage(err.message || 'Failed to terminate session', 'error')
+  } finally {
+    const next = { ...terminatingSessions.value }
+    delete next[sessionId]
+    terminatingSessions.value = next
+  }
 }
 
 </script>
@@ -52,7 +83,7 @@ function handleDelete(credential) {
       :loading="loading"
       :org-display-name="userDetail.org.display_name"
       :role-name="userDetail.role"
-      :update-endpoint="`/auth/admin/orgs/${selectedUser.org_uuid}/users/${selectedUser.uuid}/display-name`"
+      :update-endpoint="`/auth/api/admin/orgs/${selectedUser.org_uuid}/users/${selectedUser.uuid}/display-name`"
       @saved="$emit('onUserNameSaved')"
       @edit-name="handleEditName"
     />
@@ -78,15 +109,21 @@ function handleDelete(credential) {
             :credentials="userDetail.credentials"
             :aaguid-info="userDetail.aaguid_info"
             :allow-delete="true"
+            :hovered-credential-uuid="hoveredCredentialUuid"
+            :hovered-session-credential-uuid="hoveredSession?.credential_uuid"
             @delete="handleDelete"
+            @credential-hover="hoveredCredentialUuid = $event"
           />
         </div>
       </section>
       <SessionList
         :sessions="userDetail.sessions || []"
-        :allow-terminate="false"
+        :terminating-sessions="terminatingSessions"
+        :hovered-credential-uuid="hoveredCredentialUuid"
         :empty-message="'This user has no active sessions.'"
-        :section-description="'View the active sessions for this user.'"
+        :section-description="'View and manage the active sessions for this user.'"
+        @terminate="handleTerminateSession"
+        @session-hover="hoveredSession = $event"
       />
     </template>
     <div class="actions ancillary-actions">
@@ -94,8 +131,7 @@ function handleDelete(credential) {
     </div>
     <RegistrationLinkModal
       v-if="showRegModal"
-      :endpoint="`/auth/admin/orgs/${selectedUser.org_uuid}/users/${selectedUser.uuid}/create-link`"
-      :auto-copy="false"
+      :endpoint="`/auth/api/admin/orgs/${selectedUser.org_uuid}/users/${selectedUser.uuid}/create-link`"
       :user-name="userDetail?.display_name || selectedUser.display_name"
       @close="$emit('closeRegModal')"
       @copied="onLinkCopied"
@@ -115,4 +151,4 @@ function handleDelete(credential) {
 .error { color: var(--color-danger-text); }
 .small { font-size: 0.9rem; }
 .muted { color: var(--color-text-muted); }
-</style>
+</style>

frontend/src/assets/style.css

@@ -1,6 +1,5 @@
 
 :root {
-  color-scheme: light dark;
   --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: #f5f6f8;
@@ -35,14 +34,13 @@
   --space-lg: 1.5rem;
   --space-xl: 2.25rem;
   --space-xxl: 3.5rem;
-  --layout-max-width: 1080px;
+  --layout-max-width: 1400px;
   --layout-padding: clamp(1.5rem, 3vw + 1rem, 3.25rem);
   --transition-base: 160ms ease;
 }
 
 @media (prefers-color-scheme: dark) {
   :root {
-    color-scheme: dark;
     --color-canvas: #0f172a;
     --color-surface: #141b2f;
     --color-surface-subtle: #1b243b;
@@ -57,13 +55,13 @@
     --color-accent-strong: #3b82f6;
     --color-accent-contrast: #0b1120;
     --color-success-text: #34d399;
-    --color-success-bg: rgba(34, 197, 94, 0.12);
+    --color-success-bg: #1a4d2e;
     --color-error-text: #fca5a5;
-    --color-error-bg: rgba(248, 113, 113, 0.16);
+    --color-error-bg: #4a1f1f;
     --color-info-text: #bae6fd;
-    --color-info-bg: rgba(59, 130, 246, 0.16);
+    --color-info-bg: #1e3a5f;
     --color-danger: #f87171;
-    --shadow-soft: 0 0 0 rgba(0, 0, 0, 0);
+    --shadow-soft: 0 0 0 #000000;
   }
 }
 
@@ -73,15 +71,16 @@
   box-sizing: border-box;
 }
 
-html,
-body {
+html {
   height: 100%;
+  background: var(--color-canvas);
 }
 
 body {
+  height: 100%;
   margin: 0;
   font-family: var(--font-sans);
-  background: var(--color-canvas);
+  background: none;
   color: var(--color-text);
   line-height: 1.55;
   -webkit-font-smoothing: antialiased;
@@ -123,7 +122,6 @@ a:focus-visible {
   display: flex;
   flex-direction: column;
   min-height: 100vh;
-  background: var(--color-canvas);
 }
 
 .app-main {
@@ -136,23 +134,22 @@ a:focus-visible {
   flex: 1;
   width: 100%;
   display: flex;
-  padding: var(--layout-padding);
-  box-sizing: border-box;
-}
-
-.view-content {
-  flex: 1;
-  display: flex;
   flex-direction: column;
   gap: 2rem;
+  padding: var(--layout-padding);
+  box-sizing: border-box;
   margin: 0 auto;
   width: min(100%, var(--layout-max-width));
 }
 
-.view-content--wide {
+.view-root--wide {
   width: min(100%, 1200px);
 }
 
+.view-root--narrow {
+  max-width: 540px;
+}
+
 .view-header {
   display: flex;
   flex-direction: column;
@@ -232,8 +229,8 @@ button:focus-visible {
 }
 
 button:disabled {
-  opacity: 0.6;
   cursor: not-allowed;
+  filter: opacity(0.6);
 }
 
 .btn-primary {
@@ -288,7 +285,7 @@ input:focus-visible,
 textarea:focus-visible,
 select:focus-visible {
   border-color: var(--color-accent);
-  box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.15);
+  box-shadow: 0 0 0 3px #c7d2fe;
   outline: none;
 }
 
@@ -372,19 +369,19 @@ th {
 }
 
 .status.info {
-  border-color: rgba(14, 96, 155, 0.28);
+  border-color: #3b82f6;
   color: var(--color-info-text);
   background: var(--color-info-bg);
 }
 
 .status.success {
-  border-color: rgba(6, 118, 71, 0.22);
+  border-color: #16a34a;
   color: var(--color-success-text);
   background: var(--color-success-bg);
 }
 
 .status.error {
-  border-color: rgba(180, 35, 24, 0.28);
+  border-color: #dc2626;
   color: var(--color-error-text);
   background: var(--color-error-bg);
 }
@@ -392,8 +389,9 @@ th {
 .dialog-overlay {
   position: fixed;
   inset: 0;
-  background: rgba(9, 14, 24, 0.55);
-  backdrop-filter: blur(6px);
+  background: transparent;
+  backdrop-filter: blur(.1rem) brightness(0.7);
+  -webkit-backdrop-filter: blur(.1rem) brightness(0.7);
   z-index: 1100;
   display: flex;
   align-items: center;
@@ -424,9 +422,9 @@ th {
 }
 
 .qr-code {
-  border: 1px solid var(--color-border);
-  padding: 0.75rem;
-  background: var(--color-surface);
+  padding: 1rem;
+  background: #fff;
+  box-shadow: var(--shadow-soft);
 }
 
 .link-container,
@@ -447,18 +445,11 @@ th {
   width: 100%;
   display: grid;
   grid-auto-flow: row;
-  grid-template-columns: repeat(auto-fit, var(--card-width));
+  grid-template-columns: repeat(auto-fill, minmax(var(--card-width), 1fr));
   justify-content: start;
   gap: 1rem 1.25rem;
   align-items: stretch;
   margin: 0 auto;
-  max-width: calc(var(--card-width) * 4 + 3 * 1.25rem);
-}
-
-@media (max-width: 1100px) {
-  .record-list,
-  .credential-list,
-  .session-list { max-width: calc(var(--card-width) * 3 + 2 * 1.25rem); }
 }
 
 @media (max-width: 720px) {
@@ -478,6 +469,7 @@ th {
   height: 100%;
   transition: border-color 0.2s ease, box-shadow 0.2s ease, transform 0.2s ease;
   position: relative;
+  cursor: pointer;
 }
 
 .record-item:hover,
@@ -490,7 +482,12 @@ th {
 
 .record-item.is-current,
 .credential-item.current-session,
-.session-item.is-current { border-color: var(--color-accent); }
+.credential-item.is-hovered,
+.session-item.is-current,
+.session-item.is-hovered { border-color: var(--color-accent); }
+
+.credential-item.is-linked-session,
+.session-item.is-linked-credential { border-color: var(--color-accent); background-color: var(--color-surface-subtle); }
 
 .item-top {
   display: flex;
@@ -568,8 +565,8 @@ 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: rgba(220, 38, 38, 0.08); }
-.btn-card-delete:disabled { opacity: 0.4; cursor: not-allowed; }
+.btn-card-delete:hover:not(:disabled) { background: #fee; }
+.btn-card-delete:disabled { filter: opacity(0.4); cursor: not-allowed; }
 
 
 .session-emoji {
@@ -653,9 +650,6 @@ th {
 @media (max-width: 720px) {
   .view-root {
     padding: clamp(1rem, 3vw + 0.75rem, 2rem);
-  }
-
-  .view-content {
     gap: 1.75rem;
   }
 
@@ -664,6 +658,13 @@ th {
     grid-template-columns: auto auto;
   }
 
+  .global-status {
+    top: 1rem;
+  }
+}
+
+/* Mobile portrait (touch) or very narrow screens: stack buttons */
+@media (max-width: 500px) and (orientation: portrait) and (pointer: coarse), (max-width: 350px) {
   button {
     width: 100%;
   }
@@ -671,10 +672,6 @@ th {
   .button-row {
     flex-direction: column;
   }
-
-  .global-status {
-    top: 1rem;
-  }
 }
 
 .dialog-backdrop {
@@ -683,8 +680,9 @@ th {
   left: 0;
   width: 100vw;
   height: 100vh;
-  background: rgba(0, 0, 0, 0.5);
-  backdrop-filter: blur(4px);
+  background: transparent;
+  backdrop-filter: blur(.1rem) brightness(0.7);
+  -webkit-backdrop-filter: blur(.1rem) brightness(0.7);
   display: flex;
   align-items: center;
   justify-content: center;
@@ -704,7 +702,7 @@ th {
   padding: 2rem;
   background: var(--color-surface);
   border-radius: var(--radius-lg);
-  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
+  box-shadow: 0 20px 60px #1e293b;
   border: 1px solid var(--color-border);
 }
 
@@ -721,3 +719,22 @@ th {
     padding: 1.5rem;
   }
 }
+
+/* Auth iframe overlay styles */
+body:has(#auth-iframe) {
+  overflow: hidden;
+}
+
+#auth-iframe {
+  border: none;
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  z-index: 9999;
+  color-scheme: auto;
+  background: transparent;
+  backdrop-filter: blur(.1rem) brightness(0.7);
+  -webkit-backdrop-filter: blur(.1rem) brightness(0.7);
+}

frontend/src/components/AccessDenied.vue

@@ -0,0 +1,44 @@
+<template>
+  <div class="message-container">
+    <div class="message-content">
+      <h2>🔒 Access Denied</h2>
+      <div class="button-row">
+        <button class="btn-secondary" @click="goBack">Back</button>
+        <button class="btn-primary" @click="$emit('reload')">Reload Page</button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { goBack } from '@/utils/helpers'
+
+defineEmits(['reload'])
+</script>
+
+<style scoped>
+.message-container {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100vh;
+  padding: 2rem;
+}
+
+.message-content {
+  text-align: center;
+  max-width: 480px;
+}
+
+.message-content h2 {
+  margin: 0 0 1.5rem;
+  color: var(--color-heading);
+}
+
+.message-content .button-row {
+  display: flex;
+  gap: 0.75rem;
+  justify-content: center;
+}
+</style>

frontend/src/components/CredentialList.vue

@@ -6,7 +6,14 @@
       <div
         v-for="credential in credentials"
         :key="credential.credential_uuid"
-        :class="['credential-item', { 'current-session': credential.is_current_session } ]"
+        :class="['credential-item', {
+          'current-session': credential.is_current_session && !hoveredCredentialUuid && !hoveredSessionCredentialUuid,
+          'is-hovered': hoveredCredentialUuid === credential.credential_uuid,
+          'is-linked-session': hoveredSessionCredentialUuid === credential.credential_uuid
+        }]"
+        tabindex="0"
+        @focusin="handleCredentialFocus(credential.credential_uuid)"
+        @focusout="handleCredentialBlur($event)"
       >
         <div class="item-top">
           <div class="item-icon">
@@ -22,7 +29,9 @@
           </div>
           <h4 class="item-title">{{ getCredentialAuthName(credential) }}</h4>
           <div class="item-actions">
-            <span v-if="credential.is_current_session" class="badge badge-current">Current</span>
+            <span v-if="credential.is_current_session && !hoveredCredentialUuid && !hoveredSessionCredentialUuid" class="badge badge-current">Current</span>
+            <span v-else-if="hoveredCredentialUuid === credential.credential_uuid" class="badge badge-current">Selected</span>
+            <span v-else-if="hoveredSessionCredentialUuid === credential.credential_uuid" class="badge badge-current">Linked</span>
             <button
               v-if="allowDelete"
               @click="$emit('delete', credential)"
@@ -48,7 +57,7 @@
 </template>
 
 <script setup>
-import { computed } from 'vue'
+import { computed, ref } from 'vue'
 import { formatDate } from '@/utils/helpers'
 
 const props = defineProps({
@@ -56,8 +65,23 @@ const props = defineProps({
   aaguidInfo: { type: Object, default: () => ({}) },
   loading: { type: Boolean, default: false },
   allowDelete: { type: Boolean, default: false },
+  hoveredCredentialUuid: { type: String, default: null },
+  hoveredSessionCredentialUuid: { type: String, default: null },
 })
 
+const emit = defineEmits(['delete', 'credentialHover'])
+
+const handleCredentialFocus = (uuid) => {
+  emit('credentialHover', uuid)
+}
+
+const handleCredentialBlur = (event) => {
+  // Only clear if focus moved outside this element
+  if (!event.currentTarget.contains(event.relatedTarget)) {
+    emit('credentialHover', null)
+  }
+}
+
 const getCredentialAuthName = (credential) => {
   const info = props.aaguidInfo?.[credential.aaguid]
   return info ? info.name : 'Unknown Authenticator'

frontend/src/components/DeviceLinkView.vue

@@ -1,23 +1,20 @@
 <template>
-  <section class="view-root view-device-link">
-    <div class="view-content view-content--narrow">
-      <header class="view-header">
-        <h1>📱 Add Another Device</h1>
-        <p class="view-lede">Generate a one-time link to set up passkeys on a new device.</p>
-      </header>
-      <RegistrationLinkModal
-        inline
-                :endpoint="'/auth/api/user/create-link'"
-        :user-name="userName"
-        :auto-copy="false"
-        :prefix-copy-with-user-name="!!userName"
-        show-close-in-inline
-        @copied="onCopied"
-      />
-      <div class="button-row" style="margin-top:1rem;">
-        <button @click="authStore.currentView = 'profile'" class="btn-secondary">Back to Profile</button>
-      </div>
+  <section class="view-root view-root--narrow view-device-link">
+    <header class="view-header">
+      <h1>📱 Add Another Device</h1>
+      <p class="view-lede">Generate a one-time link to set up passkeys on a new device.</p>
+    </header>
+    <div class="button-row" style="margin-top:1rem;">
+      <button @click="showModal = true" class="btn-primary">Generate Registration Link</button>
+      <button @click="authStore.currentView = 'profile'" class="btn-secondary">Back to Profile</button>
     </div>
+    <RegistrationLinkModal
+      v-if="showModal"
+      endpoint="/auth/api/user/create-link"
+      :user-name="userName"
+      @close="showModal = false"
+      @copied="onCopied"
+    />
   </section>
 </template>
 
@@ -28,9 +25,10 @@ import RegistrationLinkModal from '@/components/RegistrationLinkModal.vue'
 
 const authStore = useAuthStore()
 const userName = ref(null)
+const showModal = ref(false)
+
 const onCopied = () => {
   authStore.showMessage('Link copied to clipboard!', 'success', 2500)
-  authStore.currentView = 'profile'
 }
 
 onMounted(async () => {
@@ -43,10 +41,6 @@ onMounted(async () => {
 </script>
 
 <style scoped>
-.view-content--narrow {
-  max-width: 540px;
-}
-
 .view-lede {
   margin: 0;
   color: var(--color-text-muted);

frontend/src/components/HostProfileView.vue

@@ -0,0 +1,121 @@
+<template>
+  <section class="view-root host-view" data-view="host-profile">
+    <header class="view-header">
+      <h1>{{ headingTitle }}</h1>
+      <p class="view-lede">{{ subheading }}</p>
+    </header>
+
+    <section class="section-block">
+      <div class="section-body">
+        <UserBasicInfo
+          v-if="user"
+          :name="user.user_name"
+          :visits="user.visits || 0"
+          :created-at="user.created_at"
+          :last-seen="user.last_seen"
+          :org-display-name="orgDisplayName"
+          :role-name="roleDisplayName"
+          :can-edit="false"
+        />
+        <p v-else class="empty-state">
+          {{ initializing ? 'Loading your account…' : 'No active session found.' }}
+        </p>
+      </div>
+    </section>
+
+    <section class="section-block">
+      <div class="section-body host-actions">
+        <div class="button-row">
+          <button
+            type="button"
+            class="btn-secondary"
+            @click="goBack"
+          >
+            Back
+          </button>
+          <button
+            type="button"
+            class="btn-danger"
+            :disabled="authStore.isLoading"
+            @click="logout"
+          >
+            {{ authStore.isLoading ? 'Signing out…' : 'Logout' }}
+          </button>
+          <button
+            v-if="authSiteUrl"
+            type="button"
+            class="btn-primary"
+            :disabled="authStore.isLoading"
+            @click="goToAuthSite"
+          >
+            Full Profile
+          </button>
+        </div>
+        <p class="note"><strong>Logout</strong> from {{ currentHost }}, or access your <strong>Full Profile</strong> at {{ authSiteHost }} (you may need to sign in again).</p>
+      </div>
+    </section>
+  </section>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+import UserBasicInfo from '@/components/UserBasicInfo.vue'
+import { useAuthStore } from '@/stores/auth'
+import { goBack } from '@/utils/helpers'
+
+defineProps({
+  initializing: {
+    type: Boolean,
+    default: false
+  }
+})
+
+const authStore = useAuthStore()
+const currentHost = window.location.host
+
+const user = computed(() => authStore.userInfo?.user || null)
+const orgDisplayName = computed(() => authStore.userInfo?.org?.display_name || '')
+const roleDisplayName = computed(() => authStore.userInfo?.role?.display_name || '')
+
+const headingTitle = computed(() => {
+  const service = authStore.settings?.rp_name
+  return service ? `${service} account` : 'Account overview'
+})
+
+const subheading = computed(() => {
+  return `You're signed in to ${currentHost}.`
+})
+
+const authSiteHost = computed(() => authStore.settings?.auth_host || '')
+const authSiteUrl = computed(() => {
+  const host = authSiteHost.value
+  if (!host) return ''
+  let path = authStore.settings?.ui_base_path ?? '/auth/'
+  if (!path.startsWith('/')) path = `/${path}`
+  if (!path.endsWith('/')) path = `${path}/`
+  const protocol = window.location.protocol || 'https:'
+  return `${protocol}//${host}${path}`
+})
+
+const goToAuthSite = () => {
+  if (!authSiteUrl.value) return
+  window.location.href = authSiteUrl.value
+}
+
+const logout = async () => {
+  await authStore.logout()
+}
+</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: 0 0 auto; }
+.note { margin: 0; color: var(--color-text-muted); }
+.empty-state { margin: 0; color: var(--color-text-muted); }
+@media (max-width: 600px) {
+  .host-actions .button-row { flex-direction: column; }
+  .host-actions .button-row button { width: 100%; }
+}
+</style>

frontend/src/components/LoadingView.vue

@@ -0,0 +1,45 @@
+<template>
+  <div class="loading-container">
+    <div class="loading-spinner"></div>
+    <p>{{ message }}</p>
+  </div>
+</template>
+
+<script setup>
+defineProps({
+  message: {
+    type: String,
+    default: 'Loading...'
+  }
+})
+</script>
+
+<style scoped>
+.loading-container {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100vh;
+  gap: 1rem;
+}
+
+.loading-spinner {
+  width: 40px;
+  height: 40px;
+  border: 4px solid var(--color-border);
+  border-top: 4px solid 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;
+}
+</style>

frontend/src/components/Modal.vue

@@ -17,8 +17,9 @@ defineEmits(['close'])
   left: 0;
   right: 0;
   bottom: 0;
-  background: rgba(0, 0, 0, 0.5);
-  backdrop-filter: blur(.1rem);
+  background: transparent;
+  backdrop-filter: blur(.1rem) brightness(0.7);
+  -webkit-backdrop-filter: blur(.1rem) brightness(0.7);
   display: flex;
   align-items: center;
   justify-content: center;
@@ -80,7 +81,7 @@ defineEmits(['close'])
 .modal :deep(.modal-form textarea:focus) {
   outline: none;
   border-color: var(--color-accent);
-  box-shadow: 0 0 0 2px rgba(37, 99, 235, 0.1);
+  box-shadow: 0 0 0 2px #c7d2fe;
 }
 
 .modal :deep(.modal-actions) {
@@ -90,4 +91,4 @@ defineEmits(['close'])
   margin-top: var(--space-md);
   margin-bottom: var(--space-xs);
 }
-</style>
+</style>

frontend/src/components/ProfileView.vue

@@ -1,92 +1,105 @@
 <template>
   <section class="view-root" data-view="profile">
-    <div class="view-content">
-      <header class="view-header">
-        <h1>👋 Welcome!</h1>
-        <Breadcrumbs :entries="breadcrumbEntries" />
-        <p class="view-lede">Manage your account details and passkeys.</p>
-      </header>
+    <header class="view-header">
+      <h1>User Profile</h1>
+      <Breadcrumbs :entries="breadcrumbEntries" />
+      <p class="view-lede">Account dashboard for managing credentials and authenticating with other devices.</p>
+    </header>
 
-      <section class="section-block">
-        <UserBasicInfo
-          v-if="authStore.userInfo?.user"
-          :name="authStore.userInfo.user.user_name"
-          :visits="authStore.userInfo.user.visits || 0"
-          :created-at="authStore.userInfo.user.created_at"
-          :last-seen="authStore.userInfo.user.last_seen"
+    <section class="section-block">
+      <UserBasicInfo
+        v-if="authStore.userInfo?.user"
+        :name="authStore.userInfo.user.user_name"
+        :visits="authStore.userInfo.user.visits || 0"
+        :created-at="authStore.userInfo.user.created_at"
+        :last-seen="authStore.userInfo.user.last_seen"
+        :loading="authStore.isLoading"
+        update-endpoint="/auth/api/user/display-name"
+        @saved="authStore.loadUserInfo()"
+        @edit-name="openNameDialog"
+      >
+        <div class="remote-auth-inline">
+          <label v-if="!showDeviceInfo" class="remote-auth-label">Code words from remote device:</label>
+          <RemoteAuth
+            ref="pairingEntry"
+            title=""
+            description=""
+            placeholder="word word word"
+            @completed="handlePairingCompleted"
+            @error="handlePairingError"
+            @device-info-visible="showDeviceInfo = $event"
+          />
+        </div>
+      </UserBasicInfo>
+    </section>
+
+    <section class="section-block">
+      <div class="section-header">
+        <h2>Your Passkeys</h2>
+        <p class="section-description">Keep at least one trusted passkey so you can always sign in.</p>
+      </div>
+      <div class="section-body">
+        <CredentialList
+          :credentials="authStore.userInfo?.credentials || []"
+          :aaguid-info="authStore.userInfo?.aaguid_info || {}"
           :loading="authStore.isLoading"
-          update-endpoint="/auth/api/user/display-name"
-          @saved="authStore.loadUserInfo()"
-          @edit-name="openNameDialog"
+          :hovered-credential-uuid="hoveredCredentialUuid"
+          :hovered-session-credential-uuid="hoveredSession?.credential_uuid"
+          allow-delete
+          @delete="handleDelete"
+          @credential-hover="hoveredCredentialUuid = $event"
         />
-      </section>
-
-      <section class="section-block">
-        <div class="section-header">
-          <h2>Your Passkeys</h2>
-          <p class="section-description">Keep at least one trusted passkey so you can always sign in.</p>
+        <div class="button-row">
+          <button @click="addNewCredential" class="btn-primary">Add New Passkey</button>
+          <button @click="showRegLink = true" class="btn-secondary">Add Another Device</button>
         </div>
-        <div class="section-body">
-          <CredentialList
-            :credentials="authStore.userInfo?.credentials || []"
-            :aaguid-info="authStore.userInfo?.aaguid_info || {}"
-            :loading="authStore.isLoading"
-            allow-delete
-            @delete="handleDelete"
-          />
-          <div class="button-row">
-            <button @click="addNewCredential" class="btn-primary">Add New Passkey</button>
-            <button @click="showRegLink = true" class="btn-secondary">Add Another Device</button>
-          </div>
-        </div>
-      </section>
+      </div>
+    </section>
 
-      <SessionList
-        :sessions="sessions"
-        :terminating-sessions="terminatingSessions"
-        @terminate="terminateSession"
-        section-description="Review where you're signed in and end any sessions you no longer recognize."
-      />
+    <SessionList
+      :sessions="sessions"
+      :terminating-sessions="terminatingSessions"
+      :hovered-credential-uuid="hoveredCredentialUuid"
+      @terminate="terminateSession"
+      @session-hover="hoveredSession = $event"
+      section-description="Review where you're signed in and end any sessions you no longer recognize."
+    />
 
-      <Modal v-if="showNameDialog" @close="showNameDialog = false">
-        <h3>Edit Display Name</h3>
-        <form @submit.prevent="saveName" class="modal-form">
-          <NameEditForm
-            label="Display Name"
-            v-model="newName"
-            :busy="saving"
-            @cancel="showNameDialog = false"
-          />
-        </form>
-      </Modal>
+    <Modal v-if="showNameDialog" @close="showNameDialog = false">
+      <h3>Edit Display Name</h3>
+      <form @submit.prevent="saveName" class="modal-form">
+        <NameEditForm
+          label="Display Name"
+          v-model="newName"
+          :busy="saving"
+          @cancel="showNameDialog = false"
+        />
+      </form>
+    </Modal>
 
-      <section class="section-block">
-        <div class="button-row logout-row" :class="{ single: !hasMultipleSessions }">
-          <button
-            type="button"
-            class="btn-secondary"
-            @click="history.back()"
-          >
-            Back
-          </button>
-          <button v-if="!hasMultipleSessions" @click="logoutEverywhere" class="btn-danger logout-button" :disabled="authStore.isLoading">Logout</button>
-          <template v-else>
-            <button @click="logout" class="btn-danger logout-button" :disabled="authStore.isLoading">Logout</button>
-            <button @click="logoutEverywhere" class="btn-danger logout-button" :disabled="authStore.isLoading">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>
-      </section>
-      <RegistrationLinkModal
-        v-if="showRegLink"
-                :endpoint="'/auth/api/user/create-link'"
-        :auto-copy="false"
-        :prefix-copy-with-user-name="false"
-        @close="showRegLink = false"
-        @copied="showRegLink = false; authStore.showMessage('Link copied to clipboard!', 'success', 2500)"
-      />
-    </div>
+    <section class="section-block">
+      <div class="button-row logout-row" :class="{ single: !hasMultipleSessions }">
+        <button
+          type="button"
+          class="btn-secondary"
+          @click="goBack"
+        >
+          Back
+        </button>
+        <button v-if="!hasMultipleSessions" @click="logoutEverywhere" class="btn-danger logout-button" :disabled="authStore.isLoading">Logout</button>
+        <template v-else>
+          <button @click="logout" class="btn-danger logout-button" :disabled="authStore.isLoading">Logout</button>
+          <button @click="logoutEverywhere" class="btn-danger logout-button" :disabled="authStore.isLoading">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>
+    </section>
+    <RegistrationLinkModal
+      v-if="showRegLink"
+      endpoint="/auth/api/user/create-link"
+      @close="showRegLink = false"
+    />
   </section>
 </template>
 
@@ -99,9 +112,12 @@ import Modal from '@/components/Modal.vue'
 import NameEditForm from '@/components/NameEditForm.vue'
 import SessionList from '@/components/SessionList.vue'
 import RegistrationLinkModal from '@/components/RegistrationLinkModal.vue'
+import RemoteAuth from '@/components/RemoteAuthPermit.vue'
 import { useAuthStore } from '@/stores/auth'
 import { adminUiPath, makeUiHref } from '@/utils/settings'
 import passkey from '@/utils/passkey'
+import { goBack } from '@/utils/helpers'
+import { apiJson } from '@/utils/api'
 
 const authStore = useAuthStore()
 const updateInterval = ref(null)
@@ -109,6 +125,10 @@ const showNameDialog = ref(false)
 const showRegLink = ref(false)
 const newName = ref('')
 const saving = ref(false)
+const hoveredCredentialUuid = ref(null)
+const hoveredSession = ref(null)
+const showDeviceInfo = ref(false)
+const pairingEntry = ref(null)
 
 watch(showNameDialog, (newVal) => { if (newVal) newName.value = authStore.userInfo?.user?.user_name || '' })
 
@@ -120,15 +140,28 @@ onUnmounted(() => { if (updateInterval.value) clearInterval(updateInterval.value
 
 const addNewCredential = async () => {
   try {
-    authStore.isLoading = true
-    authStore.showMessage('Adding new passkey...', 'info')
-    await passkey.register()
+    await passkey.register(null, null, () => {
+      authStore.showMessage('Adding new passkey...', 'info')
+    })
     await authStore.loadUserInfo()
     authStore.showMessage('New passkey added successfully!', 'success', 3000)
   } catch (error) {
     console.error('Failed to add new passkey:', error)
     authStore.showMessage(error.message, 'error')
-  } finally { authStore.isLoading = false }
+  }
+}
+
+const handlePairingCompleted = () => {
+  authStore.showMessage('The other device is now signed in!', 'success', 4000)
+  // Reset the form after a delay
+  setTimeout(() => pairingEntry.value?.reset(), 3000)
+}
+
+const handlePairingError = (message) => {
+  // Error is already shown in the component, optionally show global message for severe errors
+  if (!message.includes('cancelled')) {
+    authStore.showMessage(message, 'error', 4000)
+  }
 }
 
 const handleDelete = async (credential) => {
@@ -174,9 +207,7 @@ const saveName = async () => {
   if (!name) { authStore.showMessage('Name cannot be empty', 'error'); return }
   try {
     saving.value = true
-    const res = await fetch('/auth/api/user/display-name', { method: 'PUT', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ display_name: name }) })
-    const data = await res.json()
-    if (!res.ok || data.detail) throw new Error(data.detail || 'Update failed')
+    await apiJson('/auth/api/user/display-name', { method: 'PUT', body: { display_name: name } })
     showNameDialog.value = false
     await authStore.loadUserInfo()
     authStore.showMessage('Name updated successfully!', 'success', 3000)
@@ -194,6 +225,7 @@ const saveName = async () => {
 .logout-row { gap: 1rem; }
 .logout-row.single { justify-content: flex-start; }
 .logout-note { margin: 0.75rem 0 0; color: var(--color-text-muted); font-size: 0.875rem; }
+.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; }
 @media (max-width: 720px) { .logout-button { width: 100%; } }
 </style>
-

frontend/src/components/QRCodeDisplay.vue

@@ -0,0 +1,161 @@
+<template>
+  <div class="qr-display">
+    <div class="qr-section">
+      <a :href="url" @click.prevent="copyLink" class="qr-link" title="Click to copy link">
+        <canvas ref="qrCanvas" class="qr-code"></canvas>
+        <div v-if="showLink && url" class="link-text">{{ displayUrl }}</div>
+      </a>
+    </div>
+
+    <div v-if="showCopyToast" class="copy-toast">
+      ✓ Link copied to clipboard
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, watch, nextTick, computed } from 'vue'
+import QRCode from 'qrcode/lib/browser'
+
+const props = defineProps({
+  url: { type: String, required: true },
+  showLink: { type: Boolean, default: false }
+})
+
+const emit = defineEmits(['copied'])
+
+const qrCanvas = ref(null)
+const showCopyToast = ref(false)
+
+let copyToastTimer = null
+
+const displayUrl = computed(() => {
+  if (!props.url) return ''
+  return props.url.replace(/^https?:\/\//, '')
+})
+
+function drawQR() {
+  if (!props.url || !qrCanvas.value) {
+    return
+  }
+
+  try {
+    // Clear the canvas first
+    const ctx = qrCanvas.value.getContext('2d')
+    ctx.clearRect(0, 0, qrCanvas.value.width, qrCanvas.value.height)
+
+    // Generate QR code synchronously
+    QRCode.toCanvas(qrCanvas.value, props.url, {
+      scale: 6,
+      margin: 0,
+      color: {
+        dark: '#000000',
+        light: '#FFFFFF'
+      }
+    })
+
+    // Remove any inline styles added by QRCode library immediately
+    qrCanvas.value.removeAttribute('style')
+  } catch (err) {
+    console.error('QR code generation failed:', err)
+  }
+}
+
+async function copyLink() {
+  if (!props.url) return
+  try {
+    await navigator.clipboard.writeText(props.url)
+    showCopyToast.value = true
+    emit('copied')
+
+    if (copyToastTimer) clearTimeout(copyToastTimer)
+    copyToastTimer = setTimeout(() => {
+      showCopyToast.value = false
+    }, 2000)
+  } catch (err) {
+    console.error('Failed to copy link:', err)
+  }
+}
+
+// Watch for URL changes
+watch(() => props.url, () => {
+  drawQR()
+}, { immediate: true })
+
+// Watch for canvas ref becoming available
+watch(qrCanvas, () => {
+  if (qrCanvas.value && props.url) {
+    drawQR()
+  }
+}, { immediate: true })
+</script>
+
+<style scoped>
+.qr-display {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.qr-section {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.qr-link {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-decoration: none;
+  color: inherit;
+  border-radius: var(--radius-sm, 6px);
+  overflow: hidden;
+}
+
+.qr-code {
+  display: block;
+  width: 200px;
+  height: 200px;
+  max-width: 100%;
+  object-fit: contain;
+  border-radius: var(--radius-sm, 6px);
+  background: #ffffff;
+  cursor: pointer;
+}
+
+.link-text {
+  padding: 0.5rem;
+  font-size: 0.75rem;
+  color: var(--color-text-muted);
+  font-family: monospace;
+  word-break: break-all;
+  line-height: 1.2;
+  transition: color 0.2s ease;
+}
+
+.qr-link:hover .link-text {
+  color: var(--color-text);
+}
+
+.copy-toast {
+  position: absolute;
+  top: -2rem;
+  left: 50%;
+  transform: translateX(-50%);
+  background: var(--color-success);
+  color: white;
+  padding: 0.5rem 1rem;
+  border-radius: var(--radius-sm);
+  font-size: 0.875rem;
+  z-index: 10;
+  animation: fadeInOut 2s ease-in-out;
+}
+
+@keyframes fadeInOut {
+  0%, 100% { opacity: 0; }
+  10%, 90% { opacity: 1; }
+}
+</style>

frontend/src/components/RegistrationLinkModal.vue

@@ -1,148 +1,109 @@
 <template>
-  <div v-if="!inline" class="dialog-overlay" @keydown.esc.prevent="$emit('close')">
+  <div class="dialog-overlay" @keydown.esc.prevent="$emit('close')">
     <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>Device Registration Link</span>
+          📱 <span v-if="userName">Registration for {{ userName }}</span><span v-else>Add Another Device</span>
         </h2>
         <button class="icon-btn" @click="$emit('close')" aria-label="Close">❌</button>
       </div>
+
       <div class="device-link-section">
-        <div class="qr-container">
-          <a v-if="url" :href="url" @click.prevent="copy" class="qr-link">
-            <canvas ref="qrCanvas" class="qr-code"></canvas>
-            <p>{{ displayUrl }}</p>
-          </a>
-          <div v-else>
-            <em>Generating link...</em>
-          </div>
-          <p class="reg-help">
-            <span v-if="userName">The user should open this link on the device where they want to register.</span>
-            <span v-else>Open or scan this link on the device you wish to register to your account.</span>
-            <br><small>{{ expirationMessage }}</small>
-          </p>
+        <!-- Loading state -->
+        <div v-if="loading" class="loading-state">
+          <div class="spinner-small"></div>
+          <span>Generating registration link...</span>
         </div>
+
+        <!-- Error state -->
+        <div v-else-if="error" class="error-state">
+          <p class="error-message">{{ error }}</p>
+          <button class="btn-secondary" @click="generateLink">Retry</button>
+        </div>
+
+        <!-- Success state with QR code and link -->
+        <template v-else-if="linkUrl">
+          <p class="reg-help">
+            Scan this QR code on the new device, or copy the link and open it there.
+          </p>
+
+          <QRCodeDisplay
+            :url="linkUrl"
+            :show-link="true"
+            @copied="onCopied"
+          />
+
+          <p class="expiry-note" v-if="expiresAt">
+            This link expires {{ formatDate(expiresAt).toLowerCase() }}.
+          </p>
+        </template>
       </div>
+
       <div class="reg-actions">
         <button class="btn-secondary" @click="$emit('close')">Close</button>
-        <button class="btn-primary" :disabled="!url" @click="copy">Copy Link</button>
-      </div>
-    </div>
-  </div>
-  <div v-else class="registration-inline-wrapper">
-    <div class="registration-inline-block section-block">
-      <div class="section-header">
-        <h2 class="inline-heading">📱 <span v-if="userName">Registration for {{ userName }}</span><span v-else>Device Registration Link</span></h2>
-      </div>
-      <div class="section-body">
-        <div class="device-link-section">
-          <div class="qr-container">
-            <a v-if="url" :href="url" @click.prevent="copy" class="qr-link">
-              <canvas ref="qrCanvas" class="qr-code"></canvas>
-              <p>{{ displayUrl }}</p>
-            </a>
-            <div v-else>
-              <em>Generating link...</em>
-            </div>
-            <p class="reg-help">
-              <span v-if="userName">The user should open this link on the device where they want to register.</span>
-              <span v-else>Open this link on the device you wish to connect with.</span>
-              <br><small>{{ expirationMessage }}</small>
-            </p>
-          </div>
-        </div>
-        <div class="button-row" style="margin-top:1rem;">
-          <button class="btn-primary" :disabled="!url" @click="copy">Copy Link</button>
-          <button v-if="showCloseInInline" class="btn-secondary" @click="$emit('close')">Close</button>
-        </div>
       </div>
     </div>
   </div>
 </template>
 
 <script setup>
-import { ref, onMounted, watch, computed, nextTick } from 'vue'
-import QRCode from 'qrcode/lib/browser'
+import { ref, onMounted } from 'vue'
+import QRCodeDisplay from '@/components/QRCodeDisplay.vue'
+import { apiJson } from '@/utils/api'
 import { formatDate } from '@/utils/helpers'
 
 const props = defineProps({
   endpoint: { type: String, required: true },
-  autoCopy: { type: Boolean, default: true },
-  userName: { type: String, default: null },
-  inline: { type: Boolean, default: false },
-  showCloseInInline: { type: Boolean, default: false },
-  prefixCopyWithUserName: { type: Boolean, default: false }
+  userName: { type: String, default: '' }
 })
 
-const emit = defineEmits(['close','generated','copied'])
+const emit = defineEmits(['close', 'copied'])
 
-const url = ref(null)
-const expires = ref(null)
-const qrCanvas = ref(null)
+const loading = ref(true)
+const error = ref(null)
+const linkUrl = ref(null)
+const expiresAt = ref(null)
 
-const displayUrl = computed(() => url.value ? url.value.replace(/^[^:]+:\/\//,'') : '')
+async function generateLink() {
+  loading.value = true
+  error.value = null
+  linkUrl.value = null
+  expiresAt.value = null
 
-const expirationMessage = computed(() => {
-  const timeStr = formatDate(expires.value)
-  return `⚠️ Expires ${timeStr.startsWith('In ') ? timeStr.substring(3) : timeStr} and can only be used once.`
+  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
+    } else {
+      error.value = data.detail || 'Failed to generate link'
+    }
+  } catch (err) {
+    error.value = err.message || 'Failed to generate link'
+  } finally {
+    loading.value = false
+  }
+}
+
+function onCopied() {
+  emit('copied')
+}
+
+onMounted(() => {
+  generateLink()
 })
-
-async function fetchLink() {
-  try {
-    const res = await fetch(props.endpoint, { method: 'POST' })
-    const data = await res.json()
-    if (data.detail) throw new Error(data.detail)
-    url.value = data.url
-    expires.value = data.expires
-    emit('generated', { url: data.url, expires: data.expires })
-    await nextTick()
-    drawQR()
-    if (props.autoCopy) copy()
-  } catch (e) {
-    url.value = null
-    expires.value = null
-    console.error('Failed to create link', e)
-  }
-}
-
-async function drawQR() {
-  if (!url.value) return
-  await nextTick()
-  if (!qrCanvas.value) return
-  QRCode.toCanvas(qrCanvas.value, url.value, { scale: 8 }, err => { if (err) console.error(err) })
-}
-
-async function copy() {
-  if (!url.value) return
-  let text = url.value
-  if (props.prefixCopyWithUserName && props.userName) {
-    text = `${props.userName} ${text}`
-  }
-  try {
-    await navigator.clipboard.writeText(text)
-    emit('copied', text)
-    if (!props.inline) emit('close')
-  } catch (_) {
-    /* ignore */
-  }
-}
-
-onMounted(fetchLink)
-watch(url, () => drawQR(), { flush: 'post' })
-
 </script>
+
 <style scoped>
-.icon-btn { background:none; border:none; cursor:pointer; font-size:1rem; opacity:.6; }
-.icon-btn:hover { opacity:1; }
-/* Minimal extra styling; main look comes from global styles */
-.qr-link { text-decoration:none; color:inherit; }
-.reg-header-row { display:flex; justify-content:space-between; align-items:center; gap:.75rem; margin-bottom:.75rem; }
-.reg-title { margin:0; font-size:1.25rem; font-weight:600; }
-.device-dialog { background: var(--color-surface); padding: 1.25rem 1.25rem 1rem; border-radius: var(--radius-md); max-width:480px; width:100%; box-shadow:0 6px 28px rgba(0,0,0,.25); }
-.qr-container { display:flex; flex-direction:column; align-items:center; gap:.5rem; }
-.qr-code { display:block; }
-.reg-help { margin-top:.5rem; margin-bottom:.75rem; font-size:.85rem; line-height:1.25rem; text-align:center; }
-.reg-actions { display:flex; justify-content:flex-end; gap:.5rem; margin-top:.25rem; }
-.registration-inline-block .qr-container { align-items:flex-start; }
-.registration-inline-block .reg-help { text-align:left; }
+.icon-btn { background: none; border: none; cursor: pointer; font-size: 1rem; opacity: .6; }
+.icon-btn:hover { opacity: 1; }
+.reg-header-row { display: flex; justify-content: space-between; align-items: center; gap: .75rem; margin-bottom: .75rem; }
+.reg-title { margin: 0; font-size: 1.25rem; font-weight: 600; }
+.device-dialog { background: var(--color-surface); padding: 1.25rem 1.25rem 1rem; border-radius: var(--radius-md); max-width: 480px; width: 100%; box-shadow: 0 6px 28px rgba(0,0,0,.25); }
+.reg-help { margin: .5rem 0 .75rem; font-size: .85rem; line-height: 1.4; text-align: center; color: var(--color-text-muted); }
+.reg-actions { display: flex; justify-content: flex-end; gap: .5rem; margin-top: 1rem; }
+.loading-state { display: flex; align-items: center; justify-content: center; gap: .5rem; padding: 2rem 0; color: var(--color-text-muted); }
+.error-state { text-align: center; padding: 1rem 0; }
+.error-message { color: var(--color-danger-text); margin-bottom: 1rem; }
+.expiry-note { font-size: .75rem; color: var(--color-text-muted); text-align: center; margin-top: .75rem; }
 </style>

frontend/src/components/RemoteAuthPermit.vue

@@ -0,0 +1,894 @@
+<template>
+  <div class="pairing-entry">
+    <form @submit.prevent="submitCode" class="pairing-form">
+      <!-- Code input (shown when device info not yet received) -->
+      <div v-if="!deviceInfo" class="input-row">
+        <div class="input-wrapper" :class="{ 'has-error': serverError, 'is-complete': deviceInfo && !serverError, 'focused': isFocused }">
+          <!-- Visual slot-machine display overlay -->
+          <div class="slot-machine" :class="{ 'has-error': serverError, 'is-complete': deviceInfo && !serverError }" aria-hidden="true">
+            <div v-for="(word, index) in displayWords" :key="index" class="slot-reel" :class="{ 'invalid-word': word.invalid, 'empty': !word.text && !word.typedPrefix }">
+              <div class="slot-word">
+                <template v-if="word.typedPrefix">
+                  <span class="typed-prefix">{{ word.typedPrefix }}</span><span class="hint-suffix">{{ word.hintSuffix }}</span>
+                  <span v-if="word.hasCursor" class="cursor-overlay" :style="{ '--cursor-pos': word.cursorCharIndex, '--word-len': word.wordLen }"></span>
+                </template>
+                <template v-else-if="word.text">
+                  {{ word.text }}
+                  <span v-if="word.hasCursor" class="cursor-overlay" :style="{ '--cursor-pos': word.cursorCharIndex, '--word-len': word.wordLen }"></span>
+                </template>
+                <template v-else>
+                  <span v-if="word.hasCursor" class="cursor-overlay" :style="{ '--cursor-pos': 0, '--word-len': 0 }"></span>
+                </template>
+              </div>
+            </div>
+          </div>
+          <!-- Hidden input for actual text entry -->
+          <input
+            ref="inputRef"
+            v-model="code"
+            type="text"
+            :placeholder="placeholder"
+            autocomplete="off"
+            autocapitalize="none"
+            autocorrect="off"
+            spellcheck="false"
+            class="pairing-input hidden-input"
+            @input="handleInput"
+            @keydown="deferUpdateCursor"
+            @mouseup="updateCursorPos"
+            @focus="isFocused = true"
+            @blur="isFocused = false"
+          />
+        </div>
+        <!-- Processing status beside input -->
+        <div v-if="processingStatus" class="processing-status">
+          <span class="processing-icon">{{ processingStatus === 'pow' ? '🔐' : '📡' }}</span>
+          <span class="processing-spinner-small"></span>
+        </div>
+      </div>
+
+      <!-- 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 v-if="error" class="error-message" style="margin-top: 0.5rem;">{{ error }}</p>
+
+        <div class="button-row" style="margin-top: 0.75rem; display: flex; gap: 0.5rem;">
+          <button
+            type="button"
+            class="btn-secondary"
+            :disabled="loading"
+            @click="deny"
+            style="flex: 1;"
+          >
+            Deny
+          </button>
+          <button
+            ref="submitBtnRef"
+            type="submit"
+            :disabled="loading"
+            class="btn-primary"
+            style="flex: 1;"
+          >
+            {{ loading ? 'Authenticating…' : 'Authorize' }}
+          </button>
+        </div>
+      </div>
+
+      <p v-if="error && !deviceInfo" class="error-message">{{ error }}</p>
+    </form>
+  </div>
+</template>
+
+<script setup>
+import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue'
+import { startAuthentication } from '@simplewebauthn/browser'
+import aWebSocket from '@/utils/awaitable-websocket'
+import { dec as b64dec, enc as b64enc } from '@/utils/base64url'
+import { getSettings } from '@/utils/settings'
+import { getUniqueMatch, isValidWord, isValidPrefix } from '@/utils/wordlist'
+import { solvePoW } from '@/utils/pow'
+import { useAuthStore } from '@/stores/auth'
+
+const props = defineProps({
+  title: { type: String, default: 'Help Another Device Sign In' },
+  description: { type: String, default: 'Enter the code shown on the device that needs to sign in.' },
+  placeholder: { type: String, default: 'Enter three words' },
+  action: { type: String, default: 'login' } // 'login' or 'register'
+})
+
+const emit = defineEmits(['completed', 'error', 'cancelled', 'back', 'register', 'deviceInfoVisible'])
+
+// State
+const loading = ref(false)
+const error = ref(null)
+const settings = ref(null)
+let ws = null
+let authStore = null
+
+// Try to get authStore (might fail if Pinia not installed in this app instance)
+try { authStore = useAuthStore() } catch (e) { /* ignore */ }
+
+const inputRef = ref(null)
+const submitBtnRef = ref(null)
+const code = ref('')
+const isProcessing = ref(false)
+const processingStatus = ref('')
+const deviceInfo = ref(null)
+const autocompleteHint = ref('')
+
+// Watch deviceInfo and emit visibility change
+watch(deviceInfo, (newVal) => {
+  emit('deviceInfoVisible', !!newVal)
+})
+
+const hasInvalidWord = ref(false)
+const serverError = ref(false)
+const cursorPos = ref(0)
+const isFocused = ref(false)
+let wsConnecting = false
+let currentChallenge = null
+let currentWork = null
+let powPromise = null
+let powSolution = null
+let lookupTimeout = null
+let lastLookedUpCode = null
+
+// --- Helpers ---
+
+function showMessage(message, type = 'info', duration = 3000) {
+  if (authStore) {
+    authStore.showMessage(message, type, duration)
+  }
+}
+
+async function fetchSettings() {
+  try {
+    const data = await getSettings()
+    settings.value = data
+  } catch (err) {
+    console.warn('Unable to load settings', err)
+  }
+}
+
+// --- Input Mode Logic ---
+
+function getWordAtCursor(input, cursor) {
+  if (!input || cursor < 0) return { word: '', start: 0, end: 0 }
+  let start = cursor, end = cursor
+  while (start > 0 && /[a-zA-Z]/.test(input[start - 1])) start--
+  while (end < input.length && /[a-zA-Z]/.test(input[end])) end++
+  return { word: input.slice(start, end), start, end }
+}
+
+function getWords(input) {
+  return input.trim().split(/[.\s]+/).filter(w => w.length > 0)
+}
+
+function countCompleteWords(input) {
+  const endsWithSeparator = /[.\s]$/.test(input)
+  const words = getWords(input)
+  return endsWithSeparator ? words.length : Math.max(0, words.length - 1)
+}
+
+function analyzeWords(input) {
+  if (!input) return { valid: true, segments: [] }
+  const segments = []
+  const endsWithSeparator = /[.\s]$/.test(input)
+  let match, regex = /([a-zA-Z]+)|([.\s]+)/g
+  while ((match = regex.exec(input)) !== null) {
+    if (match[1]) segments.push({ text: match[1], isWord: true, start: match.index })
+    else if (match[2]) segments.push({ text: match[2], isWord: false, start: match.index })
+  }
+  const words = segments.filter(s => s.isWord)
+  let allValid = true
+  words.forEach((wordSeg, idx) => {
+    const isLastWord = idx === words.length - 1
+    const word = wordSeg.text.toLowerCase()
+    if (isLastWord && !endsWithSeparator) wordSeg.invalid = !isValidPrefix(word)
+    else wordSeg.invalid = !isValidWord(word)
+    if (wordSeg.invalid) allValid = false
+  })
+  return { valid: allValid, segments }
+}
+
+const coloredSegments = computed(() => {
+  const { segments } = analyzeWords(code.value)
+  return segments.map(s => ({ text: s.text, invalid: s.invalid || false }))
+})
+
+function checkWordsValidity(input) { return analyzeWords(input).valid }
+function allWordsValid(input) { return getWords(input).length > 0 && getWords(input).every(w => isValidWord(w)) }
+
+// Get the current partial word being typed (not yet a complete word)
+function getCurrentPartialWord(input) {
+  const endsWithSeparator = /[.\s]$/.test(input)
+  if (endsWithSeparator) return ''
+  const match = input.match(/[a-zA-Z]+$/)
+  return match ? match[0].toLowerCase() : ''
+}
+
+// Calculate cursor position in the normalized display (wordIndex, charIndex within word)
+// Returns { wordIndex: number, charIndex: number } where charIndex is position within the word text
+function calcDisplayCursor(input, rawCursorPos) {
+  if (!input || rawCursorPos === 0) {
+    return { wordIndex: 0, charIndex: 0 }
+  }
+
+  // Parse input to find word boundaries
+  const beforeCursor = input.slice(0, rawCursorPos)
+  const wordMatches = [...beforeCursor.matchAll(/[a-zA-Z]+/g)]
+
+  // Check if cursor is in whitespace after words
+  const endsWithSeparator = /[.\s]$/.test(beforeCursor)
+
+  if (wordMatches.length === 0) {
+    // No words before cursor, cursor is at start of first word
+    return { wordIndex: 0, charIndex: 0 }
+  }
+
+  const lastMatch = wordMatches[wordMatches.length - 1]
+  const lastMatchEnd = lastMatch.index + lastMatch[0].length
+
+  if (endsWithSeparator || rawCursorPos > lastMatchEnd) {
+    // Cursor is after the last word (in whitespace), so it's at start of next word
+    return { wordIndex: Math.min(wordMatches.length, 2), charIndex: 0 }
+  }
+
+  // Cursor is within the last word
+  const charIndex = rawCursorPos - lastMatch.index
+  return { wordIndex: wordMatches.length - 1, charIndex: charIndex }
+}
+
+// Compute display words for slot-machine overlay (always 3 slots)
+const displayWords = computed(() => {
+  const words = getWords(code.value)
+  const result = []
+
+  // Get analysis for validation
+  const { segments } = analyzeWords(code.value)
+  const wordSegments = segments.filter(s => s.isWord)
+
+  // Get current partial word and autocomplete hint
+  const partialWord = getCurrentPartialWord(code.value)
+  const hint = autocompleteHint.value
+  const endsWithSeparator = /[.\s]$/.test(code.value)
+
+  // Calculate where cursor should be displayed
+  const cursor = calcDisplayCursor(code.value, cursorPos.value)
+
+  // Always show exactly 3 slots
+  for (let i = 0; i < 3; i++) {
+    const isCursorSlot = cursor.wordIndex === i
+
+    if (i < words.length) {
+      const word = words[i].toLowerCase()
+      const isInvalid = wordSegments[i]?.invalid || false
+      const isLastWord = i === words.length - 1
+
+      if (isLastWord && !endsWithSeparator && hint && partialWord) {
+        // Show typed prefix + hint suffix in the same slot
+        // Total visible length is the full hint word
+        const totalLen = hint.length
+        result.push({
+          text: '',
+          typedPrefix: partialWord,
+          hintSuffix: hint.slice(partialWord.length),
+          invalid: isInvalid,
+          hasCursor: isCursorSlot,
+          cursorCharIndex: isCursorSlot ? cursor.charIndex : -1,
+          wordLen: totalLen
+        })
+      } else {
+        // Complete word - show cursor at appropriate position
+        result.push({
+          text: word,
+          invalid: isInvalid,
+          hasCursor: isCursorSlot,
+          cursorCharIndex: isCursorSlot ? cursor.charIndex : -1,
+          wordLen: word.length
+        })
+      }
+    } else {
+      // Empty slot
+      result.push({
+        text: '',
+        invalid: false,
+        hasCursor: isCursorSlot,
+        cursorCharIndex: 0,
+        wordLen: 0
+      })
+    }
+  }
+
+  return result
+})
+
+const hasThreeValidWords = computed(() => {
+  const words = getWords(code.value)
+  return words.length === 3 && words.every(w => isValidWord(w))
+})
+
+function normalizeCode(input) {
+  return input.trim().toLowerCase().split(/[.\s]+/).filter(w => w).join('.')
+}
+
+function startPowSolving() {
+  if (!currentChallenge || powPromise) return
+  const challenge = b64dec(currentChallenge)
+  powPromise = solvePoW(challenge, currentWork).then(solution => {
+    powSolution = solution
+    powPromise = null
+  })
+}
+
+async function getPowSolution() {
+  if (powSolution) { const s = powSolution; powSolution = null; return s }
+  if (powPromise) { await powPromise; const s = powSolution; powSolution = null; return s }
+  if (!currentChallenge) throw new Error('No PoW challenge available')
+  const challenge = b64dec(currentChallenge)
+  return await solvePoW(challenge, currentWork)
+}
+
+function updateChallenge(pow) {
+  if (pow?.challenge) {
+    currentChallenge = pow.challenge
+    currentWork = pow.work
+    powSolution = null
+    powPromise = null
+    startPowSolving()
+  }
+}
+
+async function ensureConnection() {
+  if (ws || wsConnecting) return
+  wsConnecting = true
+  try {
+    const authHost = settings.value?.auth_host
+    const wsPath = '/auth/ws/remote-auth/pair'
+    const wsUrl = authHost && location.host !== authHost ? `//${authHost}${wsPath}` : wsPath
+    ws = await aWebSocket(wsUrl)
+    const msg = await ws.receive_json()
+    if (msg.status && msg.detail) throw new Error(msg.detail)
+    if (!msg.pow?.challenge) throw new Error('Server did not send PoW challenge')
+    updateChallenge(msg.pow)
+  } catch (err) {
+    console.error('WebSocket connection error:', err)
+    ws = null
+    throw err
+  } finally {
+    wsConnecting = false
+  }
+}
+
+// Defer cursor position update to after browser processes the key
+function deferUpdateCursor(event) {
+  // Handle Tab/Space for autocomplete immediately
+  if (event.key === 'Tab' || event.key === ' ') {
+    handleKeydown(event)
+    return
+  }
+  // Defer cursor update to next tick
+  setTimeout(updateCursorPos, 0)
+}
+
+// Update cursor position from input
+function updateCursorPos() {
+  cursorPos.value = inputRef.value?.selectionStart ?? code.value.length
+}
+
+function updateAutocomplete() {
+  cursorPos.value = inputRef.value?.selectionStart ?? code.value.length
+  const { word, end } = getWordAtCursor(code.value, cursorPos.value)
+  const completeWordCount = countCompleteWords(code.value)
+  if (completeWordCount >= 3 || !word || word.length < 1 || cursorPos.value !== end) {
+    autocompleteHint.value = ''
+    return
+  }
+  const match = getUniqueMatch(word.toLowerCase())
+  if (match && match !== word.toLowerCase()) autocompleteHint.value = match
+  else autocompleteHint.value = ''
+}
+
+function applyAutocomplete() {
+  if (!autocompleteHint.value) return false
+  const { word, start, end } = getWordAtCursor(code.value, cursorPos.value)
+  if (!word) return false
+  const before = code.value.slice(0, start)
+  const wordsBefore = getWords(before).length
+  const isThirdWord = wordsBefore === 2
+  const suffix = isThirdWord ? '' : ' '
+  const after = code.value.slice(end)
+  code.value = before + autocompleteHint.value + suffix + after.trimStart()
+  const newPos = start + autocompleteHint.value.length + suffix.length
+  nextTick(() => {
+    inputRef.value?.setSelectionRange(newPos, newPos)
+    cursorPos.value = newPos
+  })
+  autocompleteHint.value = ''
+  return true
+}
+
+// Try to split concatenated words (e.g., "alienalien" -> "alien alien")
+function trySplitWords(input) {
+  // Only process if there's a continuous string of letters at the end
+  const match = input.match(/^(.*?)([a-zA-Z]+)$/)
+  if (!match) return input
+
+  const prefix = match[1]  // Everything before the letter sequence
+  const letters = match[2].toLowerCase()
+
+  // Try to find valid word boundaries in the letter sequence
+  const foundWords = []
+  let remaining = letters
+
+  while (remaining.length > 0) {
+    let foundWord = null
+
+    // Try to find the longest valid word from the start
+    for (let len = Math.min(remaining.length, 6); len >= 3; len--) {
+      const candidate = remaining.slice(0, len)
+      if (isValidWord(candidate)) {
+        foundWord = candidate
+        break
+      }
+    }
+
+    if (foundWord) {
+      foundWords.push(foundWord)
+      remaining = remaining.slice(foundWord.length)
+
+      // Stop after 3 words
+      if (foundWords.length >= 3) {
+        remaining = ''
+        break
+      }
+    } else {
+      // No valid word found, keep the remaining as-is
+      foundWords.push(remaining)
+      break
+    }
+  }
+
+  // Only return split version if we found at least one complete word
+  // and there's a clear boundary (more than one segment, or the segment is a complete word)
+  if (foundWords.length > 1 || (foundWords.length === 1 && isValidWord(foundWords[0]) && remaining === '')) {
+    return prefix + foundWords.join(' ')
+  }
+
+  return input
+}
+
+function handleInput() {
+  // Immediately update cursor position
+  cursorPos.value = inputRef.value?.selectionStart ?? code.value.length
+
+  // First, try to auto-split concatenated words
+  const splitCode = trySplitWords(code.value)
+  if (splitCode !== code.value) {
+    code.value = splitCode
+    nextTick(() => {
+      const newLen = splitCode.length
+      inputRef.value?.setSelectionRange(newLen, newLen)
+      cursorPos.value = newLen
+    })
+  }
+
+  const words = getWords(code.value)
+  if (words.length >= 3) {
+    const normalized = words.slice(0, 3).join(' ')
+    if (code.value !== normalized) {
+      const cursorWasAtEnd = cursorPos.value >= code.value.length
+      code.value = normalized
+      if (cursorWasAtEnd) {
+        nextTick(() => {
+          inputRef.value?.setSelectionRange(normalized.length, normalized.length)
+          cursorPos.value = normalized.length
+        })
+      }
+    }
+  }
+
+  updateAutocomplete()
+  if (lookupTimeout) { clearTimeout(lookupTimeout); lookupTimeout = null }
+  deviceInfo.value = null
+  error.value = null
+  serverError.value = false
+  hasInvalidWord.value = !checkWordsValidity(code.value)
+  const currentWords = getWords(code.value)
+  if (currentWords.length >= 1 && !ws && !wsConnecting) ensureConnection()
+  if (currentWords.length === 3) {
+    if (!allWordsValid(code.value)) return
+    lookupTimeout = setTimeout(() => { lookupDeviceInfo() }, 150)
+  }
+}
+
+async function lookupDeviceInfo() {
+  if (isProcessing.value || loading.value) return
+  if (!hasThreeValidWords.value) return
+  const normalizedCode = normalizeCode(code.value)
+  if (normalizedCode === lastLookedUpCode && deviceInfo.value) return
+
+  isProcessing.value = true
+  processingStatus.value = 'pow'
+  error.value = null
+  serverError.value = false
+
+  try {
+    await ensureConnection()
+    if (!ws) throw new Error('Failed to connect')
+    const solution = await getPowSolution()
+    const powB64 = b64enc(solution)
+    const currentCode = normalizeCode(code.value)
+    if (!hasThreeValidWords.value) return
+    processingStatus.value = 'server'
+    ws.send_json({ code: currentCode, pow: powB64 })
+    const res = await ws.receive_json()
+    updateChallenge(res.pow)
+    if (typeof res.status === 'number' && res.status >= 400) {
+      error.value = res.detail || 'Request failed'
+      serverError.value = true
+      deviceInfo.value = null
+      lastLookedUpCode = null
+      return
+    }
+    if (res.status === 'found' && res.host) {
+      code.value = currentCode.replace(/\./g, ' ')
+      deviceInfo.value = {
+        host: res.host,
+        user_agent_pretty: res.user_agent_pretty,
+        client_ip: res.client_ip,
+        action: res.action || 'login'
+      }
+      lastLookedUpCode = currentCode
+      nextTick(() => { submitBtnRef.value?.focus() })
+    } else {
+      error.value = 'Unexpected response from server'
+      serverError.value = true
+      deviceInfo.value = null
+      lastLookedUpCode = null
+    }
+  } catch (err) {
+    console.error('Lookup error:', err)
+    error.value = err.message || 'Lookup failed'
+    serverError.value = true
+    deviceInfo.value = null
+    lastLookedUpCode = null
+    if (ws) { ws.close(); ws = null }
+  } finally {
+    isProcessing.value = false
+    processingStatus.value = ''
+  }
+}
+
+function handleKeydown(event) {
+  if (event.key === 'Tab') {
+    if (autocompleteHint.value) {
+      const applied = applyAutocomplete()
+      if (applied) { event.preventDefault(); handleInput(); return }
+    }
+    if (code.value.trim()) event.preventDefault()
+    return
+  }
+  if (event.key === ' ' && autocompleteHint.value) {
+    const applied = applyAutocomplete()
+    if (applied) { event.preventDefault(); handleInput() }
+  }
+}
+
+async function submitCode() {
+  if (!deviceInfo.value || loading.value) return
+  loading.value = true
+  error.value = null
+  try {
+    if (!ws) await ensureConnection()
+    if (!ws) throw new Error('Failed to connect')
+    const solution = await getPowSolution()
+    const powB64 = b64enc(solution)
+    ws.send_json({ authenticate: true, pow: powB64 })
+    const res = await ws.receive_json()
+    if (typeof res.status === 'number' && res.status >= 400) throw new Error(res.detail || 'Authentication failed')
+    if (!res.optionsJSON) throw new Error(res.detail || 'Failed to get authentication options')
+    const authResponse = await startAuthentication(res)
+    ws.send_json(authResponse)
+    const result = await ws.receive_json()
+    if (typeof result.status === 'number' && result.status >= 400) throw new Error(result.detail || 'Authentication failed')
+    if (result.status === 'success') {
+      showMessage('Device authenticated successfully!', 'success', 3000)
+      emit('completed')
+      reset()
+    } else {
+      throw new Error(result.detail || 'Authentication failed')
+    }
+  } catch (err) {
+    console.error('Pairing error:', err)
+    const message = err.name === 'NotAllowedError'
+      ? 'Passkey authentication was cancelled'
+      : (err.message || 'Authentication failed')
+    error.value = message
+    // Don't show toast - error is shown in dialog
+    emit('error', message)
+  } finally {
+    loading.value = false
+    if (ws) { ws.close(); ws = null }
+  }
+}
+
+async function deny() {
+  // Send deny message to server before closing websocket
+  if (ws) {
+    try {
+      ws.send_json({ deny: true })
+      // Give the server a moment to process the denial
+      await new Promise(resolve => setTimeout(resolve, 100))
+    } catch (e) {
+      console.error('Error sending deny message:', e)
+    }
+    ws.close()
+    ws = null
+  }
+
+  // Reset to initial state
+  reset()
+}
+
+function reset() {
+  code.value = ''
+  error.value = null
+  serverError.value = false
+  deviceInfo.value = null
+  isProcessing.value = false
+  processingStatus.value = ''
+  autocompleteHint.value = ''
+  hasInvalidWord.value = false
+  lastLookedUpCode = null
+  if (ws) { ws.close(); ws = null }
+  currentChallenge = null
+  currentWork = null
+  powPromise = null
+  powSolution = null
+}
+
+// --- Lifecycle ---
+
+onMounted(async () => {
+  await fetchSettings()
+  inputRef.value?.focus()
+  // Initialize cursor position
+  nextTick(() => {
+    cursorPos.value = inputRef.value?.selectionStart ?? 0
+  })
+})
+
+onUnmounted(() => {
+  if (lookupTimeout) { clearTimeout(lookupTimeout); lookupTimeout = null }
+  if (ws) { ws.close(); ws = null }
+})
+
+defineExpose({ reset, deny, code, handleInput, loading, error })
+</script>
+
+<style scoped>
+/* Input Mode Styles */
+.pairing-entry {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.pairing-form {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.input-row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.input-wrapper {
+  position: relative;
+  display: flex;
+  width: 280px;
+  max-width: 100%;
+}
+
+/* Slot machine visual display (matches RemoteAuthInline) */
+.slot-machine {
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: 100%;
+  height: 100%;
+  padding: 0.875rem 1rem;
+  background: var(--color-surface-hover, rgba(0, 0, 0, 0.03));
+  border: 2px solid var(--color-border);
+  border-radius: var(--radius-sm, 6px);
+  font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;
+  display: flex;
+  gap: 0;
+  align-items: center;
+  user-select: none;
+  pointer-events: none;
+  white-space: nowrap;
+  overflow: hidden;
+  box-sizing: border-box;
+  z-index: 1;
+}
+
+.slot-machine.has-error {
+  border-color: var(--color-error, #ef4444);
+  background: var(--color-error-bg, rgba(239, 68, 68, 0.05));
+}
+
+.slot-machine.is-complete {
+  border-color: var(--color-success, #10b981);
+}
+
+.slot-reel {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: 1 1 33.333%;
+  min-width: 0;
+  height: 1.8em;
+  overflow: visible;
+  position: relative;
+  border-radius: 3px;
+}
+
+.slot-reel:not(:last-child) {
+  margin-right: 0.5rem;
+}
+
+.slot-word {
+  font-size: 1.25rem;
+  font-weight: 600;
+  letter-spacing: 0.05em;
+  text-align: center;
+  width: 100%;
+  color: var(--color-text);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+}
+
+.slot-word .typed-prefix {
+  color: var(--color-text);
+}
+
+.slot-word .hint-suffix {
+  color: var(--color-text-muted);
+  opacity: 0.6;
+}
+
+.cursor-overlay {
+  position: absolute;
+  width: 2px;
+  height: 1.2em;
+  background: var(--color-text);
+  animation: none;
+  pointer-events: none;
+  /* Position based on character index - calculate from center of slot */
+  left: calc(50% + (var(--cursor-pos) - var(--word-len, 0) / 2) * 0.65em);
+  transform: translateX(-1px);
+  opacity: 0;
+}
+
+.input-wrapper.focused .cursor-overlay {
+  opacity: 1;
+  animation: cursorBlink 1s ease-in-out infinite;
+}
+
+@keyframes cursorBlink {
+  0%, 49% {
+    opacity: 1;
+  }
+  50%, 100% {
+    opacity: 0;
+  }
+}
+
+.slot-reel.invalid-word .slot-word {
+  color: var(--color-error, #ef4444);
+}
+
+.slot-reel.invalid-word .slot-word .typed-prefix {
+  color: var(--color-error, #ef4444);
+}
+
+.slot-reel.invalid-word .cursor-overlay {
+  background: var(--color-error, #ef4444);
+}
+
+.slot-reel.empty .slot-word {
+  color: var(--color-text-muted);
+}
+
+/* Hidden input - keeps focus and handles keyboard input */
+.pairing-input {
+  flex: 1;
+  width: 100%;
+  height: 100%;
+  padding: 0.875rem 1rem;
+  font-size: 1rem;
+  font-family: inherit;
+  border: 1px solid transparent;
+  border-radius: var(--radius-sm, 6px);
+  background: transparent;
+  color: transparent;
+  caret-color: transparent;
+  outline: none;
+  box-sizing: border-box;
+  position: relative;
+  z-index: 0;
+}
+
+.pairing-input.hidden-input {
+  color: transparent;
+  caret-color: transparent;
+}
+
+.pairing-input:disabled {
+  cursor: not-allowed;
+}
+
+.pairing-input::placeholder {
+  color: transparent;
+}
+
+.processing-status {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  font-size: 0.875rem;
+  color: var(--color-text-muted);
+}
+
+.processing-icon {
+  font-size: 0.875rem;
+}
+
+.processing-spinner-small {
+  width: 12px;
+  height: 12px;
+  border: 2px solid var(--color-border);
+  border-top-color: var(--color-primary);
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+.device-info {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.device-permit-text {
+  margin: 0;
+  font-size: 0.95rem;
+  color: var(--color-text);
+}
+
+.device-meta {
+  margin: 0;
+  font-size: 0.8rem;
+  color: var(--color-text-muted);
+  font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;
+}
+
+.error-message {
+  margin: 0;
+  font-size: 0.875rem;
+  color: var(--color-error, #ef4444);
+  margin-bottom: 1rem;
+}
+</style>

frontend/src/components/RemoteAuthRequest.vue

@@ -0,0 +1,535 @@
+<template>
+  <div class="remote-auth-inline">
+    <!-- Success state -->
+    <div v-if="completed" class="success-section">
+      <p class="success-message">✅ {{ successMessage }}</p>
+    </div>
+
+    <!-- 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>
+    </div>
+
+    <!-- Connecting phase -->
+    <div v-else-if="phase === 'connecting'" class="auth-display">
+      <div class="auth-content">
+        <div class="pairing-code-section">
+          <p class="pairing-label">Enter the code words:</p>
+          <div class="slot-machine" aria-hidden="true">
+            <div class="slot-reel" v-for="(word, index) in animatedWords" :key="index">
+              <div class="slot-word">{{ word }}</div>
+            </div>
+          </div>
+          <p class="site-url">{{ siteUrlDisplay }}</p>
+        </div>
+      </div>
+
+      <div class="waiting-indicator">
+        <div class="spinner-small"></div>
+        <span>Generating code…</span>
+      </div>
+    </div>
+
+    <!-- Waiting/Authenticating phase - show codes -->
+    <div v-else class="auth-display">
+      <div class="auth-content">
+        <div v-if="pairingCode" class="pairing-code-section">
+          <p class="pairing-label">Enter the code words:</p>
+          <div class="slot-machine stopped">
+            <div class="slot-reel" v-for="(word, index) in displayCode.split(' ')" :key="index">
+              <div class="slot-word">{{ word }}</div>
+            </div>
+          </div>
+          <p class="site-url">{{ siteUrlDisplay }}</p>
+        </div>
+      </div>
+
+      <div class="waiting-indicator">
+        <div class="spinner-small"></div>
+        <span>{{ waitingMessage }}</span>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed, watch, onMounted, onUnmounted } from 'vue'
+import aWebSocket from '@/utils/awaitable-websocket'
+import { dec as b64dec, enc as b64enc } from '@/utils/base64url'
+import { getSettings } from '@/utils/settings'
+import { solvePoW } from '@/utils/pow'
+import { words } from '@/utils/wordlist'
+
+const props = defineProps({
+  active: { type: Boolean, default: false }
+})
+
+const emit = defineEmits(['authenticated', 'cancelled', 'error', 'register'])
+
+const pairingCode = ref(null)
+const completed = ref(false)
+const error = ref(null)
+const phase = ref('connecting')
+const settings = ref(null)
+const animatedWords = ref(['', '', ''])
+let ws = null
+let wordAnimationTimer = null
+
+const displayCode = computed(() => pairingCode.value ? pairingCode.value.replace(/\./g, ' ') : '')
+
+const siteUrlDisplay = computed(() => {
+  if (!settings.value) return ''
+  const authSiteUrl = settings.value.auth_site_url || `${location.protocol}//${location.host}/auth/`
+  // Remove the protocol and any trailing slash
+  const withoutProtocol = authSiteUrl.replace(/^https?:\/\//, '')
+  return withoutProtocol.endsWith('/') ? withoutProtocol.slice(0, -1) : withoutProtocol
+})
+
+const waitingMessage = computed(() => {
+  return phase.value === 'authenticating'
+    ? 'Complete on another device…'
+    : 'Waiting for authentication…'
+})
+
+const successMessage = computed(() => 'Authenticated successfully!')
+
+function getRandomWord() {
+  return words[Math.floor(Math.random() * words.length)]
+}
+
+function startWordAnimation() {
+  // Initialize with random words
+  animatedWords.value = [getRandomWord(), getRandomWord(), getRandomWord()]
+
+  let updateCount = 0
+  const maxUpdates = 20 // Number of cycles before stopping
+
+  // Different intervals for each slot to spin independently
+  const intervals = [
+    setInterval(() => {
+      const newWords = [...animatedWords.value]
+      newWords[0] = getRandomWord()
+      animatedWords.value = newWords
+    }, 140),
+    setInterval(() => {
+      const newWords = [...animatedWords.value]
+      newWords[1] = getRandomWord()
+      animatedWords.value = newWords
+    }, 170),
+    setInterval(() => {
+      const newWords = [...animatedWords.value]
+      newWords[2] = getRandomWord()
+      animatedWords.value = newWords
+    }, 200)
+  ]
+
+  wordAnimationTimer = intervals
+
+  // Stop all after max updates
+  setTimeout(() => {
+    intervals.forEach(interval => clearInterval(interval))
+    wordAnimationTimer = null
+  }, maxUpdates * 170) // Average interval time
+}
+
+function stopWordAnimation() {
+  if (wordAnimationTimer) {
+    if (Array.isArray(wordAnimationTimer)) {
+      wordAnimationTimer.forEach(interval => clearInterval(interval))
+    } else {
+      clearInterval(wordAnimationTimer)
+    }
+    wordAnimationTimer = null
+  }
+}
+
+async function startRemoteAuth() {
+  error.value = null
+  completed.value = false
+  pairingCode.value = null
+  phase.value = 'connecting'
+
+  // Start word animation
+  startWordAnimation()
+
+  try {
+    settings.value = await getSettings()
+    const authHost = settings.value?.auth_host
+    const wsPath = '/auth/ws/remote-auth/request'
+    const wsUrl = authHost && location.host !== authHost ? `//${authHost}${wsPath}` : wsPath
+
+    ws = await aWebSocket(wsUrl)
+
+    // PoW challenge
+    const powChallenge = await ws.receive_json()
+    if (powChallenge.pow) {
+      const challenge = b64dec(powChallenge.pow.challenge)
+      const nonces = await solvePoW(challenge, powChallenge.pow.work)
+      ws.send_json({ pow: b64enc(nonces), action: 'login' })
+    }
+
+    // Receive the pairing code
+    const res = await ws.receive_json()
+
+    if (res.status) {
+      throw new Error(res.detail || `Failed to create remote auth request: ${res.status}`)
+    }
+
+    pairingCode.value = res.pairing_code
+
+    // Stop word animation
+    stopWordAnimation()
+
+    phase.value = 'waiting'
+
+    // Wait for authentication
+    while (true) {
+      const msg = await ws.receive_json()
+
+      if (msg.status === 'locked') {
+        // Someone has entered the code and is authenticating
+        phase.value = 'authenticating'
+      } else if (msg.status === 'paired') {
+        // Legacy/compatibility: Device paired, now authenticating
+        phase.value = 'authenticating'
+      } else if (msg.status === 'authenticated') {
+        // Success
+        completed.value = true
+        emit('authenticated', { session_token: msg.session_token })
+        break
+      } else if (msg.status === 'denied') {
+        // Explicitly denied by the authenticating device
+        throw new Error('Access denied')
+      } else if (msg.status === 'completed') {
+        // Registration flow
+        if (msg.reset_token) {
+          completed.value = true
+          emit('register', msg.reset_token)
+        }
+        break
+      } else if (msg.status === 'error' || msg.detail) {
+        throw new Error(msg.detail || 'Remote authentication failed')
+      }
+    }
+  } catch (err) {
+    console.error('Remote authentication error:', err)
+    const message = err.message || 'Authentication failed'
+    error.value = message
+    emit('error', message)
+  } finally {
+    if (ws) {
+      ws.close()
+      ws = null
+    }
+  }
+}
+
+function retry() {
+  startRemoteAuth()
+}
+
+function cancel() {
+  if (ws) {
+    ws.close()
+    ws = null
+  }
+  emit('cancelled')
+}
+
+watch(() => props.active, (newVal) => {
+  if (newVal && !pairingCode.value && !error.value && !completed.value) {
+    startRemoteAuth()
+  }
+})
+
+onMounted(() => {
+  if (props.active) {
+    startRemoteAuth()
+  }
+})
+
+onUnmounted(() => {
+  if (ws) {
+    ws.close()
+    ws = null
+  }
+  stopWordAnimation()
+})
+
+defineExpose({ retry, cancel })
+</script>
+
+<style scoped>
+.remote-auth-inline {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  width: 100%;
+}
+
+.loading-section {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 2rem 1rem;
+  min-height: 180px;
+  justify-content: center;
+}
+
+.loading-section p {
+  margin: 0;
+  color: var(--color-text-muted);
+  font-size: 0.95rem;
+}
+
+.spinner {
+  width: 40px;
+  height: 40px;
+  border: 3px solid var(--color-border);
+  border-top-color: var(--color-primary);
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+.auth-display {
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+  width: 100%;
+  min-height: 180px;
+}
+
+.auth-content {
+  display: flex;
+  gap: 2rem;
+  align-items: center;
+  justify-content: center;
+  flex-wrap: nowrap;
+}
+
+.loading-placeholder {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.75rem;
+  width: 100%;
+  padding: 1rem;
+}
+
+.loading-placeholder p {
+  margin: 0;
+  color: var(--color-text-muted);
+  font-size: 0.95rem;
+}
+
+.pairing-code-section {
+  flex: 0 0 auto;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  width: 280px;
+  max-width: 100%;
+}
+
+.pairing-label {
+  margin: 0;
+  font-size: 0.875rem;
+  color: var(--color-text-muted);
+  font-weight: 500;
+  text-align: center;
+}
+
+.slot-machine {
+  padding: 0.875rem 1rem;
+  background: var(--color-surface-hover, rgba(0, 0, 0, 0.03));
+  border: 2px solid var(--color-border);
+  border-radius: var(--radius-sm, 6px);
+  font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;
+  display: flex;
+  align-items: center;
+  user-select: none;
+  pointer-events: none;
+  white-space: nowrap;
+  overflow: hidden;
+}
+
+.slot-reel {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: 1;
+  min-width: 0;
+  height: 1.8em;
+  overflow: hidden;
+  position: relative;
+  background: var(--color-surface, rgba(255, 255, 255, 0.5));
+  border-radius: 3px;
+}
+
+.slot-machine:not(.stopped) .slot-reel:nth-child(1) {
+  animation: slotSpin 0.14s ease-in-out infinite;
+}
+
+.slot-machine:not(.stopped) .slot-reel:nth-child(2) {
+  animation: slotSpin 0.17s ease-in-out infinite;
+}
+
+.slot-machine:not(.stopped) .slot-reel:nth-child(3) {
+  animation: slotSpin 0.20s ease-in-out infinite;
+}
+
+.slot-word {
+  font-size: 1.25rem;
+  font-weight: 600;
+  letter-spacing: 0.05em;
+  text-align: center;
+  width: 100%;
+}
+
+.slot-machine:not(.stopped) .slot-reel:nth-child(1) .slot-word {
+  animation: wordRoll 0.14s ease-in-out infinite;
+}
+
+.slot-machine:not(.stopped) .slot-reel:nth-child(2) .slot-word {
+  animation: wordRoll 0.17s ease-in-out infinite;
+}
+
+.slot-machine:not(.stopped) .slot-reel:nth-child(3) .slot-word {
+  animation: wordRoll 0.20s ease-in-out infinite;
+}
+
+@keyframes slotSpin {
+  0% {
+    box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.1);
+  }
+  50% {
+    box-shadow: inset 0 4px 8px rgba(0, 0, 0, 0.2);
+  }
+  100% {
+    box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.1);
+  }
+}
+
+@keyframes wordRoll {
+  0% {
+    transform: translateY(-30%) scale(0.9);
+    opacity: 0.4;
+    filter: blur(1.5px);
+  }
+  25% {
+    transform: translateY(-10%) scale(0.95);
+    opacity: 0.6;
+    filter: blur(1px);
+  }
+  50% {
+    transform: translateY(0) scale(1);
+    opacity: 1;
+    filter: blur(0);
+  }
+  75% {
+    transform: translateY(10%) scale(0.95);
+    opacity: 0.6;
+    filter: blur(1px);
+  }
+  100% {
+    transform: translateY(30%) scale(0.9);
+    opacity: 0.4;
+    filter: blur(1.5px);
+  }
+}
+
+.site-url {
+  margin: 0.5rem 0 0;
+  font-size: 0.8rem;
+  color: var(--color-text-muted);
+  text-align: center;
+  font-family: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;
+  opacity: 0.8;
+}
+
+.waiting-indicator {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  padding: 0.75rem;
+  background: var(--color-surface-hover, rgba(0, 0, 0, 0.02));
+  border-radius: var(--radius-sm, 6px);
+  font-size: 0.875rem;
+  color: var(--color-text-muted);
+}
+
+.spinner-small {
+  width: 16px;
+  height: 16px;
+  border: 2px solid var(--color-border);
+  border-top-color: var(--color-primary);
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+
+.success-section {
+  padding: 1rem;
+  text-align: center;
+  min-height: 180px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.success-message {
+  margin: 0;
+  font-size: 1rem;
+  color: var(--color-success, #10b981);
+  font-weight: 500;
+}
+
+.error-section {
+  padding: 1rem;
+  text-align: center;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.75rem;
+  min-height: 180px;
+}
+
+.error-message {
+  margin: 0;
+  font-size: 0.95rem;
+  color: var(--color-error, #ef4444);
+}
+
+/* Responsive adjustments */
+@media (max-width: 640px) {
+  .auth-content {
+    gap: 1.5rem;
+    flex-direction: column;
+    align-items: center;
+  }
+
+  .pairing-code-section {
+    width: 100%;
+    max-width: 280px;
+  }
+}
+
+@media (max-width: 480px) {
+  .pairing-code {
+    font-size: 1.1rem;
+    padding: 0.75rem 0.875rem;
+  }
+
+  .pairing-code-section {
+    width: 100%;
+    max-width: 100%;
+  }
+}
+</style>

frontend/src/components/RestrictedAuth.vue

@@ -0,0 +1,310 @@
+<template>
+  <div class="app-shell">
+    <div v-if="status.show" class="global-status" style="display: block;">
+      <div :class="['status', status.type]">
+        {{ status.message }}
+      </div>
+    </div>
+
+    <main class="view-root">
+      <div v-if="!initializing" class="surface surface--tight">
+        <header class="view-header center">
+          <h1>{{ headingTitle }}</h1>
+          <p v-if="isAuthenticated" class="user-line">👤 {{ userDisplayName }}</p>
+          <p class="view-lede" v-html="headerMessage"></p>
+        </header>
+
+        <section class="section-block">
+          <div class="section-body center">
+            <!-- Local passkey authentication view -->
+            <div v-if="authView === 'local'" class="auth-view">
+              <div class="button-row center">
+                <slot name="actions"
+                  :loading="loading"
+                  :can-authenticate="canAuthenticate"
+                  :is-authenticated="isAuthenticated"
+                  :authenticate="authenticateUser"
+                  :logout="logoutUser"
+                  :mode="mode">
+                  <!-- Default actions -->
+                  <button class="btn-secondary" :disabled="loading" @click="$emit('back')">Back</button>
+                  <button v-if="canAuthenticate" class="btn-primary" :disabled="loading" @click="authenticateUser">
+                    {{ loading ? (mode === 'reauth' ? 'Verifying…' : 'Signing in…') : (mode === 'reauth' ? 'Verify' : 'Login') }}
+                  </button>
+                  <button v-if="isAuthenticated && mode !== 'reauth'" class="btn-danger" :disabled="loading" @click="logoutUser">Logout</button>
+                  <button v-if="isAuthenticated && mode !== 'reauth'" class="btn-primary" :disabled="loading" @click="openProfile">Profile</button>
+                </slot>
+              </div>
+            </div>
+
+            <!-- Remote authentication view (request new remote auth) -->
+            <div v-else-if="authView === 'remote'" class="auth-view">
+              <RemoteAuthInline
+                :active="authView === 'remote'"
+                @authenticated="handleRemoteAuthenticated"
+                @register="handleRemoteRegistration"
+                @cancelled="switchToLocal"
+                @error="handleRemoteAuthError"
+              />
+            </div>
+          </div>
+        </section>
+      </div>
+    </main>
+  </div>
+</template>
+
+<script setup>
+import { computed, onMounted, onUnmounted, reactive, ref } from 'vue'
+import passkey from '@/utils/passkey'
+import { getSettings, uiBasePath } from '@/utils/settings'
+import { fetchJson, getUserFriendlyErrorMessage } from '@/utils/api'
+import RemoteAuthInline from '@/components/RemoteAuthRequest.vue'
+
+const props = defineProps({
+  mode: {
+    type: String,
+    default: 'login',
+    validator: (value) => ['login', 'reauth', 'forbidden'].includes(value)
+  }
+})
+
+const emit = defineEmits(['authenticated', 'forbidden', 'logout', 'back', 'home', 'auth-error'])
+
+const status = reactive({ show: false, message: '', type: 'info' })
+const initializing = ref(true)
+const loading = ref(false)
+const settings = ref(null)
+const userInfo = ref(null)
+const currentView = ref('initial') // 'initial', 'login', 'forbidden'
+const authView = ref('local') // 'local' or 'remote'
+let statusTimer = null
+
+const isAuthenticated = computed(() => !!userInfo.value?.authenticated)
+
+const canAuthenticate = computed(() => {
+  if (initializing.value) return false
+  if (props.mode === 'reauth') return true
+  if (currentView.value === 'forbidden') return false
+  return true
+})
+
+const headingTitle = computed(() => {
+  if (props.mode === 'reauth') {
+    return `🔐 Additional Authentication`
+  }
+  if (currentView.value === 'forbidden') return '🚫 Forbidden'
+  return `🔐 ${settings.value?.rp_name || location.origin}`
+})
+
+const headerMessage = computed(() => {
+  if (props.mode === 'reauth') {
+    return 'Please verify your identity to continue with this action.'
+  }
+  if (currentView.value === 'forbidden') {
+    return 'You lack the required permissions.'
+  }
+  if (authView.value === 'remote') {
+    return 'Confirm from your other device. Or <a href="#" class="inline-link" data-action="local">this device</a>.'
+  }
+  if (canAuthenticate.value && props.mode !== 'reauth') {
+    return 'Please sign in with your passkey. Or use <a href="#" class="inline-link" data-action="remote">another device</a>.'
+  }
+  return 'Please sign in with your passkey.'
+})
+
+const userDisplayName = computed(() => userInfo.value?.user?.user_name || 'User')
+
+function showMessage(message, type = 'info', duration = 3000) {
+  status.show = true
+  status.message = message
+  status.type = type
+  if (statusTimer) clearTimeout(statusTimer)
+  if (duration > 0) statusTimer = setTimeout(() => { status.show = false }, duration)
+}
+
+async function fetchSettings() {
+  try {
+    const data = await getSettings()
+    settings.value = data
+    if (data?.rp_name) {
+      const titleSuffix = props.mode === 'reauth'
+        ? 'Verify Identity'
+        : (isAuthenticated.value ? 'Forbidden' : 'Sign In')
+      document.title = `${data.rp_name} · ${titleSuffix}`
+    }
+  } catch (error) {
+    console.warn('Unable to load settings', error)
+  }
+}
+
+async function fetchUserInfo() {
+  try {
+    userInfo.value = await fetchJson('/auth/api/user-info', { method: 'POST' })
+    if (isAuthenticated.value && props.mode !== 'reauth') {
+      currentView.value = 'forbidden'
+      emit('forbidden', userInfo.value)
+    } else {
+      currentView.value = 'login'
+    }
+  } catch (error) {
+    console.error('Failed to load user info', error)
+    if (error.status !== 401 && error.status !== 403) {
+      showMessage(getUserFriendlyErrorMessage(error), 'error', 4000)
+    }
+    userInfo.value = null
+    currentView.value = 'login'
+  }
+}
+
+async function authenticateUser() {
+  if (!canAuthenticate.value || loading.value) return
+  loading.value = true
+  showMessage('Starting authentication…', 'info')
+  let result
+  try { result = await passkey.authenticate() } catch (error) {
+    loading.value = false
+    const message = error?.message || 'Passkey authentication cancelled'
+    const cancelled = message === 'Passkey authentication cancelled'
+    showMessage(message, cancelled ? 'info' : 'error', 4000)
+    emit('auth-error', { message, cancelled })
+    return
+  }
+  try { await setSessionCookie(result) } catch (error) {
+    loading.value = false
+    const message = error?.message || 'Failed to establish session'
+    showMessage(message, 'error', 4000)
+    emit('auth-error', { message, cancelled: false })
+    return
+  }
+  loading.value = false
+  emit('authenticated', result)
+}
+
+async function logoutUser() {
+  if (loading.value) return
+  loading.value = true
+  try {
+    await fetchJson('/auth/api/logout', { method: 'POST' })
+    userInfo.value = null
+    currentView.value = 'login'
+    showMessage('Logged out. You can sign in with a different account.', 'info', 3000)
+  } catch (error) {
+    showMessage(getUserFriendlyErrorMessage(error), 'error', 4000)
+  }
+  finally { loading.value = false }
+  emit('logout')
+}
+
+function openProfile() {
+  const profileWindow = window.open('/auth/', 'passkey_auth_profile')
+  if (profileWindow) profileWindow.focus()
+}
+
+async function setSessionCookie(result) {
+  if (!result?.session_token) {
+    console.error('setSessionCookie called with missing session_token:', result)
+    throw new Error('Authentication response missing session_token')
+  }
+  return await fetchJson('/auth/api/set-session', {
+    method: 'POST', headers: { Authorization: `Bearer ${result.session_token}` }
+  })
+}
+
+function switchToRemote() {
+  authView.value = 'remote'
+}
+
+function switchToLocal() {
+  authView.value = 'local'
+}
+
+async function handleRemoteAuthenticated(result) {
+  showMessage('Authenticated from another device!', 'success', 2000)
+  try {
+    await setSessionCookie(result)
+  } catch (error) {
+    const message = error?.message || 'Failed to establish session'
+    showMessage(message, 'error', 4000)
+    emit('auth-error', { message, cancelled: false })
+    return
+  }
+  emit('authenticated', result)
+}
+
+function handleRemoteRegistration(token) {
+  showMessage('Registration approved! Redirecting...', 'success', 2000)
+  const basePath = uiBasePath() || '/auth/'
+  window.location.href = `${basePath}${token}`
+}
+
+function handleRemoteAuthError(errorMsg) {
+  // Error is already shown in the RemoteAuth component, don't show toast
+}
+
+function handleHeaderLinkClick(event) {
+  const target = event.target
+  if (target.tagName === 'A' && target.classList.contains('inline-link')) {
+    event.preventDefault()
+    const action = target.dataset.action
+    if (action === 'remote') {
+      switchToRemote()
+    } else if (action === 'local') {
+      switchToLocal()
+    }
+  }
+}
+
+onMounted(async () => {
+  await fetchSettings()
+  await fetchUserInfo()
+  initializing.value = false
+
+  // Add click handler for inline links
+  document.addEventListener('click', handleHeaderLinkClick)
+})
+
+onUnmounted(() => {
+  document.removeEventListener('click', handleHeaderLinkClick)
+})
+
+defineExpose({
+  showMessage,
+  isAuthenticated,
+  userInfo
+})
+</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 {
+  max-width: 520px;
+  margin: 0 auto;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 1.75rem;
+}
+
+.auth-view {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 1rem;
+  width: 100%;
+}
+
+.view-lede :deep(.inline-link) {
+  color: var(--color-primary);
+  text-decoration: none;
+  transition: opacity 0.15s;
+  font-weight: 400;
+}
+
+.view-lede :deep(.inline-link:hover) {
+  opacity: 0.8;
+  text-decoration: underline;
+}
+</style>

frontend/src/components/SessionList.vue

@@ -7,33 +7,45 @@
     <div class="section-body">
       <div :class="['session-list']">
         <template v-if="Array.isArray(sessions) && sessions.length">
-          <div
-            v-for="session in sessions"
-            :key="session.id"
-            :class="['session-item', { 'is-current': session.is_current }]"
-          >
-            <div class="item-top">
-              <div class="item-icon">
-                <span class="session-emoji">🌐</span>
-              </div>
-              <h4 class="item-title">{{ sessionHostLabel(session) }}</h4>
-              <div class="item-actions">
-                <span v-if="session.is_current" class="badge badge-current">Current</span>
-                <span v-else-if="session.is_current_host" class="badge">This host</span>
-                <button
-                  v-if="allowTerminate"
-                  @click="$emit('terminate', session)"
-                  class="btn-card-delete"
-                  :disabled="isTerminating(session.id)"
-                  :title="isTerminating(session.id) ? 'Terminating...' : 'Terminate session'"
-                >🗑️</button>
-              </div>
-            </div>
-            <div class="item-details">
-              <div class="session-dates">
-                <span class="date-label">Last used:</span>
-                <span class="date-value">{{ formatDate(session.last_renewed) }}</span>
-                <span class="session-meta-info">{{ session.user_agent }} {{ session.ip }}</span>
+          <div v-for="(group, host) in groupedSessions" :key="host" class="session-group">
+            <h3 :class="['session-group-host', { 'is-current-site': group.isCurrentSite }]">
+              <template v-if="host"><a :href="hostUrl(host)">🌐 {{ host }}</a></template>
+              <template v-else>🌐 Unbound host</template>
+            </h3>
+            <div class="session-group-sessions">
+              <div
+                v-for="session in group.sessions"
+                :key="session.id"
+                :class="['session-item', {
+                  'is-current': session.is_current && !hoveredIp && !hoveredCredentialUuid,
+                  'is-hovered': hoveredSession?.id === session.id,
+                  'is-linked-credential': hoveredCredentialUuid === session.credential_uuid
+                }]"
+                tabindex="0"
+                @focusin="handleSessionFocus(session)"
+                @focusout="handleSessionBlur($event)"
+              >
+                <div class="item-top">
+                  <h4 class="item-title">{{ session.user_agent }}</h4>
+                  <div class="item-actions">
+                    <span v-if="session.is_current && !hoveredIp && !hoveredCredentialUuid" class="badge badge-current">Current</span>
+                    <span v-else-if="hoveredSession?.id === session.id" class="badge badge-current">Selected</span>
+                    <span v-else-if="hoveredCredentialUuid === session.credential_uuid" class="badge badge-current">Linked</span>
+                    <span v-else-if="!hoveredCredentialUuid && isSameNetwork(session.ip)" class="badge">Same IP</span>
+                    <button
+                      @click="$emit('terminate', session)"
+                      class="btn-card-delete"
+                      :disabled="isTerminating(session.id)"
+                      :title="isTerminating(session.id) ? 'Terminating...' : 'Terminate session'"
+                    >🗑️</button>
+                  </div>
+                </div>
+                <div class="item-details">
+                  <div class="session-dates">
+                    <span class="date-label">{{ formatDate(session.last_renewed) }}</span>
+                    <span class="date-value">{{ session.ip }}</span>
+                  </div>
+                </div>
               </div>
             </div>
           </div>
@@ -45,29 +57,150 @@
 </template>
 
 <script setup>
-import { } from 'vue'
+import { computed, ref } from 'vue'
 import { formatDate } from '@/utils/helpers'
 
 const props = defineProps({
   sessions: { type: Array, default: () => [] },
-  allowTerminate: { type: Boolean, default: true },
   emptyMessage: { type: String, default: 'You currently have no other active sessions.' },
   sectionDescription: { type: String, default: "Review where you're signed in and end any sessions you no longer recognize." },
-  terminatingSessions: { type: Object, default: () => ({}) }
+  terminatingSessions: { type: Object, default: () => ({}) },
+  hoveredCredentialUuid: { type: String, default: null },
 })
 
-const emit = defineEmits(['terminate'])
+const emit = defineEmits(['terminate', 'sessionHover'])
+
+const hoveredIp = ref(null)
+const hoveredSession = ref(null)
+
+const handleSessionFocus = (session) => {
+  hoveredSession.value = session
+  hoveredIp.value = session.ip || null
+  emit('sessionHover', session)
+}
+
+const handleSessionBlur = (event) => {
+  // Only clear if focus moved outside this element
+  if (!event.currentTarget.contains(event.relatedTarget)) {
+    hoveredSession.value = null
+    hoveredIp.value = null
+    emit('sessionHover', null)
+  }
+}
 
 const isTerminating = (sessionId) => !!props.terminatingSessions[sessionId]
 
-const sessionHostLabel = (session) => {
-  if (!session || !session.host) return 'Unbound host'
-  return session.host
+const hostUrl = (host) => {
+  // Assume http if there's a port number, https otherwise
+  const protocol = host.includes(':') ? 'http' : 'https'
+  return `${protocol}://${host}`
 }
+
+// Extract /64 prefix for IPv6, or return full IP for IPv4
+const getNetworkPrefix = ip => {
+  if (!ip) return null
+
+  // IPv4?
+  if (!ip.includes(':')) return ip
+
+  // Normalize IPv6 using URL
+  // Wrap in brackets so URL accepts it
+  const norm = new URL(`http://[${ip}]/`).hostname
+
+  // norm is now fully expanded, e.g. "2001:0db8:0000:0000:0000:0000:0000:0001"
+  const parts = norm.split(':')
+  return parts.slice(0, 4).join(':')
+}
+
+const currentNetworkPrefix = computed(() => {
+  // Use hovered IP if available, otherwise fall back to current session
+  if (hoveredIp.value) return getNetworkPrefix(hoveredIp.value)
+  const current = props.sessions.find(s => s.is_current)
+  return current ? getNetworkPrefix(current.ip) : null
+})
+
+const isSameNetwork = (ip) => {
+  if (!currentNetworkPrefix.value || !ip) return false
+  return getNetworkPrefix(ip) === currentNetworkPrefix.value
+}
+
+const groupedSessions = computed(() => {
+  const groups = {}
+  for (const session of props.sessions) {
+    const host = session.host || ''
+    if (!groups[host]) {
+      groups[host] = { sessions: [], isCurrentSite: false }
+    }
+    groups[host].sessions.push(session)
+    if (session.is_current_host) {
+      groups[host].isCurrentSite = true
+    }
+  }
+  // Sort sessions within each group by last_renewed descending
+  for (const host in groups) {
+    groups[host].sessions.sort((a, b) => new Date(b.last_renewed) - new Date(a.last_renewed))
+  }
+  // Sort groups by host name (natural sort)
+  const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' })
+  const sortedHosts = Object.keys(groups).sort(collator.compare)
+  const sortedGroups = {}
+  for (const host of sortedHosts) {
+    sortedGroups[host] = groups[host]
+  }
+  return sortedGroups
+})
 </script>
 
 <style>
 .session-meta-info {
   grid-column: span 2;
 }
-</style>
+[data-component="session-list-section"] .session-list {
+  display: flex;
+  flex-direction: column;
+  gap: 1.5em;
+}
+.session-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5em;
+}
+.session-group-host {
+  font-size: 1em;
+  font-weight: 600;
+  margin: 0;
+}
+.session-group-host a {
+  color: inherit;
+  text-decoration: none;
+}
+.session-group-host a:hover {
+  text-decoration: underline;
+}
+.session-group-host.is-current-site {
+  color: var(--color-accent);
+}
+.session-group-sessions {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(var(--card-width), 1fr));
+  gap: 0.5em;
+  align-items: start;
+}
+.session-group-sessions .session-item {
+  width: auto;
+  height: auto;
+  padding: 0.75rem;
+  gap: 0.5rem;
+}
+.session-group-sessions .session-item .item-title {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.session-group-sessions .session-item .item-details {
+  margin-left: 0;
+}
+.session-group-sessions .session-item .session-dates {
+  grid-template-columns: auto 1fr;
+}
+</style>

frontend/src/components/UserBasicInfo.vue

@@ -1,5 +1,5 @@
 <template>
-  <div v-if="userLoaded" class="user-info">
+  <div v-if="userLoaded" class="user-info" :class="{ 'has-extra': $slots.default }">
     <h3 class="user-name-heading">
       <span class="icon">👤</span>
       <span class="user-name-row">
@@ -11,12 +11,15 @@
       <div class="org-line" v-if="orgDisplayName">{{ orgDisplayName }}</div>
       <div class="role-line" v-if="roleName">{{ roleName }}</div>
     </div>
-    <span><strong>Visits:</strong></span>
-    <span>{{ visits || 0 }}</span>
-    <span><strong>Registered:</strong></span>
-    <span>{{ formatDate(createdAt) }}</span>
-    <span><strong>Last seen:</strong></span>
-    <span>{{ formatDate(lastSeen) }}</span>
+    <span class="info-label"><strong>Visits:</strong></span>
+    <span class="info-value">{{ visits || 0 }}</span>
+    <span class="info-label"><strong>Registered:</strong></span>
+    <span class="info-value">{{ formatDate(createdAt) }}</span>
+    <span class="info-label"><strong>Last seen:</strong></span>
+    <span class="info-value">{{ formatDate(lastSeen) }}</span>
+    <div v-if="$slots.default" class="user-info-extra">
+      <slot></slot>
+    </div>
   </div>
 </template>
 
@@ -44,13 +47,50 @@ const userLoaded = computed(() => !!props.name)
 </script>
 
 <style scoped>
-.user-info { display: grid; grid-template-columns: auto 1fr; gap: 10px; }
-.user-info h3 { grid-column: span 2; }
-.org-role-sub { grid-column: span 2; display:flex; flex-direction:column; margin: -0.15rem 0 0.25rem; }
+.user-info.has-extra {
+  grid-template-columns: auto 1fr;
+  grid-template-areas:
+    "heading heading"
+    "org org"
+    "label1 value1"
+    "label2 value2"
+    "label3 value3"
+    "extra extra";
+}
+
+.user-info:not(.has-extra) {
+  grid-template-columns: auto 1fr;
+  grid-template-areas:
+    "heading heading"
+    "org org"
+    "label1 value1"
+    "label2 value2"
+    "label3 value3";
+}
+
+@media (min-width: 769px) {
+  .user-info.has-extra {
+    grid-template-columns: auto 1fr 2fr;
+    grid-template-areas:
+      "heading heading extra"
+      "org org extra"
+      "label1 value1 extra"
+      "label2 value2 extra"
+      "label3 value3 extra";
+  }
+}
+
+.user-name-heading { grid-area: heading; display: flex; align-items: center; gap: 0.4rem; flex-wrap: wrap; margin: 0 0 0.25rem 0; }
+.org-role-sub { grid-area: org; display:flex; flex-direction:column; margin: -0.15rem 0 0.25rem; }
 .org-line { font-size: .7rem; font-weight:600; line-height:1.1; color: var(--color-text-muted); text-transform: uppercase; letter-spacing: 0.05em; }
 .role-line { font-size:.65rem; color: var(--color-text-muted); line-height:1.1; }
-.user-info span { text-align: left; }
-.user-name-heading { display: flex; align-items: center; gap: 0.4rem; flex-wrap: wrap; margin: 0 0 0.25rem 0; }
+.info-label:nth-of-type(1) { grid-area: label1; }
+.info-value:nth-of-type(2) { grid-area: value1; }
+.info-label:nth-of-type(3) { grid-area: label2; }
+.info-value:nth-of-type(4) { grid-area: value2; }
+.info-label:nth-of-type(5) { grid-area: label3; }
+.info-value:nth-of-type(6) { grid-area: value3; }
+.user-info-extra { grid-area: extra; padding-left: 2rem; border-left: 1px solid var(--color-border); }
 .user-name-row { display: inline-flex; align-items: center; gap: 0.35rem; max-width: 100%; }
 .user-name-row.editing { flex: 1 1 auto; }
 .icon { flex: 0 0 auto; }
@@ -62,5 +102,6 @@ const userLoaded = computed(() => !!props.name)
 .mini-btn:hover:not(:disabled) { background: var(--color-accent-soft); color: var(--color-accent); }
 .mini-btn:active:not(:disabled) { transform: translateY(1px); }
 .mini-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+@media (max-width: 768px) { .user-info-extra { padding-left: 0; padding-top: 1rem; border-left: none; border-top: 1px solid var(--color-border); } }
 @media (max-width: 480px) { .user-name-heading { flex-direction: column; align-items: flex-start; } .user-name-row.editing { width: 100%; } .display-name { max-width: 100%; } }
 </style>

frontend/src/host/HostApp.vue

@@ -1,138 +0,0 @@
-<template>
-  <div class="app-shell">
-    <StatusMessage />
-    <main class="view-root host-view">
-      <div class="view-content">
-        <header class="view-header">
-          <h1>{{ headingTitle }}</h1>
-          <p class="view-lede">{{ subheading }}</p>
-        </header>
-
-        <section class="section-block">
-          <div class="section-body">
-            <UserBasicInfo
-              v-if="user"
-              :name="user.user_name"
-              :visits="user.visits || 0"
-              :created-at="user.created_at"
-              :last-seen="user.last_seen"
-              :org-display-name="orgDisplayName"
-              :role-name="roleDisplayName"
-              :can-edit="false"
-            />
-            <p v-else class="empty-state">
-              {{ initializing ? 'Loading your account…' : 'No active session found.' }}
-            </p>
-          </div>
-        </section>
-
-        <section class="section-block">
-          <div class="section-body host-actions">
-            <div class="button-row">
-              <button
-                type="button"
-                class="btn-secondary"
-                @click="history.back()"
-              >
-                Back
-              </button>
-              <button
-                type="button"
-                class="btn-danger"
-                :disabled="authStore.isLoading"
-                @click="logout"
-              >
-                {{ authStore.isLoading ? 'Signing out…' : 'Logout' }}
-              </button>
-              <button
-                v-if="authSiteUrl"
-                type="button"
-                class="btn-primary"
-                :disabled="authStore.isLoading"
-                @click="goToAuthSite"
-              >
-                Full Profile
-              </button>
-            </div>
-            <p class="note"><strong>Logout</strong> from {{ currentHost }}, or access your <strong>Full Profile</strong> at {{ authSiteHost }} (you may need to sign in again).</p>
-          </div>
-        </section>
-      </div>
-    </main>
-  </div>
-</template>
-
-<script setup>
-import { computed, onMounted, ref } from 'vue'
-import StatusMessage from '@/components/StatusMessage.vue'
-import UserBasicInfo from '@/components/UserBasicInfo.vue'
-import { useAuthStore } from '@/stores/auth'
-
-const authStore = useAuthStore()
-const initializing = ref(true)
-const currentHost = window.location.host
-
-const user = computed(() => authStore.userInfo?.user || null)
-const orgDisplayName = computed(() => authStore.userInfo?.org?.display_name || '')
-const roleDisplayName = computed(() => authStore.userInfo?.role?.display_name || '')
-
-const headingTitle = computed(() => {
-  const service = authStore.settings?.rp_name
-  return service ? `${service} account` : 'Account overview'
-})
-
-const subheading = computed(() => {
-  const service = authStore.settings?.rp_name || 'this service'
-  return `You're signed in to ${currentHost}.`
-})
-
-const authSiteHost = computed(() => authStore.settings?.auth_host || '')
-const authSiteUrl = computed(() => {
-  const host = authSiteHost.value
-  if (!host) return ''
-  let path = authStore.settings?.ui_base_path ?? '/auth/'
-  if (!path.startsWith('/')) path = `/${path}`
-  if (!path.endsWith('/')) path = `${path}/`
-  const protocol = window.location.protocol || 'https:'
-  return `${protocol}//${host}${path}`
-})
-
-const goToAuthSite = () => {
-  if (!authSiteUrl.value) return
-  window.location.href = authSiteUrl.value
-}
-
-const logout = async () => {
-  await authStore.logout()
-}
-
-onMounted(async () => {
-  try {
-    await authStore.loadSettings()
-    const service = authStore.settings?.rp_name
-    if (service) document.title = `${service} · Account summary`
-    await authStore.loadUserInfo()
-  } catch (error) {
-    const message = error instanceof Error ? error.message : 'Unable to load session details'
-    authStore.showMessage(message, 'error', 4000)
-  } finally {
-    initializing.value = false
-  }
-})
-</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: 0 0 auto; }
-.note { margin: 0; color: var(--color-text-muted); }
-.link { color: var(--color-accent); text-decoration: none; }
-.link:hover { text-decoration: underline; }
-.view-hint { margin-top: 0.5rem; color: var(--color-text-muted); }
-.empty-state { margin: 0; color: var(--color-text-muted); }
-@media (max-width: 600px) {
-  .host-actions .button-row { flex-direction: column; }
-  .host-actions .button-row button { width: 100%; }
-}
-</style>

frontend/src/host/main.js

@@ -1,11 +0,0 @@
-import '@/assets/style.css'
-
-import { createApp } from 'vue'
-import { createPinia } from 'pinia'
-import HostApp from './HostApp.vue'
-
-const app = createApp(HostApp)
-
-app.use(createPinia())
-
-app.mount('#app')

frontend/src/restricted/RestrictedApp.vue

@@ -1,176 +0,0 @@
-<template>
-  <div class="app-shell">
-    <div v-if="status.show" class="global-status" style="display: block;">
-      <div :class="['status', status.type]">
-        {{ status.message }}
-      </div>
-    </div>
-
-    <main class="view-root">
-      <div class="view-content">
-        <div v-if="!initializing" class="surface surface--tight">
-          <header class="view-header center">
-            <h1>{{ headingTitle }}</h1>
-            <p v-if="isAuthenticated" class="user-line">👤 {{ userDisplayName }}</p>
-            <p class="view-lede">{{ headerMessage }}</p>
-          </header>
-
-          <section class="section-block">
-            <div class="section-body center">
-              <div class="button-row center">
-                <button class="btn-secondary" :disabled="loading" @click="backNav">Back</button>
-                <button v-if="canAuthenticate" class="btn-primary" :disabled="loading" @click="authenticateUser">
-                  {{ loading ? 'Signing in…' : 'Login' }}
-                </button>
-                <button v-if="isAuthenticated" class="btn-danger" :disabled="loading" @click="logoutUser">Logout</button>
-                <button v-if="isAuthenticated" class="btn-primary" :disabled="loading" @click="returnHome">Profile</button>
-              </div>
-            </div>
-          </section>
-        </div>
-      </div>
-    </main>
-  </div>
-</template>
-
-<script setup>
-import { computed, onMounted, reactive, ref } from 'vue'
-import passkey from '@/utils/passkey'
-import { getSettings, uiBasePath } from '@/utils/settings'
-
-const status = reactive({ show: false, message: '', type: 'info' })
-const initializing = ref(true)
-const loading = ref(false)
-const settings = ref(null)
-const userInfo = ref(null)
-let statusTimer = null
-
-const isAuthenticated = computed(() => !!userInfo.value?.authenticated)
-const canAuthenticate = computed(() => !initializing.value && !isAuthenticated.value)
-const basePath = computed(() => uiBasePath())
-
-const headingTitle = computed(() => {
-  if (!isAuthenticated.value) return `🔐 ${settings.value?.rp_name || location.origin}`
-  return '🚫 Forbidden'
-})
-
-const headerMessage = computed(() => {
-  if (!isAuthenticated.value) return 'Please sign in to access this page.'
-  return 'You lack the permissions required to access this page.'
-})
-
-const userDisplayName = computed(() => userInfo.value?.user?.user_name || 'User')
-
-function showMessage(message, type = 'info', duration = 3000) {
-  status.show = true
-  status.message = message
-  status.type = type
-  if (statusTimer) clearTimeout(statusTimer)
-  if (duration > 0) statusTimer = setTimeout(() => { status.show = false }, duration)
-}
-
-async function fetchSettings() {
-  try {
-    const data = await getSettings()
-    settings.value = data
-    if (data?.rp_name) document.title = isAuthenticated.value ? `${data.rp_name} · Forbidden` : `${data.rp_name} · Sign In`
-  } catch (error) {
-    console.warn('Unable to load settings', error)
-  }
-}
-
-async function fetchUserInfo() {
-  try {
-    const res = await fetch('/auth/api/user-info', { method: 'POST' })
-    console.log("fetchUserInfo response:", res); // Debug log
-    if (!res.ok) {
-      const payload = await safeParseJson(res)
-      showMessage(payload.detail || 'Unable to load user session info.', 'error', 2000)
-      return
-    }
-    userInfo.value = await res.json()
-    // If the user is authenticated but still here, they lack permissions.
-    if (isAuthenticated.value) showMessage('Permission Denied', 'error', 2000)
-  } catch (error) {
-    console.error('Failed to load user info', error)
-    showMessage('Could not contact the authentication server', 'error', 2000)
-  }
-}
-
-async function authenticateUser() {
-  if (!canAuthenticate.value || loading.value) return
-  loading.value = true
-  showMessage('Starting authentication…', 'info')
-  let result
-  try { result = await passkey.authenticate() } catch (error) {
-    loading.value = false
-    const message = error?.message || 'Passkey authentication cancelled'
-    const cancelled = message === 'Passkey authentication cancelled'
-    showMessage(cancelled ? message : `Authentication failed: ${message}`, cancelled ? 'info' : 'error', 4000)
-    return
-  }
-  try { await setSessionCookie(result.session_token) } catch (error) {
-    loading.value = false
-    const message = error?.message || 'Failed to establish session'
-    showMessage(message, 'error', 4000)
-    return
-  }
-  location.reload()
-}
-
-async function logoutUser() {
-  if (loading.value) return
-  loading.value = true
-  try { await fetch('/auth/api/logout', { method: 'POST' }) } catch (_) { /* ignore */ }
-  finally { loading.value = false; window.location.reload() }
-}
-
-async function setSessionCookie(sessionToken) {
-  const response = await fetch('/auth/api/set-session', {
-    method: 'POST', headers: { Authorization: `Bearer ${sessionToken}` }
-  })
-  const payload = await safeParseJson(response)
-  if (!response.ok || payload?.detail) throw new Error(payload?.detail || 'Session could not be established.')
-  return payload
-}
-
-function returnHome() {
-  const target = basePath.value || '/auth/'
-  if (window.location.pathname !== target) history.replaceState(null, '', target)
-  window.location.href = target
-}
-
-function backNav() {
-  try {
-    if (history.length > 1) {
-      history.back()
-      return
-    }
-  } catch (_) { /* ignore */ }
-  returnHome()
-}
-
-async function safeParseJson(response) { try { return await response.json() } catch (_) { return null } }
-
-onMounted(async () => {
-  await fetchSettings()
-  await fetchUserInfo()
-  initializing.value = false
-})
-</script>
-
-<style scoped>
-.button-row.center { display: flex; justify-content: center; gap: 0.75rem; }
-.user-line { margin: 0.5rem 0 0; font-weight: 500; color: var(--color-text); }
-/* Vertically center the restricted "dialog" surface in the viewport */
-main.view-root { min-height: 100vh; display: flex; align-items: center; justify-content: center; padding: 2rem 1rem; }
-main.view-root .view-content { width: 100%; }
-.surface.surface--tight {
-  max-width: 520px;
-  margin: 0 auto;
-  width: 100%;
-  display: flex;
-  flex-direction: column;
-  gap: 1.75rem;
-}
-</style>

frontend/src/restricted/main.js

@@ -1,5 +0,0 @@
-import { createApp } from 'vue'
-import RestrictedApp from './RestrictedApp.vue'
-import '@/assets/style.css'
-
-createApp(RestrictedApp).mount('#app')

frontend/src/stores/auth.js

@@ -1,6 +1,7 @@
 import { defineStore } from 'pinia'
 import { register, authenticate } from '@/utils/passkey'
 import { getSettings } from '@/utils/settings'
+import { apiJson } from '@/utils/api'
 
 export const useAuthStore = defineStore('auth', {
   state: () => ({
@@ -37,22 +38,21 @@ export const useAuthStore = defineStore('auth', {
         }, duration)
       }
     },
-    async setSessionCookie(sessionToken) {
-      const response = await fetch('/auth/api/set-session', {
-        method: 'POST',
-        headers: {'Authorization': `Bearer ${sessionToken}`},
-      })
-      const result = await response.json()
-      if (result.detail) {
-        throw new Error(result.detail)
+    async setSessionCookie(result) {
+      if (!result?.session_token) {
+        console.error('setSessionCookie called with missing session_token:', result)
+        throw new Error('Authentication response missing session_token')
       }
-      return result
+      return await apiJson('/auth/api/set-session', {
+        method: 'POST',
+        headers: {'Authorization': `Bearer ${result.session_token}`},
+      })
     },
     async register() {
       this.isLoading = true
       try {
         const result = await register()
-        await this.setSessionCookie(result.session_token)
+        await this.setSessionCookie(result)
         await this.loadUserInfo()
         this.selectView()
         return result
@@ -65,7 +65,7 @@ export const useAuthStore = defineStore('auth', {
       try {
         const result = await authenticate()
 
-        await this.setSessionCookie(result.session_token)
+        await this.setSessionCookie(result)
         await this.loadUserInfo()
         this.selectView()
 
@@ -82,45 +82,26 @@ export const useAuthStore = defineStore('auth', {
       this.settings = await getSettings()
     },
     async loadUserInfo() {
-      const response = await fetch('/auth/api/user-info', { method: 'POST' })
-      let result = null
       try {
-        result = await response.json()
-      } catch (_) {
-        // ignore JSON parse errors (unlikely)
+        this.userInfo = await apiJson('/auth/api/user-info', { method: 'POST' })
+        console.log('User info loaded:', this.userInfo)
+      } catch (error) {
+        // Suppress toast for 401/403 errors - the auth iframe will handle these
+        if (error.status === 401 || error.status === 403) {
+          console.log('Authentication required:', error.message)
+        } else {
+          this.showMessage(error.message || 'Failed to load user info', 'error', 5000)
+        }
+        throw error
       }
-      if (response.status === 401 && result?.detail) {
-        this.showMessage(result.detail, 'error', 5000)
-        throw new Error(result.detail)
-      }
-      if (result?.detail) {
-        // Other error style
-        this.showMessage(result.detail, 'error', 5000)
-        throw new Error(result.detail)
-      }
-      this.userInfo = result
-      console.log('User info loaded:', result)
     },
     async deleteCredential(uuid) {
-  const response = await fetch(`/auth/api/user/credential/${uuid}`, {method: 'Delete'})
-      const result = await response.json()
-      if (result.detail) throw new Error(`Server: ${result.detail}`)
-
+      await apiJson(`/auth/api/user/credential/${uuid}`, { method: 'DELETE' })
       await this.loadUserInfo()
     },
     async terminateSession(sessionId) {
       try {
-        const res = await fetch(`/auth/api/user/session/${sessionId}`, { method: 'DELETE' })
-        let payload = null
-        try {
-          payload = await res.json()
-        } catch (_) {
-          // ignore JSON parse errors
-        }
-        if (!res.ok || payload?.detail) {
-          const message = payload?.detail || 'Failed to terminate session'
-          throw new Error(message)
-        }
+        const payload = await apiJson(`/auth/api/user/session/${sessionId}`, { method: 'DELETE' })
         if (payload?.current_session_terminated) {
           sessionStorage.clear()
           location.reload()
@@ -135,42 +116,28 @@ export const useAuthStore = defineStore('auth', {
     },
     async logout() {
       try {
-        const res = await fetch('/auth/api/logout', {method: 'POST'})
-        if (!res.ok) {
-          let message = 'Logout failed'
-          try {
-            const data = await res.json()
-            if (data?.detail) message = data.detail
-          } catch (_) {
-            // ignore JSON parse errors
-          }
-          throw new Error(message)
-        }
+        await apiJson('/auth/api/logout', {method: 'POST'})
         sessionStorage.clear()
         location.reload()
       } catch (error) {
         console.error('Logout error:', error)
-        this.showMessage(error.message, 'error')
+        // Suppress toast for 401/403 errors - the auth iframe will handle these
+        if (error.status !== 401 && error.status !== 403) {
+          this.showMessage(error.message, 'error')
+        }
       }
     },
     async logoutEverywhere() {
       try {
-        const res = await fetch('/auth/api/user/logout-all', {method: 'POST'})
-        if (!res.ok) {
-          let message = 'Logout failed'
-          try {
-            const data = await res.json()
-            if (data?.detail) message = data.detail
-          } catch (_) {
-            // ignore JSON parse errors
-          }
-          throw new Error(message)
-        }
+        await apiJson('/auth/api/user/logout-all', {method: 'POST'})
         sessionStorage.clear()
         location.reload()
       } catch (error) {
         console.error('Logout-all error:', error)
-        this.showMessage(error.message, 'error')
+        // Suppress toast for 401/403 errors - the auth iframe will handle these
+        if (error.status !== 401 && error.status !== 403) {
+          this.showMessage(error.message, 'error')
+        }
       }
     },
   }

frontend/src/utils/api.js

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

frontend/src/utils/awaitable-websocket.js

@@ -5,8 +5,8 @@ class AwaitableWebSocket extends WebSocket {
   #opened = false
 
   constructor(resolve, reject, url, protocols, binaryType) {
-    // Support relative URLs even on old browsers that don't
-    super(new URL(url, location.href.replace(/^http/, 'ws')), protocols)
+    // Support relative URLs even on old browsers that don't natively support them
+    super(new URL(url, document.baseURI.replace(/^http/, 'ws')), protocols)
     this.binaryType = binaryType || 'blob'
     this.onopen = () => {
       this.#opened = true
@@ -18,12 +18,36 @@ class AwaitableWebSocket extends WebSocket {
     }
     this.onclose = e => {
       if (!this.#opened) {
-        reject(new Error(`WebSocket ${this.url} failed to connect, code ${e.code}`))
+        reject(new Error(`Failed to connect to server (code ${e.code})`))
         return
       }
-      this.#err = e.wasClean
-        ? new Error(`Websocket ${this.url} closed ${e.code}`)
-        : new Error(`WebSocket ${this.url} closed with error ${e.code}`)
+      // Create user-friendly close messages
+      let message
+      if (e.wasClean) {
+        // Standard close codes
+        switch (e.code) {
+          case 1000: message = 'Connection closed normally'; break
+          case 1001: message = 'Server is going away'; break
+          case 1002: message = 'Protocol error'; break
+          case 1003: message = 'Unsupported data received'; break
+          case 1006: message = 'Connection lost unexpectedly'; break
+          case 1007: message = 'Invalid data received'; break
+          case 1008: message = 'Policy violation'; break
+          case 1009: message = 'Message too large'; break
+          case 1010: message = 'Extension negotiation failed'; break
+          case 1011: message = 'Server encountered an error'; break
+          case 1012: message = 'Server is restarting'; break
+          case 1013: message = 'Server is overloaded, try again later'; break
+          case 1014: message = 'Bad gateway'; break
+          case 1015: message = 'TLS handshake failed'; break
+          default: message = `Connection closed (code ${e.code})`
+        }
+      } else {
+        message = e.code === 1006
+          ? 'Connection lost unexpectedly'
+          : `Connection closed with error (code ${e.code})`
+      }
+      this.#err = new Error(message)
       this.#waiting.splice(0).forEach(p => p.reject(this.#err))
     }
   }
@@ -51,17 +75,12 @@ class AwaitableWebSocket extends WebSocket {
       console.error("WebSocket received binary data, expected JSON string", data)
       throw new Error("WebSocket received binary data, expected JSON string")
     }
-    let parsed
     try {
-      parsed = JSON.parse(data)
+      return JSON.parse(data)
     } catch (err) {
       console.error("Failed to parse JSON from WebSocket message", data, err)
       throw new Error("Failed to parse JSON from WebSocket message")
     }
-    if (parsed.detail) {
-      throw new Error(`Server: ${parsed.detail}`)
-    }
-    return parsed
   }
 
   send_json(data) {

frontend/src/utils/base64url.js

@@ -0,0 +1,33 @@
+/**
+ * URL-safe Base64 encoding/decoding utilities.
+ *
+ * These functions handle base64url format (RFC 4648) which uses:
+ * - '-' instead of '+'
+ * - '_' instead of '/'
+ * - No padding '=' characters
+ */
+
+/**
+ * Decode a base64url string to Uint8Array.
+ * Handles both standard base64 and URL-safe base64 (with or without padding).
+ * @param {string} str - Base64url encoded string
+ * @returns {Uint8Array} - Decoded bytes
+ */
+export function dec(str) {
+  // Convert URL-safe characters to standard base64
+  const base64 = str.replace(/-/g, '+').replace(/_/g, '/')
+  // Add padding if needed
+  const padded = base64 + '='.repeat((4 - base64.length % 4) % 4)
+  return Uint8Array.from(atob(padded), c => c.charCodeAt(0))
+}
+
+/**
+ * Encode a Uint8Array to base64url string.
+ * @param {Uint8Array} bytes - Bytes to encode
+ * @returns {string} - Base64url encoded string (no padding)
+ */
+export function enc(bytes) {
+  const base64 = btoa(String.fromCharCode(...bytes))
+  // Convert to URL-safe and remove padding
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}

frontend/src/utils/helpers.js

@@ -24,3 +24,5 @@ export function getCookie(name) {
   const parts = value.split(`; ${name}=`)
   if (parts.length === 2) return parts.pop().split(';').shift()
 }
+
+export const goBack = () => history.back() || window.close()

frontend/src/utils/passkey.js

@@ -1,6 +1,7 @@
 import { startRegistration, startAuthentication } from '@simplewebauthn/browser'
 import aWebSocket from '@/utils/awaitable-websocket'
 import { getSettings } from '@/utils/settings'
+import { showAuthIframe } from '@/utils/api'
 
 // Generic path normalizer: if an auth_host is configured and differs from current
 // host, return absolute URL (scheme derived by aWebSocket). Otherwise, keep as-is.
@@ -10,33 +11,66 @@ async function makeUrl(path) {
   return h && location.host !== h ? `//${h}${path}` : path
 }
 
-export async function register(resetToken = null, displayName = null) {
+export async function register(resetToken = null, displayName = null, onstartreg = null) {
   let params = []
   if (resetToken) params.push(`reset=${encodeURIComponent(resetToken)}`)
   if (displayName) params.push(`name=${encodeURIComponent(displayName)}`)
   const qs = params.length ? `?${params.join('&')}` : ''
-  const ws = await aWebSocket(await makeUrl(`/auth/ws/register${qs}`))
-  try {
-    const optionsJSON = await ws.receive_json()
-    const registrationResponse = await startRegistration({ optionsJSON })
-    ws.send_json(registrationResponse)
-    return await ws.receive_json()
-  } catch (error) {
-    console.error('Registration error:', error)
-     // Replace useless and ugly error message from startRegistration
-    throw Error(error.name === "NotAllowedError" ? 'Passkey registration cancelled' : error.message)
-  } finally {
-    ws.close()
+
+  while (true) {
+    const ws = await aWebSocket(await makeUrl(`/auth/ws/register${qs}`))
+    try {
+      const res = await ws.receive_json()
+
+      // Handle auth errors (401/403) with iframe
+      if ((res.status === 401 || res.status === 403) && res.auth?.iframe) {
+        ws.close()
+        await showAuthIframe(res.auth.iframe)
+        continue
+      }
+
+      // Handle other errors (status field present means error)
+      if (res.status) {
+        throw new Error(res.detail || `Registration failed: ${res.status}`)
+      }
+
+      // Notify caller that we're about to show the browser prompt
+      if (onstartreg) onstartreg()
+
+      const registrationResponse = await startRegistration(res)
+      ws.send_json(registrationResponse)
+
+      const result = await ws.receive_json()
+      if (result.status) {
+        throw new Error(result.detail || `Registration failed: ${result.status}`)
+      }
+      return result
+    } catch (error) {
+      ws.close()
+      console.error('Registration error:', error)
+      // Replace useless and ugly error message from startRegistration
+      throw Error(error.name === "NotAllowedError" ? 'Passkey registration cancelled' : error.message)
+    }
   }
 }
 
 export async function authenticate() {
   const ws = await aWebSocket(await makeUrl('/auth/ws/authenticate'))
   try {
-    const optionsJSON = await ws.receive_json()
-    const authResponse = await startAuthentication({ optionsJSON })
+    const res = await ws.receive_json()
+    console.log('Authentication options:', res)
+    // status field present means error
+    if (res.status) {
+      throw new Error(res.detail || `Authentication failed: ${res.status}`)
+    }
+
+    const authResponse = await startAuthentication(res)
     ws.send_json(authResponse)
+
     const result = await ws.receive_json()
+    if (result.status) {
+      throw new Error(result.detail || `Authentication failed: ${result.status}`)
+    }
     return result
   } catch (error) {
     console.error('Authentication error:', error)

frontend/src/utils/pow-test.js

@@ -0,0 +1,37 @@
+import { solvePoW, verifyPoW } from './pow.js'
+
+const TRIALS = 5
+const WORK = 10
+
+async function test() {
+  console.log(`Running ${TRIALS} trials with ${WORK} work units...\n`)
+
+  const times = []
+
+  for (let trial = 1; trial <= TRIALS; trial++) {
+    const challenge = crypto.getRandomValues(new Uint8Array(8))
+
+    const start = performance.now()
+    const solution = await solvePoW(challenge, WORK)
+    const elapsed = performance.now() - start
+
+    const valid = await verifyPoW(challenge, solution, WORK)
+
+    times.push(elapsed)
+
+    console.log(`Trial ${trial.toString().padStart(2)}: ${(elapsed / 1000).toFixed(3)}s, valid=${valid}`)
+  }
+
+  const avgTime = times.reduce((a, b) => a + b, 0) / times.length
+  const minTime = Math.min(...times)
+  const maxTime = Math.max(...times)
+
+  console.log('\n--- Summary ---')
+  console.log(`Trials: ${TRIALS}`)
+  console.log(`Work units: ${WORK}`)
+  console.log(`Avg time: ${(avgTime / 1000).toFixed(3)}s`)
+  console.log(`Min time: ${(minTime / 1000).toFixed(3)}s`)
+  console.log(`Max time: ${(maxTime / 1000).toFixed(3)}s`)
+}
+
+test()

frontend/src/utils/pow.js

@@ -0,0 +1,68 @@
+/**
+ * Proof of Work utility using PBKDF2-SHA512
+ *
+ * The PoW requires finding nonces where PBKDF2(challenge, nonce) produces
+ * output with a zero first byte. Each work unit requires finding one such nonce.
+ * All valid nonces are concatenated into a solution for server verification.
+ */
+
+/**
+ * Solve a Proof of Work challenge
+ *
+ * @param {Uint8Array|ArrayBuffer} challenge - 8-byte server-provided challenge
+ * @param {number} work - Number of PBKDF2 work units required
+ * @param {object} [options] - Optional parameters
+ * @param {AbortSignal} [options.signal] - AbortSignal to cancel the operation
+ * @returns {Promise<Uint8Array>} Solution: concatenated 8-byte nonces (8 * work bytes)
+ * @throws {Error} If challenge is invalid or operation is aborted
+ */
+export async function solvePoW(challenge, work, options = {}) {
+  const { signal } = options
+  const startTime = performance.now()
+
+  // Validate inputs
+  const challengeBytes = challenge instanceof ArrayBuffer
+    ? new Uint8Array(challenge)
+    : challenge
+
+  if (!(challengeBytes instanceof Uint8Array) || challengeBytes.length !== 8) {
+    throw new Error('Challenge must be exactly 8 bytes')
+  }
+
+  // Import challenge as PBKDF2 key material
+  const baseKey = await crypto.subtle.importKey('raw', challengeBytes, 'PBKDF2', false, ['deriveBits'])
+
+  // Build solution from found nonces
+  const solution = new Uint8Array(8 * work)
+  let totalIterations = 0
+  const mask = 0x7FF  // The client must work 2048x harder than the server
+
+  // Sequential nonce starting at zero (little-endian, using Uint32Array for efficient increment)
+  const nonce = new Uint32Array(2)
+
+  for (let i = 0; i < work; i++) {
+    if (signal?.aborted) {
+      throw new DOMException('PoW operation aborted', 'AbortError')
+    }
+
+    // Find a nonce where PBKDF2 output passes the mask check
+    let result
+    do {
+      totalIterations++
+      if (++nonce[0] === 0x100000000) ++nonce[1]  // Increment 64-bit little-endian nonce
+      result = new Uint32Array(await crypto.subtle.deriveBits(
+        { name: 'PBKDF2', salt: nonce, iterations: 128, hash: 'SHA-512'},
+        baseKey,
+        32
+      ))
+    } while (result[0] & mask)
+    solution.set(new Uint8Array(nonce.buffer), i * 8)
+  }
+
+  const elapsed = (performance.now() - startTime) / 1000
+  const expectedIterations = work * (mask + 1)
+  const luckRatio = (totalIterations / expectedIterations).toFixed(1)
+  const bench = totalIterations / ((mask + 1) * elapsed)
+  console.log(`PoW work=${work} solved in ${elapsed.toFixed(2)}s (${luckRatio}x expected ${bench.toFixed(1)} work/s)`)
+  return solution
+}

frontend/vite.config.js

@@ -1,64 +1,103 @@
 import { fileURLToPath, URL } from 'node:url'
-
 import { defineConfig } from 'vite'
 import { resolve } from 'node:path'
 import vue from '@vitejs/plugin-vue'
+import { existsSync, renameSync, mkdirSync } from 'node:fs'
+import sirv from 'sirv'
 
-// https://vite.dev/config/
-export default defineConfig(({ command, mode }) => ({
+export default defineConfig(({ command }) => ({
+  appType: 'mpa',
+  publicDir: 'public',
   plugins: [
     vue(),
+    {
+      name: 'serve-examples',
+      configureServer(server) {
+        const examplesDir = resolve(__dirname, '../examples')
+        const serve = sirv(examplesDir, { dev: true })
+        server.middlewares.use((req, _res, next) => {
+          if (req.url === '/' || req.url === '/index.html') req.url = '/examples/'
+          next()
+        })
+        server.middlewares.use('/examples', serve)
+      }
+    },
+    {
+      name: 'move-html-files',
+      closeBundle() {
+        if (command !== 'build') return
+
+        const outDir = resolve(__dirname, '../paskia/frontend-build')
+        const moves = [
+          { from: 'auth.html', to: 'auth/index.html' },
+          { from: 'admin.html', to: 'admin/index.html' },
+          { from: 'restricted.html', to: 'restricted/index.html' },
+          { from: 'reset.html', to: 'reset/index.html' },
+          { from: 'forward.html', to: 'forward/index.html' }
+        ]
+
+        for (const { from, to } of moves) {
+          const fromPath = resolve(outDir, from)
+          const toPath = resolve(outDir, to)
+          if (existsSync(fromPath)) {
+            mkdirSync(resolve(outDir, to.split('/')[0]), { recursive: true })
+            renameSync(fromPath, toPath)
+          }
+        }
+      }
+    }
   ],
   resolve: {
-    alias: {
-      '@': fileURLToPath(new URL('./src', import.meta.url))
-    },
+    alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) }
   },
-  // Use absolute paths at dev, deploy under /auth/
-  base: command === 'build' ? '/auth/' : '/',
+  base: '/',
   server: {
     port: 4403,
+    allowedHosts: true,
+    fs: {
+      allow: ['..']
+    },
     proxy: {
-      '/auth/': {
+      // Only proxy these two specific backend API paths
+      '/auth/api': {
+        target: 'http://localhost:4402'
+      },
+      '/auth/ws': {
         target: 'http://localhost:4402',
-        ws: true,
-        changeOrigin: false,
-        // We proxy API + WS under /auth/, but want Vite to serve the SPA entrypoints
-        // and static assets so that HMR works. Bypass tells http-proxy to skip
-        // proxying when we return a (possibly rewritten) local path.
-        bypass(req) {
-          const rawUrl = req.url || ''
-          // Strip query/hash to match path-only for SPA entrypoints with query params (e.g. ?reset=token)
-          const url = rawUrl.split('?')[0].split('#')[0]
-          // Bypass only root SPA entrypoints + static assets so Vite serves them for HMR.
-          // Admin API endpoints (e.g., /auth/admin/orgs) must still hit backend.
-          if (url === '/auth/' || url === '/auth') return '/'
-          if (url === '/auth/host' || url === '/auth/host/') return '/host/index.html'
-          if (url === '/host' || url === '/host/') return '/host/index.html'
-          if (url === '/auth/admin' || url === '/auth/admin/') return '/admin/'
-          if (url.startsWith('/auth/assets/')) return url.replace(/^\/auth/, '')
-          if (/^\/auth\/([a-z]+\.){4}[a-z]+\/?$/.test(url)) return '/reset/index.html'
-          if (/^\/([a-z]+\.){4}[a-z]+\/?$/.test(url)) return '/reset/index.html'
-          if (url === '/auth/restricted' || url === '/auth/restricted/') return '/restricted/index.html'
-          if (url === '/restricted' || url === '/restricted/') return '/restricted/index.html'
-          // Everything else (including /auth/admin/* APIs) should proxy.
-        }
+        ws: true
+      },
+      // Passphrase links: /auth/word1.word2.word3.word4.word5
+      '^/auth/[a-z]+\\.[a-z]+\\.[a-z]+\\.[a-z]+\\.[a-z]+$': {
+        target: 'http://localhost:4402'
+      },
+      // Passphrase links: /word1.word2.word3.word4.word5
+      '^/[a-z]+\\.[a-z]+\\.[a-z]+\\.[a-z]+\\.[a-z]+$': {
+        target: 'http://localhost:4402'
       }
     }
   },
   build: {
-    outDir: '../passkey/frontend-build',
+    outDir: '../paskia/frontend-build',
     emptyOutDir: true,
-    assetsDir: 'assets',
     rollupOptions: {
       input: {
-        index: resolve(__dirname, 'index.html'),
-        admin: resolve(__dirname, 'admin/index.html'),
-        reset: resolve(__dirname, 'reset/index.html'),
-        restricted: resolve(__dirname, 'restricted/index.html'),
-        host: resolve(__dirname, 'host/index.html')
+        auth: resolve(__dirname, 'auth/index.html'),
+        admin: resolve(__dirname, 'auth/admin/index.html'),
+        restricted: resolve(__dirname, 'auth/restricted/index.html'),
+        reset: resolve(__dirname, 'int/reset/index.html'),
+        forward: resolve(__dirname, 'int/forward/index.html'),
       },
-      output: {}
+      output: {
+        entryFileNames: (chunkInfo) => {
+          return 'auth/assets/[name]-[hash].js'
+        },
+        chunkFileNames: (chunkInfo) => {
+          return 'auth/assets/[name]-[hash].js'
+        },
+        assetFileNames: (assetInfo) => {
+          return 'auth/assets/[name]-[hash][extname]'
+        }
+      }
     }
   }
 }))

paskia/__init__.py

@@ -0,0 +1,3 @@
+from paskia.sansio import Passkey
+
+__all__ = ["Passkey"]

paskia/aaguid/__init__.py

@@ -14,7 +14,7 @@ from importlib.resources import files
 __ALL__ = ["AAGUID", "filter"]
 
 # Path to the AAGUID JSON file
-AAGUID_FILE = files("passkey") / "aaguid" / "combined_aaguid.json"
+AAGUID_FILE = files("paskia") / "aaguid" / "combined_aaguid.json"
 AAGUID: dict[str, dict] = json.loads(AAGUID_FILE.read_text(encoding="utf-8"))
 
 

paskia/authsession.py

@@ -11,11 +11,11 @@ independent of any web framework:
 from datetime import datetime, timezone
 from uuid import UUID
 
-from .config import SESSION_LIFETIME
-from .db import ResetToken, Session
-from .globals import db, passkey
-from .util import hostutil
-from .util.tokens import create_token, reset_key, session_key
+from paskia.config import SESSION_LIFETIME
+from paskia.db import ResetToken, Session
+from paskia.globals import db, passkey
+from paskia.util import hostutil
+from paskia.util.tokens import create_token, reset_key, session_key
 
 EXPIRES = SESSION_LIFETIME
 
@@ -69,36 +69,26 @@ async def create_session(
 async def get_reset(token: str) -> ResetToken:
     """Validate a credential reset token. Returns None if the token is not well formed (i.e. it is another type of token)."""
     record = await db.instance.get_reset_token(reset_key(token))
-    if not record:
-        raise ValueError("Invalid or expired session token")
-    if record.expiry < datetime.now(timezone.utc):
-        await db.instance.delete_reset_token(record.key)
-        raise ValueError("Invalid or expired session token")
-    return record
+    if record and record.expiry >= datetime.now(timezone.utc):
+        return record
+    raise ValueError("This authentication link is no longer valid.")
 
 
 async def get_session(token: str, host: str | None = None) -> Session:
     """Validate a session token and return session data if valid."""
+    host = hostutil.normalize_host(host)
+    if not host:
+        raise ValueError("Invalid host")
     session = await db.instance.get_session(session_key(token))
-    if not session:
-        raise ValueError("Invalid or expired session token")
-    if session_expiry(session) < datetime.now(timezone.utc):
-        await db.instance.delete_session(session.key)
-        raise ValueError("Invalid or expired session token")
-    if host is not None:
-        normalized_host = hostutil.normalize_host(host)
-        if not normalized_host:
-            raise ValueError("Invalid host")
-        current = session.host
-        if current is None:
+    if session and session_expiry(session) >= datetime.now(timezone.utc):
+        if session.host is None:
             # First time binding: store exact host:port (or IPv6 form) now.
-            await db.instance.set_session_host(session.key, normalized_host)
-            session.host = normalized_host
-        elif current == normalized_host:
-            pass  # exact match ok
-        else:
-            raise ValueError("Invalid or expired session token")
-    return session
+            await db.instance.set_session_host(session.key, host)
+            session.host = host
+        elif session.host != host:
+            raise ValueError("Session host mismatch")
+        return session
+    raise ValueError("Your session has expired. Please sign in again!")
 
 
 async def refresh_session_token(token: str, *, ip: str, user_agent: str):

paskia/bootstrap.py

@@ -12,9 +12,9 @@ from datetime import datetime, timezone
 
 import uuid7
 
-from . import authsession, globals
-from .db import Org, Permission, Role, User
-from .util import hostutil, passphrase, tokens
+from paskia import authsession, globals
+from paskia.db import Org, Permission, Role, User
+from paskia.util import hostutil, passphrase, tokens
 
 
 def _init_logger() -> logging.Logger:
@@ -53,16 +53,10 @@ async def _create_and_log_admin_reset_link(user_uuid, message, session_type) ->
     return reset_link
 
 
-async def bootstrap_system(
-    user_name: str | None = None, org_name: str | None = None
-) -> dict:
+async def bootstrap_system() -> dict:
     """
     Bootstrap the entire system with default data.
 
-    Args:
-        user_name: Display name for the admin user (default: "Admin")
-        org_name: Display name for the organization (default: "Organization")
-
     Returns:
         dict: Contains information about created entities and reset link
     """
@@ -70,7 +64,7 @@ async def bootstrap_system(
     perm0 = Permission(id="auth:admin", display_name="Master Admin")
     await globals.db.instance.create_permission(perm0)
 
-    org = Org(uuid7.create(), org_name or "Organization")
+    org = Org(uuid7.create(), "Organization")
     await globals.db.instance.create_organization(org)
 
     # After creation, org.permissions now includes the auto-created org admin permission
@@ -89,7 +83,7 @@ async def bootstrap_system(
 
     user = User(
         uuid=uuid7.create(),
-        display_name=user_name or "Admin",
+        display_name="Admin",
         role_uuid=role.uuid,
         created_at=datetime.now(timezone.utc),
         visits=0,
@@ -159,16 +153,10 @@ async def check_admin_credentials() -> bool:
         return False
 
 
-async def bootstrap_if_needed(
-    default_admin: str | None = None, default_org: str | None = None
-) -> bool:
+async def bootstrap_if_needed() -> bool:
     """
     Check if system needs bootstrapping and perform it if necessary.
 
-    Args:
-        default_admin: Display name for the admin user
-        default_org: Display name for the organization
-
     Returns:
         bool: True if bootstrapping was performed, False if system was already set up
     """
@@ -185,35 +173,17 @@ async def bootstrap_if_needed(
 
     # 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(default_admin, default_org)
+    await bootstrap_system()
     return True
 
 
 # CLI interface
 async def main():
     """Main CLI entry point for bootstrapping."""
-    import argparse
-
     # Configure logging for CLI usage
     logging.basicConfig(level=logging.INFO, format="%(message)s", force=True)
 
-    parser = argparse.ArgumentParser(
-        description="Bootstrap passkey authentication system"
-    )
-    parser.add_argument(
-        "--user-name",
-        default=None,
-        help="Name for the admin user (default: Admin)",
-    )
-    parser.add_argument(
-        "--org-name",
-        default=None,
-        help="Name for the organization (default: Organization)",
-    )
-
-    args = parser.parse_args()
-
-    await globals.init(default_admin=args.user_name, default_org=args.org_name)
+    await globals.init()
 
 
 if __name__ == "__main__":

paskia/config.py

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

paskia/db/__init__.py

@@ -92,6 +92,7 @@ class SessionContext:
     user: User
     org: Org
     role: Role
+    credential: Credential | None = None
     permissions: list[Permission] | None = None
 
 

paskia/db/sql.py

@@ -5,6 +5,7 @@ This module provides an async database layer using SQLAlchemy async mode
 for managing users and credentials in a WebAuthn authentication system.
 """
 
+import os
 from contextlib import asynccontextmanager
 from datetime import datetime, timezone
 from uuid import UUID
@@ -26,9 +27,8 @@ from sqlalchemy.dialects.sqlite import BLOB
 from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
-from ..config import SESSION_LIFETIME
-from ..globals import db
-from . import (
+from paskia.config import SESSION_LIFETIME
+from paskia.db import (
     Credential,
     DatabaseInterface,
     Org,
@@ -39,8 +39,9 @@ from . import (
     SessionContext,
     User,
 )
+from paskia.globals import db
 
-DB_PATH = "sqlite+aiosqlite:///passkey-auth.sqlite"
+DB_PATH_DEFAULT = "sqlite+aiosqlite:///paskia.sqlite"
 
 
 def _normalize_dt(value: datetime | None) -> datetime | None:
@@ -52,7 +53,8 @@ def _normalize_dt(value: datetime | None) -> datetime | None:
 
 
 async def init(*args, **kwargs):
-    db.instance = DB()
+    db_path = os.environ.get("PASKIA_DB", DB_PATH_DEFAULT)
+    db.instance = DB(db_path)
     await db.instance.init_db()
 
 
@@ -289,7 +291,7 @@ class RolePermission(Base):
 class DB(DatabaseInterface):
     """Database class that handles its own connections."""
 
-    def __init__(self, db_path: str = DB_PATH):
+    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
@@ -439,7 +441,7 @@ class DB(DatabaseInterface):
             credential_model = result.scalar_one_or_none()
 
             if not credential_model:
-                raise ValueError("Credential not registered")
+                raise ValueError("Credential not found")
             return Credential(
                 uuid=UUID(bytes=credential_model.uuid),
                 credential_id=credential_model.credential_id,
@@ -1314,19 +1316,24 @@ class DB(DatabaseInterface):
         Uses efficient JOINs to retrieve all related data in a single database query.
         """
         async with self.session() as session:
-            # Build a query that joins sessions, users, roles, organizations, and role_permissions
+            # Build a query that joins sessions, users, roles, organizations, credentials and role_permissions
             stmt = (
                 select(
                     SessionModel,
                     UserModel,
                     RoleModel,
                     OrgModel,
+                    CredentialModel,
                     PermissionModel,
                 )
                 .select_from(SessionModel)
                 .join(UserModel, SessionModel.user_uuid == UserModel.uuid)
                 .join(RoleModel, UserModel.role_uuid == RoleModel.uuid)
                 .join(OrgModel, RoleModel.org_uuid == OrgModel.uuid)
+                .outerjoin(
+                    CredentialModel,
+                    SessionModel.credential_uuid == CredentialModel.uuid,
+                )
                 .outerjoin(RolePermission, RoleModel.uuid == RolePermission.role_uuid)
                 .outerjoin(
                     PermissionModel, RolePermission.permission_id == PermissionModel.id
@@ -1342,7 +1349,9 @@ class DB(DatabaseInterface):
 
             # Extract the first row to get session and user data
             first_row = rows[0]
-            session_model, user_model, role_model, org_model, _ = first_row
+            session_model, user_model, role_model, org_model, credential_model, _ = (
+                first_row
+            )
 
             # Create the session object
             if host is not None:
@@ -1371,11 +1380,16 @@ class DB(DatabaseInterface):
                 display_name=role_model.display_name,
             )
 
+            # Create credential object if available
+            credential_obj = (
+                credential_model.as_dataclass() if credential_model else None
+            )
+
             # Collect all unique permissions for the role
             permissions = []
             seen_permission_ids = set()
             for row in rows:
-                _, _, _, _, permission_model = row
+                _, _, _, _, _, permission_model = row
                 if permission_model and permission_model.id not in seen_permission_ids:
                     permissions.append(
                         Permission(
@@ -1405,5 +1419,6 @@ class DB(DatabaseInterface):
                 user=user_obj,
                 org=organization,
                 role=role,
+                credential=credential_obj,
                 permissions=effective_permissions if effective_permissions else None,
             )

paskia/fastapi/__init__.py

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

paskia/fastapi/__main__.py

@@ -7,11 +7,10 @@ from urllib.parse import urlparse
 
 import uvicorn
 
-from passkey.util import frontend
+from paskia.util.hostutil import normalize_origin
 
 DEFAULT_HOST = "localhost"
 DEFAULT_SERVE_PORT = 4401
-DEFAULT_DEV_PORT = 4402
 
 
 def is_subdomain(sub: str, domain: str) -> bool:
@@ -114,7 +113,13 @@ def add_common_options(p: argparse.ArgumentParser) -> None:
         "--rp-id", default="localhost", help="Relying Party ID (default: localhost)"
     )
     p.add_argument("--rp-name", help="Relying Party name (default: same as rp-id)")
-    p.add_argument("--origin", help="Origin URL (default: https://<rp-id>)")
+    p.add_argument(
+        "--origin",
+        action="append",
+        dest="origins",
+        metavar="URL",
+        help="Allowed origin URL(s). May be specified multiple times. If any are specified, only those origins are permitted for WebSocket authentication.",
+    )
     p.add_argument(
         "--auth-host",
         help=(
@@ -129,7 +134,7 @@ def main():
     logging.basicConfig(level=logging.INFO, format="%(message)s", force=True)
 
     parser = argparse.ArgumentParser(
-        prog="passkey-auth", description="Passkey authentication server"
+        prog="paskia", description="Paskia authentication server"
     )
     sub = parser.add_subparsers(dest="command", required=True)
 
@@ -147,18 +152,6 @@ def main():
     )
     add_common_options(serve)
 
-    # dev subcommand
-    dev = sub.add_parser("dev", help="Run the server in development (auto-reload)")
-    dev.add_argument(
-        "hostport",
-        nargs="?",
-        help=(
-            "Endpoint (default: localhost:4402). Forms: host[:port] | :port | "
-            "[ipv6][:port] | ipv6 | unix:/path.sock"
-        ),
-    )
-    add_common_options(dev)
-
     # reset subcommand
     reset = sub.add_parser(
         "reset",
@@ -176,65 +169,121 @@ def main():
 
     args = parser.parse_args()
 
-    if args.command in {"serve", "dev"}:
-        default_port = DEFAULT_DEV_PORT if args.command == "dev" else DEFAULT_SERVE_PORT
-        host, port, uds, all_ifaces = parse_endpoint(args.hostport, default_port)
-        devmode = args.command == "dev"
+    if args.command == "serve":
+        host, port, uds, all_ifaces = parse_endpoint(args.hostport, DEFAULT_SERVE_PORT)
     else:
         host = port = uds = all_ifaces = None  # type: ignore
-        devmode = False
-
-    # Determine origin (dev mode default override)
-    origin = args.origin
-    if devmode and not args.origin and not args.rp_id:
-        # Dev mode: Vite runs on another port, override:
-        origin = "http://localhost:4403"
-
-    # Export configuration via environment for lifespan initialization in each process
-    os.environ.setdefault("PASSKEY_RP_ID", args.rp_id)
-    if args.rp_name:
-        os.environ["PASSKEY_RP_NAME"] = args.rp_name
-    if origin:
-        os.environ["PASSKEY_ORIGIN"] = origin
-    if getattr(args, "auth_host", None):
-        os.environ["PASSKEY_AUTH_HOST"] = args.auth_host
-    else:
-        # Preserve pre-set env variable if CLI option omitted
-        args.auth_host = os.environ.get("PASSKEY_AUTH_HOST")
 
+    # Collect and normalize origins, handle auth_host
+    origins = [normalize_origin(o) for o in (getattr(args, "origins", None) or [])]
     if args.auth_host:
+        # Normalize auth_host with scheme
+        if "://" not in args.auth_host:
+            args.auth_host = f"https://{args.auth_host}"
+
         validate_auth_host(args.auth_host, args.rp_id)
-        from passkey.util import hostutil as _hostutil  # local import
 
-        _hostutil.reload_config()
+        # If origins are configured, ensure auth_host is included at top
+        if origins:
+            # Insert auth_host at the beginning (Passkey.__init__ will dedupe)
+            origins.insert(0, args.auth_host)
 
-    # One-time initialization + bootstrap before starting any server processes.
-    # Lifespan in worker processes will call globals.init with bootstrap disabled.
-    from passkey import globals as _globals  # local import
+    # Compute site_url and site_path for reset links
+    # Priority: auth_host > first origin with localhost > http://localhost:port
+    if args.auth_host:
+        site_url = args.auth_host.rstrip("/")
+        site_path = "/"
+    elif origins:
+        # Find localhost origin if rp_id is localhost, else use first origin
+        localhost_origin = (
+            next((o for o in origins if "://localhost" in o), None)
+            if args.rp_id == "localhost"
+            else None
+        )
+        site_url = (localhost_origin or origins[0]).rstrip("/")
+        site_path = "/auth/"
+    elif args.rp_id == "localhost" and port:
+        # Dev mode: use http with port
+        site_url = f"http://localhost:{port}"
+        site_path = "/auth/"
+    else:
+        site_url = f"https://{args.rp_id}"
+        site_path = "/auth/"
+
+    # Build runtime configuration
+    from paskia.config import PaskiaConfig
+
+    config = PaskiaConfig(
+        rp_id=args.rp_id,
+        rp_name=args.rp_name or None,
+        origins=origins or None,
+        auth_host=args.auth_host or None,
+        site_url=site_url,
+        site_path=site_path,
+        host=host,
+        port=port,
+        uds=uds,
+    )
+
+    # Export configuration via single JSON env variable for worker processes
+    import json
+
+    config_json = {
+        "rp_id": config.rp_id,
+        "rp_name": config.rp_name,
+        "origins": config.origins,
+        "auth_host": config.auth_host,
+        "site_url": config.site_url,
+        "site_path": config.site_path,
+    }
+    os.environ["PASKIA_CONFIG"] = json.dumps(config_json)
+
+    # Initialize globals (without bootstrap yet)
+    from paskia import globals as _globals  # local import
 
     asyncio.run(
         _globals.init(
-            rp_id=args.rp_id,
-            rp_name=args.rp_name,
-            origin=origin,
-            default_admin=os.getenv("PASSKEY_DEFAULT_ADMIN") or None,
-            default_org=os.getenv("PASSKEY_DEFAULT_ORG") or None,
-            bootstrap=True,
+            rp_id=config.rp_id,
+            rp_name=config.rp_name,
+            origins=config.origins,
+            bootstrap=False,
         )
     )
 
+    # Print startup configuration
+    from paskia.util import startupbox
+
+    startupbox.print_startup_config(config)
+
+    # Bootstrap after startup box is printed
+    from paskia.bootstrap import bootstrap_if_needed
+
+    asyncio.run(bootstrap_if_needed())
+
     # Handle recover-admin command (no server start)
     if args.command == "reset":
-        from passkey.fastapi import reset as reset_cmd  # local import
+        from paskia.fastapi import reset as reset_cmd  # local import
 
         exit_code = reset_cmd.run(getattr(args, "query", None))
         raise SystemExit(exit_code)
 
-    if args.command in {"serve", "dev"}:
+    if args.command == "serve":
         run_kwargs: dict = {
-            "reload": devmode,
             "log_level": "info",
         }
+
+        # Dev mode: enable reload when PASKIA_DEVMODE is set
+        devmode = bool(os.environ.get("PASKIA_DEVMODE"))
+        if devmode:
+            # Security: dev mode must run on localhost:4402 to prevent
+            # accidental public exposure of the Vite dev server
+            if host != "localhost" or port != 4402:
+                raise SystemExit(f"Dev mode requires localhost:4402, got {host}:{port}")
+            run_kwargs["reload"] = True
+            run_kwargs["reload_dirs"] = ["paskia"]
+            # Suppress uvicorn startup messages in dev mode
+            run_kwargs["log_level"] = "warning"
+
         if uds:
             run_kwargs["uds"] = uds
         else:
@@ -242,20 +291,17 @@ def main():
                 run_kwargs["host"] = host
                 run_kwargs["port"] = port
 
-        if devmode:
-            if os.environ.get("PASSKEY_BUN_PARENT") != "1":
-                os.environ["PASSKEY_BUN_PARENT"] = "1"
-                frontend.run_dev()
-
         if all_ifaces and not uds:
+            # Dev mode with all interfaces: use simple single-server approach
             if devmode:
                 run_kwargs["host"] = "::"
                 run_kwargs["port"] = port
-                uvicorn.run("passkey.fastapi:app", **run_kwargs)
+                uvicorn.run("paskia.fastapi:app", **run_kwargs)
             else:
+                # Production: run separate servers for IPv4 and IPv6
                 from uvicorn import Config, Server  # noqa: E402 local import
 
-                from passkey.fastapi import (
+                from paskia.fastapi import (
                     app as fastapi_app,  # noqa: E402 local import
                 )
 
@@ -278,7 +324,7 @@ def main():
 
                 asyncio.run(serve_both())
         else:
-            uvicorn.run("passkey.fastapi:app", **run_kwargs)
+            uvicorn.run("paskia.fastapi:app", **run_kwargs)
 
 
 if __name__ == "__main__":

paskia/fastapi/admin.py

@@ -2,12 +2,14 @@ import logging
 from datetime import timezone
 from uuid import UUID, uuid4
 
-from fastapi import Body, FastAPI, HTTPException, Request
-from fastapi.responses import FileResponse, JSONResponse
+from fastapi import Body, FastAPI, HTTPException, Request, Response
+from fastapi.responses import JSONResponse
 
-from ..authsession import reset_expires
-from ..globals import db
-from ..util import (
+from paskia.authsession import reset_expires
+from paskia.fastapi import authz
+from paskia.fastapi.session import AUTH_COOKIE
+from paskia.globals import db
+from paskia.util import (
     frontend,
     hostutil,
     passphrase,
@@ -16,9 +18,7 @@ from ..util import (
     tokens,
     useragent,
 )
-from ..util.tokens import encode_session_key, session_key
-from . import authz
-from .session import AUTH_COOKIE
+from paskia.util.tokens import encode_session_key, session_key
 
 app = FastAPI()
 
@@ -28,30 +28,24 @@ async def value_error_handler(_request, exc: ValueError):  # pragma: no cover -
     return JSONResponse(status_code=400, content={"detail": str(exc)})
 
 
+@app.exception_handler(authz.AuthException)
+async def auth_exception_handler(_request, exc: authz.AuthException):
+    """Handle AuthException with auth info for UI."""
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=await authz.auth_error_content(exc),
+    )
+
+
 @app.exception_handler(Exception)
-async def general_exception_handler(_request, exc: Exception):
+async def general_exception_handler(_request, exc: Exception):  # pragma: no cover
     logging.exception("Unhandled exception in admin app")
     return JSONResponse(status_code=500, content={"detail": "Internal server error"})
 
 
 @app.get("/")
 async def adminapp(request: Request, auth=AUTH_COOKIE):
-    """Serve admin SPA only for authenticated users with admin/org permissions.
-
-    On missing/invalid session or insufficient permissions, serve restricted SPA.
-    """
-    try:
-        await authz.verify(
-            auth,
-            ["auth:admin", "auth:org:*"],
-            match=permutil.has_any,
-            host=request.headers.get("host"),
-        )
-        return FileResponse(frontend.file("admin/index.html"))
-    except HTTPException as e:
-        return FileResponse(
-            frontend.file("restricted", "index.html"), status_code=e.status_code
-        )
+    return Response(*await frontend.read("/auth/admin/index.html"))
 
 
 # -------------------- Organizations --------------------
@@ -145,7 +139,9 @@ async def admin_update_org(
 
     current = await db.instance.get_organization(str(org_uuid))
     display_name = payload.get("display_name") or current.display_name
-    permissions = payload.get("permissions") or current.permissions or []
+    permissions = payload.get("permissions")
+    if permissions is None:
+        permissions = current.permissions or []
 
     # Sanity check: prevent removing permissions that would break current user's admin access
     org_admin_perm = f"auth:org:{org_uuid}"
@@ -172,6 +168,7 @@ async def admin_delete_org(org_uuid: UUID, request: Request, auth=AUTH_COOKIE):
         ["auth:admin", f"auth:org:{org_uuid}"],
         match=permutil.has_any,
         host=request.headers.get("host"),
+        max_age="5m",
     )
     if ctx.org.uuid == org_uuid:
         raise ValueError("Cannot delete the organization you belong to")
@@ -321,6 +318,7 @@ async def admin_delete_role(
         ["auth:admin", f"auth:org:{org_uuid}"],
         match=permutil.has_any,
         host=request.headers.get("host"),
+        max_age="5m",
     )
     role = await db.instance.get_role(role_uuid)
     if role.org_uuid != org_uuid:
@@ -402,7 +400,7 @@ async def admin_update_user_role(
     # 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:
+        if new_role_obj:  # pragma: no branch - always true, role validated above
             has_admin_access = (
                 "auth:admin" in new_role_obj.permissions
                 or f"auth:org:{org_uuid}" in new_role_obj.permissions
@@ -434,12 +432,15 @@ async def admin_create_user_registration_link(
         ["auth:admin", f"auth:org:{org_uuid}"],
         match=permutil.has_any,
         host=request.headers.get("host"),
+        max_age="5m",
     )
-    if (
+    if (  # pragma: no cover - defense in depth, authz.verify already checked
         "auth:admin" not in ctx.role.permissions
         and f"auth:org:{org_uuid}" not in ctx.role.permissions
     ):
-        raise HTTPException(status_code=403, detail="Insufficient permissions")
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
 
     # Check if user has existing credentials
     credentials = await db.instance.get_credentials_by_user_uuid(user_uuid)
@@ -453,9 +454,7 @@ async def admin_create_user_registration_link(
         expiry=expiry,
         token_type=token_type,
     )
-    url = hostutil.reset_link_url(
-        token, request.url.scheme, request.headers.get("host")
-    )
+    url = hostutil.reset_link_url(token)
     return {
         "url": url,
         "expires": (
@@ -485,11 +484,13 @@ async def admin_get_user_detail(
         match=permutil.has_any,
         host=request.headers.get("host"),
     )
-    if (
+    if (  # pragma: no cover - defense in depth, authz.verify already checked
         "auth:admin" not in ctx.role.permissions
         and f"auth:org:{org_uuid}" not in ctx.role.permissions
     ):
-        raise HTTPException(status_code=403, detail="Insufficient permissions")
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
     user = await db.instance.get_user_by_uuid(user_uuid)
     cred_ids = await db.instance.get_credentials_by_user_uuid(user_uuid)
     creds: list[dict] = []
@@ -497,7 +498,7 @@ async def admin_get_user_detail(
     for cid in cred_ids:
         try:
             c = await db.instance.get_credential_by_id(cid)
-        except ValueError:
+        except ValueError:  # pragma: no cover - race condition handling
             continue
         aaguid_str = str(c.aaguid)
         aaguids.add(aaguid_str)
@@ -632,11 +633,13 @@ async def admin_update_user_display_name(
         match=permutil.has_any,
         host=request.headers.get("host"),
     )
-    if (
+    if (  # pragma: no cover - defense in depth, authz.verify already checked
         "auth:admin" not in ctx.role.permissions
         and f"auth:org:{org_uuid}" not in ctx.role.permissions
     ):
-        raise HTTPException(status_code=403, detail="Insufficient permissions")
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
     new_name = (payload.get("display_name") or "").strip()
     if not new_name:
         raise HTTPException(status_code=400, detail="display_name required")
@@ -665,16 +668,65 @@ async def admin_delete_user_credential(
         ["auth:admin", f"auth:org:{org_uuid}"],
         match=permutil.has_any,
         host=request.headers.get("host"),
+        max_age="5m",
     )
-    if (
+    if (  # pragma: no cover - defense in depth, authz.verify already checked
         "auth:admin" not in ctx.role.permissions
         and f"auth:org:{org_uuid}" not in ctx.role.permissions
     ):
-        raise HTTPException(status_code=403, detail="Insufficient permissions")
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
     await db.instance.delete_credential(credential_uuid, user_uuid)
     return {"status": "ok"}
 
 
+@app.delete("/orgs/{org_uuid}/users/{user_uuid}/sessions/{session_id}")
+async def admin_delete_user_session(
+    org_uuid: UUID,
+    user_uuid: UUID,
+    session_id: str,
+    request: Request,
+    auth=AUTH_COOKIE,
+):
+    try:
+        user_org, _role_name = await db.instance.get_user_organization(user_uuid)
+    except ValueError:
+        raise HTTPException(status_code=404, detail="User not found")
+    if user_org.uuid != org_uuid:
+        raise HTTPException(status_code=404, detail="User not found in organization")
+    ctx = await authz.verify(
+        auth,
+        ["auth:admin", f"auth:org:{org_uuid}"],
+        match=permutil.has_any,
+        host=request.headers.get("host"),
+    )
+    if (  # pragma: no cover - defense in depth, authz.verify already checked
+        "auth:admin" not in ctx.role.permissions
+        and f"auth:org:{org_uuid}" not in ctx.role.permissions
+    ):
+        raise authz.AuthException(
+            status_code=403, detail="Insufficient permissions", mode="forbidden"
+        )
+
+    try:
+        target_key = tokens.decode_session_key(session_id)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=400, detail="Invalid session identifier"
+        ) from exc
+
+    target_session = await db.instance.get_session(target_key)
+    if not target_session or target_session.user_uuid != user_uuid:
+        raise HTTPException(status_code=404, detail="Session not found")
+
+    await db.instance.delete_session(target_key)
+
+    # Check if admin terminated their own session
+    current_terminated = target_key == session_key(auth)
+    return {"status": "ok", "current_session_terminated": current_terminated}
+
+
 # -------------------- Permissions (global) --------------------
 
 
@@ -705,7 +757,11 @@ async def admin_create_permission(
     auth=AUTH_COOKIE,
 ):
     await authz.verify(
-        auth, ["auth:admin"], host=request.headers.get("host"), match=permutil.has_all
+        auth,
+        ["auth:admin"],
+        host=request.headers.get("host"),
+        match=permutil.has_all,
+        max_age="5m",
     )
     from ..db import Permission as PermDC
 
@@ -764,7 +820,7 @@ async def admin_rename_permission(
         perm = await db.instance.get_permission(old_id)
         display_name = perm.display_name
     rename_fn = getattr(db.instance, "rename_permission", None)
-    if not rename_fn:
+    if not rename_fn:  # pragma: no cover - all current backends support rename
         raise ValueError("Permission renaming not supported by this backend")
     await rename_fn(old_id, new_id, display_name)
     return {"status": "ok"}
@@ -777,7 +833,11 @@ async def admin_delete_permission(
     auth=AUTH_COOKIE,
 ):
     await authz.verify(
-        auth, ["auth:admin"], host=request.headers.get("host"), match=permutil.has_all
+        auth,
+        ["auth:admin"],
+        host=request.headers.get("host"),
+        match=permutil.has_all,
+        max_age="5m",
     )
     querysafe.assert_safe(permission_id, field="permission_id")
 

paskia/fastapi/api.py

@@ -0,0 +1,308 @@
+import logging
+from contextlib import suppress
+from datetime import datetime, timedelta, timezone
+
+from fastapi import (
+    Depends,
+    FastAPI,
+    HTTPException,
+    Query,
+    Request,
+    Response,
+)
+from fastapi.responses import JSONResponse
+from fastapi.security import HTTPBearer
+
+from paskia.authsession import (
+    EXPIRES,
+    get_reset,
+    get_session,
+    refresh_session_token,
+    session_expiry,
+)
+from paskia.fastapi import authz, session, user
+from paskia.fastapi.session import AUTH_COOKIE, AUTH_COOKIE_NAME
+from paskia.globals import db
+from paskia.globals import passkey as global_passkey
+from paskia.util import frontend, hostutil, htmlutil, passphrase, userinfo
+from paskia.util.tokens import session_key
+
+bearer_auth = HTTPBearer(auto_error=True)
+
+app = FastAPI()
+
+app.mount("/user", user.app)
+
+
+@app.exception_handler(HTTPException)
+async def http_exception_handler(_request: Request, exc: HTTPException):
+    """Ensure auth cookie is cleared on 401 responses (JSON responses only)."""
+    if exc.status_code == 401:
+        resp = JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+        session.clear_session_cookie(resp)
+        return resp
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+
+
+# Refresh only if at least this much of the session lifetime has been *consumed*.
+# Consumption is derived from (now + EXPIRES) - current_expires.
+# This guarantees a minimum spacing between DB writes even with frequent /validate calls.
+_REFRESH_INTERVAL = timedelta(minutes=5)
+
+
+@app.exception_handler(ValueError)
+async def value_error_handler(_request: Request, exc: ValueError):
+    return JSONResponse(status_code=400, content={"detail": str(exc)})
+
+
+@app.exception_handler(authz.AuthException)
+async def auth_exception_handler(_request: Request, exc: authz.AuthException):
+    """Handle AuthException with auth info for UI."""
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=await authz.auth_error_content(exc),
+    )
+
+
+@app.exception_handler(Exception)
+async def general_exception_handler(
+    _request: Request, exc: Exception
+):  # pragma: no cover
+    logging.exception("Unhandled exception in API app")
+    return JSONResponse(status_code=500, content={"detail": "Internal server error"})
+
+
+@app.post("/validate")
+async def validate_token(
+    request: Request,
+    response: Response,
+    perm: list[str] = Query([]),
+    auth=AUTH_COOKIE,
+):
+    """Validate the current session and extend its expiry.
+
+    Always refreshes the session (sliding expiration) and re-sets the cookie with a
+    renewed max-age. This keeps active users logged in without needing a separate
+    refresh endpoint.
+    """
+    try:
+        ctx = await authz.verify(auth, perm, host=request.headers.get("host"))
+    except HTTPException:
+        # Global handler will clear cookie if 401
+        raise
+    renewed = False
+    if auth:
+        current_expiry = session_expiry(ctx.session)
+        consumed = EXPIRES - (current_expiry - datetime.now(timezone.utc))
+        if not timedelta(0) < consumed < _REFRESH_INTERVAL:
+            try:
+                await refresh_session_token(
+                    auth,
+                    ip=request.client.host if request.client else "",
+                    user_agent=request.headers.get("user-agent") or "",
+                )
+                session.set_session_cookie(response, auth)
+                renewed = True
+            except ValueError:
+                # Session disappeared, e.g. due to concurrent logout; global handler will clear
+                raise authz.AuthException(
+                    status_code=401, detail="Session expired", mode="login"
+                )
+    return {
+        "valid": True,
+        "user_uuid": str(ctx.session.user_uuid),
+        "renewed": renewed,
+    }
+
+
+@app.get("/forward")
+async def forward_authentication(
+    request: Request,
+    response: Response,
+    perm: list[str] = Query([]),
+    max_age: str | None = Query(None),
+    auth=AUTH_COOKIE,
+):
+    """Forward auth validation for Caddy/Nginx.
+
+    Query Params:
+    - perm: repeated permission IDs the authenticated user must possess (ALL required).
+    - max_age: maximum age of authentication (e.g., "5m", "1h", "30s"). If the session
+               is older than this, user must re-authenticate.
+
+    Success: 204 No Content with Remote-* headers describing the authenticated user.
+    Failure (unauthenticated / unauthorized): 4xx response.
+        - If Accept header contains "text/html": HTML page for authentication
+          with data attributes for mode and other metadata.
+        - Otherwise: JSON response with error details and an `iframe` field
+          pointing to /auth/restricted/?mode=... for iframe-based authentication.
+    """
+    try:
+        ctx = await authz.verify(
+            auth, perm, host=request.headers.get("host"), max_age=max_age
+        )
+        role_permissions = set(ctx.role.permissions or [])
+        if ctx.permissions:
+            role_permissions.update(permission.id for permission in ctx.permissions)
+
+        remote_headers: dict[str, str] = {
+            "Remote-User": str(ctx.user.uuid),
+            "Remote-Name": ctx.user.display_name,
+            "Remote-Groups": ",".join(sorted(role_permissions)),
+            "Remote-Org": str(ctx.org.uuid),
+            "Remote-Org-Name": ctx.org.display_name,
+            "Remote-Role": str(ctx.role.uuid),
+            "Remote-Role-Name": ctx.role.display_name,
+            "Remote-Session-Expires": (
+                session_expiry(ctx.session)
+                .astimezone(timezone.utc)
+                .isoformat()
+                .replace("+00:00", "Z")
+                if session_expiry(ctx.session).tzinfo
+                else session_expiry(ctx.session)
+                .replace(tzinfo=timezone.utc)
+                .isoformat()
+                .replace("+00:00", "Z")
+            ),
+            "Remote-Credential": str(ctx.session.credential_uuid),
+        }
+        return Response(status_code=204, headers=remote_headers)
+    except authz.AuthException as e:
+        # Clear cookie only if session is invalid (not for reauth)
+        if e.clear_session:
+            session.clear_session_cookie(response)
+
+        # Check Accept header to decide response format
+        accept = request.headers.get("accept", "")
+        wants_html = "text/html" in accept
+
+        if wants_html:
+            # Browser request - return full-page HTML with metadata
+            data_attrs = {"mode": e.mode, **e.metadata}
+            html = (await frontend.read("/int/forward/index.html"))[0]
+            html = htmlutil.patch_html_data_attrs(html, **data_attrs)
+            return Response(
+                html, status_code=e.status_code, media_type="text/html; charset=UTF-8"
+            )
+        else:
+            # API request - return JSON with iframe srcdoc HTML
+            return JSONResponse(
+                status_code=e.status_code,
+                content=await authz.auth_error_content(e),
+            )
+
+
+@app.get("/settings")
+async def get_settings():
+    pk = global_passkey.instance
+    base_path = hostutil.ui_base_path()
+    return {
+        "rp_id": pk.rp_id,
+        "rp_name": pk.rp_name,
+        "ui_base_path": base_path,
+        "auth_host": hostutil.dedicated_auth_host(),
+        "auth_site_url": hostutil.auth_site_url(),
+        "session_cookie": AUTH_COOKIE_NAME,
+    }
+
+
+@app.get("/token-info")
+async def api_token_info(token: str):
+    """Get information about a reset token.
+
+    Returns:
+        - type: "reset"
+        - user_name: display name of the user
+        - token_type: type of reset token
+    """
+    if not passphrase.is_well_formed(token):
+        raise HTTPException(status_code=404, detail="Invalid token")
+
+    # Check if this is a reset token
+    try:
+        reset_token = await get_reset(token)
+        user = await db.instance.get_user_by_uuid(reset_token.user_uuid)
+        return {
+            "type": "reset",
+            "user_name": user.display_name,
+            "token_type": reset_token.token_type,
+        }
+    except (ValueError, Exception):
+        raise HTTPException(status_code=404, detail="Token not found or expired")
+
+
+@app.post("/user-info")
+async def api_user_info(
+    request: Request,
+    response: Response,
+    reset: str | None = None,
+    auth=AUTH_COOKIE,
+):
+    """Get user information including credentials, sessions, and permissions.
+
+    Can be called with either:
+    - A session cookie (auth) for authenticated users
+    - A reset token for users in password reset flow
+    """
+    authenticated = False
+    session_record = None
+    reset_token = None
+    try:
+        if reset:
+            if not passphrase.is_well_formed(reset):
+                raise ValueError("Invalid reset token")
+            reset_token = await get_reset(reset)
+            target_user_uuid = reset_token.user_uuid
+        else:
+            if auth is None:
+                raise authz.AuthException(
+                    status_code=401,
+                    detail="Authentication required",
+                    mode="login",
+                )
+            session_record = await get_session(auth, host=request.headers.get("host"))
+            authenticated = True
+            target_user_uuid = session_record.user_uuid
+    except ValueError as e:
+        raise HTTPException(401, str(e))
+
+    # Return minimal response for reset tokens
+    if not authenticated and reset_token:
+        return await userinfo.format_reset_user_info(target_user_uuid, reset_token)
+
+    # Return full user info for authenticated users
+    assert auth is not None
+    assert session_record is not None
+
+    return await userinfo.format_user_info(
+        user_uuid=target_user_uuid,
+        auth=auth,
+        session_record=session_record,
+        request_host=request.headers.get("host"),
+    )
+
+
+@app.post("/logout")
+async def api_logout(request: Request, response: Response, auth=AUTH_COOKIE):
+    if not auth:
+        return {"message": "Already logged out"}
+    try:
+        await get_session(auth, host=request.headers.get("host"))
+    except ValueError:
+        return {"message": "Already logged out"}
+    with suppress(Exception):
+        await db.instance.delete_session(session_key(auth))
+    session.clear_session_cookie(response)
+    return {"message": "Logged out successfully"}
+
+
+@app.post("/set-session")
+async def api_set_session(
+    request: Request, response: Response, auth=Depends(bearer_auth)
+):
+    user = await get_session(auth.credentials, host=request.headers.get("host"))
+    session.set_session_cookie(response, auth.credentials)
+    return {
+        "message": "Session cookie set successfully",
+        "user_uuid": str(user.user_uuid),
+    }

paskia/fastapi/auth_host.py

@@ -3,7 +3,7 @@
 from fastapi import Request, Response
 from fastapi.responses import RedirectResponse
 
-from passkey.util import hostutil, passphrase
+from paskia.util import hostutil, passphrase
 
 
 def is_ui_path(path: str) -> bool:
@@ -73,7 +73,7 @@ def redirect_to_root_on_auth_host(request: Request, cur: str, path: str) -> Resp
 
 async def redirect_middleware(request: Request, call_next):
     """Middleware to handle auth host redirects."""
-    cfg = hostutil.configured_auth_host()
+    cfg = hostutil.dedicated_auth_host()
     if not cfg:
         return await call_next(request)
 

paskia/fastapi/authz.py

@@ -0,0 +1,110 @@
+import logging
+
+from fastapi import HTTPException
+
+from paskia.util import permutil, sessionutil
+
+logger = logging.getLogger(__name__)
+
+
+class AuthException(HTTPException):
+    """Exception raised during authentication/authorization with metadata for the UI.
+
+    Attributes:
+        status_code: HTTP status code (401 for auth, 403 for authz)
+        detail: Error message
+        mode: UI mode ('login' or 'reauth')
+        clear_session: Whether to clear the session cookie (True for invalid sessions)
+        metadata: Additional data to pass to the frontend
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        detail: str,
+        mode: str,
+        clear_session: bool = False,
+        **metadata,
+    ):
+        super().__init__(status_code=status_code, detail=detail)
+        self.mode = mode
+        self.clear_session = clear_session
+        self.metadata = metadata
+
+
+async def auth_error_content(exc: AuthException) -> dict:
+    """Generate JSON response content for an AuthException.
+
+    Returns a dict with detail, mode, and iframe URL for src embedding.
+    """
+    # Build hash fragment from mode and metadata
+    params = {"mode": exc.mode, **exc.metadata}
+    fragment = "&".join(f"{k}={v}" for k, v in params.items() if v is not None)
+    iframe_url = f"/auth/restricted/#{fragment}"
+    return {
+        "detail": exc.detail,
+        "auth": {
+            "mode": exc.mode,
+            "iframe": iframe_url,
+            **exc.metadata,
+        },
+    }
+
+
+async def verify(
+    auth: str | None,
+    perm: list[str],
+    match=permutil.has_all,
+    host: str | None = None,
+    max_age: str | None = None,
+):
+    """Validate session token and optional list of required permissions.
+
+    Returns the session context.
+
+    Raises AuthException on failure with metadata for UI rendering.
+    """
+    if not auth:
+        raise AuthException(
+            status_code=401,
+            detail="Authentication required",
+            mode="login",
+        )
+
+    ctx = await permutil.session_context(auth, host)
+    if not ctx:
+        raise AuthException(
+            status_code=401,
+            detail="Your session has expired. Please sign in again.",
+            mode="login",
+            clear_session=True,
+        )
+    # Check max_age requirement if specified
+    if max_age:
+        try:
+            if not sessionutil.check_session_age(ctx, max_age):
+                raise AuthException(
+                    status_code=401,
+                    detail="Additional authentication required",
+                    mode="reauth",
+                )
+        except ValueError as e:
+            # Invalid max_age format - log but don't fail the request
+            logger.warning(f"Invalid max_age format '{max_age}': {e}")
+
+    if not match(ctx, perm):
+        # Determine which permissions are missing for clearer diagnostics
+        missing = sorted(set(perm) - set(ctx.role.permissions))
+        logger.warning(
+            "Permission denied: user=%s role=%s missing=%s required=%s granted=%s",  # noqa: E501
+            getattr(ctx.user, "uuid", "?"),
+            getattr(ctx.role, "display_name", "?"),
+            missing,
+            perm,
+            ctx.role.permissions,
+        )
+        raise AuthException(
+            status_code=403, mode="forbidden", detail="Permission required"
+        )
+
+    return ctx

paskia/fastapi/mainapp.py

@@ -0,0 +1,130 @@
+import logging
+import os
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException, Request, Response
+from fastapi.responses import FileResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
+
+from paskia.fastapi import admin, api, auth_host, ws
+from paskia.fastapi.session import AUTH_COOKIE
+from paskia.util import frontend, hostutil, passphrase
+
+# Path to examples/index.html when running from source tree
+_EXAMPLES_DIR = Path(__file__).parent.parent.parent / "examples"
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):  # pragma: no cover - startup path
+    """Application lifespan to ensure globals (DB, passkey) are initialized in each process.
+
+    Configuration is passed via PASKIA_CONFIG JSON env variable (set by the CLI entrypoint)
+    so that uvicorn reload / multiprocess workers inherit the settings.
+    All keys are guaranteed to exist; values are already normalized by __main__.py.
+    """
+    import json
+
+    from paskia import globals
+
+    config = json.loads(os.environ["PASKIA_CONFIG"])
+
+    try:
+        # CLI (__main__) performs bootstrap once; here we skip to avoid duplicate work
+        await globals.init(
+            rp_id=config["rp_id"],
+            rp_name=config["rp_name"],
+            origins=config["origins"],
+            bootstrap=False,
+        )
+    except ValueError as e:
+        logging.error(f"⚠️ {e}")
+        # Re-raise to fail fast
+        raise
+
+    # Restore info level logging after startup (suppressed during uvicorn init in dev mode)
+    if frontend.is_dev_mode():
+        logging.getLogger("uvicorn").setLevel(logging.INFO)
+        logging.getLogger("uvicorn.access").setLevel(logging.INFO)
+
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+# Apply redirections to auth-host if configured (deny access to restricted endpoints, remove /auth/)
+app.middleware("http")(auth_host.redirect_middleware)
+
+app.mount("/auth/api/admin/", admin.app)
+app.mount("/auth/api/", api.app)
+app.mount("/auth/ws/", ws.app)
+
+# In dev mode (PASKIA_DEVMODE=1), Vite serves assets directly; skip static files mount
+if not frontend.is_dev_mode():
+    app.mount(
+        "/auth/assets/",
+        StaticFiles(directory=frontend.file("auth", "assets")),
+        name="assets",
+    )
+
+
+@app.get("/auth/restricted/")
+async def restricted_view():
+    """Serve the restricted/authentication UI for iframe embedding."""
+    return Response(*await frontend.read("/auth/restricted/index.html"))
+
+
+# Navigable URLs are defined here. We support both / and /auth/ as the base path
+# / is used on a dedicated auth site, /auth/ on app domains with auth
+
+
+@app.get("/")
+@app.get("/auth/")
+async def frontapp(request: Request, response: Response, auth=AUTH_COOKIE):
+    """Serve the user profile app.
+
+    The frontend handles mode detection (host mode vs full profile) based on settings.
+    Access control is handled via APIs.
+    """
+    return Response(*await frontend.read("/auth/index.html"))
+
+
+@app.get("/admin", include_in_schema=False)
+@app.get("/auth/admin", include_in_schema=False)
+async def admin_root_redirect():
+    return RedirectResponse(f"{hostutil.ui_base_path()}admin/", status_code=307)
+
+
+@app.get("/admin/", include_in_schema=False)
+async def admin_root(request: Request, auth=AUTH_COOKIE):
+    return await admin.adminapp(request, auth)  # Delegated to admin app
+
+
+@app.get("/auth/examples/", include_in_schema=False)
+async def examples_page():
+    """Serve examples/index.html when running from source tree.
+
+    This provides a simple test page for API mode authentication flows
+    without depending on the Vue frontend build.
+    """
+    index_file = _EXAMPLES_DIR / "index.html"
+    if not index_file.is_file():
+        raise HTTPException(
+            status_code=404,
+            detail="Examples not available (not running from source tree)",
+        )
+    return FileResponse(index_file, media_type="text/html")
+
+
+# Note: this catch-all handler must be the last route defined
+@app.get("/{token}")
+@app.get("/auth/{token}")
+async def token_link(token: str):
+    """Serve the reset app for reset tokens (password reset / device addition).
+
+    The frontend will validate the token via /auth/api/token-info.
+    """
+    if not passphrase.is_well_formed(token):
+        raise HTTPException(status_code=404)
+
+    return Response(*await frontend.read("/int/reset/index.html"))

paskia/fastapi/remote.py

@@ -0,0 +1,504 @@
+"""
+Remote authentication WebSocket endpoints.
+
+This module handles cross-device authentication where one device (requesting)
+wants to log in and another device (authenticating) provides the passkey.
+
+Endpoints:
+- /request: Called by the device wanting to be authenticated
+- /pair: Called by the authenticating device to complete the request
+"""
+
+import asyncio
+from uuid import UUID
+
+import base64url
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+
+from paskia import remoteauth
+from paskia.authsession import create_session
+from paskia.fastapi.session import infodict
+from paskia.fastapi.wsutil import validate_origin, websocket_error_handler
+from paskia.globals import db, passkey
+from paskia.util import passphrase, pow
+
+# Create a FastAPI subapp for remote auth WebSocket endpoints
+app = FastAPI()
+
+
+@app.websocket("/request")
+@websocket_error_handler
+async def websocket_remote_auth_request(ws: WebSocket):
+    """Request authentication from another device.
+
+    This endpoint is called by the device that wants to be authenticated.
+    It creates a remote auth request and waits for another device to authenticate.
+
+    Flow:
+    1. Client connects
+    2. Server sends HARD PoW challenge, client solves and responds
+    3. Server creates a 3-word pairing code and sends it with expiry
+    4. Server waits for another device to authenticate via /remote-auth/pair
+    5. When auth completes, server sends session_token to this client
+    6. Client can then use the session token to set a cookie
+    7. Connection times out after 5 minutes with explicit timeout message
+    """
+    origin = validate_origin(ws)
+    host = origin.split("://", 1)[1]
+
+    if remoteauth.instance is None:
+        raise ValueError("Remote authentication is not available")
+
+    # Track this WebSocket connection for load-based PoW difficulty
+    remoteauth.instance.increment_connections()
+    try:
+        # Send PoW challenge immediately with dynamic difficulty based on load
+        challenge = pow.generate_challenge()
+        work = remoteauth.instance.get_pow_difficulty()
+
+        await ws.send_json(
+            {
+                "pow": {
+                    "challenge": base64url.enc(challenge),
+                    "work": work,
+                }
+            }
+        )
+
+        # Receive client response with PoW solution and action
+        response = await ws.receive_json()
+
+        # Verify PoW (required for this endpoint - SECURITY)
+        solution_b64 = response.get("pow")
+        if not solution_b64:
+            raise ValueError("PoW solution required")
+
+        try:
+            solution = base64url.dec(solution_b64)
+        except Exception:
+            raise ValueError("Invalid PoW solution encoding")
+
+        pow.verify_pow(challenge, solution, work)
+
+        # Extract action from the same message
+        action = response.get("action", "login")
+        if action not in ("login", "register"):
+            action = "login"
+
+        metadata = infodict(ws, "remote-auth-request")
+
+        # Create the remote auth request
+        pairing_code, expiry = await remoteauth.instance.create_request(
+            host=host,
+            ip=metadata.get("ip") or "",
+            user_agent=metadata.get("user_agent") or "",
+            action=action,
+        )
+
+        # Send the pairing code to the client
+        await ws.send_json(
+            {
+                "pairing_code": pairing_code,
+                "expires": expiry.isoformat().replace("+00:00", "Z"),
+            }
+        )
+
+        # Set up async notification for completion
+        result_event = asyncio.Event()
+        result_data: dict = {}
+
+        def on_complete(
+            session_token: str | None,
+            user_uuid: UUID | None,
+            credential_uuid: UUID | None,
+            reset_token: str | None,
+        ):
+            # Check if this was an explicit denial (UUID(int=0) is the signal)
+            was_denied = user_uuid is not None and user_uuid == UUID(int=0)
+            result_data["session_token"] = session_token
+            result_data["user_uuid"] = user_uuid
+            result_data["credential_uuid"] = credential_uuid
+            result_data["reset_token"] = reset_token
+            result_data["was_denied"] = was_denied
+            result_event.set()
+
+        await remoteauth.instance.set_notify_callback(pairing_code, on_complete)
+
+        # Set up async notification for action lock
+        locked_event = asyncio.Event()
+        locked_data: dict = {}
+
+        def on_action_locked(action: str):
+            locked_data["action"] = action
+            locked_event.set()
+
+        await remoteauth.instance.set_action_locked_callback(
+            pairing_code, on_action_locked
+        )
+
+        # 5 minute timeout for the entire remote auth flow
+        timeout_seconds = 5 * 60
+
+        try:
+            # Wait for either:
+            # 1. Authentication to complete (result_event set)
+            # 2. Action locked (locked_event set)
+            # 3. Client to disconnect
+            # 4. Client to send a cancel or update_action message
+            # 5. Timeout after 5 minutes
+
+            async with asyncio.timeout(timeout_seconds):
+                while True:
+                    # Use asyncio.wait to handle events and websocket
+                    receive_task = asyncio.create_task(ws.receive_json())
+                    result_wait_task = asyncio.create_task(result_event.wait())
+                    locked_wait_task = asyncio.create_task(locked_event.wait())
+
+                    tasks = [receive_task, result_wait_task]
+                    # Only wait for locked event if not already locked
+                    if not locked_event.is_set():
+                        tasks.append(locked_wait_task)
+
+                    done, pending = await asyncio.wait(
+                        tasks,
+                        return_when=asyncio.FIRST_COMPLETED,
+                    )
+
+                    # Cancel pending tasks
+                    for task in pending:
+                        task.cancel()
+                        try:
+                            await task
+                        except asyncio.CancelledError:
+                            pass
+
+                    if result_wait_task in done:
+                        # Authentication completed (or expired/cancelled/denied)
+                        was_denied = result_data.get("was_denied", False)
+                        if result_data.get("session_token") or result_data.get(
+                            "reset_token"
+                        ):
+                            response = {
+                                "status": "authenticated",
+                                "user_uuid": str(result_data["user_uuid"]),
+                            }
+                            if result_data.get("session_token"):
+                                response["session_token"] = result_data["session_token"]
+                            if result_data.get("reset_token"):
+                                response["reset_token"] = result_data["reset_token"]
+                            await ws.send_json(response)
+                        else:
+                            # Check if it was explicitly denied
+                            if was_denied:
+                                await ws.send_json(
+                                    {
+                                        "status": "denied",
+                                        "detail": "Access denied",
+                                    }
+                                )
+                            else:
+                                await ws.send_json(
+                                    {
+                                        "status": "expired",
+                                        "detail": "Remote authentication request expired or was cancelled",
+                                    }
+                                )
+                        return
+
+                    if locked_wait_task in done:
+                        # Action was locked by the authenticating device
+                        await ws.send_json(
+                            {
+                                "status": "locked",
+                                "action": locked_data.get("action", "login"),
+                            }
+                        )
+                        # Continue waiting for result
+
+                    if receive_task in done:
+                        # Client sent a message
+                        msg = receive_task.result()
+                        if msg.get("action") == "cancel":
+                            await remoteauth.instance.cancel_request(pairing_code)
+                            await ws.send_json({"status": "cancelled"})
+                            return
+                        elif msg.get("action") == "update_action":
+                            # Update the action (login/register) if not locked
+                            new_action = "register" if msg.get("register") else "login"
+                            await remoteauth.instance.update_action(
+                                pairing_code, new_action
+                            )
+                        # Ignore other messages
+
+        except TimeoutError:
+            # 5 minute timeout reached
+            await remoteauth.instance.cancel_request(pairing_code)
+            await ws.send_json(
+                {
+                    "status": "timeout",
+                    "detail": "Remote authentication request timed out after 5 minutes",
+                }
+            )
+        except WebSocketDisconnect:
+            # Client disconnected, cancel the request and mark as denied
+            await remoteauth.instance.cancel_request(pairing_code, denied=True)
+        except Exception:
+            await remoteauth.instance.cancel_request(pairing_code)
+            raise
+    finally:
+        # Decrement connection count
+        remoteauth.instance.decrement_connections()
+
+
+@app.websocket("/pair")
+@websocket_error_handler
+async def websocket_remote_auth_pair(ws: WebSocket):
+    """Complete a remote authentication request using a 3-word pairing code.
+
+    This endpoint is called from the user's profile on the authenticating device.
+    The user enters the pairing code displayed on the requesting device.
+
+    Protocol:
+    1. Server sends PoW challenge immediately on connect
+    2. Client sends {code: "word.word.word", pow: "<base64>"} for 3-word pairing code
+    3. Server validates PoW and code:
+       - If invalid code/PoW: {status: 4xx, detail: "...", pow: {challenge, work}}
+       - If valid: {status: "found", host: "...", user_agent_pretty: "...", pow: {challenge, work}}
+    4. Client can then send {authenticate: true} to start WebAuthn
+    5. Server sends {optionsJSON: ...}
+    6. Client sends WebAuthn response
+    7. Server sends {status: "success", message: "..."}
+    """
+    from paskia.util import useragent
+
+    origin = validate_origin(ws)
+
+    if remoteauth.instance is None:
+        raise ValueError("Remote authentication is not available")
+
+    # Generate initial PoW challenge (always NORMAL for authenticated users)
+    challenge = pow.generate_challenge()
+    work = pow.NORMAL
+
+    await ws.send_json(
+        {
+            "pow": {
+                "challenge": base64url.enc(challenge),
+                "work": work,
+            }
+        }
+    )
+
+    request = None
+    webauthn_challenge = None
+    explicitly_denied = False
+
+    try:
+        while True:
+            msg = await ws.receive_json()
+
+            # Handle deny request first (no PoW needed - already validated during lookup)
+            if msg.get("deny") and request is not None:
+                # Cancel the request and mark it as denied
+                explicitly_denied = True
+                await remoteauth.instance.cancel_request(request.key, denied=True)
+                await ws.send_json(
+                    {
+                        "status": "denied",
+                        "message": "Request denied",
+                    }
+                )
+                break
+
+            # Handle authenticate request (no PoW needed - already validated during lookup)
+            if msg.get("authenticate") and request is not None:
+                # Generate authentication options
+                options, webauthn_challenge = passkey.instance.auth_generate_options(
+                    credential_ids=None
+                )
+                await ws.send_json({"optionsJSON": options})
+
+                # Wait for WebAuthn response
+                credential = passkey.instance.auth_parse(await ws.receive_json())
+
+                # Fetch and verify credential
+                try:
+                    stored_cred = await db.instance.get_credential_by_id(
+                        credential.raw_id
+                    )
+                except ValueError:
+                    raise ValueError(
+                        f"This passkey is no longer registered with {passkey.instance.rp_name}"
+                    )
+
+                # Verify the credential
+                passkey.instance.auth_verify(
+                    credential, webauthn_challenge, stored_cred, origin
+                )
+
+                # Update credential last_used
+                await db.instance.login(stored_cred.user_uuid, stored_cred)
+
+                # Create a session for the REQUESTING device
+                assert stored_cred.uuid is not None
+
+                session_token = None
+                reset_token = None
+
+                if request.action == "register":
+                    # For registration, create a reset token for device addition
+                    from paskia.authsession import expires
+                    from paskia.util import tokens
+
+                    token_str = passphrase.generate()
+                    expiry = expires()
+                    await db.instance.create_reset_token(
+                        user_uuid=stored_cred.user_uuid,
+                        key=tokens.reset_key(token_str),
+                        expiry=expiry,
+                        token_type="device addition",
+                    )
+                    reset_token = token_str
+                    # Also create a session so the device is logged in?
+                    # User requested: "We can make the flow always create a new session, but make additional tokens for other possibilities."
+                    session_token = await create_session(
+                        user_uuid=stored_cred.user_uuid,
+                        credential_uuid=stored_cred.uuid,
+                        host=request.host,
+                        ip=request.ip,
+                        user_agent=request.user_agent,
+                    )
+                else:
+                    # Default login action
+                    session_token = await create_session(
+                        user_uuid=stored_cred.user_uuid,
+                        credential_uuid=stored_cred.uuid,
+                        host=request.host,
+                        ip=request.ip,
+                        user_agent=request.user_agent,
+                    )
+
+                # Complete the remote auth request (notifies the waiting device)
+                completed = await remoteauth.instance.complete_request(
+                    token=request.key,
+                    session_token=session_token,
+                    user_uuid=stored_cred.user_uuid,
+                    credential_uuid=stored_cred.uuid,
+                    reset_token=reset_token,
+                )
+
+                if not completed:
+                    raise ValueError("Failed to complete remote authentication")
+
+                msg = "Authentication successful."
+                if request.action == "register":
+                    msg += " The other device can now register a passkey."
+                else:
+                    msg += " The other device is now logged in."
+
+                await ws.send_json(
+                    {
+                        "status": "success",
+                        "message": msg,
+                    }
+                )
+                break
+
+            # Handle code lookup request - requires PoW validation
+            code = msg.get("code", "")
+
+            # Validate PoW for pairing codes
+            solution_b64 = msg.get("pow")
+            if not solution_b64:
+                raise ValueError("PoW solution required")
+
+            try:
+                solution = base64url.dec(solution_b64)
+            except Exception:
+                raise ValueError("Invalid PoW solution encoding")
+
+            try:
+                pow.verify_pow(challenge, solution, work)
+            except ValueError as e:
+                # Invalid PoW - send new challenge
+                challenge = pow.generate_challenge()
+                await ws.send_json(
+                    {
+                        "status": 400,
+                        "detail": str(e),
+                        "pow": {
+                            "challenge": base64url.enc(challenge),
+                            "work": work,
+                        },
+                    }
+                )
+                continue
+
+            if not code:
+                raise ValueError("Pairing code required")
+
+            # Look up the remote auth request by pairing code
+            request = await remoteauth.instance.get_request(code)
+
+            # Generate new challenge for next request (always NORMAL for authenticated users)
+            challenge = pow.generate_challenge()
+
+            if request is None:
+                await ws.send_json(
+                    {
+                        "status": 404,
+                        "detail": "Code not found",
+                        "pow": {
+                            "challenge": base64url.enc(challenge),
+                            "work": work,
+                        },
+                    }
+                )
+                request = None  # Reset for next attempt
+                continue
+
+            # Valid code found - lock the action so it can't be changed anymore
+            # This also notifies the requesting device
+            locked_action = await remoteauth.instance.lock_action(request.key)
+            if locked_action is None:
+                # Already locked by another device
+                await ws.send_json(
+                    {
+                        "status": 409,
+                        "detail": "This request is already being processed in another window",
+                        "pow": {
+                            "challenge": base64url.enc(challenge),
+                            "work": work,
+                        },
+                    }
+                )
+                request = None  # Reset for next attempt
+                continue
+
+            request.action = locked_action  # Update local copy with locked value
+
+            # Send device info to the authenticating device
+            await ws.send_json(
+                {
+                    "status": "found",
+                    "host": request.host,
+                    "user_agent_pretty": useragent.compact_user_agent(
+                        request.user_agent
+                    ),
+                    "client_ip": request.ip,
+                    "action": request.action,
+                    "pow": {
+                        "challenge": base64url.enc(challenge),
+                        "work": work,
+                    },
+                }
+            )
+    except Exception:
+        # If websocket disconnects without explicit denial, unlock the request
+        if request and not explicitly_denied:
+            # Unlock the request so the code can be used again
+            async with remoteauth.instance._lock:
+                req = remoteauth.instance._requests.get(request.key)
+                if req and req.locked:
+                    req.locked = False
+        raise

paskia/fastapi/reset.py

@@ -1,7 +1,7 @@
 """CLI support for creating user credential reset links.
 
 Usage (via main CLI):
-    passkey-auth reset [query]
+    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
@@ -15,10 +15,10 @@ from __future__ import annotations
 import asyncio
 from uuid import UUID
 
-from passkey import authsession as _authsession
-from passkey import globals as _g
-from passkey.util import hostutil, passphrase
-from passkey.util import tokens as _tokens
+from paskia import authsession as _authsession
+from paskia import globals as _g
+from paskia.util import hostutil, passphrase
+from paskia.util import tokens as _tokens
 
 
 async def _resolve_targets(query: str | None):

paskia/fastapi/session.py

@@ -10,9 +10,9 @@ Generic session management functions have been moved to authsession.py
 
 from fastapi import Cookie, Request, Response, WebSocket
 
-from ..authsession import EXPIRES
+from paskia.authsession import EXPIRES
 
-AUTH_COOKIE_NAME = "__Host-auth"
+AUTH_COOKIE_NAME = "__Host-paskia"
 AUTH_COOKIE = Cookie(None, alias=AUTH_COOKIE_NAME)
 
 

paskia/fastapi/user.py

@@ -8,21 +8,31 @@ from fastapi import (
     Request,
     Response,
 )
+from fastapi.responses import JSONResponse
 
-from ..authsession import (
+from paskia.authsession import (
     delete_credential,
     expires,
     get_session,
 )
-from ..globals import db
-from ..util import hostutil, passphrase, tokens
-from ..util.tokens import decode_session_key, session_key
-from . import session
-from .session import AUTH_COOKIE
+from paskia.fastapi import authz, session
+from paskia.fastapi.session import AUTH_COOKIE
+from paskia.globals import db
+from paskia.util import hostutil, passphrase, tokens
+from paskia.util.tokens import decode_session_key, session_key
 
 app = FastAPI()
 
 
+@app.exception_handler(authz.AuthException)
+async def auth_exception_handler(_request, exc: authz.AuthException):
+    """Handle AuthException with auth info for UI."""
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=await authz.auth_error_content(exc),
+    )
+
+
 @app.put("/display-name")
 async def user_update_display_name(
     request: Request,
@@ -31,11 +41,15 @@ async def user_update_display_name(
     auth=AUTH_COOKIE,
 ):
     if not auth:
-        raise HTTPException(status_code=401, detail="Authentication Required")
+        raise authz.AuthException(
+            status_code=401, detail="Authentication Required", mode="login"
+        )
     try:
         s = await get_session(auth, host=request.headers.get("host"))
     except ValueError as e:
-        raise HTTPException(status_code=401, detail="Session expired") from e
+        raise authz.AuthException(
+            status_code=401, detail="Session expired", mode="login"
+        ) from e
     new_name = (payload.get("display_name") or "").strip()
     if not new_name:
         raise HTTPException(status_code=400, detail="display_name required")
@@ -52,7 +66,9 @@ async def api_logout_all(request: Request, response: Response, auth=AUTH_COOKIE)
     try:
         s = await get_session(auth, host=request.headers.get("host"))
     except ValueError:
-        raise HTTPException(status_code=401, detail="Session expired")
+        raise authz.AuthException(
+            status_code=401, detail="Session expired", mode="login"
+        )
     await db.instance.delete_sessions_for_user(s.user_uuid)
     session.clear_session_cookie(response)
     return {"message": "Logged out from all hosts"}
@@ -66,11 +82,15 @@ async def api_delete_session(
     auth=AUTH_COOKIE,
 ):
     if not auth:
-        raise HTTPException(status_code=401, detail="Authentication Required")
+        raise authz.AuthException(
+            status_code=401, detail="Authentication Required", mode="login"
+        )
     try:
         current_session = await get_session(auth, host=request.headers.get("host"))
     except ValueError as exc:
-        raise HTTPException(status_code=401, detail="Session expired") from exc
+        raise authz.AuthException(
+            status_code=401, detail="Session expired", mode="login"
+        ) from exc
 
     try:
         target_key = decode_session_key(session_id)
@@ -97,10 +117,14 @@ async def api_delete_credential(
     uuid: UUID,
     auth: str = AUTH_COOKIE,
 ):
+    # Require recent authentication for sensitive operation
+    await authz.verify(auth, [], host=request.headers.get("host"), max_age="5m")
     try:
         await delete_credential(uuid, auth, host=request.headers.get("host"))
     except ValueError as e:
-        raise HTTPException(status_code=401, detail="Session expired") from e
+        raise authz.AuthException(
+            status_code=401, detail="Session expired", mode="login"
+        ) from e
     return {"message": "Credential deleted successfully"}
 
 
@@ -110,10 +134,14 @@ async def api_create_link(
     response: Response,
     auth=AUTH_COOKIE,
 ):
+    # Require recent authentication for sensitive operation
+    await authz.verify(auth, [], host=request.headers.get("host"), max_age="5m")
     try:
         s = await get_session(auth, host=request.headers.get("host"))
     except ValueError as e:
-        raise HTTPException(status_code=401, detail="Session expired") from e
+        raise authz.AuthException(
+            status_code=401, detail="Session expired", mode="login"
+        ) from e
     token = passphrase.generate()
     expiry = expires()
     await db.instance.create_reset_token(
@@ -122,9 +150,7 @@ async def api_create_link(
         expiry=expiry,
         token_type="device addition",
     )
-    url = hostutil.reset_link_url(
-        token, request.url.scheme, request.headers.get("host")
-    )
+    url = hostutil.reset_link_url(token)
     return {
         "message": "Registration link generated successfully",
         "url": url,

paskia/fastapi/ws.py

@@ -1,34 +1,14 @@
-import logging
-from functools import wraps
 from uuid import UUID
 
-from fastapi import FastAPI, WebSocket, WebSocketDisconnect
-from webauthn.helpers.exceptions import InvalidAuthenticationResponse
-
-from ..authsession import create_session, get_reset, get_session
-from ..globals import db, passkey
-from ..util import passphrase
-from ..util.tokens import create_token, session_key
-from .session import AUTH_COOKIE, infodict
-
-
-# WebSocket error handling decorator
-def websocket_error_handler(func):
-    @wraps(func)
-    async def wrapper(ws: WebSocket, *args, **kwargs):
-        try:
-            await ws.accept()
-            return await func(ws, *args, **kwargs)
-        except WebSocketDisconnect:
-            pass
-        except (ValueError, InvalidAuthenticationResponse) as e:
-            await ws.send_json({"detail": str(e)})
-        except Exception:
-            logging.exception("Internal Server Error")
-            await ws.send_json({"detail": "Internal Server Error"})
-
-    return wrapper
+from fastapi import FastAPI, WebSocket
 
+from paskia.authsession import create_session, get_reset, get_session
+from paskia.fastapi import authz
+from paskia.fastapi.session import AUTH_COOKIE, infodict
+from paskia.fastapi.wsutil import validate_origin, websocket_error_handler
+from paskia.globals import db, passkey
+from paskia.util import passphrase
+from paskia.util.tokens import create_token, session_key
 
 # Create a FastAPI subapp for WebSocket endpoints
 app = FastAPI()
@@ -38,17 +18,16 @@ async def register_chat(
     ws: WebSocket,
     user_uuid: UUID,
     user_name: str,
+    origin: str,
     credential_ids: list[bytes] | None = None,
-    origin: str | None = None,
 ):
     """Generate registration options and send them to the client."""
     options, challenge = passkey.instance.reg_generate_options(
         user_id=user_uuid,
         user_name=user_name,
         credential_ids=credential_ids,
-        origin=origin,
     )
-    await ws.send_json(options)
+    await ws.send_json({"optionsJSON": options})
     response = await ws.receive_json()
     return passkey.instance.reg_verify(response, challenge, user_uuid, origin=origin)
 
@@ -64,20 +43,23 @@ async def websocket_register_add(
     """Register a new credential for an existing user.
 
     Supports either:
-    - Normal session via auth cookie
+    - Normal session via auth cookie (requires recent authentication)
     - Reset token supplied as ?reset=... (auth cookie ignored)
     """
-    origin = ws.headers["origin"]
+    origin = validate_origin(ws)
     host = origin.split("://", 1)[1]
     if reset is not None:
         if not passphrase.is_well_formed(reset):
-            raise ValueError("Invalid reset token")
+            raise ValueError(
+                f"The reset link for {passkey.instance.rp_name} is invalid or has expired"
+            )
         s = await get_reset(reset)
+        user_uuid = s.user_uuid
     else:
-        if not auth:
-            raise ValueError("Authentication Required")
-        s = await get_session(auth, host=host)
-    user_uuid = s.user_uuid
+        # Require recent authentication for adding a new passkey
+        ctx = await authz.verify(auth, perm=[], host=host, max_age="5m")
+        user_uuid = ctx.session.user_uuid
+        s = ctx.session
 
     # Get user information and determine effective user_name for this registration
     user = await db.instance.get_user_by_uuid(user_uuid)
@@ -89,7 +71,7 @@ async def websocket_register_add(
     challenge_ids = await db.instance.get_credentials_by_user_uuid(user_uuid)
 
     # WebAuthn registration
-    credential = await register_chat(ws, user_uuid, user_name, challenge_ids, origin)
+    credential = await register_chat(ws, user_uuid, user_name, origin, challenge_ids)
 
     # Create a new session and store everything in database
     token = create_token()
@@ -119,17 +101,43 @@ async def websocket_register_add(
 
 @app.websocket("/authenticate")
 @websocket_error_handler
-async def websocket_authenticate(ws: WebSocket):
-    origin = ws.headers["origin"]
+async def websocket_authenticate(ws: WebSocket, auth=AUTH_COOKIE):
+    origin = validate_origin(ws)
     host = origin.split("://", 1)[1]
-    options, challenge = passkey.instance.auth_generate_options()
-    await ws.send_json(options)
+
+    # If there's an existing session, restrict to that user's credentials (reauth)
+    session_user_uuid = None
+    credential_ids = None
+    if auth:
+        try:
+            session = await get_session(auth, host=host)
+            session_user_uuid = session.user_uuid
+            credential_ids = await db.instance.get_credentials_by_user_uuid(
+                session_user_uuid
+            )
+        except ValueError:
+            pass  # Invalid/expired session - allow normal authentication
+
+    options, challenge = passkey.instance.auth_generate_options(
+        credential_ids=credential_ids
+    )
+    await ws.send_json({"optionsJSON": options})
     # Wait for the client to use his authenticator to authenticate
     credential = passkey.instance.auth_parse(await ws.receive_json())
     # Fetch from the database by credential ID
-    stored_cred = await db.instance.get_credential_by_id(credential.raw_id)
+    try:
+        stored_cred = await db.instance.get_credential_by_id(credential.raw_id)
+    except ValueError:
+        raise ValueError(
+            f"This passkey is no longer registered with {passkey.instance.rp_name}"
+        )
+
+    # If reauth mode, verify the credential belongs to the session's user
+    if session_user_uuid and stored_cred.user_uuid != session_user_uuid:
+        raise ValueError("This passkey belongs to a different account")
+
     # Verify the credential matches the stored data
-    passkey.instance.auth_verify(credential, challenge, stored_cred, origin=origin)
+    passkey.instance.auth_verify(credential, challenge, stored_cred, origin)
     # Update both credential and user's last_seen timestamp
     await db.instance.login(stored_cred.user_uuid, stored_cred)
 

paskia/fastapi/wsutil.py

@@ -0,0 +1,91 @@
+"""
+Shared WebSocket utilities for FastAPI endpoints.
+"""
+
+import logging
+from functools import wraps
+
+import base64url
+from fastapi import WebSocket, WebSocketDisconnect
+from webauthn.helpers.exceptions import InvalidAuthenticationResponse
+
+from paskia.fastapi import authz
+from paskia.globals import passkey
+from paskia.util import pow
+
+
+def websocket_error_handler(func):
+    """Decorator for WebSocket endpoints that handles common errors."""
+
+    @wraps(func)
+    async def wrapper(ws: WebSocket, *args, **kwargs):
+        try:
+            await ws.accept()
+            return await func(ws, *args, **kwargs)
+        except WebSocketDisconnect:
+            pass
+        except authz.AuthException as e:
+            await ws.send_json(
+                {
+                    "status": e.status_code,
+                    **(await authz.auth_error_content(e)),
+                }
+            )
+        except (ValueError, InvalidAuthenticationResponse) as e:
+            await ws.send_json({"status": 401, "detail": str(e)})
+        except Exception:
+            logging.exception("Internal Server Error")
+            await ws.send_json({"status": 500, "detail": "Internal Server Error"})
+
+    return wrapper
+
+
+async def require_pow(ws: WebSocket, work: int | None = None) -> None:
+    """Send a PoW challenge and verify the client's solution.
+
+    Sends: {"pow": {"challenge": "<base64>", "work": 10}}
+    Expects: {"pow": "<base64-solution>"}
+
+    Args:
+        ws: WebSocket connection
+        work: PoW difficulty level (default: pow.DEFAULT_WORK)
+
+    Raises:
+        ValueError: If the PoW solution is invalid
+    """
+    challenge = pow.generate_challenge()
+    if work is None:
+        work = pow.DEFAULT_WORK
+
+    await ws.send_json(
+        {
+            "pow": {
+                "challenge": base64url.enc(challenge),
+                "work": work,
+            }
+        }
+    )
+
+    response = await ws.receive_json()
+    solution_b64 = response.get("pow")
+    if not solution_b64:
+        raise ValueError("PoW solution required")
+
+    try:
+        solution = base64url.dec(solution_b64)
+    except Exception:
+        raise ValueError("Invalid PoW solution encoding")
+
+    pow.verify_pow(challenge, solution, work)
+
+
+def validate_origin(ws: WebSocket) -> str:
+    """Extract and validate origin from WebSocket request headers.
+
+    Raises:
+        ValueError: If origin header is missing or not in allowed list
+    """
+    origin = ws.headers.get("origin")
+    if not origin:
+        raise ValueError("Origin header is required for WebSocket connections")
+    return passkey.instance.validate_origin(origin)

paskia/globals.py

@@ -1,7 +1,7 @@
 from typing import Generic, TypeVar
 
-from .db import DatabaseInterface
-from .sansio import Passkey
+from paskia.db import DatabaseInterface
+from paskia.sansio import Passkey
 
 T = TypeVar("T")
 
@@ -29,9 +29,7 @@ class Manager(Generic[T]):
 async def init(
     rp_id: str = "localhost",
     rp_name: str | None = None,
-    origin: str | None = None,
-    default_admin: str | None = None,
-    default_org: str | None = None,
+    origins: list[str] | None = None,
     *,
     bootstrap: bool = True,
 ) -> None:
@@ -45,7 +43,7 @@ async def init(
     passkey.instance = Passkey(
         rp_id=rp_id,
         rp_name=rp_name or rp_id,
-        origin=origin,
+        origins=origins,
     )
 
     # Test if we have a database already initialized, otherwise use SQL
@@ -60,7 +58,7 @@ async def init(
         # Bootstrap system if needed
         from .bootstrap import bootstrap_if_needed
 
-        await bootstrap_if_needed(default_admin, default_org)
+        await bootstrap_if_needed()
 
 
 # Global instances

paskia/remoteauth.py

@@ -0,0 +1,359 @@
+"""
+Cross-device (remote) authentication support.
+
+This module manages the flow for authenticating from another device:
+1. Device A (requesting) creates a remote auth request and displays QR/link
+2. Device B (authenticating) opens the link and authenticates with passkey
+3. Device A receives the session via WebSocket notification
+
+Alternative flow (initiated from profile/authenticating device):
+1. Device A (requesting) creates request and displays short pairing code
+2. Device B (authenticating) enters the pairing code in their profile
+3. Device B authenticates, Device A receives the session
+
+The requests are stored in-memory with short expiration (5 minutes).
+The link uses the same /{token} endpoint as reset tokens, but the server
+distinguishes between them by checking if the token exists in remoteauth first.
+The first 3 words of the token serve as the pairing code for manual entry.
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Callable
+from uuid import UUID
+
+from paskia.util import passphrase
+
+# Remote auth requests expire after this duration
+REMOTE_AUTH_LIFETIME = timedelta(minutes=5)
+
+
+@dataclass
+class RemoteAuthRequest:
+    """A pending remote authentication request."""
+
+    key: str  # The 3-word passphrase code
+    created_at: datetime
+    host: str  # The host where the session should be created
+    ip: str  # IP of the requesting device
+    user_agent: str  # User agent of the requesting device
+    action: str = "login"  # "login" or "register"
+    locked: bool = False  # True once the authenticating device has entered the code
+    # Callback to notify the requesting device when auth completes
+    # Takes (session_token, user_uuid, credential_uuid, reset_token) or (None, None, None, None) on cancel/expire
+    notify: (
+        Callable[[str | None, UUID | None, UUID | None, str | None], None] | None
+    ) = None
+    # Callback to notify the requesting device when action is locked
+    # Takes (action) to confirm what action was locked
+    action_locked_notify: Callable[[str], None] | None = None
+    # Set when authentication completes
+    completed: bool = False
+    denied: bool = False  # True if explicitly denied by the authenticating device
+    session_token: str | None = None
+    user_uuid: UUID | None = None
+    credential_uuid: UUID | None = None
+    reset_token: str | None = None
+
+
+class RemoteAuthManager:
+    """Manages pending remote authentication requests."""
+
+    def __init__(self):
+        self._requests: dict[str, RemoteAuthRequest] = {}  # keyed by 3-word code
+        self._cleanup_task: asyncio.Task | None = None
+        self._lock = asyncio.Lock()
+
+    async def start(self):
+        """Start the cleanup background task."""
+        if self._cleanup_task is None:
+            self._cleanup_task = asyncio.create_task(self._cleanup_loop())
+
+    async def stop(self):
+        """Stop the cleanup background task."""
+        if self._cleanup_task:
+            self._cleanup_task.cancel()
+            try:
+                await self._cleanup_task
+            except asyncio.CancelledError:
+                pass
+            self._cleanup_task = None
+
+    async def _cleanup_loop(self):
+        """Periodically clean up expired requests."""
+        while True:
+            try:
+                await asyncio.sleep(60)  # Check every minute
+                await self._cleanup_expired()
+            except asyncio.CancelledError:
+                break
+            except Exception:
+                logging.exception("Error in remote auth cleanup loop")
+
+    async def _cleanup_expired(self):
+        """Remove expired requests and notify waiting clients."""
+        now = datetime.now(timezone.utc)
+        expired_keys = []
+        async with self._lock:
+            for key, req in self._requests.items():
+                if now > req.created_at + REMOTE_AUTH_LIFETIME:
+                    expired_keys.append(key)
+            for key in expired_keys:
+                req = self._requests.pop(key)
+                if req.notify and not req.completed:
+                    try:
+                        req.notify(None, None, None, None)
+                    except Exception:
+                        pass
+
+    async def create_request(
+        self,
+        host: str,
+        ip: str,
+        user_agent: str,
+        action: str = "login",
+    ) -> tuple[str, datetime]:
+        """Create a new remote auth request.
+
+        The code is a 3-word passphrase.
+        We ensure uniqueness across concurrent requests.
+
+        Returns:
+            (code, expiry) - The 3-word passphrase code and expiration time
+        """
+        now = datetime.now(timezone.utc)
+        expiry = now + REMOTE_AUTH_LIFETIME
+
+        async with self._lock:
+            # Generate unique 3-word code
+            max_attempts = 100
+            for _ in range(max_attempts):
+                code = passphrase.generate(n=passphrase.N_WORDS_SHORT)
+                if code not in self._requests:
+                    break
+            else:
+                # Extremely unlikely but handle gracefully
+                raise ValueError("Unable to generate unique code")
+
+            request = RemoteAuthRequest(
+                key=code,
+                created_at=now,
+                host=host,
+                ip=ip,
+                user_agent=user_agent,
+                action=action,
+            )
+
+            self._requests[code] = request
+
+        return code, expiry
+
+    async def get_request(self, code: str) -> RemoteAuthRequest | None:
+        """Get a pending request by code, if valid and not expired."""
+        # Normalize: lowercase, dot-separated words
+        normalized = code.lower().strip().replace(" ", ".")
+        if not passphrase.is_well_formed(normalized, n=passphrase.N_WORDS_SHORT):
+            return None
+        async with self._lock:
+            req = self._requests.get(normalized)
+            if req is None:
+                return None
+            now = datetime.now(timezone.utc)
+            if now > req.created_at + REMOTE_AUTH_LIFETIME:
+                # Expired
+                del self._requests[normalized]
+                return None
+            return req
+
+    async def set_notify_callback(
+        self,
+        token: str,
+        callback: Callable[[str | None, UUID | None, UUID | None, str | None], None],
+    ) -> bool:
+        """Set the notification callback for a request.
+
+        Returns True if the request exists and callback was set.
+        """
+        async with self._lock:
+            req = self._requests.get(token)
+            if req is None:
+                return False
+            req.notify = callback
+            return True
+
+    async def set_action_locked_callback(
+        self,
+        token: str,
+        callback: Callable[[str], None],
+    ) -> bool:
+        """Set the callback for when the action is locked.
+
+        Returns True if the request exists and callback was set.
+        """
+        async with self._lock:
+            req = self._requests.get(token)
+            if req is None:
+                return False
+            req.action_locked_notify = callback
+            return True
+
+    async def update_action(
+        self,
+        token: str,
+        action: str,
+    ) -> bool:
+        """Update the action for a request (only if not locked).
+
+        Returns True if the request exists and was updated.
+        """
+        if action not in ("login", "register"):
+            return False
+        async with self._lock:
+            req = self._requests.get(token)
+            if req is None or req.locked:
+                return False
+            req.action = action
+            return True
+
+    async def lock_action(
+        self,
+        token: str,
+    ) -> str | None:
+        """Lock the action for a request (called when authenticating device enters code).
+
+        Returns the locked action, or None if request doesn't exist or is already locked.
+        Notifies the requesting device via action_locked_notify callback.
+        """
+        async with self._lock:
+            req = self._requests.get(token)
+            if req is None:
+                return None
+            if req.locked:
+                # Already locked by another authenticating device
+                return None
+            req.locked = True
+            action = req.action
+            if req.action_locked_notify:
+                try:
+                    req.action_locked_notify(action)
+                except Exception:
+                    pass
+            return action
+
+    async def complete_request(
+        self,
+        token: str,
+        session_token: str | None,
+        user_uuid: UUID,
+        credential_uuid: UUID,
+        reset_token: str | None = None,
+    ) -> bool:
+        """Mark a request as completed with the authentication result.
+
+        The request is removed after notifying the waiting client.
+        Returns True if the request existed and was completed.
+        """
+        async with self._lock:
+            req = self._requests.pop(token, None)
+            if req is None:
+                return False
+            if req.notify:
+                try:
+                    req.notify(session_token, user_uuid, credential_uuid, reset_token)
+                except Exception:
+                    pass
+            return True
+
+    async def cancel_request(
+        self, token: str, *, denied: bool = False
+    ) -> RemoteAuthRequest | None:
+        """Cancel and remove a request.
+
+        Args:
+            token: The request token
+            denied: If True, marks this as an explicit denial (not just timeout/disconnect)
+
+        Returns the removed request if it existed, None otherwise.
+        """
+        async with self._lock:
+            req = self._requests.pop(token, None)
+            if req is None:
+                return None
+            if denied:
+                req.denied = True
+            if req.notify and not req.completed:
+                try:
+                    # Pass denied status through a special UUID value (all zeros means denied)
+                    if denied:
+                        req.notify(None, UUID(int=0), None, None)
+                    else:
+                        req.notify(None, None, None, None)
+                except Exception:
+                    pass
+            return req
+
+    def get_connection_count(self) -> int:
+        """Get the current count of open WebSocket connections.
+
+        This is used to determine PoW difficulty based on load.
+        """
+        # Count is maintained externally by the WebSocket endpoints
+        return getattr(self, "_ws_count", 0)
+
+    def increment_connections(self) -> None:
+        """Increment the WebSocket connection counter."""
+        self._ws_count = getattr(self, "_ws_count", 0) + 1
+
+    def decrement_connections(self) -> None:
+        """Decrement the WebSocket connection counter."""
+        self._ws_count = max(0, getattr(self, "_ws_count", 0) - 1)
+
+    def get_pow_difficulty(self) -> int:
+        """Get PoW difficulty based on current WebSocket connection count.
+
+        Uses NORMAL difficulty with low load (< 10 connections),
+        HARD difficulty with high load (>= 10 connections).
+
+        Returns:
+            PoW work units (pow.NORMAL or pow.HARD)
+        """
+        from paskia.util import pow
+
+        count = self.get_connection_count()
+        return pow.HARD if count >= 10 else pow.NORMAL
+
+    async def consume_request(self, token: str) -> RemoteAuthRequest | None:
+        """Get and remove a request (for use by the authenticating device)."""
+        if not passphrase.is_well_formed(token, n=passphrase.N_WORDS_SHORT):
+            return None
+        async with self._lock:
+            req = self._requests.get(token)
+            if req is None:
+                return None
+            now = datetime.now(timezone.utc)
+            if now > req.created_at + REMOTE_AUTH_LIFETIME:
+                del self._requests[token]
+                return None
+            # Don't remove yet - wait until completion
+            return req
+
+
+# Global instance
+instance: RemoteAuthManager | None = None
+
+
+async def init():
+    """Initialize the global remote auth manager."""
+    global instance
+    instance = RemoteAuthManager()
+    await instance.start()
+
+
+async def shutdown():
+    """Shutdown the global remote auth manager."""
+    global instance
+    if instance:
+        await instance.stop()
+        instance = None

paskia/sansio.py

@@ -37,7 +37,7 @@ from webauthn.helpers.structs import (
     UserVerificationRequirement,
 )
 
-from .db import Credential
+from paskia.db import Credential
 
 
 class Passkey:
@@ -47,7 +47,7 @@ class Passkey:
         self,
         rp_id: str,
         rp_name: str | None = None,
-        origin: str | None = None,
+        origins: list[str] | None = None,
         supported_pub_key_algs: list[COSEAlgorithmIdentifier] | None = None,
     ):
         """
@@ -56,40 +56,58 @@ class Passkey:
         Args:
             rp_id: Your security domain (e.g. "example.com")
             rp_name: The relying party display name (e.g. "Example App"). May be shown in authenticators.
-            origin: The origin URL of the application (e.g. "https://app.example.com").
-                   If no scheme is provided, "https://" will be prepended.
-                   Must be a subdomain or same as rp_id, with port and scheme but no path included.
+            origins: List of allowed origin URLs (e.g. ["https://app.example.com", "https://auth.example.com"]).
+                    Each must be a subdomain or same as rp_id. If not provided, any subdomain of rp_id is allowed.
             supported_pub_key_algs: List of supported COSE algorithms (default is EDDSA, ECDSA_SHA_256, RSASSA_PKCS1_v1_5_SHA_256).
 
         Raises:
-            ValueError: If the origin domain doesn't match or isn't a subdomain of rp_id.
+            ValueError: If any origin domain doesn't match or isn't a subdomain of rp_id.
         """
         self.rp_id = rp_id
         self.rp_name = rp_name or rp_id
-        self.origin = self._normalize_and_validate_origin(origin, rp_id)
+        self.allowed_origins: set[str] | None = None
+        if origins:
+            # Validate and deduplicate origins into a set for O(1) lookups
+            for o in origins:
+                self._validate_origin(o, rp_id)
+            self.allowed_origins = set(origins)
         self.supported_pub_key_algs = supported_pub_key_algs or [
             COSEAlgorithmIdentifier.EDDSA,
             COSEAlgorithmIdentifier.ECDSA_SHA_256,
             COSEAlgorithmIdentifier.RSASSA_PKCS1_v1_5_SHA_256,
         ]
 
-    def _normalize_and_validate_origin(self, origin: str | None, rp_id: str) -> str:
-        if origin is None:
-            origin = f"https://{rp_id}"
-        elif "://" not in origin:
-            origin = f"https://{origin}"
-
+    def _validate_origin(self, origin: str, rp_id: str) -> None:
+        """Validate an origin URL against the rp_id."""
         hostname = urlparse(origin).hostname
         if not hostname:
             raise ValueError(f"Invalid origin URL: no hostname found in '{origin}'")
 
         if hostname == rp_id or hostname.endswith(f".{rp_id}"):
-            return origin
+            return
 
         raise ValueError(
             f"Origin domain '{hostname}' must be the same as or a subdomain of rp_id '{rp_id}'"
         )
 
+    def validate_origin(self, origin: str) -> str:
+        """Validate that origin is allowed and return it.
+
+        Args:
+            origin: The origin URL to validate (from WebSocket request header)
+
+        Returns:
+            The validated origin URL
+
+        Raises:
+            ValueError: If origin is not in the allowed list (when origins are configured)
+                       or if origin is not a valid subdomain of rp_id
+        """
+        self._validate_origin(origin, self.rp_id)
+        if self.allowed_origins is not None and origin not in self.allowed_origins:
+            raise ValueError(f"Origin '{origin}' is not in the allowed origins list")
+        return origin
+
     ### Registration Methods ###
 
     def reg_generate_options(
@@ -137,14 +155,16 @@ class Passkey:
         response_json: dict | str,
         expected_challenge: bytes,
         user_uuid: UUID,
-        origin: str | None = None,
+        origin: str,
     ) -> Credential:
         """
         Verify registration response.
 
         Args:
-            credential: The credential response from the client
+            response_json: The credential response from the client
             expected_challenge: The expected challenge bytes
+            user_uuid: The user's UUID
+            origin: The origin URL (required, must be pre-validated)
 
         Returns:
             Registration verification result
@@ -153,7 +173,7 @@ class Passkey:
         registration = verify_registration_response(
             credential=credential,
             expected_challenge=expected_challenge,
-            expected_origin=origin or self.origin,
+            expected_origin=origin,
             expected_rp_id=self.rp_id,
         )
         return Credential(
@@ -184,7 +204,7 @@ class Passkey:
             authopts: Additional arguments to generate_authentication_options.
 
         Returns:
-            Tuple of (JSON to be sent to client, challenge bytes to store)
+            Tuple of (JSON dict to be sent to client, challenge bytes to store)
         """
         options = generate_authentication_options(
             rp_id=self.rp_id,
@@ -206,7 +226,7 @@ class Passkey:
         credential: AuthenticationCredential,
         expected_challenge: bytes,
         stored_cred: Credential,
-        origin: str | None = None,
+        origin: str,
     ) -> VerifiedAuthentication:
         """
         Verify authentication response against locally stored credential data.
@@ -215,13 +235,13 @@ class Passkey:
             credential: The authentication credential response from the client
             expected_challenge: The earlier generated challenge bytes
             stored_cred: The server stored credential record (modified by this function)
+            origin: The origin URL (required, must be pre-validated)
         """
-        expected_origin = origin or self.origin
         # Verify the authentication response
         verification = verify_authentication_response(
             credential=credential,
             expected_challenge=expected_challenge,
-            expected_origin=expected_origin,
+            expected_origin=origin,
             expected_rp_id=self.rp_id,
             credential_public_key=stored_cred.public_key,
             credential_current_sign_count=stored_cred.sign_count,

paskia/util/frontend.py

@@ -0,0 +1,75 @@
+import asyncio
+import mimetypes
+import os
+from importlib import resources
+from pathlib import Path
+
+import httpx
+
+__all__ = ["path", "file", "read", "is_dev_mode"]
+
+
+def _get_dev_server() -> str | None:
+    """Get the dev server URL from environment, or None if not in dev mode."""
+    return os.environ.get("PASKIA_DEVMODE") or None
+
+
+def _resolve_static_dir() -> Path:
+    # Try packaged path via importlib.resources (works for wheel/installed).
+    try:  # pragma: no cover - trivial path resolution
+        pkg_dir = resources.files("paskia") / "frontend-build"
+        fs_path = Path(str(pkg_dir))
+        if fs_path.is_dir():
+            return fs_path
+    except Exception:  # pragma: no cover - defensive
+        pass
+    # Fallback for editable/development before build.
+    return Path(__file__).parent.parent / "frontend-build"
+
+
+path: Path = _resolve_static_dir()
+
+
+def file(*parts: str) -> Path:
+    """Return a child path under the static root."""
+    return path.joinpath(*parts)
+
+
+def is_dev_mode() -> bool:
+    """Check if we're running in dev mode (Vite frontend server)."""
+    return bool(_get_dev_server())
+
+
+async def read(filepath: str) -> tuple[bytes, int, dict[str, str]]:
+    """Read file content and return response tuple.
+
+    In dev mode, fetches from the Vite dev server.
+    In production, reads from the static build directory.
+
+    Args:
+        filepath: Path relative to frontend root, e.g. "/auth/index.html"
+
+    Returns:
+        Tuple of (content, status_code, headers) suitable for
+        FastAPI Response(*args) or Sanic raw response.
+    """
+    if is_dev_mode():
+        dev_server = _get_dev_server()
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(f"{dev_server}{filepath}")
+            resp.raise_for_status()
+            mime = resp.headers.get("content-type", "application/octet-stream")
+            # Strip charset suffix if present
+            mime = mime.split(";")[0].strip()
+            return resp.content, resp.status_code, {"content-type": mime}
+    else:
+        # Production: read from static build
+        file_path = path / filepath.lstrip("/")
+        content = await _read_file_async(file_path)
+        mime, _ = mimetypes.guess_type(str(file_path))
+        return content, 200, {"content-type": mime or "application/octet-stream"}
+
+
+async def _read_file_async(file_path: Path) -> bytes:
+    """Read file asynchronously using asyncio.to_thread."""
+    return await asyncio.to_thread(file_path.read_bytes)

paskia/util/hostutil.py

@@ -0,0 +1,76 @@
+"""Utilities for determining the auth UI host and base URLs."""
+
+import json
+import os
+from functools import lru_cache
+from urllib.parse import urlsplit
+
+
+@lru_cache(maxsize=1)
+def _load_config() -> dict:
+    """Load PASKIA_CONFIG JSON."""
+    config_json = os.getenv("PASKIA_CONFIG")
+    if not config_json:
+        return {}
+    return json.loads(config_json)
+
+
+def is_root_mode() -> bool:
+    return _load_config().get("auth_host") is not None
+
+
+def dedicated_auth_host() -> str | None:
+    """Return configured auth_host netloc, or None."""
+    auth_host = _load_config().get("auth_host")
+    if not auth_host:
+        return None
+    from urllib.parse import urlparse
+
+    parsed = urlparse(auth_host if "://" in auth_host else f"//{auth_host}")
+    return parsed.netloc or parsed.path or None
+
+
+def ui_base_path() -> str:
+    return "/" if is_root_mode() else "/auth/"
+
+
+def auth_site_url() -> str:
+    """Return the base URL for the auth site UI (computed at startup)."""
+    cfg = _load_config()
+    return cfg.get("site_url", "https://localhost") + cfg.get("site_path", "/auth/")
+
+
+def reset_link_url(token: str) -> str:
+    """Generate a reset link URL for the given token."""
+    return f"{auth_site_url()}{token}"
+
+
+def normalize_origin(origin: str) -> str:
+    """Normalize an origin URL by adding https:// if no scheme is present."""
+    if "://" not in origin:
+        return f"https://{origin}"
+    return origin
+
+
+def reload_config() -> None:
+    _load_config.cache_clear()
+
+
+def normalize_host(raw_host: str | None) -> str | None:
+    """Normalize a Host header preserving port (exact match required)."""
+    if not raw_host:
+        return None
+    candidate = raw_host.strip()
+    if not candidate:
+        return 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.
+    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 "")
+    return netloc.lower() or None

paskia/util/htmlutil.py

@@ -0,0 +1,47 @@
+"""Utility functions for HTML manipulation."""
+
+import re
+
+
+def patch_html_data_attrs(html: bytes, **data_attrs: str) -> bytes:
+    """Patch HTML by adding data attributes to the <html> tag.
+
+    If an <html> tag exists, adds data attributes to it.
+    If no <html> tag exists, prepends one with the data attributes.
+
+    Args:
+        html: The HTML content as bytes
+        **data_attrs: Key-value pairs for data attributes (e.g., mode='reauth')
+
+    Returns:
+        Modified HTML as bytes
+
+    Examples:
+        >>> patch_html_data_attrs(b'<html><body>test</body></html>', mode='reauth')
+        b'<html data-mode="reauth"><body>test</body></html>'
+
+        >>> patch_html_data_attrs(b'<body>test</body>', mode='reauth')
+        b'<html data-mode="reauth"><body>test</body>'
+    """
+    if not data_attrs:
+        return html
+
+    html_str = html.decode("utf-8")
+
+    # Build the data attributes string
+    attrs_str = " ".join(f'data-{key}="{value}"' for key, value in data_attrs.items())
+
+    # Check if there's an <html> tag (case-insensitive, may have existing attributes)
+    html_tag_pattern = re.compile(r"<html([^>]*)>", re.IGNORECASE)
+    match = html_tag_pattern.search(html_str)
+
+    if match:
+        # Insert data attributes into existing <html> tag
+        existing_attrs = match.group(1)
+        new_tag = f"<html{existing_attrs} {attrs_str}>"
+        html_str = html_tag_pattern.sub(new_tag, html_str, count=1)
+    else:
+        # Prepend <html> tag with data attributes
+        html_str = f"<html {attrs_str}>" + html_str
+
+    return html_str.encode("utf-8")

paskia/util/passphrase.py

@@ -1,8 +1,9 @@
 import secrets
 
-from .wordlist import words
+from paskia.util.wordlist import words
 
 N_WORDS = 5
+N_WORDS_SHORT = 3
 
 wset = set(words)
 

paskia/util/permutil.py

@@ -3,9 +3,9 @@
 from collections.abc import Sequence
 from fnmatch import fnmatchcase
 
-from ..globals import db
-from .hostutil import normalize_host
-from .tokens import session_key
+from paskia.globals import db
+from paskia.util.hostutil import normalize_host
+from paskia.util.tokens import session_key
 
 __all__ = ["has_any", "has_all", "session_context"]
 

paskia/util/pow.py

@@ -0,0 +1,45 @@
+"""
+Proof of Work utility using PBKDF2-SHA512.
+
+The PoW requires finding nonces where PBKDF2(challenge, nonce) produces
+output with a zero first byte. Each work unit requires finding one such nonce.
+All valid nonces are concatenated into a solution for server verification.
+"""
+
+import hashlib
+import secrets
+
+EASY = 2  # Around 0.25s
+NORMAL = 8  # Around 1s
+HARD = 32  # Around 4s
+
+
+def generate_challenge() -> bytes:
+    """Generate a random 8-byte challenge."""
+    return secrets.token_bytes(8)
+
+
+def verify_pow(challenge: bytes, solution: bytes, work: int = NORMAL) -> None:
+    """Verify a Proof of Work solution.
+
+    Args:
+        challenge: 8-byte server-provided challenge
+        solution: Concatenated 8-byte nonces (8 * work bytes)
+        work: Number of work units expected
+
+    Raises:
+        ValueError: If the solution is invalid
+    """
+    if len(challenge) != 8:
+        raise ValueError("Invalid challenge length")
+
+    if len(solution) != 8 * work:
+        raise ValueError("Invalid solution length")
+
+    # Verify each work unit - check that PBKDF2 output starts with 0x00
+    for i in range(work):
+        nonce = solution[i * 8 : (i + 1) * 8]
+        # Require first byte of PBKDF2-SHA512 to be zero
+        result = hashlib.pbkdf2_hmac("sha512", challenge, nonce, 128, 2)
+        if result[0] or result[1] & 0x07:
+            raise ValueError("Invalid PoW solution")

paskia/util/sessionutil.py

@@ -0,0 +1,37 @@
+"""Utility functions for session validation and checking."""
+
+from datetime import datetime, timezone
+
+from paskia.db import SessionContext
+from paskia.util.timeutil import parse_duration
+
+
+def check_session_age(ctx: SessionContext, max_age: str | None) -> bool:
+    """Check if a session satisfies the max_age requirement.
+
+    Uses the credential's last_used timestamp to determine authentication age,
+    since session renewal can happen without re-authentication.
+
+    Args:
+        ctx: The session context containing session and credential info
+        max_age: Maximum age string (e.g., "5m", "1h", "30s") or None
+
+    Returns:
+        True if authentication is recent enough or max_age is None, False if too old
+
+    Raises:
+        ValueError: If max_age format is invalid
+    """
+    if not max_age:
+        return True
+
+    max_age_delta = parse_duration(max_age)
+
+    # Use credential's last_used time if available, fall back to session renewed
+    if ctx.credential and ctx.credential.last_used:
+        auth_time = ctx.credential.last_used
+    else:
+        auth_time = ctx.session.renewed
+
+    time_since_auth = datetime.now(timezone.utc) - auth_time
+    return time_since_auth <= max_age_delta