docs: MQTT app-user auth reference + CLAUDE.md pointer

docs/mqtt-app-user-auth.md records what future sessions (and whoever builds
the phone app) need and can't get from the code alone:
- app connection contract: username app_<uid>, Firebase ID token as
  password, client id prefix app_<uid>_, TLS only, allowed topics per acc,
- serial field (serial_number, legacy device_id) and the device_serials
  mirror + every code path that must keep it in sync,
- the uid-field lookup rule and ACL cache invalidation,
- legacy "vesper" password flag and its log line,
- rollout checklist: backfill, go-auth VPS config (required/recommended),
  files-ACL check, TLS listener,
- decisions/gaps: FlutterFlow must sync device_serials itself; the
  device_users subcollection is intentionally ignored.

CLAUDE.md gets a short section pointing agents at it before they touch
MQTT auth or anything that edits user_list/status.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-09-30 00:45:18 +03:00
co-authored by Claude Opus 5.5
parent f5db83f26c
commit 6ea7e9d2c5
2 changed files with 154 additions and 0 deletions
+10
View File
@@ -365,6 +365,16 @@ used in a page must have a visible example there first.
---
## MQTT Auth (devices + phone-app users)
Read `docs/mqtt-app-user-auth.md` before touching `backend/mqtt/auth.py`,
`backend/mqtt/app_users.py`, or any code that changes a device's `user_list` or a
user's `status`. Any code that edits `user_list` must also update the user's
`device_serials` in the same batch and invalidate the MQTT ACL cache, or app users
lose (or keep) access to the wrong devices.
---
## API Client
```js