Repository navigation
Users and Permissions
The host console is protected by cookie authentication. Operators sign in with a local user account; what they can see and do is gated by per-permission authorization policies.
- The login page lives at
/login. It posts a native HTML form toPOST /auth/login— a cookie can only be issued on an HTTP response, not over the Blazor circuit. - The cookie (
khost.auth) lasts 12 hours with sliding expiration. - Usernames are case-insensitive (
Admin=admin); passwords are case-sensitive and hashed with Argon2id. The uniqueness index onUsers.Nameuses SQLite'sNOCASEcollation, and lookups compare withOrdinalIgnoreCaseon the .NET side because the bundled SQLite only case-folds ASCII. - The last signed-in username is remembered (
cache/last-login.json) and prefilled on the login page — like an OS lock screen, it shows who was last at the controls, and focus lands in the password field.
Lock in the settings menu posts to /auth/logout: it signs the session out and returns to the login page with the username prefilled. Nothing else is touched — the singer queue, playback, and screens keep running. Lock is hidden when the login requirement is off.
Permissions are the KHostPermission enum (src/KHost.Abstractions/Models/KHostPermission.cs); enum values are pinned explicitly because they persist as numbers in the UserGroups JSON. Users get permissions through group membership; a user in the Admin group passes every gate.
At startup one authorization policy is registered per enum value — admins pass all of them — so a page gates itself with [Authorize(Policy = nameof(KHostPermission.X))] and no gate needs its own logic. The claims come from KHostClaimsFactory: an Admin role claim plus one khost:permission claim per permission. The settings menu only lists the pages the signed-in user can open; App Settings is admin-only.
A group can also be marked Not A Singer, which keeps its members out of the singer queue's suggestions — a login account is a user like any other, and would otherwise be offered alongside the people waiting to sing. The flag is on the group rather than the user, so an account is left out by virtue of what it belongs to. The seeded Admin group has it set.
Group membership and permissions are edited in the User Groups Manager; users, including their passwords, in the Users Manager (a blank password field leaves the password unchanged).
Auth:RequireLogin (default true) controls whether the console asks for credentials at all:
- Chosen on the Security step of the first-run wizard (the admin-credentials step is skipped when it is off).
- Toggled later on the App Settings page, which writes the settings overlay. The value is read per request, so a change applies on the next page load, not the next launch.
- When off, every request runs as a synthetic console principal with the Admin role — single-operator mode. The permission gates stay wired and all pass; there is no second code path through the UI.
- Turning it on is refused while no admin-group user has a password, because that would lock every operator out. Set a password on an admin first.
LanAccessPolicy is unchanged by all of this: off-box requests still only reach /media and /ipc/screen regardless of authentication (see Architecture).
Accounts are local, so recovery is a command-line flag rather than email:
dotnet run --project src/KHost.UserInterface -- --reset-password <username>It generates a new 12-character password from an ambiguity-free alphabet (no 0/O/1/l/I), stores its hash, prints the password to the console, and exits. Run it while the host is stopped — the single-instance guard reports an already-running host instead of resetting.
Physical access to launch the process with a flag already implies ownership of the database file, so the flag grants nothing that access did not — it only makes recovery not require hand-crafting an Argon2 hash into SQLite.
KHost
Architecture
- Architecture
- Projects
- Screens and Casting
- Break Music and Ads
- Messaging
- Data and Persistence
- Plugins
Contributing