Console startup box themed as well.

README.md

@@ -1,5 +1,7 @@
 # Paskia
 
+![Screenshot](https://git.zi.fi/leovasanko/paskia/raw/main/docs/screenshots/forbidden-light.webp)
+
 An easy to install passkey-based authentication service that protects any web application with strong passwordless login.
 
 ## What is Paskia?

frontend/auth/App.vue

@@ -13,7 +13,8 @@
 <script setup>
 import { computed, onMounted, onUnmounted, ref } from 'vue'
 import { useAuthStore } from '@/stores/auth'
-import { apiJson, getAuthIframeUrl } from '@/utils/api'
+import { apiJson, SessionValidator, createAuthIframe, removeAuthIframe } from 'paskia'
+import { getAuthIframeUrl } from '@/utils/api'
 import StatusMessage from '@/components/StatusMessage.vue'
 import ProfileView from '@/components/ProfileView.vue'
 import HostProfileView from '@/components/HostProfileView.vue'
@@ -46,19 +47,23 @@ const isHostMode = computed(() => {
   const configuredHost = normalizeHost(authHost)
   return currentHost !== configuredHost
 })
-let validationTimer = null
+const userUuid = computed(() => store.userInfo?.ctx.user.uuid)
-let authIframe = null
 
 function terminateSession() {
   store.userInfo = null
   viewState.value = 'terminal'
 }
 
+const userUuidGetter = () => store.userInfo?.ctx.user.uuid
+const sessionValidator = new SessionValidator(userUuidGetter, terminateSession)
+
+onMounted(() => sessionValidator.start())
+onUnmounted(() => sessionValidator.stop())
+
 async function loadUserInfo() {
   try {
     store.userInfo = await apiJson('/auth/api/user-info', { method: 'POST' })
     viewState.value = 'profile'
-    startSessionValidation()
     return true
   } catch {
     store.userInfo = null
@@ -67,27 +72,11 @@ async function loadUserInfo() {
 }
 
 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')
+  createAuthIframe(url)
-  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 handleAuthMessage(event) {
   const data = event.data
   if (!data?.type) return
@@ -95,7 +84,7 @@ function handleAuthMessage(event) {
   switch (data.type) {
     case 'auth-success':
       // Authentication successful - reload user info
-      hideAuthIframe()
+      removeAuthIframe()
       viewState.value = 'loading'
       loadingMessage.value = 'Loading user profile...'
       loadUserInfo()
@@ -117,39 +106,17 @@ function handleAuthMessage(event) {
 
     case 'auth-back':
       // User clicked Back - show terminal state
-      hideAuthIframe()
+      removeAuthIframe()
       terminateSession()
       break
 
     case 'auth-close-request':
       // Legacy support - treat as back
-      hideAuthIframe()
+      removeAuthIframe()
       break
   }
 }
 
-async function validateSession() {
-  try {
-    await apiJson('/auth/api/validate', { method: 'POST' })
-  } catch {
-    stopSessionValidation()
-    terminateSession()
-  }
-}
-
-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)
@@ -178,8 +145,7 @@ onMounted(async () => {
 
 onUnmounted(() => {
   window.removeEventListener('message', handleAuthMessage)
-  stopSessionValidation()
+  removeAuthIframe()
-  hideAuthIframe()
 })
 </script>
 

frontend/auth/admin/AdminApp.vue

@@ -12,7 +12,7 @@ import AdminUserDetail from '@/admin/AdminUserDetail.vue'
 import AdminDialogs from '@/admin/AdminDialogs.vue'
 import { useAuthStore } from '@/stores/auth'
 import { adminUiPath, makeUiHref } from '@/utils/settings'
-import { apiJson } from '@/utils/api'
+import { apiJson, SessionValidator } from 'paskia'
 import { getDirection } from '@/utils/keynav'
 import { goBack } from '@/utils/helpers'
 
@@ -157,6 +157,21 @@ function clearSensitiveState() {
   authenticated.value = false
 }
 
+function onSessionLost(e) {
+  clearSensitiveState()
+  if (e.name === 'AuthCancelledError') {
+    showBackMessage.value = true
+  } else {
+    error.value = e.message
+  }
+}
+
+const userUuidGetter = () => info.value?.ctx.user.uuid
+const sessionValidator = new SessionValidator(userUuidGetter, onSessionLost)
+
+onMounted(() => sessionValidator.start())
+onUnmounted(() => sessionValidator.stop())
+
 async function load() {
   loading.value = true
   loadingMessage.value = 'Loading...'
@@ -177,12 +192,7 @@ async function load() {
       }
     } else parseHash()
   } catch (e) {
-    clearSensitiveState()
+    onSessionLost(e)
-    if (e.name === 'AuthCancelledError') {
-      showBackMessage.value = true
-    } else {
-      error.value = e.message
-    }
   } finally {
     loading.value = false
   }

frontend/auth/admin/main.js

@@ -1,3 +1,6 @@
+import { initThemeFromCache } from '@/utils/theme'
+initThemeFromCache()
+
 import '@/assets/style.css'
 
 import { createApp } from 'vue'

frontend/auth/main.js

@@ -1,3 +1,6 @@
+import { initThemeFromCache } from '@/utils/theme'
+initThemeFromCache()
+
 import '@/assets/style.css'
 
 import { createApp } from 'vue'

frontend/auth/restricted/RestrictedApi.vue

@@ -8,7 +8,7 @@
 </template>
 
 <script setup>
-import { computed, onMounted, ref } from 'vue'
+import { onMounted, ref } from 'vue'
 import RestrictedAuth from '@/components/RestrictedAuth.vue'
 
 // Check if this is a remote auth URL: /auth/{token}
@@ -30,14 +30,9 @@ function extractRemoteToken() {
   return null
 }
 
-// Detect mode from URL hash fragment
+// Parse URL hash fragment
-const authMode = computed(() => {
+const hashParams = new URLSearchParams(window.location.hash.slice(1))
-  const params = new URLSearchParams(window.location.hash.slice(1))
+const authMode = ['reauth', 'forbidden'].includes(hashParams.get('mode')) ? hashParams.get('mode') : 'login'
-  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) {

frontend/auth/restricted/main.js

@@ -1,3 +1,4 @@
+import './theme.js'
 import { createApp } from 'vue'
 import RestrictedApi from './RestrictedApi.vue'
 import '@/assets/style.css'

frontend/auth/restricted/theme.js

@@ -0,0 +1,11 @@
+// Early theme for restricted app - first URL param wins, then localStorage
+import { themeColors, applyTheme, getCachedTheme } from '@/utils/theme.js'
+
+function getTheme() {
+  const params = new URLSearchParams(location.hash.slice(1))
+  return params.get('theme') || getCachedTheme() || ''
+}
+
+// Use .surface selector to preserve transparent background
+applyTheme(getTheme(), '.surface')
+addEventListener('hashchange', () => applyTheme(getTheme(), '.surface'))

frontend/int/reset/ResetApp.vue

@@ -59,7 +59,7 @@
 import { computed, onMounted, reactive, ref } from 'vue'
 import passkey from '@/utils/passkey'
 import { getSettings, uiBasePath } from '@/utils/settings'
-import { apiJson, ApiError, getUserFriendlyErrorMessage } from '@/utils/api'
+import { apiJson, ApiError, getUserFriendlyErrorMessage } from 'paskia'
 
 const status = reactive({
   show: false,

frontend/package.json

@@ -10,6 +10,7 @@
   },
   "dependencies": {
     "@simplewebauthn/browser": "^13.1.2",
+    "paskia": "file:../paskia-js",
     "pinia": "^3.0.3",
     "qrcode": "^1.5.4",
     "sirv": "^3.0.2",

frontend/src/admin/AdminUserDetail.vue

@@ -5,7 +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'
+import { apiJson } from 'paskia'
 import { getDirection, navigateButtonRow, focusPreferred, focusAtIndex } from '@/utils/keynav'
 
 const props = defineProps({

frontend/src/assets/style.css

@@ -78,7 +78,6 @@ html {
 }
 
 body {
-  color-scheme: light dark;
   overflow: auto;
   scrollbar-gutter: stable;
   height: 100%;
@@ -132,6 +131,7 @@ a:focus-visible {
 }
 
 .view-root {
+  position: relative;
   flex: 1;
   width: 100%;
   display: flex;
@@ -731,42 +731,6 @@ th {
   }
 }
 
-/* Global backdrop controlled by api.js ref-counting */
-body::before {
-  content: '';
-  position: fixed;
-  inset: 0;
-  z-index: 1099;
-  background: transparent;
-  backdrop-filter: blur(0) brightness(1);
-  -webkit-backdrop-filter: blur(0) brightness(1);
-  pointer-events: none;
-  visibility: hidden;
-  transition: all 0.2s ease-out;
-}
-
-body.has-backdrop::before {
-  -webkit-backdrop-filter: blur(.2rem) brightness(0.5);
-  backdrop-filter: blur(.2rem) brightness(0.5);
-  visibility: visible;
-}
-
-body.has-backdrop {
-  overflow: auto;
-}
-
-#auth-iframe {
-  border: none;
-  position: fixed;
-  top: 0;
-  left: 0;
-  width: 100%;
-  height: 100%;
-  z-index: 9999;
-  color-scheme: auto;
-  background: transparent;
-}
-
 .slot-machine {
   padding: 0.875rem 1rem;
   background: var(--color-surface-hover, rgba(0, 0, 0, 0.03));

frontend/src/components/ProfileView.vue

@@ -1,5 +1,15 @@
 <template>
   <section class="view-root" data-view="profile">
+    <div class="theme-toggle">
+      <button class="theme-btn" @click="themeMenuOpen = !themeMenuOpen" :title="themeTitle">
+        {{ themeEmoji }}
+      </button>
+      <div v-if="themeMenuOpen" class="theme-menu" @click="themeMenuOpen = false">
+        <button class="theme-option top" :class="{ active: selectedTheme === '' }" @click.stop="setTheme('')" title="Auto">🌓</button>
+        <button class="theme-option left" :class="{ active: selectedTheme === 'light' }" @click.stop="setTheme('light')" title="Light">☀️</button>
+        <button class="theme-option right" :class="{ active: selectedTheme === 'dark' }" @click.stop="setTheme('dark')" title="Dark">🌙</button>
+      </div>
+    </div>
     <header class="view-header">
       <h1>User Profile</h1>
       <Breadcrumbs ref="breadcrumbs" :entries="breadcrumbEntries" @keydown="handleBreadcrumbKeydown" />
@@ -127,8 +137,9 @@ import { useAuthStore } from '@/stores/auth'
 import { adminUiPath, makeUiHref } from '@/utils/settings'
 import passkey from '@/utils/passkey'
 import { goBack } from '@/utils/helpers'
-import { apiJson } from '@/utils/api'
+import { apiJson } from 'paskia'
 import { navigateButtonRow, focusPreferred, focusAtIndex, getDirection } from '@/utils/keynav'
+import { updateThemeFromSession } from '@/utils/theme'
 
 const authStore = useAuthStore()
 const updateInterval = ref(null)
@@ -148,6 +159,22 @@ const breadcrumbs = ref(null)
 const userBasicInfo = ref(null)
 const userInfoSection = ref(null)
 
+// Theme preference
+const selectedTheme = ref('')
+const themeMenuOpen = ref(false)
+const themeEmoji = computed(() => ({ '': '🌓', light: '☀️', dark: '🌙' })[selectedTheme.value] || '🌓')
+const themeTitle = computed(() => ({ '': 'Auto (system)', light: 'Light mode', dark: 'Dark mode' })[selectedTheme.value] || 'Theme')
+watch(() => authStore.userInfo?.ctx?.user?.theme, (t) => { selectedTheme.value = t || '' }, { immediate: true })
+function setTheme(theme) {
+  selectedTheme.value = theme
+  themeMenuOpen.value = false
+  // Apply immediately for instant feedback
+  updateThemeFromSession({ user: { theme } }, true)
+  // Save to server in background
+  apiJson('/auth/api/user/theme', { method: 'PATCH', body: { theme } })
+    .catch(e => authStore.showMessage(e.message, 'error'))
+}
+
 // Check if any modal/dialog is open (blocks arrow key navigation)
 const hasActiveModal = computed(() => showNameDialog.value || showRegLink.value)
 
@@ -352,8 +379,16 @@ const saveName = async () => {
 .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; }
-.remote-auth-description {
+.remote-auth-description { font-size: 0.75rem; color: var(--color-text-muted); }
-  font-size: 0.75rem;
+.theme-toggle { position: absolute; top: var(--layout-padding); right: var(--layout-padding); }
-  color: var(--color-text-muted);
+.theme-btn { background: none; border: none; padding: 0.25rem; font-size: 1.25rem; cursor: pointer; opacity: 0.5; transition: opacity 0.15s; }
-}
+.theme-btn:hover { opacity: 0.8; }
+.theme-menu { position: absolute; top: 100%; right: 0; width: 5rem; height: 4rem; margin-top: 0.25rem; }
+.theme-option { position: absolute; background: none; border: none; font-size: 1.25rem; cursor: pointer; opacity: 0.5; padding: 0.25rem; border-radius: var(--radius-sm); transition: opacity 0.15s, transform 0.15s; }
+.theme-option:hover { opacity: 1; transform: scale(1.2); }
+.theme-option.active { opacity: 1; }
+.theme-option.top { top: 0; left: 50%; transform: translateX(-50%); }
+.theme-option.top:hover { transform: translateX(-50%) scale(1.2); }
+.theme-option.left { bottom: 0; left: 0; }
+.theme-option.right { bottom: 0; right: 0; }
 </style>

frontend/src/components/RegistrationLinkModal.vue

@@ -35,9 +35,10 @@
 <script setup>
 import { ref, onMounted, onUnmounted, nextTick } from 'vue'
 import QRCodeDisplay from '@/components/QRCodeDisplay.vue'
-import { apiJson } from '@/utils/api'
+import { apiJson } from 'paskia'
 import { formatDate } from '@/utils/helpers'
 import { getDirection } from '@/utils/keynav'
+import { useAuthStore } from '@/stores/auth'
 
 const props = defineProps({
   endpoint: { type: String, required: true },
@@ -46,6 +47,7 @@ const props = defineProps({
 
 const emit = defineEmits(['close', 'copied'])
 
+const authStore = useAuthStore()
 const dialog = ref(null)
 const linkUrl = ref(null)
 const expiresAt = ref(null)
@@ -73,7 +75,8 @@ async function generateLink() {
     } else {
       emit('close')
     }
-  } catch {
+  } catch (e) {
+    authStore.showMessage(e.message || 'Failed to generate link', 'error')
     emit('close')
   }
 }

frontend/src/components/RestrictedAuth.vue

@@ -58,7 +58,7 @@
 import { computed, nextTick, onMounted, onUnmounted, reactive, ref, watch } from 'vue'
 import passkey from '@/utils/passkey'
 import { getSettings, uiBasePath } from '@/utils/settings'
-import { fetchJson, getUserFriendlyErrorMessage } from '@/utils/api'
+import { fetchJson, getUserFriendlyErrorMessage } from 'paskia'
 import RemoteAuthRequest from '@/components/RemoteAuthRequest.vue'
 import { focusDialogButton } from '@/utils/keynav'
 

frontend/src/stores/auth.js

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

frontend/src/utils/api.js

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

frontend/src/utils/passkey.js

@@ -1,7 +1,7 @@
 import { startRegistration, startAuthentication } from '@simplewebauthn/browser'
 import aWebSocket from '@/utils/awaitable-websocket'
 import { getSettings } from '@/utils/settings'
-import { showAuthIframe } from '@/utils/api'
+import { showAuthIframe } from 'paskia'
 
 // Generic path normalizer: if an auth_host is configured and differs from current
 // host, return absolute URL (scheme derived by aWebSocket). Otherwise, keep as-is.

frontend/src/utils/theme.js

@@ -0,0 +1,101 @@
+// Theme override utilities - shared across apps
+// User preference or URL hash can force light/dark mode
+
+export const themeColors = {
+  light: {
+    'color-canvas': '#ffffff',
+    'color-surface': '#eff6ff',
+    'color-surface-subtle': '#dbeafe',
+    'color-border': '#2563eb',
+    'color-border-strong': '#1e40af',
+    'color-heading': '#1e3a8a',
+    'color-text': '#1e293b',
+    'color-text-muted': '#475569',
+    'color-link': '#1d4ed8',
+    'color-link-hover': '#1e40af',
+    'color-accent': '#2563eb',
+    'color-accent-strong': '#1e40af',
+    'color-accent-contrast': '#ffffff',
+    'color-success-text': '#166534',
+    'color-success-bg': '#dcfce7',
+    'color-error-text': '#b91c1c',
+    'color-error-bg': '#fee2e2',
+    'color-info-text': '#1e40af',
+    'color-info-bg': '#dbeafe',
+    'color-danger': '#dc2626',
+    'shadow-soft': '0 10px 30px rgba(30, 64, 175, 0.15)',
+  },
+  dark: {
+    'color-canvas': '#0f172a',
+    'color-surface': '#141b2f',
+    'color-surface-subtle': '#1b243b',
+    'color-border': '#25304a',
+    'color-border-strong': '#3d4d6b',
+    'color-heading': '#fff',
+    'color-text': '#e2e8f0',
+    'color-text-muted': '#94a3b8',
+    'color-link': '#60a5fa',
+    'color-link-hover': '#93c5fd',
+    'color-accent': '#60a5fa',
+    'color-accent-strong': '#3b82f6',
+    'color-accent-contrast': '#0b1120',
+    'color-success-text': '#34d399',
+    'color-success-bg': '#1a4d2e',
+    'color-error-text': '#fca5a5',
+    'color-error-bg': '#4a1f1f',
+    'color-info-text': '#bae6fd',
+    'color-info-bg': '#1e3a5f',
+    'color-danger': '#f87171',
+    'shadow-soft': '0 0 0 #000000',
+  }
+}
+
+const STYLE_ID = 'theme-override'
+const TRANSITION_ID = 'theme-transition'
+const STORAGE_KEY = 'paskia-theme'
+
+/** Apply theme override CSS - selector targets .surface for restricted app, :root for main apps */
+export function applyTheme(theme, selector = ':root', animate = false) {
+  // Add temporary transition for smooth theme change
+  if (animate) {
+    let transitionStyle = document.getElementById(TRANSITION_ID)
+    if (!transitionStyle) {
+      transitionStyle = document.createElement('style')
+      transitionStyle.id = TRANSITION_ID
+      transitionStyle.textContent = '*, *::before, *::after { transition: background-color 0.3s, color 0.3s, border-color 0.3s, box-shadow 0.3s !important; }'
+      document.head.appendChild(transitionStyle)
+    }
+    setTimeout(() => document.getElementById(TRANSITION_ID)?.remove(), 350)
+  }
+  document.getElementById(STYLE_ID)?.remove()
+  if (theme && themeColors[theme]) {
+    const css = `${selector} { ${Object.entries(themeColors[theme]).map(([k, v]) => `--${k}: ${v}`).join('; ')}; }`
+    const style = document.createElement('style')
+    style.id = STYLE_ID
+    style.textContent = css
+    document.head.appendChild(style)
+  }
+}
+
+/** Get theme from localStorage cache */
+export function getCachedTheme() {
+  return localStorage.getItem(STORAGE_KEY) || ''
+}
+
+/** Cache theme in localStorage */
+export function setCachedTheme(theme) {
+  if (theme) localStorage.setItem(STORAGE_KEY, theme)
+  else localStorage.removeItem(STORAGE_KEY)
+}
+
+/** Initialize theme from user preference (with localStorage cache for fast load) */
+export function initThemeFromCache() {
+  applyTheme(getCachedTheme())
+}
+
+/** Update theme from session context (call after login/session load) */
+export function updateThemeFromSession(ctx, animate = false) {
+  const theme = ctx?.user?.theme || ''
+  setCachedTheme(theme)
+  applyTheme(theme, ':root', animate)
+}

frontend/vite.config.js

@@ -90,7 +90,9 @@ export default defineConfig(({ command }) => ({
     }
   ].filter(Boolean),
   resolve: {
-    alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) }
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    }
   },
   base: '/',
   server: {

paskia-js/.gitignore

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

paskia-js/README.md

@@ -0,0 +1,131 @@
+# Paskia
+
+![Screenshot](https://git.zi.fi/leovasanko/paskia/raw/main/docs/screenshots/forbidden-light.webp)
+
+JavaScript utilities for [Paskia authentication system](https://git.zi.fi/leovasanko/paskia) integration into web apps.
+
+## Installation
+
+### NPM
+
+No framework dependencies. Works with any framework (Vue, React, Svelte, etc.) or vanilla JS. Typescript typing included.
+
+```sh
+npm install paskia
+```
+
+```js
+import { ... } from 'paskia'
+```
+
+### Plain JavaScript
+
+Fetch the module directly from a CDN, or [download](https://cdn.jsdelivr.net/npm/paskia@latest/dist/paskia.js) first and host yourself. No Node needed.
+
+```html
+<script type="module">
+  import { ... } from 'https://cdn.jsdelivr.net/npm/paskia@latest/dist/paskia.js'
+</script>
+```
+
+## Features
+
+### Session Validation
+
+Refresh session and track its validity with automatic polling. Pauses on lack of user activity to avoid useless traffic and to allow session expiry even when the page is left open but idle. This monitors that the same account stays logged in but doesn't do any permission checks.
+
+```js
+import { SessionValidator } from 'paskia'
+
+const validator = new SessionValidator(
+  () => currentUser?.uuid,  // getter for current user ID that we track
+  (error) => handleSessionLost(error)  // callback when session is lost
+)
+
+validator.start()  // call at your app startup/login
+validator.stop()   // stop the system (optional)
+```
+
+### API Fetch Utilities
+
+Enhanced fetch functions with automatic error handling and authentication retry:
+
+```js
+import { apiJson, apiFetch } from 'paskia'
+
+// JSON API calls with automatic auth handling
+const data = await apiJson('/api/endpoint', { method: 'POST', body: { key: 'value' } })
+
+// Raw fetch with auth handling
+const response = await apiFetch('/api/endpoint')
+```
+
+When a 401/403 response includes an auth iframe URL, the request automatically pauses, displays the authentication UI, and retries upon success. In case this is not needed, use standard `fetch` or our `fetchJson`.
+
+The JSON variants set headers automatically, with body and response in JSON.
+
+### Authentication Overlay
+
+Normally you use apiJson/apiFetch and they handle this automatically. If you need to wire it yourself, on a 401/403 response that includes `auth.iframe`, call `showAuthIframe(...)` and then retry the original request.
+
+The backend returns 401/403 responses with the correct URL for proper user feedback. Alternatively you may use `/auth/restricted/#mode=login`, `mode=reauth` or `mode=forbidden` to trigger the UX flow you need.
+
+```js
+import { showAuthIframe, AuthCancelledError } from 'paskia'
+
+const response = await fetch('/api/protected')
+if (response.status === 401 || response.status === 403) {
+  const data = await response.json()
+  if (data.auth?.iframe) {
+    await showAuthIframe(data.auth.iframe)  // Raises AuthCancelledError if the user cancels
+  }
+}
+```
+
+This resolves after the user authenticates (possibly with another account than previously), and you should usually retry the original API request. Note that successful authentication doesn't guarantee that the user still has rights to what originally failed.
+
+### Shared Blur Backdrop
+
+The authentication dialog displays with a blur backdrop (z-index 1099). The auth iframe uses z-index 9999. Your app dialogs should use z-index 1100–9998 to appear above the backdrop but below authentication.
+
+The backdrop is also reusable/refcounted, so you can keep consistent visuals for your own dialogs:
+
+```js
+import { holdGlobalBackdrop, releaseGlobalBackdrop } from 'paskia'
+
+holdGlobalBackdrop()
+try {
+  await your.own.dialog()
+} finally {
+  releaseGlobalBackdrop()
+}
+```
+
+The backdrop only disappears after all holders have released it.
+
+## Error Handling
+
+### AuthCancelledError (apiFetch, apiJson, showAuthIframe)
+
+If the user clicks Back in the authentication dialog, refusing to authenticate, `AuthCancelledError` is risen (as a response to postMessage from the iframe). The dialog closes as expected and it is up to the app how to continue from there.
+
+- Do nothing if the app can continue despite the failed operation (no UI notification needed)
+- Display a simple Access Denied page with suggestion/button to reload the page to try again
+
+Do not retry automatically.
+
+### UI feedback
+
+A set of small utilities are available for determining whether the user needs a notification and to format the error message.
+
+```js
+import { getUserFriendlyErrorMessage, shouldShowErrorToast } from 'paskia'
+
+try {
+  await apiJson('/api/action')
+} catch (e) {
+  if (shouldShowErrorToast(e)) {
+    your.message.display(getUserFriendlyErrorMessage(e))
+  }
+}
+```

paskia-js/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "paskia",
+  "version": "0.1.2",
+  "description": "Paskia authentication utilities for JavaScript",
+  "type": "module",
+  "main": "./dist/paskia.js",
+  "types": "./dist/paskia.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/paskia.d.ts",
+      "import": "./dist/paskia.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "~5.8.0",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "paskia"
+  ],
+  "license": "Unlicense"
+}

paskia-js/src/fetch.ts

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

paskia-js/src/index.ts

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

paskia-js/src/overlay.ts

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

paskia-js/src/validate.ts

@@ -0,0 +1,66 @@
+import { apiJson } from './fetch'
+
+const POLL_INTERVAL = 60 * 1000
+const IDLE_TIMEOUT = 5 * 60 * 1000
+
+export class SessionValidator {
+  private userUuidGetter: () => string | undefined
+  private onSessionLost: (error: Error) => void
+  private pollTimer: ReturnType<typeof setInterval> | null = null
+  private idleTimer: ReturnType<typeof setTimeout> | null = null
+  private active = false
+
+  constructor(userUuidGetter: () => string | undefined, onSessionLost: (error: Error) => void) {
+    this.userUuidGetter = userUuidGetter
+    this.onSessionLost = onSessionLost
+    this.resetIdleTimer = this.resetIdleTimer.bind(this)
+  }
+
+  resetIdleTimer(): void {
+    if (this.idleTimer) clearTimeout(this.idleTimer)
+    if (!this.active) this.startPolling()
+    this.idleTimer = setTimeout(() => this.stopPolling(), IDLE_TIMEOUT)
+  }
+
+  async validate(): Promise<void> {
+    try {
+      const data = await apiJson<{ ctx?: { user?: { uuid?: string } } }>('/auth/api/validate', { method: 'POST' })
+      const newUuid = data.ctx?.user?.uuid
+      if (newUuid !== this.userUuidGetter()) {
+        window.location.reload()
+      }
+    } catch (error) {
+      if ((error as Error).name !== 'NetworkError') {
+        this.stopPolling()
+        this.onSessionLost(error as Error)
+      }
+    }
+  }
+
+  startPolling(): void {
+    if (this.active) return
+    this.active = true
+    this.pollTimer = setInterval(() => this.validate(), POLL_INTERVAL)
+  }
+
+  stopPolling(): void {
+    this.active = false
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer)
+      this.pollTimer = null
+    }
+  }
+
+  start(): void {
+    window.addEventListener('pointermove', this.resetIdleTimer)
+    window.addEventListener('pointerdown', this.resetIdleTimer)
+    this.resetIdleTimer()
+  }
+
+  stop(): void {
+    window.removeEventListener('pointermove', this.resetIdleTimer)
+    window.removeEventListener('pointerdown', this.resetIdleTimer)
+    if (this.idleTimer) clearTimeout(this.idleTimer)
+    this.stopPolling()
+  }
+}

paskia-js/tsconfig.json

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

paskia-js/vite.config.js

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

paskia/aaguid/__init__.py

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

paskia/authsession.py

@@ -8,7 +8,7 @@ independent of any web framework:
 - Credential management
 """
 
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 from uuid import UUID
 
@@ -23,11 +23,11 @@ EXPIRES = SESSION_LIFETIME
 
 
 def expires() -> datetime:
-    return datetime.now(timezone.utc) + EXPIRES
+    return datetime.now(UTC) + EXPIRES
 
 
 def reset_expires() -> datetime:
-    return datetime.now(timezone.utc) + RESET_LIFETIME
+    return datetime.now(UTC) + RESET_LIFETIME
 
 
 def get_reset(token: str) -> "ResetToken":
@@ -39,24 +39,9 @@ def get_reset(token: str) -> "ResetToken":
     raise ValueError("This authentication link is no longer valid.")
 
 
-def refresh_session_token(token: str, *, ip: str, user_agent: str):
-    """Refresh a session extending its expiry."""
-    session_record = db.data().sessions.get(token)
-    if not session_record:
-        raise ValueError("Session not found or expired")
-    updated = db.update_session(
-        token,
-        ip=ip,
-        user_agent=user_agent,
-        expiry=expires(),
-    )
-    if not updated:
-        raise ValueError("Session not found or expired")
-
-
 def delete_credential(credential_uuid: UUID, auth: str, host: str | None = None):
     """Delete a specific credential for the current user."""
-    ctx = db.get_session_context(auth, hostutil.normalize_host(host))
+    ctx = db.data().session_ctx(auth, hostutil.normalize_host(host))
     if not ctx:
         raise ValueError("Session expired")
     db.delete_credential(credential_uuid, ctx.user.uuid)

paskia/db/__init__.py

@@ -2,7 +2,7 @@
 Database module for WebAuthn passkey authentication.
 
 Read: Access data() directly, use build_* to convert to public structs.
-CTX: get_session_context(key) returns SessionContext with effective permissions.
+CTX: data().session_ctx(key) returns SessionContext with effective permissions.
 Write: Functions validate and commit, or raise ValueError.
 
 Usage:
@@ -13,7 +13,7 @@ Usage:
     user = db.build_user(user_uuid)
 
     # Context
-    ctx = db.get_session_context(session_key)
+    ctx = db.data().session_ctx(session_key)
 
     # Write
     db.create_user(user)
@@ -49,7 +49,6 @@ from paskia.db.operations import (
     delete_user,
     get_organization_users,
     get_reset_token,
-    get_session_context,
     get_user_credential_ids,
     get_user_organization,
     init,
@@ -65,6 +64,7 @@ from paskia.db.operations import (
     update_user_display_name,
     update_user_role,
     update_user_role_in_organization,
+    update_user_theme,
 )
 from paskia.db.structs import (
     DB,
@@ -113,7 +113,6 @@ __all__ = [
     # Read ops
     "get_organization_users",
     "get_reset_token",
-    "get_session_context",
     "get_user_credential_ids",
     "get_user_organization",
     # Write ops
@@ -149,4 +148,5 @@ __all__ = [
     "update_user_display_name",
     "update_user_role",
     "update_user_role_in_organization",
+    "update_user_theme",
 ]

paskia/db/background.py

@@ -6,7 +6,7 @@ Periodically flushes pending changes to disk and cleans up expired items.
 
 import asyncio
 import logging
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 
 from paskia.db.operations import _store, cleanup_expired
 
@@ -33,7 +33,7 @@ async def _background_loop():
     cleanup_expired()
     await flush()
 
-    last_cleanup = datetime.now(timezone.utc)
+    last_cleanup = datetime.now(UTC)
 
     while True:
         try:
@@ -42,7 +42,7 @@ async def _background_loop():
             await flush()
 
             # Run cleanup periodically
-            now = datetime.now(timezone.utc)
+            now = datetime.now(UTC)
             if (now - last_cleanup).total_seconds() >= CLEANUP_INTERVAL:
                 cleanup_expired()
                 await flush()  # Flush cleanup changes

paskia/db/jsonl.py

@@ -2,15 +2,11 @@
 JSONL persistence layer for the database.
 """
 
-from __future__ import annotations
-
 import copy
-import json
 import logging
-import sys
 from collections import deque
 from contextlib import contextmanager
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 from uuid import UUID
@@ -19,7 +15,8 @@ import aiofiles
 import jsondiff
 import msgspec
 
-from paskia.db.migrations import apply_migrations
+from paskia.db.logging import log_change
+from paskia.db.migrations import DBVER, apply_all_migrations
 from paskia.db.structs import DB, SessionContext
 
 _logger = logging.getLogger(__name__)
@@ -33,6 +30,7 @@ class _ChangeRecord(msgspec.Struct, omit_defaults=True):
 
     ts: datetime
     a: str  # action - describes the operation (e.g., "migrate", "login", "create_user")
+    v: int  # schema version after this change
     u: str | None = None  # user UUID who performed the action (None for system)
     diff: dict = {}
 
@@ -41,43 +39,6 @@ class _ChangeRecord(msgspec.Struct, omit_defaults=True):
 _change_encoder = msgspec.json.Encoder()
 
 
-async def load_jsonl(db_path: Path) -> dict:
-    """Load data from disk by applying change log.
-
-    Replays all changes from JSONL file using plain dicts (to handle
-    schema evolution).
-
-    Args:
-        db_path: Path to the JSONL database file
-
-    Returns:
-        The final state after applying all changes
-
-    Raises:
-        ValueError: If file doesn't exist or cannot be loaded
-    """
-    if not db_path.exists():
-        raise ValueError(f"Database file not found: {db_path}")
-    data_dict: dict = {}
-    try:
-        # Read entire file at once and split into lines
-        async with aiofiles.open(db_path, "rb") as f:
-            content = await f.read()
-        for line_num, line in enumerate(content.split(b"\n"), 1):
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                change = msgspec.json.decode(line)
-                # Apply the diff to current state (marshal=True for $-prefixed keys)
-                data_dict = jsondiff.patch(data_dict, change["diff"], marshal=True)
-            except Exception as e:
-                raise ValueError(f"Error parsing line {line_num}: {e}")
-    except (OSError, ValueError, msgspec.DecodeError) as e:
-        raise ValueError(f"Failed to load database: {e}")
-    return data_dict
-
-
 def compute_diff(previous: dict, current: dict) -> dict | None:
     """Compute JSON diff between two states.
 
@@ -93,19 +54,20 @@ def compute_diff(previous: dict, current: dict) -> dict | None:
 
 
 def create_change_record(
-    action: str, diff: dict, user: str | None = None
+    action: str, version: int, diff: dict, user: str | None = None
 ) -> _ChangeRecord:
     """Create a change record for persistence."""
     return _ChangeRecord(
-        ts=datetime.now(timezone.utc),
+        ts=datetime.now(UTC),
         a=action,
+        v=version,
         u=user,
         diff=diff,
     )
 
 
 # Actions that are allowed to create a new database file
-_BOOTSTRAP_ACTIONS = frozenset({"bootstrap", "migrate"})
+_BOOTSTRAP_ACTIONS = frozenset({"bootstrap", "migrate:sql"})
 
 
 async def flush_changes(
@@ -166,66 +128,89 @@ class JsonlStore:
         self._current_user: str | None = None
         self._in_transaction: bool = False
         self._transaction_snapshot: dict[str, Any] | None = None
+        self._current_version: int = DBVER  # Schema version for new databases
 
     async def load(self, db_path: str | None = None) -> None:
         """Load data from JSONL change log."""
         if db_path is not None:
             self.db_path = Path(db_path)
+        if not self.db_path.exists():
+            return
+
+        # Replay change log to reconstruct state
+        data_dict: dict = {}
         try:
-            data_dict = await load_jsonl(self.db_path)
+            async with aiofiles.open(self.db_path, "rb") as f:
-            if data_dict:
+                content = await f.read()
-                # Preserve original state before migrations (deep copy for nested dicts)
+            for line_num, line in enumerate(content.split(b"\n"), 1):
-                original_dict = copy.deepcopy(data_dict)
+                line = line.strip()
-
+                if not line:
-                # Apply schema migrations (modifies data_dict in place)
+                    continue
-                migrated = apply_migrations(data_dict)
-
-                decoder = msgspec.json.Decoder(DB)
-                self.db = decoder.decode(msgspec.json.encode(data_dict))
-                self.db._store = self
-
-                # Update previous state to migrated data FIRST (to avoid transaction hardening reset)
-                self._previous_builtins = data_dict
-
-                # Persist migration by manually computing and queueing the diff
-                if migrated:
-                    diff = compute_diff(original_dict, data_dict)
-                    if diff:
-                        self._pending_changes.append(
-                            create_change_record("migrate", diff, user=None)
-                        )
-                        _logger.info("Queued migration changes for persistence")
-                    await self.flush()
-        except ValueError:
-            if self.db_path.exists():
-                raise
-
-    def _queue_change(self) -> None:
-        current = msgspec.to_builtins(self.db)
-        diff = compute_diff(self._previous_builtins, current)
-        if diff:
-            self._pending_changes.append(
-                create_change_record(self._current_action, diff, self._current_user)
-            )
-            self._previous_builtins = current
-            # Log the change with user display name if available
-            user_display = None
-            if self._current_user:
                 try:
-                    user_uuid = UUID(self._current_user)
+                    change = msgspec.json.decode(line)
-                    if user_uuid in self.db.users:
+                    data_dict = jsondiff.patch(data_dict, change["diff"], marshal=True)
-                        user_display = self.db.users[user_uuid].display_name
+                    self._current_version = change.get("v", 0)
-                except (ValueError, KeyError):
+                except Exception as e:
-                    user_display = self._current_user
+                    raise ValueError(f"Error parsing line {line_num}: {e}")
+        except (OSError, ValueError, msgspec.DecodeError) as e:
+            raise ValueError(f"Failed to load database: {e}")
 
-            diff_json = json.dumps(diff, default=str)
+        if not data_dict:
-            if user_display:
+            return
-                print(
+
-                    f"{self._current_action} by {user_display}: {diff_json}",
+        # Set previous state for diffing (will be updated by _queue_change)
-                    file=sys.stderr,
+        self._previous_builtins = copy.deepcopy(data_dict)
-                )
+
-            else:
+        # Callback to persist each migration
-                print(f"{self._current_action}: {diff_json}", file=sys.stderr)
+        async def persist_migration(
+            action: str, new_version: int, current: dict
+        ) -> None:
+            self._current_version = new_version
+            self._queue_change(action, new_version, current)
+
+        # Apply schema migrations one at a time
+        await apply_all_migrations(data_dict, self._current_version, persist_migration)
+
+        # Decode to msgspec struct
+        decoder = msgspec.json.Decoder(DB)
+        self.db = decoder.decode(msgspec.json.encode(data_dict))
+        self.db._store = self
+
+        # Normalize via msgspec round-trip (handles omit_defaults etc.)
+        # This ensures _previous_builtins matches what msgspec would produce
+        normalized_dict = msgspec.to_builtins(self.db)
+        await persist_migration(
+            "migrate:msgspec", self._current_version, normalized_dict
+        )
+
+    def _queue_change(
+        self, action: str, version: int, current: dict, user: str | None = None
+    ) -> None:
+        """Queue a change record and log it.
+
+        Args:
+            action: The action name for the change record
+            version: The schema version for the change record
+            current: The current state as a plain dict
+            user: Optional user UUID who performed the action
+        """
+        diff = compute_diff(self._previous_builtins, current)
+        if not diff:
+            return
+        self._pending_changes.append(create_change_record(action, version, diff, user))
+
+        # Log the change with user display name if available
+        user_display = None
+        if user:
+            try:
+                user_uuid = UUID(user)
+                if user_uuid in self.db.users:
+                    user_display = self.db.users[user_uuid].display_name
+            except (ValueError, KeyError):
+                user_display = user
+
+        log_change(action, diff, user_display, self._previous_builtins)
+        self._previous_builtins = copy.deepcopy(current)
 
     @contextmanager
     def transaction(
@@ -248,19 +233,19 @@ class JsonlStore:
         # Check for out-of-transaction modifications
         current_state = msgspec.to_builtins(self.db)
         if current_state != self._previous_builtins:
-            diff = compute_diff(self._previous_builtins, current_state)
+            # Allow bootstrap/migrate to create a new database from empty state
-            diff_json = json.dumps(diff, default=str, indent=2)
+            is_bootstrap = action in _BOOTSTRAP_ACTIONS or action.startswith("migrate:")
-            _logger.error(
+            if is_bootstrap and not self._previous_builtins:
-                "Database state modified outside of transaction! "
+                pass  # Expected: creating database from scratch
-                "This indicates a bug where DB changes occurred without a transaction wrapper. "
+            else:
-                "Resetting to last known state from JSONL file.\n"
+                diff = compute_diff(self._previous_builtins, current_state)
-                f"Changes detected:\n{diff_json}"
+                diff_json = msgspec.json.encode(diff).decode()
-            )
+                _logger.critical(
-            # Hard reset to last known good state
+                    "Database state modified outside of transaction! "
-            decoder = msgspec.json.Decoder(DB)
+                    "This indicates a bug where DB changes occurred without a transaction wrapper.\n"
-            self.db = decoder.decode(msgspec.json.encode(self._previous_builtins))
+                    f"Changes detected:\n{diff_json}"
-            self.db._store = self
+                )
-            current_state = self._previous_builtins.copy()
+                raise SystemExit(1)
 
         old_action = self._current_action
         old_user = self._current_user
@@ -272,7 +257,10 @@ class JsonlStore:
 
         try:
             yield
-            self._queue_change()
+            current = msgspec.to_builtins(self.db)
+            self._queue_change(
+                self._current_action, self._current_version, current, self._current_user
+            )
         except Exception:
             # Rollback on error: restore from snapshot
             _logger.warning("Transaction '%s' failed, rolling back changes", action)

paskia/db/logging.py

@@ -0,0 +1,318 @@
+"""
+Database change logging with pretty-printed diffs.
+
+Provides a logger for JSONL database changes that formats diffs
+in a human-readable path.notation style with color coding.
+"""
+
+import logging
+import re
+import sys
+from typing import Any
+
+logger = logging.getLogger("paskia.db")
+
+# Pattern to match control characters and bidirectional overrides
+_UNSAFE_CHARS = re.compile(
+    r"[\x00-\x1f\x7f-\x9f"  # C0 and C1 control characters
+    r"\u200e\u200f"  # LRM, RLM
+    r"\u202a-\u202e"  # LRE, RLE, PDF, LRO, RLO
+    r"\u2066-\u2069"  # LRI, RLI, FSI, PDI
+    r"]"
+)
+
+# ANSI color codes (matching FastAPI logging style)
+_RESET = "\033[0m"
+_DIM = "\033[2m"
+_PATH_PREFIX = "\033[1;30m"  # Dark grey for path prefix (like host in access log)
+_PATH_FINAL = "\033[0m"  # Default for final element (like path in access log)
+_DELETE = "\033[1;31m"  # Red for deletions
+_ADD = "\033[0;32m"  # Green for additions
+_ACTION = "\033[1;34m"  # Bold blue for action name
+_USER = "\033[0;34m"  # Blue for user display
+
+
+def _use_color() -> bool:
+    """Check if we should use color output."""
+    return sys.stderr.isatty()
+
+
+def _format_value(value: Any, use_color: bool, max_len: int = 60) -> str:
+    """Format a value for display, truncating if needed."""
+    if value is None:
+        return "null"
+
+    if isinstance(value, bool):
+        return "true" if value else "false"
+
+    if isinstance(value, (int, float)):
+        return str(value)
+
+    if isinstance(value, str):
+        # Filter out control characters and bidirectional overrides
+        value = _UNSAFE_CHARS.sub("", value)
+        # Truncate long strings
+        if len(value) > max_len:
+            return value[: max_len - 3] + "..."
+        return value
+
+    if isinstance(value, dict):
+        if not value:
+            return "{}"
+        # For small dicts, show inline
+        if len(value) == 1:
+            k, v = next(iter(value.items()))
+            return "{" + f"{k}: {_format_value(v, use_color, max_len=30)}" + "}"
+        return f"{{...{len(value)} keys}}"
+
+    if isinstance(value, list):
+        if not value:
+            return "[]"
+        if len(value) == 1:
+            return "[" + _format_value(value[0], use_color, max_len=30) + "]"
+        return f"[...{len(value)} items]"
+
+    # Fallback for other types
+    text = str(value)
+    if len(text) > max_len:
+        text = text[: max_len - 3] + "..."
+    return text
+
+
+def _format_path(path: list[str], use_color: bool) -> str:
+    """Format a path as dot notation with prefix in dark grey, final in default."""
+    if not path:
+        return ""
+    if not use_color:
+        return ".".join(path)
+    if len(path) == 1:
+        return f"{_PATH_FINAL}{path[0]}{_RESET}"
+    prefix = ".".join(path[:-1])
+    final = path[-1]
+    return f"{_PATH_PREFIX}{prefix}.{_RESET}{_PATH_FINAL}{final}{_RESET}"
+
+
+def _get_nested(data: dict | None, path: list[str]) -> Any:
+    """Get a nested value from a dict by path, or None if not found."""
+    if data is None:
+        return None
+    current = data
+    for key in path:
+        if not isinstance(current, dict) or key not in current:
+            return None
+        current = current[key]
+    return current
+
+
+def _collect_changes(
+    diff: dict,
+    path: list[str],
+    changes: list[tuple[str, list[str], Any]],
+    previous: dict | None,
+) -> None:
+    """
+    Recursively collect changes from a diff into a flat list.
+
+    Each change is a tuple of (change_type, path, new_value).
+    change_type is one of: 'add', 'update', 'delete'
+    """
+    if not isinstance(diff, dict):
+        # Leaf value - check if it existed before
+        existed = _get_nested(previous, path) is not None
+        changes.append(("update" if existed else "add", path, diff))
+        return
+
+    for key, value in diff.items():
+        if key == "$delete":
+            # $delete contains a list of keys to delete
+            if isinstance(value, list):
+                for deleted_key in value:
+                    changes.append(("delete", path + [str(deleted_key)], None))
+            else:
+                changes.append(("delete", path + [str(value)], None))
+
+        elif key == "$replace":
+            # $replace replaces the entire collection at this path
+            # We need to track what was added and what was deleted
+            old_collection = _get_nested(previous, path)
+            old_keys = (
+                set(old_collection.keys())
+                if isinstance(old_collection, dict)
+                else set()
+            )
+            new_keys = set(value.keys()) if isinstance(value, dict) else set()
+
+            # Items that existed before but not in new = deleted
+            for deleted_key in old_keys - new_keys:
+                changes.append(("delete", path + [str(deleted_key)], None))
+
+            # Items in new collection
+            if isinstance(value, dict):
+                for rkey, rval in value.items():
+                    existed = rkey in old_keys
+                    changes.append(
+                        ("update" if existed else "add", path + [str(rkey)], rval)
+                    )
+            elif value or not old_keys:
+                # Non-dict replacement or empty replacement with nothing before
+                changes.append(
+                    ("update" if old_collection is not None else "add", path, value)
+                )
+
+        elif key.startswith("$"):
+            # Other special operations (future-proofing)
+            changes.append(("add", path, {key: value}))
+
+        else:
+            # Regular nested key - check if this item existed before
+            new_path = path + [str(key)]
+            existed = _get_nested(previous, new_path) is not None
+            if existed:
+                # Item exists - recurse to show specific field changes
+                _collect_changes(value, new_path, changes, previous)
+            else:
+                # New item - record as add with full value, don't recurse
+                changes.append(("add", new_path, value))
+
+
+def _format_change_lines(
+    change_type: str, path: list[str], value: Any, use_color: bool
+) -> list[str]:
+    """Format a single change as one or more lines."""
+    if change_type == "delete":
+        if not use_color:
+            return [f"  {'.'.join(path)} ✗"]
+        if len(path) == 1:
+            return [f"  {_DELETE}{path[0]} ✗{_RESET}"]
+        prefix = ".".join(path[:-1])
+        final = path[-1]
+        return [f"  {_PATH_PREFIX}{prefix}.{_RESET}{_DELETE}{final} ✗{_RESET}"]
+
+    if change_type == "add":
+        # New item being created - only final element in green
+        # For dict values, show children on separate indented lines
+        if isinstance(value, dict) and value:
+            lines = []
+            # First line: path with green final element and grey =
+            if not use_color:
+                lines.append(f"  {'.'.join(path)} =")
+            elif len(path) == 1:
+                lines.append(f"  {_ADD}{path[0]}{_RESET} {_DIM}={_RESET}")
+            else:
+                prefix = ".".join(path[:-1])
+                final = path[-1]
+                lines.append(
+                    f"  {_PATH_PREFIX}{prefix}.{_RESET}{_ADD}{final}{_RESET} {_DIM}={_RESET}"
+                )
+            # Child lines: indented key: value, with aligned values
+            max_key_len = max(len(k) for k in value.keys())
+            field_width = max(max_key_len, 12)  # minimum 12 chars
+            for k, v in value.items():
+                v_str = _format_value(v, use_color)
+                padding = " " * (field_width - len(k))
+                if use_color:
+                    lines.append(f"    {k}{_DIM}:{_RESET}{padding} {v_str}")
+                else:
+                    lines.append(f"    {k}:{padding} {v_str}")
+            return lines
+        else:
+            value_str = _format_value(value, use_color)
+            if not use_color:
+                return [f"  {'.'.join(path)} = {value_str}"]
+            if len(path) == 1:
+                return [f"  {_ADD}{path[0]}{_RESET} {_DIM}={_RESET} {value_str}"]
+            prefix = ".".join(path[:-1])
+            final = path[-1]
+            return [
+                f"  {_PATH_PREFIX}{prefix}.{_RESET}{_ADD}{final}{_RESET} {_DIM}={_RESET} {value_str}"
+            ]
+
+    # update: Existing item being updated - normal path colors
+    value_str = _format_value(value, use_color)
+    path_str = _format_path(path, use_color)
+    if use_color:
+        return [f"  {path_str} {_DIM}={_RESET} {value_str}"]
+    return [f"  {path_str} = {value_str}"]
+
+
+def format_diff(diff: dict, previous: dict | None = None) -> list[str]:
+    """
+    Format a JSON diff as human-readable lines.
+
+    Args:
+        diff: The JSON diff dict
+        previous: The previous state dict (for determining add vs update)
+
+    Returns a list of formatted lines (without newlines).
+    Single changes return one line, multiple changes return multiple lines.
+    """
+    use_color = _use_color()
+    changes: list[tuple[str, list[str], Any]] = []
+    _collect_changes(diff, [], changes, previous)
+
+    if not changes:
+        return []
+
+    # Format each change
+    lines = []
+    for change_type, path, value in changes:
+        lines.extend(_format_change_lines(change_type, path, value, use_color))
+
+    return lines
+
+
+def format_action_header(action: str, user_display: str | None = None) -> str:
+    """Format the action header line."""
+    use_color = _use_color()
+
+    if use_color:
+        action_str = f"{_ACTION}{action}{_RESET}"
+        if user_display:
+            user_str = f"{_USER}{user_display}{_RESET}"
+            return f"{action_str} by {user_str}"
+        return action_str
+    else:
+        if user_display:
+            return f"{action} by {user_display}"
+        return action
+
+
+def log_change(
+    action: str,
+    diff: dict,
+    user_display: str | None = None,
+    previous: dict | None = None,
+) -> None:
+    """
+    Log a database change with pretty-printed diff.
+
+    Args:
+        action: The action name (e.g., "login", "admin:delete_user")
+        diff: The JSON diff dict
+        user_display: Optional display name of the user who performed the action
+        previous: The previous state dict (for determining add vs update)
+    """
+    header = format_action_header(action, user_display)
+    diff_lines = format_diff(diff, previous)
+
+    if not diff_lines:
+        logger.info(header)
+        return
+
+    if len(diff_lines) == 1:
+        # Single change - combine on one line
+        logger.info(f"{header}{diff_lines[0]}")
+    else:
+        # Multiple changes - header on its own line, then changes
+        logger.info(header)
+        for line in diff_lines:
+            logger.info(line)
+
+
+def configure_db_logging() -> None:
+    """Configure the database logger to output to stderr without prefix."""
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    logger.propagate = False

paskia/db/migrations.py

@@ -5,30 +5,29 @@ Migrations are applied during database load based on the version field.
 Each migration should be idempotent and only run when needed.
 """
 
-import logging
+from collections.abc import Awaitable, Callable
-
-_logger = logging.getLogger(__name__)
 
 
-def apply_migrations(data_dict: dict) -> bool:
+def migrate_v1(d: dict) -> None:
-    """Apply any pending schema migrations to the database dictionary.
+    """Remove Org.created_at fields."""
+    for org_data in d["orgs"].values():
+        org_data.pop("created_at", None)
 
-    Args:
-        data_dict: The raw database dictionary loaded from JSONL
 
-    Returns:
+migrations = sorted(
-        True if any migrations were applied, False otherwise
+    [f for n, f in globals().items() if n.startswith("migrate_v")],
-    """
+    key=lambda f: int(f.__name__.removeprefix("migrate_v")),
-    db_version = data_dict.get("v", 0)
+)
-    migrated = False
 
-    if db_version == 0:
+DBVER = len(migrations)  # Used by bootstrap and migrate:sql to set initial version
-        # Migration v0 -> v1: Remove created_at from orgs (field removed from schema)
-        if "orgs" in data_dict:
-            for org_data in data_dict["orgs"].values():
-                org_data.pop("created_at", None)
-        data_dict["v"] = 1
-        migrated = True
-        _logger.info("Applied schema migration: v0 -> v1 (removed org.created_at)")
 
-    return migrated
+
+async def apply_all_migrations(
+    data_dict: dict,
+    current_version: int,
+    persist: Callable[[str, int, dict], Awaitable[None]],
+) -> None:
+    while current_version < DBVER:
+        migrations[current_version](data_dict)
+        current_version += 1
+        await persist(f"migrate:v{current_version}", current_version, data_dict)

paskia/db/operations.py

@@ -2,7 +2,7 @@
 Database for WebAuthn passkey authentication.
 
 Read operations: Access _db directly, use build_* helpers to get public structs.
-Context lookup: get_session_context() returns full SessionContext with effective permissions.
+Context lookup: _db.session_ctx() returns full SessionContext with effective permissions.
 Write operations: Functions that validate and commit, or raise ValueError.
 """
 
@@ -10,7 +10,7 @@ import hashlib
 import logging
 import os
 import secrets
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from uuid import UUID
 
 import uuid7
@@ -31,7 +31,6 @@ from paskia.db.structs import (
     SessionContext,
     User,
 )
-from paskia.util.hostutil import normalize_host
 from paskia.util.passphrase import generate as generate_passphrase
 from paskia.util.passphrase import is_well_formed as _is_passphrase
 
@@ -69,21 +68,18 @@ def get_user_organization(user_uuid: UUID) -> tuple[Org, str]:
     Raises ValueError if user not found.
 
     Call sites:
-    - Get user's organization when updating user role (admin.py:493)
+    - update_user_role_in_organization: org only
-    - Get user's organization for user credential listing (admin.py:530)
+    - admin_create_user_registration_link: org only
-    - Get user's organization for user details API (admin.py:579)
+    - admin_get_user_detail: org and role
-    - Get user's organization for updating user display name (admin.py:721)
+    - admin_update_user_display_name: org only
-    - Get user's organization for deleting user credential (admin.py:754)
+    - admin_delete_user_credential: org only
-    - Get user's organization for deleting user session (admin.py:783)
+    - admin_delete_user_session: org only
     """
     if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
-    role_uuid = _db.users[user_uuid].role
+    user = _db.users[user_uuid]
-    if role_uuid not in _db.roles:
+    role = user.role
-        raise ValueError(f"Role {role_uuid} not found")
+    return role.org, role.display_name
-    role_data = _db.roles[role_uuid]
-    org_uuid = role_data.org
-    return _db.orgs[org_uuid], role_data.display_name
 
 
 def get_organization_users(org_uuid: UUID) -> list[tuple[User, str]]:
@@ -91,10 +87,8 @@ def get_organization_users(org_uuid: UUID) -> list[tuple[User, str]]:
 
     Returns list of (User, role_display_name) tuples.
     """
-    role_map = {
+    org = _db.orgs[org_uuid]
-        rid: r.display_name for rid, r in _db.roles.items() if r.org == org_uuid
+    return [(u, u.role.display_name) for role in org.roles for u in role.users]
-    }
-    return [(u, role_map[u.role]) for u in _db.users.values() if u.role in role_map]
 
 
 def get_user_credential_ids(user_uuid: UUID) -> list[bytes]:
@@ -102,7 +96,8 @@ def get_user_credential_ids(user_uuid: UUID) -> list[bytes]:
 
     Returns empty list if user has no credentials.
     """
-    return [c.credential_id for c in _db.credentials.values() if c.user == user_uuid]
+    assert user_uuid
+    return [c.credential_id for c in _db.users[user_uuid].credentials]
 
 
 def _reset_key(passphrase: str) -> bytes:
@@ -126,92 +121,6 @@ def get_reset_token(passphrase: str) -> ResetToken | None:
     return _db.reset_tokens.get(key)
 
 
-# -------------------------------------------------------------------------
-# Context lookup
-# -------------------------------------------------------------------------
-
-
-def get_session_context(
-    session_key: str, host: str | None = None
-) -> SessionContext | None:
-    """Get full session context with effective permissions.
-
-    Args:
-        session_key: The session key string
-        host: Optional host for binding/validation and domain-scoped permissions
-
-    Returns:
-        SessionContext if valid, None if session not found, expired, or host mismatch
-
-    Call sites:
-    - Example usage in docstring (db/__init__.py:16)
-    - Get session context from auth token (util/permutil.py:43)
-    """
-
-    if session_key not in _db.sessions:
-        return None
-
-    s = _db.sessions[session_key]
-    if s.expiry < datetime.now(timezone.utc):
-        return None
-
-    # Validate host matches (sessions are always created with a host)
-    if host is not None and s.host != host:
-        # Session bound to different host
-        return None
-
-    # Validate user exists
-    if s.user not in _db.users:
-        return None
-
-    # Validate role exists
-    role_uuid = _db.users[s.user].role
-    if role_uuid not in _db.roles:
-        return None
-
-    # Validate org exists
-    org_uuid = _db.roles[role_uuid].org
-    if org_uuid not in _db.orgs:
-        return None
-
-    session = _db.sessions[session_key]
-    user = _db.users[s.user]
-    role = _db.roles[role_uuid]
-    org = _db.orgs[org_uuid]
-
-    # Credential must exist (sessions are cascade-deleted when credential is deleted)
-    if s.credential not in _db.credentials:
-        return None
-    credential = _db.credentials[s.credential]
-
-    # Effective permissions: role's permissions that the org can grant
-    # Also filter by domain if host is provided
-    org_perm_uuids = {pid for pid, p in _db.permissions.items() if org_uuid in p.orgs}
-    normalized_host = normalize_host(host)
-    host_without_port = normalized_host.rsplit(":", 1)[0] if normalized_host else None
-
-    effective_perms = []
-    for perm_uuid in role.permission_set:
-        if perm_uuid not in org_perm_uuids:
-            continue
-        if perm_uuid not in _db.permissions:
-            continue
-        p = _db.permissions[perm_uuid]
-        # Check domain restriction
-        if p.domain is not None and p.domain != host_without_port:
-            continue
-        effective_perms.append(_db.permissions[perm_uuid])
-
-    return SessionContext(
-        session=session,
-        user=user,
-        org=org,
-        role=role,
-        credential=credential,
-        permissions=effective_perms,
-    )
-
-
 # -------------------------------------------------------------------------
 # Write operations (validate, modify, commit or raise ValueError)
 # -------------------------------------------------------------------------
@@ -264,9 +173,9 @@ def create_org(org: Org, *, ctx: SessionContext | None = None) -> None:
     if org.uuid in _db.orgs:
         raise ValueError(f"Organization {org.uuid} already exists")
     with _db.transaction("admin:create_org", ctx):
-        new_org = Org(display_name=org.display_name)
+        new_org = Org.create(display_name=org.display_name)
-        _db.orgs[org.uuid] = new_org
         new_org.uuid = org.uuid
+        _db.orgs[org.uuid] = new_org
         # Create Administration role with org admin permission
 
         admin_role_uuid = uuid7.create()
@@ -278,7 +187,7 @@ def create_org(org: Org, *, ctx: SessionContext | None = None) -> None:
                 break
         role_permissions = {org_admin_perm_uuid: True} if org_admin_perm_uuid else {}
         admin_role = Role(
-            org=org.uuid,
+            org_uuid=org.uuid,
             display_name="Administration",
             permissions=role_permissions,
         )
@@ -304,17 +213,15 @@ def delete_org(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     if uuid not in _db.orgs:
         raise ValueError(f"Organization {uuid} not found")
     with _db.transaction("admin:delete_org", ctx):
+        org = _db.orgs[uuid]
         # Remove org from all permissions
         for p in _db.permissions.values():
             p.orgs.pop(uuid, None)
-        # Delete roles in this org
+        # Delete roles in this org and their users
-        role_uuids = [rid for rid, r in _db.roles.items() if r.org == uuid]
+        for role in org.roles:
-        for rid in role_uuids:
+            for user in role.users:
-            del _db.roles[rid]
+                del _db.users[user.uuid]
-        # Delete users with those roles
+            del _db.roles[role.uuid]
-        user_uuids = [uid for uid, u in _db.users.items() if u.role in role_uuids]
-        for uid in user_uuids:
-            del _db.users[uid]
         del _db.orgs[uuid]
 
 
@@ -356,8 +263,8 @@ def create_role(role: Role, *, ctx: SessionContext | None = None) -> None:
     """Create a new role."""
     if role.uuid in _db.roles:
         raise ValueError(f"Role {role.uuid} already exists")
-    if role.org not in _db.orgs:
+    if role.org_uuid not in _db.orgs:
-        raise ValueError(f"Organization {role.org} not found")
+        raise ValueError(f"Organization {role.org_uuid} not found")
     with _db.transaction("admin:create_role", ctx):
         _db.roles[role.uuid] = role
 
@@ -408,7 +315,8 @@ def delete_role(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     if uuid not in _db.roles:
         raise ValueError(f"Role {uuid} not found")
     # Check no users have this role
-    if any(u.role == uuid for u in _db.users.values()):
+    role = _db.roles[uuid]
+    if role.users:
         raise ValueError(f"Cannot delete role {uuid}: users still assigned")
     with _db.transaction("admin:delete_role", ctx):
         del _db.roles[uuid]
@@ -418,8 +326,8 @@ def create_user(new_user: User, *, ctx: SessionContext | None = None) -> None:
     """Create a new user."""
     if new_user.uuid in _db.users:
         raise ValueError(f"User {new_user.uuid} already exists")
-    if new_user.role not in _db.roles:
+    if new_user.role_uuid not in _db.roles:
-        raise ValueError(f"Role {new_user.role} not found")
+        raise ValueError(f"Role {new_user.role_uuid} not found")
     with _db.transaction("admin:create_user", ctx):
         _db.users[new_user.uuid] = new_user
 
@@ -444,6 +352,23 @@ def update_user_display_name(
         _db.users[uuid].display_name = display_name
 
 
+def update_user_theme(
+    uuid: UUID,
+    theme: str,
+    *,
+    ctx: SessionContext | None = None,
+) -> None:
+    """Update user theme preference ('' for auto, 'light', 'dark')."""
+    if isinstance(uuid, str):
+        uuid = UUID(uuid)
+    if uuid not in _db.users:
+        raise ValueError(f"User {uuid} not found")
+    if theme not in ("", "light", "dark"):
+        raise ValueError(f"Invalid theme: {theme}")
+    with _db.transaction("update_user_theme", ctx):
+        _db.users[uuid].theme = theme
+
+
 def update_user_role(
     uuid: UUID,
     role_uuid: UUID,
@@ -456,7 +381,7 @@ def update_user_role(
     if role_uuid not in _db.roles:
         raise ValueError(f"Role {role_uuid} not found")
     with _db.transaction("admin:update_user_role", ctx):
-        _db.users[uuid].role = role_uuid
+        _db.users[uuid].role_uuid = role_uuid
 
 
 def update_user_role_in_organization(
@@ -468,39 +393,35 @@ def update_user_role_in_organization(
     """Update user's role by role name within their current organization."""
     if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
-    current_role_uuid = _db.users[user_uuid].role
+    user = _db.users[user_uuid]
-    if current_role_uuid not in _db.roles:
+    org = user.org
-        raise ValueError("Current role not found")
-    org_uuid = _db.roles[current_role_uuid].org
     # Find role by name in the same org
     new_role_uuid = None
-    for rid, r in _db.roles.items():
+    for r in org.roles:
-        if r.org == org_uuid and r.display_name == role_name:
+        if r.display_name == role_name:
-            new_role_uuid = rid
+            new_role_uuid = r.uuid
             break
     if new_role_uuid is None:
         raise ValueError(f"Role '{role_name}' not found in organization")
     with _db.transaction("admin:update_user_role", ctx):
-        _db.users[user_uuid].role = new_role_uuid
+        _db.users[user_uuid].role_uuid = new_role_uuid
 
 
 def delete_user(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
     """Delete user and their credentials/sessions."""
     if uuid not in _db.users:
         raise ValueError(f"User {uuid} not found")
+    user = _db.users[uuid]
     with _db.transaction("admin:delete_user", ctx):
         # Delete credentials
-        cred_uuids = [cid for cid, c in _db.credentials.items() if c.user == uuid]
+        for cred in user.credentials:
-        for cid in cred_uuids:
+            del _db.credentials[cred.uuid]
-            del _db.credentials[cid]
         # Delete sessions
-        sess_keys = [k for k, s in _db.sessions.items() if s.user == uuid]
+        for sess in user.sessions:
-        for k in sess_keys:
+            del _db.sessions[sess.key]
-            del _db.sessions[k]
         # Delete reset tokens
-        token_keys = [k for k, t in _db.reset_tokens.items() if t.user == uuid]
+        for token in user.reset_tokens:
-        for k in token_keys:
+            del _db.reset_tokens[token.key]
-            del _db.reset_tokens[k]
         del _db.users[uuid]
 
 
@@ -508,8 +429,8 @@ def create_credential(cred: Credential, *, ctx: SessionContext | None = None) ->
     """Create a new credential."""
     if cred.uuid in _db.credentials:
         raise ValueError(f"Credential {cred.uuid} already exists")
-    if cred.user not in _db.users:
+    if cred.user_uuid not in _db.users:
-        raise ValueError(f"User {cred.user} not found")
+        raise ValueError(f"User {cred.user_uuid} not found")
     with _db.transaction("create_credential", ctx):
         _db.credentials[cred.uuid] = cred
 
@@ -542,20 +463,19 @@ def delete_credential(
     """
     if uuid not in _db.credentials:
         raise ValueError(f"Credential {uuid} not found")
+    cred = _db.credentials[uuid]
     if user_uuid is not None:
-        cred_user = _db.credentials[uuid].user
+        if cred.user_uuid != user_uuid:
-        if cred_user != user_uuid:
             raise ValueError(f"Credential {uuid} does not belong to user {user_uuid}")
     with _db.transaction("delete_credential", ctx):
         # Delete all sessions using this credential
-        keys = [k for k, s in _db.sessions.items() if s.credential == uuid]
+        for sess in cred.sessions:
-        for k in keys:
+            print(sess, repr(sess.key))
-            del _db.sessions[k]
+            del _db.sessions[sess.key]
         del _db.credentials[uuid]
 
 
 def create_session(
-    key: str,
     user_uuid: UUID,
     credential_uuid: UUID,
     host: str,
@@ -564,23 +484,25 @@ def create_session(
     expiry: datetime,
     *,
     ctx: SessionContext | None = None,
-) -> None:
+) -> str:
-    """Create a new session."""
+    """Create a new session. Returns the session key."""
-    if key in _db.sessions:
-        raise ValueError("Session already exists")
     if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
     if credential_uuid not in _db.credentials:
         raise ValueError(f"Credential {credential_uuid} not found")
+    session = Session.create(
+        user=user_uuid,
+        credential=credential_uuid,
+        host=host,
+        ip=ip,
+        user_agent=user_agent,
+        expiry=expiry,
+    )
+    if session.key in _db.sessions:
+        raise ValueError("Session already exists")
     with _db.transaction("create_session", ctx):
-        _db.sessions[key] = Session(
+        _db.sessions[session.key] = session
-            user=user_uuid,
+    return session.key
-            credential=credential_uuid,
-            host=host,
-            ip=ip,
-            user_agent=user_agent,
-            expiry=expiry,
-        )
 
 
 def update_session(
@@ -612,16 +534,18 @@ def set_session_host(key: str, host: str, *, ctx: SessionContext | None = None)
     update_session(key, host=host, ctx=ctx)
 
 
-def delete_session(key: str, *, ctx: SessionContext | None = None) -> None:
+def delete_session(
+    key: str, *, ctx: SessionContext | None = None, action: str = "delete_session"
+) -> None:
     """Delete a session.
 
     The acting user should be logged via ctx.
-    For user logout, pass ctx of the user's session.
+    For user logout, pass ctx of the user's session and action="logout".
     For admin terminating a session, pass admin's ctx.
     """
     if key not in _db.sessions:
         raise ValueError("Session not found")
-    with _db.transaction("delete_session", ctx):
+    with _db.transaction(action, ctx):
         del _db.sessions[key]
 
 
@@ -634,10 +558,12 @@ def delete_sessions_for_user(
     For user logout-all, pass ctx of the user's session.
     For admin bulk termination, pass admin's ctx.
     """
+    user = _db.users.get(user_uuid)
+    if not user:
+        return
     with _db.transaction("admin:delete_sessions_for_user", ctx):
-        keys = [k for k, s in _db.sessions.items() if s.user == user_uuid]
+        for sess in user.sessions:
-        for k in keys:
+            del _db.sessions[sess.key]
-            del _db.sessions[k]
 
 
 def create_reset_token(
@@ -647,6 +573,7 @@ def create_reset_token(
     token_type: str,
     *,
     ctx: SessionContext | None = None,
+    user: str | None = None,
 ) -> None:
     """Create a reset token from a passphrase.
 
@@ -654,15 +581,16 @@ def create_reset_token(
     For self-service (user creating own recovery link), pass user's ctx.
     For admin operations, pass admin's ctx.
     For system operations (bootstrap), pass neither to log no user.
+    For API operations where ctx is not available but user is known, pass user.
     """
     key = _reset_key(passphrase)
     if key in _db.reset_tokens:
         raise ValueError("Reset token already exists")
     if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
-    with _db.transaction("create_reset_token", ctx):
+    with _db.transaction("create_reset_token", ctx, user=user):
         _db.reset_tokens[key] = ResetToken(
-            user=user_uuid, expiry=expiry, token_type=token_type
+            user_uuid=user_uuid, expiry=expiry, token_type=token_type
         )
 
 
@@ -681,7 +609,7 @@ def delete_reset_token(key: bytes, *, ctx: SessionContext | None = None) -> None
 
 def cleanup_expired() -> int:
     """Remove expired sessions and reset tokens. Returns count removed."""
-    now = datetime.now(timezone.utc)
+    now = datetime.now(UTC)
     count = 0
     with _db.transaction("expiry"):
         expired_sessions = [k for k, s in _db.sessions.items() if s.expiry < now]
@@ -726,13 +654,20 @@ def login(
     """
     if isinstance(user_uuid, str):
         user_uuid = UUID(user_uuid)
-    now = datetime.now(timezone.utc)
+    now = datetime.now(UTC)
     if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
     if credential_uuid not in _db.credentials:
         raise ValueError(f"Credential {credential_uuid} not found")
 
-    session_key = _create_token()
+    session = Session.create(
+        user=user_uuid,
+        credential=credential_uuid,
+        host=host,
+        ip=ip,
+        user_agent=user_agent,
+        expiry=expiry,
+    )
     user_str = str(user_uuid)
     with _db.transaction("login", user=user_str):
         # Update user
@@ -742,15 +677,8 @@ def login(
         _db.credentials[credential_uuid].sign_count = sign_count
         _db.credentials[credential_uuid].last_used = now
         # Create session
-        _db.sessions[session_key] = Session(
+        _db.sessions[session.key] = session
-            user=user_uuid,
+    return session.key
-            credential=credential_uuid,
-            host=host,
-            ip=ip,
-            user_agent=user_agent,
-            expiry=expiry,
-        )
-    return session_key
 
 
 def create_credential_session(
@@ -773,13 +701,20 @@ def create_credential_session(
     Returns the generated session token.
     """
 
-    now = datetime.now(timezone.utc)
+    now = datetime.now(UTC)
     expiry = now + SESSION_LIFETIME
-    session_key = _create_token()
 
     if user_uuid not in _db.users:
         raise ValueError(f"User {user_uuid} not found")
 
+    session = Session.create(
+        user=user_uuid,
+        credential=credential.uuid,
+        host=host,
+        ip=ip,
+        user_agent=user_agent,
+        expiry=expiry,
+    )
     user_str = str(user_uuid)
     with _db.transaction("create_credential_session", user=user_str):
         # Update display name if provided
@@ -790,20 +725,13 @@ def create_credential_session(
         _db.credentials[credential.uuid] = credential
 
         # Create session
-        _db.sessions[session_key] = Session(
+        _db.sessions[session.key] = session
-            user=user_uuid,
-            credential=credential.uuid,
-            host=host,
-            ip=ip,
-            user_agent=user_agent,
-            expiry=expiry,
-        )
 
         # Delete reset token if provided
         if reset_key:
             if reset_key in _db.reset_tokens:
                 del _db.reset_tokens[reset_key]
-    return session_key
+    return session.key
 
 
 # -------------------------------------------------------------------------
@@ -862,7 +790,7 @@ def bootstrap(
         reset_expiry = reset_expires()
     reset_key = _reset_key(reset_passphrase)
 
-    now = datetime.now(timezone.utc)
+    now = datetime.now(UTC)
 
     with _db.transaction("bootstrap"):
         # Create auth:admin permission
@@ -884,13 +812,13 @@ def bootstrap(
         _db.permissions[perm_org_admin_uuid] = perm_org_admin
 
         # Create organization
-        new_org = Org(display_name=org_name)
+        new_org = Org.create(display_name=org_name)
         new_org.uuid = org_uuid
         _db.orgs[org_uuid] = new_org
 
         # Create Administration role with both permissions
         admin_role = Role(
-            org=org_uuid,
+            org_uuid=org_uuid,
             display_name="Administration",
             permissions={perm_admin_uuid: True, perm_org_admin_uuid: True},
         )
@@ -900,7 +828,7 @@ def bootstrap(
         # Create admin user
         admin_user = User(
             display_name=admin_name,
-            role=role_uuid,
+            role_uuid=role_uuid,
             created_at=now,
             last_seen=None,
             visits=0,
@@ -910,7 +838,7 @@ def bootstrap(
 
         # Create reset token
         _db.reset_tokens[reset_key] = ResetToken(
-            user=user_uuid,
+            user_uuid=user_uuid,
             expiry=reset_expiry,
             token_type="admin bootstrap",
         )

paskia/db/structs.py

@@ -1,9 +1,15 @@
-from datetime import datetime, timezone
+from __future__ import annotations
+
+import secrets
+from datetime import UTC, datetime
 from uuid import UUID
 
 import msgspec
 import uuid7
 
+from paskia import db
+from paskia.util.hostutil import normalize_host
+
 # Sentinel for uuid fields before they are set by create() or DB post init
 _UUID_UNSET = UUID(int=0)
 
@@ -22,20 +28,30 @@ class Permission(msgspec.Struct, dict=True, omit_defaults=True):
     orgs: dict[UUID, bool] = {}  # org_uuid -> True (which orgs can grant this)
 
     def __post_init__(self):
-        self.uuid: UUID = _UUID_UNSET  # Convenience field, not serialized
+        if not hasattr(self, "uuid"):
+            self.uuid: UUID = _UUID_UNSET
 
     @property
     def org_set(self) -> set[UUID]:
         """Get orgs that can grant this permission as a set."""
         return set(self.orgs.keys())
 
+    @property
+    def orgs_list(self) -> list[Org]:
+        """Get list of Org objects that can grant this permission."""
+        return [
+            db.data().orgs[org_uuid]
+            for org_uuid in self.orgs.keys()
+            if org_uuid in db.data().orgs
+        ]
+
     @classmethod
     def create(
         cls,
         scope: str,
         display_name: str,
         domain: str | None = None,
-    ) -> "Permission":
+    ) -> Permission:
         """Create a new Permission with auto-generated uuid7."""
         perm = cls(
             scope=scope,
@@ -46,36 +62,84 @@ class Permission(msgspec.Struct, dict=True, omit_defaults=True):
         return perm
 
 
+class Org(msgspec.Struct, dict=True):
+    """Organization data structure."""
+
+    display_name: str
+
+    def __post_init__(self):
+        if not hasattr(self, "uuid"):
+            self.uuid: UUID = _UUID_UNSET
+
+    @property
+    def roles(self) -> list[Role]:
+        """Get all roles that belong to this organization."""
+        return [r for r in db.data().roles.values() if r.org_uuid == self.uuid]
+
+    @property
+    def permissions(self) -> list[Permission]:
+        """Get all permissions that this organization can grant."""
+        return [p for p in db.data().permissions.values() if self.uuid in p.orgs]
+
+    @classmethod
+    def create(cls, display_name: str) -> Org:
+        """Create a new Org with auto-generated uuid7."""
+        org = cls(display_name=display_name)
+        org.uuid = uuid7.create()
+        return org
+
+
 class Role(msgspec.Struct, dict=True, omit_defaults=True):
     """Role data structure.
 
     Mutable fields: display_name, permissions
-    Immutable fields: org (set at creation, never modified)
+    Immutable fields: org_uuid (set at creation, never modified)
     uuid is generated at creation.
     """
 
-    org: UUID
+    org_uuid: UUID = msgspec.field(name="org")
     display_name: str
     permissions: dict[UUID, bool] = {}  # permission_uuid -> True
 
     def __post_init__(self):
-        self.uuid: UUID = _UUID_UNSET  # Convenience field, not serialized
+        if not hasattr(self, "uuid"):
+            self.uuid: UUID = _UUID_UNSET
 
     @property
     def permission_set(self) -> set[UUID]:
         """Get permissions as a set of UUIDs."""
         return set(self.permissions.keys())
 
+    @property
+    def permissions_list(self) -> list[Permission]:
+        """Get list of Permission objects for this role."""
+        return [
+            db.data().permissions[perm_uuid]
+            for perm_uuid in self.permissions.keys()
+            if perm_uuid in db.data().permissions
+        ]
+
+    @property
+    def org(self) -> Org:
+        """Get the organization object this role belongs to."""
+        return db.data().orgs[self.org_uuid]
+
+    @property
+    def users(self) -> list[User]:
+        """Get all users that have this role."""
+        return [u for u in db.data().users.values() if u.role_uuid == self.uuid]
+
     @classmethod
     def create(
         cls,
-        org: UUID,
+        org: UUID | Org,
         display_name: str,
         permissions: set[UUID] | None = None,
-    ) -> "Role":
+    ) -> Role:
         """Create a new Role with auto-generated uuid7."""
+        org_uuid = org if isinstance(org, UUID) else org.uuid
         role = cls(
-            org=org,
+            org_uuid=org_uuid,
             display_name=display_name,
             permissions={p: True for p in (permissions or set())},
         )
@@ -83,52 +147,63 @@ class Role(msgspec.Struct, dict=True, omit_defaults=True):
         return role
 
 
-class Org(msgspec.Struct, dict=True):
+class User(msgspec.Struct, dict=True, omit_defaults=True):
-    """Organization data structure."""
-
-    display_name: str
-
-    def __post_init__(self):
-        self.uuid: UUID = _UUID_UNSET  # Convenience field, not serialized
-
-    @classmethod
-    def create(cls, display_name: str) -> "Org":
-        """Create a new Org with auto-generated uuid7."""
-        org = cls(display_name=display_name)
-        org.uuid = uuid7.create()
-        return org
-
-
-class User(msgspec.Struct, dict=True):
     """User data structure.
 
-    Mutable fields: display_name, role, last_seen, visits
+    Mutable fields: display_name, role_uuid, last_seen, visits, theme
     Immutable fields: created_at (set at creation, never modified)
     uuid is derived from created_at using uuid7.
     """
 
     display_name: str
-    role: UUID
+    role_uuid: UUID = msgspec.field(name="role")
     created_at: datetime
     last_seen: datetime | None = None
     visits: int = 0
+    theme: str = ""  # "" or "auto" = OS default, "light", "dark"
 
     def __post_init__(self):
-        self.uuid: UUID = _UUID_UNSET  # Convenience field, not serialized
+        if not hasattr(self, "uuid"):
+            self.uuid: UUID = _UUID_UNSET
+
+    @property
+    def role(self) -> Role:
+        """Get the role object this user has."""
+        return db.data().roles[self.role_uuid]
+
+    @property
+    def org(self) -> Org:
+        """Get the organization this user belongs to (via role)."""
+        return self.role.org
+
+    @property
+    def credentials(self) -> list[Credential]:
+        """Get all credentials for this user."""
+        return [c for c in db.data().credentials.values() if c.user_uuid == self.uuid]
+
+    @property
+    def sessions(self) -> list[Session]:
+        """Get all sessions for this user."""
+        return [s for s in db.data().sessions.values() if s.user_uuid == self.uuid]
+
+    @property
+    def reset_tokens(self) -> list[ResetToken]:
+        """Get all reset tokens for this user."""
+        return [t for t in db.data().reset_tokens.values() if t.user_uuid == self.uuid]
 
     @classmethod
     def create(
         cls,
         display_name: str,
-        role: UUID,
+        role: UUID | Role,
         created_at: datetime | None = None,
-    ) -> "User":
+    ) -> User:
         """Create a new User with auto-generated uuid7."""
-
+        role_uuid = role if isinstance(role, UUID) else role.uuid
         user = cls(
             display_name=display_name,
-            role=role,
+            role_uuid=role_uuid,
-            created_at=created_at or datetime.now(timezone.utc),
+            created_at=created_at or datetime.now(UTC),
         )
         user.uuid = uuid7.create(user.created_at)
         return user
@@ -143,7 +218,7 @@ class Credential(msgspec.Struct, dict=True):
     """
 
     credential_id: bytes  # Long binary ID from the authenticator
-    user: UUID
+    user_uuid: UUID = msgspec.field(name="user")
     aaguid: UUID
     public_key: bytes
     sign_count: int
@@ -152,23 +227,37 @@ class Credential(msgspec.Struct, dict=True):
     last_verified: datetime | None = None
 
     def __post_init__(self):
-        self.uuid: UUID = _UUID_UNSET  # Convenience field, not serialized
+        if not hasattr(self, "uuid"):
+            self.uuid: UUID = _UUID_UNSET
+
+    @property
+    def user(self) -> User:
+        """Get the User object for this credential."""
+        return db.data().users[self.user_uuid]
+
+    @property
+    def sessions(self) -> list[Session]:
+        """Get all sessions using this credential."""
+        return [
+            s for s in db.data().sessions.values() if s.credential_uuid == self.uuid
+        ]
 
     @classmethod
     def create(
         cls,
         credential_id: bytes,
-        user: UUID,
+        user: UUID | User,
         aaguid: UUID,
         public_key: bytes,
         sign_count: int,
         created_at: datetime | None = None,
-    ) -> "Credential":
+    ) -> Credential:
         """Create a new Credential with auto-generated uuid7."""
-        now = created_at or datetime.now(timezone.utc)
+        user_uuid = user if isinstance(user, UUID) else user.uuid
+        now = created_at or datetime.now(UTC)
         cred = cls(
             credential_id=credential_id,
-            user=user,
+            user_uuid=user_uuid,
             aaguid=aaguid,
             public_key=public_key,
             sign_count=sign_count,
@@ -184,19 +273,30 @@ class Session(msgspec.Struct, dict=True):
     """Session data structure.
 
     Mutable fields: expiry (updated on session refresh)
-    Immutable fields: user, credential, host, ip, user_agent
+    Immutable fields: user_uuid, credential_uuid, host, ip, user_agent
     key is stored in the dict key, not in the struct.
     """
 
-    user: UUID
+    user_uuid: UUID = msgspec.field(name="user")
-    credential: UUID
+    credential_uuid: UUID = msgspec.field(name="credential")
     host: str
     ip: str
     user_agent: str
     expiry: datetime
 
     def __post_init__(self):
-        self.key: str = ""  # Convenience field, not serialized
+        if not hasattr(self, "key"):
+            self.key: str = ""
+
+    @property
+    def user(self) -> User:
+        """Get the User object for this session."""
+        return db.data().users[self.user_uuid]
+
+    @property
+    def credential(self) -> Credential:
+        """Get the Credential object for this session."""
+        return db.data().credentials[self.credential_uuid]
 
     def metadata(self) -> dict:
         """Return session metadata for backwards compatibility."""
@@ -206,6 +306,32 @@ class Session(msgspec.Struct, dict=True):
             "expiry": self.expiry.isoformat(),
         }
 
+    @classmethod
+    def create(
+        cls,
+        user: UUID | User,
+        credential: UUID | Credential,
+        host: str,
+        ip: str,
+        user_agent: str,
+        expiry: datetime,
+    ) -> Session:
+        """Create a new Session with auto-generated key."""
+        user_uuid = user if isinstance(user, UUID) else user.uuid
+        credential_uuid = (
+            credential if isinstance(credential, UUID) else credential.uuid
+        )
+        session = cls(
+            user_uuid=user_uuid,
+            credential_uuid=credential_uuid,
+            host=host,
+            ip=ip,
+            user_agent=user_agent,
+            expiry=expiry,
+        )
+        session.key = secrets.token_urlsafe(12)
+        return session
+
 
 class ResetToken(msgspec.Struct, dict=True):
     """Reset/device-addition token data structure.
@@ -214,12 +340,18 @@ class ResetToken(msgspec.Struct, dict=True):
     key is stored in the dict key, not in the struct.
     """
 
-    user: UUID
+    user_uuid: UUID = msgspec.field(name="user")
     expiry: datetime
     token_type: str
 
     def __post_init__(self):
-        self.key: bytes = b""  # Convenience field, not serialized
+        if not hasattr(self, "key"):
+            self.key: bytes = b""
+
+    @property
+    def user(self) -> User:
+        """Get the User object for this reset token."""
+        return db.data().users[self.user_uuid]
 
 
 class SessionContext(msgspec.Struct):
@@ -246,7 +378,6 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
     credentials: dict[UUID, Credential] = {}
     sessions: dict[str, Session] = {}
     reset_tokens: dict[bytes, ResetToken] = {}
-    v: int = 0
 
     def __post_init__(self):
         # Store reference for persistence (not serialized)
@@ -270,3 +401,63 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
     def transaction(self, action, ctx=None, *, user=None):
         """Wrap writes in transaction. Delegates to JsonlStore."""
         return self._store.transaction(action, ctx, user=user)
+
+    def session_ctx(
+        self, session_key: str, host: str | None = None
+    ) -> SessionContext | None:
+        """Get full session context with effective permissions.
+
+        Args:
+            session_key: The session key string
+            host: Optional host for binding/validation and domain-scoped permissions
+
+        Returns:
+            SessionContext if valid, None if session not found, expired, or host mismatch
+        """
+        try:
+            s = self.sessions[session_key]
+        except KeyError:
+            return None
+
+        # Validate host matches (sessions are always created with a host)
+        if s.host != host:
+            # Session bound to different host
+            return None
+
+        try:
+            user = s.user
+            role = user.role
+            org = role.org
+            credential = s.credential
+        except KeyError:
+            return None
+
+        # Effective permissions: role's permissions that the org can grant
+        # Also filter by domain if host is provided
+        org_perm_uuids = {p.uuid for p in org.permissions}
+        normalized_host = normalize_host(host)
+        host_without_port = (
+            normalized_host.rsplit(":", 1)[0] if normalized_host else None
+        )
+
+        effective_perms = []
+        for perm_uuid in role.permission_set:
+            if perm_uuid not in org_perm_uuids:
+                continue
+            try:
+                p = self.permissions[perm_uuid]
+            except KeyError:
+                continue
+            # Check domain restriction
+            if p.domain is not None and p.domain != host_without_port:
+                continue
+            effective_perms.append(p)
+
+        return SessionContext(
+            session=s,
+            user=user,
+            org=org,
+            role=role,
+            credential=credential,
+            permissions=effective_perms,
+        )

paskia/fastapi/__main__.py

@@ -7,12 +7,12 @@ from urllib.parse import urlparse
 
 from fastapi_vue.hostutil import parse_endpoint
 from uvicorn import Config, Server
+from uvicorn import run as uvicorn_run
 
 from paskia import globals as _globals
 from paskia.bootstrap import bootstrap_if_needed
 from paskia.config import PaskiaConfig
 from paskia.db.background import flush
-from paskia.fastapi import app as fastapi_app
 from paskia.fastapi import reset as reset_cmd
 from paskia.util import startupbox
 from paskia.util.hostutil import normalize_origin
@@ -188,7 +188,8 @@ def main():
     devmode = bool(os.environ.get("FASTAPI_VUE_FRONTEND_URL"))
 
     run_kwargs: dict = {
-        "log_level": "info",
+        "log_level": "warning",  # Suppress startup messages; we use custom logging
+        "access_log": False,  # We use custom AccessLogMiddleware instead
     }
 
     if devmode:
@@ -198,8 +199,6 @@ def main():
             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"
 
     async def async_main():
         await _globals.init(
@@ -219,10 +218,18 @@ def main():
             async with asyncio.TaskGroup() as tg:
                 for ep in endpoints:
                     tg.create_task(
-                        Server(Config(app=fastapi_app, **run_kwargs, **ep)).serve()
+                        Server(
+                            Config(app="paskia.fastapi:app", **run_kwargs, **ep)
+                        ).serve()
                     )
+        elif devmode:
+            # Use uvicorn.run for proper reload support (it handles subprocess spawning)
+            ep = endpoints[0]
+            uvicorn_run("paskia.fastapi:app", **run_kwargs, **ep)
         else:
-            server = Server(Config(app=fastapi_app, **run_kwargs, **endpoints[0]))
+            server = Server(
+                Config(app="paskia.fastapi:app", **run_kwargs, **endpoints[0])
+            )
             await server.serve()
 
     try:

paskia/fastapi/admin.py

@@ -1,5 +1,4 @@
 import logging
-from datetime import timezone
 from uuid import UUID
 
 from fastapi import Body, FastAPI, HTTPException, Query, Request, Response
@@ -13,6 +12,7 @@ from paskia.db import Permission as PermDC
 from paskia.db import Role as RoleDC
 from paskia.db import User as UserDC
 from paskia.fastapi import authz
+from paskia.fastapi.response import MsgspecResponse
 from paskia.fastapi.session import AUTH_COOKIE
 from paskia.globals import passkey
 from paskia.util import (
@@ -20,46 +20,26 @@ from paskia.util import (
     passphrase,
     permutil,
     querysafe,
-    useragent,
     vitedev,
 )
+from paskia.util.apistructs import ApiPermission, ApiSession, format_datetime
 from paskia.util.hostutil import normalize_host
 
 app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
 
 
-def is_global_admin(ctx) -> bool:
+def master_admin(ctx) -> bool:
-    """Check if user has global admin permission."""
+    return any(p.scope == "auth:admin" for p in ctx.permissions)
-    effective_scopes = (
+
-        {p.scope for p in (ctx.permissions or [])}
+
-        if ctx.permissions
+def org_admin(ctx, org_uuid: UUID) -> bool:
-        else set(ctx.role.permissions or [])
+    return ctx.org.uuid == org_uuid and any(
+        p.scope == "auth:org:admin" for p in ctx.permissions
     )
-    return "auth:admin" in effective_scopes
-
-
-def is_org_admin(ctx, org_uuid: UUID | None = None) -> bool:
-    """Check if user has org admin permission.
-
-    If org_uuid is provided, checks if user is admin of that specific org.
-    If org_uuid is None, checks if user is admin of their own org.
-    """
-    effective_scopes = (
-        {p.scope for p in (ctx.permissions or [])}
-        if ctx.permissions
-        else set(ctx.role.permissions or [])
-    )
-    if "auth:org:admin" not in effective_scopes:
-        return False
-    if org_uuid is None:
-        return True
-    # User must belong to the target org (via their role)
-    return ctx.org.uuid == org_uuid
 
 
 def can_manage_org(ctx, org_uuid: UUID) -> bool:
-    """Check if user can manage the specified organization."""
+    return master_admin(ctx) or org_admin(ctx, org_uuid)
-    return is_global_admin(ctx) or is_org_admin(ctx, org_uuid)
 
 
 @app.exception_handler(ValueError)
@@ -99,42 +79,38 @@ async def admin_list_orgs(request: Request, auth=AUTH_COOKIE):
         host=request.headers.get("host"),
     )
     orgs = list(db.data().orgs.values())
-    if not is_global_admin(ctx):
+    if not master_admin(ctx):
         # Org admins can only see their own organization
         orgs = [o for o in orgs if o.uuid == ctx.org.uuid]
 
-    def role_to_dict(r):
+    def org_to_dict(o):
-        return {
-            "uuid": str(r.uuid),
-            "org": str(r.org),
-            "display_name": r.display_name,
-            "permissions": list(r.permissions.keys()),
-        }
-
-    async def org_to_dict(o):
         users = db.get_organization_users(o.uuid)
         return {
-            "uuid": str(o.uuid),
+            "uuid": o.uuid,
             "display_name": o.display_name,
-            "permissions": {
+            "permissions": {p.uuid for p in o.permissions},
-                pid for pid, p in db.data().permissions.items() if o.uuid in p.orgs
-            },
             "roles": [
-                role_to_dict(r) for r in db.data().roles.values() if r.org == o.uuid
+                {
+                    "uuid": r.uuid,
+                    "org": r.org_uuid,
+                    "display_name": r.display_name,
+                    "permissions": list(r.permissions.keys()),
+                }
+                for r in o.roles
             ],
             "users": [
                 {
-                    "uuid": str(u.uuid),
+                    "uuid": u.uuid,
                     "display_name": u.display_name,
                     "role": role_name,
                     "visits": u.visits,
-                    "last_seen": u.last_seen.isoformat() if u.last_seen else None,
+                    "last_seen": u.last_seen,
                 }
                 for (u, role_name) in users
             ],
         }
 
-    return [await org_to_dict(o) for o in orgs]
+    return MsgspecResponse([org_to_dict(o) for o in orgs])
 
 
 @app.post("/orgs")
@@ -151,7 +127,7 @@ async def admin_create_org(
     db.create_org(org, ctx=ctx)
     # Grant requested permissions to the new org
     for perm in permissions:
-        db.add_permission_to_org(str(org.uuid), perm)
+        db.add_permission_to_org(str(org.uuid), perm, ctx=ctx)
 
     return {"uuid": str(org.uuid)}
 
@@ -283,7 +259,8 @@ async def admin_create_role(
     perms = payload.get("permissions") or []
     if org_uuid not in db.data().orgs:
         raise HTTPException(status_code=404, detail="Organization not found")
-    grantable = {pid for pid, p in db.data().permissions.items() if org_uuid in p.orgs}
+    org = db.data().orgs[org_uuid]
+    grantable = {p.uuid for p in org.permissions}
 
     # Normalize permission IDs to UUIDs
     permission_uuids: set[UUID] = set()
@@ -324,7 +301,7 @@ async def admin_update_role_name(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )
     role = db.data().roles.get(role_uuid)
-    if not role or role.org != org_uuid:
+    if not role or role.org_uuid != org_uuid:
         raise HTTPException(status_code=404, detail="Role not found in organization")
 
     display_name = payload.get("display_name")
@@ -356,7 +333,7 @@ async def admin_add_role_permission(
         )
 
     role = db.data().roles.get(role_uuid)
-    if not role or role.org != org_uuid:
+    if not role or role.org_uuid != org_uuid:
         raise HTTPException(status_code=404, detail="Role not found in organization")
 
     # Verify permission exists and org can grant it
@@ -391,7 +368,7 @@ async def admin_remove_role_permission(
         )
 
     role = db.data().roles.get(role_uuid)
-    if not role or role.org != org_uuid:
+    if not role or role.org_uuid != org_uuid:
         raise HTTPException(status_code=404, detail="Role not found in organization")
 
     # Sanity check: prevent admin from removing their own access
@@ -432,7 +409,7 @@ async def admin_delete_role(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )
     role = db.data().roles.get(role_uuid)
-    if not role or role.org != org_uuid:
+    if not role or role.org_uuid != org_uuid:
         raise HTTPException(status_code=404, detail="Role not found in organization")
 
     # Sanity check: prevent admin from deleting their own role
@@ -468,8 +445,11 @@ async def admin_create_user(
     if not display_name or not role_name:
         raise ValueError("display_name and role are required")
 
-    roles = [r for r in db.data().roles.values() if r.org == org_uuid]
+    org = db.data().orgs[org_uuid]
-    role_obj = next((r for r in roles if r.display_name == role_name), None)
+    role_obj = next(
+        (r for r in org.roles if r.display_name == role_name),
+        None,
+    )
     if not role_obj:
         raise ValueError("Role not found in organization")
     user = UserDC.create(
@@ -507,7 +487,7 @@ async def admin_update_user_role(
         raise ValueError("User not found")
     if user_org.uuid != org_uuid:
         raise ValueError("User does not belong to this organization")
-    roles = [r for r in db.data().roles.values() if r.org == org_uuid]
+    roles = user_org.roles
     if not any(r.display_name == new_role for r in roles):
         raise ValueError("Role not found in organization")
 
@@ -572,11 +552,7 @@ async def admin_create_user_registration_link(
     url = hostutil.reset_link_url(token)
     return {
         "url": url,
-        "expires": (
+        "expires": format_datetime(expiry),
-            expiry.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
-            if expiry.tzinfo
-            else expiry.replace(tzinfo=timezone.utc).isoformat().replace("+00:00", "Z")
-        ),
     }
 
 
@@ -604,120 +580,39 @@ async def admin_get_user_detail(
             status_code=403, detail="Insufficient permissions", mode="forbidden"
         )
     user = db.data().users.get(user_uuid)
-    user_creds = [c for c in db.data().credentials.values() if c.user == user_uuid]
+    normalized_host = hostutil.normalize_host(request.headers.get("host"))
-    creds: list[dict] = []
+
-    aaguids: set[str] = set()
+    return MsgspecResponse(
-    for c in user_creds:
+        {
-        aaguid_str = str(c.aaguid)
+            "display_name": user.display_name,
-        aaguids.add(aaguid_str)
+            "org": {"display_name": user_org.display_name},
-        creds.append(
+            "role": role_name,
-            {
+            "visits": user.visits,
-                "credential": str(c.uuid),
+            "created_at": user.created_at,
-                "aaguid": aaguid_str,
+            "last_seen": user.last_seen,
-                "created_at": (
+            "credentials": [
-                    c.created_at.astimezone(timezone.utc)
+                {
-                    .isoformat()
+                    "credential": c.uuid,
-                    .replace("+00:00", "Z")
+                    "aaguid": c.aaguid,
-                    if c.created_at.tzinfo
+                    "created_at": c.created_at,
-                    else c.created_at.replace(tzinfo=timezone.utc)
+                    "last_used": c.last_used,
-                    .isoformat()
+                    "last_verified": c.last_verified,
-                    .replace("+00:00", "Z")
+                    "sign_count": c.sign_count,
-                ),
+                }
-                "last_used": (
+                for c in user.credentials
-                    c.last_used.astimezone(timezone.utc)
+            ],
-                    .isoformat()
+            "aaguid_info": aaguid_mod.filter(c.aaguid for c in user.credentials),
-                    .replace("+00:00", "Z")
+            "sessions": [
-                    if c.last_used and c.last_used.tzinfo
+                ApiSession.from_db(
-                    else (
+                    s,
-                        c.last_used.replace(tzinfo=timezone.utc)
+                    current_key=auth,
-                        .isoformat()
+                    normalized_host=normalized_host,
-                        .replace("+00:00", "Z")
+                    expires_delta=EXPIRES,
-                        if c.last_used
-                        else None
-                    )
-                ),
-                "last_verified": (
-                    c.last_verified.astimezone(timezone.utc)
-                    .isoformat()
-                    .replace("+00:00", "Z")
-                    if c.last_verified and c.last_verified.tzinfo
-                    else (
-                        c.last_verified.replace(tzinfo=timezone.utc)
-                        .isoformat()
-                        .replace("+00:00", "Z")
-                        if c.last_verified
-                        else None
-                    )
                 )
-                if c.last_verified
+                for s in user.sessions
-                else None,
+            ],
-                "sign_count": c.sign_count,
+        }
-            }
+    )
-        )
-
-    aaguid_info = aaguid_mod.filter(aaguids)
-
-    # Get sessions for the user
-    normalized_request_host = hostutil.normalize_host(request.headers.get("host"))
-    session_records = [s for s in db.data().sessions.values() if s.user == user_uuid]
-    current_session_key = auth
-    sessions_payload: list[dict] = []
-    for entry in session_records:
-        renewed = entry.expiry - EXPIRES
-        sessions_payload.append(
-            {
-                "id": entry.key,
-                "credential": str(entry.credential),
-                "host": entry.host,
-                "ip": entry.ip,
-                "user_agent": useragent.compact_user_agent(entry.user_agent),
-                "last_renewed": (
-                    renewed.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
-                    if renewed.tzinfo
-                    else renewed.replace(tzinfo=timezone.utc)
-                    .isoformat()
-                    .replace("+00:00", "Z")
-                ),
-                "is_current": entry.key == current_session_key,
-                "is_current_host": bool(
-                    normalized_request_host
-                    and entry.host
-                    and entry.host == normalized_request_host
-                ),
-            }
-        )
-
-    return {
-        "display_name": user.display_name,
-        "org": {"display_name": user_org.display_name},
-        "role": role_name,
-        "visits": user.visits,
-        "created_at": (
-            user.created_at.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
-            if user.created_at and user.created_at.tzinfo
-            else (
-                user.created_at.replace(tzinfo=timezone.utc)
-                .isoformat()
-                .replace("+00:00", "Z")
-                if user.created_at
-                else None
-            )
-        ),
-        "last_seen": (
-            user.last_seen.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
-            if user.last_seen and user.last_seen.tzinfo
-            else (
-                user.last_seen.replace(tzinfo=timezone.utc)
-                .isoformat()
-                .replace("+00:00", "Z")
-                if user.last_seen
-                else None
-            )
-        ),
-        "credentials": creds,
-        "aaguid_info": aaguid_info,
-        "sessions": sessions_payload,
-    }
 
 
 @app.patch("/orgs/{org_uuid}/users/{user_uuid}/display-name")
@@ -808,10 +703,10 @@ async def admin_delete_user_session(
         )
 
     target_session = db.data().sessions.get(session_id)
-    if not target_session or target_session.user != user_uuid:
+    if not target_session or target_session.user_uuid != user_uuid:
         raise HTTPException(status_code=404, detail="Session not found")
 
-    db.delete_session(session_id, ctx=ctx)
+    db.delete_session(session_id, ctx=ctx, action="admin:delete_session")
 
     # Check if admin terminated their own session
     current_terminated = session_id == auth
@@ -821,14 +716,6 @@ async def admin_delete_user_session(
 # -------------------- Permissions (global) --------------------
 
 
-def _perm_to_dict(p):
-    """Convert Permission to dict, omitting domain if None."""
-    d = {"uuid": str(p.uuid), "scope": p.scope, "display_name": p.display_name}
-    if p.domain is not None:
-        d["domain"] = p.domain
-    return d
-
-
 def _validate_permission_domain(domain: str | None) -> None:
     """Validate that domain is rp_id or a subdomain of it."""
     if domain is None:
@@ -919,18 +806,8 @@ async def admin_list_permissions(request: Request, auth=AUTH_COOKIE):
         match=permutil.has_any,
         host=request.headers.get("host"),
     )
-    perms = list(db.data().permissions.values())
+    perms = db.data().permissions.values() if master_admin(ctx) else ctx.org.permissions
-
+    return MsgspecResponse([ApiPermission.from_db(p) for p in perms])
-    # Global admins see all permissions
-    if is_global_admin(ctx):
-        return [_perm_to_dict(p) for p in perms]
-
-    # Org admins only see permissions their org can grant (by UUID)
-    grantable = {
-        pid for pid, p in db.data().permissions.items() if ctx.org.uuid in p.orgs
-    }
-    filtered_perms = [p for p in perms if p.uuid in grantable]
-    return [_perm_to_dict(p) for p in filtered_perms]
 
 
 @app.post("/permissions")

paskia/fastapi/api.py

@@ -1,6 +1,6 @@
 import logging
 from contextlib import suppress
-from datetime import datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
 
 from fastapi import (
     Depends,
@@ -14,12 +14,9 @@ from fastapi.responses import JSONResponse
 from fastapi.security import HTTPBearer
 
 from paskia import db
-from paskia.authsession import (
+from paskia.authsession import EXPIRES, expires, get_reset
-    EXPIRES,
-    get_reset,
-    refresh_session_token,
-)
 from paskia.fastapi import authz, session, user
+from paskia.fastapi.response import MsgspecResponse
 from paskia.fastapi.session import AUTH_COOKIE, AUTH_COOKIE_NAME
 from paskia.globals import passkey as global_passkey
 from paskia.util import hostutil, htmlutil, passphrase, userinfo, vitedev
@@ -81,7 +78,7 @@ async def validate_token(
     try:
         ctx = await authz.verify(
             auth,
-            perm,
+            " ".join(perm).split(),
             host=request.headers.get("host"),
             max_age=max_age,
         )
@@ -90,44 +87,24 @@ async def validate_token(
         raise
     renewed = False
     if auth:
-        consumed = EXPIRES - (ctx.session.expiry - datetime.now(timezone.utc))
+        consumed = EXPIRES - (ctx.session.expiry - datetime.now(UTC))
         if not timedelta(0) < consumed < _REFRESH_INTERVAL:
-            try:
+            db.update_session(
-                refresh_session_token(
+                auth,
-                    auth,
+                ip=request.client.host if request.client else "",
-                    ip=request.client.host if request.client else "",
+                user_agent=request.headers.get("user-agent") or "",
-                    user_agent=request.headers.get("user-agent") or "",
+                expiry=expires(),
-                )
+                ctx=ctx,
-                session.set_session_cookie(response, auth)
+            )
-                renewed = True
+            session.set_session_cookie(response, auth)
-            except ValueError:
+            renewed = True
-                # Session disappeared, e.g. due to concurrent logout; global handler will clear
+    return MsgspecResponse(
-                raise authz.AuthException(
+        {
-                    status_code=401, detail="Session expired", mode="login"
+            "valid": True,
-                )
+            "renewed": renewed,
-    return {
+            "ctx": userinfo.build_session_context(ctx),
-        "valid": True,
+        }
-        "renewed": renewed,
+    )
-        "ctx": userinfo.format_session_context(ctx),
-    }
-
-
-@app.get("/token-info")
-async def token_info(credentials=Depends(bearer_auth)):
-    """Get reset/device-add token info. Pass token via Bearer header."""
-    token = credentials.credentials
-    if not passphrase.is_well_formed(token):
-        raise HTTPException(400, "Invalid token format")
-    try:
-        reset_token = get_reset(token)
-    except ValueError as e:
-        raise HTTPException(401, str(e))
-
-    u = db.data().users.get(reset_token.user)
-    return {
-        "token_type": reset_token.token_type,
-        "display_name": u.display_name,
-    }
 
 
 @app.get("/forward")
@@ -154,7 +131,10 @@ async def forward_authentication(
     """
     try:
         ctx = await authz.verify(
-            auth, perm, host=request.headers.get("host"), max_age=max_age
+            auth,
+            " ".join(perm).split(),
+            host=request.headers.get("host"),
+            max_age=max_age,
         )
         # Build permission scopes for Remote-Groups header
         role_permissions = (
@@ -170,11 +150,9 @@ async def forward_authentication(
             "Remote-Role": str(ctx.role.uuid),
             "Remote-Role-Name": ctx.role.display_name,
             "Remote-Session-Expires": (
-                ctx.session.expiry.astimezone(timezone.utc)
+                ctx.session.expiry.astimezone(UTC).isoformat().replace("+00:00", "Z")
-                .isoformat()
-                .replace("+00:00", "Z")
                 if ctx.session.expiry.tzinfo
-                else ctx.session.expiry.replace(tzinfo=timezone.utc)
+                else ctx.session.expiry.replace(tzinfo=UTC)
                 .isoformat()
                 .replace("+00:00", "Z")
             ),
@@ -233,28 +211,48 @@ async def api_user_info(
             detail="Authentication required",
             mode="login",
         )
-    ctx = db.get_session_context(auth, request.headers.get("host"))
+    ctx = db.data().session_ctx(auth, request.headers.get("host"))
     if not ctx:
         raise HTTPException(401, "Session expired")
 
-    return await userinfo.format_user_info(
+    return MsgspecResponse(
-        user_uuid=ctx.user.uuid,
+        await userinfo.build_user_info(
-        auth=auth,
+            user_uuid=ctx.user.uuid,
-        session_record=ctx.session,
+            auth=auth,
-        request_host=request.headers.get("host"),
+            session_record=ctx.session,
+            request_host=request.headers.get("host"),
+        )
     )
 
 
+@app.get("/token-info")
+async def token_info(credentials=Depends(bearer_auth)):
+    """Get reset/device-add token info. Pass token via Bearer header."""
+    token = credentials.credentials
+    if not passphrase.is_well_formed(token):
+        raise HTTPException(400, "Invalid token format")
+    try:
+        reset_token = get_reset(token)
+    except ValueError as e:
+        raise HTTPException(401, str(e))
+
+    u = reset_token.user
+    return {
+        "token_type": reset_token.token_type,
+        "display_name": u.display_name,
+    }
+
+
 @app.post("/logout")
 async def api_logout(request: Request, response: Response, auth=AUTH_COOKIE):
     if not auth:
         return {"message": "Already logged out"}
     host = request.headers.get("host")
-    ctx = db.get_session_context(auth, host)
+    ctx = db.data().session_ctx(auth, host)
     if not ctx:
         return {"message": "Already logged out"}
     with suppress(Exception):
-        db.delete_session(auth, ctx=ctx)
+        db.delete_session(auth, ctx=ctx, action="logout")
     session.clear_session_cookie(response)
     return {"message": "Logged out successfully"}
 
@@ -263,7 +261,7 @@ async def api_logout(request: Request, response: Response, auth=AUTH_COOKIE):
 async def api_set_session(
     request: Request, response: Response, auth=Depends(bearer_auth)
 ):
-    ctx = db.get_session_context(auth.credentials, request.headers.get("host"))
+    ctx = db.data().session_ctx(auth.credentials, request.headers.get("host"))
     if not ctx:
         raise HTTPException(401, "Session expired")
     session.set_session_cookie(response, auth.credentials)

paskia/fastapi/authz.py

@@ -2,6 +2,7 @@ import logging
 
 from fastapi import HTTPException
 
+from paskia.fastapi.logging import log_permission_denied
 from paskia.util import permutil, sessionutil
 
 logger = logging.getLogger(__name__)
@@ -79,6 +80,9 @@ async def verify(
             mode="login",
             clear_session=True,
         )
+    # User's theme preference for iframe (only if explicitly set)
+    user_theme = ctx.user.theme if ctx.user.theme else None
+
     # Check max_age requirement if specified
     if max_age:
         try:
@@ -87,29 +91,27 @@ async def verify(
                     status_code=401,
                     detail="Additional authentication required",
                     mode="reauth",
+                    theme=user_theme,
                 )
         except ValueError as e:
             # Invalid max_age format - log but don't fail the request
             logger.warning(f"Invalid max_age format '{max_age}': {e}")
 
     if not match(ctx, perm):
-        # Determine which permissions are missing for clearer diagnostics
         effective_scopes = (
             {p.scope for p in (ctx.permissions or [])}
             if ctx.permissions
             else set(ctx.role.permissions or [])
         )
         missing = sorted(set(perm) - effective_scopes)
-        logger.warning(
+        log_permission_denied(
-            "Permission denied: user=%s role=%s missing=%s required=%s granted=%s",  # noqa: E501
+            ctx, perm, missing, require_all=(match == permutil.has_all)
-            getattr(ctx.user, "uuid", "?"),
-            getattr(ctx.role, "display_name", "?"),
-            missing,
-            perm,
-            list(effective_scopes),
         )
         raise AuthException(
-            status_code=403, mode="forbidden", detail="Permission required"
+            status_code=403,
+            mode="forbidden",
+            detail="Permission required",
+            theme=user_theme,
         )
 
     return ctx

paskia/fastapi/logging.py

@@ -0,0 +1,261 @@
+"""Custom access logging middleware for FastAPI/Uvicorn."""
+
+import logging
+import sys
+import time
+from ipaddress import IPv6Address
+from typing import TYPE_CHECKING
+
+from starlette.middleware.base import BaseHTTPMiddleware
+
+if TYPE_CHECKING:
+    from paskia.db.structs import SessionContext
+from starlette.requests import Request
+from starlette.responses import Response
+
+logger = logging.getLogger("paskia.access")
+
+_RESET = "\033[0m"
+_STATUS_INFO = "\033[32m"  # 1xx (green)
+_STATUS_OK = "\033[1;92m"  # 2xx (bright green)
+_STATUS_REDIRECT = "\033[32m"  # 3xx (green)
+_STATUS_CLIENT_ERR = "\033[0;31m"  # 4xx (red)
+_STATUS_SERVER_ERR = "\033[1;91m"  # 5xx (bold bright red)
+_METHOD_READ = "\033[0;34m"  # GET, HEAD, OPTIONS (blue)
+_METHOD_WRITE = "\033[1;94m"  # POST, PUT, DELETE, PATCH (bold bright blue)
+_HOST = "\033[38;5;242m"  # hostname (dark grey)
+_PATH = "\033[38;5;250m"  # path (white)
+_TIMING = "\033[38;5;242m"  # timing/devmode (dark grey)
+_WS_OPEN = "\033[1;93m"  # WebSocket connect (bold bright yellow)
+_WS_CLOSE = "\033[33m"  # WebSocket disconnect (yellow)
+_WS_STATUS = "\033[38;5;242m"  # WebSocket close status (dark grey)
+_AUTHZ_DENIED = "\033[0;31m"  # Permission denied (red)
+_AUTHZ_USER = "\033[1;34m"  # User info (light blue)
+_AUTHZ_ORG = "\033[34m"  # User info (blue)
+_AUTHZ_NEEDS = "\033[1;38;5;231m"  # Needs (brightest white)
+_AUTHZ_MISSING = "\033[1;31m"  # Missing scope (bold red)
+_AUTHZ_GRANTED = "\033[0;32m"  # Granted scope (green)
+
+
+def format_ipv6_network(ip: str) -> str:
+    """Format IPv6 address to show only network part (first 64 bits)."""
+    try:
+        addr = IPv6Address(ip)
+        # Get the integer representation and mask to first 64 bits
+        network_int = int(addr) >> 64
+        # Format as IPv6 with trailing ::
+        # Split into 4 groups of 16 bits
+        groups = []
+        for _ in range(4):
+            groups.insert(0, format(network_int & 0xFFFF, "x"))
+            network_int >>= 16
+        # Compress consecutive zero groups
+        result = ":".join(groups) + "::"
+        # Simplify leading zeros in groups and compress, then strip trailing ::
+        return str(IPv6Address(result + "0")).removesuffix("::")
+    except Exception:
+        return ip
+
+
+def format_client_ip(ip: str) -> str:
+    """Format client IP, compressing IPv6 to network part only."""
+    if not ip or ip == "-":
+        return "-"
+    if ":" in ip:
+        return format_ipv6_network(ip)
+    return ip
+
+
+def status_color(status: int) -> str:
+    """Return color code based on HTTP status."""
+    if status < 200:
+        return _STATUS_INFO
+    if status < 300:
+        return _STATUS_OK
+    if status < 400:
+        return _STATUS_REDIRECT
+    if status < 500:
+        return _STATUS_CLIENT_ERR
+    return _STATUS_SERVER_ERR
+
+
+def method_color(method: str) -> str:
+    """Return color code based on HTTP method."""
+    if method in ("GET", "HEAD", "OPTIONS"):
+        return _METHOD_READ
+    return _METHOD_WRITE
+
+
+def format_access_log(
+    client: str, status: int, method: str, host: str, path: str, duration_ms: float
+) -> str:
+    """Format access log line with colors and aligned fields."""
+    use_color = sys.stderr.isatty()
+
+    # Format components with fixed widths for alignment
+    ip = format_client_ip(client).ljust(19)  # IPv6 network max 19 chars
+    timing = f"{duration_ms:.0f}ms"
+    method_padded = method.ljust(7)  # Longest method is OPTIONS (7)
+
+    if use_color:
+        status_str = f"{status_color(status)}{status}{_RESET}"
+        timing_str = f"{_TIMING}{timing}{_RESET}"
+        method_str = f"{method_color(method)}{method_padded}{_RESET}"
+        host_str = f"{_HOST}{host}{_RESET}"
+        path_str = f"{_PATH}{path}{_RESET}"
+    else:
+        status_str = str(status)
+        timing_str = timing
+        method_str = method_padded
+        host_str = host
+        path_str = path
+
+    # Format: "IP STATUS METHOD host path TIMING"
+    return f"{ip} {status_str} {method_str} {host_str}{path_str} {timing_str}"
+
+
+# WebSocket connection counter (mod 100)
+_ws_counter = 0
+
+
+def _next_ws_id() -> int:
+    """Get next WebSocket connection ID (0-99)."""
+    global _ws_counter
+    ws_id = _ws_counter
+    _ws_counter = (_ws_counter + 1) % 100
+    return ws_id
+
+
+def log_ws_open(ws) -> int:
+    """Log WebSocket connection open. Returns connection ID for use in close."""
+    use_color = sys.stderr.isatty()
+    ws_id = _next_ws_id()
+
+    client = ws.client.host if ws.client else "-"
+    host = ws.headers.get("host", "-")
+    path = ws.url.path
+    origin = ws.headers.get("origin")
+
+    ip = format_client_ip(client).ljust(19)
+    id_str = f"{ws_id:02d}".ljust(7)  # Align with method field (7 chars)
+
+    # Determine if origin should be shown (omit when same as host)
+    # Origin header includes scheme (e.g., "https://example.com"), compare host part
+    origin_host = origin.split("://", 1)[-1] if origin else None
+    show_origin = origin_host and origin_host != host
+
+    if use_color:
+        # 🔌 aligned with status (takes ~2 char width), ID aligned with method
+        prefix = f"🔌  {_WS_OPEN}{id_str}{_RESET}"
+        host_str = f"{_HOST}{host}{_RESET}"
+        path_str = f"{_PATH}{path}{_RESET}"
+        origin_str = (
+            f" {_RESET}from {_HOST}{origin_host}{_RESET}" if show_origin else ""
+        )
+    else:
+        prefix = f"WS+ {id_str}"
+        host_str = host
+        path_str = path
+        origin_str = f" from {origin_host}" if show_origin else ""
+
+    logger.info(f"{ip} {prefix} {host_str}{path_str}{origin_str}")
+    return ws_id
+
+
+# WebSocket close codes to human-readable status
+WS_CLOSE_CODES = {
+    1000: "ok",
+    1001: "going away",
+    1002: "protocol error",
+    1003: "unsupported",
+    1005: "no status",
+    1006: "abnormal",
+    1007: "invalid data",
+    1008: "policy violation",
+    1009: "too large",
+    1010: "extension required",
+    1011: "server error",
+    1012: "restarting",
+    1013: "try again",
+    1014: "bad gateway",
+    1015: "tls error",
+}
+
+
+def log_ws_close(ws_id: int, close_code: int | None, duration: float) -> None:
+    """Log WebSocket connection close with duration and status."""
+    use_color = sys.stderr.isatty()
+
+    id_str = f"{ws_id:02d}".ljust(7)  # Align with method field (7 chars)
+    timing = f"{duration * 1000:.0f}ms"
+
+    # Convert close code to status text
+    if close_code is None:
+        status = "closed"
+    else:
+        status = WS_CLOSE_CODES.get(close_code, f"code {close_code}")
+
+    if use_color:
+        # 🔌 aligned with status, ID aligned with method
+        prefix = f"🔌  {_WS_CLOSE}{id_str}{_RESET}"
+        status_str = f"{_WS_STATUS}{status}{_RESET}"
+        timing_str = f"{_TIMING}{timing}{_RESET}"
+    else:
+        prefix = f"WS- {id_str}"
+        status_str = status
+        timing_str = timing
+
+    logger.info(f"{' ' * 19} {prefix} {status_str} {timing_str}")
+
+
+def log_permission_denied(
+    ctx: "SessionContext", required: list[str], missing: list[str], *, require_all: bool
+) -> None:
+    """Log permission denied with org, role, user and highlighted missing scopes."""
+    missing_set = set(missing)
+    scopes = " ".join(
+        f"{_AUTHZ_MISSING}{s}✗{_RESET}"
+        if s in missing_set
+        else f"{_AUTHZ_GRANTED}{s}✓{_RESET}"
+        for s in required
+    )
+    n = "" if len(required) == 1 else " all" if require_all else " any"
+    logger.warning(
+        f"{_AUTHZ_DENIED}Permission denied{_RESET} "
+        f"{_AUTHZ_USER}{ctx.user.display_name}{_RESET} "
+        f"{_AUTHZ_ORG}({ctx.org.display_name} {ctx.role.display_name}){_RESET} "
+        f"{_AUTHZ_NEEDS}needs{n}:{_RESET} {scopes}"
+    )
+
+
+class AccessLogMiddleware(BaseHTTPMiddleware):
+    """Middleware that logs HTTP requests with custom format."""
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        start = time.perf_counter()
+        response = await call_next(request)
+        duration_ms = (time.perf_counter() - start) * 1000
+
+        client = request.client.host if request.client else "-"
+        host = request.headers.get("host", "-")
+        method = request.method
+        path = request.url.path
+        if request.url.query:
+            path = f"{path}?{request.url.query}"
+        status = response.status_code
+
+        line = format_access_log(client, status, method, host, path, duration_ms)
+        logger.info(line)
+
+        return response
+
+
+def configure_access_logging():
+    """Configure the access logger to output to stderr."""
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    logger.propagate = False
+    # Suppress watchfiles "X changes detected" INFO messages (keep WARNING for reload notification)
+    logging.getLogger("watchfiles.main").setLevel(logging.WARNING)

paskia/fastapi/mainapp.py

@@ -10,14 +10,23 @@ from fastapi_vue import Frontend
 
 from paskia import globals
 from paskia.db import start_background, stop_background
+from paskia.db.logging import configure_db_logging
 from paskia.fastapi import admin, api, auth_host, ws
+from paskia.fastapi.logging import AccessLogMiddleware, configure_access_logging
 from paskia.fastapi.session import AUTH_COOKIE
 from paskia.util import hostutil, passphrase, vitedev
 
+# Configure custom logging
+configure_access_logging()
+configure_db_logging()
+
+_access_logger = logging.getLogger("paskia.access")
+
 # Vue Frontend static files
 frontend = Frontend(
     Path(__file__).parent.parent / "frontend-build",
     cached=["/auth/assets/"],
+    favicon="/paskia.webp",
 )
 
 
@@ -48,11 +57,11 @@ async def lifespan(app: FastAPI):  # pragma: no cover - startup path
         # Re-raise to fail fast
         raise
 
-    # Restore info level logging after startup (suppressed during uvicorn init in dev mode)
+    # Restore uvicorn info logging (suppressed during startup in dev mode)
+    # Keep uvicorn.error at WARNING to suppress WebSocket "connection open/closed" messages
     if frontend.devmode:
         logging.getLogger("uvicorn").setLevel(logging.INFO)
-        logging.getLogger("uvicorn.access").setLevel(logging.INFO)
+    logging.getLogger("uvicorn.error").setLevel(logging.WARNING)
-
     await frontend.load()
     await start_background()
     yield
@@ -67,6 +76,9 @@ app = FastAPI(
     openapi_url=None,
 )
 
+# Custom access logging (uvicorn's access_log is disabled)
+app.add_middleware(AccessLogMiddleware)
+
 # Apply redirections to auth-host if configured (deny access to restricted endpoints, remove /auth/)
 app.middleware("http")(auth_host.redirect_middleware)
 
@@ -124,6 +136,11 @@ async def examples_page():
     return FileResponse(index_file, media_type="text/html")
 
 
+# Frontend static files - must be before /{token} catch-all routes
+# (actual routes registered during lifespan after frontend.load())
+frontend.route(app, "/")
+
+
 # Note: this catch-all handler must be the last route defined
 @app.get("/{token}")
 @app.get("/auth/{token}")
@@ -136,7 +153,3 @@ async def token_link(token: str):
         raise HTTPException(status_code=404)
 
     return Response(*await vitedev.read("/int/reset/index.html"))
-
-
-# Final catch-all route for frontend files (keep at end of file)
-frontend.route(app, "/")

paskia/fastapi/remote.py

@@ -17,10 +17,10 @@ from fastapi import FastAPI, WebSocket, WebSocketDisconnect
 
 from paskia import db, remoteauth
 from paskia.authsession import expires
-from paskia.fastapi.session import infodict
+from paskia.fastapi.session import AUTH_COOKIE, infodict
-from paskia.fastapi.wschat import authenticate_chat
+from paskia.fastapi.wschat import authenticate_and_login
 from paskia.fastapi.wsutil import validate_origin, websocket_error_handler
-from paskia.util import hostutil, passphrase, pow, useragent
+from paskia.util import passphrase, pow, useragent
 
 # Create a FastAPI subapp for remote auth WebSocket endpoints
 app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
@@ -252,7 +252,7 @@ async def websocket_remote_auth_request(ws: WebSocket):
 
 @app.websocket("/permit")
 @websocket_error_handler
-async def websocket_remote_auth_permit(ws: WebSocket):
+async def websocket_remote_auth_permit(ws: WebSocket, auth=AUTH_COOKIE):
     """Complete a remote authentication request using a 3-word pairing code.
 
     This endpoint is called from the user's profile on the authenticating device.
@@ -270,7 +270,7 @@ async def websocket_remote_auth_permit(ws: WebSocket):
     7. Server sends {status: "success", message: "..."}
     """
 
-    origin = validate_origin(ws)
+    validate_origin(ws)
 
     if remoteauth.instance is None:
         raise ValueError("Remote authentication is not available")
@@ -310,56 +310,30 @@ async def websocket_remote_auth_permit(ws: WebSocket):
 
             # Handle authenticate request (no PoW needed - already validated during lookup)
             if msg.get("authenticate") and request is not None:
-                cred, new_sign_count = await authenticate_chat(ws, origin)
+                ctx = await authenticate_and_login(ws, auth)
 
-                # Create a session for the REQUESTING device
+                session_token = ctx.session.key
-                assert cred.uuid is not None
-
-                session_token = None
                 reset_token = None
 
                 if request.action == "register":
                     # For registration, create a reset token for device addition
-
                     token_str = passphrase.generate()
                     expiry = expires()
                     db.create_reset_token(
-                        user_uuid=cred.user,
+                        user_uuid=ctx.user.uuid,
                         passphrase=token_str,
                         expiry=expiry,
                         token_type="device addition",
+                        user=str(ctx.user.uuid),
                     )
                     reset_token = token_str
-                    # Also create a session so the device is logged in
-                    normalized_host = hostutil.normalize_host(request.host)
-                    session_token = db.login(
-                        user_uuid=cred.user,
-                        credential_uuid=cred.uuid,
-                        sign_count=new_sign_count,
-                        host=normalized_host,
-                        ip=request.ip,
-                        user_agent=request.user_agent,
-                        expiry=expires(),
-                    )
-                else:
-                    # Default login action
-
-                    normalized_host = hostutil.normalize_host(request.host)
-                    session_token = db.login(
-                        user_uuid=cred.user,
-                        credential_uuid=cred.uuid,
-                        sign_count=new_sign_count,
-                        host=normalized_host,
-                        ip=request.ip,
-                        user_agent=request.user_agent,
-                        expiry=expires(),
-                    )
 
                 # Complete the remote auth request (notifies the waiting device)
+                cred = db.data().credentials[ctx.session.credential_uuid]
                 completed = await remoteauth.instance.complete_request(
                     token=request.key,
                     session_token=session_token,
-                    user_uuid=cred.user,
+                    user_uuid=ctx.user.uuid,
                     credential_uuid=cred.uuid,
                     reset_token=reset_token,
                 )

paskia/fastapi/reset.py

@@ -10,8 +10,6 @@ display name. If multiple users match, they are listed and the command
 aborts. A new one-time reset link is always created.
 """
 
-from __future__ import annotations
-
 import asyncio
 from uuid import UUID
 

paskia/fastapi/response.py

@@ -0,0 +1,22 @@
+"""FastAPI response utilities for msgspec.Struct serialization."""
+
+import msgspec
+from fastapi import Response
+
+
+class MsgspecResponse(Response):
+    """Response that uses msgspec for JSON encoding.
+
+    Use this for returning msgspec.Struct, dict, or list with proper serialization.
+    """
+
+    media_type = "application/json"
+
+    def __init__(
+        self,
+        content: msgspec.Struct | dict | list,
+        status_code: int = 200,
+        headers: dict | None = None,
+    ):
+        body = msgspec.json.encode(content)
+        super().__init__(content=body, status_code=status_code, headers=headers)

paskia/fastapi/user.py

@@ -1,4 +1,4 @@
-from datetime import timezone
+from datetime import UTC
 from uuid import UUID
 
 from fastapi import (
@@ -43,7 +43,7 @@ async def user_update_display_name(
             status_code=401, detail="Authentication Required", mode="login"
         )
     host = request.headers.get("host")
-    ctx = db.get_session_context(auth, host)
+    ctx = db.data().session_ctx(auth, host)
     if not ctx:
         raise authz.AuthException(
             status_code=401, detail="Session expired", mode="login"
@@ -57,12 +57,34 @@ async def user_update_display_name(
     return {"status": "ok"}
 
 
+@app.patch("/theme")
+async def user_update_theme(
+    request: Request,
+    payload: dict = Body(...),
+    auth=AUTH_COOKIE,
+):
+    if not auth:
+        raise authz.AuthException(
+            status_code=401, detail="Authentication Required", mode="login"
+        )
+    ctx = db.data().session_ctx(auth, request.headers.get("host"))
+    if not ctx:
+        raise authz.AuthException(
+            status_code=401, detail="Session expired", mode="login"
+        )
+    theme = payload.get("theme", "")
+    if theme not in ("", "light", "dark"):
+        raise HTTPException(status_code=400, detail="Invalid theme")
+    db.update_user_theme(ctx.user.uuid, theme, ctx=ctx)
+    return {"status": "ok"}
+
+
 @app.post("/logout-all")
 async def api_logout_all(request: Request, response: Response, auth=AUTH_COOKIE):
     if not auth:
         return {"message": "Already logged out"}
     host = request.headers.get("host")
-    ctx = db.get_session_context(auth, host)
+    ctx = db.data().session_ctx(auth, host)
     if not ctx:
         raise authz.AuthException(
             status_code=401, detail="Session expired", mode="login"
@@ -84,14 +106,14 @@ async def api_delete_session(
             status_code=401, detail="Authentication Required", mode="login"
         )
     host = request.headers.get("host")
-    ctx = db.get_session_context(auth, host)
+    ctx = db.data().session_ctx(auth, host)
     if not ctx:
         raise authz.AuthException(
             status_code=401, detail="Session expired", mode="login"
         )
 
     target_session = db.data().sessions.get(session_id)
-    if not target_session or target_session.user != ctx.user.uuid:
+    if not target_session or target_session.user_uuid != ctx.user.uuid:
         raise HTTPException(status_code=404, detail="Session not found")
 
     db.delete_session(session_id, ctx=ctx)
@@ -141,8 +163,8 @@ async def api_create_link(
         "message": "Registration link generated successfully",
         "url": url,
         "expires": (
-            expiry.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+            expiry.astimezone(UTC).isoformat().replace("+00:00", "Z")
             if expiry.tzinfo
-            else expiry.replace(tzinfo=timezone.utc).isoformat().replace("+00:00", "Z")
+            else expiry.replace(tzinfo=UTC).isoformat().replace("+00:00", "Z")
         ),
     }

paskia/fastapi/ws.py

@@ -1,13 +1,13 @@
 from fastapi import FastAPI, WebSocket
 
 from paskia import db
-from paskia.authsession import expires, get_reset
+from paskia.authsession import get_reset
 from paskia.fastapi import authz, remote
 from paskia.fastapi.session import AUTH_COOKIE, infodict
-from paskia.fastapi.wschat import authenticate_chat, register_chat
+from paskia.fastapi.wschat import authenticate_and_login, register_chat
 from paskia.fastapi.wsutil import validate_origin, websocket_error_handler
 from paskia.globals import passkey
-from paskia.util import hostutil, passphrase
+from paskia.util import passphrase
 
 # Create a FastAPI subapp for WebSocket endpoints
 app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
@@ -38,15 +38,15 @@ async def websocket_register_add(
                 f"The reset link for {passkey.instance.rp_name} is invalid or has expired"
             )
         s = get_reset(reset)
-        user_uuid = s.user
+        user_uuid = s.user_uuid
     else:
         # Require recent authentication for adding a new passkey
         ctx = await authz.verify(auth, perm=[], host=host, max_age="5m")
-        user_uuid = ctx.session.user
+        user_uuid = ctx.session.user_uuid
         s = ctx.session
 
     # Get user information and determine effective user_name for this registration
-    user = db.data().users.get(user_uuid)
+    user = db.data().users[user_uuid]
     user_name = user.display_name
     if name is not None:
         stripped = name.strip()
@@ -59,7 +59,7 @@ async def websocket_register_add(
 
     # Create a new session and store everything in database
     metadata = infodict(ws, "authenticated")
-    token = db.create_credential_session(  # type: ignore[attr-defined]
+    token = db.create_credential_session(
         user_uuid=user_uuid,
         credential=credential,
         reset_key=(s.key if reset is not None else None),
@@ -89,43 +89,20 @@ async def websocket_authenticate(ws: WebSocket, auth=AUTH_COOKIE):
 
     # If there's an existing session, restrict to that user's credentials (reauth)
     session_user_uuid = None
-    credential_ids = None
     if auth:
-        ctx = db.get_session_context(auth, host)
+        existing_ctx = db.data().session_ctx(auth, host)
-        if ctx:
+        if existing_ctx:
-            session_user_uuid = ctx.user.uuid
+            session_user_uuid = existing_ctx.user.uuid
-            credential_ids = db.get_user_credential_ids(session_user_uuid) or None
 
-    cred, new_sign_count = await authenticate_chat(ws, origin, credential_ids)
+    ctx = await authenticate_and_login(ws, auth)
 
     # If reauth mode, verify the credential belongs to the session's user
-    if session_user_uuid and cred.user != session_user_uuid:
+    if session_user_uuid and ctx.user.uuid != session_user_uuid:
         raise ValueError("This passkey belongs to a different account")
 
-    # Create session and update user/credential in a single transaction
-    assert cred.uuid is not None
-    metadata = infodict(ws, "auth")
-    normalized_host = hostutil.normalize_host(host)
-    if not normalized_host:
-        raise ValueError("Host required for session creation")
-    hostname = normalized_host.split(":")[0]
-    rp_id = passkey.instance.rp_id
-    if not (hostname == rp_id or hostname.endswith(f".{rp_id}")):
-        raise ValueError(f"Host must be the same as or a subdomain of {rp_id}")
-
-    token = db.login(
-        user_uuid=cred.user,
-        credential_uuid=cred.uuid,
-        sign_count=new_sign_count,
-        host=normalized_host,
-        ip=metadata["ip"],
-        user_agent=metadata["user_agent"],
-        expiry=expires(),
-    )
-
     await ws.send_json(
         {
-            "user": str(cred.user),
+            "user": str(ctx.user.uuid),
-            "session_token": token,
+            "session_token": ctx.session.key,
         }
     )

paskia/fastapi/wschat.py

@@ -7,8 +7,12 @@ from uuid import UUID
 from fastapi import WebSocket
 
 from paskia import db
-from paskia.db import Credential
+from paskia.authsession import expires
+from paskia.db import Credential, SessionContext
+from paskia.fastapi.session import infodict
+from paskia.fastapi.wsutil import validate_origin
 from paskia.globals import passkey
+from paskia.util import hostutil
 
 
 async def register_chat(
@@ -31,7 +35,6 @@ async def register_chat(
 
 async def authenticate_chat(
     ws: WebSocket,
-    origin: str,
     credential_ids: list[bytes] | None = None,
 ) -> tuple[Credential, int]:
     """Run WebAuthn authentication flow and return the credential and new sign count.
@@ -39,6 +42,7 @@ async def authenticate_chat(
     Returns:
         tuple of (credential, new_sign_count) where new_sign_count comes from WebAuthn verification
     """
+    origin = validate_origin(ws)
     options, challenge = passkey.instance.auth_generate_options(
         credential_ids=credential_ids
     )
@@ -60,3 +64,52 @@ async def authenticate_chat(
 
     verification = passkey.instance.auth_verify(authcred, challenge, cred, origin)
     return cred, verification.new_sign_count
+
+
+async def authenticate_and_login(
+    ws: WebSocket,
+    auth: str | None = None,
+) -> SessionContext:
+    """Run WebAuthn authentication flow, create session, and return the session context.
+
+    If auth is provided, restrict authentication to credentials of that session's user.
+
+    Returns:
+        SessionContext for the authenticated session
+    """
+    origin = validate_origin(ws)
+    host = origin.split("://", 1)[1]
+    normalized_host = hostutil.normalize_host(host)
+    if not normalized_host:
+        raise ValueError("Host required for session creation")
+    hostname = normalized_host.split(":")[0]
+    rp_id = passkey.instance.rp_id
+    if not (hostname == rp_id or hostname.endswith(f".{rp_id}")):
+        raise ValueError(f"Host must be the same as or a subdomain of {rp_id}")
+    metadata = infodict(ws, "auth")
+
+    # Get credential IDs if restricting to a user's credentials
+    credential_ids = None
+    if auth:
+        existing_ctx = db.data().session_ctx(auth, host)
+        if existing_ctx:
+            credential_ids = db.get_user_credential_ids(existing_ctx.user.uuid) or None
+
+    cred, new_sign_count = await authenticate_chat(ws, credential_ids)
+
+    # Create session and update user/credential
+    token = db.login(
+        user_uuid=cred.user_uuid,
+        credential_uuid=cred.uuid,
+        sign_count=new_sign_count,
+        host=normalized_host,
+        ip=metadata["ip"],
+        user_agent=metadata["user_agent"],
+        expiry=expires(),
+    )
+
+    # Fetch and return the full session context
+    ctx = db.data().session_ctx(token, normalized_host)
+    if not ctx:
+        raise ValueError("Failed to create session context")
+    return ctx

paskia/fastapi/wsutil.py

@@ -3,6 +3,7 @@ Shared WebSocket utilities for FastAPI endpoints.
 """
 
 import logging
+import time
 from functools import wraps
 
 import base64url
@@ -10,6 +11,7 @@ from fastapi import WebSocket, WebSocketDisconnect
 from webauthn.helpers.exceptions import InvalidAuthenticationResponse
 
 from paskia.fastapi import authz
+from paskia.fastapi.logging import log_ws_close, log_ws_open
 from paskia.globals import passkey
 from paskia.util import pow
 
@@ -19,11 +21,15 @@ def websocket_error_handler(func):
 
     @wraps(func)
     async def wrapper(ws: WebSocket, *args, **kwargs):
+        start = time.perf_counter()
+        ws_id = log_ws_open(ws)
+        close_code = None
+
         try:
             await ws.accept()
             return await func(ws, *args, **kwargs)
-        except WebSocketDisconnect:
+        except WebSocketDisconnect as e:
-            pass
+            close_code = e.code
         except authz.AuthException as e:
             await ws.send_json(
                 {
@@ -36,6 +42,8 @@ def websocket_error_handler(func):
         except Exception:
             logging.exception("Internal Server Error")
             await ws.send_json({"status": 500, "detail": "Internal Server Error"})
+        finally:
+            log_ws_close(ws_id, close_code, time.perf_counter() - start)
 
     return wrapper
 

paskia/migrate/__init__.py

@@ -14,7 +14,7 @@ Or via the CLI entry point (if installed):
 import argparse
 import asyncio
 import re
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from uuid import UUID
 
 import base64url
@@ -154,7 +154,7 @@ async def migrate_from_sql(
                 if perm_uuid:
                     new_permissions[perm_uuid] = True
             new_role = Role(
-                org=role.org_uuid,
+                org_uuid=role.org_uuid,
                 display_name=role.display_name,
                 permissions=new_permissions,
             )
@@ -172,8 +172,8 @@ async def migrate_from_sql(
             user_key: UUID = legacy_user.uuid
             new_user = User(
                 display_name=legacy_user.display_name,
-                role=legacy_user.role_uuid,
+                role_uuid=legacy_user.role_uuid,
-                created_at=legacy_user.created_at or datetime.now(timezone.utc),
+                created_at=legacy_user.created_at or datetime.now(UTC),
                 last_seen=legacy_user.last_seen,
                 visits=legacy_user.visits,
             )
@@ -190,7 +190,7 @@ async def migrate_from_sql(
             cred_key: UUID = legacy_cred.uuid
             new_cred = Credential(
                 credential_id=legacy_cred.credential_id,
-                user=legacy_cred.user_uuid,
+                user_uuid=legacy_cred.user_uuid,
                 aaguid=legacy_cred.aaguid,
                 public_key=legacy_cred.public_key,
                 sign_count=legacy_cred.sign_count,
@@ -217,8 +217,8 @@ async def migrate_from_sql(
                 # Already in new format or unknown - try to use as-is
                 session_key = base64url.enc(old_key[:12])
             db.sessions[session_key] = Session(
-                user=sess.user_uuid,
+                user_uuid=sess.user_uuid,
-                credential=sess.credential_uuid,
+                credential_uuid=sess.credential_uuid,
                 host=sess.host,
                 ip=sess.ip,
                 user_agent=sess.user_agent,
@@ -241,14 +241,14 @@ async def migrate_from_sql(
                 # Already in new format or unknown - truncate to 9 bytes
                 token_key = old_key[:9]
             db.reset_tokens[token_key] = ResetToken(
-                user=token.user_uuid,
+                user_uuid=token.user_uuid,
                 expiry=token.expiry,
                 token_type=token.token_type,
             )
         print(f"  Migrated {len(token_models)} reset tokens")
 
     # Queue and flush all changes using the transaction mechanism
-    with db.transaction("migrate"):
+    with db.transaction("migrate:sql"):
         pass  # All data already added to _data, transaction commits on exit
 
     await store.flush()

paskia/migrate/sql.py

@@ -9,7 +9,7 @@ DO NOT use this module for new code. Use paskia.db instead.
 
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from uuid import UUID
 
 from sqlalchemy import (
@@ -25,11 +25,6 @@ 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 paskia.db import (
-    Org,
-    Role,
-)
-
 
 # Legacy User class for SQL schema (uses 'role_uuid' not 'role')
 @dataclass
@@ -71,6 +66,17 @@ class _LegacyRole:
     permissions: list[str] | None = None
 
 
+# Legacy Org class for SQL schema (has mutable permissions/roles lists)
+@dataclass
+class _LegacyOrg:
+    """Org as stored in the old SQL schema with mutable permissions/roles."""
+
+    uuid: UUID
+    display_name: str
+    permissions: list[str] | None = None
+    roles: list[_LegacyRole] | None = None
+
+
 # Legacy Session class for SQL schema (uses 'key' as field, 'user_uuid', 'credential_uuid')
 @dataclass
 class _LegacySession:
@@ -112,8 +118,8 @@ def _normalize_dt(value: datetime | None) -> datetime | None:
     if value is None:
         return None
     if value.tzinfo is None:
-        return value.replace(tzinfo=timezone.utc)
+        return value.replace(tzinfo=UTC)
-    return value.astimezone(timezone.utc)
+    return value.astimezone(UTC)
 
 
 class Base(DeclarativeBase):
@@ -128,12 +134,13 @@ class OrgModel(Base):
 
     def as_dataclass(self):
         # Base Org without permissions/roles (filled by data accessors)
-        org = Org(display_name=self.display_name)
+        return _LegacyOrg(
-        org.uuid = UUID(bytes=self.uuid)
+            uuid=UUID(bytes=self.uuid),
-        return org
+            display_name=self.display_name,
+        )
 
     @staticmethod
-    def from_dataclass(org: Org):
+    def from_dataclass(org: _LegacyOrg):
         return OrgModel(uuid=org.uuid.bytes, display_name=org.display_name)
 
 
@@ -172,7 +179,7 @@ class UserModel(Base):
         LargeBinary(16), ForeignKey("roles.uuid", ondelete="CASCADE"), nullable=False
     )
     created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
     )
     last_seen: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), nullable=True
@@ -195,7 +202,7 @@ class UserModel(Base):
             uuid=user.uuid.bytes,
             display_name=user.display_name,
             role_uuid=user.role_uuid.bytes,
-            created_at=user.created_at or datetime.now(timezone.utc),
+            created_at=user.created_at or datetime.now(UTC),
             last_seen=user.last_seen,
             visits=user.visits,
         )
@@ -215,7 +222,7 @@ class CredentialModel(Base):
     public_key: Mapped[bytes] = mapped_column(BLOB, nullable=False)
     sign_count: Mapped[int] = mapped_column(Integer, nullable=False)
     created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
     )
     last_used: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), nullable=True
@@ -255,7 +262,7 @@ class SessionModel(Base):
     user_agent: Mapped[str] = mapped_column(String(512), nullable=False)
     renewed: Mapped[datetime] = mapped_column(
         DateTime(timezone=True),
-        default=lambda: datetime.now(timezone.utc),
+        default=lambda: datetime.now(UTC),
         nullable=False,
     )
 
@@ -388,7 +395,7 @@ class DB:
             result = await session.execute(select(PermissionModel))
             return [p.as_dataclass() for p in result.scalars().all()]
 
-    async def list_organizations(self) -> list[Org]:
+    async def list_organizations(self) -> list[_LegacyOrg]:
         async with self.session() as session:
             # Load all orgs
             orgs_result = await session.execute(select(OrgModel))
@@ -415,13 +422,13 @@ class DB:
                 perms_by_role.setdefault(rp.role_uuid, []).append(rp.permission_id)
 
             # Build org dataclasses with roles and permission IDs
-            roles_by_org: dict[bytes, list[Role]] = {}
+            roles_by_org: dict[bytes, list[_LegacyRole]] = {}
             for rm in role_models:
                 r_dc = rm.as_dataclass()
                 r_dc.permissions = perms_by_role.get(rm.uuid, [])
                 roles_by_org.setdefault(rm.org_uuid, []).append(r_dc)
 
-            orgs: list[Org] = []
+            orgs: list[_LegacyOrg] = []
             for om in org_models:
                 o_dc = om.as_dataclass()
                 o_dc.permissions = perms_by_org.get(om.uuid, [])

paskia/remoteauth.py

@@ -19,9 +19,9 @@ The first 3 words of the token serve as the pairing code for manual entry.
 
 import asyncio
 import logging
+from collections.abc import Callable
 from dataclasses import dataclass
-from datetime import datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
-from typing import Callable
 from uuid import UUID
 
 from paskia.util import passphrase, pow
@@ -94,7 +94,7 @@ class RemoteAuthManager:
 
     async def _cleanup_expired(self):
         """Remove expired requests and notify waiting clients."""
-        now = datetime.now(timezone.utc)
+        now = datetime.now(UTC)
         expired_keys = []
         async with self._lock:
             for key, req in self._requests.items():
@@ -123,7 +123,7 @@ class RemoteAuthManager:
         Returns:
             (code, expiry) - The 3-word passphrase code and expiration time
         """
-        now = datetime.now(timezone.utc)
+        now = datetime.now(UTC)
         expiry = now + REMOTE_AUTH_LIFETIME
 
         async with self._lock:
@@ -160,7 +160,7 @@ class RemoteAuthManager:
             req = self._requests.get(normalized)
             if req is None:
                 return None
-            now = datetime.now(timezone.utc)
+            now = datetime.now(UTC)
             if now > req.created_at + REMOTE_AUTH_LIFETIME:
                 # Expired
                 del self._requests[normalized]
@@ -331,7 +331,7 @@ class RemoteAuthManager:
             req = self._requests.get(token)
             if req is None:
                 return None
-            now = datetime.now(timezone.utc)
+            now = datetime.now(UTC)
             if now > req.created_at + REMOTE_AUTH_LIFETIME:
                 del self._requests[token]
                 return None

paskia/util/apistructs.py

@@ -0,0 +1,110 @@
+"""API response utilities using msgspec for JSON serialization.
+
+msgspec handles UUID and datetime conversion automatically.
+API structs inherit from db structs with kw_only=True to add uuid/key fields.
+"""
+
+from datetime import UTC, datetime
+from uuid import UUID
+
+import msgspec
+
+from paskia.db.structs import Org, Permission, Role, User
+from paskia.util import useragent
+
+
+def _utc_datetime(dt: datetime | None) -> datetime | None:
+    """Convert datetime to UTC, handling both aware and naive datetimes."""
+    if dt is None:
+        return None
+    if dt.tzinfo:
+        return dt.astimezone(UTC)
+    return dt.replace(tzinfo=UTC)
+
+
+def format_datetime(dt: datetime | None) -> str | None:
+    """Format a datetime to ISO 8601 string with Z suffix for UTC."""
+    if dt is None:
+        return None
+    utc_dt = _utc_datetime(dt)
+    return utc_dt.isoformat().replace("+00:00", "Z") if utc_dt else None
+
+
+# -------------------------------------------------------------------------
+# API structs - inherit from db structs, add uuid for serialization
+# -------------------------------------------------------------------------
+
+
+class ApiUser(User, kw_only=True):
+    """User with uuid serialized."""
+
+    uuid: UUID
+
+    @classmethod
+    def from_db(cls, u: User) -> "ApiUser":
+        return cls(uuid=u.uuid, **msgspec.structs.asdict(u))
+
+
+class ApiOrg(Org, kw_only=True):
+    """Org with uuid serialized."""
+
+    uuid: UUID
+
+    @classmethod
+    def from_db(cls, o: Org) -> "ApiOrg":
+        return cls(uuid=o.uuid, **msgspec.structs.asdict(o))
+
+
+class ApiRole(Role, kw_only=True):
+    """Role with uuid serialized."""
+
+    uuid: UUID
+
+    @classmethod
+    def from_db(cls, r: Role) -> "ApiRole":
+        return cls(uuid=r.uuid, **msgspec.structs.asdict(r))
+
+
+class ApiPermission(Permission, kw_only=True):
+    """Permission with uuid serialized."""
+
+    uuid: UUID
+
+    @classmethod
+    def from_db(cls, p: Permission) -> "ApiPermission":
+        return cls(uuid=p.uuid, **msgspec.structs.asdict(p))
+
+
+class ApiSession(msgspec.Struct):
+    """Session for API responses with computed fields."""
+
+    id: str
+    credential_uuid: UUID = msgspec.field(name="credential")
+    host: str
+    ip: str
+    user_agent: str
+    last_renewed: datetime
+    is_current: bool = False
+    is_current_host: bool = False
+
+    @classmethod
+    def from_db(
+        cls,
+        s,  # Session
+        *,
+        current_key: str,
+        normalized_host: str | None,
+        expires_delta,  # timedelta
+    ) -> "ApiSession":
+        return cls(
+            id=s.key,
+            credential_uuid=s.credential_uuid,
+            host=s.host,
+            ip=s.ip,
+            user_agent=useragent.compact_user_agent(s.user_agent),
+            last_renewed=s.expiry - expires_delta,
+            is_current=s.key == current_key,
+            is_current_host=bool(
+                normalized_host and s.host and s.host == normalized_host
+            ),
+        )

paskia/util/permutil.py

@@ -40,4 +40,4 @@ async def session_context(auth: str | None, host: str | None = None):
     if not auth:
         return None
     normalized_host = normalize_host(host) if host else None
-    return db.get_session_context(auth, normalized_host)
+    return db.data().session_ctx(auth, normalized_host)

paskia/util/sessionutil.py

@@ -1,6 +1,6 @@
 """Utility functions for session validation and checking."""
 
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 
 from paskia.authsession import EXPIRES
 from paskia.db import SessionContext
@@ -34,5 +34,5 @@ def check_session_age(ctx: SessionContext, max_age: str | None) -> bool:
     else:
         auth_time = ctx.session.expiry - EXPIRES
 
-    time_since_auth = datetime.now(timezone.utc) - auth_time
+    time_since_auth = datetime.now(UTC) - auth_time
     return time_since_auth <= max_age_delta

paskia/util/startupbox.py

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

paskia/util/userinfo.py

@@ -1,107 +1,63 @@
 """User information formatting and retrieval logic."""
 
-from datetime import timezone
-
 from paskia import aaguid, db
 from paskia.authsession import EXPIRES
 from paskia.db import SessionContext
-from paskia.util import hostutil, permutil, useragent
+from paskia.util import hostutil, permutil
+from paskia.util.apistructs import ApiSession
 
 
-def _format_datetime(dt):
+def build_session_context(ctx: SessionContext) -> dict:
-    """Format a datetime object to ISO 8601 string with UTC timezone."""
+    """Build session context dict from SessionContext."""
-    if dt is None:
+    result = {
-        return None
+        "user": {"uuid": ctx.user.uuid, "display_name": ctx.user.display_name},
-    if dt.tzinfo:
+        "org": {"uuid": ctx.org.uuid, "display_name": ctx.org.display_name},
-        return dt.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+        "role": {"uuid": ctx.role.uuid, "display_name": ctx.role.display_name},
-    else:
-        return dt.replace(tzinfo=timezone.utc).isoformat().replace("+00:00", "Z")
-
-
-def format_session_context(ctx: SessionContext) -> dict:
-    """Format SessionContext for JSON response."""
-    return {
-        "user": {
-            "uuid": str(ctx.user.uuid),
-            "display_name": ctx.user.display_name,
-        },
-        "org": {
-            "uuid": str(ctx.org.uuid),
-            "display_name": ctx.org.display_name,
-        },
-        "role": {
-            "uuid": str(ctx.role.uuid),
-            "display_name": ctx.role.display_name,
-        },
         "permissions": [p.scope for p in ctx.permissions],
     }
+    if ctx.user.theme:
+        result["user"]["theme"] = ctx.user.theme
+    return result
 
 
-async def format_user_info(
+async def build_user_info(
     *,
     user_uuid,
     auth: str,
     session_record,
     request_host: str | None,
 ) -> dict:
-    """Format complete user information for authenticated users."""
+    """Build user info dict for authenticated users."""
     ctx = await permutil.session_context(auth, request_host)
+    user = db.data().users[user_uuid]
+    normalized_host = hostutil.normalize_host(request_host)
 
-    # Fetch and format credentials
+    credentials = sorted(user.credentials, key=lambda c: c.created_at)
-    user_credentials = [
+    return {
-        c for c in db.data().credentials.values() if c.user == user_uuid
+        "ctx": build_session_context(ctx),
-    ]
+        "created_at": ctx.user.created_at,
-    credentials: list[dict] = []
+        "last_seen": ctx.user.last_seen,
-    user_aaguids: set[str] = set()
+        "visits": ctx.user.visits,
-
+        "credentials": [
-    for c in user_credentials:
-        aaguid_str = str(c.aaguid)
-        user_aaguids.add(aaguid_str)
-        credentials.append(
             {
-                "credential": str(c.uuid),
+                "credential": c.uuid,
-                "aaguid": aaguid_str,
+                "aaguid": c.aaguid,
-                "created_at": _format_datetime(c.created_at),
+                "created_at": c.created_at,
-                "last_used": _format_datetime(c.last_used),
+                "last_used": c.last_used,
-                "last_verified": _format_datetime(c.last_verified),
+                "last_verified": c.last_verified,
                 "sign_count": c.sign_count,
                 "is_current_session": session_record.credential == c.uuid,
             }
-        )
+            for c in credentials
-
+        ],
-    credentials.sort(key=lambda cred: cred["created_at"])
+        "aaguid_info": aaguid.filter(c.aaguid for c in credentials),
-    aaguid_info = aaguid.filter(user_aaguids)
+        "sessions": [
-
+            ApiSession.from_db(
-    # Format sessions
+                s,
-    normalized_request_host = hostutil.normalize_host(request_host)
+                current_key=auth,
-    session_records = [s for s in db.data().sessions.values() if s.user == user_uuid]
+                normalized_host=normalized_host,
-    current_session_key = auth
+                expires_delta=EXPIRES,
-    sessions_payload: list[dict] = []
+            )
-
+            for s in user.sessions
-    for entry in session_records:
+        ],
-        sessions_payload.append(
-            {
-                "id": entry.key,
-                "credential": str(entry.credential),
-                "host": entry.host,
-                "ip": entry.ip,
-                "user_agent": useragent.compact_user_agent(entry.user_agent),
-                "last_renewed": _format_datetime(entry.expiry - EXPIRES),
-                "is_current": entry.key == current_session_key,
-                "is_current_host": bool(
-                    normalized_request_host
-                    and entry.host
-                    and entry.host == normalized_request_host
-                ),
-            }
-        )
-
-    return {
-        "ctx": format_session_context(ctx),
-        "created_at": _format_datetime(ctx.user.created_at),
-        "last_seen": _format_datetime(ctx.user.last_seen),
-        "visits": ctx.user.visits,
-        "credentials": credentials,
-        "aaguid_info": aaguid_info,
-        "sessions": sessions_payload,
     }

pyproject.toml

@@ -74,10 +74,6 @@ filterwarnings = [
     "ignore::DeprecationWarning",
 ]
 
-[tool.ruff]
-target-version = "py39"
-line-length = 88
-
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "W", "UP", "PLC0415"]
 ignore = ["E501"]  # Line too long

scripts/build-frontend.py

@@ -1,43 +1,43 @@
-import shutil
+"""Hatch build hook for building paskia-js and Vue frontend during package build."""
+
 import subprocess
 from pathlib import Path
 from sys import stderr
 
-from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface  # type: ignore
+
+# Import utilities from fastapi-vue
+exec(Path(__file__).parent.joinpath("fastapi-vue", "util.py").read_text("UTF-8"))  # noqa: S102
 
 
 def run(cmd, **kwargs):
+    """Run a command and display it."""
     display_cmd = [Path(cmd[0]).name, *cmd[1:]]
     stderr.write(f"### {' '.join(display_cmd)}\n")
     subprocess.run(cmd, check=True, **kwargs)
 
 
-def find_build_tool():
-    install = [
-        ("deno", "install", "--allow-scripts=npm:vue-demi"),
-        ("npm", "install"),
-        ("bun", "--bun", "install"),
-    ]
-
-    build = [
-        ("deno", "task", "build"),
-        ("npm", "run", "build"),
-        ("bun", "--bun", "run", "build"),
-    ]
-
-    for i, b in zip(install, build, strict=False):
-        if tool := shutil.which(i[0]):
-            return [tool, *i[1:]], [tool, *b[1:]]
-
-    raise RuntimeError("Deno, npm or Bun is required for building but none was found")
-
-
 class CustomBuildHook(BuildHookInterface):
+    """Build hook that compiles paskia-js and Vue frontend before packaging."""
+
     def initialize(self, version, build_data):
         super().initialize(version, build_data)
-        stderr.write(">>> Building the frontend\n")
+        stderr.write(">>> Building paskia-js library\n")
 
-        install_cmd, build_cmd = find_build_tool()
+        install_cmd, build_cmd = find_build_tool()  # noqa: F821 # type: ignore
+
+        try:
+            # Install dependencies for paskia-js
+            run(install_cmd, cwd="paskia-js")
+            stderr.write("\n")
+            # Build paskia-js
+            run(build_cmd, cwd="paskia-js")
+            stderr.write("\n")
+        except Exception as e:
+            stderr.write(f"Error occurred while building paskia-js: {e}\n")
+            raise
+
+        stderr.write(">>> Building the frontend\n")
 
         try:
             run(install_cmd, cwd="frontend")

tests/conftest.py

@@ -28,17 +28,14 @@ from paskia.db import (
     Permission,
     Role,
     User,
-    add_permission_to_org,
     create_credential,
-    create_org,
-    create_permission,
     create_reset_token,
     create_role,
     create_session,
     create_user,
 )
 from paskia.db.jsonl import JsonlStore
-from paskia.db.operations import DB, _create_token
+from paskia.db.operations import DB
 from paskia.fastapi.mainapp import app
 from paskia.fastapi.session import AUTH_COOKIE_NAME
 from paskia.sansio import Passkey
@@ -55,7 +52,13 @@ def event_loop():
 
 @pytest_asyncio.fixture(scope="function")
 async def test_db() -> AsyncGenerator[DB, None]:
-    """Create an in-memory JSON database for testing."""
+    """Create an in-memory JSON database for testing.
+
+    Uses bootstrap() to properly initialize the database with:
+    - auth:admin and auth:org:admin permissions
+    - A default organization with Administration role
+    - An admin user with the Administration role
+    """
 
     with tempfile.NamedTemporaryFile(suffix=".jsonl", delete=True) as f:
         db = DB()
@@ -64,6 +67,11 @@ async def test_db() -> AsyncGenerator[DB, None]:
         await store.load()
         ops_db._db = db
         ops_db._store = store
+        # Bootstrap creates the initial permissions, org, role, and admin user
+        ops_db.bootstrap(
+            org_name="Test Organization",
+            admin_name="Test Admin",
+        )
         yield db
         ops_db._db = None
         ops_db._store = None
@@ -82,49 +90,30 @@ async def passkey_instance() -> Passkey:
     paskia_globals.passkey._instance = None
 
 
-@pytest_asyncio.fixture(scope="function")
-async def test_org(test_db: DB, admin_permission: Permission) -> Org:
-    """Create a test organization with admin permission."""
-    org = Org.create(display_name="Test Organization")
-    create_org(org)
-    # Grant admin permission to this org
-    add_permission_to_org(org.uuid, admin_permission.uuid)
-    return org
-
-
 @pytest_asyncio.fixture(scope="function")
 async def admin_permission(test_db: DB) -> Permission:
-    """Create the auth:admin permission."""
+    """Get the auth:admin permission created by bootstrap."""
-    perm = Permission.create(scope="auth:admin", display_name="Master Admin")
+    return next(p for p in test_db.permissions.values() if p.scope == "auth:admin")
-    create_permission(perm)
-    return perm
 
 
 @pytest_asyncio.fixture(scope="function")
-async def org_admin_permission(test_db: DB, test_org: Org) -> Permission:
+async def org_admin_permission(test_db: DB) -> Permission:
-    """Create the auth:org:admin permission."""
+    """Get the auth:org:admin permission created by bootstrap."""
-    perm = Permission.create(scope="auth:org:admin", display_name="Organization Admin")
+    return next(p for p in test_db.permissions.values() if p.scope == "auth:org:admin")
-    create_permission(perm)
-    # Make it grantable by the org
-    add_permission_to_org(test_org.uuid, perm.uuid)
-    return perm
 
 
 @pytest_asyncio.fixture(scope="function")
-async def test_role(
+async def test_org(test_db: DB) -> Org:
-    test_db: DB,
+    """Get the test organization created by bootstrap."""
-    test_org: Org,
+    # Bootstrap creates exactly one org
-    admin_permission: Permission,
+    return next(iter(test_db.orgs.values()))
-    org_admin_permission: Permission,
+
-) -> Role:
+
-    """Create a test role with admin permission."""
+@pytest_asyncio.fixture(scope="function")
-    role = Role.create(
+async def test_role(test_db: DB) -> Role:
-        org=test_org.uuid,
+    """Get the Administration role created by bootstrap."""
-        display_name="Test Admin Role",
+    # Bootstrap creates exactly one role (Administration)
-        permissions={admin_permission.uuid, org_admin_permission.uuid},
+    return next(iter(test_db.roles.values()))
-    )
-    create_role(role)
-    return role
 
 
 @pytest_asyncio.fixture(scope="function")
@@ -139,14 +128,10 @@ async def user_role(test_db: DB, test_org: Org) -> Role:
 
 
 @pytest_asyncio.fixture(scope="function")
-async def test_user(test_db: DB, test_role: Role) -> User:
+async def test_user(test_db: DB) -> User:
-    """Create a test user with admin role."""
+    """Get the admin user created by bootstrap."""
-    user = User.create(
+    # Bootstrap creates exactly one user (admin)
-        display_name="Test Admin",
+    return next(iter(test_db.users.values()))
-        role=test_role.uuid,
-    )
-    create_user(user)
-    return user
 
 
 @pytest_asyncio.fixture(scope="function")
@@ -193,17 +178,14 @@ async def session_token(
     test_db: DB, test_user: User, test_credential: Credential
 ) -> str:
     """Create a session for the admin user and return the token."""
-    token = _create_token()
+    return create_session(
-    create_session(
         user_uuid=test_user.uuid,
         credential_uuid=test_credential.uuid,
-        key=token,
         host="localhost:4401",
         ip="127.0.0.1",
         user_agent="pytest",
         expiry=expires(),
     )
-    return token
 
 
 @pytest_asyncio.fixture(scope="function")
@@ -211,17 +193,14 @@ async def regular_session_token(
     test_db: DB, regular_user: User, regular_credential: Credential
 ) -> str:
     """Create a session for a regular user and return the token."""
-    token = _create_token()
+    return create_session(
-    create_session(
         user_uuid=regular_user.uuid,
         credential_uuid=regular_credential.uuid,
-        key=token,
         host="localhost:4401",
         ip="127.0.0.1",
         user_agent="pytest",
         expiry=expires(),
     )
-    return token
 
 
 @pytest_asyncio.fixture(scope="function")

tests/test_admin.py

@@ -12,7 +12,8 @@ These tests cover:
 """
 
 import os
-from datetime import datetime, timezone
+import secrets
+from datetime import UTC, datetime
 from uuid import UUID
 
 import httpx
@@ -36,7 +37,7 @@ from paskia.db import (
     create_session,
     create_user,
 )
-from paskia.db.operations import DB, _create_token
+from paskia.db.operations import DB
 from tests.conftest import auth_headers
 
 # -------------------- Additional Fixtures --------------------
@@ -97,17 +98,14 @@ async def second_org_session_token(
     test_db: DB, second_org_user: User, second_org_credential: Credential
 ) -> str:
     """Create a session for the second org admin user."""
-    token = _create_token()
+    return create_session(
-    create_session(
         user_uuid=second_org_user.uuid,
         credential_uuid=second_org_credential.uuid,
-        key=token,
         host="localhost:4401",
         ip="127.0.0.1",
         user_agent="pytest",
         expiry=expires(),
     )
-    return token
 
 
 @pytest_asyncio.fixture(scope="function")
@@ -132,7 +130,7 @@ async def org_admin_user(test_db: DB, org_admin_role: Role) -> User:
         role=org_admin_role.uuid,
     )
     user.visits = 5
-    user.last_seen = datetime.now(timezone.utc)
+    user.last_seen = datetime.now(UTC)
     create_user(user)
     return user
 
@@ -157,17 +155,14 @@ async def org_admin_session_token(
     test_db: DB, org_admin_user: User, org_admin_credential: Credential
 ) -> str:
     """Create a session for the org admin user."""
-    token = _create_token()
+    return create_session(
-    create_session(
         user_uuid=org_admin_user.uuid,
         credential_uuid=org_admin_credential.uuid,
-        key=token,
         host="localhost:4401",
         ip="127.0.0.1",
         user_agent="pytest",
         expiry=expires(),
     )
-    return token
 
 
 @pytest_asyncio.fixture(scope="function")
@@ -1170,11 +1165,9 @@ class TestAdminSessions:
     ):
         """Admin should be able to delete a user's session."""
         # Create an additional session to delete
-        extra_token = _create_token()
+        extra_token = create_session(
-        create_session(
             user_uuid=test_user.uuid,
             credential_uuid=test_credential.uuid,
-            key=extra_token,
             host="other.host:4401",
             ip="192.168.1.1",
             user_agent="other-agent",
@@ -1255,7 +1248,7 @@ class TestAdminSessions:
     ):
         """Deleting non-existent session should fail."""
         # Use a valid format but non-existent key
-        fake_token = _create_token()
+        fake_token = secrets.token_urlsafe(12)
         response = await client.delete(
             f"/auth/api/admin/orgs/{test_org.uuid}/users/{test_user.uuid}/sessions/{fake_token}",
             headers={**auth_headers(session_token), "Host": "localhost:4401"},

tests/test_api.py

@@ -10,14 +10,14 @@ These tests cover:
 - /auth/api/set-session - Set session from bearer token
 """
 
-from datetime import datetime, timedelta, timezone
+import secrets
+from datetime import UTC, datetime, timedelta
 
 import httpx
 import pytest
 
 from paskia.authsession import EXPIRES
 from paskia.db import create_session, delete_session
-from paskia.db.operations import _create_token
 from paskia.util.passphrase import generate
 from tests.conftest import auth_headers
 
@@ -503,7 +503,7 @@ class TestValidateSessionRefresh:
         """Validate should handle session expiry during refresh attempt."""
 
         # Create a token but don't create a session for it
-        token = _create_token()
+        token = secrets.token_urlsafe(12)
         response = await client.post(
             "/auth/api/validate",
             headers={**auth_headers(token), "Host": "localhost:4401"},
@@ -522,12 +522,10 @@ class TestValidateSessionRefresh:
         """Validate should return 401 if session disappears during refresh."""
 
         # Create a session with an old expiry time to trigger refresh
-        token = _create_token()
+        old_expiry = datetime.now(UTC) + EXPIRES - timedelta(minutes=10)
-        old_expiry = datetime.now(timezone.utc) + EXPIRES - timedelta(minutes=10)
+        token = create_session(
-        create_session(
             user_uuid=test_user.uuid,
             credential_uuid=test_credential.uuid,
-            key=token,
             host="localhost:4401",
             ip="127.0.0.1",
             user_agent="pytest",