Local operation and security

HoumeOS is a local system. The rules, the device states, the history and the permissions are stored and executed on a server inside your network. Commands never leave the LAN, and losing the internet stops neither the rules nor the schedules.

Two layers of access

• Network layer — BRIDGE_TOKEN: who may talk to the server at all. Requests carry Authorization: Bearer; for SSE the token goes as ?token=, because EventSource cannot set headers. If it is empty there is no authentication — that is for development, not for operation.
• Human layer — a session after a PIN sign-in: which person is allowed to do what. The session token travels as x-home-session and lives only in the driver — not in React state and not in localStorage. The /api/stream feed requires no session, because it only carries data.

The PIN is not in the kiosk bundle (the VITE_KIOSK_PIN variable was removed). It is verified on the server: bridge/users.json stores hashes computed with scrypt and a salt, the comparison is constant-time, and after 5 wrong PINs a pause kicks in (response 429). Sessions slide with a 30-minute expiry, and the kiosk locks itself after 3 minutes without touch.

Roles, permissions and critical actions

The three roles are explicit: admin — everything; resident — everything except config and debug; guest — lighting and scenes. Permissions are checked by action kind, not by screen: every command maps to an action and goes through checkCommand(). The answers are 401 without a session, 403 without permission, 409 for a critical action without confirm: true, 429 while paused.

Critical are door.set, door.all, cover.set, alarm.set and any device marked critical: true in the registry. The kiosk asks the person through a dialog before it sends the command, and the server demands the confirmation regardless of who asks. Editing integrations, rules, scenes, rooms and profiles sits behind the config permission.

Everything that reaches the server lands in the event log: sign-ins, sign-outs, refusals, executed rules and commands. That is the audit trail, not a promise.

What stays in the network and what is stored on the server

The history lives on the server: a sample every minute, hourly and daily aggregations, retention of 7 days of raw samples · 31 days of log · 13 months of rollups. The kiosk asks for the finished series instead of accumulating numbers in the browser. The offline shell (the PWA manifest and a hand-written service worker) stores HTML, JS, CSS and fonts, but never data: requests to /api/, requests with authorization, and mutations are not cached. Without the server the tablet shows the interface and "No connection" with the age of the last reading marked. Caching the numbers was explicitly rejected, because a stale temperature presented as live is worse than a missing one.

What is not ready yet

• HTTPS inside the network. Today the service worker and the PWA install exist only on localhost or behind your own TLS terminator; outside those, an offline shell on a tablet in the LAN needs both.
• Notification delivery outside the home — SMTP, push and webhook are still waiting on a decision; until then, news stays on the screen and in the event log.
• Session durability. Sessions live in server memory — a restart wipes them and the kiosk asks for the PIN again. Persistent token storage does not exist and is not planned.
• The security part is lighter than a certified alarm system: no zones, no mode history, no bypassing a single sensor; critical alarms work independently, and safety.mute does not delete the alert from the screen.
• Outside the LAN there is no cloud bridge and no automatic device discovery — the server address is set by hand, which is why it must be permanent (hardware and network requirements).

What is watched: telemetry-silent (not a single sample for 60 s), transport-down (a broker offline for over 30 s), devices-offline, matter-down and command-failures (3 refusals in 120 s) — the first two are critical, the rest are warnings.