docs(auth): document local OIDC and Authentik operation

docs/architecture/authentication.md

@@ -0,0 +1,55 @@
+# 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.
+
+## Configuration and trust boundaries
+
+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
+read from the mounted secret bundle and are never placed in YAML, command arguments, logs, JSON
+diagnostics, or browser storage.
+
+Local users have Argon2id password hashes, stable IDs, enabled state, roles, and `authRevision`.
+The stable roles are `user` and `admin`; `admin` inherits `user` and adds installation, session,
+Pi, workspace, secret-management, and diagnostic permissions.
+
+OIDC is provider-neutral at the browser protocol boundary. Authorization Code + PKCE, issuer,
+signature, audience, expiry, state, and nonce are validated before a principal is created.
+Authentik is the first certified group-catalog adapter, not a special browser login mode.
+
+## Group authorization
+
+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 with
+`oidc_groups_claim_invalid`. Exact configured external group names map to Thoth roles and then to
+permissions. A user with no mapped group is authenticated but receives no role and gets `403` from
+protected routes. Unmapped upstream groups are ignored silently, without an error or warning.
+
+Every configured mapping is checked by the configured group-catalog adapter. Authentik checks the
+exact group name and reports `oidc_mapped_group_missing` when it cannot find it. The dedicated
+Authentik API service account has group-view-only privilege; it is separate from the OIDC client.
+
+## Browser sessions
+
+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
+Storage.
+
+- Ordinary local sessions: 2-hour idle and 12-hour absolute expiry; closing the browser removes
+  the non-persistent cookie.
+- **Remember me** local sessions: 7-day idle and 30-day absolute expiry; they survive browser and
+  ThothII restarts.
+- OIDC sessions: at most 8 hours and never beyond the validated ID-token expiry.
+
+Local password, role, enabled-state, and logout-all changes increment `authRevision` and invalidate
+affected sessions. Authentication configuration revision changes invalidate all sessions after
+reload. Logout deletes the server record. Backup restore excludes active sessions and OIDC state,
+recreates empty private auth-state directories, and therefore forces reauthentication.
+
+See the [local guide](../install/authentication-local.md), [generic OIDC guide](../install/authentication-oidc.md),
+and [Authentik guide](../install/authentik.md) for operator procedures.

docs/architecture/overview.md

@@ -4,6 +4,9 @@
 
 ThothII è un **datamart builder human-in-the-loop**: trasforma una domanda in linguaggio naturale in SQL validato (ed eventualmente un datamart dbt) attraverso un **workflow deterministico a 8 fasi NL→SQL**, in cui il modello *propone* e un revisore umano *decide* ai gate.
 
+L'autenticazione di produzione usa local oppure OIDC generico; il solo CLI operatore è tht.
+Per sessioni, ruoli, gruppi, diagnostica e ripristino vedere la [documentazione autenticazione](authentication.md).
+
 ## I tre progetti indipendenti
 
 ```