rootnode-academy/docs/PHASE5A_STUDENT_IDENTITY_REMOTE_CLASSROOM.md

# Phase 5A — Student Identity & Remote Classroom

**Status: PHASE 5A COMPLETE. STUDENT IDENTITY COMPLETE. REMOTE CLASSROOM FOUNDATION COMPLETE.**

Phase 4.1 closed the last pre-production infrastructure gap without real hardware. Phase 5A's
job — still without real hardware — was the last real *product* gap flagged along the way: pilot
students identify themselves by picking a name from a list, and there was no way for an
instructor to run a live, remote-capable class through the platform itself. This phase replaces
pilot identification with real accounts and adds a remote classroom control center. It does
**not** add video, voice, chat, or any A/V — those stay Meet/Zoom/Teams's job; RootNode owns
identity, presence, curriculum guidance, Lab status, help requests, and instructor control.

## 1. Student identity model

`students` (migration `017_student_credentials.sql`) gained `email`, `login_identifier`,
`password_hash`, `last_login_at`, and a single credential-token triple
(`credential_token_hash`/`_purpose`/`_expires_at`) — all nullable, all additive. `email` and
`login_identifier` are independently unique (partial unique indexes, `WHERE ... IS NOT NULL`)
and both optional: an older/self-paced student gets an email, a younger instructor-managed
student gets an instructor-assigned login ID, neither is required, and nothing here blocks a
future `guardian_id` FK for a Parent Portal — deliberately not built this phase (§37).

A student with **neither** field set is unchanged from before Phase 5A: a plain pilot row,
identified with `POST /api/login { student_id }`. Setting either field (via account creation or
`/convert`) is what makes an account "real." `password_hash` reuses `platform/api/src/auth/
password.js` (scrypt, `salt:hash`) verbatim — the same function instructors use, no second
hashing scheme.

## 2. Credential lifecycle — one token mechanism, not two

Activation ("first login") and password reset are the same problem: a time-limited, single-use
secret that lets someone set a new password. `students-auth.js`'s `issueCredentialToken`/
`consumeCredentialToken` implement it once (SHA-256-hashed at rest, plaintext returned exactly
once in the API response, never logged), with `purpose` (`activation` | `reset`) distinguishing
the two callers. Activation tokens live 7 days, reset tokens 1 hour. `consumeCredentialToken` is
atomic: token verification, password hashing, `password_hash` write, and token-clearing happen
in one statement — there is no window where a token is "spent" but the password isn't set.

Instructors never see or choose a student's password (§5's "instructor creates account →
temporary credential" flow): `POST /api/admin/students`, `/convert`, and `/reset-password` all
return a token (activation or reset), which the instructor relays out of band (printed, read
aloud, handed over). The admin UI surfaces the resulting `?activate=<token>`/`?reset=<token>`
link once and never again — there is no "view credentials" screen anywhere.

## 3. Password reset without email delivery

No email-sending infrastructure exists yet, and this phase deliberately doesn't fake one.
`POST /api/student/request-password-reset` always returns an identical generic response
regardless of whether the identifier exists (anti-enumeration) and never echoes the token in
production. In non-production (`isProduction` false, i.e. `COOKIE_SECURE !== '1'`) it also
returns `dev_reset_token` so local/CI flows can complete the loop without a real inbox — a
documented dev/test path, not a production feature. The realistic production path today is
instructor-triggered: `POST /api/admin/students/:id/reset-password`. Real email delivery is a
named, not-yet-built follow-up, not something silently promised.

## 4. Session and login security — reused, not duplicated

Students and instructors share the exact same `sessions` table and mechanism
(`sessions.js`: opaque tokens, HttpOnly, SameSite, hashed at rest, revocable), differentiated
only by `session_type`/`student_id` vs `instructor_id`. `studentSession` middleware now
re-verifies `status = 'active'` on **every** request (previously only checked session
existence) — deactivating a student takes effect immediately, matching `instructorSession`'s
existing behavior, not just at next login (verified in `e2e-phase5a.js`).

