deploy: backend from ef76a7e

main.py

@@ -443,6 +443,9 @@ ROLE_POLICIES: Dict[str, Set[str]] = {
     "/api/rag/lesson": ALL_APP_ROLES,
     "/api/rag/generate-problem": TEACHER_OR_ADMIN,
     "/api/rag/analysis-context": TEACHER_OR_ADMIN,
+    "/api/rag/documents/by-subject/{subject}": ADMIN_ONLY,
+    "/api/rag/documents/by-source": ADMIN_ONLY,
+    "/api/rag/documents/all": ADMIN_ONLY,
     "/api/feedback/import-grounded": TEACHER_OR_ADMIN,
     "/api/feedback/import-grounded/summary": TEACHER_OR_ADMIN,
     "/api/import-grounded/access-audit": TEACHER_OR_ADMIN,
@@ -480,6 +483,8 @@ ROLE_POLICIES: Dict[str, Set[str]] = {
     "/api/admin/model-config/reset": ADMIN_ONLY,
     "/api/lessons/videos/search": ALL_APP_ROLES,
     "/api/lesson/personalized": ALL_APP_ROLES,
+    "/api/at-risk/resolve": ALL_APP_ROLES,
+    "/api/at-risk/fallback/{uid}/{topic_id}": ALL_APP_ROLES,
     "/api/quiz-battle/generate": ALL_APP_ROLES,
     "/api/quiz-battle/ingest-pdf": TEACHER_OR_ADMIN,
     "/api/quiz-battle/bank-status": TEACHER_OR_ADMIN,

routes/at_risk_resolution.py

@@ -9,7 +9,7 @@ import logging
 from datetime import datetime, timezone
 from typing import Any, Optional
 
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel, Field
 
 from services.ai_client import CHAT_MODEL
@@ -64,6 +64,16 @@ class ResolveResponse(BaseModel):
     fallback_generated: int = 0
 
 
+def _require_student_or_staff_access(uid: str, request: Request) -> None:
+    user = getattr(request.state, "user", None)
+    role = getattr(user, "role", None)
+    if role in {"teacher", "admin"}:
+        return
+    if role == "student" and getattr(user, "uid", None) == uid:
+        return
+    raise HTTPException(status_code=403, detail="Forbidden for this student")
+
+
 # ─── Resolution Logic ──────────────────────────────────────────────
 
 def _resolve_topic(
@@ -261,8 +271,9 @@ def _generate_fallback_content(
 # ─── Endpoints ─────────────────────────────────────────────────────
 
 @router.post("/resolve", response_model=ResolveResponse)
-async def resolve_at_risk_topics(request: ResolveRequest):
+async def resolve_at_risk_topics(request: ResolveRequest, http_request: Request):
     """Resolve flagged topics into resolution states and generate fallback content."""
+    _require_student_or_staff_access(request.uid, http_request)
     try:
         firestore_client = fs.client()
     except Exception:
@@ -311,8 +322,9 @@ async def resolve_at_risk_topics(request: ResolveRequest):
 
 
 @router.get("/fallback/{uid}/{topic_id}")
-async def get_fallback_content(uid: str, topic_id: str):
+async def get_fallback_content(uid: str, topic_id: str, request: Request):
     """Fetch cached fallback study brief for a flagged topic."""
+    _require_student_or_staff_access(uid, request)
     try:
         firestore_client = fs.client()
     except Exception:

tests/role_policy_expectations.py

@@ -0,0 +1,318 @@
+"""Independent auth contract and route registry reviewed for regression tests."""
+
+ALL_ROLES = frozenset({"student", "teacher", "admin"})
+TEACHER_ADMIN = frozenset({"teacher", "admin"})
+ADMIN_ONLY = frozenset({"admin"})
+
+# Curated contract values, intentionally literal and independent of main.ROLE_POLICIES.
+EXPECTED_ROLE_POLICIES = {
+    "/api/chat": ALL_ROLES,
+    "/api/chat/stream": ALL_ROLES,
+    "/api/verify-solution": ALL_ROLES,
+    "/api/predict-risk": TEACHER_ADMIN,
+    "/api/predict-risk/batch": TEACHER_ADMIN,
+    "/api/learning-path": ALL_ROLES,
+    "/api/analytics/daily-insight": TEACHER_ADMIN,
+    "/api/analytics/class/{class_id}": TEACHER_ADMIN,
+    "/api/analytics/class/{class_id}/students": TEACHER_ADMIN,
+    "/api/analytics/class/{class_id}/topics": TEACHER_ADMIN,
+    "/api/analytics/class/{class_id}/refresh-insights": TEACHER_ADMIN,
+    "/api/analytics/class/{class_id}/invalidate-cache": ALL_ROLES,
+    "/api/intervention/generate": TEACHER_ADMIN,
+    "/api/intervention/{student_id}": TEACHER_ADMIN,
+    "/api/intervention/{student_id}/step/{step_number}/complete": ALL_ROLES,
+    "/api/intervention/{student_id}/export-pdf": TEACHER_ADMIN,
+    "/api/pipeline/event": ALL_ROLES,
+    "/api/pipeline/profile/{student_id}": ALL_ROLES,
+    "/api/pipeline/profile/{student_id}/recompute": TEACHER_ADMIN,
+    "/api/pipeline/admin/backfill": ADMIN_ONLY,
+    "/api/upload/class-records": TEACHER_ADMIN,
+    "/api/class-section/{class_section_id}": TEACHER_ADMIN,
+    "/api/upload/class-records/risk-refresh/recent": TEACHER_ADMIN,
+    "/api/import/student-accounts/preview": TEACHER_ADMIN,
+    "/api/import/student-accounts/commit": TEACHER_ADMIN,
+    "/api/admin/users": ADMIN_ONLY,
+    "/api/admin/users/bulk-action": ADMIN_ONLY,
+    "/api/admin/school-analytics": ADMIN_ONLY,
+    "/api/teacher/create-student-account": TEACHER_ADMIN,
+    "/api/upload/course-materials": TEACHER_ADMIN,
+    "/api/upload/course-materials/recent": TEACHER_ADMIN,
+    "/api/teacher-materials/upload": TEACHER_ADMIN,
+    "/api/course-materials/topics": TEACHER_ADMIN,
+    "/api/quiz/generate": ALL_ROLES,
+    "/api/quiz/generate-async": ALL_ROLES,
+    "/api/quiz/preview": ALL_ROLES,
+    "/api/lesson/generate": TEACHER_ADMIN,
+    "/api/lesson/generate-async": TEACHER_ADMIN,
+    "/api/rag/lesson": ALL_ROLES,
+    "/api/rag/generate-problem": TEACHER_ADMIN,
+    "/api/rag/analysis-context": TEACHER_ADMIN,
+    "/api/rag/documents/by-subject/{subject}": ADMIN_ONLY,
+    "/api/rag/documents/by-source": ADMIN_ONLY,
+    "/api/rag/documents/all": ADMIN_ONLY,
+    "/api/feedback/import-grounded": TEACHER_ADMIN,
+    "/api/feedback/import-grounded/summary": TEACHER_ADMIN,
+    "/api/import-grounded/access-audit": TEACHER_ADMIN,
+    "/api/quiz/student-competency": TEACHER_ADMIN,
+    "/api/calculator/evaluate": ALL_ROLES,
+    "/api/diagnostic/generate": ALL_ROLES,
+    "/api/diagnostic/submit": ALL_ROLES,
+    "/api/diagnostic/analyze": ALL_ROLES,
+    "/api/student/competency-analysis": TEACHER_ADMIN,
+    "/api/risk/train-model": ADMIN_ONLY,
+    "/api/predict-risk/enhanced": TEACHER_ADMIN,
+    "/api/quiz/calibrate-difficulty": TEACHER_ADMIN,
+    "/api/quiz/adaptive-select": TEACHER_ADMIN,
+    "/api/learning/recommend-topics": TEACHER_ADMIN,
+    "/api/analytics/student-summary": ALL_ROLES,
+    "/api/analytics/class-insights": TEACHER_ADMIN,
+    "/api/analytics/refresh-cache": ADMIN_ONLY,
+    "/api/testing/reset-data": ALL_ROLES,
+    "/api/hf/monitoring": ADMIN_ONLY,
+    "/api/dev/generate-mock-data": ADMIN_ONLY,
+    "/api/analytics/config": TEACHER_ADMIN,
+    "/api/analytics/imported-class-overview": TEACHER_ADMIN,
+    "/api/analytics/topic-mastery": TEACHER_ADMIN,
+    "/api/automation/diagnostic-completed": ADMIN_ONLY,
+    "/api/automation/quiz-submitted": ADMIN_ONLY,
+    "/api/automation/student-enrolled": ADMIN_ONLY,
+    "/api/automation/data-imported": ADMIN_ONLY,
+    "/api/automation/content-updated": ADMIN_ONLY,
+    "/api/admin/model-config": ADMIN_ONLY,
+    "/api/admin/upload-pdf": ADMIN_ONLY,
+    "/api/admin/reingest-pdf": ADMIN_ONLY,
+    "/api/admin/delete-file": ADMIN_ONLY,
+    "/api/admin/model-config/profile": ADMIN_ONLY,
+    "/api/admin/model-config/override": ADMIN_ONLY,
+    "/api/admin/model-config/reset": ADMIN_ONLY,
+    "/api/lessons/videos/search": ALL_ROLES,
+    "/api/lesson/personalized": ALL_ROLES,
+    "/api/at-risk/resolve": ALL_ROLES,
+    "/api/at-risk/fallback/{uid}/{topic_id}": ALL_ROLES,
+    "/api/quiz-battle/generate": ALL_ROLES,
+    "/api/quiz-battle/ingest-pdf": TEACHER_ADMIN,
+    "/api/quiz-battle/bank-status": TEACHER_ADMIN,
+    "/api/class-records/upload": TEACHER_ADMIN,
+}
+
+# Fixed route/method manifest. New endpoints require an explicit review and
+# classification; no route becomes public merely by being absent from policy.
+EXPECTED_REGISTERED_ROUTE_METHODS = {
+    "/openapi.json": frozenset({"GET", "HEAD"}),
+    "/docs": frozenset({"GET", "HEAD"}),
+    "/docs/oauth2-redirect": frozenset({"GET", "HEAD"}),
+    "/redoc": frozenset({"GET", "HEAD"}),
+    "/api/rag/health": frozenset({"GET"}),
+    "/api/rag/lesson": frozenset({"POST"}),
+    "/api/rag/generate-problem": frozenset({"POST"}),
+    "/api/rag/analysis-context": frozenset({"POST"}),
+    "/api/rag/documents": frozenset({"GET"}),
+    "/api/rag/documents/by-subject/{subject}": frozenset({"DELETE"}),
+    "/api/rag/documents/by-source": frozenset({"DELETE"}),
+    "/api/rag/documents/all": frozenset({"DELETE"}),
+    "/api/admin/model-config": frozenset({"GET"}),
+    "/api/admin/model-config/profile": frozenset({"POST"}),
+    "/api/admin/model-config/override": frozenset({"POST"}),
+    "/api/admin/model-config/reset": frozenset({"DELETE"}),
+    "/api/admin/reingest-status": frozenset({"GET"}),
+    "/api/admin/upload-pdf": frozenset({"POST"}),
+    "/api/admin/reingest-pdf": frozenset({"POST"}),
+    "/api/admin/delete-file": frozenset({"POST"}),
+    "/api/admin/dashboard-analytics": frozenset({"GET"}),
+    "/api/admin/school-analytics": frozenset({"GET"}),
+    "/api/curriculum/subjects": frozenset({"GET"}),
+    "/api/curriculum/subjects/{subject_id}": frozenset({"GET"}),
+    "/api/curriculum/subjects/{subject_id}/topics": frozenset({"GET"}),
+    "/api/curriculum/subjects/{subject_id}/topics/{topic_id}": frozenset({"GET"}),
+    "/api/diagnostic/generate": frozenset({"POST"}),
+    "/api/diagnostic/submit": frozenset({"POST"}),
+    "/api/diagnostic/analyze": frozenset({"POST"}),
+    "/api/diagnostic/results/{user_id}": frozenset({"GET"}),
+    "/api/lessons/videos/search": frozenset({"POST"}),
+    "/api/quiz-battle/generate": frozenset({"POST"}),
+    "/api/quiz-battle/ingest-pdf": frozenset({"POST"}),
+    "/api/quiz-battle/bank-status": frozenset({"GET"}),
+    "/api/quiz-battle/results": frozenset({"GET"}),
+    "/api/teacher-materials/upload": frozenset({"POST"}),
+    "/api/teacher-materials/{moduleId}/generate-quiz": frozenset({"POST"}),
+    "/api/templates/class-records": frozenset({"GET"}),
+    "/api/class-records/upload": frozenset({"POST"}),
+    "/api/class-records/intervention-plan": frozenset({"POST"}),
+    "/api/class-records": frozenset({"GET"}),
+    "/api/class-records/{uploadId}/students": frozenset({"GET"}),
+    "/api/class-records/{uploadId}/ai-report": frozenset({"POST"}),
+    "/api/risk/compute": frozenset({"POST"}),
+    "/api/risk/compute/batch": frozenset({"POST"}),
+    "/api/tutor-checkin": frozenset({"POST"}),
+    "/api/practice/generate": frozenset({"POST"}),
+    "/api/practice/submit": frozenset({"POST"}),
+    "/api/practice/stats/{userId}": frozenset({"GET"}),
+    "/api/practice/history/{userId}": frozenset({"GET"}),
+    "/api/try-it-yourself/resolve-question": frozenset({"POST"}),
+    "/api/try-it-yourself/use-hint": frozenset({"POST"}),
+    "/api/try-it-yourself/complete-session": frozenset({"POST"}),
+    "/api/try-it-yourself/generate-round": frozenset({"POST"}),
+    "/api/try-it-yourself/shadow-retry": frozenset({"POST"}),
+    "/api/admin/ai-monitoring/summary": frozenset({"GET"}),
+    "/api/admin/ai-monitoring/refresh": frozenset({"POST"}),
+    "/api/analytics/class/{class_id}": frozenset({"GET"}),
+    "/api/analytics/class/{class_id}/students": frozenset({"GET"}),
+    "/api/analytics/class/{class_id}/topics": frozenset({"GET"}),
+    "/api/analytics/class/{class_id}/refresh-insights": frozenset({"POST"}),
+    "/api/analytics/class/{class_id}/invalidate-cache": frozenset({"POST"}),
+    "/api/intervention/generate": frozenset({"POST"}),
+    "/api/intervention/{student_id}": frozenset({"GET"}),
+    "/api/intervention/{student_id}/step/{step_number}/complete": frozenset({"POST"}),
+    "/api/intervention/{student_id}/export-pdf": frozenset({"GET"}),
+    "/api/pipeline/event": frozenset({"POST"}),
+    "/api/pipeline/nudge/{student_id}": frozenset({"POST"}),
+    "/api/pipeline/profile/{student_id}": frozenset({"GET"}),
+    "/api/pipeline/profile/{student_id}/recompute": frozenset({"POST"}),
+    "/api/pipeline/admin/backfill": frozenset({"POST"}),
+    "/api/deepseek/weakness-detection": frozenset({"POST"}),
+    "/api/deepseek/module-preview": frozenset({"POST"}),
+    "/api/deepseek/study-tips": frozenset({"POST"}),
+    "/api/at-risk/resolve": frozenset({"POST"}),
+    "/api/at-risk/fallback/{uid}/{topic_id}": frozenset({"GET"}),
+    "/api/curriculum/generate-module": frozenset({"POST"}),
+    "/api/mastery/record": frozenset({"POST"}),
+    "/api/jev/verify": frozenset({"POST"}),
+    "/health": frozenset({"GET"}),
+    "/api/memory/health": frozenset({"GET"}),
+    "/debug/scope-info": frozenset({"GET"}),
+    "/": frozenset({"GET"}),
+    "/api/chat": frozenset({"POST"}),
+    "/api/chat/stream": frozenset({"POST"}),
+    "/api/verify-solution": frozenset({"POST"}),
+    "/api/predict-risk": frozenset({"POST"}),
+    "/api/predict-risk/batch": frozenset({"POST"}),
+    "/api/learning-path": frozenset({"POST"}),
+    "/api/analytics/daily-insight": frozenset({"POST"}),
+    "/api/import/student-accounts/preview": frozenset({"POST"}),
+    "/api/import/student-accounts/commit": frozenset({"POST"}),
+    "/api/admin/audit-log": frozenset({"POST"}),
+    "/api/admin/users": frozenset({"GET", "PATCH", "POST", "DELETE"}),
+    "/api/admin/users/bulk-action": frozenset({"POST"}),
+    "/api/teacher/create-student-account": frozenset({"POST"}),
+    "/api/upload/class-records/risk-refresh/recent": frozenset({"GET"}),
+    "/api/class-section/{class_section_id}": frozenset({"DELETE"}),
+    "/api/upload/class-records": frozenset({"POST"}),
+    "/api/upload/course-materials": frozenset({"POST"}),
+    "/api/upload/course-materials/recent": frozenset({"GET"}),
+    "/api/course-materials/topics": frozenset({"GET"}),
+    "/api/lesson/generate": frozenset({"POST"}),
+    "/api/lesson-plans/{lesson_id}/publish": frozenset({"POST"}),
+    "/api/lesson/generate-async": frozenset({"POST"}),
+    "/api/feedback/import-grounded": frozenset({"POST"}),
+    "/api/feedback/import-grounded/summary": frozenset({"GET"}),
+    "/api/import-grounded/access-audit": frozenset({"GET"}),
+    "/api/quiz/generate": frozenset({"POST"}),
+    "/api/quiz/preview": frozenset({"POST"}),
+    "/api/quiz/generate-async": frozenset({"POST"}),
+    "/api/tasks/{task_id}": frozenset({"GET"}),
+    "/api/tasks": frozenset({"GET"}),
+    "/api/tasks/{task_id}/cancel": frozenset({"POST"}),
+    "/api/hf/monitoring": frozenset({"GET"}),
+    "/api/quiz/topics": frozenset({"GET"}),
+    "/api/quiz/student-competency": frozenset({"POST"}),
+    "/api/calculator/evaluate": frozenset({"POST"}),
+    "/api/student/competency-analysis": frozenset({"POST"}),
+    "/api/risk/train-model": frozenset({"POST"}),
+    "/api/predict-risk/enhanced": frozenset({"POST"}),
+    "/api/quiz/calibrate-difficulty": frozenset({"POST"}),
+    "/api/quiz/adaptive-select": frozenset({"POST"}),
+    "/api/learning/recommend-topics": frozenset({"POST"}),
+    "/api/analytics/student-summary": frozenset({"GET"}),
+    "/api/analytics/class-insights": frozenset({"POST"}),
+    "/api/analytics/refresh-cache": frozenset({"POST"}),
+    "/api/dev/generate-mock-data": frozenset({"POST"}),
+    "/api/testing/reset-data": frozenset({"POST"}),
+    "/api/analytics/config": frozenset({"GET"}),
+    "/api/analytics/imported-class-overview": frozenset({"GET"}),
+    "/api/analytics/topic-mastery": frozenset({"GET"}),
+    "/api/automation/diagnostic-completed": frozenset({"POST"}),
+    "/api/automation/quiz-submitted": frozenset({"POST"}),
+    "/api/automation/student-enrolled": frozenset({"POST"}),
+    "/api/automation/data-imported": frozenset({"POST"}),
+    "/api/automation/content-updated": frozenset({"POST"}),
+    "/api/lesson/diagnostic": frozenset({"POST"}),
+    "/api/lessons/generate": frozenset({"POST"}),
+    "/api/progress/evaluate": frozenset({"POST"}),
+    "/api/quiz/adaptive": frozenset({"POST"}),
+    "/api/learning/path": frozenset({"POST"}),
+    "/api/lesson/personalized": frozenset({"POST"}),
+}
+
+PUBLIC_ROUTE_EXCEPTIONS = {
+    ("GET", "/openapi.json"): "OpenAPI schema endpoint",
+    ("HEAD", "/openapi.json"): "OpenAPI schema endpoint",
+    ("GET", "/docs"): "Swagger UI endpoint",
+    ("HEAD", "/docs"): "Swagger UI endpoint",
+    ("GET", "/docs/oauth2-redirect"): "Swagger OAuth redirect endpoint",
+    ("HEAD", "/docs/oauth2-redirect"): "Swagger OAuth redirect endpoint",
+    ("GET", "/redoc"): "ReDoc endpoint",
+    ("HEAD", "/redoc"): "ReDoc endpoint",
+    ("GET", "/health"): "Unauthenticated liveness endpoint",
+    ("GET", "/"): "Unauthenticated API identity endpoint",
+    ("GET", "/api/rag/health"): "Unauthenticated RAG health endpoint",
+    ("GET", "/api/templates/class-records"): "Unauthenticated static import template",
+    ("GET", "/api/quiz/topics"): "Public topic catalog",
+    ("POST", "/api/jev/verify"): "Public verification endpoint; service controls availability",
+    ("GET", "/debug/scope-info"): "Non-API diagnostic route bypasses AuthMiddleware",
+}
+
+# AuthMiddleware authenticates these endpoints, but they have no route-specific
+# role restriction. Keep that distinct from endpoints with in-handler guards.
+AUTHENTICATED_ROUTE_EXCEPTIONS = {
+    ("GET", "/api/curriculum/subjects"): "Authenticated curriculum catalog; no role restriction",
+    ("GET", "/api/curriculum/subjects/{subject_id}"): "Authenticated curriculum catalog; no role restriction",
+    ("GET", "/api/curriculum/subjects/{subject_id}/topics"): "Authenticated curriculum catalog; no role restriction",
+    ("GET", "/api/curriculum/subjects/{subject_id}/topics/{topic_id}"): "Authenticated curriculum catalog; no role restriction",
+    ("GET", "/api/memory/health"): "Authenticated health endpoint; no role restriction",
+    ("GET", "/api/rag/documents"): "Authenticated RAG document listing; no role restriction",
+    ("POST", "/api/curriculum/generate-module"): "Authenticated module generation; no role restriction",
+    ("POST", "/api/deepseek/module-preview"): "Authenticated preview generation; no role restriction",
+    ("POST", "/api/deepseek/study-tips"): "Authenticated study tips; no role restriction",
+    ("POST", "/api/deepseek/weakness-detection"): "Authenticated weakness detection; no role restriction",
+    ("POST", "/api/learning/path"): "Authenticated learning path; no role restriction",
+    ("POST", "/api/lesson/diagnostic"): "Authenticated diagnostic lesson; no role restriction",
+    ("POST", "/api/lessons/generate"): "Authenticated lesson generation; no role restriction",
+    ("POST", "/api/mastery/record"): "Authenticated mastery record; no role restriction",
+    ("POST", "/api/progress/evaluate"): "Authenticated progress evaluation; no role restriction",
+    ("POST", "/api/quiz/adaptive"): "Authenticated adaptive quiz; no role restriction",
+    ("POST", "/api/risk/compute"): "Authenticated risk computation; no role restriction",
+    ("POST", "/api/risk/compute/batch"): "Authenticated batch risk computation; no role restriction",
+    ("POST", "/api/tutor-checkin"): "Authenticated tutor check-in; no role restriction",
+}
+
+# These routes perform an explicit handler-level ownership or role check.
+HANDLER_GUARDED_ROUTE_EXCEPTIONS = {
+    ("GET", "/api/diagnostic/results/{user_id}"): "student UID ownership check",
+    ("POST", "/api/pipeline/event"): "student event owner check",
+    ("POST", "/api/pipeline/nudge/{student_id}"): "student target ownership check",
+    ("POST", "/api/admin/audit-log"): "admin/teacher role check",
+    ("GET", "/api/admin/reingest-status"): "admin role check",
+    ("GET", "/api/admin/dashboard-analytics"): "admin role check",
+    ("GET", "/api/admin/ai-monitoring/summary"): "admin role check",
+    ("POST", "/api/admin/ai-monitoring/refresh"): "admin role check",
+    ("GET", "/api/quiz-battle/results"): "teacher/admin role check",
+    ("POST", "/api/teacher-materials/{moduleId}/generate-quiz"): "teacher/admin role check",
+    ("POST", "/api/class-records/intervention-plan"): "teacher/admin role check",
+    ("GET", "/api/class-records"): "teacher/admin role check",
+    ("GET", "/api/class-records/{uploadId}/students"): "teacher/admin role check",
+    ("POST", "/api/class-records/{uploadId}/ai-report"): "teacher/admin role check",
+    ("POST", "/api/class-records/upload"): "teacher/admin role check",
+    ("POST", "/api/practice/generate"): "authenticated user and owner checks",
+    ("POST", "/api/practice/submit"): "authenticated user and owner checks",
+    ("GET", "/api/practice/stats/{userId}"): "authenticated user and owner checks",
+    ("GET", "/api/practice/history/{userId}"): "authenticated user and owner checks",
+    ("POST", "/api/tasks/{task_id}/cancel"): "task owner or admin check",
+    ("GET", "/api/tasks/{task_id}"): "task owner or admin check",
+    ("GET", "/api/tasks"): "task owner filtering or admin check",
+    ("POST", "/api/lesson-plans/{lesson_id}/publish"): "teacher/admin role and lesson owner check",
+    ("POST", "/api/try-it-yourself/resolve-question"): "authenticated user ownership check",
+    ("POST", "/api/try-it-yourself/use-hint"): "authenticated user ownership check",
+    ("POST", "/api/try-it-yourself/complete-session"): "authenticated user ownership check",
+    ("POST", "/api/try-it-yourself/generate-round"): "authenticated user ownership check",
+    ("POST", "/api/try-it-yourself/shadow-retry"): "authenticated user ownership check",
+}

tests/test_api.py

@@ -197,6 +197,36 @@ class TestAuthMiddleware:
         assert len(data["materials"]) == 1
         assert data["materials"][0]["materialId"] == "mat-auth-1"
 
+class TestRequestTimeoutBoundary:
+    def test_request_timeout_is_terminal_504(self):
+        from starlette.requests import Request
+        from starlette.responses import Response
+
+        request = Request({
+            "type": "http",
+            "asgi": {"version": "3.0"},
+            "http_version": "1.1",
+            "method": "POST",
+            "scheme": "http",
+            "path": "/api/chat",
+            "raw_path": b"/api/chat",
+            "query_string": b"",
+            "headers": [],
+            "client": ("testclient", 50000),
+            "server": ("testserver", 80),
+        })
+        middleware = main_module.RequestMiddleware(app)
+
+        async def slow_handler(_request):
+            await asyncio.sleep(0.02)
+            return Response("late response")
+
+        with patch.object(main_module, "REQUEST_TIMEOUT_SECONDS", 0.001):
+            response = asyncio.run(middleware.dispatch(request, slow_handler))
+
+        assert response.status_code == 504
+        assert json.loads(response.body)["detail"] == "Request timed out after 0.001s"
+
 
 # ─── Chat Endpoint ─────────────────────────────────────────────
 

tests/test_audit_remediation.py

@@ -14,10 +14,61 @@ from fastapi.testclient import TestClient
 
 import main as main_module
 from main import app, resolve_required_roles, ROLE_POLICIES
+from backend.tests.role_policy_expectations import (
+    EXPECTED_REGISTERED_ROUTE_METHODS,
+    EXPECTED_ROLE_POLICIES,
+    AUTHENTICATED_ROUTE_EXCEPTIONS,
+    HANDLER_GUARDED_ROUTE_EXCEPTIONS,
+    PUBLIC_ROUTE_EXCEPTIONS,
+)
 
 
 class TestRolePolicyMatching:
-    """Verify GATE-01: parameterized route matching."""
+    """Verify independently reviewed policy and route classification contracts."""
+
+    def test_production_role_policies_match_reviewed_expected_table(self):
+        assert ROLE_POLICIES == EXPECTED_ROLE_POLICIES
+
+    def test_registered_route_methods_match_reviewed_manifest(self):
+        discovered = {}
+        for registered in app.routes:
+            route_collection = getattr(registered, "original_router", None)
+            candidates = route_collection.routes if route_collection is not None else [registered]
+            for route in candidates:
+                path = getattr(route, "path", None)
+                methods = getattr(route, "methods", None)
+                if path and methods:
+                    discovered.setdefault(path, set()).update(methods)
+
+        actual = {path: frozenset(methods) for path, methods in discovered.items()}
+        assert actual == EXPECTED_REGISTERED_ROUTE_METHODS
+
+    def test_every_registered_method_has_policy_or_reviewed_exception(self):
+        registered_methods = {
+            (method, path)
+            for path, methods in EXPECTED_REGISTERED_ROUTE_METHODS.items()
+            for method in methods
+        }
+        policy_methods = {
+            (method, path)
+            for path, methods in EXPECTED_REGISTERED_ROUTE_METHODS.items()
+            if path in EXPECTED_ROLE_POLICIES
+            for method in methods
+        }
+        reviewed_exceptions = (
+            set(PUBLIC_ROUTE_EXCEPTIONS)
+            | set(AUTHENTICATED_ROUTE_EXCEPTIONS)
+            | set(HANDLER_GUARDED_ROUTE_EXCEPTIONS)
+        )
+        unclassified = sorted(registered_methods - policy_methods - reviewed_exceptions)
+
+        assert not unclassified, f"Registered routes lack a role policy or reviewed exception: {unclassified}"
+        assert not (set(PUBLIC_ROUTE_EXCEPTIONS) & set(HANDLER_GUARDED_ROUTE_EXCEPTIONS))
+        assert not (set(PUBLIC_ROUTE_EXCEPTIONS) & set(AUTHENTICATED_ROUTE_EXCEPTIONS))
+        assert not (set(AUTHENTICATED_ROUTE_EXCEPTIONS) & set(HANDLER_GUARDED_ROUTE_EXCEPTIONS))
+        assert all(PUBLIC_ROUTE_EXCEPTIONS.values())
+        assert all(AUTHENTICATED_ROUTE_EXCEPTIONS.values())
+        assert all(HANDLER_GUARDED_ROUTE_EXCEPTIONS.values())
 
     def test_literal_routes_resolve_correctly(self):
         assert resolve_required_roles("/api/chat") == {"student", "teacher", "admin"}
@@ -35,6 +86,15 @@ class TestRolePolicyMatching:
         assert resolve_required_roles("/api/nonexistent/unknown") is None
         assert resolve_required_roles("/some/random/path") is None
 
+    def test_missing_bearer_is_denied_before_handler(self):
+        client = TestClient(app)
+        with patch.object(main_module, "_firebase_ready", True), \
+             patch.object(main_module, "_init_firebase_admin"):
+            response = client.get("/api/admin/model-config")
+
+        assert response.status_code == 401
+        assert response.json()["detail"] == "Missing or invalid Authorization bearer token"
+
 
 class TestPipelineProfileOwnership:
     """Verify GATE-02: student can only access own profile, teacher/admin can access any."""
@@ -82,6 +142,86 @@ class TestPipelineProfileOwnership:
             assert response.json()["student_id"] == "student_B"
 
 
+class TestRagAdminPolicy:
+    @pytest.mark.parametrize(
+        "path",
+        [
+            "/api/rag/documents/all",
+            "/api/rag/documents/by-source?source_file=curriculum.pdf",
+            "/api/rag/documents/by-subject/General%20Mathematics",
+        ],
+    )
+    def test_student_cannot_delete_rag_documents(self, path):
+        client = TestClient(app, headers={"Authorization": "Bearer mock_token_student_A"})
+        with patch.object(main_module, "_firebase_ready", True), \
+             patch.object(main_module, "_init_firebase_admin"), \
+             patch.object(main_module.firebase_auth, "verify_id_token", return_value={"uid": "student_A", "role": "student"}), \
+             patch("routes.rag_routes.get_vectorstore_components") as vectorstore_components:
+            response = client.delete(path)
+
+        assert response.status_code == 403
+        vectorstore_components.assert_not_called()
+
+
+class TestAtRiskOwnership:
+    @pytest.mark.parametrize(
+        ("method", "path", "payload"),
+        [
+            (
+                "post",
+                "/api/at-risk/resolve",
+                {"uid": "student_B", "flagged_topics": []},
+            ),
+            ("get", "/api/at-risk/fallback/student_B/algebra", None),
+        ],
+    )
+    def test_student_cannot_access_other_student_at_risk_data(self, method, path, payload):
+        client = TestClient(app, headers={"Authorization": "Bearer mock_token_student_A"})
+        with patch.object(main_module, "_firebase_ready", True), \
+             patch.object(main_module, "_init_firebase_admin"), \
+             patch.object(main_module.firebase_auth, "verify_id_token", return_value={"uid": "student_A", "role": "student"}), \
+             patch("routes.at_risk_resolution.fs.client") as firestore_client:
+            response = getattr(client, method)(path, json=payload) if payload is not None else getattr(client, method)(path)
+
+        assert response.status_code == 403
+        firestore_client.assert_not_called()
+
+    @pytest.mark.parametrize(
+        ("method", "path", "payload"),
+        [
+            ("post", "/api/at-risk/resolve", {"uid": "student_A", "flagged_topics": []}),
+            ("get", "/api/at-risk/fallback/student_A/algebra", None),
+        ],
+    )
+    def test_student_can_access_own_at_risk_data(self, method, path, payload):
+        client = TestClient(app, headers={"Authorization": "Bearer mock_token_student_A"})
+        firestore = MagicMock()
+        fallback_doc = firestore.collection.return_value.document.return_value.collection.return_value.document.return_value.get.return_value
+        fallback_doc.exists = True
+        fallback_doc.to_dict.return_value = {"summary": "Owned fallback"}
+        with patch.object(main_module, "_firebase_ready", True), \
+             patch.object(main_module, "_init_firebase_admin"), \
+             patch.object(main_module.firebase_auth, "verify_id_token", return_value={"uid": "student_A", "role": "student"}), \
+             patch("routes.at_risk_resolution.fs.client", return_value=firestore):
+            response = getattr(client, method)(path, json=payload) if payload is not None else getattr(client, method)(path)
+
+        assert response.status_code == 200
+
+    def test_teacher_can_access_another_students_at_risk_data(self):
+        client = TestClient(app, headers={"Authorization": "Bearer mock_token_teacher_T"})
+        firestore = MagicMock()
+        fallback_doc = firestore.collection.return_value.document.return_value.collection.return_value.document.return_value.get.return_value
+        fallback_doc.exists = False
+        with patch.object(main_module, "_firebase_ready", True), \
+             patch.object(main_module, "_init_firebase_admin"), \
+             patch.object(main_module.firebase_auth, "verify_id_token", return_value={"uid": "teacher_T", "role": "teacher"}), \
+             patch("routes.at_risk_resolution.fs.client", return_value=firestore) as firestore_client:
+            response = client.get("/api/at-risk/fallback/student_B/algebra")
+
+        assert response.status_code == 404
+        firestore_client.assert_called_once()
+
+
 class TestDiagnosticResultsEndpoint:
     """Verify GATE-05: /api/diagnostic/results/{user_id} in canonical diagnostic router."""
 

tests/test_rag_lesson_jev.py

@@ -109,3 +109,18 @@ def test_jev_exception_fails_open_cleanly(monkeypatch) -> None:
     assert response.status_code == 200
     assert response.json()["sections"][0]["content"] == "Generated introduction hallucination."
     assert response.json()["jevVerification"] is None
+
+
+def test_empty_context_fails_closed_without_generated_grounding() -> None:
+    with patch("routes.rag_routes.retrieve_lesson_pdf_context", return_value=([], "general")), \
+         patch("routes.rag_routes._generate_text") as generate_text:
+        response = client.post("/api/rag/lesson", json=PAYLOAD)
+
+    assert response.status_code == 404
+    assert response.json()["detail"] == {
+        "error": "no_curriculum_context",
+        "message": "No curriculum content found for lesson 'Introduction to Rational Functions' (General Mathematics Q1). Please ensure the PDF has been ingested.",
+        "retrievalBand": "low",
+        "sources": [],
+    }
+    generate_text.assert_not_called()

tests/test_rag_pipeline.py

@@ -44,6 +44,68 @@ class TestRetrieveCurriculumContext:
             )
             assert result == []
 
+    def test_empty_exact_retrieval_runs_subject_quarter_and_general_fallbacks(self):
+        from rag import curriculum_rag
+
+        grounded_chunk = {
+            "content": "A linear equation has equal expressions on both sides.",
+            "source_file": "SHS_GM_Q1.pdf",
+            "score": 0.9,
+            "page": 2,
+        }
+        with patch.object(
+            curriculum_rag,
+            "retrieve_curriculum_context",
+            side_effect=[[], [], [], [], [], [grounded_chunk]],
+        ) as retrieve:
+            result, mode = curriculum_rag.retrieve_lesson_pdf_context(
+                topic="M11GM-Ia-1",
+                subject="General Mathematics",
+                quarter=3,
+                lesson_title="Linear Equations",
+                storage_path="curriculum/SHS_GM_Q1.pdf",
+            )
+
+        assert result == [grounded_chunk]
+        assert mode == "general"
+        assert [call.kwargs for call in retrieve.call_args_list] == [
+            {
+                "query": "Linear Equations",
+                "subject": "General Mathematics",
+                "quarter": 3,
+                "storage_path": "curriculum/SHS_GM_Q1.pdf",
+                "top_k": 8,
+            },
+            {
+                "query": "Linear Equations",
+                "subject": "General Mathematics",
+                "storage_path": "curriculum/SHS_GM_Q1.pdf",
+                "top_k": 8,
+            },
+            {
+                "query": "Linear Equations",
+                "storage_path": "curriculum/SHS_GM_Q1.pdf",
+                "top_k": 8,
+            },
+            {
+                "query": "Linear Equations",
+                "subject": "General Mathematics",
+                "quarter": 3,
+                "top_k": 8,
+            },
+            {
+                "query": "Linear Equations",
+                "subject": "General Mathematics",
+                "quarter": 1,
+                "top_k": 8,
+            },
+            {
+                "query": "Linear Equations",
+                "subject": "General Mathematics",
+                "top_k": 8,
+            },
+        ]
+
 
 class TestDistanceToScore:
     def test_zero_distance_returns_one(self):
@@ -198,4 +260,4 @@ class TestSubjectNormalizationAndWhere:
     def test_vectorstore_dimension_alignment(self):
         from rag.vectorstore_loader import _get_collection_dimension, _resolve_vectorstore_dir
         dim = _get_collection_dimension(_resolve_vectorstore_dir())
-        assert dim in (384, None)
+        assert dim in (384, None)