feat: anti-cheat + presence panel + projector view

Refinement pass on top of the validated v1.2 base.

Hardening / quick fixes
- Caddyfile.tpl: CSP / HSTS / X-Frame / Referrer-Policy / Permissions-Policy,
  1 MiB request body cap, X-Forwarded-For pass-through; stock-Caddy compatible.
- auth.py: STUDENT_MAX_AGE 1y -> 30d.
- bootstrap.sh: stage 5 prepends `git config --add safe.directory` so the
  re-bootstrap path no longer 'detected dubious ownership' faults.
- admin.js: drop the misleading `closedPayload?.state || session.state`
  shim; state derives from session only.

Anti-cheat
- New `student_events` audit table; new POST /api/session/{sid}/event for
  blur / visibility_hidden / focus / visibility_visible. quiz.js debounces
  events at 1.5s and uses sendBeacon for visibility_hidden so the event
  survives a navigation. Counts surface in admin presence + CSV export.
- First-claim-wins on join: add_participant raises DuplicateStudentId on
  PK violation; route returns 409 + records a duplicate_join audit event
  with attempted name + IP + UA. Admin dashboard surfaces a per-row red
  badge for hits on real participants and a top-of-page alert for orphan
  attempts.
- DELETE /admin/api/students/{id} as the recovery hatch: clears the
  participant + submissions, kicks active WS sockets so a stale cookie
  cannot continue submitting. quiz.js surfaces the FastAPI detail message
  in the join form so users see the 'already in use' guidance.

Presence panel
- New presence_update WS message; in-process presence map keyed on
  student_id tracks ws_count + last_seen_ms. Admin dashboard renders
  per-student rows: connected/idle/dropped dot, blur+hidden+duplicate
  badges, 'answered current Q' tick, and a clear-student button.

Projector view (public, read-only)
- /projector/?sid=..., GET /api/session/{sid}/projector, WS
  /ws/projector/{sid}. Single self-contained projector_state snapshot
  pushed on every state change. Public leaderboard strips student_id;
  QR rendered server-side as data: URL (CSP-compliant).
- Includes per-Q answer histogram, 8-bucket response-time distribution,
  10-bucket score distribution.
- static/projector.{html,css,js}: editorial-broadside design — masthead,
  registration crosses, conic-gradient countdown ring, SVG stepped-area
  score distribution with median tick, leaderboard row-stagger. Inherits
  light/dark tokens from style.css; honours prefers-reduced-motion. No
  scroll at 1366x768 / 1920x1080 / 3440x1440.

Tests
- tests/test_anti_cheat.py: blur logging + CSV count, unknown-kind 422,
  unauthenticated event 401, duplicate-join 409 + audit, admin
  clear-student happy + 404, server-side submit lockout regression.
- tests/test_projector.py: snapshot shape, leaderboard student_id
  redaction, WS push on state change, 404 for unknown sid, page redirect
  when no sid.
- Existing tests updated for the new presence_update snapshot frame +
  CSV header columns + first-claim-wins refusal of re-key.

57/57 pytest green; smoke-tested locally end-to-end.

tests/test_anti_cheat.py

