# Feature: Auth & roles

Demo login with role selector, session management, and role-filtered navigation.

**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`

## Pages

| Route | Purpose |
|-------|---------|
| `/login` | Yimaru-style split login; **test-user dropdown** (demo personas) + locale switcher; register/join CTAs |
| `/profile` | Own account — see [profile.md](profile.md) |

## Roles

| Role | Nav sections |
|------|--------------|
| `SUPER_USER` | All — Organisation, Departments, Migration, Members, Packages, Finance, Settings |
| `HR_ADMIN` | Organisation, Departments, Migration, Members, Packages, Settings |
| `FINANCE` | Finance, Statements (read org summary) |
| `MEMBER` | Me, Orders, Prescriptions |

## Entities

- [`SessionUser`](../backend/entities/session-user.md)

## Endpoints

- [`auth.md`](../backend/endpoints/auth.md)
  - `POST /v1/auth/login`
  - `POST /v1/auth/logout`
  - `GET /v1/auth/me`
  - `GET /v1/auth/demo-profiles`

## Demo login UX

1. User picks a **test user** from the dropdown (not only a role): Selam Super, Hanna HR, Fikru Finance, Abebe Member.
2. Optional locale toggle (en/am) on the login panel.
3. Continue sets session via `loginAsUser(id)` and redirects to that user’s home path.
4. Topbar menu: Profile → `/profile`; "Switch demo user" → `/login`.
5. Multi-role demo (`user_super`) can switch active role on `/profile`.

Pre-seeded demo data: single mock org (`org_yaltopia` / Yaltopia) with realistic members, packages, spend.

## Route guards

Middleware or layout checks:

| Check | Behavior |
|-------|----------|
| Unauthenticated | Redirect to `/login` |
| MEMBER on `/finance` | 403 → member home |
| HR on `/prescriptions/:id` clinical | Withhold / redirect |
| Pending org | Block `/members`, `/packages` (active), migration commit |

## Clinical withhold

Enforced at API mock layer and UI:

- HR_ADMIN / FINANCE menus exclude Prescriptions clinical views.
- SUPER_USER sees all nav items including member Rx support paths.

## Validation / errors

| Scenario | Code |
|----------|------|
| Invalid demo role | `VALIDATION_FAILED` |
| Expired session | `UNAUTHENTICATED` |

## Mock implementation notes

```
src/mocks/auth.ts       — demo profiles + session
src/lib/api/auth.ts     — adapter
src/types/session.ts    — SessionUser type
```

## Related

- [i18n.md](i18n.md) — locale on login
- [org-registration.md](org-registration.md) — public CTAs from login