fix(security): gate the write side on entitlements, not on self-issuable rows (#543)

[guillermoscript]

What

Closes #543 (EPIC #540 §1.3).

Adds a course-access predicate to four write-side policies that pinned who a row belonged to but never whether the writer had earned it, replaces the last enrollments join in the checkpoint feature, and gates /api/certificates/issue on entitlements.

Migration: 20260726110000_write_side_entitlement_gates.sql (local only — not applied to cloud).

Why

20260725160000 (#532) stamped the rule on enrollments: "Never gate content, APIs or RLS on the presence of an enrollment row." The generalisation — never let a client assert its own grade, completion, mastery or tenant — was never applied elsewhere.

Table	Was	Now
lesson_completions	INSERT WITH CHECK (auth.uid() = user_id) — any authenticated user could record a completion for any lesson_id	routed through lessons to has_course_access
exam_submissions	identity + tenant, no access gate — a student with no entitlement could enqueue AI grading on the school's plan budget	has_course_access on the exam's course
lesson_checkpoint_attempts	identity + checkpoint consistency + access, but score/passed/completed/evaluator_type/attempt_number unconstrained	server-write-only (the #538 pattern)
practice_attempts	FOR ALL USING (user_id = auth.uid()) — no tenant predicate at all	split SELECT/INSERT, active tenant_users row required, score/count CHECKs, source pinned, append-only

practice_attempts.course_id is deliberately not gated (see the second commit). It is an optional, model-supplied label on the MCP tool, not a server-derived value, so an access predicate on it would turn a mislabelled drill into a hard 42501 — and the cross-tenant attack is already closed by the membership check; course_id only scopes item_ratings within the caller's own tenant.

Two of these were more than theoretical:

• The certificate was mintable. /api/certificates/issue checks auth, tenant and duplicates but never checked access; eligibility falls through to a raw lesson_completions count. Self-issuable completions ⇒ self-issuable credential.
• practice_attempts crossed tenants. Two SECURITY DEFINER triggers fire on that fully caller-controlled row: handle_practice_attempt_elo writes the tenant-shared item_ratings anchors, and handle_practice_attempt_xp creates a gamification_profiles row for the named tenant — the exact eligibility source rollover_leagues scans, so a non-member surfaced in another school's league standings. 20260716120000's stated rationale ("a student session cannot write shared rating rows from application code") did not hold.

Bonus, same class: the lesson_checkpoints SELECT policy still authorized by joining enrollments. Refunds revoke entitlements and never enrollments, so a refunded student kept reading every enabled checkpoint on the course.

Shape

The three added predicates mirror the #509 content read policies: tenant match AND (staff OR course author OR has_course_access). Teachers hold no entitlement for courses they author, so the staff/author branches are what keep authoring and preview working; students only ever match the access branch. Preview lessons (#426) are deliberately not a branch on lesson_completions — reading a preview is fine, recording progress against an unbought course is the thing being stopped.

lesson_checkpoint_attempts could not be fixed with a predicate: every column but the identity ones is a grading output. The route already held an admin client and its own resolveCourseAccessState gate (#535), so the insert moved there and the authenticated INSERT/UPDATE/DELETE grants were revoked.

How to QA

On a fresh npm run db:reset, with npm run dev running:

npx playwright test tests/playwright/write-side-rls.spec.ts \
                    tests/playwright/checkpoint-access.spec.ts --workers=1

15 tests, one per acceptance criterion: a completion for an unreachable lesson, an exam submission without entitlement, a direct {passed: true, score: 100} checkpoint attempt, a practice_attempts row naming a foreign tenant, a wrong-answer attempt read back from the DB to prove the stored grade is the server's, /api/certificates/issue refused with completions present, and a refunded student reading zero checkpoints. Each negative has a positive control so a refusal can't pass for the wrong reason.

Manual, as student@e2etest.com on lvh.me:3000: complete a lesson, submit an exam, pass a checkpoint — unchanged. As owner@e2etest.com: teacher grading and authoring unchanged.

Test results

Gate	Result
npm run typecheck	pass
npm run test:unit	370/370 (baseline)
npm run build	pass
npx eslint on changed files	clean (also cleared 5 pre-existing anys in the certificates route that pre-commit lints whole-file)
#543 specs	15/15
student journey + student-courses/exams/features, certificate-issuance, enrollment-flows, evaluations-security	52 passed, 4 failed (pre-existing)
tenant-isolation	10/10
teacher-content	13/13
teacher-courses	13/13
admin-crud	14 passed, 3 failed (pre-existing)

Every failure above is pre-existing. The 3 admin-crud product-wizard failures (product-creation-wizard testid never renders) reproduce identically on 146a8cfa. The 4 student-side failures are — full-student-journey and certificate-issuance plus two student-features sidebar tests. Verified by re-running them on 146a8cfa with a fresh DB: identical failures. full-student-journey targets course 9999 / lessons 10000-10001, which supabase/seed.sql does not create.

One thing worth knowing for future E2E work: student-exams.spec.ts:58 deletes Alice's entitlements row for course 2001 in its cleanup and never restores it. That leak was harmless while nothing gated on entitlements; now it makes later specs in the same run fail. Not fixed here (out of scope), but it is why a long mixed run shows failures a per-spec run does not.

Screenshots / GIF

None — no user-visible surface changed. The one new user-facing string is the existing accessDenied / accessSuspended 403 shape from #535, reused verbatim by /api/certificates/issue.

Checklist

• npm run typecheck and npm run test:unit pass
• npm run build passes
• Every new tenant-scoped query filters by tenant_id (or the table genuinely has no such column — lesson_completions has none, so the course is reached through lessons)
• Tested with every relevant role (student / teacher / admin)
• Loading and error states handled
• New UI strings added to both messages/en.json and messages/es.json — n/a, no new strings
• Migration applies cleanly on npm run db:reset; lib/database.types.ts needs no regeneration (policies and constraints only, no schema shape change)

🤖 Generated with Claude Code

https://claude.ai/code/session_011SbrtmdXw6ZwH2UeTCuT2v