Skip to content

Replace API secret login with first-run password flow#2

Merged
zhaiiker merged 1 commit into
mainfrom
fix/web-migration-cleanup-vps-ready
May 18, 2026
Merged

Replace API secret login with first-run password flow#2
zhaiiker merged 1 commit into
mainfrom
fix/web-migration-cleanup-vps-ready

Conversation

@zhaiiker
Copy link
Copy Markdown
Owner

User-facing change: the management secret no longer surfaces in the UI. On first launch the backend boots into 'first-run' mode and the web UI shows a 'create administrator password' screen (>=8 chars). After that, returning visitors see a normal password login. Both screens exchange the password for a long-lived management secret which the SPA caches in localStorage and sends as Authorization: Bearer.

Backend

  • Add public /v0/management/auth/{status,setup,login} routes plus an authed /change_password endpoint. Setup and login are rate limited per remote address (10 attempts / 60s) and password hashing uses scrypt with a per-install random salt.
  • managementAuthMiddleware now lets the public auth paths through unauthenticated; the global enable check in proxy/server.ts does the same so first-run still works when the API is otherwise disabled.
  • Extend ManagementApiConfig with firstRunCompleted, passwordHash, passwordSalt and passwordSetAt; the password fields are redacted by the config GET endpoint alongside the secret itself.
  • Default management API to enabled with firstRunCompleted=false so a fresh install lands on the setup screen automatically.
  • backend/index.ts no longer auto-generates a secret on first boot; it prints a 'first run detected' banner instead and still honours the CHAT2API_MANAGEMENT_SECRET escape hatch for headless setups.

Frontend

  • ApiService.auth.{status,setup,login,changePassword} added.
  • The 401 handler in the response interceptor now ignores /auth/* so a failed login no longer blows away other state.
  • Rewrite AuthProvider as a small state machine (loading / firstRun / login / authenticated / offline) that talks to ApiService.auth. The cached secret is validated against /config on boot.
  • New PasswordSettings card surfaced under Settings - Security so the operator can change the password (and optionally rotate the secret) later without leaving the UI.

Docs: DEPLOYMENT.md updated to describe the new first-run flow.

User-facing change: the management secret no longer surfaces in the UI.
On first launch the backend boots into 'first-run' mode and the web UI
shows a 'create administrator password' screen (>=8 chars). After that,
returning visitors see a normal password login. Both screens exchange
the password for a long-lived management secret which the SPA caches
in localStorage and sends as Authorization: Bearer.

Backend
- Add public /v0/management/auth/{status,setup,login} routes plus an
  authed /change_password endpoint. Setup and login are rate limited
  per remote address (10 attempts / 60s) and password hashing uses
  scrypt with a per-install random salt.
- managementAuthMiddleware now lets the public auth paths through
  unauthenticated; the global enable check in proxy/server.ts does the
  same so first-run still works when the API is otherwise disabled.
- Extend ManagementApiConfig with firstRunCompleted, passwordHash,
  passwordSalt and passwordSetAt; the password fields are redacted by
  the config GET endpoint alongside the secret itself.
- Default management API to enabled with firstRunCompleted=false so a
  fresh install lands on the setup screen automatically.
- backend/index.ts no longer auto-generates a secret on first boot; it
  prints a 'first run detected' banner instead and still honours the
  CHAT2API_MANAGEMENT_SECRET escape hatch for headless setups.

Frontend
- ApiService.auth.{status,setup,login,changePassword} added.
- The 401 handler in the response interceptor now ignores /auth/* so a
  failed login no longer blows away other state.
- Rewrite AuthProvider as a small state machine (loading / firstRun /
  login / authenticated / offline) that talks to ApiService.auth. The
  cached secret is validated against /config on boot.
- New PasswordSettings card surfaced under Settings - Security so the
  operator can change the password (and optionally rotate the secret)
  later without leaving the UI.

Docs: DEPLOYMENT.md updated to describe the new first-run flow.
@zhaiiker zhaiiker merged commit 8026fc2 into main May 18, 2026
@zhaiiker zhaiiker deleted the fix/web-migration-cleanup-vps-ready branch May 20, 2026 04:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants