ADR 0012: Owner and read-only guest accounts¶
- Status: Accepted
- Date: 2026-11-11
- Supersedes: the single-user scope of ADR 0005
Context¶
ADR 0005 chose exactly one account: no user management, no roles, nothing to misconfigure. Households want to show a tab (shopping list, waste calendar, transit departures) to family members or flatmates without giving them the owner's password or the ability to change anything (#82). API tokens (#96) and kiosk displays (#50) need the same kind of limited access.
Decision¶
- There is still exactly one owner with full rights. The setup, the
password reset via
waylight reset-accountand all settings stay owner-only. - The owner can create up to 20 guests: own name and password, own sessions and optional two-factor authentication, a list of shared tabs, and a disabled flag. Guests sign in with name + password; the owner keeps signing in with the password only.
- Authorization is decided centrally in the auth module's request guard
(
usecase.Authorizer, ruledomain.GuestMayAccess) — controllers of other modules contain no permission checks. The rule is an allow-list: - self-service on the own account (password, two-factor, sessions, logout);
GETof the dashboard (filtered to shared tabs), modules list and appearance;GETof modules whose widgets are on a shared tab (resolved through theGuestScopeport, implemented in the composition root), except any/settingsendpoint and the auth, transfer, backup, notification and backup-monitor modules;- everything else, including every write, is
403. New endpoints are therefore closed for guests by default. - The authenticated account travels as
kernel.Principalin the request context; modules that show per-user views (the dashboard) read it there. - Sessions, recovery codes and security events belong to an account
(
auth_accounts, migration 0005 moves the owner over unchanged).
Consequences¶
- One permission model that API tokens and kiosk tokens can reuse (scopes instead of tabs).
- Changing a guest's tabs or disabling it takes effect on the next request: the account is loaded per request (one indexed SQLite lookup).
- Widget data is shared at module granularity: a guest who sees the notes widget can read all notes, not only those shown in the widget. The settings page says so; sensitive data belongs on tabs that are not shared.
- Guests cannot change anything, not even check off a to-do. Shared editing would need per-object ownership and is out of scope.