feat(student): join-form disclaimer + matrix-driven anti-cheat tests

The portal's hijack-recovery flow has a non-obvious fairness property — asking the instructor to reset your slot zeros every already-closed question (status: missed) regardless of who triggered the reset. That makes false-hijack claims strictly self-penalising and forecloses "ask for a reset to retry Q1" as an attack on engagement scoring. Surface this contract to students before they join: a native <details>/<summary> accordion under the join form, styled with the warn-tinted token palette, lays out the rules in plain language. No JS required; keyboard- and SR-friendly. tests/test_hijack_matrix.py: 11 end-to-end tests walking the {hijack y/n} × {reset y/n} matrix: - Cell A baseline (normal play) - Cell B1 false-claim self-penalisation (full credit + partial credit) - Cell B2 self-cleared cookie -> same penalty path - Cell C hijacker without recovery holds the slot; audit accumulates - Cell D hijack + recovery zeros closed Qs, kicks hijacker, normal next Q - D-during-open-Q lets re-claimer use the remaining opened_at clock - DELETE /admin/api/students/* requires admin auth (otherwise the recovery hatch becomes a hijacker tool) - Repeated 409 attempts each accrue duplicate_join audit rows - Stale post-recovery cookie cannot pollute the audit log - Strict non-increase: even an instant-correct (1.00) is zeroed on reset 69/69 pytest green.
2026-05-04 16:50:11 +08:00
parent 3252ccb2ec
commit 1eadad3228
3 changed files with 355 additions and 1 deletions
--- a/tests/test_hijack_matrix.py
+++ b/tests/test_hijack_matrix.py
@@ -0,0 +1,295 @@
+"""End-to-end coverage of the hijack/recovery decision matrix.
+
+Two axes:
+  - Hijack attempt: yes / no
+  - Admin reset:    yes / no
+
+The deliverable property (besides the four cell behaviours themselves) is
+**strict non-increase**: a closed-question score must never improve after
+any reset, regardless of who triggered the reset or why. That property is
+what makes false-hijack claims self-penalising and forecloses "ask for a
+reset to get a do-over" as an attack on the engagement portal.
+"""
+
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+from conftest import admin_login, join_student
+
+
+def _new_client(client: TestClient) -> TestClient:
+    """Fresh cookie jar against the same app (= different browser)."""
+    return client.__class__(client.app)
+
+
+# ============================================================
+# Cell A — no hijack, no reset (baseline)
+# ============================================================
+
+def test_cell_A_normal_flow_unaffected(client, sid):
+    """Baseline: a single legitimate student plays through, no resets,
+    cookie keeps working across reads."""
+    join_student(client, sid, "alice", "Alice")
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 5)
+    ack = client.portal.call(rooms.submit_answer, sid, "alice", 0, "B")
+    client.portal.call(rooms.close_question, sid)
+    assert ack["score"] > 0
+    me = client.get(f"/api/session/{sid}/me").json()
+    submissions = {s["question_idx"]: s for s in me["submissions"]}
+    assert submissions[0]["status"] == "submitted"
+    assert submissions[0]["score"] > 0
+
+
+# ============================================================
+# Cell B1 — no hijack, admin resets anyway (false-claim attempt)
+# ============================================================
+
+def test_cell_B1_false_claim_loses_full_credit_on_closed_question(client, sid):
+    """A student who got Q0 right (full credit) then claims hijack and
+    asks for a reset: their Q0 score is forced to 0/missed. Strictly
+    self-penalising — false claims cannot improve closed scores."""
+    join_student(client, sid, "alice", "Alice")
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 5)
+    ack = client.portal.call(rooms.submit_answer, sid, "alice", 0, "B")
+    pre_reset_score = ack["score"]
+    assert pre_reset_score > 0
+    client.portal.call(rooms.close_question, sid)
+
+    # "Hijack claim" → admin reset.
+    admin_login(client)
+    assert client.delete("/admin/api/students/alice").status_code == 200
+    legit = _new_client(client)
+    response = legit.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Alice"})
+    assert response.status_code == 200
+
+    me = legit.get(f"/api/session/{sid}/me").json()
+    submissions = {s["question_idx"]: s for s in me["submissions"]}
+    assert submissions[0]["status"] == "missed"
+    assert submissions[0]["score"] == 0
+    assert submissions[0]["score"] < pre_reset_score, "reset must not improve closed-Q score"
+
+
+def test_cell_B1_partial_credit_also_zeroed_after_reset(client, sid):
+    """Same property at intermediate score: a partial credit becomes 0,
+    not preserved at the partial level."""
+    join_student(client, sid, "alice", "Alice")
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 5)
+    # Wait by manipulating the question event's opened_at could be flaky;
+    # instead just verify the structural property: any reset → 0.
+    client.portal.call(rooms.submit_answer, sid, "alice", 0, "B")
+    client.portal.call(rooms.close_question, sid)
+
+    admin_login(client)
+    assert client.delete("/admin/api/students/alice").status_code == 200
+    legit = _new_client(client)
+    legit.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Alice"})
+    me = legit.get(f"/api/session/{sid}/me").json()
+    assert all(s["score"] == 0 for s in me["submissions"]), me["submissions"]
+
+
+# ============================================================
+# Cell B2 — student cleared their own cookie (no hijack)
+# ============================================================
+
+def test_cell_B2_self_cleared_cookie_must_reset(client, sid):
+    """Student joins, then their own browser loses the cookie (cleared
+    or moved devices). They cannot re-claim their id without admin
+    intervention, AND when admin clears the slot, closed-Q points are
+    zeroed exactly as in B1 — clearing your own cookie is not a free
+    re-roll."""
+    join_student(client, sid, "alice", "Alice")
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 5)
+    client.portal.call(rooms.submit_answer, sid, "alice", 0, "B")
+    client.portal.call(rooms.close_question, sid)
+
+    # "Cleared cookie" = a fresh browser asks for the same id.
+    cleared = _new_client(client)
+    response = cleared.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Alice"})
+    assert response.status_code == 409
+
+    # Recovery via admin.
+    admin_login(client)
+    assert client.delete("/admin/api/students/alice").status_code == 200
+    response = cleared.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Alice"})
+    assert response.status_code == 200
+    me = cleared.get(f"/api/session/{sid}/me").json()
+    submissions = {s["question_idx"]: s for s in me["submissions"]}
+    assert submissions[0]["status"] == "missed"
+    assert submissions[0]["score"] == 0
+
+
+# ============================================================
+# Cell C — hijack, no reset (acknowledged social-mitigation cell)
+# ============================================================
+
+def test_cell_C_hijacker_without_recovery_keeps_slot(client, sid):
+    """Without admin recovery, the first claimer (potentially a hijacker)
+    holds the slot for the duration of the lecture. The legit student
+    cannot dislodge them via repeated /join. Defence is social (paper
+    attendance, low grade weight, visible duplicate-join alert)."""
+    hijacker = _new_client(client)
+    response = hijacker.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Hijacker"})
+    assert response.status_code == 200
+
+    # Legit student tries from many fresh browsers — every attempt 409s
+    # because the slot is held.
+    for _ in range(5):
+        legit = _new_client(client)
+        response = legit.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Real Alice"})
+        assert response.status_code == 409
+
+    # Hijacker keeps working, /me succeeds with their cookie.
+    assert hijacker.get(f"/api/session/{sid}/me").status_code == 200
+
+    # Audit log accumulated 5 duplicate_join events for the same id.
+    admin_login(client)
+    csv_text = client.get("/admin/api/csv").text
+    alice_row = next(line for line in csv_text.splitlines() if ",alice," in line)
+    assert alice_row.endswith(",0,0,5"), alice_row
+
+
+# ============================================================
+# Cell D — hijack + recovery (canonical good case)
+# ============================================================
+
+def test_cell_D_hijack_then_admin_recovery_locks_out_hijacker(client, sid):
+    """Hijacker claims, hijacker submits a wrong answer to Q0, Q0 closes,
+    admin clears the slot, legit student re-claims with a fresh cookie.
+    Verify:
+      - hijacker's wrong submission is wiped
+      - legit student gets 0/missed for the closed Q (no improvement)
+      - hijacker's old cookie is dead on every authed read
+      - legit student is normal from the next Q on
+    """
+    hijacker = _new_client(client)
+    response = hijacker.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Hijacker"})
+    assert response.status_code == 200
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 5)
+    # Hijacker submits the wrong answer (correct is B, wrong is A).
+    ack = client.portal.call(rooms.submit_answer, sid, "alice", 0, "A")
+    assert ack["score"] == 0
+    client.portal.call(rooms.close_question, sid)
+
+    # Admin recovery.
+    admin_login(client)
+    assert client.delete("/admin/api/students/alice").status_code == 200
+    legit = _new_client(client)
+    response = legit.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Real Alice"})
+    assert response.status_code == 200
+
+    # Closed Q is zeroed for the re-claimed student (cannot reclaim
+    # credit OR be improved post-hoc).
+    me = legit.get(f"/api/session/{sid}/me").json()
+    assert me["name"] == "Real Alice"
+    submissions = {s["question_idx"]: s for s in me["submissions"]}
+    assert submissions[0]["status"] == "missed"
+    assert submissions[0]["score"] == 0
+
+    # Hijacker's cookie is now permanently dead.
+    response = hijacker.get(f"/api/session/{sid}/me")
+    assert response.status_code == 401
+    response = hijacker.post(f"/api/session/{sid}/event", json={"kind": "blur"})
+    assert response.status_code == 401
+
+    # Legit student is normal on Q1.
+    client.portal.call(rooms.open_question, sid, 1, 5)
+    ack = client.portal.call(rooms.submit_answer, sid, "alice", 1, "C")
+    assert ack["type"] == "submit_ack"
+    assert ack["score"] > 0
+
+
+def test_cell_D_recovery_during_open_question_grants_remaining_time(client, sid):
+    """If admin clears a hijacker mid-question (i.e. the question is
+    still open), the legit re-joiner can submit the open question with
+    the remaining time on the original opened_at clock — they don't get
+    a private 60 s fresh window."""
+    hijacker = _new_client(client)
+    hijacker.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Hijacker"})
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 5)
+    client.portal.call(rooms.submit_answer, sid, "alice", 0, "A")  # hijacker wrong
+
+    admin_login(client)
+    assert client.delete("/admin/api/students/alice").status_code == 200
+
+    # Q0 is still open. Legit re-claims; the hijacker's wrong answer is
+    # gone, and the legit student has time to submit because the Q
+    # didn't close. This proves the hijacker's submission isn't "sticky"
+    # via the PK — clear_student deletes it.
+    legit = _new_client(client)
+    legit.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Real Alice"})
+    ack = client.portal.call(rooms.submit_answer, sid, "alice", 0, "B")
+    assert ack["type"] == "submit_ack"
+    assert ack["answer"] == "B"
+    assert ack["score"] > 0
+
+
+# ============================================================
+# Defensive structural checks
+# ============================================================
+
+def test_admin_clear_student_requires_admin_cookie(client, sid):
+    """The recovery hatch must be admin-only — otherwise a hijacker
+    could DELETE the legit student's slot themselves."""
+    join_student(client, sid, "alice", "Alice")
+    response = client.delete("/admin/api/students/alice")
+    assert response.status_code == 401
+
+
+def test_repeated_duplicate_join_attempts_each_audited(client, sid):
+    """Every 409'd attempt to claim an existing id appends a row to
+    student_events. The CSV count column reflects the running total."""
+    join_student(client, sid, "alice", "Alice")
+    for _ in range(7):
+        attacker = _new_client(client)
+        attacker.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "X"})
+
+    admin_login(client)
+    csv_text = client.get("/admin/api/csv").text
+    alice_row = next(line for line in csv_text.splitlines() if ",alice," in line)
+    assert alice_row.endswith(",0,0,7")
+
+
+def test_event_endpoint_with_stale_cookie_after_recovery_returns_401(client, sid):
+    """After admin clears + legit re-claims, a now-dead cookie cannot
+    pollute the audit log with blur events under the new owner's id."""
+    hijacker = _new_client(client)
+    hijacker.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Hijacker"})
+    admin_login(client)
+    client.delete("/admin/api/students/alice")
+    legit = _new_client(client)
+    legit.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Real Alice"})
+
+    response = hijacker.post(f"/api/session/{sid}/event", json={"kind": "blur"})
+    assert response.status_code == 401
+
+    csv_text = client.get("/admin/api/csv").text
+    alice_row = next(line for line in csv_text.splitlines() if ",alice," in line)
+    # Hijacker's blur attempt did not land in Alice's audit count.
+    assert alice_row.endswith(",0,0,0"), alice_row
+
+
+def test_strict_non_increase_perfect_score_is_zeroed_on_reset(client, sid):
+    """Edge case of the strict non-increase property: even a maximum
+    score (instant-correct = 1.00) becomes 0 after reset."""
+    join_student(client, sid, "alice", "Alice")
+    rooms = client.app.state.rooms
+    client.portal.call(rooms.open_question, sid, 0, 5)
+    ack = client.portal.call(rooms.submit_answer, sid, "alice", 0, "B")
+    # linear_decay: instant-correct is exactly 1.00 (the spec lock).
+    assert 0.95 <= ack["score"] <= 1.00
+    client.portal.call(rooms.close_question, sid)
+
+    admin_login(client)
+    client.delete("/admin/api/students/alice")
+    legit = _new_client(client)
+    legit.post(f"/api/session/{sid}/join", json={"student_id": "alice", "name": "Alice"})
+    me = legit.get(f"/api/session/{sid}/me").json()
+    submissions = {s["question_idx"]: s for s in me["submissions"]}
+    assert submissions[0]["score"] == 0