74 lines
2.9 KiB
Markdown
74 lines
2.9 KiB
Markdown
# 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.
|
|
|
|
## Web UI login
|
|
|
|
The web UI Login tab runs the same session (`poc/src/qr-session.ts`). See [webui.md](webui.md).
|
|
|
|
- `POST /api/auth/qr` starts the session. `GET /api/auth` returns the state and the QR image.
|
|
- On success the token is written to the token file. A running managed core restarts with
|
|
`VESKSLOP_FORCE_TOKEN=1`, so the new account takes effect.
|
|
- A captcha challenge shows the sitekey. Paste the hCaptcha response token to finish.
|
|
- The API never returns the token.
|
|
|
|
To log in a second account, set a different `TOKEN_FILE` for the daemon (and thus the spawned core)
|
|
and restart the daemon. One daemon manages one account at this time.
|
|
|
|
## 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 live |
|
|
| Pinned profile directory | Implemented and verified live |
|
|
| Token seeding | Implemented and verified live |
|
|
| Headless first-launch skip | Implemented and verified live |
|
|
| Devtools patch | Upstream Vesktop code. Keep it. |
|