Admin UI remote option; docs match simplified protocol

Domain edit dialog: satellite-mode toggle with remote URL, write-only sync token, cache TTL and re-sync interval, with auth-host requirement validated before submit; domain list marks remote domains. AdminApp sends remote wholesale on PATCH (null clears, absent token keeps the stored one).
Fix sync client resync condition (ready-tracked, not staging)
2026-09-21 01:14:00 +00:00 · 2026-09-21 01:07:47 +00:00 · 2026-09-21 01:04:53 +00:00 · 2026-09-20 23:46:53 +00:00 · 2026-09-20 23:45:01 +00:00 · 2026-09-20 23:26:00 +00:00
46 changed files with 2347 additions and 532 deletions
@@ -188,11 +188,12 @@ Paste the following and save:

 ```ini
 [Unit]
-Description=Paskia
+Description=Paskia authentication system

 [Service]
 Type=simple
 User=paskia
+SyslogIdentifier=paskia
 WorkingDirectory=/srv/paskia
 ExecStart=uvx paskia@latest

@@ -0,0 +1,176 @@
+# Remote Proxy / Satellite
+
+Paskia can serve a configured domain (rp-id) from a **remote** paskia
+instance instead of the local database, so latency-sensitive checks
+(`/auth/api/forward`, `/auth/api/validate`) answer in ~1 ms even when the
+auth server is on another continent. Example: `app2.example.com` runs on
+our local host and needs fast local checks, while `app1.example.com` and
+`auth.example.com` run far away — all sharing `example.com` as rp-id.
+
+Client applications that used `https://auth.example.com` as their auth
+backend (forward-auth checks) only repoint to the local satellite
+(`http://127.0.0.1:4401`); both remain usable interchangeably, and the
+satellite ultimately uses `auth.example.com`.
+
+Status: **implemented**. The feature lives in `paskia/satellite.py`
+(satellite side: replica, sync client, host dispatch, forwarding) and
+`paskia/syncfeed.py` + `paskia/fastapi/sync.py` (remote side: change
+feed and sync WebSocket). The design review comparing the rejected
+alternatives is at the end of this document.
+
+## Configuration
+
+A domain becomes remote in the admin domains UI (master admin, on the
+primary server's auth host — this configuration itself never touches a
+remote): enable *Remote instance* and set the remote URL and sync token.
+In the stored config (`DomainConfig.remote`):
+
+```json
+"remote": {
+  "url": "https://auth.example.com",
+  "token": "<sync token>",
+  "cache_ttl": 60,
+  "refresh_interval": 300
+}
+```
+
+- `url` — the remote instance's base URL. The satellite connects to
+  `{url}/auth/api/sync/ws`; the connection is server-to-server and not
+  host-dispatched, so internal addresses work.
+- `token` — bearer token for the sync channel. The **remote accepts tokens
+  via its `PASKIA_SYNC_TOKENS` environment variable** (comma-separated);
+  nothing is stored in the remote's database, and with the variable unset
+  the sync endpoint stays closed. The token is write-only over the admin
+  API (an empty field keeps the stored one).
+- `cache_ttl` — seconds the replica remains trusted after the sync channel
+  goes down; then checks fail closed (503). Set it large (up to the 24 h
+  session lifetime) for fail-open behavior.
+- `refresh_interval` — seconds between reconnects; every connect starts
+  from a full snapshot, which reconciles any drift.
+
+A remote domain **must mark an auth host** (validated cross-domain and in
+the UI): the profile, admin and sign-in pages live there, so browsers and
+WebSockets go directly to the remote. Other domains on the same satellite
+remain fully local — the multi-domain config mixes both kinds freely.
+
+## How it works
+
+**Dispatch is keyed by host, and only this module knows about stores.**
+`satellite.store_for_host(host)` returns the local DB or the replica of
+the remote backing the host's domain (raising 503 `HTTPException` when
+the replica is unavailable). The session read path (`session_ctx`,
+`authz.verify`, `build_user_info`, `/check`) just passes the host it
+already has; writes dispatch likewise (`satellite.refresh_session` —
+write-behind for remote, `db.update_session` for local;
+`satellite.evict_session` on logout). `satellite.forward_request(request)`
+returns the proxied response for remote domains or `None` for local ones.
+
+**The replica** is a plain `DB` struct instance in RAM, never persisted.
+On connect the remote sends a snapshot of the replicated tables
+(permissions, orgs, roles, users, credentials, sessions), then live
+upsert/delete events emitted from the struct `store()`/`delete()` hooks
+(which also cover cascade deletes) and field-mutating operations. A
+single ordered WebSocket cannot gap; a slow subscriber is dropped and
+resyncs. The feed carries no usable secrets: sessions are keyed by
+`hash_secret` output, credentials carry public keys only, and the OIDC
+signing key is never replicated.
+
+## Endpoint behavior for remote domains
+
+| Endpoint | Handling |
+|---|---|
+| `GET /auth/api/forward`, `GET /check`, `GET /user-info`, `GET /settings` | served from the replica (sub-ms) |
+| `POST /auth/api/validate` | verified from the replica; the throttled refresh updates the replica and is written back over the sync channel; cookie renewed locally |
+| `POST /auth/api/logout` | proxied to the remote (original Host preserved) and evicted from the replica immediately |
+| `POST /auth/api/set-session`, `GET /token-info` | proxied (the exchange code/reset token lives on the remote); the session arrives via sync event |
+| `/auth/oidc/*` | proxied (signing key and OIDC sessions stay on the remote) |
+| `/auth/ws/*`, `/auth/remote-auth/*`, admin, profile | not served — the auth host requirement means these are reached on the remote directly |
+
+Freshness hierarchy:
+
+1. Changes made **through** the satellite: immediate (write-behind,
+   optimistic eviction).
+2. Changes made **directly on the remote**: a sync event, ~1 network RTT.
+3. Channel down: the replica stays authoritative until `cache_ttl` past
+   the disconnect (dead-peer detection is bounded by the ~10 s keepalive),
+   then 503. Every reconnect starts from a fresh snapshot.
+
+## The remote side
+
+Strictly additive and RAM-only: `syncfeed` (a subscriber set fed by the
+commit hooks) and the token-gated `/auth/api/sync/ws` endpoint serving
+snapshot + live events and accepting `session_refresh` write-backs. With
+no satellites connected, the hooks are a no-op.
+
+## Trust and caveats
+
+- The satellite host holds a full copy of the remote's auth data in RAM
+  (minus the OIDC key) — treat it as trusted as the remote.
+- Avatars are stored on the remote's disk; `user-info` from a replica
+  reports no avatar URL.
+- OIDC sessions in a replica-backed `user-info` show the client UUID
+  rather than its name (OIDC clients are not replicated).
+
+---
+
+# Design review (the rejected alternatives)
+
+## Option A — caching HTTP reverse proxy
+
+A thin proxy caching `/auth/api/forward`, `/check`, `/user-info`,
+`/settings` responses keyed by `(Host, cookie, query)` with
+`TTL = min(configured TTL, Remote-Session-Expires − now)`; everything
+else forwarded verbatim, WebSockets tunneled, `/logout` intercepted for
+eviction. **Option B** adds a remote change feed so eviction happens
+within one RTT instead of at TTL.
+
+- Remote changes: none for A; one additive endpoint for B.
+- The proxy needs no credentials — requests are authenticated by the end
+  user's cookie, forwarded on a miss.
+
+## What the read-only local state buys over the HTTP cache
+
+- **Full `SessionContext` locally.** A replays the byte-response it once
+  saw; the satellite *computes* the answer. Query combinations never seen
+  before (new `perm`/`max_age`/`public` shapes) are served locally but
+  miss A's cache. The replica holds the *domain model*, so derived
+  answers (effective permissions per host, `max_age` against
+  `credential.last_used`, `Remote-*` composition) are correct without
+  having been witnessed.
+- **One invalidation model.** A hand-builds invalidation rules per
+  endpoint (query-key mapping, cookie re-keying on renew, 401 variants).
+  Events mutate the replica (upsert/delete by table+key) and every
+  endpoint becomes consistent at once — including future ones.
+- **Degradation behaves like a real instance.** With the remote down, the
+  satellite serves a coherent auth service from the replica (expiry
+  enforced locally, bounded by `cache_ttl`); A serves unrelated cached
+  responses with gaps wherever the cache was cold.
+- **Multi-domain uniformity.** Remote backing is a property of a domain
+  in the existing registry; local and remote rp-ids coexist in one
+  instance. A is a separate component bolted in front of specific URLs.
+- **User simplicity.** Configured once in domain config; A needs
+  deployment and cache-key discipline per frontend application.
+
+## What it costs
+
+- The read path must be honest about which DB it reads: `DB.session_ctx`
+  and `/check` were rewritten to use their own tables instead of struct
+  convenience properties that reach the global database. (A first draft's
+  contextvar-dependent `db.data()` was rejected: a global accessor whose
+  meaning shifts under the caller. Dispatch is instead keyed explicitly
+  by the request host.)
+- A sync protocol (snapshot + live events + reconnect reconciliation).
+- A trusted satellite host (full data copy in RAM).
+- Additive remote code (sync endpoint + commit hooks), where A needs
+  none.
+- Replica housekeeping (expiry sweeper, write-behind, optimistic
+  eviction).
+
+## Summary
+
+A(+B) is the right tool to "make forward-auth fast in front of an
+untouched server". The satellite — implemented here — is the right tool
+when it should *be* a paskia instance for its remote domains: one
+consistency model, correct answers for un-cached query shapes, graceful
+degradation, and per-domain mixing with local rp-ids, at the price of the
+read-path cleanup, the sync protocol, and a trusted satellite host.
@@ -8,6 +8,17 @@
        :root {
            color-scheme: light dark;  /* Automatic themes by browser */
        }
+        .section a, .section button {
+            display: inline-block;
+            padding: 0.4em;
+            margin-right: 0.3em;
+            border: none;
+            background: #aaa2;
+            color: inherit;
+            font: inherit;
+            text-decoration: none;
+            cursor: pointer;
+        }
    </style>
 </head>
 <body>
@@ -20,13 +31,14 @@
        <div class="content">
            <div class="section">
                <h2>Management Site</h2>
-                <button onclick="window.open('/auth/', '_blank')">👤 User Profile</button>
-                <button onclick="window.open('/auth/admin/', '_blank')">⚙️ Admin Panel</button>
+                <a href="/auth/">👤 User Profile</a>
+                <a href="/auth/admin/">⚙️ Admin Panel</a>
            </div>

            <div class="section">
                <h2>API Mode (not leaving the page)</h2>
                <p>For SPAs and fetch() calls - shows auth in an iframe overlay:</p>
+                <button onclick="profileDemo()">👤 Login/Profile</button>
                <button onclick="apiCall('/auth/api/user-info', 'GET')">📋 Get User Info</button>
                <button onclick="apiCall('/auth/api/forward?max_age=10s')">🔄 Reauth (max_age=10s)</button>
                <button onclick="apiCall('/auth/api/forward?perm=auth:admin')">🛡️ Admin Only</button>
@@ -35,10 +47,10 @@

            <div class="section">
                <h2>Browser Mode (full page)</h2>
-                <p>Block access to otherwise open site - intended for forward-auth mechanism (Caddy, Nginx):</p>
-                <button onclick="browserNav('/auth/api/forward')">🔐 Basic Auth</button>
-                <button onclick="browserNav('/auth/api/forward?max_age=10s')">🔄 Reauth (max_age=10s)</button>
-                <button onclick="browserNav('/auth/api/forward?perm=auth:admin')">🛡️ Admin Only</button>
+                <p>Block access to otherwise open site - intended for forward-auth mechanism (Caddy, Nginx). If not authenticated, you'll see the login page; after auth, a 204 response (blank page = success). Back returns here:</p>
+                <a href="/auth/api/forward">🔐 Basic Auth</a>
+                <a href="/auth/api/forward?max_age=10s">🔄 Reauth (max_age=10s)</a>
+                <a href="/auth/api/forward?perm=auth:admin">🛡️ Admin Only</a>
            </div>

            <pre id="output">Click a button to test...</pre>
@@ -46,52 +58,51 @@
    </div>

    <script type="module">
-        import { apiFetch, apiJson, AuthCancelledError } from '/paskia-js/dist/paskia.js'
-
-        const output = document.getElementById('output');
+        import { apiFetch, apiJson, AuthCancelledError, profile } from '/paskia-js/dist/paskia.js'

        function log(msg) {
-            output.textContent = msg;
+            console.log(msg)
+            document.getElementById('output').textContent = msg
        }

        // Make an API call using paskia module (handles 401/403 automatically)
        window.apiCall = async function(url, method = 'GET') {
-            log(`${method} ${url}...`);
+            log(`${method} ${url}...`)
            try {
-                const response = await apiFetch(url, { method });
+                const response = await apiFetch(url, { method })

                // Forward endpoint returns 204 on success
                if (response.status === 204) {
-                    log('✓ Success (204 No Content)');
-                    return;
+                    log('✓ Success (204 No Content)')
+                    return
                }

                if (!response.ok) {
-                    log(`Error: ${response.status} ${response.statusText}`);
-                    return;
+                    log(`Error: ${response.status} ${response.statusText}`)
+                    return
                }

-                const data = await response.json();
-                log('✓ Response:\n' + JSON.stringify(data, null, 2));
+                const data = await response.json()
+                log('✓ Response:\n' + JSON.stringify(data, null, 2))
            } catch (e) {
                if (e instanceof AuthCancelledError) {
-                    log('Authentication cancelled');
+                    log('Authentication cancelled')
                } else {
-                    log(`Error: ${e.message}`);
+                    log(`Error: ${e.message}`)
                }
            }
        }

        window.logout = async function() {
-            await fetch('/auth/api/logout', { method: 'POST' });
-            log('Logged out');
+            await fetch('/auth/api/logout', { method: 'POST' })
+            log('Logged out')
        }

-        // Browser mode: open the forward endpoint directly in a new window.
-        window.browserNav = function(url) {
-            log('Opening in new window...\nIf not authenticated, you\'ll see the login page.\nAfter auth, you\'ll see a 204 response (blank page = success).');
-            window.open(url, '_blank');
+        // Profile dialog: resolves 'login' / 'logout' / 'back'
+        window.profileDemo = async function() {
+            log(`Profile return: ${await profile()}`)
        }
+
    </script>
 </body>
 </html>
@@ -2,7 +2,14 @@
  <div class="app-shell">
    <StatusMessage />
    <main class="app-main">
-      <HostProfileView v-if="viewState === 'profile' && isHostMode" />
+      <HostProfileView
+        v-if="viewState === 'profile' && isHostMode"
+        :ctx="store.ctx"
+        :user-info="store.userInfo"
+        :settings="store.settings"
+        @back="goBack"
+        @logout="onHostLogout"
+      />
      <ProfileView v-else-if="viewState === 'profile'" />
      <LoadingView v-else-if="viewState === 'loading'" :message="loadingMessage" />
      <AccessDenied v-else-if="viewState === 'terminal'" />
@@ -15,6 +22,7 @@ import { computed, onMounted, onUnmounted, ref } from 'vue'
 import { useAuthStore } from '@/stores/auth'
 import { apiJson, SessionValidator, settings as paskiaSettings } from 'paskia'
 import { updateThemeFromSession } from '@/utils/theme'
+import { goBack } from '@/utils/helpers'
 import StatusMessage from '@/components/StatusMessage.vue'
 import ProfileView from '@/components/ProfileView.vue'
 import HostProfileView from '@/components/HostProfileView.vue'
@@ -48,6 +56,12 @@ const isHostMode = computed(() => {
  return currentHost !== configuredHost
 })

+// HostProfileView already posted /auth/api/logout; clear local state and reload.
+function onHostLogout() {
+  sessionStorage.clear()
+  window.location.reload()
+}
+
 function onSessionLost(e) {
  store.userInfo = null
  store.ctx = null
@@ -480,6 +480,7 @@ function createDomain() {
    origins: [],
    originValidation: [],
    wellKnownCheck: null,
+    remote: null,
  })
 }

@@ -495,6 +496,8 @@ function openDomain(domain) {
    origins: rows.map(r => r.key),
    originValidation: rows.map(() => null),
    wellKnownCheck: null,
+    // The sync token is write-only: an empty field keeps the stored one
+    remote: domain.remote ? { ...domain.remote, token: '' } : null,
  })
 }

@@ -923,9 +926,19 @@ async function submitDialog() {
      }

      closeDialog()
+      // remote is replaced wholesale when present; null clears it, an
+      // absent key (create without remote) leaves it unset.
+      const remote = d.remote?.url?.trim()
+        ? {
+            url: d.remote.url.trim().replace(/\/+$/, ''),
+            token: d.remote.token || '',
+            cache_ttl: Number(d.remote.cache_ttl) || 60,
+            refresh_interval: Number(d.remote.refresh_interval) || 300,
+          }
+        : null
      const req = d.isNew
