fix(security): gate checkpoint attempts on entitlements, not enrollments (#532)

The lesson-checkpoint attempt route reads through the service-role client, so
the RLS backstop added in #509 never applied to it, and the only gate it had
was an active `enrollments` row. That row has not meant "has access" since
migration 20260516150000: nothing revokes it (refunds revoke entitlements,
and tenants.access_cutoff_at is read only inside has_course_access), and its
RLS INSERT policy let any tenant member issue one for any course in their
tenant. Three populations could therefore spend the school's AI grading
budget and write progress records for content they had no right to: students
past their tenant's access cutoff (#494), students whose entitlement was
revoked by a refund (#498/#515), and anyone who self-inserted an enrollment.

- Route now calls resolveCourseAccessState() and returns a 403 that tells a
  tenant suspension apart from a missing entitlement, so the checkpoint UI can
  explain which one it is (new translated copy, en + es).
- Same check added to the two sibling admin-client media routes (analyze,
  signed-url), which were ownership-checked only. Not live holes — both sit
  behind the gated upload path — but both spend AI credits or mint storage
  URLs, and an entitlement can be revoked after the upload was authorized.
- Migration 20260725160000 stops enrollments being an access grant at the
  database level: its INSERT policy and the checkpoint-attempt INSERT policy
  now both require has_course_access(). Every legitimate writer (enroll_user,
  self_enroll_subscription_course, grant_free_entitlement,
  issue_certificate_if_eligible) is SECURITY DEFINER, so none are affected.
- docs/MONETIZATION.md now describes the API-route layer accurately instead of
  claiming page gates cover it, and both docs state that an enrollment row is
  not an access grant.

New E2E spec pins the three states (entitled 200, revoked 403 accessDenied,
cutoff 403 accessSuspended); its two refusal cases fail against the old code.

The four pre-existing `no-explicit-any` errors in the media analyze route are
fixed rather than bypassed, since lint-staged lints the whole file.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019QSWA8GwmjsYHUS7ov5NG3

Author: guillermoscript

app/api/exercises/media/analyze/route.ts

@@ -1,5 +1,6 @@
 import { createAdminClient } from '@/lib/supabase/admin'
 import { getApiAuthContext } from '@/lib/supabase/api-auth'
+import { hasCourseAccess } from '@/lib/services/course-access'
 import { runSpeechPipeline } from '@/lib/speech/pipeline'
 import { getPipeline } from '@/lib/speech/registry'
 import type { ExerciseContext } from '@/lib/speech/types'
@@ -8,6 +9,22 @@ export const maxDuration = 120
 
 const STORAGE_BUCKET = 'exercise-media'
 
+/** The `exercises(...)` join on the submission row. */
+type JoinedExercise = {
+  id: number
+  title: string | null
+  instructions: string | null
+  course_id: number
+  tenant_id: string
+  exercise_config: {
+    passing_score?: number
+    topic_prompt?: string
+    rubric?: ExerciseContext['rubric']
+    stt_provider?: string
+    ai_coach?: string
+  } | null
+}
+
 export async function POST(req: Request) {
   // 1. Auth — cookie session (web) or Bearer token (mobile), server-verified
   const auth = await getApiAuthContext(req)
@@ -44,8 +61,10 @@ export async function POST(req: Request) {
     return new Response('Submission not found', { status: 404 })
   }
 
+  const exercise = submission.exercises as unknown as JoinedExercise | null
+
   // 5. Status guard — only pending submissions can be analyzed (prevents re-triggering)
-  const passingScore = ((submission.exercises as any)?.exercise_config as any)?.passing_score ?? 70
+  const passingScore = exercise?.exercise_config?.passing_score ?? 70
   if (submission.status === 'completed') {
     return Response.json({ already_completed: true, evaluation: submission.ai_evaluation, passed: true, passingScore })
   }
@@ -57,11 +76,18 @@ export async function POST(req: Request) {
   }
 
   // 6. Verify exercise tenant matches (defense in depth)
-  const exercise = submission.exercises as any
   if (!exercise || exercise.tenant_id !== tenantId) {
     return new Response('Exercise not found', { status: 404 })
   }
 
+  // 6b. Course access (issue #532). Ownership of the submission is not access:
+  // this route runs on the admin client and spends AI credits, and an
+  // entitlement can be revoked — or the tenant's access cutoff can pass —
+  // between the gated upload and this call.
+  if (!(await hasCourseAccess(adminClient, user.id, exercise.course_id))) {
+    return new Response('You do not have access to this course', { status: 403 })
+  }
+
   // 7. Atomically set processing (prevents concurrent analysis of same submission)
   const { data: updated, error: updateError } = await adminClient
     .from('exercise_media_submissions')
@@ -149,14 +175,15 @@ export async function POST(req: Request) {
     }
 
     return Response.json({ evaluation, passed, passingScore })
-  } catch (err: any) {
+  } catch (err) {
     console.error('Speech pipeline error:', err)
 
     await adminClient
       .from('exercise_media_submissions')
       .update({ status: 'failed' })
       .eq('id', submissionId)
 
-    return new Response(err.message ?? 'Analysis failed', { status: 500 })
+    const message = err instanceof Error ? err.message : 'Analysis failed'
+    return new Response(message, { status: 500 })
   }
 }

app/api/exercises/media/signed-url/route.ts

@@ -1,5 +1,6 @@
 import { createAdminClient } from '@/lib/supabase/admin'
 import { getApiAuthContext } from '@/lib/supabase/api-auth'
+import { hasCourseAccess } from '@/lib/services/course-access'
 
 const STORAGE_BUCKET = 'exercise-media'
 
@@ -21,7 +22,7 @@ export async function POST(req: Request) {
 
   const { data: submission, error } = await adminClient
     .from('exercise_media_submissions')
-    .select('media_url, user_id, tenant_id')
+    .select('media_url, user_id, tenant_id, exercises(course_id, tenant_id)')
     .eq('id', submissionId)
     .single()
 
@@ -33,6 +34,21 @@ export async function POST(req: Request) {
     return new Response('Submission not found', { status: 404 })
   }
 
+  // Course access (issue #532). Owning the recording is not the same as being
+  // entitled to the course it belongs to: this handler mints a storage URL off
+  // the admin client, and entitlements can be revoked (or the tenant's access
+  // cutoff can pass) after the submission was created.
+  const exercise = submission.exercises as unknown as {
+    course_id: number
+    tenant_id: string
+  } | null
+  if (!exercise || exercise.tenant_id !== tenantId) {
+    return new Response('Submission not found', { status: 404 })
+  }
+  if (!(await hasCourseAccess(adminClient, user.id, exercise.course_id))) {
+    return new Response('You do not have access to this course', { status: 403 })
+  }
+
   const { data: urlData } = await adminClient
     .storage
     .from(STORAGE_BUCKET)

app/api/lesson-checkpoints/[checkpointId]/attempt/route.ts

@@ -2,6 +2,7 @@ import { z } from 'zod'
 import { generateObject } from 'ai'
 import { getApiAuthContext } from '@/lib/supabase/api-auth'
 import { createAdminClient } from '@/lib/supabase/admin'
+import { resolveCourseAccessState } from '@/lib/services/course-access'
 import { AI_MODELS } from '@/lib/ai/config'
 import { gradeCheckpointQuestions } from '@/lib/checkpoints/grading'
 import {
@@ -92,18 +93,28 @@ export async function POST(
     return Response.json({ error: 'Checkpoint not found' }, { status: 404 })
   }
 
-  // Active enrollment required — mirrors the RLS insert policy so failures
-  // surface as a clear 403 instead of an opaque insert error.
-  const { data: enrollment } = await adminClient
-    .from('enrollments')
-    .select('enrollment_id')
-    .eq('user_id', user.id)
-    .eq('course_id', exercise.course_id)
-    .eq('status', 'active')
-    .limit(1)
-    .maybeSingle()
-  if (!enrollment) {
-    return Response.json({ error: 'Not enrolled in this course' }, { status: 403 })
+  // Course access required (issue #532). This route reads through the admin
+  // client, so #509's RLS backstop on content never applies here — the gate
+  // has to be explicit. It must be `entitlements`, not `enrollments`: an
+  // enrollment row is a progress record that nothing revokes and that a
+  // tenant member can issue for themselves, so it grants no access on its own.
+  const accessState = await resolveCourseAccessState(
+    adminClient,
+    user.id,
+    exercise.course_id
+  )
+  if (accessState !== 'granted') {
+    return Response.json(
+      {
+        error:
+          accessState === 'suspended'
+            ? "Your school's access is currently suspended"
+            : 'You do not have access to this course',
+        accessDenied: true,
+        accessSuspended: accessState === 'suspended',
+      },
+      { status: 403 }
+    )
   }
 
   const config = exercise.exercise_config ?? {}

components/lesson/checkpoints/checkpoint-exercise-renderer.tsx

@@ -21,9 +21,28 @@ interface CheckpointExerciseRendererProps {
   checkpoint: LessonCheckpointClientData
 }
 
-type AttemptResponse =
-  | { ok: true; data: CheckpointAttemptResult }
-  | { ok: false; status: number; notCompleted?: boolean; error?: string }
+type AttemptFailure = {
+  ok: false
+  status: number
+  notCompleted?: boolean
+  accessDenied?: boolean
+  accessSuspended?: boolean
+  error?: string
+}
+
+type AttemptResponse = { ok: true; data: CheckpointAttemptResult } | AttemptFailure
+
+/**
+ * The route's access refusals (issue #532) carry flags rather than only a
+ * message, so the student reads translated copy instead of the server's raw
+ * English — and a school-wide suspension reads differently from "you never
+ * bought this course", which is the distinction #494 exists to make.
+ */
+function attemptErrorKey(res: AttemptFailure): 'accessSuspended' | 'accessDenied' | null {
+  if (res.accessSuspended) return 'accessSuspended'
+  if (res.accessDenied) return 'accessDenied'
+  return null
+}
 
 async function postAttempt(checkpointId: number, body: unknown): Promise<AttemptResponse> {
   try {
@@ -38,6 +57,8 @@ async function postAttempt(checkpointId: number, body: unknown): Promise<Attempt
         ok: false,
         status: res.status,
         notCompleted: payload?.notCompleted === true,
+        accessDenied: payload?.accessDenied === true,
+        accessSuspended: payload?.accessSuspended === true,
         error: typeof payload?.error === 'string' ? payload.error : undefined,
       }
     }
@@ -120,7 +141,8 @@ function ClosedCheckpointForm({ checkpoint }: CheckpointExerciseRendererProps) {
     const res = await postAttempt(checkpoint.id, { kind: 'answers', answers: payload })
     setSubmitting(false)
     if (!res.ok) {
-      setError(res.error ?? t('genericError'))
+      const errorKey = attemptErrorKey(res)
+      setError(errorKey ? t(errorKey) : (res.error ?? t('genericError')))
       return
     }
     setResult(res.data)
@@ -257,7 +279,8 @@ function TextCheckpointForm({ checkpoint }: CheckpointExerciseRendererProps) {
     const res = await postAttempt(checkpoint.id, { kind: 'text', text })
     setSubmitting(false)
     if (!res.ok) {
-      setError(res.error ?? t('genericError'))
+      const errorKey = attemptErrorKey(res)
+      setError(errorKey ? t(errorKey) : (res.error ?? t('genericError')))
       return
     }
     setResult(res.data)
@@ -346,7 +369,8 @@ function ExternalCheckpointForm({ checkpoint }: CheckpointExerciseRendererProps)
         setNotCompleted(true)
         return
       }
-      setError(res.error ?? t('genericError'))
+      const errorKey = attemptErrorKey(res)
+      setError(errorKey ? t(errorKey) : (res.error ?? t('genericError')))
       return
     }
     setResult(res.data)

docs/DATABASE_SCHEMA.md

@@ -456,6 +456,8 @@ Written by `enroll_user()` and `handle_new_subscription()`. Read via `has_course
 
 > The old `product_id` / `subscription_id` columns and their "one or the other" CHECK constraint were **dropped** in the entitlements migration. If you find code or docs referencing them, they are out of date. Students on a subscription self-enroll from `/dashboard/student/browse` (`useEnrollment()` hook); subscriptions grant access but do not auto-enroll.
 
+> **Never gate on the presence of an enrollment row** (issue #532). Nothing revokes one — refunds revoke *entitlements* and `tenants.access_cutoff_at` is read only inside `has_course_access()` — so a row survives every revocation path, and until migration `20260725160000` any tenant member could insert one for any course in their tenant. The INSERT policy now also requires `has_course_access()`; legitimate writers (`enroll_user()`, `self_enroll_subscription_course()`, `grant_free_entitlement()`, `issue_certificate_if_eligible()`) are all `SECURITY DEFINER` and unaffected.
+
 #### `products`
 Purchasable course bundles. Tenant-scoped.
 

docs/MONETIZATION.md

@@ -243,7 +243,9 @@ The two sections above are **creation-time soft caps only** — they block a *ne
 - Enforcement itself is in the database: once `access_cutoff_at` passes while the tenant is still over its plan's limits, `has_course_access()` (SQL function, migration `supabase/migrations/20260724130000_access_cutoff_enforcement.sql`) starts returning `false` for every student in that tenant. Access is restored automatically as soon as usage is back under the limit or the tenant upgrades.
 - That function is enforced in two layers (issue #509 — before it, the cutoff was a no-op on exactly the pages that serve content):
   - **RLS** (`supabase/migrations/20260724150000_content_entitlement_rls.sql`): the `authenticated` SELECT policies on `lessons`, `exercises`, `exams` and `lesson_resources` all require `has_course_access()`, with escape hatches for the course's author and for active teachers/admins of the tenant (`is_tenant_staff()`). Published preview lessons (`is_preview`) stay readable to everyone. This is the backstop — it holds even where a page uses the service-role client.
-  - **Page/route gates**: `requireCourseAccess()` (`lib/services/course-access-guard.ts`) on every student course route — course detail, lessons, exercises (list + detail), exams (list, taker, result, review), community — plus `hasCourseAccess()` in the certificate, AI tutor and exercise-submission APIs. A refusal caused by the tenant cutoff (rather than by a missing entitlement) sends the student to `/dashboard/student/access-suspended`, which explains that the school is over its limits and that their enrollment is intact.
+  - **Page gates**: `requireCourseAccess()` (`lib/services/course-access-guard.ts`) on every student course route — course detail, lessons, exercises (list + detail), exams (list, taker, result, review), community. A refusal caused by the tenant cutoff (rather than by a missing entitlement) sends the student to `/dashboard/student/access-suspended`, which explains that the school is over its limits and that their enrollment is intact.
+  - **API-route gates**: an API route that reads through `createAdminClient()` is outside the RLS backstop by construction, so it has to carry the check itself. The routes that serve or produce paid content all call `hasCourseAccess()` / `resolveCourseAccessState()` (`lib/services/course-access.ts` — the API-safe module; `course-access-guard.ts` imports `next/navigation` and is for pages only): `api/certificates/generate`, `api/chat/aristotle`, `api/exercises/artifact/evaluate`, `api/exercises/media/upload-url`, `api/exercises/media/analyze`, `api/exercises/media/signed-url`, and `api/lesson-checkpoints/[checkpointId]/attempt`. The checkpoint route returns a 403 that distinguishes a suspension from a missing entitlement, so the checkpoint UI can say which one it is.
+- **An `enrollments` row is not an access grant** (issue #532). Since migration `20260516150000` it is a learning-progress record: nothing revokes it (refunds revoke *entitlements*, and `access_cutoff_at` is read only inside `has_course_access()`), and its RLS INSERT policy now requires `has_course_access()` precisely because it used to be self-issuable by any tenant member. Gate on entitlements — never on an enrollment row.
 - This is a deliberate decision, not an oversight: with no production users yet, real enforcement was shipped directly rather than grandfathering pre-existing over-limit usage.
 
 #### Blast radius — the cutoff is tenant-wide and all-or-nothing (issue #517)

messages/en.json

@@ -3890,6 +3890,8 @@
       "retry": "Try again",
       "review": "Edit and resubmit",
       "genericError": "Something went wrong. Please try again.",
+      "accessDenied": "You don't have access to this course.",
+      "accessSuspended": "Your school's access is currently suspended. Your progress is safe — ask your school administrator to restore access.",
       "aiUnavailable": "Your answer was recorded, but AI feedback is unavailable right now.",
       "externalPrompt": "This checkpoint is completed through its exercise page. Open the exercise, finish it there, then sync your result here.",
       "externalLinkLabel": "Open exercise",

messages/es.json

@@ -3735,6 +3735,8 @@
       "retry": "Intentar de nuevo",
       "review": "Editar y reenviar",
       "genericError": "Algo salió mal. Inténtalo de nuevo.",
+      "accessDenied": "No tienes acceso a este curso.",
+      "accessSuspended": "El acceso de tu escuela está suspendido en este momento. Tu progreso está a salvo: pide a la administración de tu escuela que lo restablezca.",
       "aiUnavailable": "Tu respuesta fue registrada, pero la retroalimentación con IA no está disponible en este momento.",
       "externalPrompt": "Este checkpoint se completa en su página de ejercicio. Abre el ejercicio, termínalo allí y luego sincroniza tu resultado aquí.",
       "externalLinkLabel": "Abrir ejercicio",

supabase/migrations/20260725160000_entitlement_gated_enrollment_inserts.sql

@@ -0,0 +1,64 @@
+-- Issue #532 — an `enrollments` row is not an access grant.
+--
+-- Since migration 20260516150000, `enrollments` is a learning-progress record
+-- and `entitlements` is the source of truth for course access. The INSERT
+-- policy below never caught up: its WITH CHECK was
+--
+--   (auth.uid() = user_id) AND (tenant_id = get_tenant_id())
+--
+-- so any tenant member could POST /rest/v1/enrollments for any course in
+-- their tenant and manufacture a row that *looks* like proof of access.
+-- Nothing revokes an enrollment either — refunds revoke entitlements
+-- (lib/payments/webhook-dispatch.ts) and `tenants.access_cutoff_at` (#494) is
+-- read only inside has_course_access() — so the row also survives every
+-- revocation path. Code that reads it as an access check (the lesson-checkpoint
+-- attempt API route, and the checkpoint-attempt INSERT policy below) was
+-- therefore gate-less in three cases: past the tenant access cutoff, after a
+-- refund, and for a self-inserted row.
+--
+-- Both policies now gate on has_course_access(), the same function the page
+-- guards and the content RLS from #509 use.
+--
+-- Safe for every legitimate writer: enroll_user(), self_enroll_subscription_course(),
+-- grant_free_entitlement() and issue_certificate_if_eligible() are all
+-- SECURITY DEFINER (RLS does not apply to them), and admin/seed paths use the
+-- service-role client. No client-side `enrollments` INSERT exists in the app.
+-- The policy is tightened rather than dropped so any caller that genuinely
+-- holds access keeps working.
+
+DROP POLICY IF EXISTS "Users can create own enrollments" ON public.enrollments;
+
+CREATE POLICY "Users can create own enrollments"
+  ON public.enrollments FOR INSERT TO authenticated
+  WITH CHECK (
+    (SELECT auth.uid()) = user_id
+    AND tenant_id = (SELECT get_tenant_id())
+    AND public.has_course_access((SELECT auth.uid()), course_id)
+  );
+
+-- The checkpoint-attempt insert policy leaned on the same self-issuable row.
+-- Everything else about it is unchanged: same user, same enabled checkpoint,
+-- same (checkpoint, lesson, exercise, tenant) consistency requirement.
+DROP POLICY IF EXISTS lesson_checkpoint_attempts_students_insert_own_rows
+  ON public.lesson_checkpoint_attempts;
+
+CREATE POLICY lesson_checkpoint_attempts_students_insert_own_rows
+  ON public.lesson_checkpoint_attempts FOR INSERT TO authenticated
+  WITH CHECK (
+    user_id = (SELECT auth.uid())
+    AND EXISTS (
+      SELECT 1
+      FROM lesson_checkpoints c
+      WHERE c.id = lesson_checkpoint_attempts.checkpoint_id
+        AND c.tenant_id = lesson_checkpoint_attempts.tenant_id
+        AND c.lesson_id = lesson_checkpoint_attempts.lesson_id
+        AND c.exercise_id = lesson_checkpoint_attempts.exercise_id
+        AND c.is_enabled
+    )
+    AND public.has_course_access((SELECT auth.uid()), lesson_checkpoint_attempts.course_id)
+  );
+
+COMMENT ON TABLE public.enrollments IS
+  'Learning-progress record only (since 20260516150000). NOT an access grant: '
+  'course access lives in `entitlements` and is checked with has_course_access(). '
+  'Never gate content, APIs or RLS on the presence of an enrollment row.';