# Refactor guide: auth, registration, login UI, and user management

This document is the **implementation spec** for refactoring authentication. It replaces an earlier “as-is only” description with **ordered instructions** informed by [`auth-implementation-feedback.md`](./auth-implementation-feedback.md). Use it when changing **`fe0` login/registration UI** (`Login.tsx`, `AuthContext`, `auth-service`) and the supporting **`be0`** + **PostgreSQL** behavior.

---

## 1. Non‑negotiable: security

**Blocker:** The registration endpoint **`POST /api/v1/auth/register`** currently persists **`UserRoleRow(role=body.role)`** where `role` is **client-supplied**. That is **privilege escalation**: anyone who can call the API with a valid `@ump.edu.vn`-style address can send `"admin"` and become **Quản trị viên**. Email validation is not a substitute for server-side role authority.

**Instruction:** Before any cosmetic UI work, **stop trusting `role` from the client on register**. Derive roles **only** on the server (see §5). Treat closing this hole as **P0**; remaining items are hygiene by comparison.

---

## 2. Product rules (target behavior)

1. **Email domains:** `{name}@umc.edu.vn` **or** `{name}@ump.edu.vn` only (normalize: trim, lowercase; **server is authoritative**; client validation is UX only).

2. **Roles from identity (no user-facing role picker on login or register):**
   - A configurable set of emails maps to **Quản trị viên** (`admin` in `fe0/src/lib/permissions.ts`).
   - Every other allowed email gets **Người nộp đơn** (`viewer`) on **first registration**.
   - **Hội đồng** (`editor`) is **not** self-service: grant/revoke via **admin UserManagement** (API), not registration.

3. **User management:** Admins can **list** users and roles, **grant** Hội đồng, **revoke** it, and **deactivate** accounts as needed. The page must be **CRUD-capable from day one** (read-only listing alone is insufficient).

---

## 3. Current implementation (baseline to remove or replace)

### 3.1 Backend (`be0/src/auth_api.py`)

- **`_normalize_ump_email` / `UMP_EMAIL_RE`:** only `@ump.edu.vn` — **reject** `@umc.edu.vn` today.
- **Register:** inserts `User` + `UserRoleRow(role=body.role)` — **trusted client role (bug).**
- **Login:** returns `roles` from DB; **no** role in HTTP body — correct for API shape, but the **frontend** then forces a **role Select** and `buildUserWithSelectedRole(user, selectedRole)`, which **fails** if the user picks the wrong row. That is **not** “no role picker”; it is an **inverted** UX (identity should drive role; users should not see a selector).

### 3.2 Frontend

- **`fe0/src/pages/Login.tsx`:** `validateUmpEmail` — UMP only; **`loginRole` / `regRole`** Selects; register sends **`role`** in JSON.
- **`fe0/src/contexts/AuthContext.tsx`:** After login/register, **`buildUserWithSelectedRole(..., selectedRole)`** (and after register, **`payload.role`**) — **circular** with today’s register bug: client chooses → server stores → client “confirms” the same choice. After server-derived roles, this must become **trust `user.roles` from the API** (see §6).
- **`fe0/src/lib/auth-service.ts`:** Register payload includes **`role`** — remove once API ignores it.
- **`/dashboard/users`:** linked from `DashboardSidebar.tsx` / `admin/DashboardSidebar.tsx` but **no route** in `fe0/src/app/router/routes.tsx` → **404**.

### 3.3 Database

- **`user_role` enum** (`001_initiative_schema.sql`): `applicant`, `council_member`, `editor`, `admin`, `viewer` — **five values**; auth code only reads/writes **three**. Collapsing `applicant`↔`viewer` and `council_member`↔`editor` (or standardizing on one pair) is a **design decision** — do not leave five values with only three “real” forever (see §8).

### 3.4 JWT

- Roles are **embedded in the JWT** at issue time. If an admin **changes** `user_roles` in DB, the user sees new permissions only after **refresh** (or re-login). **Acceptable**, but: surface this in **UserManagement** or docs (e.g. “changes apply on next refresh”) and optionally trigger refresh after admin actions on the **same** browser session if you add that flow later.

---

## 4. Configuration: admin emails (avoid brittle hardcoding)

**Feedback:** Hardcoding the five institutional emails in source is brittle.

**Instruction:** Load the admin allow-list from **environment** (e.g. comma-separated `AUTH_ADMIN_EMAILS`) **and/or** a **seeded DB table** (e.g. `admin_emails` with audit columns). The server’s derivation logic must use **one** resolved list (env merged with DB, or DB only after migration — pick one approach and document it).

Frontend must **not** duplicate the list for **authorization**; at most duplicate **domain regex** for UX (§5.1).

---

## 5. Backend refactor instructions (`be0`)

### 5.1 Email allow-list

- Replace “UMP-only” normalization with a function that accepts **`@ump.edu.vn`** **or** **`@umc.edu.vn`** (same local-part rules as today unless product says otherwise).
- **Reject** everything else with **400** and a clear message.
- **Ship server change before or with** client regex update; server must stay correct if the client is bypassed.

### 5.2 Registration: derive role; ignore client `role`

- **Remove** `role` from the public contract **or** accept but **ignore** it (document deprecation); **never** insert `UserRoleRow` from the client.
- On register: if normalized email ∈ admin list → ensure **`admin`** in `user_roles` (and **not** `viewer`-only self-service for those accounts — product: admins are allow-listed); else → insert **`viewer`** only.
- **Do not** assign **`editor`** at registration.

### 5.3 Login and refresh: **mandatory** role reconciliation

**Feedback:** “Optionally reconcile on login” is too weak; **make it mandatory**.

On **every** `login` and **`refresh`** (and ideally before issuing JWT in those handlers):

1. **Admin by email rule:** If email ∈ admin list and user **lacks** `admin` → **add** `admin` row in `user_roles`.
2. **Removal:** If email **∉** admin list and user’s `admin` was **only** from the email rule → **remove** `admin`.  
   **Critical:** If you later add **`admin` grants via UserManagement** (not email-derived), you **must not** strip those when reconciling. Implement **one** of:
   - **Two sources of truth:** e.g. column `users.is_admin_by_policy BOOLEAN` vs `admin` from grants table; or
   - **Tag rows:** e.g. separate table `user_role_grants(source='email_policy'|'admin_ui')` before mutating; or
   - **Rule:** only auto-remove `admin` if it was created by the policy sync marker you define.

Document the chosen rule in code comments and in this doc.

3. **Default applicant:** If user has **no** `viewer` and is not only admin-only (decide product: admins also `viewer` or not), apply your migration policy — usually new users get `viewer`; existing users need a **data migration** (§8).

### 5.4 Rate limiting

- Add **basic rate limiting** on **`/auth/register`** (per IP or per email) once role assignment is fixed — still an unauthenticated write.

### 5.5 Admin API (read **and** write)

Minimum surface for a real UserManagement product:

| Method | Path (example) | Purpose |
|--------|----------------|---------|
| `GET` | `/api/v1/admin/users` | List users: id, email, full_name, roles[], is_active, … |
| `POST` | `/api/v1/admin/users/:id/roles` | Grant **Hội đồng** (`editor`) — body may specify role |
| `DELETE` | `/api/v1/admin/users/:id/roles/:role` | Revoke `editor` (and optionally other roles per policy) |
| `PATCH` | `/api/v1/admin/users/:id` | e.g. `is_active` — deactivate without deleting |

Protect with existing admin checks (e.g. JWT must include `admin`, `_require_admin_user` pattern in `be0/main.py`).

**Why writes matter:** Viewers never become Hội đồng via registration or the email list; without grant/revoke APIs, the UserManagement page is a **read-only museum**.

### 5.6 Password reset (self-service)

- **`POST /api/v1/auth/forgot-password`** — body `{ "email" }`. Email is normalized with the same institutional rules as register. For valid domains, the JSON response is **always** the same generic success message whether or not the account exists (**enumeration-safe**). Bodies **must not** carry `role` or any privilege field (models use `extra="ignore"`).
- **`POST /api/v1/auth/reset-password`** — `{ "token", "newPassword", "newPasswordConfirm" }`. One-time token stored only as a **hash** in `password_reset_tokens`, short TTL (see `be0/src/auth_api.py`).
- **Rate limiting:** forgot (per normalized email + per client IP) and reset (per IP), implemented in `be0/src/auth_rate_limit.py`.
- **Outbound mail:** configure **`SMTP_HOST`**, **`SMTP_PORT`** (default 587), **`SMTP_USER`**, **`SMTP_PASSWORD`**, **`AUTH_MAIL_FROM`**, **`SMTP_USE_TLS`** (default on), or use **`AUTH_MAIL_LOG_ONLY=1`** to log reset links (development). Set **`AUTH_PUBLIC_WEB_ORIGIN`** or **`PUBLIC_WEB_ORIGIN`** so email links point at the SPA (default `http://localhost:8081`).
- **JWT `cv` (credential version):** column `users.credential_version` increments on password **`/change-password`** and **`/reset-password`**; middleware in `be0/main.py` plus **`/auth/refresh`** reject tokens whose `cv` no longer matches. Apply **`be0/migrations/012_password_reset.sql`**.

