Multi-tenancy e isolamento de dados

Modelo conceitual

Tenant (Instituicao)
  ├── Users (alunos, professores, coordenadores, admin institucional)
  ├── Courses → Modules → Lessons
  ├── ClassGroups (turmas)
  ├── MediaAssets (biblioteca de midia)
  ├── Automations
  ├── EmailTemplates
  ├── VideoProviderConfig (BBB/Zoom/Teams/Meet)
  ├── TenantApiKey (chaves proprias de IA)
  ├── TenantSubscription (billing)
  ├── ...todas as outras entidades

Usuarios sem tenantId sao B2C (plataforma direta). Usuarios com tenantId pertencem a uma instituicao.

Isolamento de dados — 3 camadas

Camada 1: Filtro obrigatorio em queries

Toda query Prisma em codigo de aplicacao filtra por tenantId:

const { tenantId } = requireTenant(user);
const courses = await prisma.course.findMany({
  where: { tenantId }, // OBRIGATORIO
});

requireTenant() em apps/web/lib/tenant.ts retorna NextResponse 403 se o usuario nao tem tenant. Sem essa chamada, e impossivel acessar dados B2B.

Camada 2: RLS no Supabase

Como safety net contra bugs, policies RLS no Supabase reforcam isolamento ate em queries diretas. Se um codigo esquecer o filtro tenantId, o banco recusa.

Camada 3: Auditoria de admin global

Quando um admin global precisa acessar dados de um tenant (suporte, debug), ele usa impersonacao via cookie HMAC com:

• TTL fixo de 1h (nao prorrogavel)
• Assinatura HMAC-SHA256 com IMPERSONATION_SECRET
• Auditoria em AdminAuditLog (acao impersonate.start, IP, user-agent)
• getUserProfile() retorna isImpersonating: true + overlay em memoria
• Supabase auth NUNCA modificado (apenas overlay)
• Banner sticky no /institution/ alerta o admin durante a sessao

O painel admin SaaS global inclui impersonacao para suporte.

Per-tenant API keys

Por padrao, todas as chamadas LLM usam chaves globais (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc) do Studeia. Custos vao para o tenant via metering.

Mas instituicoes que ja tem contas Anthropic/OpenAI/Google podem usar proprias chaves (TenantApiKey, criptografada AES-256-GCM no banco):

1. Custos vao DIRETO para a conta do tenant na Anthropic/OpenAI
2. Studeia nao cobra margem de IA — apenas a assinatura mensal
3. Resolucao automatica: TenantApiKey → ProviderApiKey global → process.env (cascata em apps/web/lib/api-key-resolver.ts)

NUNCA seta process.env em runtime (conflitaria entre tenants) — passa a key via options do SDK.

White-label completo

Cada tenant pode personalizar:

Roles e permissoes

Limites por plano

Limites enforceados via checkTenantResourceLimit(tenantId, resource) em apps/web/lib/plan-limits.ts:

7 pontos de enforcement (todos auditados em 2026-04-11):

1. POST /api/courses/[courseId]/enroll — self-enroll do aluno
2. POST /api/institution/courses/[id]/clone — clone de curso
3. POST /api/institution/courses/import — import IMS CC
4. executeEnrollUser() em automacao
5. POST /api/scim/v2/Users — provisionamento SCIM
6. POST /api/institution/users — vincular usuario existente
7. PATCH /api/institution/users/[id] — promover role

Como solicitar override enterprise

Tenants enterprise podem ter Tenant.maxStudentsOverride: Int? ajustado pelo admin global. Sem override (null), enterprise = ilimitado. Contato comercial via contact@studeia.com.

Limitacoes

• Um User pertence a UM tenant. Para professores que atendem multiplas escolas, criar usuarios separados.
• Compartilhamento de cursos entre tenants nao e nativo (cada tenant tem seu CMS isolado). Roadmap: marketplace de cursos com licenciamento.
• Migracao de tenant para outro plano e instantanea, mas downgrade que viola limites atuais e bloqueado ate o tenant ajustar os recursos.

Veja tambem

• White-label
• SSO Enterprise
• Comparativo: Studeia vs Moodle