feat: support passwordless desktop sessions

[Soulter]

Summary

• add a hidden POST /api/v1/auth/desktop-session endpoint for desktop-managed runtimes
• require a per-process session secret and a loopback client before issuing a dashboard JWT
• suppress first-run password setup and password warnings only when desktop session authentication is active
• keep the existing username/password login flow unchanged

Why

The desktop WebUI can require a random initial password before the user has access to logs, and an expired dashboard JWT can leave users unable to recover if they no longer know that password. The desktop client already owns and launches the local backend, so it can safely establish a local session without exposing a general password bypass.

Security boundaries

• the endpoint is disabled unless ASTRBOT_DESKTOP_MANAGED=1 and a session secret are both present
• the secret is checked with constant-time comparison
• only loopback clients are accepted
• unauthorized callers receive no desktop JWT
• no refresh token or long-lived desktop credential is stored

Companion desktop PR

AstrBotDevs/AstrBot-desktop#166

Validation

• uv run ruff format .
• uv run ruff check .
• uv run pytest tests/test_desktop_runtime.py tests/test_dashboard.py -k desktop_session -q (7 passed)
• pnpm typecheck

Summary by Sourcery

Add passwordless desktop session authentication for desktop-managed backends, issuing short-lived dashboard JWTs only for loopback clients when a per-process session secret is configured, while keeping existing password-based login unchanged.

New Features:

• Introduce a hidden /api/v1/auth/desktop-session endpoint that issues dashboard JWTs for authenticated desktop-managed runtimes without requiring a password.
• Enable desktop runtimes to establish local dashboard sessions using a per-process session secret and loopback-only verification.

Enhancements:

• Suppress initial password setup, default-password warnings, and password-upgrade hints when desktop session authentication is active.
• Tag JWTs with an auth_source claim when generated from non-password authentication flows.
• Extend dashboard stats version responses to reflect that password warnings are disabled under desktop session authentication.

Tests:

• Add unit tests for desktop session secret handling, loopback client validation, and constant-time secret verification.
• Add dashboard API tests covering desktop session JWT issuance, rejection paths, endpoint visibility, and suppression of password setup and warning flags.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	astrbot-docs	48b5384	Commit Preview URL Branch Preview URL	Aug 07 2026, 07:51 AM

[sourcery-ai]

Hey - I've left some high level feedback:

• In AuthService.desktop_session you’re checking is_desktop_session_auth_enabled and is_loopback_client_host before calling verify_desktop_session_secret, which repeats those checks internally; consider consolidating the checks into one place (either in desktop_session or in verify_desktop_session_secret) to avoid drift and simplify reasoning about the security boundary.
• Given that auth_source is now a typed value in JWTs (e.g., "password" vs "desktop"), it may be worth centralizing those strings as constants or an enum-like structure to avoid typos and make future sources (e.g., SSO) easier to add consistently.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In `AuthService.desktop_session` you’re checking `is_desktop_session_auth_enabled` and `is_loopback_client_host` before calling `verify_desktop_session_secret`, which repeats those checks internally; consider consolidating the checks into one place (either in `desktop_session` or in `verify_desktop_session_secret`) to avoid drift and simplify reasoning about the security boundary.
- Given that `auth_source` is now a typed value in JWTs (e.g., "password" vs "desktop"), it may be worth centralizing those strings as constants or an enum-like structure to avoid typos and make future sources (e.g., SSO) easier to add consistently.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}