Admins **do not** set plaintext passwords; a future “Gửi email đặt lại mật khẩu” in UserManagement should call the same forgot-password logic server-side.

---

## 6. Frontend refactor instructions (`fe0`) — login components

### 6.1 `Login.tsx`

**Remove:**

- All **`<Vai trò đăng nhập>`** / **`loginRole`** state and `Select`.
- All **`regRole`** state and registration **role** `Select`.
- Imports only used for role pickers (`ROLE_DISPLAY_NAMES`, role icons, extra `Select` pieces) — prune dead imports.

**Keep / adjust:**

- Email + password fields; copy should say **UMP or UMC** once regex allows both.
- Replace `validateUmpEmail` with something like `validateInstitutionalEmail` matching **both** domains (still **UX**; server validates for real).

**Behavior:**

- **`handleLogin`:** call `login(email, password)` **without** a role argument (update `AuthContext` signature — §6.2).
- **`handleRegister`:** call `register({ fullName, email, password, passwordConfirm })` **without** `role` (update types and `auth-service`).

**Post-login navigation:** Keep using `resolvePostLoginPath`, but pass the **resolved active role** from context (single derived role — §6.2), e.g. `resolvePostLoginPath(user.roles[0], fromPathname)` or a small helper `getPrimaryRole(user)`.

### 6.2 `AuthContext.tsx`

**`login`:** Change to `login(email, password)` only. After `authService.login`, build session user from **`result.user.roles` returned by the server** — **no** second argument from the UI.

**`register`:** Same: **no** `role` in payload; after success, **trust** `result.user.roles` from API.

**`buildUserWithSelectedRole`:** Refactor or replace:

- **Preferred:** `buildUserFromAuthPayload(authUser)` that sets **one** active role using a **deterministic rule**:
  - If multiple roles exist (e.g. `admin` + `editor`), use **highest privilege** (e.g. `admin` > `editor` > `viewer`) for `user.roles` / permissions in the shell, **or**
  - Keep `availableRoles` for a future **internal** switcher only if product requires it — but **not** on the login screen.
- **Remove** reliance on `localStorage['auth-active-role']` for **login/register** flows unless you keep it **only** for intentional in-app role switching between **already granted** roles (optional follow-up).
- Eliminate error paths like “wrong role selected” for login — users never select.

**Session restore (`refreshSession`):** Same as login: **no** client-selected role; apply the same deterministic mapping from API `roles`.

### 6.3 `auth-service.ts`

- **`register`:** Omit `role` from JSON body once API ignores it.
- Types: `AuthUser` unchanged if API still returns `roles: Role[]`.

### 6.4 Routes and UserManagement page

- Add a real route for **`/dashboard/users`** (or move link to **`/dashboard/admin/users`** and update sidebars consistently).
- Implement **`UserManagement`** with `ProtectedRoute` requiring **`admin.users`** (or equivalent): **table + actions** calling the admin API from §5.5.
- Plan the UI as **list + grant editor + revoke editor + deactivate** from **day one**.

### 6.5 Callers of `login` / `register`

- Grep for `login(` and `register(` across `fe0` (e.g. tests, `SignUpModal.tsx`) and update signatures.

---

## 7. Target data flow (after refactor)

```mermaid
sequenceDiagram
  participant UI as Login.tsx
  participant Ctx as AuthContext
  participant API as auth-service.ts
  participant BE as be0 auth_api
  participant DB as PostgreSQL

  Note over UI,DB: Register (no client role)
  UI->>Ctx: register({ fullName, email, passwords })
  Ctx->>API: POST /api/v1/auth/register (no role)
  API->>BE: body without trusted role
  BE->>BE: derive admin vs viewer from email list
  BE->>DB: INSERT users + user_roles (server only)
  BE-->>API: JWT + user.roles
  Ctx->>Ctx: buildUserFromAuthPayload(user)

  Note over UI,DB: Login (no role picker)
  UI->>Ctx: login(email, password)
  Ctx->>API: POST /api/v1/auth/login
  API->>BE: email + password
  BE->>DB: load user; reconcile policy roles
  BE-->>API: JWT + user.roles
  Ctx->>Ctx: buildUserFromAuthPayload(user)
```

