SkillPixel LMS: Gated lesson media on R2

The tenant id comes from gen_random_uuid() and the API already returns it on the user profile. The bucket does not list, and the prefix is not an access control. The presign helper only uses the prefix to build the key it signs, and the enrollment check happens before that.

Pieces

• Private R2 bucket. Public access off. The default is to reuse the existing slide bucket, which is already private and wired as r2_slide_bucket. SP-670 confirms.
• Markers in the DB. Stored URLs become path-only markers: /media/tenants/{tenant_id}/quiz-images/{quiz_nanoid}/{file}.png. Nothing in the DB carries a host or a signature. The /media/ prefix is only a marker the rewrite helper looks for.
• Read-time rewrite. When the backend serves question content, one helper replaces every marker in question HTML, explanation, option values, and resources with a presigned GET URL for the private bucket. Signing is a local HMAC over the key and expiry, no network call, so 20 URLs per quiz cost nothing. The response also carries expires_at.
• Enrollment gate for free. The quiz endpoints already refuse callers who are not enrolled. The presigned URL only exists inside a response that passed that check, so the gate is per course, not per tenant.
• Editor round-trip. The instructor editor receives presigned URLs. On save the backend normalises them back to markers. The DB never stores a signed URL.
• Refresh. The frontend refetches the questions list shortly before expires_at, and once on any image or audio load error. It reuses the timer helper already used for slide pages.
• Uploads. Presigned PUT still goes to R2, only the target bucket changes.

Course covers, tenant branding, banners, blog images, instructor avatars, hall of fame. Landing pages and search engines need them. Nothing moves for these.

SP-670 Setup

1. Reuse the slide bucket or create a media bucket.
2. Pick the 4 h lifetime.
3. Confirm Range on a presigned GET from Safari.
4. Check copy_objects in apps/backend/app/services/storage.py copies across buckets. It uses one bucket for source and target today.
5. Confirm CORS on the private bucket allows GET from tenant origins including custom domains.

SP-671 Read path

1. Write the marker-to-presigned helper next to the existing presign code in services/storage.py.
2. Apply it to the student endpoints that return question content: GET /api/v1/quizzes/{quiz_nanoid}/questions and GET /api/v1/quizzes/{lesson_nanoid}/attempts/{attempt_nanoid}. The quiz info and attempts list endpoints carry no media.
3. Apply it to the instructor question endpoints in routers/v1/instructor.py, and check routers/v1/chat.py, which also reads questions.
4. Add expires_at to the questions list and attempt detail responses.
5. Unit tests with image, audio, and option images.

SP-672 Write path

1. Private-bucket write path returning a marker.
2. Switch the base64 embed rewrite in services/question.py around lines 945 to 997 and the audio upload.
3. Validators in services/rich_text.py and key parsers in services/storage.py accept marker, presigned, and legacy static-host forms.
4. Save path normalises to markers. delete_quiz_images and delete_quiz_audio target the private bucket.
5. clone_questions_for_duplicate_quiz and copy_objects target the private bucket for duplicate, licensing, _materialise_copy in services/b2b_licensing.py, and marketplace, _create_managed_replica in services/tenant_marketplace.py.
6. Update the quiz-related tests among the 37 test files that reference the storage service.

SP-673 Frontend

1. In apps/frontend/src/apis/student/useQuiz.ts, reuse scheduleUrlRefresh.ts with expires_at to call LessonsService.listQuestions again before expiry. Quiz info and attempts do not need a refetch.
2. Add an error listener on img and audio in the quiz renderers, refetch the questions list once, deduplicated.
3. Attempt review: refetch getQuizAttemptDetail on media error the same way.
4. Instructor editor refetches on error.
5. Confirm save sends the editor URL as is and the backend normalises it.

SP-674 Migration

1. List and cross-bucket copy quiz-images and quiz-audio keys under tenants/.
2. Rewrite question, explanation, options, and resources from https://static.skillpixel.vn/tenants/... to /media/tenants/... markers.
3. Dry run with counts against the inventory in section 1.
4. Write a rollback file, then run beta, then prod.
5. Delete public copies after a one-week soak. Leave the SP-671 base64 questions alone.

SP-675 Rollout

1. Beta on a wildcard host and a custom domain.
2. Two-minute lifetime test. A copied link after expiry gives 403.
3. Edit and save keeps a marker in the DB.
4. Prod release with the migration in the same window.
5. Watch PostHog for 24 h. Confirm the SP-640 storage job counts the private bucket, then clean up.

• Presigned R2 URLs from the backend, no Worker, no proxy.
• Markers in the DB, never signed URLs.
• Lifetime 4 hours.
• Default reuse the slide bucket.
• Enrollment check at mint time.
• Uploads unchanged except the bucket.
• Marketing assets stay public.
• Base64 questions untouched.