# Phase 3b·3 — User Management (Gebruikers) — Design

- **Created:** 2026-06-24
- **Status:** Approved (brainstorming) — ready for implementation plan
- **Tracker:** Plane (workspace `solelog`, project SoleLog)
- **Cycle:** Third and final Phase 3b cycle (completes the Phase 3 admin panel)
- **Touches:** `packages/shared`, `apps/api`, `apps/admin`

## Goal

An admin can manage the workplace logins: see every user with role + status, create a user,
change a user's role, reset a forgotten password, and deactivate/reactivate an account — without
ever losing production history. No self-service email reset exists (no mailer), so the admin
setting a password is the only recovery path.

_Done when:_ an admin can list users (with role + active/inactive status), create a worker or admin
who can then sign in, flip a user's role, reset a user's password (new works, old fails),
deactivate an account (sign-in blocked) and reactivate it — while the API refuses any action that
would lock out the admins (self-deactivate, self-demote, or removing the last active admin).

## Scope decisions (confirmed during brainstorming, 2026-06-24)

1. **Operations:** create, set role (worker ↔ admin), reset password, deactivate/reactivate.
   **No hard delete** — the `work_sessions` FK cascades, so deleting a user would wipe their logged
   history. Deactivation (better-auth `banned`) keeps the data and blocks sign-in.
2. **Lockout guards (server-side):** no self-deactivate, no self-demote, and a last-active-admin
   invariant — any demote/deactivate that would leave zero active admins is refused (400 + Dutch
   message).
3. **Password floor:** better-auth's default minimum of **8** characters for create + reset.

## A. Backend

### Small enabling refactor
Extract the inline admin gate (currently `adminRoutes.use('/api/admin/*', …)` in `routes/admin.ts`)
into a reusable **`adminGuard`** middleware in `lib/require-user.ts`:

```
export const adminGuard: MiddlewareHandler — 401 if no session, 403 if not admin, else next().
```

`admin.ts` swaps its inline guard for `adminRoutes.use('/api/admin/*', adminGuard)` (existing admin
tests cover it). The new user router uses the same middleware.

### New `routes/admin-users.ts` (own Hono router, mounted in `app.ts`, gated by `adminGuard`)
User management is a distinct responsibility and `admin.ts` already carries sessions + report +
export, so it gets its own file.

- **`GET /api/admin/users`** — **moved here from `admin.ts`** and enriched. Direct DB read of
  `user`, ordered by name, returning `{ id, email, name, role, status, created_at }` where
  `status` is `'inactive'` when `banned` is truthy else `'active'`, and `role` defaults to
  `'worker'` when null. The report/session pickers read only `id`/`name`, so they keep working.
- **`POST /api/admin/users`** — create. Body `CreateUserInput { email, name, password, role }`.
  Calls `auth.api.createUser({ body: { email, password, name, role } })` (hashes the password,
  generates the id + account row; works despite `disableSignUp`, as `seed.ts` already relies on).
  A duplicate email throws → mapped to **409** (`{ error: 'E-mailadres bestaat al.' }`). Returns the
  created user in the list shape.
- **`POST /api/admin/users/:id/role`** — body `SetRoleInput { role }`. Plain column update
  `db.update(user).set({ role }).where(eq(user.id, id))` (role is a `user` column; no better-auth
  call needed). **Guards** (below) run first. Returns the updated list item.
- **`POST /api/admin/users/:id/password`** — body `SetPasswordInput { password }`. Calls
  `auth.api.setUserPassword({ body: { userId: id, newPassword: password }, headers: <forwarded> })`
  (needs better-auth hashing). 404 if the user does not exist.
- **`POST /api/admin/users/:id/deactivate`** — plain update
  `db.update(user).set({ banned: true, banReason: null, banExpires: null })` **and**
  `db.delete(session).where(eq(session.userId, id))` so any live bearer token dies at the next
  `getSession`. The admin plugin already blocks banned users at sign-in. **Guards** run first.
- **`POST /api/admin/users/:id/reactivate`** — plain update
  `db.update(user).set({ banned: false, banReason: null, banExpires: null })`.

All write routes 404 on an unknown `:id`. The whole surface is behind `adminGuard` → 401 (no
session) / 403 (non-admin).

### Guards (helper in `admin-users.ts`, run before role/deactivate mutations)
Given the acting admin (`caller = await getSessionUser(c)`) and the target `id`:

- **Self-deactivate:** deactivate where `id === caller.id` → 400 `"Je kunt jezelf niet deactiveren."`
- **Self-demote:** role change to `'worker'` where `id === caller.id` → 400
  `"Je kunt jezelf niet degraderen."`
- **Last active admin:** for a demote (target currently admin → worker) or a deactivate of an admin,
  count active admins (`role = 'admin' AND (banned IS NULL OR banned = 0)`) **excluding the target**;
  if that count is 0 → 400 `"Er moet minstens één actieve beheerder blijven."`

