ThothII/docs/install/authentication-local.md

Local authentication

Use local mode for a standalone PC or Mac, with shell.mode: full and shell.defaultLocale: en in the installation descriptor. Presentation and authentication are independent: selecting full does not create accounts. Omics embedded instead uses the upstream guide, not local users.

Configure local authentication through tht; passwords are entered at an echo-free prompt or read from a protected --password-file, never from a command argument.

Bootstrap

After the installation descriptor and protected secret bundle exist, configure the first enabled administrator:

tht --installation /absolute/path/thothii-installation.yaml auth configure \
  --mode local --public-url http://127.0.0.1:8080 \
  --admin-user <operator-user> --admin-display-name <display-name> \
  --password-file /absolute/path/protected-password-file

The password file is temporary operator input: keep it private and remove it after configuration. The resulting users.yaml contains Argon2id hashes, never plaintext passwords. To use prompts, omit the admin and password options in an interactive terminal. tht setup performs the same bootstrap before it starts the stack.

The non-secret local auth.yaml has this exact shape:

version: 1
mode: local
publicUrl: http://127.0.0.1:8080
session:
  regularTtlSeconds: 43200
  regularIdleSeconds: 7200
  rememberTtlSeconds: 2592000
  rememberIdleSeconds: 604800
  oidcTtlSeconds: 28800
local:
  usersFile: users.yaml

User administration

tht auth user list [--json]
tht auth user add <username> --role user|admin [--display-name <name>] [--password-file <file>]
tht auth user set-password <username> [--password-file <file>]
tht auth user enable <username>
tht auth user disable <username>
tht auth user grant <username> --role user|admin
tht auth user revoke <username> --role user|admin
tht auth user logout-all <username> --yes

User commands are unavailable in OIDC mode. The last enabled administrator cannot be disabled or demoted. Every password, role, enabled-state, and logout-all change increments the user’s authRevision, invalidating its sessions. tht auth status --json is redacted and suitable for machine use; JSON output is pristine on stdout.

Session behavior and recovery

Full shows its own login form and, after login, the verified display name in its header. The name menu contains Log out. This sends a CSRF-protected request to /api/auth/logout, revokes the session and returns to login. Language/theme preferences may remain in the browser; they are not credentials.

An ordinary login expires after 2 hours idle or 12 hours absolute. Selecting Remember me makes the cookie persistent and changes the limits to 7 days idle or 30 days absolute. Remembered sessions survive a browser and backend restart, but not a user revision change, configuration revision change, logout, or restore. Restore does not include sessions or OIDC state and requires every user to authenticate again.

If access is lost, use tht auth user set-password, enable, role changes, or logout-all as appropriate, then log in again. Do not copy passwords, hashes, cookies, CSRF values, or secret values into tickets, logs, or evidence.

Check readiness with tht auth check; add --json for the machine contract. Use tht doctor --json for the aggregate installation report.

Projected server installations

This section applies only when a Linux profile: server descriptor declares a runtime projection. The canonical authentication root stays root-owned and is the only authority. The container reads only the separate read-only runtime projection selected by CURRENT; it never falls back to the canonical files or to a previous generation. Run projected mutations and repairs through the root-operated tht commands, and never edit runtime files directly.

Mac, Windows, and local direct-file authentication remain unchanged when the projection is absent.