---

## 8. Data migration and enum cleanup

**One-time migration** after fixing register:

- For each `users` row: if email ∈ admin list → ensure `admin` (per reconciliation rules); else if no explicit **editor** grant from admin tooling → normalize to **`viewer`** only as per product.
- **Existing `editor` rows:** **Preserve** as Hội đồng unless product says to wipe and re-grant.
- **Users who became `admin` via the old bug:** Migration should **align** with email policy: if not in admin list, **remove** spurious `admin` (with the same caution as §5.3 if you introduce UI-granted admin later).

**Enum (`applicant` / `council_member`):**

- Decide: **aliases** of `viewer` / `editor` vs **canonical** names.
- Ship a migration that **consolidates** rows and **narrows** the enum or renames consistently. Do **not** finish the auth refactor while five enum values exist but only three are meaningful.

---

## 9. Tests (mandatory for rules that regress silently)

Table-driven tests (Python **or** TS — preferably backend for authority):

- Each admin-configured email → effective roles include **`admin`** (after register and after login).
- `user@ump.edu.vn` (not admin) → **`viewer`** only.
- `user@umc.edu.vn` (not admin) → **`viewer`** only; invalid domain → **400**.
- Case and whitespace on email → **normalized** to same key as policy list.
- Register **ignores** injected `role: "admin"` in JSON for non-admin email (or rejects body field entirely).

---

## 10. Suggested order of work

Aligned with [`auth-implementation-feedback.md`](./auth-implementation-feedback.md):

1. **Fix register:** ignore client `role`; derive roles server-side (**closes privilege escalation**). Ship alone if needed.
2. **Allow `@umc.edu.vn`** on server, then update client regex/copy.
3. **Remove** login/register role selectors; simplify **`AuthContext`** / **`buildUserWithSelectedRole`** → **`buildUserFromAuthPayload`** with a deterministic multi-role rule.
4. **Implement admin API** (list + grant/revoke + patch `is_active`) with authz.
5. **Build UserManagement** page and **add** `/dashboard/users` route; fix sidebar 404.
6. **Data migration + enum cleanup.**
7. **Rate limiting** on register; **tests** from §9.

Steps **1–3** are mostly **deletion and server logic** on the login path. Steps **4–5** are the bulk of **new** code.

---

## 11. File index

| Area | File(s) |
|------|---------|
| Login / register UI | `fe0/src/pages/Login.tsx` |
| Session + role resolution | `fe0/src/contexts/AuthContext.tsx` |
| HTTP client | `fe0/src/lib/auth-service.ts` |
| Permissions / labels | `fe0/src/lib/permissions.ts` |
| Post-login paths | `fe0/src/lib/dashboardNavigation.ts` |
| Routes | `fe0/src/app/router/routes.tsx` |
| Sidebars (dead link) | `fe0/src/components/DashboardSidebar.tsx`, `fe0/src/components/admin/DashboardSidebar.tsx` |
| Auth API | `be0/src/auth_api.py` |
| Password reset mail + rate limits + JWT cv middleware | `be0/src/auth_mail.py`, `be0/src/auth_rate_limit.py`, `be0/src/auth_credential_middleware.py` |
| ORM / enum | `be0/src/initiative_db/models.py`, `be0/migrations/001_initiative_schema.sql` |
| Admin guard patterns | `be0/main.py` (`_require_admin_user`, etc.) |

---

## 12. Evaluation notes incorporated from feedback

| Topic | Handling in this refactor |
|-------|---------------------------|
| Client `role` on register | **Privilege escalation — fix first** |
| Login role Select | **Inverted spec — remove** |
| `buildUserWithSelectedRole` after register | **Circular — trust server `roles`** |
| Email allow-list “sharing” | **Server canonical**; duplicate small regex on client if needed |
| Reconcile on login | **Mandatory**, with **safe rule** for non-email admin grants |
| Admin emails in source | **Env or DB table** |
| Admin API | **Read + write** (grant/revoke/deactivate) |
| UserManagement UI | **CRUD from day one** |
| JWT staleness | **Document**; optional future refresh UX |
| Migration / enum | **Explicit steps** §8 |
| Rate limit register | **§5.4** |
| Tests | **§9** |