# Users, roles & security

Authentication uses cookie sessions and is off by default. Enable it with gateway \[auth\].enabled = true in server.toml, then configure each project's sources, bindings, and roles in project.toml. A project auth block alone does not enable enforcement.

## Gateway admin auth.

```toml
# config/server.toml
[auth]
enabled = true
session_ttl_secs = 86400       # 24h (default)
cookie_name = "thermite_session"
cookie_secure = false          # set true behind TLS

[[auth.users]]
username = "admin"
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$…$…"
roles = ["admin"]
```

With authentication enabled, gateway public routes are `/login`, `/logout`, `GET /api/status` (health probes), `GET /api/license/status`, `GET /favicon.ico`, `/hmi/thermite.js` and `/hmi/thermite.css` when HMI serving is enabled; also GET / and GET /portal/logo when the portal is enabled. Public GET branding assets are /admin/logo and /admin/assets/ followed by base.css, theme.css, roboto.ttf, or roboto-mono.ttf. On a project mount: `/login`, `/logout`, `/healthz`, and `/branding/*`, /hmi/thermite.js, and /hmi/thermite.css. A project's `/api/status` and screens require a session. Projects can *explicitly* permit restricted anonymous access.

## Generate password hashes with thermite-passwd.

Passwords are argon2id hashes with per-user random salts. The bundled `thermite-passwd` binary reads the password from stdin — it refuses arguments, so the secret never has to appear on a command line. Use the interactive prompt for credentials, then store the resulting hash in the user configuration.

```sh
# interactive — prompts without echoing
$ thermite-passwd

# output: paste the generated hash into password_hash
$argon2id$v=19$m=19456,t=2,p=1$…$…
```

Paste the output into a `password_hash` field — in `[[auth.users]]` or a project's `users.toml`.

## Project users, bindings, and roles.

With authentication enabled, each project authenticates its operators. A *source* supplies identities, a *binding* maps a user to role names, and a *role* is a set of permission flags. Two source types exist today: `embedded` (a project-local `users.toml`) and `gateway-source`, which today uses the built-in gateway user list. Directory (LDAP/AD) and SSO sources are not integrated.

```toml
# projects/press-line/project.toml
[project.auth]
inherit = false              # disable the implicit server credential source
sources = ["local"]

[project.auth.source.local]
type = "embedded"
credentials_file = "users.toml"

[[project.auth.bindings]]
source = "local"
username = "operator"
roles = ["operator"]

[project.auth.roles.operator]
can_write_tags = true
can_read_history = false

# projects/press-line/users.toml
[[users]]
username = "operator"
password_hash = "$argon2id$…"
```

With authentication enabled, projects require login by default and named users need a matching binding. Setting anonymous_role to a defined role issues restricted anonymous sessions with read permissions; anonymous sessions cannot write tags or acknowledge alarms. Sessions are scoped per project and draft, so a cookie from one is rejected on another.

## Permissions with authentication enabled.

| Flag | Default | Status | Gates |
| --- | --- | --- | --- |
| `can_write_tags` | `false` | Enforced | With authentication enabled, permits writes through the project API. |
| `can_read_history` | `true` | Enforced | With authentication enabled, permits project history queries. |
| `can_ack_alarms` | `false` | Enforced | With authentication enabled, permits acknowledgement and shelving through the project alarm API. |
| `can_run_queries` | `false` | Reserved | Accepted in config; no project route enforces this flag. |
| `can_trigger_transactions` | `false` | Reserved | Accepted in config; no project route enforces this flag. |
| `can_run_reports` | `false` | Reserved | Accepted in config; no project route enforces this flag. |

## Cookies, CSRF, and lifecycles.

- Session cookies are `HttpOnly; SameSite=Lax`; tokens are 32 random bytes. With authentication enabled, protected state-changing requests need the `X-CSRF-Token` header matching a JS-readable CSRF cookie (thermite.js handles this for screens). Login and logout are exempt.
- With authentication enabled, WebSocket upgrades use single-use tickets from `POST /api/ws-ticket` rather than the cookie alone — cross-origin hijack defense.
- Sessions live in memory: restarting the gateway logs everyone out. Logout revokes immediately.
- Per-client login rate limiting is not built in. Rate-limit `/login` at the proxy if the gateway is reachable from untrusted networks.

## Terminate TLS in front of the gateway.

The gateway's HTTP listener is plain HTTP; run it behind a reverse proxy (nginx, Caddy, your load balancer) that terminates TLS, and set `cookie_secure = true` so browsers refuse to send sessions over plaintext. The TLS that is built in is gateway-to-gateway: mesh links between peers are mutually authenticated with per-gateway certificates pinned by fingerprint.
