docs: document Studio identity and tenant isolation setup

docs/STUDIO_IDENTITY_SETUP.md

@@ -0,0 +1,42 @@
+# MediaRouter Studio identity and tenant isolation
+
+MediaRouter Studio authenticates users with Supabase on the Next.js server and forwards a short-lived, signed identity envelope to MediaRouter. The shared MediaRouter API token is a server-to-server transport credential; it must never be exposed to browser code.
+
+## Required configuration
+
+Set these values in both environments:
+
+- **Studio / Vercel:** `STUDIO_IDENTITY_SECRET` and `MEDIAROUTER_API_TOKEN`. Keep them server-only; do not use a `NEXT_PUBLIC_` prefix.
+- **MediaRouter / Hugging Face Space:** `STUDIO_IDENTITY_SECRET` with the exact same secret value, plus the existing API authentication and production database configuration.
+
+Use a cryptographically random secret of at least 32 bytes. Generate one with a password manager or a secure local random generator. Do not paste it into source control, logs, or chat. Restart/redeploy both services after setting it.
+
+The Studio proxy signs the UTF-8 bytes of four newline-separated values in this order: timestamp (Unix seconds), Supabase user ID, normalized email, display name. It uses HMAC-SHA256 and sends the lowercase hexadecimal signature in `x-mr-studio-signature`. The backend validates the signature in constant time and rejects envelopes more than 300 seconds from server time.
+
+## Tenant onboarding is explicit
+
+A valid Supabase session proves identity, but it does **not** automatically grant a MediaRouter workspace. Before a user can use tenant-backed Studio APIs, the backend security database must contain:
+
+1. An active `users` row whose `subject` exactly matches the Supabase user ID.
+2. Exactly one active `workspace_memberships` row for that user, linked to an active `workspaces` row.
+3. A supported membership role: `owner`, `admin`, `developer`, `operator`, `viewer`, or `member`.
+
+Users with no active membership or more than one active workspace membership are denied. This is deliberate: the current Studio identity envelope has no workspace selector, and the backend must not guess a tenant. Do not solve onboarding by trusting a workspace ID from a browser request or by assigning every newly signed-in user an owner role. Implement a separately authorized invitation/provisioning flow before allowing self-service workspace creation.
+
+## Authorization behavior
+
+The backend treats the shared API key as transport authentication only when a signed Studio identity is present. It resolves the Supabase subject against persisted backend membership, replaces the key's tenant identity with that persisted principal, and intersects API-key scopes with the membership role's default scopes. Workspace owners/admins are mapped to the backend `developer` capability set, not the global API `admin` role. Viewer/member access is restricted to the viewer capability set.
+
+If any Studio identity header is present, the complete envelope and signature are required. The Studio proxy also fails closed when it cannot validate a Supabase session; it must not forward the shared token as a fallback for an unidentified browser request.
+
+## Production verification checklist
+
+- [ ] Set the same random `STUDIO_IDENTITY_SECRET` in Vercel and the HF Space.
+- [ ] Confirm `MEDIAROUTER_API_TOKEN` is only a server-side Vercel environment variable.
+- [ ] Provision one explicit backend user and workspace membership for each Studio user, or implement an authorized invitation flow.
+- [ ] Use a non-superuser tenant database role and verify forced RLS policies on production tables; a passing application-level check alone is not proof of database isolation.
+- [ ] Test with two distinct Studio accounts: create/read/update/delete a project and access an asset/job in account A, then confirm account B cannot read, mutate, cancel, or download A's resources.
+- [ ] Test expired and tampered signatures, disabled users/memberships/workspaces, and users with zero or multiple active memberships.
+- [ ] Run the backend unit/integration tests and inspect production logs for denied cross-tenant access before merging/deploying.
+
+This document describes the intended configuration and checks; it is not evidence that the live deployment has been configured or that the checklist has passed.