Human Roles, Responsibilities & Accessibility

Hierarchy

Two ranking axes: rank (strict numeric ordering — a role can only act on roles strictly below it) and canManage (a separate gate on whether the role has any management authority at all).

Researcher & auditor sit above instructor in rank so an instructor cannot demote them — but canManage:false keeps them out of the management chain entirely. They observe; they don't manage.

Three identity layers — never collapse

Per docs/role-capabilities.md §1.1, every authenticated session carries three identity fields. Each governs a distinct set of decisions; do not collapse them.

Two distinct gating systems

The codebase enforces permissions through two parallel layers. Don't confuse them.

canManageUser({ actorRole, isAdmin }, target, newRole)
canViewUser  ({ actorRole, isAdmin }, target)
subordinatesOf(role, { isAdmin })

// server/middleware/auth.js
requireRole('instructor', 'coord', 'admin')
requireAdmin

Where role checks actually live

Permissions are enforced in four distinct layers. A request typically passes through several of them before producing a response.

Server route guards · full inventory

Every Express route guard currently active in the server, in dependency order.

Sidebar & route allow-lists

From client/src/config/sections.js. Two concerns are now separated:

• Access (roles) — who can navigate to / render this view. Used by canAccessRole(), the route gate in App.jsx.
• Rail (sidebarFor, optional) — which roles get this view as a top-level entry in the left sidebar. sidebarFor: [] means drill-down-only (e.g. Essay Deep-Dive opens from an Inbox row, not the rail). When omitted, rail visibility follows roles.

Group order follows the production loop and role hierarchy: Overview · Writing · Mentoring · Rubrics · Grading · Integrity · Pedagogy · Formats · Data & Research · People · Governance · Account. Within each group, items are ordered by workflow or by breadth-of-audience.

Per-role rail (what each role actually sees)

Each non-inspector role gets a tight rail of primary entries — secondary tools (revision history, OCR, similarity detection, etc.) live inside the surface where they're used, not the rail.

The fine-grained capability matrix

Capability legend

✓ allowed ✗ forbidden — not meaningful ⚠ allowed with constraint

Sample area · Rubric (8 of 11 capabilities)

To give you the flavour — see docs/role-capabilities.md §3 for the full 8-area matrix (Rubric · Submission & grading · Calibration · Integrity · Pedagogy · Data & Research · Governance · Cross-cutting).

Notable: rubric:approve-curated is the only column where auditor has ✓ and admin has ✗ — the curated tier is gated on external review, not internal authority. rubric:promote-curated is a propose action; the approve must follow.

How a request flows through the gates

For an authenticated request (Bearer … header):

1. attachUser (middleware/auth.js) — verifies Bearer against the OAuth gateway (or dev-bearer table), reads the GCS profile, builds req.user = { uid, email, isAdmin, activeRole, storedRole, tenantRoles, tid }.
2. auth — 401 if no req.user. Mounted at app.use('/api', auth), after the public routers.
3. Optional requireRole(...) / requireAdmin — 403 if activeRole not in the allowed set.
4. In-handler logic — isInstructorish filtering, ownership checks, scope filtering (e.g. listUsersFor returns only outranked users via canViewUser).
5. xAPI emission — every state-change emits a statement; 403 emits denied, 5xx emits errored via logBug.

Practical FAQ

References

• server/lib/roles.js — role hierarchy, canManageUser, canViewUser, subordinatesOf.
• server/lib/users.js — GCS profile read/write, setUserRole, actorCapabilities.
• server/middleware/auth.js — attachUser, auth, requireRole, requireAdmin.
• client/src/config/sections.js — sidebar visibility allow-lists.
• docs/auth-and-roles.md — user-management contract (the layer this page describes).
• docs/role-capabilities.md — feature-capability spec (the matrix that is not yet implemented).
• CLAUDE.md — auth gateway, bug LRS, GCS layout, architecture invariants.