@@ -0,0 +1,89 @@
+"""Anti-cheat / audit-event coverage:
+  - tab-blur events are recorded and surfaced in CSV + presence
+  - duplicate-join attempts are 409 + audited
+  - admin clear-student removes the participant + submissions
+  - submit lockout (one answer per Q per student) is server-enforced
+"""
+
+from __future__ import annotations
+
+from conftest import admin_login, join_student
+
+
+def test_blur_event_is_logged_and_counted(client, sid):
+    join_student(client, sid, "s1", "Alice")
+    response = client.post(f"/api/session/{sid}/event", json={"kind": "blur", "question_idx": 0})
+    assert response.status_code == 200
+    response = client.post(f"/api/session/{sid}/event", json={"kind": "blur", "question_idx": 0})
+    assert response.status_code == 200
+    response = client.post(f"/api/session/{sid}/event", json={"kind": "visibility_hidden"})
+    assert response.status_code == 200
+
+    # The event count is exposed via CSV export. Two blur events + one
+    # visibility_hidden event should land on the s1 row.
+    admin_login(client)
+    csv_text = client.get("/admin/api/csv").text
+    s1_row = next(line for line in csv_text.splitlines() if ",s1," in line)
+    # Trailing fields are blur_count, hidden_count, duplicate_join_attempts.
+    assert s1_row.endswith(",2,1,0"), s1_row
+
+
+def test_event_endpoint_rejects_unknown_kind(client, sid):
+    join_student(client, sid, "s1", "Alice")
+    response = client.post(f"/api/session/{sid}/event", json={"kind": "screenshot"})
+    assert response.status_code == 422
+
+
+def test_event_endpoint_requires_student_cookie(client, sid):
+    response = client.post(f"/api/session/{sid}/event", json={"kind": "blur"})
+    assert response.status_code == 401
+
+
+def test_duplicate_join_is_logged_in_csv(client, sid):
+    """A 409 join attempt records a `duplicate_join` audit row whose
+    count rolls up into CSV + presence_update."""
+    join_student(client, sid, "s1", "Alice")
+    # Second client tries to claim s1 from a fresh cookie jar.
+    fresh = client.__class__(client.app)
+    response = fresh.post(f"/api/session/{sid}/join", json={"student_id": "s1", "name": "Hijacker"})
+    assert response.status_code == 409
+
+    admin_login(client)
+    csv_text = client.get("/admin/api/csv").text
+    s1_row = next(line for line in csv_text.splitlines() if ",s1," in line)
+    assert s1_row.endswith(",0,0,1"), s1_row
+
+
+def test_admin_clear_student_frees_id(client, sid):
+    """First-claim-wins recovery: admin can clear a participant so the
+    legitimate student (or anyone, since there's no further identity
+    check) can re-join with that id."""
+    join_student(client, sid, "s1", "Alice")
+    admin_login(client)
+    response = client.delete("/admin/api/students/s1")
+    assert response.status_code == 200
+    # The slot is now free; the same id can be re-claimed from a fresh
+    # cookie jar.
+    fresh = client.__class__(client.app)
+    response = fresh.post(f"/api/session/{sid}/join", json={"student_id": "s1", "name": "Alice Again"})
+    assert response.status_code == 200
+
+
+def test_admin_clear_student_404s_when_no_match(client, sid):
+    admin_login(client)
+    assert client.delete("/admin/api/students/nobody").status_code == 404
+
+
+def test_submit_lockout_is_server_enforced(client, sid):
+    """Server-side: a second submit for the same (sid, student_id, qidx)
+    returns the *original* ack rather than overwriting the answer. The
+    PK constraint + existing_submit_ack early-return guarantees this."""
+    join_student(client, sid, "s1", "Alice")
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 5)
+    first = client.portal.call(rooms.submit_answer, sid, "s1", 0, "B")
+    second = client.portal.call(rooms.submit_answer, sid, "s1", 0, "C")
+    assert first["type"] == "submit_ack"
+    assert second["type"] == "submit_ack"
+    assert second["answer"] == first["answer"] == "B"
+    assert second["score"] == first["score"]

tests/test_api_student.py

@@ -11,14 +11,25 @@ def test_session_metadata_join_me_and_stats(client, sid):
     assert join["ok"] is True
     assert "qz_student" in client.cookies
 
-    join_student(client, sid, "s1", "Updated Name")
     me = client.get(f"/api/session/{sid}/me")
     assert me.status_code == 200
-    assert me.json()["name"] == "Updated Name"
+    assert me.json()["name"] == "First Name"
 
     stats = client.get(f"/api/session/{sid}/stats").json()
     assert stats["question_idx"] is None
-    assert stats["top5"][0]["name"] == "Updated Name"
+    assert stats["top5"][0]["name"] == "First Name"
+
+
+def test_duplicate_student_id_join_is_rejected(client, sid):
+    """First-claim-wins anti-hijack: a second join attempting the same
+    student_id must 409 (without overwriting name or rotating the cookie).
+    The original cookie keeps working; recovery is via admin clear-student."""
+    join_student(client, sid, "s1", "First Name")
+    response = client.post(f"/api/session/{sid}/join", json={"student_id": "s1", "name": "Hijacker"})
+    assert response.status_code == 409
+    assert "already in use" in response.text.lower()
+    me = client.get(f"/api/session/{sid}/me").json()
+    assert me["name"] == "First Name"
 
 
 def test_root_without_sid_redirects_to_canonical(client, sid):

