Users and access

Electric Cherry requires a user session for operator pages and management APIs. HTTPS protects the connection; server-side role checks protect each operation. There is no anonymous management mode or public registration.

Leaderboard API reads (GET and HEAD /api/leaderboard) are public and need no session or credentials. This exception covers only that exact API route; leaderboard/profile pages, match-history routes and management operations retain their access checks. HTTPS requirements still apply. See the leaderboard API reference for requests and response fields.

First administrator and upgrades

Generate a setup secret: openssl rand -hex 32.
Set EC_SETUP_TOKEN to that value in the controller environment (or Compose .env), set EC_PUBLIC_URL to the external HTTPS URL, and start EC. For a direct Node deployment, set ORIGIN to that same URL.
Visit EC. /setup asks for the setup token, a username, display name and password. Only the holder of the token can create the first administrator.
Remove EC_SETUP_TOKEN after setup and restart/recreate the controller. Setup remains closed once any user exists, even if the token is still set.
Use Admin → Users to create additional accounts. Share temporary passwords privately; each user must change theirs on first login.

Existing installations become protected on upgrade. Existing game servers and agent enrollment credentials continue working independently of browser login. Preserve the current database when upgrading: accounts and sessions are stored there alongside the fleet metadata. Never publish a blank setup page with a guessable token. An unset setup token holds setup closed.

Roles

Capability	Viewer	Super Viewer	Operator	Administrator
Fleet, metrics, matches and operation summaries	Yes	Yes	Yes	Yes
Raw configs, file diffs, logs, saved RCON and telemetry diagnostics	No	Read	Read	Read
Deploy/start/stop/restart/rebuild/remove servers and run diagnostic probes	No	No	Yes	Yes
Scripts, plugins, configs, campaigns, betas and collections	Read summaries	Read	Manage	Manage
Host setup, deletion, enrollment, credentials, runtime preparation and game-file upload/cache	Read status	Read status	Read status	Manage
Server keys and global settings/maintenance policies	No	Read	No	Manage
Users and account audit activity	No	Read	No	Manage
Create users, change roles, disable accounts and reset passwords	No	No	No	Yes
Own password and sign out	Yes	Yes	Yes	Yes

Super Viewer is a read-only administrator. It includes the Admin navigation and access to sensitive configuration and diagnostic content, but cannot change fleet state, settings, keys, or other accounts. Cleanup previews remain available because they do not save settings or run cleanup. Assign it only to people trusted to read administrative information. Existing accounts and sessions are preserved on upgrade.

Operators can launch using available game-pool keys already saved by an administrator. They cannot save keys indirectly through a launch request. An operator's content permissions include executable scripts and plugins; assign that role only to people trusted to operate the game fleet.

Drift previews (/api/drift) and GitHub release lookups (/api/plugins/github/release) require operator or administrator access, including GET and HEAD requests. These endpoints initiate fleet file scans or use GitHub API quota; Viewers and Super Viewers cannot trigger them.

Saved RCON failure replies are available to Super Viewers, operators and administrators in the server's Diagnostics tab. Player addresses are redacted before diagnostics are saved; successful checks clear the saved reply. Fleet snapshots and live status streams contain no reply snippets. Upgrades discard older saved RCON snippets.

Permissions are checked on the server for API calls, normal pages and Svelte page-data requests. Hiding UI controls is a convenience, not the access boundary. The controller prevents disabling or demoting the last enabled administrator. Accounts are disabled rather than deleted so history retains their identity.

Passwords, sessions and recovery

Passwords are 8–128 characters and stored using salted scrypt hashes. Temporary passwords created or reset by administrators must be changed before any fleet access. Password changes require the current password.

Sessions use random tokens in HTTP-only cookies, with only token hashes stored in SQLite. HTTPS uses a Secure __Host- cookie. By default, sessions expire after 12 hours, or 30 minutes without authenticated requests; background dashboard polling counts as activity.

Select Keep me signed in on this device at sign-in to stay signed in for 30 days, including between visits from a phone's home-screen app. This option is unchecked by default and applies only to that browser or home-screen app. Remembered sessions have no inactivity timeout, but still expire 30 days after sign-in; activity does not extend that deadline. Use this option only on a device you trust. Existing sessions keep their original limits after upgrading.

