Controle de acesso

O controle de acesso fica concentrado em lib/access-control. Esse diretório reúne as peças que decidem se o usuário atual pode executar uma ação ou acessar um recurso — services de domínio continuam responsáveis pelas regras de negócio, mas validações de acesso reutilizáveis não devem ficar espalhadas em lib/services.

O motor é multi-tenant: um usuário pode estar vinculado a várias empresas (Empresa/MembroEmpresa, ver Empresas e multi-tenant), cada uma com seus próprios perfis (Role) e um plano de assinatura (Plano) que funciona como teto de features. Não existe mais perfil global do usuário — permissão sempre vem do vínculo com a empresa ativa da sessão.

Estrutura

• context.ts: monta o AccessContext do usuário atual (sessão + vínculo com a empresa ativa + permissões do perfil + teto do plano).
• current-user.ts: helpers para obter o usuário/contexto atual, incluindo UsuarioAtualContexto (usado por BaseService para escopar queries por empresaId).
• policy.ts: decisões puras — papel ativo (canActAs), vínculo com empresa (temEmpresaAtiva) e permissão granular (canUseFeature).
• action-guards.ts: guards de papel/tenant (assertAdminAction, assertEmpresaAction, assertProprietarioEmpresa), usados por server actions.
• permission-guard.ts: guard de permissão granular (assertCurrentUserCan), usado por server actions.
• permission-registry.ts: catálogo único de recursos e operações (resourceRegistry/permissionKeys) — fonte de verdade das chaves recurso:acao, consumida pela tela de perfis, pela tela de planos e pelo componente PermissionMatrixField.
• errors.ts: erros padronizados de acesso.

AccessContext

AccessContext é o objeto base para qualquer decisão de acesso. Contém o usuário atual, se ele é admin da plataforma e o vínculo dele com a empresa ativa da sessão (ou null, se nenhuma).

export type AccessContext = {
  usuarioId: string;
  isAdmin: boolean;
  membroEmpresa: {
    membroId: string;
    empresaId: string;
    roleId: string;
    roleNome: string;
    permissoes: string[];
    permissoesPlano: Record<string, boolean>;
  } | null;
};

• membroEmpresa vem do MembroEmpresa ativo do usuário para a empresa ativa da sessão (cookie EMPRESA_ATIVA_COOKIE, sempre revalidado contra o banco — o cookie nunca é confiado sozinho). Um usuário sem nenhuma empresa (ou sem cookie de empresa ativa válido) tem membroEmpresa: null.
• permissoes vem de role.permissoes (Role.permissoes, uma coluna String[] no Prisma) — o perfil que o MembroEmpresa aponta, escopado à empresa.
• permissoesPlano vem de planoService.buscarMatriz(empresa.planoId) — a matriz de features liberadas pelo plano de assinatura da empresa (empresaId a partir do plano em /admin/planos). Empresa sem planoId (null) equivale a "tudo liberado", para não travar empresas criadas antes de o teto de plano existir.

Exemplo real: app/(admin)/admin/layout.tsx usa getAccessContext() e canActAs(ctx, "ADMIN") para decidir se o usuário pode entrar na área administrativa (global, não por empresa), redirecionando para /dashboard caso contrário. Já app/dashboard/empresa/layout.tsx usa temEmpresaAtiva(ctx) para o gate da área de gerenciamento de empresa.

Três mecanismos de decisão

O motor tem três camadas, para três tipos de regra diferentes:

• Papel administrativo da plataforma (isAdmin, binário): decide acesso a áreas/funcionalidades globais, fora do escopo de qualquer empresa (ex.: /admin, /admin/planos). Verificado com canActAs(ctx, "ADMIN") / assertAdminAction.
• Vínculo com empresa (membroEmpresa !== null, binário): decide acesso à área de gerenciamento de uma empresa como um todo, independente do perfil específico. Verificado com temEmpresaAtiva(ctx) / assertEmpresaAction. Há também canActAs(ctx, "PROPRIETARIO_EMPRESA") / assertProprietarioEmpresa, reservado às ações exclusivas do Proprietário (inativar a empresa, transferir titularidade).
• Permissão granular (recurso:acao, lista): decide acesso a uma ação específica dentro de um recurso. Verificado com canUseFeature(ctx, permissao) / assertCurrentUserCan(permissao).

canUseFeature exige duas condições independentes para liberar uma permissão granular:

1. A chave estar em ctx.membroEmpresa.permissoes (o perfil do usuário na empresa libera) — exceto para o perfil "Proprietário", que sempre passa nesta camada, mesmo que a chave não esteja gravada em Role.permissoes (ver Empresas e multi-tenant — o Proprietário sempre tem todas as permissões e não é editável em /dashboard/empresa/papeis).
2. A chave estar em ctx.membroEmpresa.permissoesPlano (o plano da empresa libera) — sem exceção, nem para o Proprietário: o teto de plano vale para qualquer perfil.

Um usuário admin da plataforma (ctx.isAdmin === true) sempre passa em canUseFeature, ignorando as duas camadas — acesso irrestrito, sem depender de vínculo com nenhuma empresa.

Fluxo padrão de uma action protegida

1. Validar o input com schema (zod).
2. Montar AccessContext com getAccessContext() (ou obtê-lo já validado via assertCurrentUserCan).
3. Validar papel/tenant com os guards.
4. Chamar o service, sempre passando o empresaId do contexto — nunca aceitar um empresaId vindo do client sem confirmar o vínculo.

