LeoVasanko/paskia
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Multi-site plan v4: combined paskia.kantadb, bootstrap-only CLI, runtime realm management

Browse Source
This commit is contained in:
LeoVasanko
2026-09-06 03:19:42 +00:00
parent 383c9f472e
commit 2da1ce777a
1 changed files with 741 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/MultiSite.md
+741
View File
@@ -0,0 +1,741 @@
# Multi-Site Support: Combined-Database Plan
Status: **draft v4 for review** — no code changes made. v4 folds in a
simplification round: Related Origin Requests are now assumed to have
**universal browser support** (Firefox included); there are **no existing
multi-database deployments** to migrate — the only legacy path is adopting
a lone `<rp-id>.paskiadb` into the new combined `paskia.kantadb` file; and
realm configuration is **bootstrap-only on the CLI** — rp-ids, rp-names,
origins and auth hosts are managed at runtime through the master-admin web
interface, so the serve command takes no realm arguments at all.
Goal: one paskia process on one port (4401) serves multiple sites with
**one combined database**. The _administrative instance_ is separated from
the _WebAuthn RP_: organizations and users are global across rp-ids;
rp-id becomes a first-class per-realm object; passkeys remain tied to
their rp-id (WebAuthn-enforced); sessions remain host-bound exactly as
today. Motivating case: `app1.company.com` and `app2.com` cannot share an
rp-id, but user management must be under single common controls.
Decisions already made (from review rounds):
- **One combined database** at a fixed CWD-relative path:
**`paskia.kantadb`** (a single kanta JSONL file). No `PASKIA_DB`, no
per-rp-id directories, no directory scanning. The `paskiadb`/`main.db`
names are retired (§10).
- **CLI is bootstrap-only**: `paskia init` seeds the database with the
initial realm(s); plain `paskia` opens `paskia.kantadb` and serves
whatever realms are stored. rp-id no longer selects which database to
open, which removes the whole class of CLI/runtime mixups.
- **Runtime realm management via the admin interface**: adding rp-ids,
changing rp-names, origins and auth hosts are master-admin operations
(§9), exactly like rp-name changes work today after first setup. The
admin interface is shared across the whole instance — as long as a
master admin can log in on some host, all further configuration happens
there.
- Cross-rp-id logins are **permitted** (§2 mechanisms); no separate
per-site user silos.
---
## 1. What is global vs. per-realm
**Global (single instance, shared across realms):**
| Data | Notes |
| ------------------------------- | ----------------------------------------------------------------------- |
| Organizations, Roles, Users | already global structs; unchanged |
| Permissions | `domain` field already host-scopes effectiveness (`structs.py:704-706`) |
| Sessions | already host-bound (`Session.host`, exact match `structs.py:678-682`) |
| Credentials/passkeys | global collection, each stamped with its `rp_id` (§4) |
| Reset tokens | user-bound; global |
| Avatars | `users/<uuid>/profile.webp` under the one user-files root (§10) |
| Auth codes, remote-auth manager | in-memory; gain rp-id fields (§7) |
**Per-realm (registry, keyed by rp-id):**
| Data | Notes |
| -------------------------------------- | --------------------------------------------------------------- |
| `rp_id`, `rp_name`, origins, auth_host | stored combined `Config` (§3) |
| `Passkey` instance | per rp-id; ceremonies verify against the _origin realm's_ rp-id |
| `site_url`/`site_path` | runtime derivation, per realm |
| OIDC provider (keys, clients) | per rp-id — each realm is an independent issuer (§8) |
Terminology: a **realm** is one rp-id with its associated hosts and
origins (the feedback's "authentication realm"). A **site** is any host
served by the instance; each host belongs to exactly one realm. The
_administrative instance_ is the whole process: global users/orgs, N
realms.
The key simplification: `db.data()` stays a plain global singleton. The
contextvar is needed only for the **current realm** (passkey, config,
OIDC view) — not for database access.
## 2. Login architecture: three composable mechanisms
The plan implements the realm infrastructure (§3-§9) once, plus three
mechanisms that share it. They are alternatives _per deployment_, and
composable within one instance.
### 2.A WebAuthn Related Origin Requests (preferred for trusted domain families)
WebAuthn Level 3 lets otherwise-unrelated domains share one rp-id: the
canonical RP publishes `/.well-known/webauthn` listing permitted origins,
and those origins may then run ceremonies with the common rp-id locally —
no redirects, no cross-domain cookies. Browser support is now universal
(Firefox included), so ROR needs no fallback mechanism for browser
reasons.
Model: realm `company.com` with related origin `https://app2.com`. A page
on `app2.com` calls WebAuthn with `rpId: "company.com"`; the passkey is
scoped to `company.com`; `clientDataJSON.origin` is `https://app2.com`,
which the backend validates against the realm's allow-list.
Server-side feasibility (verified against the installed `webauthn` 3.0.0):
paskia's `Passkey` passes `expected_origin=<the pre-validated origin>`
and `expected_rp_id=self.rp_id` (`sansio.py:188-193,255-263`); the
library string-compares origin and rp-id separately. The frontend never
chooses `rpId` client-side — ceremony options arrive from the server over
the WS (`frontend/src/utils/passkey.js:40,68`). So the change set is:
- `Passkey._validate_origin` (`sansio.py:95-106`) currently requires
origin == rp-id or subdomain. New rule: an origin is valid if it is in
the rp-id subtree **or explicitly listed in the realm's configured
origins**. Explicit listing becomes the trust boundary — exactly the
right semantics, since `allowed_origins` is already an allow-list.
(Today's semantics are subtree-AND-listed when a list exists; the new
subtree-OR-listed is additive-only, so existing configs keep passing.)
- **Remove the redundant inline origin gate** in `authenticate_and_login`
(`wschat.py:93-95` re-implements `hostname == rp_id or endswith`) — it
would reject related origins after `validate_origin` accepted them.
Dispatch already resolved the realm from the Origin; the endpoint-side
`validate_origin` is the single origin rule.
- New endpoint: `GET /.well-known/webauthn` on the canonical rp-id host,
serving `{"origins": ["https://app2.com", ...]}` from the realm's
configured non-subdomain origins.
- Dispatch resolution gains a rule: a Host matching a configured
related-origin hostname resolves to that origin's realm (exact match
only — `www.app2.com` does not follow `app2.com`; document this).
Deployment constraint (documented in §15): the **browser** fetches
`https://<rp-id>/.well-known/webauthn` from the canonical apex directly —
if paskia does not host the apex, the JSON must be published there
statically.
Constraints and warnings (from the WebAuthn WG, to be documented):
implementations must support at least **5 registrable origin labels** and
may cap more aggressively — this is for a small family of same-trust
domains, not hundreds of customer domains. Sharing an rp-id merges the
security boundary: a weakly protected marketing domain should not share
the realm of the admin application. Config validation enforces a
configurable cap (default 5) on related origins per realm.
**Re-enrollment note**: passkeys never move between rp-ids
(WebAuthn-enforced). A host family that first deploys separate realms
(2.B) and later consolidates to Related Origins re-enrolls: authenticate
against the old realm (or via 2.C), register a new credential under the
common rp-id, retire the old one. The UI's per-credential rp-id badge
(§9) makes this visible. No automated credential migration is provided or
needed.
### 2.B Multiple rp-id realms under one administrative instance (the base refactor)
For domains that should _not_ share an rp-id: rp-id is a first-class
object (realm), not an instance attribute. Users are global identities;
credentials carry `rp_id`:
```
Instance
├── Orgs / Roles / Users (global)
└── Realms
├── company.com (origins [...], credentials scoped by rp_id)
├── app2.com (origins [...], credentials scoped by rp_id)
└── customer.net (origins [...], credentials scoped by rp_id)
```
Alice can hold both a `company.com` and an `app2.com` passkey; sessions
stay host-only. This is the refactor described in §3-§9 and is worthwhile
**regardless of which login mechanism a deployment uses** — 2.A is
implemented as "a realm may declare extra origins", 2.C as "a realm may
be entered via remote authorization".
**Deferred idea from the feedback — an Identity layer above the
org-owned User** (`Identity → N org memberships + N credentials`). Not
part of this plan: the current `User → Role → Org` ownership
(`structs.py:198-286`) is deeply embedded (bootstrap, admin API,
permissions), and multi-site works without it. We do adopt the feedback's
architectural rule now: **authentication establishes identity, not
organization** — the requested hostname selects the org/permission
context after authentication (already true via `Permission.domain`
host-scoping and session host binding). A future Identity split should
preserve that rule.
### 2.C Remote authorization + opportunistic local enrollment (bootstrap/recovery path)
For a realm where the user has no credential, the existing remote-login
mechanism already provides a federation-style flow: unauthenticated device
requests, authenticated device permits, a short-lived **single-use opaque
exchange code** (60s `CookieCode`, `authcode.py`) is redeemed by the
requesting host, which sets its own host-only cookie. No shared cookies,
no reusable tokens in URLs — matching the feedback's
authorization-code-shaped recommendation; the two channels (WS pairing
code vs redirect with `state`) are UX variants over the same code
redemption primitive.
Changes under this plan:
- Cross-realm permits are **allowed** (§7.2): a device authenticated at
`company.com` may authorize a session for `app2.com`; the request's
realm is recorded and shown to the approver; the target host is
registry-validated.
- **Same-device redirect variant** (optional, closes open question from
v1): "logged in at the auth host, bounce to the app host with a code" —
reuse the same `CookieCode` machinery with a `redirect_uri`+`state`
parameter set, PKCE not needed server-to-self but `state` protects the
redirect leg. This is a small addition over §7.1, kept as an optional
follow-up.
- **Opportunistic local enrollment**: after a cross-realm remote login,
the UI offers "Add a passkey for faster login here". The mechanism
already exists — the remote flow's `register` action issues a
`device addition` reset token (`remote.py:325-333`) and registration
runs locally under the new realm's rp-id, stamping `Credential.rp_id`
(§4). This makes remote login primarily bootstrap/recovery, while
everyday authentication stays local.
### Policy summary (how deployments choose)
| Situation | Mechanism |
| -------------------------------------------------- | --------------------------------------------- |
| Few closely related, equally trusted brand domains | 2.A Related Origins — one passkey |
| Independent / customer / lower-trust domains | 2.B separate realms — passkey per realm |
| User lacks a credential for the current realm | 2.C remote authorization, then enroll locally |
## 3. Configuration model
### 3.1 Stored config (breaking change)
```python
class RealmConfig(msgspec.Struct, omit_defaults=True):
rp_id: str
rp_name: str | None = None
auth_host: str | None = None # this realm's dedicated auth host
origins: list[str] | None = None # subdomain origins AND related origins (§2.A)
class Config(msgspec.Struct, omit_defaults=True):
realms: list[RealmConfig] # at least one; first entry is the default realm
listen: list[str] | None = None # process-global
```
- Old top-level `rp_id/rp_name/auth_host/origins` fields removed; a kanta
migration converts existing databases (§10). Default constructors move
to the new shape everywhere: `structs.py:622` (DB.config factory),
`operations.py:40` (sentinel), `db/bootstrap.py:148`.
- "At least one realm" is not expressible in msgspec — enforce it in a
startup/validation check.
- First entry is the default realm, used only where a default is genuinely
needed (bootstrap reset-link URL, startup box ordering, master-admin
entry point) — never for dispatch.
- **Origin validation**: each configured origin is either in the rp-id
subtree (classic) or an explicit related origin (§2.A). Related origins
are counted and capped (default 5 registrable labels per realm) and
must not collide with another realm's rp-id/auth-host/related origins.
These rules are enforced **both at startup and at admin write time**
(§9) — startup-only checks are bypassable at runtime. Origins are never
_implicitly_ cross-domain.
### 3.2 CLI: bootstrap (`paskia init`) vs. serve (`paskia`)
The CLI is split so that realm options exist only at bootstrap time —
they can never mix with runtime configuration of an already-configured
instance:
- **`paskia init`** — creates `paskia.kantadb` in CWD and seeds it:
- `--rp-id`: repeatable/comma-separated, default `["localhost"]`;
normalized, deduped. Multiple values create multiple realms at once
(useful for devserver/e2e); the **first is the default realm**.
- `--rp-name`: single value, applies to the default realm. Its purpose
is that the very first admin registration ceremony already shows the
correct RP name; afterwards rp-names are edited via the admin
interface (§9), as are any additional realms' names.
- `--auth-host`, `--origin`: apply to the default realm; existing
normalization (`validate_auth_host`, `normalize_origin`,
`normalize_auth_host_and_origins`) reused. Further realms' hosts are
configured via the admin interface.
- `--listen`: stored into `Config.listen` (process-global).
- Runs the kanta bootstrap (admin user + registration reset link, link
URL from the default realm) and prints the link. Refuses to run if
`paskia.kantadb` already exists, or if an un-adopted legacy
`*.paskiadb` is present (§10 — serve must adopt it first).
- **`paskia`** — serve. Takes **no realm options**; only `--listen`
(per-run override of stored `Config.listen`, never persisted) and
dev/debug flags. Startup flow: legacy-adoption pre-flight (§10) → open
`paskia.kantadb` → validate the stored realm set cross-realm (rp-ids
distinct; auth hosts distinct from each other and from every rp-id;
related origins capped and collision-free) → build the realm registry
(§5) → serve. Missing database → startup error pointing at
`paskia init`.
- `--save` is removed: init always persists, serve has nothing to save,
and runtime edits go through the admin API which persists directly.
- `PASKIA_VITE_URL` site_url fallback applies to the localhost realm
only (devserver).
Nested rp-ids are allowed (longest-suffix dispatch determinism). Adding a
child rp-id moves **no data** — users are global; only new ceremonies
stamp the child rp-id.
### 3.3 Runtime accessors
- The realm registry is built in the FastAPI lifespan **after
`kanta.open()`**, from `db.data().config.realms` — realm data no longer
travels through `PASKIA_CONFIG` at all. Per-realm
`site_url`/`site_path` are computed at registry-build time by a shared
derivation function (same priority as today: auth_host > origins[0] >
PASKIA_VITE_URL > `http://localhost:port` > `https://rp-id`), using the
effective listen endpoints for the localhost fallback.
- `PASKIA_CONFIG` shrinks to process-global serve parameters (the
effective listen endpoints) so the derivation inside the server
process can resolve the localhost-port fallback. A welcome side effect:
`db/lifecycle.py:28-37` no longer needs `PASKIA_CONFIG` at import time
to locate the database — the path is fixed (§10).
- `update_runtime_config` → `update_realm_runtime(rp_id, realm_config)`:
ports the site_url/site_path recomputation (`runtime.py:44-75`),
persists the combined `Config`, refreshes the registry entry in place
(dispatch must see auth_host and related-origin changes immediately).
Realm creation/deletion (§9) add/remove registry entries the same way.
- `util/hostutil.py` helpers take a realm parameter (`is_root_mode`,
`dedicated_auth_host`, `api_url`, `auth_site_url`, `ui_base_path`,
`reset_link_url`). `reset_link_url` has two context classes: the
bootstrap callback (`db/bootstrap.py:37-43`, no request context) uses
the **default** realm's URL; the request-context call sites
(`fastapi/user.py:294`, `admin/users.py:125`) must use the **current
request realm's** URL — otherwise device-addition links mint
credentials under the wrong realm's rp-id.
- Dead code removed: `util/frontend.py`, `hostutil.reload_config`.
## 4. Credentials get an rp-id
- `Credential` (`structs.py:289-304`) gains `rp_id: str`, stamped at
registration from the ceremony's rp-id (`Passkey.reg_verify`,
`sansio.py:194-200`, and `Credential.create`, `structs.py:337-360`,
both gain the parameter). Field placement: `Credential` is not
`kw_only`, so the required field must precede the defaulted ones
(`structs.py:303-304`). With Related Origins the stamp is always the
_realm's canonical_ rp-id regardless of which origin the ceremony ran
on — the credential genuinely is a `company.com` passkey.
- **Backfill migration** (`migrate_v6`): existing credentials get the old
stored `config.rp_id` (read from the DB's own config during replay).
`Credential` has no `omit_defaults`, so the field self-normalizes; the
migration writes the _correct_ value.
- `authenticate_chat` (`wschat.py:50-57`): the raw_id scan is filtered by
`c.rp_id == ceremony rp-id` — prevents wrong error semantics and a
cross-realm oracle ("no credential" vs "verification failed" would leak
which rp-id a credential belongs to).
- `exclude_credentials` (registration, `ws.py:78`) and reauth
`allow_credentials` (`wschat.py:99-103`) are filtered by the ceremony's
rp-id — `User.credential_ids` becomes cross-realm once users are global.
- Cascades are uuid-keyed and unchanged; deleting a user removes their
passkeys across all realms (correct: users are global).
## 5. Dispatch and realm context
- New module `paskia/realms.py`: `Realm { runtime, passkey }` and a
registry keyed by rp-id, built in the lifespan from the stored combined
`Config` (§3.3) and refreshed on admin realm writes. No per-realm
Kanta/DB.
- Host resolution (`resolve(host)`): normalize
(`hostutil.normalize_host`, gaining trailing-dot stripping), then
exact rp-id → exact auth_host → **exact related-origin hostname** →
longest-suffix rp-id. Unknown → `None`. (Order safe because startup and
admin-write validation forbids collisions between these sets.)
- **Pure ASGI dispatch middleware**, outermost (registered after
`redirect_middleware`), handling `"http"` and `"websocket"` scopes.
Unknown Host → 421 Misdirected Request (WS: pre-accept rejection). Sets
the `current_realm` contextvar + `request.state.realm`.
- **WebSocket resolution follows the `Origin`, not the connection
`Host`**: in auth-host mode the login page is on the app host, the WS
connects to the auth host, and Origin names the host being logged into
(docs/API.md auth-host section). So:
1. middleware resolves the origin realm from the Origin hostname —
including related-origin hostnames (a ceremony on `app2.com` for
rp-id `company.com` resolves to the `company.com` realm);
2. the connection `Host` must be a valid WS endpoint for that realm:
the realm's _effective auth host_ (§6), or the origin host itself
when the realm has no auth host at all — else pre-accept reject;
3. `validate_origin` runs endpoint-side against the origin realm's
`Passkey` (post-accept JSON errors preserved, `wsutil.py:23,34-35`);
4. `current_realm` = origin realm for the WS handler's duration.
The ceremony rp-id is always the origin realm's rp-id — exactly what
the browser enforces for the page's origin under both classic and
related-origin rules.
- `paskia/globals.py` deleted; `from paskia.globals import passkey` →
`current_realm().passkey`; `db.data()` stays global.
## 6. Auth host: per-realm values with global fallback
A realm without its own auth host falls back to the first configured auth
host (realm-list order):
```
effective_auth_host(realm) = realm.auth_host or first_configured_auth_host or None
```
**Own vs. effective auth host must be distinguished everywhere** — this
was a review finding with real consequences. The split:
- **Follow the realm's OWN auth host**: UI mode detection
(`App.vue:43-49` minimal-profile decision), the redirect middleware
(`auth_host.py:39-53`), `ui_base_path`, and `reset_link_url`. A realm
with no own auth host keeps its full UI on its own hosts — otherwise
reset/registration pages on `app2.com` would redirect to
`auth.company.com`, where the ceremony's Origin resolves the _owner_
realm and stamps the wrong `Credential.rp_id`, breaking 2.B onboarding
and 2.C local enrollment.
- **Follow the EFFECTIVE auth host**: WS endpoint selection only
(`passkey.js:8-12` builds the WS URL from settings). The fallback auth
host serves WS + restricted APIs for foreign realms.
- Settings (`ApiSettings`) exposes both fields (add `own_auth_host`
alongside the effective `auth_host`) so the frontend can make the mode
decision correctly.
- Root mode (`site_path == "/"`) applies only on a realm's _own_ auth
host, so it is never ambiguous: a realm's UI lives on its own hosts;
the fallback auth host serves the _owner_ realm's UI plus WS for the
rest.
- Admin changes to auth_host re-validate cross-realm uniqueness against
the live registry (§9).
## 7. Login flows and in-memory stores
### 7.1 Auth codes (`authcode.py:45-113`)
- `OIDCCode` and `CookieCode` gain `rp_id`, verified at redemption
(`oid.py:184`, `api.py:407`) — defense in depth; cheap.
- **Stamping source matters** (review blocker): codes are stamped with
the realm of the session they will redeem — not naively with the
current realm at issuance. Remote-completion codes are minted inside
the _permit_ handler (`remote.py:336-341`, permitting realm's context)
but redeemed by the _requesting_ device on its own host, so they are
stamped with `RemoteAuthRequest.rp_id` (§7.2) — stamping them with the
permitter's realm would break every cross-realm remote login.
Registration-flow codes (`ws.py:97`) and OIDC codes (`ws.py:233-241`)
stamp from the current realm (issue and redeem sides always match).
The host re-check at `api.py:414-416` already binds `CookieCode`
independently; the rp_id check is additive.
- Future stores (e.g. docs/AuthTickets.md's `AuthTicket`) inherit the
rp_id field.
### 7.2 Remote authentication — cross-realm permits allowed
- `RemoteAuthRequest` (`remoteauth.py:33-58`) gains `rp_id` — the
requesting device's origin realm (resolved at `remote.py:48-49,93-98`).
- **Permit side may differ from the request side** (this is mechanism
2.C): the permitting device authenticates with _its_ realm's passkey,
and the existing `session_host=request.host` override
(`remote.py:315-321`) creates the session for the requesting host.
Changes required:
- the `session_host` override must resolve to a **configured realm**
(registry check) — today it is only non-empty-checked
(`wschat.py:108-114`); arbitrary-host session binding is refused;
- the request's rp-id is shown to the permitting user ("device at
app2.com requests login");
- the login transaction logs both the session host and the permitting
host/credential.
- No policy flag for now: cross-realm remote login is how the product
works (users are global). A future per-realm policy field can add
isolation.
- Exchange codes stay single-use, 60s, host-bound at redemption
(`api.py:407-416` re-checks `session_ctx(secret, host)`).
### 7.3 Same-device redirect variant (optional follow-up)
"Logged in at auth host → bounce to app host with a code": reuse
`CookieCode` with `redirect_uri` + `state`; redeem at the target host's
`/auth/api/set-session` as today. Small addition; optional.
## 8. OIDC: per-realm providers in one DB
- `DB.oidc: OIDC` becomes `dict[str, OIDC]` keyed by rp-id (migration
wraps the existing struct under the old rp-id). Each realm is an
independent provider: own signing key, own clients.
- `util/oidjwt.py` key cache (`:22-24`) keyed by rp-id; keys remain
stored per realm in the DB (`structs.py:599-601`).
- Issuer stays per-request-Host (`oid.py:64-68`, discovery at
`mainapp.py:89-124`) — each realm host is an issuer alias sharing the
realm's key. **`Session` gains two fields** (both `omit_defaults`,
migration-free): `issuer: str | None` — stamped from the WS **Origin**
(scheme included, `ws.py:207-209`) at OIDC-session creation
(`ws.py:217-226`) and re-stamped at refresh (`oid.py:251-316`;
stamping from the WS _connection_ Host would be wrong — that is the
effective auth host, not the authorize/discovery host the RP
validates against); and `rp_id: str | None` — the owning realm, needed
by every path that runs **without request context**:
- backchannel logout (`oidc_notify.py:24-27` issuer, `:44` client
lookup, `:91-101` signing) uses `session.rp_id` to select the
realm's key and `session.issuer` as `iss`;
- `cleanup_expired` (`lifecycle.py:149-151`) drives the above with no
request; pre-upgrade sessions (`rp_id=None`) fall back to registry
issuer→realm resolution, then the default realm;
- the logfmt UUID→label lookup (`lifecycle.py:84-93`) iterates all
realms' client dicts;
- session listings (`apistructs.py:120` `client_name`) resolve the
client under the session's own realm, not the request's.
- **Log censoring must follow the new shape (security)**: the transaction
log censor (`lifecycle.py:108-109`) matches only `oidc.key` /
`.endswith(".oidc.key")`; the new path is `oidc.<rp-id>.key` — without
a segment/regex-based rule, realm signing keys would print in plaintext
in the JSONL log and in the `migrate:v7` diff. Also harden
`_lookup_uuid_in_state` (`lifecycle.py:55`) for the nested clients.
- Admin OIDC-client CRUD operates on the current realm's `OIDC` entry.
- `_validate_permission_domain` (`admin/permissions.py:18-36`) accepts a
subdomain of **any** configured rp-id, any related-origin hostname, or
any realm's client UUID.
- `domain == client UUID` permission grouping (`oid.py:341,441`) looks up
the current realm's clients (OIDC sessions are always created under the
origin realm).
## 9. API and frontend changes
- `GET /auth/api/settings` (`api.py:301-316`): per-request-Host realm
values (rp_id, rp_name, effective auth_host, site URLs). Schema
unchanged.
- **Realm management (master admin only)** — this is how new rp-ids are
added after bootstrap, mirroring how rp-name is already edited post
setup (`admin/server_config.py:18-78` becomes per-realm):
- New endpoints, e.g. `GET/POST /auth/api/admin/realms` and
`PATCH/DELETE /auth/api/admin/realms/{rp_id}`, gated on the
`auth:admin` scope. The admin UI gains a realm list/editor.
- Create: `rp_id` + optional `rp_name` (defaults to the rp-id),
`auth_host`, `origins`; full §3.1 validation (cap, cross-realm
collisions); registry entry added immediately (§3.3), including its
`Passkey` instance and OIDC provider entry (§8).
- Update: same validation against the live registry; changing a
realm's rp-id itself is **not supported** (it would orphan every
credential stamped with the old rp-id) — delete and recreate
instead.
- Delete: refused for the last remaining realm and while any
credential carries the realm's rp-id (re-enroll or delete those
credentials first); cascades nothing else (users/orgs are global).
- The client-side subdomain check in `AdminDialogs.vue:70-79` must
relax to accept configured related origins.
(`AdminDialogs.vue:96`'s rp-id connectivity probe keeps working: a
related origin answers with the realm's rp_id.)
- Credential listings: `Credential.rp_id` serializes automatically into
`ApiUserDetail.credentials` (both `GET /auth/api/user-info` and
`GET /auth/api/admin/users/{uuid}` return the raw struct).
- Frontend `CredentialList.vue` (shared by ProfileView and
AdminUserDetail): rp-id badge **only when
`credential.rp_id !== settings.rp_id`** — single-realm installs see no
change; even multi-realm installs only mark foreign passkeys. The
frontend already knows its rp-id (`stores/auth.js`) and already
compares rp-ids elsewhere (`AdminDialogs.vue:95-96`).
- **Enrollment prompt (2.C)**: after a cross-realm remote login, the
profile view offers "Add a passkey for faster login here" (mechanism
exists; UI wiring only).
- Bootstrap/reset links use the default realm's URL
(`db/bootstrap.py:37-43`, `paskia/bootstrap.py:40-89`).
- **Bootstrap caveat to handle**: `check_admin_credentials`
(`bootstrap.py:40-89`) prints a registration link when the first admin
"has no credentials" (`bootstrap.py:73` checks _any_ credential). With
global users, an admin may have passkeys only under _another_ realm's
rp-id — the check must test for an admin credential **under the default
realm's rp-id**, or the printed link is unusable.
- Cosmetic: `admin/users.py:115` picks "user registration" vs "account
recovery" token labels from _any_ credential existing; under global
users this can mislabel (e.g. "recovery" for a user who only lacks a
passkey in this realm). `token_type` is display-only (no gating:
`api.py:369`, `structs.py:469`) — adjust the wording logic, no
security impact.
## 10. Database path, adoption, and migrations
- Fixed CWD-relative path: **`paskia.kantadb`** — a single kanta JSONL
file. Kanta rotation siblings (`paskia@<timestamp>.kantadb`) are
unaffected. `PASKIA_DB` removed with no replacement;
`db/paths.py:8-47` drops the rp-id parameter and the root-directory
logic. CWD selects the deployment as needed.
- **User files** (avatars, `util/avatar.py:20`) move to a fixed sibling
directory **`paskia.data/users/`** (the old `users/` lived under the
per-rp-id directory; the name `paskia.data` is a proposal, see §16).
- **Legacy adoption** (the only supported migration — no multi-database
merging exists or is needed): if `paskia.kantadb` is absent and exactly
one `*.paskiadb` candidate exists in CWD — a directory containing
`main.db`, or a legacy single-file database (`db/paths.py:39-47`'s
`_migrate_legacy_db_file` case) — it is adopted: `main.db` (or the
single file) becomes `paskia.kantadb`, `users/` becomes
`paskia.data/users/`, and the old directory is removed. Multiple
candidates → startup error listing them, asking the operator to remove
or rename strays (e.g. a `*.bak.paskiadb` backup); empty directories
are ignored. Adoption runs as an explicit pre-flight step in the serve
command, **before** the read-only startup open — read-only opens never
trigger adoption or migration writes (verified against kanta: read-only
opens replay migrations in memory before decode and skip all writes,
and old Config shapes decode because `migrate_v7` runs pre-decode).
- Kanta migrations (`db/migrations.py`, name-scanned `migrate_vN`):
- `migrate_v6`: `Credential.rp_id` backfill from old `config.rp_id`.
- `migrate_v7`: `Config` restructure (old fields → `realms[0]`); wrap
`oidc` under the old rp-id key.
- `kanta.ctx.rp_id` is **kept** (set to the default realm) — `migrate_v2`
(`migrations.py:24`) still reads it when replaying v1-era databases;
only its role as "the" rp-id ends. Alternatively harden v2 to tolerate
a missing ctx; keeping the wiring is cheaper.
- The startup box prints per-realm lines (`util/startupbox.py`).
## 11. Lifespan and background tasks
- One `Kanta` for `paskia.kantadb`, constructed at import time from the
fixed path (no `PASKIA_CONFIG` dependency in `db/lifecycle.py`), opened
once in the lifespan; single bootstrap hook; one background cleanup
task (`db/background.py`) — unchanged in shape (DB is global).
- The kanta bootstrap hook only ever fires for a database created by
`paskia init` (which supplies the initial combined `Config`); the serve
command never bootstraps — a missing database is a startup error
pointing at `paskia init` (§3.2).
- Registry built from the stored `Config` after open; per-realm `Passkey`
instances constructed (each realm's origins validated at startup —
fail-fast preserved, now including related-origin cap checks).
- `bootstrap_if_needed` / `check_admin_credentials` still run at serve
startup (reprint a usable registration link when the admin lacks a
credential under the default realm, §9).
- `oidc_notify` fire-and-forget tasks need no realm context for DB access
(global DB); issuer comes from the session (§8).
- The dispatch middleware is the only place `current_realm` is set; admin
realm writes refresh the registry (§3.3, §9).
## 12. Devserver (`scripts/devserver.py`)
- Extract init-argument parsing into an importable function (e.g.
`paskia/cliconfig.py`); `paskia init` and `devserver.py` share it — no
duplicated logic.
- devserver `--rp-id`/`--auth-host` become multi-value identically
(append + comma-split) and are passed to the init step; forwarding
(`devserver.py:146-156`) loops over the initialized realms.
- Caddy dev origins (`devserver.py:167-183`): iterate all rp-ids and all
effective auth hosts (`build_caddyfile` already takes a list); the dev
Caddyfile also forwards `/.well-known/webauthn`.
- `PASKIA_AUTH_HOST` (consumed by `frontend/vite.config.js:10`) becomes
comma-joined; vite config reads the first — dev-only, keep simple.
## 13. Security model
- **Dispatch**: unknown Host → 421 before any router/DB access (breaking
change vs today: direct-IP and unconfigured-name access stop working;
trailing dots normalized).
- **Related Origins boundary**: cross-domain origins are valid only when
explicitly configured and capped; the well-known document is served
only for the canonical realm and only lists configured origins.
Document the WG's trust warning: all origins sharing an rp-id share one
security boundary — do not mix trust levels within a realm.
- **Realm administration**: realm create/update/delete is gated on
`auth:admin` (§9) — deployment-wide by design; validation runs on every
write, not just at startup.
- **Passkeys**: rp-id binding browser-enforced and now server-recorded;
ceremonies, credential scans, exclude/allow lists all scoped to the
origin realm's rp-id. No cross-realm oracle in the scan.
- **Sessions**: unchanged — host-bound, exact match. Cross-realm sessions
arise only via (a) a ceremony at the origin realm (incl. related
origins), or (b) a remote permit by a device holding a valid session at
its own realm (§7.2), with registry-validated target host.
- **Users/orgs global**: deleting a user/org cascades across all realms —
intended. `auth:admin` is deployment-wide (document prominently).
Permission `domain` host-scoping unchanged.
- **Cross-realm permit transparency**: requesting realm/host shown to the
approver; both sides logged.
- **Secret hygiene in logs**: the OIDC signing-key censoring follows the
new `oidc.<rp-id>.key` path shape (§8) — without it, realm keys leak
into the JSONL transaction log.
- **OIDC**: per-realm keys/issuers; logout tokens carry the stored
issuer.
## 14. Tests
- `tests/conftest.py`: the import-time `PASKIA_CONFIG` seed
(`conftest.py:30-40`) goes away with the fixed DB path — the app-level
Kanta and the test fixtures chdir to / open a temp directory so
`paskia.kantadb` lands there. Realm config is seeded into the DB
fixture (a two-realm config: `localhost` + `test.example.com`);
`passkey_instance` becomes a registry/current-realm fixture.
`Credential.create` call sites (`conftest.py:189-195,203-210`,
`tests/test_admin.py:95,149`) gain the `rp_id` argument.
- New tests:
- CLI: `paskia init` seeds one/multiple realms; init refuses on an
existing database; serve without a database errors; legacy adoption
(single dir, single file, multiple candidates → error, empty dir
ignored); `--save` gone.
- Admin realm management: create/validate (collisions, related-origin
cap)/update/delete rules (last realm, credential-bearing realm);
registry refresh visible to dispatch without restart.
- dispatch: 421 unknown host; trailing-dot; related-origin hostname →
owning realm (exact only — `www.` variants 421); WS origin-realm
resolution; WS to auth host with app-host Origin accepted; arbitrary
Host/Origin combos rejected.
- credentials: rp_id stamping (incl. ceremony on a related origin →
canonical rp-id); backfill migration; scan/exclude/allow filtering;
no cross-realm oracle.
- **Related Origins server-side (pytest only)**: origin-validation
rules (subtree-OR-listed), `/.well-known/webauthn` contents and
absence-when-unconfigured. **Not e2e**: a genuine related origin
needs a non-subdomain host over HTTPS, and the browser fetches the
well-known document from the browser process itself — not
interceptable in the current plain-HTTP harness
(`playwright.config.js:27`). E2E for ROR requires deliberate TLS/DNS
infra; skip unless that is built.
- cross-realm remote login end-to-end (request at realm B, permit at
realm A, session valid only on B's host); exchange codes minted in
the permit path redeem on the requester's realm (§7.1); arbitrary
`session_host` refused.
- bootstrap caveat: admin with only foreign-realm credentials still
gets a usable registration link for the default realm.
- OIDC: per-realm keys/issuers; issuer stamped from WS Origin (not the
connection Host); refresh re-stamps; backchannel logout selects the
session realm's key with no request context; log censoring covers
`oidc.<rp-id>.key`.
- E2E: `global-setup.ts` drops `PASKIA_DB`, spawns `paskia init --rp-id
localhost,test.localhost` with `cwd` in the tmp dir, then serves; add a
`http://test.localhost:4404` project exercising dispatch and a
cross-realm remote login (remote auth currently has no e2e coverage;
this feature needs it).
## 15. Docs and compatibility
- README: multi-realm model, `paskia init` bootstrap, combined DB at
`paskia.kantadb`, `PASKIA_DB` removal, Related Origins setup.
- docs/API.md: auth-host section rewritten for own-vs-effective fallback
semantics and cross-realm behavior; `/.well-known/webauthn` documented;
realm-management admin endpoints documented.
- **Related Origins deployment guidance** (the critical operational
bit): the browser fetches `https://<rp-id>/.well-known/webauthn` from
the canonical apex directly. If paskia hosts the apex, our endpoint
serves it; if the apex is hosted elsewhere (typical for marketing
domains), the JSON must be published there statically. Existing
examples serve `/.well-known/*` statically (`docs/proxy/caddy.md`,
`caddy/Caddyfile:10-14`) — they must not shadow paskia's endpoint when
paskia does host it.
- docs/proxy + `caddy/auth/setup`: forward
`/.well-known/openid-configuration` **and** `/.well-known/webauthn`;
the vite dev proxy allowlist (`frontend/vite.config.js:16-24`) gains
both paths; Host preservation requirement unchanged.
- `oidc.md` (root): updated for per-realm providers and `Session.issuer`.
- Breaking changes: DB moved to `paskia.kantadb` (auto-adopted from a
lone legacy `*.paskiadb`; `PASKIA_DB` removed), serve command drops all
realm options and `--save` (use `paskia init` / the admin interface),
`PASKIA_CONFIG` format reduced to serve parameters,
`Config`/`DB.oidc`/`Credential` schema migrations, `paskia/globals.py`
removed, unknown Host → 421, `paskia.util.frontend` removed.
## 16. Open questions
1. Same-device redirect flow (§7.3): include in this release or defer?
2. User-files directory name: `paskia.data/` (proposed) vs something
else; it holds only avatars today.
3. Bare `paskia` with no database: proposed behavior is a startup error
pointing at `paskia init`. Alternative: keep today's zero-config dev
experience by auto-initializing a `localhost` realm. Strictness avoids
bootstrap/runtime mixups; auto-init is friendlier for first contact.
(Settled during review, for the record: fallback-auth-host UI semantics —
a realm's UI lives on its own hosts, the fallback auth host serves WS and
restricted APIs for foreign realms plus the owner realm's UI; settings
exposes own vs. effective auth host, §6. OIDC logout signing without
request context — `Session.rp_id` + `Session.issuer` fields, §8. Related
Origins e2e — pytest only, §14. Realm configuration after bootstrap —
admin interface only, serve takes no realm options, §3.2. Combined DB
name and location — `paskia.kantadb` in CWD, §10.)