# 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.