Document Discord sign-in on ProvinceSystem branch previews

projects/ProvinceSystem/DEPLOY.md

@@ -29,8 +29,11 @@ the `ps-preview-router` Caddy container (`127.0.0.1:8090`, behind the `*.tfminec
   `dependabot/**` branches are skipped.
 - **Data:** the first `up` copies the dev backend's data, input, defines and output folders, with sign-in sessions,
   OAuth states and link codes deleted. A redeploy of the same branch keeps its data.
-- **Environment:** only `SKINS_DEV=1`, `SITE_PUBLIC_URL` and random `STAFF_KEY`/`PLUGIN_KEY`. Discord sign-in, Patreon,
-  CoreProtect and patch notes are off, so signed-in and staff pages cannot be tried on a preview.
+- **Environment:** only `SKINS_DEV=1`, `SITE_PUBLIC_URL` and random `STAFF_KEY`/`PLUGIN_KEY`, plus
+  `SIGN_IN_SITE=https://dev.tfminecraft.net` built into the backend image. Patreon, CoreProtect and patch notes are off.
+- **Sign-in:** Discord sign-in goes through dev, which needs `PREVIEW_SIGN_IN_DOMAIN=tfminecraft.net`, and keeps the
+  dev account's role ([Branch previews](docs/identity/auth-security.md#branch-previews)). A player signed in on dev
+  usually skips Discord.
 - **Access:** public, with `X-Robots-Tag: noindex, nofollow`.
 - **Limits:** at most four previews at once (`up` exits 3); backend 2 GB / 1.5 CPU, frontend 1 GB / 1 CPU.
 - **Lifetime:** each `up` sets the expiry to 90 minutes later; `ps-preview-reap.timer` runs `reap` every minute.

projects/ProvinceSystem/docs/identity/auth-security.md

@@ -46,6 +46,35 @@ Some answers pause every check:
 asked, and "I've joined, check again" falls back to a Discord sign-in.
 Source: [`guild_check.py`](https://github.com/TF-Minecraft/ProvinceSystem/blob/main/backend/src/auth/guild_check.py).
 
+### Branch previews
+
+Discord returns players only to registered callbacks, so a preview at
+`https://<slug>.tfminecraft.net` signs in through dev instead
+([`preview_sign_in.py`](https://github.com/TF-Minecraft/ProvinceSystem/blob/main/backend/src/auth/preview_sign_in.py)).
+Preview images set `SIGN_IN_SITE=https://dev.tfminecraft.net` and hold no Discord settings.
+Dev sets `PREVIEW_SIGN_IN_DOMAIN=tfminecraft.net`.
+
+1. The preview's `/auth/discord/start` stores a random state in its state cookie and
+   sends the browser to dev's `/api/auth/preview/start` with the state, the preview's
+   origin and the return path.
+2. Dev accepts only `https://<slug>.<PREVIEW_SIGN_IN_DOMAIN>` origins whose slug is not
+   reserved. Without a dev session, it signs the player in with Discord and Discord's
+   callback returns them to that route.
+3. Dev refreshes the session's guild check with the bot. If the bot cannot answer and
+   the check is over 15 minutes old, or the preview asked for a recheck because the
+   player was already signed in there ("I've joined, check again"), dev signs the
+   player in with Discord again. It then
+   stores a hashed single-use ticket for that preview (120 seconds) and redirects to the
+   preview's `/api/auth/preview/callback`. Access logs drop the query on both routes.
+4. The preview checks the state against its cookie, then posts the ticket and its
+   origin to dev's `/api/auth/preview/redeem`. Dev deletes the ticket and returns the
+   Discord identity, website role and guild check.
+5. The preview opens its own session with that role and check.
+
+A player already signed in on dev skips Discord unless the bot cannot answer one of
+those checks. The preview never sees the dev session
+or the Discord secret, and its changes stay in its own copy of dev's data.
+
 ## Microsoft link
 
 Signed-in players can link Minecraft by signing in with Microsoft instead of