Rate limiting reuses Phase 4.1's Postgres-backed `tooManyAttempts` (`security.js`) with a
`student:` key prefix — 8 attempts / 5 minutes, survives a Platform API restart because it's a
table, not an in-memory Map (verified with a real restart in both `e2e-phase5a.js` and the
rehearsal drill). CSRF reuses the existing double-submit cookie pattern (`rn_csrf_s`).

**A real bug this closed:** the legacy `POST /api/login` (bare `student_id`, no password) only
checked `password_hash` to decide whether an account had "moved on" from pilot mode. An account
mid-conversion — instructor has issued an activation token, student hasn't set a password yet —
has `credential_token_hash` set but `password_hash` still `NULL`, and was reachable through the
old insecure path for that whole window. Found via testing, fixed by checking
`student.password_hash || student.credential_token_hash` instead (`server.js`).

## 5. Pilot migration

No destructive migration. `017_student_credentials.sql` only adds nullable columns — every
existing pilot row, its progress, attempts, achievements, and cohort membership are completely
untouched at migration time. `POST /api/admin/students/:id/convert` assigns email/login_
identifier and issues an activation token without touching `student_id` (the FK every other
table hangs off of) or anything downstream of it. Verified directly, not just asserted: the
Phase 5A rehearsal drill (`infra/scripts/drills/test-phase5a-rehearsal.js`) seeds real pre-
existing progress/attempt/achievement rows for a pilot student, converts them, activates them,
logs in the new way, and confirms `/api/progress` shows the exact same completed scenario —
nothing orphaned, nothing re-created.

## 6. Remote classroom — a fourth session concept

Distinct from cohort membership, assessment sessions, and Lab environments: a scheduled,
bounded teaching event. `018_classroom_sessions.sql` adds `classroom_sessions` (lifecycle
`scheduled → live → ended`, or `cancelled`), `classroom_participants`, `classroom_events`
(append-only audit), `classroom_announcements`, and `help_requests`. A partial unique index
(`WHERE status = 'live'`) enforces at most one live classroom per cohort at the database level —
the app layer catches the resulting `23505` and returns a clean `ALREADY_LIVE` (409), not a
raw constraint error (verified in `e2e-phase5a.js`).

## 7. Presence — derived, not stored

`classroom.derivePresence(lastSeenAt, leftAt)` is a pure function computing `online` /
`recently_active` / `offline` from a timestamp at read time — there's no status column that can
go stale or need a background job to sweep. Heartbeats (`POST /api/classroom/:id/heartbeat`,
client fires every 20-30s while the Classroom tab is open and joined) are throttled server-side
(`WHERE last_seen_at IS NULL OR last_seen_at < now() - interval`), never depend on Lab terminal
activity, and stop the moment the tab is closed or the student leaves — no invasive tracking.

## 8. The classroom dashboard — real data, not a second state system

`GET /api/admin/classroom-sessions/:id` is the one place that reaches beyond `classroom.js`: it
joins participant/presence data with the Provisioner's actual `environments` state (same enum
every other Lab-status view uses — `none`/`requested`/`provisioning`/`running`/`resetting`/
`error`/`destroying`/`destroyed`) and a lightweight academic snapshot from the existing
`progress`/`scenario_attempts` tables (current stage, most recent scenario, validation-fail
count, hints used). Never inspects terminal command history. Nothing here is a second Lab-state
or academic-state system — it's the existing ones, read the same way every other admin view
already reads them.

## 9. Help requests — a queue, not a chat

`POST /api/classroom/:id/help-request { category, message }` → `open` → (instructor)
`acknowledge` → `resolve`. That's the entire surface — explicitly no chat, no video, no remote
shell takeover (§37). The instructor dashboard's help queue polls the same dashboard endpoint
everything else does.

## 10. Guidance, never control

`setCurrentActivity` (current scenario) and announcements are exactly that — a link the student
can choose to open, a message they can read. Nothing server-side redirects a student's browser
or marks work complete on their behalf. The external meeting URL (`classroom_sessions.
meeting_url`) is a generic field the student sees as a link — RootNode never proxies or embeds
Meet/Zoom/Teams/anything else, so it isn't coupled to a single vendor.