Because the caller is always an active admin, the self-guards already guarantee ≥1 admin remains;
the last-admin check is explicit defense-in-depth and documents the invariant.

### Why direct-DB for role/status (not `auth.api`)
`role` and `banned` are ordinary `user` columns; updating them directly is version-proof and
trivially testable in-process. Only **create** and **reset-password** need better-auth (password
hashing), so only those go through `auth.api.*`. The exact `auth.api` method names + param keys are
verified against the installed better-auth version during implementation.

## B. Shared contracts (`@solelog/shared`)

- `UserStatus = z.enum(['active', 'inactive'])`.
- The user list shape gains `status: UserStatus` (extend the existing `AdminUser` schema, which is
  `id/email/name/role/created_at`, with `status`; if `AdminUser` is unused elsewhere, repurpose it as
  the list item — verified during planning).
- `CreateUserInput = { email: string().email(), name: string().trim().min(1),
  password: string().min(8), role: Role }`.
- `SetRoleInput = { role: Role }`.
- `SetPasswordInput = { password: string().min(8) }`.

No DB migration — `role`, `banned`, `banReason`, `banExpires` already exist on `user`.

## C. Admin UI (`apps/admin`)

- **`components/Sidebar.tsx`** — move `'Gebruikers'` into `navItems`
  (`{ to: '/gebruikers', label: 'Gebruikers' }`); `soonItems` is now empty, so **remove the
  "Binnenkort" block** entirely.
- **`App.tsx`** — add `<Route path="/gebruikers" element={<Users />} />`.
- **`screens/Users.tsx`** (Gebruikers): a row per user from `useUsers` — name, email, **role pill**
  (Beheerder/Werker), **status pill** (Actief/Inactief), created date. `+ Nieuwe gebruiker` opens the
  create form. Per-row actions: **Maak admin / Maak werker** (role toggle), **Reset wachtwoord**
  (reveals an inline password input + Opslaan), **Deactiveer / Heractiveer**. The signed-in admin's
  **own row** (matched via `useMe`) shows a "jij" badge with the role + deactivate actions hidden
  (password reset on self is allowed).
- **`components/UserForm.tsx`** — the create form: name, email, password, role `<select>`, with
  inline validation mirroring the API (email format, password ≥ 8). Submits `CreateUserInput`.
- **`api/users.ts`** — `useUsers` (`['admin','users']`, list shape) + mutations `useCreateUser`,
  `useSetUserRole`, `useResetUserPassword`, `useDeactivateUser`, `useReactivateUser` (all invalidate
  `['admin','users']`). The existing minimal `useAdminUsers` (in `admin-sessions.ts`) stays for the
  pickers.

## Error handling

- Duplicate email on create → 409 → form shows "E-mailadres bestaat al."
- Guard violations → 400 with the Dutch messages above → surfaced inline near the row/action.
- Short password → 400 → inline on the password field.
- Any better-auth error is caught and returned as a JSON `{ error }` (never a 500 stack).

## Testing

- **API** (`admin-users.test.ts`, in-process via `createApp()` + `app.request`):
  - `GET` returns role + status; worker token → 403.
  - create → the new user can sign in with the given password; duplicate email → 409; password < 8 →
    400; created user appears with the right role/status.
  - set role worker→admin and admin→worker (plain rows, verified in DB/readback).
  - reset password → sign-in with the new password succeeds and the old one fails.
  - deactivate → sign-in is blocked; the user's sessions are gone; reactivate → sign-in works again.
  - guards: self-deactivate, self-demote, and last-active-admin demote/deactivate each → 400 with the
    expected message; the action did not take effect.
- **Admin** (vitest + Testing Library):
  - Users renders a row per user with role + status pills.
  - `+ Nieuwe gebruiker` → create form posts `CreateUserInput`.
  - row actions (Maak admin, Reset wachtwoord, Deactiveer) call the right mutations with the right id.
  - the signed-in admin's own row hides the role/deactivate actions.

## Adversarial verification (ultracode)

After the build, a dedicated review agent independently scrutinizes the **lockout guards** and the
**create/ban auth wiring**: it tries to construct a sequence that reaches zero active admins, checks
that deactivate truly blocks sign-in (not just hides the UI), confirms the worker-token 403 gating on
every route, and verifies the tests actually exercise these paths rather than asserting trivially.
Findings are reported (not auto-applied); real holes get a follow-up fix task.

## Out of scope

- Hard delete; email-based password reset (no mailer); session/impersonation management beyond the
  deactivate-revokes-sessions behavior; bulk operations; editing a user's email/name after creation.

## Build approach

spec → `writing-plans` → one **Workflow** (~6 TDD tasks, sequential — dependent, shared tree —
commit per task) + a final adversarial security-review stage. Tracked as a Plane epic. Completes
Phase 3b and the Phase 3 admin panel.