diff --git a/docs/MultiSite.md b/docs/MultiSite.md new file mode 100644 index 0000000..1f8efb2 --- /dev/null +++ b/docs/MultiSite.md @@ -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 `.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//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=` +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:///.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..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@.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..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..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:///.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.)