Add multi-user MAX authentication and tenant isolation

README.md

@@ -1,11 +1,11 @@
 # QMAX
 
-QMAX is a private Android messenger client backed by a personal bridge server. The Android app talks to your QMAX server, and the server uses PyMax as the only MAX bridge.
+QMAX is a multi-user Android messenger client backed by a self-hosted bridge server. Each Android user verifies a separate MAX account, while one QMAX server and one PyMax worker can serve all accounts.
 
 Current shape:
 
 - `server/QMax.Api` - ASP.NET Core API, SQLite cache, JWT pairing auth, SignalR hub, attachment storage, APK update catalog.
-- `pymax-worker` - Python/PyMax worker with a persistent MAX mobile API session.
+- `pymax-worker` - Python/PyMax worker with an isolated persistent MAX mobile API session per QMAX user.
 - `android` - Kotlin + Jetpack Compose Android client pointed at `https://qmax.kusoft.xyz`.
 - `deploy` - Docker Compose + Caddy for Raspberry Pi 5.
 
@@ -44,22 +44,15 @@ qmax.kusoft.xyz {
 Set strong values in `.env`:
 
 - `QMAX_JWT_SECRET` - at least 32 random characters.
-- `QMAX_PAIRING_CODE` - one-time-ish pairing password for your Android client and `/admin/max`.
-- `QMAX_MAX_PHONE_NUMBER` - the phone number linked to the MAX account used by PyMax.
+- `QMAX_PAIRING_CODE` - optional server registration code shared with allowed users; leave it empty for open registration.
 
 Secrets must stay in `.env`, not in git.
 
 ## MAX Login
 
-Open:
+On the Android login screen enter the QMAX server URL, the user's MAX phone number and, when configured, `QMAX_PAIRING_CODE`. QMAX asks PyMax to start MAX authorization. Enter the code delivered by MAX in the app; only after PyMax reports an authorized session does QMAX issue that user a JWT and refresh token.
 
-```text
-https://qmax.kusoft.xyz/admin/max?pairingCode=YOUR_PAIRING_CODE
-```
-
-Use **Start phone login**. When MAX sends the confirmation code, submit it on the same page or from the Android app settings.
-
-The worker stores PyMax session state in the `qmax-pymax-session` Docker volume, so the MAX session should survive restarts until MAX expires the login token.
+The worker stores sessions under `accounts/<QMAX user id>/` in the `qmax-pymax-session` Docker volume. Session files and imported-contact mappings are not shared between users.
 
 ## Android Pairing
 
@@ -73,7 +66,9 @@ cd android
 On first launch:
 
 - Server: `https://qmax.kusoft.xyz`
-- Code: `QMAX_PAIRING_CODE` from `.env`
+- Phone: the user's MAX phone number
+- Registration code: `QMAX_PAIRING_CODE` from `.env`, if the server owner configured one
+- MAX code: the confirmation code sent by MAX after the first step
 
 The first screen after pairing is the chat list.
 
@@ -128,13 +123,15 @@ https://argus.kusoft.xyz/api/apps/qmax/download/latest?platform=android&channel=
 
 The Android app checks this manifest, compares semantic versions, downloads the APK to a temporary file, verifies SHA-256, and only then opens Android's package installer.
 
-## Current MAX Mapping Status
+## Implemented MAX Mapping
 
-The deployed worker is authorized through PyMax and currently maps:
+The worker code maps:
 
 - chat list and message history through PyMax;
 - text sending through PyMax;
 - attachment upload through PyMax file/photo/video models;
 - image, video, file and voice attachment projection through the API;
 - Android image attachment caching with `.part` downloads before a file is shown from local storage;
-- explicit session status and phone-code re-login from Android settings.
+- explicit per-user session status and phone-code re-login from Android settings.
+
+An end-to-end login against the live MAX service was not run in this workspace; it must be verified on the target Raspberry Pi with real accounts.