# Users

> The Users root of the Users page, the roster of local users, and the user panel where a user's display name, role and PIN are set, including the primary administrator and the admin PIN recovery.

The **Users** root holds one node per local user of the station. A local user is a display
name bound to exactly one role, with an optional PIN. There are no passwords, no e-mail
addresses and no per-user permissions: the role decides everything the user may do, and the
user is the name that decision is signed under.

The root and its children are for an administrator on this circuit (the Manage local users
permission). Anyone else sees the root without a count or children and, on opening it, the
notice that says to sign in as an administrator under Signed in now or on the user chip. The
one exception is a station with no users at all, where the root offers the first-use setup
to whoever is at the bench (see [Users](users#first-use)).

## The roster {#the-roster}

Opening the Users root shows the card **USERS** with the line "{n} local user(s) on this
station. Each holds one role, and the role decides what they may do." and one row per user,
in the order the station holds them.

| Element | What it shows |
| --- | --- |
| Avatar and display name | The name the column, the roster and the sign-in list use. |
| You | A chip on the user signed in on this circuit. |
| Primary administrator | A chip on the master user created by the first-use setup. |
| Sub-line | "PIN set" or "No PIN", then "never signed in", "last access today", "last access yesterday", "last access {n} days ago" or, past 60 days, the date in the station's configured format. |
| Trailing text | The role the user holds; a gap mark when that role no longer exists. |

Clicking a row opens that user's node in the column, which is where the user is both read and
changed. Creating a user is the column footer's **New user** (see [Users](users#new-and-the-column-footer));
removing one is **Remove user** on the detail bar.

In the column, each user node trails the name of its role.

## The user panel {#the-user-panel}

A user's panel saves as you work, the way every panel in the app does: the name commits when
the field is left, the role the moment it is picked. There is no Save button. While the
runtime is stopped the whole panel is inert under a "Runtime stopped" note; while a user is
selected that another screen has just removed, the panel says "That user is no longer on this
station. Pick another in the column."

### Identity {#identity}

| Field | What it is | Values / default | Effect |
| --- | --- | --- | --- |
| Display name | The name the column, the roster and the sign-in list use for this person. | Up to 80 characters; a new user starts as **New user**; a blank name is stored as **User**. | Commits when the field is left. The feed reports "Renamed the user to '{name}'." with the name the station actually stored. |

The head of the card repeats the avatar, the **You** and **Primary administrator** chips and
the PIN and last-access sub-line from the roster.

### Role {#role}

| Field | What it is | Values / default | Effect |
| --- | --- | --- | --- |
| Role | The role granting this user's permissions. | Every role except Not signed in, which is never assigned to anyone. A user created from the column starts on Operator when that seed exists. | Applies at once; the feed reports "'{name}' now holds the {role} role." The user's screens re-check the new role on their next press, even while signed in. |

Under the picker, the card reads the role's reach: "Can change {n} of 6 areas" (or
"View-only" / "No access") and the labeled reach strip, the same silhouette the Roles list
draws. When the role has been deleted the card says "This user's role is gone, so nothing is
granted. Pick a role that exists." A user whose role is gone falls to the floor: View
dashboards and nothing else.

For the primary administrator there is no picker. The card names the Admin role and says
"Primary administrator: full access, and the holder of the offline recovery key. Its role is
fixed and cannot be changed." The station refuses any edit that would demote it.

### Signing in {#signing-in}

The **SIGNING IN** card opens with the user's state: "This user is asked for a PIN when
signing in." or "This user signs in with a tap: no PIN is set." A PIN is a command with its
own button, not a field that autosaves: half a PIN is not an intention, and a stored one must
never be replaced by a stray keystroke.

| Field or command | What it is | Values / default | Effect |
| --- | --- | --- | --- |
| Set a PIN / Change the PIN | The masked entry for the new PIN, placeholder "4 to 6 digits". | Up to 6 characters typed; anything that is not a digit is dropped before the check. | Nothing until the button is pressed. |
| Set PIN / Change PIN | Stores the PIN, salted and hashed. | Refused on the field with "A PIN is 4 to 6 digits." when the digits left are fewer than 4. | The feed reports "PIN set for '{name}'." (or "Admin PIN set." for the primary administrator). The field clears. |
| Remove PIN | Takes the PIN away, so the next sign-in is a plain tap. Shown only when a PIN is set, and never for the primary administrator. | | Asks first, in the same window Remove user and Delete role use: "Remove the PIN from '{name}'? Signing in as this user becomes a plain tap, on every screen of this station and in any browser that reaches it. A PIN can be set again, but this one cannot be brought back." On Remove, the feed reports "PIN removed from '{name}'. Signing in as this user is now a plain tap." |
| Forgot the admin PIN? | A link shown only on the primary administrator; opens the recovery flow below. | | |

The hint under the field says what the PIN is: "Optional and local, 4 to 6 digits. It only
controls who uses this station; it is not protection against tampering." On the primary
administrator it reads "4 to 6 digits. Setting a PIN reveals a one-time recovery key, so
write it down."

Switching to another user in the column clears anything half-typed in these fields, so a
PIN drafted for one person is never applied to the next.

## The primary administrator {#the-primary-administrator}

The first user the station ever gets is the **primary administrator** (the master user):
created by **Set up local users**, named **Administrator** until you rename it, on the Admin
role, with no PIN. It is what makes the station governable and recoverable, so three things
about it are fixed:

- It cannot be removed. **Remove user** stays greyed on it with the reason "The primary
  administrator stays: its recovery key is what resets a forgotten admin PIN, from the sign-in
  screen, without anyone signed in."
- Its role cannot change. It is an Admin by construction; the panel shows no picker.
- Its PIN cannot simply be removed. Setting or changing it is the way its recovery key is
  minted; a primary administrator with no PIN at all is the state the first-use setup leaves.

Other users can be put on the Admin role too, and they manage users and roles like the
primary one. What they lack is the recovery key.

### The recovery key {#the-recovery-key}

Setting or changing the primary administrator's PIN rotates its recovery key and shows the
new one in a window titled **Admin recovery key**:

> The admin PIN is set. Write down this recovery key. It is shown only once and is the only
> offline way to reset a forgotten admin PIN:

The key is twelve characters in three groups, such as `ABCD-EFGH-JKLM`, drawn from an alphabet
without the easily confused 0, O, 1, I and L. It is stored hashed, like the PIN, and is never
shown again. The window is the one thing on this page that is not a scrolling panel, because
it must not be scrolled past.

### Resetting the admin PIN {#resetting-the-admin-pin}

There are two doors on the same key, and they ask for exactly the same two things.

On this page, for an administrator who is already signed in, **Forgot the admin PIN?** replaces
the PIN fields with the recovery form:

| Field or command | What it is | Effect |
| --- | --- | --- |
| Recovery key | The key written down when the PIN was last set. Case and surrounding spaces do not matter. | |
| New PIN | Masked, 4 to 6 digits. | Refused on the field with "The new PIN must be 4 to 6 digits." |
| Reset PIN | Verifies the key, stores the new PIN and rotates the key. | A wrong key stays on the field: "That recovery key is not correct." On success the feed reports "Admin PIN reset." and the window shows the new key: "The admin PIN was reset. Your new recovery key (the previous one no longer works):". |
| Cancel | Returns to the PIN fields and clears both. | |

The other door is the **sign-in screen**, and it is the one that matters when the PIN is
actually forgotten: on a station whose only administrator is locked out, this page cannot be
opened at all. Pick the primary administrator on the roster (the title-bar chip, or the sign-in
card a browser gets), and under the keypad there is **Forgot the PIN?**. It asks for the same
recovery key and the same new PIN, refuses a wrong key in the same words, and then shows the
rotated key on a step of its own with a **Done** button, because it is shown once. Nobody has to
be signed in: the key itself is the authorization, and the reset is journaled like any other.

Recovery is layered and needs no network: an administrator resets any other user's PIN from
that user's panel; the primary administrator's own PIN is reset with the recovery key, from the
sign-in screen or from here; with both lost, the way back is restoring a configuration backup (see
[Backups](settings-backups)). There is deliberately no "wipe access control" button.

## Where users are stored {#where-users-are-stored}

Users, roles, PIN hashes and the recovery-key hash live in the station's configuration
database with no machine-bound key, so they travel inside a configuration backup and survive
a move to another computer, fully offline.

## What the panel does not do {#what-the-panel-does-not-do}

- It does not set permissions on a user. Change the role under [Roles](users-roles), and
  every user holding it changes at once.
- It does not show or recover a plain PIN. Only the hash is stored; a forgotten PIN is
  replaced, never read back.
- It does not sign the user in. That is the [Signed in now](users-signed-in) root and the
  title-bar chip; see [Signing in](users-signing-in).
- It refuses every write while the runtime is stopped: rename, role change, PIN set, PIN
  removal, reset and creation all answer "Runtime stopped".
- It does not remove the primary administrator, and it does not create a second one.