Both student-facing surfaces (the per-device join page and the
front-of-room projector) now render options as text only, no A/B/C/D
chips, no numeric prefixes. The letter-namespace remains internal:
canonical A..D in pool.json + submissions storage; canonical position
1..4 in the CSV export. Admin dashboard keeps letters because it is the
instructor's private console.
Why this lands now: the discussion of per-student option shuffling
flagged that A/B/C/D as discussion handles ("the answer is B") is itself
a leaky channel. Removing the labels closes that channel for the
non-shuffled case and keeps it closed if shuffling is added later.
Wire protocol: the submit message carries the option's full text
("answer": "Pipelining"). Server's submit_answer resolves text -> letter
via app.pool.resolve_option_key, which also accepts a canonical letter
so internal callers and tests stay readable. A non-matching string is
recorded as a zero-score submission with answer=NULL, locked in via the
PK + existing_submit_ack short-circuit. So an attempted UI bypass that
posts a fabricated string just produces a wrong answer; no retry.
CSV: A=1 .. D=2 .. C=3 .. D=4 in the answer column. Empty when no option
matched. Header unchanged so downstream pandas readers don't break, but
the value type is int instead of letter.
Histogram: the failsafe "submitted-but-no-match" row buckets into
"missed" alongside genuine misses — both yield zero credit and the
instructor cares about the same thing.
Tests:
- test_submit_accepts_option_text_resolves_to_canonical: production
wire format produces correct grading + canonical-letter storage.
- test_submit_failsafe_locks_in_zero_score_on_garbage_text: a non-
matching string is recorded at score=0 and a follow-up correct
submission cannot overwrite it.
71/71 green.
A multi-hour lecture has questions spread over the whole period; we can't
reasonably expect students to keep their devices focused for that long.
Blur events still get logged (no code change) so we have signal for
post-hoc analysis if the histogram is striking, but we don't promise it
as enforcement, and we don't make students self-monitor against an
unrealistic standard.
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.
Closes the post-recovery re-attack window. Previously cookies were
authenticated purely cryptographically — once a hijacker received a
signed cookie for student_id=X, that cookie remained valid forever
(until QUIZ_SECRET_KEY rotated), even after admin clear-student + legit
re-claim issued a fresh cookie_id for X.
Now /me, /event, and /ws/student all check that the cookie's cookie_id
matches participants.cookie_id for the (sid, student_id). Mismatch ->
401 + Set-Cookie clearing for HTTP, ws.close(4001) for WS. The legit
re-claim wins because admin clear_student deletes the row and the next
join inserts the new student's cookie_id; the hijacker's cookie now
fails the DB check on every subsequent request.
Test: tests/test_anti_cheat.py::test_post_recovery_old_cookie_is_dead
covers the full hijack -> clear -> re-claim -> hijacker-locked-out
sequence end to end.
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.
Replace the manual "Disconnected → Reconnect button" screen with a small
top-banner that retries the WS up to 8 times (500ms → 5s, ~27s budget).
On open, snapshot replay restores the question card and countdown so a
brief network blip is invisible to the student. After the retry budget
exhausts, fall back to a manual "Reload" card.
Same path covers initial WS-open failures (transient TLS hiccups on the
Aliyun edge), since the first connect() and subsequent reconnects share
the schedule. Auth-related closes (1008) still hard-reload immediately
so an invalidated cookie lands on the join form, not in a retry loop.
Submits are now also gated on ws.readyState === OPEN; clicks during a
reconnect are silent no-ops, and the question re-renders fresh once the
server replays state.
Local API stress (lib.mjs / api_stress.mjs):
- setupSession now does login -> /admin/api/reset and returns sid="main".
Drops the dead /admin/api/quizzes + /admin/api/sessions calls left over
from the multi-quiz codex era.
- bootServer writes the fixture pool (STRESS_POOL by default) to a tmp
file and passes QUIZ_POOL_PATH so the v1.2 server has a session at
startup.
- happyPath: drop the post-connect lobby_update wait (race with snapshot
dispatch) and stop double-driving the lifecycle (next() already opens
the next question, an explicit open() afterwards is a no-op).
- cross_session: rewritten as "cookie not honored on a non-existent sid"
since v1.2 hosts a single canonical session.
Live accuracy stress (live_accuracy.mjs):
- Per-student lobby-snapshot timeout (12s) with WS error/close rejection,
so a stalled handshake no longer hangs Promise.all until the outer
shell timeout (which produced the exit=124 cycles).
- Open all student WSs in parallel (mirrors what real students do); the
batch-of-8 throttle was masking the question we wanted answered.
- Instructor WS open also bounded by a 15s race so any failure surfaces
as actionable error text instead of a silent stall.
Bootstrap (deploy/bootstrap.sh):
- Stage 1 provisions a 2GB swap file (idempotent) with vm.swappiness=10.
1GB-RAM ECS instances OOM-kill uvicorn under WS-burst start-of-class
pressure; swap absorbs the spike without affecting steady state.
- Pool seeding prefers examples/demo10_pool.json over the 2-question
example so a fresh deploy boots with a usable demo.
Pool fixture (examples/demo10_pool.json):
- 10-question generic-knowledge demo pool, gitignore exception added.
tests/stress/live_accuracy.mjs: classroom-scale accuracy + latency
test that targets the deployed server (single-session, sid=main).
Logs in as admin via /admin/login, resets the session, joins N
students serially over HTTP, opens N student WebSockets in batches
of 8 (250ms apart) plus the instructor WS, then drives every
question through the admin "next" command. Each student picks
uniformly random A-D, sends the submit, waits for the submit_ack,
and records the round-trip latency. After session_ended, the script
verifies that every student whose pick == correct got score > 0,
every other submission got score == 0, and reports p50/p95/p99
ack latency. First live run: 50 students, 100 submits, 100% acks,
100% accuracy match, p99 555ms (≈intercontinental RTT to HK).
tests/stress/live_loop.sh: tmux-friendly loop that runs the live
test every 60s and appends a JSONL summary line per cycle to
runs/live_summary.jsonl. Mirrors the morning's api_stress run_loop
shape so per-cycle aggregates are easy to scrape.
app/rate_limit.py: tiny in-memory token bucket. Capacity + refill
in tokens/minute, keyed by client IP via X-Forwarded-For (with a
fallback to request.client.host). Process-local state — admin
login is the only user.
POST /admin/login: rate-limited at 10 attempts/minute/IP. Generous
for the legit instructor (who succeeds in 1-2 tries) and prohibitive
for brute force from a single attacker IP. Student endpoints
deliberately NOT rate-limited because campus students share NAT
gateways and IP-level limits would false-positive a whole class.
The bucket is per-app-instance (instantiated inside the router
factory), so test apps each get a fresh one and tests don't poison
each other.
Per-question score is now a float in [0.0, 1.0] snapped to a 21-level
0.05 grid, replacing the previous 0-1000 integer scale. Easier to read
on a leaderboard, ties become acceptable rather than vanishingly rare,
and small clock-skew differences no longer split rankings.
DB schema: score is REAL now (SQLite type affinity is loose enough that
existing rows still read fine, but new inserts go in as floats).
Frontend: added fmtScore() helpers in admin.js and quiz.js to render
two decimal places consistently (0.85, 1.20, 5.00) so float-arithmetic
sums never display as 0.8500000000000001.
Tests: linear_decay/flat/exponential_decay assertions updated; added
a snap-to-grid invariant test.
Students joining or reconnecting while the session is in question_closed
or finished previously got only a 'state' broadcast and nothing else,
leaving the SPA stuck on whatever was rendered before (typically the
join form's disabled state). Now send_student_snapshot replays the
question_closed message (and on finished, the session_ended payload)
so the SPA can render the reveal or final card immediately.
Mirrors the instructor-side reconnect fix in 22d1096.
Two issues from the first user test pass:
1. POST /admin/login was 500'ing on any password attempt that contained
non-ASCII characters (e.g. a smart-quote autofill from the browser
password manager). secrets.compare_digest(str, str) requires both
sides to be bytes or ASCII-only str; otherwise it raises TypeError.
Encoding both sides to UTF-8 bytes before the constant-time compare
makes the route degrade cleanly to 401 instead of 500.
2. Reconnecting an instructor while the session is in question_closed
left the dashboard stuck on "Reveal pending..." because
send_instructor_snapshot only replayed state + lobby_update +
full_leaderboard for closed sessions, not the question_open and
question_closed payloads needed to render the reveal card.
Now we replay question_open + question_closed + full_leaderboard
for the question_closed branch, so the SPA renders the full reveal
immediately on reconnect without waiting for the next event.
Three coupled fixes from the first manual test pass:
1. Stale signed cookie no longer 500s. `rooms.me()` now raises KeyError
when the participant row is gone (the previous code deref'd None and
threw TypeError, caught by quiz.js's catch-all as 'link expired').
`/api/session/{sid}/me` translates KeyError into 401 + delete_cookie,
so the client falls back to the join form cleanly.
Returning a JSONResponse directly because `raise HTTPException`
discards Response.delete_cookie mutations (FastAPI middleware
composes a fresh response on exception).
2. Reset is now a soft restart from the student's perspective. Before
closing each student WS in `RoomManager.reset`, the server now sends
a `{"type": "session_reset"}` message. The student SPA tears down
local state and re-runs boot(); /me returns 401 (now that the
participant is gone) and the join form renders without the user
having to manually reload. The WS close handler suppresses its
"Disconnected" screen during a reset to avoid a flash.
3. "You" highlight on the student leaderboard is now matched by id, not
by name. `RoomManager.leaderboard()` accepts an optional
`you_student_id` and stamps `is_you: true` on the matching entry only.
No other students' ids leak over the wire (we still don't include
`student_id` in the public top5 payload). quiz.js's renderBoard
prefers `r.is_you` when any row is marked, falling back to name match
for backward compatibility.
41/41 tests pass. Two new tests cover (a) the 401 + cookie-clear path
after reset and (b) `is_you` marking only the requesting student.
Targeted fixes on top of the editorial-lecture-hall pass:
- Leaderboard rank columns now align across all rows; medal stripes
reserve their 3px width on every row (no more 6px shift between
podium and chasers). Silver bumps to higher-contrast values in both
light and dark modes.
- Student leaderboard gains a visible "you" highlight (blue stripe,
blue name + score, small "you" eyebrow under the name). Matches by
display name since the server's student-facing top5 doesn't include
student_id.
- Lobby and Finished states share an editorial state-cta treatment:
display-serif "Ready to start." / "That's a wrap." with a numeric
cta-stats strip that anchors the right column on a projector.
- "02 PRE-FLIGHT" eyebrow continues the "01 JOIN" sequence on the
side panel, giving the page a magazine-spread rhythm.
- Live distribution suppresses empty bars when zero submissions and
shows a calm italic "Bars appear once the first answer comes in."
line instead.
- Roster orders newest-first; the top three rows light their dot
green and the freshest row gets a soft pulsing halo, so the
operator sees the room filling up at a glance.
- Student reveal "Your pick" tag moves to a top-edge ribbon above the
option text so it stops colliding with the count column on phones.
Editorial-lecture-hall direction: Source Serif 4 for question prose
and headlines, IBM Plex Sans chrome, IBM Plex Mono for tabular numerics
(countdown, scores, rank, session id, join URL). Single ink-blue accent
in light mode, brass-amber in dark mode; warm paper background instead
of the soft grey wash. Dropped border-radius from soft 14px to a sharp
2-4px to read as printed material rather than consumer app.
Density rebalanced for the two viewing surfaces. Student question text
goes to clamp(1.5rem, 2.4vw, 1.95rem) so it dominates a 390px phone;
admin chrome (Q-num, countdown, hist labels) tightened so the projector
read is "QUESTION LIVE" + question + options + distribution at a glance
across a 1920x1080 lecture hall. State badge is uppercase + tracked
with a status dot; live state pulses, urgent countdown (<=10s) blinks.
Leaderboard becomes a tabular scoreboard: hairline borders, alternating
row tint, gold/silver/bronze left-border medals on top 3 only (no other
rank treatments), mono numerics throughout. QR panel now has its own
SCAN TO JOIN eyebrow, the URL row sits below in mono with a copy CTA,
session id rendered as a code chip, anchored as one shareable artifact.
Picked-answer button gets a 2-step settle (scale 0.97 -> 1, color
swap), correct-row reveal animates an inset border-draw, countdown bar
gets a slow breathing highlight overlay; all motion respects
prefers-reduced-motion. JS change is one line per SPA: toggle .urgent
on the countdown when remaining <= 10s.
Backend simplification:
- The server now loads ONE pool JSON from $QUIZ_POOL_PATH at startup and
upserts a single canonical session. The session id comes from the pool
JSON's optional "session_id" field, falling back to $QUIZ_SESSION_ID.
- The multi-quiz / multi-session CRUD API is gone:
DELETED GET/POST /admin/api/quizzes
DELETED POST /admin/api/quizzes/upload
DELETED GET/POST /admin/api/sessions
DELETED GET /admin/login (HTML stub)
DELETED GET /admin/api/sessions/{sid}/csv (replaced by /admin/api/csv)
Replaced with a single-session control surface:
GET /admin/ — serves admin.html unconditionally
GET /admin/api/state — admin-gated; pool meta + state + QR + join URL
POST /admin/api/reset — admin-gated; wipe submissions + back to lobby
POST /admin/logout — clear admin cookie
GET /admin/api/csv — single-session results
WS /ws/instructor/{sid} — kept; new commands "next" + "reset"
- Instructor "Next" button is now a single state-driving command
(RoomManager.advance_to_next): from lobby it opens Q0; from question_open
it closes the current Q and opens the next; from question_closed it
opens the next; if past the last question it ends the session.
- New RoomManager.reset wipes submissions, participants, and per-question
state, then broadcasts a clean lobby.
- Student GET / now redirects to /?sid=<canonical> when no sid is given,
so the QR / share URL is fully deterministic.
Frontend rewrite (functional baseline; visual polish to follow):
- /admin/ is now a single SPA: GET /admin/api/state decides login form
vs dashboard. No separate /admin/login URL bar.
- Admin dashboard is state-driven with one primary action per state.
QR code, join URL, and live participant list are always visible on the
left so the operator can leave the page on a projector.
- Student answer buttons are big and tappable; reveal screen highlights
correct/wrong choice + shows score, total, and rank.
- Static admin/student SPAs share a CSS palette with light/dark support.
Tests rewritten around the single canonical session id.
The auto-bootstrapped session lets each test fixture skip the old
quiz/session creation dance. 39/39 tests pass.
Cleanup:
- Deleted CODEX_PROMPT.md, IMPLEMENTATION_REPORT.md, NOTES.md, SPEC.md,
static/observer.html (obsolete codex-build artifacts and the unused
observer view).
- .gitignore now blocks /pool.json (the runtime file the operator drops
on the server) and the leftover .codex_done / codex_run.log / etc.
- bootstrap.sh seeds /opt/quiz/pool.json from examples/pool_example.json
on first deploy so a fresh box reaches a usable state without manual
intervention; .env now includes QUIZ_POOL_PATH.
Unconditional 'exec < /dev/tty' broke non-interactive SSH invocations
where /dev/tty isn't openable. Move the reattach into the env-prompt
branch and skip it cleanly if /root/.quiz.env was pre-populated, with
a clear error if both stdin and /root/.quiz.env are missing.
One-shot deploy for fresh Ubuntu 24.04 root SSH:
curl -fsSL https://gitea.ahkhan.me/apps/quiz/raw/branch/master/deploy/bootstrap.sh | bash
bootstrap.sh: idempotent stage-by-stage installer for Caddy, Python venv,
quiz system user, repo clone to /opt/quiz, env-var prompts, systemd unit,
Caddyfile, and a healthz check. Reattaches /dev/tty so curl|bash can read
the admin password interactively.
quiz.service: uvicorn under the quiz system user (no shell, no SSH),
ProtectSystem=full, ProtectHome=true, PrivateTmp=true, NoNewPrivileges=true.
Caddyfile.tpl: reverse_proxy 127.0.0.1:8001 with auto Let's Encrypt;
DOMAIN substituted at install time.
examples/pool_example.json: generic demo pool, schema reference only.
README rewritten around the deploy flow + class-day lifecycle.
Real pools contain answer keys; only the generic demo pool example is
allowed to be tracked. Also excludes the .codex_done / codex_run.log /
codex_last_message.md leftovers from the original codex build run.
The first-pass JSON-decode hardening exposed two latent bugs that the
fuzz scenario hits as soon as the WS handler stays alive past a bad
message:
1) `data.get("type")` is called on whatever `receive_json()` decodes,
but valid JSON can be a list/string/number, not just a dict. Reject
non-object payloads with a structured bad_message error before
dispatch.
2) `submit_answer` did `if answer not in {"A","B","C","D"}` which
raises TypeError when the client sends an unhashable answer
(e.g. a dict). Add an isinstance(str) guard so any non-string
answer falls into the bad_answer branch instead of crashing the
handler.
31/31 pytest still passes. Together with the prior commit, the WS
handlers now survive the full set of fuzz payloads without dropping
the connection.
A single malformed JSON message (or a "WebSocket is not connected" race
on disconnect) was killing the per-client handler with an uncaught
exception in the ASGI app. The surrounding try/except only caught
WebSocketDisconnect, so the server would log a stack trace and the
client would silently drop.
Wrap receive_json() to catch JSONDecodeError, send a structured
{"type":"error","code":"bad_message"} ack, and continue. Widen the
outer except to (WebSocketDisconnect, RuntimeError) so disconnect
races on send/receive after close exit the handler cleanly instead
of bubbling up the ASGI stack.
Both student_ws and instructor_ws hardened in parallel. 31/31 pytest
suite still passes; this fixes the recurring fuzz-scenario warn and
the cycle-187-style cascade observed in the stress loop.
Two suites under tests/stress/, plus a tmux-friendly run_loop.sh
runner. Both boot a fresh uvicorn on an isolated DB per cycle and
log JSON line summaries to runs/.
api_stress.mjs covers WS-level scenarios that the existing pytest
suite does not exercise: 20-student happy path, late joiners with
correct remaining_ms, mid-question disconnect, browser-sleep + wake
to a different question_idx, cookie tampering and cross-session
cookie reuse, duplicate student_id, bad submit (out-of-order, wrong
idx, resubmit no-op), close-boundary race with auto-close, malformed
JSON fuzz, and flaky reconnect.
ui_stress.mjs drives the same flows in a real Chromium context via
playwright: happy UI, sleep/wake by closing+reopening a context with
the persisted cookie, document.cookie tampering attempt, and two
browser contexts joining with the same student_id.
Findings will be summarised in runs/summary.jsonl over time. One known
issue surfaces from the fuzz scenario: app/room.py student_ws's
receive_json call propagates JSONDecodeError out of the only
try/except (which catches WebSocketDisconnect), killing that client's
WS handler. Other clients are unaffected.
