Rework core integration: validated capability layer, docs, and session state

2026-09-11 14:09:04 +02:00
parent 2a15f057df
commit e62d3007d8
33 changed files with 1897 additions and 612 deletions
@@ -0,0 +1,63 @@
+# Authentication
+
+This document describes account login and token persistence.
+
+## QR login
+
+`poc/src/qr-login.ts` logs in to an account with a QR code. The tool connects to the Discord
+remote-auth gateway. It shows the QR code in the terminal. The user scans the code with the Discord
+mobile app. The tool then writes the account token to a file.
+
+```sh
+pnpm poc:qr
+TOKEN_FILE=/path/to/token pnpm poc:qr
+```
+
+The tool prints the QR code, the approval result, and the token file path. If Discord asks for a
+captcha, the tool shows the challenge and reads a key from `HCAPTCHA_KEY` or from the terminal.
+
+The flow was verified end-to-end on 2026-09-11.
+
+## Token file
+
+- Default path: `poc/.token`, relative to the `poc/` directory.
+- Override: `TOKEN_FILE`.
+- File mode: `600`.
+- The file is gitignored.
+- The token belongs to the puppet account. zzib is only the DM test target.
+
+## Client session persistence
+
+The client session is separate from the token file. The session lives in the Electron profile.
+
+The design has three parts:
+
+1. **Pinned profile directory.** `DATA_DIR` is `$VENCORD_USER_DATA_DIR`, else `$VESKSLOP_DATA_DIR`,
+   else `<appData>/veskslop`. The path does not depend on the app name. A rename or a version update
+   does not move the profile.
+2. **Token seeding.** On startup, the preload reads the token file through a synchronous IPC call.
+   The preload writes `localStorage.token` before the client boots. The seed happens only when no
+   session exists. `VESKSLOP_FORCE_TOKEN=1` overrides an existing session.
+3. **Recovery.** If Discord invalidates the session, run `pnpm poc:qr` again. Then update the token
+   file.
+
+The client stores the session in `<DATA_DIR>/sessionData`. A version update keeps the directory.
+
+## Devtools caution
+
+Discord deletes the stored token when it thinks that devtools opened. Vesktop already patches this
+detector in `src/renderer/patches/devtoolsFixes.ts`. Keep this patch. Without it, random logouts
+can occur.
+
+## Status
+
+| Part | Status |
+| --- | --- |
+| QR login and token file | Implemented and verified |
+| Pinned profile directory | Implemented and verified. Currently out of the tree after the CDP pivot. |
+| Token seeding | Implemented and verified. Currently out of the tree after the CDP pivot. |
+| Headless first-launch skip | Implemented and verified. Currently out of the tree after the CDP pivot. |
+| Devtools patch | Upstream Vesktop code. Keep it. |
+
+The three out-of-tree parts are small. Add them again with the core bridge, at the same time as the
+bridge hooks.