Veskslop-t/docs/auth.md

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.

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.

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