## 11. CSV roster import — whole-file, transactional

`student-csv.js` hand-parses (no CSV dependency — the file format here is small and simple
enough that pulling in a library would just be one more thing to audit) and validates the
**entire** file before any database write. `POST /api/admin/students/import` then does every
insert inside one Postgres transaction — one bad row rolls back the whole import rather than
leaving a half-imported roster, which is the more dangerous failure mode of the two. Never
accepts a `password`/`password_hash`/`credential_token_hash` column — activation tokens are
always generated server-side, never taken from input.

## 12. Observability

`GET /metrics` is a hand-rolled Prometheus text-exposition endpoint (no `prom-client`
dependency — a handful of counters/gauges don't need one) with real in-process counters for
login success/failure and on-demand gauges for live-classroom/help-request/Lab-state counts.
No student or instructor ID ever appears as a label value — every label is a bounded enum
(status, presence, result), per the explicit no-PII/no-high-cardinality-labels instruction. The
Prometheus scrape job for the Platform API (`infra/monitoring/prometheus/prometheus.yml.j2`),
previously commented out, is now active.

## 13. Frontend

**Student side** (`frontend/src/platform/`): `LoginScreen` (credentialed, now the default entry
point) with links to the legacy pilot entry and forgot-password; `SetPasswordScreen` (shared
activate/reset UI, driven by `?activate=`/`?reset=` query params — no router library, matching
this app's existing state-machine-per-shell convention); `ForgotPasswordScreen`; a `Classroom`
tab (live-class banner, join, guidance-only current-activity link, own Lab status/launch reusing
the My Learning tab's exact API, announcements, Need Help form); a `Profile` tab (identity,
cohort, progress, achievements, active-session count, change-password).

**Admin side** (`frontend/src/admin/`): `StudentsView` gained credential status in the roster
table, a create-student form (email/login-ID/cohort), convert/reset-password/revoke-sessions
controls per student, and a bulk CSV import form. A new `ClassroomView` is the control center:
cohort picker → schedule/list classes → a live dashboard (participants with presence/Lab-status/
current-work, help queue with acknowledge/resolve, current-activity setter, announcement
poster, start/end/cancel, Prepare Labs).

## 14. Testing — real, not asserted

- `platform/test/e2e-phase5a.js` (21 checks): activation single-use, password security (§32 —
  correct/wrong/unknown-identifier/deactivated/immediate-deactivation/rate-limit/rate-limit-
  survives-restart/change-password/session-revocation/forgot-password anti-enumeration/admin
  reset/CSRF), and the two-student RBAC matrix (§31 — student can't reach `/api/admin/*`,
  assigned/unassigned/viewer instructor access), plus a classroom lifecycle smoke pass.
- `infra/scripts/drills/test-phase5a-rehearsal.js` (15 checks): 5 pilot students, real seeded
  progress/attempt/achievement history, a live classroom, help requests, announcements, **a real
  Platform API restart mid-rehearsal** proving classroom/session/presence recovery, then
  converting two students mid-rehearsal and confirming every bit of their prior history survived
  under the new login.
- Both run against a live `docker-compose.dev.yml` stack over real HTTP, not mocks.
- The full pre-existing regression suite (Phase 1/2A/2B/3A/3B/4.1) was re-run unmodified given
  how much shared code (`server.js`, `admin-routes.js`, `sessions.js`, `rbac.js`) this phase
  touched — see the Phase 5A completion report for results.

## 15. What was deliberately not built

Per §37: video/voice conferencing, student-to-student chat, remote instructor shell takeover,
screen recording or proctoring, public registration or course catalog, payments/Stripe, a Parent
Portal, school/SIS integrations, real email delivery infrastructure, certificates, an AI tutor,
a mobile app, a multi-Lab-host scheduler, and production deployment itself. Each is a plausible
"while we're in here" addition and each was left alone on purpose — the schema and API surface
built this phase don't block any of them later.