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 gate uses the prefix only to match the cookie tenant against the key tenant.

Pieces

• Private R2 bucket. Public access off. The Worker reads it through an R2 binding, so no S3 keys leave Cloudflare. Reuse the slide bucket or add a media bucket per env. SP-670 decides.
• Route. Worker mounted at /media/* on every tenant host. Tenant hosts already go through Cloudflare, both the *.skillpixel.vn wildcard and Phase 4 custom domains via Cloudflare for SaaS. Stored URLs become path-only: /media/tenants/{tenant_id}/quiz-images/{quiz_nanoid}/{file}.png
• Signed token and cookie. After Firebase login the frontend calls the backend, which checks tenant membership and returns a token {tenant_id, user_id, exp} with an HMAC. The frontend POSTs the token to /media/session on the current host and the Worker sets the sp_media cookie. HttpOnly, Secure, SameSite=Lax, Path=/media, about 30 minutes.
• Why the Worker sets the cookie, not the API. The API host is not the tenant host. A Set-Cookie from the api host with Domain=.skillpixel.vn reaches wildcard tenants but never a custom domain like learn.partner.com. The cookie must be first-party on the page host.
• Refresh. Timer at two thirds of cookie life, paused when the tab is hidden, plus a one-shot refresh and retry when an image or audio element errors with 401. This piggy-backs on the Firebase token renewal the frontend already does.
• Uploads unchanged. Presigned PUT still writes to the bucket. Only reads change.

Presigned GET works for slides because pages are fetched fresh per view. For images inside stored HTML you would rewrite every URL on every read, and browsers cannot cache a URL that changes each time. The cookie gate keeps stored HTML stable and keeps edge and browser caching.

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 Spike

1. Confirm a Worker route on /media/* fires on Cloudflare for SaaS custom hostnames, not only on wildcard hosts.
2. Decide the bucket: reuse the slide bucket or add a media bucket per env.
3. Generate the HMAC secret and place it in Infisical and as a wrangler secret.
4. Write the route and secret decisions back into this plan.

SP-671 Media Worker

1. Parse the sp_media cookie and verify the HMAC with 60 s slack on exp.
2. Match the cookie tenant against the key tenant prefix. Return 401 on no or bad cookie, 403 on tenant mismatch.
3. Read the object through the R2 binding. Return 404 when it is missing.
4. Add edge cache lookup and store, and support Range requests for audio.
5. Handle POST /media/session: verify the token and set the cookie.
6. Write wrangler config and a CI deploy job.
7. Cover it with vitest and miniflare tests.

SP-672 Backend

1. Add the session token endpoint with a membership check that signs {tenant_id, user_id, exp}.
2. Update apps/backend/app/services/storage.py: tenant_object_key, public_blob_url, quiz_image_key_from_url, quiz_audio_key_from_url, and the copy_objects container, so the gated write path returns /media/ URLs.
3. Switch quiz image and audio uploads to the private bucket.
4. Update services/question.py: the base64 embed rewrite around lines 945 to 997 and clone_questions_for_duplicate_quiz.
5. Update services/rich_text.py validators and extractors, plus the key parsers and delete helpers.
6. Update the clone paths: services/b2b_licensing.py _materialise_copy, services/tenant_marketplace.py _create_managed_replica, and services/course.py duplicate_course.
7. 37 backend test files reference the storage service. Only the quiz-related ones need edits.

SP-673 Frontend

1. Refresh the cookie on Firebase token renewal plus a timer at two thirds of cookie life, paused when the tab is hidden.
2. Reuse apps/frontend/src/lib/scheduleUrlRefresh.ts, the same timer helper used for slide presigned URLs.
3. Add an error listener on image and audio elements: one-shot refresh and retry on a 401.
4. Clear the cookie on logout.
5. Wire local dev: wrangler dev behind the Vite proxy or a dev-only backend route. The API base is VITE_API_BASE_URL, and requests send X-Tenant-Host, so the backend resolves the tenant from that header.

SP-674 Migration

1. Server-side copy of quiz objects from https://static.skillpixel.vn to the private bucket under target path prefix /media/.
2. Rewrite URLs in question text, explanation, options, and resources. Use the inventory counts from section 1.
3. Keep the 671 base64 questions untouched.
4. Dry run first, write a rollback file, then run beta, then prod.
5. Delete the public copies after a soak.

SP-675 Rollout

1. Beta walkthrough on a wildcard host and a custom domain.
2. Check Safari audio with Range requests on a real device.
3. Watch PostHog for image and audio errors.
4. Release to prod, then clean up the public bucket.

• Tenant-level gate.
• First-party cookie on the tenant host.
• Worker sets the cookie.
• Auth before cache.
• Path-only stored URLs.
• Uploads unchanged.
• Marketing assets stay public.
• Base64 questions untouched.