P-06
Vínculo
CRM de relacionamento institucional em que cada regra, permissão e rastro vive no Postgres.
cliente████Equipe de articulação política (sistema interno, por convite)
Sistema interno para equipes de articulação política organizarem contatos, o histórico de relacionamento, projetos e campanhas de mobilização com funil, registro por canal e prioridade configurável. Sem backend próprio: a SPA fala direto com o Postgres, e RLS, triggers e RPCs decidem tudo. Login sem senha, 2º fator obrigatório para admin, log de atividade append-only e uma auditoria interna de segurança já aplicada.
- supabase
- postgres
- rls
- react
- mfa
- audit-log
- edge
- cloudflare
- etl
01Visão geral
O Vínculo é um CRM para equipes de articulação política. Ele reúne num só lugar os contatos com quem a equipe se relaciona (lideranças e organizações), a história desse relacionamento, os projetos (frentes de trabalho) e as campanhas: ações concretas do tipo "mobilizar um grupo de lideranças em duas redes sociais até a data X".
Antes, essas informações viviam em planilhas, conversas de WhatsApp e na memória de quem fez cada contato. O sistema transforma isso numa base consultável: quem já foi contatado, por qual canal, com que resultado, quem é o responsável, qual o alcance somado de quem topou e quem deveria ser abordado primeiro.
O acesso é só por convite e tem dois níveis de usuário. O operador nunca é impedido de trabalhar: o que muda entre usuários é o escopo (a quais projetos cada um tem acesso), não a função. As funções sensíveis (gestão de contas, log de atividade, decisões de exclusão) ficam com administradores, que precisam de segundo fator.
02O problema
- Dado espalhado e sem dono. A mesma liderança aparecia em várias planilhas, com grafias diferentes, e ninguém sabia quem tinha falado com ela por último.
- A unidade de trabalho estava errada. A primeira versão organizava status e público pelo projeto. No teste com a equipe ficou claro que o trabalho real acontece na ação (campanha), onde existem público-alvo, funil e resultado. O modelo precisou ser reorganizado com o sistema já em uso.
- Base sensível, equipe pequena. É uma base de relacionamento político: vazamento, alteração silenciosa ou uso indevido por alguém de dentro custariam caro. O sistema precisava deixar rastro de tudo sem virar um log impossível de ler.
- Entrada de dados em volume. Os contatos chegam por planilha (CSV/XLSX) em formatos heterogêneos: "1,2 mil" seguidores, partido por extenso, UF por nome, telefone com e sem DDI.
03A solução
- Contatos (lideranças e organizações): ficha completa, alcance por canal, histórico eleitoral (lista, não campo), até três contatos de gabinete com papel, marcadores livres normalizados, linha do tempo de notas versionadas e o card de auditoria do próprio contato.
- Lista de contatos com filtros no servidor: UF, partido, cargo, alinhamento, faixa de idade, marcadores, projeto/campanha; exportação CSV protegida contra CSV injection.
- Campanhas como unidade de trabalho: funil fechado de 9 status (válido em todas as campanhas, o que permite somar resultados entre elas), até 5 substatus configuráveis por status, registro por canal (URL de publicação, ou a flag "sem link" para stories e lives), responsável por contato, observações em linha do tempo, mensagem pronta de WhatsApp e ações em lote.
- Prioridade configurável por campanha: a campanha pontua metadados do contato ("nesta ação, estado X vale 2, acima de 50 mil seguidores vale 3") e a tabela ordena pela soma, com o porquê de cada ponto no tooltip.
- Impacto potencial × realizado: soma do alcance dos canais da campanha, calculada uma vez por pessoa no nível do projeto para não contar o mesmo seguidor em cada ação.
- Importação guiada (CSV/XLSX): wizard de 5 passos com auto-mapeamento de colunas por sinônimos, normalização pt-BR, resolução de vocabulário em lote, detecção de duplicatas (CNPJ → e-mail → nome + UF) e lote desfazível.
- Carga de dados públicos eleitorais: scripts que leem os resultados oficiais, cruzam com a base e gravam votação e marcadores de forma idempotente, numa página própria que mostra o que a carga mudou.
- Dashboard "War Room": KPIs, gráficos e mapa do Brasil em SVG puro (paths pré-gerados com
d3-geo, sem biblioteca de mapa no bundle). - Administração: convite de usuários, níveis, desativação, exclusão com diagnóstico do que a impede, fila de exclusão de notas e um log de atividade unificado.
- RLS em todas as 26 tabelas, com escopo por projeto resolvido por funções compartilhadas; anon não acessa nada além de uma RPC de falha de login com rate limit.
- 2º fator exigido de forma cirúrgica: o predicado aal2 protege logs, auditoria e gestão de contas, sem atrapalhar o uso diário.
- Log de atividade unificado, append-only e à prova de cliente, paginado por cursor: 1,5 ms por página sobre 100 mil linhas.
- Prioridade de contatos configurável por campanha, calculada por função pura e explicada ponto a ponto no tooltip.
- Importação CSV/XLSX com normalização pt-BR, detecção de duplicatas e lote desfazível.
- Script SQL pós-migration que verifica o hardening de 20 funções sensíveis e já pegou uma regressão real.
04Arquitetura
Ler o diagrama como lista (15 componentes, 18 conexões)
Componentes
- Navegador (SPA): Operador<br>escopo por projeto, Admin<br>2º fator obrigatório
- Cloudflare: Pages<br>build Vite · SPA fallback, Turnstile<br>captcha no login
- Edge Functions (Deno): admin-usuarios<br>revalida admin + aal2<br>service_role, acesso-emergencia<br>captcha + rate limit<br>código de recuperação
- Postgres: 26 tabelas com RLS<br>escopo por projeto/campanha, RPCs de leitura<br>filtro no servidor · cursor, Triggers<br>auditoria · invariantes · guarda de posse, eventos + auditoria<br>append-only, pg_cron<br>lembretes · retenção de logs
- Supabase: Auth<br>OTP por e-mail · TOTP (aal2)<br>sessão 24 h / 7 dias, PostgREST<br>anon sem acesso, EF, PG
Conexões
- Operador<br>escopo por projeto → Pages<br>build Vite · SPA fallback
- Admin<br>2º fator obrigatório → Pages<br>build Vite · SPA fallback
- Operador<br>escopo por projeto → Turnstile<br>captcha no login
- Admin<br>2º fator obrigatório → Turnstile<br>captcha no login
- Pages<br>build Vite · SPA fallback → PostgREST<br>anon sem acesso (JWT do usuário)
- Pages<br>build Vite · SPA fallback → Auth<br>OTP por e-mail · TOTP (aal2)<br>sessão 24 h / 7 dias
- Admin<br>2º fator obrigatório → admin-usuarios<br>revalida admin + aal2<br>service_role (Bearer aal2)
- Pages<br>build Vite · SPA fallback → acesso-emergencia<br>captcha + rate limit<br>código de recuperação
- acesso-emergencia<br>captcha + rate limit<br>código de recuperação → Turnstile<br>captcha no login
- admin-usuarios<br>revalida admin + aal2<br>service_role → Auth<br>OTP por e-mail · TOTP (aal2)<br>sessão 24 h / 7 dias
- acesso-emergencia<br>captcha + rate limit<br>código de recuperação → Auth<br>OTP por e-mail · TOTP (aal2)<br>sessão 24 h / 7 dias
- PostgREST<br>anon sem acesso → 26 tabelas com RLS<br>escopo por projeto/campanha
- PostgREST<br>anon sem acesso → RPCs de leitura<br>filtro no servidor · cursor
- 26 tabelas com RLS<br>escopo por projeto/campanha → Triggers<br>auditoria · invariantes · guarda de posse
- Triggers<br>auditoria · invariantes · guarda de posse → eventos + auditoria<br>append-only
- pg_cron<br>lembretes · retenção de logs → eventos + auditoria<br>append-only
- Dados abertos<br>eleitorais (carga offline) → 26 tabelas com RLS<br>escopo por projeto/campanha (scripts Python<br>idempotente)
- GitHub<br>CI: lint · 526 testes · build → Pages<br>build Vite · SPA fallback (push na main → auto-deploy)
A decisão central é não ter backend próprio: a SPA fala direto com o PostgREST usando o JWT do usuário, e toda regra que importa vive no Postgres (RLS, triggers, CHECKs, RPCs). O único código que roda com privilégio elevado está em duas edge functions, e cada uma revalida quem chama antes de usar a service_role.
05Por dentro
- Postgres no Supabase, com 58 migrations versionadas (0001–0045; sufixos
b/c/dsão correções da mesma rodada), 26 tabelas ativas, 15 enums, 69 funções, 53 triggers e 80 policies de RLS no estado final. - RLS em todas as tabelas, políticas apenas para
authenticated. O escopo é resolvido por funções (app.acessa_projeto,acessa_campanha,acessa_participante_campanha,gerencia_projeto), reaproveitadas por todas as policies. - Invariantes no banco, não na tela: teto de 5 substatus por status, 10 critérios × 6 faixas de prioridade, 3 contatos de gabinete, 20 marcadores por contato; trocar o status principal apaga marcações que deixaram de casar; o registro por canal deriva
realizadoda URL (ou da flag "sem link") num trigger de normalização. - Leitura por RPC onde a view não escala:
fn_contatos_filtrados/fn_contatos_csvrecebem os filtros no corpo (POST) em vez de uma lista de ids na URL, efn_projeto_contatosune duas fontes (campanhas + vínculo manual) deduplicando por pessoa. - Dois rastros complementares:
auditoria(trigger genérico em toda gravação, guardando só o diff em UPDATE) eeventos(login, logout, exportação, abertura de contato, gestão de contas), ambos append-only. pg_cron: lembretes diários às 09h e limpeza mensal de logs pela política de retenção.- Carga eleitoral: scripts Python (658 linhas) leem os JSONs públicos de resultado, descartam na leitura qualquer documento pessoal que a fonte traga, cruzam nome civil/de urna + UF com a base e gravam com unique parcial, para que rodar duas vezes não duplique nada.
- React 19 + Vite 6 + TypeScript, React Router 7 e TanStack Query 5 para cache e invalidação. 180 arquivos em
src/, organizados por domínio (features/*, cada um com suas telas e um*Api.tsde dados). - Design system próprio ("Command Center"): dark-first, tokens HSL em CSS com Tailwind v4 (
@theme inline), primitivos acessíveis sobre Radix UI, fontes Space Grotesk / Inter / JetBrains Mono. - Bundle cuidado: o parser de XLSX só entra por
import()dinâmico na rota de importação, e o mapa do dashboard é SVG pré-gerado. - Lógica pura testável: prioridade, filtros, normalização, duplicatas, validação da importação, agrupamento do log, idade, CSV, datas, marcadores e sanitização ficam em módulos sem React/Supabase, cobertos por 526 testes Vitest (10 deles marcados como
it.failsdocumentando bugs conhecidos ainda não corrigidos). - 20 rotas, com guards
RotaAutenticadaeRotaAdmine páginas pesadas carregadas sob demanda.
- Cloudflare Pages com auto-deploy no push da
main, SPA fallback por_redirects. No Cloudflare só há variáveis publicáveis (URL e anon key do Supabase, site key do Turnstile). - Supabase: Postgres, Auth, Edge Functions (Deno),
pg_cron. Migrations aplicadas e versionadas; tipos TypeScript gerados a partir do schema. - CI no GitHub Actions:
lint(0 erros),testebuild(tsc -bé o gate de tipos) em todo push e PR, com Node fixado por.nvmrc. - Verificação pós-migration: um script SQL confere, para 20 funções sensíveis, exigência de
aal2,search_pathfixo e ausência de grant paraanon. Foi ele que pegou uma regressão em que umdrop/createde função tinha apagado o hardening.
06Segurança
8 ataques considerados, 8 defesas em produção.
Força bruta, criação de contas indevidas, redefinição de senha e tomada de conta.
Criar conta digitando qualquer e-mail na tela de login
Signup desligado e shouldCreateUser: false; contas só nascem pela edge function de admin, e e-mail sem acesso recebe a mesma resposta que um válido.
Tomar o e-mail de um admin e abrir logs ou gerir contas
Logs, auditoria e gestão de contas exigem aal2 (TOTP) no banco e na edge function; remover o 2º fator também exige aal2, e cadastrar um fator dispara e-mail de aviso.
Força bruta nos códigos de recuperação
Edge function com Turnstile, limite de 5 tentativas por IP e por e-mail contando só eventos gravados pelo banco, fail-closed (503) e códigos guardados como hash bcrypt.
Quem tem algum acesso tentando ganhar mais: virar admin, ler o que não deve, manter acesso revogado.
Operador se promover a admin via API
authenticated só tem grant de UPDATE em usuarios.nome; nível e status passam pela edge function, que revalida admin + aal2 e não rebaixa o último admin ativo.
Usuário com acesso a um projeto virar dono dele e escondê-lo dos outros
Triggers de guarda de posse: só admin troca o criador, e só quem gerencia muda a permissão do projeto ou o projeto de uma campanha.
XSS, iframe, fórmula em CSV, upload disfarçado e manipulação do prompt da IA.
Injetar fórmula na planilha exportada
O CSV gerado escapa = + - @ e a exportação acima de 500 contatos alerta os admins.
Estourar a fatura, esgotar limites, inundar logs e derrubar funções com carga.
Inundar o log com falhas de login falsas
A única RPC aberta a anon tem rate limit de 20/min por IP e catálogo fechado de tipos; o alerta de ataque deduplica por tipo (1 por hora).
Mexer em contagens, apagar a base, editar o histórico ou negar o que foi autorizado.
Apagar ou editar o rastro depois de agir
eventos e auditoria são append-only, sem policy de UPDATE/DELETE para ninguém; a escrita passa por RPC security definer que resolve autor, IP e navegador no servidor.
Autenticação
- Login sem senha: o usuário recebe um código por e-mail (
signInWithOtp→verifyOtp). As senhas antigas foram invalidadas de propósito, para não sobrar um caminho paralelo com segredo reutilizável. - Sem cadastro público:
shouldCreateUser: falseno cliente, signup desligado e contas criadas só pela edge function de administração. - Anti-enumeração: e-mail sem acesso recebe a mesma resposta que um válido; a tentativa fica registrada no log (só para admin).
- Captcha Cloudflare Turnstile no login, validado no servidor.
- Sessões com teto no servidor: 24 h de inatividade e 7 dias de duração máxima. "Lembrar deste dispositivo" escolhe só entre
localStorageesessionStorage; o limite real é imposto pelo Auth. - 2º fator TOTP obrigatório para administradores. O admin sem fator fica preso na página de segurança até cadastrar um. O suporte a chave de segurança (WebAuthn) está implementado, mas fica desligado por flag enquanto a plataforma não libera o recurso.
- Códigos de recuperação: 8 códigos de uso único, guardados só como hash bcrypt e exibidos uma vez. O consumo passa por uma edge function com captcha, rate limit de 5 tentativas por IP e por e-mail, e fail-closed: se a contagem falhar, responde 503 em vez de liberar. Cada uso gera evento e alerta os admins.
Autorização
- RLS em 100% das tabelas,
anonsem acesso a nada além de uma RPC de registro de falha de login. - Exigência de
aal2cirúrgica: o predicadofn_e_admin_aal2()protege as RPCs de log, as policies deeventoseauditoriae toda a gestão de contas. A edge functionadmin-usuarioslê o claimaaldo Bearer e recusa sem ele. - Sem escalada de privilégio:
authenticatedsó tem grant de UPDATE emusuarios.nome; nível e status passam pela edge function, que revalida admin + 2º fator no servidor, impede rebaixar o último admin ativo e valida ousuario_idcomo UUID. - Guarda de posse (auditoria interna de outubro): triggers impedem que quem apenas acessa um projeto se torne seu criador, mude a permissão de acesso ou mova uma campanha para outro projeto, um caminho que antes permitia esconder ou apagar trabalho alheio.
- Exclusão sensível só por admin: perfis têm soft-delete com guarda por trigger; exclusão de nota passa por fila de solicitação; usuário com histórico não é apagado, é desativado, preservando a autoria.
Rastro e detecção
eventoseauditoriasão append-only: ninguém, nem admin, tem policy de UPDATE/DELETE. A escrita passa por RPCssecurity definerque resolvem autor, IP e navegador no servidor e validam o tipo contra um catálogo fechado.- A RPC pública de falha de login tem rate limit de 20/min por IP.
- Alertas no sino: 5+ falhas de login em 15 min, exportação acima de 500 contatos e mudanças em contas.
Dados e privacidade
- Minimização: o contato guarda ano de nascimento, não data; a exportação CSV é identificação mínima, sem dado pessoal sensível; na carga eleitoral, documentos pessoais da fonte são descartados na leitura e nunca gravados nem versionados.
- Retenção definida: eventos de leitura por 6 meses, demais eventos e auditoria por 24 meses, com limpeza agendada.
Validação e hardening
- Sanitização na entrada (
sanitizarTexto,urlOuNulo, etc.) e CHECKs no banco; semdangerouslySetInnerHTMLnemeval. - Funções
security definercomsearch_pathfixo, verificadas por script após cada migration. - CSV gerado escapa
= + - @contra formula injection. service_roleexiste apenas dentro das edge functions; o cache do React Query é limpo ao sair ou trocar de conta.
07Desafios técnicos
Reorganizar o modelo com o sistema em uso
Status, substatus e público migraram do projeto para a campanha (migrations 0023–0029). O status principal virou vocabulário fechado de 9 valores, justamente para que "Realizou" fosse somável entre campanhas; o que cada campanha configura são os substatus. O vínculo manual projeto × contato sobreviveu sem status, e a tabela do projeto passou a mostrar a origem de cada pessoa (campanha, manual ou ambos), porque ambiguidade visível é melhor que implícita. Triggers garantem que trocar o status não deixe marcações órfãs.
Um log que se lê, e não só se varre
A auditoria nativa do Auth não era populada no ambiente hospedado, então o app passou a registrar seus próprios eventos. Com 100 mil linhas de teste, a view que unia auditoria e eventos levava de 125 ms a 1,5 s na primeira página. Ela foi trocada por uma RPC com LIMIT dentro de cada braço do UNION ALL, join só sobre as 50 linhas finais e paginação por cursor (criado_em, id), o que chegou a 1,5 ms / 17 buffers. O diff em JSONB só trafega quando o usuário expande a linha. Contra o ruído: deduplicação de leituras por janela no banco, remoção de registros sem valor na origem e agrupamento de rajadas legítimas (uma importação, um lote de substatus) só na apresentação, sem apagar rastro.
Quando o hardening some sozinho
Um drop/create de função reescreve o corpo inteiro, e duas vezes uma migration apagou proteção sem ninguém perceber: o revoke de anon numa RPC e a exigência de aal2 em outra. A resposta foi processo: um SQL de verificação que lista as funções sensíveis com o que se espera de cada uma e precisa sair com ok = true em todas as linhas. Na auditoria de outubro ele achou a segunda regressão, e a mesma rodada fechou um caminho de tomada de posse de projetos e um vetor que permitia bloquear o acesso de emergência de qualquer e-mail inflando o contador de tentativas.
Fazer a URL parar de crescer
A lista de contatos mandava os ids filtrados na query string: cerca de 15 KB com ~400 contatos e +37 bytes por contato novo, a caminho de uma tela em branco por erro de protocolo, sem aviso nenhum. O filtro foi para uma RPC (POST, filtros no corpo), e a URL passou a ter tamanho constante. Uma regra de lint da casa agora sinaliza .in() com lista dinâmica.
08Resultados
- Em produção desde julho de 2026; 63 commits entre 27/07 e 05/10/2026, em sete rodadas de mudanças guiadas pelo feedback da equipe usuária.
- 58 migrations, 26 tabelas com RLS, 80 policies, 2 edge functions, 2 jobs
pg_cron. - 526 testes automatizados nos módulos puros (516 passando, 10 falhas esperadas documentando bugs conhecidos); lint com 0 erros; CI em todo push.
- Auditoria interna de segurança em outubro de 2026, com as correções da etapa 1 (posse de projeto/campanha,
aal2restaurado, edge functions endurecidas) já aplicadas, enpm auditzerado (4 → 0). - Log de atividade medido em 1,5 ms por página sobre 100 mil linhas.
- 58
- Migrations
- 26
- Tabelas com RLS
- 80
- Policies de RLS
- 69
- Funções SQL
- 53
- Triggers
- 526
- Testes automatizados
- 2
- Edge functions
- 63
- Commits
- ~26 mil
- Linhas de TypeScript
- 6.183
- Linhas de SQL
- 1,5 ms
- Página do log de atividade
como medimos
ls supabase/migrations | wc -l (0001–0045, com sufixos b/c/d)
como medimos
28 create table − 2 drop table nas migrations; enable row level security em todas
como medimos
simulação de create/drop policy em ordem sobre as migrations
como medimos
nomes distintos em create [or replace] function nas migrations
como medimos
nomes distintos em create trigger nas migrations
como medimos
npx vitest run: 516 passed | 10 expected fail, 11 arquivos
como medimos
supabase/functions/ (admin-usuarios, acesso-emergencia)
como medimos
git rev-list --count HEAD (27/07 a 05/10/2026)
como medimos
linhas não vazias em *.ts/*.tsx versionados (12.909 + 15.088), incluindo ~2 mil de tipos gerados
como medimos
linhas não vazias em *.sql versionados
como medimos
medição com 100 mil linhas registrada na migration 0017 e no CLAUDE.md §14
09Linha do tempo
- jul 2026
Primeira versão em produção no Cloudflare Pages, com importação CSV/XLSX e log de atividade.
- jul 2026
Login sem senha por código, códigos de recuperação e 2º fator obrigatório para admin.
- jul 2026
Reorganização do modelo: a campanha vira a unidade de trabalho, com canais múltiplos e registro por canal.
- ago 2026
Prioridade de contatos por pontuação configurável em cada campanha.
- ago 2026
Filtro de contatos movido para RPC no servidor, eliminando a lista de ids na URL.
- out 2026
Carga de dados eleitorais públicos, marcadores e página do que a carga mudou.
- out 2026
Auditoria interna: CI com 526 testes, verificação SQL do hardening e correções de posse e aal2.
10Stack
- React 19
- Vite 6
- TypeScript
- React Router 7
- TanStack Query 5
- Tailwind CSS 4
- Radix UI
- Recharts
- Supabase
- PostgREST
- Supabase Auth (OTP + TOTP)
- Edge Functions (Deno)
- PL/pgSQL
- PostgreSQL
- Row Level Security
- pg_cron
- pg_trgm
- unaccent
- Python (carga de dados públicos)
- Cloudflare Pages
- GitHub Actions
- Vitest
- ESLint
- MFA TOTP obrigatório para admin (aal2)
- Login sem senha por código
- Cloudflare Turnstile
- Códigos de recuperação com bcrypt
- Rate limiting em RPC e edge function
- Auditoria append-only
11Ficha técnica
- type
- CRM interno · por convite
- stack
- React 19 · Vite · TypeScript
- db
- Postgres · 26 tabelas · 80 policies RLS
- auth
- OTP por e-mail · TOTP p/ admin (aal2)
- deploy
- Cloudflare Pages · Supabase
- audit
- append-only · cursor paginado
- tests
- 526 vitest · CI em todo push
- status
- em produção
Um app de consultoria fitness gerado por IA, levado a padrão de produção: RLS sem avaliação por linha, treino que não se perde offline e CI que testa o banco de verdade
Canal público de denúncias com painel de triagem onde a autorização mora no banco: RLS por papel, contatos só por função auditada, sessão revogada na hora e robô que salva provas antes de expirarem.
A plataforma da campanha pelo fim da escala 6x1: adesão nacional, rede de voluntários e defesa anti-bot em 7 camadas
Quer um sistema assim para a sua operação?
A Node projeta, constrói e protege plataformas sob medida para campanhas, mandatos e movimentos.

TECNOLOGIA E INTELIGÊNCIA POLÍTICA
© 2026 NODE. Todos os direitos reservados.