# 0020. Back office sign-in

- Status: Accepted
- Date: 2026-10-28

## Context

The back office (M7) is a web app served by the hub, for owners and managers on a laptop or
phone. It edits the menu, staff and settings that every device sells with, removes devices and
shows reports, so it needs real sign-in. Until now a hub only knew devices (ADR 0019): tokens
issued by pairing, and staff identified by short PINs on the device itself. A 4–8 digit PIN is
fine behind a device's own lock screen and lockout, but too weak for a page that may be reachable
over the internet. A shop reaches the back office in one of two ways: set up from scratch in the
browser, or moved to the hub from its first POS device (ADR 0019), with an owner who has a PIN
but no password yet. One hub may serve several shops, and one person may run more than one.

## Decision

**Accounts.** A back office account is an email and a password, kept in the hub's registry
(`hub.sqlite`) next to device tokens. Each account is linked, per shop, to one staff member of
that shop. The staff member's role decides what the account may do: owners and managers may sign
in; cashiers can't. Archiving a staff member or making them a cashier ends their sign-in at
once. One account can manage several shops on the same hub and switch between them. Passwords
are hashed with scrypt (N = 2^15, r = 8, p = 1, parameters stored with the hash) and are at least
8 characters.

**Sessions.** Signing in sets an `HttpOnly`, `SameSite=Lax` cookie (`Secure` behind HTTPS)
holding a random token; the hub stores only its hash. Sessions last 30 days from last use. Every
request that changes something must carry the `x-openkedai-api` header, which a page on another
site can't send without the hub's permission (CORS is never granted), so the cookie can't be
used by a forged form. Wrong passwords and codes are limited per address and per email.

**Ways in.**
- **New shop in the browser.** The setup wizard asks for the hub's setup code (ADR 0019), then
  the shop's details, the owner's name and POS PIN, and an email and password. A person who is
  already signed in adds the shop to their account.
- **A shop moved from a POS device.** An owner or manager on a paired device opens Settings → Hub
  → Back office and gets a one-time **sign-in code** (8 characters, 30 minutes) with the back
  office's address. In the browser, "I have a code from the POS" asks for the code, an email and
  a password. The device asks for the code on behalf of the staff member using it, trusted as
  devices are (ADR 0019).
- **Forgotten password.** A new sign-in code from a POS device resets the password of the staff
  member's account and signs it out everywhere.
- **Managers.** An owner can give a manager (or another owner) an email and password from the
  Staff page.

**Rules the hub enforces** (devices still enforce roles on themselves): only owners manage owners
or give back office access; a shop always keeps at least one owner; nobody changes their own role
or removes themselves.

**Plugin routes** (ADR 0018) get real meaning: `owner` routes answer a signed-in owner or manager
of the shop, `staff` routes a signed-in owner or manager or a paired device, `device` routes a
paired device.

**Removing devices.** Owners and managers remove a device in the back office or from another
device (a device can't remove itself). Its tokens stop working at once, its live connection is
told and closed, and it stops syncing with a reason. Its row and sales stay. A pairing code can
bring it back with its own id and device code (`POST /api/devices/rejoin`), so its sales waiting
in its outbox still reach the hub.

## Consequences

- Owners and managers can run the shop from a browser without a terminal; the only secret they
  may need from the server is the setup code, which a hosted or PaaS deploy can set with
  `OPENKEDAI_SETUP_CODE`.
- Accounts live in the hub's registry rather than in a shop's file, because one person can run
  several shops. Moving a shop's file to another hub doesn't move its accounts; its owner signs
  in again with a code from a POS device.
- No email is ever sent: there is no mail server to configure, and the POS sign-in code covers
  password resets. Email-based resets and two-factor sign-in can come later.
- Sign-in on a shop LAN without HTTPS sends the password in the clear on that network, as device
  tokens are (ADR 0019). The hub guide recommends HTTPS for any hub reachable from the internet.