user admin

ARCHITECTURE.md

@@ -37,6 +37,7 @@ there is no browser-side persistence or independent playback state.
 flowchart TB
     Main[main.rkt<br/>configuration and lifecycle]
     Server[private/server.rkt<br/>HTTP adapter]
+    Users[private/users.rkt<br/>users, networks and sessions]
     Player[private/player.rkt<br/>application state and commands]
     Library[private/library.rkt<br/>filesystem and metadata]
     UI[public/index.html + styles.css + app.js<br/>browser UI]
@@ -49,6 +50,7 @@ flowchart TB
     Main --> Player
     Main --> Library
     Server --> Player
+    Server --> Users
     Server --> UI
     Player --> Library
     Player --> Audio
@@ -214,6 +216,20 @@ DOM signatures prevent rebuilding unchanged library, tab, and playlist
 collections on every poll. Playback status and other small values are updated
 on every render.
 
+### 3.7 User authentication
+
+Authentication is enabled by adding Argon2id password hashes under `[users]`.
+Requests whose effective client address belongs to a configured local network
+bypass login. A forwarded address is accepted only when the direct peer belongs
+to `[authentication] trusted-proxies`; the rightmost `X-Forwarded-For` value is
+used so an untrusted client cannot prepend a local address.
+
+Successful logins create opaque 256-bit session tokens. Only the token is sent
+to the browser in a `Secure`, `HttpOnly`, `SameSite=Strict` cookie; server-side
+session state has an idle timeout and is intentionally volatile. Login failures
+are rate-limited per effective client address. Agent endpoints are outside user
+sessions and retain their separate application-ID authorization.
+
 ## 4. Key runtime flows
 
 ### 4.1 Browse and play a directory
@@ -287,6 +303,7 @@ file:
 - named library root paths under `[libraries]` (the legacy semicolon-separated
   setting remains supported);
 - allowed 256-bit playback-agent IDs under `[playback-agents]`.
+- Argon2id user hashes, local networks, trusted proxies, and session timeout.
 
 Command-line network settings override INI values. Library paths from both
 sources are combined and de-duplicated.
@@ -297,12 +314,13 @@ state, and all other mutable state.
 
 ## 7. Security and operational boundaries
 
-The browser API has no user authentication, TLS termination, CSRF protection,
-or per-user state. Anyone who can reach the HTTP port can inspect the exposed
-library names and control the shared player. The default localhost binding is
-therefore an important security boundary. Binding to a LAN address should be an
-explicit deployment decision and should use an external trusted network
-boundary or authenticated reverse proxy when untrusted clients are possible.
+The browser API has optional user authentication but no TLS termination or
+per-user player state. Authentication must be enabled before exposing it to an
+untrusted network, and a reverse proxy must provide HTTPS because session
+cookies are always marked `Secure`. Local-network bypass and forwarded client
+addresses are security-sensitive configuration: only known reverse-proxy peers
+may be trusted, and the application port should remain firewalled from the
+internet.
 
 Playback-agent registration and polling are authorized against a default-deny
 INI allowlist. Media URLs additionally contain an opaque per-track token. The