feat(enrollment): entitlements model for course access

Introduces the entitlements model to fix a structural flaw in the billing/enrollment
architecture: the old `enrollments` table doubled as both an access-grant and a
billing-attribution record, causing plan purchases over product-owned courses to
500 (valid_enrollment CHECK violation) and subscription lapses to silently revoke
perpetually-owned courses.

Key changes:
- New `entitlements` table (one row per access source: product/subscription/free/admin_grant)
- `has_course_access()` SECURITY DEFINER RPC as single access-gate truth
- Drop enrollments.product_id / subscription_id (Phase 3)
- Renewal-aware handle_new_subscription (extends expires_at correctly)
- Revenue splits honour applies_to_providers (platform fee only on Stripe sales)
- Stripe webhook charge.refunded: fix status missing from select + remove non-existent refunded_amount column

All flows browser-verified: sub lapse, perpetual product survival, Stripe refund,
free enrollment, renewal, exam/community gates. Two regression specs added.

Author: guillermoscript

app/[locale]/(public)/checkout/actions.ts

@@ -2,45 +2,53 @@
 
 import { createClient as createServerClient } from '@/lib/supabase/server';
 import { revalidatePath } from 'next/cache';
-import { getCurrentUserId } from '@/lib/supabase/tenant'
+import { getCurrentUserId, getCurrentTenantId } from '@/lib/supabase/tenant'
 
 /**
- * Mock enrollment for testing checkout flow
- * In production, this should be called by Stripe webhook after successful payment
- * 
- * This action:
- * 1. Creates a transaction record
- * 2. Calls enroll_user RPC (for products) or handle_new_subscription (for plans)
- * 3. Enrolls user in associated courses
+ * Mock checkout — creates a successful transaction.
+ *
+ * Enrollment is handled by the `after_transaction_insert` DB trigger
+ * (`trigger_manage_transactions`), which calls `enroll_user` /
+ * `handle_new_subscription` — the same single path the Stripe webhook uses.
+ * In production this action is replaced by the Stripe webhook.
  */
 export async function enrollUser(courseId?: string, planId?: string, paymentMethod: string = 'mock_test') {
-    // 1. Authenticate user
+    // 1. Authenticate user + resolve tenant
     const supabase = await createServerClient();
     const userId = await getCurrentUserId()
     if (!userId) {
         throw new Error("You must be logged in to enroll.");
     }
+    const tenantId = await getCurrentTenantId();
 
     try {
         if (courseId) {
-            // Get product for this course (pick first match)
+            // Get product for this course (pick first match, scoped to tenant)
             const { data: productCourses } = await supabase
                 .from('product_courses')
                 .select('product_id, product:products(*)')
                 .eq('course_id', parseInt(courseId))
+                .eq('tenant_id', tenantId)
                 .limit(1);
 
             if (!productCourses || productCourses.length === 0) {
                 throw new Error("No product found for this course.");
             }
 
-            const product = productCourses[0].product as any;
+            const product = productCourses[0].product as unknown as {
+                product_id: number;
+                price: number | string;
+                currency: string;
+            };
 
-            // Create transaction record (mock payment)
+            // Create the transaction. The after_transaction_insert trigger
+            // enrolls the user (entitlements + enrollment record) — no explicit
+            // RPC call here, the trigger is the single enrollment path.
             const { data: transaction, error: txError } = await supabase
                 .from('transactions')
                 .insert({
                     user_id: userId,
+                    tenant_id: tenantId,
                     product_id: product.product_id,
                     amount: product.price,
                     currency: product.currency,
@@ -55,38 +63,30 @@ export async function enrollUser(courseId?: string, planId?: string, paymentMeth
                 throw new Error("Failed to create transaction: " + txError.message);
             }
 
-            // Call enroll_user RPC function
-            // This function checks for transaction and enrolls in linked courses
-            const { error: enrollError } = await supabase.rpc('enroll_user', {
-                _user_id: userId,
-                _product_id: product.product_id
-            });
-
-            if (enrollError) {
-                console.error("Enrollment error:", enrollError);
-                throw new Error("Failed to enroll: " + enrollError.message);
-            }
-
             revalidatePath('/dashboard/student');
             return { success: true, transaction_id: transaction.transaction_id };
 
         } else if (planId) {
-            // Get plan details
+            // Get plan details (scoped to tenant)
             const { data: plan, error: planError } = await supabase
                 .from('plans')
                 .select('*')
                 .eq('plan_id', parseInt(planId))
+                .eq('tenant_id', tenantId)
                 .single();
 
             if (planError || !plan) {
                 throw new Error("Plan not found.");
             }
 
-            // Create transaction for plan
+            // Create the transaction. The after_transaction_insert trigger
+            // creates the subscription + entitlements (or extends an existing
+            // subscription on renewal).
             const { data: transaction, error: txError } = await supabase
                 .from('transactions')
                 .insert({
                     user_id: userId,
+                    tenant_id: tenantId,
                     plan_id: plan.plan_id,
                     amount: plan.price,
                     currency: plan.currency,
@@ -101,18 +101,6 @@ export async function enrollUser(courseId?: string, planId?: string, paymentMeth
                 throw new Error("Failed to create transaction: " + txError.message);
             }
 
-            // Call handle_new_subscription RPC function
-            const { error: subError } = await supabase.rpc('handle_new_subscription', {
-                _user_id: userId,
-                _plan_id: plan.plan_id,
-                _transaction_id: transaction.transaction_id
-            });
-
-            if (subError) {
-                console.error("Subscription error:", subError);
-                throw new Error("Failed to create subscription: " + subError.message);
-            }
-
             revalidatePath('/dashboard/student');
             return { success: true, transaction_id: transaction.transaction_id };
         }
@@ -126,85 +114,72 @@ export async function enrollUser(courseId?: string, planId?: string, paymentMeth
 }
 
 /**
- * Enroll user in a free course or plan
+ * Enroll the current user in a free course.
+ *
+ * Grants a `free` entitlement via the grant_free_entitlement RPC
+ * (SECURITY DEFINER, idempotent). No product/transaction is fabricated.
+ * See docs/ENTITLEMENTS_MIGRATION_PLAN.md.
  */
-export async function enrollFree(courseId?: string, planId?: string) {
+export async function enrollFree(courseId?: string) {
     const supabase = await createServerClient();
     const userId = await getCurrentUserId()
     if (!userId) {
         throw new Error("You must be logged in to enroll.");
     }
+    const tenantId = await getCurrentTenantId();
 
     try {
-        if (courseId) {
-            // Check if the course is actually free
-            const { data: productCourses } = await supabase
-                .from('product_courses')
-                .select('product:products(product_id, price)')
-                .eq('course_id', parseInt(courseId))
-                .limit(1);
+        if (!courseId) {
+            throw new Error("Free enrollment only supported for courses currently.");
+        }
 
-            const courseProduct = productCourses?.[0]?.product as any;
-            const isFree = courseProduct ? parseFloat(courseProduct.price) === 0 : true;
+        const numericCourseId = parseInt(courseId);
 
-            if (!isFree) {
-                throw new Error("This course is not free. Please use the paid enrollment flow.");
-            }
+        // 1. Validate the course: it must belong to this tenant and be published.
+        // Prevents enrolling in another tenant's course or an unpublished draft
+        // via a crafted checkout URL.
+        const { data: course, error: courseError } = await supabase
+            .from('courses')
+            .select('course_id, status, tenant_id')
+            .eq('course_id', numericCourseId)
+            .eq('tenant_id', tenantId)
+            .single();
 
-            // For free courses, we need a product_id to satisfy the constraint
-            let productId: number;
-
-            if (courseProduct?.product_id) {
-                productId = courseProduct.product_id;
-            } else {
-                // Create a free product if one doesn't exist
-                const { data: freeProduct, error: createError } = await supabase
-                    .from('products')
-                    .insert({
-                        name: `Free Access - ${courseId}`,
-                        price: 0,
-                        currency: 'usd',
-                        status: 'active',
-                        payment_provider: 'stripe'
-                    })
-                    .select('product_id')
-                    .single();
-
-                if (createError) throw createError;
-
-                // Link product to course
-                await supabase
-                    .from('product_courses')
-                    .insert({
-                        product_id: freeProduct.product_id,
-                        course_id: parseInt(courseId)
-                    });
-
-                productId = freeProduct.product_id;
-            }
+        if (courseError || !course) {
+            throw new Error("Course not found.");
+        }
+        if (course.status !== 'published') {
+            throw new Error("This course is not available for enrollment.");
+        }
 
-            // Create enrollment with product_id
-            const { error } = await supabase
-                .from('enrollments')
-                .insert({
-                    user_id: userId,
-                    course_id: parseInt(courseId),
-                    product_id: productId,
-                    status: 'active',
-                    enrollment_date: new Date().toISOString()
-                });
-
-            if (error) {
-                // If already enrolled, that's fine
-                if (error.code === '23505') return { success: true, alreadyEnrolled: true };
-                throw error;
-            }
+        // 2. Guard: reject if a paid product is linked to this course.
+        const { data: productCourses } = await supabase
+            .from('product_courses')
+            .select('product:products(price)')
+            .eq('course_id', numericCourseId)
+            .eq('tenant_id', tenantId)
+            .limit(1);
 
-            revalidatePath('/dashboard/student');
-            return { success: true };
+        const linkedProduct = productCourses?.[0]?.product as unknown as {
+            price: number | string;
+        } | undefined;
+
+        if (linkedProduct && Number(linkedProduct.price) !== 0) {
+            throw new Error("This course is not free. Please use the paid enrollment flow.");
+        }
+
+        // 3. Grant a free entitlement (entitlements model). Idempotent.
+        const { error: grantError } = await supabase.rpc('grant_free_entitlement', {
+            _user_id: userId,
+            _course_id: numericCourseId,
+        });
+
+        if (grantError) {
+            throw new Error("Failed to enroll: " + grantError.message);
         }
-        
-        throw new Error("Free enrollment only supported for courses currently.");
+
+        revalidatePath('/dashboard/student');
+        return { success: true };
     } catch (error) {
         console.error("Free enrollment failed:", error);
         throw error;

app/[locale]/(public)/courses/[id]/page.tsx

@@ -23,6 +23,7 @@ import {
 import { Card, CardContent } from "@/components/ui/card";
 import { getTranslations } from 'next-intl/server';
 import { getCurrentUserId } from '@/lib/supabase/tenant'
+import { hasCourseAccess } from '@/lib/services/course-access'
 
 export const dynamic = 'force-dynamic';
 
@@ -80,20 +81,10 @@ export default async function CourseDetailsPage(props: { params: Promise<{ id: s
     const estimatedHours = Math.floor(totalLessons * 10 / 60);
     const estimatedMinutes = (totalLessons * 10) % 60;
 
-    // Check user's enrollment
+    // Check user's access (entitlements model)
     let hasAccess = false;
     if (userId) {
-        const { data: enrollment } = await supabase
-            .from('enrollments')
-            .select('enrollment_id')
-            .eq('user_id', userId)
-            .eq('course_id', parseInt(params.id))
-            .eq('status', 'active')
-            .maybeSingle();
-
-        if (enrollment) {
-            hasAccess = true;
-        }
+        hasAccess = await hasCourseAccess(supabase, userId, parseInt(params.id));
     }
 
     // Fetch product for pricing

app/[locale]/dashboard/student/browse/page.tsx

@@ -8,6 +8,7 @@ import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert'
 import Link from 'next/link'
 import { IconAlertCircle, IconSparkles, IconTrophy, IconSearch } from '@tabler/icons-react'
 import {getCurrentTenantId, getCurrentUserId } from '@/lib/supabase/tenant'
+import { fetchAccessibleCourseIds } from '@/lib/services/course-access'
 
 export default async function BrowseCoursesPage({
   searchParams,
@@ -53,7 +54,7 @@ export default async function BrowseCoursesPage({
   }
 
   // Parallelize 4 independent queries
-  const [{ data: subscriptions }, { data: categories }, { data: courses }, { data: enrollments }] = await Promise.all([
+  const [{ data: subscriptions }, { data: categories }, { data: courses }, accessibleCourseIds] = await Promise.all([
     supabase.from('subscriptions').select(`
       subscription_id,
       subscription_status,
@@ -71,8 +72,8 @@ export default async function BrowseCoursesPage({
     supabase.from('course_categories').select('id, name')
       .eq('tenant_id', tenantId).order('name'),
     query,
-    supabase.from('enrollments').select('course_id')
-      .eq('user_id', userId).eq('tenant_id', tenantId).eq('status', 'active'),
+    // "Already enrolled" set — entitlements model (any active access source).
+    fetchAccessibleCourseIds(supabase, userId),
   ])
 
   const activeSubscription = subscriptions?.[0]
@@ -98,7 +99,7 @@ export default async function BrowseCoursesPage({
   const tCourses = await getTranslations('dashboard.student.courses')
   const tSearch = await getTranslations('courseSearch')
 
-  const enrolledCourseIds = new Set(enrollments?.map(e => e.course_id) || [])
+  const enrolledCourseIds = accessibleCourseIds
 
   const hasActiveFilters = sanitizedSearch || category
 

app/[locale]/dashboard/student/courses/[courseId]/community/page.tsx

@@ -1,6 +1,7 @@
 import { createAdminClient } from '@/lib/supabase/admin'
 import {getCurrentTenantId, getCurrentUserId } from '@/lib/supabase/tenant'
 import { getUserRole } from '@/lib/supabase/get-user-role'
+import { hasCourseAccess } from '@/lib/services/course-access'
 import { redirect, notFound } from 'next/navigation'
 import { getTranslations } from 'next-intl/server'
 import { CommunityFeed } from '@/components/community/community-feed'
@@ -27,16 +28,9 @@ export default async function StudentCourseCommunityPage({ params }: PageProps)
 
   const adminClient = createAdminClient()
 
-  // Verify enrollment and fetch course in parallel
-  const [{ data: enrollment }, { data: course }] = await Promise.all([
-    adminClient
-      .from('enrollments')
-      .select('enrollment_id')
-      .eq('user_id', userId)
-      .eq('course_id', numericCourseId)
-      .eq('status', 'active')
-      .eq('tenant_id', tenantId)
-      .single(),
+  // Verify access (entitlements model) and fetch course in parallel
+  const [hasAccess, { data: course }] = await Promise.all([
+    hasCourseAccess(adminClient, userId, numericCourseId),
     adminClient
       .from('courses')
       .select('course_id, title')
@@ -45,7 +39,7 @@ export default async function StudentCourseCommunityPage({ params }: PageProps)
       .single(),
   ])
 
-  if (!enrollment) {
+  if (!hasAccess) {
     redirect('/dashboard/student')
   }