Capítulo 18 de 59

O Risco Fatal das Chaves: Service Role vs. Anon Key

Índice do Manual

No desenvolvimento de arquiteturas baseadas em Supabase e Next.js, o manuseio de credenciais é o ponto exato onde a negligência técnica destrói sistemas.

Um erro comum em equipes juniores — e um vício perigoso em agentes de Inteligência Artificial — é a confusão operacional entre as duas chaves de API fornecidas pelo Supabase: a Anon Key e a Service Role Key.

Trocar o local de uso dessas chaves não gera apenas um erro no terminal. Usar a chave pública no lugar da privada impede o funcionamento de processos de backend. Pior: vazar a chave privada para o frontend concede controle absoluto do banco de dados para qualquer usuário na internet.

Documentamos abaixo a lei arquitetural sobre o isolamento e o escopo exato de cada chave.


1. Anon Key (A Chave Pública)

A anon_key (Anonymous Key) é a chave projetada exclusivamente para a exposição pública. No Next.js, ela é declarada no arquivo de ambiente com o prefixo público: NEXT_PUBLIC_SUPABASE_ANON_KEY.

O que ela faz?

Ela atua apenas como uma "maçaneta" para a porta do seu banco de dados. Ela permite que a requisição chegue ao Supabase, mas não concede nenhuma permissão automática.

Toda requisição feita com a anon_key bate imediatamente na barreira do RLS (Row Level Security). Se o usuário não estiver logado ou se a política de segurança (Policy) não permitir a leitura, o banco de dados simplesmente retornará uma matriz vazia ou um erro de permissão.

Onde utilizá-la:

  • Em qualquer código de Frontend (Client Components do Next.js).
  • Quando você deseja que as regras normais de segurança (RLS) sejam aplicadas rigorosamente.
  • No momento de realizar login, logout e criar contas de usuários padrões.

2. Service Role Key (A Chave Mestre Administrativa)

A service_role_key é o nível "Deus" (God Mode) da infraestrutura do Supabase. Ela é declarada estritamente como SUPABASE_SERVICE_ROLE_KEY (sem o prefixo NEXT_PUBLIC).

O que ela faz?

Esta chave foi projetada para rotinas administrativas puras. Ela ignora (bypass) 100% das políticas de segurança do RLS.

Se um código utiliza esta chave, ele tem permissão matemática e irrestrita para deletar todos os usuários, apagar todos os bancos de dados e limpar o Storage inteiro, independentemente de quem estiver logado (ou se ninguém estiver logado).

Onde utilizá-la (A Lei):

O uso desta chave é terminantemente proibido no código do cliente (Frontend). No backend, ela é restrita a:

  • Supabase Edge Functions (Deno): Ao receber Webhooks externos (como Stripe ou WhatsApp) ou disparos de Database Triggers, a requisição não possui um usuário logado na sessão. A service_role_key entra em ação na Edge Function para atualizar o banco no nível de sistema.
  • Exceções Administrativas em Server Actions do Next.js: Operações restritas de super-administração que o RLS bloqueia por design (como a API auth.admin.inviteUserByEmail() para convidar colaboradores ou resetar contas), SEMPRE precedidas pela checagem manual de autorização do usuário logado no topo da função.
  • Scripts de migração ou automações executadas via terminal local fechado.

3. A Armadilha do Backend (Server Components e Server Actions Comuns)

O erro conceitual mais letal na transição para o Next.js moderno (App Router) é acreditar que, como o código está rodando no Backend (Server Components ou Server Actions), deve-se utilizar a service_role_key para buscar ou salvar dados corriqueiros.

Isso é categoricamente falso.

No ecossistema Supabase, a segurança mora no Banco de Dados (RLS), não no servidor web. Se o backend utilizar a chave mestre para operações comuns, o Supabase ignorará o RLS. Uma simples busca por "listar pedidos" retornaria os pedidos de todas as empresas cadastradas no sistema SaaS, forçando o desenvolvedor a escrever dezenas de filtros manuais no código web, o que invariavelmente gera vazamentos de dados entre clientes (Cross-Tenant Data Leakage).

A regra de ouro para o Next.js: Toda busca de Server Component e mutação de Server Action acionada por um usuário deve utilizar a anon_key combinada aos Cookies de Sessão do navegador (usando @supabase/ssr). Desta forma, o servidor age em nome do usuário logado, e o próprio PostgreSQL impõe a filtragem das linhas pelo RLS.

Como Implementar a Exceção Administrativa em Server Actions com Segurança

Se a sua Server Action realmente precisa invocar a API de administração (auth.admin), siga obrigatoriamente este padrão de três etapas:

// app/actions/admin-invite-user.ts
"use server";

import { createServerClient } from "@/lib/supabase/server";
import { createClient } from "@supabase/supabase-js";

export async function inviteEmployeeAction(email: string) {
  // 1. Identifica o usuario logado com o client comum (ANON + Cookies)
  const supabase = await createServerClient();
  const { data: { user }, error: authError } = await supabase.auth.getUser();

  if (authError || !user) {
    throw new Error("Sessao invalida. Faca login novamente.");
  }

  // 2. Valida se o usuario logado possui permissao de Administrador no banco
  const { data: profile } = await supabase
    .from("profiles")
    .select("role")
    .eq("id", user.id)
    .single();

  if (profile?.role !== "admin") {
    throw new Error("Acesso negado: apenas administradores podem convidar usuarios.");
  }

  // 3. APENAS com a autorizacao confirmada, instancia o client Service Role
  const supabaseAdmin = createClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.SUPABASE_SERVICE_ROLE_KEY!
  );

  const { data, error } = await supabaseAdmin.auth.admin.inviteUserByEmail(email);

  if (error) {
    throw new Error(`Falha ao enviar convite: ${error.message}`);
  }

  return { success: true, invitedUser: data.user };
}

4. O Veredito Arquitetural e Tratamento de Falhas

A arquitetura moderna prevê que a confiança no código do desenvolvedor é zero. Para evitar falhas, impomos as seguintes barreiras:

  1. Prevenção de Vazamento Front-End: O Next.js possui uma trava nativa onde apenas variáveis com prefixo NEXT_PUBLIC_ são enviadas ao navegador. A chave mestre nunca deve possuir este prefixo. Se for declarada como NEXT_PUBLIC_SUPABASE_SERVICE_ROLE_KEY, a infraestrutura está comprometida e o token revogado.
  2. Uso de Service Role sob Demanda Restrita: A service_role_key só entra em campo em Edge Functions sem usuário logado (Webhooks externos) ou em Server Actions administrativas com checagem rigorosa de role === 'admin' antes da execução.
  3. Revisão de Código Restrita: Se um robô autônomo de Inteligência Artificial ou um desenvolvedor tentar utilizar a service_role_key dentro de um Server Component para fazer listagens comuns de tela, o código deve ser rejeitado. Toda busca de UI utiliza anon_key + Cookies.

Dominar o isolamento destas chaves não é um mero detalhe de configuração; é a assinatura de maturidade técnica que separa sistemas amadores de plataformas corporativas blindadas.