SaaS multi-tenant no SurrealDB: organizações, times e permissões

Permissões como dados deixam o SaaS evoluir

Quando permissões ficam presas num enum do código, cada novo recurso exige alteração e deploy coordenados. Como registros, elas podem ser criadas em seed e agrupadas em papéis por organização.

UPSERT permission:members_read CONTENT {
  name: 'members/read',
  description: 'Visualizar membros da organização'
};

UPSERT permission:members_manage CONTENT {
  name: 'members/manage',
  description: 'Convidar, alterar e suspender membros'
};

UPSERT permission:billing_read CONTENT {
  name: 'billing/read',
  description: 'Visualizar plano, faturas e cobrança'
};

UPSERT permission:billing_manage CONTENT {
  name: 'billing/manage',
  description: 'Alterar plano e dados de cobrança'
};

Um papel “Financeiro” pode ter leitura e gestão de cobrança sem receber acesso a membros. Um papel “Gestor da unidade” pode enxergar somente dados de uma filial. O nome amigável do papel pode variar; as permissões continuam sendo contratos estáveis.

Como verificar uma autorização

Autorização deve responder a três perguntas:

1. qual é o usuário autenticado?
2. qual é a organização da operação?
3. o vínculo ativo aponta para um papel com a permissão necessária?

DEFINE FUNCTION fn::can(
  $user: record<user>,
  $organization: record<organization>,
  $permission_name: string
) {
  RETURN array::len(
    SELECT VALUE id
    FROM member_of
    WHERE in = $user
      AND out = $organization
      AND status = 'active'
      AND $permission_name IN role.permissions.name
    LIMIT 1
  ) > 0;
};

Adapte e valide a sintaxe à versão usada no projeto. Mais importante que copiar a função é testar o comportamento: acesso permitido no tenant correto, negado no tenant errado e negado quando o vínculo está suspenso.

O isolamento precisa chegar a cada registro

Considere uma tabela de projetos. Todo projeto deve pertencer a uma organização, e toda consulta pública precisa ser escopada por ela.

DEFINE TABLE project SCHEMAFULL;
DEFINE FIELD organization ON project TYPE record<organization>;
DEFINE FIELD name ON project TYPE string;
DEFINE FIELD status ON project TYPE string
  ASSERT $value IN ['draft', 'active', 'archived'];
DEFINE FIELD created_by ON project TYPE record<user>;
DEFINE FIELD created_at ON project TYPE datetime DEFAULT time::now();

DEFINE INDEX project_by_org ON project FIELDS organization;

Não aceite organization do formulário como verdade. O servidor deve derivar o tenant do contexto autorizado e verificar o vínculo. Caso contrário, trocar um ID na requisição pode mover ou criar dados dentro de outra empresa.

Convites precisam ser tratados como credenciais

Um convite é uma autorização pendente. Ele deve ter token imprevisível, validade, uso único, organização, papel e destinatário. Evite guardar o token puro se um hash atender ao fluxo. Ao aceitar:

1. valide expiração e uso anterior;
2. confirme a identidade ou o e-mail esperado;
3. crie o vínculo de forma idempotente;
4. marque o convite como usado na mesma transação;
5. registre o evento para auditoria.

Enviar o mesmo formulário duas vezes não pode criar duas memberships. O índice único em member_of(in, out) funciona como última barreira, mas o fluxo também precisa responder de forma previsível à repetição.

Equipes, unidades e subsidiárias: quando adicionar?

Não modele uma hierarquia corporativa inteira no primeiro dia.

• Equipes fazem sentido quando pessoas colaboram em subconjuntos de projetos.
• Unidades fazem sentido para filiais, departamentos ou regiões com dados próprios.
• Subsidiárias entram quando uma empresa-mãe precisa delegar acesso a organizações juridicamente ou operacionalmente separadas.

Comece com organização, membership e papel. Adicione outro nível quando existir uma pergunta concreta de autorização que o nível atual não consegue responder.

LGPD, auditoria e suporte

Multi-tenancy aumenta o impacto de qualquer falha: um bug pode expor dados de uma empresa para outra. Além de permissões, planeje:

• log de alterações sensíveis com ator, tenant e horário;
• exportação e exclusão com escopo correto;
• retenção de convites e contas suspensas;
• suporte administrativo sem “virar” qualquer usuário silenciosamente;
• mascaramento de dados em ambientes não produtivos;
• alertas para volume incomum de leitura ou exportação.

Logs também contêm dados. Não registre token de convite, sessão, documento completo ou corpo indiscriminado de requisições.

Testes que um SaaS multi-tenant precisa ter

Uma suíte mínima deve provar:

1. membro ativo lê dados da própria organização;
2. o mesmo membro não lê dados de outra organização;
3. membro sem billing/read não vê cobrança;
4. membro suspenso perde acesso;
5. convite expirado falha;
6. convite repetido não duplica vínculo;
7. usuário em duas organizações recebe permissões diferentes;
8. trocar o ID da organização na requisição não contorna autorização;
9. exclusão de usuário não deixa relações órfãs sem decisão explícita;
10. tarefas internas não usam um tenant recebido sem validação.

Peça para a IA gerar esses testes, mas confira se eles exercitam a conexão com privilégios reais. Testar tudo como root apenas prova que root pode fazer tudo.

Perguntas frequentes sobre multi-tenancy no SurrealDB

Devo criar um banco por cliente?

Depende do contrato, escala e isolamento exigido. Um banco compartilhado com tenant explícito simplifica operação e visão agregada; bancos separados aumentam isolamento, mas multiplicam migrações, conexões e observabilidade. Não escolha sem mapear backup, suporte e custo.

Papel e permissão são a mesma coisa?

Não. Permissão representa uma ação; papel agrupa permissões. Isso permite que cada organização tenha papéis como “Financeiro” ou “Operações” sem mudar o código da aplicação.

Posso confiar apenas na API para separar tenants?

Uma API bem construída é uma camada importante, mas permissões e invariantes próximas dos dados criam defesa em profundidade. A falha de uma rota não deve transformar o banco inteiro em leitura pública.

Preciso de equipes desde o MVP?

Geralmente não. Implemente primeiro organização, vínculo e papel. Equipe só entra quando usuários realmente precisam compartilhar uma parte do tenant com regras diferentes.

Uma base pequena, mas impossível de atravessar

O melhor MVP multi-tenant não é o que tem a matriz de permissões mais sofisticada. É o que consegue provar que uma pessoa nunca atravessa a fronteira da organização errada.

Comece pelo guia SurrealDB para vibe coding, modele um único recurso com tenant obrigatório e escreva os testes negativos antes de construir o painel de administração.

Do vibe ao produto. Com método.