Supabase Service Key para Telemetria Server-Side

Runbook para configurar, validar e rotacionar SUPABASE_SERVICE_ROLE_KEY sem expor uma credencial privilegiada.

Quando usar: a telemetria server-side de IA não consegue gravar em ai_request_logs ou ai_model_status, ou o diagnóstico aponta 401/403. Confirme o erro antes de rotacionar a chave; gráficos vazios também podem ser causados por schema, RLS, deploy, período selecionado ou ausência de eventos.

Limites de segurança

SUPABASE_SERVICE_ROLE_KEY é uma credencial privilegiada e server-only.

não use prefixos PUBLIC_ ou VITE_;
não coloque o valor em Markdown, issue, chat, log ou commit;
não envie a chave ao navegador;
não confunda com a chave anon/publishable;
restrinja leitura de .dev.vars ao ambiente local;
em produção, use o secret store da plataforma;
após exposição suspeita, rotacione em vez de apenas apagar o texto.

Este runbook nunca precisa imprimir a chave para validar sua presença.

1. Diagnosticar

No diretório do projeto:

node tooling/check-supabase-key.mjs

Interprete o resultado sem copiar o secret:

Resultado	Próxima ação
variável ausente	configurar desenvolvimento e/ou produção
`401`	conferir projeto, formato, expiração ou rotação
`403`	conferir tipo da chave e autorização da operação
erro de rede	validar URL, DNS e disponibilidade antes de trocar credencial
chave aceita, escrita falha	revisar migration, tabela, payload e logs do servidor

2. Obter uma credencial válida

Abra Project Settings → API Keys no dashboard do projeto correto. Prefira a secret key server-side recomendada pelo Supabase; use a service_role legada somente quando a integração ainda exigir esse formato.

Antes de salvar, confirme:

a chave pertence ao mesmo projeto de SUPABASE_URL;
o ambiente é desenvolvimento, homologação ou produção;
não é a chave pública anon/publishable;
existe um plano de rotação e revogação da credencial anterior.

3. Configurar desenvolvimento local

Salve em .dev.vars, que deve permanecer ignorado pelo Git:

SUPABASE_SERVICE_ROLE_KEY="<secret-server-only>"

Não replique essa linha em um arquivo de exemplo com valor real. Um template pode declarar apenas o nome da variável e uma descrição.

Reinicie o processo de desenvolvimento para recarregar o ambiente e rode:

node tooling/check-supabase-key.mjs

4. Configurar produção

Para o projeto Cloudflare Pages atual:

npx wrangler pages secret put SUPABASE_SERVICE_ROLE_KEY --project-name=webapp

Cole o valor somente no prompt seguro. Depois, faça o deploy pelo fluxo normal do projeto. Não passe a chave como argumento de linha de comando, pois ela pode ficar no histórico ou na lista de processos.

5. Validar ponta a ponta

Gere uma chamada de IA controlada ou execute o teste administrativo.
Confirme no servidor que a persistência retornou sucesso.
Verifique se um novo registro aparece no período correto do painel.
Confirme que nenhum log contém a chave, header de autenticação ou payload privado.
Observe por alguns minutos antes de revogar a credencial anterior.

Uma validação bem-sucedida prova a operação exercitada, não todas as permissões do projeto.

Rotação

crie uma nova secret key;
atualize .dev.vars e o secret de produção;
reinicie/deploy os consumidores;
valide leitura/escrita necessárias;
revogue a chave antiga;
registre data e motivo da rotação sem registrar o valor.

Se houver múltiplos ambientes, rotacione um por vez e não reutilize a mesma credencial entre eles quando a plataforma permitir separação.

Relação com a arquitetura agnóstica

Esta chave pertence ao adapter Supabase e não deve atravessar a porta de telemetria. O domínio conhece uma operação como recordAIUsage; somente o composition root escolhe o adapter e injeta sua credencial.

Os clientes e tipos já estão canônicos em src/lib/db/providers/supabase, e src/lib/supabase apenas os reexporta durante a transição. Isso torna a fronteira auditável. Adicionar Turso ou outro provider não autoriza reutilizar a chave Supabase nem expor uma API genérica de banco.

Supabase Service Key para Telemetria Server-Side