Especialista Supabase no Specsfy: documentação técnica

Quando usar

Acionar quando o projeto tem supabase/config.toml, migrations em supabase/migrations/, ou clientes @supabase/supabase-js e a tarefa envolve RLS, Auth, Storage, Realtime, Edge Functions ou ambiente local Supabase (supabase start).
Acionar também para revisão de política de acesso, policy RLS ausente ou incorreta, ou exposição indevida de service_role.
Não acionar para tuning puro de índice/plano/isolation do Postgres subjacente sem o contexto Supabase — usar $specsfy-specialist-postgres e trazer o resultado de volta para as policies.
Combinar com $specsfy-specialist-application-security quando a revisão envolver JWT, claims customizadas ou superfícies de autorização fora do banco.

Identificar SDK usado (@supabase/supabase-js, ssr, framework específico), projeto, schemas expostos via API, migrations existentes e estratégia de ambientes (local, preview, produção).
Mapear identidades, tenants, papéis (anon, authenticated, papéis customizados) e a origem de cada claim usada em decisão de acesso (auth.uid(), auth.jwt(), metadata).
Modelar tabelas, funções e views no Postgres primeiro — a API REST/ GraphQL e os tipos gerados são derivados do schema, não o contrário.
Definir privilégios (GRANT) para o objeto e políticas RLS para cada operação (SELECT, INSERT, UPDATE, DELETE) e papel, negando por padrão.
Implementar a migration versionada e testar com usuários representativos de cada papel, incluindo o caso sem sessão (anon).
Validar Auth, Storage, Realtime ou Edge Functions apenas quando o projeto de fato os usa — não configurar superfície que a aplicação não expõe.
Verificar tipos TypeScript gerados, estratégia de pooling (session vs transaction), logs e política de backup/rollback antes de considerar pronto.

Habilitar RLS em toda tabela de schema exposto à API e negar por padrão — tabela com RLS desabilitada em schema público é acessível por qualquer anon que descubra o nome.
Nunca expor service_role no cliente (browser, app mobile, bundle público), ela ignora RLS e só pertence a ambiente de servidor confiável.
Testar cada policy separadamente para anon, authenticated e qualquer papel de aplicação — uma policy que “parece” restringir mas usa USING (true) equivale a não ter policy.
Tratar como superfície crítica: funções SECURITY DEFINER (rodam com privilégio do dono, não do chamador — precisam de search_path fixo e validação interna própria), claims customizadas no JWT (podem ser manipuladas se a fonte não for confiável) e buckets de Storage marcados como públicos.
Versionar toda mudança de schema em migration (supabase migration new), edição manual no dashboard de produção diverge do histórico e quebra supabase db diff/CI.
Separar autorização de produto (o que este usuário pode fazer com este registro) da mera autenticação (quem é o usuário) — RLS resolve a primeira, Auth resolve a segunda.
Planejar conexão direta (poucas conexões persistentes, migrations), session pool (compatibilidade ampla, PREPARE funciona) ou transaction pool (alta concorrência, serverless) conforme o workload e o driver.

Policy USING (true)/WITH CHECK (true) deixada “temporariamente” para destravar desenvolvimento e nunca revisada antes de produção — equivale a RLS desabilitada.
Checar tenant/ownership só no cliente (filtrar a query pelo tenant_id no frontend) sem policy correspondente no banco — qualquer chamada direta à API contorna o filtro.
Função SECURITY DEFINER sem SET search_path = ''/schema fixo — permite sequestro de função por objeto de mesmo nome em outro schema no search_path do chamador.
Migration aplicada manualmente em produção via dashboard, divergindo do histórico versionado — o próximo db push/db diff não sabe reconciliar o estado real.
Confiar em claim customizada do JWT sem validar sua origem (ex.: campo gravável pelo próprio usuário sendo usado como papel de autorização).

Provar acesso permitido e negado com identidades reais de teste para cada papel, incluindo sessão ausente (anon) e o “vizinho” de outro tenant.
Executar supabase db reset/lint/migrations no ambiente local antes de promover — o projeto local reproduz o schema e as policies de produção.
Conferir tipos gerados (supabase gen types) atualizados, replicação/ Realtime restrita ao mesmo modelo de tenancy, policies de Storage por bucket, e segredos de Edge Functions fora do código-fonte.
Avaliar recuperação e exportação dos dados além do backup gerenciado — testar um restore ou export completo, não assumir que o backup automático garante RTO aceitável.
Não declarar uma tabela “protegida por RLS” sem o teste negativo (acesso que deveria falhar, falhando de fato).

$specsfy-specialist-docker cobre serviços locais e imagens auxiliares, esta skill governa os contratos gerenciados da plataforma Supabase.
$specsfy-specialist-postgres para modelagem de schema, índice, plano de query e isolation por trás do Supabase.
$specsfy-specialist-application-security para modelagem de ameaça de JWT, claims e superfícies de autorização além de RLS.
$specsfy-specialist-laravel quando o mesmo projeto tiver um backend Laravel consumindo o mesmo Postgres além do Supabase.

Leia references/standards.md antes de alterar RLS, Auth, schemas expostos, Storage, Realtime ou estratégia de conexão.