fix(sec): remediate broken access control (BOLA/IDOR) across API + parent model (#59)

[franciszver]

Summary

Closes the systemic broken-access-control (BOLA/IDOR) cluster from the security review (epic #59). API routes authenticated the caller — or skipped auth entirely — but never checked that the requested object belonged to that caller. This PR centralizes the ownership check and applies it everywhere.

Implements the full remediation plan:

• Security P0 — Access-policy & role-registration decisions (blocker) #60/Security P1 — Shared object-access authz helper + cross-user 403 test harness #61 — foundation: new src/api/middleware/authz.py::assert_can_access_student(db, current_user, target_student_id) encoding the access model (student→own, tutor→TutorStudentAssignment, parent→denied, admin→all). Registration restricted to student only (tutor/parent become admin-provisioned).
• Security P2 — Close unauthenticated routes: practice, nudges, jobs (+WS) #62 — unauthenticated routes: practice (/assign, /assign/async, /complete, /summary), nudges (/check, /users/{id}, /{id}/engage), and jobs (GET + WebSocket) now require auth and authorize the target. The /jobs/{id}/ws WebSocket authenticates on connect (token query param) and closes 1008 before streaming.
• Security P3 — Fix authenticated IDORs: summaries, enhancements, messaging, dashboards, analytics #63 — read IDORs: summaries, enhancements conversation-context and conversation-history, and messaging threads now authorize the supplied id; parent dashboards and analytics engagement are locked to admin (parent↔student linkage deferred — see below). conversation-history previously let any tutor read any student's Q&A — now restricted to assigned tutors, consistent with its sibling.
• Security P4 — Overrides: derive tutor identity from JWT + relationship checks #64 — overrides: create_override derives tutor_id from the JWT (not the request body) and verifies the target Summary/PracticeAssignment belongs to the authorized student; GET history gains the same check.
• Security P5 — Verify green, regression gate, PR-template check #65 — gate: PR template now requires an object-access check on any *_id-taking route.

Review gates run

• /security-review (adversarial) — found and fixed a BOLA where create_override authorized student_id but not the target_id's owner.
• /simplify — flattened the jobs WS auth flow; direct 404 on malformed practice id.
• /code-review (deep) — found and fixed a BLOCKER (/practice/assign/async was missed) and hardened the helper to fail closed (403, not 500) on a None/malformed target.

Tests

615 passed, 1 skipped, 2 xfailed (was 549 on main). ~66 new authz tests, red-first: cross-user access → 403, no-auth on the previously-open routes → 401, malformed ids → 422, owner/assigned-tutor/linked-parent/admin → 2xx. Includes a WebSocket owner-accept test for /jobs/{id}/ws and parent linked/unlinked coverage.

Service-to-service auth — investigated, resolved as docs-only (#67)

The docs claimed X-API-Key service-to-service auth (Rails calling these routes). Research across docs, callers, and full git history found: no Rails code ever existed, X-API-Key was never implemented server-side, and there is no scheduler/cron caller — render.yaml runs only web services, there's no scheduler library, and nudges fire in-process during the frontend's authenticated GET /nudges/users/{id} call. Every real caller is the JWT-sending React frontend. So no live caller breaks. This PR updates the docs to state JWT-only and removes the dead ai_service_api_key/rails_app_url config.

Follow-ups — all resolved in this PR

• Security: implement or confirm service-to-service auth (X-API-Key) for Rails-called routes #67 — service-to-service auth investigated; resolved as a docs/dead-config fix (see above).
• Build ParentStudentAssignment model + re-open parent dashboards/analytics #68 — built ParentStudentAssignment (model + migration 004), extended the helper with a fail-closed parent branch, and re-opened parent dashboards + engagement to linked parents (/parent/students now returns only linked students; links are admin/seed-provisioned, no self-service linking endpoint). Registration stays student-only.
• Tighten handler *_id params from str to UUID for automatic 422 validation #69 — retyped handler *_id params str→UUID; malformed ids now return 422.
• conversation-history cross-tutor IDOR and the WebSocket owner-accept test were also fixed here.

Every new/re-opened route routes through require_role + assert_can_access_student, both deny-by-default; a fresh adversarial review of the parent re-opening confirmed no fail-open path or cross-parent leak.

Closes #59, #60, #61, #62, #63, #64, #65, #67, #68, #69.

🤖 Generated with Claude Code