# 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