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.
This commit is contained in:
ameer
2026-05-04 16:08:59 +08:00
parent f38722ed66
commit 9ea0a8b039
20 changed files with 3029 additions and 72 deletions

89
tests/test_anti_cheat.py Normal file
View File

@@ -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"]