feat: upgrade toolchain and soften sync recovery after network blips
Bump Vite 8, matrix-js-sdk, and related deps; fix immer/vanilla-extract imports for new majors. Replace blocking sync error dialog with background recovery on wake/offline, and disable Vite auto-open in dev. Add feature handoff documentation index.
This commit is contained in:
97
docs/handoff/features/authentication/HANDOFF.md
Normal file
97
docs/handoff/features/authentication/HANDOFF.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# Authentication — handoff
|
||||
|
||||
## Summary
|
||||
|
||||
Auth covers login, registration, password reset, SSO, and server selection before the Matrix client starts. Sessions are persisted locally and restored on app launch via `ClientRoot`.
|
||||
|
||||
## User-facing behavior
|
||||
|
||||
- Pick homeserver (ServerPicker) or use default from config
|
||||
- Login: password, token, SSO redirect
|
||||
- Register: password-based with optional email flows
|
||||
- Reset password flow
|
||||
- Auth layout shows Paarrot branding
|
||||
- Device display name defaults to `Paarrot`
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Unauthenticated routes (AuthLayout)
|
||||
→ Login / Register / ResetPassword / SSOLogin
|
||||
→ session written to localStorage (sessions.ts)
|
||||
ClientRoot (authenticated)
|
||||
→ initClient(session) → startClient(mx)
|
||||
```
|
||||
|
||||
## Key files
|
||||
|
||||
| Path | Role |
|
||||
|------|------|
|
||||
| `cinny/src/app/pages/auth/login/Login.tsx` | Login hub |
|
||||
| `cinny/src/app/pages/auth/login/PasswordLoginForm.tsx` | Password login |
|
||||
| `cinny/src/app/pages/auth/login/TokenLogin.tsx` | Access token login |
|
||||
| `cinny/src/app/pages/auth/SSOLogin.tsx` | SSO redirect |
|
||||
| `cinny/src/app/pages/auth/register/Register.tsx` | Registration |
|
||||
| `cinny/src/app/pages/auth/register/PasswordRegisterForm.tsx` | Password register |
|
||||
| `cinny/src/app/pages/auth/reset-password/ResetPassword.tsx` | Password reset |
|
||||
| `cinny/src/app/pages/auth/ServerPicker.tsx` | Homeserver selection |
|
||||
| `cinny/src/app/pages/auth/AuthLayout.tsx` | Auth chrome + logo |
|
||||
| `cinny/src/app/pages/auth/login/loginUtil.ts` | Login helpers |
|
||||
| `cinny/src/app/pages/auth/register/registerUtil.ts` | Register helpers |
|
||||
| `cinny/src/app/state/sessions.ts` | Session storage |
|
||||
| `cinny/src/client/initMatrix.ts` | Client init from session |
|
||||
| `cinny/src/app/pages/afterLoginRedirectPath.ts` | Post-login redirect |
|
||||
|
||||
## Data model
|
||||
|
||||
| Key | Storage | Content |
|
||||
|-----|---------|---------|
|
||||
| Session store | localStorage | access token, user id, device id, hs url |
|
||||
| `setAfterLoginRedirectPath` | sessionStorage/memory | deep link target after login |
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `matrix-js-sdk` login/register APIs
|
||||
- Homeserver `.well-known` / login flows (`useParsedLoginFlows`, `useAuthFlows`)
|
||||
- OIDC/SSO via redirect URLs
|
||||
|
||||
## Integration points
|
||||
|
||||
- **Router**: unauthenticated vs `ClientRoot` split
|
||||
- **matrix-client**: `initClient` consumes session
|
||||
- **Device verification**: post-login verification UI in router
|
||||
|
||||
## Testing
|
||||
|
||||
### Manual
|
||||
|
||||
1. Login with password on test homeserver.
|
||||
2. Token login with valid access token.
|
||||
3. SSO flow if server supports it.
|
||||
4. Register new account; verify email if required.
|
||||
5. Logout clears session and returns to login.
|
||||
|
||||
### Automated
|
||||
|
||||
- None
|
||||
|
||||
## Known issues & gotchas
|
||||
|
||||
- `initial_device_display_name: 'Paarrot'` hardcoded in login/register forms
|
||||
- Session logout from server triggers full localStorage clear + reload
|
||||
- Server picker URL must match actual homeserver capabilities
|
||||
|
||||
## Future work
|
||||
|
||||
- Multi-account without full reload (see account-switcher)
|
||||
- Passkey / WebAuthn if upstream adds support
|
||||
|
||||
## Related docs
|
||||
|
||||
- [matrix-client HANDOFF](../matrix-client/HANDOFF.md)
|
||||
- [e2e-and-devices HANDOFF](../e2e-and-devices/HANDOFF.md)
|
||||
|
||||
## Add your extra things here
|
||||
|
||||
- Auth routes: `LOGIN_PATH`, `REGISTER_PATH`, `RESET_PASSWORD_PATH` in `paths.ts`
|
||||
- `UnAuthRouteThemeManager` vs `AuthRouteThemeManager` in ThemeManager.tsx
|
||||
Reference in New Issue
Block a user