tests/test_csv_export.py

@@ -12,6 +12,9 @@ def test_csv_export_contains_one_row_per_submission(client, sid):
 
     response = client.get("/admin/api/csv")
     lines = response.text.strip().splitlines()
-    assert lines[0] == "sid,student_id,name,question_idx,answer,elapsed_ms,score,status"
+    assert lines[0] == "sid,student_id,name,question_idx,answer,elapsed_ms,score,status,blur_count,hidden_count,duplicate_join_attempts"
     assert len(lines) == 2
     assert ",s1,Student One,0,B," in lines[1]
+    # Default audit-event counts are 0 for a clean run (no blur events,
+    # no duplicate-join attempts).
+    assert lines[1].endswith(",0,0,0")

tests/test_projector.py

@@ -0,0 +1,76 @@
+"""Projector view (public read-only):
+  - snapshot endpoint returns the expected shape
+  - leaderboard never carries student_ids (privacy)
+  - WS client receives a projector_state message on connect
+  - state changes (open question, submit, close) push fresh snapshots
+"""
+
+from __future__ import annotations
+
+import pytest
+from starlette.websockets import WebSocketDisconnect
+
+from conftest import admin_login, join_student
+
+
+def test_projector_snapshot_includes_required_fields(client, sid):
+    join_student(client, sid, "s1", "Alice")
+    response = client.get(f"/api/session/{sid}/projector")
+    assert response.status_code == 200
+    body = response.json()
+    assert body["type"] == "projector_state"
+    assert body["state"] == "lobby"
+    assert body["sid"] == sid
+    assert body["participant_count"] == 1
+    assert "qr_url" in body and body["qr_url"].startswith("data:image/svg+xml")
+    assert "join_url" in body
+    assert body["pool_meta"]["question_count"] >= 1
+    assert "score_distribution" in body
+    assert "leaderboard" in body
+
+
+def test_projector_leaderboard_redacts_student_ids(client, sid):
+    """The /admin board carries student_ids; the public projector
+    leaderboard must NOT — student_id namespace is private."""
+    join_student(client, sid, "s1", "Alice")
+    join_student(client, sid, "s2", "Bob")
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 5)
+    client.portal.call(rooms.submit_answer, sid, "s1", 0, "B")
+    client.portal.call(rooms.close_question, sid)
+
+    snapshot = client.get(f"/api/session/{sid}/projector").json()
+    for row in snapshot["leaderboard"]:
+        assert "student_id" not in row, "projector leaderboard leaks student_ids"
+
+
+def test_projector_ws_pushes_snapshot_on_state_change(client, sid):
+    join_student(client, sid, "s1", "Alice")
+    admin_login(client)
+    with client.websocket_connect(f"/ws/projector/{sid}") as ws:
+        initial = ws.receive_json()
+        assert initial["type"] == "projector_state"
+        assert initial["state"] == "lobby"
+
+        # Trigger a state change via the room manager directly.
+        rooms = client.app.state.rooms
+        client.portal.call(rooms.open_question, sid, 0, 5)
+        push = ws.receive_json()
+        assert push["type"] == "projector_state"
+        assert push["state"] == "question_open"
+        assert push["question"] is not None
+        assert push["question"]["idx"] == 0
+
+
+def test_projector_404_for_unknown_sid(client):
+    assert client.get("/api/session/UNKNOWN/projector").status_code == 404
+    with pytest.raises(WebSocketDisconnect) as exc:
+        with client.websocket_connect("/ws/projector/UNKNOWN"):
+            pass
+    assert exc.value.code == 4001
+
+
+def test_projector_page_redirects_when_no_sid(client, sid):
+    response = client.get("/projector/", follow_redirects=False)
+    assert response.status_code == 302
+    assert response.headers["location"].endswith(f"sid={sid}")

tests/test_ws_admin.py

@@ -11,6 +11,17 @@ def test_instructor_ws_requires_admin_cookie(client, sid):
     assert exc.value.code == 4001
 
 
