Trilha de Auditoria no Supabase: Logs Imutáveis e Compliance LGPD
Trilha de Auditoria Corporativa no Supabase: Logs Imutáveis e Compliance LGPD/SOC 2
Em sistemas corporativos, plataformas SaaS B2B e aplicações que processam dados sensíveis (financeiros, jurídicos ou de saúde), a capacidade de responder com precisão matemática "Quem alterou o quê, quando e de onde?" não é apenas uma boa prática de engenharia: é uma exigência legal e regulatória inegociável.
Normas como SOC 2 Type II (Trust Services Criteria CC6.1 e CC6.8), ISO/IEC 27001 (Controle A.12.4) e a LGPD (Art. 37) exigem que todas as alterações em registros críticos mantenham um histórico perene, auditável e, fundamentalmente, imutável.
Neste guia técnico e arquitetural, você aprenderá a projetar um sistema de auditoria de nível corporativo (Enterprise Audit Trail) direto no PostgreSQL do Supabase, utilizando Database Triggers genéricos em PL/pgSQL, captura de diffs em formato JSONB e políticas de Row Level Security (RLS) que impedem qualquer adulteração retroativa de registros.
1. Os Três Pilares de uma Trilha de Auditoria Inviolável
Muitas equipes tentam implementar auditoria gravando logs manualmente no código da aplicação (dentro de Server Actions ou rotas de API). Essa abordagem falha catastroficamente por três motivos:
- Falta de Cobertura Universal: Se um desenvolvedor executar um script de correção direto no banco ou esquecer de chamar a função de log em uma nova rota, a alteração torna-se invisível.
- Vulnerabilidade a Adulteração: Se a aplicação tem permissão para alterar o log, um invasor ou administrador mal-intencionado pode apagar os rastros da invasão.
- Alto Custo de Rede: Fazer duas gravações separadas da aplicação para o banco de dados dobra a latência da operação.
O Modelo Postgres-Native
A auditoria corporativa segura mora dentro do motor relacional do PostgreSQL:
┌─────────────────────────────────────────────────────────────┐
│ OPERAÇÃO DO USUÁRIO │
│ (INSERT, UPDATE ou DELETE via Next.js ou API) │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ TABELA DE NEGÓCIO (Ex: invoices) │
│ Execução da Transação SQL │
└──────────────────────────────┬──────────────────────────────┘
│
┌──────────────────┴──────────────────┐
▼ (Trigger Automático AFTER) ▼
┌──────────────────────────────────────┐ ┌───────────────────┐
│ FUNÇÃO PL/pgSQL GENÉRICA │ │ DADOS FINAIS │
│ - Extrai auth.uid() do JWT │ │ GRAVADOS │
│ - Calcula diff JSONB (OLD vs NEW) │ └───────────────────┘
│ - Captura IP e User-Agent │
└──────────────────┬───────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ TABELA DE AUDITORIA IMUTÁVEL (audit_logs) │
│ - RLS: Bloqueio Total de UPDATE e DELETE │
│ - Apenas INSERT via Trigger do Sistema │
└─────────────────────────────────────────────────────────────┘
2. Modelagem do Esquema de Auditoria (audit_logs)
O primeiro passo é criar a tabela central que armazenará todos os eventos de auditoria do sistema de forma estruturada:
-- 1. Cria a tabela central de auditoria imutavel
CREATE TABLE audit_logs (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
table_name TEXT NOT NULL,
record_id UUID NOT NULL,
action TEXT NOT NULL CHECK (action IN ('INSERT', 'UPDATE', 'DELETE')),
old_data JSONB,
new_data JSONB,
changed_fields JSONB,
actor_id UUID REFERENCES auth.users(id) ON DELETE SET NULL,
actor_role TEXT,
ip_address INET,
user_agent TEXT,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
);
-- 2. Indices de alta performance para consultas de auditoria e compliance
CREATE INDEX idx_audit_logs_table_record
ON audit_logs (table_name, record_id);
CREATE INDEX idx_audit_logs_actor_id
ON audit_logs (actor_id);
CREATE INDEX idx_audit_logs_created_at
ON audit_logs (created_at DESC);
CREATE INDEX idx_audit_logs_action
ON audit_logs (action);
3. A Função de Trigger Universal em PL/pgSQL
Em vez de criar uma função para cada tabela, eu estruturo uma função genérica em PL/pgSQL capaz de inspecionar dinamicamente qualquer tabela do banco de dados, calcular os campos alterados e extrair a identidade do usuário autenticado no Supabase Auth:
CREATE OR REPLACE FUNCTION process_audit_log()
RETURNS TRIGGER AS $$
DECLARE
v_old_data JSONB := NULL;
v_new_data JSONB := NULL;
v_changed_fields JSONB := '{}'::JSONB;
v_record_id UUID;
v_actor_id UUID;
v_actor_role TEXT;
v_key TEXT;
BEGIN
-- 1. Identifica o autor da acao via JWT do Supabase
v_actor_id := auth.uid();
v_actor_role := auth.role();
-- 2. Processa os dados de acordo com a operacao SQL
IF (TG_OP = 'INSERT') THEN
v_new_data := to_jsonb(NEW);
v_record_id := NEW.id;
ELSIF (TG_OP = 'UPDATE') THEN
v_old_data := to_jsonb(OLD);
v_new_data := to_jsonb(NEW);
v_record_id := NEW.id;
-- Calcula apenas as colunas que efetivamente sofreram alteracao
FOR v_key IN SELECT jsonb_object_keys(v_new_data)
LOOP
IF (v_old_data -> v_key IS DISTINCT FROM v_new_data -> v_key) THEN
v_changed_fields := v_changed_fields || jsonb_build_object(
v_key, jsonb_build_object(
'old', v_old_data -> v_key,
'new', v_new_data -> v_key
)
);
END IF;
END LOOP;
ELSIF (TG_OP = 'DELETE') THEN
v_old_data := to_jsonb(OLD);
v_record_id := OLD.id;
END IF;
-- 3. Grava o registro na tabela de auditoria
INSERT INTO audit_logs (
table_name,
record_id,
action,
old_data,
new_data,
changed_fields,
actor_id,
actor_role,
created_at
) VALUES (
TG_TABLE_NAME,
v_record_id,
TG_OP,
v_old_data,
v_new_data,
CASE WHEN TG_OP = 'UPDATE' THEN v_changed_fields ELSE NULL END,
v_actor_id,
v_actor_role,
NOW()
);
RETURN COALESCE(NEW, OLD);
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
Aplicando a Trilha em Tabelas Críticas
Basta vincular o trigger às tabelas que exigem rastreabilidade regulatória:
-- Vincula o trigger a tabela de faturas e pedidos
CREATE TRIGGER audit_invoices_trigger
AFTER INSERT OR UPDATE OR DELETE ON invoices
FOR EACH ROW EXECUTE FUNCTION process_audit_log();
-- Vincula o trigger a tabela de membros da organizacao
CREATE TRIGGER audit_organization_members_trigger
AFTER INSERT OR UPDATE OR DELETE ON organization_members
FOR EACH ROW EXECUTE FUNCTION process_audit_log();
4. Imutabilidade Absoluta com Row Level Security (RLS)
A regra de ouro da auditoria é: uma vez gravado, um log jamais poderá ser alterado ou deletado, nem mesmo por administradores do sistema.
Para assegurar essa garantia perante auditores de conformidade, configuro políticas estritas de RLS no PostgreSQL:
-- 1. Ativa o Row Level Security na tabela de logs
ALTER TABLE audit_logs ENABLE ROW LEVEL SECURITY;
-- 2. Permite LEITURA apenas para administradores e auditores de seguranca
CREATE POLICY "Auditors and SuperAdmins can view audit logs"
ON audit_logs
FOR SELECT
TO authenticated
USING (
EXISTS (
SELECT 1 FROM profiles
WHERE profiles.id = auth.uid()
AND profiles.role IN ('security_auditor', 'super_admin')
)
);
-- 3. Bloqueio TOTAL de mutacoes manuais
-- NENHUMA politica de INSERT, UPDATE ou DELETE e criada para usuarios.
-- As gravacoes ocorrem exclusivamente pela funcao SECURITY DEFINER do Trigger.
A ausência proposital de políticas de UPDATE e DELETE no RLS garante que nenhuma chamada de API, Server Action ou cliente frontend consiga adulterar os logs. O PostgreSQL rejeitará qualquer tentativa de modificação com erro de permissão.
5. Exibindo o Histórico de Auditoria no Next.js (force-dynamic)
Como a tela de auditoria é um painel administrativo confidencial de alta criticidade, ela deve obrigatoriamente utilizar export const dynamic = "force-dynamic", garantindo que nenhum log seja servido a partir de caches estáticos e que a validação de permissões ocorra a cada requisição.
// app/(admin)/audit-trail/page.tsx
import { createServerClient } from "@/lib/supabase/server";
import { redirect } from "next/navigation";
// Painel administrativo exige leitura dinamica sem cache
export const dynamic = "force-dynamic";
interface AuditLogEntry {
id: string;
table_name: string;
record_id: string;
action: "INSERT" | "UPDATE" | "DELETE";
changed_fields: Record<string, { old: unknown; new: unknown }> | null;
actor_id: string | null;
created_at: string;
}
export default async function AuditTrailPage() {
const supabase = await createServerClient();
const { data: { user } } = await supabase.auth.getUser();
if (!user) {
redirect("/login");
}
// 1. Busca os logs de auditoria mais recentes sob o RLS do usuario
const { data: logs, error } = await supabase
.from("audit_logs")
.select("id, table_name, record_id, action, changed_fields, actor_id, created_at")
.order("created_at", { ascending: false })
.limit(50);
if (error) {
return (
<div className="p-8 text-destructive">
Acesso negado ou erro ao carregar relatorio de auditoria.
</div>
);
}
return (
<div className="container mx-auto p-8">
<h1 className="text-2xl font-bold mb-6">Trilha de Auditoria Corporativa</h1>
<div className="border rounded-lg overflow-hidden bg-card">
<table className="w-full text-left text-sm">
<thead className="bg-muted border-b">
<tr>
<th className="p-4">Data / Hora</th>
<th className="p-4">Tabela</th>
<th className="p-4">Ação</th>
<th className="p-4">Autor ID</th>
<th className="p-4">Modificações (Diff)</th>
</tr>
</thead>
<tbody className="divide-y">
{logs?.map((log: AuditLogEntry) => (
<tr key={log.id} className="hover:bg-muted/50">
<td className="p-4 font-mono text-xs">
{new Date(log.created_at).toLocaleString("pt-BR")}
</td>
<td className="p-4 font-semibold">{log.table_name}</td>
<td className="p-4">
<span className={`px-2 py-1 rounded text-xs font-bold ${
log.action === 'INSERT' ? 'bg-emerald-500/20 text-emerald-500' :
log.action === 'UPDATE' ? 'bg-amber-500/20 text-amber-500' :
'bg-destructive/20 text-destructive'
}`}>
{log.action}
</span>
</td>
<td className="p-4 font-mono text-xs text-muted-foreground">
{log.actor_id ?? "Sistema / Cron"}
</td>
<td className="p-4 font-mono text-xs">
{log.changed_fields ? (
<pre className="bg-muted p-2 rounded max-w-md overflow-x-auto">
{JSON.stringify(log.changed_fields, null, 2)}
</pre>
) : (
<span className="text-muted-foreground">—</span>
)}
</td>
</tr>
))}
</tbody>
</table>
</div>
</div>
);
}
6. Estratégias de Retenção e Particionamento Temporal
Em sistemas com centenas de milhares de mutações diárias, a tabela audit_logs pode acumular gigabytes de dados rapidamente.
Para manter o banco veloz e os custos de armazenamento sob controle:
- Particionamento por Data (
RANGE PARTITIONING): Crie partições mensais no PostgreSQL (audit_logs_2026_01,audit_logs_2026_02). Isso permite que queries de auditoria filtrem partições inteiras instantaneamente. - Cold Storage Archival (S3 / Supabase Storage): Logs com mais de 365 dias podem ser exportados via cron job para arquivos compactados Parquet no Supabase Storage, liberando espaço no banco relacional enquanto mantêm a conformidade para auditorias futuras.
Conclusão: Maturidade Corporativa e Segurança Probatória
A implementação de uma trilha de auditoria nativa no PostgreSQL transforma a postura de segurança da sua empresa.
Ao eliminar a dependência de logs manuais em código e delegar a responsabilidade para Triggers em PL/pgSQL e políticas de RLS imutáveis, você garante que qualquer investigação de incidente, auditoria contábil ou inspeção regulatória (LGPD / SOC 2) disponha de registros íntegros, incontestáveis e com valor probatório.
Se a sua empresa precisa estruturar controles de segurança corporativa, arquitetar bancos de dados em conformidade com SOC 2 e LGPD ou desenvolver sistemas SaaS blindados com Next.js e Supabase, conheça meus serviços de desenvolvimento sob medida ou solicite uma consulta comigo.