Max Litruv Boonzaayer
e058165830
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.
98 lines
3.2 KiB
Markdown
98 lines
3.2 KiB
Markdown
# 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
|