# 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` | Demo role selector + locale switcher; "Register organisation" / "Request registration" CTAs |

## 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 selects persona: Super User, HR Administrator, Finance Approver, Member.
2. Optional locale toggle (en/am).
3. "Continue as …" sets mock session and redirects to role-appropriate home.
4. Topbar profile menu includes "Switch demo user" → returns to `/login`.

Pre-seeded demo data: single mock org (`org_01DEMO`) 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