+def _drain_until(ws, target_type, max_msgs=12):
+    """Helper: pull messages off `ws` until one matches `target_type`. Lets
+    tests skip auxiliary state-tracking messages (presence_update,
+    full_leaderboard) that fire as side-effects of state changes."""
+    for _ in range(max_msgs):
+        msg = ws.receive_json()
+        if msg["type"] == target_type:
+            return msg
+    raise AssertionError(f"did not see message {target_type!r} after {max_msgs} attempts")
+
+
 def test_instructor_next_command_drives_full_loop(client, sid):
     """The 'next' WS message drives the entire lifecycle:
     lobby → opens Q0 → closes Q0 + opens Q1 → ... → closes last + ends."""
@@ -19,16 +30,14 @@ def test_instructor_next_command_drives_full_loop(client, sid):
     with client.websocket_connect(f"/ws/student/{sid}") as student_ws:
         assert student_ws.receive_json()["type"] == "state"
         with client.websocket_connect(f"/ws/instructor/{sid}") as admin_ws:
-            # Drain lobby snapshot.
-            assert admin_ws.receive_json()["type"] == "state"
-            assert admin_ws.receive_json()["type"] == "lobby_update"
+            # Drain lobby snapshot (state + lobby_update + presence_update).
+            _drain_until(admin_ws, "presence_update")
 
             # First "next" opens Q0 from lobby.
             admin_ws.send_json({"type": "next"})
             assert student_ws.receive_json()["type"] == "question_open"
-            admin_open = admin_ws.receive_json()
-            assert admin_open["type"] == "question_open"
-            assert admin_ws.receive_json()["type"] == "live_histogram"
+            _drain_until(admin_ws, "question_open")
+            _drain_until(admin_ws, "live_histogram")
 
             # Second "next" closes Q0 and opens Q1.
             admin_ws.send_json({"type": "next"})
@@ -42,17 +51,16 @@ def test_instructor_close_then_next_emits_clean_open(client, sid):
     with client.websocket_connect(f"/ws/student/{sid}") as student_ws:
         assert student_ws.receive_json()["type"] == "state"
         with client.websocket_connect(f"/ws/instructor/{sid}") as admin_ws:
-            assert admin_ws.receive_json()["type"] == "state"
-            assert admin_ws.receive_json()["type"] == "lobby_update"
+            _drain_until(admin_ws, "presence_update")
             admin_ws.send_json({"type": "open_question", "question_idx": 0, "time_limit": 2})
             assert student_ws.receive_json()["type"] == "question_open"
-            assert admin_ws.receive_json()["type"] == "question_open"
-            assert admin_ws.receive_json()["type"] == "live_histogram"
+            _drain_until(admin_ws, "question_open")
+            _drain_until(admin_ws, "live_histogram")
 
             admin_ws.send_json({"type": "close_question"})
             assert student_ws.receive_json()["type"] == "question_closed"
-            admin_msgs = [admin_ws.receive_json(), admin_ws.receive_json()]
-            assert {m["type"] for m in admin_msgs} == {"question_closed", "full_leaderboard"}
+            _drain_until(admin_ws, "question_closed")
+            _drain_until(admin_ws, "full_leaderboard")
 
             admin_ws.send_json({"type": "next"})
             assert student_ws.receive_json()["type"] == "question_open"
@@ -62,16 +70,12 @@ def test_reset_command_returns_session_to_lobby(client, sid):
     join_student(client, sid, "s1", "Student One")
     admin_login(client)
     with client.websocket_connect(f"/ws/instructor/{sid}") as admin_ws:
-        assert admin_ws.receive_json()["type"] == "state"
-        assert admin_ws.receive_json()["type"] == "lobby_update"
+        _drain_until(admin_ws, "presence_update")
         admin_ws.send_json({"type": "open_question", "question_idx": 0, "time_limit": 2})
-        assert admin_ws.receive_json()["type"] == "question_open"
-        assert admin_ws.receive_json()["type"] == "live_histogram"
+        _drain_until(admin_ws, "question_open")
+        _drain_until(admin_ws, "live_histogram")
 
         admin_ws.send_json({"type": "reset"})
-        # After reset, the instructor receives a state=lobby snapshot + lobby_update.
-        msgs = []
-        while len(msgs) < 2:
-            msgs.append(admin_ws.receive_json())
-        types = [m["type"] for m in msgs]
-        assert "state" in types
+        # After reset, instructor receives a state=lobby snapshot.
+        msg = _drain_until(admin_ws, "state")
+        assert msg["state"] == "lobby"