RFC: Authentication & onboarding for Z-Wave JS UI

[AlCalzone]

RFC: Authentication & onboarding for Z-Wave JS UI

Status: Draft for discussion
Audience: Z-Wave JS UI maintainers + HA add-on/integration owners

---

1. Summary

Z-Wave JS UI ships with authentication disabled by default and, when enabled, a hardcoded
admin / zwave credential that is never forced to change. This RFC makes ZUI
secure-by-default on every install method and removes shipped default credentials — while
keeping access frictionless when ZUI runs embedded behind a host that already authenticates its
users (most notably the Home Assistant add-on behind ingress, where ZUI simply defers auth to the
ingress proxy). It also adds long-lived API tokens for programmatic clients (e.g. a future HA
integration that consumes ZUI's API).

---

2. Background & problem

The default authentication posture is the single most important structural security issue in ZUI
today, because it turns operations that would otherwise require a login into unauthenticated,
network-reachable ones. Two halves:

• Auth off by default. A fresh install binds to all interfaces and exposes its full HTTP API
  and real-time socket to any anonymous client on the network.
• Hardcoded default credentials. When auth is turned on, the seeded login is admin / zwave,
  with no forced change — and the UI even advertises these defaults.

A guiding principle: addressing only the default-off posture without eliminating the default
credentials would just replace "no auth" with "admin/zwave" — both must be solved together.

The building blocks already exist — scrypt password hashing, JWT sessions, a fail-closed session
secret, rate limiting, and reverse-proxy support — so this is mostly a defaults-and-onboarding
problem plus a few targeted crypto-hardening fixes (§7), not a build-from-scratch effort.

---

3. Goals / non-goals

Goals

• No install exposes its API or real-time socket unauthenticated by default; embedded installs
  defer that authentication to the host.
• No hardcoded credentials ship in the product.
• Frictionless experience when ZUI is embedded behind a host that authenticates its users — no
  second login on top of the host's.
• A documented path for programmatic/API clients (long-lived API tokens).
• A migration that closes the hole on existing installs without silently locking legitimate users
  out.

Non-goals

• Multi-user / RBAC beyond a single admin (could be a later evolution).
• Authenticating the embedded @zwave-js/server WebSocket (the socket the HA integration uses
  today) — see §8, this needs upstream work.
• Replacing the existing crypto primitives (we harden a few; see §7).

---

4. Deployment contexts

Any solution must work across all four, which pull in different directions:

Context	Who reaches ZUI	Auth expectation
Standalone Docker	User's browser on the LAN (often 0.0.0.0 exposed)	Must require auth; needs a usable first-run flow
Standalone npm	Same as Docker	Same
Embedded in a host app (e.g. HA add-on, behind ingress)	The host proxies the UI and has already authenticated the user	No second login — defer auth to the host
Host app → ZUI API (e.g. HA integration; future)	A machine client, not a browser	Authenticates with a long-lived API token (D5)

Home Assistant is the primary concrete instance of the "embedded" context:

• The add-on runs behind HA ingress (ingress: true). HA authenticates the user and proxies
  every request from the fixed internal IP 172.30.32.2. Per HA's ingress contract these
  connections are pre-authenticated, so the add-on must not require its own auth for them.
• The ingress path prefix arrives via X-Ingress-Path — ZUI must honor it so assets resolve
  under the sub-path. HA also forwards the user identity via X-Remote-User-Id / -Name /
  -Display-Name, but ZUI needs these only for display/audit, never for the auth decision.

---

5. Design decisions

D1 — Default authentication posture

Authentication is always on. The existing gateway.authEnabled setting is removed — there
is no in-app toggle. The only way to disable auth is an explicit env var,
DANGEROUSLY_DISABLE_AUTH=1, logged loudly on every startup, for local development or
deliberately-trusted networks.

• Pros — secure by default; one obvious, alarming opt-out instead of a quietly-flippable
  setting; still flexible for users behind their own authenticating proxy.
• Cons — an "off" mode still exists, so it relies on users not setting the opt-out carelessly.

D2 — Migration for existing installs

Flip everyone on upgrade. Auth becomes enabled for all installs; any install still on the
shipped default credential is forced to set a real admin password at next login. Users who
deliberately ran without auth must set DANGEROUSLY_DISABLE_AUTH=1 (D1).

• Pros — closes the exposure uniformly across the whole install base.
• Cons — a breaking change: headless/API clients break until they set a credential/token or opt
  out (see §6).

D3 — First-run credential on a fresh standalone install

Forced setup wizard. On first run with no users, ZUI serves a guarded "setup required" state
that forces creating the admin account before any protected route is reachable. Env-provided
credentials (DEFAULT_USERNAME + DEFAULT_PASSWORD) remain an opt-in headless bootstrap that skips
the wizard. No admin/zwave credential ever ships.

• Pros — best UX for a web app; no credential ever ships; self-explanatory first run.
• Cons — requires building a setup UI plus a guarded "setup required" server state.

D4 — Authentication when embedded behind an authenticating host (e.g. HA add-on)

When a request reaches ZUI from a configured trusted reverse proxy, ZUI skips its own
authentication for that request — the proxy (HA's ingress) has already authenticated the user.
This is controlled by a new env var, AUTH_TRUSTED_PROXY (a sibling of TRUST_PROXY), set to
the proxy's address — 172.30.32.2 for HA ingress; it accepts one or more IPs/CIDRs and applies to
both the HTTP API and the Socket.IO connection. The HA add-on sets it automatically; standalone
installs leave it unset. Such requests are treated as fully authorized (ZUI is single-user), so no
token, shared "system identity", or trust of X-Remote-User-* is needed for the auth decision; the
user's own admin credential is untouched and stays fully user-managed.

The match is keyed on the connection's real peer IP, never a forwarded header (see §7). Other
source IPs are not blocked — they simply get normal authentication. So direct access to ZUI's web port (8091, if the user publishes
it) still requires a login or API token; the HA add-on leaves that port unmapped by default
(ports: { 8091/tcp: null }, while ingress still reaches the container port internally), so out of
the box the only route in is the pre-authenticated ingress path.

• Pros — no second login; no token/identity machinery; reuses the host's existing auth; trivial
  to implement (a peer-IP check on both transports); the user's own credential is untouched.
• Cons — relies on a correct peer-IP check and on the trusted proxy being the only path that
  can reach the port it fronts (see §7); standalone reverse-proxy setups must firewall the app port
  accordingly.

D5 — Programmatic API access

Add long-lived, named, revocable API tokens — CSPRNG-generated, hash-only storage, shown once —
for programmatic clients (scripts, external integrations, a future HA integration consuming ZUI's
API). A token authenticates on both transports: the Authorization: Bearer header (or
x-access-token) for the REST API, and the Socket.IO handshake auth field (browsers can't set
headers on a WebSocket). Both auth paths must hash-match the opaque token, not only verify session
JWTs as they do today.

• Pros — standard pattern; serves any external client; decoupled from interactive login (no
  1-day expiry).
• Cons — new token store + management UI to build.

D6 — Credential recovery (standalone)

Reset the store. Standalone installs recover a lost admin password by deleting the users file,
which drops back to the first-run setup wizard (it must not re-seed any default credential). The
reset must also invalidate all API tokens — a credential reset that left existing tokens valid
would let a leaked token outlive the credential it was bound to. Embedded deployments need no
recovery path: the host authenticates every request, so ZUI never depends on a stored password
there.

• Pros — nothing to build; no recovery flow to secure (a recovery path is itself an attack
  surface).
• Cons — destructive (drops all users and tokens); no graceful self-service reset for standalone
  users.

---

6. Release & migration

ZUI ships all of the above in a single major release — no phased rollout. Because auth becomes
mandatory (D1/D2), downstream applications must be updated before they can run on the new major:

• The HA add-on must set AUTH_TRUSTED_PROXY=172.30.32.2 (D4).
• Any external client or integration relying on the old unauthenticated API must adopt an API token
  (D5) or set credentials.

This is a breaking change — flag it prominently in the changelog. Ship the add-on update
together with the release so HA users get the frictionless ingress path the moment auth becomes
mandatory, avoiding a window of double-login (or broken-access) pain.

---

7. Security considerations

• Trust the connection, not the headers. The AUTH_TRUSTED_PROXY check (D4) must match the
  real socket peer IP, never X-Forwarded-For or any client-supplied header — those are
  spoofable. The trusted proxy must also be the only thing that can reach the port it fronts (HA
  ingress guarantees this; standalone reverse-proxy setups must firewall the app port).
• No insecure intermediate state. While "setup required" (D3), every protected route and the
  Socket.IO connection must refuse access.
• Constant-time password check. verifyPsw must compare derived keys with a timing-safe
  comparison (crypto.timingSafeEqual), not ===.
• Pin JWT algorithms. verifyJWT must pass an explicit algorithms allow-list to jwt.verify
  (on both the REST and Socket.IO paths), so a token can't be presented under an unexpected
  algorithm.
• Tokens & passwords: CSPRNG generation, hash-only storage, plaintext shown once, individually
  revocable; a credential reset invalidates all tokens (D6).
• Preserve the fail-closed session secret — do not regress it.

---

8. Out of scope

• The embedded @zwave-js/server WebSocket (port 3000, the socket the HA integration connects
  to today) is unauthenticated and binds all interfaces by default. Adding auth there needs an
  upstream @zwave-js/server change plus HA-core support, and is distinct from the web UI / REST API
  this RFC secures. Recommend documenting network isolation (bind it to loopback when co-located)
  and tracking auth upstream separately.

[robertsLando]

I agree with all statements above, I would only release this in a single v12 release instead of having more phases. Aobut the zwave js serve thing I think it could be worth adding a tracking issue there too with a reference to this one

[robertsLando]

Strong RFC — I went through it against the current code and the premises hold up: scrypt hashing, the fail-closed session secret, rate limiting, JWT sessions, and the ZWAVE_EXTERNAL_SETTINGS injection channel all exist as described, and the "defaults & onboarding, not build-auth-from-scratch" framing is accurate. A few risks and refinements, roughly in priority order:

1. "Flip everyone on upgrade" (D2) is the riskiest call. The install base is large and heavily headless — Docker on a LAN, Node-RED/scripts hitting REST + Socket.IO without a token. Flipping auth on in an ordinary upgrade 401s all of them at once, and auto-updaters (Watchtower, add-on auto-update) mean most users won't see the changelog first. The forced-password-change mitigation only helps installs that already had auth on with default creds — the minority. Worth considering: tie the flip to a major version bump, secure new installs (empty users.json) immediately, and give existing exposed installs a deprecation window (persistent banner + loud startup log) before flipping.

2. The proxy-IP gate (D4) is where a mistake is catastrophic, and it needs to be pinned down. The gate must compare the raw TCP peer (req.socket.remoteAddress), never req.ip — req.ip is derived from X-Forwarded-For once trust proxy is set, and ZUI already exposes TRUST_PROXY with broad presets. A user setting TRUST_PROXY=true for their own proxy combined with an IP gate written against req.ip would let any LAN client send X-Forwarded-For: 172.30.32.2 + X-Remote-User-Id and auto-login as admin. Since 172.30.32.2 is a public constant, IP alone is thin defense — worth an explicit embedded-mode signal (+ a per-boot shared secret via the settings channel the add-on already controls) and making "reject spoofed identity headers on a direct connection" a mandatory test.

3. The ingress path prefix (Phase 2) is bigger than it looks. BASE_PATH exists in config today but isn't actually wired into routing — only a legacy X-External-Path redirect uses it. HA ingress serves under a runtime, per-session path, so the frontend asset URLs, router base, and Socket.IO path all need to become runtime-derived. Probably the largest code change in the RFC; worth spiking early.

4. Consider splitting D5 from D6. Generic hashed/revocable API tokens (D5) are useful for every programmatic client (Node-RED, custom dashboards), so they could ship independently and early. The host-mints-and-injects provisioning (D6) couples three repos and can stall on HA-core coordination — no need to make generic tokens wait on it.

5. §10 undercuts the "secure by default" headline. The @zwave-js/server websocket (port 3000) — the channel the zwave_js integration actually uses to control devices today — stays unauthenticated and all-interfaces-bound. Securing the UI/REST while that stays open is only half the story; binding it to loopback when co-located could be made the add-on default now rather than just documented.

Cheap hardening to fold in while in the area: verifyPsw compares with key === derivedKey rather than crypto.timingSafeEqual; and verifyJWT is called with no algorithms option at any of its three call sites — §9 asks for algorithm pinning, just make sure all three get ['HS256'], not only the REST path. Also worth defining precedence between the existing authEnabled setting and the new DANGEROUSLY_DISABLE_AUTH env var, and steering add-on maintainers away from the disable flag for the ingress case (embedded should stay auth-ON via D4).

One detail for D6/D7: a credential reset must also invalidate API tokens (or orphaned valid tokens survive the reset), and ZUI should register the injected host token in an idempotent "host token" slot rather than appending a new hash on every restart.

[AlCalzone]

mean most users won't see the changelog first

I'm not convinced by that. Anyone who auto-updates to a different major version is just asking for trouble.

P alone is thin defense — worth an explicit embedded-mode signal (+ a per-boot shared secret via the settings channel the add-on already controls)

The auto-login is supposed to be limited to the token that the host application passed to Z-UI on startup - should probably be made more explicit in the RFC.

Also worth defining precedence between the existing authEnabled setting and the new DANGEROUSLY_DISABLE_AUTH env var

The authEnabled setting should go away.

[AlCalzone]

Additional info when running as a HA addon:
https://developers.home-assistant.io/docs/apps/presentation/#ingress

• Only connections from 172.30.32.2 must be allowed. You should deny access to all other IP addresses within your app server.
• Users are previously authenticated via Home Assistant. Authentication is not required.

---

We need to be able to specify this when starting Z-UI.

[AlCalzone]

After some more discussion, it seems that the preferred way to handle this is to listen on two different endpoints. One like today, but with authentication. And one that binds only to a host-provided network, checks for the source IP and drops auth.

[robertsLando]

sounds good and a nice balance 👍🏼

[AlCalzone]

RFC updated with all feedback

[robertsLando]

Looks good to me