# 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](shell-and-language.md), 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:

```sh
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:

~~~yaml
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

```sh
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.