ThothII/docs/install/authentication-local.md

Local authentication

Use local mode for a standalone PC or Mac. Configure it 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

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.