geocrop-platform./apps/nextgen/.harness/changelogs/2026-07-22-user-roles.md

2026-07-22 — Phase 1 PR 1: auxiliary roles (thin slice)

Branch: feature/admin-cohorts-2026-07-22 Owner: fchin Scope: auxiliary role grants + class covers + parent-as-staff UI

What landed

Schema

• New user_roles table (Knex migration 2026072200000010_user_roles.js):
  • 19 supported role values
  • Optional scope (scope_class_id, scope_subject_id, scope_cohort_id)
  • Time-bounded grants (starts_at, expires_at)
  • Revocation audit (revoked_at, revoked_by, revoke_reason)
  • Standard sync columns
  • Active-grant unique partial index
  • Covering index for the getEffectiveRolesForUser hot path

Backend

• server/src/utils/rbac.js — new RBAC helper module:
  • getEffectiveRolesForUser(userId) — reads user_roles + users.role, returns the union
  • getEffectiveRoles(user) — reads from JWT payload (O(1))
  • hasRole(user, role) — O(1) string check
  • hasRoleForClass(user, classId, role) — checks class-scoped grants + form-tutor + admin
  • getActiveCovers(classId, date?) — covers query used by the class detail UI
  • requireRole(role), requireRoleForClass(role, fromPath) — express middleware
• server/src/controllers/userRoles.controller.js — new controller:
  • GET /api/users/:id/roles — list grants (active + revoked)
  • POST /api/users/:id/roles — grant (admin only, audit-logged)
  • PUT /api/user-roles/:id — update expires_at / reason (admin only)
  • DELETE /api/user-roles/:id — soft-revoke (admin only, audit-logged)
  • GET /api/user-roles/active-covers?class_id=&date= — covers query
• server/src/index.js modifications:
  • Login now embeds effective_roles in the JWT payload and the user response
  • New GET /api/auth/refresh-roles re-signs the JWT with the latest effective roles
• server/src/controllers/attendance.controller.js:
  • New canMarkForClass(req, classId) helper using the new RBAC module
  • POST /api/attendance now rejects when a teacher tries to mark attendance for a class they don't own (no class-scoped grant)
• server/src/services/SyncEngine.js:
  • user_roles appended to tablesToSync after users (FK dependency)

Frontend

• client/src/store/auth.ts:
  • User interface now has effective_roles: string[]
  • New refreshRoles() action calls /api/auth/refresh-roles
  • New hasEffectiveRole(user, role) helper for route gating
• client/src/store/userRoles.ts — new Zustand store with fetchUserRoles, grantRole, updateGrant, revokeGrant, fetchActiveCovers
• client/src/components/RoleBadge.tsx — new component, shows primary role + auxiliary roles
• client/src/components/CoverAssignmentForm.tsx — new modal, supports cover and auxiliary modes
• client/src/components/ParentViewToggle.tsx — new component, parent-as-staff toggle in the user menu
• client/src/pages/admin/UserRoles.tsx — new admin page for managing grants
• client/src/App.tsx:
  • ProtectedRoute now checks effective_roles (falls back to user.role for old JWTs)
  • AppLayout calls refreshRoles() once per auth session on mount
  • New route /admin/user-roles registered for school_admin + systems_admin
• client/src/components/Nav.tsx:
  • New Auxiliary Roles nav entry for admins
  • Default-nav picker prefers an effective role that has a NAV_CONFIG entry
  • RoleBadge rendered next to the user name
  • ParentViewToggle mounted above the action buttons

Docs

• AGENTS.md — updated team section (fchin / Arthur / Craig) and Knex framework note (was stale)
• .harness/plans/2026-07-22-phase1-cohorts-assignments.md — full Phase 1 plan
• .harness/plans/2026-07-22-phase2-analytics.md — Phase 2 plan (deferred)
• .harness/plans/2026-07-22-phase3-offboarding.md — Phase 3 plan (deferred)
• .harness/plans/2026-07-22-cohorts-assignments-analytics-offboarding.md — superseded 7-feature draft, kept for paper trail

How to verify

1. cd server && npm install && npm run db:init — applies the new migration
2. Login as admin@school.com / admin123 — JWT payload now contains effective_roles: ['school_admin']
3. Open /admin/user-roles — pick a user, grant a librarian auxiliary role. The right-pane list updates.
4. Open /library in a new tab — the librarian page now loads (previously forbidden for non-librarians)
5. From /admin/user-roles, grant a teacher an unscoped librarian grant. Sign in as that teacher — the role badge in the user menu shows "Librarian +"
6. Grant a class cover: pick a teacher, click "Class Cover", pick a class, set expires_at to today + 1 day. The cover appears in the list.
7. Sign in as the covering teacher. The class detail page (when PR 3 lands) will show "currently covering" — for now, the change is visible in the JWT.

What it does NOT do (deferred to follow-ups)

• Does NOT migrate any other controller's req.user.role check to the new hasRole helper. That's the "incremental RBAC migration" follow-up. Only attendance.controller.js adopts the new pattern this PR.
• Does NOT add a "former staff" or "alumni" page (those are Phase 3).
• Does NOT add CSV export of grants (manual JSON dump for now).
• Does NOT auto-prune expired user_roles rows. The RBAC check filters them out at read time; a daily cleanup is a follow-up.
• Does NOT change the existing users.role CHECK constraint — the primary role stays the same.

Risk register

• JWT shape change: existing JWTs without effective_roles still work (fallback to user.role everywhere). Refresh on app load picks up the new shape within one client cycle.
• Offline path: refreshRoles is a no-op when offline. The PWA continues to use the last-known effective_roles. The SyncEngine will sync user_roles rows so they're available when the user comes back online.
• One controller touched: only attendance.controller.js adopts the new pattern. All other controllers keep their existing req.user.role checks. This is the deliberately thin slice.