-        ? apiJson('/auth/api/admin/domains/', { method: 'POST', body: { rp_id, rp_name, origins } })
-        : apiJson(`/auth/api/admin/domains/${rp_id}`, { method: 'PATCH', body: { rp_name, origins } })
+        ? apiJson('/auth/api/admin/domains/', { method: 'POST', body: { rp_id, rp_name, origins, ...(remote ? { remote } : {}) } })
+        : apiJson(`/auth/api/admin/domains/${rp_id}`, { method: 'PATCH', body: { rp_name, origins, remote } })
      req
        .then(() => {
          authStore.showMessage(`Domain "${rp_id}" ${d.isNew ? 'created' : 'updated'}.`, 'success', 2500)
@@ -1,5 +1,36 @@
 <template>
+  <template v-if="authMode === 'profile'">
+    <!--
+      Profile mode: render nothing until the session check completes (avoids
+      a load-time flash of the wrong view). Without a session, the login flow
+      runs in place of the profile; on success auth-success is posted and the
+      host resolves profile() with 'login'.
+    -->
+    <RestrictedAuth
+      v-if="profileState === 'login'"
+      mode="login"
+      @authenticated="handleAuthenticated"
+      @back="handleBack"
+    />
+    <HostProfileView
+      v-else-if="profileState === 'ready'"
+      :ctx="profileCtx"
+      :user-info="profileInfo"
+      :settings="profileSettings"
+      @back="handleBack"
+      @logout="handleLogout"
+    />
+    <div v-else class="view-root profile-pending">
+      <div class="surface surface--tight">
+        <p class="view-lede">{{ profileState === 'error' ? 'Could not load your account.' : 'Loading your account…' }}</p>
+        <div class="button-row">
+          <button type="button" class="btn-secondary" @click="handleBack">Back</button>
+        </div>
+      </div>
+    </div>
+  </template>
  <RestrictedAuth
+    v-else
    :mode="authMode"
    :remote-auth-token="remoteAuthToken"
    :oidc-query-string="oidcQueryString"
@@ -11,6 +42,10 @@
 <script setup>
 import { onMounted, ref } from 'vue'
 import RestrictedAuth from '@/components/RestrictedAuth.vue'
+import HostProfileView from '@/components/HostProfileView.vue'
+import { fetchJson, settings as paskiaSettings } from 'paskia'
+import { getSettings } from '@/utils/settings'
+import { updateThemeFromSession } from '@/utils/theme'

 // Check if this is a remote auth URL: /auth/{token}
 // The token is a 5-word passphrase like "word1.word2.word3.word4.word5"
@@ -45,8 +80,32 @@ let authMode
 if (window.location.pathname === '/auth/restricted/oidc') {
  authMode = 'oidc'
 } else {
-  // Both iframe and forward auth use hash params for mode (forbidden/login/reauth)
-  authMode = ['reauth', 'forbidden'].includes(hashParams.get('mode')) ? hashParams.get('mode') : 'login'
+  // Both iframe and forward auth use hash params for mode (forbidden/login/reauth/profile)
+  authMode = ['reauth', 'forbidden', 'profile'].includes(hashParams.get('mode')) ? hashParams.get('mode') : 'login'
+}
+
+// Profile mode state: 'loading' | 'login' | 'ready' | 'error'
+const profileState = ref('loading')
+const profileCtx = ref(null)
+const profileInfo = ref(null)
+const profileSettings = ref(null)
+
+async function loadProfile() {
+  try {
+    const [validateData, infoData, settingsData] = await Promise.all([
+      fetchJson('/auth/api/validate', { method: 'POST', timeout: paskiaSettings.auth_ms }),
+      fetchJson('/auth/api/user-info', { method: 'GET', timeout: paskiaSettings.auth_ms }),
+      getSettings()
+    ])
+    profileCtx.value = validateData.ctx
+    profileInfo.value = infoData
+    profileSettings.value = settingsData
+    updateThemeFromSession(validateData.ctx)
+    profileState.value = 'ready'
+  } catch (error) {
+    // No/expired session: run the login flow in place of the profile
+    profileState.value = error.status === 401 || error.status === 403 ? 'login' : 'error'
+  }
 }

 function postToParent(message) {
@@ -74,10 +133,18 @@ function handleBack() {
  })
 }

+function handleLogout() {
+  postToParent({
+    type: 'auth-logout'
+  })
+}
+
 onMounted(() => {
  // Check for remote auth token in URL
  remoteAuthToken.value = extractRemoteToken()

+  if (authMode === 'profile') loadProfile()
+
  postToParent({
    type: 'auth-ready'
  })
@@ -89,3 +156,15 @@ onMounted(() => {
  })
 })
 </script>
+
+<style scoped>
+.view-root.profile-pending { min-height: 100vh; align-items: center; justify-content: center; padding: 2rem 1rem; }
+.profile-pending .surface {
+  max-width: 520px;
+  margin: 0 auto;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 1.75rem;
+}
+</style>
@@ -3,7 +3,7 @@
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <script>{let t=localStorage.getItem('paskia-theme');if(!t){let p=new URLSearchParams(location.hash.slice(1)).get('theme');if(p==='light'||p==='dark')t=p}(t==='dark'||t!=='light'&&matchMedia('(prefers-color-scheme:dark)').matches)&&document.documentElement.classList.add('dark');if(window.location.pathname==='/auth/restricted/iframe')document.documentElement.style.background='transparent'}</script>
+    <script>{let t=new URLSearchParams(location.hash.slice(1)).get('theme');if(t!=='light'&&t!=='dark')t=localStorage.getItem('paskia-theme');(t==='dark'||t!=='light'&&matchMedia('(prefers-color-scheme:dark)').matches)&&document.documentElement.classList.add('dark');if(window.location.pathname==='/auth/restricted/iframe')document.documentElement.style.background='transparent'}</script>
    <link rel="stylesheet" href="/src/assets/style.css">
  </head>
  <body>
@@ -464,6 +464,7 @@ defineExpose({ focusFirstElement })
            </div>
            <div class="perm-id-info">
              <span class="id-text">{{ domain.rp_id }}</span>
+              <span v-if="domain.remote" class="id-text" :title="`Served from remote ${domain.remote.url} (satellite mode)`">🛰 {{ domain.remote.url }}</span>
            </div>
          </td>
          <td class="domain-origins"><span v-for="(e, i) in originDisplayEntries(domain)" :key="e.key">{{ i ? ', ' : '' }}{{ e.key }}{{ e.auth ? '🔑' : '' }}{{ e.related ? '🔗' : '' }}</span></td>
@@ -18,6 +18,33 @@ const title = computed(() =>
 // compares against it, and hosts are case-insensitive)
 const dialogRpId = computed(() => (props.dialog.data?.rp_id || '').trim().toLowerCase())

+// --- Remote (satellite) backing ---
+//
+// A remote domain is served from another paskia instance: this one keeps a
+// RAM-only read replica for fast local session checks and forwards
+// mutations. The remote must accept our sync token via its
+// PASKIA_SYNC_TOKENS environment variable. An auth host (the remote's) is
+// required — profile, admin and sign-in pages live there.
+const remoteEnabled = computed({
+  get: () => !!props.dialog.data?.remote,
+  set: on => {
+    const d = props.dialog.data
+    if (!d) return
+    d.remote = on ? { url: '', token: '', cache_ttl: 60, refresh_interval: 300 } : null
+  },
+})
+
+const remoteUrlInvalid = computed(() => {
+  const url = props.dialog.data?.remote?.url?.trim()
+  if (!url) return false
+  return !/^https?:\/\/[^\s/]+/.test(url)
+})
+
+// Remote domains must mark an auth host (the server rejects the save)
+const remoteMissingAuthHost = computed(
+  () => !!props.dialog.data?.remote && !props.dialog.data?.auth_host
+)
+
 // Block submit on hard errors: malformed entries, an over-cap related
 // list (the server rejects the save), a save that would lock the admin
 // out of the domain they are using, or validation still in flight.
@@ -31,6 +58,8 @@ const isValidationInvalid = computed(() => {
  if (relatedEntries.value.length > 5) return true
  if (d.isNew && !isWellFormedDomain(d.rp_id || '')) return true
  if (lockoutWarning.value) return true
+  if (remoteUrlInvalid.value || remoteMissingAuthHost.value) return true
+  if (d.remote && !d.remote.url?.trim()) return true
  return false
 })

@@ -515,6 +544,33 @@ function onRemoveOrigin(i) {
    <p class="small muted">
      Only the listed sites may sign in with {{ dialog.data.rp_id }} passkeys. Wildcards may be used: <strong>**.{{ dialog.data.rp_id }}</strong> allows the whole domain, <strong>*.{{ dialog.data.rp_id }}</strong> only a single subdomain level.<template v-if="relatedEntries.length"> 🔗 means related host requiring WebAuthn ROR setup.</template><template v-if="dialog.data.auth_host"> 🔑 is the dedicated Paskia host for all account management.</template>
    </p>
+
+    <div class="origin-label">
+      <label class="remote-toggle">
+        <input type="checkbox" v-model="remoteEnabled" />
+        Remote instance (satellite mode)
+      </label>
+    </div>
+    <template v-if="dialog.data.remote">
+      <label>Remote URL
+        <input v-model="dialog.data.remote.url" placeholder="https://auth.example.com" data-form-type="other" :class="{ 'input-error': remoteUrlInvalid }" />
+      </label>
+      <p v-if="remoteUrlInvalid" class="small error">Must be an http(s) URL.</p>
+      <p v-if="remoteMissingAuthHost" class="small error">A remote domain must mark an auth host above — profile, admin and sign-in pages live there (typically the remote's own site).</p>
+      <label>Sync token
+        <input v-model="dialog.data.remote.token" type="password" placeholder="Token in the remote's PASKIA_SYNC_TOKENS" autocomplete="off" data-form-type="other" />
+      </label>
+      <p class="small muted">Accepted by the remote via its PASKIA_SYNC_TOKENS environment variable.<template v-if="!dialog.data.isNew"> Leave empty to keep the stored token.</template></p>
+      <label>Staleness limit (cache TTL, seconds)
+        <input v-model.number="dialog.data.remote.cache_ttl" type="number" min="1" />
+      </label>
+      <label>Full re-sync interval (seconds)
+        <input v-model.number="dialog.data.remote.refresh_interval" type="number" min="30" />
+      </label>
+      <p class="small muted">
+        Session checks run locally against a RAM replica of the remote (sub-millisecond). If the connection is down longer than the staleness limit, checks fail closed (503).
+      </p>
+    </template>
  </AdminDialog>
 </template>

@@ -540,4 +596,7 @@ function onRemoveOrigin(i) {
  border-color: var(--color-error);
  background: var(--color-error-bg, rgba(239, 68, 68, 0.05));
 }
+
+.remote-toggle { display: flex; align-items: center; gap: var(--space-xs); font-weight: 600; font-size: 0.95rem; }
+.remote-toggle input { width: auto; }
 </style>
@@ -1,92 +1,116 @@
 <template>
-  <section class="view-root view-root--wide host-view" data-view="host-profile">
-    <header class="view-header">
-      <h1>{{ headingTitle }}</h1>
-      <p class="view-lede">{{ subheading }}</p>
-    </header>
+  <div class="view-root host-profile" data-view="host-profile">
+    <div class="surface surface--tight">
+      <!-- Heading/lede belong to the standalone page; in the dialog the host
+           page already provides the surrounding context. -->
+      <header v-if="!inIframe" class="view-header center">
+        <h1>{{ headingTitle }}</h1>
+        <p class="view-lede">{{ subheading }}</p>
+      </header>

-    <section class="section-block" ref="userInfoSection">
-      <div class="section-body">
-        <UserBasicInfo
-          v-if="ctx"
-          :name="ctx.user.display_name"
-          :avatar-url="authStore.userInfo.user.avatar_url"
-          :visits="authStore.userInfo.user.visits"
-          :created-at="authStore.userInfo.user.created_at"
-          :last-seen="authStore.userInfo.user.last_seen"
-          :email="ctx.user.email"
-          :telephone="ctx.user.telephone"
-          :org-display-name="orgDisplayName"
-          :role-name="roleDisplayName"
-          :can-edit="false"
-        />
-        <p v-else class="empty-state">
-          {{ initializing ? 'Loading your account…' : 'No active session found.' }}
-        </p>
-      </div>
-    </section>
-
-    <section class="section-block">
-      <div class="section-body host-actions">
-        <div class="button-row" ref="buttonRow" @keydown="handleButtonRowKeydown">
-          <button
-            type="button"
-            class="btn-secondary"
-            @click="goBack"
-          >
-            Back
-          </button>
-          <button
-            type="button"
-            class="btn-danger"
-            :disabled="authStore.isLoading"
-            @click="logout"
-          >
-            {{ authStore.isLoading ? 'Signing out…' : 'Logout' }}
-          </button>
-          <button
-            v-if="authSiteUrl"
-            type="button"
-            class="btn-primary"
-            :disabled="authStore.isLoading"
-            @click="goToAuthSite"
-          >
-            Full Profile
-          </button>
+      <section class="section-block">
+        <div class="section-body">
+          <UserBasicInfo
+            v-if="sessionCtx && info"
+            :name="sessionCtx.user.display_name"
+            :avatar-url="info.user.avatar_url"
+            :visits="info.user.visits"
+            :created-at="info.user.created_at"
+            :last-seen="info.user.last_seen"
+            :email="sessionCtx.user.email"
+            :telephone="sessionCtx.user.telephone"
+            :org-display-name="orgDisplayName"
+            :role-name="roleDisplayName"
+            :can-edit="false"
+          />
+          <p v-else class="empty-state">
+            {{ loading ? 'Loading your account…' : 'No active session found.' }}
+          </p>
        </div>
-        <p class="note"><strong>Logout</strong> from {{ currentHost }}, or access your <strong>Full Profile</strong> at {{ authSiteHost }} (you may need to sign in again).</p>
-      </div>
-    </section>
-  </section>
+      </section>
+
+      <section class="section-block">
+        <div class="section-body host-actions">
+          <div class="button-row" ref="buttonRow" @keydown="handleButtonRowKeydown">
+            <button
+              type="button"
+              class="btn-secondary"
+              @click="$emit('back')"
+            >
+              Back
+            </button>
+            <button
+              v-if="sessionCtx"
+              type="button"
+              class="btn-danger"
+              :disabled="busy"
+              @click="logout"
+            >
+              {{ busy ? 'Signing out…' : 'Logout' }}
+            </button>
+            <button
+              type="button"
+              class="btn-primary"
+              :disabled="busy"
+              @click="goToAuthSite"
+            >
+              Full Profile
+            </button>
+          </div>
+          <p v-if="!inIframe" class="note"><strong>Logout</strong> from {{ currentHost }}, or view your <strong>Full Profile</strong> at {{ authSiteHost }} (you may need to sign in again).</p>
+        </div>
+      </section>
+    </div>
+  </div>
 </template>

 <script setup>
-import { computed, ref } from 'vue'
+import { computed, onMounted, ref } from 'vue'
 import UserBasicInfo from '@/components/UserBasicInfo.vue'
-import { useAuthStore } from '@/stores/auth'
-import { goBack } from '@/utils/helpers'
+import { getSettings } from '@/utils/settings'
+import { fetchJson, settings as paskiaSettings } from 'paskia'
+import { updateThemeFromSession } from '@/utils/theme'
 import { getDirection, navigateButtonRow } from '@/utils/keynav'

-defineProps({
-  initializing: {
-    type: Boolean,
-    default: false
+// Data may be provided by the parent (full-page /auth/ app already loaded it
+// into the store); otherwise the component fetches it itself (restricted iframe).
+const props = defineProps({
+  ctx: {
+    type: Object,
+    default: null
+  },
+  userInfo: {
+    type: Object,
+    default: null
+  },
+  settings: {
+    type: Object,
+    default: null
  }
 })

-const authStore = useAuthStore()
+const emit = defineEmits(['back', 'logout'])
+
+const inIframe = window.parent !== window
 const currentHost = window.location.host

+const fetchedCtx = ref(null)
+const fetchedInfo = ref(null)
+const fetchedSettings = ref(null)
+const loading = ref(!(props.ctx && props.userInfo))
+const busy = ref(false)
+
 // Template refs for navigation
-const userInfoSection = ref(null)
 const buttonRow = ref(null)

-const ctx = computed(() => authStore.userInfo || null)
-const orgDisplayName = computed(() => ctx.value?.org?.display_name ?? '')
-const roleDisplayName = computed(() => ctx.value?.role?.display_name ?? '')
+const sessionCtx = computed(() => props.ctx || fetchedCtx.value)
+const info = computed(() => props.userInfo || fetchedInfo.value)
+const settingsData = computed(() => props.settings || fetchedSettings.value)
+const orgDisplayName = computed(() => sessionCtx.value?.org?.display_name ?? '')
+const roleDisplayName = computed(() => sessionCtx.value?.role?.display_name ?? '')

 const headingTitle = computed(() => {
-  const service = authStore.settings?.rp_name
+  const service = settingsData.value?.rp_name
  return service ? `${service} account` : 'Account overview'
 })

@@ -94,11 +118,12 @@ const subheading = computed(() => {
  return `You're signed in to ${currentHost}.`
 })

-const authSiteHost = computed(() => authStore.settings?.auth_host || '')
+const authSiteHost = computed(() => settingsData.value?.auth_host || '')
 const authSiteUrl = computed(() => {
-  const host = authSiteHost.value
-  if (!host) return ''
-  let path = authStore.settings?.ui_base_path ?? '/auth/'
+  // Fall back to the current host when no separate auth host is configured;
+  // the full profile is at ui_base_path either way.
+  const host = authSiteHost.value || currentHost
+  let path = settingsData.value?.ui_base_path ?? '/auth/'
  if (!path.startsWith('/')) path = `/${path}`
  if (!path.endsWith('/')) path = `${path}/`
  const protocol = window.location.protocol || 'https:'
@@ -107,11 +132,27 @@ const authSiteUrl = computed(() => {

 const goToAuthSite = () => {
  if (!authSiteUrl.value) return
-  window.location.href = authSiteUrl.value
+  // Inside an iframe, open the full profile in a new window and close the
+  // frame (auth-back) so the host page regains focus.
+  if (inIframe) {
+    window.open(authSiteUrl.value, '_blank')
+    emit('back')
+  } else {
+    window.location.href = authSiteUrl.value
+  }
 }

 const logout = async () => {
-  await authStore.logout()
+  if (busy.value) return
+  busy.value = true
+  try {
+    await fetchJson('/auth/api/logout', { method: 'POST', timeout: paskiaSettings.auth_ms })
+  } catch (error) {
+    console.error('Logout error:', error)
+  }
+  // The parent decides how to react: the full-page app reloads, the iframe
+  // host receives auth-logout and closes the frame.
+  emit('logout')
 }

 // Keyboard navigation for button row
@@ -124,7 +165,39 @@ const handleButtonRowKeydown = (event) => {
  if (direction === 'left' || direction === 'right') {
    navigateButtonRow(buttonRow.value, event.target, direction, { itemSelector: 'button' })
  }
-  // Up does nothing (no elements above to navigate to)
-  // Down does nothing (no elements below to navigate to)
 }
+
+onMounted(async () => {
+  if (!props.settings) {
+    getSettings().then((data) => { fetchedSettings.value = data })
+  }
+  if (props.ctx && props.userInfo) return
+  try {
+    const [validateData, infoData] = await Promise.all([
+      fetchJson('/auth/api/validate', { method: 'POST', timeout: paskiaSettings.auth_ms }),
+      fetchJson('/auth/api/user-info', { method: 'GET', timeout: paskiaSettings.auth_ms })
+    ])
+    fetchedCtx.value = validateData.ctx
+    fetchedInfo.value = infoData
+    updateThemeFromSession(validateData.ctx)
+  } catch (error) {
+    if (error.status !== 401 && error.status !== 403) {
+      console.error('Failed to load account summary:', error)
+    }
+  } finally {
+    loading.value = false
+  }
+})
 </script>
+
+<style scoped>
+.view-root.host-profile { min-height: 100vh; align-items: center; justify-content: center; padding: 2rem 1rem; }
+.surface.surface--tight {
+  max-width: 520px;
+  margin: 0 auto;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 1.75rem;
+}
+</style>
@@ -38,9 +38,20 @@ export function initThemeFromCache() {
  applyTheme(getCachedTheme())
 }

+/** Theme default from the URL hash (restricted iframe/forward pages only) */
+function getHashTheme() {
+  const theme = new URLSearchParams(window.location.hash.slice(1)).get('theme')
+  return theme === 'light' || theme === 'dark' ? theme : ''
+}
+
 /** Update theme from session context (call after login/session load) */
 export function updateThemeFromSession(ctx, animate = false) {
  const theme = ctx?.user?.theme || ''
+  // Always keep the cache in sync with the profile: empty override clears it
+  // so stale values never mask future server-provided themes.
  setCachedTheme(theme)
-  applyTheme(theme, document.documentElement, animate)
+  // Without a profile override, stay consistent with the initial paint: a
+  // theme parameter on the URL (e.g. host page color scheme injected by
+  // paskia-js) remains in effect before the browser/desktop default.
+  applyTheme(theme || getHashTheme(), document.documentElement, animate)
 }
@@ -8,11 +8,11 @@
 * - Disables Vite's screen clearing on startup
 *
 * Options:
- *   paths - Array of paths to proxy (default: ["/api"])
+ *   paths - Array of paths to proxy (default: ['/api'])
 */

-export default function fastapiVue({ paths = ["/api"] } = {}) {
-  const backendUrl = process.env.PASKIA_BACKEND_URL || "http://localhost:4402"
+export default function fastapiVue({ paths = ['/api'] } = {}) {
+  const backendUrl = process.env.PASKIA_BACKEND_URL || 'http://localhost:4402'

  // Build proxy configuration for each path
  const proxy = {}
@@ -25,12 +25,12 @@ export default function fastapiVue({ paths = ["/api"] } = {}) {
  }

  return {
-    name: "vite-plugin-fastapi-paskia",
+    name: 'vite-plugin-fastapi-paskia',
    config: () => ({
      clearScreen: false,
      server: { proxy },
      build: {
-        outDir: "../paskia/frontend-build",
+        outDir: '../paskia/frontend-build',
        emptyOutDir: true,
      },
    }),
@@ -64,6 +64,14 @@ export default defineConfig(({ command }) => ({
        })
      }
    },
+    {
+      name: 'serve-paskia-js',
+      configureServer(server) {
+        // Serve the locally built paskia-js module for the examples page
+        const serve = sirv(resolve(__dirname, '../paskia-js'), { dev: true })
+        server.middlewares.use('/paskia-js', serve)
+      }
+    },
    {
      name: 'serve-examples',
      configureServer(server) {
@@ -1,14 +1,14 @@
-# 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.
+# Paskia
+
+JavaScript utilities for integrating the [Paskia authentication system](https://git.zi.fi/leovasanko/paskia) into web apps.

 ## Installation

-### NPM
+### npm

-No framework dependencies. Works with any framework (Vue, React, Svelte, etc.) or vanilla JS. Typescript typing included.
+No framework dependencies. Works with Vue, React, Svelte, vanilla JavaScript and other frontend stacks. TypeScript types are included.

 ```sh
 npm install paskia
@@ -20,7 +20,7 @@ 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.
+Import directly from a CDN, or [download](https://cdn.jsdelivr.net/npm/paskia@latest/dist/paskia.js) and host it yourself. No Node.js is required.

 ```html
 <script type="module">
@@ -28,91 +28,102 @@ Fetch the module directly from a CDN, or [download](https://cdn.jsdelivr.net/npm
 </script>
 ```

-## Features
+## Authentication

-### Session Validation
+### API requests

-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.
+`apiFetch` wraps `fetch` with Paskia authentication handling, while `apiJson` adds automatic JSON request/response handling. Both support request timeouts. For the same JSON and timeout handling without prompting the user for authentication, use `fetchJson`.
+
+```js
+import { apiJson, apiFetch } from 'paskia'
+
+const data = await apiJson('/api/endpoint', {
+  method: 'POST',
+  body: { key: 'value' }
+})
+
+const response = await apiFetch('/api/endpoint')
+```
+
+With `apiJson`, a provided `body` is JSON-encoded with the appropriate content type and the response is parsed as JSON.
+
+When the server requests authentication, the API call pauses while the appropriate Paskia dialog is shown and retries after successful authentication.
+
+> Paskia uses `401` and `403` responses to trigger the appropriate **login**, **reauthentication** or **access denied** flow. The backend supplies the authentication URL and context; see the main Paskia documentation for the full response protocol.
+
+### Account and Profile
+
+`profile()` provides a single dialog for an application's login/profile button that allows the user to sign in, view who they are and sign out without ever leaving the page.
+
+```js
+import { profile } from 'paskia'
+
+const result = await profile()
+if (result !== 'back')  // Refresh application state
+```
+
+When signed out, it presents the login flow and returns `'login'` on success. When signed in, it shows the profile and returns `'logout'` after logout. `'back'` is returned when the dialog is closed without an expected session change.
+
+Authentication and profile dialogs follow the user's theme override when set in profile, otherwise the host page's light/dark `color-scheme` to remain in the application's color scheme, then the browser/OS preference.
+
+### Lower-level Authentication
+
+`apiFetch` and `apiJson` call `showAuthIframe()` internally. Applications using plain `fetch` or `fetchJson` can call it directly with an authentication URL returned by the backend:
+
+```js
+import { showAuthIframe } from 'paskia'
+
+await showAuthIframe(data.auth.iframe)
+```
+
+## Session Validation
+
+`SessionValidator` periodically checks that the active Paskia session is still valid and still belongs to the user your application currently has loaded. Validation also refreshes the session to avoid expiry during use.

 ```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
+  () => currentUser?.uuid,  // User ID currently known by your app
+  error => handleSessionLost(error)
 )

-validator.start()  // call at your app startup/login
-validator.stop()   // stop the system (optional)
+validator.start()
+validator.stop()
 ```

-### API Fetch Utilities
+The first callback is read on each check, so a logout, expired session or switch to another account invalidates the session your app is currently using. Polling pauses while the user is inactive, avoiding unnecessary traffic and allowing idle sessions to expire.

-Enhanced fetch functions with automatic error handling and authentication retry:
+## Timeout Settings

-```js
-import { apiJson, apiFetch } from 'paskia'
-
-// JSON API calls with automatic auth handling
-const data = await apiJson('/api/endpoint', { method: 'POST', body: { key: 'value' } })
-
-// Raw fetch with auth handling
-const response = await apiFetch('/api/endpoint')
-```
-
-When a 401/403 response includes an auth iframe URL, the request automatically pauses, displays the authentication UI, and retries upon success. In case this is not needed, use standard `fetch` or our `fetchJson`.
-
-The JSON variants set headers automatically, with body and response in JSON.
-
-### Timeout Settings
-
-Paskia exports a mutable settings object for defaults used by fetch/auth/session validation timers. Default values shown below.
+Paskia exports mutable defaults for network and session timers:

 ```js
 import { settings } from 'paskia'

-// General fetch timeout used by apiFetch/apiJson/fetchJson when no timeout is passed
-settings.fetch_ms = 10000
-
-// Fetch timeout used by SessionValidator (/auth/api/validate is fast)
-settings.auth_ms = 1000
-
-// SessionValidator polling and idle timers
-settings.poll_ms = 60000
-settings.idle_ms = 300000
+settings.fetch_ms = 10000   // apiFetch, apiJson and fetchJson timeout
+settings.auth_ms = 1000     // Session validation request timeout
+settings.poll_ms = 60000    // Session validation interval
+settings.idle_ms = 300000   // Inactivity before validation pauses
 ```

-You can still override timeout per request:
+Request timeout can also be overridden per call:

 ```js
-await apiJson('/api/upload', { method: 'POST', body: data, timeout: 30000 })
+await apiJson('/api/upload', {
+  method: 'POST',
+  body: data,
+  timeout: 30000
+})
 ```

-### Authentication Overlay
+## Shared Blur Backdrop

-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.
+A shared backdrop provides consistent UX across your application, avoiding different things stacking with their own backdrops and dialogs in unexpected manner.

-The backend returns 401/403 responses with the correct URL for proper user feedback. Alternatively you may use `/auth/restricted/iframe#mode=login`, `mode=reauth` or `mode=forbidden` to trigger the UX flow you need.
+Paskia dialogs use a shared blurred backdrop at z-index `1099` and the authentication iframe at `9999`. Application dialogs can use `1100`–`9998` to appear between them.

-```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:
+The same refcounted backdrop can be used by application UI:

 ```js
 import { holdGlobalBackdrop, releaseGlobalBackdrop } from 'paskia'
@@ -125,31 +136,26 @@ try {
 }
 ```

-The backdrop only disappears after all holders have released it.
+It disappears after all holders release it, also avoiding awkward fade/appear animations when changing between multiple dialogs.

 ## Error Handling

-### AuthCancelledError (apiFetch, apiJson, showAuthIframe)
+### `AuthCancelledError`

-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.
+`apiFetch`, `apiJson` and `showAuthIframe` raise `AuthCancelledError` when the user cancels required authentication with Back or Escape. This means the user does not wish to authenticate, and should not be asked again.

- 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
+Continue without the failed operation when possible, or show an appropriate terminal view when authentication is required to continue.

-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.
+When the error is a direct result of a user action, we don't want to show an additional message for that, while in other situations we should. Helpers determine whether an error needs user notification and provide a suitable message:

 ```js
 import { getUserFriendlyErrorMessage, shouldShowErrorToast } from 'paskia'

 try {
  await apiJson('/api/action')
-} catch (e) {
-  if (shouldShowErrorToast(e)) {
-    your.message.display(getUserFriendlyErrorMessage(e))
+} catch (error) {
+  if (shouldShowErrorToast(error)) {
+    your.message.display(getUserFriendlyErrorMessage(error))
  }
 }
 ```
@@ -1,6 +1,6 @@
 {
  "name": "paskia",
-  "version": "1.4.0",
+  "version": "2.1.0",
  "description": "Paskia authentication utilities for JavaScript",
  "author": "Leo Vasanko",
  "license": "Unlicense",
@@ -20,6 +20,7 @@ export {
  isAuthIframeOpen,
  hideAuthIframe,
  showAuthIframe,
+  profile,
 } from './overlay'

 export { SessionValidator } from './validate'
@@ -32,12 +32,27 @@ body.paskia-backdrop {
  color-scheme: auto;
  background: transparent;
 }
+#${AUTH_IFRAME_ID}.paskia-dialog {
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: min(36rem, 100%);
+  height: min(42rem, 100%);
+}
 `

+type DialogResult = 'login' | 'logout' | 'back'
+type DialogKind = 'auth' | 'profile'
+
 let authIframe: HTMLIFrameElement | null = null
-let authPromise: Promise<void> | null = null
-let authResolve: (() => void) | null = null
+let authPromise: Promise<DialogResult | undefined> | null = null
+let authResolve: ((result?: DialogResult) => void) | null = null
 let authReject: ((error: Error) => void) | null = null
+// Auth flows reject AuthCancelledError on auth-back (callers rely on it to
+// abort request retries) and resolve void on auth-success. The profile dialog
+// never rejects: auth-back resolves 'back', and auth-success (the user logged
+// in while the profile dialog was open) resolves 'login'.
+let dialogKind: DialogKind = 'auth'
 let messageListenerInstalled = false
 let backdropHolders = 0

@@ -89,7 +104,7 @@ function handleAuthMessage(event: MessageEvent): void {
    case 'auth-success':
      hideAuthIframe()
      if (authResolve) {
-        authResolve()
+        authResolve(dialogKind === 'profile' ? 'login' : undefined)
        authPromise = null
        authResolve = null
        authReject = null
@@ -98,8 +113,20 @@ function handleAuthMessage(event: MessageEvent): void {

    case 'auth-back':
      hideAuthIframe()
-      if (authReject) {
+      if (dialogKind === 'auth' && authReject) {
        authReject(new AuthCancelledError())
+      } else if (authResolve) {
+        authResolve('back')
+      }
+      authPromise = null
+      authResolve = null
+      authReject = null
+      break
+
+    case 'auth-logout':
+      hideAuthIframe()
+      if (authResolve) {
+        authResolve('logout')
        authPromise = null
        authResolve = null
        authReject = null
@@ -116,12 +143,15 @@ function ensureMessageListener(): void {
  }
 }

-export function showAuthIframe(iframeUrl: string, title = 'Authentication'): Promise<void> {
+function openIframe(iframeUrl: string, title: string, kind: DialogKind): Promise<DialogResult | undefined> {
  injectStyles()
  ensureMessageListener()

  if (authPromise) return authPromise

+  dialogKind = kind
+  iframeUrl = withAppTheme(iframeUrl)
+
  if (document.getElementById(AUTH_IFRAME_ID)) {
    authPromise = new Promise((resolve, reject) => {
      authResolve = resolve
@@ -140,6 +170,7 @@ export function showAuthIframe(iframeUrl: string, title = 'Authentication'): Pro

  authIframe = document.createElement('iframe')
  authIframe.id = AUTH_IFRAME_ID
+  if (kind === 'profile') authIframe.classList.add('paskia-dialog')
  authIframe.title = title
  authIframe.src = iframeUrl
  document.body.appendChild(authIframe)
@@ -147,6 +178,49 @@ export function showAuthIframe(iframeUrl: string, title = 'Authentication'): Pro
  return authPromise
 }

+// Detect the host page's own color scheme (CSS color-scheme on body) as an
+// implicit app-level default. Only an unambiguous 'light' or 'dark' counts;
+// 'normal', 'light dark' etc. mean the page adapts, so no override is needed.
+function detectColorScheme(): string {
+  if (typeof window === 'undefined' || !document.body) return ''
+  const scheme = getComputedStyle(document.body).colorScheme
+  return scheme === 'light' || scheme === 'dark' ? scheme : ''
+}
+
+// Apply the host page's own color scheme to the iframe URL hash — only when
+// the URL has no theme parameter yet (a server-provided user theme override
+// is authoritative). The restricted UI's precedence is: URL parameter (user
+// override from the server, else host color scheme) > cached profile theme
+// (localStorage) > browser/desktop default.
+function withAppTheme(iframeUrl: string): string {
+  const theme = detectColorScheme()
+  if (!theme) return iframeUrl
+  const hashIndex = iframeUrl.indexOf('#')
+  const base = hashIndex === -1 ? iframeUrl : iframeUrl.slice(0, hashIndex)
+  const params = new URLSearchParams(hashIndex === -1 ? '' : iframeUrl.slice(hashIndex + 1))
+  if (params.has('theme')) return iframeUrl
+  params.set('theme', theme)
+  return `${base}#${params}`
+}
+
+export function showAuthIframe(iframeUrl: string, title = 'Authentication'): Promise<void> {
+  return openIframe(iframeUrl, title, 'auth').then(() => undefined)
+}
+
+/**
+ * Show the minimal profile of the logged-in user in a compact dialog iframe.
+ *
+ * Unlike the auth flows, this always resolves — 'login' when the user was
+ * signed out and completed the login flow inside the frame, 'logout' when
+ * they signed out inside the frame, 'back' when they closed it otherwise.
+ * The caller decides from context how to react to each (e.g. whether to
+ * start a new login attempt with showAuthIframe).
+ */
+export function profile(): Promise<DialogResult> {
+  return openIframe('/auth/restricted/iframe#mode=profile', 'Profile', 'profile')
+    .then((result) => result ?? 'back')
+}
+
 export function createAuthIframe(iframeUrl: string, title = 'Authentication'): HTMLIFrameElement {
  injectStyles()
  const existing = document.getElementById(AUTH_IFRAME_ID)
@@ -5,8 +5,8 @@ import os
 import sys
 from pathlib import Path

-import msgspec
-from fastapi_vue import server
+from fastapi_vue import env, server, teleport
+from fastapi_vue.logging import setup_logging
 from kanta import Kanta

 from paskia.db import legacy
@@ -17,8 +17,12 @@ from paskia.domains import build as build_registry
 from paskia.domains import configure as configure_domains
 from paskia.domains import validate_config
 from paskia.util import hostutil, startupbox
-from paskia.util.constants import DEFAULT_PORT, DEVMODE
-from paskia.util.runtime import ServeConfig
+from paskia.util.runtime import serve_config
+
+# Keep the literal value here: fastapi-vue-setup reads DEFAULT_PORT from
+# this module on upgrades. The app-side shared copy is paskia.util.constants.
+DEFAULT_PORT = 4401
+os.environ["FASTAPI_VUE"] = "PASKIA"

 EPILOG = """\
 Examples:
@@ -186,18 +190,6 @@ def cmd_migrate(args: argparse.Namespace) -> None:
    print(f"✅ {action} {db_file_path()} (domains: {', '.join(rp_ids)})")


-def _save_listen(db_path: Path, listen: list[str] | None) -> None:
-    """Persist the listen endpoints to the stored configuration."""
-    kanta = Kanta(str(db_path), DB())
-
-    async def _write() -> None:
-        async with kanta:
-            with kanta.transaction("serve:save_listen"):
-                kanta.data.config.listen = listen
-
-    asyncio.run(_write())
-
-
 def cmd_serve(args: argparse.Namespace) -> None:
    """Open the combined database and serve all configured domains."""
    db_path = db_file_path()
@@ -210,14 +202,20 @@ def cmd_serve(args: argparse.Namespace) -> None:
            )
        raise SystemExit(f"Database {db_path} not found — run 'paskia init' first.")

-    if args.save and args.listen is not None:
-        # '--listen ""' clears the stored endpoints (back to the default)
-        _save_listen(db_path, _split_multi(args.listen) or None)
-
    config = _load_stored_config(db_path)

-    listen = _split_multi(args.listen) or config.listen
-    configure_domains(listen=listen)
+    # Effective serve parameters, teleported to the server process(es); the
+    # app persists the listen endpoints to the database when save is set.
+    cfg = serve_config()
+    cfg.save = bool(args.save and args.listen is not None)
+    if cfg.save:
+        # '--listen ""' clears the stored endpoints (back to the default)
+        cfg.listen = _split_multi(args.listen) or None
+    else:
+        cfg.listen = _split_multi(args.listen) or config.listen
+    teleport()  # Serialize bound config before spawning workers
+
+    configure_domains(listen=cfg.listen)
    try:
        registry = build_registry(config)
    except ValueError as e:
@@ -225,29 +223,26 @@ def cmd_serve(args: argparse.Namespace) -> None:
    # Sanitization warnings (serving is best-effort; fixing the stored config
    # is the admin's job via the admin interface) are logged by build().

-    # Pass process-global serve parameters to the server process(es)
-    os.environ["PASKIA_CONFIG"] = msgspec.json.encode(
-        ServeConfig(listen=listen)
-    ).decode()
-
-    startupbox.print_startup_config(registry, listen=listen)
+    startupbox.print_startup_config(
+        registry, listen=cfg.listen, default_port=DEFAULT_PORT
+    )

    # Run the server (spawns processes in dev mode)
    # tracerite, access logging and log config are handled by fastapi_vue.server;
    # we print our own startup config box, so disable the built-in one.
    server.run(
        "paskia.fastapi.mainapp:app",
-        listen=listen,
+        listen=cfg.listen,
        default_port=DEFAULT_PORT,
        server_header=False,
        startup_box=None,
-        reload=Path(__file__).parent if DEVMODE else False,
+        reload=Path(__file__).parent if env.dev else False,
    )


 def main():
-    # Configure logging to remove the "ERROR:root:" prefix
-    logging.basicConfig(level=logging.INFO, format="%(message)s", force=True)
+    # Full logging setup (tracerite, formatting) before any CLI output
+    setup_logging()

    parser = argparse.ArgumentParser(
        prog="paskia",
@@ -24,8 +24,15 @@ EXPIRES = SESSION_LIFETIME


 def session_ctx(auth: str, host: str | None = None):
-    """Get session context with normalized host."""
-    return db.data().session_ctx(auth, hostutil.normalize_host(host))
+    """Get session context with normalized host.
+
+    The store is dispatched by host: remote domains read their replica.
+    """
+    from paskia import satellite  # noqa: PLC0415  (import cycle)
+
+    return satellite.store_for_host(host).session_ctx(
+        auth, hostutil.normalize_host(host)
+    )


 def expires() -> datetime:
@@ -67,7 +67,10 @@ async def check_admin_credentials() -> bool:
        # Check first admin user for credentials on any configured domain
        admin_user = admin_users[0]
        reg = domains.registry()
-        configured = sorted(d.rp_id for d in reg.domains)
+        # Remote domains hold their credentials on the remote instance
+        configured = sorted(d.rp_id for d in reg.domains if d.remote is None)
+        if not configured:
+            return False

        if not any(admin_user.credential_ids_for(rp_id) for rp_id in configured):
            # Admin exists but has no credential on any domain
@@ -67,6 +67,7 @@ from paskia.db.structs import (
    DomainConfig,
    Org,
    Permission,
+    RemoteConfig,
    ResetToken,
    Role,
    Session,
@@ -90,6 +91,7 @@ __all__ = [
    "Org",
    "Permission",
    "DomainConfig",
+    "RemoteConfig",
    "ResetToken",
    "Role",
    "Session",
@@ -13,7 +13,7 @@ from uuid import UUID

 import uuid7

-from paskia import oidc_notify
+from paskia import oidc_notify, syncfeed
 from paskia.config import SESSION_LIFETIME
 from paskia.db.structs import (
    DB,
@@ -23,6 +23,7 @@ from paskia.db.structs import (
    Org,
    OriginEntry,
    Permission,
+    RemoteConfig,
    ResetToken,
    Role,
    Session,
@@ -103,6 +104,7 @@ def update_permission(
        _db.permissions[uuid].scope = scope
        _db.permissions[uuid].display_name = display_name
        _db.permissions[uuid].domain = domain
+        syncfeed.emit("permissions", str(uuid), _db.permissions[uuid])


 def delete_permission(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
@@ -155,6 +157,7 @@ def update_org_name(
        raise ValueError(f"Organization {uuid} not found")
    with _transaction("admin:update_org_name", ctx):
        _db.orgs[uuid].display_name = display_name
+        syncfeed.emit("orgs", str(uuid), _db.orgs[uuid])


 def delete_org(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
@@ -180,6 +183,9 @@ def add_permission_to_org(

    with _transaction("admin:add_permission_to_org", ctx):
        _db.permissions[permission_uuid].orgs[org_uuid] = True
+        syncfeed.emit(
+            "permissions", str(permission_uuid), _db.permissions[permission_uuid]
+        )


 def remove_permission_from_org(
@@ -197,6 +203,9 @@ def remove_permission_from_org(

    with _transaction("admin:remove_permission_from_org", ctx):
        _db.permissions[permission_uuid].orgs.pop(org_uuid, None)
+        syncfeed.emit(
+            "permissions", str(permission_uuid), _db.permissions[permission_uuid]
+        )


 def create_role(role: Role, *, ctx: SessionContext | None = None) -> None:
@@ -220,6 +229,7 @@ def update_role_name(
        raise ValueError(f"Role {uuid} not found")
    with _transaction("admin:update_role_name", ctx):
        _db.roles[uuid].display_name = display_name
+        syncfeed.emit("roles", str(uuid), _db.roles[uuid])


 def add_permission_to_role(
@@ -235,6 +245,7 @@ def add_permission_to_role(
        raise ValueError(f"Permission {permission_uuid} not found")
    with _transaction("admin:add_permission_to_role", ctx):
        _db.roles[role_uuid].permissions[permission_uuid] = True
+        syncfeed.emit("roles", str(role_uuid), _db.roles[role_uuid])


 def remove_permission_from_role(
@@ -248,6 +259,7 @@ def remove_permission_from_role(
        raise ValueError(f"Role {role_uuid} not found")
    with _transaction("admin:remove_permission_from_role", ctx):
        _db.roles[role_uuid].permissions.pop(permission_uuid, None)
+        syncfeed.emit("roles", str(role_uuid), _db.roles[role_uuid])


 def delete_role(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
@@ -302,6 +314,7 @@ def update_user_display_name(
            slug = slugify_name(display_name)
            if slug and not is_username_taken(slug, exclude_uuid=uuid):
                user.preferred_username = slug
+        syncfeed.emit("users", str(uuid), user)


 def update_user_info(
@@ -380,6 +393,7 @@ def update_user_info(
            user.preferred_username = preferred_username
        if telephone is not _UNSET:
            user.telephone = telephone
+        syncfeed.emit("users", str(uuid), user)


 def update_user_role(
@@ -395,6 +409,7 @@ def update_user_role(
        raise ValueError(f"Role {role_uuid} not found")
    with _transaction("admin:update_user_role", ctx):
        _db.users[uuid].role_uuid = role_uuid
+        syncfeed.emit("users", str(uuid), _db.users[uuid])


 def delete_user(uuid: UUID, *, ctx: SessionContext | None = None) -> None:
@@ -429,6 +444,7 @@ def update_credential_sign_count(
        _db.credentials[uuid].sign_count = sign_count
        if last_used:
            _db.credentials[uuid].last_used = last_used
+        syncfeed.emit("credentials", str(uuid), _db.credentials[uuid])


 def delete_credential(
@@ -476,6 +492,7 @@ def update_session(
            s.validated = validated
        if issuer is not None:
            s.issuer = issuer
+        syncfeed.emit("sessions", key, s)


 def delete_session(
@@ -598,6 +615,9 @@ def login(
        # Update credential
        _db.credentials[credential_uuid].sign_count = sign_count
        _db.credentials[credential_uuid].last_used = now
+        syncfeed.emit(
+            "credentials", str(credential_uuid), _db.credentials[credential_uuid]
+        )
    return token


@@ -625,6 +645,9 @@ def oidc_login(
        # Update credential
        _db.credentials[credential_uuid].sign_count = sign_count
        _db.credentials[credential_uuid].last_used = now
+        syncfeed.emit(
+            "credentials", str(credential_uuid), _db.credentials[credential_uuid]
+        )


 def create_credential_session(
@@ -714,9 +737,10 @@ def update_domain(
    *,
    rp_name: str | None,
    origins: dict[str, bool | OriginEntry],
+    remote: RemoteConfig | None = None,
    ctx: SessionContext | None = None,
 ) -> None:
-    """Replace a domain's rp_name and origins table (wholesale).
+    """Replace a domain's rp_name, origins table and remote (wholesale).

    The rp-id itself is immutable: credentials are stamped with it, so
    changing it would orphan them — delete and recreate the domain instead.
@@ -728,6 +752,7 @@ def update_domain(
    with _transaction("admin:update_domain", ctx):
        domain.rp_name = rp_name
        domain.origins = origins
+        domain.remote = remote


 def delete_domain(rp_id: str, *, ctx: SessionContext | None = None) -> None:
@@ -9,7 +9,7 @@ from uuid import UUID
 import msgspec
 import uuid7

-from paskia import db
+from paskia import db, syncfeed
 from paskia.util import passphrase as passphrase_util
 from paskia.util.crypto import hash_secret

@@ -51,6 +51,7 @@ class Permission(msgspec.Struct, dict=True, omit_defaults=True):
    def store(self) -> None:
        """Store this permission in the database. Must be called inside a transaction."""
        db.data().permissions[self.uuid] = self
+        syncfeed.emit("permissions", str(self.uuid), self)

    def delete(self) -> None:
        """Delete this permission and remove it from all roles.
@@ -59,8 +60,10 @@ class Permission(msgspec.Struct, dict=True, omit_defaults=True):
        """
        _data = db.data()
        for role in _data.roles.values():
-            role.permissions.pop(self.uuid, None)
+            if role.permissions.pop(self.uuid, None) is not None:
+                syncfeed.emit("roles", str(role.uuid), role)
        del _data.permissions[self.uuid]
+        syncfeed.emit("permissions", str(self.uuid), None)

    @classmethod
    def create(
@@ -103,6 +106,7 @@ class Org(msgspec.Struct, dict=True):
    def store(self) -> None:
        """Store this organization in the database. Must be called inside a transaction."""
        db.data().orgs[self.uuid] = self
+        syncfeed.emit("orgs", str(self.uuid), self)

    def delete(self) -> None:
        """Delete this org and cascade to roles, users. Remove from permissions.
@@ -111,12 +115,16 @@ class Org(msgspec.Struct, dict=True):
        """
        _data = db.data()
        for p in _data.permissions.values():
-            p.orgs.pop(self.uuid, None)
+            if p.orgs.pop(self.uuid, None) is not None:
+                syncfeed.emit("permissions", str(p.uuid), p)
        for role in self.roles:
            for user in role.users:
                del _data.users[user.uuid]
+                syncfeed.emit("users", str(user.uuid), None)
            del _data.roles[role.uuid]
+            syncfeed.emit("roles", str(role.uuid), None)
        del _data.orgs[self.uuid]
+        syncfeed.emit("orgs", str(self.uuid), None)

    @classmethod
    def create(cls, display_name: str, created_at: datetime | None = None) -> Org:
@@ -170,10 +178,12 @@ class Role(msgspec.Struct, dict=True, omit_defaults=True):
    def store(self) -> None:
        """Store this role in the database. Must be called inside a transaction."""
        db.data().roles[self.uuid] = self
+        syncfeed.emit("roles", str(self.uuid), self)

    def delete(self) -> None:
        """Delete this role from the database. Must be called inside a transaction."""
        del db.data().roles[self.uuid]
+        syncfeed.emit("roles", str(self.uuid), None)

    @classmethod
    def create(
@@ -254,6 +264,7 @@ class User(msgspec.Struct, dict=True, omit_defaults=True, kw_only=True):
    def store(self) -> None:
        """Store this user in the database. Must be called inside a transaction."""
        db.data().users[self.uuid] = self
+        syncfeed.emit("users", str(self.uuid), self)

    def delete(self) -> None:
        """Delete this user and cascade to credentials, sessions, reset tokens.
@@ -263,11 +274,14 @@ class User(msgspec.Struct, dict=True, omit_defaults=True, kw_only=True):
        _data = db.data()
        for cred in self.credentials:
            del _data.credentials[cred.uuid]
+            syncfeed.emit("credentials", str(cred.uuid), None)
        for sess in self.sessions:
            del _data.sessions[sess.key]
+            syncfeed.emit("sessions", sess.key, None)
        for token in self.reset_tokens:
            del _data.reset_tokens[token.key]
        del _data.users[self.uuid]
+        syncfeed.emit("users", str(self.uuid), None)

    @classmethod
    def create(
@@ -331,6 +345,7 @@ class Credential(msgspec.Struct, dict=True):
    def store(self) -> None:
        """Store this credential in the database. Must be called inside a transaction."""
        db.data().credentials[self.uuid] = self
+        syncfeed.emit("credentials", str(self.uuid), self)

    def delete(self) -> None:
        """Delete this credential and all its sessions.
@@ -340,7 +355,9 @@ class Credential(msgspec.Struct, dict=True):
        _data = db.data()
        for sess in self.sessions:
            del _data.sessions[sess.key]
+            syncfeed.emit("sessions", sess.key, None)
        del _data.credentials[self.uuid]
+        syncfeed.emit("credentials", str(self.uuid), None)

    @classmethod
    def create(
@@ -418,10 +435,13 @@ class Session(msgspec.Struct, dict=True, omit_defaults=True):
        _data.sessions[self.key] = self
        _data.users[self.user_uuid].last_seen = last_seen
        _data.users[self.user_uuid].visits += 1
+        syncfeed.emit("sessions", self.key, self)
+        syncfeed.emit("users", str(self.user_uuid), _data.users[self.user_uuid])

    def delete(self) -> None:
        """Delete this session from the database. Must be called inside a transaction."""
        del db.data().sessions[self.key]
+        syncfeed.emit("sessions", self.key, None)

    @classmethod
    def create(
@@ -622,6 +642,21 @@ class OriginEntry(msgspec.Struct, omit_defaults=True):
    auth_host: bool = False  # This site hosts the account/admin interface


+class RemoteConfig(msgspec.Struct, omit_defaults=True):
+    """Upstream paskia instance backing a remote (satellite-served) domain.
+
+    The satellite keeps a RAM-only read replica of the remote's tables and
+    answers session-dependent reads locally; mutations are forwarded. The
+    token authenticates the sync channel (the remote reads accepted tokens
+    from its PASKIA_SYNC_TOKENS environment, never from its database).
+    """
+
+    url: str  # e.g. "https://auth.example.com"
+    token: str = ""
+    cache_ttl: int = 60  # staleness bound (seconds) while the sync channel is down
+    refresh_interval: int = 300  # full re-sync cadence (seconds)
+
+
 class DomainConfig(msgspec.Struct, omit_defaults=True):
    """Configuration for one domain (one WebAuthn rp-id).

@@ -641,6 +676,7 @@ class DomainConfig(msgspec.Struct, omit_defaults=True):

    rp_name: str | None = None
    origins: dict[str, bool | OriginEntry] = {}
+    remote: RemoteConfig | None = None


 class Config(msgspec.Struct, omit_defaults=True):
@@ -728,17 +764,21 @@ class DB(msgspec.Struct, dict=True, omit_defaults=False):
        if s.host != host:
            return None

+        # Look up via this instance's own tables: a DB must be
+        # self-contained so that read replicas work unchanged.
        try:
-            user = s.user
-            role = user.role
-            org = role.org
-            credential = s.credential
+            user = self.users[s.user_uuid]
+            role = self.roles[user.role_uuid]
+            org = self.orgs[role.org_uuid]
+            credential = self.credentials[s.credential_uuid]
        except KeyError:
            return None

        # Effective permissions: role's permissions that the org can grant,
        # filtered by domain restriction
-        org_perm_uuids = {p.uuid for p in org.permissions}
+        org_perm_uuids = {
+            p.uuid for p in self.permissions.values() if org.uuid in p.orgs
+        }

        effective_perms = []
        for perm_uuid in role.permission_set:
@@ -14,13 +14,14 @@ domain are in-domain, entries outside it are related.

 from __future__ import annotations

+import asyncio
 import contextvars
 import logging
 import os

 from fastapi_vue.hostutil import parse_endpoints

-from paskia.db.structs import Config, DomainConfig, OriginEntry
+from paskia.db.structs import Config, DomainConfig, OriginEntry, RemoteConfig
 from paskia.sansio import Passkey
 from paskia.util import hostutil
 from paskia.util.constants import DEFAULT_PORT
@@ -101,6 +102,11 @@ class Domain:
    def rp_name(self) -> str:
        return self.passkey.rp_name

+    @property
+    def remote(self) -> RemoteConfig | None:
+        """Upstream config when this domain is served as a satellite."""
+        return self.config.remote
+
    @property
    def own_auth_host(self) -> str | None:
        """This domain's own auth host as host[:port], if configured."""
@@ -207,6 +213,10 @@ def validate_config(

    for rp_id, domain in config.domains.items():
        hostutil.validate_rp_id(rp_id)
+        if domain.remote is not None and not domain.remote.url.startswith(
+            ("https://", "http://")
+        ):
+            raise ValueError(f"Domain '{rp_id}': remote URL must be an http(s) URL")

        domain_auth_host: str | None = None
        related_count = 0
@@ -273,6 +283,11 @@ def validate_config(
                f"Domain '{rp_id}' has {related_count} related origins "
                f"(maximum {related_origin_cap})"
            )
+        if domain.remote is not None and domain_auth_host is None:
+            raise ValueError(
+                f"Domain '{rp_id}' is remote — it must mark an auth host "
+                "(profile, admin and sign-in pages live there)"
+            )

    rp_ids = set(config.domains)
    for hn, owner in auth_hosts.items():
@@ -363,6 +378,20 @@ def sanitize_config(
                    auth_seen = True
            origins[key] = props

+        if domain.remote is not None:
+            if not domain.remote.url.startswith(("https://", "http://")):
+                warn(f"Domain '{rp_id}': invalid remote URL — remote dropped")
+                remote = None
+            else:
+                remote = domain.remote
+                if not auth_seen:
+                    warn(
+                        f"Domain '{rp_id}': remote domain without an auth host — "
+                        "profile, admin and sign-in pages have nowhere to live"
+                    )
+        else:
+            remote = None
+
        related = sorted(k for k in origins if is_related_key(rp_id, k))
        if len(related) > related_origin_cap:
            warn(
@@ -372,7 +401,9 @@ def sanitize_config(
            for key in related[related_origin_cap:]:
                del origins[key]

-        domains[rp_id] = DomainConfig(rp_name=domain.rp_name, origins=origins)
+        domains[rp_id] = DomainConfig(
+            rp_name=domain.rp_name, origins=origins, remote=remote
+        )

    if not domains:
        raise ValueError("No servable domain in the stored configuration")
@@ -461,6 +492,17 @@ def _derive_site(

 _registry: DomainRegistry | None = None
 _listen: list[str] | None = None
+_rebuild_listeners: list = []
+
+
+def add_rebuild_listener(fn) -> None:
+    """Register fn(registry), called after every init_registry rebuild."""
+    _rebuild_listeners.append(fn)
+
+
+def remove_rebuild_listener(fn) -> None:
+    if fn in _rebuild_listeners:
+        _rebuild_listeners.remove(fn)


 def configure(*, listen: list[str] | None = None) -> None:
@@ -501,6 +543,12 @@ def init_registry(config: Config) -> DomainRegistry:
    """Build and install the global registry from a combined configuration."""
    global _registry
    _registry = build(config)
+    for fn in _rebuild_listeners:
+        result = fn(_registry)
+        if asyncio.iscoroutine(result):
+            # init_registry runs within a running loop in every serving
+            # context (lifespan, tests, admin rebuild).
+            asyncio.get_running_loop().create_task(result)
    return _registry


@@ -12,7 +12,7 @@ immediately.
 from fastapi import Body, FastAPI, Request

 from paskia import db, domains
-from paskia.db.structs import Config, DomainConfig, OriginEntry
+from paskia.db.structs import Config, DomainConfig, OriginEntry, RemoteConfig
 from paskia.fastapi import authz
 from paskia.fastapi.admin.errors import install_error_handlers
 from paskia.fastapi.response import MsgspecResponse
@@ -27,6 +27,14 @@ install_error_handlers(app)


 def _domain_to_api(domain: domains.Domain) -> ApiDomain:
+    remote = domain.config.remote
+    if remote is not None:
+        # The sync token is a bearer secret: never echoed back
+        remote = RemoteConfig(
+            url=remote.url,
+            cache_ttl=remote.cache_ttl,
+            refresh_interval=remote.refresh_interval,
+        )
    return ApiDomain(
        rp_id=domain.rp_id,
        rp_name=domain.rp_name,
@@ -34,6 +42,28 @@ def _domain_to_api(domain: domains.Domain) -> ApiDomain:
        site_url=domain.site_url,
        auth_site_url=domain.auth_site_url,
        auth_host=domain.own_auth_host,
+        remote=remote,
+    )
+
+
+def _normalize_remote(
+    value, existing: RemoteConfig | None = None
+) -> RemoteConfig | None:
+    """Parse a remote object from the admin UI (raises on malformed).
+
+    An absent/empty token keeps the previously stored one — the token is
+    write-only over the API.
+    """
+    if value is None:
+        return None
+    if not isinstance(value, dict) or not isinstance(value.get("url"), str):
+        raise ValueError("remote must be an object with a url")
+    token = str(value.get("token") or "") or (existing.token if existing else "")
+    return RemoteConfig(
+        url=value["url"].rstrip("/"),
+        token=token,
+        cache_ttl=int(value.get("cache_ttl") or 60),
+        refresh_interval=int(value.get("refresh_interval") or 300),
    )


@@ -123,6 +153,7 @@ async def admin_create_domain(
    new = DomainConfig(
        rp_name=(payload.get("rp_name") or "").strip() or None,
        origins=_normalize_origins_map(payload.get("origins")),
+        remote=_normalize_remote(payload.get("remote")),
    )

    config = db.data().config
@@ -156,9 +187,15 @@ async def admin_update_domain(
    if rp_id not in config.domains:
        raise ValueError(f"Domain {rp_id} not found")

+    current_remote = config.domains[rp_id].remote
    updated = DomainConfig(
        rp_name=(payload.get("rp_name") or "").strip() or None,
        origins=_normalize_origins_map(payload.get("origins")),
+        remote=(
+            _normalize_remote(payload["remote"], existing=current_remote)
+            if "remote" in payload
+            else current_remote
+        ),
    )
    would_be = Config(
        domains={k: updated if k == rp_id else v for k, v in config.domains.items()},
@@ -171,6 +208,7 @@ async def admin_update_domain(
        rp_id,
        rp_name=updated.rp_name,
        origins=updated.origins,
+        remote=updated.remote,
        ctx=ctx,
    )
    _rebuild_registry()
@@ -14,7 +14,7 @@ from fastapi import (
 from fastapi.responses import JSONResponse
 from fastapi.security import HTTPBearer

-from paskia import authcode, db
+from paskia import authcode, db, satellite
 from paskia._version import __version__
 from paskia.authsession import EXPIRES, get_reset, session_ctx
 from paskia.domains import current_domain
@@ -122,8 +122,9 @@ async def validate_token(
    if auth and renew:
        consumed = datetime.now(UTC) - ctx.session.validated
        if not timedelta(0) < consumed < _REFRESH_INTERVAL:
-            db.update_session(
+            satellite.refresh_session(
                ctx.session.key,
+                request.headers.get("host"),
                ip=get_client_ip(request),
                user_agent=request.headers.get("user-agent"),
                validated=datetime.now(UTC),
@@ -162,16 +163,16 @@ async def check_user(

    No session cookie is read or written. Caller authentication is not required.
    """
-    data = db.data()
+    host = hostutil.normalize_host(request.headers.get("host"))
+    data = satellite.store_for_host(host)
    try:
        u = data.users[user_uuid]
-        role = u.role
-        org = role.org
+        role = data.roles[u.role_uuid]
+        org = data.orgs[role.org_uuid]
    except KeyError:
        raise HTTPException(status_code=404, detail="User not found")

-    host = hostutil.normalize_host(request.headers.get("host"))
-    org_perm_uuids = {p.uuid for p in org.permissions}
+    org_perm_uuids = {p.uuid for p in data.permissions.values() if org.uuid in p.orgs}

    effective_perms = []
    for perm_uuid in role.permission_set:
@@ -212,7 +213,7 @@ def _remote_headers(ctx) -> dict[str, str]:
        "Remote-Session-Expires": (
            (ctx.session.validated + EXPIRES).isoformat().replace("+00:00", "Z")
        ),
-        "Remote-Credential": str(ctx.session.credential),
+        "Remote-Credential": str(ctx.credential.uuid),
    }


@@ -351,8 +352,10 @@ async def api_user_info(


@app.get("/token-info")
-async def token_info(credentials=Depends(bearer_auth)):
+async def token_info(request: Request, credentials=Depends(bearer_auth)):
    """Get reset/device-add token info. Pass token via Bearer header."""
+    if (proxied := await satellite.forward_request(request)) is not None:
+        return proxied
    if not credentials or not credentials.credentials:
        raise HTTPException(401, "Bearer token required")
    token = credentials.credentials
@@ -375,6 +378,10 @@ async def token_info(credentials=Depends(bearer_auth)):

@app.post("/logout")
 async def api_logout(request: Request, response: Response, auth=AUTH_COOKIE):
+    if (proxied := await satellite.forward_request(request)) is not None:
+        if auth and proxied.status_code == 200:
+            satellite.evict_session(auth, request.headers.get("host"))
+        return proxied
    if not auth:
        return {"message": "Already logged out"}
    host = request.headers.get("host")
@@ -399,6 +406,11 @@ async def api_set_session(
    if not auth or not auth.credentials:
        raise HTTPException(400, "Bearer token required")

+    if (proxied := await satellite.forward_request(request)) is not None:
+        # The exchange code lives in the remote's RAM; redeem it there. The
+        # session itself reaches the replica via the sync channel.
+        return proxied
+
    host = hostutil.normalize_host(request.headers.get("host", ""))
    if not host:
        raise HTTPException(400, "Host header required")
@@ -63,6 +63,11 @@ class DispatchMiddleware:
        host = _header(scope, "host")
        host_domain = registry.resolve(host)
        if host_domain is None:
+            # The sync endpoint is server-to-server and token-gated: the
+            # satellite may reach us via an address outside our domains.
+            if scope.get("path") == "/auth/api/sync/ws" and registry.domains:
+                await self._dispatch(scope, receive, send, registry.domains[0])
+                return
            await send({"type": "websocket.close", "code": _WS_CLOSE_POLICY_VIOLATION})
            return

@@ -5,13 +5,13 @@ from pathlib import Path

 from fastapi import FastAPI, HTTPException, Request, Response
 from fastapi.responses import FileResponse, RedirectResponse
-from kanta.logging import configure_logging as configure_kanta_logging
+from fastapi_vue import env

-from paskia import authcode, db, domains, remoteauth
+from paskia import authcode, db, domains, remoteauth, satellite
 from paskia.bootstrap import bootstrap_if_needed
 from paskia.db.background import start_background, stop_background
 from paskia.db.lifecycle import kanta
-from paskia.fastapi import admin, api, auth_host, oid, ws
+from paskia.fastapi import admin, api, auth_host, oid, sync, ws
 from paskia.fastapi.admin.adminapp import adminapp
 from paskia.fastapi.dispatch import DispatchMiddleware

@@ -19,12 +19,8 @@ from paskia.fastapi.dispatch import DispatchMiddleware
 from paskia.fastapi.front import frontend
 from paskia.fastapi.session import AUTH_COOKIE
 from paskia.util import passphrase, vitedev
-from paskia.util.constants import DEVMODE
 from paskia.util.runtime import serve_config

-# Configure custom logging
-configure_kanta_logging()
-
 # Path to examples/index.html when running from source tree
 _EXAMPLES_DIR = Path(__file__).parent.parent.parent / "examples"

@@ -33,22 +29,28 @@ _EXAMPLES_DIR = Path(__file__).parent.parent.parent / "examples"
 async def lifespan(app: FastAPI):  # pragma: no cover - startup path
    """Application lifespan: open the combined database and build the domain registry.

-    Process-global serve parameters (listen endpoints) are passed via the
-    PASKIA_CONFIG JSON env variable (set by the CLI entrypoint) so that
-    uvicorn reload / multiprocess workers derive site URLs the same way.
-    Domain configuration is read from the database.
+    Process-global serve parameters (listen endpoints, save flag) are passed
+    via the PASKIA_CONFIG JSON env variable (set by the CLI entrypoint) so
+    that uvicorn reload / multiprocess workers derive site URLs the same
+    way. With the save flag set, the listen endpoints are persisted here —
+    the CLI never opens the database read-write. Domain configuration is
+    read from the database.
    """
    cfg = serve_config()
-    domains.configure(listen=cfg.listen if cfg else None)
+    domains.configure(listen=cfg.listen)

    await asyncio.to_thread(
        Path(kanta.filename).parent.mkdir, parents=True, exist_ok=True
    )
    async with kanta:
+        if cfg.save:
+            with kanta.transaction("serve:save_listen"):
+                db.data().config.listen = cfg.listen
        try:
            domains.init_registry(db.data().config)
            await remoteauth.init()
            await authcode.start()
+            await satellite.manager.start()
        except ValueError as e:
            logging.error(f"⚠️ {e}")
            # Re-raise to fail fast
@@ -59,6 +61,7 @@ async def lifespan(app: FastAPI):  # pragma: no cover - startup path
        await start_background()
        yield
        await stop_background()
+        await satellite.manager.stop()
        await authcode.stop()


@@ -68,7 +71,7 @@ app = FastAPI(
    docs_url=None,
    redoc_url=None,
    openapi_url=None,
-    debug=DEVMODE,
+    debug=env.dev,
 )

 # WebSocket and HTTP access logging is handled by fastapi_vue's ASGI middleware;
@@ -82,6 +85,7 @@ app.middleware("http")(auth_host.redirect_middleware)
 app.add_middleware(DispatchMiddleware)

 app.mount("/auth/api/admin/", admin.app)
+app.mount("/auth/api/sync", sync.app)
 app.mount("/auth/api/", api.app)
 app.mount("/auth/ws/", ws.app)
 app.mount("/auth/oidc/", oid.app)
@@ -20,7 +20,7 @@ from fastapi import Depends, FastAPI, Form, HTTPException, Request
 from fastapi.responses import JSONResponse
 from fastapi.security import HTTPBearer

-from paskia import authcode, db
+from paskia import authcode, db, satellite
 from paskia.db.structs import OIDC, Session
 from paskia.util import avatar, oidjwt
 from paskia.util.crypto import hash_secret
@@ -30,6 +30,14 @@ _logger = logging.getLogger(__name__)
 app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)


+@app.middleware("http")
+async def proxy_remote_domain(request: Request, call_next):
+    """OIDC key material and sessions stay on the remote; proxy everything."""
+    if (proxied := await satellite.forward_request(request)) is not None:
+        return proxied
+    return await call_next(request)
+
+
 def _provider() -> OIDC:
    """Return the instance-global OIDC provider state."""
    return db.data().oidc
@@ -0,0 +1,94 @@
+"""Sync WebSocket endpoint: serves snapshots and live events to satellites.
+
+Token-gated via PASKIA_SYNC_TOKENS (env); closed when unset. All state is
+RAM-only (syncfeed); the database schema is untouched. Protocol: snapshot
+chunks per table, `ready`, then live upsert/delete events; the client sends
+session_refresh write-backs. Reconnects always restart from a snapshot.
+"""
+
+import asyncio
+import logging
+from datetime import datetime
+
+import msgspec
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+
+from paskia import db, syncfeed
+
+_logger = logging.getLogger(__name__)
+
+app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+
+
+async def _send(ws: WebSocket, message: dict) -> None:
+    await ws.send_bytes(syncfeed.encode(message))
+
+
+async def _apply_client_message(message: dict) -> None:
+    """Satellite write-behind: session refresh (validated/ip/user-agent)."""
+    if message.get("type") != "session_refresh":
+        return
+    key = message.get("key") or ""
+    session = db.data().sessions.get(key)
+    if session is None:
+        return
+    try:
+        validated = msgspec.convert(message.get("validated"), datetime)
+    except msgspec.ValidationError:
+        return
+    db.update_session(
+        key,
+        ip=message.get("ip") or None,
+        user_agent=message.get("user_agent") or None,
+        validated=validated,
+    )
+
+
+@app.websocket("/ws")
+async def sync_websocket(ws: WebSocket):
+    tokens = syncfeed.tokens_from_env()
+    auth = ws.headers.get("authorization", "")
+    if not tokens or auth.removeprefix("Bearer ").strip() not in tokens:
+        await ws.close(code=1008)
+        return
+    await ws.accept()
+
+    queue = syncfeed.subscribe()
+    try:
+        data = db.data()
+        for table in syncfeed.TABLES:
+            await _send(
+                ws,
+                {
+                    "type": "snapshot",
+                    "table": table,
+                    "items": [
+                        [str(key), msgspec.to_builtins(obj)]
+                        for key, obj in getattr(data, table).items()
+                    ],
+                },
+            )
+        await _send(ws, {"type": "ready"})
+
+        sender = asyncio.create_task(_pump(ws, queue))
+        try:
+            while True:
+                await _apply_client_message(
+                    msgspec.json.decode(await ws.receive_bytes())
+                )
+        finally:
+            sender.cancel()
+    except WebSocketDisconnect:
+        pass
+    except Exception:
+        _logger.exception("Sync WebSocket failed")
+    finally:
+        syncfeed.unsubscribe(queue)
+
+
+async def _pump(ws: WebSocket, queue: asyncio.Queue) -> None:
+    try:
+        while True:
+            await _send(ws, await queue.get())
+    except WebSocketDisconnect, RuntimeError, asyncio.CancelledError:
+        pass
@@ -0,0 +1,344 @@
+"""Satellite side of remote domains: RAM-only replicas + host dispatch.
+
+Domains configured with ``DomainConfig.remote`` are backed by a remote
+paskia instance. This module owns the whole feature: it resolves which
+store serves a request host (local DB or the remote's read replica),
+dispatches session writes (refresh write-behind, logout eviction), and
+forwards requests the satellite cannot answer (exchange-code redemption,
+OIDC, reset tokens) to the remote.
+
+A replica is a plain DB instance, never persisted, fed by a sync
+WebSocket (snapshot on connect, then live events) and swept for
+expired sessions locally. While the channel is down the replica stays trusted for the
+domain's cache_ttl, then reads fail with RemoteUnavailable (fail-closed;
+a large cache_ttl gives fail-open behavior bounded by session expiry).
+"""
+
+import asyncio
+import contextlib
+import logging
+import time
+from datetime import UTC, datetime
+from uuid import UUID
+
+import httpx
+import msgspec
+import websockets
+from fastapi import HTTPException, Request, Response
+
+from paskia import db, domains
+from paskia.config import SESSION_LIFETIME
+from paskia.db.structs import (
+    DB,
+    Credential,
+    Org,
+    Permission,
+    RemoteConfig,
+    Role,
+    Session,
+    User,
+)
+from paskia.util.crypto import hash_secret
+
+_logger = logging.getLogger(__name__)
+
+_TABLES = {
+    "permissions": (Permission, True),
+    "orgs": (Org, True),
+    "roles": (Role, True),
+    "users": (User, True),
+    "credentials": (Credential, True),
+    "sessions": (Session, False),
+}
+
+_RECONNECT_DELAY = 5
+_SWEEP_INTERVAL = 60
+
+
+class RemoteReplica:
+    """One remote instance's replica, its sync client and write-behind queue."""
+
+    def __init__(self, remote: RemoteConfig):
+        self.remote = remote
+        self.db = DB()
+        self.last_contact = 0.0  # monotonic time the feed last went down
+        self.connected = False
+        self._pending_refresh: dict[str, dict] = {}
+        self._refresh_signal = asyncio.Event()
+        self._task: asyncio.Task | None = None
+        self._sweeper: asyncio.Task | None = None
+        self._stopped = True
+
+    def available(self) -> bool:
+        """Synced, and connected now or within cache_ttl of the disconnect."""
+        if not self.last_contact:
+            return False
+        return self.connected or (
+            time.monotonic() - self.last_contact <= self.remote.cache_ttl
+        )
+
+    def refresh_session(
+        self, key: str, validated, ip: str | None, user_agent: str | None
+    ) -> None:
+        """Apply a /validate refresh locally and queue it for the remote."""
+        session = self.db.sessions.get(key)
+        if session is not None:
+            session.validated = validated
+            if ip is not None:
+                session.ip = ip
+            if user_agent is not None:
+                session.user_agent = user_agent
+        self._pending_refresh[key] = {
+            "type": "session_refresh",
+            "key": key,
+            "validated": msgspec.to_builtins(validated),
+            "ip": ip,
+            "user_agent": user_agent,
+        }
+        self._refresh_signal.set()
+
+    async def start(self) -> None:
+        self._stopped = False
+        self._task = asyncio.create_task(self._run())
+        self._sweeper = asyncio.create_task(self._sweep())
+
+    async def stop(self) -> None:
+        self._stopped = True
+        for task in (self._task, self._sweeper):
+            if task:
+                task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await task
+
+    async def _sweep(self) -> None:
+        while True:
+            await asyncio.sleep(_SWEEP_INTERVAL)
+            limit = datetime.now(UTC) - SESSION_LIFETIME
+            for key in [k for k, s in self.db.sessions.items() if s.validated < limit]:
+                del self.db.sessions[key]
+
+    async def _run(self) -> None:
+        while not self._stopped:
+            try:
+                await self._connect()
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:
+                _logger.info("Sync to %s failed: %s", self.remote.url, e)
+            if self.connected:
+                # The TTL clock starts when the feed goes down, not at the
+                # last message — an idle connection is healthy.
+                self.connected = False
+                self.last_contact = time.monotonic()
+            if not self._stopped:
+                await asyncio.sleep(_RECONNECT_DELAY)
+
+    async def _connect(self) -> None:
+        ws_url = self.remote.url.replace("http", "ws", 1) + "/auth/api/sync/ws"
+        async with websockets.connect(
+            ws_url,
+            additional_headers={"Authorization": f"Bearer {self.remote.token}"},
+            # Prompt dead-peer detection: availability semantics count on it
+            ping_interval=5,
+            ping_timeout=5,
+        ) as ws:
+            sender = asyncio.create_task(self._send_loop(ws))
+            staging: DB | None = None
+            ready_at = 0.0
+            try:
+                while True:
+                    if ready_at:
+                        # Periodic reconnects give full-snapshot reconciliation
+                        remaining = self.remote.refresh_interval - (
+                            time.monotonic() - ready_at
+                        )
+                        if remaining <= 0:
+                            return
+                        try:
+                            message = msgspec.json.decode(
+                                await asyncio.wait_for(ws.recv(), remaining)
+                            )
+                        except TimeoutError:
+                            return  # periodic resync: reconnect for a snapshot
+                    else:
+                        message = msgspec.json.decode(await ws.recv())
+                    mtype = message.get("type")
+                    if mtype == "snapshot":
+                        staging = staging or DB()
+                        for key, fields in message["items"]:
+                            _apply(staging, message["table"], key, fields)
+                    elif mtype == "event":
+                        if staging is not None:
+                            raise ValueError("sync: event before ready")
+                        _apply(
+                            self.db,
+                            message["table"],
+                            message["key"],
+                            message.get("fields"),
+                        )
+                    elif mtype == "ready":
+                        if staging is not None:
+                            self.db = staging
+                            staging = None
+                        self.connected = True
+                        self.last_contact = ready_at = time.monotonic()
+            finally:
+                sender.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await sender
+
+    async def _send_loop(self, ws) -> None:
+        while True:
+            self._refresh_signal.clear()
+            while self._pending_refresh:
+                _, message = self._pending_refresh.popitem()
+                await ws.send(msgspec.json.encode(message))
+            await self._refresh_signal.wait()
+
+
+def _apply(replica: DB, table: str, key: str, fields: dict | None) -> None:
+    """Apply an upsert (fields given) or delete (fields None) to a replica."""
+    cls, uuid_key = _TABLES[table]
+    store = getattr(replica, table)
+    store_key = UUID(key) if uuid_key else key
+    if fields is None:
+        store.pop(store_key, None)
+        return
+    obj = msgspec.convert(fields, cls)
+    if uuid_key:
+        obj.uuid = store_key
+    else:
+        obj.key = key
+    store[store_key] = obj
+
+
+class SatelliteManager:
+    """Replicas keyed by remote URL; domains sharing a remote share one."""
+
+    def __init__(self):
+        self.replicas: dict[str, RemoteReplica] = {}
+
+    async def start(self) -> None:
+        domains.add_rebuild_listener(self.reconcile)
+        await self.reconcile(domains.registry())
+
+    async def stop(self) -> None:
+        domains.remove_rebuild_listener(self.reconcile)
+        for replica in self.replicas.values():
+            await replica.stop()
+        self.replicas.clear()
+
+    async def reconcile(self, registry: domains.DomainRegistry) -> None:
+        """Start/stop replicas to match the configured remote domains."""
+        wanted = {}
+        for domain in registry.domains:
+            if domain.remote is not None:
+                wanted.setdefault(domain.remote.url, domain.remote)
+        for url in list(self.replicas):
+            if url not in wanted:
+                await self.replicas.pop(url).stop()
+        for url, remote in wanted.items():
+            replica = self.replicas.get(url)
+            if replica is None or replica.remote != remote:
+                if replica is not None:
+                    await replica.stop()
+                replica = RemoteReplica(remote)
+                self.replicas[url] = replica
+                await replica.start()
+
+
+manager = SatelliteManager()
+
+
+# -------------------------------------------------------------------------
+# Host-keyed dispatch: the only interface the rest of the app uses
+# -------------------------------------------------------------------------
+
+
+def replica_for_host(host: str | None) -> RemoteReplica | None:
+    """The replica serving this host, or None for locally served hosts."""
+    domain = domains.registry().resolve(host)
+    if domain is None or domain.remote is None:
+        return None
+    return manager.replicas.get(domain.remote.url)
+
+
+def store_for_host(host: str | None) -> DB:
+    """The data store to read for a request host: the local database, or
+    the replica of the remote backing the host's domain."""
+    replica = replica_for_host(host)
+    if replica is None:
+        return db.data()
+    if not replica.available():
+        raise HTTPException(503, "Remote authentication service unavailable")
+    return replica.db
+
+
+def refresh_session(
+    key, host: str | None, ip: str, user_agent: str, validated, ctx=None
+):
+    """/validate refresh: write-behind for remote domains, else local DB."""
+    replica = replica_for_host(host)
+    if replica is not None:
+        replica.refresh_session(key, validated, ip, user_agent)
+    else:
+        db.update_session(
+            key, ip=ip, user_agent=user_agent, validated=validated, ctx=ctx
+        )
+
+
+def evict_session(auth: str, host: str | None) -> None:
+    """Drop a session from the replica (its remote deletion arrives via sync)."""
+    replica = replica_for_host(host)
+    if replica is not None:
+        replica.db.sessions.pop(hash_secret("cookie", auth), None)
+
+
+_TIMEOUT = httpx.Timeout(15.0, connect=5.0)
+
+_HOP_BY_HOP = {
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailers",
+    "transfer-encoding",
+    "upgrade",
+    "content-length",
+    "accept-encoding",
+    "content-encoding",
+}
+
+_clients: dict[str, httpx.AsyncClient] = {}
+
+
+async def forward_request(request: Request) -> Response | None:
+    """Forward the request to its domain's remote, or None when local.
+
+    The original Host header is preserved so the remote dispatches to the
+    same domain (sessions are host-bound). The user's cookie authenticates
+    the forwarded call; the satellite needs no credentials of its own.
+    """
+    domain = domains.registry().resolve(request.headers.get("host"))
+    if domain is None or domain.remote is None:
+        return None
+    url = domain.remote.url
+    client = _clients.get(url)
+    if client is None:
+        client = _clients[url] = httpx.AsyncClient(base_url=url, timeout=_TIMEOUT)
+    upstream = await client.request(
+        request.method,
+        request.url.path,
+        params=request.url.query,
+        content=await request.body(),
+        headers={
+            k: v for k, v in request.headers.items() if k.lower() not in _HOP_BY_HOP
+        },
+    )
+    response = Response(content=upstream.content, status_code=upstream.status_code)
+    # Raw headers to preserve repeated Set-Cookie
+    response.raw_headers = [
+        (k, v) for k, v in upstream.headers.raw if k.decode().lower() not in _HOP_BY_HOP
+    ]
+    return response
@@ -0,0 +1,60 @@
+"""RAM-only change feed letting satellite instances mirror this server.
+
+Nothing here touches the database file: committed mutations are pushed to
+connected satellites over the sync WebSocket (fastapi/sync.py). Satellites
+authenticate with a token from the PASKIA_SYNC_TOKENS environment variable
+(comma-separated); with the variable unset the sync endpoint stays closed.
+
+There is deliberately no replay log: snapshots are small, so a reconnecting
+satellite simply takes a fresh one.
+"""
+
+import asyncio
+import os
+
+import msgspec
+
+# Tables mirrored by satellites (reset tokens, OIDC data and domain config
+# are instance-local and never replicated).
+TABLES = ("permissions", "orgs", "roles", "users", "credentials", "sessions")
+
+_subscribers: set[asyncio.Queue] = set()
+
+
+def emit(table: str, key: str, obj) -> None:
+    """Publish an upsert (obj given) or delete (obj None) to subscribers."""
+    event = {
+        "type": "event",
+        "table": table,
+        "key": key,
+        "fields": msgspec.to_builtins(obj) if obj is not None else None,
+    }
+    for queue in list(_subscribers):
+        try:
+            queue.put_nowait(event)
+        except asyncio.QueueFull:
+            # Slow consumer: drop it; the client reconnects and resyncs.
+            _subscribers.discard(queue)
+
+
+def subscribe() -> asyncio.Queue:
+    queue: asyncio.Queue = asyncio.Queue(maxsize=1000)
+    _subscribers.add(queue)
+    return queue
+
+
+def unsubscribe(queue: asyncio.Queue) -> None:
+    _subscribers.discard(queue)
+
+
+def tokens_from_env() -> set[str]:
+    """Accepted sync tokens (PASKIA_SYNC_TOKENS, comma-separated)."""
+    return {
+        t.strip()
+        for t in os.environ.get("PASKIA_SYNC_TOKENS", "").split(",")
+        if t.strip()
+    }
+
+
+def encode(message: dict) -> bytes:
+    return msgspec.json.encode(message)
@@ -14,7 +14,15 @@ import msgspec
 from uarite import uaparse

 from paskia import db
-from paskia.db.structs import Credential, Org, OriginEntry, Permission, Role, User
+from paskia.db.structs import (
+    Credential,
+    Org,
+    OriginEntry,
+    Permission,
+    RemoteConfig,
+    Role,
+    User,
+)

 # -------------------------------------------------------------------------
 # API structs - inherit from db structs, add uuid for serialization
@@ -194,6 +202,7 @@ class ApiDomain(msgspec.Struct):
    site_url: str
    auth_site_url: str
    auth_host: str | None
+    remote: RemoteConfig | None = None


 class ApiTokenInfo(msgspec.Struct, omit_defaults=True):
@@ -1,6 +1,5 @@
 """Small, dependency-free constants shared by CLI and server modules."""

-import os
-
+# App-side default; paskia.__main__ keeps its own literal copy because
+# fastapi-vue-setup reads DEFAULT_PORT from the CLI module on upgrades.
 DEFAULT_PORT = 4401
-DEVMODE = os.getenv("PASKIA_DEV") == "1"
@@ -98,15 +98,3 @@ def normalize_host(raw_host: str | None) -> str | None:
        # Strip port from host:port
        netloc = netloc.rsplit(":", 1)[0]
    return netloc.lower().rstrip(".") or None
-
-
-def format_endpoint(ep: dict) -> str:
-    """Format an endpoint dict to a listen string (e.g. 'unix:/path' or 'host:port')."""
-    if uds := ep.get("uds"):
-        return f"unix:{uds}"
-    host = ep["host"]
-    port = ep["port"]
-    # Bracket IPv6 addresses
-    if ":" in host:
-        host = f"[{host}]"
-    return f"{host}:{port}"
@@ -2,35 +2,28 @@

 Domain configuration lives in the database (``Config.domains``); the
 ``PASKIA_CONFIG`` environment variable only carries the effective listen
-endpoints so that child processes (uvicorn reload / workers) can derive
-site URLs the same way the parent did.
+endpoints and whether to persist them, so that child processes (uvicorn
+reload / workers) derive site URLs the same way the parent did. The CLI
+entry point mutates the bound object before ``server.run()`` calls
+``teleport()`` to pass it on.
 """

-import os
-from functools import lru_cache
-
 import msgspec
+from fastapi_vue import env


 class ServeConfig(msgspec.Struct):
    """Process-global serve parameters."""

    listen: list[str] | None = None
+    save: bool = False  # Persist listen to the stored config on startup


-@lru_cache(maxsize=1)
-def _load() -> ServeConfig | None:
-    raw = os.getenv("PASKIA_CONFIG")
-    if not raw:
-        return None
-    return msgspec.json.decode(raw.encode(), type=ServeConfig)
-
-
-def serve_config() -> ServeConfig | None:
-    """Return cached serve configuration loaded from PASKIA_CONFIG."""
-    return _load()
+def serve_config() -> ServeConfig:
+    """Return the serve configuration bound to PASKIA_CONFIG."""
+    return env(ServeConfig, name="CONFIG")


 def clear_cache() -> None:
-    """Clear cached serve configuration; next serve_config() reloads."""
-    _load.cache_clear()
+    """Drop the bound configuration; next serve_config() re-decodes."""
+    env._bindings.pop("CONFIG", None)  # noqa: SLF001
@@ -2,24 +2,21 @@

 from __future__ import annotations

-import os
 import re
-from sys import stderr
 from typing import TYPE_CHECKING
 from urllib.parse import urlparse

+from fastapi_vue import env
 from fastapi_vue.hostutil import parse_endpoints
+from fastapi_vue.server import print_startup_box

-from paskia._version import __version__
 from paskia.domains import auth_host_url, origin_url, partition_origins
 from paskia.util import hostutil
-from paskia.util.constants import DEFAULT_PORT, DEVMODE
-from paskia.util.hostutil import format_endpoint, wildcard_base
+from paskia.util.hostutil import wildcard_base

 if TYPE_CHECKING:
    from paskia.domains import DomainRegistry

-BOX_WIDTH = 80  # Maximum inner width (excluding box chars)
 URL_COL = 22  # Column where header URLs start (past the logo graphic)

 # ANSI color codes
@@ -28,46 +25,12 @@ YELLOW = "\033[38;5;184m"  # Bright yellow (6x6x6 cube, r=4 g=4)
 BRIGHT_YELLOW = "\033[38;5;226m"  # Brightest yellow (6x6x6 cube)
 BRIGHT_WHITE = "\033[1;37m"  # Bold bright white

-_TOKENS = re.compile(r"\033\[[0-9;]*m|.")
-

 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 _truncate(text: str, width: int) -> str:
-    """Cut text to at most `width` visible chars, keeping ANSI codes intact."""
-    if _visible_len(text) <= width:
-        return text
-    out = []
-    visible = 0
-    for tok in _TOKENS.findall(text):
-        if tok.startswith("\033"):
-            out.append(tok)
-        elif visible < width - 1:
-            out.append(tok)
-            visible += 1
-        else:
-            break
-    return "".join(out) + "…" + RESET
-
-
-def line(text: str = "", width: int = BOX_WIDTH) -> str:
-    """Format a line inside the box with proper padding, truncating if needed."""
-    text = _truncate(text, width)
-    padding = width - _visible_len(text)
-    return f"┃ {text}{' ' * padding} ┃\n"
-
-
-def top(width: int = BOX_WIDTH) -> str:
-    return "┏" + "━" * (width + 2) + "┓\n"
-
-
-def bottom(width: int = BOX_WIDTH) -> str:
-    return "┗" + "━" * (width + 2) + "┛\n"
-
-
 def _compact_url(url: str) -> str:
    """Bare host for https URLs; scheme and port kept for plain http."""
    stripped = url.removeprefix("https://")
@@ -135,7 +98,10 @@ def _signin_summary(in_domain: list[str], rp_id: str) -> str:


 def print_startup_config(
-    registry: DomainRegistry, listen: list[str] | None = None
+    registry: DomainRegistry,
+    listen: list[str] | None = None,
+    *,
+    default_port: int,
 ) -> None:
    """Print server configuration on startup (one section per domain)."""
    # Key graphic with yellow shading (bright for highlights, dark for body)
@@ -146,18 +112,15 @@ def print_startup_config(

    domains = sorted(registry.domains, key=lambda d: d.rp_id)

-    # Format listen endpoints (dev mode only uses the first endpoint)
-    endpoints = list(parse_endpoints(listen, DEFAULT_PORT))
-    if DEVMODE:
-        endpoints = endpoints[:1]  # server.run reload=True uses only one
-    parts = [format_endpoint(ep) for ep in endpoints]
+    # Endpoints as bound, passed to fastapi_vue for the {listen} field
+    endpoints = list(parse_endpoints(listen, default_port))

    # Header URLs: when a vite dev server is configured, its URL (marked
    # "vite dev"); otherwise one per configured auth host (a full origin URL,
    # clickable in terminals). If none are configured, guess one domain
    # (prefer the shortest https rp_id) and link its /auth/ site path.
    # Entries are pre-styled: bold for the URL, plain for any marker.
-    vite_url = os.environ.get("PASKIA_VITE_URL") if DEVMODE else None
+    vite_url = env.vite_url if env.dev else None
    if vite_url:
        header_urls = [f"{w}{vite_url}{r} (vite dev)"]
    else:
@@ -178,9 +141,10 @@ def print_startup_config(
    rows = []
    # Logo lines 4-5 carry the first two header URLs; further URLs go on
    # blank-gutter lines beneath the graphic, all at the same column.
+    # @VERSION@/@LISTEN@ are filled in by fastapi_vue's print_startup_box.
    logo = [
        f" {b}▄▄▄▄▄{r}",
-        f"{b}█{y}     {b}█{r} Paskia {__version__} @ {' '.join(parts)}",
+        f"{b}█{y}     {b}█{r} Paskia @VERSION@ @ @LISTEN@",
        f"{b}█{y}     {b}█{y}▄▄▄▄▄▄▄▄▄▄▄▄{r}",
        f"{b}█{y}     {b}█{y}▀▀▀▀{b}█{y}▀▀{b}█{y}▀▀{b}█{r}",
        f" {y}▀▀▀▀▀{r}",
@@ -196,7 +160,7 @@ def print_startup_config(
        rows.append(f"{' ' * URL_COL}{url}")

    for domain in domains:
-        # One compact line per domain; overlong lines are capped at render.
+        # One compact line per domain.
        rp_name = domain.rp_name
        suffix = f" ({rp_name})" if rp_name and rp_name != domain.rp_id else ""
        head = f"{w}{domain.rp_id}{r}{suffix}"
@@ -204,21 +168,22 @@ def print_startup_config(
            rows.append(f"{head} — no sign-in sites")
            continue
        in_domain, related = partition_origins(domain.rp_id, domain.config.origins)
-        parts = []
+        phrases = []
        if in_domain:
-            parts.append(_signin_summary(in_domain, domain.rp_id))
-        parts.extend(_compact_url(origin_url(k)) for k in sorted(related))
+            phrases.append(_signin_summary(in_domain, domain.rp_id))
+        phrases.extend(_compact_url(origin_url(k)) for k in sorted(related))
        # "with" implies the rp_id itself may sign in (exact key or a full
        # wildcard); otherwise the origins are a mere list, after a colon.
        covers_self = any(
            k == domain.rp_id or k == f"**.{domain.rp_id}" for k in in_domain
        )
        sep = " with " if covers_self else ": "
-        rows.append(f"{head}{sep}{' and '.join(parts)}")
+        rows.append(f"{head}{sep}{' and '.join(phrases)}")

-    # Size the box to the widest row, capped at BOX_WIDTH.
-    width = min(BOX_WIDTH, max(_visible_len(t) for t in rows))
-    out = [top(width)]
-    out.extend(line(text, width) for text in rows)
-    out.append(bottom(width))
-    stderr.write("".join(out))
+    # fastapi_vue prints the box: version from package metadata, listen
+    # addresses as bound (localhost expanded to both loopbacks). Braces in
+    # our content (e.g. an rp-name) are escaped before template formatting.
+    text = "\n".join(rows)
+    text = text.replace("{", "{{").replace("}", "}}")
+    text = text.replace("@VERSION@", "{version}").replace("@LISTEN@", "{listen}")
+    print_startup_box(text, "paskia.fastapi.mainapp:app", endpoints)
@@ -1,6 +1,6 @@
 """User information formatting and retrieval logic."""

-from paskia import aaguid, db
+from paskia import aaguid, satellite
 from paskia.db import SessionContext
 from paskia.util import avatar, hostutil
 from paskia.util.apistructs import (
@@ -43,24 +43,30 @@ async def build_user_info(
    ctx: SessionContext | None = None,
 ) -> ApiUserDetail:
    """Build user info struct for authenticated users."""
-    user = db.data().users[user_uuid]
+    data = satellite.store_for_host(request_host)
+    user = data.users[user_uuid]
    normalized_host = hostutil.normalize_host(request_host)

+    user_sessions = [s for s in data.sessions.values() if s.user_uuid == user_uuid]
+    user_credentials = [
+        c for c in data.credentials.values() if c.user_uuid == user_uuid
+    ]
+
    sessions = {
        s.key: ApiUserSession.from_db(
            s,
            current_key=session_key,
            normalized_host=normalized_host,
        )
-        for s in user.sessions
+        for s in user_sessions
    }

    return ApiUserDetail(
        user=ApiUser.from_db(user, avatar_url=avatar.avatar_browser_url(user.uuid)),
-        credentials={c.uuid: c for c in user.credentials},
+        credentials={c.uuid: c for c in user_credentials},
        aaguid_info={
            k: ApiAaguidInfo(**v)
-            for k, v in aaguid.filter(c.aaguid for c in user.credentials).items()
+            for k, v in aaguid.filter(c.aaguid for c in user_credentials).items()
        },
        sessions=sessions,
        permissions={p.uuid: ApiPermission.from_db(p) for p in ctx.permissions}
@@ -21,8 +21,8 @@ dependencies = [
    "pyjwt[crypto]>=2.11.0",
    "jsondiff>=2.2.1",
    "msgspec>=0.20.0",
-    "fastapi-vue~=1.4.2",
-    "kanta>=0.7.0",
+    "fastapi-vue~=1.7.2",
+    "kanta>=0.9.2",
    "uarite>=0.2.1",
 ]
 [dependency-groups]
@@ -10,6 +10,7 @@ import subprocess
 import sys
 from contextlib import suppress
 from pathlib import Path
+from subprocess import CalledProcessError
 from urllib.parse import urlparse

 import tracerite
@@ -68,10 +69,13 @@ def build_caddyfile(origins: list[str], viteurl: str, backurl: str) -> str:
    return "\n".join(caddyfile_parts)


-async def run_caddy(
-    origins: list[str], viteurl: str, backurl: str
-) -> asyncio.subprocess.Process:
-    """Start Caddy as HTTPS reverse proxy, wait for ready signal."""
+async def run_caddy(origins: list[str], viteurl: str, backurl: str) -> None:
+    """Run Caddy as HTTPS reverse proxy for the group's lifetime.
+
+    Waits for the ready signal, then drains stderr until Caddy exits or the
+    task is cancelled (ProcessGroup shutdown), terminating Caddy on exit.
+    Raises CalledProcessError if Caddy dies, cancelling the group.
+    """
    caddy_path = shutil.which("caddy")
    if not caddy_path:
        logger.warning("Caddy not found. Install it to use --caddy option.")
@@ -86,57 +90,56 @@ async def run_caddy(
        stdin=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE,
    )
-    proc.stdin.write(caddyfile.encode())
-    await proc.stdin.drain()
-    proc.stdin.close()
+    try:
+        proc.stdin.write(caddyfile.encode())
+        await proc.stdin.drain()
+        proc.stdin.close()

-    # Wait for ready signal or failure
-    while True:
-        if proc.returncode is not None:
-            remaining = await proc.stderr.read()
-            for line in remaining.decode().splitlines():
-                if line:
-                    logger.info("caddy: %s", line)
-            logger.warning("Caddy startup failed (exit code %d)", proc.returncode)
-            raise SystemExit(1)
-
-        line = await proc.stderr.readline()
-        if not line:
-            continue
-
-        decoded = line.decode().rstrip()
-        if "serving initial configuration" in decoded:
-            break
-
-        # Parse and show errors during startup
-        if decoded:
-            try:
-                log = json.loads(decoded)
-                level = log.get("level", "")
-                if level in ("error", "fatal", "warn"):
-                    logger.warning("caddy: %s", log.get("msg", decoded))
-            except json.JSONDecodeError:
-                if "error" in decoded.lower() or "fatal" in decoded.lower():
-                    logger.warning("caddy: %s", decoded)
-
-    # Start background task to drain stderr
-    async def drain_caddy_stderr():
+        # Wait for ready signal or failure
        while True:
+            if proc.returncode is not None:
+                await log_caddy_stderr(proc.stderr, starting=True)
+                logger.warning("Caddy startup failed (exit code %d)", proc.returncode)
+                raise CalledProcessError(proc.returncode, cmd)
+
            line = await proc.stderr.readline()
            if not line:
-                break
-            decoded = line.decode().rstrip()
-            if decoded:
-                try:
-                    log = json.loads(decoded)
-                    level = log.get("level", "")
-                    if level in ("error", "fatal", "warn"):
-                        logger.warning("caddy: %s", log.get("msg", decoded))
-                except json.JSONDecodeError:
-                    pass  # Ignore non-JSON output after startup
+                continue

-    asyncio.create_task(drain_caddy_stderr())
-    return proc
+            decoded = line.decode().rstrip()
+            if "serving initial configuration" in decoded:
+                break
+
+            log_caddy_line(decoded, starting=True)
+
+        # Drain stderr until Caddy exits
+        await proc.wait()
+        await log_caddy_stderr(proc.stderr)
+        raise CalledProcessError(proc.returncode, cmd)
+    finally:
+        with suppress(ProcessLookupError):
+            proc.terminate()
+        await proc.wait()
+
+
+def log_caddy_line(decoded: str, *, starting: bool = False) -> None:
+    """Log one Caddy stderr line (JSON during/after startup)."""
+    if not decoded:
+        return
+    try:
+        log = json.loads(decoded)
+        level = log.get("level", "")
+        if level in ("error", "fatal", "warn"):
+            logger.warning("caddy: %s", log.get("msg", decoded))
+    except json.JSONDecodeError:
+        if starting and ("error" in decoded.lower() or "fatal" in decoded.lower()):
+            logger.warning("caddy: %s", decoded)
+
+
+async def log_caddy_stderr(stream: asyncio.StreamReader, *, starting: bool = False) -> None:
+    """Drain and log remaining Caddy stderr."""
+    while line := await stream.readline():
+        log_caddy_line(line.decode().rstrip(), starting=starting)


 def _split_multi(values: list[str] | None) -> list[str]:
@@ -204,22 +207,25 @@ async def run_devserver(args: argparse.Namespace, remaining: list[str]) -> None:
                caddy_origins.append(f"https://{rp_id}")
            seen: set = set()
            caddy_origins = [x for x in caddy_origins if not (x in seen or seen.add(x))]
-            caddy_proc = await run_caddy(caddy_origins, viteurl, backurl)
-            pg._procs.append(caddy_proc)
-            pg._cmds[caddy_proc.pid] = "caddy"
+            pg.create_task(run_caddy(caddy_origins, viteurl, backurl))

+        pg.create_task(check_ports_free(viteurl, backurl))
        npm_proc = await pg.spawn(*npm_install, cwd=frontend_path)
-        await check_ports_free(viteurl, backurl)
-        await pg.spawn(*paskia)
+        await pg.spawn(*paskia, vital=True)
        await pg.wait(
            npm_proc, ready(backurl, path="/auth/api/settings?from=devserver.py")
        )
-        await pg.spawn(*vite, cwd=frontend_path)
+        await pg.spawn(*vite, cwd=frontend_path, vital=True)


 def main():
    tracerite.load()
-    parser = argparse.ArgumentParser(add_help=False)
+    parser = argparse.ArgumentParser(
+        add_help=False,
+        description="Run Vite and FastAPI development servers",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=HELP_EPILOG,
+    )
    parser.add_argument(
        "-l",
        "--listen",
@@ -243,8 +249,12 @@ def main():
    )
    args, remaining = parser.parse_known_args()

-    with suppress(KeyboardInterrupt):
+    try:
        asyncio.run(run_devserver(args, remaining))
+    except* KeyboardInterrupt:
+        pass  # user stopped the devserver: normal exit
+    except* subprocess.SubprocessError, RuntimeError:
+        raise SystemExit(1) from None  # logged in devutil already; exit 1


 HELP_EPILOG = """
@@ -11,20 +11,27 @@ from pathlib import Path
 MIN_NODE_VERSION = 20


-class _PrefixFormatter(logging.Formatter):
-    """Formatter that adds prefix based on log level."""
+class _Formatter(logging.Formatter):
+    """Prefix formatter, intentionally different from fastapi_vue.logging.
+
+    INFO and below pass through unprefixed so messages can use their own
+    markings (>>>, ###); WARNING and above get an emoji prefix.
+    """

    def format(self, record: logging.LogRecord) -> str:
+        if record.levelno >= logging.ERROR:
+            return f"🛑 {record.getMessage()}"
        if record.levelno >= logging.WARNING:
-            return f"⚠️  {record.getMessage()}"
+            return f"💣 {record.getMessage()}"
        return record.getMessage()


 _handler = logging.StreamHandler()
-_handler.setFormatter(_PrefixFormatter())
+_handler.setFormatter(_Formatter())
 logger = logging.getLogger("fastapi-vue")
 logger.addHandler(_handler)
 logger.setLevel(logging.INFO)
+logger.propagate = False  # own handler; do not double-print via a configured root


 def _check_node_version(node_path: str) -> None:
@@ -1,108 +1,87 @@
 # ruff: noqa: INP001
 """Utilities meant for devserver script, used only in source repository with dev deps."""

+from __future__ import annotations
+
 import asyncio
-import subprocess
 import sys
+from asyncio.subprocess import Process
 from contextlib import suppress
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Self
+from subprocess import CalledProcessError
+from typing import TYPE_CHECKING, Any
 from urllib.parse import urlsplit

 from buildutil import find_dev_tool, find_install_tool, logger
 from fastapi_vue.hostutil import parse_endpoint

 if TYPE_CHECKING:
-    from collections.abc import Coroutine
+    from collections.abc import Awaitable


-class ProcessGroup:
-    """Manage async subprocesses with automatic cleanup, like TaskGroup for processes."""
+class ProcessGroup(asyncio.TaskGroup):
+    """TaskGroup with structured ownership of async subprocesses."""

-    def __init__(self) -> None:
-        """Initialize empty process tracking."""
-        self._procs: list[asyncio.subprocess.Process] = []
-        self._cmds: dict[int, str] = {}  # pid -> command name
+    def __init__(self, *, terminate_timeout: float = 10) -> None:
+        """Set the grace period before terminate() escalates to kill()."""
+        super().__init__()
+        self._terminate_timeout = terminate_timeout
+        self._cmds: dict[Process, tuple[str, ...]] = {}

    async def spawn(
-        self,
-        *cmd: str,
-        cwd: str | None = None,
-    ) -> asyncio.subprocess.Process:
-        """Spawn a subprocess and track it."""
-        cmd_name = Path(cmd[0]).stem
-        logger.info(">>> %s", " ".join([cmd_name, *cmd[1:]]))
-        proc = await asyncio.create_subprocess_exec(*cmd, cwd=cwd)
-        self._procs.append(proc)
-        self._cmds[proc.pid] = cmd_name
-        return proc
+        self, *cmd: str, cwd: str | None = None, vital: bool = False
+    ) -> Process:
+        """Spawn and own a subprocess. If a vital process exits, the group cancels."""

-    async def wait(
-        self,
-        *waitables: asyncio.subprocess.Process | Coroutine[Any, Any, Any],
-    ) -> None:
-        """Wait for processes/coroutines to complete, raise SystemExit on failure."""
+        async def run() -> None:
+            name = Path(cmd[0]).stem
+            logger.info(">>> %s", " ".join([name, *cmd[1:]]))
+            try:
+                proc = await asyncio.create_subprocess_exec(*cmd, cwd=cwd)
+                self._cmds[proc] = cmd
+                started.set_result(proc)
+            except Exception as e:  # noqa: BLE001
+                started.set_exception(e)
+                return

-        async def wait_proc(proc: asyncio.subprocess.Process) -> None:
-            returncode = await proc.wait()
-            if returncode != 0:
-                cmd_name = self._cmds.get(proc.pid, "unknown")
-                raise subprocess.CalledProcessError(returncode, cmd_name)
-
-        tasks = [
-            wait_proc(w) if isinstance(w, asyncio.subprocess.Process) else w
-            for w in waitables
-        ]
-        try:
-            await asyncio.gather(*tasks)
-        except subprocess.CalledProcessError as e:
-            logger.warning("%s failed with exit status %d", e.cmd, e.returncode)
-            raise SystemExit(1) from None
-
-    async def __aenter__(self) -> Self:
-        """Enter the async context manager."""
-        return self
-
-    async def __aexit__(self, exc_type: type[BaseException] | None, *_: object) -> None:
-        """Wait for one process to exit, terminate others, then wait for all."""
-        await self._cleanup(immediate=exc_type is not None)
-
-    async def _cleanup(self, *, immediate: bool = False) -> None:
-        running = [p for p in self._procs if p.returncode is None]
-        if not running:
-            return
-
-        if not immediate:
-            # Wait for any one process to exit
-            with suppress(asyncio.CancelledError):
-                await asyncio.wait(
-                    [asyncio.create_task(p.wait()) for p in running],
-                    return_when=asyncio.FIRST_COMPLETED,
-                )
-
-        # Terminate remaining processes
-        for p in self._procs:
-            if p.returncode is None:
+            try:
+                returncode = await proc.wait()
+            finally:
                with suppress(ProcessLookupError):
-                    p.terminate()
-
-        # Wait for all to finish (with overall timeout), shielded from cancellation
-        still_running = [p for p in self._procs if p.returncode is None]
-        if still_running:
-            with suppress(asyncio.CancelledError):
+                    proc.terminate()
                try:
-                    await asyncio.shield(
-                        asyncio.wait_for(
-                            asyncio.gather(*[p.wait() for p in still_running]),
-                            timeout=10,
-                        ),
-                    )
+                    await asyncio.wait_for(proc.wait(), self._terminate_timeout)
                except TimeoutError:
-                    for p in self._procs:
-                        if p.returncode is None:
-                            with suppress(ProcessLookupError):
-                                p.kill()
-                            await p.wait()
+                    with suppress(ProcessLookupError):
+                        proc.kill()
+                    await proc.wait()
+
+            if vital:
+                logger.warning("Vital process %s exited", name)
+                raise CalledProcessError(returncode, cmd)
+
+        started = asyncio.get_running_loop().create_future()
+        self.create_task(run())
+        return await asyncio.shield(started)
+
+    async def wait(self, *waitables: Process | Awaitable) -> tuple[Any, ...]:
+        """Wait concurrently and return results in argument order."""
+
+        async def task(w: Process | Awaitable) -> Any:  # noqa: ANN401
+            if not isinstance(w, Process):
+                return await w
+            if retcode := await w.wait():
+                cmd = self._cmds[w]
+                logger.warning(
+                    "Process %s exited with status %d", Path(cmd[0]).stem, retcode
+                )
+                raise CalledProcessError(retcode, cmd)
+            return retcode
+
+        async with asyncio.TaskGroup() as group:
+            tasks = [group.create_task(task(w)) for w in waitables]
+
+        return tuple(task.result() for task in tasks)


 async def http_get_server(url: str, timeout: float) -> str | None:  # noqa: ASYNC109
@@ -128,42 +107,43 @@ async def http_get_server(url: str, timeout: float) -> str | None:  # noqa: ASYN
                writer.close()
    except OSError, EOFError, ValueError, TimeoutError:
        return None
-    for line in data.decode("latin-1").split("\r\n"):
+    for line in data.decode(errors="replace").split("\r\n"):
        if line.lower().startswith("server:"):
-            return line.split(":", 1)[1].strip()
+            return line[7:].strip()
    return ""


 async def check_ports_free(*urls: str) -> None:
-    """Verify URLs are not responding (ports are free). Raise SystemExit if any respond."""
+    """Verify URLs are not responding (ports are free).

-    async def check(url: str) -> None:
-        server = await http_get_server(url, timeout=0.1)
+    Meant to run as a task inside a TaskGroup. Logs the conflict and raises
+    RuntimeError (handled like a failed process) if any URL responds.
+    """
+    servers = await asyncio.gather(*(http_get_server(url, timeout=0.1) for url in urls))
+    for url, server in zip(urls, servers, strict=True):
        if server is not None:
-            logger.warning(
+            logger.error(
                "Conflicting %s already running at %s", server or "server", url
            )
-            raise SystemExit(1)
-
-    await asyncio.gather(*[check(url) for url in urls])
+            raise RuntimeError(url)


 async def ready(url: str, path: str = "", max_attempts: int = 50) -> None:
    """Wait for the server to be ready by polling an endpoint.

    Use empty path to disable the check and make this return immediately.
-    Raises SystemExit(1) if server doesn't start in time.
+    Logs, then raises RuntimeError if the server doesn't start in time.
    """
    if not path:
        return

    for attempt in range(max_attempts):
        if await http_get_server(f"{url}{path}", timeout=1.0) is not None:
-            logger.info("✓ Backend ready!")
+            logger.info("🟢 Backend ready!")
            return
        if attempt == max_attempts - 1:
-            logger.warning("Backend didn't start in time")
-            raise SystemExit(1)
+            logger.error("Backend at %s didn't start in time", url)
+            raise RuntimeError(url)
        await asyncio.sleep(0.1)


@@ -0,0 +1,158 @@
+#!/usr/bin/env -S uv run
+"""Release build for paskia (PyPI) and paskia-js (npm).
+
+Usage: release.py [patch|minor|major]  (default: patch)
+
+Bumps the version from the latest vX.Y.Z tag, commits "Release x.y.z" with
+the paskia-js version bump and tags it, then builds both packages from a
+clean slate. On failure the release commit and tag are rolled back.
+Publishing is left to the user; the command is printed on success.
+"""
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+# Build outputs removed before building
+ARTIFACTS = ["dist", "paskia-js/dist", "paskia/frontend-build", "build"]
+
+# Dependency state removed for a fresh upstream resolve (all untracked)
+JS_DIRS = ["paskia-js", "frontend"]
+JS_JUNK = ["node_modules", "package-lock.json", "deno.lock", "bun.lock"]
+
+BUMPS = ("patch", "minor", "major")
+
+
+def run(cmd: list[str], cwd: Path = REPO_ROOT) -> None:
+    print(f"### {' '.join(cmd)}")
+    subprocess.run(cmd, cwd=cwd, check=True)  # noqa: S603
+
+
+def abort(msg: str) -> None:
+    print(f"error: {msg}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def git(*args: str) -> str:
+    return subprocess.run(  # noqa: S603
+        ["git", *args], cwd=REPO_ROOT, check=True, capture_output=True, text=True
+    ).stdout.strip()
+
+
+def check_clean_tree() -> None:
+    status = git("status", "--porcelain")
+    if status:
+        print(status, file=sys.stderr)
+        abort("working tree is not clean; commit or stash all changes first")
+
+
+def latest_version() -> tuple[int, int, int]:
+    """Highest vX.Y.Z tag, as a tuple."""
+    tags = []
+    for tag in git("tag", "--list", "v*").splitlines():
+        parts = tag.removeprefix("v").split(".")
+        if len(parts) == 3 and all(p.isdigit() for p in parts):
+            tags.append(tuple(int(p) for p in parts))
+    if not tags:
+        abort("no existing vX.Y.Z tags found")
+    return max(tags)
+
+
+def next_version(bump: str) -> tuple[int, int, int]:
+    major, minor, patch = latest_version()
+    if bump == "major":
+        return (major + 1, 0, 0)
+    if bump == "minor":
+        return (major, minor + 1, 0)
+    return (major, minor, patch + 1)
+
+
+def set_js_version(version: str) -> None:
+    pkg_path = REPO_ROOT / "paskia-js/package.json"
+    pkg = json.loads(pkg_path.read_text())
+    if pkg.get("version") == version:
+        return
+    print(f"paskia-js/package.json: {pkg.get('version')} -> {version}")
+    pkg["version"] = version
+    pkg_path.write_text(json.dumps(pkg, indent=2) + "\n")
+
+
+def remove(path: Path, rel: str) -> None:
+    if not path.exists():
+        return
+    print(f"rm -rf {rel}")
+    if path.is_dir():
+        shutil.rmtree(path)
+    else:
+        path.unlink()
+
+
+def clean() -> None:
+    for rel in ARTIFACTS:
+        remove(REPO_ROOT / rel, rel)
+    for d in JS_DIRS:
+        for junk in JS_JUNK:
+            remove(REPO_ROOT / d / junk, f"{d}/{junk}")
+
+
+def main() -> None:
+    bump = sys.argv[1] if len(sys.argv) == 2 else "patch"
+    if len(sys.argv) > 2 or bump not in BUMPS:
+        print(__doc__)
+        raise SystemExit(1)
+
+    check_clean_tree()
+    version_tuple = next_version(bump)
+    version = ".".join(str(p) for p in version_tuple)
+    tag = f"v{version}"
+    if tag in git("tag", "--list", tag).splitlines():
+        abort(f"tag {tag} already exists")
+    print(f"Release version: {version}")
+
+    previous_head = git("rev-parse", "HEAD")
+    released = False
+    try:
+        # Clean before committing: only the uv build (hatch-vcs) depends on
+        # the tag, so the release commit can be made from a clean slate.
+        clean()
+        set_js_version(version)
+        run(["git", "add", "paskia-js/package.json"])
+        run(["git", "commit", "-m", f"Release {version}"])
+        run(["git", "tag", tag])
+        released = True
+
+        # uv build runs the hatch hook that builds paskia-js and the Vue
+        # frontend into paskia/frontend-build with fresh dependencies.
+        run(["uv", "build"])
+        # Explicit paskia-js build: verifies the package standalone and
+        # leaves paskia-js/dist ready for npm publish.
+        run(["npm", "install"], cwd=REPO_ROOT / "paskia-js")
+        run(["npm", "run", "build"], cwd=REPO_ROOT / "paskia-js")
+    except BaseException:
+        if released:
+            print("Build failed; rolling back the release commit and tag.", file=sys.stderr)
+            subprocess.run(["git", "tag", "-d", tag], cwd=REPO_ROOT, check=False)  # noqa: S603
+            # The tree was clean before the release commit, so a hard reset
+            # back to it is safe.
+            subprocess.run(["git", "reset", "--hard", previous_head], cwd=REPO_ROOT, check=False)  # noqa: S603
+        raise
+
+    # Push the release commit to the tracking remote, then the new tag.
+    # Not rolled back on failure: the local release is intact, just push again.
+    try:
+        run(["git", "push"])
+        run(["git", "push", "--tags"])
+    except subprocess.CalledProcessError:
+        abort("push failed; the release commit and tag exist locally, push manually")
+
+    print(f"\nBuild completed successfully for version {version}.")
+    print("To publish, review the artifacts and run:")
+    print("\nuv publish && cd paskia-js && npm publish")
+
+
+if __name__ == "__main__":
+    main()
@@ -172,6 +172,7 @@ def test_serve_uses_stored_config(run_cli, tmp_path):
    assert calls["listen"] is None  # stored listen (None) used
    serve = msgspec.json.decode(os.environ["PASKIA_CONFIG"].encode(), type=ServeConfig)
    assert serve.listen is None
+    assert serve.save is False


 def test_serve_listen_override_not_persisted(run_cli, tmp_path):
@@ -181,24 +182,33 @@ def test_serve_listen_override_not_persisted(run_cli, tmp_path):
    assert calls["listen"] == ["4403"]
    serve = msgspec.json.decode(os.environ["PASKIA_CONFIG"].encode(), type=ServeConfig)
    assert serve.listen == ["4403"]
+    assert serve.save is False
    # Stored config keeps the original listen value
    assert stored_config(tmp_path).listen == ["4402"]


 def test_serve_listen_save_persists(run_cli, tmp_path):
+    """--save teleports the save flag; the app persists, the CLI is read-only."""
    run_cli("init", "--listen", "4402")
    calls = run_cli("--listen", "4403", "--save")

    assert calls["listen"] == ["4403"]
-    assert stored_config(tmp_path).listen == ["4403"]
+    serve = msgspec.json.decode(os.environ["PASKIA_CONFIG"].encode(), type=ServeConfig)
+    assert serve.listen == ["4403"]
+    assert serve.save is True
+    # The CLI itself does not write the database
+    assert stored_config(tmp_path).listen == ["4402"]


 def test_serve_listen_save_clear(run_cli, tmp_path):
-    """--listen "" --save clears the stored endpoints (back to default)."""
+    """--listen "" --save teleports a clear (back to default) for the app."""
    run_cli("init", "--listen", "4402")
    run_cli("--listen", "", "--save")

-    assert stored_config(tmp_path).listen is None
+    serve = msgspec.json.decode(os.environ["PASKIA_CONFIG"].encode(), type=ServeConfig)
+    assert serve.listen is None
+    assert serve.save is True
+    assert stored_config(tmp_path).listen == ["4402"]


 def test_serve_suggests_migrate_when_legacy_present(run_cli, tmp_path):
@@ -0,0 +1,427 @@
+"""Tests for remote (satellite) domains: config, replica application, feed."""
+
+import secrets
+import time
+from datetime import UTC, datetime
+from uuid import UUID
+
+import httpx
+import msgspec
+import pytest
+import pytest_asyncio
+from fastapi import Response
+
+import paskia.db.operations as ops_db
+from paskia import domains, satellite, syncfeed
+from paskia.db.structs import (
+    DB,
+    Config,
+    Credential,
+    DomainConfig,
+    Org,
+    OriginEntry,
+    Permission,
+    RemoteConfig,
+    Role,
+    Session,
+    User,
+)
+from paskia.fastapi.mainapp import app
+from paskia.fastapi.session import AUTH_COOKIE_NAME
+from paskia.util.crypto import hash_secret
+
+from .conftest import TEST_RP_ID
+
+REMOTE_URL = "http://remote.test"
+
+
+def _remote_domain_config(**kw) -> Config:
+    return Config(
+        domains={
+            TEST_RP_ID: DomainConfig(origins={f"**.{TEST_RP_ID}": True}),
+            "example.com": DomainConfig(
+                origins={
+                    "**.example.com": True,
+                    "auth.example.com": OriginEntry(auth_host=True),
+                },
+                remote=RemoteConfig(url=REMOTE_URL, token="t", **kw),
+            ),
+        }
+    )
+
+
+def test_remote_domain_valid():
+    domains.validate_config(_remote_domain_config())
+
+
+def test_remote_domain_requires_auth_host():
+    config = _remote_domain_config()
+    config.domains["example.com"].origins = {"**.example.com": True}
+    with pytest.raises(ValueError, match="auth host"):
+        domains.validate_config(config)
+
+
+def test_remote_domain_requires_http_url():
+    config = _remote_domain_config()
+    config.domains["example.com"].remote.url = "ftp://x"
+    with pytest.raises(ValueError, match="http"):
+        domains.validate_config(config)
+
+
+def test_sanitize_preserves_remote():
+    config, warnings = domains.sanitize_config(_remote_domain_config())
+    assert not warnings
+    assert config.domains["example.com"].remote.url == REMOTE_URL
+
+
+def test_apply_upsert_and_delete():
+    replica = DB()
+    user = User.create(display_name="U", role=UUID(int=1))
+    user.uuid = UUID(int=2)
+    satellite._apply(replica, "users", str(user.uuid), _builtins(user))
+    assert replica.users[user.uuid].display_name == "U"
+    satellite._apply(replica, "users", str(user.uuid), None)
+    assert not replica.users
+
+
+def _builtins(obj):
+    return msgspec.to_builtins(obj)
+
+
+def test_apply_session_roundtrip():
+    """Sessions keep their string key and datetime/UUID fields."""
+    replica = DB()
+    session = Session.create(
+        user=UUID(int=1),
+        credential=UUID(int=2),
+        key=hash_secret("cookie", "sekret"),
+        host="app2.example.com",
+        ip="127.0.0.1",
+        user_agent="ua",
+        validated=datetime.now(UTC),
+        rp_id="example.com",
+    )
+    satellite._apply(replica, "sessions", session.key, _builtins(session))
+    stored = replica.sessions[session.key]
+    assert stored.host == "app2.example.com"
+    assert stored.validated == session.validated
+    assert stored.user_uuid == UUID(int=1)
+
+
+def test_apply_credential_bytes_roundtrip():
+    """credential_id/public_key are bytes over the wire (base64 in JSON)."""
+    replica = DB()
+    cred = Credential.create(
+        credential_id=secrets.token_bytes(32),
+        user=UUID(int=1),
+        aaguid=UUID(int=0),
+        public_key=secrets.token_bytes(64),
+        sign_count=3,
+        rp_id="example.com",
+    )
+    cred.uuid = UUID(int=9)
+    # Simulate the full wire path: builtins -> JSON -> builtins
+    wire = msgspec.json.decode(msgspec.json.encode(_builtins(cred)))
+    satellite._apply(replica, "credentials", str(cred.uuid), wire)
+    stored = replica.credentials[cred.uuid]
+    assert stored.credential_id == cred.credential_id
+    assert stored.public_key == cred.public_key
+    assert stored.sign_count == 3
+
+
+def test_feed_emit_to_subscribers():
+    queue = syncfeed.subscribe()
+    try:
+        user = User.create(display_name="A", role=UUID(int=1))
+        syncfeed.emit("users", "k1", user)
+        syncfeed.emit("users", "k1", None)
+        assert queue.get_nowait()["fields"]["display_name"] == "A"
+        assert queue.get_nowait()["fields"] is None
+    finally:
+        syncfeed.unsubscribe(queue)
+
+
+def test_feed_drops_full_queue():
+    queue = syncfeed.subscribe()
+    try:
+        for i in range(1001):
+            syncfeed.emit("users", f"k{i}", None)
+        assert queue.qsize() == 1000
+        syncfeed.emit("users", "k1001", None)  # subscriber already dropped
+        assert queue.qsize() == 1000
+    finally:
+        syncfeed.unsubscribe(queue)
+
+
+@pytest.mark.asyncio
+async def test_operations_emit_events(test_db):
+    """Writes through db.operations land on the sync feed."""
+    queue = syncfeed.subscribe()
+    try:
+        user = next(iter(test_db.users.values()))
+        ops_db.update_user_display_name(user.uuid, "Renamed")
+        event = queue.get_nowait()
+        assert event["table"] == "users"
+        assert event["key"] == str(user.uuid)
+        assert event["fields"]["display_name"] == "Renamed"
+    finally:
+        syncfeed.unsubscribe(queue)
+
+
+@pytest.mark.asyncio
+async def test_replica_refresh_and_evict():
+    replica = satellite.RemoteReplica(RemoteConfig(url=REMOTE_URL, token="t"))
+    token = secrets.token_urlsafe(12)
+    session = Session.create(
+        user=UUID(int=1),
+        credential=UUID(int=2),
+        key=hash_secret("cookie", token),
+        host="app2.example.com",
+        ip="1.1.1.1",
+        user_agent="ua",
+        validated=datetime(2020, 1, 1, tzinfo=UTC),
+    )
+    replica.db.sessions[session.key] = session
+
+    now = datetime.now(UTC)
+    replica.refresh_session(session.key, now, "2.2.2.2", "new-ua")
+    assert replica.db.sessions[session.key].validated == now
+    queued = replica._pending_refresh[session.key]
+    assert queued["type"] == "session_refresh"
+    assert queued["ip"] == "2.2.2.2"
+
+    # Host-keyed dispatch eviction (the replica's domain is resolved by host)
+    domains.configure(listen=["localhost:4401"])
+    domains.init_registry(_remote_domain_config())
+    satellite.manager.replicas[REMOTE_URL] = replica
+    satellite.evict_session(token, "app2.example.com")
+    assert not replica.db.sessions
+    satellite.manager.replicas.pop(REMOTE_URL)
+
+
+def test_availability_gate():
+    replica = satellite.RemoteReplica(
+        RemoteConfig(url=REMOTE_URL, token="t", cache_ttl=60)
+    )
+    assert not replica.available()  # never synced
+    replica.last_contact = time.monotonic()
+    assert replica.available()
+
+
+# -------------------------------------------------------------------------
+# API-level: endpoints served from an injected replica
+# -------------------------------------------------------------------------
+
+
+def _replica_db() -> tuple[DB, str]:
+    """A replica DB holding one org/role/perm/user/credential/session."""
+    replica = DB()
+    org = Org.create(display_name="Org")
+    org.uuid = UUID(int=101)
+    replica.orgs[org.uuid] = org
+    perm = Permission.create(scope="auth:admin", display_name="Admin")
+    perm.uuid = UUID(int=102)
+    perm.orgs[org.uuid] = True
+    replica.permissions[perm.uuid] = perm
+    role = Role.create(org=org.uuid, display_name="Admins", permissions={perm.uuid})
+    role.uuid = UUID(int=103)
+    replica.roles[role.uuid] = role
+    user = User.create(display_name="Remote Admin", role=role.uuid)
+    user.uuid = UUID(int=104)
+    replica.users[user.uuid] = user
+    cred = Credential.create(
+        credential_id=b"cid",
+        user=user.uuid,
+        aaguid=UUID(int=0),
+        public_key=b"pk",
+        sign_count=0,
+        rp_id="example.com",
+    )
+    cred.uuid = UUID(int=105)
+    replica.credentials[cred.uuid] = cred
+    secret = secrets.token_urlsafe(12)
+    session = Session.create(
+        user=user.uuid,
+        credential=cred.uuid,
+        key=hash_secret("cookie", secret),
+        host="app2.example.com",
+        ip="127.0.0.1",
+        user_agent="pytest",
+        validated=datetime.now(UTC),
+        rp_id="example.com",
+    )
+    replica.sessions[session.key] = session
+    return replica, secret
+
+
+@pytest_asyncio.fixture
+async def remote_client(test_db):
+    """ASGI client with example.com as a remote domain on a warm replica."""
+    config = _remote_domain_config()
+    domains.configure(listen=["localhost:4401"])
+    domains.init_registry(config)
+    replica_db, secret = _replica_db()
+    replica = satellite.RemoteReplica(RemoteConfig(url=REMOTE_URL, token="t"))
+    replica.db = replica_db
+    replica.last_contact = time.monotonic()
+    replica.connected = True
+    satellite.manager.replicas[REMOTE_URL] = replica
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://localhost:4401"
+    ) as client:
+        yield client, secret, replica
+    satellite.manager.replicas.pop(REMOTE_URL, None)
+
+
+@pytest.mark.asyncio
+async def test_forward_served_from_replica(remote_client):
+    client, secret, _ = remote_client
+    r = await client.get(
+        "/auth/api/forward?perm=auth:admin",
+        headers={"Host": "app2.example.com", "Cookie": f"{AUTH_COOKIE_NAME}={secret}"},
+    )
+    assert r.status_code == 204
+    assert r.headers["remote-name"] == "Remote Admin"
+    assert r.headers["remote-groups"] == "auth:admin"
+
+
+@pytest.mark.asyncio
+async def test_forward_replica_denies_missing_perm(remote_client):
+    client, secret, _ = remote_client
+    r = await client.get(
+        "/auth/api/forward?perm=other:scope",
+        headers={"Host": "app2.example.com", "Cookie": f"{AUTH_COOKIE_NAME}={secret}"},
+    )
+    assert r.status_code == 403
+
+
+@pytest.mark.asyncio
+async def test_validate_renews_locally_and_queues_writebehind(remote_client):
+    client, secret, replica = remote_client
+    session = next(iter(replica.db.sessions.values()))
+    session.validated = datetime(2020, 1, 1, tzinfo=UTC)  # force refresh threshold
+    r = await client.post(
+        "/auth/api/validate",
+        headers={"Host": "app2.example.com", "Cookie": f"{AUTH_COOKIE_NAME}={secret}"},
+    )
+    assert r.status_code == 200
+    assert r.json()["renewed"] is True
+    assert session.validated.year > 2020  # applied to the replica
+    queued = replica._pending_refresh[session.key]
+    assert queued["type"] == "session_refresh"
+
+
+@pytest.mark.asyncio
+async def test_remote_domain_503_when_replica_stale(remote_client):
+    client, secret, replica = remote_client
+    replica.connected = False
+    replica.last_contact = 0
+    r = await client.get(
+        "/auth/api/forward",
+        headers={"Host": "app2.example.com", "Cookie": f"{AUTH_COOKIE_NAME}={secret}"},
+    )
+    assert r.status_code == 503
+
+
+@pytest.mark.asyncio
+async def test_logout_proxied_and_evicted(remote_client, monkeypatch):
+    client, secret, replica = remote_client
+
+    async def fake_forward(request):
+        return Response(status_code=200, content=b'{"message": "Logged out"}')
+
+    monkeypatch.setattr(satellite, "forward_request", fake_forward)
+    r = await client.post(
+        "/auth/api/logout",
+        headers={"Host": "app2.example.com", "Cookie": f"{AUTH_COOKIE_NAME}={secret}"},
+    )
+    assert r.status_code == 200
+    assert not replica.db.sessions  # evicted optimistically
+
+
+@pytest.mark.asyncio
+async def test_admin_configures_remote_domain(client, session_token, test_db):
+    """The admin domains API stores remote config and masks the token."""
+    r = await client.post(
+        "/auth/api/admin/domains/",
+        json={
+            "rp_id": "example.com",
+            "rp_name": "Example",
+            "origins": {
+                "**.example.com": True,
+                "auth.example.com": {"auth_host": True},
+            },
+            "remote": {"url": "http://remote.test", "token": "sekret", "cache_ttl": 30},
+        },
+        headers={
+            "Host": "localhost:4401",
+            "Cookie": f"{AUTH_COOKIE_NAME}={session_token}",
+        },
+    )
+    assert r.status_code == 200, r.text
+    stored = test_db.config.domains["example.com"]
+    assert stored.remote.url == "http://remote.test"
+    assert stored.remote.token == "sekret"
+
+    r = await client.get(
+        "/auth/api/admin/domains/",
+        headers={
+            "Host": "localhost:4401",
+            "Cookie": f"{AUTH_COOKIE_NAME}={session_token}",
+        },
+    )
+    entry = next(d for d in r.json() if d["rp_id"] == "example.com")
+    assert entry["remote"]["url"] == "http://remote.test"
+    assert "token" not in entry["remote"]  # write-only
+
+    headers = {"Host": "localhost:4401", "Cookie": f"{AUTH_COOKIE_NAME}={session_token}"}
+    origins = {"**.example.com": True, "auth.example.com": {"auth_host": True}}
+
+    # PATCH without the remote key preserves it (and its token)
+    r = await client.patch(
+        "/auth/api/admin/domains/example.com",
+        json={"rp_name": "Ex", "origins": origins},
+        headers=headers,
+    )
+    assert r.status_code == 200, r.text
+    assert stored.remote.url == "http://remote.test"
+    assert stored.remote.token == "sekret"
+
+    # PATCH with a new URL but no token keeps the stored token
+    r = await client.patch(
+        "/auth/api/admin/domains/example.com",
+        json={"rp_name": "Ex", "origins": origins,
+              "remote": {"url": "http://other.test", "cache_ttl": 30}},
+        headers=headers,
+    )
+    assert r.status_code == 200, r.text
+    assert stored.remote.url == "http://other.test"
+    assert stored.remote.token == "sekret"
+
+    # PATCH with remote: null clears it
+    r = await client.patch(
+        "/auth/api/admin/domains/example.com",
+        json={"rp_name": "Ex", "origins": origins, "remote": None},
+        headers=headers,
+    )
+    assert r.status_code == 200, r.text
+    assert stored.remote is None
+
+
+@pytest.mark.asyncio
+async def test_admin_remote_domain_requires_auth_host(client, session_token):
+    r = await client.post(
+        "/auth/api/admin/domains/",
+        json={
+            "rp_id": "example.com",
+            "origins": {"**.example.com": True},
+            "remote": {"url": "http://remote.test"},
+        },
+        headers={
+            "Host": "localhost:4401",
+            "Cookie": f"{AUTH_COOKIE_NAME}={session_token}",
+        },
+    )
+    assert r.status_code == 400
+    assert "auth host" in r.json()["detail"]
@@ -0,0 +1,51 @@
+"""Tests for startup box sign-in summaries (paskia/util/startupbox.py).
+
+Pruning must mirror the actual origin matching in sansio._allowlisted:
+wildcards cover https origins (any port) under their base, except under
+localhost where any scheme and any port match.
+"""
+
+from paskia.util.startupbox import _signin_summary
+
+
+def test_auth_host_pruned_under_full_wildcard():
+    """'**.vasanko.com' already covers auth.vasanko.com."""
+    keys = ["**.vasanko.com", "auth.vasanko.com"]
+    assert _signin_summary(keys, "vasanko.com") == "all subdomains"
+
+
+def test_http_origin_not_covered_by_https_wildcard():
+    """Plain http outside localhost is not wildcard-covered; stays listed."""
+    keys = ["**.example.com", "http://app.example.com"]
+    summary = _signin_summary(keys, "example.com")
+    assert summary == "all subdomains, http://app.example.com"
+
+
+def test_localhost_wildcard_covers_any_scheme_and_port():
+    keys = ["**.localhost", "http://localhost:3000", "localhost:8080"]
+    assert _signin_summary(keys, "localhost") == "all subdomains"
+
+
+def test_https_port_key_covered_by_wildcard():
+    """Wildcards match https origins at any port, so 'host:8443' is redundant."""
+    keys = ["**.example.com", "app.example.com:8443"]
+    assert _signin_summary(keys, "example.com") == "all subdomains"
+
+
+def test_single_level_wildcard_pruning():
+    """'*.example.com' covers one subdomain level only."""
+    keys = ["*.example.com", "app.example.com", "deep.app.example.com"]
+    summary = _signin_summary(keys, "example.com")
+    assert summary == "subdomains, deep.app.example.com"
+
+
+def test_no_wildcard_keeps_all_entries():
+    keys = ["auth.example.com", "app.example.com"]
+    summary = _signin_summary(keys, "example.com")
+    assert summary == "app.example.com, auth.example.com"
+
+
+def test_entries_outside_wildcard_base_kept():
+    keys = ["**.app.example.com", "auth.example.com"]
+    summary = _signin_summary(keys, "example.com")
+    assert summary == "all subdomains of app.example.com, auth.example.com"
Author	SHA1	Message	Date
LeoVasanko	2a04d7e0d3	Admin UI remote option; docs match simplified protocol Domain edit dialog: satellite-mode toggle with remote URL, write-only sync token, cache TTL and re-sync interval, with auth-host requirement validated before submit; domain list marks remote domains. AdminApp sends remote wholesale on PATCH (null clears, absent token keeps the stored one).	2026-09-21 01:14:00 +00:00
LeoVasanko	33e3185b39	Fix sync client resync condition (ready-tracked, not staging)	2026-09-21 01:07:47 +00:00
LeoVasanko	ea780a20e1	Host-keyed dispatch in the satellite module; snapshot-only sync Callers never see stores: session_ctx/verify/user-info resolve the store from the request host via satellite.store_for_host; session refresh and logout eviction are dispatch functions too (satellite.refresh_session / evict_session). API handlers keep one code path plus forward_request one-liners; proxy.py folds into satellite.py; Domain.store and the store parameters are gone; 503 comes from the dispatch point as a plain HTTPException. The sync protocol drops replay/generation/seq: snapshots are small, so every connect starts from a full snapshot and a single ordered WebSocket cannot gap; a slow subscriber is dropped and resyncs. The satellite reconnects every refresh_interval to reconcile drift.	2026-09-21 01:04:53 +00:00
LeoVasanko	2b21bfb98a	Docs: remote satellite configuration, behavior, and design review	2026-09-20 23:46:53 +00:00
LeoVasanko	44364fdffc	Fix replica-path leaks and availability semantics from live testing - _remote_headers and /check used struct convenience properties that read the global database; they now use the SessionContext / the handed store (also fixes Remote-Credential carrying a struct repr instead of the UUID). - Replica availability: TTL clock starts at disconnect, not at last message or failed reconnect; tight WS keepalive for prompt dead-peer detection. - Proxy preserves repeated Set-Cookie via raw headers; sync endpoint does its own accept (wsutil decorator pre-accepts) and bypasses host dispatch (server-to-server; satellite may use an out-of-domain address). - Admin-credential bootstrap warning skips remote domains. Verified live with two instances (remote :4501, satellite :4402): replica snapshot + events, 204 forward with Remote-* in <1ms, validate write-behind landing on the remote, proxied logout with instant local eviction, 503 after cache_ttl of disconnect, resync after remote restart.	2026-09-20 23:45:01 +00:00
LeoVasanko	9394c38179	Remote domain configuration via admin domains API ApiDomain carries the remote block (sync token write-only, never echoed); create/patch accept it, validated with the combined config (auth host mandatory for remote domains). db.update_domain replaces remote wholesale like the other domain fields.	2026-09-20 23:26:00 +00:00
LeoVasanko	5ecb10166d	Add remote domains: RAM replica + RAM-only sync channel DomainConfig.remote {url, token, cache_ttl, refresh_interval} marks a domain as backed by a remote paskia instance (auth host required). The remote publishes committed changes via struct store()/delete() hooks and explicit emits in field-mutating operations into syncfeed, an in-RAM sequenced ring buffer served over a token-gated WebSocket (/auth/api/sync/ws, tokens from PASKIA_SYNC_TOKENS env). The satellite keeps a plain DB replica per remote URL, applies snapshots/events, enforces expiry locally, and writes session refreshes back over the same channel. /validate refreshes locally with write-behind; /logout, /set-session, /token-info and /auth/oidc/* are proxied to the remote with the original Host header; logout also evicts from the replica. Replicas go fail-closed (503) after cache_ttl of silence.	2026-09-20 23:21:08 +00:00
LeoVasanko	20b145d816	Make session read path store-explicit DB.session_ctx now reads only its own tables instead of struct convenience properties that reach the global database, so a DB instance (a read replica) is self-contained. session_ctx/session_context/ authz.verify/build_user_info take an explicit store parameter defaulting to the local database; api.py endpoints resolve it from the dispatched domain (Domain.store).	2026-09-20 23:08:56 +00:00
LeoVasanko	b5733657f9	Fastapi-vue-setup 1.7.2 logging fixes.	2026-09-18 19:07:33 +00:00
LeoVasanko	4de164c457	Use fastapi-vue RuntimeConfig passing, simplifying code.	2026-09-18 19:00:13 +00:00
LeoVasanko	3e4f77ba93	Update fastapi-vue-setup 1.6.1 with major changes.	2026-09-18 03:22:54 +00:00
LeoVasanko	66c2a9bf07	release.py: print the publish command unindented, on its own line	2026-09-18 01:35:09 +00:00
LeoVasanko	c4360df110	Release 2.1.0	2026-09-18 01:32:45 +00:00
LeoVasanko	c676665795	Add release script with version bump, tagging and rollback	2026-09-18 01:32:09 +00:00
LeoVasanko	55dd43661c	Rewritten README.	2026-09-18 01:11:45 +00:00
LeoVasanko	753ce868c6	Examples: simplify profile demo to print the result code	2026-09-18 00:27:21 +00:00
LeoVasanko	3e0152e688	Profile iframe handles no-session internally with in-place login The restricted entry validates the session before rendering anything (no load-time flash): 401/403 switches to the existing login component in place of the profile, success renders the panel fully populated via props, other failures show a minimal card with Back only. The dialog drops the standalone page's heading and help text.	2026-09-18 00:27:21 +00:00
LeoVasanko	c5efa03908	profile(): resolve 'login' when login flow completes inside the dialog The overlay now tracks which dialog kind is open: auth-success from a profile dialog resolves 'login', auth-back only rejects AuthCancelledError for auth dialogs.	2026-09-18 00:27:21 +00:00
LeoVasanko	0ca4e07e23	Dev server: serve paskia-js module, rework examples page The Vite dev server now maps /paskia-js/ to the local paskia-js build (the examples page's module import has 404'd since it was introduced, leaving all buttons dead). Navigation actions on the examples page are now plain same-window links so the flows' back navigation returns to the page; added a Profile Summary button exercising profile().	2026-09-17 19:17:00 +00:00
LeoVasanko	baa993e586	Theme precedence: URL param, then localStorage, then browser default The restricted page's early script now honors the URL theme parameter before the cached profile theme, so a fresh server-provided override wins and the host color scheme applies without a flash. After session load, an empty profile theme clears the cache but keeps the URL parameter in effect instead of reverting to the system default.	2026-09-17 19:17:00 +00:00
LeoVasanko	42240dd2c7	Unify host profile view as framed dialog, add profile iframe mode HostProfileView now renders the same centered frame card as the login flows, whether shown full-page at /auth/ (host mode) or inside the new #mode=profile restricted iframe. The component self-fetches its data when the parent does not provide it, and emits back/logout so each context reacts appropriately: the full page reloads, the iframe posts auth-back / auth-logout to the host.	2026-09-17 19:17:00 +00:00
LeoVasanko	2ec709905e	paskia-js: profile() dialog, auth-logout message, host color-scheme adoption New profile() function opens the minimal profile in a compact dialog iframe and always resolves ('logout' \| 'back'), keeping the auth flow's resolve/reject contract separate and unchanged. The overlay now injects the host page's computed color-scheme into the iframe URL theme param when the server has not provided one.	2026-09-17 19:17:00 +00:00
LeoVasanko	6eb862278f	Add tests for startup box sign-in summary wildcard pruning	2026-09-10 19:57:37 +00:00
LeoVasanko	dbd697772a	Updated systemd unit in README for better messages.	2026-09-10 01:55:44 +00:00