# 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. |