Password changes always require the current password. Remembered administrator sessions also require the administrator's current password when creating accounts or editing users, including access changes and password resets. A successful password change replaces the current session, preserving its remember-device choice with a fresh lifetime, and revokes all other sessions.

For API clients, POST /api/auth/login accepts an optional boolean rememberMe (omitted or false keeps the default limits). When using a remembered session, POST /api/users and PATCH /api/users/:id require the administrator's password in currentPassword; the password field remains the target user's temporary password. The password-change endpoint preserves the current session's choice.

Login replaces the existing browser session. Logout revokes it. Changing a password, changing a role, disabling an account, or revoking that user's sessions invalidates their existing sessions. Live event streams check revocation every 15 seconds and then close.

Login and password changes for enabled Administrators and Super Viewers are exempt from per-account and per-address rate limits, including existing exhausted windows. Their attempts do not consume either limit. Other accounts and initial setup use persistent 15-minute windows. Exemptions use the account's current database role; password verification is still required. The database stores audit entries for login results, account changes and successful management requests without recording passwords, tokens or request bodies. Administrators and Super Viewers can review recent entries in Users.

For every role, the password service runs at most two scrypt operations at once and queues up to 16 more for up to two seconds. If that queue fills or the wait expires, the request returns HTTP 429 with Retry-After: 2. The persistent rate limits return Retry-After: 900 when a non-exempt account or address reaches its attempt limit.

An administrator can reset another user's password from Users. If the only administrator forgets their password, an operator with local controller/container access can run the recovery command in an interactive terminal:

docker compose exec electric-cherry node scripts/reset-admin.mjs admin
# Direct Node deployment, using the correct database:
DB_PATH=./data/cherry.db node scripts/reset-admin.mjs admin

Replace admin with the existing administrator's username. The command prompts without echoing the password, resets that enabled administrator only, revokes their sessions and records the recovery. It does not expose a remote recovery endpoint or accept passwords as command arguments.

Agent and telemetry connections

Host agents retain enrollment/host-token authentication under /api/agent/. Installer and release files remain public so a new machine can enroll. A browser login never substitutes for a host credential, and host tokens cannot manage EC. The agent and standalone updater source contain no credentials. Automatic updates fetch the controller's public HTTPS release manifest and verify its checksums and compatibility. The installed host retains its own credential; the updater accepts an upgrade only after a fresh authenticated heartbeat from the new agent process. Updating agent code does not change browser sessions or user roles. See automatic agent updates for the one-time installer upgrade required by existing hosts. Host deletion uses a separate operation-scoped receipt token so the uninstall worker can confirm removal and retry its acknowledgment after host credentials are revoked. That token authorizes only the corresponding cleanup receipt.

Game reporters must send a separate secret of at least 32 characters configured as EC_TELEMETRY_TOKEN:

POST /api/telemetry
Authorization: Bearer <telemetry-token>
Content-Type: application/json

X-EC-Telemetry-Token is also supported. Cookies, query parameters and JSON fields cannot supply it. A missing server token disables ingestion; a missing or wrong request token is rejected before parsing or recording the payload. Existing JSON event fields are unchanged. Configure your uploaded reporter/plugin, or a trusted relay if that reporter cannot set headers, before upgrading. Use HTTPS for the reporter-facing endpoint. Rotating this shared token requires updating reporters.

Proxy and local development

Keep Node's internal port behind your TLS proxy and configure ORIGIN correctly. Management writes require an exact matching Origin header, including login, JSON requests and multipart uploads. Do not configure a proxy to replace arbitrary incoming origins with your trusted origin. Machine endpoints use their own token checks and do not require a browser Origin.

Use the adapter's real client-address configuration only with a trusted proxy that strips spoofed forwarding headers; login throttling otherwise uses the direct peer address. Forwarded host or user headers do not authenticate users.

Local HTTP browser development requires EC_AUTH_ALLOW_HTTP=true and a loopback hostname (localhost, 127.0.0.1 or ::1). This uses a separate development cookie. It never enables HTTP login for a LAN/public hostname. Agent HTTP development remains separately controlled by EC_AGENT_ALLOW_HTTP and the agent's loopback-only option.

The implementation follows OWASP's guidance for authorization on every request, password hashing, and session management.

12 KiB Raw Blame History Unescape Escape