1.9 KiB
Require Web Login Design
Goal
When a user opens the self-hosted Hoppscotch web frontend without an active session, the app must not be usable. The user should see only a login page until authentication succeeds.
Scope
- Applies only to the web shell in
packages/hoppscotch-selfhost-web. - Does not change the desktop shell behavior.
- Does not change backend authentication endpoints or session semantics.
- Reuses the existing Hoppscotch auth platform and login UI.
Architecture
The self-hosted web platform will register a root UI extension that acts as an
auth gate. The gate will subscribe to the existing platform.auth user stream
and render above the app only when the current platform is web and no confirmed
user exists.
The gate has three visible states:
- Auth check pending: show a centered spinner while
performAuthInit()verifies the cookie-backed session. - Anonymous: show a full-screen login-only page using the existing
FirebaseLogincomponent. - Authenticated: render nothing, allowing the normal Hoppscotch app to remain usable.
Data Flow
performAuthInit() already checks the backend session and updates
currentUser$. The auth gate must not perform its own token or cookie checks.
It only observes the existing stream, so login, logout, refresh, and local auth
continue to use the current implementation.
Route Behavior
The gate blocks interaction with normal app routes by covering the UI, not by
redirecting. This avoids changing common router behavior and avoids breaking
special routes such as /enter and /device-login, which use the empty
layout and are outside the normal application shell.
Testing
Add a focused unit test for the gate state logic:
- pending auth check requires the blocking screen;
- anonymous confirmed state requires the blocking screen;
- authenticated state does not block;
- desktop platform does not block.
Run the targeted test and a typecheck or lint command for the touched package.