docs: document full and embedded rendering with server authentication

docs/architecture/authentication.md

@@ -1,18 +1,27 @@
 # Authentication architecture
 
-ThothII has two production authentication modes: `local` and generic `oidc`. The host operator
-surface is one CLI, `tht`; there is no separate authentication executable. The backend owns
-opaque browser sessions and authorization, while `tht` owns protected configuration and local-user
-files.
+ThothII supports `local` and generic `oidc` through protected `auth.yaml`, plus
+the trusted-proxy `upstream` path used by Omics. The host operator surface is
+one CLI, `tht`; there is no separate authentication executable. The backend owns
+authorization in all paths and opaque browser sessions only in local/OIDC.
+`tht` owns protected local/OIDC configuration and local-user files; upstream
+identity is supplied per request by the authenticated server proxy.
+
+Presentation is separate: [full/embedded rendering](application-shell.md) does
+not select authentication. The Mac uses full/local; Omics uses embedded/upstream;
+a standalone server can use full/OIDC. Do not configure a second ThothII OIDC
+login simply because Omics itself authenticates users through Authentik.
 
 ```mermaid
 flowchart TB
     BROWSER["Browser"] --> BOUNDARY["Authentication boundary"]
     BOUNDARY --> LOCAL["Local users\nArgon2id hashes"]
     BOUNDARY --> OIDC["OIDC provider\nAuthorization Code PKCE"]
+    BOUNDARY --> UPSTREAM["Trusted proxy\nVerified portal session"]
     OIDC --> GROUPS["Groups claim\nexact mapping"]
     LOCAL --> PRINCIPAL["Thoth principal"]
     GROUPS --> PRINCIPAL
+    UPSTREAM --> PRINCIPAL
     PRINCIPAL --> ROLES["Roles"]
     ROLES --> PERMISSIONS["Permissions"]
     PERMISSIONS --> ROUTES["Protected routes"]
@@ -21,6 +30,13 @@ flowchart TB
 
 ## Configuration and trust boundaries
 
+The following protected-file configuration applies to local/OIDC. Upstream uses
+`AUTH_MODE=upstream` without a mounted `auth.yaml` or authentication runtime
+projection. The backend refuses both authorities together. `AUTH_MODE=none`
+and `mock` are development/test modes, not production fallbacks. The exact
+upstream setup, header contract, proxy hops and origin checks are in the
+[server integration guide](../install/authentication-upstream.md).
+
 The installation descriptor points to an operator-controlled authentication directory. It contains
 non-secret `auth.yaml` and, for local mode, `users.yaml`. POSIX installations use a private
 directory and owner-only regular files; Windows uses equivalent owner-only ACLs. Secret values are
@@ -49,6 +65,10 @@ Authentik is the first certified group-catalog adapter, not a special browser lo
 
 ## Group authorization
 
+This section describes **ThothII's direct OIDC login**, not the embedded Omics
+path. Omics checks its own capability and administrator status and supplies
+normalized identity headers; ThothII does not repeat the OIDC groups exchange.
+
 OIDC must return a direct, non-empty `groups` claim whose value is a JSON array of strings.
 Missing, malformed, indirect, or overage-style claims fail closed. The browser callback returns
 HTTP 401 with the generic code `oidc_callback_failed`; it does not expose the internal reason.
@@ -100,6 +120,10 @@ prerequisite fails.
 
 ## Browser sessions
 
+This section applies only to **local and direct OIDC**. Upstream reuses the
+portal's authenticated session at the proxy boundary, not a ThothII cookie;
+its `/me` response has `session: null` and `csrfToken: null`.
+
 The browser receives only an opaque `HttpOnly`, `SameSite=Lax` cookie named `thothii_session`.
 State-changing cookie requests require the in-memory CSRF token, same-origin `Origin`, and Fetch
 Metadata checks when present. The frontend never stores bearer tokens or session secrets in Web
@@ -116,5 +140,20 @@ affected sessions. Authentication configuration revision changes invalidate all
 reload. Logout deletes the server record. Backup restore excludes active sessions and OIDC state,
 recreates empty private auth-state directories, and therefore forces reauthentication.
 
+Full local/OIDC logout calls `POST /auth/logout`, revokes the server session and
+clears its cookie. It does not call the identity provider's global logout. If the
+provider still has an SSO session, the next OIDC login can complete without
+another password prompt. Embedded has no ThothII logout control: use the portal.
+
+## Access revalidation
+
+The frontend treats `/me` as the access authority. In embedded it does not fetch
+`/auth/config` or offer local/OIDC login. On focus, pageshow, visibility return
+and event-stream reconnection it rechecks access. A 401/403 from this probe clears
+protected state; a 403 on one operation is not automatically an app-wide logout.
+Neither the DOM adapter nor the proxy's initial SSE check guarantees instantaneous
+revocation of streams already open in other tabs.
+
 See the [local guide](../install/authentication-local.md), [generic OIDC guide](../install/authentication-oidc.md),
-and [Authentik guide](../install/authentik.md) for operator procedures.
+[Authentik guide](../install/authentik.md), [upstream integration](../install/authentication-upstream.md),
+and [manual acceptance matrix](../testing/authentication-manual-acceptance.md).