Imported from promovaweb/specsfy (
specialists/specsfy-specialist-supabase/SKILL.md). Install upstream withnpx skills add promovaweb/specsfy --skill specsfy-specialist-supabase. Copyright stays with the author.
Supabase
Quando usar
- Acionar quando o projeto tem
supabase/config.toml, migrations emsupabase/migrations/, ou clientes@supabase/supabase-jse 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-postgrese trazer o resultado de volta para as policies. - Combinar com
$specsfy-specialist-application-securityquando a revisão envolver JWT, claims customizadas ou superfícies de autorização fora do banco.
No Specsfy
-
Fonte de entrada por fase
- Em
specsfy-02-backlog, leia o item emspecs/backlog/e registre ali as decisões e sinais do especialista, além das dúvidas abertas. - Em
specsfy-03-specifyespecsfy-04-validate, use a spec aberta e devolva a conclusão à seção trabalhada pela fase. - Em
specsfy-05-tasks, ajude a sugerir e sincronizar especialistas e modos entre o cabeçalho, a seção 8 e as tarefas. Só essa fase escreve a seção 14. - Em
specsfy-06-implement, limite-se à tarefa indicada e ao passo carregado.
Nas fases com spec, leia a spec aberta indicada pela skill chamadora ou localizada por
specsfy status. Consulte a linha| Especialistas |, a subseção#### Especialistasem### 8. Plano técnicoe a seção pertinente à fase. Leia também.specsfy/STACK.md,.specsfy/RULES.mde, por tratar schema, policy e dado persistido,.specsfy/DATABASE.md. - Em
-
Siga o modo indicado na spec ou na tarefa, no formato
Especialista: $specsfy-specialist-supabase. Sem indicação, confirme pelo "Quando usar" acima se existesupabase/config.tomlno projeto. -
Devolva a conclusão e as dúvidas abertas no destino indicado no item 1, no próprio backlog, na spec ou na tarefa da fase.
-
Não mude o estado da spec nem marque gate: isso pertence a
$specsfy-03-specify,$specsfy-04-validate,$specsfy-05-taskse$specsfy-06-implement. -
Quando a fase trabalhar o modelo de dados ou o plano técnico da spec, registre papel, privilégio e policy de cada operação em
### 9. Modelo de dados, marque a migration na subseçãoMigrationse mantenha.specsfy/DATABASE.mdrefletindo o schema real.
Fluxo
- 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 escolha 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.
Padrões
- 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
anonque descubra o nome. - Nunca expor a chave secreta no cliente (browser, app mobile, bundle
público); ela resolve para o papel
service_role, ignora RLS e só pertence a ambiente de servidor confiável. Onde a RLS deve decidir, use a chave publicável (sb_publishable_…);anoneservice_roleem JWT são as chaves legadas, com descontinuação anunciada para o fim de 2026. - Testar cada policy separadamente para
anon,authenticatede qualquer papel de aplicação: uma policy que "parece" restringir mas usaUSING (true)equivale a não ter policy. - Tratar Realtime como superfície autorizada: Postgres Changes só entrega a
linha que a RLS da tabela permite ler, e canal privado de Broadcast/Presence
exige policy em
realtime.messagesmaisconfig: { private: true }no cliente. - Tratar como superfície crítica: funções
SECURITY DEFINER(rodam com privilégio do dono, não do chamador, precisam desearch_pathfixo 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 osupabase db pushe o 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,
PREPAREfunciona) ou transaction pool (alta concorrência, serverless) conforme o workload e o driver.
Antipadrões
- 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_idno frontend) sem policy correspondente no banco: qualquer chamada direta à API contorna o filtro. - Função
SECURITY DEFINERsemSET search_path = ''/schema fixo: permite sequestro de função por objeto de mesmo nome em outro schema nosearch_pathdo chamador. - Migration aplicada manualmente em produção via dashboard, divergindo do
histórico versionado: o próximo
db pushfalha por divergência de histórico e exigemigration repairpara 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).
Validaçã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,supabase db lint,supabase test dbesupabase db advisorsno ambiente local antes de promover: o projeto local reproduz o schema e as policies de produção. - Conferir tipos gerados (
supabase gen types --remote) 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).
Skills relacionadas
$specsfy-specialist-dockercobre serviços locais e imagens auxiliares; esta skill governa os contratos gerenciados da plataforma Supabase.$specsfy-specialist-postgrespara modelagem de schema, índice, plano de query e isolation por trás do Supabase.$specsfy-specialist-application-securitypara modelagem de ameaça de JWT, claims e superfícies de autorização além de RLS.$specsfy-specialist-laravelquando 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.