"use server";

import { assertAdminAction, getAccessContext } from "@/lib/access-control";
import { DataBaseResponse } from "@/lib/services/config/database-response";
import { z } from "zod";

const schema = z.object({
  id: z.string().min(1),
});

export async function exemploAction(input: unknown) {
  const parsed = schema.safeParse(input);

  if (!parsed.success) {
    return DataBaseResponse.error({
      code: "VALIDATION_ERROR",
      message: "Dados inválidos.",
    }).serialize();
  }

  const ctx = await getAccessContext();
  await assertAdminAction(ctx);

  // ...lógica protegida
}

Exemplo real: permissão granular escopada por empresa (agenda:*)

app/agenda/_components/engine/agendamento.actions.ts protege criação, atualização e exclusão de eventos com assertCurrentUserCan, uma permissão por ação, e sempre escopa ao empresaId do vínculo ativo:

"use server";

import { assertCurrentUserCan } from "@/lib/access-control";
import { EmpresaRequiredError } from "@/lib/access-control/errors";

export async function criarEventoAction(input: unknown) {
  const ctx = await assertCurrentUserCan("agenda:create");

  // ctx.usuarioId já validado; se o usuário não tiver a permissão
  // "agenda:create" (nem em Role.permissoes, nem no plano da empresa) e
  // não for admin, a linha acima já lançou AccessDeniedError.

  if (!ctx.membroEmpresa) {
    throw new EmpresaRequiredError();
  }

  // ...validação do input e chamada ao agendamentoService, passando
  // ctx.membroEmpresa.empresaId
}

Guard de permissão e escopo de tenant são checagens independentes: mesmo o admin da plataforma (que sempre passa em assertCurrentUserCan) precisa de uma empresa ativa pra criar um evento, porque Evento pertence a uma Empresa, não a um usuário. atualizarEventoAction e excluirEventoAction seguem o mesmo padrão, com "agenda:update" e "agenda:delete".

Como incluir uma nova permissão

1. Escolha o nome no formato recurso:acao (ex.: relatorios:export, financeiro:delete) e adicione-o em lib/access-control/permission-registry.ts (resourceRegistry), classificando a operação como create/read/update/delete (fica atrás do checkbox mestre do recurso na UI de perfis/planos) ou extra (só aparece em "+ opções"). Se o recurso tiver uma operação read, aplicarDependenciasDeLeitura trava automaticamente create/update/delete desse recurso atrás da leitura — não dá pra liberar escrita sem leitura, nem na UI (PermissionMatrixField) nem gravando direto via role.service/plano.service.
2. Libere no plano: em /admin/planos (área global, só admin), marque a chave como permitida para o(s) plano(s) que devem ter acesso à feature — sem isso, canUseFeature nunca libera a permissão, mesmo que o perfil do usuário a tenha.
3. Atribua a um perfil da empresa: em /dashboard/empresa/papeis, marque a chave no perfil desejado (ou crie um perfil customizado). Não exige migration — Role.permissoes é String[].
4. Proteja a action com await assertCurrentUserCan("recurso:acao") logo no topo, antes de validar o input.
5. Esconda a UI correspondente, se fizer sentido, checando canUseFeature(ctx, "recurso:acao") num Server Component (sem precisar lançar erro — só decide o que renderizar).

A página /dashboard/exemplos mostra, para o usuário logado, o resultado de cada camada (perfil, plano, canUseFeature) para todas as chaves do catálogo — útil pra depurar por que uma permissão está ou não liberada.

Policies

policy.ts contém decisões sem consultar o banco (o AccessContext já foi carregado por getAccessContext()):

• canActAs(ctx, "ADMIN" | "PROPRIETARIO_EMPRESA") — papel administrativo da plataforma ou papel de Proprietário na empresa ativa.
• temEmpresaAtiva(ctx) — há vínculo ativo com alguma empresa (ou o usuário é admin da plataforma).
• canUseFeature(ctx, permissao) — permissão granular (recurso:acao); admin sempre retorna true; ver as duas camadas (perfil + plano) acima.

Use policy quando a decisão depender apenas do AccessContext já carregado — por exemplo, pra decidir o que renderizar num Server Component sem lançar erro.

Erros

Erros disponíveis em errors.ts: AuthenticationRequiredError, AccessDeniedError, ProfileRequiredError, EmpresaRequiredError.

assertAdminAction/assertProprietarioEmpresa lançam ProfileRequiredError (subclasse de AccessDeniedError); assertEmpresaAction lança EmpresaRequiredError (também subclasse de AccessDeniedError); assertCurrentUserCan lança AccessDeniedError diretamente, com a permissão faltante na mensagem.

Estendendo o RBAC

Para adicionar um novo perfil, recurso ou regra de ownership:

1. Se for decisão sem banco, adicione em policy.ts.
2. Se for uma permissão granular nova (recurso:acao), siga "Como incluir uma nova permissão" acima — cadastro no registry, teto de plano, atribuição a um perfil, guard na action.
3. Se precisar carregar um recurso com verificação de ownership além do escopo de empresa, crie um guard próprio (siga o padrão de assertProprietarioEmpresa).
4. Se for composição comum de server action, adicione em action-guards.ts ou permission-guard.ts, conforme o mecanismo (papel/tenant ou permissão).